mindforge-cc 2.0.0-alpha.9 → 2.1.0

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

@@ -1,98 +1,35 @@
-# 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 }
-```
+---
+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
+---
+
+<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>

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>