mindforge-cc 9.0.0 → 10.0.0

package/.agent/workflows/mindforge-map-codebase.md

@@ -1,370 +0,0 @@
-<purpose>
-Orchestrate parallel codebase mapper agents to analyze codebase and produce structured documents in .planning/codebase/
-
-Each agent has fresh context, explores a specific focus area, and **writes documents directly**. The orchestrator only receives confirmation + line counts, then writes a summary.
-
-Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
-</purpose>
-
-<philosophy>
-**Why dedicated mapper agents:**
-- Fresh context per domain (no token contamination)
-- Agents write documents directly (no context transfer back to orchestrator)
-- Orchestrator only summarizes what was created (minimal context usage)
-- Faster execution (agents run simultaneously)
-
-**Document quality over length:**
-Include enough detail to be useful as reference. Prioritize practical examples (especially code patterns) over arbitrary brevity.
-
-**Always include file paths:**
-Documents are reference material for the agent when planning/executing. Always include actual file paths formatted with backticks: `src/services/user.ts`.
-</philosophy>
-
-<process>
-
-<step name="init_context" priority="first">
-Load codebase mapping context:
-
-```bash
-INIT=$(node ".agent/bin/mindforge-tools.cjs" init map-codebase)
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-```
-
-Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`.
-</step>
-
-<step name="check_existing">
-Check if .planning/codebase/ already exists using `has_maps` from init context.
-
-If `codebase_dir_exists` is true:
-```bash
-ls -la .planning/codebase/
-```
-
-**If exists:**
-
-```
-.planning/codebase/ already exists with these documents:
-[List files found]
-
-What's next?
-1. Refresh - Delete existing and remap codebase
-2. Update - Keep existing, only update specific documents
-3. Skip - Use existing codebase map as-is
-```
-
-Wait for user response.
-
-If "Refresh": Delete .planning/codebase/, continue to create_structure
-If "Update": Ask which documents to update, continue to spawn_agents (filtered)
-If "Skip": Exit workflow
-
-**If doesn't exist:**
-Continue to create_structure.
-</step>
-
-<step name="create_structure">
-Create .planning/codebase/ directory:
-
-```bash
-mkdir -p .planning/codebase
-```
-
-**Expected output files:**
-- STACK.md (from tech mapper)
-- INTEGRATIONS.md (from tech mapper)
-- ARCHITECTURE.md (from arch mapper)
-- STRUCTURE.md (from arch mapper)
-- CONVENTIONS.md (from quality mapper)
-- TESTING.md (from quality mapper)
-- CONCERNS.md (from concerns mapper)
-
-Continue to spawn_agents.
-</step>
-
-<step name="detect_runtime_capabilities">
-Before spawning agents, detect whether the current runtime supports the `Task` tool for subagent delegation.
-
-**Runtimes with Task tool:** Claude Code, Cursor, OpenCode (native subagent support via `Task` or `task`)
-**Runtimes WITHOUT Task tool:** Antigravity, Gemini CLI, Codex, and others
-
-**How to detect:** Check if you have access to a `Task` or `task` tool (either casing counts). If you do NOT have a Task/task tool (or only have tools like `browser_subagent` which is for web browsing, NOT code analysis):
-
-→ **Skip `spawn_agents` and `collect_confirmations`** — go directly to `sequential_mapping` instead.
-
-**CRITICAL:** Never use `browser_subagent` or `Explore` as a substitute for `Task`. The `browser_subagent` tool is exclusively for web page interaction and will fail for codebase analysis. If `Task` is unavailable, perform the mapping sequentially in-context.
-</step>
-
-<step name="spawn_agents" condition="Task tool is available">
-Spawn 4 parallel mindforge-codebase-mapper agents.
-
-Use Task tool with `subagent_type="mindforge-codebase-mapper"`, `model="{mapper_model}"`, and `run_in_background=true` for parallel execution.
-
-**CRITICAL:** Use the dedicated `mindforge-codebase-mapper` agent, NOT `Explore` or `browser_subagent`. The mapper agent writes documents directly.
-
-**Agent 1: Tech Focus**
-
-```
-Task(
-  subagent_type="mindforge-codebase-mapper",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase tech stack",
-  prompt="Focus: tech
-
-Analyze this codebase for technology stack and external integrations.
-
-Write these documents to .planning/codebase/:
-- STACK.md - Languages, runtime, frameworks, dependencies, configuration
-- INTEGRATIONS.md - External APIs, databases, auth providers, webhooks
-
-Explore thoroughly. Write documents directly using templates. Return confirmation only."
-)
-```
-
-**Agent 2: Architecture Focus**
-
-```
-Task(
-  subagent_type="mindforge-codebase-mapper",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase architecture",
-  prompt="Focus: arch
-
-Analyze this codebase architecture and directory structure.
-
-Write these documents to .planning/codebase/:
-- ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points
-- STRUCTURE.md - Directory layout, key locations, naming conventions
-
-Explore thoroughly. Write documents directly using templates. Return confirmation only."
-)
-```
-
-**Agent 3: Quality Focus**
-
-```
-Task(
-  subagent_type="mindforge-codebase-mapper",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase conventions",
-  prompt="Focus: quality
-
-Analyze this codebase for coding conventions and testing patterns.
-
-Write these documents to .planning/codebase/:
-- CONVENTIONS.md - Code style, naming, patterns, error handling
-- TESTING.md - Framework, structure, mocking, coverage
-
-Explore thoroughly. Write documents directly using templates. Return confirmation only."
-)
-```
-
-**Agent 4: Concerns Focus**
-
-```
-Task(
-  subagent_type="mindforge-codebase-mapper",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase concerns",
-  prompt="Focus: concerns
-
-Analyze this codebase for technical debt, known issues, and areas of concern.
-
-Write this document to .planning/codebase/:
-- CONCERNS.md - Tech debt, bugs, security, performance, fragile areas
-
-Explore thoroughly. Write document directly using template. Return confirmation only."
-)
-```
-
-Continue to collect_confirmations.
-</step>
-
-<step name="collect_confirmations">
-Wait for all 4 agents to complete using TaskOutput tool.
-
-**For each agent task_id returned by the Agent tool calls above:**
-```
-TaskOutput tool:
-  task_id: "{task_id from Agent result}"
-  block: true
-  timeout: 300000
-```
-
-Call TaskOutput for all 4 agents in parallel (single message with 4 TaskOutput calls).
-
-Once all TaskOutput calls return, read each agent's output file to collect confirmations.
-
-**Expected confirmation format from each agent:**
-```
-## Mapping Complete
-
-**Focus:** {focus}
-**Documents written:**
-- `.planning/codebase/{DOC1}.md` ({N} lines)
-- `.planning/codebase/{DOC2}.md` ({N} lines)
-
-Ready for orchestrator summary.
-```
-
-**What you receive:** Just file paths and line counts. NOT document contents.
-
-If any agent failed, note the failure and continue with successful documents.
-
-Continue to verify_output.
-</step>
-
-<step name="sequential_mapping" condition="Task/task tool is NOT available (e.g. Antigravity, Gemini CLI, Codex)">
-When the `Task` tool is unavailable, perform codebase mapping sequentially in the current context. This replaces `spawn_agents` and `collect_confirmations`.
-
-**IMPORTANT:** Do NOT use `browser_subagent`, `Explore`, or any browser-based tool. Use only file system tools (Read, Bash, Write, Grep, Glob, list_dir, view_file, grep_search, or equivalent tools available in your runtime).
-
-Perform all 4 mapping passes sequentially:
-
-**Pass 1: Tech Focus**
-- Explore package.json/Cargo.toml/go.mod/requirements.txt, config files, dependency trees
-- Write `.planning/codebase/STACK.md` — Languages, runtime, frameworks, dependencies, configuration
-- Write `.planning/codebase/INTEGRATIONS.md` — External APIs, databases, auth providers, webhooks
-
-**Pass 2: Architecture Focus**
-- Explore directory structure, entry points, module boundaries, data flow
-- Write `.planning/codebase/ARCHITECTURE.md` — Pattern, layers, data flow, abstractions, entry points
-- Write `.planning/codebase/STRUCTURE.md` — Directory layout, key locations, naming conventions
-
-**Pass 3: Quality Focus**
-- Explore code style, error handling patterns, test files, CI config
-- Write `.planning/codebase/CONVENTIONS.md` — Code style, naming, patterns, error handling
-- Write `.planning/codebase/TESTING.md` — Framework, structure, mocking, coverage
-
-**Pass 4: Concerns Focus**
-- Explore TODOs, known issues, fragile areas, security patterns
-- Write `.planning/codebase/CONCERNS.md` — Tech debt, bugs, security, performance, fragile areas
-
-Use the same document templates as the `mindforge-codebase-mapper` agent. Include actual file paths formatted with backticks.
-
-Continue to verify_output.
-</step>
-
-<step name="verify_output">
-Verify all documents created successfully:
-
-```bash
-ls -la .planning/codebase/
-wc -l .planning/codebase/*.md
-```
-
-**Verification checklist:**
-- All 7 documents exist
-- No empty documents (each should have >20 lines)
-
-If any documents missing or empty, note which agents may have failed.
-
-Continue to scan_for_secrets.
-</step>
-
-<step name="scan_for_secrets">
-**CRITICAL SECURITY CHECK:** Scan output files for accidentally leaked secrets before committing.
-
-Run secret pattern detection:
-
-```bash
-# Check for common API key patterns in generated docs
-grep -E '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|sk_test_[a-zA-Z0-9]+|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]+|AKIA[A-Z0-9]{16}|xox[baprs]-[a-zA-Z0-9-]+|-----BEGIN.*PRIVATE KEY|eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.)' .planning/codebase/*.md 2>/dev/null && SECRETS_FOUND=true || SECRETS_FOUND=false
-```
-
-**If SECRETS_FOUND=true:**
-
-```
-⚠️  SECURITY ALERT: Potential secrets detected in codebase documents!
-
-Found patterns that look like API keys or tokens in:
-[show grep output]
-
-This would expose credentials if committed.
-
-**Action required:**
-1. Review the flagged content above
-2. If these are real secrets, they must be removed before committing
-3. Consider adding sensitive files to Claude Code "Deny" permissions
-
-Pausing before commit. Reply "safe to proceed" if the flagged content is not actually sensitive, or edit the files first.
-```
-
-Wait for user confirmation before continuing to commit_codebase_map.
-
-**If SECRETS_FOUND=false:**
-
-Continue to commit_codebase_map.
-</step>
-
-<step name="commit_codebase_map">
-Commit the codebase map:
-
-```bash
-node ".agent/bin/mindforge-tools.cjs" commit "docs: map existing codebase" --files .planning/codebase/*.md
-```
-
-Continue to offer_next.
-</step>
-
-<step name="offer_next">
-Present completion summary and next steps.
-
-**Get line counts:**
-```bash
-wc -l .planning/codebase/*.md
-```
-
-**Output format:**
-
-```
-Codebase mapping complete.
-
-Created .planning/codebase/:
-- STACK.md ([N] lines) - Technologies and dependencies
-- ARCHITECTURE.md ([N] lines) - System design and patterns
-- STRUCTURE.md ([N] lines) - Directory layout and organization
-- CONVENTIONS.md ([N] lines) - Code style and patterns
-- TESTING.md ([N] lines) - Test structure and practices
-- INTEGRATIONS.md ([N] lines) - External services and APIs
-- CONCERNS.md ([N] lines) - Technical debt and issues
-
-
----
-
-## ▶ Next Up
-
-**Initialize project** — use codebase context for planning
-
-`/mindforge-new-project`
-
-<sub>`/clear` first → fresh context window</sub>
-
----
-
-**Also available:**
-- Re-run mapping: `/mindforge-map-codebase`
-- Review specific file: `cat .planning/codebase/STACK.md`
-- Edit any document before proceeding
-
----
-```
-
-End workflow.
-</step>
-
-</process>
-
-<success_criteria>
-- .planning/codebase/ directory created
-- If Task tool available: 4 parallel mindforge-codebase-mapper agents spawned with run_in_background=true
-- If Task tool NOT available: 4 sequential mapping passes performed inline (never using browser_subagent)
-- All 7 codebase documents exist
-- No empty documents (each should have >20 lines)
-- Clear completion summary with line counts
-- User offered clear next steps in MindForge style
-</success_criteria>

package/.agent/workflows/mindforge-milestone-summary.md

@@ -1,223 +0,0 @@
-# Milestone Summary Workflow
-
-Generate a comprehensive, human-friendly project summary from completed milestone artifacts.
-Designed for team onboarding — a new contributor can read the output and understand the entire project.
-
----
-
-## Step 1: Resolve Version
-
-```bash
-VERSION="$ARGUMENTS"
-```
-
-If `$ARGUMENTS` is empty:
-1. Check `.planning/STATE.md` for current milestone version
-2. Check `.planning/milestones/` for the latest archived version
-3. If neither found, check if `.planning/ROADMAP.md` exists (project may be mid-milestone)
-4. If nothing found: error "No milestone found. Run /mindforge-new-project or /mindforge-new-milestone first."
-
-Set `VERSION` to the resolved version (e.g., "1.0").
-
-## Step 2: Locate Artifacts
-
-Determine whether the milestone is **archived** or **current**:
-
-**Archived milestone** (`.planning/milestones/v{VERSION}-ROADMAP.md` exists):
-```
-ROADMAP_PATH=".planning/milestones/v${VERSION}-ROADMAP.md"
-REQUIREMENTS_PATH=".planning/milestones/v${VERSION}-REQUIREMENTS.md"
-AUDIT_PATH=".planning/milestones/v${VERSION}-MILESTONE-AUDIT.md"
-```
-
-**Current/in-progress milestone** (no archive yet):
-```
-ROADMAP_PATH=".planning/ROADMAP.md"
-REQUIREMENTS_PATH=".planning/REQUIREMENTS.md"
-AUDIT_PATH=".planning/v${VERSION}-MILESTONE-AUDIT.md"
-```
-
-Note: The audit file moves to `.planning/milestones/` on archive (per `complete-milestone` workflow). Check both locations as a fallback.
-
-**Always available:**
-```
-PROJECT_PATH=".planning/PROJECT.md"
-RETRO_PATH=".planning/RETROSPECTIVE.md"
-STATE_PATH=".planning/STATE.md"
-```
-
-Read all files that exist. Missing files are fine — the summary adapts to what's available.
-
-## Step 3: Discover Phase Artifacts
-
-Find all phase directories:
-
-```bash
-mindforge-tools.cjs init progress
-```
-
-This returns phase metadata. For each phase in the milestone scope:
-
-- Read `{phase_dir}/{padded}-SUMMARY.md` if it exists — extract `one_liner`, `accomplishments`, `decisions`
-- Read `{phase_dir}/{padded}-VERIFICATION.md` if it exists — extract status, gaps, deferred items
-- Read `{phase_dir}/{padded}-CONTEXT.md` if it exists — extract key decisions from `<decisions>` section
-- Read `{phase_dir}/{padded}-RESEARCH.md` if it exists — note what was researched
-
-Track which phases have which artifacts.
-
-**If no phase directories exist** (empty milestone or pre-build state): skip to Step 5 and generate a minimal summary noting "No phases have been executed yet." Do not error — the summary should still capture PROJECT.md and ROADMAP.md content.
-
-## Step 4: Gather Git Statistics
-
-Try each method in order until one succeeds:
-
-**Method 1 — Tagged milestone** (check first):
-```bash
-git tag -l "v${VERSION}" | head -1
-```
-If the tag exists:
-```bash
-git log v${VERSION} --oneline | wc -l
-git diff --stat $(git log --format=%H --reverse v${VERSION} | head -1)..v${VERSION}
-```
-
-**Method 2 — STATE.md date range** (if no tag):
-Read STATE.md and extract the `started_at` or earliest session date. Use it as the `--since` boundary:
-```bash
-git log --oneline --since="<started_at_date>" | wc -l
-```
-
-**Method 3 — Earliest phase commit** (if STATE.md has no date):
-Find the earliest `.planning/phases/` commit:
-```bash
-git log --oneline --diff-filter=A -- ".planning/phases/" | tail -1
-```
-Use that commit's date as the start boundary.
-
-**Method 4 — Skip stats** (if none of the above work):
-Report "Git statistics unavailable — no tag or date range could be determined." This is not an error — the summary continues without the Stats section.
-
-Extract (when available):
-- Total commits in milestone
-- Files changed, insertions, deletions
-- Timeline (start date → end date)
-- Contributors (from git log authors)
-
-## Step 5: Generate Summary Document
-
-Write to `.planning/reports/MILESTONE_SUMMARY-v${VERSION}.md`:
-
-```markdown
-# Milestone v{VERSION} — Project Summary
-
-**Generated:** {date}
-**Purpose:** Team onboarding and project review
-
----
-
-## 1. Project Overview
-
-{From PROJECT.md: "What This Is", core value proposition, target users}
-{If mid-milestone: note which phases are complete vs in-progress}
-
-## 2. Architecture & Technical Decisions
-
-{From CONTEXT.md files across phases: key technical choices}
-{From SUMMARY.md decisions: patterns, libraries, frameworks chosen}
-{From PROJECT.md: tech stack if documented}
-
-Present as a bulleted list of decisions with brief rationale:
-- **Decision:** {what was chosen}
-  - **Why:** {rationale from CONTEXT.md}
-  - **Phase:** {which phase made this decision}
-
-## 3. Phases Delivered
-
-| Phase | Name | Status | One-Liner |
-|-------|------|--------|-----------|
-{For each phase: number, name, status (complete/in-progress/planned), one_liner from SUMMARY.md}
-
-## 4. Requirements Coverage
-
-{From REQUIREMENTS.md: list each requirement with status}
-- ✅ {Requirement met}
-- ⚠️ {Requirement partially met — note gap}
-- ❌ {Requirement not met — note reason}
-
-{If MILESTONE-AUDIT.md exists: include audit verdict}
-
-## 5. Key Decisions Log
-
-{Aggregate from all CONTEXT.md <decisions> sections}
-{Each decision with: ID, description, phase, rationale}
-
-## 6. Tech Debt & Deferred Items
-
-{From VERIFICATION.md files: gaps found, anti-patterns noted}
-{From RETROSPECTIVE.md: lessons learned, what to improve}
-{From CONTEXT.md <deferred> sections: ideas parked for later}
-
-## 7. Getting Started
-
-{Entry points for new contributors:}
-- **Run the project:** {from PROJECT.md or SUMMARY.md}
-- **Key directories:** {from codebase structure}
-- **Tests:** {test command from PROJECT.md or GEMINI.md}
-- **Where to look first:** {main entry points, core modules}
-
----
-
-## Stats
-
-- **Timeline:** {start} → {end} ({duration})
-- **Phases:** {count complete} / {count total}
-- **Commits:** {count}
-- **Files changed:** {count} (+{insertions} / -{deletions})
-- **Contributors:** {list}
-```
-
-## Step 6: Write and Commit
-
-**Overwrite guard:** If `.planning/reports/MILESTONE_SUMMARY-v${VERSION}.md` already exists, ask the user:
-> "A milestone summary for v{VERSION} already exists. Overwrite it, or view the existing one?"
-If "view": display existing file and skip to Step 8 (interactive mode). If "overwrite": proceed.
-
-Create the reports directory if needed:
-```bash
-mkdir -p .planning/reports
-```
-
-Write the summary, then commit:
-```bash
-mindforge-tools.cjs commit "docs(v${VERSION}): generate milestone summary for onboarding" \
-  --files ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md"
-```
-
-## Step 7: Present Summary
-
-Display the full summary document inline.
-
-## Step 8: Offer Interactive Mode
-
-After presenting the summary:
-
-> "Summary written to `.planning/reports/MILESTONE_SUMMARY-v{VERSION}.md`.
->
-> I have full context from the build artifacts. Want to ask anything about the project?
-> Architecture decisions, specific phases, requirements, tech debt — ask away."
-
-If the user asks questions:
-- Answer from the artifacts already loaded (CONTEXT.md, SUMMARY.md, VERIFICATION.md, etc.)
-- Reference specific files and decisions
-- Stay grounded in what was actually built (not speculation)
-
-If the user is done:
-- Suggest next steps: `/mindforge-new-milestone`, `/mindforge-progress`, or sharing the summary with the team
-
-## Step 9: Update STATE.md
-
-```bash
-mindforge-tools.cjs state record-session \
-  --stopped-at "Milestone v${VERSION} summary generated" \
-  --resume-file ".planning/reports/MILESTONE_SUMMARY-v${VERSION}.md"
-```