Orchestrating Spec Driven Development

For any non-trivial feature or bugfix request, do NOT start coding immediately. Run the pipeline:

1. Classify: feature or bugfix?
   - feature  -> requirements.md, design.md, tasks.md
   - bugfix   -> bugfix.md, design.md, tasks.md
2. Generate requirements.md (or bugfix.md) -> run Requirements Analysis -> request approval
3. Generate design.md -> request approval
4. Generate tasks.md -> build dependency DAG -> group into waves
5. Execute waves, running independent tasks concurrently
6. After each task: sync IDE diagnostics, self-correct, checkpoint state

If the request is trivial (single-line fix, typo, config tweak), skip the pipeline and just do it — but say so explicitly ("Skipping SDD pipeline: trivial change").

Phase 0 — Classify & Scaffold

• Determine artifact set: feature (requirements.md) vs bugfix (bugfix.md). Both pair with design.md + tasks.md.
• Create files under /specs/<feature-name>/ (or repo convention if a steering file specifies one).
• Load any /steering/*.md files first — they override default style/architecture assumptions silently and without re-prompting the user.

Phase 1 — Requirements Artifact

Write requirements.md with: user stories, acceptance criteria (EARS or Given/When/Then format), explicit non-goals, and constraints.

Run the Requirements Analysis Engine before moving on. Scan for:

• Logical contradictions — two criteria that cannot both be true simultaneously.
• Unstated assumptions — implied behavior never written down (e.g., "fast" with no threshold, auth assumed but not specified).
• Missing edge cases — empty states, concurrency, partial failure, boundary values, permission denial, network loss.

Output findings as a numbered list inline in the review, not buried in prose. Do not proceed to design until contradictions are resolved and gaps are either filled or explicitly deferred by the human reviewer.

Approval gate: present the spec for inline comment. Treat each unresolved comment as a blocker. Do not generate code until the human approves.

Phase 2 — Design Artifact

Write design.md: architecture, data models, interfaces/APIs, sequence of operations, failure modes, and testing strategy (including which requirements map to property-based tests vs. example-based unit tests).

Every design decision with more than one reasonable option gets flagged explicitly ("Decision: X vs Y — chose X because...") so the human can override at the approval gate.

Approval gate again before task breakdown.

Phase 3 — Tasks Artifact & DAG

Write tasks.md as atomic, independently-verifiable units of work. For each task, declare:

- id: T1
  description: ...
  depends_on: []
  touches: [files/paths]

Build a DAG from depends_on. Topologically sort into waves: wave N contains all tasks whose dependencies are fully satisfied by waves < N. Tasks within a wave are assumed parallel-safe — verify this by checking touches for file-level collisions; split a wave further if two tasks in it touch the same file.

Progress tracking:

Progress:
- [ ] Wave 1: T1, T3, T4 (parallel)
- [ ] Wave 2: T2 (depends on T1)
- [ ] Wave 3: T5, T6 (depends on T2, T3)

Phase 4 — Execution Loop (per task)

1. Implement against the approved design.
2. Generate property-based tests from spec invariants (not just the happy-path example in requirements.md) — prefer these over hand-picked unit tests for boundary logic, parsing, math, state machines.
3. Pull live diagnostics (compiler/linter/type-checker) from the workspace; treat any new error introduced by this task as a blocking self-correction loop — fix before marking task complete.
4. Record a checkpoint (state snapshot) after each task completes successfully, so the human can rewind to this exact point.
5. Mark task [x] in tasks.md progress checklist.

Phase 5 — Governance (applies throughout, not a separate phase)

• Before any file read/write or shell command: check .ignorefile (git-style ignore syntax) and permissions.yaml policy. If a path is ignored or a command isn't allowlisted, refuse and surface the restriction to the user instead of silently working around it.
• Fire event hooks at the defined lifecycle points: Prompt Submit, Pre-Tool Use, Post-Tool Use, Agent Stop. Hooks may run formatters, audit logs, or safety checks — never skip them to save time.
• Load Agent Skills / MCP-connected "Powers" on demand when a task needs domain-specific instructions or external data, rather than front-loading everything into context.

Example 1: Input: "Add rate limiting to the /api/upload endpoint" Output:

• Classified as feature → requirements.md drafted with criteria ("max N requests per IP per minute", "return 429 with Retry-After header")
• Requirements analysis flags: unstated assumption (is limit per-IP or per-API-key?), missing edge case (behavior during limiter backend outage)
• After human resolves ambiguities → design.md proposes token-bucket vs sliding-window, flags decision for approval
• tasks.md: T1 (middleware scaffold), T2 (storage backend, depends T1), T3 (tests, depends T1) → Wave 1: T1; Wave 2: T2, T3 parallel
• Property-based test generated: random burst request sequences verifying count never exceeds limit regardless of timing jitter

Example 2: Input: "Fix: users can submit empty forms" Output:

• Classified as bugfix → bugfix.md captures repro steps, root cause hypothesis, acceptance criteria for the fix
• Skips separate requirements analysis depth (bugfix is narrower) but still checks for missing edge cases: whitespace-only input, multi-field forms where only some fields are empty
• design.md is short: validation layer change + where it sits in the stack
• Single-task tasks.md, one wave, executed and checkpointed