Workflow

Orchestrate the development workflow for: $ARGUMENTS

Overview

You are the workflow conductor. You sequence 8 stages, enforce gates between them, dispatch to stage skills, and maintain a state file. You do NOT perform stage-specific work yourself — you delegate to the appropriate skill or sub-agent at each stage.

Stages and Dispatch

Initialization

When invoked, first check for an existing workflow state:

cat .workflow/state.json 2>/dev/null

If state exists and is not completed: Resume from currentStage. Show the dashboard and ask the user whether to continue or restart.

If no state exists: Initialize a new workflow:

1. Generate a short ID: workflow-$(date +%s | tail -c 5)
2. Create or confirm the feature branch (per AGENTS.md branch rules)
3. Write the initial state file (see State Schema below)
4. Begin at Stage 1: Ideation

State Schema

Write to .workflow/state.json:

{
  "id": "workflow-<short-id>",
  "title": "<feature name from $ARGUMENTS>",
  "branch": "<type>/<branch-name>",
  "startedAt": "<ISO timestamp>",
  "updatedAt": "<ISO timestamp>",
  "currentStage": "ideation",
  "stages": {
    "ideation": { "status": "pending", "completedAt": null, "notes": "" },
    "dev-docs": { "status": "pending", "artifacts": { "spec": null, "adr": null } },
    "planning": { "status": "pending", "artifacts": { "plan": null } },
    "implementation": { "status": "pending", "artifacts": { "summaries": [], "issues": [] } },
    "review": { "status": "pending", "artifacts": { "findings": [] } },
    "revision": { "status": "pending", "iterations": 0, "maxIterations": 3 },
    "compound": { "status": "pending", "artifacts": { "solution": null } },
    "reflection": { "status": "pending" }
  }
}

Stage Execution Protocol

For each stage:

1. Update state: Set currentStage and stage status to "in_progress", update updatedAt
2. Show dashboard (see Dashboard section below)
3. Dispatch: Invoke the stage skill/command
4. Check gate: Verify the gate conditions for the current stage
5. Record artifacts: Update the stage's artifacts in state with file paths
6. Advance: Set stage status to "completed" with completedAt, move currentStage to next stage
7. Loop: Return to step 1 for the next stage

Gate Enforcement

If a gate condition is not met after the stage skill returns:

• Tell the user which gate conditions failed and why
• Ask whether to retry the stage or skip (with acknowledgment of risk)
• Do NOT silently advance past a failed gate

Stage Transitions with Special Logic

Stage 4 → 5 (Implementation → Review): Before dispatching review, run the between-stage check:

git fetch origin && git log origin/main --oneline -5

If main has advanced, classify the conflict (no overlap / mechanical / semantic) before proceeding.

Stage 5 → 6 (Review → Revision): Only enter Revision if review found issues. If review is clean, skip directly to Stage 7 (Compound).

Stage 6 → 5 (Revision loop): Revision dispatches back to Review. This loop continues until review passes or maxIterations (3) is reached.

Sub-Agent Structured Output Format

When dispatching implementation sub-agents (Stage 4), each must return its summary in this format. Persist each summary to disk immediately upon receipt:

## Sub-Agent Work Summary

### Task
- Branch: <current branch>
- Spec: specs/<spec-file>.md
- ADR: .adr/staging/<adr-file>.md (if applicable)

### Changes
- Files modified: [list with paths]
- Files created: [list with paths]
- Files deleted: [list with paths]
- Lines: +N / -N

### Claims
Specific, testable statements about what the implementation does.
Review sub-agents verify these claims rather than reading all the code.

1. "[Function/module X] handles [case Y] by [doing Z]"
   - Verifiable by: [test name or command]
2. "[Component A] now [behaves in way B] when [condition C]"
   - Verifiable by: [test name or command]

### Hypothesis Alignment
For each ADR hypothesis that this unit of work touches:

- H1 "[hypothesis text]": [SUPPORTS | REFUTES | NO EVIDENCE] -- [brief evidence]
- H2 "...": ...

### Tests
- Tests written: N
- Tests passing: N/N
- Commands: `[exact test command to reproduce]`
- Coverage: [files/functions covered by tests]

### Known Gaps
- [anything not completed, deferred, or uncertain]
- [any divergence from spec with justification]

### Accepted ADR Conflicts
- [any previously accepted ADR whose reasoning is contradicted or undermined by this work]
- [leave empty if none found]

### Risks
- [anything that could break other parts of the system]
- [any assumptions made that should be verified]

Save summaries to: .adr/staging/<NNN>-<name>-summary.md

Operational Rules

1. 1 sub-agent = 1 commit: Each sub-agent's unit of work is exactly one commit, made after review validates the work — not during implementation.
2. Summaries to disk: Persist sub-agent summaries immediately. Without this, orchestrator crashes lose all work.
3. Orchestrators delegate: You do NOT read implementation code or write production code. You dispatch sub-agents and validate their summaries.
4. Atomic commits: The commit includes both code changes AND any spec updates in the same commit.
5. Conventional commits: All commits follow <type>[scope]: <description> format.

Dashboard

After each stage transition, render this dashboard:

WORKFLOW: <title>
Branch: <branch>
Started: <startedAt>

Stage                 Status        Artifacts
-------               ------        ---------
1. Ideation           [status]      [notes excerpt]
2. Dev-Time Docs      [status]      spec: [path], adr: [path]
3. Planning           [status]      plan: [path]
4. Implementation     [status]      summaries: N, issues: N
5. Review             [status]      findings: N
6. Revision           [status]      iterations: N/3
7. Compound           [status]      [solution path]
8. Reflection         [status]

Current: Stage N - <stage name>
Next action: <what to do next>

Status symbols: [ ] pending, [~] in_progress, [x] completed, [-] skipped

Completion

When Stage 8 (Reflection) completes:

1. Set all stage statuses to reflect final state
2. Update updatedAt
3. Report the final dashboard
4. The state file remains for archaeological reference but is gitignored

Error Recovery

If you are resuming a workflow after a crash or context loss:

1. Read .workflow/state.json to determine where you were
2. Check for persisted summaries: ls .adr/staging/*-summary-*.md
3. Check working tree: git status
4. Determine which recovery case applies (see WMD incident response) and resume accordingly

Reference

The rationale, failure modes, and detailed process descriptions that inform this workflow are documented in docs/WORKFLOW-MASTER-DESCRIPTION.md. Consult it when you need to understand WHY a rule exists, not just WHAT the rule is.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.