mindforge-cc 6.2.0-alpha → 6.2.0

package/.claude/commands/mindforge/costs.md

@@ -1,28 +1,15 @@
 ---
-name: mindforge:costs
-description: Real-time cost tracking for AI model usage
-argument-hint: [--phase N] [--session ID] [--window 7d]
-allowed-tools:
-  - view_file
-  - run_command
+description: Real-time cost tracking for all AI model usage.
 ---
 
-<objective>
-Monitor and control project expenses related to AI model usage, enforcing budget guardrails and providing granular spend analysis.
-</objective>
+# MindForge v2 — Costs Command
+# Usage: /mindforge:costs [--phase N] [--session ID] [--window 7d]
 
-<execution_context>
-.claude/commands/mindforge/costs.md
-</execution_context>
+## Purpose
+Real-time cost tracking for all AI model usage.
+Enforce daily budgets and see per-model spend.
 
-<context>
-Metrics: Total spend, daily limit usage, per-model breakdown.
-Sources: AUDIT.jsonl and local token logs.
-</context>
-
-<process>
-1. **Gather Usage Data**: Parse logs for the specified phase, session, or time window.
-2. **Calculate Spend**: Apply pricing models to the detected token counts per model.
-3. **Enforce Budgets**: Compare current spend against configured daily and project limits.
-4. **Display Report**: Present the total spend and limit usage as a percentage.
-</process>
+## Metrics
+- Total spend: $X.XX
+- Daily limit usage: XX%
+- Per-model breakdown (Tokens/Cost)

package/.claude/commands/mindforge/cross-review.md

@@ -1,31 +1,21 @@
 ---
-name: mindforge:cross-review
-description: Get code reviewed by multiple AI models simultaneously for consensus validation
-argument-hint: [--phase N] [--models list] [--focus area]
-allowed-tools:
-  - run_command
-  - view_file
-  - write_to_file
+description: Get the same code diff reviewed by multiple AI models simultaneously.
 ---
 
-<objective>
-Increase review confidence by aggregating findings from multiple diverse AI models, identifying consensus issues and providing a multi-perspective quality assessment.
-</objective>
+# MindForge v2 — Cross-Review Command
+# Usage: /mindforge:cross-review [--phase N] [--models list] [--focus area]
 
-<execution_context>
-.claude/commands/mindforge/cross-review.md
-</execution_context>
+## Purpose
+Get the same code diff reviewed by multiple AI models simultaneously.
+Claude finds what Claude finds. GPT-4o finds what GPT-4o finds.
+Consensus findings = high confidence issues.
 
-<context>
-Models: Claude (Primary/Architectural), GPT-4o (Adversarial/Security).
-Focus: Specific area like "security", "performance", or "consistency".
-Pre-check: Models must be available via existing API integrations.
-</context>
+## Round 1: Primary (Claude)
+Senior architect review.
 
-<process>
-1. **Round 1 (Primary)**: Execute architectural review using the primary model.
-2. **Round 2 (Adversarial)**: Execute security-focused review using the secondary model.
-3. **Synthesis**: Compare findings from both rounds. Identify consensus "high confidence" issues.
-4. **Final Verdict**: Issue a gating verdict that must be resolved for `/mindforge:ship`.
-5. **Log**: Record the multi-model review results in the audit trail.
-</process>
+## Round 2: Adversarial (GPT-4o)
+Critical security and edge case review.
+
+## Synthesis
+Consensus detector filters findings.
+Verdict is gating for `/mindforge:ship`.

package/.claude/commands/mindforge/dashboard.md

@@ -1,35 +1,102 @@
 ---
-name: mindforge:dashboard
-description: Start the MindForge real-time web dashboard
-argument-hint: [--port N] [--open] [--stop] [--status]
-allowed-tools:
-  - run_command
-  - list_dir
-  - view_file
-  - open_browser_url
+description: Start the MindForge real-time web dashboard — a live observability UI for the
 ---
 
-<objective>
-Provide a real-time web-based observability interface for the project, allowing the team to monitor execution progress, quality metrics, pending approvals, and team activity.
-</objective>
-
-<execution_context>
-.claude/commands/mindforge/dashboard.md
-</execution_context>
-
-<context>
-Port: Default 7339 (configurable via --port).
-Security: Binding to 127.0.0.1 (local only).
-Features: Server-Sent Events for live updates, no-auth by design.
-</context>
-
-<process>
-1. **Handle Flags**:
-    - If `--stop`: Find the PID from the PID file and terminate the process.
-    - If `--status`: Check if the dashboard is running and report the URL/PID.
-    - Default: Start the server.
-2. **Start Server**: Execute the dashboard binary/script on the specified port.
-3. **Open Browser**: If `--open` is provided, trigger the default system browser to the dashboard URL.
-4. **Monitor**: Listen for steering inputs from the dashboard and route them to the active MindForge session.
-5. **Log**: Record `dashboard_started` or `dashboard_stopped` in the audit log.
-</process>
+# MindForge v2 — Dashboard Command
+# Usage: /mindforge:dashboard [--port 7339] [--open] [--stop] [--status]
+# Version: v2.0.0-alpha.5
+
+## Purpose
+Start the MindForge real-time web dashboard — a live observability UI for the
+entire team. Shows execution progress, quality metrics, pending approvals,
+knowledge graph, and team activity without requiring CLI access.
+
+## Design
+The dashboard is a localhost-only web server:
+- No build step — single HTML file, no bundler, no npm packages on client
+- No authentication — binding to 127.0.0.1 is the security model
+- Live updates via Server-Sent Events — no WebSocket library needed
+- Designed for screensharing at standups, not external access
+
+## Usage
+
+### Start the dashboard
+```
+/mindforge:dashboard
+→ Dashboard running at: http://localhost:7339
+→ Press CTRL+C to stop (or /mindforge:dashboard --stop)
+```
+
+### Start and open in browser
+```
+/mindforge:dashboard --open
+→ Opens http://localhost:7339 in your default browser
+```
+
+### Custom port
+```
+/mindforge:dashboard --port 7340
+→ Useful if 7339 is already in use
+```
+
+### Stop the dashboard
+```
+/mindforge:dashboard --stop
+→ Finds the running dashboard process (from PID file) and sends SIGTERM
+```
+
+### Check dashboard status
+```
+/mindforge:dashboard --status
+→ Checks if dashboard is running, shows port and PID
+→ Also shows: http://localhost:7339/api/status
+```
+
+## Dashboard pages
+
+### Activity (default)
+- Phase name, auto mode status (RUNNING/PAUSED/ESCALATED/IDLE)
+- Wave progress bar (tasks completed / total)
+- Live AUDIT event feed with color-coded event types
+- Steering input: send guidance to auto mode without touching the CLI
+
+### Quality Metrics
+- Session quality score trend (last 20 sessions)
+- Verify pass rate over time
+- Security findings by severity (CRITICAL/HIGH/MEDIUM/LOW)
+- Cost per session trend
+
+### Approvals
+- All pending Tier 2/3 governance requests
+- [Approve] and [Reject] buttons — no CLI needed for approval
+- Tier, phase/plan, description, time since requested, expiry warning
+- Recent approval history
+
+### Knowledge
+- Search the knowledge graph from the browser
+- Entries filtered by confidence, type, tags
+- Color-coded by knowledge type
+
+### Team
+- Active developers (by git email, from AUDIT.jsonl)
+- What each person is working on (last task)
+- File conflict warnings (two developers recently touching the same file)
+
+## Security rules
+1. Never expose the dashboard on 0.0.0.0 — localhost only
+2. Never forward the port externally (no ngrok, no port forwarding)
+3. For remote team visibility: screenshare your browser instead
+4. The dashboard shows project details including code patterns and decisions
+
+## Integration with auto mode
+When `/mindforge:auto` is running and the dashboard is open:
+- Activity feed updates live as tasks complete
+- Wave progress bar advances in real-time
+- Any escalations appear immediately with red indicator
+- The Steering input is active — inject guidance without a second terminal
+
+## AUDIT entry
+```json
+{ "event": "dashboard_started", "port": 7339, "pid": 12345 }
+{ "event": "dashboard_stopped", "pid": 12345 }
+```

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

@@ -1,34 +1,133 @@
 ---
-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
+description: Systematic debugging using the Debug Specialist persona with full RCA protocol.
 ---
 
-<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>
+# 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 0 — Initial Intelligence Check
+Read `AGENTS_LEARNING.md` before intake. Check the "Mistakes Observed" and "Anti-Patterns" sections to see if this issue matches a known historical failure.
+
+## 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.

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

@@ -1,36 +1,142 @@
 ---
-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
+description: Planning without discussion produces generic plans.
 ---
 
-<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>
+# 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? (I will query Context7 for current docs if available)"
+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."