mindforge-cc 11.3.0 → 11.3.1

package/.claude/commands/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"]
+}
+```

package/.claude/commands/mindforge/market-research.md

@@ -0,0 +1,94 @@
+---
+description: "Competitive analysis and market sizing (TAM/SAM/SOM). Usage: /mindforge:market-research [market] [--competitors url1,url2]"
+---
+
+<objective>
+Conduct structured market research including TAM/SAM/SOM sizing, competitive landscape analysis, SWOT assessment per competitor, opportunity scoring, and positioning recommendations.
+</objective>
+
+<execution_context>
+@.mindforge/skills/market-researcher/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (market vertical or product category, optional --competitors with URLs)
+Knowledge: PROJECT.md, existing product briefs, industry reports, competitor intelligence.
+</context>
+
+<process>
+1. **Define market boundaries**: Establish the scope of the market:
+   - Industry vertical and sub-segment
+   - Geographic scope (global, regional, country-specific)
+   - Customer segments (enterprise, SMB, consumer, developer)
+   - Price tier (free, freemium, mid-market, enterprise)
+   - Adjacent markets that may converge
+
+2. **Size TAM/SAM/SOM**: Calculate market opportunity using both top-down and bottom-up:
+   - **TAM** (Total Addressable Market): Total revenue opportunity if 100% market share
+   - **SAM** (Serviceable Addressable Market): Segment reachable with current product/channel
+   - **SOM** (Serviceable Obtainable Market): Realistic capture in 3 years given competition
+   - Document assumptions, data sources, and confidence level for each estimate
+   - Express in both revenue ($) and units (customers/seats)
+
+3. **Analyze competitors**: For each competitor (from --competitors flag or discovered):
+   - Product overview and core value proposition
+   - Target customer segment and ICP
+   - Pricing model and tiers
+   - Key features and differentiators
+   - Known weaknesses and customer complaints
+   - Estimated market share and revenue
+   - Recent strategic moves (funding, acquisitions, pivots)
+
+4. **SWOT each competitor**: For each analyzed competitor:
+   - **Strengths**: What they do better than anyone else
+   - **Weaknesses**: Where they consistently underperform
+   - **Opportunities**: Market shifts they could capitalize on
+   - **Threats**: Risks to their current position
+   - Rate each dimension 1-5 for severity/importance
+
+5. **Score opportunities**: Evaluate market entry/expansion opportunities:
+   - Market attractiveness (size, growth rate, profitability)
+   - Competitive intensity (number of players, switching costs, differentiation)
+   - Capability fit (how well our strengths match the opportunity)
+   - Time-to-value (how quickly we can capture share)
+   - Risk level (regulatory, technical, market timing)
+   - Composite score and ranking
+
+6. **Identify market gaps**: Find underserved segments or unmet needs:
+   - Features competitors lack that customers request (review mining)
+   - Customer segments ignored by incumbents
+   - Pricing gaps (overserved premium, underserved value tier)
+   - Geographic gaps (markets without localized solutions)
+   - Integration gaps (ecosystems with no good solution)
+
+7. **Recommend positioning**: Based on analysis, propose:
+   - Primary positioning statement (for whom, what, unlike, because)
+   - Differentiation axes (where to compete vs where to concede)
+   - Messaging pillars (3-4 key claims supported by evidence)
+   - Category strategy (create new category vs redefine existing)
+   - Pricing strategy recommendation with rationale
+
+8. **Trend analysis**: Identify market dynamics:
+   - Growth trends (CAGR, seasonal patterns)
+   - Technology shifts impacting the market
+   - Regulatory changes on the horizon
+   - Buyer behavior evolution
+   - Consolidation patterns (M&A activity)
+
+9. **Output research report**: Write structured report to `.planning/MARKET-RESEARCH-[slug].md`:
+   - Executive Summary (key findings in 5 bullets)
+   - Market Sizing (TAM/SAM/SOM with methodology)
+   - Competitive Landscape (matrix comparison table)
+   - SWOT Analyses (per competitor)
+   - Opportunity Assessment (scored and ranked)
+   - Positioning Recommendation
+   - Risks and Uncertainties
+   - Appendix (data sources, methodology notes)
+
+10. **Confidence assessment**: Rate the overall research confidence:
+    - Data recency (when were sources last updated)
+    - Source diversity (single source vs triangulated)
+    - Assumptions requiring validation
+    - Recommended next steps for higher-confidence data
+    - Expiry date (when this research should be refreshed)
+</process>

package/.claude/commands/mindforge/marketplace.md

@@ -0,0 +1,124 @@
+---
+description: Discover, evaluate, and install community-published MindForge skills from the
+---
+
+# MindForge v2 — Marketplace Command
+# Usage: /mindforge:marketplace [search|featured|trending|install|publish]
+# Version: v2.0.0-alpha.6
+
+## Purpose
+Discover, evaluate, and install community-published MindForge skills from the
+marketplace — a curated layer on top of the npm registry.
+
+The marketplace is the shortcut: instead of learning from documentation yourself,
+install skills that the community has already created, validated, and battle-tested.
+
+## Sub-commands
+
+### search [query]
+Find skills relevant to your tech stack or domain.
+```
+/mindforge:marketplace search "prisma"
+/mindforge:marketplace search "stripe payment processing"
+/mindforge:marketplace search "HIPAA compliance"
+/mindforge:marketplace search "graphql api"
+```
+
+Output:
+```
+🔍 Marketplace search: "prisma" (6 results)
+
+  1. prisma-advanced (v1.2.3)
+     Advanced Prisma patterns: relations, migrations, performance, cursor pagination
+     847 installs this week
+
+  2. prisma-schema (v1.0.1)
+     Prisma schema design: models, relations, enums, cascade rules
+     234 installs this week
+
+  3. prisma-testing (v1.0.0)
+     Testing Prisma with Jest: database seeding, teardown, transaction rollback
+     156 installs this week
+
+Install: /mindforge:marketplace install prisma-advanced
+```
+
+### featured
+Show curated featured skills by category.
+```
+/mindforge:marketplace featured
+```
+
+Output:
+```
+🏪 MindForge Community Skills — Featured
+
+  Database:
+    db-postgres-advanced v2.1.0  — Advanced PostgreSQL patterns, indexes, partitioning
+    db-prisma-advanced   v1.2.0  — Prisma relations, migrations, query optimisation
+    db-drizzle           v1.0.0  — Drizzle ORM type-safe patterns
+
+  API:
+    api-graphql v1.4.0  — GraphQL schema, resolvers, N+1 prevention
+    api-rest    v2.0.0  — REST API design, versioning, error schemas
+
+  Compliance:
+    fintech-pci-compliance  v1.1.0 — PCI DSS Level 1 safeguards
+    healthtech-hipaa        v1.0.1 — HIPAA Security Rule for PHI
+    [more...]
+```
+
+### trending
+Show most-installed skills this month.
+```
+/mindforge:marketplace trending
+```
+
+### install [name] [--tier project|org]
+Install a marketplace skill.
+```
+/mindforge:marketplace install prisma-advanced
+/mindforge:marketplace install mindforge-skill-api-graphql --tier org
+/mindforge:marketplace install fintech-pci-compliance --tier project
+```
+
+Short names work (without `mindforge-skill-` prefix).
+Delegates to `/mindforge:install-skill` for actual installation.
+Shows quality score and session_quality_lift before installing.
+
+### publish [skill-dir]
+Publish a skill to the community marketplace.
+```
+/mindforge:marketplace publish .mindforge/skills/my-skill/
+```
+
+Requirements:
+- Quality score ≥ 80/100
+- No injection patterns
+- Has complete version history
+- Has author contact (GitHub issues URL)
+
+## Skill quality display format
+
+```
+📊 Skill: prisma-advanced v1.2.3
+   Quality score: 94/100 (Excellent)
+   ★★★★★ Session quality lift: +8.2 points (over 1,247 sessions)
+   847 installs/week | Published by: @prisma-community
+
+   Top trigger keywords: "prisma schema", "@relation", "prisma migrate",
+                          "prisma generate", "onDelete", "cursor pagination"
+
+   [Install] [Preview SKILL.md] [View on npm]
+```
+
+## AUDIT entry
+```json
+{
+  "event": "marketplace_action",
+  "action": "search|install|publish",
+  "query": "[search query if search]",
+  "skill_name": "[name if install/publish]",
+  "quality_score": 94
+}
+```

package/.claude/commands/mindforge/mcp-server.md

@@ -0,0 +1,88 @@
+---
+description: "Scaffold MCP server implementation with tools, resources, and prompts. Usage: /mindforge:mcp-server [name] [--transport stdio|http] [--tools list]"
+---
+
+<objective>
+Scaffold a complete MCP (Model Context Protocol) server implementation with well-designed tools, resources, and prompts — ready for integration with Claude, VS Code, or any MCP-compatible client.
+</objective>
+
+<execution_context>
+@.mindforge/skills/mcp-server-patterns/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (server name, optional --transport stdio|http, optional --tools comma-separated list)
+Knowledge: MCP specification, existing server patterns, client capabilities, Zod schema patterns.
+</context>
+
+<process>
+1. **Identify capabilities**: Based on the server name and --tools flag, determine:
+   - What domain does this server expose? (database, API, file system, service)
+   - What operations should be available as tools? (CRUD, queries, actions)
+   - What data should be exposed as resources? (documents, schemas, configs)
+   - What prompts would help users interact effectively?
+   - What permissions/scopes are needed?
+
+2. **Design tool schemas**: For each tool, define with Zod:
+   - Tool name (verb-noun format: `query_database`, `create_issue`)
+   - Description (clear, concise, explains when to use it)
+   - Input schema (Zod object with descriptions per field)
+   - Required vs optional parameters
+   - Validation rules (min/max, regex patterns, enums)
+   - Example inputs for documentation
+
+3. **Design resources**: For each resource, define:
+   - URI pattern (e.g., `myserver://projects/{id}/config`)
+   - MIME type (application/json, text/markdown, etc.)
+   - Description of what the resource represents
+   - Whether it supports subscriptions (live updates)
+   - Access pattern (list → read, or direct URI)
+
+4. **Choose transport**: Based on --transport flag or requirements:
+   - `stdio`: For local CLI integration (simpler, lower latency, single client)
+   - `http`: For remote/multi-client access (SSE for server→client, HTTP POST for client→server)
+   - Document the connection lifecycle and reconnection behavior
+   - Configure appropriate timeouts and keep-alive settings
+
+5. **Scaffold implementation**: Generate the project structure:
+   - `src/index.ts` — Server entry point and transport setup
+   - `src/tools/` — One file per tool with handler and schema
+   - `src/resources/` — Resource providers with URI routing
+   - `src/prompts/` — Prompt templates with argument schemas
+   - `package.json` — Dependencies (@modelcontextprotocol/sdk, zod)
+   - `tsconfig.json` — Strict TypeScript configuration
+
+6. **Add error handling**: Implement robust error handling:
+   - Typed error codes (InvalidParams, MethodNotFound, InternalError)
+   - User-friendly error messages (not stack traces)
+   - Graceful degradation when external services are unavailable
+   - Request validation before processing (fail fast)
+   - Timeout handling for long-running operations
+
+7. **Implement tool handlers**: For each tool:
+   - Parse and validate input against Zod schema
+   - Execute the operation with proper error boundaries
+   - Return structured results (content array with type and text/image)
+   - Log operations for debugging (structured JSON logs)
+   - Handle cancellation for long-running tools
+
+8. **Add prompts**: Design prompt templates that:
+   - Guide users toward effective tool usage
+   - Include argument schemas for dynamic prompts
+   - Provide context about server capabilities
+   - Suggest workflows combining multiple tools
+
+9. **Test with MCP Inspector**: Generate test configuration:
+   - Inspector connection config (transport settings)
+   - Test cases for each tool (valid inputs, edge cases, error cases)
+   - Resource listing and read verification
+   - Prompt rendering with sample arguments
+   - Connection lifecycle testing (connect, disconnect, reconnect)
+
+10. **Output documentation**: Generate:
+    - README.md with installation and usage instructions
+    - Tool reference (auto-generated from schemas)
+    - Resource URI reference
+    - Example client configuration for Claude Desktop / VS Code
+    - Troubleshooting guide (common connection issues)
+</process>

package/.claude/commands/mindforge/meeting-design.md

@@ -0,0 +1,37 @@
+---
+name: mindforge:meeting-design
+description: "Design effective meeting or async process. Usage: /mindforge:meeting-design [purpose] [--format sync|async|hybrid] [--size small|large]"
+argument-hint: "[purpose] [--format sync|async|hybrid] [--size small|large]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design meetings or async processes that maximize output per minute of team time. Applies forcing functions to eliminate unnecessary sync time and optimize for decision quality over meeting cadence.
+</objective>
+
+<execution_context>
+@.mindforge/skills/meeting-architecture/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/meeting-architecture/`
+State: Evaluates meeting purpose, applies async-first heuristics, designs agendas with decision protocols, outputs structured meeting artifact templates.
+</context>
+
+<process>
+1. **Async-First Filter**: Ask "Can this be a doc + comment thread?" If yes (status update, one-way announcement, information gathering) → reject meeting, design async artifact instead (RFC, decision doc, survey). Only proceed to sync if: requires real-time debate, builds team rapport, or resolves ambiguity that written async cannot.
+
+2. **Purpose Classification**: Decision (choose between options) → design with pre-read + decision protocol (DACI/RACI). Brainstorm (generate options) → structure with divergent → convergent phases. Alignment (shared understanding) → pre-read heavy, meeting for Q&A only. Planning (decompose work) → prepare draft plan async, sync to resolve dependencies only.
+
+3. **Attendee Optimization**: Required (can't make decision without them), Optional (contribute but not block), FYI (read notes after). Default everyone to FYI. Promote to Required only if they have unique context or decision authority. Cap Required at 5 people. If >5 Required → meeting scope too broad, split into separate sessions.
+
+4. **Pre-Work Design**: Distribute artifact 48h before (1-pager for 30min meeting, 3-pager for 60min). Include: context (why now), options (what are we choosing between), recommendation (what I think we should do), decision needed (what must be resolved in sync). Set expectation: no pre-read = no attendance. Meeting time is for synthesis, not information transfer.
+
+5. **Agenda Structure**: 5min - Restate decision/goal from pre-read. 15min - Surface objections/alternatives (round-robin, everyone speaks). 20min - Debate trade-offs (timebox per topic). 15min - Converge on decision (decision maker calls it). 5min - Document outcomes, next actions, owner. Total 60min max. If more needed → insufficient pre-work or wrong format.
+
+6. **Decision Protocol**: DACI (Driver owns outcome, Approver makes call, Contributors give input, Informed are notified). Identify each role before meeting. During debate, label contributions (this is input vs this is a block). At decision point, Approver explicitly states decision + rationale. Driver documents decision in shared log within 24h.
+
+7. **Async Alternative Design**: For rejected meetings → create structured artifact. Status update → written update in Slack with (accomplished, in-progress, blocked, help-needed). Brainstorm → Miro board with 48h async contribution window. Alignment → Loom video + doc with comment thread. Planning → draft plan in Notion, async review with inline feedback, sync only for dependency resolution.
+</process>

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

@@ -0,0 +1,26 @@
+---
+description: Display session and phase quality trends with early warning signals.
+---
+
+# 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 }
+```