gsd-code-first 1.0.0

package/commands/gsd/iterate.md

@@ -0,0 +1,124 @@
+---
+name: gsd:iterate
+description: Run the full code-first iteration loop - extract tags, generate plan, approve, execute (Code-First fork)
+argument-hint: "[--non-interactive] [--verify] [--annotate]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Task
+  - Glob
+  - Grep
+---
+
+<objective>
+Orchestrates the complete code-first development loop. It extracts `@gsd-tags` from annotated code, spawns `gsd-code-planner` to generate a plan from `CODE-INVENTORY.md`, pauses for human approval of the plan, then spawns the appropriate executor to implement it.
+
+This is the flagship command of the gsd-code-first fork — the core value proposition that turns annotated code into executed plans in a single command.
+
+**Arguments:**
+- `--non-interactive` — skip the approval gate and auto-approve the generated plan (for CI/headless pipelines)
+- `--verify` — run `/gsd:verify-work` after the executor completes
+- `--annotate` — refresh `@gsd-tags` by re-running extract-tags after the executor completes
+
+**Error handling:** If any step fails, iterate stops immediately and reports the failure. No subsequent steps are executed after a failure.
+</objective>
+
+<context>
+$ARGUMENTS
+
+@.planning/PROJECT.md
+@.planning/REQUIREMENTS.md
+@.planning/ROADMAP.md
+</context>
+
+<process>
+
+## Step 1 — Show current mode and run extract-tags
+
+Read the current phase mode configuration via bash:
+```bash
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-get default_phase_mode
+```
+Display to the user: "Current mode: {mode}"
+
+Then run extract-tags to scan the codebase and produce an up-to-date CODE-INVENTORY.md:
+```bash
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" extract-tags --format md --output .planning/prototype/CODE-INVENTORY.md
+```
+
+If this command exits with a non-zero exit code, **STOP** and report:
+> "iterate failed at step 1: extract-tags error. Check that @gsd-tags exist in your codebase and the project is initialized."
+
+## Step 2 — Spawn gsd-code-planner
+
+Spawn the `gsd-code-planner` agent via the Task tool, passing `$ARGUMENTS` as context.
+
+The agent will:
+- Read `.planning/prototype/CODE-INVENTORY.md` (produced by step 1) as its primary planning input
+- Read `@gsd-todo` tags as the task backlog (each todo becomes one task)
+- Read `@gsd-context`, `@gsd-decision`, `@gsd-constraint`, and `@gsd-risk` tags for plan context
+- Produce a Markdown PLAN.md in `.planning/prototype/` following the GSD plan format
+
+Wait for `gsd-code-planner` to complete. If the agent fails or does not produce a plan file, **STOP** and report:
+> "iterate failed at step 2: code-planner error. The gsd-code-planner agent did not complete successfully."
+
+## Step 3 — Approval gate
+
+Check if `--non-interactive` is present in `$ARGUMENTS`.
+
+**If `--non-interactive` IS present:**
+Log: "Auto-approving plan (--non-interactive mode)." and proceed to step 4.
+
+**If `--non-interactive` is NOT present:**
+Read the generated plan from `.planning/prototype/` and present its full contents to the user. Then ask:
+
+> "Review the plan above. Approve execution? [yes/no]"
+
+Wait for the user's response. If the user responds with anything other than clear approval (`yes`, `y`, `approve`), **STOP** and report:
+> "iterate stopped: plan not approved. The plan has been saved to .planning/prototype/ -- you can edit it and re-run /gsd:iterate, or approve it manually."
+
+**IMPORTANT:** There is no code path that reaches step 4 without explicit approval or `--non-interactive`. The approval gate is mandatory.
+
+## Step 4 — Spawn executor
+
+Check if ARC mode is enabled via bash:
+```bash
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" config-get arc.enabled
+```
+
+- If the result is `true`: spawn `gsd-arc-executor` via the Task tool, passing the plan path from `.planning/prototype/` as context.
+- If the result is `false` or not set: spawn `gsd-executor` via the Task tool, passing the plan path from `.planning/prototype/` as context.
+
+Wait for the executor to complete. If the executor fails, **STOP** and report:
+> "iterate failed at step 4: executor error. Check the plan output and executor logs for details."
+
+## Step 5 — Post-execution flags
+
+Check `$ARGUMENTS` for optional post-execution flags:
+
+**If `--verify` is present:**
+Run `/gsd:verify-work` to validate the executed changes meet success criteria.
+
+**If `--annotate` is present:**
+Re-run extract-tags to refresh CODE-INVENTORY.md with any new or updated annotations added during execution:
+```bash
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" extract-tags --format md --output .planning/prototype/CODE-INVENTORY.md
+```
+
+## Step 6 — Show summary
+
+Display a completion summary to the user:
+
+```
+iterate complete.
+
+Steps completed: [list of steps 1-5 that ran]
+Plan path: .planning/prototype/[plan-filename]
+Executor: [gsd-arc-executor | gsd-executor]
+Verification: [ran | skipped]
+Re-annotation: [ran | skipped]
+```
+
+</process>

package/commands/gsd/join-discord.md

@@ -0,0 +1,18 @@
+---
+name: gsd:join-discord
+description: Join the GSD Discord community
+---
+
+<objective>
+Display the Discord invite link for the GSD community server.
+</objective>
+
+<output>
+# Join the GSD Discord
+
+Connect with other GSD users, get help, share what you're building, and stay updated.
+
+**Invite link:** https://discord.gg/gsd
+
+Click the link or paste it into your browser to join.
+</output>

package/commands/gsd/list-phase-assumptions.md

@@ -0,0 +1,46 @@
+---
+name: gsd:list-phase-assumptions
+description: Surface Claude's assumptions about a phase approach before planning
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+---
+
+<objective>
+Analyze a phase and present Claude's assumptions about technical approach, implementation order, scope boundaries, risk areas, and dependencies.
+
+Purpose: Help users see what Claude thinks BEFORE planning begins - enabling course correction early when assumptions are wrong.
+Output: Conversational output only (no file creation) - ends with "What do you think?" prompt
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/list-phase-assumptions.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+Project state and roadmap are loaded in-workflow using targeted reads.
+</context>
+
+<process>
+1. Validate phase number argument (error if missing or invalid)
+2. Check if phase exists in roadmap
+3. Follow list-phase-assumptions.md workflow:
+   - Analyze roadmap description
+   - Surface assumptions about: technical approach, implementation order, scope, risks, dependencies
+   - Present assumptions clearly
+   - Prompt "What do you think?"
+4. Gather feedback and offer next steps
+</process>
+
+<success_criteria>
+
+- Phase validated against roadmap
+- Assumptions surfaced across five areas
+- User prompted for feedback
+- User knows next steps (discuss context, plan phase, or correct assumptions)
+  </success_criteria>

package/commands/gsd/list-workspaces.md

@@ -0,0 +1,19 @@
+---
+name: gsd:list-workspaces
+description: List active GSD workspaces and their status
+allowed-tools:
+  - Bash
+  - Read
+---
+<objective>
+Scan `~/gsd-workspaces/` for workspace directories containing `WORKSPACE.md` manifests. Display a summary table with name, path, repo count, strategy, and GSD project status.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/list-workspaces.md
+@~/.claude/get-shit-done/references/ui-brand.md
+</execution_context>
+
+<process>
+Execute the list-workspaces workflow from @~/.claude/get-shit-done/workflows/list-workspaces.md end-to-end.
+</process>

package/commands/gsd/manager.md

@@ -0,0 +1,39 @@
+---
+name: gsd:manager
+description: Interactive command center for managing multiple phases from one terminal
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Task
+---
+<objective>
+Single-terminal command center for managing a milestone. Shows a dashboard of all phases with visual status indicators, recommends optimal next actions, and dispatches work — discuss runs inline, plan/execute run as background agents.
+
+Designed for power users who want to parallelize work across phases from one terminal: discuss a phase while another plans or executes in the background.
+
+**Creates/Updates:**
+- No files created directly — dispatches to existing GSD commands via Skill() and background Task agents.
+- Reads `.planning/STATE.md`, `.planning/ROADMAP.md`, phase directories for status.
+
+**After:** User exits when done managing, or all phases complete and milestone lifecycle is suggested.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/manager.md
+@~/.claude/get-shit-done/references/ui-brand.md
+</execution_context>
+
+<context>
+No arguments required. Requires an active milestone with ROADMAP.md and STATE.md.
+
+Project context, phase list, dependencies, and recommendations are resolved inside the workflow using `gsd-tools.cjs init manager`. No upfront context loading needed.
+</context>
+
+<process>
+Execute the manager workflow from @~/.claude/get-shit-done/workflows/manager.md end-to-end.
+Maintain the dashboard refresh loop until the user exits or all phases complete.
+</process>

package/commands/gsd/map-codebase.md

@@ -0,0 +1,71 @@
+---
+name: gsd:map-codebase
+description: Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents
+argument-hint: "[optional: specific area to map, e.g., 'api' or 'auth']"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+<objective>
+Analyze existing codebase using parallel gsd-codebase-mapper agents to produce structured codebase documents.
+
+Each mapper agent explores a focus area and **writes documents directly** to `.planning/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.
+
+Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/map-codebase.md
+</execution_context>
+
+<context>
+Focus area: $ARGUMENTS (optional - if provided, tells agents to focus on specific subsystem)
+
+**Load project state if exists:**
+Check for .planning/STATE.md - loads context if project already initialized
+
+**This command can run:**
+- Before /gsd:new-project (brownfield codebases) - creates codebase map first
+- After /gsd:new-project (greenfield codebases) - updates codebase map as code evolves
+- Anytime to refresh codebase understanding
+</context>
+
+<when_to_use>
+**Use map-codebase for:**
+- Brownfield projects before initialization (understand existing code first)
+- Refreshing codebase map after significant changes
+- Onboarding to an unfamiliar codebase
+- Before major refactoring (understand current state)
+- When STATE.md references outdated codebase info
+
+**Skip map-codebase for:**
+- Greenfield projects with no code yet (nothing to map)
+- Trivial codebases (<5 files)
+</when_to_use>
+
+<process>
+1. Check if .planning/codebase/ already exists (offer to refresh or skip)
+2. Create .planning/codebase/ directory structure
+3. Spawn 4 parallel gsd-codebase-mapper agents:
+   - Agent 1: tech focus → writes STACK.md, INTEGRATIONS.md
+   - Agent 2: arch focus → writes ARCHITECTURE.md, STRUCTURE.md
+   - Agent 3: quality focus → writes CONVENTIONS.md, TESTING.md
+   - Agent 4: concerns focus → writes CONCERNS.md
+4. Wait for agents to complete, collect confirmations (NOT document contents)
+5. Verify all 7 documents exist with line counts
+6. Commit codebase map
+7. Offer next steps (typically: /gsd:new-project or /gsd:plan-phase)
+</process>
+
+<success_criteria>
+- [ ] .planning/codebase/ directory created
+- [ ] All 7 codebase documents written by mapper agents
+- [ ] Documents follow template structure
+- [ ] Parallel agents completed without errors
+- [ ] User knows next steps
+</success_criteria>

package/commands/gsd/milestone-summary.md

@@ -0,0 +1,51 @@
+---
+type: prompt
+name: gsd:milestone-summary
+description: Generate a comprehensive project summary from milestone artifacts for team onboarding and review
+argument-hint: "[version]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+---
+
+<objective>
+Generate a structured milestone summary for team onboarding and project review. Reads completed milestone artifacts (ROADMAP, REQUIREMENTS, CONTEXT, SUMMARY, VERIFICATION files) and produces a human-friendly overview of what was built, how, and why.
+
+Purpose: Enable new team members to understand a completed project by reading one document and asking follow-up questions.
+Output: MILESTONE_SUMMARY written to `.planning/reports/`, presented inline, optional interactive Q&A.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/milestone-summary.md
+</execution_context>
+
+<context>
+**Project files:**
+- `.planning/ROADMAP.md`
+- `.planning/PROJECT.md`
+- `.planning/STATE.md`
+- `.planning/RETROSPECTIVE.md`
+- `.planning/milestones/v{version}-ROADMAP.md` (if archived)
+- `.planning/milestones/v{version}-REQUIREMENTS.md` (if archived)
+- `.planning/phases/*-*/` (SUMMARY.md, VERIFICATION.md, CONTEXT.md, RESEARCH.md)
+
+**User input:**
+- Version: $ARGUMENTS (optional — defaults to current/latest milestone)
+</context>
+
+<process>
+Read and execute the milestone-summary workflow from @~/.claude/get-shit-done/workflows/milestone-summary.md end-to-end.
+</process>
+
+<success_criteria>
+- Milestone version resolved (from args, STATE.md, or archive scan)
+- All available artifacts read (ROADMAP, REQUIREMENTS, CONTEXT, SUMMARY, VERIFICATION, RESEARCH, RETROSPECTIVE)
+- Summary document written to `.planning/reports/MILESTONE_SUMMARY-v{version}.md`
+- All 7 sections generated (Overview, Architecture, Phases, Decisions, Requirements, Tech Debt, Getting Started)
+- Summary presented inline to user
+- Interactive Q&A offered
+- STATE.md updated
+</success_criteria>

package/commands/gsd/new-milestone.md

@@ -0,0 +1,44 @@
+---
+name: gsd:new-milestone
+description: Start a new milestone cycle — update PROJECT.md and route to requirements
+argument-hint: "[milestone name, e.g., 'v1.1 Notifications']"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+<objective>
+Start a new milestone: questioning → research (optional) → requirements → roadmap.
+
+Brownfield equivalent of new-project. Project exists, PROJECT.md has history. Gathers "what's next", updates PROJECT.md, then runs requirements → roadmap cycle.
+
+**Creates/Updates:**
+- `.planning/PROJECT.md` — updated with new milestone goals
+- `.planning/research/` — domain research (optional, NEW features only)
+- `.planning/REQUIREMENTS.md` — scoped requirements for this milestone
+- `.planning/ROADMAP.md` — phase structure (continues numbering)
+- `.planning/STATE.md` — reset for new milestone
+
+**After:** `/gsd:plan-phase [N]` to start execution.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/new-milestone.md
+@~/.claude/get-shit-done/references/questioning.md
+@~/.claude/get-shit-done/references/ui-brand.md
+@~/.claude/get-shit-done/templates/project.md
+@~/.claude/get-shit-done/templates/requirements.md
+</execution_context>
+
+<context>
+Milestone name: $ARGUMENTS (optional - will prompt if not provided)
+
+Project and milestone context files are resolved inside the workflow (`init new-milestone`) and delegated via `<files_to_read>` blocks where subagents are used.
+</context>
+
+<process>
+Execute the new-milestone workflow from @~/.claude/get-shit-done/workflows/new-milestone.md end-to-end.
+Preserve all workflow gates (validation, questioning, research, requirements, roadmap approval, commits).
+</process>

package/commands/gsd/new-project.md

@@ -0,0 +1,42 @@
+---
+name: gsd:new-project
+description: Initialize a new project with deep context gathering and PROJECT.md
+argument-hint: "[--auto]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+  - AskUserQuestion
+---
+<context>
+**Flags:**
+- `--auto` — Automatic mode. After config questions, runs research → requirements → roadmap without further interaction. Expects idea document via @ reference.
+</context>
+
+<objective>
+Initialize a new project through unified flow: questioning → research (optional) → requirements → roadmap.
+
+**Creates:**
+- `.planning/PROJECT.md` — project context
+- `.planning/config.json` — workflow preferences
+- `.planning/research/` — domain research (optional)
+- `.planning/REQUIREMENTS.md` — scoped requirements
+- `.planning/ROADMAP.md` — phase structure
+- `.planning/STATE.md` — project memory
+
+**After this command:** Run `/gsd:plan-phase 1` to start execution.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/new-project.md
+@~/.claude/get-shit-done/references/questioning.md
+@~/.claude/get-shit-done/references/ui-brand.md
+@~/.claude/get-shit-done/templates/project.md
+@~/.claude/get-shit-done/templates/requirements.md
+</execution_context>
+
+<process>
+Execute the new-project workflow from @~/.claude/get-shit-done/workflows/new-project.md end-to-end.
+Preserve all workflow gates (validation, approvals, commits, routing).
+</process>

package/commands/gsd/new-workspace.md

@@ -0,0 +1,44 @@
+---
+name: gsd:new-workspace
+description: Create an isolated workspace with repo copies and independent .planning/
+argument-hint: "--name <name> [--repos repo1,repo2] [--path /target] [--strategy worktree|clone] [--branch name] [--auto]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - AskUserQuestion
+---
+<context>
+**Flags:**
+- `--name` (required) — Workspace name
+- `--repos` — Comma-separated repo paths or names. If omitted, interactive selection from child git repos in cwd
+- `--path` — Target directory. Defaults to `~/gsd-workspaces/<name>`
+- `--strategy` — `worktree` (default, lightweight) or `clone` (fully independent)
+- `--branch` — Branch to checkout. Defaults to `workspace/<name>`
+- `--auto` — Skip interactive questions, use defaults
+</context>
+
+<objective>
+Create a physical workspace directory containing copies of specified git repos (as worktrees or clones) with an independent `.planning/` directory for isolated GSD sessions.
+
+**Use cases:**
+- Multi-repo orchestration: work on a subset of repos in parallel with isolated GSD state
+- Feature branch isolation: create a worktree of the current repo with its own `.planning/`
+
+**Creates:**
+- `<path>/WORKSPACE.md` — workspace manifest
+- `<path>/.planning/` — independent planning directory
+- `<path>/<repo>/` — git worktree or clone for each specified repo
+
+**After this command:** `cd` into the workspace and run `/gsd:new-project` to initialize GSD.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/new-workspace.md
+@~/.claude/get-shit-done/references/ui-brand.md
+</execution_context>
+
+<process>
+Execute the new-workspace workflow from @~/.claude/get-shit-done/workflows/new-workspace.md end-to-end.
+Preserve all workflow gates (validation, approvals, commits, routing).
+</process>

package/commands/gsd/next.md

@@ -0,0 +1,24 @@
+---
+name: gsd:next
+description: Automatically advance to the next logical step in the GSD workflow
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - SlashCommand
+---
+<objective>
+Detect the current project state and automatically invoke the next logical GSD workflow step.
+No arguments needed — reads STATE.md, ROADMAP.md, and phase directories to determine what comes next.
+
+Designed for rapid multi-project workflows where remembering which phase/step you're on is overhead.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/next.md
+</execution_context>
+
+<process>
+Execute the next workflow from @~/.claude/get-shit-done/workflows/next.md end-to-end.
+</process>

package/commands/gsd/note.md

@@ -0,0 +1,34 @@
+---
+name: gsd:note
+description: Zero-friction idea capture. Append, list, or promote notes to todos.
+argument-hint: "<text> | list | promote <N> [--global]"
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+---
+<objective>
+Zero-friction idea capture — one Write call, one confirmation line.
+
+Three subcommands:
+- **append** (default): Save a timestamped note file. No questions, no formatting.
+- **list**: Show all notes from project and global scopes.
+- **promote**: Convert a note into a structured todo.
+
+Runs inline — no Task, no AskUserQuestion, no Bash.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/note.md
+@~/.claude/get-shit-done/references/ui-brand.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+Execute the note workflow from @~/.claude/get-shit-done/workflows/note.md end-to-end.
+Capture the note, list notes, or promote to todo — depending on arguments.
+</process>

package/commands/gsd/pause-work.md

@@ -0,0 +1,38 @@
+---
+name: gsd:pause-work
+description: Create context handoff when pausing work mid-phase
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Create `.continue-here.md` handoff file to preserve complete work state across sessions.
+
+Routes to the pause-work workflow which handles:
+- Current phase detection from recent files
+- Complete state gathering (position, completed work, remaining work, decisions, blockers)
+- Handoff file creation with all context sections
+- Git commit as WIP
+- Resume instructions
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/pause-work.md
+</execution_context>
+
+<context>
+State and phase progress are gathered in-workflow with targeted reads.
+</context>
+
+<process>
+**Follow the pause-work workflow** from `@~/.claude/get-shit-done/workflows/pause-work.md`.
+
+The workflow handles all logic including:
+1. Phase directory detection
+2. State gathering with user clarifications
+3. Handoff file writing with timestamp
+4. Git commit
+5. Confirmation with resume instructions
+</process>

package/commands/gsd/plan-milestone-gaps.md

@@ -0,0 +1,34 @@
+---
+name: gsd:plan-milestone-gaps
+description: Create phases to close all gaps identified by milestone audit
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<objective>
+Create all phases necessary to close gaps identified by `/gsd:audit-milestone`.
+
+Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase.
+
+One command creates all fix phases — no manual `/gsd:add-phase` per gap.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/plan-milestone-gaps.md
+</execution_context>
+
+<context>
+**Audit results:**
+Glob: .planning/v*-MILESTONE-AUDIT.md (use most recent)
+
+Original intent and current planning state are loaded on demand inside the workflow.
+</context>
+
+<process>
+Execute the plan-milestone-gaps workflow from @~/.claude/get-shit-done/workflows/plan-milestone-gaps.md end-to-end.
+Preserve all workflow gates (audit loading, prioritization, phase grouping, user confirmation, roadmap updates).
+</process>