declare-cc 0.2.0 → 0.3.0

package/commands/declare/check-todos.md

@@ -0,0 +1,125 @@
+---
+description: List pending todos and select one to work on or route to a milestone
+argument-hint: ""
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Task
+---
+
+List all pending todos, let the user select one, and offer to act on it now or plan it into the next milestone.
+
+**Step 1: Load pending todos.**
+
+```bash
+node dist/declare-tools.cjs check-todos
+```
+
+Parse the JSON output. It contains a `todos` array with `{id, description, created, path}` objects.
+
+If `todos` is empty:
+
+```
+No pending todos. Capture ideas with `/declare:add-todo`.
+```
+
+Stop.
+
+**Step 2: Display the todo list.**
+
+```
+## Pending Todos ([count])
+
+1. [id]: [description] — [created]
+2. [id]: [description] — [created]
+...
+```
+
+Ask: "Which todo would you like to look at? Enter the number, ID, or 'skip' to exit."
+
+**Step 3: Load the selected todo.**
+
+Wait for the user's response.
+
+If "skip" or empty: exit.
+
+Identify the selected todo by number or ID from the list.
+
+Read the todo file at its `path`:
+
+```bash
+cat [path]
+```
+
+Display the full todo content so the user can review it.
+
+**Step 4: Offer actions.**
+
+Ask: "What would you like to do with this todo?"
+
+Present these options:
+
+```
+1. Work on it now (spawn a quick task agent)
+2. Add to next milestone planning
+3. Mark as completed (move to completed/)
+4. Skip (leave pending)
+```
+
+**Step 5: Execute the chosen action.**
+
+**Option 1 — Work on it now:**
+
+Spawn a Task agent:
+
+```
+Execute this todo task. Make atomic commits after each logical unit of work.
+
+Task: [description]
+Context file: [path]
+
+Read the context file. Do the work. When complete, report what was done, files changed, and commit hashes.
+```
+
+After the agent completes, display its report, then ask: "Mark this todo as completed? (yes/no)"
+
+If yes: run:
+
+```bash
+node dist/declare-tools.cjs complete-todo --id [id]
+```
+
+Display: "Todo [id] marked as completed."
+
+**Option 2 — Add to next milestone planning:**
+
+Ask: "Which milestone should this feed into? (e.g. M-14, or 'new' to create a new one)"
+
+If the user provides a milestone ID, display:
+
+```
+Noted: "[description]" should be considered when planning [milestone-id].
+```
+
+Add this note as a reminder: suggest the user mention it when running `/declare:milestones` or `/declare:actions` for that milestone.
+
+**Option 3 — Mark as completed:**
+
+```bash
+node dist/declare-tools.cjs complete-todo --id [id]
+```
+
+Parse the JSON output and display: "Todo [id] moved to completed/."
+
+**Option 4 — Skip:**
+
+Display: "Todo left pending."
+
+**Step 6: Offer to review another todo.**
+
+After completing any action (or skipping), ask: "Would you like to review another todo? (yes/no)"
+
+If yes: return to Step 2 with the updated list (reload to reflect any completions).
+
+If no: exit.

package/commands/declare/complete-milestone.md

@@ -0,0 +1,215 @@
+---
+description: Archive a completed Declare milestone — snapshot graph, tag release, and prepare for next cycle
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+argument-hint: "[vX.Y]"
+---
+
+Archive a completed Declare milestone: snapshot the graph, check milestone statuses, update PROJECT.md, create a git tag, and prepare for the next cycle.
+
+**Step 0: Determine version.**
+
+Parse `$ARGUMENTS` for a version string matching `vX.Y` or `X.Y`.
+
+If no version in `$ARGUMENTS`, ask: "What version are we completing? (e.g., v1.0)"
+
+Normalize to `vX.Y` format (prepend `v` if absent).
+
+**Step 1: Pre-flight check — verify milestone statuses.**
+
+Load the full graph:
+
+```bash
+node dist/declare-tools.cjs load-graph
+```
+
+Parse the JSON output. If it contains an `error` field, tell the user to run `/declare:init` first and stop.
+
+For each milestone in the graph, check its `status` field. A milestone is complete when its status is `DONE`, `KEPT`, `HONORED`, or `RENEGOTIATED`.
+
+Milestones are NOT complete if their status is `PENDING`, `ACTIVE`, or `BROKEN`.
+
+Present a status table:
+
+```
+## Pre-flight Check: vX.Y
+
+| Milestone | Title                          | Status  | Complete? |
+| --------- | ------------------------------ | ------- | --------- |
+| M-01      | Context capture per milestone  | KEPT    | YES       |
+| M-02      | Milestone research pipeline    | PENDING | NO        |
+```
+
+If any milestones are NOT complete, show a warning:
+
+```
+Warning: [N] milestone(s) not yet complete:
+- M-XX: [title] (PENDING)
+- M-YY: [title] (BROKEN)
+
+Options:
+1. Proceed anyway — mark version complete with known incomplete milestones
+2. Stop — complete remaining milestones first, then re-run
+```
+
+If the user chooses to stop, end here.
+
+If the user proceeds with incomplete milestones, note them as known gaps in Step 5.
+
+If ALL milestones are complete, display:
+
+```
+All [N] milestones complete. Proceeding with vX.Y completion.
+```
+
+**Step 2: Gather stats from git log.**
+
+```bash
+git log --oneline | wc -l
+git log --oneline --since="$(git log --format='%ai' | tail -1)" | wc -l
+git diff --stat HEAD~$(git log --oneline | wc -l | tr -d ' ')..HEAD 2>/dev/null | tail -1 || echo "stats unavailable"
+git log --format="%ai" | tail -1
+git log --format="%ai" | head -1
+```
+
+If a previous git tag exists, calculate stats since that tag:
+
+```bash
+# Check for existing tags
+git tag --list "v*" | sort -V | tail -1
+
+# If previous tag exists (e.g., v0.9), use it as the range start
+PREV_TAG=$(git tag --list "v*" | sort -V | tail -1)
+if [ -n "$PREV_TAG" ]; then
+  git log --oneline "$PREV_TAG"..HEAD | wc -l
+  git diff --stat "$PREV_TAG"..HEAD | tail -1
+  git log --format="%ai" "$PREV_TAG"..HEAD | tail -1
+fi
+```
+
+Present:
+
+```
+## Milestone Stats: vX.Y
+
+- Milestones: [N] total ([N complete] complete, [N incomplete] incomplete)
+- Commits since last tag: [N] commits
+- Files changed: [M] files, [+N/-N] lines
+- Timeline: [Start date] → [End date] ([N] days)
+```
+
+**Step 3: Archive graph snapshot.**
+
+Run the complete-milestone CJS command to snapshot the current graph state:
+
+```bash
+node dist/declare-tools.cjs complete-milestone --version vX.Y
+```
+
+Parse the JSON output.
+
+If it contains an `error` field, display it and stop.
+
+On success, display:
+
+```
+## Archive Complete
+
+Snapshot saved to .planning/milestones/vX.Y/
+
+Files archived:
+- .planning/milestones/vX.Y/FUTURE.md
+- .planning/milestones/vX.Y/MILESTONES.md
+- .planning/milestones/vX.Y/M-XX-*/PLAN.md  (for each milestone folder)
+```
+
+**Step 4: Update PROJECT.md "Current State" section.**
+
+Read `.planning/PROJECT.md`:
+
+```bash
+cat .planning/PROJECT.md
+```
+
+Locate or create a `## Current State` section. Update it to reflect the completed version:
+
+```markdown
+## Current State
+
+**Version shipped:** vX.Y (YYYY-MM-DD)
+**Milestones completed:** [N] ([M-01, M-02, ...])
+**Known gaps:** [list incomplete milestones, or "None"]
+**Next step:** Run /declare:new-milestone to start vX.Z cycle
+```
+
+If the section already exists, update it in place. If it does not exist, append it after the last section.
+
+Write the updated PROJECT.md back.
+
+**Step 5: Create git tag.**
+
+```bash
+git tag -a vX.Y -m "$(cat <<'TAGMSG'
+Declare vX.Y
+
+Milestones shipped:
+- M-XX: [title]
+- M-YY: [title]
+
+[Brief one-line summary of what this version delivers]
+
+See .planning/milestones/vX.Y/ for full graph snapshot.
+TAGMSG
+)"
+```
+
+Confirm: "Tagged: vX.Y"
+
+**Step 6: Commit archived files.**
+
+Stage and commit all archive files and updated documents:
+
+```bash
+git add .planning/milestones/vX.Y/ .planning/PROJECT.md
+git commit -m "chore: archive vX.Y milestone snapshot
+
+- Snapshot: .planning/milestones/vX.Y/
+- PROJECT.md: updated Current State section
+"
+```
+
+**Step 7: Show completion summary.**
+
+```
+## vX.Y Complete
+
+**Milestones shipped:** [N]
+**Archive:** .planning/milestones/vX.Y/
+**Git tag:** vX.Y
+**PROJECT.md:** Updated
+
+---
+
+Next: Start the next milestone cycle.
+
+Run /declare:new-milestone
+```
+
+**Error handling:**
+
+- If `node dist/declare-tools.cjs load-graph` returns an error, suggest running `/declare:init` first.
+- If `node dist/declare-tools.cjs complete-milestone` returns an error containing "already exists", ask the user if they want to delete the existing archive and retry.
+- If git is not initialized, inform the user that git tagging requires `git init` and a prior commit.
+
+**Key patterns:**
+
+- Pre-flight check surfaces incomplete milestones before archiving — never silently proceed.
+- Archive is a snapshot, not a destructive operation — FUTURE.md and MILESTONES.md remain in place.
+- PROJECT.md is the persistent memory across versions — always update it.
+- Git tag marks the historical release point for the snapshot.
+- This command archives only — use /declare:new-milestone to reset for the next cycle.

package/commands/declare/dashboard.md

@@ -0,0 +1,76 @@
+---
+description: Open the interactive DAG dashboard in the browser (starts the server if needed)
+allowed-tools:
+  - Bash
+---
+
+Open the Declare interactive DAG dashboard — a live web UI showing declarations, milestones, and actions as a navigable graph.
+
+**Step 1: Check if the server is already running.**
+
+```bash
+curl -sf http://localhost:3847/api/graph -o /dev/null && echo "RUNNING" || echo "NOT_RUNNING"
+```
+
+**Step 2: Start the server if it is not running.**
+
+If the output from Step 1 is `NOT_RUNNING`:
+
+Start the server in the background, capturing its PID:
+
+```bash
+nohup node dist/declare-tools.cjs serve --port 3847 > /tmp/declare-dashboard.log 2>&1 &
+echo $!
+```
+
+Then wait briefly and confirm it started:
+
+```bash
+sleep 1 && curl -sf http://localhost:3847/api/graph -o /dev/null && echo "STARTED" || echo "FAILED"
+```
+
+If the result is `FAILED`, report the error and show the last lines of the log:
+
+```bash
+tail -20 /tmp/declare-dashboard.log
+```
+
+**Step 3: Open the dashboard in the browser.**
+
+Detect the OS and open the URL:
+
+```bash
+if [[ "$OSTYPE" == "darwin"* ]]; then
+  open http://localhost:3847
+else
+  xdg-open http://localhost:3847 2>/dev/null || echo "Visit http://localhost:3847 in your browser"
+fi
+```
+
+**Step 4: Confirm to the user.**
+
+Show the user:
+
+```
+Dashboard running at http://localhost:3847
+
+The graph auto-refreshes every 5 seconds.
+Click any node to inspect its details.
+
+Server log: /tmp/declare-dashboard.log
+To stop:    kill <PID>
+```
+
+Where `<PID>` is the process ID captured in Step 2 (or a reminder to find it with `lsof -ti :3847`).
+
+If the server was already running (Step 1 returned `RUNNING`), say "Server was already running."
+
+**Step 5: Tail server output (optional).**
+
+If `$ARGUMENTS` contains `--tail` or `--log`:
+
+```bash
+tail -f /tmp/declare-dashboard.log
+```
+
+Otherwise, skip this step.

package/commands/{gsd → declare}/debug.md

@@ -1,7 +1,7 @@
 ---
-name: gsd:debug
+name: declare:debug
 description: Systematic debugging with persistent state across context resets
-argument-hint: [issue description]
+argument-hint: "[issue description]"
 allowed-tools:
   - Read
   - Bash
@@ -12,9 +12,9 @@ allowed-tools:
 <objective>
 Debug issues using scientific method with subagent isolation.
 
-**Orchestrator role:** Gather symptoms, spawn gsd-debugger agent, handle checkpoints, spawn continuations.
+**Orchestrator role:** Gather symptoms, spawn declare-debugger agent, handle checkpoints, spawn continuations.
 
-**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
+**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh context per investigation. Main context stays lean for user interaction.
 </objective>
 
 <context>
@@ -31,12 +31,12 @@ ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
 ## 0. Initialize Context
 
 ```bash
-INIT=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs state load)
+INIT=$(node dist/declare-tools.cjs get-state)
 ```
 
 Extract `commit_docs` from init JSON. Resolve debugger model:
 ```bash
-DEBUGGER_MODEL=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs resolve-model gsd-debugger --raw)
+DEBUGGER_MODEL=$(node dist/declare-tools.cjs config-get debugger_model 2>/dev/null || echo "claude-opus-4-5")
 ```
 
 ## 1. Check Active Sessions
@@ -60,7 +60,7 @@ Use AskUserQuestion for each:
 
 After all gathered, confirm ready to investigate.
 
-## 3. Spawn gsd-debugger Agent
+## 3. Spawn declare-debugger Agent
 
 Fill prompt and spawn:
 
@@ -92,7 +92,7 @@ Create: .planning/debug/{slug}.md
 ```
 Task(
   prompt=filled_prompt,
-  subagent_type="gsd-debugger",
+  subagent_type="declare-debugger",
   model="{debugger_model}",
   description="Debug {slug}"
 )
@@ -104,7 +104,7 @@ Task(
 - Display root cause and evidence summary
 - Offer options:
   - "Fix now" - spawn fix subagent
-  - "Plan fix" - suggest /gsd:plan-phase --gaps
+  - "Plan fix" - suggest `/declare:plan` to address root cause
   - "Manual fix" - done
 
 **If `## CHECKPOINT REACHED`:**
@@ -145,7 +145,7 @@ goal: find_and_fix
 ```
 Task(
   prompt=continuation_prompt,
-  subagent_type="gsd-debugger",
+  subagent_type="declare-debugger",
   model="{debugger_model}",
   description="Continue debug {slug}"
 )
@@ -156,7 +156,7 @@ Task(
 <success_criteria>
 - [ ] Active sessions checked
 - [ ] Symptoms gathered (if new)
-- [ ] gsd-debugger spawned with context
+- [ ] declare-debugger spawned with context
 - [ ] Checkpoints handled correctly
 - [ ] Root cause confirmed before fixing
 </success_criteria>

package/commands/declare/discuss.md

@@ -0,0 +1,65 @@
+---
+description: Gather milestone context through adaptive questioning before execution
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Task
+argument-hint: "<M-XX> [--auto]"
+---
+
+Extract implementation decisions that downstream agents need — the planner and executor will use CONTEXT.md to know what choices are locked.
+
+**How it works:**
+1. Analyze the milestone to identify gray areas (behavior, output, flow, etc.)
+2. Present gray areas — user selects which to discuss
+3. Deep-dive each selected area until satisfied
+4. Create CONTEXT.md with decisions that guide planning and execution
+
+**Output:** `CONTEXT.md` in the milestone folder — decisions clear enough that downstream agents can act without asking the user again.
+
+**Step 1: Load the graph.**
+
+```bash
+node dist/declare-tools.cjs load-graph
+```
+
+Parse the JSON output. If it contains an `error` field, tell the user to run `/declare:init` first and stop.
+
+Extract milestone data. Identify the milestone matching `$ARGUMENTS` (e.g., `M-01`). If no milestone ID is provided, tell the user to provide one (e.g., `/declare:discuss M-01`) and stop.
+
+If the milestone ID is not found in the graph, tell the user and stop:
+```
+Milestone [M-XX] not found.
+
+Use /declare:status to see available milestones.
+```
+
+**Step 2: Follow the discuss workflow.**
+
+Read and follow all steps in:
+
+@workflows/discuss.md
+
+Pass the loaded graph state and milestone data into the workflow.
+
+The milestone directory is: `.planning/milestones/[M-XX]-[slug]/`
+
+CONTEXT.md is written to: `.planning/milestones/[M-XX]-[slug]/CONTEXT.md`
+
+**Step 3: Commit context.**
+
+After CONTEXT.md is written, commit it:
+
+```bash
+node dist/declare-tools.cjs commit "docs(M-XX): capture milestone context" --files ".planning/milestones/[M-XX]-[slug]/CONTEXT.md"
+```
+
+Replace `M-XX` and `[M-XX]-[slug]` with the actual milestone ID and slug.
+
+**Step 4: Handle auto-advance.**
+
+Check for `--auto` in `$ARGUMENTS` and follow the auto-advance step in the workflow.

package/commands/declare/health.md

@@ -0,0 +1,92 @@
+---
+description: Diagnose .planning/ directory health and optionally repair issues
+argument-hint: [--repair]
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+---
+
+Validate `.planning/` directory integrity and report actionable issues.
+
+**Step 1: Parse arguments.**
+
+Check `$ARGUMENTS` for the `--repair` flag.
+
+**Step 2: Run health check.**
+
+If `--repair` was passed:
+
+```bash
+node dist/declare-tools.cjs health-check --repair
+```
+
+Otherwise:
+
+```bash
+node dist/declare-tools.cjs health-check
+```
+
+Parse the JSON output. It contains:
+- `healthy`: boolean — whether all checks passed
+- `issues`: array of `{ type, message, path, fixable }` objects
+- `repaired`: array of strings describing what was fixed (only present when `--repair` was used)
+
+**Step 3: Display results.**
+
+**If healthy (no issues):**
+
+```
+.planning/ health: OK
+
+All checks passed:
+  FUTURE.md            — exists and parseable
+  MILESTONES.md        — exists and parseable
+  config.json          — exists and parseable
+  Milestone folders    — all referenced milestones have folders
+  Orphan check         — no orphaned milestone folders
+```
+
+**If there are issues:**
+
+Show a header with the count:
+
+```
+.planning/ health: [N] issue(s) found
+```
+
+Then list each issue clearly:
+
+```
+  [type indicator] [message]
+  Path: [path]
+  Fixable: yes / no
+```
+
+Use these type indicators:
+- `missing_file` → "MISSING"
+- `parse_error` → "PARSE ERROR"
+- `missing_folder` → "MISSING FOLDER"
+- `orphaned_folder` → "ORPHAN"
+
+**If `--repair` was used and repairs were made:**
+
+```
+Repaired [N] issue(s):
+  - [repair description]
+  ...
+
+Remaining issues: [N] (require manual intervention)
+```
+
+**Step 4: Suggest next steps.**
+
+If there are unfixable issues, suggest:
+- Missing FUTURE.md or MILESTONES.md: "Run `/declare:init` to recreate missing files"
+- Parse errors: "Manually inspect and fix the file at [path]"
+- Orphaned folders: "Remove or reconnect the folder: [path]"
+
+If there are fixable issues and `--repair` was NOT passed:
+```
+Run `/declare:health --repair` to automatically fix [N] fixable issue(s).
+```