mindforge-cc 1.0.0

package/.agent/mindforge/debug.md

@@ -0,0 +1,126 @@
+# MindForge — Debug Command
+# Usage: /mindforge:debug [description]
+
+Systematic debugging using the Debug Specialist persona with full RCA protocol.
+
+## Activation
+
+Load `.mindforge/personas/debug-specialist.md` immediately.
+This command runs entirely in that persona for its full duration.
+
+## Step 1 — Intake
+
+Ask the user:
+1. "Describe the problem. What is happening vs. what should happen?"
+2. "Can you reproduce it reliably? If yes: what are the exact steps?"
+3. "When did this start? Was it working before? What changed?"
+4. "Do you have an error message or stack trace? Paste it here."
+
+Capture all answers before proceeding.
+
+## Step 2 — Triage
+
+Classify the issue immediately:
+- **Regression** (was working, now broken) → check recent commits
+- **Never worked** (new feature failing) → check the plan and verify step
+- **Environment issue** (works locally, fails in CI) → check environment diffs
+- **Data issue** (specific data causes failure) → check data shape assumptions
+- **Integration issue** (fails when calling external service) → check contracts
+
+Report classification to user: "This looks like a [type] issue. Here's my approach..."
+
+## Step 3 — Follow Debug Specialist protocol
+
+Execute the full protocol from `debug-specialist.md`:
+1. Reproduce
+2. Isolate
+3. Read the error
+4. Check recent changes
+5. Instrument
+6. Form hypothesis
+7. Test hypothesis (write a failing test)
+8. Fix
+9. Verify (test from step 7 now passes, no regressions)
+10. Document
+
+At each step, report what was found before moving to the next step.
+Do not skip steps or combine them.
+
+## Step 3b — Full test suite verification (mandatory)
+After the fix and targeted verify pass, run the project's full test suite.
+Do not mark the debug task complete if any tests fail.
+
+## Step 4 — Check recent git history
+
+```bash
+git log --oneline -20
+git diff HEAD~[N] HEAD -- [suspected file]
+```
+
+If a recent commit is the likely cause, show the user the specific diff.
+
+## Step 5 — Write the RCA report
+
+Create `.planning/phases/[current-phase]/DEBUG-[timestamp].md`:
+
+```markdown
+# Debug Report — [short description]
+
+## Date
+[ISO-8601]
+
+## Problem
+[User's description + what was verified during debugging]
+
+## Root cause category
+[Logic error / Data error / Integration error / Concurrency error /
+Configuration error / Dependency error]
+
+## Root cause
+[Precise description of what the actual cause was]
+
+## Evidence
+- [How the root cause was confirmed]
+- [Failing test that proved the bug: file:line]
+
+## Fix applied
+- File: [path]
+- Change: [description]
+- Commit: [SHA]
+
+## Regression test
+[Test written to prevent this from recurring: file:line]
+
+## Prevention
+[What should change in process/code to prevent this class of bug]
+```
+
+## Step 6 — Write AUDIT entry
+
+```json
+{
+  "id": "uuid",
+  "timestamp": "ISO-8601",
+  "event": "debug_completed",
+  "agent": "mindforge-debug-specialist",
+  "phase": [current phase or null],
+  "session_id": "sess_abc",
+  "issue_type": "regression",
+  "root_cause_category": "Logic error",
+  "root_cause_summary": "[one sentence]",
+  "commit_sha": "[fix commit sha]",
+  "regression_test_added": true,
+  "report_path": ".planning/phases/[N]/DEBUG-[timestamp].md"
+}
+```
+
+## When the bug cannot be reproduced
+
+Ask:
+1. "Does it happen every time or intermittently?"
+2. "Does it happen in specific environments only? (dev/staging/prod)"
+3. "Does it happen for specific users or all users?"
+
+If intermittent: focus on concurrency, caching, and race conditions.
+Write a monitoring/logging plan to catch the next occurrence.
+Document the inconclusive investigation in the DEBUG report with evidence gathered.

package/.agent/mindforge/discuss-phase.md

@@ -0,0 +1,138 @@
+# MindForge — Discuss Phase Command
+# Usage: /mindforge:discuss-phase [N] [--batch] [--auto]
+# Captures implementation decisions before planning begins.
+# Run this BEFORE /mindforge:plan-phase for complex phases.
+
+## Purpose
+Planning without discussion produces generic plans.
+Discussion captures YOUR decisions — layout preferences, library choices,
+UX specifics, edge cases you've already thought through — so the planner
+builds what you actually want, not what seems reasonable.
+
+## When to use
+- Any phase with UI/UX components (visual decisions need capturing)
+- Any phase with multiple valid implementation approaches
+- Any phase where you already have opinions on the approach
+- Any phase touching external services (your preferences on APIs matter)
+- Skip for trivial phases (e.g., "add one field to an existing form")
+
+## Step 1 — Analyse the phase scope
+
+Read:
+- ROADMAP.md for the phase description
+- REQUIREMENTS.md for the requirements in this phase
+- ARCHITECTURE.md for relevant architectural context
+
+Identify the phase's primary domain and any secondary domains.
+If multiple domains are involved, cover each relevant set of questions.
+- **Visual/UI** → ask about layout, interactions, states, empty states, animations
+- **API/Backend** → ask about response format, error handling, auth approach, versioning
+- **Data/Database** → ask about schema design, migration strategy, data volume expectations
+- **Integration** → ask about third-party API choices, error recovery, retry strategy
+- **Infrastructure** → ask about deployment strategy, scaling approach, observability
+
+## Step 2 — Structured discussion
+
+Ask questions ONE AT A TIME. Wait for the full answer before asking the next.
+Do not batch questions (unless `--batch` flag is provided).
+
+### Visual/UI phases — ask about:
+1. "Walk me through what a user sees on this screen from top to bottom."
+2. "What does the empty state look like? (nothing loaded yet / no results / error)"
+3. "Any animations or transitions you're picturing? Or keep it static?"
+4. "On mobile — stacks vertically or anything different?"
+5. "Any edge cases? (very long text, images that fail to load, loading states)"
+
+### API/Backend phases — ask about:
+1. "What's the intended consumer? Internal frontend / external developers / both?"
+2. "For errors — do you want detailed error objects with field-level info or simple messages?"
+3. "Rate limiting needed on any of these endpoints?"
+4. "Any background processing involved, or all synchronous?"
+5. "Versioning approach? /v1/ prefix or header-based?"
+
+### Data/Database phases — ask about:
+1. "What's the expected data volume? Thousands / millions / billions of rows?"
+2. "Any fields that need full-text search vs. exact match?"
+3. "Soft delete or hard delete for user-facing records?"
+4. "Any fields that change frequently vs. infrequently? (affects indexing strategy)"
+5. "Data retention requirements? When can records be deleted?"
+
+### Integration phases — ask about:
+1. "Have you already chosen the third-party service / API? If so, which?"
+2. "What should happen if the third-party service is down? Queue / fail / fallback?"
+3. "Webhooks or polling for receiving updates?"
+4. "Any rate limits you know about on their end?"
+5. "Testing approach? Do they have a sandbox environment?"
+
+## --batch mode
+If `--batch` flag is provided: group related questions and present them together.
+Appropriate when the user wants faster intake and is familiar with MindForge.
+
+Example batch:
+```
+Visual decisions for Phase 2:
+  1. Layout: card grid / table / list?
+  2. Empty state: illustration / simple message / hide section?
+  3. Loading: skeleton / spinner / none?
+  4. Mobile: same layout / stacked / hidden?
+Answer 1-4:
+```
+
+## --auto mode
+If `--auto` flag is provided: skip the discussion entirely.
+The planner will make reasonable defaults for all decisions.
+Use when: the phase is straightforward and you trust the planner's judgment.
+Warn clearly: "Skipping discussion. Planner will make implementation decisions.
+              Results may not match your vision exactly. Proceeding without
+              explicit decisions can create rework later."
+
+## Step 3 — Write CONTEXT.md
+
+After discussion, write `.planning/phases/[N]/CONTEXT.md`:
+
+```markdown
+# Phase [N] Implementation Context
+# Captured: [ISO-8601]
+# Discussion mode: [interactive / batch / auto]
+
+## Phase description
+[From ROADMAP.md]
+
+## Implementation decisions (captured from discussion)
+
+### [Domain: Visual / API / Data / Integration / etc.]
+
+**Decision:** [What was decided]
+**Rationale:** [Why — from user's words]
+**Implications for planning:**
+  - [What the planner should do because of this decision]
+  - [Specific library or pattern to use]
+  - [What to avoid]
+
+[Repeat for each significant decision]
+
+## Open questions (unresolved during discussion)
+- [Question 1]: [Status — decide during planning / decide during execution]
+
+## User's explicit preferences
+[Verbatim or near-verbatim quotes from the discussion that capture specific intent]
+
+## Defaults accepted (decisions the user deferred to the planner)
+- [Area]: planner's choice
+```
+
+## Step 4 — Confirm and guide
+
+Show the user a summary of what was captured:
+
+"✅ Phase [N] discussion complete. [N] decisions captured.
+
+  Key decisions:
+  - [Decision 1 summary]
+  - [Decision 2 summary]
+  - [Decision 3 summary]
+
+  See full context: .planning/phases/[N]/CONTEXT.md
+
+  Next step: Run /mindforge:plan-phase [N] to create implementation plans
+  using these decisions."

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

@@ -0,0 +1,165 @@
+# 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
+3. Run `<verify>` — capture exact output
+4. If verify PASSES:
+   - 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.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```

package/.agent/mindforge/health.md

@@ -0,0 +1,21 @@
+# 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/mindforge/help.md

@@ -0,0 +1,23 @@
+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 the agent's system context.

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

@@ -0,0 +1,131 @@
+# 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)
+```