mindforge-cc 2.0.0 → 2.1.0

package/.claude/commands/mindforge/benchmark.md

@@ -1,33 +1,30 @@
-# MindForge — Benchmark Command
-# Usage: /mindforge:benchmark [--skill skill-name] [--compare skill-a skill-b]
+---
+name: mindforge:benchmark
+description: Measure skill effectiveness and project metrics over time
+argument-hint: [--skill skill-name] [--compare skill-a skill-b]
+allowed-tools:
+  - view_file
+  - list_dir
+---
 
-Measure skill effectiveness over time.
+<objective>
+Analyze command and skill performance by correlating usage data with verify pass rates and project quality scores, facilitating data-driven decisions on tool improvements.
+</objective>
 
-## Single skill benchmark
-For a named skill, analyse AUDIT.jsonl and skill-usage.jsonl:
-- How many times was the skill loaded this month?
-- What is the verify pass rate for tasks where this skill was loaded?
-- Are there anti-patterns less common after this skill is loaded?
-- What is the average session quality score when this skill is active?
+<execution_context>
+.claude/commands/mindforge/benchmark.md
+</execution_context>
 
-Report:
-```
-Skill Benchmark: security-review v1.0.0
-────────────────────────────────────────
-Usage (last 30 days): 47 task loads
-Trigger distribution: text match 68%, file-path 22%, file-name 10%
-Verify pass rate:     91% (vs. 84% baseline without this skill)
-Security findings:    8 HIGH caught (0 CRITICAL missed in tasks using this skill)
-Session quality lift: +6.2 points average when loaded
+<context>
+Sources: AUDIT.jsonl, skill-usage.jsonl
+Metrics: Pass rate, load frequency, anti-pattern reduction, quality lift.
+</context>
 
-Assessment: HIGH VALUE — clear quality improvement signal
-```
-
-## Skill comparison
-Compare two skills head-to-head:
-- Load frequency
-- Verify pass rate improvement
-- Anti-pattern detection rate
-- Context budget cost (token estimate)
-
-Helps decide: should you keep both skills, or deprecate the lower-performer?
+<process>
+1. **Gather Data**: Extract usage and outcome logs for the target skill(s).
+2. **Calculate Trends**: Determine pass rate vs baseline and session quality improvement.
+3. **Generate Assessment**:
+    - For single skill: Provide a usage distribution and quality lift report.
+    - For comparison: Provide a head-to-head comparison on cost and effectiveness.
+4. **Recommendation**: Advise on whether to keep, improve, or deprecate the targeted skills.
+</process>

package/.claude/commands/mindforge/browse.md

@@ -1,26 +1,28 @@
-# /mindforge:browse
+---
+name: mindforge:browse
+description: Control the persistent MindForge browser daemon for visual verification
+argument-hint: <url | action>
+allowed-tools:
+  - open_browser_url
+  - run_command
+---
 
-## Usage
-`@mindforge browse <url | action>`
+<objective>
+Enable the agent to interact with web interfaces, maintain persistent sessions, and perform visual audits of UI changes using an automated browser daemon.
+</objective>
 
-## Description
-Controls the persistent MindForge browser daemon. 
-Maintains session state (cookies/localStorage) for the AI.
+<execution_context>
+.claude/commands/mindforge/browse.md
+</execution_context>
 
-## Actions
-| Action | Description |
-|---|---|
-| `--start` | Initialize browser daemon |
-| `--stop` | Kill browser daemon |
-| `--status` | Show daemon health and active sessions |
-| `--session <name>` | Switch browser context |
-| `--import-session <name> --from <browser>` | Import cookies from host browser (chrome, arc, etc) |
-| `<url>` | Navigate the current page to URL |
-| `click <selector>` | Trigger click event |
-| `type <sel> <text>` | Fill input field |
-| `screenshot` | Capture current viewport |
+<context>
+Security: Daemon binds to 127.0.0.1. Sessions are gitignored.
+State: Supports cookie/localStorage persistence via named sessions.
+</context>
 
-## Security
-- Daemon binds to `127.0.0.1` only.
-- Session files are gitignored.
-- Use only for debugging and visual verification.
+<process>
+1. **Control Daemon**: Start, stop, or query the health/active sessions of the browser daemon.
+2. **Session Management**: Switch between browser contexts or import sessions from the host (Chrome/Arc).
+3. **Navigate & Interact**: Load URLs, click selectors, and type text into input fields.
+4. **Verify**: Capture screenshots of the current viewport for visual confirmation.
+</process>

package/.claude/commands/mindforge/complete-milestone.md

@@ -1,18 +1,32 @@
-Archive a completed milestone, generate a release report, and prepare the next
- milestone. Usage: `/mindforge:complete-milestone <name> <version>`
+---
+name: mindforge:complete-milestone
+description: Archive a completed milestone and prepare the next version
+argument-hint: <name> <version>
+allowed-tools:
+  - list_dir
+  - view_file
+  - write_to_file
+  - run_command
+---
 
-## Step 1 — Validate milestone completion
-Ensure every included phase is verified and has no pending blocking approvals.
+<objective>
+Finalize a project milestone by summarizing shipped value, archiving phase artifacts, and preparing the environment for the next development cycle.
+</objective>
 
-## Step 2 — Generate milestone report
-Summarise shipped phases, notable changes, risks, approvals, and unresolved
- follow-ups.
+<execution_context>
+.claude/commands/mindforge/complete-milestone.md
+</execution_context>
 
-## Step 3 — Archive milestone artifacts
-Archive only the phases included in the milestone, not the entire
- `.planning/phases/` directory. Preserve history in the archive while keeping
- active planning files available in place.
+<context>
+Validation: Ensures all included phases are verified and have no pending approvals.
+Storage: Moves phase files to a milestone-specific archive.
+</context>
 
-## Step 4 — Release metadata
-Create the release tag, update `STATE.md` with milestone summary, and mark the
- project ready for the next version.
+<process>
+1. **Validate**: Confirm every phase in the milestone is signed off and verified.
+2. **Summarize**: Generate a MILESTONE-REPORT with shipped functionality, risks, and follow-ups.
+3. **Archive**: Move the included `.planning/phases/` directories to a persistent milestone archive.
+4. **Tag**: Create a git release tag for the milestone.
+5. **State Reset**: Update `STATE.md` to reflect the milestone completion and target the next version.
+6. **Audit**: Log `milestone_completed` event.
+</process>

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

@@ -1,11 +1,28 @@
-# MindForge v2 — Costs Command
-# Usage: /mindforge:costs [--phase N] [--session ID] [--window 7d]
+---
+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
+---
 
-## Purpose
-Real-time cost tracking for all AI model usage.
-Enforce daily budgets and see per-model spend.
+<objective>
+Monitor and control project expenses related to AI model usage, enforcing budget guardrails and providing granular spend analysis.
+</objective>
 
-## Metrics
-- Total spend: $X.XX
-- Daily limit usage: XX%
-- Per-model breakdown (Tokens/Cost)
+<execution_context>
+.claude/commands/mindforge/costs.md
+</execution_context>
+
+<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>

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

@@ -1,17 +1,31 @@
-# MindForge v2 — Cross-Review Command
-# Usage: /mindforge:cross-review [--phase N] [--models list] [--focus area]
+---
+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
+---
 
-## 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.
+<objective>
+Increase review confidence by aggregating findings from multiple diverse AI models, identifying consensus issues and providing a multi-perspective quality assessment.
+</objective>
 
-## Round 1: Primary (Claude)
-Senior architect review.
+<execution_context>
+.claude/commands/mindforge/cross-review.md
+</execution_context>
 
-## Round 2: Adversarial (GPT-4o)
-Critical security and edge case review.
+<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>
 
-## Synthesis
-Consensus detector filters findings.
-Verdict is gating for `/mindforge:ship`.
+<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>

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>