declare-cc 1.0.7 → 2.0.0

package/commands/declare/actions.md

@@ -1,113 +0,0 @@
----
-description: Define actions per milestone — what must be done and what each produces (creates PLAN.md)
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
-argument-hint: "[M-XX] [--auto]"
----
-
-Derive action plans for milestones by working backward from what must be done.
-
-**Step 1: Load current graph state.**
-
-```bash
-node 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 and mode.**
-
-- 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 `$ARGUMENTS` contains `--auto`, use **auto mode** (see Step 3b). Otherwise use **interactive mode** (Step 3a).
-
-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 3a: Interactive mode (default) — per-milestone approval.**
-
-Read and follow the workflow:
-
-@workflows/actions.md
-
-For each milestone, derive and present the plan, then ask for approval using AskUserQuestion:
-
-```
-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.
-
-After approval, persist:
-
-```bash
-node dist/declare-tools.cjs create-plan --milestone "M-XX" --actions '[{"title":"Action Title","produces":"what it creates"}]'
-```
-
-**Step 3b: Auto mode (`--auto`) — derive all, present once, persist all.**
-
-Derive action plans for ALL milestones in scope without pausing between them. Use the same backward derivation logic from the workflow, but skip all AskUserQuestion prompts.
-
-After deriving all plans:
-
-1. Present the complete set as one summary:
-
-```
-## Derived Action Plans
-
-### M-01: [title]
-1. [Action A] -- produces [what]
-2. [Action B] -- produces [what]
-
-### M-02: [title]
-1. [Action A] -- produces [what]
-2. [Action B] -- produces [what]
-
-...
-
-Total: X milestones, Y actions
-```
-
-2. Ask ONE confirmation using AskUserQuestion: "Create all plans?" with options: "Yes, create all" / "Let me adjust first"
-
-3. If approved, persist ALL plans by calling create-plan for each milestone (these are fast — just file writes + commits).
-
-4. If the user wants adjustments, let them specify which milestones to adjust, adjust, then re-present.
-
-**Step 4: Show summary and suggest next step.**
-
-After all milestones processed:
-
-1. Reload the graph to get final counts:
-```bash
-node dist/declare-tools.cjs load-graph
-```
-
-2. Start the dashboard if not already running:
-```bash
-curl -sf http://localhost:3847/api/graph -o /dev/null || (node dist/declare-tools.cjs serve --port 3847 > /tmp/declare-dashboard.log 2>&1 & sleep 1 && open http://localhost:3847 2>/dev/null || true)
-```
-
-3. Show summary: milestones processed, plans created, total actions derived.
-4. Suggest the next step clearly:
-
-```
-Actions and edges are live in the dashboard → http://localhost:3847
-
-  /declare:plan M-XX    — research + planner + checker loop → EXEC-PLAN files
-  /declare:execute M-XX — once plans exist, execute with wave scheduling
-```
-
-If multiple milestones were planned, list each one with its suggested next command.

package/commands/declare/add-todo.md

@@ -1,41 +0,0 @@
----
-description: Capture an idea or task as a todo for later work
-argument-hint: "[description]"
-allowed-tools:
-  - Bash
----
-
-Capture an idea, task, or issue that surfaced during the current session as a structured todo.
-
-**Step 1: Get the description.**
-
-Parse `$ARGUMENTS` for a description string.
-
-If `$ARGUMENTS` is non-empty, use it as the description directly.
-
-If `$ARGUMENTS` is empty, infer the description from the current conversation context: look at the last few exchanges for any mentioned ideas, tasks, follow-ups, or issues the user flagged. If context is ambiguous, ask:
-
-"What would you like to capture as a todo? Give a short description."
-
-Wait for the user's reply.
-
-**Step 2: Create the todo.**
-
-```bash
-node dist/declare-tools.cjs add-todo --description "[description]"
-```
-
-Parse the JSON output. It contains `id`, `path`, and `committed`.
-
-**Step 3: Confirm capture.**
-
-Display:
-
-```
-Todo [id] captured: [path]
-"[description]"
-```
-
-If `committed` is true, mention the commit hash.
-
-Suggest: "Run `/declare:check-todos` to see all pending todos."

package/commands/declare/audit.md

@@ -1,76 +0,0 @@
----
-description: Audit milestone completion against declarations before archiving
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-argument-hint: "[M-XX]"
----
-
-Audit a milestone's completion by cross-referencing completed actions against its declarations.
-
-**Step 1: Determine milestone scope.**
-
-If `$ARGUMENTS` contains a milestone ID (e.g., `M-01`), use it directly.
-
-Otherwise, run the milestone picker and ask the user to select:
-
-```bash
-node dist/declare-tools.cjs execute
-```
-
-Display milestones and ask: "Which milestone would you like to audit?"
-
-**Step 2: Run the audit.**
-
-```bash
-node dist/declare-tools.cjs audit-milestone --milestone M-XX
-```
-
-Parse the JSON output.
-
-**Step 3: Display audit results.**
-
-```
-## Milestone Audit: M-XX — [milestoneTitle]
-
-**Declarations checked:** [declarationsChecked]
-**Actions checked:** [actionsChecked] ([actionsDone] done)
-
-### Coverage
-```
-
-For each declaration, show whether it has completed supporting actions.
-
-For each gap, display:
-
-```
-### Gaps Found
-
-| Severity | Type | Description |
-|----------|------|-------------|
-| BLOCKER  | pending-actions | A-01, A-02 not yet complete |
-| WARNING  | missing-verification | No VERIFICATION.md found |
-```
-
-**Step 4: Route based on result.**
-
-If `passed` is true (no blockers):
-
-```
-Audit passed. This milestone is ready to complete.
-
-Run `/declare:complete-milestone` to archive and tag this milestone.
-```
-
-If `passed` is false (blockers found):
-
-```
-Audit found [N] blocker(s). Resolve these before completing the milestone.
-```
-
-For pending actions: suggest running `/declare:execute M-XX` to complete them.
-For missing plan: suggest running `/declare:actions M-XX` first.
-For declaration gaps: offer to derive additional actions with `/declare:actions M-XX`.

package/commands/declare/check-todos.md

@@ -1,125 +0,0 @@
----
-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

@@ -1,215 +0,0 @@
----
-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-cycle 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-cycle
-```
-
-**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-cycle to reset for the next cycle.

package/commands/declare/dashboard.md

@@ -1,65 +0,0 @@
----
-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: Resolve the port for this project.**
-
-Each project gets its own stable port derived from the project path. Check if it's already been assigned:
-
-```bash
-cat .planning/server.port 2>/dev/null || echo "NOT_SET"
-```
-
-If a port file exists, use that port. If not, the SessionStart hook hasn't fired yet — use the default port 3847 and set PORT to it.
-
-```bash
-PORT=$(cat .planning/server.port 2>/dev/null || echo "3847")
-echo "PORT=$PORT"
-```
-
-**Step 2: Check if the server is already running on that port.**
-
-```bash
-curl -sf http://localhost:${PORT}/api/graph -o /dev/null && echo "RUNNING" || echo "NOT_RUNNING"
-```
-
-**Step 3: Start the server if it is not running.**
-
-If `NOT_RUNNING`:
-
-```bash
-nohup node dist/declare-tools.cjs serve --port ${PORT} > /tmp/declare-dashboard.log 2>&1 &
-sleep 1 && curl -sf http://localhost:${PORT}/api/graph -o /dev/null && echo "STARTED" || echo "FAILED"
-```
-
-If `FAILED`:
-```bash
-tail -20 /tmp/declare-dashboard.log
-```
-
-**Step 4: Open the dashboard in the browser.**
-
-```bash
-if [[ "$OSTYPE" == "darwin"* ]]; then
-  open http://localhost:${PORT}
-else
-  xdg-open http://localhost:${PORT} 2>/dev/null || echo "Visit http://localhost:${PORT} in your browser"
-fi
-```
-
-**Step 5: Confirm to the user.**
-
-```
-Dashboard running at http://localhost:[PORT]
-
-The graph updates live as agents run and files change.
-Click any node to inspect details and exec-plan.
-
-To stop: kill $(lsof -ti :[PORT])
-```
-
-If the server was already running (Step 2 returned `RUNNING`), say "Server was already running."