declare-cc 0.1.0 → 0.3.0

package/commands/declare/map-codebase.md

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

@@ -15,7 +15,7 @@ Derive milestones by working backward from declared futures.
 **Step 1: Load current graph state.**
 
 ```bash
-node /Users/guilherme/Projects/get-shit-done/dist/declare-tools.cjs load-graph
+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.
@@ -33,7 +33,7 @@ Note all declarations and milestones from the graph -- the workflow needs full c
 
 Read and follow the full workflow instructions:
 
-@/Users/guilherme/Projects/get-shit-done/workflows/milestones.md
+@workflows/milestones.md
 
 Pass the loaded graph state into the workflow so it knows about existing declarations and milestones.
 
@@ -50,15 +50,15 @@ Which of these milestones should we create for D-XX?
 - [ ] Milestone C -- because [reason]
 ```
 
-**Step 5: Persist each accepted milestone.**
+**Step 5: Persist all accepted milestones in one batch call.**
 
-For each checked milestone:
+Build a JSON array of the checked milestones, then create them all at once:
 
 ```bash
-node /Users/guilherme/Projects/get-shit-done/dist/declare-tools.cjs add-milestone --title "Milestone Title" --realizes "D-XX"
+node dist/declare-tools.cjs add-milestones --json '[{"title":"Milestone A","realizes":"D-XX"},{"title":"Milestone B","realizes":"D-XX"}]'
 ```
 
-Parse the JSON output to confirm the milestone was created and note its assigned ID.
+This creates all milestones and makes a single git commit. Parse the JSON output — it returns `{ milestones: [{ id, title, realizes, status }], committed, hash }`.
 
 **Step 6: Inconsistency flagging.**
 
@@ -74,7 +74,7 @@ After all declarations processed:
 
 1. Reload the graph to get final counts:
 ```bash
-node /Users/guilherme/Projects/get-shit-done/dist/declare-tools.cjs load-graph
+node dist/declare-tools.cjs load-graph
 ```
 
 2. Show summary: declarations processed, milestones derived.

package/commands/declare/new-milestone.md

@@ -0,0 +1,172 @@
+---
+description: Start a new Declare milestone cycle — archive declarations, 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