mindforge-cc 1.0.0

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

@@ -0,0 +1,155 @@
+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."

package/.claude/commands/mindforge/install-skill.md

@@ -0,0 +1,15 @@
+# MindForge — Install Skill Command
+# Usage: /mindforge:install-skill [skill-name|package-name] [--tier 1|2|3] [--registry URL]
+
+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 (Level 1 + Level 2 from skill-validator.md)
+5. Run injection guard check
+6. Install to tier directory (default: Tier 2 org skill)
+7. Register in MANIFEST.md
+8. Write AUDIT entry
+9. Confirm: "Run /mindforge:skills validate to verify installation"

package/.claude/commands/mindforge/map-codebase.md

@@ -0,0 +1,298 @@
+# MindForge — Map Codebase Command
+# Usage: /mindforge:map-codebase [area]
+# Onboards MindForge to an existing (brownfield) codebase.
+# Run this INSTEAD of /mindforge:init-project when joining an existing project.
+
+## When to use this command
+- Joining an existing project that has no MindForge context files
+- Adding MindForge to a team that already has a codebase
+- Onboarding to a new-to-you repository
+- Re-mapping after major architectural changes
+
+## What it produces
+- `.planning/ARCHITECTURE.md` — system architecture discovered from code
+- `.planning/PROJECT.md` — project identity inferred from codebase + user confirmation
+- `.mindforge/org/CONVENTIONS.md` — actual conventions found in the code
+- `.planning/STATE.md` — current position (MindForge onboarded, ready to plan)
+- `.planning/decisions/ADR-NNN-[title].md` — key architectural decisions found
+
+## Pre-execution security check
+
+Before reading ANY files, build an exclusion list.
+NEVER read these file patterns during codebase mapping:
+
+```bash
+# Build the exclusion list
+EXCLUDED_PATTERNS=(
+  "*.env"         ".env.*"       "*.env.local"
+  "*.key"         "*.pem"        "*.p12"         "*.pfx"
+  "secrets/*"     "**/secrets/*" "**/.secrets/*"
+  "*.secret"      "*credentials*"
+  ".npmrc"        # may contain npm tokens
+  ".pypirc"       # may contain PyPI tokens
+  "~/.aws/*"      "~/.ssh/*"
+)
+```
+
+For any file the agent is about to read, check:
+1. Does the file name match any excluded pattern?
+2. Is the file in a directory named `secrets/`, `.secrets/`, or `credentials/`?
+3. Is the file listed in `.gitignore`? (`.gitignore` files are intentionally excluded from git for a reason)
+
+If yes to any: SKIP the file. Log that it was skipped.
+Do not include any content from excluded files in ARCHITECTURE.md or CONVENTIONS.md.
+
+## Step 0 — Clean up any previous mapping artifacts
+
+```bash
+# Remove any stale temp files from a previous mapping attempt
+if [ -d ".planning/map-temp" ]; then
+  echo "Cleaning up previous mapping session..."
+  rm -rf .planning/map-temp
+fi
+mkdir -p .planning/map-temp
+```
+
+## Step 1 — Codebase inventory
+
+Spawn FOUR parallel subagents. Each focuses on one analysis area.
+Each subagent writes its findings to a temporary file.
+
+### Subagent A — Technology Stack Analyst
+Context: minimal (CONVENTIONS.md template + task description)
+Persona: architect.md
+Task:
+```
+Analyse this repository's technology stack. Read:
+- package.json / requirements.txt / Cargo.toml / go.mod (root and workspaces)
+- Dockerfile, docker-compose.yml (if present)
+- CI/CD configuration: .github/workflows/, .gitlab-ci.yml, .circleci/
+- Infrastructure files: terraform/, pulumi/, k8s/, helm/
+
+Write to: .planning/map-temp/STACK.md
+Include:
+- Runtime/language and version
+- Framework(s) and versions
+- Database(s) used
+- Cache and queue systems
+- Testing framework(s)
+- Build and bundling tools
+- Deployment target (AWS/GCP/Azure/bare metal/etc.)
+- External services integrated (payment, email, auth, etc.)
+```
+
+### Subagent B — Architecture Analyst
+Context: minimal
+Persona: architect.md
+Task:
+```
+Analyse this repository's architecture. Read:
+- All files in src/ (or equivalent) — structure, not content
+- README.md and any docs/ directory
+- Any architecture diagrams (look for .png, .svg, .drawio in docs/)
+- Entry points: index.ts, main.py, app.go, server.ts (root-level)
+
+Write to: .planning/map-temp/ARCHITECTURE-RAW.md
+Include:
+- Architectural pattern: MVC / Clean Architecture / Hexagonal / Modular Monolith / Microservices
+- Domain model: what are the core entities? (infer from models/, entities/, types/)
+- API surface: public endpoints found in routes/, controllers/, handlers/
+- Module structure: how is the code organised? Feature-based / Layer-based?
+- Key design patterns in use: Repository, Service, Factory, Observer, etc.
+```
+
+### Scale handling for large codebases
+
+Before reading source files, count them:
+```bash
+find src/ -type f \( -name "*.ts" -o -name "*.py" -o -name "*.go" \) | wc -l
+```
+
+If count > 200 files: use sampling strategy instead of full read:
+- Read 3 files from each top-level subdirectory
+- Prioritise: largest files (by size), entry points (index.*, main.*, app.*)
+- Read the full Prisma schema / SQLAlchemy models / Django models file (always)
+- Read all route/controller index files (always)
+- Sample 2-3 files per feature directory
+- Do NOT read test files during mapping (they follow source patterns, not add to them)
+
+If count > 1000 files: read only entry points, schema files, and top-level indices.
+Report to the user: "Large codebase detected ([N] source files).
+Using sampling strategy — some conventions may require manual confirmation."
+
+### Subagent C — Conventions Analyst
+Context: minimal
+Persona: developer.md
+Task:
+```
+Analyse the actual coding conventions used in this repository.
+Read 5-10 representative source files from different areas of the codebase.
+
+Write to: .planning/map-temp/CONVENTIONS-RAW.md
+Infer and document:
+- Naming conventions: variables, functions, classes, files, database columns
+- Import order and grouping style
+- Error handling patterns: how are errors thrown and caught?
+- TypeScript patterns: preferred type patterns, generic usage
+- Comment style: JSDoc, inline, etc.
+- Test file naming and location pattern
+- Async patterns: callbacks / promises / async-await
+- State management (frontend): if applicable
+- Any recurring patterns that appear across multiple files
+
+Important: document what IS there, not what should be there.
+This is a description of reality, not a prescription.
+```
+
+### Subagent D — Quality Baseline Analyst
+Context: minimal
+Persona: qa-engineer.md
+Task:
+```
+Assess the current quality baseline of this repository.
+
+Write to: .planning/map-temp/QUALITY-BASELINE.md
+Check:
+- Test coverage: does a test suite exist? What framework? Run: [test command] --coverage
+- Linting: is a linter configured? (.eslintrc, .pylintrc, ruff.toml, etc.)
+- Type checking: TypeScript config? Strict mode enabled?
+- CI/CD: does it run tests on PRs?
+- Security: any security scanning in CI?
+- Known issues: open GitHub/GitLab issues, TODO count in source
+
+Note: do not fix anything. Only document what exists.
+```
+
+## Step 2 — Synthesise findings
+
+Read all four temp files. Synthesise into the permanent context files.
+
+### Write `.planning/ARCHITECTURE.md`
+
+Use ARCHITECTURE-RAW.md as input. Write a clean, structured architecture document:
+
+```markdown
+# [Project Name] — Architecture
+
+## System overview
+[2-3 sentences from the subagent's findings]
+
+## Technology stack
+[From STACK.md — organised by layer]
+
+## Architectural pattern
+[From ARCHITECTURE-RAW.md]
+
+## Domain model
+[Core entities and their relationships]
+
+## API surface
+[Key endpoints / GraphQL operations / gRPC services found]
+
+## Module structure
+[How the codebase is organised]
+
+## External integrations
+[Third-party services found]
+
+## Known architectural decisions
+[Any ADRs, architecture docs, or README decisions found]
+
+## Quality baseline
+[From QUALITY-BASELINE.md — honest assessment]
+
+## MindForge onboarding notes
+[What was inferred vs. confirmed, what needs human review]
+```
+
+### Write `.mindforge/org/CONVENTIONS.md`
+
+Use CONVENTIONS-RAW.md as input. Write the conventions file in the standard format,
+but clearly mark inferred conventions:
+
+```markdown
+# Coding Conventions — [Project Name]
+# Source: Inferred from codebase analysis by MindForge
+# Status: DRAFT — confirm with team before treating as authoritative
+
+## IMPORTANT
+These conventions were inferred from code analysis. Review each section
+and mark as [CONFIRMED] or [NEEDS REVIEW] before running /mindforge:plan-phase.
+
+## Naming conventions [NEEDS REVIEW]
+[What was found]
+```
+
+## Step 3 — Present findings for confirmation
+
+Present a summary to the user. Ask for confirmation and corrections:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+MindForge Codebase Analysis Complete
+
+  Stack:
+    Runtime   : Node.js 20 (inferred from .nvmrc)
+    Framework : Next.js 14 (inferred from package.json)
+    Database  : PostgreSQL via Prisma (inferred from prisma/schema.prisma)
+    Auth      : NextAuth.js (inferred from package.json)
+
+  Architecture:
+    Pattern   : Feature-based modular (inferred from src/ structure)
+    Entities  : User, Organization, Project, Task (inferred from Prisma schema)
+    API       : REST API in src/app/api/ (24 route files found)
+
+  Quality baseline:
+    Tests     : Vitest, ~340 test files, ~67% coverage (inferred from coverage report)
+    Linting   : ESLint configured, strict TypeScript
+    CI/CD     : GitHub Actions (4 workflows)
+
+  Conventions: see .mindforge/org/CONVENTIONS.md (DRAFT — needs review)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Does this look correct? (yes / correct [field]: [value] / no)
+```
+
+Wait for user confirmation. Apply any corrections the user provides.
+
+## Step 4 — Write PROJECT.md and STATE.md
+
+After confirmation, write:
+
+`.planning/PROJECT.md` — populated with confirmed findings
+`.planning/STATE.md` — status: "Codebase mapped. Ready to plan first phase."
+Add a warning in STATE.md if CONVENTIONS.md is still DRAFT and requires review.
+`.planning/HANDOFF.json` — updated with onboarding completion
+
+## Step 5 — Clean up and report
+
+After analysis completes, delete `.planning/map-temp/` to avoid stale data.
+
+```bash
+rm -rf .planning/map-temp/
+```
+
+Report to user:
+"✅ Codebase mapped.
+
+  Files created:
+    .planning/ARCHITECTURE.md
+    .planning/PROJECT.md
+    .mindforge/org/CONVENTIONS.md (DRAFT — please review)
+    .planning/STATE.md
+
+  Review .mindforge/org/CONVENTIONS.md and mark each section as [CONFIRMED].
+  Then run /mindforge:plan-phase 1 to begin your first phase."
+
+Write AUDIT entry:
+```json
+{
+  "event": "codebase_mapped",
+  "files_analysed": [N],
+  "entities_found": [N],
+  "api_routes_found": [N],
+  "conventions_confidence": "medium",
+  "requires_human_review": [".mindforge/org/CONVENTIONS.md"]
+}
+```

package/.claude/commands/mindforge/metrics.md

@@ -0,0 +1,22 @@
+# MindForge — Metrics Command
+# Usage: /mindforge:metrics [--phase N] [--window short|medium|long] [--export path]
+
+Display session and phase quality trends with early warning signals.
+
+## Data sources
+- `.mindforge/metrics/session-quality.jsonl`
+- `.mindforge/metrics/phase-metrics.jsonl`
+- `.mindforge/metrics/skill-usage.jsonl`
+- `.mindforge/metrics/compaction-quality.jsonl`
+- `.planning/AUDIT.jsonl` for correlation
+
+## Dashboard sections
+- session quality trend
+- verify pass/security/failure/compaction summary
+- skill usage distribution
+- early warnings + recommendations
+
+## AUDIT
+```json
+{ "event": "metrics_viewed", "window": "short", "early_warnings": 0 }
+```

package/.claude/commands/mindforge/migrate.md

@@ -0,0 +1,40 @@
+# MindForge — Migrate Command
+# Usage: /mindforge:migrate [--from X.Y.Z] [--to X.Y.Z] [--dry-run] [--force]
+
+## Purpose
+Run explicit schema migrations for .planning/ files.
+Normally triggered automatically by /mindforge:update.
+Use this command manually when: auto-migration failed, manual version jump, recovery.
+
+## Flow
+
+### Auto-detect migration need
+Read `schema_version` from HANDOFF.json.
+Compare against current `package.json` version.
+Determine migration path.
+
+### Dry-run mode (--dry-run)
+Show: which migrations would run, what each changes.
+Show: breaking changes for the migration path.
+Make NO changes to any file.
+
+### Backup first
+Before any changes: create `.planning/migration-backup-[timestamp]/`
+Verify backup integrity (file count, non-empty).
+If backup fails: ABORT. Explain disk space issue.
+
+### Execute migrations
+Run `node bin/migrations/migrate.js`.
+Show progress for each migration.
+If any migration fails: auto-restore from backup.
+
+### Verify
+Run /mindforge:health after migration.
+If health errors: report with specific fix instructions.
+Preserve backup until user is satisfied — they must delete it manually.
+
+## Manual version override
+`/mindforge:migrate --from 0.1.0 --to 1.0.0` — forces migration between specified versions.
+Use with care: intended for recovery scenarios where HANDOFF.json schema_version is wrong.
+
+## AUDIT entry

package/.claude/commands/mindforge/milestone.md

@@ -0,0 +1,12 @@
+Create or update a milestone definition in `.planning/milestones/` and track the
+ health of grouped phases. Usage: `/mindforge:milestone <name> [phase list]`
+
+## Outputs
+- milestone document with included phases
+- health summary (on track, at risk, blocked)
+- linked approvals, blockers, and verification status
+
+## Health rules
+- any blocked phase makes the milestone at risk
+- missing verification keeps milestone status yellow
+- completed verified phases count toward release readiness

package/.claude/commands/mindforge/next.md

@@ -0,0 +1,105 @@
+# MindForge — Next Command
+# Usage: /mindforge:next
+
+Auto-detect the current project state and execute the appropriate next step.
+The user does not need to know the workflow. MindForge figures it out.
+
+## HANDOFF.json priority rule
+Check HANDOFF.json BEFORE running the decision tree.
+
+If HANDOFF.json exists AND `updated_at` is within 48 hours AND `next_task` is not null:
+present the HANDOFF state first. Only run the decision tree if the user declines
+or the HANDOFF.json is stale.
+
+## State detection logic
+
+Read STATE.md and HANDOFF.json. Then follow this decision tree:
+
+### Decision tree
+
+```
+Does .planning/PROJECT.md exist AND have content?
+  NO  → Run /mindforge:init-project
+  YES → Continue
+
+Does .planning/ROADMAP.md exist AND have phases defined?
+  NO  → Tell user: "Project is initialised but no phases are defined yet.
+         Describe what Phase 1 should accomplish and I'll plan it."
+         Then run /mindforge:plan-phase 1
+  YES → Continue
+
+Read the phase status from STATE.md.
+
+Does the current phase have plans? (check .planning/phases/[N]/PLAN-[N]-*.md)
+  NO  → Run /mindforge:plan-phase [N]
+  YES → Continue
+
+Do SUMMARY files exist for all plans in the current phase?
+  NO  → Run /mindforge:execute-phase [N]
+  YES → Continue
+
+Does VERIFICATION.md exist for the current phase?
+  NO  → Run /mindforge:verify-phase [N] (automated part)
+  YES → Continue
+
+Does UAT.md exist and show all tests passing?
+  NO  → Run /mindforge:verify-phase [N] (UAT part)
+  YES → Continue
+
+Is this phase marked as shipped in STATE.md?
+  NO  → Run /mindforge:ship [N]
+  YES → Continue
+
+Are there more phases in ROADMAP.md?
+  YES → Increment phase number. Run /mindforge:plan-phase [N+1]
+  NO  → Tell user: "All phases complete! Run /mindforge:ship [N] for the final release."
+```
+
+## Partial phase execution handling
+In the decision tree step "Do SUMMARY files exist for all plans?":
+
+Do not treat this as binary. Check individually:
+
+```
+PLAN-[N]-01.md exists?          SUMMARY-[N]-01.md exists?
+PLAN-[N]-02.md exists?          SUMMARY-[N]-02.md exists?
+PLAN-[N]-03.md exists?          SUMMARY-[N]-03.md exists?
+```
+
+If some SUMMARY files exist and some don't: this is a partially-executed phase.
+Report: "Phase [N] is partially executed: plans [X, Y] are done, [Z] is not."
+Ask: "Resume execution from Plan [Z]? (yes/no)"
+Do not restart the entire phase — resume from the first missing SUMMARY.
+
+## Before auto-executing: always confirm
+Before running any command automatically, tell the user:
+
+```
+MindForge next step detected:
+  Current state : [description of current state]
+  Next action   : [what will be run]
+  Command       : /mindforge:[command] [args]
+
+Run this now? (yes/no/different)
+```
+
+If user says "different": ask what they want to do instead.
+If user says "yes": proceed with the detected command.
+
+## Handling HANDOFF.json (session restart)
+If HANDOFF.json has a `next_task` field from a previous session:
+Present it prominently:
+
+```
+Previous session found:
+  Saved at  : [updated_at from HANDOFF.json]
+  Left off  : [last_completed_task]
+  Next task : [next_task]
+
+Options:
+  1. Continue from where we left off
+  2. Check current state and determine next step fresh
+  3. Tell me what you want to do
+
+Choose 1, 2, or 3:
+```