declare-cc 0.1.0

package/commands/declare/actions.md

@@ -0,0 +1,78 @@
+---
+description: Derive action plans per milestone
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+argument-hint: "[M-XX]"
+---
+
+Derive action plans for milestones by working backward from what must be done.
+
+**Step 1: Load current graph state.**
+
+```bash
+node /Users/guilherme/Projects/get-shit-done/dist/declare-tools.cjs load-graph
+```
+
+Parse the JSON output. If the output contains an `error` field, tell the user to run `/declare:init` first and stop.
+
+If no milestones exist in the graph, tell the user to run `/declare:milestones` first and stop.
+
+Note all milestones and their current plan status from the graph.
+
+**Step 2: Determine scope.**
+
+- If `$ARGUMENTS` contains a milestone ID (e.g., `M-01`), derive only for that milestone.
+- Otherwise, derive for all milestones that don't have a plan yet (milestones where `hasPlan` is false or no PLAN.md folder exists).
+
+If all milestones already have plans and no specific milestone was requested, tell the user: "All milestones already have action plans. Run `/declare:status` to see coverage."
+
+**Step 3: Follow the action derivation workflow.**
+
+Read and follow the full workflow instructions:
+
+@/Users/guilherme/Projects/get-shit-done/workflows/actions.md
+
+Pass the loaded graph state into the workflow so it knows about existing milestones and actions.
+
+**Step 4: For each milestone, derive and present plan for approval.**
+
+The workflow derives actions for each milestone. After derivation, present the complete plan and ask for approval using AskUserQuestion:
+
+```
+Use AskUserQuestion to ask the user to approve the derived plan for each milestone.
+
+Proposed plan for M-XX "[milestone title]":
+- A-XX: [action title] -- produces [what]
+- A-XX: [action title] -- produces [what]
+
+Approve this plan? (yes/adjust/skip)
+```
+
+If the user wants adjustments, adjust and re-present. If they skip, move to the next milestone.
+
+**Step 5: Persist each approved plan.**
+
+For each approved plan, call create-plan:
+
+```bash
+node /Users/guilherme/Projects/get-shit-done/dist/declare-tools.cjs create-plan --milestone "M-XX" --actions '[{"title":"Action Title","produces":"what it creates"}]'
+```
+
+Parse the JSON output to confirm the plan was created.
+
+**Step 6: Show summary and suggest next step.**
+
+After all milestones processed:
+
+1. Reload the graph to get final counts:
+```bash
+node /Users/guilherme/Projects/get-shit-done/dist/declare-tools.cjs load-graph
+```
+
+2. Show summary: milestones processed, plans created, total actions derived.
+3. Suggest: "Run `/declare:status` to see coverage and health."

package/commands/declare/future.md

@@ -0,0 +1,52 @@
+---
+description: Declare futures through guided conversation
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+argument-hint: "[--add]"
+---
+
+Guide the user through declaring their project's future as present-tense truth statements.
+
+**Step 1: Load current graph state.**
+
+```bash
+node /Users/guilherme/Projects/get-shit-done/dist/declare-tools.cjs load-graph
+```
+
+Parse the JSON output. If the output contains an `error` field (e.g., "No Declare project found"), tell the user to run `/declare:init` first and stop.
+
+Note the existing declarations from the graph (if any) -- the workflow needs this context.
+
+**Step 2: Determine mode.**
+
+- If `$ARGUMENTS` contains `--add`, skip the intro and go directly to the per-declaration loop (adding to existing declarations).
+- If the graph already has declarations and `--add` is NOT present, show existing declarations and ask: "Would you like to add to these, or start fresh?"
+
+**Step 3: Follow the declaration capture workflow.**
+
+Read and follow the full workflow instructions:
+
+@/Users/guilherme/Projects/get-shit-done/workflows/future.md
+
+Pass the loaded graph state into the workflow so it knows about existing declarations.
+
+**Step 4: Persist each confirmed declaration.**
+
+After each declaration passes language detection and NSR validation and the user confirms it, persist it:
+
+```bash
+node /Users/guilherme/Projects/get-shit-done/dist/declare-tools.cjs add-declaration --title "Short Title" --statement "Full present-tense declaration statement"
+```
+
+Parse the JSON output to confirm the declaration was created and note its assigned ID (e.g., D-01).
+
+**Step 5: Show summary and suggest next step.**
+
+After all declarations are captured:
+
+1. List all declarations with their IDs and statements.
+2. Suggest: "Run `/declare:milestones` to work backward from these declarations to milestones and actions."

package/commands/declare/milestones.md

@@ -0,0 +1,81 @@
+---
+description: Derive milestones backward from declared futures
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+argument-hint: "[D-XX]"
+---
+
+Derive milestones by working backward from declared futures.
+
+**Step 1: Load current graph state.**
+
+```bash
+node /Users/guilherme/Projects/get-shit-done/dist/declare-tools.cjs load-graph
+```
+
+Parse the JSON output. If the output contains an `error` field, tell the user to run `/declare:init` first and stop.
+
+If no declarations exist in the graph, tell the user to run `/declare:future` first and stop.
+
+Note all declarations and milestones from the graph -- the workflow needs full context.
+
+**Step 2: Determine scope.**
+
+- If `$ARGUMENTS` contains a declaration ID (e.g., `D-01`), derive only for that specific declaration.
+- Otherwise, derive for all declarations that have no milestones yet (declarations with empty milestones arrays in the graph).
+
+**Step 3: Follow the milestone derivation workflow.**
+
+Read and follow the full workflow instructions:
+
+@/Users/guilherme/Projects/get-shit-done/workflows/milestones.md
+
+Pass the loaded graph state into the workflow so it knows about existing declarations and milestones.
+
+**Step 4: Per-declaration milestone confirmation with checkboxes.**
+
+After the workflow proposes milestones for a declaration, present them using AskUserQuestion with multi-select checkboxes:
+
+```
+Use AskUserQuestion to present proposed milestones as a checklist. The user checks which milestones to accept. Format:
+
+Which of these milestones should we create for D-XX?
+- [ ] Milestone A -- because [reason]
+- [ ] Milestone B -- because [reason]
+- [ ] Milestone C -- because [reason]
+```
+
+**Step 5: Persist each accepted milestone.**
+
+For each checked milestone:
+
+```bash
+node /Users/guilherme/Projects/get-shit-done/dist/declare-tools.cjs add-milestone --title "Milestone Title" --realizes "D-XX"
+```
+
+Parse the JSON output to confirm the milestone was created and note its assigned ID.
+
+**Step 6: Inconsistency flagging.**
+
+If milestones already exist for a declaration being processed (re-derivation case):
+- Show existing milestones for that declaration
+- Ask the user if they still align with the declaration
+- Offer to keep, re-derive, or adjust
+- Do NOT auto-reconcile -- the user decides what to update
+
+**Step 7: Show summary and suggest next step.**
+
+After all declarations processed:
+
+1. Reload the graph to get final counts:
+```bash
+node /Users/guilherme/Projects/get-shit-done/dist/declare-tools.cjs load-graph
+```
+
+2. Show summary: declarations processed, milestones derived.
+3. Suggest: "Run `/declare:actions` to derive action plans for each milestone."

package/commands/declare/status.md

@@ -0,0 +1,62 @@
+---
+description: Show graph state, layer counts, health indicators, and last activity
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+---
+
+Show the current state of the Declare project graph.
+
+**Step 1: Run the status tool.**
+
+```bash
+node /Users/guilherme/Projects/get-shit-done/dist/declare-tools.cjs status
+```
+
+Parse the JSON output.
+
+**Step 2: Handle errors.**
+
+If the output contains an `error` field (e.g., "No Declare project found"), display the error and suggest running `/declare:init`.
+
+**Step 3: Format the status display.**
+
+Render a rich visual summary with these sections:
+
+**Project header:** Display the project name prominently.
+
+**Graph Stats:** Show counts in a compact format:
+- Declarations: N
+- Milestones: N
+- Actions: N
+- Edges: N
+
+**Status Distribution:** Show the breakdown by status (PENDING/ACTIVE/DONE) as a visual bar or counts.
+
+**Validation Health:**
+- If `health` is "healthy": show a pass indicator
+- If `health` is "warnings": show warnings with the validation error list
+- If `health` is "errors": show errors with the validation error list and actionable suggestions for each
+
+For each validation error, provide a brief suggestion:
+- `orphan`: "Connect this node to a parent with an edge"
+- `cycle`: "Check for circular dependencies in your graph"
+- `broken_edge`: "The target node may have been removed -- update or remove the edge"
+
+**Coverage:** Show milestone plan coverage from the `coverage` field:
+- "Plan coverage: X of Y milestones have plans (Z%)"
+- If coverage is less than 100%, list milestones without plans and suggest: "Run `/declare:actions` to derive plans for uncovered milestones."
+
+**Health Indicators:** If `staleness` indicators exist, render them:
+- NO_PLAN: "[M-XX] has no action plan"
+- STALE: "[M-XX] plan not updated in N days"
+- COMPLETABLE: "[M-XX] all actions done -- consider marking milestone as DONE"
+- INCONSISTENT: "[M-XX] marked DONE but has incomplete actions"
+
+If no staleness indicators: "All milestones healthy."
+
+**Last Activity:** Show the timestamp and commit message from the last git activity.
+
+The overall feel should be like a dashboard -- compact, scannable, with clear health indicators.

package/commands/gsd/add-phase.md

@@ -0,0 +1,39 @@
+---
+name: gsd:add-phase
+description: Add phase to end of current milestone in roadmap
+argument-hint: <description>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Add a new integer phase to the end of the current milestone in the roadmap.
+
+Routes to the add-phase workflow which handles:
+- Phase number calculation (next sequential integer)
+- Directory creation with slug generation
+- Roadmap structure updates
+- STATE.md roadmap evolution tracking
+</objective>
+
+<execution_context>
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@~/.claude/get-shit-done/workflows/add-phase.md
+</execution_context>
+
+<process>
+**Follow the add-phase workflow** from `@~/.claude/get-shit-done/workflows/add-phase.md`.
+
+The workflow handles all logic including:
+1. Argument parsing and validation
+2. Roadmap existence checking
+3. Current milestone identification
+4. Next phase number calculation (ignoring decimals)
+5. Slug generation from description
+6. Phase directory creation
+7. Roadmap entry insertion
+8. STATE.md updates
+</process>

package/commands/gsd/add-todo.md

@@ -0,0 +1,42 @@
+---
+name: gsd:add-todo
+description: Capture idea or task as todo from current conversation context
+argument-hint: [optional description]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Capture an idea, task, or issue that surfaces during a GSD session as a structured todo for later work.
+
+Routes to the add-todo workflow which handles:
+- Directory structure creation
+- Content extraction from arguments or conversation
+- Area inference from file paths
+- Duplicate detection and resolution
+- Todo file creation with frontmatter
+- STATE.md updates
+- Git commits
+</objective>
+
+<execution_context>
+@.planning/STATE.md
+@~/.claude/get-shit-done/workflows/add-todo.md
+</execution_context>
+
+<process>
+**Follow the add-todo workflow** from `@~/.claude/get-shit-done/workflows/add-todo.md`.
+
+The workflow handles all logic including:
+1. Directory ensuring
+2. Existing area checking
+3. Content extraction (arguments or conversation)
+4. Area inference
+5. Duplicate checking
+6. File creation with slug generation
+7. STATE.md updates
+8. Git commits
+</process>

package/commands/gsd/audit-milestone.md

@@ -0,0 +1,42 @@
+---
+name: gsd:audit-milestone
+description: Audit milestone completion against original intent before archiving
+argument-hint: "[version]"
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - Write
+---
+<objective>
+Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.
+
+**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/audit-milestone.md
+</execution_context>
+
+<context>
+Version: $ARGUMENTS (optional — defaults to current milestone)
+
+**Original Intent:**
+@.planning/PROJECT.md
+@.planning/REQUIREMENTS.md
+
+**Planned Work:**
+@.planning/ROADMAP.md
+@.planning/config.json (if exists)
+
+**Completed Work:**
+Glob: .planning/phases/*/*-SUMMARY.md
+Glob: .planning/phases/*/*-VERIFICATION.md
+</context>
+
+<process>
+Execute the audit-milestone workflow from @~/.claude/get-shit-done/workflows/audit-milestone.md end-to-end.
+Preserve all workflow gates (scope determination, verification reading, integration check, requirements coverage, routing).
+</process>

package/commands/gsd/check-todos.md

@@ -0,0 +1,41 @@
+---
+name: gsd:check-todos
+description: List pending todos and select one to work on
+argument-hint: [area filter]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action.
+
+Routes to the check-todos workflow which handles:
+- Todo counting and listing with area filtering
+- Interactive selection with full context loading
+- Roadmap correlation checking
+- Action routing (work now, add to phase, brainstorm, create phase)
+- STATE.md updates and git commits
+</objective>
+
+<execution_context>
+@.planning/STATE.md
+@.planning/ROADMAP.md
+@~/.claude/get-shit-done/workflows/check-todos.md
+</execution_context>
+
+<process>
+**Follow the check-todos workflow** from `@~/.claude/get-shit-done/workflows/check-todos.md`.
+
+The workflow handles all logic including:
+1. Todo existence checking
+2. Area filtering
+3. Interactive listing and selection
+4. Full context loading with file summaries
+5. Roadmap correlation checking
+6. Action offering and execution
+7. STATE.md updates
+8. Git commits
+</process>

package/commands/gsd/cleanup.md

@@ -0,0 +1,18 @@
+---
+name: gsd:cleanup
+description: Archive accumulated phase directories from completed milestones
+---
+<objective>
+Archive phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`.
+
+Use when `.planning/phases/` has accumulated directories from past milestones.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/cleanup.md
+</execution_context>
+
+<process>
+Follow the cleanup workflow at @~/.claude/get-shit-done/workflows/cleanup.md.
+Identify completed milestones, show a dry-run summary, and archive on confirmation.
+</process>

package/commands/gsd/complete-milestone.md

@@ -0,0 +1,136 @@
+---
+type: prompt
+name: gsd:complete-milestone
+description: Archive completed milestone and prepare for next version
+argument-hint: <version>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md and REQUIREMENTS.md.
+
+Purpose: Create historical record of shipped version, archive milestone artifacts (roadmap + requirements), and prepare for next milestone.
+Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tagged.
+</objective>
+
+<execution_context>
+**Load these files NOW (before proceeding):**
+
+- @~/.claude/get-shit-done/workflows/complete-milestone.md (main workflow)
+- @~/.claude/get-shit-done/templates/milestone-archive.md (archive template)
+  </execution_context>
+
+<context>
+**Project files:**
+- `.planning/ROADMAP.md`
+- `.planning/REQUIREMENTS.md`
+- `.planning/STATE.md`
+- `.planning/PROJECT.md`
+
+**User input:**
+
+- Version: {{version}} (e.g., "1.0", "1.1", "2.0")
+  </context>
+
+<process>
+
+**Follow complete-milestone.md workflow:**
+
+0. **Check for audit:**
+
+   - Look for `.planning/v{{version}}-MILESTONE-AUDIT.md`
+   - If missing or stale: recommend `/gsd:audit-milestone` first
+   - If audit status is `gaps_found`: recommend `/gsd:plan-milestone-gaps` first
+   - If audit status is `passed`: proceed to step 1
+
+   ```markdown
+   ## Pre-flight Check
+
+   {If no v{{version}}-MILESTONE-AUDIT.md:}
+   ⚠ No milestone audit found. Run `/gsd:audit-milestone` first to verify
+   requirements coverage, cross-phase integration, and E2E flows.
+
+   {If audit has gaps:}
+   ⚠ Milestone audit found gaps. Run `/gsd:plan-milestone-gaps` to create
+   phases that close the gaps, or proceed anyway to accept as tech debt.
+
+   {If audit passed:}
+   ✓ Milestone audit passed. Proceeding with completion.
+   ```
+
+1. **Verify readiness:**
+
+   - Check all phases in milestone have completed plans (SUMMARY.md exists)
+   - Present milestone scope and stats
+   - Wait for confirmation
+
+2. **Gather stats:**
+
+   - Count phases, plans, tasks
+   - Calculate git range, file changes, LOC
+   - Extract timeline from git log
+   - Present summary, confirm
+
+3. **Extract accomplishments:**
+
+   - Read all phase SUMMARY.md files in milestone range
+   - Extract 4-6 key accomplishments
+   - Present for approval
+
+4. **Archive milestone:**
+
+   - Create `.planning/milestones/v{{version}}-ROADMAP.md`
+   - Extract full phase details from ROADMAP.md
+   - Fill milestone-archive.md template
+   - Update ROADMAP.md to one-line summary with link
+
+5. **Archive requirements:**
+
+   - Create `.planning/milestones/v{{version}}-REQUIREMENTS.md`
+   - Mark all v1 requirements as complete (checkboxes checked)
+   - Note requirement outcomes (validated, adjusted, dropped)
+   - Delete `.planning/REQUIREMENTS.md` (fresh one created for next milestone)
+
+6. **Update PROJECT.md:**
+
+   - Add "Current State" section with shipped version
+   - Add "Next Milestone Goals" section
+   - Archive previous content in `<details>` (if v1.1+)
+
+7. **Commit and tag:**
+
+   - Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, archive files
+   - Commit: `chore: archive v{{version}} milestone`
+   - Tag: `git tag -a v{{version}} -m "[milestone summary]"`
+   - Ask about pushing tag
+
+8. **Offer next steps:**
+   - `/gsd:new-milestone` — start next milestone (questioning → research → requirements → roadmap)
+
+</process>
+
+<success_criteria>
+
+- Milestone archived to `.planning/milestones/v{{version}}-ROADMAP.md`
+- Requirements archived to `.planning/milestones/v{{version}}-REQUIREMENTS.md`
+- `.planning/REQUIREMENTS.md` deleted (fresh for next milestone)
+- ROADMAP.md collapsed to one-line entry
+- PROJECT.md updated with current state
+- Git tag v{{version}} created
+- Commit successful
+- User knows next steps (including need for fresh requirements)
+  </success_criteria>
+
+<critical_rules>
+
+- **Load workflow first:** Read complete-milestone.md before executing
+- **Verify completion:** All phases must have SUMMARY.md files
+- **User confirmation:** Wait for approval at verification gates
+- **Archive before deleting:** Always create archive files before updating/deleting originals
+- **One-line summary:** Collapsed milestone in ROADMAP.md should be single line with link
+- **Context efficiency:** Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone
+- **Fresh requirements:** Next milestone starts with `/gsd:new-milestone` which includes requirements definition
+  </critical_rules>