declare-cc 1.0.8 → 2.0.0

package/commands/declare/plan.md

@@ -1,320 +0,0 @@
----
-name: declare:plan
-description: Create detailed EXEC-PLAN files for milestone actions with planner/checker verification loop
-argument-hint: "[M-XX] [--skip-research]"
-agent: declare-planner
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Task
-  - WebFetch
-  - mcp__context7__*
----
-<objective>
-Create executable EXEC-PLAN files for all actions in a milestone with integrated verification.
-
-**Default flow:** Load context → optional research check → spawn declare-planner → spawn declare-plan-checker → if issues spawn planner for revision (max 3 iterations) → commit
-
-**Orchestrator role:** Parse arguments, validate milestone, load context, spawn declare-planner, verify with declare-plan-checker, iterate until pass or max iterations, present results.
-</objective>
-
-<context>
-Milestone: $ARGUMENTS (matching pattern M-XX, e.g. M-01)
-
-**Flags:**
-- `--skip-research` — Skip research check, go straight to planning
-</context>
-
-<process>
-
-**Step 1: Parse arguments.**
-
-Extract milestone ID from `$ARGUMENTS` (pattern `M-XX`). If not provided or unrecognized, list available milestones:
-
-```bash
-node dist/declare-tools.cjs load-graph
-```
-
-Parse the JSON output. Display a numbered list of milestones with their status and action counts. Ask the user which milestone to plan.
-
-Check if `--skip-research` is present in `$ARGUMENTS`.
-
-**Step 2: Load milestone data.**
-
-```bash
-node dist/declare-tools.cjs load-graph
-```
-
-Parse the JSON output. Find the milestone matching the ID. Extract:
-- `milestone`: milestone ID and title (from `milestones` array)
-- `declarations`: upstream declarations that realize this milestone (trace via `realizes` field)
-- `actions`: all actions whose `causes` array includes this milestone ID
-- `milestoneFolderPath`: derive as `.planning/milestones/M-XX-<slug>/`
-- `researchPath`: `.planning/milestones/M-XX-<slug>/RESEARCH.md` if it exists
-- `contextPath`: `.planning/milestones/M-XX-<slug>/CONTEXT.md` if it exists
-
-If no actions found, display: "No actions found for M-XX. Run `/declare:actions M-XX` first to create the milestone plan." and exit.
-
-If all actions already have EXEC-PLANs and status is not PENDING, display: "All actions for M-XX already have EXEC-PLANs. Use `/declare:execute M-XX` to run them." and exit.
-
-**Step 3: Ensure milestone context exists.**
-
-Check if CONTEXT.md exists at `milestoneFolderPath/CONTEXT.md`.
-
-If CONTEXT.md does **not** exist, use AskUserQuestion:
-- header: "Context"
-- question: "Milestone [M-XX] has no implementation context yet. Discussing decisions now gives the planner the information it needs to create better EXEC-PLANs."
-- options:
-  - "Discuss first (Recommended)" — Run discuss workflow, then proceed to planning
-  - "Plan without context" — Skip; planner will use its own judgment
-
-If "Discuss first":
-
-Display: `Running /declare:discuss [M-XX]...`
-
-Spawn a Task agent:
-- subagent_type: `general-purpose`
-- model: `opus`
-- description: `Discuss M-XX implementation decisions`
-- prompt:
-  ```
-  Run /declare:discuss [M-XX] for the Declare project.
-  Working directory: [absolute cwd]
-  Follow all instructions in commands/declare/discuss.md.
-  After capturing context, return DONE.
-  ```
-
-Wait for the task to complete. Then reload `contextPath` — CONTEXT.md should now exist.
-
-If "Plan without context": continue to Step 4.
-
-**Step 4: Research check (unless --skip-research).**
-
-If `researchPath` exists, display:
-```
-RESEARCH.md found at [researchPath]. Using existing research.
-```
-
-If `researchPath` does not exist, assess whether research is needed:
-
-- If actions involve new external libraries, external APIs, or major architectural decisions → suggest research:
-  ```
-  Research recommended for M-XX ([title]).
-  Actions involve: [brief reason, e.g., "new external service integration"].
-  Run `/declare:research M-XX` first, or pass --skip-research to plan without research.
-  ```
-  Ask: "Proceed without research? (yes/no)" If no, exit.
-
-- If actions are purely internal (refactoring, adding features to existing patterns, docs) → skip silently.
-
-**Step 5: Load context files.**
-
-```bash
-cat [contextPath] 2>/dev/null          # CONTEXT.md if exists
-cat [researchPath] 2>/dev/null         # RESEARCH.md if exists
-cat .planning/MILESTONES.md            # Full milestones for declaration context
-cat .planning/FUTURE.md 2>/dev/null    # Declarations source of truth
-cat .planning/STATE.md 2>/dev/null     # Current position and decisions
-```
-
-Also read the milestone's PLAN.md (at `milestoneFolderPath/PLAN.md`) for action details.
-
-**Step 6: Spawn declare-planner.**
-
-Spawn a Task agent using `agents/declare-planner.md` with `model: "opus"` and the following prompt:
-
-```
-Plan milestone ${MILESTONE} actions.
-
-Context loaded:
-- Milestone: [milestone title]
-- Declarations: [D-XX: statement, ...]
-- Actions: [A-XX: title (produces: ..., dependsOn: [...])]
-- Milestone folder: [milestoneFolderPath]
-- CONTEXT.md: [contents or "not found"]
-- RESEARCH.md: [contents or "not found"]
-- MILESTONES.md: [relevant milestone section]
-- FUTURE.md: [relevant declaration statements]
-- STATE.md decisions: [relevant decisions]
-
-For each action, create an EXEC-PLAN file at:
-  [milestoneFolderPath]/[action-id]-EXEC-PLAN.md
-
-Follow all instructions in agents/declare-planner.md.
-Return: PLANNING COMPLETE with wave structure and EXEC-PLANs created.
-```
-
-Wait for the planner to complete.
-
-**Step 7: Spawn declare-plan-checker.**
-
-After planner completes, spawn a Task agent using `agents/declare-plan-checker.md` with `model: "haiku"` and the following prompt:
-
-```
-Verify EXEC-PLAN files for milestone ${MILESTONE}.
-
-Context:
-- Milestone: [milestone title]
-- Declarations: [D-XX: statement, ...]
-- Milestone folder: [milestoneFolderPath]
-- CONTEXT.md: [contents or "not found"]
-- MILESTONES.md: [relevant milestone section]
-
-EXEC-PLANs to verify:
-[list of EXEC-PLAN file paths created by planner]
-
-Follow all instructions in agents/declare-plan-checker.md.
-Return: VERIFICATION PASSED or ISSUES FOUND with structured issues YAML.
-```
-
-Wait for the checker to complete.
-
-**Step 8: Evaluate checker result.**
-
-Parse the checker's return.
-
-If **VERIFICATION PASSED**: proceed to Step 10.
-
-If **ISSUES FOUND**: proceed to Step 9 (revision loop).
-
-**Step 9: Revision loop (max 3 iterations).**
-
-Track revision count. If revision count >= 3, skip to Step 9 with a warning.
-
-Spawn declare-planner again in revision mode with `model: "opus"`:
-
-```
-Revise EXEC-PLAN files for milestone ${MILESTONE} based on checker feedback.
-
-This is revision attempt [N] of 3.
-
-Checker issues found:
-[paste the structured issues YAML from checker]
-
-Existing EXEC-PLANs:
-[list of EXEC-PLAN file paths]
-
-Context:
-- Milestone folder: [milestoneFolderPath]
-- CONTEXT.md: [contents or "not found"]
-
-Follow revision_mode instructions in agents/declare-planner.md.
-Make targeted fixes only — do not rewrite working plans.
-Return: REVISION COMPLETE with changes made.
-```
-
-After revision, re-run checker (Step 7). Increment revision count.
-
-Repeat until VERIFICATION PASSED or revision count reaches 3.
-
-**Step 10: Commit EXEC-PLANs.**
-
-Pass each file as a separate `--files` argument (not space-separated in one argument):
-
-```bash
-node dist/declare-tools.cjs commit "docs(${MILESTONE}): create exec-plans for milestone actions" --files [path/to/A-01-EXEC-PLAN.md] --files [path/to/A-02-EXEC-PLAN.md]
-```
-
-If the commit reports `nothing_to_commit`, the planner already committed the files — that is fine, continue.
-
-**Step 11: Present results.**
-
-Display final summary:
-
-```
-## Planning Complete: M-XX — [milestone title]
-
-**Actions planned:** [N] action(s) in [M] wave(s)
-**Checker:** [PASSED | PASSED after N revision(s) | Warning: max revisions reached]
-
-### Wave Structure
-
-| Wave | Actions | Autonomous |
-| ---- | ------- | ---------- |
-| 1    | A-01, A-02 | yes, yes |
-| 2    | A-03    | no (has checkpoint) |
-
-### EXEC-PLANs Created
-
-| Action | Title | Tasks | Wave |
-| ------ | ----- | ----- | ---- |
-| A-01   | [title] | [N]  | 1    |
-| A-02   | [title] | [N]  | 1    |
-
-### Next Steps
-
-```
-
-After displaying the summary, reload the graph and check for milestones that still have no EXEC-PLANs (hasPlan is false OR actions array for that milestone has no EXEC-PLAN files):
-
-- If **other milestones still need planning**, list them and suggest planning those next:
-  ```
-  Remaining milestones to plan:
-    /declare:plan M-02  — [title]
-    /declare:plan M-03  — [title]
-
-  Plan all milestones before executing. Run /declare:execute only when all are planned.
-  ```
-
-- If **this was the last milestone to plan**, compute dependency waves before spawning anything — do not blindly parallelize all milestones.
-
-  **Step A: Compute milestone dependency waves.**
-
-  Load the graph, then read each milestone's PLAN.md. For each action, check its `dependsOn` field. If an action in M-02 lists `dependsOn: ["A-01"]` and A-01 belongs to M-01, then M-02 depends on M-01.
-
-  Build a milestone-level dependency graph from these cross-milestone action references. Run a topological sort (Kahn's algorithm) to group milestones into waves:
-  - Wave 1: milestones with no dependencies on other pending milestones
-  - Wave 2: milestones whose dependencies are all in wave 1
-  - …and so on
-
-  If no cross-milestone `dependsOn` edges exist, all milestones go into wave 1 (full parallelism). Show the wave plan before executing:
-
-  ```
-  ## Milestone Execution Waves
-
-  Wave 1 (parallel): M-01 [title], M-03 [title]
-  Wave 2 (after wave 1): M-02 [title]
-  ```
-
-  **Step B: Execute wave by wave using the Task tool.**
-
-  For each wave, spawn one Task agent per milestone **in the same response** so they execute in parallel:
-
-  Subagent type: `gsd-executor`
-  model: `opus`
-  Prompt per milestone:
-  ```
-  Execute milestone [M-XX] "[title]" for the Declare project.
-  Working directory: [absolute path to cwd]
-  Run: /declare:execute [M-XX]
-  EXEC-PLANs are in: [absolute path to milestone folder]
-  ```
-
-  Wait for the entire wave to complete before spawning the next wave.
-
-  After all waves finish, propagate statuses:
-  ```bash
-  node dist/declare-tools.cjs sync-status
-  ```
-
-If max revisions reached with issues remaining, display blocker list prominently:
-
-```
-### Remaining Issues (not resolved after 3 revisions)
-
-[list issues with fix hints]
-
-Consider reviewing EXEC-PLANs manually at: [milestoneFolderPath]
-```
-
-**Error handling:**
-
-- If `load-graph` returns an error, display it and exit.
-- If planner fails to create EXEC-PLANs, display the error and suggest checking the milestone folder exists.
-- If checker returns malformed output (not VERIFICATION PASSED or ISSUES FOUND), treat as passed and log a warning.
-- If commit fails, display the error but do not block — planning work is already on disk.
-
-</process>

package/commands/declare/prioritize.md

@@ -1,65 +0,0 @@
----
-description: Rank actions by unblocking power (dependency weight score)
-allowed-tools:
-  - Read
-  - Bash
-  - Grep
-  - Glob
----
-
-Show a ranked list of actions ordered by their unblocking power -- how many milestones and declarations each action contributes to.
-
-**Step 1: Build the command.**
-
-Start with the base command:
-
-```bash
-node dist/declare-tools.cjs prioritize
-```
-
-If `$ARGUMENTS` contains `--declaration D-XX`:
-- Append `--declaration D-XX` to filter actions to those under a specific declaration's subtree:
-
-```bash
-node dist/declare-tools.cjs prioritize --declaration D-XX
-```
-
-If `$ARGUMENTS` contains `--output <path>`:
-- Append `--output <path>` to write the ranking to a file:
-
-```bash
-node dist/declare-tools.cjs prioritize --output <path>
-```
-
-Both flags can be combined.
-
-**Step 2: Run the command and parse JSON output.**
-
-**Step 3: Handle errors.**
-
-If the output contains an `error` field:
-- Display the error message.
-- If "not found", suggest checking declaration IDs with `/declare:status`.
-- If "No Declare project", suggest running `/declare:init`.
-
-**Step 4: Display the ranking.**
-
-If `totalActions` is 0:
-- Display: "No actions found. Create actions first with `/declare:actions`."
-- Stop here.
-
-Otherwise, render the ranked list as a formatted table:
-
-| Rank | ID | Action | Score |
-|------|----|--------|-------|
-| 1 | A-03 | [title] | 4 |
-| 2 | A-01 | [title] | 3 |
-| ... | ... | ... | ... |
-
-Use the `ranking` array from the JSON output. Each entry has: `rank`, `id`, `title`, `score`.
-
-**Explain the score:** "Score = number of milestones and declarations this action contributes to (unblocking power). Higher score means completing this action unblocks more of the graph."
-
-If `filter` is non-null, note: "Filtered to actions under **[filter]**."
-
-If `outputFile` is present in the result, inform the user: "Output written to [path]."

package/commands/declare/progress.md

@@ -1,116 +0,0 @@
----
-name: declare:progress
-description: Show current project position, recent work summary, and route to the next action
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
----
-
-Show project progress, summarize recent work, and route to the appropriate next action.
-
-**Step 1: Load state and graph.**
-
-Run both commands:
-
-```bash
-node dist/declare-tools.cjs get-state
-```
-
-```bash
-node dist/declare-tools.cjs load-graph
-```
-
-Parse both JSON outputs.
-
-If `get-state` returns an error (STATE.md not found), display:
-
-```
-No STATE.md found. Run /declare:new-project to initialize this project.
-```
-
-Then stop.
-
-**Step 2: Determine current position.**
-
-From the `get-state` output, extract:
-- `currentPosition`: the milestone or action currently active
-- `recentWork`: what was last worked on
-- `decisions`: key decisions recorded
-- `sessionHistory`: last session entries
-
-From the `load-graph` output, extract:
-- `milestones` array: find milestones with status `PENDING` or `ACTIVE`
-- `actions` array: find actions for the active milestone with status `PENDING` or `ACTIVE`
-- Count total milestones, total done milestones, total actions done
-
-**Step 3: Display progress dashboard.**
-
-Render a compact, scannable summary:
-
-```
-## Project Progress
-
-**Position:** [currentPosition from STATE.md]
-**Milestones:** [done count] / [total count] complete
-**Graph health:** [health field from load-graph, or "unknown" if absent]
-
-### Active Milestone
-
-[If an ACTIVE milestone exists, show:]
-**[M-XX]: [title]** — [status]
-Actions: [done]/[total] complete
-
-[pending actions listed as:]
-- A-XX: [title] (PENDING)
-- A-XX: [title] (DONE)
-
-### Recent Work
-
-[recentWork from STATE.md, or "(no recent work recorded)" if empty]
-
-### What's Next
-
-[See routing logic in Step 4]
-```
-
-**Step 4: Route to next action.**
-
-Evaluate project state and present the appropriate option(s):
-
-**Route A — Active milestone with pending actions:**
-- "Actions remain for [M-XX]. Ready to continue."
-- Offer: "Run `/declare:execute [M-XX]` to continue execution"
-
-**Route B — Milestone just completed, not yet verified:**
-- "[M-XX] is DONE but not yet verified."
-- Offer: "Run `/declare:verify [M-XX]` to verify milestone truth"
-
-**Route C — All milestones for active declarations complete:**
-- "All milestones for the current declaration wave are complete."
-- Offer: "Run `/declare:complete-milestone` or plan the next milestone with `/declare:new-cycle`"
-
-**Route D — No active milestone:**
-- "No active milestone found."
-- Offer: "Run `/declare:new-cycle` to plan the next milestone, or `/declare:status` to review the full graph"
-
-**Route E — No declarations exist:**
-- "No declarations found. Start by defining what you want to be true."
-- Offer: "Run `/declare:future` to add your first declaration"
-
-**Route F — Graph load error:**
-- Display the error from `load-graph`
-- Offer: "Run `/declare:health` to diagnose and repair the project structure"
-
-Present routes as a numbered list when more than one applies. Keep suggestions concise — one line per option.
-
-**Step 5: Update session record.**
-
-After displaying the dashboard, record the session view:
-
-```bash
-node dist/declare-tools.cjs record-session --stopped-at "Checked progress — [currentPosition]"
-```
-
-Do not display the output of this command.

package/commands/declare/quick.md

@@ -1,119 +0,0 @@
----
-description: Execute a quick ad-hoc task with atomic commits outside the milestone structure
-argument-hint: "[task description] [--full]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Glob
-  - Grep
-  - Bash
-  - Task
----
-
-Execute a small, ad-hoc task with atomic commits. Quick tasks live in `.planning/quick/` separate from milestone-driven phases.
-
-**Default:** Skips plan-checking and verification. Use when you know exactly what to do.
-
-**`--full` flag:** Adds plan-review before execution and a verification step after. Use when you want quality guarantees without full milestone ceremony.
-
-**Step 1: Get the task description.**
-
-Parse `$ARGUMENTS` for a task description and a `--full` flag.
-
-If `$ARGUMENTS` contains text other than `--full`, treat that text as the task description. Strip `--full` from the description.
-
-If `$ARGUMENTS` is empty or contains only `--full`, ask:
-
-"What would you like to do? Describe the task in one or two sentences."
-
-Wait for the user's reply and use it as the task description.
-
-**Step 2: Create the quick task folder.**
-
-```bash
-node dist/declare-tools.cjs quick-task --description "[task description]"
-```
-
-Parse the JSON output. It contains `id`, `folder`, `planPath`, and `committed`.
-
-Display:
-
-```
-Quick Task [id] created: [folder]
-```
-
-**Step 3 (--full only): Plan review.**
-
-If `--full` flag is present:
-
-Read the QUICK-PLAN.md at `planPath`:
-
-```bash
-cat [planPath]
-```
-
-Review the plan and display a brief assessment (2-4 bullet points):
-
-```
-## Plan Review
-
-- [Assessment of scope and approach]
-- [Any potential issues or missing steps]
-- [Suggested refinements if needed]
-```
-
-Ask: "Proceed with this plan? (yes/refine)"
-
-If "refine": ask for clarification, update the QUICK-PLAN.md with the refined plan, then continue.
-
-If "yes": proceed to Step 4.
-
-If `--full` is NOT present, skip this step and proceed directly to Step 4.
-
-**Step 4: Execute the task.**
-
-Spawn a Task agent with `subagent_type="general-purpose"` to execute the work:
-
-```
-Execute the quick task described below. Make atomic commits after each logical unit of work.
-
-Task: [task description]
-Plan file: [planPath]
-
-Read the plan file for context. Do the work. When complete, report:
-- What was done
-- Files created or modified
-- Commit hashes
-- Any issues encountered
-```
-
-Wait for the Task agent to complete. Display its report.
-
-**Step 5 (--full only): Verification.**
-
-If `--full` flag is present:
-
-Ask: "Does the completed work match what you expected? Review the agent's report above. (yes/issues)"
-
-If "issues": describe what is missing or wrong, then re-spawn the Task agent with the correction context appended.
-
-If "yes": proceed to Step 6.
-
-If `--full` is NOT present, proceed directly to Step 6.
-
-**Step 6: Report completion.**
-
-Display:
-
-```
-## Quick Task Complete
-
-**Task:** [task description]
-**Folder:** [folder]
-**Mode:** [default | full]
-```
-
-List all files created or modified and all commit hashes from the agent's report.
-
-Suggest: "Run `/declare:status` to see overall project health."