declare-cc 0.1.0 → 0.3.0

package/commands/declare/plan.md

@@ -0,0 +1,236 @@
+---
+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 --milestone M-XX
+```
+
+Parse the JSON output. Extract:
+- `milestone`: milestone ID and title
+- `declarations`: array of declaration IDs and statements
+- `actions`: array of `{id, title, produces, dependsOn, status}`
+- `milestoneFolderPath`: path to the milestone planning folder
+- `researchPath`: path to RESEARCH.md if it exists
+- `contextPath`: path to 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: 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 4: 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 5: Spawn declare-planner.**
+
+Spawn a Task agent using `agents/declare-planner.md` with 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 6: Spawn declare-plan-checker.**
+
+After planner completes, spawn a Task agent using `agents/declare-plan-checker.md` with 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 7: Evaluate checker result.**
+
+Parse the checker's return.
+
+If **VERIFICATION PASSED**: proceed to Step 9.
+
+If **ISSUES FOUND**: proceed to Step 8 (revision loop).
+
+**Step 8: 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:
+
+```
+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 6). Increment revision count.
+
+Repeat until VERIFICATION PASSED or revision count reaches 3.
+
+**Step 9: Commit EXEC-PLANs.**
+
+```bash
+node dist/declare-tools.cjs commit "docs(${MILESTONE}): create exec-plans for milestone actions" --files [space-separated list of EXEC-PLAN file paths]
+```
+
+**Step 10: 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
+
+Execute: `/declare:execute M-XX`
+
+/clear first — fresh context window
+```
+
+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

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

@@ -0,0 +1,116 @@
+---
+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-milestone`"
+
+**Route D — No active milestone:**
+- "No active milestone found."
+- Offer: "Run `/declare:new-milestone` 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

@@ -0,0 +1,119 @@
+---
+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 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."

package/commands/declare/reapply-patches.md

@@ -0,0 +1,178 @@
+---
+description: Review and reapply locally-modified declare-cc files after an update
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<purpose>
+After a declare-cc update wipes and reinstalls .claude/commands/declare/ files, this command lets you review each locally-modified file that was backed up, preview what changed, and selectively merge your modifications into the new installed version.
+</purpose>
+
+<process>
+
+## Step 1: Detect backed-up patches
+
+Read the backup metadata file (repo-relative):
+
+```bash
+cat .planning/declare-local-patches/backup-meta.json 2>/dev/null
+```
+
+**If the file does not exist or the directory is empty:**
+```
+No local patches found. Nothing to reapply.
+
+Local patches are saved automatically when you run /declare:update
+and locally-modified files are detected before the update runs.
+```
+Exit.
+
+Parse the JSON. It contains:
+- `from_version`: the version that was installed when the backup was made
+- `backup_date`: ISO timestamp of the backup
+- `files`: array of `{ path, backup_name }` entries
+
+## Step 2: Show patch summary
+
+Read the current installed version:
+
+```bash
+node dist/declare-tools.cjs help
+```
+
+Parse the version field.
+
+Display:
+
+```
+## Local Patches to Reapply
+
+**Backed up from:** v{from_version}
+**Backed up on:**   {backup_date}
+**Current version:** v{current_version}
+**Files backed up:** {count}
+
+| # | File | Status |
+|---|------|--------|
+| 1 | {path} | Pending |
+| 2 | {path} | Pending |
+```
+
+## Step 3: Process each file
+
+Iterate over each entry in `files`.
+
+### 3a. Read both versions
+
+Read the backed-up (user's modified) copy:
+
+```bash
+cat ".planning/declare-local-patches/{backup_name}"
+```
+
+Read the current installed copy:
+
+```bash
+cat "{path}"
+```
+
+### 3b. Compare
+
+If the two files are identical: report `Skipped (already upstream)` and continue to the next file.
+
+If they differ: proceed to 3c.
+
+### 3c. Show diff preview and ask
+
+Display a diff preview. Describe the key differences in plain language (do not dump raw diff output). For example:
+
+```
+--- Diff preview: {path} ---
+
+Your backed-up version adds/changes:
+- [describe what the user's version has that the new version does not, in plain language]
+
+The new installed version adds/changes:
+- [describe what the new upstream version has that the backup does not]
+```
+
+Use AskUserQuestion:
+- Question: "What would you like to do with .claude/commands/declare/{filename}?"
+- Options:
+  - "Keep my version (overwrite installed file with backup)"
+  - "Keep new version (discard backup for this file)"
+  - "Merge manually (I will edit the file after this command)"
+
+**If user chooses "Keep my version":**
+- Write the backed-up content to `{path}`.
+- Report: `Reapplied — your version is active`.
+
+**If user chooses "Keep new version":**
+- Do not modify `{path}`.
+- Report: `Kept new version — backup preserved in .planning/declare-local-patches/`.
+
+**If user chooses "Merge manually":**
+- Do not modify `{path}`.
+- Display:
+  ```
+  Backed-up copy: .planning/declare-local-patches/{backup_name}
+  Installed copy: {path}
+  Edit {path} manually, using the backup as reference.
+  ```
+- Report: `Deferred — manual merge required`.
+
+## Step 4: Update status table
+
+After processing all files, display the final status table:
+
+```
+## Reapply Complete
+
+| # | File | Result |
+|---|------|--------|
+| 1 | {path} | Reapplied |
+| 2 | {path} | Skipped (already upstream) |
+| 3 | {path} | Kept new version |
+| 4 | {path} | Deferred (manual merge) |
+
+{reapplied_count} file(s) reapplied. {skipped_count} skipped. {deferred_count} deferred.
+```
+
+## Step 5: Cleanup option
+
+Ask:
+
+Use AskUserQuestion:
+- Question: "What would you like to do with the backup files in .planning/declare-local-patches/?"
+- Options:
+  - "Keep backups (preserve for reference)"
+  - "Remove backups (clean up patch directory)"
+
+**If user chooses "Remove backups":**
+
+```bash
+rm -rf .planning/declare-local-patches
+```
+
+Display: `Backup directory removed.`
+
+**If user chooses "Keep backups":**
+Display: `Backups preserved at .planning/declare-local-patches/`
+
+</process>
+
+<success_criteria>
+- [ ] backup-meta.json located and parsed
+- [ ] Version comparison shown (backed-up from vs current)
+- [ ] Each file diff previewed in plain language
+- [ ] User confirms action per file (keep mine / keep new / manual)
+- [ ] Chosen versions written correctly
+- [ ] Final status table shown
+- [ ] Cleanup option offered
+</success_criteria>