thevoidforge 21.0.11 → 21.0.12

package/dist/docs/methods/MCP_INTEGRATION.md

@@ -0,0 +1,139 @@
+# MCP INTEGRATION GUIDE
+## System Protocol · Used by: All Agents
+## Using Model Context Protocol Servers with the Scaffold
+
+> *External tools expand what agents can do. This guide covers when and how to use them.*
+
+## What MCP Servers Are
+
+MCP (Model Context Protocol) servers provide Claude Code with access to external tools and services — databases, APIs, file systems, SaaS platforms — through a standardized interface. They extend what agents can do beyond code and local files.
+
+## When to Use MCP Servers
+
+| Scenario | MCP Server | Which Agent Uses It |
+|----------|-----------|-------------------|
+| Project management | Todoist, Linear, Jira | Picard (planning), Batman (bug tracking) |
+| Documentation | Notion, Confluence | Picard (ADRs), Galadriel (design docs) |
+| Communication | Slack | All (status updates, handoffs) |
+| Design | Figma | Galadriel (design specs), Arwen (visual audit) |
+| Monitoring | Datadog, Grafana | Kusanagi (L — monitoring), Stark (Fury — performance) |
+| Version control | GitHub | All (PRs, issues, code review) |
+| Database | PostgreSQL, Supabase | Stark (Banner — schema), Picard (Spock — data architecture) |
+| AI/ML | Hugging Face | Stark (model selection), Picard (architecture) |
+
+## Integration Patterns
+
+### Pattern 1: Task Tracking
+
+When the PRD is large, use a project management MCP to track build phases:
+
+```
+Phase 0 (Orient)     → Create project with sections matching build phases
+Phase 1-8 (Build)    → Create tasks per feature, track completion
+Phase 9-11 (Audit)   → Create issues per finding, link to code
+Phase 12-13 (Deploy) → Launch checklist as task list
+```
+
+### Pattern 2: Communication
+
+For team visibility during parallel agent work:
+
+```
+Agent starts phase    → Post status to project channel
+Agent finds blocker   → Post to relevant agent's attention
+Agent completes phase → Post summary with deliverables
+Handoff between agents → Post handoff context
+```
+
+### Pattern 3: Documentation
+
+For projects that need living documentation:
+
+```
+ADRs (Picard)           → Architecture decision page/doc
+API docs (Stark)        → API reference page
+UX audit (Galadriel)    → Issue tracker with screenshots
+Security findings (Kenobi) → Security audit doc with severity tags
+```
+
+## Configuring MCP Servers
+
+MCP servers are configured in Claude Code's settings. Each server provides specific tools that become available during sessions.
+
+### Project-Level Configuration
+
+Add MCP servers relevant to your project in `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "npx",
+      "args": ["-y", "@mcp-server/package-name"],
+      "env": {
+        "API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+### Common Server Configurations
+
+**GitHub** — PRs, issues, code review:
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+**PostgreSQL** — Direct database access:
+```json
+{
+  "mcpServers": {
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres"],
+      "env": {
+        "DATABASE_URL": "${DATABASE_URL}"
+      }
+    }
+  }
+}
+```
+
+## Security Rules (Kenobi Enforces)
+
+1. **Never commit MCP API keys to git.** Use environment variable references.
+2. **Use read-only access** where possible. Write access only when explicitly needed.
+3. **Scope permissions narrowly.** Don't give a server access to all repos when it only needs one.
+4. **Review what data MCP servers can access.** PII-containing databases need extra caution.
+5. **Rotate keys** if a server is removed or compromised.
+
+## Agent-MCP Mapping
+
+When delegating work, agents should use MCP tools that match their domain:
+
+| Agent | Primary MCP Tools | Use Case |
+|-------|------------------|----------|
+| **Picard** | GitHub (PRs/issues), Notion (docs) | Architecture decisions, planning |
+| **Stark** | Database, GitHub (code) | Schema inspection, API implementation |
+| **Galadriel** | Figma, Notion (design docs) | Design specs, component inventory |
+| **Batman** | GitHub (issues), project management | Bug tracking, regression checklists |
+| **Kenobi** | GitHub (security alerts) | Vulnerability scanning, audit trails |
+| **Kusanagi** | Monitoring, cloud providers | Infrastructure management, deploy status |
+
+## When NOT to Use MCP
+
+- Don't use MCP for something the local filesystem handles fine
+- Don't add MCP servers speculatively — add them when a specific need arises
+- Don't use MCP to bypass local development (e.g., don't query prod DB when you should use a local copy)
+- Don't configure MCP servers with overly broad permissions

package/dist/docs/methods/MUSTER.md

@@ -0,0 +1,148 @@
+# THE MUSTER — Full-Roster Agent Deployment
+## System Protocol · Orchestrates: All 9 Universes · Defined by: **Fury** (Marvel)
+## Activation: `--muster` flag on any command
+
+> *"The beacons are lit! Gondor calls for aid!" — Gandalf*
+> *"And Rohan will answer." — Théoden*
+
+## AGENT DEPLOYMENT IS MANDATORY
+
+**When `--muster` is invoked, you MUST launch agents via the Agent tool as separate sub-processes.** Do NOT shortcut to inline analysis. Do NOT "think through" each agent's perspective in your own response. The Muster exists because parallel sub-processes catch things sequential inline reasoning misses. Inline analysis that roleplays agent perspectives is NOT a Muster — it is a protocol violation.
+
+**Why this rule exists:** In the v18.0 design session, the agent presented an inline analysis that "covered" 6 domain leads' perspectives in a single response. When the user demanded real agent deployment, the actual 3-wave Muster found 5 blockers and expanded the plan from 5 to 8 missions. The inline version missed all 5 blockers. Inline reasoning is not a substitute for parallel sub-process analysis. (Field report #154)
+
+## Identity
+
+The Muster is VoidForge's maximum-agent protocol. When `--muster` is passed, every agent across all 9 universes that has relevant expertise for the specific task gets deployed. It is not a review protocol (that's the Gauntlet). It is not a build protocol (that's /assemble). It is a **decision-density protocol** — the flag you use when you want every perspective in the room before committing to a direction.
+
+**When to use:** Architecture decisions that affect the whole system. Campaign mission planning for critical features. Build phases where the wrong choice costs days. Any moment where "I wish I'd asked someone else" would be expensive.
+
+**When NOT to use:** Routine missions, bug fixes, documentation updates, or any task where the standard agent roster is sufficient. The Muster is expensive — 30-50 agent launches. Use it for decisions that matter.
+
+## The Protocol
+
+### Step 1 — The Beacons (Gandalf)
+
+Read the task scope and produce a 1-paragraph brief:
+- What is being built/decided/designed?
+- What domains does it touch? (security, UX, architecture, financial, AI, infra, growth)
+- What decisions need to be made?
+- What are the stakes if the wrong choice is made?
+
+### Step 2 — The Muster Roll (Théoden)
+
+For each of the 9 universes, evaluate which agents have relevant expertise for **this specific task**. Not "who exists" — "who has something to say."
+
+**Evaluation criteria per agent:**
+1. Does this agent's domain overlap with the task? → Include
+2. Does this agent's adversarial lens apply? → Include in Wave 3
+3. Does this agent bring a unique perspective no other included agent covers? → Include
+4. Would this agent's findings be a subset of another agent's? → Exclude (dedup)
+
+**Universe leads (always evaluated, included if relevant):**
+
+| Universe | Lead | Domain | Include When |
+|---|---|---|---|
+| Star Trek | Picard | Architecture | Architecture, schema, scaling decisions |
+| Marvel | Stark | Code Review | Implementation, patterns, integration |
+| DC | Batman | QA | Edge cases, error states, testing strategy |
+| Tolkien | Galadriel | UX | User-facing changes, a11y, design |
+| Star Wars | Kenobi | Security | Auth, encryption, access control, secrets |
+| Anime | Kusanagi | DevOps | Deploy, infra, monitoring, networking |
+| Cosmere | Kelsier | Growth | Revenue, campaigns, distribution, analytics |
+| Foundation | Seldon | AI | LLM integration, prompts, orchestration, safety |
+| Dune | Chani | Comms | Remote control, messaging, notifications |
+
+**Extended roster (include when domain matches):**
+
+| Agent | Universe | Include When |
+|---|---|---|
+| Spock | Star Trek | Schema, data modeling, normalization |
+| Scotty | Star Trek | Scaling, performance, service boundaries |
+| Torres | Star Trek | Performance architecture, bottlenecks |
+| La Forge | Star Trek | Failure modes, graceful degradation |
+| Janeway | Star Trek | Novel architectures (event-sourcing, CQRS, serverless) |
+| Riker | Star Trek | Trade-off challenges, ADR review |
+| Troi | Star Trek | PRD compliance, prose verification |
+| Tuvok | Star Trek | Security architecture, auth flow design |
+| Kim | Star Trek | API design, REST conventions |
+| Banner | Marvel | Edge cases, boundary conditions |
+| Strange | Marvel | Complexity analysis, time-sensitive decisions |
+| Romanoff | Marvel | Attack surface, reconnaissance |
+| Vision | Marvel | Diff analysis, change classification |
+| Wong | Marvel | Lessons, pattern promotion |
+| Nightwing | DC | Regression testing, re-verification |
+| Deathstroke | DC | Adversarial bypass, defense testing |
+| Constantine | DC | Cursed code, hidden problems in "clean" areas |
+| Oracle | DC | Data analysis, forensics |
+| Samwise | Tolkien | Accessibility, screen readers, keyboard nav |
+| Éowyn | Tolkien | Enchantment, micro-animations, delight |
+| Elrond | Tolkien | Systems integration, council synthesis |
+| Celeborn | Tolkien | Design system, visual consistency |
+| Ahsoka | Star Wars | Access control, authorization patterns |
+| Maul | Star Wars | Adversarial security, bypass attempts |
+| Padmé | Star Wars | Functional verification, critical path testing |
+| Yoda | Star Wars | Wisdom, architectural longevity |
+| Vin | Cosmere | Analytics, metrics, pattern detection |
+| Navani | Cosmere | SEO, technical precision, structured data |
+| Steris | Cosmere | Budget, forecasting, contingency |
+| Szeth | Cosmere | Compliance, legal, policy enforcement |
+| Dalinar | Cosmere | Competitive analysis, strategic positioning |
+| Salvor Hardin | Foundation | Model selection, cost-performance |
+| Gaal Dornick | Foundation | Prompt engineering, guardrails |
+| The Mule | Foundation | Adversarial AI, inputs the model can't predict |
+| Bayta Darell | Foundation | Evaluation, golden datasets, regression |
+| Senku | Anime | Engineering first-principles, science |
+| Levi | Anime | Precision, zero-waste execution |
+| Spike | Anime | Chaos testing, unexpected interactions |
+| Holo | Anime | Economics, trade-offs, market dynamics |
+
+### Step 3 — The Ride (Éomer)
+
+Deploy agents in 3 waves:
+
+**Wave 1 — Vanguard (5-8 agents, parallel):**
+Domain leads for every relevant universe. These set the baseline analysis.
+
+**Wave 2 — Main Force (5-10 agents, parallel):**
+Supporting experts. Each gets Wave 1's findings as context so they build on (not duplicate) the leads' work.
+
+**Wave 3 — Adversarial (3-5 agents, parallel):**
+Challenge agents who specifically try to break what Waves 1-2 recommended:
+- **Deathstroke** (DC) — bypasses proposed defenses
+- **Maul** (Star Wars) — attacks proposed security
+- **The Mule** (Foundation) — adversarial AI testing
+- **Constantine** (DC) — finds cursed code in "clean" proposals
+- **Riker** (Star Trek) — challenges trade-offs ("Number One, does this hold up?")
+
+### Step 4 — The Council (Théoden + Gandalf)
+
+Synthesize all findings:
+1. **Deduplicate** — same finding from multiple agents → keep the most detailed, note agreement
+2. **Resolve conflicts** — when agents disagree, present both positions with reasoning
+3. **Preserve dissent** — if 8 agents agree and 1 disagrees, the dissent is noted (not suppressed)
+4. **Recommend** — unified recommendation with confidence level
+
+## Integration Points
+
+| Command | What `--muster` Does |
+|---|---|
+| `/architect --muster` | Full 9-universe architecture review (vs Star Trek bridge crew default) |
+| `/campaign --muster` | Per-mission full-roster deployment (expensive — use for critical missions only) |
+| `/build --muster` | Every build phase gets cross-universe review |
+| `/gauntlet --muster` | Synonym for `--infinity` (Gauntlet already has this concept) |
+
+## Intensity Spectrum
+
+```
+--fast        Standard agents, reduced passes (skip last 2 rounds/phases)
+(default)     Standard agents, full protocol
+--muster      Every viable agent, 3 waves, adversarial challenge
+--infinity    Every agent as own sub-process, 10 rounds (Gauntlet only)
+```
+
+## Cost Awareness
+
+The Muster launches 30-50 agent sub-processes. This consumes significant context. Use it when the decision justifies the investment — architecture choices, security-critical features, financial system design, launch preparation.
+
+For routine work, the standard agent roster is sufficient. The Muster is the heavy artillery, not the sidearm.

package/dist/docs/methods/PRD_GENERATOR.md

@@ -0,0 +1,186 @@
+# PRD GENERATOR — From Idea to Production-Ready PRD
+## System Protocol · Defined by: **Sisko** (Star Trek)
+
+## Purpose
+
+Use this prompt with Claude to generate a comprehensive PRD from a rough product idea. The output PRD can then be dropped into `/docs/PRD.md` and built by the team (Galadriel, Stark, Batman, Kenobi, Picard, Kusanagi) using the Build Protocol.
+
+---
+
+## Usage
+
+Paste the prompt below into a Claude conversation, followed by your product idea (as rough as 1-3 sentences). Claude will generate a full PRD.
+
+---
+
+## The Prompt
+
+```
+You are a senior product manager and systems architect. Your task is to take a rough product idea and produce a comprehensive, buildable Product Requirements Document (PRD).
+
+The PRD must be detailed enough that an AI coding agent can build the entire application from it without asking clarifying questions. Every section must be specific — no vague hand-waving.
+
+Produce the following sections. Start with a YAML frontmatter block, then the full PRD:
+
+## Frontmatter (REQUIRED — placed at top of document)
+```yaml
+name: "[project name]"
+type: "full-stack"  # full-stack | api-only | static-site | prototype
+framework: ""       # next.js | django | rails | express | etc.
+database: ""        # postgres | mysql | sqlite | mongodb | none
+cache: ""           # redis | none
+styling: ""         # tailwind | css-modules | styled-components | etc.
+auth: yes           # yes | no
+payments: none      # stripe | lemonsqueezy | none
+workers: no         # yes | no
+admin: no           # yes | no
+marketing: no       # yes | no
+email: none         # resend | sendgrid | ses | none
+deploy: "vps"       # vps | vercel | railway | cloudflare | static | docker
+```
+
+## 1. Product Vision
+- Name (suggest 2-3 if none given, pick the best)
+- One-liner (under 15 words)
+- What it does (2-3 sentences, mechanistic — not marketing)
+- Who it's for (specific customer profile)
+- Brand personality (3 adjectives + what it's NOT)
+
+## 2. System Architecture
+- High-level architecture diagram (ASCII)
+- Route structure (every URL)
+- Service boundaries
+- **External API integration research (REQUIRED):** If the product integrates with any external API (payment, analytics, landing pages, social, email, etc.), you MUST read the actual API documentation before writing data models, endpoint specifications, or integration types. If WebFetch fails (Cloudflare, auth-gated docs), ask the user for a local copy of the API docs. Never design against assumed API shapes — real APIs diverge from assumptions in naming conventions, endpoint structure, auth methods, and available features. The PRD's data models and API routes must reflect the real API surface, not a hypothetical one. (Field report #265: 6 hypothetical Kongo API endpoints were designed without reading the docs; none existed — the real API handled everything differently.)
+
+## 3. Tech Stack
+- Framework, styling, database, cache, auth, payments, email, storage, hosting
+- Rationale for each choice
+- All dependencies
+
+## 4. Core Features
+For each feature:
+- User flow (numbered steps)
+- Data model (entities, fields, relationships)
+- API endpoints (method, path, input, output, auth)
+- UI description (screens, states: loading/empty/error/success)
+- Edge cases
+
+## 5. Authentication & Accounts
+- Auth methods
+- User model (complete fields)
+- Roles and permissions
+- Session management
+- Password manager compatibility requirements
+
+## 6. Database Schema
+- Complete schema (Prisma format preferred)
+- All models, fields, types, relations, indexes, enums
+
+## 7. API Design
+- Every route with method, auth, input schema, output schema
+- Error response format
+- Rate limiting rules
+
+## 8. Tiers & Pricing (if applicable)
+- Feature comparison table
+- Pricing
+- What's gated and how enforcement works (client + server)
+
+## 9. Payment Processing (if applicable)
+- Provider and integration approach
+- Webhook events to handle
+- Subscription lifecycle
+
+## 10. Analytics & Tracking
+- Event taxonomy (every event with properties)
+- Key metrics and funnels
+
+## 11. Admin Dashboard (if applicable)
+- What the team sees and can do
+- Sections and data
+
+## 12. Email & Notifications
+- Every transactional email (trigger, subject, content summary)
+
+## 13. Security
+- Encryption (at rest, in transit)
+- Rate limiting
+- Input validation
+- CORS, CSRF, XSS prevention
+- File upload security
+- Secret management
+
+## 13.5 AI Architecture (conditional — if the product uses AI/LLM features)
+Ask the user: "Does your product use AI or LLM features? If yes: What models? What do they do (classify, generate, route, orchestrate)? What happens when the AI is wrong?" Generate a PRD section:
+
+## AI Architecture
+- **Provider:** [anthropic / openai / local / multi]
+- **Models:** [list with justification]
+- **AI Features:** [classification, generation, tool-use, routing, orchestration]
+- **Failure strategy:** [what happens when the AI fails]
+- **Eval strategy:** [how you'll measure quality]
+
+## 14. Brand Voice & Personality
+- How the product speaks
+- Example microcopy for: buttons, errors, empty states, confirmations, destructive actions
+- What tone to avoid
+
+## 15. Deployment & Infrastructure
+- Target hosting with specific setup
+- Process management
+- DNS/SSL
+- Backup strategy
+- Complete environment variable list
+
+## 16. Launch Sequence
+- Phased build plan (what gets built in what order)
+- Each phase has: scope, dependencies, and "done" criteria
+
+RULES:
+- Every number must be specific (not "many" or "several")
+- Every feature must have all states defined (loading, empty, error, success)
+- Every API endpoint must have input validation described
+- The schema must be complete — no "add more fields as needed"
+- Environment variables must be listed exhaustively
+- If you must assume something, state the assumption explicitly
+
+THE PRODUCT IDEA:
+```
+
+Then paste your idea below the prompt.
+
+---
+
+## Tips for Better PRDs
+
+1. **More input = better output.** Even rough notes, competitor links, or sketches help.
+2. **Name your customer.** "Seed-stage founders raising their first round" > "startups."
+3. **Name your stack if you have preferences.** Otherwise the generator picks sensible defaults.
+4. **Include pricing if you know it.** Revenue model shapes the architecture.
+5. **Include examples of products you admire.** Helps calibrate the voice and UX direction.
+
+---
+
+## PRD Evolution Log
+
+For complex projects that go through iterative `/architect --plan` refinement, add a PRD Evolution Log section at the bottom of the PRD:
+
+```markdown
+## PRD Evolution Log
+
+| Date | Change | Reason |
+|------|--------|--------|
+| YYYY-MM-DD | Initial PRD generated | Sisko's interview |
+| YYYY-MM-DD | Restructured phases: auth before payments | Dependency analysis (Picard) |
+| YYYY-MM-DD | Added historical validation phase | Strategy requires data proof before infra |
+```
+
+This section is optional for simple PRDs but recommended for any PRD that undergoes 3+ revision commits before building begins. The log captures *why* the PRD evolved — the git diff shows *what* changed but not the architectural reasoning. (Field report #126)
+
+## After Generating
+
+1. Review the PRD — fix anything that feels wrong
+2. Save it as `/docs/PRD.md` in your project
+3. Open Claude Code
+4. Say: "Build this project from the PRD"
+5. The Build Protocol will deploy Picard, Stark, Galadriel, and the rest in sequence