Spec Work

Work Execution Command

Execute work efficiently while maintaining quality and finishing features.

Introduction

This command takes a work document (plan or specification) or a bare prompt describing the work, and executes it systematically. The focus is on shipping complete features by understanding requirements quickly, following existing patterns, and maintaining quality throughout.

Workflow Contract Summary

• Inputs: settled implementation-ready code plan, validated task pack, explicit knowledge-work plan, or concrete bounded implementation prompt.
• Outputs: scoped source changes, task/unit evidence, required review/residual posture, structured verification closeout, and an authorization-aware handoff. A task pack remains derived; its source plan owns scope/lifecycle.
• Hard exits: unresolved target repo/dirty overlap/source owner, requirements-only or invalid unified metadata, task-pack/source-plan drift, scope-changing acceptance/architecture/provider/source-runtime discovery, failed required review/verification, or missing mutation/commit/landing authority for the requested exit.
• Ownership: scripts prepare deterministic facts; LLMs judge semantic fit. Canonical source is modified; generated runtime mirrors are never source fixes. Local mutation, commit, landing, lifecycle, and durable evidence are separate exits.
• Consumers: spec-code-review, caller-owned LFG/goal flows, commit/PR/release workflows, spec-compound, and human reviewers.

Reference Trigger Map

Scenario Capability

Follows docs/contracts/workflows/scenario-capability-matrix.md. Overrides: high-risk

• foreign-residual-workspace -> blocked-action-required: stop before source writes, behavior-bearing tests that rely on suspect local artifacts, review fixes, commits, lifecycle mutation, or PR-ready claims until the named cleanup/init action runs or the user explicitly accepts degraded evidence.
• optional external-tool evidence unavailable -> fallback-only: use bounded direct source, test, log, diff, and user-provided evidence; disclose the missing capability and do not claim unconfirmed impact or coverage.
• non-git-build-workspace coverage gaps -> partial: keep work inside explicit target_repo/covered roots and directly inspect any uncovered build module before changing or claiming behavior there.

Input Document

<input_document> #<invocation arguments supplied by the current host> </input_document>

Execution Workflow

Phase 0: Input Triage

First, parse a leading mode token. If <input_document> begins with mode:return-to-caller (or the legacy aliases mode:caller-owned-tail / caller:lfg), strip that token before anything else: the remainder of the string is the plan path, and this run executes in Return-to-Caller Mode (see § Return-to-Caller Mode) — implement and locally verify only, then return the structured envelope instead of running the standalone shipping tail. Classify the stripped plan path with the rules below. A mode token with no following path is an error: report it rather than treating mode:return-to-caller as a bare prompt.

Determine how to proceed based on what was provided in <input_document> (after any mode token is stripped).

The classification order is mode token -> file metadata -> task pack -> unified plan -> legacy plan / knowledge-work -> bare prompt. Do not classify by filename alone.

File document (input is a path to an existing plan, specification, or task pack): read only the metadata first — YAML frontmatter for Markdown, or visible header metadata for HTML.

If Markdown metadata carries type: task-pack, do not read the full task-pack body before this classification. Load references/work-intake-and-task-pack.md and follow its deterministic validation, source-plan replay, semantic-fit, Task Pack Contract/Waves, drift, task review, failure handoff, and lifecycle rules. A validated task pack is a first-class execution input, but its source plan remains authoritative and the task pack stays status: derived. This branch replaces the remaining file classification; after successful intake, continue Phase 1 with the resolved source plan plus validated contract.

For a declared unified artifact, validate critical metadata before classification. Duplicate critical metadata, missing artifact_readiness or execution, or a conflict between visible HTML metadata and content shape is invalid. Fail closed to a spec-plan <plan-path> repair handoff; do not normalize, merge, or guess the intended value. This validation applies only after the artifact declares artifact_contract: spec-unified-plan/v1; a truly legacy plan with no unified contract remains on the compatibility path below.

Before readiness classification, inspect lifecycle status. Only status: active is eligible for a new implementation run. completed, partially-shipped, or superseded returns source-plan-non-active and must not enter spec-work, generate execution tasks, or be treated as implementation-ready even when artifact_readiness: implementation-ready remains in historical metadata. A legacy plan with no managed status may continue only with source-plan-lifecycle-unmanaged recorded as a limitation. A discovered mismatch between plan status and source reality is a finding, not authorization. "The plan says completed but the code doesn't have it yet", "the user asked to finish it", or a recorded limitation note never converts a non-active plan into an executable one — return source-plan-non-active with the mismatch as a finding for the plan owner instead of implementing.

• If it carries artifact_contract: spec-unified-plan/v1, classify artifact_readiness before reading the body.
  • artifact_readiness: requirements-only -> stop and tell the user this Product Contract needs spec-plan enrichment before implementation. Offer the exact spec-plan <plan-path> handoff.
  • artifact_readiness: implementation-ready plus execution: code -> continue to Phase 1 using the unified-plan reader strategy below.
  • Any other readiness value or any non-code/unclassified execution mode -> do not auto-execute as code. Route execution: knowledge-work to the non-code carve-out; otherwise ask the user to return to spec-plan to produce an implementation-ready code plan.
  • Progress-like values (active, in_progress, completed, done) are invalid readiness values. Stop and ask for plan repair rather than guessing.
• If it carries execution: knowledge-work, this is a non-code plan — read references/non-code-execution.md and follow that carve-out instead of the rest of this workflow.
• Otherwise (legacy plan, field absent, or execution: code) -> continue to Phase 1 and run the normal code lifecycle. Exception: metadata that carries a progress-like artifact_readiness value (active, in_progress, completed, done) without declaring the unified contract is still an invalid readiness marker, not a legacy plan — stop and ask for plan repair exactly as in the declared-contract branch instead of silently entering the code lifecycle.

Blank invocation latest-plan discovery: when <input_document> is blank, glob docs/plans/*.md and docs/plans/*.html, inspect metadata for the newest candidates, and only auto-select an active plan that is artifact_readiness: implementation-ready plus execution: code or an eligible legacy code plan. Never select completed, partially-shipped, or superseded. Stop instead of silently executing when the newest matching artifact is requirements-only, non-active, execution: knowledge-work, an approach-plan, or an unclassified universal/answer-seeking output. Ask for an explicit path or a spec-plan enrichment step. Superseded sibling: if a requirements-only candidate has a same-basename file in the other format (<basename>.md / <basename>.html) that is active and implementation-ready, a format conversion left the requirements-only copy stale — select the active implementation-ready sibling and execute it rather than stopping.

Bare prompt (input is a description of work, not a file path):

0. Open-ended symptom check. A symptom report with no error text, no stack, no failing test, and no concrete reproducible behavior ("it feels off", "something is wrong somewhere, fix it") is an open-ended diagnosis request, not an implementation prompt: name spec-debug as the owning workflow and route there instead of entering implementation here. Finding and fixing the bug yourself inside this workflow is doing spec-debug's job in the wrong place, even when the diagnosis is quick.

1. Scan the work area

   • Identify files likely to change based on the prompt
   • Find existing test files for those areas (search for test/spec files that import, reference, or share names with the implementation files)
   • Note local patterns and conventions in the affected areas

2. Assess complexity and route

   Complexity	Signals	Action
   Trivial	1-2 files, no behavioral change (typo, config, rename)	Proceed to Phase 1 step 2 (execution boundary), then implement directly — no task list, no execution loop. Apply Test Discovery if the change touches behavior-bearing code
   Small / Medium	Clear scope, under ~10 files	Build a task list from discovery. Proceed to Phase 1 step 2
   Large	Cross-cutting, architectural decisions, 10+ files, touches auth/payments/migrations	Inform the user this would benefit from spec-brainstorm or spec-plan to surface edge cases and scope boundaries. Honor their choice. If proceeding, build a task list and continue to Phase 1 step 2

---

Phase 1: Quick Start

1. Read Plan and Clarify (skip if arriving from Phase 0 with a bare prompt)

   • For validated task-pack input, treat the resolved source_plan as the plan read below and use only the machine-readable Task Pack Contract/execution_waves for task creation. Follow references/work-intake-and-task-pack.md; do not re-split from the source plan or human-readable cards.
   • For unified plans, size your read. A short plan (lightweight or requirements-only, a screen or two) can be read in full. For a long implementation-ready plan, do not read the whole document first — it is expensive and unnecessary. Build a section map, then read only what the active unit needs: metadata, then Goal Capsule, Verification Contract, Definition of Done, the Implementation Units heading list, and only the active U-ID section plus referenced R/F/AE/KTD excerpts. Read appendices or unrelated U-IDs only when the active unit cites them. To build the map: in markdown scan headings (rg -n '^#{1,3} ' <plan> — top-level sections plus ### U<N>. units); in HTML scan the <h1>–<h3> heading elements and their anchor ids. Match on the stable section names / unit IDs (Goal Capsule, Verification Contract, ### U<N>., …), ignoring HTML wrapper tags — not on a format-specific pattern.
   • For legacy plans, read the work document completely. Both formats (.md, .html) carry the same section names and IDs; HTML just wraps them in semantic elements (<section>, <article>, etc.).
   • Treat the plan as a decision artifact, not an execution script
   • If the plan includes sections such as Implementation Units, Work Breakdown, Requirements (or legacy Requirements Trace), Files, Test Scenarios, or Verification, use those as the primary source material for execution
   • Check for Execution note on each implementation unit — these carry the plan's natural-language execution direction for that unit (for example, start from failing proof, characterize legacy behavior, or prefer smoke/runtime verification). Note them when creating tasks, but do not reduce them to keyword matching.
   • Check for a Deferred to Implementation or Implementation-Time Unknowns section — these are questions the planner intentionally left for you to resolve during execution. Note them before starting so they inform your approach rather than surprising you mid-task
   • Check for a Scope Boundaries section — these are explicit non-goals. Refer back to them if implementation starts pulling you toward adjacent work
   • Review any references or links provided in the plan
   • For a direct implementation-ready plan whose unit count, dependency graph, context volume, or verification spread makes a derived index materially useful, suggest spec-write-tasks once as an optional path. Never auto-compile it and never block direct execution solely because a task pack would help.
   • If the user explicitly asks for TDD, test-first, characterization-first execution, or a specific verification style in this session, honor that direction even if the plan has no Execution note
   • If anything is unclear or ambiguous, ask clarifying questions now
   • If clarifying questions were needed above, get user approval on the resolved answers. If no clarifications were needed, proceed without a separate approval step — plan scope is the plan's authority, not something to renegotiate
   • Do not skip this - better to ask questions now than build the wrong thing
   • Do not edit the plan body during execution. The plan is a decision artifact; progress lives in git commits and the task tracker, not the plan. The only permitted plan mutation is the final shipping closeout transition described in references/shipping-workflow.md: after the completion gates close, the tail owner may use the deterministic helper to change a Markdown source plan from active to completed. This marker is not progress or completion evidence. Leaf workers, reviewers, and subagents never mutate plan status. Legacy - [ ] / - [x] marks remain ignored; per-unit completion is determined from current source and verification evidence.

2. Establish Execution Boundary And Strategy

   Read references/execution-strategy.md before the first write, behavior-bearing test, review fix, commit, or landing action. It is the owner for branch/worktree, task tracking, worker dispatch, parallel safety, integration, commit, and landing details.

   Hard anchors remain here:

   • Resolve one current Git root and, in a parent workspace, one explicit target_repo or per-task repo scope. Artifact --repo is not mutation authority.
   • Record pre-existing dirty paths and stop for overlapping user-owned edits unless an explicit bounded preservation strategy exists.
   • Modify canonical source of truth; generated runtime mirrors are not source fixes.
   • A necessary discovered file may join the actual changed set only with direct evidence that it completes existing scope. A scope-changing discovery involving acceptance, public contract, architecture, provider/repo boundary, or source ownership returns to spec-plan/task regeneration.
   • Missing worker dispatch authorization/capability falls back inline. Unknown isolation follows shared-directory rules.
   • Local implementation does not imply commit_authorization; commit does not imply landing_authorization. Without them, keep verified changes uncommitted and do not push/open a PR.

   STOP — before the first behavior-bearing mutation, read references/feedback-and-tests.md. It owns smallest feedback loop, vertical slicing, proof/characterization, test discovery, system-wide checks, and not-run replacement evidence. For a trivial non-behavioral edit, use the narrow obvious check and do not load or restate the full reference.

   STOP — before adding or materially changing a durable surface, read references/implementation-quality.md. Durable surfaces include dependencies, files, abstractions, helpers/wrappers/adapters, public/schema/runtime/provider/source-of-truth boundaries, workflow handoffs, generators, skills/agents, and artifact contracts. Recheck current source with reuse / extend / compose / new; if the active plan/task did not authorize the needed architecture decision, stop back instead of designing it during implementation. Ordinary bounded edits to an already-owned surface do not emit an architecture matrix or decision note.

   Apply the reference and record one run-local boundary: target_repo, current HEAD/branch, pre-existing dirty paths and overlap, canonical source owner, allowed/changed paths, scope-changing discoveries, worker dispatch authorization/capability/isolation, and separate mutation/commit/landing authorization. Branch or worktree mutation requires explicit authority; never pull/switch/create/rename merely because a plan exists. Default-branch commit still requires explicit confirmation.

   A necessary discovered file may join the changed set only when direct evidence shows it completes existing scope. Acceptance/public-contract/architecture/provider/repo/source-owner expansion returns to spec-plan or task regeneration. Unknown isolation follows shared-directory rules; missing dispatch authorization/capability runs inline. Workers never commit.

3. Create Task List (skip if Phase 0 already built one, or if Phase 0 routed as Trivial)

   • Validated task packs use only pinned Task Pack Contract.tasks and execution_waves; preserve task_id, dependencies, source refs, declared files, stop_if, and review intent.
   • Direct plans use implementation units/U-IDs, dependencies, files, scenarios, verification, execution notes, and patterns; do not invent code-level micro-steps or a parallel private plan.
   • Use the current host tracker when available; otherwise keep a run-local list. Track blockers and evidence, not commit existence.

4. Choose Execution Engine, then Strategy

   Read Execution engines only when plan shape or explicit direction makes a non-default engine relevant. Inline is the portable default. A non-default engine needs explicit authorization and current-session semantic capability, preserves task-pack checkpoints/structured returns, and never changes tail ownership.

   Before worker dispatch, inherit the full boundary from references/execution-strategy.md and record worker_dispatch_authorization, capability_probe, worker_dispatch_capability, worker_context_isolation, worker_model_override, and worker_bounded_parallelism, then normalize the path as worker_dispatch_outcome. Missing authorization forbids discovery and fixes capability_probe: not_applicable plus capability unknown. Only after authorization may the current-session registry/schema be consumed as provider_untrusted evidence. Use serial execution for dependencies, overlapping files/contracts/schema/config/lockfiles/generated outputs, shared environment singletons, or unknown bounded parallelism. Stop parallelizing after broad unplanned edits, repeated conflicts, or out-of-scope failures.

   Give each worker a bounded unit packet rather than the whole plan: Goal Capsule/DoD, active unit, relevant R/F/AE/KTD and Verification excerpts, files/patterns/scenarios/execution note, plus the triggered feedback/implementation-quality rules. Require changed paths and evidence fields in the return. The orchestrator verifies the actual tree, detects collisions/overwrites, integrates in dependency order, reruns authoritative checks, updates task state, and records one of dispatch_authorization_missing, subagent_capability_missing, or worker_capability_unproven, plus any isolation limitations.

Anti-Rationalization Red Flags

这是注意力提醒,不是 gate,也不替代 LLM 判断;最终是否停下、如何处理仍由你按当前证据决定。