mindforge-cc 2.1.4 → 2.3.0

package/.agent/workflows/mindforge:audit.md

@@ -0,0 +1,33 @@
+---
+description: Query .planning/AUDIT.jsonl by phase, event, date, severity, integration, or
+---
+Query `.planning/AUDIT.jsonl` by phase, event, date, severity, integration, or
+ agent. Usage: `/mindforge:audit [filters]`
+
+## Supported options
+- `--phase N`
+- `--event NAME`
+- `--agent NAME`
+- `--severity LEVEL`
+- `--date YYYY-MM-DD`
+- `--summary`
+- `--verify`
+- `--export PATH`
+
+## Summary mode
+Summarise counts by event, severity, integration, and phase.
+Entries with `"phase": null` are reported as `project-level`, not dropped.
+
+## Verify mode
+Validate JSONL shape and chronological ordering.
+Timestamp comparison may use string comparison because ISO-8601 UTC timestamps
+ with a `Z` suffix sort lexicographically.
+
+## Archive rotation
+If the active audit log exceeds 10,000 lines, rotate it into
+ `.planning/audit-archive/` before continuing heavy writes. Rotation must never
+ delete history; it archives then resets the active file.
+
+## Export safety
+Validate export paths stay inside the project directory. If a path traversal or
+ unsafe destination is requested, export into `.planning/` instead.

package/.agent/workflows/mindforge:auto.md

@@ -0,0 +1,25 @@
+---
+description: Starts the MindForge Autonomous Execution Engine for the
+---
+# /mindforge:auto [Phase N]
+
+**Purpose**: Starts the MindForge Autonomous Execution Engine for the
+specified phase. The agent will execute all waves, handle repairs, and
+perform compliance gates without requiring human confirmation.
+
+## Usage
+- `/mindforge:auto --phase 3` (Standard unattended mode)
+- `/mindforge:auto --resume` (Resumes from last checkpoint)
+- `/mindforge:auto --headless` (CI/CD optimized output)
+- `/mindforge:auto --dry-run` (Show the wave DAG and plan without executing)
+
+## Behavior
+- **Zero-Interaction**: Auto-approves Tier 1/2 changes if gates pass.
+- **Self-Repair**: Tries RETRY/DECOMPOSE before asking for help.
+- **Checkpointing**: Constant state persistence in `HANDOFF.json`.
+- **Governance**: ESCALATES on Tier 3 changes (Auth/Payment/PII).
+
+## Environment Variables
+- `AUTO_MODE_TIMEOUT_MINUTES`: Default 120.
+- `AUTO_PUSH_ON_WAVE_COMPLETE`: Default false.
+- `SLACK_WEBHOOK_URL`: Required for notifications.

package/.agent/workflows/mindforge:benchmark.md

@@ -0,0 +1,36 @@
+---
+description: Measure skill effectiveness over time.
+---
+# MindForge — Benchmark Command
+# Usage: /mindforge:benchmark [--skill skill-name] [--compare skill-a skill-b]
+
+Measure skill effectiveness over time.
+
+## 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?
+
+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
+
+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?

package/.agent/workflows/mindforge:browse.md

@@ -0,0 +1,29 @@
+---
+description: @mindforge browse <url | action>
+---
+# /mindforge:browse
+
+## Usage
+`@mindforge browse <url | action>`
+
+## Description
+Controls the persistent MindForge browser daemon. 
+Maintains session state (cookies/localStorage) for the AI.
+
+## 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 |
+
+## Security
+- Daemon binds to `127.0.0.1` only.
+- Session files are gitignored.
+- Use only for debugging and visual verification.

package/.agent/workflows/mindforge:complete-milestone.md

@@ -0,0 +1,21 @@
+---
+description: Archive a completed milestone, generate a release report, and prepare the next
+---
+Archive a completed milestone, generate a release report, and prepare the next
+ milestone. Usage: `/mindforge:complete-milestone <name> <version>`
+
+## Step 1 — Validate milestone completion
+Ensure every included phase is verified and has no pending blocking approvals.
+
+## Step 2 — Generate milestone report
+Summarise shipped phases, notable changes, risks, approvals, and unresolved
+ follow-ups.
+
+## 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.
+
+## Step 4 — Release metadata
+Create the release tag, update `STATE.md` with milestone summary, and mark the
+ project ready for the next version.

package/.agent/workflows/mindforge:costs.md

@@ -0,0 +1,14 @@
+---
+description: Real-time cost tracking for all AI model usage.
+---
+# MindForge v2 — Costs Command
+# Usage: /mindforge:costs [--phase N] [--session ID] [--window 7d]
+
+## Purpose
+Real-time cost tracking for all AI model usage.
+Enforce daily budgets and see per-model spend.
+
+## Metrics
+- Total spend: $X.XX
+- Daily limit usage: XX%
+- Per-model breakdown (Tokens/Cost)

package/.agent/workflows/mindforge:cross-review.md

@@ -0,0 +1,20 @@
+---
+description: Get the same code diff reviewed by multiple AI models simultaneously.
+---
+# MindForge v2 — Cross-Review Command
+# Usage: /mindforge:cross-review [--phase N] [--models list] [--focus area]
+
+## 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.
+
+## Round 1: Primary (Claude)
+Senior architect review.
+
+## Round 2: Adversarial (GPT-4o)
+Critical security and edge case review.
+
+## Synthesis
+Consensus detector filters findings.
+Verdict is gating for `/mindforge:ship`.

package/.agent/workflows/mindforge:dashboard.md

@@ -0,0 +1,101 @@
+---
+description: Start the MindForge real-time web dashboard — a live observability UI for the
+---
+# 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/.agent/workflows/mindforge:debug.md

@@ -0,0 +1,129 @@
+---
+description: Systematic debugging using the Debug Specialist persona with full RCA protocol.
+---
+# 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.

package/.agent/workflows/mindforge:discuss-phase.md

@@ -0,0 +1,141 @@
+---
+description: Planning without discussion produces generic plans.
+---
+# 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."

package/.agent/workflows/mindforge:do.md

@@ -0,0 +1,25 @@
+---
+description: Smart natural language dispatcher to route intent to the right MindForge command
+---
+<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>