GSD 2 — Autonomous Spec Driven Agent Framework Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection GSD 2 is a standalone CLI that turns a structured spec into running software autonomously. It controls the agent harness directly — managing fresh context windows per task, git worktree isolation, crash recovery, cost tracking, and stuck detection — rather than relying on LLM self loops. One command, walk away, come back to a built project with clean git history. Installation Requires Node.js 18+. Works with Claude (Anthropic) as the underlying model via the Pi SDK. Core Concepts Work Hierarchy Iron rule: A task must fit in one context window. If it can't, split it into two tasks. Directory Layout Commands /gsd auto — Primary Autonomous Mode Run the full automation loop. Reads .gsd/STATE.md , dispatches each unit in a fresh session, handles recovery, and advances through the entire milestone without intervention. /gsd init — Initialize a Project Scaffold the .gsd/ directory from a ROADMAP.md and optional PROJECT.md . Creates initial STATE.md , registers milestones and slices from your roadmap, sets up the cost ledger. /gsd status — Dashboard Shows current position, per slice costs, token usage, and what's queued next. Output example: /gsd run — Single Unit Dispatch Execute one specific unit manually instead of running the full loop. /gsd migrate — Migrate from v1 Import old .planning/ directories from the original Get Shit Done. /gsd costs — Cost Report Detailed cost breakdown with projections. Project Setup 1. Write ROADMAP.md 2. Write PROJECT.md 3. Initialize 4. Run The Auto Mode State Machine Each phase runs in a fresh session with context pre inlined into the dispatch prompt: Phase What the LLM receives What it produces Research PROJECT.md, ROADMAP.md, slice description, codebase index RESEARCH.md with findings, gotchas, relevant files Plan Research output, slice description, must haves PLAN.md with task breakdown, verification steps Execute (task N) Task plan, prior task summaries, dependency summaries, DECISIONS.md Working code committed to git Complete All task summaries, slice plan SUMMARY.md, UAT script, updated ROADMAP.md Reassess Completed slice summary, full ROADMAP.md Updated roadmap with any corrections Must Haves: Mechanically Verifiable Outcomes Every task plan includes must haves — explicit, checkable criteria the LLM uses to confirm completion. Write them as shell commands or file existence checks: The execute phase ends only when the LLM can check off every must have. Git Strategy GSD manages git automatically in auto mode: Each task commits with a structured message. Each slice commits a summary commit. The milestone squash merges to main as one clean entry. Crash Recovery GSD writes a lock file at .gsd/LOCK when a unit starts and removes it on clean completion. If the process dies: The recovery briefing is synthesized from every tool call that reached disk — file writes, shell output, partial completions — so the resumed session has context continuity. Cost Controls Set a budget ceiling to pause auto mode before overspending: The cost ledger at .gsd/costs/ledger.json : Decisions Register .gsd/DECISIONS.md is auto injected into every task dispatch. Record architectural decisions here and the LLM will respect them across all future sessions: Stuck Detection If the same unit dispatches twice without producing its expected artifact, GSD: 1. Retries once with a deep diagnostic prompt that includes what was expected vs. what exists on disk 2. If the second attempt fails, stops auto mode and reports: Skills Integration GSD supports auto detecting and installing relevant skills during the research phase. Create SKILLS.md in your project: Skills are injected into the research and plan dispatch prompts, giving the LLM curated knowledge about your exact stack without burning context on irrelevant docs. Timeout Supervision Three timeout tiers prevent runaway sessions: Timeout Default Behavior Soft 8 min Sends "please wrap up" steering message Idle 3 min no tool calls Sends "are you stuck?" recovery prompt Hard 15 min Pauses auto mode, preserves all disk state Configure in .gsd/config.json : TypeScript Integration (Pi SDK) GSD is built on the [Pi SDK](https://github.com/badlogic/pi mono). You can extend it programmatically: Custom Dispatch Hooks Inject custom context into any dispatch prompt: Register in .gsd/config.json : Roadmap Reassessment After each slice completes, GSD runs a reassessment pass that may: Re order upcoming slices based on discovered dependencies Split a slice that turned out larger than expected Mark a slice as no longer needed Add a new slice for discovered work The LLM edits ROADMAP.md in place. You can review diffs with: To disable reassessment: Troubleshooting Auto mode stops immediately with "no pending slices" All slices in ROADMAP.md are marked [x] . Reset a slice: remove [x] from its entry and delete .gsd/milestones/M1/slices/S3/SUMMARY.md . LLM keeps failing must haves Check .gsd/sessions/ for the last session log. Common causes: must have references wrong file path, or test command needs environment variable. Adjust must haves in the task's PLAN.md and re run with /gsd run task M1/S3/T2 . Cost ceiling hit unexpectedly The research phase on large codebases can be expensive. Set researchModel to a cheaper model in config, or reduce codebase index depth. Lock file left after clean exit Git worktree conflicts Session file too large for recovery If .gsd/sessions/ grows large, GSD compresses sessions older than 24h automatically. Manual cleanup: Links [GitHub: gsd build/GSD 2](https://github.com/gsd build/GSD 2) [npm: gsd pi](https://www.npmjs.com/package/gsd pi) [Pi SDK](https://github.com/badlogic/pi mono) [Original GSD v1](https://github.com/gsd build/get shit done)

gsd-2-agent-framework