Agent workflow commands and source ownership

Start a session by inspecting this checkout. Use the complete feature slug when an orchestrator selected the work; inspection never changes Spec Kit's pointer.

Omit --feature to use SPECIFY_FEATURE_DIRECTORY, then .specify/feature.json. Without either, status reports no selected feature. Numeric prefixes alone are ambiguous and rejected. Commands work from another working directory when invoked through their absolute path. Paths supplied to --feature are relative to the checkout; evidence and handoff paths are also resolved relative to the checkout.

Sources and ownership

• The constitution owns binding constraints.
• .agents/workflow.json owns routing, full-slug catalog, lifecycle and explicit enrollment. It stores no task progress or workflow phase.
• Each feature's spec.md, plan.md and tasks.md own intent, design and tasks.
• .specify/feature.json selects work for Spec Kit; it does not describe the status of the repository's other features.
• .specify/commands contains pinned command sources. Harness command/skill copies are generated by setup-agent.sh and ignored.
• setup-agent.sh owns pinned upstream skill sources. Project-owned verification lives in .agents/skills/verify-signaltty. Other supported harnesses share that source through relative links.
• verify.py owns executed checks and their reports. verification_evidence.py owns content identity shared by the runner and workflow CLI.

The documentation index separates current architecture and development instructions from decisions, research and historical evidence. The feature catalog preserves every existing directory and ID. unreviewed means its recorded lifecycle has not been investigated. It does not mean the feature is unimplemented. completed is a recorded claim; current proof is assessed separately. Superseded entries name their successor's full slug.

Register and work on a feature

Follow speckit-specify, speckit-clarify, speckit-plan, speckit-tasks, then speckit-implement. Use the existing task routing and development setup. Invoke the skill through your harness; next distinguishes agent-command names from executable shell arguments. Already accepted requirements and existing test seams remain valid.

After creating a feature directory, add its full slug to the catalog:

Add [FR-###] references to checkbox task lines for every functional requirement. Keep task IDs unique. Historical features remain unenrolled until their process artifacts are reviewed; repository checks do not demand rewritten historical specs.

index without --write checks the generated catalog and routing table. It does not infer lifecycle, modify tasks or persist feature selection. check inspects prerequisites and proof; it never starts a test run. Planning requires a clarified spec. Implementation additionally requires plan, numbered tasks, requirement coverage and the checked checklists/requirements.md and any additional review checklists. Delivery also requires checked tasks and applicable successful full or desktop evidence. These checks establish structural readiness; review and behavior tests establish whether the intent is satisfied.

The constitution's documentation-only and one-line exemptions are explicit: check --phase implementation --scope docs-only or --scope one-line skips feature artifacts. The scope is a caller declaration, not an automatic assessment of the diff. Repository integrity and the full delivery gate still apply.

Verify and deliver

Publishing, GitHub checks, review comments and authorized merging follow the CI and PR procedure.

The runner invokes the same repository check in local runs and CI. It checks catalog coverage, source links, generated indexes, verification symlinks and installed command copies. Setup's commands check --agent all --installed-only owns harness discovery and compares installed contents with sources; missing or edited generated files require reinstallation for that harness. A harness with no generated commands is not presumed installed.

Stage final source before the delivery run. Provenance includes tracked and nonignored new working files, executable/permission modes, symlink targets, and staged file content. Verification records snapshots before and after commands. Different input snapshots prevent success; later changes make the proof stale. Committing identical staged and working content preserves its identity. Use one writer per checkout and keep source stable while verifying. Matching snapshots do not certify the absence of temporary edits restored between captures. Evidence goes under ignored target/verification/ or outside the checkout. A nonignored in-repository output is rejected instead of excluding source files.

Use --evidence for a chosen directory or summary.json. No latest-run guess is made. Doctor/fast, legacy, incomplete, running and failed reports are not delivery proof. GUI screenshots still need inspection; real desktop, accessibility and paid-provider limits remain those in docs/17.

Resume and recover

Handoff creates a new file and refuses to replace an existing one. The default is ignored target/handoffs/; choose a durable new path for multi-session work. Generated facts include Git state, open task references, selected evidence and next action. The decisions/ownership section is separate from observed facts. Writing a nonignored handoff into source invalidates previous proof, and the CLI reports evidence status again after creation.

Failed verification reports identify category, step, log and recovery action. For setup failure, correct the reported prerequisite and run doctor. For a command failure, read that step's log and form a diagnosis before a bounded rerun. If the failure repeats, collect new evidence and revise the hypothesis. For stale proof, finish source writes and rerun full. For interruption, confirm owned processes stopped before restarting. next directs inspection of a running report and diagnosis of a failed or unavailable report before another run. The workflow does not retry commands automatically.

JSON and evaluation

--json emits schema_version: 1, command, ok, data and findings. Findings include a stable code, message, path when applicable and a correction action. Exit 0 means inspection or checks succeeded; 1 means a gate failed; 2 means invalid input. Read commands are safe to repeat. Only index --write and handoff write files.

Use the existing evaluation task bank and result template to compare discovery, resume and stale-proof handling in disposable worktrees. Fix model, prompt, environment and resource limits, vary trial order and repeat. Evaluate completion and regressions before time, tokens and interventions. The tooling tests prove these commands' behavior; they do not measure an improvement in agent productivity. The research records sources and limits; ADR-0037 records the design.