declare-cc 1.0.8 → 2.0.0

package/commands/declare/help.md

@@ -1,31 +0,0 @@
----
-description: Show available Declare commands
-allowed-tools:
-  - Read
-  - Bash
----
-
-Show the Declare command reference.
-
-**Step 1: Run the help tool.**
-
-```bash
-node dist/declare-tools.cjs help
-```
-
-Parse the JSON output.
-
-**Step 2: Format the help display.**
-
-Display a clean command reference:
-
-**Header:** "Declare -- Future-first project planning"
-
-**Brief description:** Declare lets you define what you want to be true about the future, then builds a causal graph of milestones and actions to get there. It validates structural integrity and tracks progress through the graph.
-
-**Available Commands:** For each command in the JSON output, display:
-- Command name (bold)
-- Description
-- Usage example
-
-**Version:** Show the version number at the bottom.

package/commands/declare/init.md

@@ -1,39 +0,0 @@
----
-description: Initialize Declare project with future declarations and graph structure
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
----
-
-Initialize a Declare project in the current working directory.
-
-**Step 1: Run the init tool.**
-
-```bash
-node dist/declare-tools.cjs init $ARGUMENTS
-```
-
-Parse the JSON output. It will contain:
-- `initialized`: whether initialization succeeded
-- `created`: list of files that were created
-- `existing`: list of files that already existed
-- `committed`: whether a git commit was made
-
-**Step 2: Handle existing files.**
-
-If the `existing` array is non-empty, present the existing files to the user and ask which ones they want to keep vs replace. For each file they want to replace:
-1. Delete the existing file
-2. Re-run `node dist/declare-tools.cjs init` to recreate it
-
-**Step 3: Report results.**
-
-Show the user a brief summary of what was created (file name + one-line purpose). If a commit was made, mention the hash.
-
-Then immediately prompt the user to start declaring:
-
-> **Ready. Run `/declare:future` to declare what's true when this project succeeds.**
-
-Do not suggest editing files manually or running `/declare:status`. The next step is always `/declare:future`.

package/commands/declare/map-codebase.md

@@ -1,149 +0,0 @@
----
-name: declare:map-codebase
-description: Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents
-argument-hint: "[optional: specific area to map, e.g., 'api' or 'auth']"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - Task
----
-
-<objective>
-Analyze existing codebase using parallel declare-codebase-mapper agents to produce structured codebase documents.
-
-Each mapper agent explores a focus area and **writes documents directly** to `.planning/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.
-
-Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
-</objective>
-
-<context>
-Focus area: $ARGUMENTS (optional - if provided, tells agents to focus on specific subsystem)
-
-**Load project state if exists:**
-Check for .planning/STATE.md - loads context if project already initialized
-
-**This command can run:**
-- Before /declare:init (brownfield codebases) - creates codebase map first
-- After /declare:init (greenfield codebases) - updates codebase map as code evolves
-- Anytime to refresh codebase understanding
-</context>
-
-<when_to_use>
-**Use map-codebase for:**
-- Brownfield projects before initialization (understand existing code first)
-- Refreshing codebase map after significant changes
-- Onboarding to an unfamiliar codebase
-- Before major refactoring (understand current state)
-- When STATE.md references outdated codebase info
-
-**Skip map-codebase for:**
-- Greenfield projects with no code yet (nothing to map)
-- Trivial codebases (<5 files)
-</when_to_use>
-
-<process>
-
-## Step 1: Check existing map
-
-```bash
-ls .planning/codebase/ 2>/dev/null
-```
-
-If `.planning/codebase/` already exists and contains documents, ask the user:
-- **Refresh** — re-run all 4 agents and overwrite existing documents
-- **Update** — re-run only specific focus areas (ask which ones)
-- **Skip** — use existing map as-is and proceed
-
-If directory doesn't exist or is empty, proceed directly to Step 2.
-
-## Step 2: Create directory structure
-
-```bash
-mkdir -p .planning/codebase
-```
-
-## Step 3: Secret scan
-
-Before spawning agents, verify no secrets are in scope:
-
-```bash
-# Check for .env files in working directory
-ls .env* 2>/dev/null && echo "WARNING: .env files present - agents will note existence only, never read contents"
-```
-
-Remind yourself: agents must never read `.env`, credentials, keys, or any file listed in `<forbidden_files>` within the mapper agent definition.
-
-## Step 4: Spawn 4 parallel mapper agents
-
-Spawn all four agents simultaneously using the Task tool:
-
-```
-Agent 1: declare-codebase-mapper
-  Focus: tech
-  Task: Analyze technology stack and external integrations. Write STACK.md and INTEGRATIONS.md to .planning/codebase/
-
-Agent 2: declare-codebase-mapper
-  Focus: arch
-  Task: Analyze architecture and file structure. Write ARCHITECTURE.md and STRUCTURE.md to .planning/codebase/
-
-Agent 3: declare-codebase-mapper
-  Focus: quality
-  Task: Analyze coding conventions and testing patterns. Write CONVENTIONS.md and TESTING.md to .planning/codebase/
-
-Agent 4: declare-codebase-mapper
-  Focus: concerns
-  Task: Identify technical debt and issues. Write CONCERNS.md to .planning/codebase/
-```
-
-Wait for all 4 agents to complete. Collect only their confirmation messages (NOT document contents).
-
-## Step 5: Verify output
-
-```bash
-wc -l .planning/codebase/*.md 2>/dev/null
-```
-
-Confirm all 7 documents exist:
-- `.planning/codebase/STACK.md`
-- `.planning/codebase/INTEGRATIONS.md`
-- `.planning/codebase/ARCHITECTURE.md`
-- `.planning/codebase/STRUCTURE.md`
-- `.planning/codebase/CONVENTIONS.md`
-- `.planning/codebase/TESTING.md`
-- `.planning/codebase/CONCERNS.md`
-
-If any document is missing, re-spawn the relevant agent for that focus area.
-
-## Step 6: Commit codebase map
-
-```bash
-git add .planning/codebase/
-git commit -m "docs: add codebase map (.planning/codebase/)"
-```
-
-If git is not initialized, skip this step and note it.
-
-## Step 7: Report and next steps
-
-Report a summary of what was mapped:
-- Documents created and their line counts
-- Key findings surfaced (from agent confirmations only — do NOT read document contents)
-
-Offer next steps based on context:
-- If no .planning/STATE.md: suggest `/declare:init` to initialize project planning
-- If .planning/STATE.md exists: suggest `/declare:plan-phase` to plan next work using the map
-- If significant concerns were found: highlight that CONCERNS.md has issues worth reviewing before planning
-
-</process>
-
-<success_criteria>
-- [ ] .planning/codebase/ directory created
-- [ ] All 7 codebase documents written by mapper agents
-- [ ] Documents follow template structure
-- [ ] Parallel agents completed without errors
-- [ ] Codebase map committed to git
-- [ ] User knows next steps
-</success_criteria>

package/commands/declare/milestones.md

@@ -1,98 +0,0 @@
----
-description: Derive milestones backward from declared futures
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
-argument-hint: "[D-XX]"
----
-
-Derive milestones by working backward from declared futures.
-
-**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 declarations exist in the graph, tell the user to run `/declare:future` first and stop.
-
-Note all declarations and milestones from the graph -- the workflow needs full context.
-
-**Step 2: Scope review (first-time derivation only).**
-
-Skip this step if `$ARGUMENTS` contains a specific declaration ID (e.g., `D-01`) — targeted re-derivation skips scope review.
-
-Otherwise, check if any milestones already exist in the graph. If milestones already exist, this is a re-derivation — skip scope review and proceed to Step 3.
-
-If this is the first time deriving milestones (no milestones in the graph yet), run the scope review workflow before deriving anything:
-
-@workflows/scope.md
-
-Pass all declarations from the loaded graph into the scope workflow. After the scope is confirmed, continue to Step 3.
-
-**Step 3: Determine derivation scope.**
-
-- If `$ARGUMENTS` contains a declaration ID (e.g., `D-01`), derive only for that specific declaration.
-- Otherwise, derive for all declarations that have no milestones yet (declarations with empty milestones arrays in the graph).
-
-**Step 4: Follow the milestone derivation workflow.**
-
-Read and follow the full workflow instructions:
-
-@workflows/milestones.md
-
-Pass the loaded graph state into the workflow so it knows about existing declarations and milestones.
-
-**Step 5: Per-declaration milestone confirmation with checkboxes.**
-
-After the workflow proposes milestones for a declaration, present them using AskUserQuestion with multi-select checkboxes:
-
-```
-Use AskUserQuestion to present proposed milestones as a checklist. The user checks which milestones to accept. Format:
-
-Which of these milestones should we create for D-XX?
-- [ ] Milestone A -- because [reason]
-- [ ] Milestone B -- because [reason]
-- [ ] Milestone C -- because [reason]
-```
-
-**Step 6: Persist all accepted milestones in one batch call.**
-
-Build a JSON array of the checked milestones, then create them all at once:
-
-```bash
-node dist/declare-tools.cjs add-milestones --json '[{"title":"Milestone A","realizes":"D-XX"},{"title":"Milestone B","realizes":"D-XX"}]'
-```
-
-This creates all milestones and makes a single git commit. Parse the JSON output — it returns `{ milestones: [{ id, title, realizes, status }], committed, hash }`.
-
-**Step 7: Inconsistency flagging.**
-
-If milestones already exist for a declaration being processed (re-derivation case):
-- Show existing milestones for that declaration
-- Ask the user if they still align with the declaration
-- Offer to keep, re-derive, or adjust
-- Do NOT auto-reconcile -- the user decides what to update
-
-**Step 8: Show summary and suggest next step.**
-
-After all declarations 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 (dashboard updates live when files change):
-```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: declarations processed, milestones derived.
-4. Suggest: "Milestones are live in the dashboard → http://localhost:3847 — Run `/declare:actions` to derive action plans."

package/commands/declare/new-cycle.md

@@ -1,172 +0,0 @@
----
-description: Start a new Declare cycle — archive current declarations to FUTURE-ARCHIVE.md, reset FUTURE.md and MILESTONES.md, preserve PROJECT.md and STATE.md
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - AskUserQuestion
-argument-hint: "[milestone focus, e.g., 'v1.1 Web Dashboard']"
----
-
-Start a new Declare milestone cycle. Archives the current declarations to FUTURE-ARCHIVE.md, resets FUTURE.md and MILESTONES.md for fresh declarations, and preserves project memory in PROJECT.md and STATE.md.
-
-**Step 0: Determine milestone focus.**
-
-Parse `$ARGUMENTS` for a milestone name or focus description.
-
-If `$ARGUMENTS` is empty or contains no useful text, ask: "What's the focus of this next milestone? (e.g., 'v1.1 Web Dashboard', 'v2.0 Collaborative Features')"
-
-**Step 1: Load project context.**
-
-Read the current project state:
-
-```bash
-cat .planning/PROJECT.md
-cat .planning/STATE.md
-cat .planning/FUTURE.md
-cat .planning/MILESTONES.md
-```
-
-If `.planning/PROJECT.md` does not exist, tell the user to run `/declare:init` first and stop.
-
-Present a summary of what was in the current milestone:
-
-```
-## Current Milestone Summary
-
-**Declarations ([N] total):**
-- D-01: [statement snippet]
-- D-02: [statement snippet]
-
-**Milestones ([N] total):**
-- M-XX: [title] ([status])
-- M-YY: [title] ([status])
-
-**About to start:** [milestone focus from Step 0]
-```
-
-**Step 2: Archive previous declarations to FUTURE-ARCHIVE.md.**
-
-Read `.planning/FUTURE.md` to get all current declarations.
-
-Append the current declarations to `.planning/FUTURE-ARCHIVE.md` (create if it does not exist), with a versioned header:
-
-```markdown
----
-
-## Archived: [previous milestone version or "v[N]"] — [today's date]
-
-**Milestone focus:** [previous milestone focus, if known from PROJECT.md or STATE.md]
-
-[Full content of current FUTURE.md — all declarations as-is]
-```
-
-After appending, verify the archive was written:
-
-```bash
-cat .planning/FUTURE-ARCHIVE.md | tail -20
-```
-
-Report: "Archived [N] declarations to .planning/FUTURE-ARCHIVE.md"
-
-**Step 3: Reset FUTURE.md.**
-
-Overwrite `.planning/FUTURE.md` with an empty template:
-
-```markdown
-# Future: [project name from PROJECT.md]
-
-<!-- Declarations for [new milestone focus] will be added here. -->
-<!-- Run /declare:future to declare the new milestone's futures. -->
-```
-
-Extract the project name from `.planning/PROJECT.md` (look for the `# Future:` or `# Project:` heading, or use the directory name as fallback).
-
-**Step 4: Reset MILESTONES.md.**
-
-Overwrite `.planning/MILESTONES.md` with an empty table:
-
-```markdown
-# Milestones: [project name]
-
-## Milestones
-
-| ID | Title | Status | Realizes | Plan |
-|----|-------|--------|----------|------|
-```
-
-This table is empty — new milestones will be derived from the new declarations via `/declare:milestones`.
-
-**Step 5: Update STATE.md session.**
-
-Read `.planning/STATE.md` and update the session fields. Preserve all existing content (project context, decisions, todos) — only update:
-
-- `Last session`: today's date
-- `Stopped at`: "Started [new milestone focus] — awaiting new declarations"
-- If there is a `## Current Position` or `## Status` section, update it to reflect the new cycle beginning
-
-Write the updated STATE.md back.
-
-Example update (preserve all other sections unchanged):
-
-```markdown
-## Session Continuity
-
-Last session: [today]
-Stopped at: Started [new milestone focus] — awaiting new declarations via /declare:future
-```
-
-**Step 6: Commit reset.**
-
-Stage and commit the reset files:
-
-```bash
-git add .planning/FUTURE.md .planning/MILESTONES.md .planning/FUTURE-ARCHIVE.md .planning/STATE.md
-git commit -m "chore: start new milestone cycle -- [new milestone focus]
-
-- FUTURE-ARCHIVE.md: archived [N] declarations from previous cycle
-- FUTURE.md: reset for new declarations
-- MILESTONES.md: reset for new milestones
-- STATE.md: updated session
-"
-```
-
-**Step 7: Show next steps.**
-
-```
-## New Milestone Cycle Started
-
-**Focus:** [new milestone focus]
-
-**What was preserved:**
-- .planning/PROJECT.md (project memory, validated requirements, decisions)
-- .planning/STATE.md (session continuity, todos, blockers)
-
-**What was reset:**
-- .planning/FUTURE.md (empty — ready for new declarations)
-- .planning/MILESTONES.md (empty — ready for derived milestones)
-- .planning/FUTURE-ARCHIVE.md (archived [N] previous declarations)
-
----
-
-**Next step:** Declare the futures for this milestone.
-
-Run /declare:future
-```
-
-**Error handling:**
-
-- If `.planning/FUTURE.md` is already empty or has no declarations, warn: "FUTURE.md appears to be empty — nothing to archive. Continue to reset MILESTONES.md? (yes/no)"
-- If `.planning/MILESTONES.md` still has PENDING or ACTIVE milestones, warn: "Warning: [N] milestones are not yet complete. Run /declare:complete-milestone first to archive the current version, then run /declare:new-milestone."
-- If git commit fails, display the error and instruct the user to commit manually.
-
-**Key patterns:**
-
-- PROJECT.md and STATE.md are project memory — they persist across milestone cycles and are NEVER reset.
-- FUTURE.md and MILESTONES.md are milestone-scoped — they reset every cycle.
-- FUTURE-ARCHIVE.md is append-only — previous declarations are never deleted, only archived.
-- This command does NOT create new declarations — it resets the slate for /declare:future.
-- Scope of the next milestone is set by asking "What's the focus?" not by writing declarations yet.
-- After this command: /declare:future -> /declare:milestones -> /declare:actions -> /declare:execute