mindforge-cc 2.0.0-alpha.9 → 2.1.0

package/.claude/commands/mindforge/execute-phase.md

@@ -1,167 +1,37 @@
-# 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.
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
+---
+name: mindforge:execute-phase
+description: Execute the wave-based execution plan for a specific phase
+argument-hint: [N]
+allowed-tools:
+  - view_file
+  - write_to_file
+  - run_command
+  - list_dir
+---
+
+<objective>
+Coordinate the parallel execution of task plans for a phase using a wave-based approach, ensuring dependency integrity, automated verification, and audit logging.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/execute-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (Phase N)
+Sources: .planning/phases/[N]/PLAN-*.md, STATE.md, REQUIREMENTS.md
+Engine: wave-executor.md, dependency-parser.md, context-injector.md
+</context>
+
+<process>
+1. **Pre-checks**: Verify phase status, plan existence, and requirement content. Run dependency parser.
+2. **Display Wave Plan**: Present the wave-based execution graph and wait for user approval.
+3. **Audit Initiation**: Log `phase_execution_started` in `AUDIT.jsonl`.
+4. **Wave Execution**:
+    - For each wave: Execute tasks in parallel.
+    - For each task: Inject context, run implementation, run `<verify>`, and commit with SHA.
+    - If any task fails: Stop the wave and offer debugging.
+5. **Phase Verification**: Check requirement coverage in the implementation and write `VERIFICATION.md`.
+6. **Update State**: Update `STATE.md`, `HANDOFF.json`, and write `WAVE-REPORT-[N].md`.
+7. **Auto-capture**: If enabled, detect new patterns/skills from the implemented phase.
+</process>

package/.claude/commands/mindforge/health.md

@@ -1,21 +1,31 @@
-# MindForge — Health Command
-# Usage: /mindforge:health [--repair] [--category C] [--verbose]
+---
+name: mindforge:health
+description: Run the MindForge health engine to diagnose and repair issues
+argument-hint: [--repair] [--category C] [--verbose]
+allowed-tools:
+  - run_command
+  - list_dir
+  - view_file
+---
 
-Run all seven health-engine categories from `.mindforge/intelligence/health-engine.md`.
+<objective>
+Ensure the MindForge environment and project state are valid, secure, and optimally configured by running a suite of diagnostic checks across multiple categories.
+</objective>
 
-## Output
-- category status summary
-- errors (must fix)
-- warnings (should fix)
-- informational signals
+<execution_context>
+.claude/commands/mindforge/health.md
+</execution_context>
 
-## 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
+<context>
+Engine: .mindforge/intelligence/health-engine.md
+Categories: installation, context, skills, personas, state, integrations, security.
+Flags: --repair (auto-fix), --verbose (full details).
+</context>
 
-## AUDIT
-Append:
-```json
-{ "event": "health_check_completed", "errors": 0, "warnings": 0, "repaired": 0 }
-```
+<process>
+1. **Initialize Diagnostics**: Load the health engine and target specifically requested categories (or all by default).
+2. **Execute Checks**: Scan for configuration errors, missing files, security misconfigurations, and state inconsistencies.
+3. **Repair (Optional)**: If `--repair` is set, apply safe automated fixes for detected issues.
+4. **Report Findings**: Categorize results into Errors (must fix), Warnings (should fix), and Info.
+5. **Audit**: Log `health_check_completed` with counts of errors, warnings, and repairs.
+</process>

package/.claude/commands/mindforge/help.md

@@ -1,23 +1,29 @@
-Show all available MindForge commands.
+---
+name: mindforge:help
+description: Show all available MindForge commands and current project summary
+argument-hint: none
+allowed-tools:
+  - list_dir
+  - view_file
+---
 
-## Pre-check
-If `.planning/STATE.md` exists, read it.
-If `.planning/PROJECT.md` is missing, treat the project as "Not initialised".
+<objective>
+Provide a searchable, categorized directory of all accessible MindForge commands, along with a quick snapshot of the project's current state.
+</objective>
 
-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:
+<execution_context>
+.claude/commands/mindforge/help.md
+</execution_context>
 
-| Command                      | Description                                  |
-|------------------------------|----------------------------------------------|
-| /mindforge:help              | Show all available commands                  |
-| /mindforge:init-project      | ...                                          |
-| ...                          | ...                                          |
+<context>
+Discovery: Scans `.claude/commands/mindforge/*.md`
+State: PROJECT.md and STATE.md
+</context>
 
-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 the agent's system context.
+<process>
+1. **Command Scan**: List all markdown definitions in the command directory and extract their first-line descriptions or YAML metadata.
+2. **Read Project Info**: Summarize the current project name, active phase, and recommended next step.
+3. **Format Dashboard**: Render a clean table of commands and descriptions.
+4. **Verify Context**: If `CLAUDE.md` hasn't been read in the current session, remind the user to load it as the agent's context.
+5. **Display**: Present the help table and project summary.
+</process>

package/.claude/commands/mindforge/init-org.md

@@ -1,131 +1,37 @@
-# 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)
-```
+---
+name: mindforge:init-org
+description: Set up MindForge at the organization level with standardized context
+argument-hint: [--org-name "Name"] [--update]
+allowed-tools:
+  - run_command
+  - list_dir
+  - write_to_file
+  - view_file
+---
+
+<objective>
+Establish a consistent engineering culture and governance framework by generating organization-wide context files, security policies, and tech stack defaults for all projects.
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/init-org.md
+</execution_context>
+
+<context>
+Scope: Organization-wide (Tier 1/2).
+Output: Shared `.mindforge/org/` repository or npm package.
+Governance: Defines Tier 2/3 approver lists and compliance burdens.
+</context>
+
+<process>
+1. **Interview**: Conduct a structured interview about org identity, tech stack, deployment defaults, and compliance (GDPR, HIPAA, etc.).
+2. **Generate Defaults**:
+    - `ORG.md`: Mission and global architecture defaults.
+    - `CONVENTIONS.md`: Tech-stack-specific coding standards.
+    - `SECURITY.md`: Compliance-mapped security policies.
+    - `TOOLS.md`: Approved library and dependency list.
+3. **Configuration**: Pre-populate `INTEGRATIONS-CONFIG.md` and `GOVERNANCE-CONFIG.md`.
+4. **Skill Recommendation**: Suggest core and compliance skills to install org-wide.
+5. **Distribution**: Offer to package the configuration into an npm package for project-wide inheritance.
+6. **Audit**: Log `org_initialised` with frameworks and recommended skills.
+</process>

package/.claude/commands/mindforge/init-project.md

@@ -1,155 +1,40 @@
-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.
-
-## 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."
+---
+name: mindforge:init-project
+description: Initialise a new project under the MindForge framework
+argument-hint: none
+allowed-tools:
+  - view_file
+  - write_to_file
+  - list_dir
+---
+
+<objective>
+Initialise a new project by conducting a structured requirements interview, setting up the `.planning/` directory, and creating the foundational context files (PROJECT.md, REQUIREMENTS.md, STATE.md, HANDOFF.json).
+</objective>
+
+<execution_context>
+.claude/commands/mindforge/init-project.md
+</execution_context>
+
+<context>
+Target Directory: .planning/
+State: Checks if .planning/PROJECT.md already exists before re-initialising.
+</context>
+
+<process>
+1. **Pre-check**: Read `.planning/PROJECT.md`. If it exists, ask the user if they want to re-initialise.
+2. **Requirements Interview**: Ask the following 7 questions one by one:
+    - Description of the project.
+    - Primary user description.
+    - Problem statement.
+    - Tech stack (recommend one if requested).
+    - Scope exclusions (v1).
+    - Success criteria.
+    - Compliance requirements.
+3. **Generate Context Files**:
+    - Write `.planning/PROJECT.md` with the interview results.
+    - Write `.planning/REQUIREMENTS.md` with functional and non-functional tables.
+    - Write `.planning/STATE.md` set to "Project initialised".
+    - Write `.planning/HANDOFF.json` with initial state and context references.
+4. **Finalize**: Confirm the creation of files and guide the user to the next step (`/mindforge:plan-phase 1`).
+</process>