mindforge-cc 1.0.0

package/docs/architecture/README.md

@@ -0,0 +1,35 @@
+# MindForge Architecture Overview
+
+## Architectural style
+MindForge is a modular, file-driven framework. Behavior is defined by
+Markdown protocols and JSON schemas, with a small Node.js CLI runtime.
+
+## Core layers
+1. **Command layer** — Markdown commands in `.claude/commands/mindforge/`
+2. **Engine layer** — Execution protocols under `.mindforge/engine/`
+3. **Governance layer** — Approvals, audit, compliance gates in `.mindforge/governance/`
+4. **Intelligence layer** — Health, difficulty, anti-patterns in `.mindforge/intelligence/`
+5. **Distribution layer** — Installer, registry, CI, SDK, plugins
+
+## Key data artifacts
+- `.planning/PROJECT.md` — project brief
+- `.planning/STATE.md` — current execution state
+- `.planning/HANDOFF.json` — machine-readable session handoff
+- `.planning/AUDIT.jsonl` — append-only audit log
+
+## Runtime flow (high level)
+1. `/mindforge:plan-phase` generates atomic plans with dependencies
+2. `/mindforge:execute-phase` runs plans in waves
+3. `/mindforge:verify-phase` runs automated + human gates
+4. `/mindforge:ship` generates release artifacts and PR metadata
+
+## Installation targets
+- Claude Code: `~/.claude/` or `.claude/`
+- Antigravity: `~/.gemini/antigravity/` or `.agent/`
+
+## SDK integration
+`@mindforge/sdk` provides programmatic access to health checks, audit log
+streaming, and command builders.
+
+## Stability contract
+See ADR-020: command interfaces, schemas, and SDK exports are stable in v1.x.x.

package/docs/architecture/decision-records-index.md

@@ -0,0 +1,26 @@
+# MindForge — Architecture Decision Records Index
+
+All 20 ADRs in chronological order.
+
+| ADR | Title | Status | Day | Key decision |
+|---|---|---|---|---|
+| ADR-001 | HANDOFF.json for cross-session state | Accepted | Day 2 | HANDOFF.json as the primary cross-session state artifact |
+| ADR-002 | Markdown-based commands | Accepted | Day 1 | Slash commands as Markdown files (not code) |
+| ADR-003 | Keyword-trigger model for skill loading | Accepted | Day 1 | Deterministic keyword matching over AI-decided selection |
+| ADR-004 | Wave parallelism over full parallelism | Accepted | Day 2 | Wave-based (dependency-ordered) over unconstrained parallel |
+| ADR-005 | Append-only JSONL for audit log | Accepted | Day 2 | AUDIT.jsonl append-only (never update, never delete) |
+| ADR-006 | Three-tier skills architecture | Accepted | Day 3 | Core → Org → Project tier hierarchy |
+| ADR-007 | Keyword-trigger model (reaffirmed at Day 3 scale) | Accepted | Day 3 | Confirmed at 10+ skill scale |
+| ADR-008 | Just-in-time skill loading | Accepted | Day 3 | Load at task time, not session start |
+| ADR-009 | Environment-variable-only credential storage | Accepted | Day 4 | Credentials only in env vars, never in config files |
+| ADR-010 | Compliance gates non-bypassable; approvals allow emergency | Accepted | Day 4 | Gates: never bypass. Approvals: emergency override with audit |
+| ADR-011 | Integration failures are non-blocking | Accepted | Day 4 | Jira/Slack/GitHub down ≠ phase blocked |
+| ADR-012 | Intelligence outputs feed back into system behaviour | Accepted | Day 5 | Difficulty → granularity, retro → MINDFORGE.md, quality → behaviour |
+| ADR-013 | MINDFORGE.md as constitution with non-overridable primitives | Accepted | Day 5 | Non-overridable governance primitives cannot be disabled |
+| ADR-014 | Metrics are system signals, not developer performance | Accepted | Day 5 | Quality scores improve the system, not evaluate individuals |
+| ADR-015 | npm as the public skills registry | Accepted | Day 6 | npm ecosystem for skill distribution |
+| ADR-016 | CI timeout exits with code 0 (soft stop) | Accepted | Day 6 | Timeout = save and resume, not failure |
+| ADR-017 | SDK event stream is localhost-only | Accepted | Day 6 | SSE binds to 127.0.0.1 only |
+| ADR-018 | Installer detects and handles self-install | Accepted | Day 7 | Installer running inside its own repo = no-op for framework files |
+| ADR-019 | Self-update preserves original install scope | Accepted | Day 7 | Update local→local, global→global |
+| ADR-020 | v1.0.0 stable interface contract | Accepted | Day 7 | Defines what "stable" means for plugins and SDK consumers |

package/docs/ci-cd-integration.md

@@ -0,0 +1,30 @@
+# MindForge CI/CD Integration
+
+## Overview
+MindForge supports non-interactive CI mode for GitHub Actions, GitLab CI, and Jenkins.
+CI mode activates when `CI=true` or `MINDFORGE_CI=true`.
+
+## GitHub Actions
+Use `.github/workflows/mindforge-ci.yml` for:
+- Health checks
+- Security scanning
+- Quality gates
+- AI PR review (if `ANTHROPIC_API_KEY` is set)
+
+## GitLab CI
+Use `.gitlab-ci-mindforge.yml` as a template. Ensure CI variables include:
+- `ANTHROPIC_API_KEY`
+- `GITHUB_TOKEN` (optional)
+- `SLACK_BOT_TOKEN` (optional)
+
+## Jenkins
+Use `.mindforge/ci/jenkins-adapter.md` for a Jenkinsfile template.
+
+## Governance in CI
+- Tier 1 auto-approves.
+- Tier 2 auto-approves only if `CI_AUTO_APPROVE_TIER2=true`.
+- Tier 3 always blocks CI and requires human approval.
+
+## Timeouts
+Timeouts are soft stops (exit code 0). MindForge saves state to `HANDOFF.json` and
+prints a summary in the CI step output.

package/docs/ci-quickstart.md

@@ -0,0 +1,78 @@
+# MindForge CI Quickstart (v1.0.0)
+
+This page shows how to run MindForge in real pipelines with non-interactive
+behavior and reliable outputs.
+
+## 1. Basic CI run (GitHub Actions)
+
+```yaml
+name: MindForge CI
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  mindforge:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install MindForge
+        run: npx mindforge-cc@latest --claude --local
+
+      - name: Run MindForge suite
+        run: node tests/install.test.js
+```
+
+## 2. CI mode behavior
+Set `CI=true` to enable non-interactive operation.
+
+MindForge in CI:
+- Skips interactive prompts
+- Emits structured output (if configured)
+- Blocks Tier 3 changes
+- Logs all gate results
+
+## 3. Recommended env settings
+```bash
+CI=true
+MINDFORGE_CI=true
+```
+
+## 4. Add full test battery (v1.0.0)
+```bash
+SUITES=(install wave-engine audit compaction skills-platform \
+        integrations governance intelligence metrics \
+        distribution ci-mode sdk production migration e2e)
+
+for SUITE in "${SUITES[@]}"; do
+  node tests/${SUITE}.test.js
+done
+```
+
+## 5. Reporting
+If you want JSON output in CI, set in `MINDFORGE.md`:
+```
+CI_OUTPUT_FORMAT=json
+```
+
+## 6. Common CI pitfalls
+- Missing Node 18+ → install newer Node
+- CI failing on Tier 3 changes → approvals required
+- Missing `.planning/` in CI → run `/mindforge:init-project` or `map-codebase`
+
+## 7. GitLab CI example
+```yaml
+stages: [test]
+
+mindforge:
+  stage: test
+  image: node:20
+  script:
+    - npx mindforge-cc@latest --claude --local
+    - node tests/install.test.js
+```

package/docs/commands-reference.md

@@ -0,0 +1,11 @@
+# MindForge — Commands Reference
+
+| Command                         | Description                                   |
+|---------------------------------|-----------------------------------------------|
+| `/mindforge:help`               | Show all commands and current project status  |
+| `/mindforge:init-project`       | Initialise a new project (requirements, scope, state) |
+| `/mindforge:plan-phase [N]`     | Plan a phase: discuss → research → create task plans |
+| `/mindforge:execute-phase [N]`  | Execute plans with wave-based parallelism     |
+| `/mindforge:verify-phase [N]`   | Human acceptance testing + automated checks  |
+| `/mindforge:ship [N]`           | Generate changelog, run quality gates, create PR |
+

package/docs/contributing/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing to MindForge
+
+Thanks for contributing. MindForge prioritizes reliability, security, and
+repeatability. Please follow the guidelines below.
+
+## Workflow
+1. Fork the repo and create a branch from `main`
+2. Use branch prefix `feat/`, `fix/`, `chore/`, `docs/`, `test/`
+3. Make small, focused commits with clear messages
+4. Run tests before opening a PR
+
+## Local setup
+```bash
+npm install
+npm test
+```
+
+## Commit guidance
+- One logical change per commit
+- Avoid formatting-only changes mixed with functional changes
+- No TODO comments in committed code
+
+## Tests
+Run the relevant suite for your change:
+```bash
+node tests/install.test.js
+# plus any affected suites
+```
+
+## PR checklist
+- [ ] Tests pass locally
+- [ ] Docs updated (if behavior changed)
+- [ ] New commands added to command reference
+- [ ] Security-sensitive changes reviewed
+
+## Security
+If you find a vulnerability, do not open a public issue. Report via
+`docs/security/SECURITY.md`.

package/docs/contributing/plugin-authoring.md

@@ -0,0 +1,50 @@
+# Plugin Authoring Guide (v1.0.0)
+
+## Overview
+Plugins extend MindForge with commands and skills. They are installed from npm
+under the `mindforge-plugin-*` namespace.
+
+## Structure
+```
+my-plugin/
+  plugin.json
+  commands/
+    my-command.md
+  skills/
+    my-skill/
+      SKILL.md
+```
+
+## plugin.json (required)
+```json
+{
+  "name": "mindforge-plugin-example",
+  "version": "1.0.0",
+  "mindforge_plugin_api_version": "1.0.0",
+  "min_mindforge_version": "1.0.0",
+  "commands": ["commands/my-command.md"],
+  "skills": ["skills/my-skill/SKILL.md"],
+  "permissions": {
+    "read_state": true,
+    "write_state": false,
+    "network": false
+  }
+}
+```
+
+## Command authoring
+Command files are standard MindForge command markdown. The first non-empty line
+is used as the command description.
+
+## Compatibility
+- `mindforge_plugin_api_version` must be `1.0.0` for MindForge v1.x.x
+- Command name conflicts are auto-renamed per `plugin-loader.md`
+
+## Security guidelines
+- Keep permissions minimal
+- Never exfiltrate project data without explicit user approval
+- Pass injection guard (no override or jailbreak phrases)
+
+## Test locally
+Use `/mindforge:plugins validate` and `/mindforge:plugins install --local` to
+validate and install into a test project.

package/docs/contributing/skill-authoring.md

@@ -0,0 +1,41 @@
+# Skill Authoring Guide (v1.0.0)
+
+## Purpose
+Skills capture repeatable domain expertise. They are loaded by keyword triggers.
+
+## Create a skill
+1. Create a directory under `.mindforge/skills/<skill-name>/`
+2. Add `SKILL.md` with frontmatter
+3. Add optional `assets/` or `references/`
+
+## SKILL.md template
+```markdown
+---
+name: my-skill
+version: 1.0.0
+description: One-line description of the skill
+triggers: ["keyword1", "keyword2"]
+owner: my-team
+scope: project
+---
+
+# Skill content
+- Guidance
+- Checklists
+- Examples
+```
+
+## Validation
+Run:
+```
+/mindforge:skills validate
+```
+
+## Publishing (optional)
+Publish to npm under `mindforge-skill-*`.
+See `docs/skills-publishing-guide.md` for full steps.
+
+## Security rules
+- No instructions that override system policies
+- No credentials or secrets in content
+- Avoid excessive prompts that expand tokens without value

package/docs/enterprise-setup.md

@@ -0,0 +1,25 @@
+# MindForge Enterprise Setup
+
+## Goal
+Configure Jira, Confluence, Slack, and SCM governance safely without storing
+ credentials in the repository.
+
+## Setup sequence
+1. Fill non-sensitive values in
+   `.mindforge/org/integrations/INTEGRATIONS-CONFIG.md`
+2. Export credentials as environment variables
+3. Validate connectivity through `connection-manager.md`
+4. Run `/mindforge:sync-jira` and `/mindforge:sync-confluence`
+5. Confirm Slack notification behaviour and undelivered-alert fallback
+
+## Security rules
+- never commit tokens
+- never run credential-bearing calls with `set -x`
+- never use `curl -v` with Authorization headers
+- rotate credentials by updating the environment, not config files
+
+## Supported Day 4 outputs
+- Jira epics and stories for phases/plans
+- Confluence architecture and ADR publishing
+- Slack notifications and thread tracking
+- milestone health and completion workflow

package/docs/faq.md

@@ -0,0 +1,38 @@
+# MindForge FAQ (v1.0.0)
+
+## Is MindForge tied to Claude only?
+No. MindForge supports Claude Code and Antigravity. Install with `--claude`,
+`--antigravity`, or `--all`.
+
+## Global vs local install?
+- **Global:** installs to your home directory and applies to all projects.
+- **Local:** installs to the current repo only. Local takes precedence.
+
+## Does MindForge store secrets?
+No. Credentials must stay in environment variables. MindForge never writes
+secrets to files.
+
+## Why did CI fail on Tier 3 changes?
+Tier 3 (compliance) changes are blocked in CI by design. Use approvals.
+
+## How do I uninstall?
+```
+npx mindforge-cc@latest --uninstall --claude --local
+```
+Uninstall does not delete `.planning/` or `.mindforge/`.
+
+## How do I know which commands are available?
+Run:
+```
+/mindforge:help
+```
+
+## Can I add custom commands?
+Yes, via plugins or by adding command markdown files in your project.
+Plugins are preferred for sharing and versioning.
+
+## How do I update to the latest version?
+```
+/mindforge:update
+/mindforge:update --apply
+```

package/docs/getting-started.md

@@ -0,0 +1,36 @@
+# MindForge — Getting Started
+
+This guide gets you from zero to a working MindForge project in under five minutes.
+
+## Install
+
+```bash
+# Claude Code (global)
+npx mindforge-cc --claude --global
+
+# Project-local install
+npx mindforge-cc --claude --local
+```
+
+## Initialise your project
+
+Open Claude Code in your repository and run:
+
+```
+/mindforge:help
+/mindforge:init-project
+```
+
+The init command creates your core planning files:
+- `.planning/PROJECT.md`
+- `.planning/REQUIREMENTS.md`
+- `.planning/STATE.md`
+- `.planning/HANDOFF.json`
+
+## Next steps
+
+1. Plan Phase 1: `/mindforge:plan-phase 1`
+2. Execute Phase 1: `/mindforge:execute-phase 1`
+3. Verify Phase 1: `/mindforge:verify-phase 1`
+4. Ship Phase 1: `/mindforge:ship 1`
+

package/docs/governance-guide.md

@@ -0,0 +1,23 @@
+# MindForge Governance Guide
+
+## Goal
+Explain how change classification, approvals, compliance gates, and milestone
+ governance work in Day 4.
+
+## Governance flow
+1. Classify the change before plan execution
+2. Apply Tier 3 signals first
+3. Request approval when required
+4. Enforce compliance gates before completion or release
+5. Log decisions and approvals to AUDIT
+
+## Key guarantees
+- Tier 3 can be triggered by code content, not just file paths
+- GDPR/PII gate runs independently of skill loading
+- emergency override requires explicit `--emergency` and listed approver identity
+- approval expiry is session-detected and config-driven
+
+## Team operation
+- multi-developer sessions coordinate via shared `HANDOFF.json`
+- stale active developers expire after 4 hours
+- shared state merges happen through git conflict resolution, not silent overwrite

package/docs/mindforge-md-reference.md

@@ -0,0 +1,53 @@
+# 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`
+
+### 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/monorepo-guide.md

@@ -0,0 +1,26 @@
+# MindForge Monorepo Guide
+
+## Overview
+MindForge detects common monorepo setups (npm workspaces, pnpm, Nx, Turborepo, Lerna)
+and builds a workspace manifest for multi-package planning.
+
+## Detect workspace
+Run:
+```
+/mindforge:workspace detect
+```
+This writes `.planning/WORKSPACE-MANIFEST.json` and prints package order.
+
+## Plan across packages
+Use:
+```
+/mindforge:workspace plan phase N
+```
+Each PLAN file includes `<package>` and `<working-dir>` fields.
+
+## Test across packages
+Use:
+```
+/mindforge:workspace test
+```
+Tests run in dependency order, then root integration tests if configured.

package/docs/persona-customisation.md

@@ -0,0 +1,56 @@
+# MindForge Persona Customisation
+
+## Overview
+MindForge personas are shared and versioned. To tailor them for a specific
+project or phase, use the override system rather than editing the core persona
+files. Overrides are additive and safe to maintain across upgrades.
+
+## Where overrides live
+- Project overrides: `.mindforge/personas/overrides/[persona].md`
+- Phase overrides: `.planning/phases/[N]/persona-overrides/[persona].md`
+
+Priority order:
+1. Phase override
+2. Project override
+3. Core persona
+
+## Override format
+Overrides extend, modify, or remove sections from the base persona.
+Use the following directives:
+
+- `## Additional [section]` — append content to the base persona section
+- `## Modified [section]` — replace the base persona section
+- `## Removed [section]` — remove the base persona section
+- `KEY: VALUE` — override specific parameters (e.g., `MAX_FUNCTION_LINES: 60`)
+
+## Example override
+
+```markdown
+# Developer Persona Override — Payments Service
+# Scope: project
+# Author: Jane Doe
+# Created: 2026-03-20
+
+## Additional coding standards
+- All payment flows must be idempotent.
+- All monetary values use integer cents.
+
+## Modified conventions
+# Override: "Functions ≤ 40 lines" → allow 60 lines for orchestrators.
+MAX_FUNCTION_LINES: 60
+
+## Project-specific forbidden patterns
+- Never call Stripe directly from controllers — use PaymentService only.
+```
+
+## Best practices
+- Keep overrides minimal and specific.
+- Prefer new personas only when the cognitive mode is fundamentally different.
+- Document why an override exists so future maintainers understand its intent.
+- Review overrides at the end of each phase; prune what is no longer relevant.
+
+## Validation checklist
+- [ ] Override file is scoped correctly (project vs. phase)
+- [ ] Sections are clearly labeled (Additional / Modified / Removed)
+- [ ] Conflicts are resolved (phase overrides win)
+- [ ] Overrides do not contradict SECURITY.md

package/docs/quick-verify.md

@@ -0,0 +1,33 @@
+# MindForge Quick Verify (v1.0.0)
+
+Use this after installation to confirm everything works.
+
+## 1. Health check
+```
+/mindforge:health
+```
+
+## 2. Create minimal project state
+```
+/mindforge:init-project
+```
+
+## 3. Verify core files exist
+Expected:
+- `.planning/PROJECT.md`
+- `.planning/STATE.md`
+- `.planning/HANDOFF.json`
+- `.planning/AUDIT.jsonl`
+
+## 4. Optional repair
+If anything looks off:
+```
+/mindforge:health --repair
+```
+
+## 5. Clean success signal
+Run:
+```
+/mindforge:status
+```
+You should see a valid phase status and next action.

package/docs/reference/audit-events.md

@@ -0,0 +1,53 @@
+# MindForge Audit Events — Reference (v1.0.0)
+
+## Overview
+`AUDIT.jsonl` is the append-only record of MindForge operations.
+Each line is a JSON object with a required `event` type and a `session_id`.
+
+## Location
+`.planning/AUDIT.jsonl`
+
+## Required fields (all events)
+- `id` (UUID v4)
+- `timestamp` (ISO-8601)
+- `event` (string)
+- `agent` (string)
+- `phase` (number or null)
+- `session_id` (string)
+
+## Common event types
+### `project_initialised`
+Fields: `project_name`, `tech_stack`, `compliance`
+
+### `phase_planned`
+Fields: `plan_count`, `wave_count`, `research_conducted`
+
+### `phase_execution_started`
+Fields: `plan_count`, `wave_count`, `dependency_graph_path`
+
+### `phase_execution_completed`
+Fields: `tasks_completed`, `tasks_failed`, `verify_status`, `verification_path`
+
+### `task_started`
+Fields: `plan`, `task_name`
+
+### `task_completed`
+Fields: `plan`, `commit_sha`, `verify_result`
+
+### `security_scan_completed`
+Fields: `critical`, `high`, `medium`, `low`, `findings_path`
+
+### `gate_result`
+Fields: `gate`, `status`, `detail`
+
+### `plugin_installed`
+Fields: `plugin_name`, `version`, `permissions`
+
+### `plugin_uninstalled`
+Fields: `plugin_name`
+
+## Rotation
+Rotate when file exceeds 10,000 lines. Archive into `.planning/audit-archive/`.
+
+## Schema source
+See `.mindforge/audit/AUDIT-SCHEMA.md` for full examples and field definitions.