Autonomous Spec Writer

Overview

All subagent dispatches use disk-mediated dispatch. See

shared/dispatch-convention.md

Fully autonomous skill that takes a GitHub epic (or equivalent issue tracker artifact), processes child tickets without human interaction, and produces complete design docs + implementation plans + machine-readable contracts per ticket. Designed to run unattended while a separate agent (or human) handles implementation.

The core insight: Separate the cognitive work (design, investigation, decision-making, planning) from the execution work (implementation, testing). One agent specs autonomously, another builds. The spec agent requires no human input after the initial invocation -- it investigates the codebase, makes design decisions, documents its reasoning, and flags uncertainty via terminal alerts rather than blocking on human answers. Contracts solve the hard problem of two async agents communicating through prose -- prose is ambiguous, contracts make inter-ticket interfaces structural and verifiable.

Invocation:

/spec https://github.com/org/repo/issues/123
/spec PROJ-456    # if Jira/Atlassian MCP is available

Announce at start: "I'm using the spec skill to autonomously produce design docs, implementation plans, and contracts for this epic."

Communication Requirement (Non-Negotiable)

After each wave completes and after each ticket within a wave reports back, output a status update to the terminal. This is NOT optional -- the user cannot see agent activity without your narration.

Every status update must include:

1. Current wave -- Which wave is in progress or just completed
2. Tickets completed / remaining -- Counts for the current wave and overall
3. Alerts emitted -- Any medium/low/block confidence decisions from that wave
4. Re-queued tickets -- Any tickets moved to a later wave due to dependency discovery

After compaction: If you just experienced context compaction, follow the Compaction Recovery procedure, re-read state from the scratch directory, and output current status before continuing. Do NOT proceed silently.

Example of GOOD narration:

"Wave 2 complete. 3/3 tickets committed. 1 medium-confidence alert on #45 (chose Redis over Postgres for session store). #67 re-queued to Wave 3 (new dependency on #45 discovered). Overall: 7/12 tickets done, 5 remaining across 2 waves."

Anti-Rationalization Table — spec

no-alternatives: true

Status: SKIPPED

Pipeline Status

Write a status file to

~/.claude/projects/<hash>/memory/pipeline-status.md

Write Triggers

Write the status file at every point where the Communication Requirement mandates narration: before dispatch, after completion, phase transitions, health changes, escalations, and after compaction recovery.

Status File Format

The status file uses this structure (overwritten in full each time):

# Pipeline Status
**Updated:** <current timestamp>
**Started:** <timestamp from first write — persisted across compaction>
**Skill:** spec
**Phase:** <current phase, e.g. "Wave 2 (3/4 tickets in progress)">
**Health:** <GREEN|YELLOW|RED>
**Suggested Action:** <omit when GREEN; concrete one-sentence action when YELLOW/RED>
**Elapsed:** <computed from Started>

## Recent Events
- [HH:MM] <most recent event>
- [HH:MM] <previous event>
(last 5 events, newest first)

Skill-Specific Body

Append after the shared header:

## Tickets
- Wave 1: 3/3 complete
- Wave 2: 2/4 in progress (#45 writing, #67 investigating)
- Alerts: 1 medium-confidence on #45

## Compression State
Goal: [epic URL and description]
Key Decisions:
- [accumulated decisions, max 10]
Active Constraints:
- [dependency constraints, re-queued tickets]
Next Steps:
1. [immediate next action]
2. [subsequent actions]

Health State Machine

Health transitions are one-directional within a phase: GREEN -> YELLOW -> RED. Phase boundaries reset to GREEN.

• Phase boundaries (reset to GREEN): each new wave
• YELLOW: ticket re-queued more than once, teammate failure on a ticket, medium-confidence alert
• RED: 2+ tickets failed in same wave, unresolvable dependency cycle, block-confidence alert

When health is YELLOW or RED, include

**Suggested Action:**

Inline CLI Format

Output concise inline status alongside the status file write:

• Minor transitions (dispatch, completion): one-liner, e.g.

  Wave 2 [7/12] #45 spec committed | GREEN | 45m

• Phase changes and escalations: expanded block with

  ---

  separators
• Health transitions: always expanded with old -> new health

Compaction Recovery

After compaction, before re-writing the status file: 0. Read the

## Compression State

pipeline-status.md

1. Read the rest of

   pipeline-status.md

   to recover

   Started

   timestamp and

   Recent Events

   buffer
2. Reconstruct phase, health, and skill-specific body from internal state files
3. Emit a Compression State Block into the conversation to seed the new context window
4. Write the updated status file
5. Output inline status to CLI

Epic Extraction

GitHub has no first-class "epic with child tickets" API. Use a fallback chain to extract scope units from the provided issue:

Extraction Strategy (ordered fallback)

1. Sub-issues via GraphQL: Query the

   trackedIssues

   field on the issue. If the issue has sub-issues, use them as scope units.
2. Task list checkboxes: Parse the issue body for task list items (

   - [ ]

   /

   - [x]

   ) that reference issues via

   #NNN

   syntax. Extract referenced issue numbers as scope units.
3. Body issue references: Parse the issue body for any GitHub issue URLs (

   https://github.com/.../issues/NNN

   ) or

   #NNN

   references not inside task lists. Extract as scope units.
4. Manual identification: If none of the above yield scope units, present the full issue body to the user and ask: "I couldn't find discrete child tickets. Can you identify the scope units for this work? You can provide issue numbers, paste URLs, or describe the work items and I'll create tickets for each."

Handling No Discrete Tickets

If the epic represents a single monolithic piece of work (no children, user confirms it's one unit), process it as a single-ticket run: one investigation, one design doc, one contract. The orchestration flow still applies, just with a single item in the queue.

Scratch Directory

All orchestrator and teammate state is persisted to

~/.claude/projects/<project-hash>/memory/spec/scratch/<run-id>/

scratch-directory.md

Context Budget Management

Processing 5+ tickets will exhaust the orchestrator's context window. The skill uses cascading context compression:

Preemptive Context Checkpoint

The orchestrator triggers a planned save-and-compact cycle: compact after every 2 waves, or after any single wave that contained 4+ tickets. These thresholds are tied to the amount of work processed rather than unreliable context capacity estimates.

When a checkpoint triggers:

1. Persist all current state to the scratch directory (ticket statuses, dependency graph, wave schedule, decisions log).
2. Emit a Compression State Block into the conversation capturing Goal, accumulated decisions, active constraints, and next steps.
3. Trigger compaction explicitly between waves rather than hitting mid-ticket compaction.
4. After compaction, recover state via the Compaction Recovery procedure below.
5. Resume processing with the next wave.

This prevents mid-ticket compaction, which wastes partial investigation work. The checkpoint always occurs at a clean boundary between waves.

Per-Ticket Context Lifecycle

1. Before ticket investigation: Read only the ticket body, dependency graph, and upstream contracts relevant to this ticket from the scratch directory. Do not load prior tickets' full investigation results into context.
2. During investigation: Run investigation agents as sub-agents (Agent tool). They return summaries, not full search results.
3. After ticket completion: Write all outputs to disk (design doc, contract, status update). Compress the ticket's context contribution to a single-paragraph summary appended to

   decisions.md

   . Release the full investigation context.

Ticket Complexity Triage

Teammates run as sub-agents with their own context windows. Complex tickets can exhaust a teammate's context before investigation completes. Mitigate by triaging complexity before dispatch:

1. Complexity signal: Count the number of design dimensions requiring investigation (inferred from ticket body + upstream dependency count + codebase area size from cartographer). If a ticket has 5+ design dimensions or 3+ upstream contracts to consume, flag it as "complex."
2. Simplified investigation for complex tickets: Complex tickets use quick-scan investigation for ALL dimensions (read recon brief per dimension instead of 3-agent deep dive), with more aggressive summarization. The teammate's task description includes: "This ticket is flagged as complex. Use quick-scan investigation for all dimensions. Summarize each finding to 2-3 sentences before proceeding to the next dimension."
3. Two-phase split for very large tickets: If a ticket has 8+ design dimensions, the orchestrator splits investigation into two phases with an intermediate disk persist. Phase A investigates the first half of dimensions, writes findings to

   tickets/<ticket-number>/partial-investigation.md

   , and completes. Phase B reads the partial investigation from disk, investigates the remaining dimensions, and proceeds to writing. This doubles the effective context budget at the cost of one extra sub-agent dispatch.

Compaction Recovery

After context compaction: 0. Read

## Compression State

1. Read

   scratch/<run-id>/invocation.md

   first -- recover epic URL, extraction method, and user preferences.
2. Read

   scratch/<run-id>/ticket-status.json

   -- determine which tickets are complete, in-progress, or pending.
3. Read

   scratch/<run-id>/wave-schedule.json

   -- recover the current wave schedule.
4. Read

   scratch/<run-id>/dependency-graph.json

   -- recover the current dependency DAG.
5. Read

   scratch/<run-id>/decisions.md

   -- recover the decision log for context cascading to remaining tickets.
6. For any ticket with status

   investigating

   ,

   dependency-check

   ,

   writing

   , or

   validating

   : restart from the beginning of its current phase.
7. Emit a Compression State Block into the conversation to seed the new context window. 7.5. Read session index summary (supplementary): If the CSB Scratch State contains a

   Session Index:

   path, or if globbing

   ~/.claude/projects/<hash>/memory/session-index/*/summary.md

   finds a recent file, read

   summary.md

   . Include the Activity Timeline, Files Modified, and Key Decisions sections in the post-compaction narration. If no session index exists, skip silently — this step is purely additive.
8. Resume processing from the wave schedule, skipping completed/committed tickets.

Checkpoint Timing

Emit a Compression State Block at:

• Wave boundaries: After each wave completes, before starting the next
• Preemptive context checkpoints: After every 2 waves, or after any single wave with 4+ tickets
• Ticket re-queues: When tickets are re-queued to later waves due to dependency discovery
• Escalations: Before any escalation to user
• Health transitions: On any GREEN->YELLOW or YELLOW->RED transition

Pipeline-Active Marker

Before any dispatch work, check for a crashed prior spec session:

1. Check

   <scratch>/.pipeline-active

   (where

   <scratch>

   is

   ~/.claude/projects/<hash>/memory/

   )
2. Not found: Write the pipeline-active marker (JSON with

   pipeline_id

   set to current session ID,

   skill

   set to

   "spec"

   ,

   phase

   set to

   "init"

   ,

   start_time

   set to current ISO-8601 timestamp,

   scratch_dir

   and

   dispatch_dir

   paths,

   branch

   from

   git branch --show-current

   ,

   baseline_sha

   from

   git rev-parse HEAD

   ). Proceed to Orchestration Flow.
3. Found, same

   pipeline_id

   : Compaction recovery (existing behavior). Do not re-write the marker.
4. Found, different

   pipeline_id

   : Previous spec session crashed. Check marker's

   branch

   against current branch — if mismatched, warn the user which branch the crashed session was on. Present to user:

   "Previous spec session on branch [marker.branch] crashed. Start fresh? [yes]" Delete the stale marker. Write a fresh marker. Proceed to Orchestration Flow. (Full replay orchestration for spec is deferred -- detection and cleanup only for now.)

Marker cleanup: Delete

.pipeline-active

Orchestration Flow

/spec <epic-url>
  |
  +-- [1] Consult cartographer (once) + forge feed-forward (once)
  |
  +-- [2] Fetch epic, extract child tickets (fallback chain)
  |
  +-- [3] Read ALL tickets upfront
  |
  +-- [4] Content-analyze tickets, infer dependency graph
  |
  +-- [5] Build wave schedule from dependency graph
  |       Group independent tickets into waves. Within a wave,
  |       all tickets are guaranteed to have no cross-dependencies.
  |
  +-- [6] Present execution plan to user
  |       "Wave 1: #1, #3, #5 (independent). Wave 2: #2 (depends on #1), #4..."
  |
  +-- [7] Ask: "Auto-create a PR for the epic, or just commit to the branch?"
  |
  +-- [8] Persist initial state to scratch directory
  |       Write invocation.md, scope-units.json, dependency-graph.json,
  |       wave-schedule.json, ticket-status.json (all pending)
  |
  +-- [9] Create team + tasks (Agent Teams, with sequential fallback)
  |
  +-- [10] Process waves sequentially, tickets within each wave in parallel
  |        |
  |        +-- Per wave:
  |            +-- Preemptive context checkpoint (every 2 waves, or after large waves)
  |            +-- Dispatch all tickets in wave as parallel teammates
  |            +-- Per ticket (teammate writes to tickets/<ticket-number>/):
  |                +-- Skip if completed (silent)
  |                +-- Skip if spec docs exist (mention in output)
  |                +-- Update local status -> "investigating"
  |                +-- Run investigation (same depth as /design)
  |                +-- Dependency discovery check -> write discoveries.json
  |                +-- Update local status -> "writing"
  |                +-- Security signal scan (shared/security-signals.md) -> include security_review in contract if signals detected
  |                +-- Write design doc + implementation plan + contract to output/
  |                +-- Contract schema validation
  |                +-- Update local status -> "validating"
  |                +-- Lightweight per-ticket validation (5 checks)
  |                +-- Update local status -> "committed"
  |                +-- Persist outputs + local decisions to ticket dir
  |                +-- (On failure: local status -> "failed", log reason, continue)
  |            +-- After wave completes (orchestrator):
  |                +-- Reconcile per-ticket outputs into shared state files
  |                +-- Cascade contracts: copy to shared contracts/ directory
  |                +-- Copy outputs from ticket dirs to docs/plans/
  |                +-- Commit outputs to spec/<epic-number> branch (serialized)
  |                +-- Check for re-queued tickets, update wave schedule
  |                +-- Output status update to terminal (include security_review status per ticket if present)
  |
  +-- [11] End-of-run quality gate
  |        +-- Phase 1: Per-document gates (design + plan per ticket, in parallel)
  |        +-- Phase 2: Cross-ticket integration check (contracts + dep graph only)
  |
  +-- [12] Summary report

Step-by-Step Detail

[1] Consult cartographer + forge: Use

crucible:cartographer

crucible:forge

[2] Fetch epic, extract child tickets: Use the extraction fallback chain (sub-issues, task list checkboxes, body references, manual identification). See Epic Extraction section.

[3] Read ALL tickets upfront: Fetch the full title, body, labels, and linked issues for every extracted ticket. This enables dependency analysis before any investigation begins.

[4] Content-analyze tickets, infer dependency graph: Read every ticket's content and identify explicit references ("after #123 is done", "depends on the interface from #456") and implicit dependencies (ticket A defines an interface, ticket B consumes it). Build a DAG. See Dependency Analysis section for cycle handling.

[5] Build wave schedule: Topological sort the dependency graph. Assign each ticket to the earliest wave where all upstream dependencies are in prior waves. No intra-wave dependencies. See Wave-Based Scheduling section.

[6] Present execution plan: Show the user the wave schedule with ticket groupings and dependency rationale. The user can override (reorder, force sequential, etc.) or approve.

[7] Ask about auto-PR: "Auto-create a PR for the epic, or just commit to the branch?"

[8] Persist initial state: Write

invocation.md

scope-units.json

dependency-graph.json

wave-schedule.json

ticket-status.json

pending

[9] Create team + tasks: Use Agent Teams (TeamCreate/TaskCreate) for parallel execution. If Agent Teams unavailable, fall back to sequential subagent dispatch. See Parallel Execution section.

[10] Process waves: Sequential between waves, parallel within waves. Per-wave details in the flow diagram above. Post-wave reconciliation updates shared state, cascades contracts, copies outputs to

docs/plans/

[11] End-of-run quality gate: Two phases -- per-document gates on each design doc and plan, then cross-ticket integration check on contracts and dependency graph. See End-of-Run Quality Gate section.

Decision Extraction (After All Waves Complete)

After all waves complete and before branch/PR operations:

1. Read

   scratch/<run-id>/decisions.md

   (shared decision log)
2. For each ticket in committed status, read

   tickets/<ticket-number>/decisions.md

3. Collect all file paths from committed design docs (the

   Path:

   or file references within each design doc's Current State Analysis)
4. Map decisions to cartographer modules using file path prefix matching
5. Dispatch cartographer recorder with directive "Extract decisions for cartographer" Input: collected decisions, module mapping, existing module files, existing decisions.md
6. Write recorder output to cartographer storage
7. This step is RECOMMENDED, not REQUIRED -- failure does not block the spec run

[12] Summary report: Output a final report with: tickets completed, tickets failed (with reasons), tickets blocked (with decision context), alerts emitted, contracts produced, and the branch/PR URL.

Parallel Execution via Agent Teams

The orchestrator uses Agent Teams (TeamCreate/TaskCreate) to dispatch tickets within a wave in parallel:

1. Create team at run start:

   TeamCreate: team_name="spec-<epic-number>", description="Speccing epic #NNN"
   

2. Create tasks for each ticket via TaskCreate, with description containing the ticket body, upstream contracts, and relevant decisions log entries.

3. Dispatch teammates for each ticket in the current wave. Each teammate writes all outputs to its isolated scratch directory (

   tickets/<ticket-number>/output/

   ). Teammates do not perform any git operations -- the orchestrator handles all git work after the wave completes.

4. Track completion via TaskGet/TaskList. As teammates complete, the orchestrator collects results and updates the scratch directory.

Agent Teams Fallback

If

TeamCreate

Agent teams are not available. Recommended: set

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Falling back to sequential subagent dispatch via Agent tool.

Then fall back to sequential subagent dispatch via the Agent tool. Each ticket in a wave is dispatched sequentially instead of in parallel. All other behavior (wave scheduling, dependency discovery, validation, quality gate) is unchanged -- the run is slower but functionally identical.

Wave-Based Scheduling

Tickets are grouped into execution waves based on the dependency graph. This eliminates the need for runtime cancellation of in-progress tickets -- a capability Claude Code does not support.

Wave Construction

1. Topological sort the dependency graph.
2. Assign each ticket to the earliest wave where all its upstream dependencies are in prior waves.
3. All tickets within a single wave are guaranteed independent of each other -- no ticket in wave N depends on another ticket in wave N.
4. Persist the wave schedule to

   scratch/<run-id>/wave-schedule.json

   .

Wave Execution

Waves execute sequentially. Within each wave, all tickets execute in parallel (via Agent Teams) or sequentially (via Agent tool fallback). A wave does not begin until all tickets in the prior wave have reached a terminal state (committed or failed).

Re-queuing on Dependency Discovery

If investigation reveals a new dependency between two tickets assigned to the same wave:

1. The downstream ticket's status is set to

   "re-queued"

   with reason "new upstream dependency discovered from #NNN".
2. The downstream ticket is removed from the current wave and added to the next wave (or a new wave is created if none exists).
3. The wave schedule is persisted to disk.
4. The downstream ticket's work products (if any) are discarded -- it will restart from scratch in its new wave.

Because all tickets within a wave are dispatched simultaneously, the re-queued ticket may already be in progress. This is acceptable: the teammate will complete its work, but the orchestrator discards the results and re-processes the ticket in the correct wave with the upstream dependency's outputs available. No runtime cancellation is needed -- the wasted work is bounded to a single ticket's investigation and writing.

Per-Ticket Spec Writing

Each ticket goes through the same investigation process as

/design

spec/spec-writer-prompt.md

Step 1: Investigation

At the start of each ticket's investigation, dispatch

/recon

/recon
  task: "<ticket title and description>"
  session_id: "<spec-epic-run-id>"
  modules: ["impact-analysis"]

The

session_id

On recon failure: "Recon failed: [reason]. Falling back to inline investigation." Proceed without recon context -- dimension investigations explore from scratch.

Same depth as

/design

• Deep dive (architectural decisions): 2 parallel agents (domain researcher, impact analyst) with recon brief context + challenger
• Quick scan (implementation approach): read relevant sections of the recon brief (no agent dispatch needed)
• Direct resolution (no technical implications): decide immediately

All investigation results cascade -- prior ticket decisions inform subsequent investigations via the decisions log in the scratch directory.

If the ticket is flagged "complex" (5+ design dimensions or 3+ upstream contracts), use quick-scan for ALL dimensions (read recon brief). Summarize each finding to 2-3 sentences.

Step 2: Dependency Discovery

After investigation completes but before writing begins:

1. Compare investigation findings against the current dependency graph.
2. If new cross-ticket dependencies found, write to

   tickets/<ticket-number>/discoveries.json

   .
3. If no new dependencies, write empty discoveries:

   { "dependencies": [] }

   .

The orchestrator reconciles all discoveries after the wave completes:

• Downstream ticket pending: Update graph. Re-queue if same wave.
• Downstream ticket in same wave (already dispatched): Mark as

  re-queued

  . Orchestrator discards results and re-processes in a subsequent wave.
• Downstream ticket already committed: Set to

  needs-respec

  . Emit terminal alert. Add to summary report.

Step 3: Autonomous Decision-Making

Where

/design

/spec

• Synthesizes investigation results
• Picks the recommended option (or the only viable path)
• Documents reasoning in the design doc
• Assigns a confidence level to each decision

Decision thresholds:

blocked

Alert format:

SPEC ALERT [#123] (medium confidence): Chose X over Y -- see design doc for reasoning
SPEC ALERT [#123] (low confidence): Chose X over Y -- REVIEW RECOMMENDED before /build picks this up
SPEC ALERT [#123] (blocked): Cannot decide autonomously -- irreversible security/data-integrity decision. See scratch dir for options. Provide input on re-invocation.

Step 4: Document Generation

Produces three artifacts per ticket in

tickets/<ticket-number>/output/

docs/plans/

a. Design doc (

YYYY-MM-DD-<topic>-design.md

Frontmatter:

---
ticket: "#123"
epic: "#100"
title: "Brief ticket title"
date: "2026-03-21"
source: "spec"
---

Body sections:

• Current state analysis
• Target state
• Key decisions with confidence scores and alternatives considered
• Migration/implementation path (high-level direction, not task-level)
• Risk areas
• Acceptance criteria

b. Implementation plan (

YYYY-MM-DD-<topic>-implementation-plan.md

Same frontmatter as design doc (

ticket

epic

title

date

source

/build

/build

c. Contract (

YYYY-MM-DD-<topic>-contract.yaml

See

contract-schema.md

Step 5: Contract Schema Validation

After generating the contract YAML, validate against the schema. The rules below must stay consistent with the field definitions in

contract-schema.md

1. Required fields present: Verify

   version

   ,

   ticket

   ,

   epic

   ,

   title

   ,

   date

   ,

   api_surface

   , and

   invariants

   all exist.
2. Field value validation:

   • api_surface[].type

     must be one of:

     function

     ,

     class

     ,

     interface

     ,

     endpoint

     ,

     event

   • api_surface[].params

     must be present for

     function

     ,

     class

     , and

     interface

     types. Each param must have

     name

     ,

     type

     , and

     required

     fields.

   • invariants.checkable[].check_method

     must be one of:

     grep

     ,

     code-inspection

     ,

     file-structure

   • invariants.testable[].test_tag

     must match the pattern

     contract:<category>:<id>

3. Security review field validation (when present):

   • security_review.status

     must be one of:

     required

     ,

     recommended

   • security_review.signals_detected

     must be a non-empty array
   • Each entry must have

     category

     (one of:

     auth

     ,

     crypto

     ,

     external_input

     ,

     secrets

     ,

     network

     ,

     pii_data

     ,

     dependencies

     ) and

     evidence

     (non-empty string)

   • security_review.deployment_context

     (if present) must be one of:

     public

     ,

     intranet

     ,

     hybrid

4. Integration point validation: For each entry in

   integration_points

   , verify that the referenced contract file exists in

   docs/plans/

   or the scratch directory's

   contracts/

   folder. If the referenced contract does not yet exist (upstream ticket not yet processed), log a warning but do not block.
5. On validation failure: Report specific errors. Re-dispatch the contract generation step with the validation errors as feedback. If the second attempt also fails, log the errors, mark the contract as having validation warnings, and continue -- do not block the entire run on a malformed contract.

Step 6: Lightweight Per-Ticket Validation

Five checks before committing:

1. Contract schema check: Verify the contract passed Step 5 validation without errors.
2. Acceptance criteria present: Verify the design doc contains an acceptance criteria section with at least one concrete criterion.
3. Invariants defined: Verify the contract contains at least one checkable or testable invariant.
4. Frontmatter complete: Verify all required frontmatter fields (

   ticket

   ,

   epic

   ,

   title

   ,

   date

   ,

   source

   ) are present in both the design doc and implementation plan.
5. Cross-reference check: Verify the design doc, implementation plan, and contract all reference the same ticket number.

If any check fails, set ticket status to

"failed"

Step 7: Error Handling

On any failure during per-ticket processing:

1. Write status to

   tickets/<ticket-number>/status.json

   : set status to

   "failed"

   , record the error reason.
2. Log the failure to the terminal with the ticket number and error summary.
3. Continue processing remaining tickets -- do not halt the entire run.
4. Include failed tickets in the summary report with failure reasons.

Re-invocation resume logic:

On re-invocation of

/spec

1. Detect existing scratch directory (match on epic URL in

   invocation.md

   ). If not found at the canonical path, use the project-hash recovery procedure.
2. Read

   ticket-status.json

   to determine resume point.
3. Skip

   committed

   tickets. Retry

   failed

   and

   re-queued

   tickets. Resume

   pending

   tickets. Re-process

   needs-respec

   tickets with upstream contracts now available. Unblock

   blocked

   tickets: present blocking decision context and options to user, collect input, then resume.
4. Present the resume plan to the user before proceeding.

Quality Gate Requirement (Non-Negotiable)

Every quality gate in this pipeline MUST run to completion. This is NOT optional — you may NOT self-assess whether a quality gate is "needed" based on ticket size, complexity, or scope. Spec dispatches quality gates on every committed ticket (potentially dozens), which creates strong temptation to skip on "simple" tickets. Do not yield to this temptation.

Fixing findings is NOT the same as passing the gate. The iteration loop must complete with a clean verification round (0 Fatal, 0 Significant on a fresh review). Spec is the highest-volume gate dispatcher — the short-circuit temptation is strongest here.

The only valid skip is an unambiguous user instruction specifically referencing the gate. General feedback is not skip approval.

Gate tracking: Before compiling the end-of-run summary, verify that every committed ticket has per-document gate round counts >= 1 with clean final rounds. If any gate was skipped with explicit user approval, record it as

USER_SKIP

End-of-Run Quality Gate

After all waves complete and all tickets are in terminal states, run a two-phase quality gate.

Phase 1: Per-Document Quality Gates

For each committed ticket, dispatch two standard quality gate passes using existing artifact types:

1. Design doc gate: (Non-negotiable — see Quality Gate Requirement.) Dispatch

   crucible:quality-gate

   with artifact type

   design

   on the ticket's design doc. Review scope: Are decisions well-reasoned? Are acceptance criteria testable? Is the current-state analysis accurate?
2. Implementation plan gate: (Non-negotiable — see Quality Gate Requirement.) Dispatch

   crucible:quality-gate

   with artifact type

   plan

   on the ticket's implementation plan. Review scope: Are tasks concrete? Do they align with the design doc? Are dependencies between tasks identified?

These use the quality gate's existing iterative fix loop. Each gate runs within normal context budgets (one document per gate invocation). Per-document gates can run in parallel across tickets (via Agent Teams, or sequentially via Agent tool fallback).

Phase 2: Cross-Ticket Integration Check

After all per-document gates pass, run a mandatory integration check across ticket boundaries using the prompt template

spec/integration-check-prompt.md

crucible:quality-gate

Input (kept small for context budget):

• All contract YAML files (500-1000 tokens each)
• The final dependency graph
• The decisions log, filtered: only cross-ticket decisions and medium/low/block confidence decisions. Single-ticket high-confidence decisions are excluded to keep context within budget.

Review scope:

• Do contracts at integration points agree on signatures, types, and params?
• Are there contradictory decisions across tickets?
• Does the dependency graph match the actual integration points declared in contracts?
• Are there gaps -- tickets that should have integration points but don't?

On findings: Each finding identifies a specific ticket and document. The orchestrator routes the fix based on finding type:

• Design or plan findings: Dispatch a per-document quality gate (

  design

  or

  plan

  artifact type) on the identified document, with the integration finding included as review context.
• Contract findings (mismatched signatures, missing integration points, contradictory surface declarations): Re-run the contract generation pipeline for the affected ticket -- re-execute Step 4 (contract portion) and Step 5 (validation). Contracts are re-derived from the source of truth rather than patched by a fix agent.

Verification re-pass: After all integration-triggered fixes complete, re-run the cross-ticket integration check exactly once as a verification pass. If the verification pass finds new issues, do NOT enter another fix cycle -- escalate to the user: "Integration verification found [N] new issue(s) after fix pass. These require manual review: [list findings]." Include unresolved findings in the summary report. This bounds the integration check to exactly two passes (initial + verification).

Dependency Analysis

The skill reads all tickets upfront and infers the dependency graph from content analysis:

• Reads every ticket's title, body, labels, and any linked issues
• Identifies explicit references ("after #123 is done", "depends on the interface from #456")
• Identifies implicit dependencies (ticket A defines an interface, ticket B consumes it)
• Builds a DAG, detects cycles

Cycle Detection

On cycle detection:

1. Present the cycle concretely: Display the cycle as a list of edges: "#A depends on #B depends on #C depends on #A" with the specific dependency reason for each edge.
2. Suggest breaking strategies: For each edge in the cycle, assess which dependency is weakest and suggest: (a) merge the cyclic tickets if tightly coupled, (b) defer the weakest dependency edge -- process downstream without upstream contract, mark for re-validation, or (c) remove a dependency edge if the user determines it is not a true blocker.
3. User resolves: The user selects a breaking strategy or removes a specific dependency edge. The orchestrator updates the dependency graph, persists the modified

   dependency-graph.json

   with an annotation in

   decisions.md

   , and re-runs wave construction.
4. If user unavailable (re-invocation scenario): Apply the weakest-edge deferral strategy automatically. Remove the weakest edge, log the decision as a medium-confidence autonomous decision with a terminal alert, and continue. The deferred ticket is marked for re-validation after its upstream completes.

The dependency graph is presented to the user before execution begins. The user can override (reorder, force sequential, etc.) or approve.

The dependency graph is a living document -- it may be updated during investigation (see Dependency Discovery in Step 2). The initial graph is the best guess from ticket content; investigation reveals ground truth from the codebase.

Skip Logic

• Completed tickets (checked off in the epic): skipped silently.
• Committed tickets (status

  committed

  in

  ticket-status.json

  ): skipped silently on re-invocation.
• Tickets with existing spec docs (matching frontmatter

  ticket

  field in

  docs/plans/*-design.md

  ): mentioned in output, skipped. User sees: "Skipping #123 -- spec doc already exists at

  docs/plans/2026-03-15-auth-refactor-design.md

  "
• Needs-respec tickets (status

  needs-respec

  in

  ticket-status.json

  ): re-processed on re-invocation with upstream contracts available. If the re-processed ticket generates a filename matching an existing file in

  docs/plans/

  , the new output overwrites the old file.

Branch Strategy

All tickets in an epic commit to a single branch:

spec/<epic-number>

docs/plans/

• Branch naming:

  spec/<epic-number>

  (e.g.,

  spec/123

  )
• No per-teammate worktrees: Teammates do not use git worktrees. Each teammate writes all outputs to its isolated scratch directory. Teammates perform no git operations.
• Orchestrator handles git: After each wave completes, the orchestrator copies outputs from per-ticket scratch directories to

  docs/plans/

  , then commits to the

  spec/<epic-number>

  branch. All git operations are serialized through the orchestrator. If the orchestrator needs a worktree for the epic branch (e.g., the user's working tree is on a different branch), it creates a single worktree for its own use.
• Commit ordering: Within a wave, the orchestrator commits each ticket's outputs sequentially. Across waves, commits are naturally sequential.
• Repository safety check (before PR creation): Before creating the PR, run

  gh repo view --json isPrivate -q .isPrivate

  . If the repo is public, scan all commit messages and the PR body for proprietary company information, internal names, or sensitive data. STOP and confirm with the user if anything looks sensitive. This is especially critical for /spec because it runs largely autonomously and files multiple issues in batch.
• PR creation: A single PR is created (if user opted in) from the

  spec/<epic-number>

  branch after all tickets complete.

Contract Format

Machine-readable contracts make inter-ticket interfaces structural and verifiable rather than relying on ambiguous prose. Full schema (YAML), version rejection rule, invariant categories, cascading rules, and required-fields table: see

contract-schema.md

Red Flags

• Skipping Compression State Block emission at checkpoint boundaries
• Emitting a Compression State Block with stale or missing Key Decisions (decisions must be cumulative across all prior blocks)
• Allowing the Goal field to drift across successive Compression State Blocks (must match original user request)
• Exceeding 10 entries in the Key Decisions list without overflow-compressing the oldest
• Skipping a per-document quality gate because the ticket seems "small", "simple", or "trivial"
• Self-assessing that a quality gate is unnecessary based on perceived ticket complexity
• Declaring a quality gate "done" after fixing findings without a clean verification round (fixing is not passing)
• Skipping the integration check because "all per-document gates passed so it's fine"
• Interpreting general user feedback as approval to skip a quality gate that has not yet run — once a gate has run and presented findings to the user, the user's decision to proceed is authoritative
• Treating session index summary as authoritative over CSB state (session index is supplementary narrative, CSB is authoritative state)

Integration

Sub-skills used:

• crucible:cartographer -- consult mode, once at start of run
• crucible:forge -- feed-forward mode, once at start of run
• crucible:design -- investigation prompts (parallel agents) reused for autonomous investigation. Templates in

  design/investigation-prompts.md

  .
• crucible:recon -- dispatched per-ticket at investigation start with

  modules: ["impact-analysis"]

  and epic-level

  session_id

  for Structure Scout cache reuse across tickets. Replaces Codebase Scout. Fallback: investigate from scratch.
• crucible:assay -- dispatched per architectural dimension (Deep Dive) with

  decision_type: "architecture"

  . Confidence routing: high=accept, medium=alert, low=block-alert. Fallback: manual synthesis.
• crucible:quality-gate -- per-document gates (artifact types

  design

  and

  plan

  ) + cross-ticket integration check on contracts
• crucible:worktree -- orchestrator-only, for the epic branch if the user's working tree is on a different branch

Prompt templates:

• spec/spec-writer-prompt.md

  -- Per-ticket teammate prompt encoding the full 7-step spec writing flow

• spec/integration-check-prompt.md

  -- Cross-ticket integration check prompt for Phase 2 quality gate

Trigger words:

/spec

Contract between /spec and /build:

/spec

docs/plans/

YYYY-MM-DD-<topic>-{design,implementation-plan,contract}.{md,yaml}

ticket

epic

title

date

source

/build

docs/plans/

ticket

Key Principles

• Autonomous execution -- No human input after initial invocation. Investigate, decide, document, flag uncertainty.
• Wave-based parallelism -- Independent tickets run in parallel within waves. Dependent tickets are sequenced across waves. No runtime cancellation needed.
• Contract-first output -- Machine-readable contracts are a first-class output, not an afterthought. Contracts make inter-ticket interfaces structural and verifiable.
• Disk-persisted state -- All critical state lives on disk in the scratch directory. Context compaction cannot lose progress. The orchestrator never relies solely on context memory.
• Graceful degradation -- Agent Teams fallback to sequential dispatch. Re-invocation resumes from scratch directory state. Failed tickets are isolated. Blocked tickets defer to the user.
• Cascading context -- Every decision informs subsequent investigations. Upstream contracts flow to downstream tickets. The decisions log is the running memory of the epic.
• Quality over velocity -- Per-ticket validation, per-document quality gates, cross-ticket integration checks. The pipeline produces correct, consistent output even at the cost of additional passes.