mindforge-cc 2.0.0 → 2.1.0

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>

package/.claude/commands/mindforge/help.md

@@ -1,23 +1,29 @@
-Show all available MindForge commands.
+---
+name: mindforge:help
+description: Show all available MindForge commands and current project summary
+argument-hint: none
+allowed-tools:
+  - list_dir
+  - view_file
+---
 
-## Pre-check
-If `.planning/STATE.md` exists, read it.
-If `.planning/PROJECT.md` is missing, treat the project as "Not initialised".
+<objective>
+Provide a searchable, categorized directory of all accessible MindForge commands, along with a quick snapshot of the project's current state.
+</objective>
 
-1. Scan every .md file in `.claude/commands/mindforge/`
-2. For each file, extract the first non-empty line as the command description
-3. Display as a clean table:
+<execution_context>
+.claude/commands/mindforge/help.md
+</execution_context>
 
-| Command                      | Description                                  |
-|------------------------------|----------------------------------------------|
-| /mindforge:help              | Show all available commands                  |
-| /mindforge:init-project      | ...                                          |
-| ...                          | ...                                          |
+<context>
+Discovery: Scans `.claude/commands/mindforge/*.md`
+State: PROJECT.md and STATE.md
+</context>
 
-4. After the table, print:
-   "Current project: [read PROJECT.md first line, or 'Not initialised']"
-   "Current phase:   [read STATE.md current phase, or 'None']"
-   "Next step:       [read STATE.md next action]"
-
-5. If CLAUDE.md has not been read this session, remind the user to ensure
-   it is loaded as the agent's system context.
+<process>
+1. **Command Scan**: List all markdown definitions in the command directory and extract their first-line descriptions or YAML metadata.
+2. **Read Project Info**: Summarize the current project name, active phase, and recommended next step.
+3. **Format Dashboard**: Render a clean table of commands and descriptions.
+4. **Verify Context**: If `CLAUDE.md` hasn't been read in the current session, remind the user to load it as the agent's context.
+5. **Display**: Present the help table and project summary.
+</process>