Problem

Power users who adopt a spec-driven, phased development methodology (map → discuss → plan → execute → verify → ship → milestone) must maintain a separate tool chain — GSD (gsd-build/get-shit-done, MIT, npm) — alongside Archon. Every GSD invocation happens outside Archon, so platform routing, isolation, run history, SSE streaming, and approval gates are unavailable. Developers using Archon for AI-assisted work hit this gap every time their project requires structured spec work, which for practitioners of this methodology is on every non-trivial feature or bug fix.

Proposed Solution

Port GSD's 9 core-loop commands to Archon YAML workflows, shipping them as opt-in examples under .archon/workflows/experimental/gsd/. This mirrors the existing experimental/ pattern (e.g. fit-issue-creator.yaml) and gates promotion to bundled defaults on real-world exercise — avoiding pushing 9 new workflows in front of every Archon user on day one.

Design decisions (not open — all resolved):

• State persistence: .planning/ in-repo, tracked in git. Per-run $ARTIFACTS_DIR breaks cross-milestone accumulation; .archon/state/ is gitignored and drops the spec/plan trail from PRs. Add .planning/.gitignore to exclude scratch files (FALLOW.json, in-progress REVIEW.md).
• Execute-phase parallelism: loop: node with fresh_context: true, one task per iteration. Static fan-out requires runtime YAML emission (a bash node materializing YAML at runtime) which Archon doesn't natively support. Slower wall-clock but identical context hygiene to GSD's parallel waves; matches the existing archon-piv-loop pattern.
• Provider default: claude (matches upstream GSD's posture; unlocks skills:, agents:, hooks: per-node). Swapping to provider: pi for cross-runtime operation documented as a one-line config change.

User Flow

Before (current)

[!] npm install -g gsd-build/get-shit-done    (separate install, separate tool)
[!] gsd map-codebase                           (runs outside Archon — no run history)
[!] gsd discuss-phase "Add auth"               (no approval gates, no SSE streaming)
[!] gsd plan-phase                             (no isolation, no per-node tool restrictions)
[!] gsd execute-phase                          (parallel waves need separate npm orchestration)
[!] gsd verify-work                            (no Archon observability)
[!] gsd ship                                   (manual PR steps, no Archon workflow run record)
[!] .planning/ state managed manually — survives milestones but lives outside Archon's view

After (proposed)

[+] No separate install — workflows auto-discovered from .archon/workflows/experimental/gsd/
[+] archon workflow run gsd-map-codebase "describe repo"
[+] archon workflow run gsd-discuss-phase "Add auth"
[+] archon workflow run gsd-plan-phase          (approval gate pauses for human review; comment captured via capture_response)
[+] archon workflow run gsd-execute-phase       (fresh-context loop, one task per iteration)
[+] archon workflow run gsd-verify-work         (runs in isolation worktree)
[+] archon workflow run gsd-ship                (PR creation + merge via DAG nodes)
[+] .planning/ committed to git — spec/plan trail survives across milestones and appears in PRs
[+] .planning/.gitignore excludes scratch files (FALLOW.json, in-progress REVIEW.md)
[+] Full Archon observability: run history, per-node streaming, tool restrictions, approval gates
[+] provider: pi swap documented as one-line config override for cross-runtime users

Alternatives Considered

Scope

• Package(s) likely affected: workflows (YAML + command files; bundled-defaults generation if/when promoted to defaults), cli (no code changes — workflows auto-discovered)
• Breaking change? No
• Database changes needed? No
• New external dependencies? No

Security Considerations

• New permissions/capabilities? No — workflows execute under existing provider permissions
• New external network calls? No
• Secrets/tokens handling? No

Definition of Done

• 9 workflow YAML files created under .archon/workflows/experimental/gsd/ (gsd-map-codebase, gsd-new-project, gsd-discuss-phase, gsd-plan-phase, gsd-execute-phase, gsd-verify-work, gsd-ship, gsd-complete-milestone, gsd-new-milestone)
• Command files or inline prompt: nodes covering GSD's 33 subagent prompts (deduplicated where prompts are shared across phases)
• .planning/.gitignore committed, excluding FALLOW.json and in-progress scratch files
• gsd-execute-phase uses a loop: node with fresh_context: true; one task per iteration
• All 9 workflows pass bun run cli validate workflows with zero errors
• provider: claude set as default; provider: pi one-line override documented in workflow header comments
• At least one full map-codebase → discuss → plan → execute → verify → ship cycle run against a real or sample codebase
• bun run validate passes (type-check, lint, format, tests, bundled-check)
• Promotion criteria documented in a comment or follow-up issue (e.g. "move to bundled defaults after N verified real-world cycles")