declare-cc 1.0.8 → 2.0.0

package/commands/declare/settings.md

@@ -1,119 +0,0 @@
----
-description: Configure Declare workflow settings interactively
-allowed-tools:
-  - Read
-  - Bash
-  - AskUserQuestion
----
-
-Interactive configuration of Declare workflow settings and model profile.
-
-**Step 1: Read current config.**
-
-```bash
-node dist/declare-tools.cjs config-get model_profile
-```
-
-```bash
-node dist/declare-tools.cjs config-get workflow.research
-```
-
-```bash
-node dist/declare-tools.cjs config-get workflow.plan_check
-```
-
-```bash
-node dist/declare-tools.cjs config-get workflow.auto_advance
-```
-
-Extract current values (use defaults if key not found: model_profile="quality", research=true, plan_check=true, auto_advance=false).
-
-**Step 2: Ask the 5 configuration questions in sequence using AskUserQuestion.**
-
-For each question, show the current value so the user knows what's selected now. Accept Enter to keep the current value.
-
-**Question 1: Model profile**
-
-```
-Which model profile should Declare agents use?
-
-  1. quality   — claude-opus-4-5 for all agents (highest quality, most spend)
-  2. balanced  — claude-sonnet-4-5 for execution, opus-4-5 for planning (recommended)
-  3. budget    — claude-haiku-3-5 for execution, sonnet-4-5 for planning (low spend)
-
-Current: [current value]
-Enter 1, 2, or 3 (or press Enter to keep current):
-```
-
-**Question 2: Research phase**
-
-```
-Enable research phase before milestone planning?
-Research gives agents web context but takes extra time.
-
-Current: [true/false]
-Enter yes/no (or press Enter to keep current):
-```
-
-**Question 3: Plan check**
-
-```
-Enable plan-checker review loop after planning?
-Plan-checker validates plans before execution starts.
-
-Current: [true/false]
-Enter yes/no (or press Enter to keep current):
-```
-
-**Question 4: Auto-advance**
-
-```
-Enable auto-advance mode?
-In auto mode, checkpoints are skipped and agents continue without pausing for human verification.
-Only enable if you trust the agents to proceed without review.
-
-Current: [true/false]
-Enter yes/no (or press Enter to keep current):
-```
-
-**Step 3: Parse answers and persist each changed setting.**
-
-Map answers to values:
-- Profile "1" → "quality", "2" → "balanced", "3" → "budget". Empty input → keep current.
-- "yes"/"y" → true, "no"/"n" → false. Empty input → keep current.
-
-For each setting that changed, run config-set:
-
-```bash
-node dist/declare-tools.cjs config-set --key model_profile --value <profile>
-```
-
-```bash
-node dist/declare-tools.cjs config-set --key workflow.research --value <true|false>
-```
-
-```bash
-node dist/declare-tools.cjs config-set --key workflow.plan_check --value <true|false>
-```
-
-```bash
-node dist/declare-tools.cjs config-set --key workflow.auto_advance --value <true|false>
-```
-
-**Step 4: Display confirmation.**
-
-Show a summary table of the final configuration:
-
-```
-Declare settings saved.
-
-Model profile : [profile]
-Research      : [enabled/disabled]
-Plan check    : [enabled/disabled]
-Auto-advance  : [enabled/disabled]
-
-Quick commands:
-  /declare:set-profile quality|balanced|budget   — switch profile
-  /declare:health                                — check project health
-  /declare:settings                              — open this menu
-```

package/commands/declare/status.md

@@ -1,65 +0,0 @@
----
-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 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"
-
-**Last Activity:** Show the timestamp and commit message from the last git activity.
-
-**Performance:** If the status output contains a `performance` field (non-null):
-
-Show the project rollup first:
-"Performance: [rollup.performance] (alignment: [rollup.alignment] x integrity: [rollup.integrity])"
-
-Then show per-declaration breakdown:
-
-| Declaration | Alignment | Integrity | Performance |
-|-------------|-----------|-----------|-------------|
-| D-XX: [title] | HIGH | MEDIUM | MEDIUM |
-
-If `performance` is null, skip this section entirely (graceful degradation for projects with no declarations).
-
-Keep the "Performance: HIGH (alignment: HIGH x integrity: HIGH)" plain text label format -- qualitative labels only, never numeric scores.
-
-The overall feel should be like a dashboard -- compact, scannable, with clear health indicators.

package/commands/declare/trace.md

@@ -1,81 +0,0 @@
----
-description: Trace a node's why-chain upward through the DAG to its source declarations
-allowed-tools:
-  - Read
-  - Bash
-  - Grep
-  - Glob
----
-
-Trace why a node exists by following its upward causation chain through the Declare DAG.
-
-**Step 1: Determine the node to trace.**
-
-If `$ARGUMENTS` contains a node ID (matching pattern `A-XX`, `M-XX`, or `D-XX`):
-- Use that ID directly. Proceed to Step 2.
-
-If `$ARGUMENTS` contains `--output <path>`, note the output path but still look for a node ID in the remaining arguments.
-
-If `$ARGUMENTS` is empty or contains no node ID (interactive mode):
-- Run the tool without arguments to get available nodes:
-
-```bash
-node dist/declare-tools.cjs trace
-```
-
-- Parse the JSON output. It contains a `nodes` object with `declarations`, `milestones`, and `actions` arrays.
-- Present a numbered list grouped by type:
-
-**Declarations:**
-1. D-01: [title] [STATUS]
-2. D-02: [title] [STATUS]
-
-**Milestones:**
-3. M-01: [title] [STATUS]
-...
-
-**Actions:**
-N. A-01: [title] [STATUS]
-...
-
-- Ask the user: "Which node would you like to trace? Provide the ID (e.g., A-01)."
-- Wait for the user's response, then use their provided ID in Step 2.
-
-**Step 2: Run the trace.**
-
-Build the command:
-
-```bash
-node dist/declare-tools.cjs trace <node-id>
-```
-
-If `--output <path>` was provided in `$ARGUMENTS`, append it:
-
-```bash
-node dist/declare-tools.cjs trace <node-id> --output <path>
-```
-
-Run the command and parse the JSON output.
-
-**Step 3: Handle errors.**
-
-If the output contains an `error` field:
-- Display the error message.
-- If the error mentions "not found", suggest running `/declare:trace` without arguments to see available nodes.
-- If the error mentions "No Declare project", suggest running `/declare:init`.
-
-**Step 4: Display the trace.**
-
-Use the `formatted` field from the JSON output as the primary display. It contains a pre-rendered tree with Unicode connectors showing the why-chain from the traced node upward to its source declarations.
-
-Display it in a code block for proper formatting:
-
-```
-[contents of formatted field]
-```
-
-Below the tree, add context:
-- "Traced **N** path(s) from **[node-id]** to source declarations."
-- If `truncated` is true: "Showing 20 of [totalPaths] paths. Use --output to capture all paths."
-
-If `outputFile` is present in the result, inform the user: "Output written to [path]."

package/commands/declare/update.md

@@ -1,251 +0,0 @@
----
-description: Update declare-cc to the latest npm version with local-patch preservation
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
----
-
-<purpose>
-Check whether a newer version of declare-cc is available on npm, show the version diff, back up any locally-modified files before the update runs, execute the install, reapply patches, and confirm the result.
-</purpose>
-
-<process>
-
-## Step 1: Get the installed version
-
-Run the declare-tools help command and parse the version field from its JSON output:
-
-```bash
-node dist/declare-tools.cjs help
-```
-
-Parse the JSON. The version is in the `version` field.
-
-If the command fails or returns no version:
-```
-Could not read installed version.
-Make sure you are running this command from the declare-cc project root (the directory containing dist/declare-tools.cjs).
-```
-Exit.
-
-Store as `INSTALLED_VERSION`.
-
-## Step 2: Check the latest npm version
-
-```bash
-npm view declare-cc version 2>/dev/null
-```
-
-If the command fails or returns empty output:
-```
-Could not check for updates (offline or npm unavailable).
-
-To update manually: npx declare-cc@latest
-```
-Exit.
-
-Store as `LATEST_VERSION`.
-
-## Step 3: Compare versions
-
-Parse both as semver (split on `.`, compare major/minor/patch numerically).
-
-**If installed == latest:**
-```
-declare-cc is up to date (v{INSTALLED_VERSION})
-```
-Exit.
-
-**If installed > latest:**
-```
-## Declare Update
-
-**Installed:** v{INSTALLED_VERSION}
-**Latest:** v{LATEST_VERSION}
-
-You are ahead of the latest npm release (development build?). No update needed.
-```
-Exit.
-
-**If installed < latest:** proceed to Step 4.
-
-## Step 4: Show version diff and confirm
-
-Display the pending update:
-
-```
-## Declare Update Available
-
-**Installed:** v{INSTALLED_VERSION}
-**Latest:**    v{LATEST_VERSION}
-```
-
-Use AskUserQuestion:
-- Question: "Update to v{LATEST_VERSION}?"
-- Options:
-  - "Yes, update now"
-  - "No, cancel"
-
-If the user cancels: exit.
-
-## Step 5: Scan for local modifications
-
-Before updating, check whether any files inside `.claude/commands/declare/` differ from what the package originally installed.
-
-**5a. Locate the baseline manifest.**
-
-The installer writes a manifest at install time. Check for it:
-
-```bash
-# repo-relative path
-cat .claude/commands/declare/.install-manifest.json 2>/dev/null
-```
-
-If the manifest exists, parse it. It contains an array of `{ path, hash }` entries where `hash` is the SHA-256 of the file at install time.
-
-If the manifest does not exist, skip the diff scan and proceed directly to Step 6 with a note:
-```
-No install manifest found — skipping local-modification scan.
-(Patches will not be backed up automatically.)
-```
-
-**5b. Hash each tracked file and compare.**
-
-For each entry in the manifest:
-
-```bash
-# compute current hash
-shasum -a 256 ".claude/commands/declare/{entry.path}" 2>/dev/null | awk '{print $1}'
-```
-
-If the current hash differs from the manifest hash, the file has been locally modified.
-
-**5c. If modifications found, back them up.**
-
-Create the backup directory (repo-relative):
-
-```bash
-mkdir -p .planning/declare-local-patches
-```
-
-Write a backup metadata file `.planning/declare-local-patches/backup-meta.json`:
-
-```json
-{
-  "from_version": "{INSTALLED_VERSION}",
-  "backup_date": "{ISO timestamp}",
-  "files": [
-    { "path": ".claude/commands/declare/{file}", "backup_name": "{safe-filename}" }
-  ]
-}
-```
-
-Copy each modified file:
-
-```bash
-cp ".claude/commands/declare/{file}" ".planning/declare-local-patches/{safe-filename}"
-```
-
-Display a summary:
-
-```
-## Local Modifications Detected
-
-The following files differ from the original installation and have been backed up:
-
-| File | Backup |
-|------|--------|
-| .claude/commands/declare/{file} | .planning/declare-local-patches/{safe-filename} |
-
-These will be reapplied automatically after the update.
-Run /declare:reapply-patches manually at any time to review or re-merge them.
-```
-
-**5d. If no modifications found:**
-```
-No local modifications detected. Proceeding with clean update.
-```
-
-## Step 6: Run the update
-
-```bash
-npx declare-cc@latest
-```
-
-Capture stdout and stderr. If the command exits non-zero:
-```
-## Update Failed
-
-The installer returned an error:
-
-{stderr}
-
-You can retry manually:  npx declare-cc@latest
-Your patch backups (if any) are preserved in .planning/declare-local-patches/
-```
-Exit.
-
-## Step 7: Reapply patches (if any were backed up)
-
-If patches were backed up in Step 5, reapply them automatically.
-
-Read `.planning/declare-local-patches/backup-meta.json`.
-
-For each backed-up file:
-
-1. Read the backed-up (user's modified) version from `.planning/declare-local-patches/{safe-filename}`.
-2. Read the newly installed version from `.claude/commands/declare/{file}`.
-3. If the files are identical (the upstream incorporated the change): report `Skipped (already upstream)` and continue.
-4. If the files differ: apply the user's version directly over the newly installed file.
-   - Write the backed-up content to `.claude/commands/declare/{file}`.
-   - Report `Reapplied`.
-
-Display result table:
-
-```
-## Patches Reapplied
-
-| File | Result |
-|------|--------|
-| .claude/commands/declare/{file} | Reapplied |
-| .claude/commands/declare/{file} | Skipped (already upstream) |
-```
-
-If any reapplied file differs significantly from the new upstream version (the file changed in a way that may conflict), display:
-```
-Note: {file} was reapplied from your backup but the upstream also changed this file.
-Run /declare:reapply-patches to review the diff and resolve conflicts manually.
-```
-
-## Step 8: Confirm completion
-
-```
-## Declare Updated
-
-v{INSTALLED_VERSION} -> v{LATEST_VERSION}
-
-Restart Claude Code to pick up the new commands.
-```
-
-If patches were reapplied:
-```
-Your local modifications have been reapplied. Run /declare:reapply-patches to verify or adjust.
-```
-
-</process>
-
-<success_criteria>
-- [ ] Installed version read from node dist/declare-tools.cjs help
-- [ ] Latest version checked via npm view declare-cc version
-- [ ] No-op if already up to date
-- [ ] Version diff shown and user confirms before proceeding
-- [ ] Local modifications scanned against install manifest
-- [ ] Modified files backed up to .planning/declare-local-patches/
-- [ ] Update run via npx declare-cc@latest
-- [ ] Patches reapplied after update
-- [ ] Completion confirmed with restart reminder
-</success_criteria>

package/commands/declare/verify.md

@@ -1,65 +0,0 @@
----
-name: declare:verify
-description: Validate milestone deliverables through conversational UAT. When issues found, diagnoses root causes and creates fix plans.
-argument-hint: "[milestone ID, e.g., 'M-08']"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Edit
-  - Write
-  - Task
----
-<objective>
-Validate milestone deliverables through conversational testing with persistent state.
-
-Purpose: Confirm what was built actually works from user's perspective. One test at a time, plain text responses, no interrogation. When issues are found, automatically diagnose root causes (spawn parallel declare-debugger agents) and create fix action plans.
-
-Output: {milestone_id}-UAT.md in milestone folder tracking all test results. If issues found: diagnosed gaps with root causes, verified fix action plans ready for `/declare:execute M-{id} --gaps-only`.
-</objective>
-
-<execution_context>
-@workflows/verify.md
-</execution_context>
-
-<context>
-Milestone: $ARGUMENTS (optional)
-- If provided: Test specific milestone (e.g., "M-08")
-- If not provided: Check for active sessions or prompt for milestone ID
-
-@.planning/STATE.md
-</context>
-
-<process>
-Execute the verify workflow from @workflows/verify.md end-to-end.
-Preserve all workflow gates: session management, test presentation, diagnosis, fix planning, routing.
-
-**Loading milestone plans:**
-```bash
-# List PLAN.md files in milestone directory
-MILESTONE_DIR=$(echo "$ARGUMENTS" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
-ls ".planning/milestones/${MILESTONE_DIR}/"*-PLAN.md 2>/dev/null
-```
-
-**Writing UAT results:**
-```bash
-node dist/declare-tools.cjs commit "test(${MILESTONE_ID}): complete UAT - ${PASSED} passed, ${ISSUES} issues" \
-  --files ".planning/milestones/${MILESTONE_DIR}/${MILESTONE_ID}-UAT.md"
-```
-
-**On gaps found — spawn parallel declare-debugger agents (one per gap):**
-
-For each gap in the UAT Gaps section, spawn a declare-debugger agent with:
-- `model: "opus"`
-- `symptoms_prefilled: true` (skip symptom gathering)
-- `goal: find_root_cause_only` (diagnose but don't fix)
-- Pre-filled symptoms from the gap's test_id, expected, and actual fields
-
-Collect all ROOT CAUSE FOUND responses, update UAT.md with root_cause for each gap.
-
-**After diagnosis — create fix action plans:**
-
-Review diagnosed gaps and create fix action plans targeting each root cause.
-Plans should be concrete, executable steps referencing specific files to change.
-</process>

package/commands/declare/visualize.md

@@ -1,74 +0,0 @@
----
-description: Visualize the Declare DAG as a top-down ASCII tree with status markers
-allowed-tools:
-  - Read
-  - Bash
-  - Grep
-  - Glob
-  - Write
----
-
-Render the Declare DAG as a top-down tree showing declarations, milestones, and actions with their status.
-
-**Step 1: Build the command.**
-
-Start with the base command:
-
-```bash
-node dist/declare-tools.cjs visualize
-```
-
-If `$ARGUMENTS` contains a scope ID (matching pattern `D-XX` or `M-XX`):
-- Append it to scope the visualization to that subtree:
-
-```bash
-node dist/declare-tools.cjs visualize <scope-id>
-```
-
-If `$ARGUMENTS` contains `--output <path>`:
-- Append it to write the tree to a file:
-
-```bash
-node dist/declare-tools.cjs visualize --output <path>
-```
-
-Both scope and output can be combined:
-
-```bash
-node dist/declare-tools.cjs visualize <scope-id> --output <path>
-```
-
-**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 valid IDs by running `/declare:status` to see available nodes.
-- If "No Declare project", suggest running `/declare:init`.
-
-**Step 4: Display the tree.**
-
-Use the `formatted` field from the JSON output directly. It contains the pre-rendered ASCII tree with Unicode box-drawing connectors and status markers.
-
-Display it in a code block for proper alignment:
-
-```
-[contents of formatted field]
-```
-
-**Status marker legend:**
-- `[checkmark]` = DONE
-- `[>]` = ACTIVE
-- `[circle]` = PENDING
-- `[!]` = BLOCKED (has non-done children)
-
-**Step 5: Show stats.**
-
-Below the tree, display: "**N** declarations, **N** milestones, **N** actions"
-
-Using the `stats` object from the JSON output.
-
-If scope was used, note: "Scoped to subtree of **[scope-id]**."
-
-If `outputFile` is present in the result, inform the user: "Output written to [path]."