declare-cc 0.1.0 → 0.3.0

package/commands/declare/research.md

@@ -0,0 +1,267 @@
+---
+description: Research how to implement a milestone (spawns 4 parallel researchers, then synthesizes)
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+argument-hint: "[M-XX]"
+---
+
+Research how to implement a milestone by spawning 4 parallel researcher agents (stack, features, architecture, pitfalls) then synthesizing their findings into a unified RESEARCH.md.
+
+**Step 1: Load graph and validate milestone.**
+
+```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.
+
+If `$ARGUMENTS` contains a milestone ID (e.g., `M-02`), use it directly. Otherwise, list all pending milestones and ask the user to specify one.
+
+Extract from the graph the milestone's `title`, `goal`, and which declaration IDs it `realizes` (e.g., `D-01`). If the milestone is not found, tell the user and stop.
+
+Note the milestone slug by converting the milestone title to lowercase with hyphens (e.g., "Milestone research pipeline" → "milestone-research-pipeline"). The milestone folder path is `.planning/milestones/M-XX-slug/`.
+
+**Step 2: Check for existing research.**
+
+```bash
+ls .planning/milestones/M-XX-slug/RESEARCH.md 2>/dev/null
+```
+
+If RESEARCH.md already exists:
+- Display: "RESEARCH.md already exists for M-XX. Options: 1) Re-research (overwrite), 2) View existing, 3) Cancel"
+- Wait for user choice before continuing.
+
+If it does not exist, continue.
+
+**Step 3: Check for existing CONTEXT.md.**
+
+```bash
+ls .planning/milestones/M-XX-slug/CONTEXT.md 2>/dev/null
+```
+
+If CONTEXT.md exists, it contains user decisions that constrain research. Load it and pass it to all researcher agents.
+
+**Step 4: Display research banner.**
+
+```
+## Researching: M-XX — [milestoneTitle]
+
+**Declares:** [declaration IDs and statements]
+**Goal:** [milestone goal or title]
+**Mode:** Parallel research (4 agents → synthesizer)
+
+Spawning 4 researchers: STACK, FEATURES, ARCHITECTURE, PITFALLS...
+```
+
+**Step 5: Spawn 4 parallel declare-researcher agents.**
+
+Spawn all 4 Task agents in the same response so they run in parallel. Each agent researches a specific domain.
+
+For each researcher, the prompt follows this pattern (fill in milestone-specific context):
+
+**STACK researcher:**
+
+```
+First, read agents/declare-researcher.md for your role and instructions.
+
+<research_domain>STACK</research_domain>
+
+<objective>
+Research the standard technology stack for implementing milestone M-XX: [milestoneTitle]
+
+Investigate: What libraries, frameworks, and tools form the standard stack for this domain? What versions are current? What are the "blessed" combinations experts use?
+</objective>
+
+<milestone_context>
+Milestone: M-XX — [milestoneTitle]
+Goal: [milestoneGoal]
+Realizes: [declarationIds and statements]
+[contextMdContent if exists]
+</milestone_context>
+
+<output>
+Write your findings to: .planning/milestones/M-XX-slug/STACK.md
+Use the RESEARCH.md structure from your instructions but title it "STACK Research".
+Do NOT commit — the synthesizer will commit everything together.
+</output>
+```
+
+**FEATURES researcher:**
+
+```
+First, read agents/declare-researcher.md for your role and instructions.
+
+<research_domain>FEATURES</research_domain>
+
+<objective>
+Research the features and capabilities required to implement milestone M-XX: [milestoneTitle]
+
+Investigate: What capabilities are table stakes (must-have)? What are differentiators? What should be deferred to later milestones? What do users/implementers actually need?
+</objective>
+
+<milestone_context>
+Milestone: M-XX — [milestoneTitle]
+Goal: [milestoneGoal]
+Realizes: [declarationIds and statements]
+[contextMdContent if exists]
+</milestone_context>
+
+<output>
+Write your findings to: .planning/milestones/M-XX-slug/FEATURES.md
+Use the RESEARCH.md structure from your instructions but title it "FEATURES Research".
+Do NOT commit — the synthesizer will commit everything together.
+</output>
+```
+
+**ARCHITECTURE researcher:**
+
+```
+First, read agents/declare-researcher.md for your role and instructions.
+
+<research_domain>ARCHITECTURE</research_domain>
+
+<objective>
+Research the architecture patterns for implementing milestone M-XX: [milestoneTitle]
+
+Investigate: What are the standard component structures? What data flows are typical? What design patterns do experts use? What project organization works best?
+</objective>
+
+<milestone_context>
+Milestone: M-XX — [milestoneTitle]
+Goal: [milestoneGoal]
+Realizes: [declarationIds and statements]
+[contextMdContent if exists]
+</milestone_context>
+
+<output>
+Write your findings to: .planning/milestones/M-XX-slug/ARCHITECTURE.md
+Use the RESEARCH.md structure from your instructions but title it "ARCHITECTURE Research".
+Do NOT commit — the synthesizer will commit everything together.
+</output>
+```
+
+**PITFALLS researcher:**
+
+```
+First, read agents/declare-researcher.md for your role and instructions.
+
+<research_domain>PITFALLS</research_domain>
+
+<objective>
+Research common pitfalls and failure modes when implementing milestone M-XX: [milestoneTitle]
+
+Investigate: What do beginners get wrong? What causes rewrites? What performance, security, or correctness traps exist? What should never be hand-rolled?
+</objective>
+
+<milestone_context>
+Milestone: M-XX — [milestoneTitle]
+Goal: [milestoneGoal]
+Realizes: [declarationIds and statements]
+[contextMdContent if exists]
+</milestone_context>
+
+<output>
+Write your findings to: .planning/milestones/M-XX-slug/PITFALLS.md
+Use the RESEARCH.md structure from your instructions but title it "PITFALLS Research".
+Do NOT commit — the synthesizer will commit everything together.
+</output>
+```
+
+Use one Task tool call per researcher. Spawn all 4 in the same response.
+
+**Step 6: After all 4 researchers complete, display interim summary.**
+
+```
+### Research Phase Complete
+
+| Domain | Status | Key Finding |
+|--------|--------|-------------|
+| STACK | Done | [brief summary from agent return] |
+| FEATURES | Done | [brief summary from agent return] |
+| ARCHITECTURE | Done | [brief summary from agent return] |
+| PITFALLS | Done | [brief summary from agent return] |
+
+Spawning synthesizer...
+```
+
+If any researcher returned `## RESEARCH BLOCKED`, surface the blocker to the user before spawning the synthesizer. Ask whether to continue with partial research or abort.
+
+**Step 7: Spawn declare-research-synthesizer.**
+
+```
+First, read agents/declare-research-synthesizer.md for your role and instructions.
+
+<objective>
+Synthesize the 4 research files for milestone M-XX: [milestoneTitle] into a unified RESEARCH.md.
+</objective>
+
+<milestone_context>
+Milestone: M-XX — [milestoneTitle]
+Goal: [milestoneGoal]
+Realizes: [declarationIds and statements]
+Milestone folder: .planning/milestones/M-XX-slug/
+</milestone_context>
+
+<research_files>
+- .planning/milestones/M-XX-slug/STACK.md
+- .planning/milestones/M-XX-slug/FEATURES.md
+- .planning/milestones/M-XX-slug/ARCHITECTURE.md
+- .planning/milestones/M-XX-slug/PITFALLS.md
+</research_files>
+
+<output>
+Write synthesized output to: .planning/milestones/M-XX-slug/RESEARCH.md
+Commit all research files (the 4 domain files + RESEARCH.md) together:
+  node dist/declare-tools.cjs commit "docs(M-XX): complete milestone research" --files .planning/milestones/M-XX-slug/
+</output>
+```
+
+Use one Task tool call for the synthesizer.
+
+**Step 8: Present results.**
+
+After the synthesizer returns `## SYNTHESIS COMPLETE`:
+
+```
+## Research Complete: M-XX — [milestoneTitle]
+
+**Files created:**
+- .planning/milestones/M-XX-slug/STACK.md
+- .planning/milestones/M-XX-slug/FEATURES.md
+- .planning/milestones/M-XX-slug/ARCHITECTURE.md
+- .planning/milestones/M-XX-slug/PITFALLS.md
+- .planning/milestones/M-XX-slug/RESEARCH.md
+
+**Overall confidence:** [from synthesizer]
+
+### Key Findings
+[3-5 bullets from synthesizer executive summary]
+
+### Planning Implications
+[Suggested action groups from synthesizer]
+
+**Next step:** Run `/declare:actions M-XX` to derive action plans informed by this research.
+```
+
+**Error handling:**
+
+- If `load-graph` returns an error: stop and ask user to run `/declare:init`.
+- If the milestone folder does not exist: run `mkdir -p .planning/milestones/M-XX-slug/` before spawning researchers.
+- If a researcher agent fails: log the failure, continue with the other 3 researchers, then inform the synthesizer about the missing file.
+- If synthesis is blocked: display the synthesizer's `## SYNTHESIS BLOCKED` message and ask the user how to proceed.
+- If RESEARCH.md already exists and user chose to re-research: the synthesizer will overwrite it.
+
+**Key patterns:**
+
+- 4 parallel researchers run concurrently for speed (stack, features, architecture, pitfalls).
+- Researchers write domain files but do NOT commit.
+- Synthesizer reads all 4 files, writes RESEARCH.md, and commits everything in one shot.
+- Research informs `/declare:actions` planning — always suggest it as next step.
+- CONTEXT.md (from `/declare:discuss`) constrains research when present.
+- Milestone folder path follows `.planning/milestones/M-XX-slug/` convention.
+- Use repo-relative paths in all file references and agent prompts.

package/commands/declare/resume.md

@@ -0,0 +1,146 @@
+---
+name: declare:resume
+description: Restore full project context from a previous session and route to the next action
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+---
+
+Restore project context from a previous session and route to the appropriate next action.
+
+**Step 1: Check for handoff file.**
+
+Check whether `.continue-here.md` exists at the project root:
+
+```bash
+ls .continue-here.md 2>/dev/null && echo "found" || echo "not found"
+```
+
+**Step 2a: If `.continue-here.md` exists — restore from handoff.**
+
+Read `.continue-here.md`.
+
+Display its contents in a clean, structured format:
+
+```
+## Resuming from Saved Context
+
+**Paused at:** [Paused timestamp from file]
+**Position:** [Position from file]
+
+### Active Milestone
+
+[Active milestone details from file]
+
+### Remaining Actions
+
+[Remaining actions list from file]
+
+### Decisions Made Last Session
+
+[Decisions from file]
+
+### Blockers
+
+[Blockers from file]
+```
+
+Then run `load-graph` to get fresh action statuses (actions may have changed since the pause):
+
+```bash
+node dist/declare-tools.cjs load-graph
+```
+
+If graph loads successfully, cross-reference: if any actions listed as PENDING in `.continue-here.md` are now DONE in the graph, note that:
+
+```
+Note: Since pausing, [A-XX] has been completed.
+```
+
+Proceed to Step 3 (routing).
+
+**Step 2b: If `.continue-here.md` does not exist — load from STATE.md.**
+
+Run:
+
+```bash
+node dist/declare-tools.cjs get-state
+```
+
+```bash
+node dist/declare-tools.cjs load-graph
+```
+
+If `get-state` returns an error (STATE.md not found):
+
+```
+No project state found. Run /declare:new-project to initialize.
+```
+
+Then stop.
+
+Display the state context:
+
+```
+## Resuming from STATE.md
+
+**Current Position:** [currentPosition]
+**Last Activity:** [most recent session history entry, if any]
+
+### Recent Work
+
+[recentWork from STATE.md]
+
+### Decisions
+
+[decisions from STATE.md, or "(none recorded)"]
+```
+
+Proceed to Step 3 (routing).
+
+**Step 3: Route to next action.**
+
+Evaluate the current project state and present the most relevant next step:
+
+**Route A — Pending actions on active milestone:**
+- "Ready to continue [M-XX] — [N] actions remaining."
+- Offer: "`/declare:execute [M-XX]` to continue"
+
+**Route B — Active milestone fully complete, not yet verified:**
+- "[M-XX] has all actions done but is not yet verified."
+- Offer: "`/declare:verify [M-XX]` to verify milestone truth"
+
+**Route C — Blocker recorded:**
+- "A blocker was recorded: [blocker text]"
+- Offer options: "Resolve it manually, then run `/declare:execute [M-XX]`" or "`/declare:status` to review the graph"
+
+**Route D — No active milestone:**
+- "No active milestone found."
+- Offer: "`/declare:new-milestone` to plan next milestone" or "`/declare:status` to review graph"
+
+**Route E — No project initialized:**
+- "Project not initialized."
+- Offer: "`/declare:new-project` to initialize"
+
+Present the route as a clear, single recommendation with an alternative if applicable.
+
+**Step 4: Record session resumption.**
+
+```bash
+node dist/declare-tools.cjs record-session --stopped-at "Resumed — [currentPosition]"
+```
+
+Do not display the output of this command.
+
+**Step 5: Clean up handoff file (if used).**
+
+If `.continue-here.md` was used in Step 2a and routing shows work is continuing normally, offer:
+
+```
+The .continue-here.md handoff file can be removed once you are fully resumed.
+Run: git rm .continue-here.md && git commit -m "chore: resume work — remove handoff file"
+```
+
+Do not remove it automatically — leave that to the user.

package/commands/declare/set-profile.md

@@ -0,0 +1,66 @@
+---
+description: Switch model profile for Declare agents (quality/balanced/budget)
+argument-hint: <profile>
+allowed-tools:
+  - Read
+  - Bash
+---
+
+Switch the model profile used by Declare agents. Controls which Claude model each agent uses, balancing output quality vs token spend.
+
+**Step 1: Validate the profile argument.**
+
+Parse `$ARGUMENTS` to extract the profile name. It must be one of: `quality`, `balanced`, `budget`.
+
+If the argument is missing or invalid, display the usage error and the profile table below, then stop.
+
+```
+Usage: /declare:set-profile <profile>
+
+Profiles:
+  quality   — claude-opus-4-5 for all agents
+  balanced  — claude-sonnet-4-5 for execution, claude-opus-4-5 for planning
+  budget    — claude-haiku-3-5 for execution, claude-sonnet-4-5 for planning
+```
+
+**Step 2: Read current profile.**
+
+```bash
+node dist/declare-tools.cjs config-get model_profile
+```
+
+Extract the current value (default "quality" if key not found).
+
+**Step 3: Apply the new profile.**
+
+```bash
+node dist/declare-tools.cjs config-set --key model_profile --value <profile>
+```
+
+If the command fails, display the error and stop.
+
+**Step 4: Display confirmation.**
+
+Show a confirmation with the model table:
+
+```
+Profile switched: [old] → [new]
+
+Model assignments for "[new]" profile:
+
+  Agent         Model
+  ───────────────────────────────────────────────
+  Planner       [planner model]
+  Plan-checker  [plan-checker model]
+  Executor      [executor model]
+  Verifier      [verifier model]
+  Researcher    [researcher model]
+
+Use /declare:settings to configure additional workflow options.
+```
+
+Model assignments by profile:
+
+- **quality**: all agents use `claude-opus-4-5`
+- **balanced**: planner=`claude-opus-4-5`, plan-checker=`claude-opus-4-5`, executor=`claude-sonnet-4-5`, verifier=`claude-sonnet-4-5`, researcher=`claude-opus-4-5`
+- **budget**: planner=`claude-sonnet-4-5`, plan-checker=`claude-sonnet-4-5`, executor=`claude-haiku-3-5`, verifier=`claude-haiku-3-5`, researcher=`claude-sonnet-4-5`

package/commands/declare/settings.md

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

@@ -12,7 +12,7 @@ Show the current state of the Declare project graph.
 **Step 1: Run the status tool.**
 
 ```bash
-node /Users/guilherme/Projects/get-shit-done/dist/declare-tools.cjs status
+node dist/declare-tools.cjs status
 ```
 
 Parse the JSON output.
@@ -45,18 +45,21 @@ For each validation error, provide a brief suggestion:
 - `cycle`: "Check for circular dependencies in your graph"
 - `broken_edge`: "The target node may have been removed -- update or remove the edge"
 
-**Coverage:** Show milestone plan coverage from the `coverage` field:
-- "Plan coverage: X of Y milestones have plans (Z%)"
-- If coverage is less than 100%, list milestones without plans and suggest: "Run `/declare:actions` to derive plans for uncovered milestones."
+**Last Activity:** Show the timestamp and commit message from the last git activity.
 
-**Health Indicators:** If `staleness` indicators exist, render them:
-- NO_PLAN: "[M-XX] has no action plan"
-- STALE: "[M-XX] plan not updated in N days"
-- COMPLETABLE: "[M-XX] all actions done -- consider marking milestone as DONE"
-- INCONSISTENT: "[M-XX] marked DONE but has incomplete actions"
+**Performance:** If the status output contains a `performance` field (non-null):
 
-If no staleness indicators: "All milestones healthy."
+Show the project rollup first:
+"Performance: [rollup.performance] (alignment: [rollup.alignment] x integrity: [rollup.integrity])"
 
-**Last Activity:** Show the timestamp and commit message from the last git activity.
+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.