mindforge-cc 2.0.0 → 2.1.1

package/.claude/commands/mindforge/debug.md

@@ -1,126 +1,34 @@
-# MindForge — Debug Command
-# Usage: /mindforge:debug [description]
-
-Systematic debugging using the Debug Specialist persona with full RCA protocol.
-
-## Activation
-
-Load `.mindforge/personas/debug-specialist.md` immediately.
-This command runs entirely in that persona for its full duration.
-
-## Step 1 — Intake
-
-Ask the user:
-1. "Describe the problem. What is happening vs. what should happen?"
-2. "Can you reproduce it reliably? If yes: what are the exact steps?"
-3. "When did this start? Was it working before? What changed?"
-4. "Do you have an error message or stack trace? Paste it here."
-
-Capture all answers before proceeding.
-
-## Step 2 — Triage
-
-Classify the issue immediately:
-- **Regression** (was working, now broken) → check recent commits
-- **Never worked** (new feature failing) → check the plan and verify step
-- **Environment issue** (works locally, fails in CI) → check environment diffs
-- **Data issue** (specific data causes failure) → check data shape assumptions
-- **Integration issue** (fails when calling external service) → check contracts
-
-Report classification to user: "This looks like a [type] issue. Here's my approach..."
-
-## Step 3 — Follow Debug Specialist protocol
-
-Execute the full protocol from `debug-specialist.md`:
-1. Reproduce
-2. Isolate
-3. Read the error
-4. Check recent changes
-5. Instrument
-6. Form hypothesis
-7. Test hypothesis (write a failing test)
-8. Fix
-9. Verify (test from step 7 now passes, no regressions)
-10. Document
-
-At each step, report what was found before moving to the next step.
-Do not skip steps or combine them.
-
-## Step 3b — Full test suite verification (mandatory)
-After the fix and targeted verify pass, run the project's full test suite.
-Do not mark the debug task complete if any tests fail.
-
-## Step 4 — Check recent git history
-
-```bash
-git log --oneline -20
-git diff HEAD~[N] HEAD -- [suspected file]
-```
-
-If a recent commit is the likely cause, show the user the specific diff.
-
-## Step 5 — Write the RCA report
-
-Create `.planning/phases/[current-phase]/DEBUG-[timestamp].md`:
-
-```markdown
-# Debug Report — [short description]
-
-## Date
-[ISO-8601]
-
-## Problem
-[User's description + what was verified during debugging]
-
-## Root cause category
-[Logic error / Data error / Integration error / Concurrency error /
-Configuration error / Dependency error]
-
-## Root cause
-[Precise description of what the actual cause was]
-
-## Evidence
-- [How the root cause was confirmed]
-- [Failing test that proved the bug: file:line]
-
-## Fix applied
-- File: [path]
-- Change: [description]
-- Commit: [SHA]
-
-## Regression test
-[Test written to prevent this from recurring: file:line]
-
-## Prevention
-[What should change in process/code to prevent this class of bug]
-```
-
-## Step 6 — Write AUDIT entry
-
-```json
-{
-  "id": "uuid",
-  "timestamp": "ISO-8601",
-  "event": "debug_completed",
-  "agent": "mindforge-debug-specialist",
-  "phase": [current phase or null],
-  "session_id": "sess_abc",
-  "issue_type": "regression",
-  "root_cause_category": "Logic error",
-  "root_cause_summary": "[one sentence]",
-  "commit_sha": "[fix commit sha]",
-  "regression_test_added": true,
-  "report_path": ".planning/phases/[N]/DEBUG-[timestamp].md"
-}
-```
-
-## When the bug cannot be reproduced
-
-Ask:
-1. "Does it happen every time or intermittently?"
-2. "Does it happen in specific environments only? (dev/staging/prod)"
-3. "Does it happen for specific users or all users?"
-
-If intermittent: focus on concurrency, caching, and race conditions.
-Write a monitoring/logging plan to catch the next occurrence.
-Document the inconclusive investigation in the DEBUG report with evidence gathered.
+---
+name: mindforge:debug
+description: Perform systematic debugging using the RCA protocol
+argument-hint: [description]
+allowed-tools:
+  - run_command
+  - view_file
+  - write_to_file
+  - list_dir
+---
+
+<objective>
+Resolve complex software defects by following a rigorous Root Cause Analysis (RCA) protocol, including reproduction, isolation, instrumentation, and regression testing.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/debug.md
+</execution_context>
+
+<context>
+Persona: debug-specialist.md
+Lifecycle: Triage -> Reproduce -> Hypothesis -> Fix -> Verify.
+Artifact: .planning/phases/[N]/DEBUG-[timestamp].md
+</context>
+
+<process>
+1. **Intake**: Gather symptoms, reproduction steps, working history, and error logs.
+2. **Triage**: Classify as Regression, Never Worked, Environment, or Integration issue.
+3. **Isolate**: Use git history and breadcrumb logging to identify the failure point.
+4. **Reproduce**: Write a failing test case that proves the bug.
+5. **Fix**: Implement the minimum necessary change to resolve the issue.
+6. **Verify**: Ensure the new test passes and run the full project test suite to detect regressions.
+7. **Document**: Write the `DEBUG-[timestamp].md` RCA report and log the event in `AUDIT.jsonl`.
+</process>

package/.claude/commands/mindforge/discuss-phase.md

@@ -1,138 +1,36 @@
-# MindForge — Discuss Phase Command
-# Usage: /mindforge:discuss-phase [N] [--batch] [--auto]
-# Captures implementation decisions before planning begins.
-# Run this BEFORE /mindforge:plan-phase for complex phases.
-
-## Purpose
-Planning without discussion produces generic plans.
-Discussion captures YOUR decisions — layout preferences, library choices,
-UX specifics, edge cases you've already thought through — so the planner
-builds what you actually want, not what seems reasonable.
-
-## When to use
-- Any phase with UI/UX components (visual decisions need capturing)
-- Any phase with multiple valid implementation approaches
-- Any phase where you already have opinions on the approach
-- Any phase touching external services (your preferences on APIs matter)
-- Skip for trivial phases (e.g., "add one field to an existing form")
-
-## Step 1 — Analyse the phase scope
-
-Read:
-- ROADMAP.md for the phase description
-- REQUIREMENTS.md for the requirements in this phase
-- ARCHITECTURE.md for relevant architectural context
-
-Identify the phase's primary domain and any secondary domains.
-If multiple domains are involved, cover each relevant set of questions.
-- **Visual/UI** → ask about layout, interactions, states, empty states, animations
-- **API/Backend** → ask about response format, error handling, auth approach, versioning
-- **Data/Database** → ask about schema design, migration strategy, data volume expectations
-- **Integration** → ask about third-party API choices, error recovery, retry strategy
-- **Infrastructure** → ask about deployment strategy, scaling approach, observability
-
-## Step 2 — Structured discussion
-
-Ask questions ONE AT A TIME. Wait for the full answer before asking the next.
-Do not batch questions (unless `--batch` flag is provided).
-
-### Visual/UI phases — ask about:
-1. "Walk me through what a user sees on this screen from top to bottom."
-2. "What does the empty state look like? (nothing loaded yet / no results / error)"
-3. "Any animations or transitions you're picturing? Or keep it static?"
-4. "On mobile — stacks vertically or anything different?"
-5. "Any edge cases? (very long text, images that fail to load, loading states)"
-
-### API/Backend phases — ask about:
-1. "What's the intended consumer? Internal frontend / external developers / both?"
-2. "For errors — do you want detailed error objects with field-level info or simple messages?"
-3. "Rate limiting needed on any of these endpoints?"
-4. "Any background processing involved, or all synchronous?"
-5. "Versioning approach? /v1/ prefix or header-based?"
-
-### Data/Database phases — ask about:
-1. "What's the expected data volume? Thousands / millions / billions of rows?"
-2. "Any fields that need full-text search vs. exact match?"
-3. "Soft delete or hard delete for user-facing records?"
-4. "Any fields that change frequently vs. infrequently? (affects indexing strategy)"
-5. "Data retention requirements? When can records be deleted?"
-
-### Integration phases — ask about:
-1. "Have you already chosen the third-party service / API? If so, which?"
-2. "What should happen if the third-party service is down? Queue / fail / fallback?"
-3. "Webhooks or polling for receiving updates?"
-4. "Any rate limits you know about on their end?"
-5. "Testing approach? Do they have a sandbox environment?"
-
-## --batch mode
-If `--batch` flag is provided: group related questions and present them together.
-Appropriate when the user wants faster intake and is familiar with MindForge.
-
-Example batch:
-```
-Visual decisions for Phase 2:
-  1. Layout: card grid / table / list?
-  2. Empty state: illustration / simple message / hide section?
-  3. Loading: skeleton / spinner / none?
-  4. Mobile: same layout / stacked / hidden?
-Answer 1-4:
-```
-
-## --auto mode
-If `--auto` flag is provided: skip the discussion entirely.
-The planner will make reasonable defaults for all decisions.
-Use when: the phase is straightforward and you trust the planner's judgment.
-Warn clearly: "Skipping discussion. Planner will make implementation decisions.
-              Results may not match your vision exactly. Proceeding without
-              explicit decisions can create rework later."
-
-## Step 3 — Write CONTEXT.md
-
-After discussion, write `.planning/phases/[N]/CONTEXT.md`:
-
-```markdown
-# Phase [N] Implementation Context
-# Captured: [ISO-8601]
-# Discussion mode: [interactive / batch / auto]
-
-## Phase description
-[From ROADMAP.md]
-
-## Implementation decisions (captured from discussion)
-
-### [Domain: Visual / API / Data / Integration / etc.]
-
-**Decision:** [What was decided]
-**Rationale:** [Why — from user's words]
-**Implications for planning:**
-  - [What the planner should do because of this decision]
-  - [Specific library or pattern to use]
-  - [What to avoid]
-
-[Repeat for each significant decision]
-
-## Open questions (unresolved during discussion)
-- [Question 1]: [Status — decide during planning / decide during execution]
-
-## User's explicit preferences
-[Verbatim or near-verbatim quotes from the discussion that capture specific intent]
-
-## Defaults accepted (decisions the user deferred to the planner)
-- [Area]: planner's choice
-```
-
-## Step 4 — Confirm and guide
-
-Show the user a summary of what was captured:
-
-"✅ Phase [N] discussion complete. [N] decisions captured.
-
-  Key decisions:
-  - [Decision 1 summary]
-  - [Decision 2 summary]
-  - [Decision 3 summary]
-
-  See full context: .planning/phases/[N]/CONTEXT.md
-
-  Next step: Run /mindforge:plan-phase [N] to create implementation plans
-  using these decisions."
+---
+name: mindforge:discuss-phase
+description: Capture implementation decisions before planning begins
+argument-hint: [N] [--batch] [--auto]
+allowed-tools:
+  - view_file
+  - list_dir
+  - write_to_file
+---
+
+<objective>
+Capture critical implementation decisions (UI/UX, architecture, choice of libraries) through a structured discussion before generating plans. This prevents generic planning and ensures the output matches the user's vision.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/discuss-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (Phase N, optional flags for batch or auto mode)
+Sources: ROADMAP.md, REQUIREMENTS.md, ARCHITECTURE.md.
+Output: .planning/phases/phase-[N]/CONTEXT.md
+</context>
+
+<process>
+1. **Analyze Scope**: Read roadmap, requirements, and architecture to identify the primary domain (UI, API, Data, etc.).
+2. **Structured Discussion**:
+    - If `--auto`: Skip discussion and warn the user.
+    - If `--batch`: Group questions by domain.
+    - Default: Ask domain-specific questions one at a time (e.g., visual layout, error handling, data volume).
+3. **Generate CONTEXT.md**:
+    - Document all captured decisions and their rationale.
+    - Note implications for the upcoming planning phase.
+    - List any unresolved "open questions".
+4. **Guide**: Confirm completion and point the user to `/mindforge:plan-phase [N]`.
+</process>

package/.claude/commands/mindforge/do.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:do
+description: Smart natural language dispatcher to route intent to the right MindForge command
+argument-hint: <text>
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Provide a high-level, natural language interface for users to interact with MindForge without needing to remember specific command names. Routes user intent to the most appropriate internal command.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/do.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (The user's intent in plain English)
+Knowledge: Must be aware of all available `.claude/commands/mindforge/*.md` definitions.
+</context>
+
+<process>
+1. **Analyze input**: Parse the user's natural language request.
+2. **Match command**: Compare the intent against the descriptions and objectives of all known MindForge commands.
+3. **Execute match**:
+    - If a clear match is found, immediately pivot to that command's logic.
+    - If multiple matches are possible, ask the user for clarification.
+    - If no match is found, suggest the most relevant command or offer `/mindforge:help`.
+4. **Learn (Optional)**: If the user confirms a routing was correct, record the mapping for future intent resolution.
+</process>

package/.claude/commands/mindforge/execute-phase.md

@@ -1,190 +1,37 @@
-# MindForge — Execute Phase Command
-# Usage: /mindforge:execute-phase [N]
-
-## Pre-checks (all must pass before execution starts)
-
-1. Read STATE.md — confirm phase [N] is in "planned" status.
-   If STATE.md shows phase [N] as already "complete": ask user to confirm re-execution.
-
-2. Verify plan files exist:
-   ```
-   .planning/phases/[N]/PLAN-[N]-01.md   (minimum one plan required)
-   ```
-   If missing: stop. Tell user: "No plans found for Phase [N]. Run /mindforge:plan-phase [N] first."
-
-3. Verify REQUIREMENTS.md exists and has content.
-   If empty: warn user but allow continuation.
-
-4. Run the dependency parser (`.mindforge/engine/dependency-parser.md`).
-   If validation fails (circular deps, missing deps): stop and report. Do not execute.
-
-## Step 1 — Build and display the execution plan
-
-After dependency parsing succeeds, display the wave plan to the user:
-
-```
-Phase [N] Execution Plan
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-  Wave 1 (parallel)     Wave 2 (parallel)     Wave 3
-  ┌─────────────┐       ┌─────────────┐       ┌─────────────┐
-  │ Plan 01     │       │ Plan 03     │       │ Plan 05     │
-  │ User model  │──┐    │ User API    │──┐    │ Checkout UI │
-  └─────────────┘  │    └─────────────┘  │    └─────────────┘
-  ┌─────────────┐  │    ┌─────────────┐  │
-  │ Plan 02     │──┘    │ Plan 04     │──┘
-  │ Product     │       │ Product API │
-  └─────────────┘       └─────────────┘
-
-  Total tasks: 5    Waves: 3    Est. time: depends on model speed
-
-Proceed? (yes/no)
-```
-
-If the user says no: stop. Do not execute anything.
-
-## Step 2 — Write pre-execution audit entry
-
-Append to `.planning/AUDIT.jsonl`:
-```json
-{
-  "id": "[uuid-v4]",
-  "timestamp": "[ISO-8601]",
-  "event": "phase_execution_started",
-  "phase": [N],
-  "wave_count": [total waves],
-  "task_count": [total tasks],
-  "agent": "mindforge-orchestrator",
-  "session_id": "[session identifier]"
-}
-```
-
-## Step 3 — Execute waves using the wave executor
-
-Follow the complete protocol in `.mindforge/engine/wave-executor.md`.
-
-For each wave:
-
-### Wave start
-Write to console:
-```
-━━━ Wave [W] of [total] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  Starting [X] tasks in parallel...
-```
-
-### Per-task execution (inject context per `context-injector.md`)
-For each plan in the wave:
-1. Load context package (per `context-injector.md`)
-2. Execute the plan instructions
-   - Run `<verify>` — capture exact output
-   - If verify PASSES:
-     - Run `<verify-visual>` via `visual-verify-executor.js`
-     - If visual verify FAILS: stop and report (treat as verify failure)
-     - Write SUMMARY-[N]-[M].md
-   - Execute commit: `git add [files] && git commit -m "[type]([scope]): [task name]"`
-   - Capture git SHA
-   - Write AUDIT entry for task completion
-5. If verify FAILS:
-   - Write SUMMARY-[N]-[M].md with failure details
-   - Write AUDIT entry for task failure
-   - STOP this wave immediately
-   - Report: "Task [plan ID] failed: [verify output]. Stopping Phase [N]."
-   - Do not start next wave
-   - Ask user: "Spawn debug agent to diagnose? (yes/no)"
-
-### Wave completion (before starting next wave)
-After all tasks in wave complete:
-1. Run: `[project test command]`
-2. If tests fail:
-   - Identify failing tests
-   - Run `git log --oneline -[wave-task-count]` to see wave commits
-   - Report which commit likely introduced the failure
-   - Stop. Ask user how to proceed.
-3. If tests pass:
-   - Report: "Wave [W] complete. All [X] tasks passed. Tests passing. ✅"
-   - Write WAVE-REPORT update
-
-## Step 4 — Phase-level verification
-
-After all waves complete, run the verification pipeline:
-
-1. Read every v1 requirement from REQUIREMENTS.md for this phase
-2. For each requirement, verify it is implemented:
-   - Search the codebase for the implementation
-   - Check if a test covers it
-   - Mark: ✅ implemented + tested | ⚠️ implemented, no test | ❌ not found
-3. Write `.planning/phases/[N]/VERIFICATION.md`
-4. Run the full test suite one final time
-5. If any requirement is ❌: create a fix plan and report to user
-
-## Step 5 — Update state and write wave report
-
-Write `.planning/phases/[N]/WAVE-REPORT-[N].md` (per template in wave-executor.md)
-
-Update STATE.md:
-```markdown
-## Current phase
-[N] — Execution complete ✅
-
-## Last completed task
-Phase [N]: All [X] tasks completed across [W] waves.
-
-## Next action
-Run /mindforge:verify-phase [N] for human acceptance testing.
-```
-
-Update HANDOFF.json with completed phase info.
-
-Write final AUDIT entry:
-```json
-{
-  "id": "[uuid-v4]",
-  "timestamp": "[ISO-8601]",
-  "event": "phase_execution_completed",
-  "phase": [N],
-  "tasks_completed": [X],
-  "waves_executed": [W],
-  "commits": ["sha1", "sha2", "..."],
-  "test_result": "passing",
-  "agent": "mindforge-orchestrator"
-}
-```
-
-## Step 6 — Report to user
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-✅ Phase [N] execution complete
-
-  Tasks completed : [X] / [X]
-  Waves executed  : [W]
-  Commits made    : [X]
-  Tests           : All passing
-  Requirements    : [X] / [X] implemented
-
-Next step: Run /mindforge:verify-phase [N] for UAT sign-off.
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-## Step 7 — Auto-capture check (when AUTO_CAPTURE_SKILLS=true)
-
-After all gates pass and the phase is verified:
-
-```bash
-# Check if auto-capture is enabled
-CAPTURE=$(grep -m1 "^AUTO_CAPTURE_SKILLS=" MINDFORGE.md 2>/dev/null | cut -d= -f2 | tr -d ' ')
-if [ "$CAPTURE" = "true" ]; then
-  node -e "
-    const { detectPatterns, formatForPresentation } = require('./bin/skills-builder/pattern-detector');
-    detectPatterns(${PHASE_NUM}).then(result => {
-      const display = formatForPresentation(result);
-      console.log(display);
-    }).catch(err => console.error('[auto-capture] Error:', err.message));
-  "
-fi
-```
-
-If patterns are found: display the prompt and await user input.
-If user selects yes: run `/mindforge:learn --session` targeting this phase's SUMMARY files.
-If user selects no: write AUDIT entry `auto_capture_skipped` and continue.
-If no patterns found: exit silently (no noise in the output).
-```
+---
+name: mindforge:execute-phase
+description: Execute the wave-based execution plan for a specific phase
+argument-hint: [N]
+allowed-tools:
+  - view_file
+  - write_to_file
+  - run_command
+  - list_dir
+---
+
+<objective>
+Coordinate the parallel execution of task plans for a phase using a wave-based approach, ensuring dependency integrity, automated verification, and audit logging.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/execute-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (Phase N)
+Sources: .planning/phases/[N]/PLAN-*.md, STATE.md, REQUIREMENTS.md
+Engine: wave-executor.md, dependency-parser.md, context-injector.md
+</context>
+
+<process>
+1. **Pre-checks**: Verify phase status, plan existence, and requirement content. Run dependency parser.
+2. **Display Wave Plan**: Present the wave-based execution graph and wait for user approval.
+3. **Audit Initiation**: Log `phase_execution_started` in `AUDIT.jsonl`.
+4. **Wave Execution**:
+    - For each wave: Execute tasks in parallel.
+    - For each task: Inject context, run implementation, run `<verify>`, and commit with SHA.
+    - If any task fails: Stop the wave and offer debugging.
+5. **Phase Verification**: Check requirement coverage in the implementation and write `VERIFICATION.md`.
+6. **Update State**: Update `STATE.md`, `HANDOFF.json`, and write `WAVE-REPORT-[N].md`.
+7. **Auto-capture**: If enabled, detect new patterns/skills from the implemented phase.
+</process>

package/.claude/commands/mindforge/health.md

@@ -1,21 +1,31 @@
-# MindForge — Health Command
-# Usage: /mindforge:health [--repair] [--category C] [--verbose]
+---
+name: mindforge:health
+description: Run the MindForge health engine to diagnose and repair issues
+argument-hint: [--repair] [--category C] [--verbose]
+allowed-tools:
+  - run_command
+  - list_dir
+  - view_file
+---
 
-Run all seven health-engine categories from `.mindforge/intelligence/health-engine.md`.
+<objective>
+Ensure the MindForge environment and project state are valid, secure, and optimally configured by running a suite of diagnostic checks across multiple categories.
+</objective>
 
-## Output
-- category status summary
-- errors (must fix)
-- warnings (should fix)
-- informational signals
+<execution_context>
+.claude/commands/mindforge/health.md
+</execution_context>
 
-## Flags
-- `--repair`: apply safe auto-repair only
-- `--category`: one of `installation|context|skills|personas|state|integrations|security`
-- `--verbose`: include passing checks and exact inspected values
+<context>
+Engine: .mindforge/intelligence/health-engine.md
+Categories: installation, context, skills, personas, state, integrations, security.
+Flags: --repair (auto-fix), --verbose (full details).
+</context>
 
-## AUDIT
-Append:
-```json
-{ "event": "health_check_completed", "errors": 0, "warnings": 0, "repaired": 0 }
-```
+<process>
+1. **Initialize Diagnostics**: Load the health engine and target specifically requested categories (or all by default).
+2. **Execute Checks**: Scan for configuration errors, missing files, security misconfigurations, and state inconsistencies.
+3. **Repair (Optional)**: If `--repair` is set, apply safe automated fixes for detected issues.
+4. **Report Findings**: Categorize results into Errors (must fix), Warnings (should fix), and Info.
+5. **Audit**: Log `health_check_completed` with counts of errors, warnings, and repairs.
+</process>