mindforge-cc 2.1.0 → 2.1.2

package/docs/user-guide.md

@@ -1,296 +1,170 @@
-# MindForge User Guide (v2.0.0)
+# MindForge User Guide (v2.1.1)
 
-This guide gets you from install to productive, with the minimum needed to run
-MindForge in a real project. It assumes Node.js 18+.
+This guide gets you from install to productive, with the minimum needed to run MindForge in a real project. It assumes Node.js 18+.
 
 ## 1. Install
 
 ### Claude Code (global)
+
 ```bash
 npx mindforge-cc@latest --claude --global
 ```
 
 ### Claude Code (local, per project)
-```bash
-npx mindforge-cc@latest --claude --local
-```
-
-Optional utilities:
-```bash
-npx mindforge-cc@latest --claude --local --with-utils
-```
 
-Minimal scaffolding:
 ```bash
-npx mindforge-cc@latest --claude --local --minimal
+npx mindforge-cc@latest --claude --local
 ```
 
 ### Antigravity
+
 ```bash
-npx mindforge-cc@latest --antigravity --global
-# or
 npx mindforge-cc@latest --antigravity --local
 ```
 
-### Cursor
-```bash
-npx mindforge-cc@latest --cursor --local
-```
+### Specific Runtime (Universal)
 
-### Gemini CLI
 ```bash
-npx mindforge-cc@latest --gemini --global
+npx mindforge-cc@latest --runtime <name>
 ```
 
-### GitHub Copilot
-```bash
-npx mindforge-cc@latest --copilot --local
-```
+---
 
-### OpenCode
-```bash
-npx mindforge-cc@latest --opencode --global
-```
+## 2. Verify Installation
 
-### Specific Runtime (Universal)
-```bash
-npx mindforge-cc@latest --runtime <name>
-```
+Open your agentic runtime (Claude Code, Antigravity, etc.) in your project directory and run:
 
-### Multiple runtimes
 ```bash
-npx mindforge-cc@latest --runtime claude,cursor --local
-```
-
-## 2. Verify installation
-Open Claude Code or Antigravity in your project directory and run:
-```
 /mindforge:health
 ```
 
 If health reports issues, run:
-```
+
+```bash
 /mindforge:health --repair
 ```
 
-## 3. Initialize a new project
-```
-/mindforge:init-project
-```
-This creates the core planning artifacts in `.planning/`.
+## 3. Initialize a New Project
 
-## 4. Brownfield onboarding (existing codebase)
-```
-/mindforge:map-codebase
+```bash
+/mindforge:init-project
 ```
-This generates `.planning/ARCHITECTURE.md` and an inferred conventions file.
 
-## 5. Standard workflow
-```
-/mindforge:plan-phase 1
-/mindforge:execute-phase 1
-/mindforge:verify-phase 1
-/mindforge:ship 1
-```
+This scaffolds the core framework in `.agent/` and creates project-specific planning artifacts in `.planning/`.
 
-## 6. Autonomous Execution (v2)
-For complex phases that require no human intervention, use the autonomous engine.
+## 4. Onboarding an Existing Codebase
 
-### Start autonomous phase
 ```bash
-/mindforge:auto --phase 1
+/mindforge:map-codebase
 ```
 
-### Steering mid-execution
-If you need to guide the agent while it is running in another terminal:
-```bash
-/mindforge:steer "Focus on bug fixes in the auth module"
-```
+This analyzes your code, generating `.planning/ARCHITECTURE.md` and inferred development conventions.
 
 ---
 
-## 7. Browser Runtime & Visual QA (v2)
-MindForge can now control a persistent browser for visual verification and QA.
+## 5. Unified Workflow
 
-### Navigate and interact
-```bash
-/mindforge:browse --navigate https://example.com
-/mindforge:browse --click "#login-btn"
-```
+MindForge v2.1.1 uses a unified 4-pillar workflow for predictable delivery:
 
-### Run visual QA
-To scan for UI bugs and generate regression tests:
 ```bash
-/mindforge:qa --diff
+/mindforge:plan-phase [N]     # discuss → research → plan
+/mindforge:execute-phase [N]  # parallel execution of task plans
+/mindforge:verify-phase [N]   # UAT + automated validation
+/mindforge:ship [N]           # generate changelog + create PR
 ```
 
 ---
 
-## 8. Multi-Model Intelligence (v2)
-MindForge v2 can route tasks between Claude, GPT, and Gemini for the best balance of context, cost, and quality.
+## 6. High-Performance Personas
 
-### Cross-Model Review
-To get an adversarial review from multiple high-tier models:
-```bash
-/mindforge:cross-review
-```
-This will aggregate findings, detect consensus, and generate a `CROSS-REVIEW-[N].md` report.
+MindForge v2.1.1 introduces 32+ specialized personas. Each persona is optimized for a specific stage of the lifecycle.
 
-### Deep Research
-To leverage Gemini 1.5 Pro's huge context window for codebase-wide research:
-```bash
-/mindforge:research "How does the governance layer handle emergency overrides?"
-```
+- **Planner**: Orchestrates complex multi-file architectural changes.
+- **Executor**: Focused on pixel-perfect implementation and coding standards.
+- **Debugger**: Systematic root-cause analysis and verification.
+- **Researcher**: Deep codebase and dependency analysis via Context7.
+
+To switch personas or see the full list:
 
-### Cost Tracking
-Monitor your daily spend and model-specific usage:
 ```bash
-/mindforge:costs --summary
+/mindforge:personas --list
 ```
-MindForge will block further calls if `MODEL_COST_HARD_LIMIT_USD` is reached.
 
 ---
 
-## 9. Persistent Knowledge Graph (v2)
-MindForge now has long-term memory. It captures architectural decisions, bug patterns, and team preferences, making them available across project sessions.
+## 7. Autonomous Execution
 
-### Manual Memory entry
-To explicitly record a project-wide preference:
-```bash
-/mindforge:remember --add "preference: Use direct imports for internal modules" --tags "#nodejs"
-```
+For complex tasks that require minimal intervention:
 
-### Search and retrieval
-To find related knowledge manually:
 ```bash
-/mindforge:remember --search "Tailwind best practices"
+/mindforge:autonomous --phase [N]
 ```
 
-### Global Promotion
-To make a specific project insight available across ALL your MindForge projects on this machine:
+Use the **Steer** command to guide logic without stopping execution:
+
 ```bash
-/mindforge:remember --promote [ENTRY_ID]
+/mindforge:steer "Prioritize the React component refactoring"
 ```
 
-### Automatic Loading
-Relevant memories are automatically loaded at the start of every session, providing context about past decisions and patterns.
-
 ---
 
-## 10. Real-time Dashboard (v2)
-MindForge provides a premium web-based dashboard for real-time observability of your agent waves, metrics, and team activity.
+## 8. Real-time Dashboard
+
+Observe your agent waves, token spend, and milestone progress in real-time.
 
-### Start the Dashboard
 ```bash
 /mindforge:dashboard --start --open
 ```
-This will start the Express-based SSE bridge and open `http://localhost:7339` in your default browser.
 
-### Features
-- **Live Activity**: Real-time stream of audit logs and agent status.
-- **Metrics & Costs**: Live visualization of token spend and session quality.
-- **Browser Governance**: Approve or reject Tier 2/3 changes directly from the UI.
-- **Team Feed**: See what other agents are doing in a multi-agent environment.
+The dashboard provides a premium web interface at `http://localhost:7339`.
+
+---
+
+## 9. Persistent Knowledge & Memory
+
+MindForge captures architectural decisions and bug patterns across sessions.
 
-### Stop the Dashboard
 ```bash
-/mindforge:dashboard --stop
+/mindforge:note "Add to memory: Always use functional components for UI"
+/mindforge:remember --search "auth patterns"
 ```
 
 ---
 
-## 11. Update and migration
-### Check for updates
-```
-/mindforge:update
-```
+## 10. Self-Building Skills
 
-### Apply updates
-```
-/mindforge:update --apply
-```
+Extend MindForge by learning from documentation or community sources.
 
-### Run schema migrations manually
-```
-### Run schema migrations manually
-```
-/mindforge:migrate --from v1.0.0 --to v2.0.0
-```
+```bash
+/mindforge:learn https://docs.nextjs.org "nextjs-mastery"
 ```
 
-## 11. Plugins
-### List / validate
-```
-/mindforge:plugins list
-/mindforge:plugins validate
-```
+---
 
-### Install
-```
-/mindforge:plugins install mindforge-plugin-<name>
-```
+## 11. Git & PR Integration
 
-## 12. Custom Runtimes (v2)
-MindForge v2 allows you to scaffold support for any AI agent runtime by generating the necessary instruction files and directory structures.
+MindForge v2.1.1 features automated PR creation and commit management.
 
-### Scaffold a New Runtime
 ```bash
-/mindforge:new-runtime
+/mindforge:pr-branch "feature/auth-refactor"
+/mindforge:ship --auto-pr
 ```
-This command will interview you about the runtime's name, entry file (e.g., `INSTRUCTIONS.md`), and whether it supports slash commands. It then scaffolds the standard MindForge preamble and directory structure for that agent.
 
-## 12. Self-Building Skills (v2)
-MindForge can now learn new skills automatically from documentation, project history, or the community marketplace.
+---
 
-### Learn from Source
-To create a new skill from a URL, local file, or npm package:
-```bash
-/mindforge:learn https://docs.prisma.io "prisma-best-practices"
-```
-This triggers a 7-step generation pipeline that researches, extracts patterns, and scores the resulting skill.
+## 12. Update & Maintenance
+
+Keep your framework current with the latest personas and library updates:
 
-### Skills Marketplace
-Discover and install community-authored skills:
 ```bash
-/mindforge:marketplace search "tailwind"
-/mindforge:marketplace install mindforge-skill-react-patterns
+/mindforge:update --apply
 ```
 
-### Auto-Capture
-MindForge automatically detects recurring patterns in your phase outputs. After a successful `/mindforge:execute-phase`, the agent may suggest capturing a new skill if it identifies high-value engineering patterns.
+---
 
-## 13. Token usage profiling
-```
-/mindforge:tokens --profile
-/mindforge:tokens --summary
-```
+## 13. Reference & Support
 
-Token optimization policies are defined in:
-- `.mindforge/production/token-optimiser.md`
-
-## 14. Configuration (MINDFORGE.md)
-Key settings live in `MINDFORGE.md`. See:
-- `docs/reference/config-reference.md`
-
-Common settings:
-- `PLANNER_MODEL`, `EXECUTOR_MODEL`, `REVIEWER_MODEL`
-- `VERIFY_PASS_RATE_WARNING_THRESHOLD`
-- `TOKEN_WARN_THRESHOLD`, `TOKEN_LEAN_MODE`
-- `MINDFORGE_AUTO_CHECK_UPDATES`
-
-## 15. Troubleshooting
-- Health issues: run `/mindforge:health --repair`
-- Schema drift: run `/mindforge:migrate --dry-run` then apply
-- Installer issues: re-run with `--force`
-- CI mode: set `CI=true` and check `.mindforge/ci/` docs
-
-## 16. Security
-MindForge never stores credentials in files. See:
-- `docs/security/SECURITY.md`
-- `docs/security/threat-model.md`
-
-## 17. Reference docs
-- Commands: `docs/reference/commands.md`
-- SDK: `docs/reference/sdk-api.md`
-- Skills: `docs/reference/skills-api.md`
-- Audit events: `docs/reference/audit-events.md`
+- **Commands**: `docs/commands-reference.md`
+- **Personas**: `docs/PERSONAS.md`
+- **Troubleshooting**: `docs/troubleshooting.md`
+- **Discord**: `/mindforge:join-discord`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindforge-cc",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "MindForge - Enterprise Agentic Framework for Claude Code and Antigravity",
   "bin": {
     "mindforge-cc": "bin/install.js"
@@ -23,7 +23,9 @@
   ],
   "scripts": {
     "test": "node tests/install.test.js",
-    "lint": "eslint ."
+    "lint": "eslint .",
+    "commit": "cz",
+    "prepare": "husky"
   },
   "keywords": [
     "claude-code",
@@ -38,8 +40,11 @@
   "devDependencies": {
     "@eslint/js": "^9.0.0",
     "@types/node": "^20.0.0",
+    "commitizen": "4.3.1",
+    "cz-conventional-changelog": "3.3.0",
     "eslint": "^9.0.0",
     "globals": "^15.0.0",
+    "husky": "9.1.7",
     "playwright": "^1.40.0"
   },
   "engines": {

package/.mindforge/memory/knowledge-base.jsonl

@@ -1,7 +0,0 @@
-{"id":"34a7925f-7361-4836-91eb-916495033861","timestamp":"2026-03-22T17:25:37.659Z","type":"team_preference","topic":"Use Tailwind","content":"Always use Tailwind for CSS.","source":"manual","project":"[Project Name]","confidence":0.9,"tags":["ui","css"],"linked_adrs":[],"times_referenced":0,"last_referenced":null,"deprecated":false,"deprecated_by":null}
-{"id":"34a7925f-7361-4836-91eb-916495033861","timestamp":"2026-03-22T17:25:37.659Z","type":"team_preference","topic":"Use Tailwind","content":"Always use Tailwind for CSS.","source":"manual","project":"[Project Name]","confidence":0.9500000000000001,"tags":["ui","css"],"linked_adrs":[],"times_referenced":1,"last_referenced":"2026-03-22T17:25:37.665Z","deprecated":false,"deprecated_by":null}
-{"id":"34a7925f-7361-4836-91eb-916495033861","timestamp":"2026-03-22T17:25:37.659Z","type":"team_preference","topic":"Use Tailwind","content":"Always use Tailwind for CSS.","source":"manual","project":"[Project Name]","confidence":0.9500000000000001,"tags":["ui","css"],"linked_adrs":[],"times_referenced":1,"last_referenced":"2026-03-22T17:25:37.665Z","deprecated":true,"deprecated_by":null,"deprecated_reason":"Switching to Vanilla CSS","deprecated_at":"2026-03-22T17:25:37.666Z"}
-{"id":"a2d4b3a6-fdaa-4c9a-b654-286d9ea133e2","timestamp":"2026-03-22T17:25:37.670Z","type":"domain_knowledge","topic":"Auth with JWT","content":"Secure JWT with httpOnly cookies.","source":"manual","project":"[Project Name]","confidence":0.8,"tags":["auth"],"linked_adrs":[],"times_referenced":0,"last_referenced":null,"deprecated":false,"deprecated_by":null}
-{"id":"6c1f0f31-3903-4b95-bae8-5473ffbec9eb","timestamp":"2026-03-22T17:25:37.671Z","type":"domain_knowledge","topic":"Database SQL","content":"Use indexed columns for fast queries.","source":"manual","project":"[Project Name]","confidence":0.7,"tags":["db"],"linked_adrs":[],"times_referenced":0,"last_referenced":null,"deprecated":false,"deprecated_by":null}
-{"id":"a9878977-cb7c-4dcf-8161-760ffd5e7de9","timestamp":"2026-03-22T17:25:37.673Z","type":"code_pattern","topic":"React Memo","content":"Use React.memo to prevent re-renders.","source":"manual","project":"[Project Name]","confidence":0.6,"tags":["ui"],"linked_adrs":[],"times_referenced":0,"last_referenced":null,"deprecated":false,"deprecated_by":null}
-{"id":"739dcb0a-9c4b-40d2-846b-535b7e4cb274","timestamp":"2026-03-22T17:25:51.782Z","type":"team_preference","topic":"Use Tailwind","content":"Always use Tailwind for CSS.","source":"manual","project":"[Project Name]","confidence":0.9,"tags":["ui","css"],"linked_adrs":[],"times_referenced":0,"last_referenced":null,"deprecated":false,"deprecated_by":null}

package/.mindforge/memory/pattern-library.jsonl

@@ -1 +0,0 @@
-{"id":"a9878977-cb7c-4dcf-8161-760ffd5e7de9","timestamp":"2026-03-22T17:25:37.673Z","type":"code_pattern","topic":"React Memo","content":"Use React.memo to prevent re-renders.","source":"manual","project":"[Project Name]","confidence":0.6,"tags":["ui"],"linked_adrs":[],"times_referenced":0,"last_referenced":null,"deprecated":false,"deprecated_by":null}

package/.mindforge/memory/team-preferences.jsonl

@@ -1,4 +0,0 @@
-{"id":"34a7925f-7361-4836-91eb-916495033861","timestamp":"2026-03-22T17:25:37.659Z","type":"team_preference","topic":"Use Tailwind","content":"Always use Tailwind for CSS.","source":"manual","project":"[Project Name]","confidence":0.9,"tags":["ui","css"],"linked_adrs":[],"times_referenced":0,"last_referenced":null,"deprecated":false,"deprecated_by":null}
-{"id":"34a7925f-7361-4836-91eb-916495033861","timestamp":"2026-03-22T17:25:37.659Z","type":"team_preference","topic":"Use Tailwind","content":"Always use Tailwind for CSS.","source":"manual","project":"[Project Name]","confidence":0.9500000000000001,"tags":["ui","css"],"linked_adrs":[],"times_referenced":1,"last_referenced":"2026-03-22T17:25:37.665Z","deprecated":false,"deprecated_by":null}
-{"id":"34a7925f-7361-4836-91eb-916495033861","timestamp":"2026-03-22T17:25:37.659Z","type":"team_preference","topic":"Use Tailwind","content":"Always use Tailwind for CSS.","source":"manual","project":"[Project Name]","confidence":0.9500000000000001,"tags":["ui","css"],"linked_adrs":[],"times_referenced":1,"last_referenced":"2026-03-22T17:25:37.665Z","deprecated":true,"deprecated_by":null,"deprecated_reason":"Switching to Vanilla CSS","deprecated_at":"2026-03-22T17:25:37.666Z"}
-{"id":"739dcb0a-9c4b-40d2-846b-535b7e4cb274","timestamp":"2026-03-22T17:25:51.782Z","type":"team_preference","topic":"Use Tailwind","content":"Always use Tailwind for CSS.","source":"manual","project":"[Project Name]","confidence":0.9,"tags":["ui","css"],"linked_adrs":[],"times_referenced":0,"last_referenced":null,"deprecated":false,"deprecated_by":null}

package/.planning/browser-daemon.log

@@ -1,32 +0,0 @@
-node:internal/modules/cjs/loader:1459
-  throw err;
-  ^
-
-Error: Cannot find module 'playwright-core'
-Require stack:
-- /Users/sairamugge/Desktop/MindForge/bin/browser/browser-daemon.js
-    at Module._resolveFilename (node:internal/modules/cjs/loader:1456:15)
-    at defaultResolveImpl (node:internal/modules/cjs/loader:1066:19)
-    at resolveForCJSWithHooks (node:internal/modules/cjs/loader:1071:22)
-    at Module._load (node:internal/modules/cjs/loader:1242:25)
-    at wrapModuleLoad (node:internal/modules/cjs/loader:255:19)
-    at Module.require (node:internal/modules/cjs/loader:1556:12)
-    at require (node:internal/modules/helpers:152:16)
-    at Object.<anonymous> (/Users/sairamugge/Desktop/MindForge/bin/browser/browser-daemon.js:9:20)
-    at Module._compile (node:internal/modules/cjs/loader:1812:14)
-    at Object..js (node:internal/modules/cjs/loader:1943:10) {
-  code: 'MODULE_NOT_FOUND',
-  requireStack: [
-    '/Users/sairamugge/Desktop/MindForge/bin/browser/browser-daemon.js'
-  ]
-}
-
-Node.js v24.14.0
-[daemon] Browser daemon listening on port 7338
-[daemon] Browser daemon listening on port 7338
-[daemon] Browser daemon listening on port 7338
-[daemon] Browser daemon listening on port 7338
-[daemon] Browser daemon listening on port 7338
-[daemon] Browser daemon listening on port 7338
-[daemon] Browser daemon listening on port 7338
-[daemon] Browser daemon listening on port 7338

package/docs/mindforge-md-reference.md

@@ -1,57 +0,0 @@
-# MINDFORGE.md Reference
-
-`MINDFORGE.md` is the project-level constitution for MindForge defaults.
-
-## Location
-Place at repo root beside `package.json`.
-
-## Syntax
-- `KEY=value`
-- comments with `#`
-- multiline values with triple quotes
-
-## Core settings
-### Model preferences
-- `PLANNER_MODEL`
-- `EXECUTOR_MODEL`
-- `REVIEWER_MODEL`
-- `VERIFIER_MODEL`
-- `SECURITY_MODEL`
-
-Valid values: `claude-opus-4-5`, `claude-sonnet-4-5`, `claude-haiku-4-5`, `inherit`.
-Unavailable value -> fallback to `inherit` with warning.
-
-### Execution behavior
-- `TIER1_AUTO_APPROVE`
-- `WAVE_CONFIRMATION_REQUIRED`
-- `AUTO_DISCUSS_PHASE`
-- `VERIFY_PASS_RATE_WARNING_THRESHOLD`
-- `COMPACTION_THRESHOLD_PCT`
-- `MAX_TASKS_PER_PHASE`
-- `AUTONOMOUS_MODE_ENABLED`
-- `NODE_REPAIR_ENABLED`
-- `STUCK_DETECTION_TIMEOUT_MS`
-- `STEERING_CHECK_INTERVAL_MS`
-
-### Quality and governance
-- `MIN_TEST_COVERAGE_PCT`
-- `MAX_FUNCTION_LINES`
-- `MAX_CYCLOMATIC_COMPLEXITY`
-- `BLOCK_ON_MEDIUM_SECURITY_FINDINGS`
-- `DISCUSS_PHASE_REQUIRED_ABOVE_DIFFICULTY`
-- `ANTIPATTERN_SENSITIVITY`
-
-### Skills
-- `ALWAYS_LOAD_SKILLS`
-- `DISABLED_SKILLS`
-- `MAX_FULL_SKILL_INJECTIONS`
-
-## Non-overridable rules
-Cannot be overridden in MINDFORGE.md:
-- security auto-trigger
-- plan-first rule
-- secret detection gate
-- audit-writing requirement
-- critical security/secret blocking quality gates
-
-See ADR-013 for rationale.

package/docs/reference/config-reference.md

@@ -1,64 +0,0 @@
-# MindForge Configuration Reference (MINDFORGE.md)
-
-## Location
-`MINDFORGE.md` in the project root (beside `package.json`).
-
-## Syntax
-- `KEY=value`
-- Comments with `#`
-- Multiline values with triple quotes
-
-## Model preferences
-- `PLANNER_MODEL`
-- `EXECUTOR_MODEL`
-- `REVIEWER_MODEL`
-- `VERIFIER_MODEL`
-- `SECURITY_MODEL`
-- `DEBUG_MODEL`
-
-Valid values: `claude-opus-4-5`, `claude-sonnet-4-5`, `claude-haiku-4-5`, `inherit`.
-Unavailable values fallback to `inherit` with a warning.
-
-## Execution behavior
-- `TIER1_AUTO_APPROVE`
-- `WAVE_CONFIRMATION_REQUIRED`
-- `AUTO_DISCUSS_PHASE`
-- `VERIFY_PASS_RATE_WARNING_THRESHOLD` (v1.0.0 uses 0.0–1.0 range)
-- `COMPACTION_THRESHOLD_PCT`
-- `MAX_TASKS_PER_PHASE`
-
-## Quality standards
-- `MIN_TEST_COVERAGE_PCT`
-- `MAX_FUNCTION_LINES`
-- `MAX_CYCLOMATIC_COMPLEXITY`
-- `REQUIRE_ADR_FOR_ALL_DECISIONS`
-- `BLOCK_ON_MEDIUM_SECURITY_FINDINGS`
-
-## Skills behavior
-- `ALWAYS_LOAD_SKILLS`
-- `DISABLED_SKILLS`
-- `MAX_FULL_SKILL_INJECTIONS`
-
-## Governance behavior
-- `DISCUSS_PHASE_REQUIRED_ABOVE_DIFFICULTY`
-- `ANTIPATTERN_SENSITIVITY`
-- `BLOCK_ON_HIGH_ANTIPATTERNS`
-
-## Token settings
-- `TOKEN_WARN_THRESHOLD`
-- `TOKEN_LEAN_MODE`
-- `TOKEN_MAX_FILE_LINES`
-
-## Update settings
-- `MINDFORGE_AUTO_CHECK_UPDATES` (true/false)
-
-## Non-overridable rules
-The following cannot be overridden by MINDFORGE.md:
-- Security auto-trigger for auth/payment/PII changes
-- Plan-first rule
-- Secret detection gate
-- AUDIT writing requirement
-- Critical security and secret-related quality gates
-
-See `.mindforge/production/token-optimiser.md` and `docs/mindforge-md-reference.md`
-for full detail.