mindforge-cc 11.3.0 → 11.4.0

package/.agent/mindforge/learn-instinct.md

@@ -0,0 +1,58 @@
+---
+description: Manually capture a learned behavior as an instinct with initial confidence scoring. Usage - /mindforge:learn-instinct [observation] [--behavior "what to do"] [--confidence 0.7] [--tags tag1,tag2]
+---
+
+<objective>
+Create a new instinct entry manually, capturing a behavioral pattern the agent
+should remember and apply in future sessions.
+</objective>
+
+<execution_context>
+@.mindforge/engine/instincts/instinct-schema.md
+@.mindforge/engine/instincts/capture-engine.md
+@.mindforge/skills/continuous-learning/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Parse arguments:
+   - observation: what pattern was observed (required)
+   - --behavior: what to do when pattern detected (required)
+   - --confidence: initial confidence (default: 0.7 for manual capture)
+   - --tags: classification tags (optional, auto-derived if not provided)
+2. **Deduplication check:**
+   - Read `.mindforge/engine/instincts/instinct-store.jsonl`
+   - Compare observation against all active instincts (same project)
+   - If >80% word overlap: warn "Similar instinct exists" and show it
+   - Ask user: reinforce existing or create new?
+3. **Capacity check:**
+   - Count active instincts for current project
+   - If at 100: identify lowest-confidence instinct for pruning
+   - Inform user: "At capacity. Will prune: [lowest instinct] (confidence: X)"
+4. **Create instinct entry:**
+   ```json
+   {
+     "id": "inst-[generate-uuid]",
+     "created_at": "[current timestamp]",
+     "updated_at": "[current timestamp]",
+     "observation": "[from args]",
+     "behavior": "[from args]",
+     "confidence": [from args or 0.7],
+     "times_applied": 0,
+     "times_succeeded": 0,
+     "times_failed": 0,
+     "project": "[current project name]",
+     "tags": [from args or auto-derived],
+     "status": "active",
+     "promoted_to_skill": null,
+     "last_applied_at": null,
+     "source_sessions": ["[current session id]"]
+   }
+   ```
+5. Append entry to `instinct-store.jsonl`.
+6. Report: "Instinct captured. Active: [count]/100. Confidence: [X]."
+7. Log in AUDIT: instinct_created event.
+</process>

package/.agent/mindforge/learn.md

@@ -0,0 +1,147 @@
+---
+description: Convert any knowledge source into a reusable, validated, committed MindForge SKILL.md.
+---
+
+# MindForge v2 — Learn Command
+# Usage: /mindforge:learn [url|path|--session|npm:package] [--name skill-name] [--tier project|org|core]
+# Version: v2.0.0-alpha.6
+
+## Purpose
+Convert any knowledge source into a reusable, validated, committed MindForge SKILL.md.
+Feed Claude your documentation and it writes down what it learned — for every future session.
+
+## The insight
+Every developer on your team already knows how Prisma works, how your internal API
+conventions are structured, how your CI pipeline behaves. That knowledge lives in their
+heads and in documentation. `/mindforge:learn` captures it permanently as skills that
+load automatically whenever relevant work begins.
+
+## Usage examples
+
+### Learn from external documentation
+```
+/mindforge:learn https://docs.prisma.io/concepts/components/prisma-schema
+/mindforge:learn https://stripe.com/docs/webhooks
+/mindforge:learn https://docs.aws.amazon.com/lambda/latest/dg/nodejs-handler.html
+```
+→ Fetches the page (with SSRF protection)
+→ Uses Gemini 2.5 Pro (1M context) for large docs, claude-sonnet-4-6 for smaller ones
+→ Extracts 10 patterns + 15-25 trigger keywords
+→ Writes SKILL.md + scores it + presents for approval
+
+### Learn from local documentation
+```
+/mindforge:learn ./docs/api-conventions.md
+/mindforge:learn ./docs/internal/
+/mindforge:learn ./CONTRIBUTING.md
+```
+→ Reads local files directly (no model call for reading, only for analysis)
+→ Perfect for: internal API docs, team conventions, onboarding guides
+
+### Learn from npm package docs
+```
+/mindforge:learn npm:zod
+/mindforge:learn context7:zod
+/mindforge:learn npm:drizzle-orm
+/mindforge:learn context7:drizzle-orm
+```
+→ Fetches README from npm registry or real-time docs from Context7
+→ Extracts patterns from the package documentation
+
+### Learn from current session
+```
+/mindforge:learn --session
+```
+→ Analyses SUMMARY files from the most recent phase
+→ Finds patterns that appeared across 2+ tasks
+→ Generates up to 3 skills from what was learned (focused: quality over quantity)
+→ Does NOT repeat patterns already in the knowledge base
+
+## Flags
+
+### --name [skill-name]
+Override the auto-generated skill name (kebab-case).
+Default: inferred from the URL domain/path or file name.
+Example: `/mindforge:learn ./docs/prisma-patterns.md --name prisma-advanced`
+
+### --tier [project|org|core]
+Where to install the skill (default: project).
+- project: only loads in this project (T3)
+- org: loads in all projects using this org config (T2)
+- core: loads everywhere (T1 — use sparingly)
+
+### --model [model-id]
+Override the model used for analysis.
+Default: RESEARCH_MODEL for large content (>50K chars), EXECUTOR_MODEL for small.
+
+## Output format
+
+```
+📚 Learning from: https://docs.prisma.io/...
+
+  🔍 Fetching content...            done (148K chars)
+  🧠 Extracting patterns (gemini-2.5-pro)...
+  Step 1/3 — Extracting patterns... done (10 patterns)
+  Step 2/3 — Generating triggers... done (22 triggers)
+  Step 3/3 — Writing SKILL.md...    done
+
+📊 Skill Quality Score: 84/100 (Good — can register + publish)
+  trigger_coverage   : 26/30   ✅
+  mandatory_actions  : 21/25   ✅
+  code_examples      : 17/20   ✅
+  self_check         : 12/15   ✅
+  injection_safe     : 10/10   ✅
+  no_placeholders    : 9/10    ✅
+  version_history    : 8/10    ⚠️
+
+Preview (top 3 patterns):
+  1. [CRITICAL] Always define explicit cascade behaviour
+     "Set onDelete on every @relation — never rely on database defaults"
+  2. [HIGH] Use compound indexes for cursor pagination
+     "Always index (createdAt, id) together for reliable cursor pagination"
+  3. [HIGH] Never use String for UUID fields in Prisma schema
+     "Use @id @default(uuid()) with the String type — Prisma handles this"
+
+Triggers (22): prisma schema, schema.prisma, @relation, prisma migrate,
+               @id @default, prisma.findMany, prisma generate, model definition...
+
+Skill file: .mindforge/skills/prisma-schema/SKILL.md
+
+[ y ] Register in project tier and commit
+[ n ] Discard
+[ e ] Edit SKILL.md before registering
+[ p ] Register AND publish to community marketplace (score ≥ 80 ✅)
+```
+
+## After registration
+
+```
+✅ Skill registered: prisma-schema (T3 Project)
+
+  Will auto-load when tasks contain:
+    "prisma schema", "schema.prisma", "@relation", "prisma migrate"...
+
+  Committed: feat(skills): learn prisma-schema from docs.prisma.io
+
+  Next: /mindforge:skills info prisma-schema
+```
+
+## Integration with auto-capture
+When `AUTO_CAPTURE_SKILLS=true` in MINDFORGE.md:
+`/mindforge:learn --session` is called automatically after each phase completion.
+The prompt is shown; if no patterns found, it exits silently (no noise).
+
+## AUDIT entry
+```json
+{
+  "event": "skill_learned",
+  "source_type": "url|local|session|npm",
+  "source": "[url or path]",
+  "skill_name": "prisma-schema",
+  "quality_score": 84,
+  "pattern_count": 10,
+  "trigger_count": 22,
+  "tier": "project",
+  "cost_usd": 0.31
+}
+```

package/.agent/mindforge/learning.md

@@ -0,0 +1,20 @@
+---
+description: Consult or initialize the project agentic learning memory - AGENTS_LEARNING.md
+---
+
+# /mindforge:learning [init]
+
+Consult the project's persistent engineering memory to avoid past mistakes and follow established best practices.
+
+## Usage
+
+- `/mindforge:learning`: Displays the current learning status and path to the learning file.
+- `/mindforge:learning init`: Initializes a new `AGENTS_LEARNING.md` in the project root if it doesn't already exist.
+
+## Why use this?
+Before starting any significant implementation or refactor, you MUST consult the learning memory. It contains project-specific "Anti-Patterns" to avoid and "Best Practices" that have been proven in this specific system.
+
+## Example
+1. Run `/mindforge:learning` to find where the learning file is.
+2. Read the file to understand recent architectural shifts or discovered failure scenarios.
+3. If the project is new, run `/mindforge:learning init` to scaffold the memory.

package/.agent/mindforge/llm-route.md

@@ -0,0 +1,37 @@
+---
+name: mindforge:llm-route
+description: "Design LLM orchestration and routing. Usage: /mindforge:llm-route [system] [--strategy cascade|parallel|router] [--budget tokens]"
+argument-hint: "[system] [--strategy cascade|parallel|router] [--budget tokens]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design intelligent LLM orchestration systems that route requests across multiple models based on complexity, cost, and latency requirements. This command creates routing strategies (cascade, parallel, learned routing), fallback mechanisms, and optimization patterns that balance quality, speed, and cost across heterogeneous LLM deployments.
+</objective>
+
+<execution_context>
+@.mindforge/skills/llm-orchestration/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/llm-orchestration/`
+State: Analyzes request patterns, model capabilities, cost constraints, and quality thresholds to design routing logic, caching strategies, and orchestration workflows that optimize for throughput and accuracy.
+</context>
+
+<process>
+1. **Request Classification**: Design intent classification to route queries by type (factual lookup, creative generation, reasoning), implement complexity scoring using heuristics or learned classifiers, and create routing decision trees based on input characteristics.
+
+2. **Cascade Routing Strategy**: Implement cheapest-first cascade (Haiku → Sonnet → Opus) with confidence thresholding, design validation checks to determine if escalation is needed, and specify retry logic with context preservation across models.
+
+3. **Parallel Routing with Fusion**: Design parallel execution across multiple models for critical queries, implement response fusion strategies (voting, averaging, judge model selection), and optimize for latency with timeout and early-exit conditions.
+
+4. **Learned Routing Models**: Train routing classifiers on historical query/outcome data, implement feature extraction (query length, domain, user tier), and design online learning loops to adapt routing decisions based on performance feedback.
+
+5. **Caching and Deduplication**: Implement semantic caching with embedding similarity thresholds, design cache invalidation strategies for dynamic content, and create prompt canonicalization to maximize cache hit rates.
+
+6. **Cost and Performance Optimization**: Track cost per query across models with token usage accounting, implement budget constraints and throttling per user/tenant, and design cost-aware routing that prioritizes cheaper models when quality thresholds permit.
+
+7. **Fallback and Resilience**: Design graceful degradation when primary models are unavailable, implement retry logic with exponential backoff across providers, and create circuit breakers to isolate failing models without impacting overall system availability.
+</process>

package/.agent/mindforge/load-test.md

@@ -0,0 +1,30 @@
+---
+description: Design load test scenario with profiles. Usage - /mindforge:load-test [endpoint] [--profile ramp|spike|soak] [--target-rps N]
+---
+
+<objective>
+Design and implement a load testing strategy with configurable profiles that
+validates system behavior under stress. Identifies breaking points, latency
+degradation curves, and resource exhaustion thresholds.
+</objective>
+
+<execution_context>
+@.mindforge/skills/load-testing/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Define SLAs and performance objectives — target p50/p95/p99 latencies, maximum error rate, throughput requirements, and resource utilization ceilings.
+2. Select test type based on --profile flag: ramp (gradual increase to find ceiling), spike (sudden burst to test elasticity), or soak (sustained load to find memory leaks and connection exhaustion).
+3. Design the load profile with specific stages — VU ramp-up duration, hold duration, ramp-down. For spike: define burst magnitude and recovery window.
+4. Write the test script using k6 or Locust. Include realistic user flows, proper think times, data parameterization, and correlation of dynamic values.
+5. Configure thresholds that define pass/fail criteria — e.g., http_req_duration p95 < 500ms, http_req_failed < 1%, checks > 99%.
+6. Run the load test against staging environment. Ensure staging mirrors production topology (same instance types, connection pool sizes, rate limits).
+7. Analyze results: identify bottleneck (CPU, memory, DB connections, external dependency), find the inflection point where latency degrades non-linearly.
+8. Document findings with charts: latency vs throughput curve, error rate vs load, resource utilization timeline. Include specific recommendations for capacity planning.
+9. Create a repeatable test suite that can run in CI on a schedule (nightly) or before releases. Configure baseline comparison to detect regressions.
+10. Log load-test invocation in AUDIT with: endpoint, profile, target RPS, peak RPS achieved, p95 latency at peak.
+</process>

package/.agent/mindforge/logistics.md

@@ -0,0 +1,31 @@
+---
+name: mindforge:logistics
+description: "Design logistics optimization system. Usage: /mindforge:logistics [component] [--type routing|warehouse|delivery]"
+argument-hint: "[component] [--type routing|warehouse|delivery]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Designs logistics and supply chain optimization systems for route planning, warehouse management, and last-mile delivery. Produces architectures for vehicle routing algorithms, inventory optimization, real-time tracking, and delivery orchestration with cost and time efficiency goals.
+</objective>
+
+<execution_context>
+@.mindforge/skills/logistics-optimization/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/logistics-optimization/`
+State: Evaluates logistics optimization requirements, operational constraints, and produces architecture with route planning algorithms, warehouse automation integration, real-time tracking, and dynamic dispatch systems.
+</context>
+
+<process>
+1. **Domain Analysis**: Identify logistics scope (last-mile delivery, long-haul trucking, warehouse fulfillment, multi-modal shipping) and define optimization objectives (minimize cost, delivery time, carbon footprint), constraints (vehicle capacity, driver hours, time windows), and scale (orders/day, fleet size).
+2. **Route Optimization**: Design vehicle routing system with constraint satisfaction algorithms (VRP, CVRP with time windows), real-time route recalculation for dynamic orders, traffic-aware routing with ETA prediction, and multi-stop optimization considering driver shifts and vehicle capacity.
+3. **Warehouse Management Integration**: Architect WMS integration for order allocation to warehouses based on inventory availability and proximity, pick-pack-ship workflow orchestration, barcode/RFID tracking for package movement, and automated sorting system coordination.
+4. **Real-Time Tracking**: Implement GPS tracking for delivery vehicles with position updates, geofencing for delivery zone entry/exit events, mobile app for driver navigation and proof-of-delivery (signature, photo), and customer notification system with live tracking links.
+5. **Dynamic Dispatch**: Build dispatch system with load balancing across drivers, real-time order insertion into existing routes, driver assignment optimization based on location and capacity, and exception handling for failed deliveries with automatic rescheduling.
+6. **Inventory Optimization**: Design inventory forecasting with demand prediction, safety stock calculations, reorder point automation, and multi-warehouse inventory balancing to reduce stockouts while minimizing holding costs with ABC analysis for prioritization.
+7. **Analytics and Reporting**: Create operational dashboards with delivery performance metrics (on-time rate, cost per delivery, vehicle utilization), route efficiency analysis, driver performance tracking, and predictive analytics for demand forecasting and capacity planning.
+</process>

package/.agent/mindforge/map-codebase.md

@@ -0,0 +1,302 @@
+---
+description: - Joining an existing project that has no MindForge context files
+---
+
+# 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"]
+}
+```