Confirm successful installation by checking the skill directory location:
.cursor/skills/gsd-2-agent-framework
Restart Cursor to activate gsd-2-agent-framework. Access via /gsd-2-agent-framework in your agent's command palette.
β
Security Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your environment. Always review source, verify the publisher, and test in isolation before production.
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
npminstall-g gsd-pi
Requires Node.js 18+. Works with Claude (Anthropic) as the underlying model via the Pi SDK.
Core Concepts
Work Hierarchy
Milestone β a shippable version (4β10 slices)
Slice β one demoable vertical capability (1β7 tasks)
Task β one context-window-sized unit of work
Iron rule: A task must fit in one context window. If it can't, split it into two tasks.
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 auto
# or with options:/gsd auto --budget5.00# pause if cost exceeds $5/gsd auto --milestone M1 # run only milestone 1/gsd auto --dry-run # show dispatch plan without executing
/gsd init β Initialize a Project
Scaffold the .gsd/ directory from a ROADMAP.md and optional PROJECT.md.
/gsd init
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.
Execute one specific unit manually instead of running the full loop.
/gsd run --slice M1/S4 # run research + plan + execute for a slice/gsd run --task M1/S4/T2 # run a single task/gsd run --phase research M1/S4 # run just the research phase/gsd run --phase plan M1/S4 # run just the planning phase
/gsd migrate β Migrate from v1
Import old .planning/ directories from the original Get Shit Done.
/gsd migrate # migrate current directory/gsd migrate ~/projects/old-project # migrate specific path
# My Project Roadmap## Milestone 1: Core API### S1: Database schema and migrationsSet up Postgres schema for users, posts, and comments.
### S2: REST endpointsCRUD endpoints for all resources with validation.
### S3: AuthenticationJWT-based auth with refresh tokens.
## Milestone 2: Frontend### S1: React app scaffold...
2. Write PROJECT.md
# My ProjectA REST API for a blogging platform built with Express + TypeScript + Postgres.
## Tech Stack- Node.js 20, TypeScript 5
- Express 4
- PostgreSQL 15 via pg + kysely
- Jest for tests
## Conventions- All endpoints return `{ data, error }` envelope
- Database migrations in `db/migrations/`- Feature modules in `src/features/<name>/`
3. Initialize
/gsd init
4. Run
/gsd auto
The Auto-Mode State Machine
Research β Plan β Execute (per task) β Complete β Reassess β Next Slice
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
Every task plan includes must-haves β explicit, checkable criteria the LLM uses to confirm completion. Write them as shell commands or file existence checks:
## Must-Haves- [ ] `npm test -- --testPathPattern=auth` passes with 0 failures
- [ ] File `src/features/auth/jwt.ts` exists and exports `signToken`, `verifyToken`- [ ] `curl -X POST http://localhost:3000/auth/login` returns 200 with `{ data: { token } }`- [ ] No TypeScript errors: `npx tsc --noEmit` exits 0
The execute phase ends only when the LLM can check off every must-have.
Git Strategy
GSD manages git automatically in auto mode:
main
βββ milestone/M1 β worktree branch created at start
βββ commit: [M1/S1/T1] implement user model
βββ commit: [M1/S1/T2] add migrations
βββ commit: [M1/S1] slice complete
βββ commit: [M1/S2/T1] POST /users endpoint
βββ ...
After milestone complete:
main β squash merge of milestone/M1 as "[M1] Auth system"
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:
# Next run detects the lock and auto-recovers:/gsd auto
# Output:# β Lock file found: M1/S3/T2 was interrupted# Synthesizing recovery briefing from session artifacts...# Resuming with full context
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:
.gsd/DECISIONS.md is auto-injected into every task dispatch. Record architectural decisions here and the LLM will respect them across all future sessions:
# Decisions Register## D1: Use kysely not prisma**Date:** 2025-01-14
**Reason:** Better TypeScript inference, no code generation step needed.
**Impact:** All DB queries use kysely QueryBuilder syntax.
## D2: JWT in httpOnly cookie, not Authorization header**Date:** 2025-01-14
**Reason:** Better XSS protection for the web client.
**Impact:** Auth middleware reads `req.cookies.token`.
Stuck Detection
If the same unit dispatches twice without producing its expected artifact, GSD:
Retries once with a deep diagnostic prompt that includes what was expected vs. what exists on disk
If the second attempt fails, stops auto mode and reports:
β Stuck on M1/S3/T1 after 2 attempts
Expected: src/features/auth/jwt.ts (not found)
Last session: .gsd/sessions/M1-S3-T1-attempt2.log
Run `/gsd run --task M1/S3/T1` to retry manually
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.
βΊAccess to product documentation and roadmap tools (Jira, Notion, etc.)
βΊUnderstanding of product management frameworks (RICE, Jobs-to-be-Done, etc.)
βΊStakeholder contact information and communication channels
Time Estimate
30-60 minutes to see productivity improvements
Steps
1Install product management skill
2Start with user story generation for known feature
3Progress to competitive analysis: research 2-3 competitors
4Use for roadmap prioritization: apply RICE/ICE scoring
5Draft stakeholder communications and refine based on feedback
6Build template library for recurring PM tasks
7Share effective prompts with product team
Common Pitfalls
β Not validating competitive researchβverify facts before sharing
β Accepting user stories without involving engineering team
β Over-relying on frameworks without qualitative judgment
β Not customizing outputs to company culture and communication style
β Skipping stakeholder validation of generated requirements
Best Practices
β Do
+Validate research and competitive analysis with real data
+Collaborate with engineering when generating technical requirements
+Customize frameworks and templates to your company context
+Use skill for first drafts, refine with stakeholder input
+Document successful prompt patterns for PM tasks
+Combine AI efficiency with human judgment and intuition
β Don't
βDon't publish competitive analysis without fact-checking
βDon't finalize user stories without engineering review
βDon't make prioritization decisions solely on AI scoring
βDon't skip customer validation of generated requirements
βDon't ignore company-specific context and culture
π‘ Pro Tips
β Provide context: company goals, constraints, customer feedback
β Ask for alternatives: 'Show 3 ways to prioritize this roadmap'
β Request stakeholder-specific formatting: 'Executive summary vs. engineering spec'
β Use skill for 70% generation + 30% customization to company needs
When to Use This
β Use when
Use for user story writing, competitive research, roadmap prioritization, stakeholder communication, and PRD drafting. Best for reducing repetitive documentation and research work.
β Avoid when
Avoid for strategic product vision (requires deep customer empathy), pricing decisions (needs market and financial expertise), or when face-to-face customer discovery is more valuable than speed.
Learning Path
1Basic: user stories, feature specs, status updates