mindforge-cc 1.0.5 → 2.0.0-alpha.6

package/docs/reference/commands.md

@@ -1,8 +1,9 @@
-# MindForge v1.0.0 — Complete Commands Reference
+# MindForge v2.0.0 — Complete Commands Reference
 
-## All 36 commands
+## All 40+ commands
 
 ### Lifecycle commands (core workflow)
+
 | Command | Usage | Description | Added |
 |---|---|---|---|
 | `/mindforge:init-project` | `init-project` | Guided project setup — creates all `.planning/` files | Day 1 |
@@ -11,9 +12,15 @@
 | `/mindforge:execute-phase` | `execute-phase [N]` | Wave-based parallel execution of all phase plans | Day 1+2 |
 | `/mindforge:verify-phase` | `verify-phase [N]` | Automated + human acceptance testing pipeline | Day 1 |
 | `/mindforge:ship` | `ship [N]` | Create PR, write release notes, push to remote | Day 1 |
+| `/mindforge:auto` | `auto [--phase N] [--milestone M]` | Walk-away autonomous execution with stuck detection | Day 8 |
+| `/mindforge:steer` | `steer "instruction"` | Inject guidance into a running autonomous session | Day 8 |
 | `/mindforge:next` | `next` | Auto-detect and execute the correct next workflow step | Day 2 |
+| `/mindforge:cross-review` | `cross-review` | Adversarial multi-model code review and synthesis | Day 10 |
+| `/mindforge:research` | `research "query"` | Deep research using Gemini 1.5 Pro 1M context | Day 10 |
+| `/mindforge:remember` | `remember [--add X|--search Y|--promote ID|--stats]` | Persistent knowledge graph management | Day 11 |
 
 ### Project setup & discovery
+
 | Command | Usage | Description | Added |
 |---|---|---|---|
 | `/mindforge:map-codebase` | `map-codebase` | Brownfield onboarding: infer stack and seed docs | Day 6 |
@@ -24,6 +31,7 @@
 | `/mindforge:debug` | `debug [plan-id]` | Debug a failed plan with root-cause workflow | Day 5 |
 
 ### Governance & compliance
+
 | Command | Usage | Description | Added |
 |---|---|---|---|
 | `/mindforge:approve` | `approve [--tier 2|3]` | Process approvals and emergency overrides | Day 4 |
@@ -34,6 +42,7 @@
 | `/mindforge:retrospective` | `retrospective [N]` | Phase retrospective and improvement actions | Day 5 |
 
 ### Skills & plugins
+
 | Command | Usage | Description | Added |
 |---|---|---|---|
 | `/mindforge:skills` | `skills [list|validate|refresh]` | Manage core/org/project skills | Day 3 |
@@ -42,6 +51,7 @@
 | `/mindforge:plugins` | `plugins [list|install|uninstall|validate]` | Manage plugin lifecycle | Day 7 |
 
 ### Intelligence & metrics
+
 | Command | Usage | Description | Added |
 |---|---|---|---|
 | `/mindforge:metrics` | `metrics [--phase N]` | Compute quality and throughput metrics | Day 5 |
@@ -50,6 +60,7 @@
 | `/mindforge:tokens` | `tokens [--profile] [--summary]` | Token usage profiling and optimisation | Day 7 |
 
 ### Integrations & distribution
+
 | Command | Usage | Description | Added |
 |---|---|---|---|
 | `/mindforge:init-org` | `init-org` | Org-wide MindForge setup | Day 6 |
@@ -57,8 +68,11 @@
 | `/mindforge:sync-confluence` | `sync-confluence [--page ...]` | Publish docs to Confluence | Day 4 |
 | `/mindforge:pr-review` | `pr-review [--range A..B]` | AI PR review with context | Day 6 |
 | `/mindforge:workspace` | `workspace [detect|plan|test]` | Monorepo workspace management | Day 6 |
+| `/mindforge:browse` | `browse [--navigate URL] [--command]` | Control persistent browser daemon and sessions | Day 9 |
+| `/mindforge:qa` | `qa [--diff] [--all]` | Run systematic visual QA and regression tests | Day 9 |
 
 ### Release & maintenance
+
 | Command | Usage | Description | Added |
 |---|---|---|---|
 | `/mindforge:update` | `update [--apply] [--force] [--check]` | Check for and apply framework updates | Day 7 |
@@ -66,6 +80,7 @@
 | `/mindforge:release` | `release [--tag vX]` | Framework release pipeline (core team) | Day 7 |
 
 ### Utility
+
 | Command | Usage | Description | Added |
 |---|---|---|---|
 | `/mindforge:help` | `help` | Show all available commands and current project status | Day 1 |

package/docs/reference/sdk-api.md

@@ -1,18 +1,23 @@
-# MindForge SDK API — Reference (v1.0.0)
+# MindForge SDK API — Reference (v2.0.0-alpha.4)
 
 ## Package
+
 `@mindforge/sdk`
 
 ## Exports
+
 From `sdk/src/index.ts`:
+
 - `MindForgeClient`
 - `MindForgeEventStream`
 - `commands`
+- `MindForgeMemory` (Day 11)
 - Types: `MindForgeConfig`, `PhaseResult`, `TaskResult`, `SecurityFinding`,
   `GateResult`, `HealthReport`, `HealthIssue`, `MindForgeEvent`, `CommandOptions`
 - `VERSION`
 
 ## MindForgeClient
+
 High-level API for reading local project state.
 
 Methods:

package/docs/testing-current-version.md

@@ -0,0 +1,130 @@
+# MindForge v2.0.0-alpha.6: In-Depth Testing Guide (Antigravity)
+
+This document provides a step-by-step rigorous testing flow to validate the entire MindForge framework from a blank project state. It is designed to be shared and logged for architectural review.
+
+## 🏁 Phase 0: Isolated Setup
+1. Create a new empty directory (e.g., `Mind-Forge-Test`): `mkdir Mind-Forge-Test && cd Mind-Forge-Test`
+2. **Linked Alpha Testing** (Simulated Live Publish):
+   - Use the **Absolute Binary Path** to bypass shell PATH configuration issues:
+     ```bash
+     /Users/sairamugge/.vite-plus/js_runtime/node/24.14.0/bin/mindforge-cc --antigravity --local
+     ```
+   - *Confirmation*: Run the command with `--version`. It must show `v2.0.0-alpha.6`.
+3. Verify the local binary exists: `ls agents/bin/install.js` (or `.agent/bin/install.js` if legacy)
+
+## 🏗 Phase 1: Registry & Integrity
+**Objective**: Verify that MindForge correctly registers the project and mirrors commands.
+
+**Command**:
+```bash
+./mindforge:init-project
+```
+
+**Post-Init Verification**:
+- Check `.claude/commands/mindforge/` and `.agent/commands/mindforge/`. They should be identical.
+- Verify the project is in the global registry (optional):
+  ```bash
+  cat ~/.mindforge/registry.json
+  ```
+**Prompt to Agent**:
+> "Initialize this project for me. I am building a simple 'Weather Proxy API' in Node.js. Please set up the `.planning/` directory and registry."
+
+**Success Criteria**:
+- `.planning/PROJECT.md` is created with the Weather Proxy brief.
+- `.mindforge/` metadata directory is populated.
+
+## 📝 Phase 2: Workflow & Planning
+**Objective**: Test the planning engine and dependency mapping.
+
+**Prompt to Agent**:
+> "I need a plan to implement the weather service. Phase 1 should handle the API structure, Phase 2 should handle the weather fetching logic, and Phase 3 should add caching. Generate a detailed plan for Phase 1."
+
+**Command**:
+```bash
+/mindforge:plan-phase 1
+```
+
+**Success Criteria**:
+- `.planning/phases/phase-1/PLAN.md` is generated.
+- Plan status is set to `[ ]` in `task.md`.
+
+## 🤖 Phase 3: Autonomous Execution (The "Walk-Away" Test)
+**Objective**: Test the `/mindforge:auto` engine and state management.
+
+**Command**:
+```bash
+/mindforge:auto --phase 1
+```
+
+**Success Criteria**:
+- MindForge iterates through tasks without human intervention.
+- Code is written to the project (e.g., `index.js`, `routes/`).
+- `.planning/AUDIT.jsonl` is logging every execution step.
+
+## 📊 Phase 4: Observability (Dashboard)
+**Objective**: Test the Real-time Dashboard and SSE Bridge.
+
+**Command**:
+```bash
+/mindforge:dashboard --start --open
+```
+
+**Testing Steps**:
+1. Keep the dashboard open at `http://localhost:7339`.
+2. Run another command (e.g., `/mindforge:health`).
+3. Verify that the "Activity Feed" in the browser updates instantly.
+4. Check the "Metrics" tab for token spend data.
+
+## 🧠 Phase 5: Persistent Memory
+**Objective**: Test the Knowledge Graph retrieval.
+
+**Command**:
+```bash
+/mindforge:remember --search "api structure"
+```
+
+**Success Criteria**:
+- MindForge returns findings from the earlier `/mindforge:init-project` or `/mindforge:plan-phase` steps.
+
+## ⚔️ Phase 6: Multi-Model Hardening
+**Objective**: Test the adversarial cross-review system.
+
+**Command**:
+```bash
+/mindforge:cross-review
+```
+
+**Success Criteria**:
+- MindForge invokes secondary models (GPT/Gemini) to critique the code generated in Phase 3.
+- Review results are logged in `review_results.md`.
+
+## 🚢 Phase 7: Verification & Shipping
+**Objective**: Test the quality gates and release automation.
+
+**Commands**:
+```bash
+/mindforge:verify-phase 1
+/mindforge:ship 1
+```
+
+**Success Criteria**:
+- `CHANGELOG.md` is updated.
+- A PR-ready diff is generated.
+
+---
+
+## 🛡 Phase 8: Framework Conflict Check
+**Objective**: Ensure MindForge is isolated from other frameworks.
+
+1. **Port Check**: Verify the dashboard is on `7339` and not conflicting with common framework ports (e.g., 8000, 8080).
+2. **Directory Check**: Ensure no other framework is writing to `.planning/` or `.mindforge/`.
+3. **Process Check**: Run `ps aux | grep mindforge` to ensure only one instance of the SSE bridge is active.
+
+## 📂 Logging for Review
+All Antigravity sessions are logged. To share your results for review, zip and send:
+- `.planning/AUDIT.jsonl` (Full execution history)
+- `CHANGELOG.md` (Outcome summary)
+## 💡 Troubleshooting
+- **Command not found**: Ensure you are using `./mindforge:command` or `/mindforge:command` within the agent.
+- **Wrong Version**: Run `/mindforge:health` and check for "v2.0.0-alpha.6". If it shows "v1.0.5", your installation failed or you are using the global `npx` version.
+- **Registry Error**: Check `~/.mindforge/registry.json` exists; it is now automatically created by the v2 installer.

package/docs/user-guide.md

@@ -1,4 +1,4 @@
-# MindForge User Guide (v1.0.0)
+# MindForge User Guide (v2.0.0-alpha.6)
 
 This guide gets you from install to productive, with the minimum needed to run
 MindForge in a real project. It assumes Node.js 18+.
@@ -68,7 +68,113 @@ This generates `.planning/ARCHITECTURE.md` and an inferred conventions file.
 /mindforge:ship 1
 ```
 
-## 6. Update and migration
+## 6. Autonomous Execution (v2)
+For complex phases that require no human intervention, use the autonomous engine.
+
+### Start autonomous phase
+```bash
+/mindforge:auto --phase 1
+```
+
+### 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"
+```
+
+---
+
+## 7. Browser Runtime & Visual QA (v2)
+MindForge can now control a persistent browser for visual verification and QA.
+
+### Navigate and interact
+```bash
+/mindforge:browse --navigate https://example.com
+/mindforge:browse --click "#login-btn"
+```
+
+### Run visual QA
+To scan for UI bugs and generate regression tests:
+```bash
+/mindforge:qa --diff
+```
+
+---
+
+## 8. Multi-Model Intelligence (v2)
+MindForge v2 can route tasks between Claude, GPT, and Gemini for the best balance of context, cost, and quality.
+
+### 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.
+
+### 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?"
+```
+
+### Cost Tracking
+Monitor your daily spend and model-specific usage:
+```bash
+/mindforge:costs --summary
+```
+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.
+
+### Manual Memory entry
+To explicitly record a project-wide preference:
+```bash
+/mindforge:remember --add "preference: Use direct imports for internal modules" --tags "#nodejs"
+```
+
+### Search and retrieval
+To find related knowledge manually:
+```bash
+/mindforge:remember --search "Tailwind best practices"
+```
+
+### Global Promotion
+To make a specific project insight available across ALL your MindForge projects on this machine:
+```bash
+/mindforge:remember --promote [ENTRY_ID]
+```
+
+### 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.
+
+### 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.
+
+### Stop the Dashboard
+```bash
+/mindforge:dashboard --stop
+```
+
+---
+
+## 11. Update and migration
 ### Check for updates
 ```
 /mindforge:update
@@ -84,7 +190,7 @@ This generates `.planning/ARCHITECTURE.md` and an inferred conventions file.
 /mindforge:migrate --from v0.6.0 --to v1.0.0
 ```
 
-## 7. Plugins
+## 11. Plugins
 ### List / validate
 ```
 /mindforge:plugins list
@@ -96,7 +202,7 @@ This generates `.planning/ARCHITECTURE.md` and an inferred conventions file.
 /mindforge:plugins install mindforge-plugin-<name>
 ```
 
-## 8. Skills
+## 12. Skills
 ```
 /mindforge:skills list
 /mindforge:skills validate
@@ -104,7 +210,7 @@ This generates `.planning/ARCHITECTURE.md` and an inferred conventions file.
 
 To publish or install a skill, see `docs/skills-publishing-guide.md`.
 
-## 9. Token usage profiling
+## 13. Token usage profiling
 ```
 /mindforge:tokens --profile
 /mindforge:tokens --summary
@@ -113,7 +219,7 @@ To publish or install a skill, see `docs/skills-publishing-guide.md`.
 Token optimization policies are defined in:
 - `.mindforge/production/token-optimiser.md`
 
-## 10. Configuration (MINDFORGE.md)
+## 14. Configuration (MINDFORGE.md)
 Key settings live in `MINDFORGE.md`. See:
 - `docs/reference/config-reference.md`
 
@@ -123,18 +229,18 @@ Common settings:
 - `TOKEN_WARN_THRESHOLD`, `TOKEN_LEAN_MODE`
 - `MINDFORGE_AUTO_CHECK_UPDATES`
 
-## 11. Troubleshooting
+## 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
 
-## 12. Security
+## 16. Security
 MindForge never stores credentials in files. See:
 - `docs/security/SECURITY.md`
 - `docs/security/threat-model.md`
 
-## 13. Reference docs
+## 17. Reference docs
 - Commands: `docs/reference/commands.md`
 - SDK: `docs/reference/sdk-api.md`
 - Skills: `docs/reference/skills-api.md`

package/docs/usp-features.md

@@ -1,7 +1,7 @@
-# MindForge v1.0.0 — Unique Selling Points, Features, and Best Practices
+# MindForge v2.0.0 — Unique Selling Points, Features, and Best Practices (v2.0.0-alpha.6)
 
-This document summarizes what makes MindForge v1.0.0 distinct, what features
-are included in the first stable release, and how to use them effectively.
+This document summarizes what makes MindForge v2.0.0 distinct, what features
+are included in the latest alpha release, and how to use them effectively.
 
 ---
 
@@ -31,6 +31,21 @@ are included in the first stable release, and how to use them effectively.
 7. **Extensible with plugins and skills**
    - Plugins add commands and skills without changing core files, keeping upgrades safe.
 
+8. **Autonomous “Walk-Away” Execution (v2)**
+   - `/mindforge:auto` allows for full phase/milestone completion with intelligent stuck detection and node repair (RETRY → DECOMPOSE → ESCALATE).
+
+9. **Persistent Visual QA (v2)**
+   - Headful/headless browser runtime with named session persistence and systematic visual diff verification.
+
+10. **Multi-Model Intelligence Layer (v2)**
+    - Dynamic routing between Anthropic, OpenAI, and Gemini based on task persona and security tier. Adversarial code reviews ensure maximum coverage.
+
+11. **Persistent Knowledge Graph (v2)**
+    - Captures and ranks engineering context (decisions, bug patterns, preferences) across project sessions using TF-IDF and confidence reinforcement.
+
+12. **Real-time Observability Dashboard (v2)**
+    - High-fidelity web interface for live audit streams, metrics visualization, and browser-based governance with zero performance overhead.
+
 ---
 
 ## Feature Set (v1.0.0)
@@ -141,18 +156,65 @@ preserving scope (local vs global).
 
 ---
 
-### 10. Token Usage Optimiser
-**What it does:** Profiles and reduces token usage across sessions.
+### 11. Autonomous Execution (v2)
+**What it does:** Enables handoff-free execution of complex phases and milestones.
 
 **How to use:**
+```bash
+/mindforge:auto --phase 1
+/mindforge:steer "Focus on security hardening next"
 ```
-/mindforge:tokens --profile
-/mindforge:tokens --summary
+
+---
+
+### 12. Browser Runtime & Visual QA (v2)
+**What it does:** Playwright-powered browser control with session persistence and automated UI bug detection.
+
+**How to use:**
+```bash
+/mindforge:browse --navigate https://example.com
+/mindforge:qa --diff
+```
+
+---
+
+### 13. Multi-Model Intelligence (v2)
+**What it does:** Unified API client for Anthropic, OpenAI, and Gemini with persona-based routing and automated cost tracking.
+
+**How to use:**
+```bash
+/mindforge:cross-review # Adversarial multi-model review
+/mindforge:research "Deep search query" # 1M context research
+/mindforge:costs # Usage and budget summary
+```
+
+---
+
+### 14. Persistent Knowledge Graph (v2)
+**What it does:** Long-term memory system that ensures architectural decisions and bug patterns are never forgotten. Supports TF-IDF search, confidence scoring, and global promotion.
+
+**How to use:**
+```bash
+/mindforge:remember --add "insight" # Manual capture
+/mindforge:remember --search "query" # Manual retrieval
+/mindforge:remember --promote [ID] # Promote to machine-wide global store
+/mindforge:remember --stats # View memory health
+```
+
+---
+
+### 16. Real-time Dashboard (v2)
+**What it does:** Web-based control plane for observing agent waves, costs, and quality metrics in real-time.
+
+**How to use:**
+```bash
+/mindforge:dashboard --start --open
 ```
+Access at `http://localhost:7339` (Localhost-only for security).
 
 ---
 
-### 11. SDK (TypeScript)
+### 15. SDK (TypeScript)
 **What it does:** Programmatic access to health, audit log, event stream, and commands.
 
 **How to use:**

package/docs/workflow-atlas.md

@@ -0,0 +1,57 @@
+# 🗺️ MindForge Workflow Atlas
+
+This document classifies every workflow and action in the MindForge `.github/` directory, explaining their triggers, roles, and governance tiers.
+
+---
+
+## 🏗️ The 5-Layer Plane Architecture (v2.0.0 — Recommended)
+
+These workflows form the modular "Beast" architecture implemented for enterprise-grade autonomy.
+
+### 1. Control Plane (`control-plane.yml`)
+- **Primary Trigger**: `push` or `pull_request` to `main` or `develop`.
+- **Role**: The Central Nervous System. It runs the `change-classifier.js` to assign a **Governance Tier (1-3)**. It enforces security gates and routes execution to other planes.
+- **Priority**: High. This is the non-bypassable entry point.
+
+### 2. Execution Plane (`execution-plane.yml`)
+- **Primary Trigger**: `workflow_call` (Exclusively invoked by the Control Plane).
+- **Role**: The Muscle. It handles the environment setup, project health checks (`mindforge-cli.js health`), and executes the agent in `--headless` mode.
+- **Verification**: Runs `npm test` and `npm run lint`.
+
+### 3. AI Intelligence Layer (`ai-intelligence.yml`)
+- **Primary Trigger**: `workflow_call` (Invoked by Control Plane specifically on Pull Requests).
+- **Role**: The Brain. Performs adversarial code reviews using **Claude** and **GPT-4o**. Posts a combined architectural review as a PR comment.
+
+### 4. Release Plane (`release-plane.yml`)
+- **Primary Trigger**: `push` of a version tag (e.g., `git push origin v1.2.3`).
+- **Role**: The Logistics. Automates building the package, publishing to **npm**, and drafting a GitHub Release with changelogs.
+
+### 5. Observability Plane (`observability-plane.yml`)
+- **Primary Trigger**: `workflow_run` (Auto-runs whenever the "MindForge Control Plane" completes).
+- **Role**: The Memory. Collects metrics on token costs, success rates, and audit logs to generate a summary of CI effectiveness.
+
+---
+
+## 🏛️ Maintenance & Legacy Workflows
+
+These are existing workflows that provide secondary check-points or manual controls.
+
+| Workflow | Trigger | Role | Status |
+| :--- | :--- | :--- | :--- |
+| `mindforge-ci.yml` | `push` to `main` or `feat/**` | Basic health/test check for feature branches. | **Active** |
+| `mindforge-autonomous.yml` | `schedule` (Daily) or Manual | Runs deep maintenance or long-running tasks. | **Active** |
+| `mindforge-ai-review.yml` | PR Label: `needs-review` | Label-triggered deep AI review. | **Fallback** |
+| `mindforge-release.yml` | Tag: `v*` | Original release script. | **Redundant** |
+| `mindforge-observability.yml`| `workflow_run` of "Core CI" | Original observability collector. | **Redundant** |
+
+---
+
+## 🚦 Trigger Logic Summary
+
+| Event | Workflow Triggered | Primary Action |
+| :--- | :--- | :--- |
+| **New PR** | `control-plane.yml` | Classify → Security Scan → AI PR Review |
+| **Commit to main** | `control-plane.yml` | Governance check → Execution |
+| **Push Tag (v*)** | `release-plane.yml` | Publish to npm → Create GitHub Release |
+| **Manual Reset** | `mindforge-autonomous.yml` | Run /mindforge:auto on specific phase |
+| **Midnight** | `mindforge-autonomous.yml` | Daily health & autonomous cleanup |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindforge-cc",
-  "version": "1.0.5",
+  "version": "2.0.0-alpha.6",
   "description": "MindForge - Enterprise Agentic Framework for Claude Code and Antigravity",
   "bin": {
     "mindforge-cc": "bin/install.js"
@@ -39,9 +39,13 @@
     "@eslint/js": "^9.0.0",
     "@types/node": "^20.0.0",
     "eslint": "^9.0.0",
-    "globals": "^15.0.0"
+    "globals": "^15.0.0",
+    "playwright": "^1.40.0"
   },
   "engines": {
     "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "express": "^4.19.2"
   }
-}
+}