mindforge-cc 2.1.4 → 2.3.0

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

@@ -0,0 +1,193 @@
+---
+description: 1. Read STATE.md — confirm phase [N] is in "planned" status.
+---
+# MindForge — Execute Phase Command
+# Usage: /mindforge:execute-phase [N]
+
+## Pre-checks (all must pass before execution starts)
+
+1. Read STATE.md — confirm phase [N] is in "planned" status.
+   If STATE.md shows phase [N] as already "complete": ask user to confirm re-execution.
+
+2. Verify plan files exist:
+   ```
+   .planning/phases/[N]/PLAN-[N]-01.md   (minimum one plan required)
+   ```
+   If missing: stop. Tell user: "No plans found for Phase [N]. Run /mindforge:plan-phase [N] first."
+
+3. Verify REQUIREMENTS.md exists and has content.
+   If empty: warn user but allow continuation.
+
+4. Run the dependency parser (`.mindforge/engine/dependency-parser.md`).
+   If validation fails (circular deps, missing deps): stop and report. Do not execute.
+
+## Step 1 — Build and display the execution plan
+
+After dependency parsing succeeds, display the wave plan to the user:
+
+```
+Phase [N] Execution Plan
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Wave 1 (parallel)     Wave 2 (parallel)     Wave 3
+  ┌─────────────┐       ┌─────────────┐       ┌─────────────┐
+  │ Plan 01     │       │ Plan 03     │       │ Plan 05     │
+  │ User model  │──┐    │ User API    │──┐    │ Checkout UI │
+  └─────────────┘  │    └─────────────┘  │    └─────────────┘
+  ┌─────────────┐  │    ┌─────────────┐  │
+  │ Plan 02     │──┘    │ Plan 04     │──┘
+  │ Product     │       │ Product API │
+  └─────────────┘       └─────────────┘
+
+  Total tasks: 5    Waves: 3    Est. time: depends on model speed
+
+Proceed? (yes/no)
+```
+
+If the user says no: stop. Do not execute anything.
+
+## Step 2 — Write pre-execution audit entry
+
+Append to `.planning/AUDIT.jsonl`:
+```json
+{
+  "id": "[uuid-v4]",
+  "timestamp": "[ISO-8601]",
+  "event": "phase_execution_started",
+  "phase": [N],
+  "wave_count": [total waves],
+  "task_count": [total tasks],
+  "agent": "mindforge-orchestrator",
+  "session_id": "[session identifier]"
+}
+```
+
+## Step 3 — Execute waves using the wave executor
+
+Follow the complete protocol in `.mindforge/engine/wave-executor.md`.
+
+For each wave:
+
+### Wave start
+Write to console:
+```
+━━━ Wave [W] of [total] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Starting [X] tasks in parallel...
+```
+
+### Per-task execution (inject context per `context-injector.md`)
+For each plan in the wave:
+1. Load context package (per `context-injector.md`)
+2. Execute the plan instructions
+   - Run `<verify>` — capture exact output
+   - If verify PASSES:
+     - Run `<verify-visual>` via `visual-verify-executor.js`
+     - If visual verify FAILS: stop and report (treat as verify failure)
+     - Write SUMMARY-[N]-[M].md
+   - Execute commit: `git add [files] && git commit -m "[type]([scope]): [task name]"`
+   - Capture git SHA
+   - Write AUDIT entry for task completion
+5. If verify FAILS:
+   - Write SUMMARY-[N]-[M].md with failure details
+   - Write AUDIT entry for task failure
+   - STOP this wave immediately
+   - Report: "Task [plan ID] failed: [verify output]. Stopping Phase [N]."
+   - Do not start next wave
+   - Ask user: "Spawn debug agent to diagnose? (yes/no)"
+
+### Wave completion (before starting next wave)
+After all tasks in wave complete:
+1. Run: `[project test command]`
+2. If tests fail:
+   - Identify failing tests
+   - Run `git log --oneline -[wave-task-count]` to see wave commits
+   - Report which commit likely introduced the failure
+   - Stop. Ask user how to proceed.
+3. If tests pass:
+   - Report: "Wave [W] complete. All [X] tasks passed. Tests passing. ✅"
+   - Write WAVE-REPORT update
+
+## Step 4 — Phase-level verification
+
+After all waves complete, run the verification pipeline:
+
+1. Read every v1 requirement from REQUIREMENTS.md for this phase
+2. For each requirement, verify it is implemented:
+   - Search the codebase for the implementation
+   - Check if a test covers it
+   - Mark: ✅ implemented + tested | ⚠️ implemented, no test | ❌ not found
+3. Write `.planning/phases/[N]/VERIFICATION.md`
+4. Run the full test suite one final time
+5. If any requirement is ❌: create a fix plan and report to user
+
+## Step 5 — Update state and write wave report
+
+Write `.planning/phases/[N]/WAVE-REPORT-[N].md` (per template in wave-executor.md)
+
+Update STATE.md:
+```markdown
+## Current phase
+[N] — Execution complete ✅
+
+## Last completed task
+Phase [N]: All [X] tasks completed across [W] waves.
+
+## Next action
+Run /mindforge:verify-phase [N] for human acceptance testing.
+```
+
+Update HANDOFF.json with completed phase info.
+
+Write final AUDIT entry:
+```json
+{
+  "id": "[uuid-v4]",
+  "timestamp": "[ISO-8601]",
+  "event": "phase_execution_completed",
+  "phase": [N],
+  "tasks_completed": [X],
+  "waves_executed": [W],
+  "commits": ["sha1", "sha2", "..."],
+  "test_result": "passing",
+  "agent": "mindforge-orchestrator"
+}
+```
+
+## Step 6 — Report to user
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ Phase [N] execution complete
+
+  Tasks completed : [X] / [X]
+  Waves executed  : [W]
+  Commits made    : [X]
+  Tests           : All passing
+  Requirements    : [X] / [X] implemented
+
+Next step: Run /mindforge:verify-phase [N] for UAT sign-off.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Step 7 — Auto-capture check (when AUTO_CAPTURE_SKILLS=true)
+
+After all gates pass and the phase is verified:
+
+```bash
+# Check if auto-capture is enabled
+CAPTURE=$(grep -m1 "^AUTO_CAPTURE_SKILLS=" MINDFORGE.md 2>/dev/null | cut -d= -f2 | tr -d ' ')
+if [ "$CAPTURE" = "true" ]; then
+  node -e "
+    const { detectPatterns, formatForPresentation } = require('./bin/skills-builder/pattern-detector');
+    detectPatterns(${PHASE_NUM}).then(result => {
+      const display = formatForPresentation(result);
+      console.log(display);
+    }).catch(err => console.error('[auto-capture] Error:', err.message));
+  "
+fi
+```
+
+If patterns are found: display the prompt and await user input.
+If user selects yes: run `/mindforge:learn --session` targeting this phase's SUMMARY files.
+If user selects no: write AUDIT entry `auto_capture_skipped` and continue.
+If no patterns found: exit silently (no noise in the output).
+```

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

@@ -0,0 +1,24 @@
+---
+description: Run all seven health-engine categories from .mindforge/intelligence/health-engine.md.
+---
+# MindForge — Health Command
+# Usage: /mindforge:health [--repair] [--category C] [--verbose]
+
+Run all seven health-engine categories from `.mindforge/intelligence/health-engine.md`.
+
+## Output
+- category status summary
+- errors (must fix)
+- warnings (should fix)
+- informational signals
+
+## Flags
+- `--repair`: apply safe auto-repair only
+- `--category`: one of `installation|context|skills|personas|state|integrations|security`
+- `--verbose`: include passing checks and exact inspected values
+
+## AUDIT
+Append:
+```json
+{ "event": "health_check_completed", "errors": 0, "warnings": 0, "repaired": 0 }
+```

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

@@ -0,0 +1,26 @@
+---
+description: Show all available MindForge commands.
+---
+Show all available MindForge commands.
+
+## Pre-check
+If `.planning/STATE.md` exists, read it.
+If `.planning/PROJECT.md` is missing, treat the project as "Not initialised".
+
+1. Scan every .md file in `.claude/commands/mindforge/`
+2. For each file, extract the first non-empty line as the command description
+3. Display as a clean table:
+
+| Command                      | Description                                  |
+|------------------------------|----------------------------------------------|
+| /mindforge:help              | Show all available commands                  |
+| /mindforge:init-project      | ...                                          |
+| ...                          | ...                                          |
+
+4. After the table, print:
+   "Current project: [read PROJECT.md first line, or 'Not initialised']"
+   "Current phase:   [read STATE.md current phase, or 'None']"
+   "Next step:       [read STATE.md next action]"
+
+5. If CLAUDE.md has not been read this session, remind the user to ensure
+   it is loaded as MindForge's system context.

package/.agent/workflows/mindforge:init-org.md

@@ -0,0 +1,134 @@
+---
+description: Set up MindForge at the organisation level — create standardised org-level
+---
+# MindForge — Init Org Command
+# Usage: /mindforge:init-org [--org-name "Name"] [--update]
+
+## Purpose
+Set up MindForge at the organisation level — create standardised org-level
+context files that are shared across ALL projects in the organisation.
+
+Intended to be run ONCE by a platform engineer or engineering lead.
+Output is committed to a shared `mindforge-org-config` repository
+and distributed to projects as a git submodule or npm package.
+
+## Step 1 — Gather org information
+
+Ask (one question at a time):
+1. "What is your organisation name?"
+2. "Describe what your organisation builds in 1-2 sentences."
+3. "What is your primary tech stack? (describe in plain English)"
+4. "What is your default deployment target? (AWS / GCP / Azure / self-hosted / hybrid)"
+5. "What regulatory frameworks apply to your organisation?"
+   Options: GDPR / HIPAA / SOC 2 / PCI-DSS / ISO 27001 / None / Multiple
+6. "What is your source control platform?" (GitHub / GitLab / Bitbucket / Azure DevOps)
+7. "What is your issue tracker?" (Jira / GitHub Issues / Linear / Azure DevOps / None)
+8. "Who are your Tier 3 compliance approvers? (email addresses, comma-separated)"
+
+## Step 2 — Generate org-level context files
+
+Create (or update with `--update`) these files:
+
+### `.mindforge/org/ORG.md`
+Populated from answers with:
+- Organisation identity and mission
+- Default tech stack with version recommendations
+- Architecture defaults
+- Team conventions
+- Compliance requirements
+
+### `.mindforge/org/CONVENTIONS.md`
+Generate sensible defaults based on the tech stack detected.
+For TypeScript/Node.js stacks: strict TypeScript, ESLint, Conventional Commits
+For Python stacks: ruff, mypy, black formatting
+For Go: standard Go toolchain conventions
+Mark each section clearly: [DEFAULT] or [CUSTOMISE THIS]
+
+### `.mindforge/org/SECURITY.md`
+Generate based on declared compliance frameworks:
+- GDPR → include GDPR-specific policies
+- HIPAA → include PHI handling requirements
+- PCI-DSS → include card data handling policies
+- SOC 2 → include access control requirements
+Mark critical sections: [REVIEW WITH SECURITY TEAM]
+
+### `.mindforge/org/TOOLS.md`
+Generate approved library list based on tech stack.
+Include common forbidden libraries (moment.js, request, etc.)
+Mark: [ADD YOUR APPROVED LIBRARIES]
+
+### `.mindforge/org/integrations/INTEGRATIONS-CONFIG.md`
+Pre-populate based on declared platforms:
+- GitHub → fill GitHub config section
+- Jira → fill Jira config section
+Mark credential fields clearly: [SET VIA ENVIRONMENT VARIABLE]
+
+### `.mindforge/governance/GOVERNANCE-CONFIG.md`
+Pre-populate based on declared approvers and compliance frameworks.
+Higher compliance burden → lower Tier 2/3 thresholds.
+Stricter approval SLAs for HIPAA/PCI-DSS organisations.
+
+## Step 3 — Generate skills recommendation
+
+Based on the tech stack and compliance requirements, recommend skills to install:
+
+```
+Recommended skills for your tech stack:
+
+Core skills (already included — v0.6.0):
+  ✅ security-review, code-quality, api-design, testing-standards, documentation,
+     performance, accessibility, data-privacy, incident-response, database-patterns
+
+Additional skills recommended for your stack:
+  [tech-stack-specific recommendations from registry]
+
+For your compliance requirements:
+  [compliance-specific skill recommendations]
+
+Install all recommendations?
+  yes → npx mindforge-skills install [list]
+  no  → I'll show you the install commands for each
+```
+
+## Step 4 — Create distribution package
+
+Offer to create an org-skills npm package for distributing org-level config:
+
+```
+Create `@your-org/mindforge-config` npm package?
+This package will distribute your org-level MindForge configuration
+to all projects in your organisation via: npx @your-org/mindforge-config
+
+Files included:
+  .mindforge/org/ORG.md
+  .mindforge/org/CONVENTIONS.md
+  .mindforge/org/SECURITY.md
+  .mindforge/org/TOOLS.md
+  .mindforge/org/skills/MANIFEST.md
+  .mindforge/org/integrations/INTEGRATIONS-CONFIG.md (without credentials)
+  .mindforge/governance/GOVERNANCE-CONFIG.md (without credentials)
+```
+
+## Step 5 — Write AUDIT entry and report
+
+```json
+{ "event": "org_initialised", "org_name": "[name]", "compliance_frameworks": [...], "skills_recommended": [...] }
+```
+
+Report:
+```
+✅ MindForge organisation configuration complete.
+
+Files created:
+  .mindforge/org/ORG.md
+  .mindforge/org/CONVENTIONS.md
+  .mindforge/org/SECURITY.md
+  .mindforge/org/TOOLS.md
+  .mindforge/governance/GOVERNANCE-CONFIG.md
+
+Next steps:
+  1. Review each file — look for [CUSTOMISE THIS] markers
+  2. Fill in SECURITY.md with your security team
+  3. Commit to your org's mindforge-config repository
+  4. Share with all projects: npx @your-org/mindforge-config (if you created the package)
+```

package/.agent/workflows/mindforge:init-project.md

@@ -0,0 +1,169 @@
+---
+description: Initialise a new project under the MindForge framework.
+---
+Initialise a new project under the MindForge framework.
+
+## Pre-check
+Read `.planning/PROJECT.md`. If it already exists and contains content,
+ask: "A project is already initialised. Do you want to reinitialise? (yes/no)"
+Stop if the user says no.
+
+## Pre-flight Environment Check
+Verify that `CLAUDE.md` exists at the root of the project and `.claude/commands/mindforge/` is populated. If not, silently run the following to enable zero-config IDE autocomplete (Cursor, Windsurf, Claude Code):
+```bash
+mkdir -p .claude/commands/mindforge
+cp -r .agent/mindforge/* .claude/commands/mindforge/ 2>/dev/null || true
+cp -r .agents/workflows/* .claude/commands/mindforge/ 2>/dev/null || true
+cp .agent/CLAUDE.md ./CLAUDE.md 2>/dev/null || true
+cp .agent/CLAUDE.md ./.cursorrules 2>/dev/null || true
+cp .agent/CLAUDE.md ./.windsurfrules 2>/dev/null || true
+```
+
+## Step 1 — Requirements interview
+Ask these questions one at a time. Wait for the full answer before asking the next.
+Do not batch them. Do not rush.
+
+1. "What is this project? Give me a 1-2 sentence description."
+2. "Who is the primary user? Describe them specifically."
+3. "What problem does this solve for them? What is the pain today?"
+4. "What tech stack do you want to use? (Say 'recommend one' if unsure.)"
+   — If they say recommend: ask 3 clarifying questions about team size,
+     deployment environment, and performance requirements. Then recommend
+     a specific stack with brief rationale for each choice.
+5. "What is explicitly NOT in scope for v1? Name at least 3 things."
+6. "What does a successful v1 look like? How will you know it worked?"
+7. "Are there any compliance requirements? (GDPR, HIPAA, SOC2, PCI-DSS, none)"
+
+## Step 2 — Create context files
+
+Write `.planning/PROJECT.md`:
+```markdown
+# [Project Name]
+[One-line description]
+
+## Problem statement
+[From answer 3]
+
+## Target user
+[From answer 2]
+
+## Tech stack
+| Layer      | Choice          | Rationale                      |
+|------------|-----------------|--------------------------------|
+| [layer]    | [technology]    | [why]                          |
+
+## v1 scope — IN
+[Bullet list of what is included]
+
+## v1 scope — OUT (explicitly excluded)
+[Bullet list from answer 5]
+
+## Success criteria
+[From answer 6]
+
+## Compliance
+[From answer 7]
+
+## Initialised
+[ISO 8601 timestamp]
+```
+
+Write `.planning/REQUIREMENTS.md`:
+```markdown
+# Requirements — [Project Name]
+
+## Functional requirements
+| ID    | Requirement              | Acceptance criterion           | Scope |
+|-------|--------------------------|--------------------------------|-------|
+| FR-01 |                          |                                | v1    |
+
+## Non-functional requirements
+| ID     | Category      | Requirement                    | Measure        |
+|--------|---------------|--------------------------------|----------------|
+| NFR-01 | Performance   |                                |                |
+| NFR-02 | Security      |                                |                |
+| NFR-03 | Availability  |                                |                |
+
+## Out of scope
+[Items explicitly excluded from v1]
+```
+
+Write `.planning/STATE.md`:
+```markdown
+# MindForge — Project State
+
+## Status
+Project initialised. No phases started.
+
+## Current phase
+None
+
+## Last completed task
+Project initialisation
+
+## Next action
+Run /mindforge:plan-phase 1 to begin planning Phase 1.
+
+## Decisions made
+- Project scope defined (see PROJECT.md)
+- Tech stack chosen (see PROJECT.md)
+
+## Active blockers
+None
+
+## Last updated
+[ISO 8601 timestamp]
+```
+
+Write `.planning/HANDOFF.json`:
+```json
+{
+  "schema_version": "1.0.0",
+  "project": "[project name]",
+  "phase": null,
+  "plan": null,
+  "plan_step": null,
+  "last_completed_task": {
+    "description": "Project initialisation",
+    "commit_sha": null,
+    "verified": true
+  },
+  "next_task": "Run /mindforge:plan-phase 1",
+  "in_progress": {
+    "file": null,
+    "intent": null,
+    "completed_steps": [],
+    "remaining_steps": []
+  },
+  "blockers": [],
+  "decisions_needed": [],
+  "context_refs": [
+    ".planning/PROJECT.md",
+    ".planning/STATE.md",
+    ".planning/REQUIREMENTS.md"
+  ],
+  "agent_notes": "Fresh project. Read PROJECT.md and REQUIREMENTS.md before planning.",
+  "session_summary": "Project initialised.",
+  "recent_files": [
+    ".planning/PROJECT.md",
+    ".planning/REQUIREMENTS.md",
+    ".planning/STATE.md",
+    ".planning/HANDOFF.json"
+  ],
+  "recent_commits": [],
+  "updated_at": "[ISO 8601 timestamp]",
+  "_warning": "Never store secrets, tokens, or passwords in this file. It is tracked in git."
+}
+```
+
+## Step 3 — Confirm and guide
+Tell the user:
+"✅ MindForge project initialised.
+
+Files created:
+  .planning/PROJECT.md
+  .planning/REQUIREMENTS.md
+  .planning/STATE.md
+  .planning/HANDOFF.json
+
+Next step: Run /mindforge:plan-phase 1 to plan your first phase."

package/.agent/workflows/mindforge:install-skill.md

@@ -0,0 +1,27 @@
+---
+description: Follow the full installation protocol from .mindforge/distribution/registry-client.md.
+---
+Follow the full installation protocol from `.mindforge/distribution/registry-client.md`.
+
+Steps:
+1. Resolve package name from skill name.
+2. Check if already installed (skip if same version, offer upgrade if newer).
+3. Fetch from registry (npm or private if --registry specified).
+4. Validate the skill:
+   ```bash
+   node bin/mindforge-cli.js validate-skill ./SKILL.md
+   ```
+5. Run injection guard check (handled by validator).
+6. Install to tier directory:
+   ```bash
+   node bin/mindforge-cli.js install-skill [skill-name] --tier [1|2|3]
+   ```
+7. Register in MANIFEST.md:
+   ```bash
+   node bin/mindforge-cli.js register-skill [skill-name] [version] [tier]
+   ```
+8. Write AUDIT entry:
+   ```bash
+   node bin/mindforge-cli.js audit-skill [skill-name] [version] [tier]
+   ```
+9. Confirm: "Run /mindforge:skills validate to verify installation"