mindforge-cc 1.0.0

package/docs/usp-features.md

@@ -0,0 +1,214 @@
+# MindForge v1.0.0 — Unique Selling Points, Features, and Best Practices
+
+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.
+
+---
+
+## Unique Selling Points (USPs)
+
+1. **File‑driven governance, not magic**
+   - MindForge defines behavior through Markdown and JSON schemas, so teams can
+     audit, review, and version everything like normal code.
+
+2. **Wave‑based parallel execution**
+   - Plans run in dependency‑ordered “waves,” delivering speed without chaos.
+
+3. **Non‑bypassable compliance gates**
+   - Security, secrets, and test gates are enforced by design, not optional.
+
+4. **Session compaction with continuity**
+   - When context fills, MindForge writes machine‑readable handoffs that preserve
+     state, decisions, and next steps.
+
+5. **Production‑ready installer + updater**
+   - Full install/update/uninstall support for both Claude Code and Antigravity,
+     plus scoped updates and schema migrations.
+
+6. **Built‑in audit trail**
+   - `AUDIT.jsonl` provides a complete, append‑only history of actions and results.
+
+7. **Extensible with plugins and skills**
+   - Plugins add commands and skills without changing core files, keeping upgrades safe.
+
+---
+
+## Feature Set (v1.0.0)
+
+### 1. Installation & Distribution
+**What it does:** Production‑grade installer with update, uninstall, and CI support.
+
+**How to use:**
+```bash
+npx mindforge-cc@latest --claude --global
+npx mindforge-cc@latest --claude --local
+npx mindforge-cc@latest --antigravity --global
+```
+
+---
+
+### 2. Core Workflow Engine
+**What it does:** End‑to‑end lifecycle for planning, execution, verification, and shipping.
+
+**How to use:**
+```
+/mindforge:init-project
+/mindforge:plan-phase 1
+/mindforge:execute-phase 1
+/mindforge:verify-phase 1
+/mindforge:ship 1
+```
+
+---
+
+### 3. Wave Execution
+**What it does:** Runs independent plans in parallel waves based on dependencies.
+
+**How to use:**
+- Create a phase plan with dependencies
+- Run `/mindforge:execute-phase N`
+- MindForge groups tasks into waves automatically
+
+---
+
+### 4. Governance & Compliance Gates
+**What it does:** Enforces secret scanning, CRITICAL security findings, tests,
+CVE checks, and GDPR retention.
+
+**How to use:**
+```
+/mindforge:security-scan --deep --secrets --deps
+/mindforge:verify-phase 1
+```
+
+---
+
+### 5. Intelligence Layer
+**What it does:** Health checks, difficulty scoring, anti‑pattern detection,
+team profiling, and metrics.
+
+**How to use:**
+```
+/mindforge:health
+/mindforge:metrics
+/mindforge:profile-team
+```
+
+---
+
+### 6. Skills Platform
+**What it does:** Loads skill packs on keyword triggers (Core/Org/Project tiers).
+
+**How to use:**
+```
+/mindforge:skills list
+/mindforge:skills validate
+```
+
+---
+
+### 7. Plugin System
+**What it does:** Extends MindForge with new commands, skills, personas, and hooks.
+
+**How to use:**
+```
+/mindforge:plugins list
+/mindforge:plugins install mindforge-plugin-<name>
+/mindforge:plugins validate
+```
+
+---
+
+### 8. Migration Engine
+**What it does:** Safely upgrades `.planning/` schemas across versions with backups.
+
+**How to use:**
+```
+/mindforge:migrate --from v0.6.0 --to v1.0.0
+```
+
+---
+
+### 9. Self‑Update System
+**What it does:** Checks for updates, shows changelog diff, applies updates while
+preserving scope (local vs global).
+
+**How to use:**
+```
+/mindforge:update
+/mindforge:update --apply
+```
+
+---
+
+### 10. Token Usage Optimiser
+**What it does:** Profiles and reduces token usage across sessions.
+
+**How to use:**
+```
+/mindforge:tokens --profile
+/mindforge:tokens --summary
+```
+
+---
+
+### 11. SDK (TypeScript)
+**What it does:** Programmatic access to health, audit log, event stream, and commands.
+
+**How to use:**
+```ts
+import { MindForgeClient } from '@mindforge/sdk';
+const client = new MindForgeClient({ projectRoot: '.' });
+const report = await client.health();
+```
+
+---
+
+## Best Practices for v1.0.0
+
+1. **Always run health after install**
+   - `/mindforge:health --repair` fixes drift immediately.
+
+2. **Keep PLAN files lean**
+   - Focus on *what*, not *how* (150–400 words).
+
+3. **Use local installs for repos**
+   - Local installs are safer and prevent cross‑project drift.
+
+4. **Run migrations explicitly**
+   - Don’t rely on auto‑inference when upgrading older state files.
+
+5. **Treat plugins like production dependencies**
+   - Validate plugins and prefer pinned versions.
+
+6. **Use the audit log as ground truth**
+   - Query `.planning/AUDIT.jsonl` for accountability and traceability.
+
+7. **Gate Tier 3 changes through approvals**
+   - CI will block Tier 3 changes without explicit approval.
+
+8. **Keep secrets out of files**
+   - Use environment variables only. MindForge enforces this.
+
+---
+
+## Using MindForge for Your Requirements
+
+### If you need strict governance
+- Run full workflow (`plan → execute → verify → ship`)
+- Enable security scans and approvals
+
+### If you need fast iteration
+- Use `/mindforge:quick` for single tasks
+- Keep local install with minimal setup
+
+### If you need team scale
+- Use milestones, approvals, and `/mindforge:profile-team`
+- Enable CI mode for consistent enforcement
+
+---
+
+## Summary
+MindForge v1.0.0 combines governance, observability, and execution rigor into a
+single workflow engine that works across Claude Code and Antigravity. Its core
+value is consistent, repeatable quality in long‑running AI development sessions.

package/eslint.config.mjs

@@ -0,0 +1,31 @@
+import js from "@eslint/js";
+import globals from "globals";
+
+/** @type {import('eslint').Linter.Config[]} */
+export default [
+  js.configs.recommended,
+  {
+    languageOptions: {
+      ecmaVersion: "latest",
+      sourceType: "module",
+      globals: {
+        ...globals.node,
+        ...globals.es2021
+      }
+    },
+    rules: {
+      "no-console": "off",
+      "no-unused-vars": "warn",
+      "semi": ["error", "always"],
+      "quotes": ["error", "single"]
+    }
+  },
+  {
+    ignores: [
+      "**/node_modules/",
+      "dist/",
+      "coverage/",
+      ".gemini/"
+    ]
+  }
+];

package/examples/starter-project/.planning/AUDIT.jsonl

@@ -0,0 +1 @@
+{"id":"example-001","timestamp":"2026-03-22T00:00:00.000Z","event":"project_initialised","agent":"mindforge-example","phase":null,"session_id":"example-session"}

package/examples/starter-project/.planning/HANDOFF.json

@@ -0,0 +1,23 @@
+{
+  "schema_version": "1.0.0",
+  "plugin_api_version": "1.0.0",
+  "project": "Example Project",
+  "phase": null,
+  "plan": null,
+  "next_task": "Run /mindforge:plan-phase 1",
+  "blockers": [],
+  "decisions_needed": [],
+  "decisions_made": [],
+  "discoveries": [],
+  "implicit_knowledge": [],
+  "quality_signals": [],
+  "context_refs": [
+    ".planning/PROJECT.md",
+    ".planning/STATE.md"
+  ],
+  "recent_commits": [],
+  "recent_files": [],
+  "session_id": "example-session",
+  "_warning": "Never store secrets, tokens, or passwords in this file.",
+  "updated_at": "2026-03-22T00:00:00.000Z"
+}

package/examples/starter-project/.planning/PROJECT.md

@@ -0,0 +1,27 @@
+# Example Project
+
+## Status
+✅ Initialised
+
+## Problem statement
+A minimal example project to demonstrate MindForge configuration.
+
+## Target users
+Developers setting up MindForge for the first time.
+
+## Tech stack
+| Layer | Technology | Version | Rationale |
+|---|---|---|---|
+| Runtime | Node.js | 20 | LTS |
+
+## v1 Scope — IN
+- [x] Core setup and planning workflow
+
+## v1 Scope — OUT
+- Full product implementation
+
+## Success criteria
+MindForge installation verified and `/mindforge:status` works.
+
+## Key constraints
+- Keep example minimal

package/examples/starter-project/.planning/STATE.md

@@ -0,0 +1,10 @@
+# Project State
+
+## Status
+Ready for planning
+
+## Current phase
+None
+
+## Next action
+Run /mindforge:plan-phase 1

package/examples/starter-project/MINDFORGE.md

@@ -0,0 +1,40 @@
+NAME=ExampleProject
+VERSION=1.0.0
+DESCRIPTION=Starter example for MindForge v1.0.0
+MINDFORGE_VERSION_REQUIRED=1.0.0
+
+# Model preferences
+PLANNER_MODEL=claude-sonnet-4-5
+EXECUTOR_MODEL=claude-sonnet-4-5
+REVIEWER_MODEL=claude-sonnet-4-5
+VERIFIER_MODEL=claude-sonnet-4-5
+SECURITY_MODEL=claude-opus-4-5
+DEBUG_MODEL=claude-opus-4-5
+
+# Execution behavior
+TIER1_AUTO_APPROVE=true
+WAVE_CONFIRMATION_REQUIRED=false
+AUTO_DISCUSS_PHASE=false
+VERIFY_PASS_RATE_WARNING_THRESHOLD=0.85
+COMPACTION_THRESHOLD_PCT=70
+MAX_TASKS_PER_PHASE=15
+
+# Quality standards
+MIN_TEST_COVERAGE_PCT=80
+MAX_FUNCTION_LINES=40
+MAX_CYCLOMATIC_COMPLEXITY=10
+REQUIRE_ADR_FOR_ALL_DECISIONS=false
+BLOCK_ON_MEDIUM_SECURITY_FINDINGS=false
+
+# Skills behavior
+ALWAYS_LOAD_SKILLS=security-review
+DISABLED_SKILLS=
+MAX_FULL_SKILL_INJECTIONS=3
+
+# Token settings
+TOKEN_WARN_THRESHOLD=40000
+TOKEN_LEAN_MODE=false
+TOKEN_MAX_FILE_LINES=300
+
+# Update settings
+MINDFORGE_AUTO_CHECK_UPDATES=true

package/examples/starter-project/README.md

@@ -0,0 +1,14 @@
+# MindForge Starter Project (Example)
+
+This is a minimal example to show expected `.planning/` state and configuration.
+
+## Contents
+- `MINDFORGE.md`
+- `.planning/PROJECT.md`
+- `.planning/STATE.md`
+- `.planning/HANDOFF.json`
+- `.planning/AUDIT.jsonl`
+
+## How to use
+Copy this folder into a new repo and open Claude Code or Antigravity.
+Run `/mindforge:health` and `/mindforge:status` to verify.