npm - mindforge-cc - Versions diffs - 8.2.0 → 10.0.0 - Mend

mindforge-cc 8.2.0 → 10.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1667) hide show

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

@@ -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 DELETED Viewed

@@ -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"
-```