Singularity Flow 0.9.0

Singularity Flow runs a software development lifecycle out of Git itself. Work items move through declared phases; every artifact and every approval is a commit, so any machine can pick the work up from the repository alone.

Start here

singularity-flow quickstart

Eight seconds, entirely offline, no model invoked, and your own repository is untouched — it builds a throwaway one, takes a work item through every step, and removes it. It is the fastest way to see what the rest of this document describes.

Before a POC demo, run npm run poc:release-gate. It builds diagnostic local artifacts and proves the seeded POC workflow against a throwaway real Git remote, independent reviewer, native Copilot handoff, and restart recovery without invoking a model. It is not release authority; a release candidate uses the retained build-once artifact pair and signed physical-host matrix described in docs/RELEASE-ARTIFACT-HANDOFF.md. See the verification checklist for the evidence boundary and the Playwright POC runbook for real-machine host setup, authorized target smoke testing, evidence capture, and day-of-demo rehearsal.

Then, on a repository you care about:

init deliberately asks no organisation question and writes no capability map. Until a reviewed map is activated, the repository is the single implicit capability This repository (repository-root). Start the first Story normally. Add structure later only when a narrower owner, protected path, or published dependency is real; see Progressive capability disclosure.

The full documentation map is in docs/README.md. The consolidated system, authority, storage, and implementation-status view is in the Architecture Review Board document. The additive, model-free SGOS compiler/runtime profile and its explicit staged boundaries are in the SGOS guide. For a practical walkthrough covering normal Story usage, explicit Intent-to-Process execution, recovery, and Git-trusted Capability Pack sharing, read How to use SGOS. For bounded work that begins without a Story, follow the ad hoc work and landing as a Story guide. For a private output Story that has no product repository, follow the local signed-deliverables guide. The L1 profile is model-free, publishes a create-only signed archive, and keeps remote delivery and repository adoption disabled. For the Repository brief every phase prompt gets and the repository knowledge it is read from, see Repository knowledge. For the additive, model-free structural read registry, provenance and coverage contracts, active view inventory, and deliberately deferred FWM stages, see Future-proof world-model read contracts. The read-only return experience is documented in Developer Home and Story Return. The shared Home routing, readiness evidence, compact submission receipt, and cross-clone return locator are documented in the golden developer journey. In VS Code, My Work is the visible home; Talk to SFlow is retained only as a hidden compatibility alias. In Copilot, developers can ask ordinary questions such as “What am I working on?”, “What is blocking this Story?”, or “Start a new bug fix.” /sf-home is the explicit escape hatch. Reads may run immediately; any mutation is previewed and requires an explicit selection before it runs.

What it is

Singularity Flow is a Git-native SDLC workflow for GitHub Copilot. A repository-owned YAML file defines work types, phase sequences, artifact templates, agents, human approval authority groups, and publication policy. Generated artifacts and lifecycle decisions are committed to a work-item branch and pushed after every operation, so another terminal or VS Code session can safely resume from Git. Its preferred direct Copilot skills use the short sf- prefix.

Singularity Flow is the product under the Singularity brand. The installer creates personal aliases such as /sf-start, /sf-submit, and /sf-about, so normal use has no plugin namespace. The packaged sflow-* skills remain available for compatibility, including the qualified /singularity-flow/sflow-* form.

The optional Capability Ledger records high-value Story and Initiative lifecycle events on an unrelated state orphan branch. Durable work-branch intents let another machine reconcile a missing ledger append after partial publication. Run /sf-about for the installed version and a concise capability summary. The full singularity-flow executable remains a compatible CLI for existing scripts and documentation.

The package contains:

• A deterministic Node.js CLI (singularity-flow or sflow).
• Explicit model-independent operation policies, a strict --no-model mode, and manual artifact publication.
• A VS Code extension for workspaces, intake, workflow configuration, progress, documents, and approvals.
• A GitHub Copilot plugin with collision-safe skills and a bundled workflow runtime.
• A canonical searchable help manual shared by the CLI, Copilot, and VS Code.
• Editable feature, bugfix, chore, and Figma-export-to-mobile profiles.
• Editable agent prompts and artifact templates.
• A Repository brief in every phase prompt, approval auditing, token accounting, and a final spec-to-code conformance gate.
• Opt-in clause-driven specification indexes, claim maps, coverage, acceptance evidence, and a VS Code traceability view.
• Exact local prompt-composition caching and honest deployment validation for orphan state ledgers.
• Opt-in Harness Imports for revision-bound sfref:v1 artifacts, deterministic bounded previews, exact engine conformance evidence, and approved scoped knowledge recall.
• Opt-in Flow Impact studies with automatic Story enrollment, revision-bound receipts, honest exposure and missing-data records, aggregate privacy floors, uncertainty intervals, quality-gated inference labels, and deterministic two-arm comparisons of reviewed prompt sets.
• A deterministic home, repository doctor, guided run mode, portable review bundles, safe recovery, workflow simulation, assignments, and read-only watching.
• Recursive design-package inventory and a local image gallery for exported Figma/mobile evidence.
• Opt-in initiative orchestration for Epics and repository-specific stories, with separate Epic/Story Work/Jira IDs, typed evidence, interface contracts, cross-repository progress, and enterprise phase gates.
• A native Copilot handoff: VS Code renders phase-aware context while authoring stays in the user’s normal Copilot session; the installed /sf-* aliases can be used directly.
• Local multi-repository workspaces with one Epic lead repository, per-repository Jira boards and App IDs, document staging, health checks, resumable setup, and Copilot context separation.
• A structured activity log (error through trace) covering commands and hook decisions, written machine-local under .git/ with secrets redacted and never to standard output.

Start with the documentation map, pending-work roadmap, and glossary. The Git branches and stored state guide explains the application, Story, configuration, review, and orphan state branches and their safe retention rules. For a complete explanation of the runtime, prompt composition, Repository brief, phase lifecycle, Git state transfer, approvals, Epic planning, Jira, workspaces, VS Code, telemetry, and security boundaries, read How Singularity Flow works. The VS Code UI remediation and regression contract covers active Story navigation, timeout recovery, responsive behavior, and visual fixtures. For the implementation-level path from /sf-* through the Node.js launcher, command dispatcher, prompt composer, question bridge, and Git publication, read Singularity Flow under the hood. For the exact model boundary, model-disabled execution, external-command policy, and human-authored artifact flow, read Model independence and manual authorship.

Conversational developer guidance

Developers do not need to memorize the lifecycle command set to find the next safe step. The shell, Copilot, and VS Code all read the same durable workspace, repository, and work-item records and use the same deterministic guidance planners. They do not share an in-memory conversation or global state.

Use the surface that is already open:

My Work can join a private, machine-local journal at read time. sflow journal refresh records one bounded offline Git observation; sflow journal today shows at most three progress and three attention summaries. Journal bytes remain outside Git, are never pushed, and are never Story evidence or a productivity score. Use /sf-journal in Copilot or sflow explain local-work-journal for privacy, retention, export, and deletion controls. Successful lifecycle commands append only a bounded semantic outcome after the authoritative operation completes; journal failure cannot fail or replay that operation. On a later local day, Home and /sf-home can show Yesterday — where you stopped from the same machine-local facts, without depending on the previous Copilot model or conversation.

The conversational router recognizes seven closed intents. It is deliberately not a free-form command parser:

A recommendation names the active context, explains why the action is next, summarizes recorded artifacts, checks, and approvals, and reports the workspace, repository, identity, worktree, and remote preflight state. It also discloses what the action can change and whether confirmation is required. New Story intake still requires the work description, definition of done, and an explicit remote base branch; conversational wording never supplies those product decisions silently.

All conversational routes resolve to read operations first. Read-only questions may be answered immediately, but Continue, Start, Generate, Submit, Next, pull-request creation, and every review or approval ceremony require an explicit selection. Ambiguous wording asks for clarification, the displayed command is only a preview, and raw developer prose is not retained in the routing result. Help questions are classified model-free as concept, procedure, diagnosis, comparison, command discovery, or recovery; weak matches say no grounded answer exists and close matches return choices. Use singularity-flow nextsteps [WORK-ID] when you want the full ordered NOW, THEN, and ALTERNATIVE plan instead of one recommendation.

For an outcome that spans several Stories or sessions, use /sf-goal. A Goal requires observable success criteria and can link existing Stories or Initiatives across the active workspace. Its local durable record is shared by the CLI and Copilot, but remains personal advisory state: selecting or completing a Goal never starts work, advances a phase, grants approval, moves a Git ref, or claims that a change was proved. See sflow explain goals-and-outcomes.

Requirements

• Node.js 20 or newer for the CLI and VS Code extension build.
• Git with a configured identity.
• A Git remote when git.publish: required is configured.
• GitHub CLI authentication is recommended so lifecycle events can record the authenticated GitHub login as well as Git identity.

Install and initialize

npm install --global ./singularity-flow-0.9.0.tgz
cd your-repository
singularity-flow init --work-id WORK-123 --base main --fetch
git add singularity
git commit -m "[WORK-123][bootstrap] Initialize Singularity Flow"
git push -u origin setup/WORK-123
singularity-flow start WORK-123 --from-branch setup/WORK-123

This branch-local bootstrap is the recommended path when main is protected: init --work-id uses setup/, leaving the actual Story branch available for start. Singularity Flow creates or reuses WORK-123, writes configuration only on that branch, and never pushes or modifies main. If the process configuration should become the shared default for later Work IDs, raise a normal reviewed pull request from the bootstrap branch; direct access to main is not required.

For the first repository in an organisation, use the URL-based bootstrap. It clones the detected application branch, publishes a collision-safe sflow/govern/- proposal, seeds the independent sflow/config and state branches, and leaves the application branch unchanged:

singularity-flow bootstrap  --capability platform --name "Platform"
# The command prints the exact pull-request command for the configuration proposal.

In VS Code, run Singularity Flow: Guided Start — Capability, Workspace, Work. The three-step journey maps the capability, carries it into workspace creation, selects the new workspace, and opens first-work intake. It uses the same preflights and confirmations as the individual screens and resumes after the one window reload needed to activate a first workspace.

Use --direct only as an explicit opt-out in a repository whose application branch intentionally accepts direct configuration pushes.

Initialization installs:

.github/
└── agents/
    ├── architect.agent.md
    ├── developer.agent.md
    ├── product-owner.agent.md
    └── qa.agent.md
singularity/
├── workflow.yml
├── impact.yml
├── portfolio.yml
├── capabilities.yml
├── prompts/
│   └── copilot-planning.md
└── templates/
    ├── common/
    ├── feature/
    ├── bugfix/
    └── chore/

These files are ordinary reviewed repository files and remain fully editable. Agent Markdown follows GitHub Copilot’s repository-agent convention under .github/agents/; singularity/agents.lock.yml is reserved for optional trust-pinned remote Markdown dependencies. Initialization can be audited or safely repeated on any branch:

singularity-flow init --check
singularity-flow init --repair

For a fresh repository, deterministic smart initialization can propose the commands and minimum repository law without running the repository, contacting the network, or calling a model:

# Effect-free: inspect stacks, commands, proof gaps, origins, suggestions, and exact target bytes.
singularity-flow init --smart-detect --dry-run --json

# Save a reviewable, non-active proposal, then regenerate and activate only that exact proposal.
singularity-flow init --smart-detect --output init-proposal.json --json
singularity-flow init --smart-detect \
  --accept-proposal init-proposal.json \
  --confirm sha256:

# Metadata-only validation; this does not run tests, builds, scripts, or models.
singularity-flow precheck --quick
singularity-flow config explain --pointer /commands/verification/0

If initialization is interrupted, use the exact proposal hash reported by the CLI; recovery never deletes application work or adopts an unrelated commit:

singularity-flow init --recover --proposal sha256:

--yes accepts only visible, unambiguous defaults. It never selects optional protected-path suggestions and refuses unavailable verification unless --allow-unavailable-verification is explicit. Smart activation commits only its declared SFlow paths and preserves unrelated staged, unstaged, and untracked work. It creates the implicit repository-root capability, so a fresh repository does not need singularity/capabilities.yml. An identical rerun reports no-change; an existing non-smart configuration is never overwritten. In Copilot, /sf-init provides the same proposal-first journey. See sflow explain smart-initialization for the complete safety model.

Build manifests may be symbolic links to regular files inside the same repository. Detection binds both the link chain and the target bytes into its source hash, so changing either invalidates the readiness receipt. External, dangling, cyclic, directory and oversized targets remain refused as unsafe; do not disable the path guard to work around them.

Kotlin JVM plugins in Maven or Gradle use the existing structured JUnit test route. A .gradle.kts file alone denotes Kotlin DSL, not Kotlin application code. Kotlin Android and multiplatform builds need an explicit test target instead of a guessed JVM test task. .NET detection covers C#, F# and VB projects and .sln/.slnx solutions, prefers one solution over its same-directory projects, and reports ambiguous peer entry points. It also hashes SDK, NuGet and shared build configuration. The .NET route uses dotnet test with fresh TRX results; its current proof ceiling is module-level observation, not exact acceptance-criterion proof. Required SDKs are not installed automatically.

SwiftPM intake recognizes Package.swift, binds Package.resolved and .swift-version, and requires a confirmed structured test run instead of recording a “nothing to test” receipt. The inferred swift test command collects XCTest and Swift Testing XML from a dedicated generated report directory, retains failed/skipped counts, and clears only the known report pair before readiness execution. The proof ceiling is module-observed, not exact criterion proof. Detection does not execute Package.swift, fetch dependencies or install/accept an SDK license. Xcode-only projects require an explicit scheme, destination and structured result command; nested-only packages still need module-scoped readiness support. See Swift support status.

For large monorepos, precheck --scope dependency-test narrows the command types, not the repository directories. Module-scoped readiness and exact Kotlin/.NET criterion adapters remain follow-up work; this manifest-link fix does not claim either or a 300 GB performance qualification.

Repair copies only missing packaged files and never overwrites repository customizations. It therefore does not convert or overwrite a version-1 workflow.yml. That YAML configuration format is separate from durable JSON record migration. Registered durable records migrate to their current shape in memory while their stored bytes remain unchanged; future versions fail with an upgrade remedy. In Copilot CLI, use /sf-init [WORK-ID]; /sf-doctor also runs the read-only initialization inventory before its wider repository diagnostics.

For an existing workspace, the normal repeatable upgrade is a safe reinitialization—not a reset. It reviews every selected repository and restores only missing seeds or exact current/historical registered framework seeds, together with their framework-owned dependencies. User-created and user-modified workflows, phases, artifact sets, templates, prompts, and agents remain repository-owned and unchanged. It also refreshes exact configuration state projections and checks durable schema readability. Capability-specific publication and locator repair remain separate; user-owned capability definitions are preserved unchanged in the approved configuration mirror. Same-name and modified-seed collisions are preserved and reported instead of being guessed to be framework content. Story artifacts under singularity/work-items/ are never part of this refresh. Preview first and apply only its exact plan:

singularity-flow workspace reinitialize --dry-run
singularity-flow workspace reinitialize --confirm-plan wrip-...

Safe reinitialize refuses --resolve ...=bundled and --accept-bundled-conflicts; it cannot be used to transfer ownership of repository content to the framework. Use ordinary workspace refresh-configuration and its separately reviewed three-way conflict choices when deliberate adoption of packaged content is intended. The reviewed reinitialize candidate can upgrade a registered legacy workflow schema; immutable evidence and Git history are never rewritten. In Copilot use /sf-admin reinitialize; in VS Code run Singularity Flow: Reinitialize Framework Assets (Preserves User Content).

For a deliberate clean restart, factory reset replaces the complete singularity/ tree from the templates bundled in the currently installed npm package, removes former .singularity/ and .sdlc/ layouts, and clears both worktree-private and repository-shared .git/.../singularity-flow/ runtime state. Always preview first:

singularity-flow factory-reset --dry-run
# Then copy the exact confirmation string printed by the preview:
singularity-flow factory-reset --confirm "RESET  " \
  --expect-scope-sha256 ""
singularity-flow init --check
git status --short

Saved workspaces whose lead repository explicitly declares workflow version 1 are automatically forgotten when the workspace registry is read. This removes only the machine-local registration and active selection; it never deletes the workspace directory or repository clone. Run singularity-flow workspace prune to see the discarded registrations. Recreate the workspace after resetting its lead repository to the bundled version-2 configuration.

This discards uncommitted workflow state, generated artifacts, templates, prompts, sessions, locks, local telemetry, and pending publication records in the reset scope. It preserves application source, Git history and configuration, workspace clones, the global workspace registry, and valid custom .github/agents files not supplied by the package. A custom agent that would make the new configuration invalid is preserved byte-for-byte under .github/singularity-flow-recovered-agents//, removed from active agent discovery, and reported with its exact source, recovery path, digest, and validation reason. The replacement and any recovered agent are left uncommitted for review. In Copilot, /sf-factory-reset enforces the same preview and contributor-entered confirmation sequence.

In VS Code, open Workspaces → Fast onboarding & Git → Factory reset, or run Singularity Flow: Factory Reset Local SFlow Data (Destructive) from the Command Palette. Choose any canonical Git root; it does not need to load as a current SFlow repository first. The editor shows the engine-generated remove/replace/preserve boundary and dirty SFlow paths. If data would be lost, it requires the explicit Discard all local SFlow data choice, then the exact repository-bound confirmation. Application source, Git history, and remote sflow/config and state branches remain untouched. The replacement is local and uncommitted for Source Control review.

For a complete local restart of the current repository and this machine’s Singularity Flow registry, use the short one-shot command:

sf-reset-all --yes

It reinstalls the installed npm package’s singularity/ defaults, removes the current repository’s .git/singularity-flow/, and clears ~/.singularity-flow/ (saved workspaces, active selection, lead registry, and local CLI setup). It does not delete application source, Git history, or physical workspace and repository clones. VS Code keychain credentials are also preserved; reset Jira or Teams credentials separately in VS Code. Run sf-reset-all without --yes to preview the exact boundary.

To forget all Singularity Flow state and personalization on this machine while preserving every physical workspace, repository, branch, dirty file, manifest, and repository-local recovery record, use:

singularity-flow local-reset --forget-only --dry-run
# Review preserved workspaces and every machine-state target, then:
singularity-flow local-reset --forget-only --confirm "FORGET LOCAL"
# Short equivalent:
sf-local-reset --forget-only --confirm "FORGET LOCAL"

To instead remove every validated Singularity-managed workspace directory and clear machine-local state without uninstalling the product, use:

singularity-flow local-reset --dry-run
# Review the exact workspace paths and preserved components, then:
singularity-flow local-reset --confirm "RESET LOCAL"
# Short equivalent:
sf-local-reset --confirm "RESET LOCAL"

The destructive local-reset mode removes only workspace roots proven by both the machine registry and a matching regular workspace.json. It also clears local sessions, caches, telemetry configuration, recovery state, Singularity-named Copilot sessions, and the VS Code extension’s Singularity credentials/settings on next activation. It preserves the installed CLI, VS Code extension, Copilot plugin, /sf-* skills, unregistered repositories, and personal skills. Run it from outside the workspace directories listed by the preview.

In an interactive terminal either mode displays its complete preview and prompts for the exact mode-bound phrase in the same invocation. Cancellation, EOF, or a mismatch changes nothing. Non-interactive and --json callers must use --dry-run, followed by --confirm. FORGET LOCAL never authorizes workspace deletion, and RESET LOCAL never authorizes --forget-only.

To replace only the locally installed Singularity Flow product while keeping all repositories, workspaces, lifecycle state, credentials, and user configuration, use the fingerprint-bound clean reinstall:

sf-reinstall --checkout /absolute/path/to/sflow-source --dry-run
# Copy the exact fingerprint confirmation printed by the preview:
sf-reinstall --checkout /absolute/path/to/sflow-source \
  --confirm "REINSTALL SINGULARITY FLOW "

The preview first builds and tests an isolated copy of the selected checkout, creates and hashes the npm tarball and VSIX, and only then offers a confirmation. Applying it replaces the global singularity-flow npm package, both historical Copilot plugin identities, marker-owned direct /sf-* skills, the VS Code extension, and the installer-managed telemetry wrapper. It never runs Git and never scans for or changes repository singularity/, .singularity/, .git/singularity-flow/, branches, worktrees, artifacts, workspace clones, ~/.singularity-flow workspace selection, VS Code state, SecretStorage, Jira credentials, or personal skills. A receipt is written under ~/.singularity-flow/installations/. A successful full clean reinstall also retains the exact validated tarball and installed VSIX in the managed content-addressed version store and atomically replaces current.json with a schema-v2 rollback receipt. This is the supported product-only migration when a legacy schema-v1 receipt still points at mutable checkout artifacts; those old paths are never adopted as rollback authority. If VS Code already has the extension installed, a CLI-only clean reinstall is admitted only when a schema-v2 receipt already binds that untouched VSIX to verified content-addressed bytes. Otherwise it refuses before packaging or product removal and requires a full clean reinstall so rollback authority is complete for every installed surface. The first clean reinstall of a legacy or unreceipted installation cannot promise automatic restoration of old product bytes that were never retained. If that apply fails after removal, it keeps the verified candidate bundle and prints one exact roll-forward recovery command. After a schema-v2 receipt exists, normal source upgrades and promoted-distribution installs can admit exact prior bytes and compensate touched surfaces automatically.

Replace copied identity values safely

To replace an old login, display name, or email across the current files in a copied workspace or checkout, preview the exact files first:

npm run identities:replace -- \
  --root /absolute/path/to/copied-workspace \
  --replace "old-login=new-login" \
  --replace "Old Display Name=New Display Name"

The preview prints a fingerprint-bound confirmation. Apply only after reviewing it:

npm run identities:replace -- \
  --root /absolute/path/to/copied-workspace \
  --replace "old-login=new-login" \
  --replace "Old Display Name=New Display Name" \
  --apply --confirm "REPLACE IDENTITIES "

The utility skips .git, dependencies, build output, symlinks, binary files, invalid UTF-8, and files larger than 5 MiB. It changes current text files only; it never rewrites Git history. Do not use it to alter identity-bound approvals in active work—start a fresh Story or record a new decision instead.

For a company registry, add --registry ; credentials stay in .npmrc. If Copilot is unavailable, --cli-only replaces just the Node package and command shims. A missing code executable is reported and the already-built VSIX is retained for later installation.

For a genuinely fresh Singularity installation across the machine, run the installer from a clean Singularity Flow source checkout. Preview first:

singularity-flow fresh-install --checkout /path/to/sflow-source
# Review every path. Then perform the deletion and reinstall:
singularity-flow fresh-install --checkout /path/to/sflow-source --yes

From inside the product checkout, --checkout may be omitted. The guarded command first validates the required executable and registry, resolves one exact source commit and tree, and stages those bytes in a private detached worktree. Destructive reset begins only after that preflight succeeds, and installation executes the staged immutable source rather than the mutable checkout. The legacy ./install.sh --factory-reset form is refused because it could load checkout dependencies before npm ci.

This broader mode deletes every registered workspace directory, including its managed repository clones, documents, generated artifacts, and local caches. It also clears ~/.singularity-flow, Singularity-named Copilot session state, managed /sf-* aliases, old plugin copies, the old global npm package, and the installed VS Code extension before installing fresh copies from this checkout. Untracked singularity/, .singularity/, and .github/agents/ directories created inside the installer checkout are included in the preview and removed; any other checkout change still stops the reset. An existing directory is deleted only when its regular workspace.json validates and exactly matches its registry entry; an ambiguous entry stops the whole reset. Unregistered application directories, personal Copilot skills, and the installer checkout are preserved. The reinstall leaves a one-time reset marker; when the new VS Code extension first activates it clears Singularity Flow Jira, Teams, indexed provider secrets, onboarding profile, and extension global state.

Initialization also installs singularity/portfolio.yml. It is inert until an initiative is started and provides editable initiative-lite and enterprise-delivery profiles. See INITIATIVE-ORCHESTRATION.md for the complete multi-repository guide.

The Epic and Story pages do not start or embed a Copilot planning session. Requirements and Planning show the exact /sf-* command to run from the open repository, with one-click copy controls. The installed skill composes the selected phase, agent, Repository brief, approved inputs, agent skills, requirements, and templates inside the user’s normal Copilot CLI session. Refresh the VS Code Lifecycle view after the skill commits and pushes its result. Epic planning uses pinned Jira and uploaded source evidence.

Repository discovery before onboarding

Start with the repository’s credential-free clone URL. In VS Code, paste it into Map a capability; Create workspace links to that mapping flow when a capability is not mapped yet. If you do not have the URL, Browse repositories… is an optional way to find one. Selecting a result fills the same field and checks setup read-only; it does not apply any change.

The model-free repository catalog can also find a repository by account membership before you have a clone URL or workspace:

singularity-flow repositories list --scope known
singularity-flow repositories search payments --scope provider --provider github --host git.example.corp

The default known scope reads only saved SFlow registries and retained approved-map observations; it performs no Git or provider request. Provider scope is an explicit bounded read through the active stored gh identity for the selected host. Listing never clones, maps, proposes, or creates a workspace. Each row has an expiring opaque selection reference; repositories select --action inspect revalidates it and prepares the existing onboarding inspection. In VS Code, use the optional Browse repositories… control below the Git URL field. Selecting a result runs the same read-only setup check as entering its URL. Copilot exposes the same journey as /sf-repositories; it discloses provider-backed names only after an explicit provider/host request and labels the private/internal count. Without that request, use the native picker or direct CLI.

Define a constitution

Open Configuration → Flow Policy & sign-off → Constitution, or run Singularity Flow: Constitution from the VS Code command palette. The editor is also available in Workflow Studio. Add articles with a stable ID, title and rule. Human-reviewed principles support Must/Should and required/optional evidence. Machine articles select an existing phase approval minimum; their rule text is generated from the effective configuration, not written or enforced by a model.

Expand Workflow applicability to select Off, Warn or Enforce for editable workflows. Seeded workflow settings remain read-only; duplicate a workflow before customizing its mode. Use Review changes → Check changes → Publish for review, then review and activate the resulting configuration proposal. With a local working-tree authority, the same Changes screen explicitly offers Write to this repository instead. Defining an article never silently activates a new machine policy or changes a running Story. New Stories pin the approved constitution; existing Stories retain their original rules.

Approved article meanings cannot change under the same ID. Replace withdraws the old article and creates a new ID; Withdraw retains its text and history. Existing malformed or hand-edited files are reported instead of overwritten. The form supports workflow-declared Markdown paths under singularity/, outside Story/runtime directories (normally singularity/constitution.md). Read-only CLI equivalents remain singularity-flow constitution check --json and singularity-flow constitution show --json.

Set up or recover one repository

Use one repository-centric command for first setup, recovery, and supported upgrades:

singularity-flow capability onboard  --dry-run --json
singularity-flow capability onboard  --confirm-plan  --json

The dry run returns a repository-onboarding-plan/v1 with one understandable status, exact effects and preserved data, and the next Shell and Copilot commands. It does not write. In VS Code, the repository URL and setup summary stay in one flow: inspect the summary and confirm the plan once. The CLI passes its planId; apply checks that the observed repository refs are unchanged before it writes. /sf-capability-map follows the same preview-and-confirm flow.

The normal statuses are Ready, Ready to restore, Update available, Linked to team configuration, SFlow repository · capability not mapped, Not set up, State branch not recognized, Could not check Git, Needs a choice, and A newer SFlow version is required. Recovery never overwrites an unrecognized state branch, and a linked delivery repository continues to its team configuration instead of creating its own authority. Git object IDs, authority pins, and cache leases remain in diagnostics rather than the normal journey.

Recognized state is enough to resume when sflow/config is missing. A repository-bound verified configuration mirror restores the exact retained history commit when available and otherwise reconstructs it from the verified mirror. A delivery locator continues to its verified lead, while lifecycle-only state proceeds to capability mapping without inventing ownership.

Advanced recovery modes are explicit and always previewed separately:

singularity-flow capability onboard  --migrate --dry-run --json
singularity-flow capability onboard  --recreate --dry-run --json
singularity-flow capability onboard  --reset-local --dry-run --json

Neither Copilot nor the UI chooses one of those modes on the contributor’s behalf. --migrate means custom-preserving reconciliation of missing or exact historical packaged seeds in a valid workflow-v2 configuration; it does not migrate an unsupported workflow-v1 configuration. --recreate builds the installed workflow-v2 package and preserves verified portable organisation data from current configuration, a repository-bound state mirror, or retained history. --reset-local works offline and clears only matching capability lead-registry and organisation cache entries. It does not clear workspace registrations, the active workspace/session, FOS pins, clones, or remote refs.

For routine upgrades, install a matching current CLI package and VS Code extension first. Then open Workspaces → Upgrade / migrate SFlow (or Configuration → Upgrade / migrate SFlow), review the selected workspace’s exact plan, and type its plan ID in the scrollable confirmation page. Re-create is configuration recovery, not an installer or a routine migration: it cannot fix a bug in an older CLI. The safe upgrade preserves repository-owned customizations and Story history; existing Stories retain their pinned policy, rather than silently adopting new policy.

Shell equivalent:

singularity-flow workspace reinitialize  --dry-run --json
singularity-flow workspace reinitialize  --confirm-plan  --json
singularity-flow workspace migrate-schemas --json

The last command is a read-only compatibility check across active registered workspaces. Supported old schemas migrate in memory when read, not by rewriting approvals or evidence in Git. Review any reported custom-asset conflicts or unreadable records separately. A newer configuration than the installed build can read requires a compatible build; changing schemaVersion or recreating configuration is not a substitute.

Story Start automatically reloads a missing or stale application-checkout configuration from the approved authority, before its launch readiness check. It validates and reuses that exact snapshot in the managed Story checkout; it does not rewrite the application checkout, recreate sflow/config, install dependencies, or run tests. If authority is absent or unreadable, Start returns a structured recovery plan and VS Code shows its repository-bound recovery actions. Diagnose Git access, review setup or the safe upgrade preview, then refresh intake and retry the same Story ID. Invalid or unsupported approved policy is never silently replaced with an older local workflow.

An applied plan may safely stop with a resumable partial result:

An onboarding proposal (sflow/config-change/onboarding/...) is not a capability-map proposal (sflow/config-change/capability/...). capability proposals lists only the latter. For a new repository, the one setup confirmation shows what installed defaults will create; a separate diff review is not required. Fresh setup creates sflow/config directly with an exact create lease. When restoring, migrating, or recreating existing configuration, inspect the exact changed files and diff, source and proposal commits, and any omitted paths before approval. A restore or recreate derived from another ref needs a proposal because Git cannot atomically prove that source ref stayed fixed while creating a new authority branch. Repository policy can also reject direct creation. If setup returns a proposal, list pending setup branches with capability setup-proposals --lead --json, inspect the named branch and commit with capability setup-proposal --lead --json, then explicitly approve it with capability setup-activate --lead --confirm --json. If direct-branch protection cannot be verified, the command refuses until you explicitly choose --acknowledge-unprotected or use external review. Activation uses an exact lease and cannot bypass server review controls; if those controls require an external merge, use the repository’s normal review path. Existing capability-map changes remain exact-commit review proposals and become active only after approval. Recheck onboarding after approval before creating a capability-map proposal. A missing sflow/config target may need an authorized maintainer to establish the branch from the reviewed setup commit.

Selected branch snapshots use depth-one, no-tags, blobless partial clones. Onboarding deletes and refuses a snapshot above 16,384 local files or 128 MiB before checkout or parsing, even if the server ignores filtering. Verified state mirrors are bounded further to 512 declared assets, 64 KiB of aggregate path bytes, and 64 MiB of asset content.

Onboard a team in one proposal

Use /sf-capability-map in Copilot and choose Onboard a team, or run singularity-flow capability map-team --help. A team becomes one collection capability and each new shipping repository becomes a delivery child. The journey lists repositories visible through the explicitly selected GitHub/GHE identity but labels them Not checked yet until inspected. Only repositories the contributor selects are inspected, sequentially, with a maximum of 20 per onboarding.

Inspection produces four honest outcomes: Will add, Will link, Needs a choice, or Left out. A failed or unresolved repository is set aside rather than blocking eligible selections. Before mutation, Flow shows the exact tree and complete shell command. One confirmed map-team invocation then creates one atomic review proposal; it does not activate the map or write an application branch. Review the proposal and activate its exact full commit separately. Reusing the same matching team ID later adds selected children without recreating the collection.

singularity-flow capability map-team order-services \
  --lead "https://git.example.corp/retail/sflow-config.git" \
  --name "Order Services" --jira-project ORDS \
  --member order-routing-service=https://git.example.corp/retail/order-routing-service.git \
  --member-name order-routing-service="Order routing" \
  --link existing-order-ui \
  --json

The native team panel transports the same normalized fields with capability map-team --request --json. Its closed UTF-8 document is capped at 512 KiB, contains only credential-free repository locators, and is created privately and removed after the CLI finishes. This keeps a valid 20-repository request below the Windows process command-line limit; the individual flags remain available for small manual shell invocations.

After activation, create a workspace separately and repeat --capability to select capabilities from this or other teams. The workspace preview remains the authority for which repositories will be cloned and which managed checkouts can be reused.

Capabilities, and the workspaces made of them

What an organisation builds is a forest of one or more capability trees. Capability kind is a closed pair: a collection groups related capabilities and names no repository; a delivery ships from one or more repositories. Either kind may contain child capabilities. A capability may be top-level or linked under another capability, and each tree may go to any depth. Jira projects and team names belong to a capability, not to a repository or workspace. Optional type: tech|business is a separate domain classification; it is not capability kind.

The approved map lives at singularity/capabilities.yml on the lead repository’s dedicated sflow/config configuration branch, with the repositories it refers to declared in singularity/portfolio.yml on that same branch. Editing checks nothing out permanently: Flow clones sflow/config into a temporary directory, pushes a sflow/config-change/capability/... review branch, and discards the checkout. It never writes the lead repository’s application default branch.

End-to-end guide: capability onboarding to a working workspace

The example below onboards a payments-api delivery capability whose approved configuration is owned by the platform lead repository. Replace every example URL, ID, and local path; capability and workspace IDs use lower-case kebab case.

1. Locate the configuration authority

singularity-flow capability leads --json
singularity-flow capability organisation \
  "https://git.example.corp/acme/platform.git" --refresh --json

Use the lead repository that owns the organisation map. If no lead is registered, pass its clone URL explicitly in the following commands; the first proposal can initialize a lead repository that does not use Singularity Flow yet, without a prior workspace or bootstrap operation.

2. Propose the capability

singularity-flow capability map payments-api \
  --lead "https://git.example.corp/acme/platform.git" \
  --name "Payments API" \
  --kind delivery \
  --type tech \
  --parent payments \
  --repository "https://git.example.corp/acme/payments-api.git" \
  --metadata applicationId=APP-1001 \
  --metadata costCenter=PAYMENTS \
  --json

A delivery capability requires at least one repeatable --repository; a collection groups other capabilities and must not name repositories. For a delivery spanning several repositories, repeat --repository and add --lead-repository to identify which delivery repository owns state. The result returns a review branch, its sflow/config base, and a full proposal commit. Nothing is active yet, and no application branch was changed.

3. Review the exact proposal

singularity-flow capability proposals \
  --lead "https://git.example.corp/acme/platform.git"

singularity-flow capability proposal "" \
  --lead "https://git.example.corp/acme/platform.git" \
  --json

Review the complete commit, changed-file set, and diff. The proposal must target sflow/config and contain only approved configuration. Keep the full proposalCommit; a shortened SHA is deliberately rejected during activation.

4. Approve and activate

singularity-flow capability activate "" \
  --lead "https://git.example.corp/acme/platform.git" \
  --confirm "" \
  --json

Activation makes a normal non-force update, records the reviewer and exact commit in the capability ledger, and projects the approved map to the orphan state branch. It never updates the application default branch.

If activation reports CAPABILITY_CONFIGURATION_UNPROTECTED, the dry-run proved that this identity can update an unprotected sflow/config. Follow organisational policy and, only after explicitly accepting that exception, repeat the exact command with --acknowledge-unprotected. If branch protection or permissions reject the normal update, merge the preserved proposal branch into sflow/config through the repository’s review controls, then rerun the same exact-hash capability activate command. It detects the external merge and completes the activation audit and state projection. capability publish repairs a projection; it is not a substitute for activating a reviewed proposal.

5. Verify onboarding readiness

singularity-flow capability organisation \
  "https://git.example.corp/acme/platform.git" --readiness --refresh --json

singularity-flow capabilities doctor payments-api --json

Proceed only when the capability is present in the active tree, every delivery repository resolves, and the configuration/state authorities are ready. A proposal branch by itself is not an onboarded capability.

6. Register the workspace

singularity-flow workspace prepare \
  "https://git.example.corp/acme/platform.git" \
  --id payments-work \
  --name "Payments workspace" \
  --capability payments-api \
  --lead-capability payments-api \
  --base "/approved/workspaces" \
  --json

prepare is a non-materializing preflight. It returns a bootstrapId, the exact destination, repository plan, branch plan, and any authentication, network, disk, or state-branch blockers. Review that output, then resume the same plan:

singularity-flow workspace bootstrap resume "" \
  --confirm payments-work \
  --json

The normal resume registers the workspace and its repository bindings without cloning application code. Selecting a collection includes its descendants. Selecting a delivery includes all repositories it ships from. --lead-capability identifies the repository used as the workspace’s default context; it must be one of the selected delivery capabilities. Interrupted setup is resumed with the same bootstrap ID. Use explicit --clone for a checkout now, or --initialize to check out and initialize its state branch immediately.

7. Select and verify the workspace

singularity-flow workspace use payments-work --repository payments-api --json
singularity-flow workspace current --json
singularity-flow workspace list --json

The current result names the workspace, lead repository, selected repository, and planned local repository path. A newly registered repository may be marked missing until work needs its files. /sf-start in Copilot and Lifecycle Start work in VS Code materialize the repositories needed by an unambiguous Story capability before reading workflow policy or starting the Story. If intake has no exact capability binding, VS Code prepares the required workspace set rather than guessing; unrelated repositories otherwise remain planned. For explicit early code access, run singularity-flow workspace repair --repository .

VS Code and Copilot path

• In VS Code, use Configuration → Capabilities → Map capability. For a new repository, Set up SFlow creates sflow/config directly from the installed defaults after the exact plan check; it needs no separate setup approval. If branch policy rejects direct creation, open Review setup proposal, approve its exact commit, and Check setup again. Capability mapping still creates a separate proposal, open Review capability proposal. Merge and acknowledge uses exact-commit activation and cannot bypass branch protection.
• If setup was proposed on another laptop or before this extension was installed, open Review proposals → Find setup proposal… and enter that repository’s credential-free clone URL. The queue checks its setup branches directly.
• Use Workspaces → Create workspace, review the preflight, resume it, then choose Work here. The selected workspace becomes the context for Lifecycle and Configuration.
• In Copilot, /sf-capability-map performs propose, review, and explicit activation; /sf-workspace prepares or selects the workspace; /sf-workspace-session attaches the current Copilot session to its repository.

Common onboarding failures

• “No capability map to publish” — the proposal is not active. Review it and run exact-commit capability activate; do not call capability publish first.

• Proposal branch creation works but activation is rejected — creating a branch does not prove permission to update protected sflow/config. Use the repository’s normal review merge, then rerun exact-hash activation.

• Activation says review-required — the proposal and approved branch are unchanged. Merge the named proposal into sflow/config through normal repository controls, then run the returned exact activation command to record the audit and projection. Activation says activation-pending for a network, credential, or transport failure instead; correct that classified cause and run the same command.

• “Confirmation must be the exact proposal commit” — re-read capability proposal and use its complete proposalCommit, not the displayed short SHA.

• Proposal is empty, conflicted, from unrelated history, or contains application files — activation changes nothing and retains the branch for inspection. Run singularity-flow capability fsck --lead to classify the exact ref. Rebase or replace a reviewable proposal with a configuration-only proposal; never force it into sflow/config. An unrelated-history proposal can be removed only with the fsck-reported full commit and a reason:

  singularity-flow capability discard-proposal "" \
    --lead "" --confirm "" \
    --reason "configuration authority was intentionally re-created" --json
  

  The exact-SHA lease refuses a moved or valid proposal and preserves approved configuration, state, application branches, and every other proposal.

• Missing state or configuration readiness — rerun activation after an external merge, then use capability organisation --readiness --refresh before workspace creation. If activation completed but projection is pending, run the returned capability publish --lead ... repair command; do not repeat the merge.

• Workspace materialization is interrupted — inspect workspace bootstrap status or workspace doctor --network, repair the named cause, and resume the existing bootstrap ID. If its bounded attempt budget is exhausted, keep the same reviewed plan and explicitly open another recovery generation:

  singularity-flow workspace bootstrap retry "" \
    --confirm "" \
    --reason "corrected the reported blocker" \
    --json
  

  Retry proves that any partial target belongs to that exact bootstrap before it resets attempt counters; it never adopts an unrelated directory.

In VS Code, Configuration → Review proposals lists pending changes across all registered lead repositories and works without an active workspace. Select a row to inspect the exact diff and activate the reviewed commit.

Fresh repository setup creates sflow/config from installed defaults with an exact create lease, without changing the application branch. It falls back to a review proposal if remote branch policy rejects direct creation. Restoring or migrating existing configuration remains a separate reviewed operation; reusable configuration is preserved, while runtime state, evidence, and telemetry are not imported into shared configuration.

Map publication is retry-safe across timeouts and dropped connections. Before any remote write, SFlow requires an explicit Git-configured user.name and user.email; it never attributes a proposal to an operating-system username or unknown@invalid. The proposal is bound to the exact approved sflow/config commit with Git leases, and a failed transport response is reconciled against the exact remote proposal ref before SFlow reports success, failure, conflict, or an unknown outcome. An unknown outcome retains the exact commit and structured inspection/retry argv in a private machine-local recovery record with a seven-day expiry; public diagnostics expose only its opaque recovery ID and expiry. Expired records and their proven SFlow temporary checkouts are swept before a later capability mutation (there is no background cleanup daemon). Recovery is never reconstructed from a partial command. Local lead-cache or temporary-cleanup problems are reported separately and cannot undo a confirmed remote proposal.

The VS Code Map screen saves its exact validated command before starting. Cancellation, closing the panel, or losing the process result requires Inspect remote outcome before Retry exact request becomes available. Inspection opens an existing proposal, recognizes an already-active capability, or permits replay only after both are absent; the engine still rejects any authority movement in the final race. Repository discovery scans pending proposals in bounded pages, with 64 active/unreadable entries per inspection and an absolute 4,096 advertised-ref ceiling. Every explicit fetch page is also capped at 64 refspecs and 24 KiB of conservatively encoded Windows UTF-16 argv, so long proposal names create smaller safe pages. Reaching the ceiling reports partial coverage and blocks a new mapping instead of guessing that none exists. See the capability-map Git robustness plan for the failure contract, implemented guarantees, and remaining physical office/Windows evidence matrix.

Capabilities may carry any number of organisation-defined text attributes under metadata, for example application IDs, cost centres, owner codes, or service tiers. The CLI accepts repeatable --metadata KEY=VALUE; the VS Code capability screens provide matching key/value rows. These values are stored with the capability in singularity/capabilities.yml—the approved authority is the lead repository’s sflow/config branch, and the reviewed map is projected to the orphan state branch. Use --metadata KEY= with the legacy expert capability edit flow to remove one key. New CLI-managed maps are changed through capability add, capability protect, and capability depend; each command creates a receipt-bound review proposal and never edits an application branch. Version-1 maps retain their legacy behavior until an explicit reviewed capability adopt-managed operation is approved.

When a Story starts, Flow copies one exact approved sflow/config revision onto the new Story branch and commits singularity/configuration-source.json. That record pins the source repository, full configuration commit, and SHA-256 of every copied configuration asset. Later phases therefore cannot silently change when shared configuration advances. Application main remains application code and never receives capability, workflow, agent, prompt, skill, or template edits from this path. In VS Code, creating, editing, deleting, or initially mapping a capability automatically opens Review capability proposal. That screen shows the exact source and target commits, changed files, and diff. Merge and acknowledge performs a normal non-force merge into sflow/config, publishes the orphan state projection, records an append-only activation event, and refreshes any retained Workspace form. Flow first dry-runs the exact target push. If the remote permits a direct update, the actor must explicitly acknowledge that protection is not enforced for them. If the remote rejects it, the proposal remains intact for the repository’s normal pull-request controls; the application default branch is never changed.

After an external review merge, run the proposal’s same exact-hash capability activate ... --confirm action; it detects that the commit is already present and publishes the orphan state projection. capability publish remains a projection-repair command, not a substitute for exact proposal activation. Unreviewed configuration is never copied to an application branch or the state proof branch.

Organisation reads use the capability mirror on the orphan state branch when it is available and fall back to the approved sflow/config copy during bootstrap or repair. A validated machine-local cache is keyed by the configuration branch commit, so unchanged reads avoid another clone. If the remote is temporarily unreachable, the CLI and VS Code show the last validated map with an explicit stale warning. Use capability organisation --refresh or the VS Code refresh action to bypass the cache and contact the remote.

When a Story or Initiative starts, Flow resolves the owning capability from the active workspace (or accepts --capability when a repository participates in more than one). It snapshots the capability path, map SHA-256, inherited policy, and active leases into the lifecycle branch. That immutable snapshot then tightens phase availability, write scope, checks, approval identities and thresholds, self-approval, and document/token budgets; later capability-map changes cannot silently rewrite work already in progress.

Use one diagnostic from the terminal, Copilot, or the VS Code Diagnostics command:

singularity-flow capabilities doctor
# Copilot: /sf-capability-doctor

A workspace is a set of capabilities and a local working directory. The repositories it clones are what those capabilities ship from, derived rather than listed again. One chosen capability is the lead capability; the repository it ships from is where the orphan state branch is created when the workspace is initialised.

singularity-flow workspace prepare https://git.example.corp/acme/platform.git \
  --id commerce-work \
  --capability commerce --lead-capability payments-api \
  --base ~/work --initialize

# After reviewing the returned preflight and exact target:
singularity-flow workspace bootstrap resume  \
  --confirm commerce-work

Choosing a capability includes everything beneath it, the way choosing a directory includes its contents — and the selection is recorded rather than its expansion, so a capability added to the map later is picked up by a workspace that asked for its parent. No two workspaces may occupy the same directory. Workspace setup does not require Jira. prepare creates no workspace destination: it records an integrity-checked session and classifies runtime, path, disk, registry, authentication, network, and branch failures. resume rechecks before using the existing staged clone transaction, so interrupted setups continue by bootstrap ID instead of starting over. Use workspace doctor --network for an explicit remote diagnostic. See WORKSPACES.md.

Already have the clone? singularity-flow workspace adopt --id --base --dry-run --json produces a preserving proof before it creates a workspace shell. Dirty clones need the exact content-aware --confirm-dirty hash from that preview. SFlow does not fetch, switch, stash, commit, reset, clean, edit remotes, or move the clone. Pre-Story pushes use durable transport intents: singularity-flow push status inspects them and singularity-flow push retry re-observes the exact remote ref before a bounded retry; neither path force-pushes.

The editor extension exposes both actions from one Workspaces view. A saved workspace is its local directory plus its mapped capability scope; the selected workspace shows both together beneath the workspace list. Work here makes it the context used by Lifecycle and Configuration. If the extension activated before any workspace was selected, VS Code reloads that same window once to bind those views to the lead repository; it never creates another window. Open lead repository remains a separate, explicit action for editing code and is not required just to select a workspace.

Workspace display names can be changed locally. Before archiving, Singularity Flow refreshes every participating repository and proves that every Story is closed or cancelled; inaccessible repositories and active Stories block the action. Archived workspaces move into a separate VS Code folder while their checkouts, branches, generated artifacts, approvals, and history remain available for inspection and restore.

The VS Code sidebar deliberately separates work from setup. Favorites stays at the top and lets each developer pin the menus they use most through Choose favorites; those selections are stored only in personal VS Code state and never enter repository configuration. First-time users start with Guided Start first, followed by persona-relevant work and setup menus. Favorites and Lifecycle open by default while the supporting sections remain collapsed; the sidebar remembers later choices. Lifecycle is the intake and delivery view: start Initiative, Epic, or Story intake, choose the workflow for that work, inspect the selected workflow’s phases and artifacts, run the next action, and make approval decisions. Workflow choices disappear from Lifecycle after intake because that choice is then pinned to the active work. Configuration is where the machinery is created and edited: workflow and phase design, gates, World Model source scope, workflow.yml, portfolio.yml, artifact templates, Agent Markdown and its prompts, skills and prompt packs, remote agent resources, mappings, and approval policy. Capabilities are not a fourth lifecycle/configuration concept; they are shown as part of the selected Workspace scope.

Story intake lets you search workflow names, descriptions and phases, and star workflows as personal favourites for each repository. Favourites appear first; Other workflows starts collapsed and opens when searching. These preferences do not change workflow configuration or the selected Story workflow. Workflow Studio also searches workflows and routing rules, agents, skills and reusable instructions. Seeded, read-only workflows and editable workflows have distinct colour accents and labels. Agent cards and workflow step inspectors expose read-only saved prompts, applicable skills and linked instructions, including built-in agents; these are saved definitions, not the final Story-bound prompt.

From Copilot, /sf-workspaces lists saved contexts and /sf-workspace selects one. From a terminal, singularity-flow workspace copilot starts Copilot in the selected repository and names the session for the workspace; a Story branch adds the Story ID. Singularity renders labels such as Payments / MOB-123 > as a context banner because Copilot does not provide a supported way to replace its own native > input marker.

Once selected, the workspace repository is also the explicit fallback for repository-scoped CLI and /sf-* commands launched outside a Git checkout. A current Git checkout always wins, and setup, reset, installation, and workspace administration commands are deliberately never redirected.

If Copilot or VS Code is already open in the wrong checkout, run singularity-flow session workspace [--repository ID] [--story ID] from any directory, invoke /sf-workspace-session, or choose Singularity Flow: Attach Copilot Session to Workspace from the VS Code command palette. The command records the machine-local workspace context and identifies the exact repository. VS Code replaces the current window with that repository and opens a fresh chat; a terminal receives the exact workspace copilot command because a child process cannot change its parent process’s directory.

Before a Story exists, Change Flight Plan in Home, the command palette, or the editor context menu runs the same model-free repository engine as singularity-flow impact preview. It binds proven/inferred/unknown findings to a committed baseline and does not create lifecycle state. The separate, exactly confirmed impact start ceremony revalidates that baseline, creates an isolated worktree and Story branch, and pins a compact agent context and verification checklist. Accepted work is compared with actual changed paths at submission, and unexamined scope expansion blocks.

Before a Story or Epic exists, Lifecycle → Explore workspace impact can call Copilot over revision-pinned, disposable copies of every selected workspace repository. It needs no Work ID and creates no branch. The local report records the repository commits, staged documents, prompt, summary, and freshness. Changes to a captured repository HEAD or to the saved prompt/summary make the report stale. A useful result can be copied into the workspace document inbox and then explicitly selected as intake evidence; advisory output is never silently treated as approved lifecycle state. The terminal equivalent is singularity-flow workspace impact analyze --description "..."; /sf-workspace-impact provides the guided Copilot CLI flow.

Interrupted workspace creation is resumable: selecting the same workspace ID and exact repository plan retries missing clones and updates the local materialization journal. Singularity Flow rejects configuration drift at an existing target, canonicalizes recent workspace aliases, and refuses linked workspace manifests rather than crossing a local storage boundary.

singularity/portfolio.yml remains an advanced editable runtime contract for teams that use initiative orchestration, but it is not a separate workspace database and is not required to create or open a workspace.

Each participating repository can carry application identity and arbitrary scalar key/value metadata. Use Initiatives → Portfolio designer → Add repository, or edit the same YAML directly:

repositories:
  mobile:
    url: [email protected]:company/mobile.git
    defaultBranch: main
    required: true
    metadata:
      appId: APP-1001
      name: Mobile application
      owner: Digital Channels
      costCenter: CC-42

This metadata stays in singularity/portfolio.yml, is pinned into initiative state, copied into local workspace manifests, included in planning context, and passed to materialized story seeds.

The leading dot was intentionally removed: repository-owned configuration, prompts, templates, artifacts, and workflow state now live in the visible singularity/ folder. Private machine/session data remains under .git/singularity-flow/ and ~/.singularity-flow/.

Start an initiative from GitHub Copilot:

/sf-initiative-start INIT-2026-001
/sf-initiative-phase
/sf-initiative-next
/sf-initiative-status

Starting uses main (or the configured default branch) only as the source baseline for the new initiative branch. It does not merge anything into main; completed code still follows the repository’s normal pull-request and merge process.

Epic planning is the streamlined default

For a Jira Epic that should end with reviewed Stories, an approved high-level specification, canonical repository branches, and Product Owner validation, use the four-phase epic-planning profile:

/sf-epic-start MOB-100
/sf-epic-sources
/sf-epic-requirements
/sf-epic-story-draft
/sf-epic-publish
/sf-epic-status
/sf-epic-next
/sf-epic-sync
/sf-epic-drift
/sf-epic-review
/sf-epic-review-decision
/sf-epic-merge-plan
/sf-stack
/sf-refresh-branch
/sf-regression-investigate
/sf-story-start
/sf-story-fetch
/sf-story-checks
/sf-worldmodel
/sf-agents
/sf-telemetry

Stories in the Epic’s own repository are branched from the Epic branch, which is the only branch carrying the approved Epic artifacts their seeds cite by hash:

main
└── MOB-100          Epic branch: requirements, Story plan, specification
      ├── MOB-123    Story branches, cut from the Epic branch
      └── MOB-124

Story pull requests target the Epic branch and merge in a dependency-safe stack. singularity-flow stack sync --epic MOB-100 publishes the current order to the orphan state branch in every participating repository; singularity-flow pr reads it and refuses out-of-order work. After every blocking Story has merged, preview and open the final Epic pull request with:

singularity-flow epic pr --epic MOB-100
singularity-flow epic pr --epic MOB-100 --create

The detected application branch—not a hard-coded main—is the base. Stories in other repositories keep branching from that repository’s own default branch — an Epic branch is never created where one does not already exist. See INITIATIVE-ORCHESTRATION.md for the full topology.

The VS Code extension presents one navigation for every role. An Epic planning section carries the journey — Epics, Requirements, Planning, Create Stories, Copilot CLI handoff, and Artifact templates — alongside Delivery, Decisions, Configuration, and Learn in the same collapsible sidebar (⌘/Ctrl+B). The role chosen during onboarding suggests an initial planning agent; it does not route to a different shell, and there is no experience to switch between. The active workspace remains visible in the top bar, while each phase page shows the exact command for the normal Copilot CLI.

Click the Main menu disclosure in the Singularity Flow sidebar to collapse or expand its destination list. Workspace context, pinned shortcuts and utilities remain available; the local preference survives refreshes and VS Code restarts.

Planning combines Story decomposition and the high-level specification without hiding either phase. Generated Stories and their REQ-nnn/AC-nnn allocation are reviewed before the publication screen creates or attaches each Jira Story, uses the returned Jira key as its stable Work ID, and creates the corresponding canonical Git branch with seed and receipt commits. Copilot explicitly stops after drafting so business reviewers can use the UI to edit, split, add tasks and key/value metadata, or adopt a Jira Story that is not linked to the Epic. Direct adoption preserves the Story’s existing Jira parent. Successful Jira/Git publication completes planning and opens the delivery dashboard. Developers use Delivery → Story intake to choose an assigned Jira Story or enter its exact key, inspect the parent Epic and acceptance criteria, confirm repository routing, and select the workflow; its phase agent is automatic. The Story can be started directly without first creating or selecting an Epic in Singularity Flow; any Jira parent is retained as optional lineage. The same entry point is available through /sf-story-start; a Story published by an Epic can still be fetched with /sf-story-fetch. Intake pins the Jira snapshot, creates or resumes the canonical Jira-key branch, commits, and pushes before phase work begins. Developers finalize independently, and the Product Owner closes the Epic only after the exact parent specification and every blocking Story’s spec-to-code evidence match. Each stage keeps completed work available for audit.

Artifact templates include a visual drag-and-drop builder with a reusable section library, reorderable canvas, in-place guidance editing, live Markdown preview, and exact Source mode. Templates may also be loaded from a public HTTPS Markdown URL after a bounded, credential-free fetch and a SHA-256/content preview. The selected bytes are copied into the repository and become the local template; generation never depends on the URL remaining available.

An Epic can be imported from Jira or created without Jira. Local Epics reserve collision-safe IDs such as SF-E-001 through an atomic branch push; their Stories retain immutable STORY-nnn plan IDs and receive scoped Work IDs such as SF-S-001-001. The prefixes and padding are configurable in singularity/portfolio.yml, and the selected identity authority is pinned for the life of the Epic. The same lifecycle is available as singularity-flow epic .... Pinned source files stay in Jira attachments, Artifactory, SharePoint, S3, or an approved HTTPS location; Git carries immutable source records and lineage rather than large source bytes. SharePoint delegated OAuth in VS Code remains unsupported until the documented corporate redirect-flow and proxy spike succeeds; credentials must remain in approved secure stores. Requirements trace SRC-* → REQ-nnn → AC-nnn; plan version 2 then traces these to STORY-nnn → returned Jira key/numeric ID → canonical branch → optional Developer child branch → review packet → configured repository-check and PR evidence → conformance → exact-hash decision.

Developers register custom branches explicitly:

singularity-flow story branch create feature/login-ui --parent MOB-123
singularity-flow story submit

Reviewers use Epic workspace → Review or singularity-flow epic review MOB-123. Exact-SHA checks can read configured GitHub repository-check and PR state without running repository code on the reviewer’s machine. See HELP.md for the complete workflow and corporate credential/storage behavior.

When publishing, the user explicitly selects which approved requirements and specification outputs Jira receives. Those files and hashes are part of the reviewed write plan and are uploaded with hash-stamped filenames to the Epic, every Story, or both. After all blocking Stories are complete and their exact review packets, GitHub checks, and conformance tree hashes match, the Product Owner runs singularity-flow epic complete --confirm or uses the wizard to create and push the immutable Epic completion report.

Built-in help

The canonical product manual is HELP.md. For an end-to-end diagram and operational walkthrough, use HOW-TO.md. To run the complete lifecycle without a Jira connection, use LOCAL-RUNBOOK.md. Load all help or one focused topic from the terminal:

singularity-flow help
singularity-flow help quick-start
singularity-flow help jira-intake
singularity-flow help troubleshooting
singularity-flow help --json

For a safe first experience, run the complete quick-fix rehearsal:

singularity-flow guide --first-run
# Preserve the isolated toy repository for inspection:
singularity-flow guide --first-run --keep

The guide creates a temporary Git repository with a passing Node test, records readiness against its exact base commit, then runs the real start → prepare → publish → submit lifecycle through deterministic Implement and Verify phases, prints the sandbox boundary before execution, and removes it after success unless --keep is supplied. It makes no network request and invokes no model. A failure is retained with failure.json so it can be reproduced.

Low-risk repository work can select the built-in quick-fix work type. Its two-phase rail uses deterministic evidence, no human approval for Implement, and a hash-bound verification policy waiver only when every declared predicate passes. Unknown risk, protected paths, semantic boundary changes, failed checks, multiple repositories, or an oversized change fall back to normal human review.

Source-writing phases also use work intervals. The committed baseline pins the phase’s starting source/configuration state; optional local checkpoints store only hashes under .git; and submission atomically records a final specification-to-change reconciliation. Protected or oversized quick fixes are blocked with a non-destructive escalation plan. No CI provider or Git-host workflow file is required. See Work intervals.

Developer-experience diagnostics are opt-in and bounded:

singularity-flow snapshot WORK-123 --include lifecycle --timings --json
singularity-flow snapshot WORK-123 --include lifecycle --if-revision  --json
singularity-flow report WORK-123 --timings
singularity-flow pr describe WORK-123 --format markdown

--if-revision returns a notModified envelope without repeating snapshot payload. pr describe generates deterministic Markdown locally; it may copy the text to the clipboard or update an existing PR only when those actions are explicitly requested. It never creates a PR implicitly.

In Copilot, /sf-help loads the manual for general questions; /sf-help WORK-123 loads the selected work item’s immutable workflow guide. VS Code also provides the explicit, model-free @sflow participant. Its reviewed-help commands (/help, /why, /how, /recover, /explain, and /topics) share the packaged offline resolver, while /next, /status, /checks, /converge, /docs, /inputs, /workflows, /approve, and /validate render declared deterministic engine operations with zero model calls. The safe mappings are intentionally narrow: /next reads nextsteps, /checks uses precheck --quick, /inputs is an active-phase dry run, and /approve only reviews context before handing off to the existing guarded approval surface. Unknown free text shows command help; it is never model-routed. Drafting commands are not implemented. See the @sflow Chat Participant boundary.

Reviewed help cites the selected topic and opens guarded /sf-* actions as partial queries that the user must review and submit. VS Code includes the same resolver in the always-available Help view and searchable Help Center, bundled for offline use. It has focused entries for capabilities, workspaces, Story intake, workflow state, agents, prompts, world-model composition, troubleshooting, every /sf-* skill, and every top-level CLI command.

Copilot start, resume, approval, rejection, and agent flows use its interactive question facility to show the YAML-configured choices. Choose a label instead of typing an agent or workflow ID. During start or approval, a shell without persistent stdin uses a short-lived one-time selection receipt, so the contributor or reviewer can stay in Copilot. If interactive questions themselves are disabled, Singularity Flow stops rather than choosing a default.

Use /sf-nextsteps [WORK-ID] whenever you need a compact ordered plan. Its CLI equivalent, singularity-flow nextsteps [WORK-ID], works before initialization, without an active work item, during pending publication recovery, throughout every phase, and after completion. It is read-only and marks actions as NOW, THEN, or ALTERNATIVE.

For an executable, revision-bound plan use /sf-continue or Lifecycle → Continue safely in VS Code. The underlying commands are singularity-flow action plan --json and singularity-flow action authorize --action --confirm followed by singularity-flow action execute --action --authorization . The local authorization is bound to that exact plan/action and is consumed once. The plan expires and becomes stale whenever the branch, HEAD, staged/unstaged file bytes, or lifecycle snapshot changes. See Governed execution for the action protocol, isolated Git publication, review-packet binding, and its explicit containment boundary.

One-command local update and installation

For an end-user or office-laptop distribution, keep the promoted release directory intact and use its platform wrapper; do not clone this source repository:

# macOS/Linux
./install.sh --artifact-key /trusted/artifact-builder-public.pem

# Windows PowerShell / Command Prompt
.\install.ps1 --artifact-key C:\trusted\artifact-builder-public.pem
install.cmd --artifact-key C:\trusted\artifact-builder-public.pem

Those distribution scripts verify the signed artifact receipt against an independently obtained artifact-builder public key before executing package code, snapshot the exact local tarball and VSIX, then validate the release manifest, checksums, identities, versions, and canonical operator assets. They run no Git command. Use --dry-run for a preview, --registry for an approved corporate registry, or --cli-only without Copilot/VS Code. To remove only installed product surfaces while preserving every repository, workspace, credential, personal skill, and retained audit artifact, run the matching uninstall.sh, uninstall.ps1, or uninstall.cmd; preview first or add --yes. See DISTRIBUTION.md.

From a clean clone, update the tracked branch, create the distribution tarball, install it globally, remove any previous Copilot plugin identities, and install the bundled plugin by default (or one approved organisation marketplace plugin when explicitly configured):

./install.sh

npm run install:local is an alias for the same script.

Every source-install mode requires Node.js 20 or newer. Use the narrowest surface that you need:

# Rebuild this exact clean checkout; do not fetch or pull.
./install.sh --no-update

# Install the CLI and VS Code extension without requiring or changing standalone Copilot assets.
./install.sh --skip-copilot

# Build, install, and verify only the VS Code extension.
./install.sh --vscode-only

# Install only the global CLI.
./install.sh --cli-only

# Resume an interrupted activation from the exact already-staged tarball and VSIX.
./install.sh --from-staged-artifacts

--vscode-only requires the code command and does not install the global CLI, Copilot plugin or skills, telemetry helper, or workspace configuration. It is mutually exclusive with --cli-only, --skip-vscode, and --skip-copilot. --no-update still requires a clean Git checkout; it only suppresses network update of that checkout. --skip-copilot leaves existing standalone Copilot assets untouched while retaining the CLI and VSIX installation.

Build, test, package, and retained-artifact messages describe staging only; they do not mean that the product was activated. Matching singularity-flow --version output is not sufficient either, because distinct builds can share a semantic version. A full installation is complete only after the installer verifies the exact installed singularity-flow --build provenance, verifies every selected surface—including singularity-flow plugin verify --json when Copilot is installed—and commits ~/.singularity-flow/installations/current.json. Only then does it print the exact final banner Singularity Flow product activation — COMPLETE AND VERIFIED. Explicitly narrowed modes print Singularity Flow product activation — PARTIAL BY REQUEST; a normal install whose optional manager is unavailable prints Singularity Flow product activation — COMPLETE WITH SKIPS and names the skipped surface in its receipt. If no recognized final activation banner appears, use the recovery command printed by the installer and do not infer success from earlier build/package output or version labels. If activation committed but the process stopped before that banner, use the printed receipt inspection and exact-build verification commands; do not blindly rerun installation.

The VSIX contains its own engine for extension features, but the portable Playwright MCP host entry uses the global singularity-flow launcher. On a blank machine that needs managed MCP, use --skip-copilot (CLI + VSIX) rather than --vscode-only; the latter deliberately does not install an MCP host launcher.

--from-staged-artifacts is emitted automatically when product activation is interrupted. It is a standalone recovery mode: it reloads the machine-local activation journal, verifies the recorded checkout, installer, validator, content-addressed retained artifact paths, package identities, versions, and SHA-256 digests, and then retries only activation. The validated tarball and VSIX are retained under ~/.singularity-flow/installations/versions/sha256//, so recovery does not depend on mutable checkout archives. Activation is protected by a process-owned lease and operation/revision compare-and-swap journal updates. Recovery also rebuilds its isolated CLI prefix from the retained tarball before executing it; a prior mutable cache is never reused. It never pulls Git, installs source dependencies, runs tests, rebuilds, or repackages, and it ignores registry/mode environment overrides. If the original install requested workspace configuration refresh, recovery leaves that separate Git operation explicitly pending and prints its command. Successful activation does not delete the retained version set; the deliberate machine reset boundary removes the installation store.

The VSCE packaging toolchain is installed once and cached from its committed lock, content-addressed by that lock, the npm registry, Node major, platform, architecture, and sealed physical tree, under ~/.singularity-flow/toolchains/vsce/. Every later install verifies the complete cached tree and reuses it — the step that used to re-download the toolchain on each run now takes seconds. ./install.sh --refresh-vsce-toolchain forces a verified reinstall. Published generations are immutable and retained because another installer may still be using them; cleanup is deliberately manual rather than an unsafe automatic deletion. Each step of the installer prints its own elapsed time.

A normal install also checks the repository selected by the active workspace. If the new package contains workflows that repository does not have yet, the installer adds only those missing packaged workflows. Existing and customized workflows and repository agents are preserved. The repository must be clean, and the resulting configuration changes are deliberately left uncommitted for review and publication. Use --no-workspace-workflow-sync to skip this step. The fingerprint-bound --clean-reinstall path never reads or changes a workspace.

For existing workspaces created by older builds, follow the standalone configuration refresh guide. It covers the VS Code and CLI preview/apply flow, plan IDs, conflict choices, protected configuration branches, state projection, and bundled model-routing upgrades.

On Windows, open Git Bash in the Singularity Flow checkout and use the Windows wrapper. It checks Node.js 20+, updates the checkout safely, confirms that the CRLF Agent Markdown fix is present, and delegates to the same validated installer:

bash ./install-windows-git-bash.sh

# With a corporate npm registry / Artifactory
bash ./install-windows-git-bash.sh \
  --registry "https://artifacts.company.com/artifactory/api/npm/npm-virtual/"

It does not change global or repository core.autocrlf, run dos2unix, or rewrite tracked files. Keep registry credentials in the user’s .npmrc.

Before dependency installation, the script asks you to choose:

1. The registry currently returned by npm config get registry.
2. The public npm registry.
3. A custom company registry or Artifactory URL.

For a non-interactive or repeatable company setup, pass the registry explicitly:

./install.sh \
  --registry "https://artifacts.company.com/artifactory/api/npm/npm-virtual/"

You can provide the same override through an environment variable:

SINGULARITY_FLOW_NPM_REGISTRY="https://artifacts.company.com/artifactory/api/npm/npm-virtual/" \
  ./install.sh

The standard npm environment variable works as well, which is useful when an enterprise launcher already provides it:

NPM_CONFIG_REGISTRY="https://artifacts.company.com/artifactory/api/npm/npm-virtual/" \
  ./install.sh

Registry precedence is --registry, SINGULARITY_FLOW_NPM_REGISTRY, NPM_CONFIG_REGISTRY, then npm config get registry (including user and project .npmrc files).

For an interactive installation, run ./install.sh, choose Custom company registry / Artifactory, and enter the registry URL. The --registry option takes precedence over the environment variable and interactive selection.

Keep Artifactory authentication in your user or company .npmrc; do not put credentials in the registry URL. For example:

registry=https://artifacts.company.com/artifactory/api/npm/npm-virtual/
always-auth=true
//artifacts.company.com/artifactory/api/npm/npm-virtual/:_authToken=${NPM_TOKEN}

Export the token only in the shell or CI secret store, then run the installer:

export NPM_TOKEN="your-artifactory-token"
./install.sh \
  --registry "https://artifacts.company.com/artifactory/api/npm/npm-virtual/"

The selected registry is exported as NPM_CONFIG_REGISTRY for the complete installer process. It therefore reaches every npm ci, npm run, lifecycle subprocess, packaging helper, and global installation—not only the first dependency install. The script rejects credentials embedded in a URL, never prints tokens, and does not modify persistent npm configuration.

To reinstall the currently checked-out product without pulling or changing any repository, use the same shared planner through the installer:

./install.sh --clean-reinstall --dry-run
./install.sh --clean-reinstall \
  --registry "https://artifacts.company.com/artifactory/api/npm/npm-virtual/" \
  --confirm "REINSTALL SINGULARITY FLOW "

This path delegates to singularity-flow reinstall before the normal installer performs any Git check. All build and package validation completes before the first installed surface is removed. After verification, each artifact installed by the selected mode is retained under ~/.singularity-flow/installations/versions/sha256/ and current.json is replaced with its schema-v2 bindings. A full clean reinstall therefore migrates a legacy receipt for every installed product surface before the next normal upgrade.

By default, the installer loads the Copilot plugin bundled inside the installed package. To use a company-managed Copilot marketplace instead, provide its approved source:

SINGULARITY_FLOW_MARKETPLACE_SOURCE="company/singularity-flow" \
  ./install.sh --registry "https://artifacts.company.com/artifactory/api/npm/npm-virtual/"

The installer provides a named sflow_copilot compatibility helper, but never shadows the user’s copilot executable. Start an instrumented session with sflow copilot, sflow workspace copilot, or VS Code Continue with Copilot CLI. After one machine-local disclosure, the Node launcher creates a unique metadata-only OpenTelemetry file for that process under /singularity-flow/telemetry/raw/; prompt, response, source, and tool content capture is forced off. Existing endpoints and authentication headers are preserved, and unsafe composition reports conflict while work continues. Manual Copilot and native IDE chat remain unmetered by SFlow. Phase publication commits only a sanitized summary to singularity/work-items//telemetry/-gen.json.

Model-backed generation snapshots each UTF-8 prompt once into a private temporary file for exact hashing, admission, optional consented capture, and cleanup. The verified text is delivered through Copilot CLI’s ACP stdio protocol; the temporary file is never attached to Copilot. Prompt content never enters process arguments, environment variables, logs, telemetry, or invocation receipts; receipts retain only its SHA-256, byte count, encoding, selected transport, and negotiated ACP protocol version. The default input policy is 8 MiB. singularity-flow doctor blocks model-backed generation when the configured Copilot executable does not advertise --acp. Provider transport defaults to auto; acp-stdio forces a reviewed ACP wrapper and attachment is an explicit legacy compatibility option. Provider configuration must not override adapter-owned cwd, prompt, ACP, attachment, model, or tool-policy flags.

The single self-contained install.sh performs:

validate Node.js 20+ and the clean checkout
git pull --ff-only (unless --no-update)
choose configured, public, or custom npm registry
npm ci --registry=
npm run check
npm run vscode:build
npm test
npm pack --json
npm run vscode:package
retain and verify candidate and prior exact artifacts
code --install-extension  --force
code --list-extensions --show-versions
 plugin install
configure metadata-only Copilot OpenTelemetry
npm install --global  --registry=
singularity-flow --version
singularity-flow --build
singularity-flow plugin verify --json (when Copilot is selected)
commit ~/.singularity-flow/installations/current.json
refresh approved configuration in registered workspace repositories
print Singularity Flow product activation — COMPLETE AND VERIFIED

The CLI is replaced directly; it is not uninstalled first, so a failed npm replacement does not deliberately remove the working command. All requested artifacts are built, validated, and copied into a content-addressed machine-local version store before activation; completing those build and package steps only stages the candidate. The retained tarball is installed and executed from a digest-addressed private prefix before any product mutation. Activation then replaces and verifies the VSIX, Copilot plugin, and telemetry files before replacing and verifying the globally callable CLI last. Exact build provenance, rather than semantic-version equality alone, binds that CLI verification. The committed installation receipt is the transaction commit point; workspace configuration refresh remains a separate Git operation after activation.

The schema-v5 activation journal binds exact candidate and prior CLI/VSIX artifacts, byte-for-byte snapshots of touched configuration files, completed/skipped surface states, and a compare-and-swap revision. Any failure or handled signal before the commit point compensates in reverse dependency order and verifies restoration of every touched surface. A successful rollback records rolled-back and prints the exact --from-staged-artifacts retry command. An interrupted recovery completes rollback before retrying the same verified candidate. If any restoration cannot be verified, the journal records rollback-failed, blocks a new activation, and directs the operator to that journal instead of claiming success or guessing from version labels. Post-install PATH or version mismatches use this same recovery path and cannot leave an unexplained activating record.

The script refuses a checkout with uncommitted changes and never resets, rebases, or force-pushes. It keeps the generated singularity-flow-.tgz in the repository root for local recovery or reinstallation and prints the installed CLI and Copilot plugin versions. That source-install tarball is not a promotable release artifact; corporate distribution uses the retained, signed build-once pair. Fully exit any running Copilot CLI process, then open a new terminal and start Copilot from the repository after installation; environment variables cannot be injected into a process that was already running.

Direct ./install.sh --factory-reset is intentionally refused. A machine-wide reset must be previewed and run through singularity-flow fresh-install; that trusted CLI boundary verifies every deletion target and stages the exact reviewed source commit before removing anything.

Configuration

In VS Code, open Configuration → Open Configuration Center for the guided overview. People & approvals manages real human Git identities and authority groups; MCP tools manages agent/phase/tool policy and reports whether the matching VS Code or Copilot host server is configured. These are deliberately separate from AI agents. All visual saves are validated by the CLI and preserve unrelated YAML content. After a save, Configuration → Unpublished configuration lists every changed file and provides Review & publish configuration. That action previews the exact scope, creates one commit, and pushes the current approved configuration-review branch; unrelated working-tree changes block it, and the engine never publishes configuration from the protected application branch. See docs/CONFIGURATION-CENTER.md.

singularity/workflow.yml is the definition for new work items. It contains:

• workTypes: profile-specific phase sequences, template overrides, optional phaseOverrides, and a pinned intelligence contract for Repository brief (worldModel), AST, and agent-brief use.
• inputsMode: backward-compatible off, audit-oriented record, or blocking enforce phase dataflow.
• phases: default templates, approved upstream inputs, artifact paths, write scope, clarification checkpoints, quality commands, and approval rules.
• agents: prompt-only agents and suggested phases.
• approvalSecurity: independently controls self-approval and automatic enrollment of a new Git identity before new work pins its authority groups; both default on outside the regulated profile.
• approvalAuthorities: real-human approval groups matched by Git email or authenticated GitHub login.
• documents: allowed upload phases, maximum file size, and text-preview limit; work types may override this policy.
• git: remote name and whether publication is required.
• governance: protected paths and traceability rules.

Template resolution is deterministic: a work-type override wins, then the phase default is used, and initialization fails when neither exists. At start, the resolved profile, configuration hash, and template hashes are stored in workflow.json. The selected work type is then immutable for that work item.

The bundled profiles are:

The two benchmark profiles are paired controls. They use the same five phases, artifact templates, default agents, write scopes, approvals, and rejection routes. Benchmark A gets the Repository brief, requests one bounded optional AST page, and passes approval-bound agent briefs between phases. If AST is unavailable, Benchmark A continues through ordinary repository file access. Benchmark B leaves out the Repository brief and AST context, and passes the full approved artifacts instead. The selected profile and intelligence policy are immutable for the Story. Select the two profiles across comparable Stories; do not treat a hand-selected pair as randomized evidence. Use Flow Impact receipts when measuring the result.

Agent mappings connect native Copilot agents to Agent Markdown. Each phase activates its configured default agent automatically; /sf-agent is an explicit, audited override. An agent changes instruction context only and can never grant approval permission. Phase approvals reference approvalAuthorities; every decision records the human identity, matched authority group, identity-assurance level, and active agent separately.

For figma-mobile, committed PNG exports are the canonical approval baseline. VS Code and the generated local gallery provide verified thumbnails, full-size previews, and local PDF viewing; visual-verification evidence registers the pinned design, implementation screenshot, and diff image under the Story. Live Figma links open externally over HTTPS and are explicitly labeled as mutable convenience context.

Start and resume

singularity-flow workspace branches --json
singularity-flow start ENG-142 --title "Add invoice export" --from-branch main --fetch
singularity-flow resume ENG-142 --fetch

Every new Story first requires an explicit branch published by every required repository; no branch is preselected, even when only one is available. With no source flags, start then asks whether intake comes from a Jira story or a manual description and documents. Manual mode asks for the title, audience, problem, outcome, acceptance criteria, and supporting file paths or HTTPS URLs. After source intake is complete, start asks for a workflow template (feature, bugfix, chore, classic-delivery, figma-mobile, benchmarking-a, benchmarking-b, poc-lite, poc-workflow, or another configured work type).

classic-delivery follows Intake → Code → Testing → Code checking. Code runs the configured structured repository tests and commits a normalized passing test receipt to the Story branch. Testing reviews those Code-phase results; Code checking verifies the same Git-bound evidence. Both refuse missing, failed, or stale receipts. Configure the repository’s test adapter in the approved workflow before starting Code work. Fresh repositories receive the packaged work type at initialization; for an existing repository, preview singularity-flow workflow install classic-delivery --dry-run, then install it through its approved configuration path.

For review feedback, Classic Delivery supports an explicit reject-to-Code rework cycle. /sf-revision-attachments can stage a local reviewer file against an active Story, but does not run a REV loop or replace Code’s committed test receipt. Check singularity-flow revision activation --json before assuming REV execution is available; the current build reports it disabled. See Classic Delivery review and rework for both Copilot and shell steps.

poc-lite is the repository-native, model-free profile. PLAN records the bounded objective, ACT delivers product and executable test changes, VERIFY records the configured repository checks, and FINALIZE stops for one explicit human quality approval. The profile leaves out the Repository brief, disables AST, model, agent-brief, and MCP requirements, and imposes no external service dependency; use global --no-model when invoking it from the CLI.

poc-workflow is the enterprise Playwright profile. It requires a hash-bound Playwright host attestation and live browser smoke receipt, accessibility/runtime/visual evidence, real TypeScript and Playwright execution, at most two kernel-enforced human-authorized repair generations, and separate quality and engineering decisions at publication. The kernel restricts its generation and repair phases to recognized test-automation paths, so an instruction cannot authorize product-source edits. It never runs an autonomous healing loop or writes the selected base branch. Its phases use separate least-privilege analyst, explorer, test-developer, and validator agents. The first phase activates its default agent; resume activates the current phase’s default. The active agent is stored locally in .git/singularity-flow/session.json; opening a session does not create a repository commit. It is prompt context, not a real identity or approval credential.

The receipt flow is local and auditable: singularity-flow choices begin start --json returns the live remote-base, YAML-derived intake, and workflow options; Copilot presents them through ask_user; and each exact answer is recorded with singularity-flow choices answer. Approval receipts bind to the submitted phase, generation, artifact hashes, and exact phase confirmation. The phase agent is recorded as audit context; approval authority is recalculated from the reviewer’s identity and the pinned authority registry.

Receipt answers use a short-lived filesystem mutation lock, so Copilot can submit different answers concurrently from separate CLI processes without losing one. Every read verifies the receipt schema, filename token, repository HEAD shape, and bounded expiry timestamps before accepting it. Shared CLI JSON and text replacement also uses collision-resistant temporary files and cleans them after either success or failure.

New repositories keep session selection explicit but nonblocking in singularity/workflow.yml:

session:
  workItemSelection: prompt # off | reuse | prompt
  requireBeforeTools: false

The bundled Copilot plugin registers only a nonblocking subagentStart command hook. It maps an exact Copilot custom-agent name to the same Singularity Flow agent ID for the local session. It never injects a startup model prompt and never denies Bash, edit, search, or view tools; deterministic CLI lifecycle checks remain the enforcement boundary. The retained session-start and agent-guard CLI hook handlers are available only for teams that deliberately install a custom command-hook policy.

The skill catalog is held to plugin/skills/registry.yml: all bundled skills are explicit /sf-* operations, so installation never takes over native Copilot requests. Select the SFlow workflow agent to opt into ordinary-language routing. /sf-pause pauses that guidance on this machine; /sf-pause off restores it without changing or advancing a Story. Switch to the host’s default Agent and start a new chat to discard previously loaded phase instructions. Terminal equivalent: singularity-flow pause [on|off|status] --json. Body budgets, output contracts, utility-agent routing, and measurement guidance are documented in docs/SKILL-EFFICIENCY.md. Run npm run audit:skills to verify the catalog.

New repositories also rotate Copilot context after an approved phase:

contextPolicy:
  onApproval: new       # keep | compact | new
  onRejection: keep
  phaseOverrides:
    implementation: compact

The boundary is advisory because a child process cannot clear its parent Copilot CLI conversation. After the approval commit and push succeed, the CLI prints the exact next actions. new prints /clear followed by /sf-next, compact prints /compact followed by /sf-next, and keep continues directly. The next skill reconstructs its phase prompt from approved Git artifacts, pinned inputs, the selected agent, templates, agent Markdown, and the Repository brief. Clearing therefore removes conversation history without losing state. It reduces tokens sent in later phases but does not refund tokens already consumed. Rejections default to keep so the correction conversation retains review feedback. The normalized policy is pinned in work-item and initiative state; configurations without it retain the earlier keep behavior.

/sf-session applies this policy in order. For each new Copilot session it uses an exact work ID or Jira ID explicitly supplied by the contributor, or asks for one when it is absent. Discovery refreshes only the configured state branch (normally state), verifies its reachable ledger chain, and reads each indexed Story’s exact pinned workflow. It does not enumerate or fetch every application branch. Attachment fetches only the selected Story branch, checks out a missing local tracking branch, and fast-forwards to the verified remote head. It then activates the current phase’s default agent. /sf-agent explicitly overrides that prompt context without changing the human identity or its approval authority.

Production bootstrap enables the state ledger. Legacy repositories must enable it in approved configuration, initialize it with singularity-flow ledger init, and explicitly reconcile retained lifecycle intents with singularity-flow ledger reconcile before remote Story discovery. An empty verified ledger means no indexed Stories; missing, corrupt, or unrefreshable state is an explicit diagnostic, never a fallback scan or a claim that there are zero Stories. session open-local remains available for an already verified managed local checkout. Reconciliation cannot invent records for historical Stories that never emitted ledger intents.

VS Code publication waits for the checks, commit and push, then acknowledges the exact completed JSON receipt. It does not wait for the subsequent review/snapshot rendering. Pending same-checkout watcher reads wait outside the shared process pool while a mutation runs; other repositories remain responsive. Named progress stages distinguish artifact checking, discovery, validation/tests, commit and push. Candidate integrity, fresh required tests, secret scanning, hooks and concurrency checks are unchanged.

The attach path is deliberately conservative: missing, malformed, ahead, or diverged branches stop with a clear message, as does a dirty tree when attachment would require a checkout or fast-forward. If the requested Story branch is already checked out and its HEAD exactly matches the freshly fetched remote HEAD, attachment may bind the new Copilot session in place while preserving unpublished phase edits. It never creates a work branch, merges, rebases, resets, stashes, force-checks out, or discards local work. Run it directly with singularity-flow session candidates and singularity-flow session attach ENG-142. Copilot must already be open inside a clone of the application repository so singularity/workflow.yml and its configured remote are known; when the selected branch is absent locally, Git materializes it from the remote rather than cloning a duplicate repository.

Reviewers can open /sf-inbox or run singularity-flow inbox to fetch a repository-wide queue of committed phases awaiting approval. The inbox reads workflow state directly from remote work-item branches without checking each one out. It shows the work/Jira ID, title, phase, generation, approval threshold, waiting time, human authority groups, artifact path, self-approval warning, and exact remote commit. Selecting an item uses the same conservative session-attachment flow before displaying the complete phase documents; it never approves automatically.

No ID or agent is inferred, and the active agent never replaces the authenticated Git identity in audit records. Existing repositories without session behave exactly as before (off). The resolved policy is pinned into each work item so a base-branch YAML edit cannot weaken an active item silently.

On another terminal, resume --fetch fetches and fast-forwards the work-item branch. Committed branch state is the handoff protocol; the local session file is not part of it.

Jira intake

Jira access uses Atlassian REST directly. Jira Cloud needs only the Jira URL, Atlassian username/email, and PAT/API token. The VS Code connection command presents exactly those credential fields, stores the token in SecretStorage, and sends the standard Basic-auth value base64(username:PAT); it never requests an Atlassian password:

export JIRA_BASE_URL="https://company.atlassian.net"
export JIRA_USERNAME="[email protected]"
export JIRA_PAT=""

JIRA_EMAIL and JIRA_API_TOKEN remain accepted aliases. The CLI does not load .env files. Set these values for the current shell, inject them from a password manager, or configure them as protected CI secrets. Discover optional custom-field IDs and then export the fields used by your Jira site:

singularity-flow jira fields --query "Acceptance Criteria"
singularity-flow jira fields --query "Story Points"
singularity-flow jira fields --query "Sprint"

export SINGULARITY_FLOW_JIRA_ACCEPTANCE_FIELD="customfield_12345"
export SINGULARITY_FLOW_JIRA_STORY_POINTS_FIELD="customfield_10016"
export SINGULARITY_FLOW_JIRA_SPRINT_FIELD="customfield_10020"
# Optional comma-separated additional fields:
export SINGULARITY_FLOW_JIRA_EXTRA_FIELDS="customfield_10001,customfield_10002"

Verify access before starting work:

singularity-flow jira status
singularity-flow jira doctor
singularity-flow jira pull ENG-142
singularity-flow jira assigned --project ENG
singularity-flow start ENG-142 --jira --from-branch main

Jira Cloud and Jira Data Center are both supported. Data Center uses JIRA_DEPLOYMENT=data-center and a Bearer JIRA_PAT; the Cloud path uses username plus PAT/API token with Basic authentication. singularity-flow jira status, projects, epics --project, children, and permissions --project provide read-only discovery. The Copilot CLI exposes the same operations as collision-safe skills:

• /sf-jira-status checks the connection and authenticated Jira identity.
• /sf-jira-doctor checks the active workspace, repository Jira policy, CLI credential availability, identity, configured projects, permissions, boards, and Epic visibility, then prints corrective actions.
• /sf-jira-assigned lists incomplete Stories assigned to that identity.
• /sf-jira-board lists Stories grouped under active/future sprints and never queries the backlog.
• /sf-jira-update changes one Story only after displaying its current state and receiving exact Story-key confirmation.

Discover boards and retrieve sprint work without backlog:

singularity-flow jira boards --project ENG
singularity-flow jira board 42 --state active,future --type Story

Explicit direct updates use Jira’s available transitions and dedicated assignee, priority, sprint, and comment APIs. Every mutating command requires the exact Jira key:

singularity-flow jira transitions ENG-142
singularity-flow jira transition ENG-142 --to "In Progress" --confirm ENG-142
singularity-flow jira assign ENG-142 --to me --confirm ENG-142
singularity-flow jira priority ENG-142 --to High --confirm ENG-142
singularity-flow jira sprint ENG-142 --to 81 --confirm ENG-142
singularity-flow jira comment ENG-142 --text "Ready for review" --confirm ENG-142

The CLI does not infer a transition or silently skip transition screens that require additional fields.

For corporate use, enable and constrain the connector in singularity/portfolio.yml, then run Singularity Flow: Connect Jira Securely in VS Code. The token is validated before VS Code stores it through SecretStorage; it never enters Git, prompts, logs, or workspace files. The extension exposes it only to the short-lived CLI child process. Host/project allowlists, deployment/auth mode, permitted writes, and owned fields remain repository policy. Use singularity-flow jira doctor for the complete read-only diagnostic.

When singularity/portfolio.yml is absent, initialize or configure the repository from Configuration before starting Jira intake.

Initiative-planning Jira writes are never immediate UI mutations. initiative jira-plan produces and pushes an exact reviewed diff; initiative jira-apply --plan additionally requires an approved Plan/Elaboration phase, Jira permission preflight, exact initiative confirmation, unchanged Jira updatedAt values, and a plan that still matches the pinned connection, deployment, and project policy. Applied operations produce committed receipts, and retries accept only receipts that match the exact reviewed plan. That planner excludes status, assignee, sprint, priority, and resolution. A separately invoked /sf-jira-update is an operator action against one exact Story and is not part of the initiative write plan.

Manual story intake without Jira

Manual intake has the same durable state-transfer behavior as Jira intake. Put the supplied story details in YAML or JSON; Markdown and plain-text briefs are also accepted. The structured format can capture the user, problem, desired outcome, scope, stakeholders, urgency, constraints, dependencies, acceptance criteria, risks, notes, and supporting documents. See examples/manual-story.yml for a complete example.

In VS Code, choose Start new work and leave Create without Jira selected. Enter a Work ID and title, use the larger description editor, and optionally choose as many as four local supporting documents or images, naming each one and choosing, for each, where it is kept (committed to Git or on this machine only) and which phases use it. Enhance description sends the bounded draft through private standard input to the configured model with tools disabled and puts its advisory proposal back into the editor beside the unchanged draft for review. Apply proposal replaces the draft only after an explicit click; Discard preserves it. Enhancement never saves, starts, commits, or pushes anything. Then choose the workflow template and session agent. Create Story branch creates and publishes the same durable state as the CLI command below. If that Work-ID branch already exists, VS Code fetches and resumes it instead of creating a duplicate.

singularity-flow start WORK-123 \
  --from-branch main \
  --story-file ./manual-story.yml \
  --document ./additional-context.pdf --document-name "Additional context" \
  --document-url https://www.figma.com/design/example --document-url-name "Checkout design"

--document and --document-url may be repeated; every document needs its own name, given by the --document-name or --document-url-name that follows it, in the same order. --document-phases PHASE,...|all and --document-store git|local are given once for every document or once per --document, in the same order (--document-url-phases does the same for links); the defaults are every phase and Git. A story file may also declare a documents list containing paths or URLs, each with a name (an existing label still names it), and optional kind and phases. Relative document paths are resolved from the story file’s directory. The command copies each file to singularity/work-items//inputs/DOC-nnn/, records its SHA-256 and metadata in documents.json, and creates and pushes those exact bytes together with source.json, a readable USER-STORY.md, and the workflow state in the opening commit. Intake and later phase prompts receive this active hash-verified evidence, so another laptop does not need the original local path. It still asks the contributor to choose the workflow template; the phase agent is automatic interactively.

The model-assisted wording operation is also available directly. Its schema-versioned JSON draft contains title, description, acceptanceCriteria, and an attachments path array; the result is only an advisory proposal and does not mutate a Story:

singularity-flow story enhance-description --draft-stdin --json < story-draft.json

When existing code is reference-only, attach its repository and branch without making it a writable Capability member:

singularity-flow start SPARK-RULES-1 --from-branch main \
  --work-type reference-driven-build \
  --title "Create PySpark batch rule evaluation" \
  --description "Use the Java API as reference; deliver only to this PySpark repository" \
  --reference-repository java-rule-engine=https://github.example/office/java-rule-engine.git \
  --reference-branch java-rule-engine=release/2026-q3

SFlow resolves the branch to an exact SHA before Story mutation, stores that immutable pin in the Story, and materializes a detached, ignored checkout for generation. It never branches, commits, or pushes the reference repository. VS Code provides structured ID/URL/branch fields, a provisional read-only check, and a Lifecycle health section. Generation receives a bounded model-free navigation overlay; it does not read or build a World Model for a reference and never blocks because one is absent. See Reference repositories at Story intake.

For a short manual request without a story file:

singularity-flow start WORK-123 \
  --from-branch main \
  --title "Add invoice export" \
  --description "Finance needs a repeatable export of filtered invoices." \
  --acceptance-criteria "An authorized user can export the filtered invoice set."

Help for the selected workflow template

At any time after starting work, show the chosen template, its complete phase sequence, artifacts, suggested agents, human approval authority groups, approval thresholds, current position, and exact next action:

singularity-flow guide WORK-123

From Copilot, use:

/sf-help WORK-123

The guide is read-only. Depending on state, it recommends /sf-phase, /sf-submit, /sf-approve or /sf-reject, and /sf-progress after completion.

For the complete sequence of immediate, subsequent, and alternative actions instead of the full template explanation:

singularity-flow nextsteps WORK-123

From Copilot, use /sf-nextsteps WORK-123.

To execute one next action instead of only displaying the plan, use either form:

/sf-next

sflow-next
# equivalent: singularity-flow next

Those two commands are the router pair. After the router selects an action, report that action’s own pair separately. For example, phase generation is Copilot: /sf-phase and Shell: singularity-flow prepare planning; /sf-phase is never the equivalent of singularity-flow next. A completed action and the remaining next action are also reported under separate labels, so a recommendation is never described as something already executed.

The command performs exactly one lifecycle action. It recovers a pending push, prepares and composes the active generation, submits an already-published generation, opens the normal interactive approval flow, or runs the terminal gate after completion. Story context comes from the workflow prompt, so starting another Story does not create a task-guide requirement. The legacy --task flag is accepted for compatibility and ignored by lifecycle composition; use an explicit wm compose --task command only when intentionally requesting an ad-hoc task guide. Copilot completes and publishes a prepared artifact; it does not silently chain that publication into submission. Approval verifies the real reviewer identity and authority group, activates the phase agent, then requires exact phase confirmation; every approval gets its own commit and push.

Progress

singularity-flow progress ENG-142
singularity-flow progress ENG-142 --json
singularity-flow progress ENG-142 --markdown

Progress is based on approved phases, so it is deterministic: approved phases / total phases. The command shows an arrow-based workflow map in addition to the progress bar and detailed phase table. Completed (✓), current (▶), awaiting-approval (◆), and pending (○) phases are visually distinct. It also shows percentage, current position, generation count, approvals received/required, uploaded-document count, and token usage. It never guesses partial completion inside an unapproved phase. --markdown returns a bounded presentation with headings, a visual journey, and a phase table; /sf-progress uses this form so Copilot renders the result instead of relaying a terminal table.

Workflow performance reports

Generate a report from the committed work-item history without changing lifecycle state:

singularity-flow report ENG-142
singularity-flow report ENG-142 --format json
singularity-flow report ENG-142 --format html --out workflow-report.html

From Copilot, use /sf-report ENG-142. Markdown is the default; JSON exposes the derived data and HTML includes script-free inline charts. Reports show total and per-phase wall-clock duration, approval waiting, active time, generation/rework count, rejections, self-approvals, provider/model identity, exact token usage with per-model totals, quality-check duration, and the largest approval-latency bottleneck. An open approval request accumulates waiting time through report generation.

When Copilot leaves token counts off its spans, the report charts what it did instead: requests, turns, model and tool calls, estimated premium requests (from optional tokens.premiumMultipliers), quota and model-substitution events, and the size of the prompt SFlow composed for each phase, against its budget. Each count is marked observed, partial or unavailable; none is shown as zero when it was not captured.

CLI responsiveness is separately from workflow duration. Run npm run benchmark:dx to measure the pinned reference fixture, or add --timings to a command to see dispatch, module load, and execution stages. Local POC and release gates run npm run benchmark:dx:enforce automatically, so an absolute-budget regression cannot be packaged unnoticed. See Developer-experience performance. Audited but deliberately deferred performance work is tracked in the pending-work roadmap. The Performance v2 implementation report covers shared session reads, lighter handlers and workflow-designer preflight, with measured gains and remaining qualification.

Durations include nights and weekends; they are not business-hours or developer-productivity estimates. Reports are derived views, not authoritative workflow state. Standard output is read-only, while --out writes only the requested report file and does not commit or push it automatically.

Supporting documents and designs

Supporting inputs are managed under singularity/work-items//inputs/ and cataloged in documents.json. Every document has a name, unique in its Story ignoring case (detached documents keep theirs), which lists, prompts, reviews and every command that takes a document accept as well as its DOC-nnn ID. Every document is also offered to a set of phases: by default the phase it was added in and every later one. Only those phases’ prompts and source reviews include it; documents list --phase PHASE shows what one phase uses, and documents scope changes the set with a recorded decision. Uploads are allowed only in the phases configured by documents.allowedPhases, narrowed to the work type’s own phases; the starter profile allows intake, requirements, design, implementation-spec and the corresponding bugfix phases, and the spec-driven work types allow specification and planning, the phases whose source review reads them. A work type whose phases share no name with its list accepts uploads in its first phase. Documents given when a Story is started are always accepted as part of its opening record.

In VS Code, open Singularity Flow → Lifecycle → Attach evidence & designs. The same action works for the selected Story or Epic and offers:

• Multiple files, including images, PDFs, Markdown, Office documents, and design assets. A Story asks for a name for each file, suggesting its file name.
• A complete Figma export folder. Story uploads preserve it as one package; Epic intake pins its regular files in deterministic order.
• A Figma design URL or another HTTPS reference. Links are recorded without following them and no Figma credential is stored.

The target is always shown before the write. Singularity Flow then uses the existing CLI transaction to validate the phase, copy or catalog the evidence, calculate hashes, commit, and push. The new stable document/source IDs appear immediately under Lifecycle after refresh. The equivalent Copilot command is /sf-upload.

GitHub Copilot CLI can also load the bundled experimental Documents extension. Enable experimental features with /experimental on, start a fresh session, then use /documents for a searchable canvas or /documents view PHASE-DESIGN to open a specific artifact. The extension embeds a fresh document snapshot directly in the canvas; run /documents again after generating or uploading files to reload it. Hosts without canvas rendering automatically fall back to terminal output. Copilot currently does not allow plugins to add another built-in home tab, so the canvas is the supported tab-like document browser.

# Local documents, screenshots, PDFs, .fig files, or other binary files: one --name per file, in order
singularity-flow documents upload ./brief.pdf ./checkout-wireframe.png \
  --name "Payment brief" --name "Checkout wireframe"

# Complete exported design package, imported recursively in stable path order; members are
# named "/". --phases limits which phases use it.
singularity-flow documents upload ./figma-export --kind figma-export --name "Checkout export" --phases design,implementation

# External Figma or design link (recorded, not downloaded)
singularity-flow documents upload \
  --url https://www.figma.com/design/example \
  --name "Checkout design"

# Keep a sensitive file on this machine only: the commit carries its name, size and SHA-256
singularity-flow documents upload ./salary-bands.xlsx --name "Salary bands" --store local

singularity-flow documents list
singularity-flow documents list --phase design
singularity-flow documents view "Payment brief"

# Change which phases use a document: preview, then apply with a reason
singularity-flow documents scope "Payment brief" --phases requirements,design --reason "Design owns the flow now" --dry-run
singularity-flow documents scope "Payment brief" --phases requirements,design --reason "Design owns the flow now"

# Stop future prompts from using evidence without deleting its audited bytes
singularity-flow documents detach DOC-001 --reason "Superseded by the approved design"
singularity-flow documents detach DOC-002 --scope package --reason "Replace the complete Figma export"
singularity-flow documents list --all

# Initiative evidence uses the same detachment model
singularity-flow epic sources detach SRC-001 --epic MOB-100 --reason "Source withdrawn by Product"
singularity-flow epic sources list --epic MOB-100 --all

Every uploaded file receives a stable DOC-nnn identifier, content hash, MIME type, original filename, phase, human actor, and agent. Directory imports preserve the package name and relative source path for every discovered regular file; symbolic links are rejected. Upload creates and pushes one atomic work-item commit. Text evidence is fenced and embedded in Copilot prompts up to the pinned preview-byte limit per document and 48 KiB per prompt across its documents (documents.maxPromptEvidenceBytes); past that, a document is shown in part or named with the command that reads it. A prompt composed but not yet published is recomposed when the documents its phase is offered change. A DOCX or XLSX contributes its extracted text, bounded the same way and recorded as a versioned rendition, and its text is scanned for secrets at upload and commit. Images, PDFs, .fig, and other binaries contribute a verified repository path, MIME type, byte count, and SHA-256 so Copilot can inspect them with its file/image tools without base64 token inflation. Prompts ask for citations by ID and name, as in DOC-001 — Payment brief, and the spec-driven specification lists what it relied on under ## Sources.

Source review cites the Story and every readable document offered to the phase. A document it cannot cite (a link, a PDF or image with no text layer, a document kept on one machine, or one too large) no longer stops the review: it is listed as unreadable and becomes a pending decision, unreadable:DOC-nnn, that an approver records with singularity-flow review-source decide --finding unreadable:DOC-nnn --reason "…". A review whose documents are all readable binds exactly what it bound before. Live Figma links remain external references and are never fetched automatically.

Where a document’s bytes are kept is chosen per upload with --store. git, the default, commits them under inputs/ so every clone has them. local keeps them on the machine that added them, in that clone’s Git directory (.git/singularity-flow-documents/, owner-only, outside the runtime directory a factory reset removes), and commits only the name, size and SHA-256. documents store --store git, run on the machine that holds it, commits the same bytes under the same ID. Its Story worktrees see the file; another clone or machine lists it as kept on another machine, refuses to open it and says who added it, and the gate warns instead of failing. Prompts never include a local document’s bytes or where it is stored, because prompt receipts are committed: they name it and say how to read it on the machine that has it. Folders and links cannot be kept locally, and source review cannot cite a local document. documents.storage: {allowed, default} in the workflow configuration narrows the choice or changes the default. OneDrive and Jira storage are refused as not yet available. start takes --document-store, and a story file entry takes store.

Changing a document’s phases is an atomic commit/push decision too. It requires a reason and records a hash-addressed decision under evidence/document-scope/. The change applies forward only: it decides what later prompts include and never reopens a phase. Work already published with the document keeps it, and --dry-run lists that work first; to withdraw a document from it, detach the document.

Names and phases arrived with version 3 of the document catalog. An older catalog reads as version 3: each document takes its label or file name (a duplicate gains (DOC-n)), and is offered to every phase, so existing prompts and reviews do not change. Builds that know only version 2 refuse a version 3 catalog, so everyone on a team should upgrade before anyone adds a named document.

Detachment is also an atomic commit/push decision. It requires a reason, retains the bytes and an append-only hash-addressed decision record, excludes the evidence from later prompts, and reopens only phases whose recorded compositions depended on it. Default catalogs show active evidence; --all includes detached history, actor, and reason. VS Code exposes the same operations under Lifecycle → Manage evidence & designs, including file-level and complete-package Figma detachment.

Generate a phase

Copilot users normally invoke the appropriate skill, for example:

/sf-phase

The skill combines its phase contract with the active agent and the Repository brief. The equivalent deterministic CLI sequence is:

singularity-flow wm compose --phase intake
singularity-flow prepare intake
# Fill the generated template.
singularity-flow phase publish intake
singularity-flow submit

phase publish validates phase write scope and the required artifact, adds managed metadata, updates state, commits [WORK-ID][phase:][generated:], and pushes the work-item branch. After publication succeeds, it displays every published document with its path, hash, and text content so the generated result can be reviewed immediately. Source-code formats such as Java, JavaScript, TypeScript, Python, Go, and shell scripts are rendered as text. Because Copilot can collapse Shell output, the bundled lifecycle skills reload the phase as JSON and reproduce each exact text artifact between visible BEGIN/END markers in the assistant response. Submission and every later decision are separate atomic commit-and-push operations.

Artifacts live under:

singularity/work-items//artifacts//
singularity/work-items//inputs/DOC-nnn/

Managed metadata records the work type, phase, generation, human actor, agent, source/config/template hashes, token usage, commit information, and approval history. Do not edit workflow.json, STATUS.md, approval records, or the managed metadata block manually.

Lifecycle commands normally follow prepare/edit → publish → submit → approve/reject. Named sequence gates in singularity/workflow.yml are independently configurable as hard or soft, globally and per work type. Hard gates exit with code 2 before mutation. Soft gates show the same state, reason, and exact next command, then require a human to type continue; non-interactive use stops safely. Confirmed exceptions are attributed to the authenticated identity and selected agent, recorded in workflow history and artifact metadata, and exposed in status, reports, and final-evaluation warnings. Missing gate configuration defaults to hard, and the resolved policy is immutable for each work item. See singularity-flow help sequencing for all gate IDs and an example.

Approved phase inputs

Starter repositories use inputsMode: enforce and connect the full feature, bugfix, chore, and Figma-mobile phase chains. Existing repositories with no key resolve to off. Each work item pins its mode and normalized input declarations at creation. In the feature profile, implementation receives both the approved design and approved implementation specification directly; either being missing, unapproved, or hash-mismatched blocks preparation and publication.

inputsMode: enforce
phases:
  design:
    inputs:
      - requirements
      - phase: intake
        optional: true
        maxBytes: 16384

Use singularity-flow inputs design --dry-run to inspect provenance without writing, or /sf-inputs in Copilot. Normal preparation writes a managed artifact block and context/inputs-design-gen.json; publication recollects inputs and the gate verifies approved hashes and rendered-block freshness.

The shipped spec-driven-standard profile reduces repeated model context with an approval-bound projection instead of truncating upstream documents arbitrarily:

phaseOverrides:
  implementation:
    inputs:
      - phase: specification
        projection: approved-summary
        preserve: [Requirements, Non-functional requirements, Boundary conditions]
        maximumSummaryBytes: 32768
        expansion: hash-bound-reference
        fallback: whole

The producer authors an Agent brief (or Executive summary, Summary, TL;DR, or Overview) section. On phase publication, the kernel deterministically copies that section and the configured critical sections into context/briefs/; submission then binds both source and brief hashes into the review packet and shows the brief alongside the complete generated artifact. Only after approval can a downstream phase receive the brief. Its managed input block includes the source artifact’s sfref:v1: handle so an agent can expand a named section with singularity-flow show --section "" when exact wording is needed. A missing or changed brief fails closed; fallback: whole preserves legacy behavior when no authored summary exists. Work items created before this configuration change keep their pinned full-input declarations.

Human clarification checkpoints

Copilot clarification is configured per phase and is pinned with the work item. It is part of the exact prompt produced by wm compose, after the active phase contract and before agent and repository evidence:

phases:
  requirements:
    clarification:
      mode: required       # off | when-needed | required
      maxQuestions: 5
      topics: [scope, acceptance criteria, dependencies, constraints, risks]

• off adds no interactive checkpoint.
• when-needed asks only when sources, approved inputs, and the Repository brief leave a material ambiguity.
• required always pauses for at least one human response. If the evidence appears complete, Copilot asks the contributor to confirm its concise interpretation instead of silently continuing.

The starter workflows use required from initial intake through Design and specification creation (including bug-fix and mobile-design equivalents), then when-needed during implementation, verification, and conformance. Copilot asks one concise batch through ask_user, waits, and records the human response against the exact prompt and prospective generation before it authors. It incorporates confirmed answers as artifact decisions and leaves only explicitly deferred, non-blocking items under Open questions. If questions cannot be asked or recorded, the skill prints them and stops. The CLI never guesses an answer.

singularity-flow clarification record requirements \
  --question "Is this outcome and scope correct?" \
  --answer "Yes; exclude historical migration."
singularity-flow clarification status requirements

For a batch, pass --response-file responses.json. A model-assisted publication in a required phase fails when the response record is missing, bound to an older prompt/generation, or contains a material unresolved decision. Explicit --authored human work remains the intentional manual path and does not claim that Copilot asked questions.

Token usage

See Self-provisioning usage telemetry for the capability matrix, consent boundary, local storage layout, and native-host limitations.

With SFlow-provisioned Copilot telemetry, every owned process has an opaque launch ID and separate raw stream. Copilot exports a chat span only after the response finishes, so phase publish may initially mark the current generation pending. The next submit or /sf-next invocation automatically reconciles the completed span in its own commit and push before submission. The sanitized record is committed under the work item:

singularity/work-items//telemetry/-gen.json

For another provider, or when supplying a trusted external usage record, pass it explicitly:

singularity-flow phase publish implementation --usage-json usage.json

The JSON may contain provider, model, input, output, cached-input, total tokens, start/end timestamps, provider cost, and collection source. When Copilot does not expose exact values, the committed record is explicitly marked unavailable; the CLI never estimates silently. Reports identify the provider/model for every phase and aggregate token records by model as well as phase and agent.

Workflow reports prefer the exact provider cost emitted by Copilot telemetry. When provider cost is absent, they can calculate cost from exact usage and optional prices configured by exact model name. Rates are currency units per million tokens; no fallback prices are bundled because provider pricing changes over time:

tokens:
  mode: exact-or-unavailable
  pricing:
    provider-model-name:
      input: 3
      output: 15
      cachedInput: 0.3

Missing usage or pricing remains visibly unavailable; a mixture of priced and unpriced records is labeled partial.

Diagnose the local exporter or explicitly retry a delayed generation with:

singularity-flow telemetry probe
singularity-flow telemetry enable
singularity-flow copilot
singularity-flow telemetry status
singularity-flow telemetry reconcile implementation
singularity-flow telemetry disable

telemetry status reports qualified launch coverage as captured, partial, unavailable, conflict, or disabled. A configured exporter is not called captured until a valid event is observed. Reconciliation never commits raw traces or host paths—only the allow-listed phase record. Telemetry does not participate in lifecycle gates or authorization.

Inspect the same content-free observations without reconciling or mutating anything:

singularity-flow context xray WORK-123
singularity-flow context doctor
singularity-flow context compile WORK-123 --slice evidence --json
singularity-flow context expand 'sfref:...'
singularity-flow tokens status WORK-123
singularity-flow tokens report WORK-123 --json
singularity-flow tokens report --today
singularity-flow tokens compare --study context-packet-pilot

Context X-Ray defaults to the Story’s current phase; Token Ledger reports the whole Story unless --phase is supplied. Requested and resolved model identities are reported separately. Provider metrics retain field-level exact, partial, or unavailable status, while SFlow’s packet byte-to-token values are explicitly estimated; missing cache usage is never rewritten as zero.

Approval and change requests

From a terminal:

singularity-flow approvals ENG-142
singularity-flow approve design --work-id ENG-142 --fetch
singularity-flow reject design --work-id ENG-142 --fetch --to requirements --reason "Failure behavior is missing"
singularity-flow reopen ENG-142 --fetch --to implementation --reason "Production feedback requires a safer rollback"

approvals is read-only. It shows each phase beside the document or artifact-set members being approved, the pinned authority groups and threshold, the current approvers, and what remains. The approval-chain alias returns the same view. Add --json to inspect invalidated earlier decisions without counting them as current approvals.

Approval verifies the reviewer’s Git/GitHub identity against the phase authority groups and shows current hashes, checks, usage, prior approvals and self-approval warnings. /sf-approve [--work-id WORK-ID] confirms the exact current review already visible in the same chat after submission, Inbox or an approval preview. Complete document bodies may be reused across publication, submission and approval only with an identical non-null displayBinding; this content identity never grants approval. The separate reviewBinding is revalidated against the current immutable packet and must have been shown before human confirmation. A changed approval binding needs fresh confirmation, not another dump of unchanged documents. Changed documents, missing chat context or incomplete displays need complete review; collapsed tool output and summaries are not review. The CLI consumes a one-time receipt, never --yes, and automatically advances when its threshold is met. Next-phase authoring remains separate. Multi-approval thresholds require distinct human identities; requiredAuthorities additionally requires each named functional group.

Every individual approval is an atomic lifecycle decision: it updates the decision ledger and workflow state, creates its own [WORK-ID][phase:][approve] commit, and pushes that commit before reporting success. This also applies to approvals that do not yet satisfy a multi-approval threshold. A failed push retains the local commit and blocks further decisions until singularity-flow sync succeeds.

Only a Git/GitHub identity matched to one of the phase’s configured approvalAuthorities may decide a phase. The active agent is recorded as prompt/audit context but never grants permission. If the authenticated generator and approver are the same person, the approval is allowed when policy permits but is visibly recorded as selfApproval: true; it is never represented as independent review.

Requesting changes may target only a phase listed in the deciding phase’s rejectTo policy. While a phase is awaiting approval, reject reopens that target. After a Story is closed, reopen uses the final phase’s same policy. Both create a structured CR-nnn record containing the exact comment, requester identity, authority group, agent, source artifact hashes, target phase, timestamp, and invalidated approval cone. Prior artifacts and decisions remain in Git history.

Open requests appear in STATUS.md, the VS Code Lifecycle tree, and the next Copilot prompt for the reopened phase. A new generation does not silently close the request: it becomes resolved only when the reopened phase is approved, with the resolving generation and artifact hashes recorded.

The behavior is configurable per phase:

approval:
  authorities: [product-approvers]
  minimum: 1
  rejectTo: [requirements, design, implementation]
  changeRequests:
    commentRequired: true
    reopenCompleted: true

Publication and recovery

With git.publish: required, generation and lifecycle commands are successful only after a normal fast-forward push. Before the first write, the transaction journal persists an integrity-bound preimage. If the process dies before commit, sync reclaims its dead lock, preserves the interrupted partial bytes under .git/singularity-flow/publication-rescues/, restores only the recorded roots, verifies the restored digest, and leaves unrelated source or staged changes untouched. A live command is reported as active and is never rolled back.

If a push fails after commit, the local commit is retained and a machine-local pending-publication record blocks further transitions until:

singularity-flow sync

After the commit boundary, sync retries the existing commit without rewriting history. Optimistic branch-head checks prevent concurrent decisions from silently overwriting each other.

For isolated tests only, git.publish: off disables remote publication. Do not use it when Git is the state-transfer channel.

Implementation specification and conformance

Feature work includes an implementation-spec after design. It uses stable SPEC-nnn identifiers mapped to approved AC-n acceptance criteria and captures APIs, schemas, affected files/components, security, observability, migration, and test expectations. Bugfixes use the smaller fix-spec template with the same identifiers.

The final conformance artifact compares every approved AC-n and SPEC-nnn with exact source/test file-and-line evidence. Each item must be classified as matched, partial, missing, deviated, or unplanned. Approved deviations and all self-approvals are disclosed. The report stores a source/test tree hash; later code changes make it stale and fail the gate.

singularity-flow gate --terminal

The deterministic gate checks profile/template snapshots, remote publication, artifact integrity, agents, human identities, authority groups, approval thresholds, rejection cascades, AC/SPEC traceability, conformance freshness, and protected workflow/template/agent/skill files.

World model

The World Model is the Repository brief every phase prompt gets, read from the committed source with no build and no model: the rules that apply, contracts, flows, what the Story’s change touches, and the risky places. It is guidance and never blocks or authorizes anything. worldModel.knowledge.prompt: off leaves it out of every prompt, worldModel.knowledge.maxBytes sets its size, and a work type’s intelligence.worldModel: off leaves it out for that work type. For the business or product reading of the code, use repository knowledge (see Repository knowledge).

singularity-flow wm brief --phase design --work-id WORK-123
singularity-flow wm knowledge status
singularity-flow wm knowledge show business

Large monorepos do not need a repository-wide brief. In Configuration Center → World model, or in singularity/workflow.yml, set repository-relative sourceRoots plus any sharedRoots. A capability may pin a narrower scope; child application roots replace the parent scope while shared roots accumulate. New lifecycle state pins that resolution so an active Story does not drift when the capability map changes.

The registered World Model (published views on the state branch), the CALM architecture projection, and architecture intent were removed. Their settings in an older singularity/workflow.yml are ignored and singularity-flow doctor lists them as removed-settings; their wm commands refuse with WMB_REMOVED, and architecture refuses with COMMAND_REMOVED. Old World Model files on a state branch stay in Git and are not read.

For bounded structural references, singularity-flow wm ast context --paths src --max-facts 50 --max-output-bytes 32768 --json uses the same pinned scope and a selected-cone content binding. Java, Python, Kotlin, and Swift receive text-assured declaration previews from the bundled on-demand polyglot scanner; JavaScript/TypeScript retain the built-in lexical text floor. The preview scanner is not a parser and cannot satisfy a required syntax gate. Optional reviewed parser and semantic packs execute through a bounded structured-argv contract only with a complete project/toolchain binding and are not kernel dependencies. Separate text, syntax, and semantic records are reused by content/derivation hash, so an unrelated monorepo edit does not invalidate the selected cone. With no configured roots, the default is changed tracked files—not a monorepo-wide scan—and --all must be explicit. Facts are returned in byte- and count-bounded pages; continue only with the opaque nextCursor, which fails stale if policy, revision, scope, or relevant bytes change. Required symbol gates require syntax assurance from a real parser; text previews remain advisory. Receipts bind broker and extractor versions as well as outcomes. See AST Intelligence for policy, cache, preference, and adapter details. AST prompt context is always optional: disabled, unavailable, or file-inventory-only results inject zero AST bytes and ordinary repository file access continues. When structural facts are injected, the prompt audit records their count and exact payload bytes so AST/no-AST studies can compare context cost and provider usage without treating a file listing as structural value. In VS Code, use Singularity Flow → Configuration → AST intelligence, the Configuration Center, or Singularity Flow: AST Intelligence Settings from the Command Palette. The panel exposes repository and machine policy, lifecycle-gate receipts, bounded previews, adapter availability, the per-language/project readiness matrix, cache hit/miss evidence, and guarded cache cleanup; environment policy is displayed read-only and configuration changes remain local until published. Its scope banner names the active workspace repository. Multi-repository workspaces can select a different ready repository there; the durable selection is shared with My Work, Lifecycle, Configuration, Copilot, and workspace current rather than being private to the panel.

For new workspaces, Map a capability can select a blobless or blobless-sparse clone. Sparse mode always retains singularity/ and .github/agents/, and its default refuse fallback prevents a Git server that ignores filtering from silently downloading the full monorepo. Scope and clone policy are separate: scope decides what the model sees; sparse checkout decides what is materialized locally.

singularity-flow doctor --performance --offline
singularity-flow doctor --performance --json

This explicit read-only benchmark reports total versus scoped files, warm Git status and fingerprint timings, sparse/partial-clone state, and recommendations. It never changes Git configuration. Ordinary Home and doctor reads do not run the benchmark.

Phase prompt composition

# These --task forms explicitly request an ad-hoc task guide.
singularity-flow wm compose --phase design --task "Design invoice export" --dry-run
singularity-flow wm compose --phase design --task "Design invoice export"
singularity-flow wm show-prompt

wm compose is the single phase entry point. It combines the active Agent Markdown, the Repository brief, an exact task guide only when explicitly requested with --task, applicable evidence, and locked remote agent skills. wm inject remains an alias for compatibility.

Use /sf-show-prompt at any active Story phase to display the complete /sf-phase SKILL.md followed by the exact rendered phase prompt. The inspection uses --render-only: it does not create a composition record, prepare an artifact, edit workflow state, commit, or push. Pass --skill sflow-design (or another installed Flow skill ID) to inspect that skill contract with the same current-phase prompt.

For an opt-in, workspace-local history of the prompts actually composed for Copilot, use /sf-prompt-log on (or singularity-flow prompt-log on). Review records in VS Code under Configuration → Prompt audit, or run singularity-flow prompt-log list and singularity-flow prompt-log view latest. Capture is off by default and never includes Copilot’s hidden system prompt or chat history. The structured view separates prompt sections, authorized tools, provider usage, and context-efficiency measurements. It reports managed upstream bytes and duplicate approved-reference previews removed before transport, AST structural facts/payload bytes, and optional sections omitted by the approved token budget.

Prompt records are private (0600), append-locked, scrub common credential formats, and use a machine-local HMAC chain to detect accidental edits, deletion, or reordering. The default retention is 30 days with a 64 MiB storage ceiling; change the duration with prompt-log retention --retention-days . A malformed interrupted JSONL tail is quarantined before the next capture. Use prompt-log repair --confirm "REPAIR PROMPT AUDIT" for an explicit integrity recovery, or prompt-log clear --confirm "DELETE PROMPT AUDIT" to remove active history and all recovery copies.

Help-routing quality uses a separate content-free local log under /.singularity-flow/help-metrics/events.jsonl. It stores classifications, outcomes, topic IDs, matching methods, latency, answer size, and selected action categories—never questions, answers, paths, Work IDs, Git identities, or file content. Use singularity-flow help-metrics status --json, on, off, or clear; nothing is transmitted off the laptop.

wm compose compiles named prompt sections under the Story’s pinned tokenEconomy profile. off and observe preserve compatibility (observe reports an overflow); assist removes lowest-priority optional sections and records their hashes; enforce does the same but refuses with TKN_MANDATORY_CONTEXT_OVERFLOW when the non-evictable Flow Policy context alone cannot fit. Approved upstream artifacts contribute only their producer-authored bytes—their managed input blocks are never nested again—and an exact path/hash match is never injected a second time as a reference preview.

Non-dry-run composition writes both a JSON provenance record and the exact rendered prompt under the work item’s context/ directory. The Repository brief is guidance, never authority: nothing in it refuses publication, submission, or completion. Registered durable state is read through pure, deterministic in-memory migration chains; no read rewrites a stored record or changes its hash.

Fault intake and repair

Anything may report that it is broken; only pinned policy decides what happens next. Fault intake stores sanitized, content-hashed evidence below the repository Git directory, so reporting a test, build, IDE, CI, staging, or production failure never dirties application source.

# Wrap a local command and record any non-zero result.
singularity-flow run --repair-on-fault -- npm test

# Or record an external build failure.
singularity-flow fault report --source ci --environment ci --type unit-test \
  --build 1842 --commit 81ac012 --command "npm test" --exit-code 1 \
  --log artifacts/test.log --idempotency-key payment-build-1842

singularity-flow fix FLT-... --diagnose-only
singularity-flow fix FLT-... --plan-only --allow-path src/payment \
  --verify-argv '["npm","test","--","payment"]'

Node integrations use the same kernel without parsing terminal output:

import { createSflow } from 'singularity-flow/src/api.mjs';
const sflow = createSflow({ root: process.cwd() });
const fault = await sflow.fault.report(envelope);
const repair = await sflow.repair.request({ faultId: fault.faultId, mode: 'policy-decides' });

Local and IDE execution defaults to guided repair, while CI and staging execution defaults to proposal only. An authorized local review of a CI proposal creates a new immutable plan generation rather than editing the CI plan. Production and security faults remain diagnosis-only. Requirement, policy, and architecture faults remain challenge-required until a separate ceremony creates a durable challenge or amendment record; selecting Fix again joins the same unresolved repair. --auto cannot raise that ceiling. A guided repair creates a local isolated sflow/repair/* branch only after the human confirms the exact plan hash. Diagnostic path observations never become mutation authority; at least one explicit bounded --allow-path is required. Candidate patches enter through repair attempt; the kernel checks every path before applying them and runs the complete pinned verification set as exact argv without a shell in a disposable verification worktree with a scrubbed environment. Direct publication, remote Git, shell, deployment, and destructive verifier commands are refused. macOS sandboxing or Linux Bubblewrap also denies network and external writes when a real probe succeeds. Runtime and library files on the host remain readable, so plans state host-read-permitted and require maintainer-reviewed verifiers rather than claiming full host isolation. The result records the boundary used. It never pushes, approves, merges, releases, deploys, or edits production.

In Copilot use /sf-fault and /sf-fix. In VS Code unresolved faults appear in My Work with Fix this and Diagnose. All surfaces call the same records and kernel functions. See singularity-flow explain fault-intake-and-repair.

Remote Markdown agents

agents under .github/agents or the plugin’s agents/ directory may declare public HTTPS Markdown skills, templates, and generated outputs in exact dependency tables. Singularity Flow presents these files as agents because they are context, not people, agents, or approval authorities.

Configure a repository agent

Create an agent Markdown file in the lead repository at .github/agents/.agent.md. Agent and dependency IDs must use lower-case kebab-case. Native Copilot files may keep a human-readable frontmatter name; when it is not an ID, Singularity Flow uses the kebab-case filename as the identity and retains name only as a display label. Legacy native files that also use the display name as their filename are normalized deterministically; new files should use the explicit kebab-case filename.

For example, create .github/agents/architecture.agent.md:

---
name: architecture
description: Architecture agent with reviewed remote Markdown dependencies.
---

# Architecture agent

Review requirements, architecture, security, operability, and implementation
boundaries.

## Remote skills

| ID | URL | Phases | Optional | Max bytes |
|---|---|---|---|---|
| secure-design | https://example.com/agents/secure-design.md | design,implementation-spec | false | 262144 |
| api-review | https://example.com/agents/api-review.md | design | true | 262144 |

## Remote artifact templates

| ID | URL | Phases | Optional | Max bytes |
|---|---|---|---|---|
| design-template | https://example.com/templates/design.md | design | false | 262144 |

## Remote generated artifacts

| ID | URL template | Phase | Target | Optional | Max bytes |
|---|---|---|---|---|---|
| threat-model | https://example.com/output/{workId}/{generation}/threat-model.md | design | artifacts/design/threat-model.md | true | 1048576 |

The headings, column names, and column order are exact. Use comma-separated phase IDs; *, -, or an empty value means all. The enclosing agent already defines the agent scope. Optional accepts true or false. The default size limit is 1 MiB and the hard ceiling is 10 MiB.

Remote resources must be non-empty UTF-8 Markdown available through public HTTPS without embedded credentials, cookies, or authorization headers. Generated-output URLs may use only the URL-encoded {workId}, {workType}, {phase}, and {generation} variables. Their targets must be Markdown paths under the declared phase’s artifacts// directory. Links outside these three dependency tables are treated as ordinary prose and never fetched.

Trust and activate the agent

Run these commands from the repository root:

singularity-flow agents list
singularity-flow agents lock architecture
singularity-flow agents sync architecture
singularity-flow agents status architecture

The first lock operation displays the pack source and dependency hashes and requires typing the exact pack name. It writes singularity/agents.lock.yml. Review, commit, and push that file so every contributor uses the same trusted content.

agents sync never changes trust. It verifies the committed lock, caches the Markdown atomically under .git/singularity-flow/, and makes the pack active for the local session without changing the selected agent. Matching remote skills are then added to the normal prompt composition:

phase contract and template
+ selected governed-agent prompt
+ Repository brief
+ active agent skill Markdown
+ approved phase inputs

Remote skills are pack-scoped prompt context; they do not become global slash commands and cannot approve.

Automatic Copilot-agent mapping

When Copilot starts a custom agent, its subagentStart event includes the selected agent name. Singularity Flow first checks the committed optional mapping file singularity/agent-mappings.yml, then falls back to an exact ID match against repository agents in .github/agents and the bundled plugin agents:

version: 1
mappings:
  "Playwright Test Engineer": playwright-test-engineer
  mobile-delivery-agent: mobile-delivery

The YAML keys are Copilot custom-agent IDs and the values are discovered Singularity Flow agent IDs. Inspect the effective routing with:

singularity-flow agents mappings

A resolved local-only agent, or a resolved locked pack whose bytes are already verified in the local cache, becomes the active session agent automatically. The current work-item binding and agent are preserved.

The hook never downloads content or establishes trust. An unlocked, changed, or uncached remote pack remains inactive and Copilot receives the exact agents lock, lock --update, or sync command to show the contributor. An unrelated Copilot agent has no effect. Invalid mappings and unknown target packs fail validation instead of silently selecting another pack. agents remain instructions and context—not a human identity, agent, or approval authority. Edit the mapping visually in VS Code Configuration → Agents & delivery or commit the YAML normally so every contributor receives the same routing.

Use a remote artifact template

A remote template replaces a workflow template only through an explicit reference in singularity/workflow.yml:

workTypes:
  feature:
    templateOverrides:
      design: agent:architecture/design-template

When a work item uses the template, Singularity Flow copies it into committed work-item context and pins its hash in workflow resolution. Later URL changes therefore cannot silently alter active work.

Update or refresh remote content

Agent-file or dependency changes require a deliberate lock update:

singularity-flow agents lock architecture --update
singularity-flow agents sync architecture
singularity-flow agents status architecture

Inspect the old and new hashes, type the exact agent name, and commit and push the updated singularity/agents.lock.yml.

Dynamic generated output is fetched once for the prospective generation and then reused. Refresh it deliberately when its remote result changes:

singularity-flow agents refresh-output threat-model
# Use --replace only when intentionally discarding local edits.
singularity-flow agents refresh-output threat-model --replace

VS Code Configuration → Agents & delivery provides the same lifecycle visually: edit the three structured resource tables, map native Copilot agent names, inspect per-resource hashes and cache state, open the exact trust/update confirmation in an integrated terminal, and sync locked content. Authenticated private Git, Artifactory, cookie, and bearer token downloads are not supported in this delivery. See HELP.md for lifecycle and integrity details.

Where remote skills and templates are managed

Remote Markdown has two storage planes so trust is shared while downloaded bytes remain local until a work item actually uses them:

The safe operating sequence is therefore declare → lock → review and commit → sync → start work. sync cannot update a trusted hash. A changed remote file stops with a stale-lock error until a contributor runs agents lock --update, reviews the hash change, confirms the exact agent ID, and commits the new lock. Remote templates are inert unless a workflow explicitly names agent:/.

MCP tools such as Playwright

MCP servers are host capabilities, not remote Markdown. VS Code or Copilot CLI owns their process, transport, trust prompts, and credentials. Singularity Flow adds the layer: mcpServers in singularity/workflow.yml assigns a host server to explicit agents, phases, and tool names; the Agent Markdown tools field permits the corresponding server/tool or server/* namespace; phase prompt composition includes the resulting policy.

singularity-flow mcp scaffold playwright  # merge-safe, exact package version
singularity-flow mcp scaffold figma       # remote Figma MCP; add --local for desktop
singularity-flow mcp status
singularity-flow mcp doctor
singularity-flow mcp probe playwright --network
singularity-flow mcp warm playwright --network
singularity-flow mcp verify-offline playwright
singularity-flow mcp auth status playwright
singularity-flow mcp attest figma --confirm figma

VS Code exposes a complete policy editor, joined host status, and the same safe scaffold under Configuration → MCP tools. The Visual Assurance dashboard is available from Lifecycle, Inbox, and the Configuration Center. It presents approved design-source versions, deterministic design inventory, viewport coverage, implementation captures, comparison/diff evidence, and MCP provenance in one review surface. Opening or refreshing the dashboard performs no network access; network diagnostics, server warm-up, and remote evidence capture are separate, explicitly confirmed actions. Recorded PNG comparisons can be inspected inline as side-by-side, overlay-slider, or deterministic diff views. The cards retain the exact approved, implementation, and diff hashes. Candidate versions never replace the approved source silently, and host readiness can be attested only after exact server-name confirmation. When a reviewed candidate should become the new baseline, use the explicit Promote action in Visual Assurance or run singularity-flow mcp design-sources promote --confirm . Promotion is an audited publication: it reopens design intake, invalidates that phase and its downstream approvals, and pins the chosen record for the next capture generation. Corporate npm registry, proxy, and CA configuration continue to come from .npmrc, environment variables, and the host. Durable screenshots or reports can be hash-recorded with singularity-flow mcp record and are revalidated by the Flow Gate. For figma-mobile, design-intake publication creates a deterministic source set and approval binds that exact set; downstream prompts receive its verified metadata and hashes rather than silently following the live file. See MCP tools and Mobile model intake for the complete security and evidence workflow.

Useful commands

An initiative output with kind: binary-bundle may omit a text template. Phase preparation reports its exact repository target as awaiting upload without fabricating an empty file. Copy the ZIP, image collection, signed evidence package, or other bundle to that path and run the initiative phase command again to hash and register it. Required missing bundles block publication with their expected paths. Downstream Copilot prompts record binary paths, sizes, and SHA-256 values without decoding or injecting the raw bytes.

Initiative repository synchronization reads child workflow state from the exact fetched commit. Malformed, unsupported, or identity-mismatched child state is isolated as stale and blocked instead of aborting every repository. Both profiles enforce the same delivery semantics: Build/Construction requires blocking stories through verification, and Release/Delivery requires conformance. Phase approval remains bound to the exact current bundle hash; dependency invalidation rewinds to the earliest affected phase while preserving unrelated approved work. Initiative reports combine initiative and child model/token/cost data without upgrading partial coverage to exact.

Durable schema compatibility and clean reset

Durable JSON families declare their current version, readable range, and ordered migration chain in one registry. Writers always emit the registry’s current version. Readers migrate readable history in memory and leave Git, ledger, evidence, approval, and local-state bytes untouched. sflow doctor --json reports the stored version distribution and flags out-of-range records. Factory reset is for an intentional clean restart; it is not the normal schema-upgrade mechanism.

Development and packaging

npm install
npm test
npm run check
npm pack --dry-run

VS Code extension

The supported visual surface is the VS Code extension:

• Guided Start is the first-use front door: Map capability → Create workspace → Start work. Existing capability maps and an already-selected workspace are detected and skipped, so the same command remains useful after onboarding.
• Workspaces selects local project context and shows the directory, lead repository, repository health, Jira routing, metadata, and capability scope. Selecting a row stays in the current VS Code window; opening a repository is a separate explicit action. The workspace editor changes its display name and selects capabilities already available in its materialized repository boundary. Use Copy workspace when that boundary must change.
• Lifecycle owns Story/Initiative intake, workflow selection, the phase rail, generated artifacts, progress, checks, submissions, and approvals.
• Inbox brings generated Markdown, JSON, YAML, registered evidence, review packets, and pending decisions into one business-friendly view. Its portfolio dashboard summarizes capabilities, repositories, Jira routes, open work, approvals, and diagnostics.
• Story Analytics turns the committed Story report into a phase rail and business-readable dashboards for completion, elapsed/active/waiting time, approval bottlenecks, generations and rework, models, exact-or-unavailable token usage