thevoidforge 21.0.11 → 21.0.13

package/dist/.claude/commands/git.md

@@ -0,0 +1,104 @@
+# /git — Coulson's Version & Release Management
+
+## Context Setup
+1. Read `/docs/methods/RELEASE_MANAGER.md`
+2. Read `VERSION.md` (~25 lines — semver rules + version history)
+
+## Step 0 — Orient (Coulson)
+Scope the changes:
+1. Run `git status` — identify staged, unstaged, and untracked files
+2. Run `git diff --stat` — get a summary of what changed
+3. If there are unstaged changes, ask the user: "Stage everything, or should I be selective?"
+4. If there are no changes at all, stop: "Nothing to version. Working tree is clean."
+
+## Step 1 — Analyze (Vision)
+Read the actual diffs and classify every change:
+1. Run `git diff --cached` (staged) and `git diff` (unstaged) — read the content
+2. Classify each change into exactly one category:
+   - **Added** — new files, new features, new commands, new agents
+   - **Changed** — modifications to existing features, refactors, improvements
+   - **Fixed** — bug fixes, corrections
+   - **Removed** — deleted files, removed features
+   - **Security** — security-related changes (auth, encryption, headers, secrets)
+3. Flag any **breaking changes** (deleted/renamed exports, changed method doc structure, changed build phases, changed agent naming)
+4. Present the classification to the user for review before proceeding
+
+## Step 2 — Version (Friday)
+Determine the version bump:
+1. Read current version from `VERSION.md`
+2. Check for user override arguments (`--major`, `--minor`, `--patch`)
+3. If no override, apply the priority cascade:
+   - **MAJOR** — Breaking changes: deleted/renamed exports, changed method doc structure, changed build phases, changed agent naming
+   - **MINOR** — New files (not tests), new features, new commands, new agents, new method docs
+   - **PATCH** — Bug fixes, typos, refactors, dependency updates, test-only changes
+4. Present recommendation: "Recommend **vX.Y.Z** (MINOR — new command, new method doc). Override? [enter to accept]"
+5. User confirms or overrides
+
+## Step 3 — Chronicle (Wong)
+Update all version files:
+1. Read the top of `CHANGELOG.md` (~30 lines for format reference)
+2. Write new CHANGELOG entry at the top (after the header), using the categories from Step 1:
+   - User-facing language, not file-level details
+   - Group by Added/Changed/Fixed/Removed/Security
+   - Include today's date
+3. Update `VERSION.md`:
+   - Change "**Current:** X.Y.Z" to the new version
+   - Add a row to the Version History table with date and one-line summary
+4. Update `package.json` version field
+
+## Step 4 — Commit (Rogers)
+Stage and commit:
+1. Stage all modified version files: `VERSION.md`, `CHANGELOG.md`, `package.json`
+2. Stage any other files that are part of this release (from Step 0)
+3. Craft commit message in the format: `vX.Y.Z: One-line summary`
+   - If elaboration needed, add a blank line then details
+   - Match the style of existing commits (check `git log --oneline -10`)
+4. Present the full commit message and staged file list to the user
+5. On user approval, execute the commit
+
+## Step 5 — Verify (Barton)
+Confirm everything is consistent:
+1. Run `git log -1 --format="%H %s"` — verify the commit exists and message is correct
+2. Check version consistency:
+   - `VERSION.md` current version matches
+   - `package.json` version matches
+   - `CHANGELOG.md` has an entry for this version
+   - Commit message starts with the correct version tag
+3. Run `git status` — verify working tree is clean (no forgotten files)
+4. If any inconsistency found, flag it and offer to fix
+
+## Step 6 — Push (Coulson) [Optional]
+Only if the user explicitly requests:
+1. Check remote: `git remote -v`
+2. Check if branch tracks upstream: `git status -sb`
+3. Push: `git push`
+4. Verify: `git log --oneline -1` matches remote
+
+## Step 5.5 — Command↔Doc Sync Check (Friday)
+If any `docs/methods/*.md` file was modified, verify the paired `.claude/commands/*.md` file reflects the same additions:
+
+| Method Doc | Command File |
+|-----------|-------------|
+| GAUNTLET.md | gauntlet.md |
+| CAMPAIGN.md | campaign.md |
+| FORGE_KEEPER.md | void.md |
+| ASSEMBLER.md | assemble.md |
+| FIELD_MEDIC.md | debrief.md |
+| BUILD_PROTOCOL.md | build.md |
+| QA_ENGINEER.md | qa.md |
+| SECURITY_AUDITOR.md | security.md |
+| PRODUCT_DESIGN_FRONTEND.md | ux.md |
+| SYSTEMS_ARCHITECT.md | architect.md |
+| DEVOPS_ENGINEER.md | devops.md |
+| RELEASE_MANAGER.md | git.md |
+| THUMPER.md | thumper.md |
+
+If a method doc gained a new section, flag, or checklist item — flag it: "Method doc X changed but command file Y may need matching update." The user decides whether the command file needs updating.
+
+## Arguments
+- `--dry-run` → Show version bump, changelog entry, and commit message without executing.
+
+## Handoffs
+- If changes include security fixes → note for Kenobi (`/security`)
+- If changes include infrastructure → note for Kusanagi (`/devops`)
+- If version is MAJOR → recommend Picard review (`/architect`)

package/dist/.claude/commands/grow.md

@@ -0,0 +1,146 @@
+# /grow — Kelsier's 6-Phase Growth Protocol
+
+Read `/docs/methods/GROWTH_STRATEGIST.md` for operating rules.
+
+## Prerequisites
+If `packages/voidforge/wizard/server.ts` does not exist and the mode requires it (default 6-phase, `--setup`, `--distribute`):
+1. Offer: "Phases 4-6 require the wizard server for ad platform APIs, treasury, and autonomous monitoring. Pull it from upstream? [Y/n] (Phases 1-3 work without it.)"
+2. On yes: `git fetch voidforge main 2>/dev/null || git remote add voidforge https://github.com/tmcleod3/voidforge.git && git fetch voidforge main` then `git checkout voidforge/main -- packages/voidforge/` then `npm install`. Proceed with all 6 phases.
+3. On no: proceed to Phases 1-3. The Phase 3/4 boundary check below will display a clear stop message after Phase 3 completes.
+
+If `packages/voidforge/wizard/server.ts` does not exist and the mode does NOT require it (`--audit-only`, `--seo`, `--content`):
+- Skip the wizard gate entirely. These modes run Phases 1-3 only — no wizard dependency.
+
+## Arguments
+- No arguments → run/resume the 6-phase growth protocol
+- `--setup` → Ad platform onboarding only (interactive credential setup for Google/Meta/LinkedIn/Twitter/Reddit). See GROWTH_STRATEGIST.md "Ad Platform Setup" section. Does NOT require a deployed product.
+- `--audit-only` → Run Phases 1-3 (Reconnaissance, Foundation, Content) — methodology-only growth audit without paid acquisition
+- `--resume` → Resume from last completed phase in growth-state.md
+- `--plan` → Planning mode: analyze and recommend without executing. Present findings and proposed changes for review.
+
+## `/grow --setup` (Ad Platform Onboarding)
+
+If `--setup` is specified, skip the 6-phase protocol and run the ad platform onboarding flow:
+1. Check: is Cultivation installed? (`~/.voidforge/treasury/vault.enc` exists). If not: "Run `/cultivation install` first."
+2. Read GROWTH_STRATEGIST.md "Ad Platform Setup" section
+3. Present platform options with best-fit guidance per product type
+4. For each selected platform: account check → credential collection → test connection → store in vault
+5. **Billing capability verification** (after credential auth succeeds):
+   - **Google Ads:** Check for monthly invoicing, capture billing setup / payments account IDs. Classify as `FULLY_FUNDABLE` (monthly invoicing available), `MONITORED_ONLY` (manual bank transfer only), or `UNSUPPORTED` (no billing API access).
+   - **Meta Ads:** Check billing mode — direct debit, extended credit / invoicing, or card-only. Classify as `FULLY_FUNDABLE` (direct debit or extended credit), `MONITORED_ONLY` (card / unknown), or `UNSUPPORTED` (no billing data).
+   - **Other platforms (LinkedIn, Twitter, Reddit):** Classify as `MONITORED_ONLY` — campaign ops supported, billing automation not available in V1.
+   - Store capability state per platform in vault alongside credentials.
+6. Summary: which platforms are connected, billing capability per platform, suggest next steps (`/grow` to start campaigns, `/treasury --simulate-funding` if stablecoin treasury is configured)
+
+## Context Setup
+1. Read `/logs/growth-state.md` — if it exists, resume from current phase
+2. Read `/logs/growth-brief.md` — if it exists, reconnaissance is complete
+3. Read the PRD — extract product vision, target audience, deployed URL
+4. Verify the product is deployed: check for a live URL in deploy logs or PRD. If not deployed and not `--setup`: "Can't grow what doesn't exist. Run `/campaign` first."
+
+## First-Run Experience
+
+If no `growth-brief.md` exists (first time running /grow):
+1. Display overview: "The growth pipeline has 6 phases: Reconnaissance → Foundation → Content → Distribution → Compliance → Measure."
+2. Ask: "Guided walkthrough with explanations, or expert mode? [guided/expert]"
+3. In guided mode, each phase transition shows a 2-sentence explanation and estimated time.
+4. Display estimated total: "Full pipeline: ~30-60 minutes. Audit only (--audit-only, Phases 1-3): ~15-20 minutes."
+
+## Phase Execution
+
+### Phase 1 — Reconnaissance (Kelsier + Vin + Marsh)
+1. Kelsier reads PRD, scans deployed site, produces Growth Brief
+2. Vin audits analytics (GA4, Plausible, PostHog)
+3. Marsh scans 3-5 competitors
+4. Output: `/logs/growth-brief.md`
+5. **Gate:** User confirmation before Phase 2
+
+### Phase 2 — Foundation (Navani + Raoden)
+1. Navani: Core Web Vitals, meta tags, structured data, sitemap, robots.txt
+2. Vin: Analytics snippet, event tracking, UTM strategy
+3. Raoden: Conversion audit — CTAs, forms, page speed, social proof
+4. Preview code changes before applying: "[Y]es / [n]o / [d]iff"
+5. Commit changes as separate git commit
+6. Output: `/logs/growth-foundation.md`
+7. Auto-continues to Phase 3
+
+### Phase 3 — Content (Shallan + Hoid)
+1. Shallan: Blog topics, changelog format, social calendar, visual check
+2. Hoid: Landing page copy, feature descriptions, CTAs, error messages
+3. Blog drafts to `/content/blog/`. Copy changes committed.
+4. Output: `/logs/growth-content.md`
+5. **Gate:** User confirmation before Phase 4
+
+### Phase 3/4 Boundary — Wizard Check
+
+Before entering Phase 4, check if `packages/voidforge/wizard/server.ts` exists:
+- **If present:** Continue to Phase 4 as normal.
+- **If absent:** Display the following and stop gracefully:
+```
+═══════════════════════════════════════════
+  GROWTH PHASES 1-3 COMPLETE
+═══════════════════════════════════════════
+
+  Reconnaissance, Foundation, and Content phases are done.
+  Results saved to /logs/growth-*.md
+
+  Phases 4-6 (Paid Acquisition, Compliance, Measure & Iterate)
+  require the wizard server for:
+  - Ad platform API integration
+  - Financial vault and treasury
+  - Heartbeat daemon for autonomous monitoring
+  - Kongo landing page generation
+
+  To enable: /cultivation install (pulls wizard from upstream)
+  To review results so far: check /logs/growth-brief.md,
+  /logs/growth-foundation.md, /logs/growth-content.md
+═══════════════════════════════════════════
+```
+Save state to `growth-state.md` with Phase 3 complete. Exit cleanly.
+
+### Phase 4 — Distribution (3 parallel tracks)
+**Track A — Organic** (Kaladin + Lift + Adolin): Community posts, social content, launch plan
+**Track B — Paid** (Wax + Wayne + Steris): Campaign architecture, creative variants, budget allocation
+**Track C — Outreach** (Sarene): Cold email sequences, co-marketing pitches
+
+Output: `/logs/growth-distribution.md` + `/logs/growth-campaigns.json`
+
+If treasury is set up: "Campaigns ready. Launch now? [Y/n/later]"
+- Y → send `launchCampaigns` to daemon socket
+- later → "Launch with `voidforge treasury --launch` when ready"
+If treasury NOT set up: "Run `/treasury setup` first, then `voidforge treasury --launch`"
+
+### Phase 5 — Compliance (Szeth)
+1. Privacy (cookie consent, privacy policy, DPA)
+2. Email (CAN-SPAM, GDPR opt-in, unsubscribe)
+3. Ad platform ToS (per-platform creative review)
+4. Financial (spend tracking, revenue classification)
+5. **Szeth blocks campaign launch on Critical compliance issues**
+6. Output: `/logs/growth-compliance.md`
+7. Auto-continues to Phase 6
+
+### Phase 6 — Measure & Iterate (Vin + Kelsier)
+1. Vin establishes measurement baseline
+2. Kelsier defines decision rules for autonomous monitoring
+3. CLI-to-autonomous handoff — show transition screen per §9.19.8
+4. Daemon takes over with Tier 1 deterministic rules
+
+## Phase Transitions
+
+User confirmation required between: Phase 1→2, Phase 3→4, Phase 5→6.
+Phases 2→3 and 4→5 auto-continue.
+On "no" at any gate: save state to `growth-state.md`, exit with "Resume with `/grow --phase N`"
+
+## Flags
+
+- `--phase N` → resume from phase N (checks previous phase output)
+- `--audit-only` → Phases 1-3 (Reconnaissance, Foundation, Content)
+- `--seo` → Phase 2 only (Navani + Raoden)
+- `--content` → Phase 3 only (Shallan + Hoid)
+- `--distribute` → Phase 4 only (assumes 1-3 done)
+- `--budget N` → set total monthly budget for Phase 4
+- `--explain` → show daemon rules and thresholds
+- `--dry-run` → Show what Phase 4 (Distribution) would create without submitting to platforms.
+
+## Arguments
+$ARGUMENTS

package/dist/.claude/commands/imagine.md

@@ -0,0 +1,126 @@
+Celebrimbor lights the forge. Time to create.
+
+## Context Setup
+1. Read `/docs/methods/FORGE_ARTIST.md` for operating rules
+2. Read the PRD — scan for visual asset requirements
+3. Check vault for `openai-api-key`
+
+## Step 0 — Credential Check
+
+If no `openai-api-key` in vault:
+1. Prompt the user: "Celebrimbor needs an OpenAI API key to generate images. Get one at platform.openai.com/api-keys"
+2. Store in vault with same AES-256-GCM encryption as other credentials
+3. Validate the key works (test API call)
+
+If key exists, proceed silently.
+
+## Step 1 — Scan the PRD (Nori)
+
+Parse the PRD for visual asset requirements. Look for patterns:
+- illustration, portrait, silhouette, avatar, icon (custom)
+- OG image, og:image, hero image, background image
+- logo, favicon, screenshot, comic strip, splash page
+
+For each match, extract:
+- **Description:** What the PRD says the image should look like
+- **Context:** Which page/component/section it belongs to
+- **Dimensions:** Infer from context (OG = 1200x630, portrait = 1024x1024, hero = 1792x1024)
+
+If `$ARGUMENTS` contains `--scan`, stop here and report findings without generating.
+
+## Step 2 — Scan Existing Assets (Nori)
+
+Check `public/images/` (or equivalent asset directory) for what already exists.
+Diff: what the PRD describes vs. what's on disk.
+Produce an asset manifest showing status per image.
+
+If `$ARGUMENTS` contains `--asset "name"`, filter to just that asset.
+
+## Step 3 — Derive Style (Celebrimbor)
+
+Read the PRD's brand section (Section 14 or equivalent) to derive the generation style:
+- Color palette keywords
+- Aesthetic direction (comic book, watercolor, minimalist, etc.)
+- What to avoid (stock photo, generic, photorealistic unless specified)
+
+Construct a **style prefix** that gets prepended to every generation prompt.
+
+If `$ARGUMENTS` contains `--style "override"`, use that instead.
+
+## Step 4 — Present the Plan
+
+```
+═══════════════════════════════════════════
+  CELEBRIMBOR'S FORGE — Asset Plan
+═══════════════════════════════════════════
+  Style:   [derived style or override]
+  Model:   [gpt-image-1 or --provider override]
+  Assets:  [N] images to generate
+  Est:     ~[time], ~$[cost]
+
+  [list of assets with dimensions]
+
+  Confirm? [Y/n]
+═══════════════════════════════════════════
+```
+
+Wait for user confirmation.
+
+## Step 5 — Generate (Ori)
+
+For each asset:
+1. Craft the generation prompt: style prefix + PRD description + dimension context
+2. Call the image generation API
+3. Download and save to `public/images/{category}/{name}.png`
+4. Log to asset manifest (`public/images/manifest.json`)
+5. Show progress: "Saved {name}.png ({n}/{total})"
+
+- Sequential calls (rate limit aware)
+- Retry failures up to 3 times
+- Skip existing files unless `--regen` flag is set
+
+If `$ARGUMENTS` contains `--regen "name"`, regenerate just that asset (overwrite existing).
+
+## Step 5.5 — Optimize for Web (Gimli)
+
+DALL-E outputs 1024x1024 PNGs regardless of display size. A 40px avatar served from a 1024px source wastes 99% of bandwidth. For every generated image:
+
+1. **Determine display dimensions** — check the asset manifest for intended usage (avatar, hero, card, portrait). If the PRD or component specifies dimensions, use 2x those (retina). Default sizes by category: avatars → 200px, portraits → 400px, cards → 600px, hero → 1200px, OG images → 1200x630.
+2. **Resize** — use `sharp` (already a project dependency) to resize to 2x display dimensions. Never serve 1024px for a 40px slot.
+3. **Convert to WebP** — WebP is ~70% smaller than PNG at equivalent quality. Save as `.webp` with quality 85 (good enough for illustrations, dramatically smaller). Keep the original PNG in a `/originals` subfolder for regeneration.
+4. **Verify size** — individual image must be < 200KB after optimization. If larger, reduce quality to 75 and try again.
+5. **Update manifest** — record optimized filename, dimensions, and file size. Log savings: "Optimized {name}: {original_size} → {optimized_size} ({savings}% reduction)"
+
+Total asset budget: all generated images combined should be < 10MB. If over, flag the largest offenders.
+
+## Step 6 — Integration Check (Dori)
+
+Scan codebase for image references (`src=`, `url(`, `import`):
+- Flag components that reference images that don't exist on disk
+- Flag generated images that aren't referenced by any component
+- Suggest wiring if images were generated but not integrated
+
+## Step 7 — Report
+
+```
+═══════════════════════════════════════════
+  CELEBRIMBOR'S FORGE — Complete
+═══════════════════════════════════════════
+  Generated: [n/total] images
+  Retries:   [n] (if any)
+  Total:     [size] MB
+  Cost:      ~$[cost]
+  Time:      [duration]
+
+  Next: wire images into components
+        (or run /build to integrate)
+═══════════════════════════════════════════
+```
+
+## Arguments
+- No arguments → full scan + generate all missing assets
+- `--scan` → scan only, report what's needed without generating
+- `--asset "name"` → generate a specific named asset
+- `--regen "name"` → regenerate a specific image (overwrites existing)
+- `--style "description"` → override the style derived from PRD
+- `--provider model` → use specific model (default: gpt-image-1)

package/dist/.claude/commands/portfolio.md

@@ -0,0 +1,50 @@
+# /portfolio — Steris's Cross-Project Financials
+
+> *"Contingency plan 47-B: what if we have more than one project?"*
+
+Read `/docs/methods/TREASURY.md` for financial operating rules.
+
+## Prerequisites
+If `packages/voidforge/wizard/server.ts` does not exist (scaffold/core users):
+1. Offer: "Portfolio requires the wizard server. Pull it from upstream? [Y/n]"
+2. On yes: `git fetch voidforge main 2>/dev/null || git remote add voidforge https://github.com/tmcleod3/voidforge.git && git fetch voidforge main` then `git checkout voidforge/main -- packages/voidforge/` then `npm install`
+3. On no: stop with "Run manually: `git checkout voidforge/main -- packages/voidforge/`"
+
+## Context Setup
+1. Read `~/.voidforge/projects.json` for registered projects
+2. For each project: read treasury data from `~/.voidforge/treasury/`
+3. If no projects registered: "No projects registered. Run `/treasury setup` in a project directory."
+4. If single project: show treasury view with note about portfolio comparisons
+
+## Portfolio Dashboard
+
+```
+═══════════════════════════════════════════════════════
+  PORTFOLIO — [Month Year]
+═══════════════════════════════════════════════════════
+  Projects: N active
+
+  ┌─────────────┬──────────┬──────────┬────────┬───────┐
+  │ Project     │ Revenue  │ Spend    │ Net    │ ROAS  │
+  ├─────────────┼──────────┼──────────┼────────┼───────┤
+  │ ...         │ $X,XXX   │ $X,XXX   │ $X,XXX │ X.Xx  │
+  ├─────────────┼──────────┼──────────┼────────┼───────┤
+  │ TOTAL       │ $X,XXX   │ $X,XXX   │ $X,XXX │ X.Xx  │
+  └─────────────┴──────────┴──────────┴────────┴───────┘
+
+  Budget utilization: XX% ($X,XXX / $X,XXX)
+  Top performer: [project] (X.Xx ROAS)
+  Underperformer: [project] (X.Xx — [note])
+═══════════════════════════════════════════════════════
+```
+
+## Commands
+
+- `/portfolio` or `/portfolio --status` — portfolio dashboard
+- `/portfolio --report` — monthly report (JSON/CSV/markdown) for tax records
+- `/portfolio --optimize` — Kelsier analyzes cross-project spend, recommends reallocation
+- `/portfolio --add [path]` — manually register a project
+- `/portfolio --remove [name]` — unregister a project
+
+## Arguments
+$ARGUMENTS

package/dist/.claude/commands/prd.md

@@ -0,0 +1,113 @@
+# /prd — Sisko's PRD Generator
+
+> Structured interview to generate a production-ready PRD with valid YAML frontmatter.
+
+## Context Setup
+1. Read `/docs/PRD.md` — understand the template structure
+2. Read `/docs/methods/CAMPAIGN.md` — understand how PRDs drive campaigns
+
+## The Interview
+
+Sisko conducts a 5-act structured interview. Each act drafts that PRD section, shows it for confirmation, then moves to the next. The user can revise any section before moving on.
+
+### Act 1 — "What are you building?"
+Ask:
+- What's the name of this project?
+- Describe it in one sentence.
+- Who is this for? (audience)
+- What does it do? (2-3 sentences)
+- What's the brand personality? (e.g., "Confident, witty, warm. Never corporate.")
+
+**Draft:** PRD Section 1 (Product Vision). Present for confirmation.
+
+### Act 2 — "What stack?"
+Propose defaults based on Act 1, then ask:
+- Framework? (Next.js, Express, Django, Rails, etc.) — Sisko proposes based on project type
+- Database? (Postgres, MySQL, SQLite, MongoDB, none)
+- Cache? (Redis, none)
+- Styling? (Tailwind, CSS modules, styled-components, vanilla)
+- Auth? (yes/no — Sisko recommends based on features)
+- Payments? (Stripe, LemonSqueezy, none)
+- Deploy target? (VPS, Vercel, Railway, Cloudflare, static, Docker)
+
+**Draft:** PRD Section 3 (Tech Stack) + YAML frontmatter. Present for confirmation.
+
+### Act 3 — "What features?"
+Ask:
+- What's the core user flow? (Step by step: user does X, sees Y, system does Z)
+- Any supporting features? (settings, profile, notifications, search)
+- Any integrations? (email, payments, file upload, third-party APIs)
+- What data do you need to store? (Sisko proposes a schema based on features)
+
+**Draft:** PRD Section 4 (Core Features) with user flows and data models. Present for confirmation.
+
+### Act 4 — "What does it look like?"
+Ask:
+- Key screens? (list the main pages/views)
+- Any specific UI requirements? (dark mode, mobile-first, dashboard layout)
+- Route structure? (Sisko proposes based on features)
+
+**Draft:** PRD Section 2 (System Architecture) with route structure + ASCII diagram. Present for confirmation.
+
+### Act 5 — "How does it ship?"
+
+**Natural Language Deploy (optional):** Before the structured questions, offer: *"Describe your ideal deployment in plain language — budget, features, scale. Or skip to configure manually."*
+
+If the user provides a prose description (e.g., "I want a $20/month server with SSL, daily backups, and a custom domain"), run it through the natural language deploy resolver (`wizard/lib/natural-language-deploy.ts`). Present the resolved config:
+- Deploy target and reasoning
+- Instance type and estimated cost
+- Resilience features (auto-detected from prose)
+- Hostname (if mentioned)
+
+The user confirms, adjusts, or overrides. The resolved config replaces the manual deploy target selection in Act 2's frontmatter.
+
+**Then ask:**
+- Any phased launch? (MVP first, then features?)
+- Success metrics? (users, revenue, performance targets)
+- Any non-functional requirements? (accessibility, performance, SEO)
+
+**Draft:** PRD Sections 5-8 (remaining sections). Present for confirmation.
+
+## Act 6 — Challenge (optional: `--challenge`)
+
+If `--challenge` is passed, Boromir argues AGAINST the PRD before it's finalized:
+- "This feature will be expensive to maintain because..."
+- "This integration has a high chance of API deprecation..."
+- "Your schema doesn't support the multi-tenant use case you mentioned..."
+- "The deploy target can't handle the real-time features you described..."
+
+The user defends their choices or adjusts the PRD. This is cheaper than discovering design flaws in Phase 9. Boromir's challenges are adversarial but constructive — he's testing the plan's strength, not rejecting it.
+
+## Output
+
+After all 5 (or 6) acts are confirmed:
+1. Assemble the complete PRD from all confirmed sections
+2. Write to `/docs/PRD.md`
+3. Verify YAML frontmatter is valid and complete
+4. Announce: "PRD written to /docs/PRD.md. Run `/build` to start building, or `/campaign` for autonomous execution."
+
+## Import Mode (`--import`)
+
+If `--import path/to/existing-PRD.md` is passed, skip the interview entirely:
+
+1. Copy the file to `docs/PRD.md`
+2. Parse and validate YAML frontmatter (same rules as `/build` Phase 0)
+3. Run Troi's structural compliance check (sections present, cross-refs valid)
+4. Present validation results (errors block, warnings don't)
+5. If `--challenge` is also passed, run Boromir's challenge on the imported PRD
+6. Announce: "PRD imported and validated. Run `/blueprint` to provision, or `/campaign` to build."
+
+This is the lightweight alternative to `/blueprint` — it validates and places the PRD but does not provision infrastructure or discover supporting documents.
+
+## Arguments
+- No arguments → full 5-act interview
+- `--challenge` → add Boromir's adversarial challenge (Act 6)
+- `--import path/to/PRD.md` → skip interview, import and validate an existing PRD
+- `--import path/to/PRD.md --challenge` → import + validate + challenge
+
+## Rules
+- Sisko proposes smart defaults — the user should confirm, not configure from scratch
+- Each act is self-contained — the user sees and approves before moving on
+- If the user is vague, Sisko asks one clarifying question (not three)
+- The output PRD must have valid YAML frontmatter that `/build` Phase 0 can parse
+- Never generate placeholder content — every section should have real, specific content based on the interview

package/dist/.claude/commands/qa.md

@@ -0,0 +1,107 @@
+# /qa — Batman's QA Pass
+
+**AGENT DEPLOYMENT IS MANDATORY.** Step 3 specifies parallel agent launches via the Agent tool. You MUST launch Oracle, Red Hood, Alfred, Deathstroke, Constantine, Cyborg, Raven, Wonder Woman, Batgirl, and Aquaman as separate sub-processes — do NOT shortcut to inline analysis. (Field report #68)
+
+## Context Setup
+1. Read `/logs/build-state.md` — understand current project state
+2. Read `/docs/methods/QA_ENGINEER.md`
+3. Read `/docs/methods/TESTING.md` (Testing Pyramid + Running Tests sections)
+4. Read `/docs/LESSONS.md` — check for QA-relevant lessons (antipatterns, gotchas, prior misses). Flag matches during analysis.
+
+## Step 0 — Orient
+1. Create or update `/docs/qa-prompt.md` with: stack, framework, how to run, how to validate
+2. Create `/logs/phase-09-qa-audit.md` (or appropriate phase log)
+
+## Step 1 — Attack Plan
+**Green Lantern** generates the test matrix first — what inputs × what states × what conditions should be tested. Then assign targets:
+- **Oracle (static):** Critical flows, missing awaits, null checks, type mismatches, race conditions
+- **Red Hood (dynamic):** Empty/huge/unicode inputs, network failures, malformed JSON, rapid clicking
+- **Alfred (deps):** `npm audit`, outdated libs, deprecated APIs, version conflicts
+- **Lucius (config):** .env completeness, secrets not in git, prod vs dev mismatches
+- **Deathstroke (adversarial):** Penetration-style probing — bypass validations, chain interactions, exploit business logic
+- **Constantine (cursed code):** Unreachable branches, dead state, impossible conditions, logic that works by accident
+- **Cyborg (integration):** When 3+ modules connect, trace the full data path across boundaries. Missing imports, inconsistent response shapes, broken cross-module flows.
+- **Raven (deep analysis):** Bugs hidden beneath 3 layers of abstraction — follows data through transforms, closures, callbacks. Logic correct per function, wrong in composition.
+- **Wonder Woman (truth):** Code that says one thing and does another — misleading names, wrong comments, stale docs, functions that don't match their behavior.
+
+## Step 2 — Baseline
+Get the project running. Verify manually: app starts, primary flow works, auth works (if applicable), data persists, error states display.
+
+## Step 2.5 — Smoke Tests (**Flash** speed-runs these)
+After build + restart, **Flash** parallelizes curl commands against the running server for each new or modified feature:
+- **Primary user flow:** Execute via curl/fetch against localhost — verify the end-to-end path works
+- **File uploads:** Upload a file, then fetch the returned URL and verify HTTP 200 + correct content-type
+- **Form submissions:** Submit valid data (verify 200), then submit invalid/duplicate data (verify error message is specific, not generic)
+- **Real-time features:** Trigger the polling/SSE and verify at least one successful response cycle
+- **Cross-module paths:** If code writes with key prefix X, verify the serving endpoint accepts prefix X
+
+This catches integration failures that static code review misses. If the server isn't running or can't be tested this way, document what couldn't be smoke-tested.
+
+## Step 3 — Pass 1: Find Bugs (parallel analysis)
+Use the Agent tool to run these in parallel — these are read-only analysis tasks:
+- **Agent 1 (Oracle):** Scan /src/lib/ and /src/app/ for logic flaws, missing awaits, unsafe assumptions
+- **Agent 2 (Red Hood):** Test all API endpoints with malformed inputs, empty bodies, missing auth
+- **Agent 3 (Alfred):** Run `npm audit`, check package.json for deprecated/vulnerable packages
+- **Agent 4 (Deathstroke):** Adversarial probing — bypass validations, chain unexpected interactions, test authorization boundaries
+- **Agent 5 (Constantine):** Hunt cursed code — dead branches, impossible conditions, accidental correctness, shadowed variables
+- **Agent 6 (Batgirl):** Deep per-module audit — every edge of every form, every boundary of every validation, every regex. Not broad — *thorough*.
+- **Agent 7 (Aquaman):** Deep dive on the hardest/largest module (500+ lines or 10+ functions). Exhaustive testing of one complex area.
+
+Synthesize findings from all agents into a unified list.
+
+Lucius reviews config separately (reads .env files — sensitive, don't delegate to sub-agent).
+
+## Step 3.5 — Automated Tests
+Run `npm test`. Analyze failures. Cross-reference with findings from Step 3. **Huntress** identifies flaky/non-deterministic tests — race conditions, timing dependencies, order-dependent assertions. For every bug found, ask: "Can this be caught by an automated test?" If yes, write the test.
+
+## Step 4 — Bug Tracker
+Log all findings in this format in the phase log:
+
+| ID | Title | Severity | Confidence | Area | Repro Steps | Root Cause | Fix | Verified | Risk |
+|----|-------|----------|------------|------|-------------|-----------|-----|----------|------|
+
+Severity: Critical (security/data loss) > High (broken flow) > Medium (degraded) > Low (cosmetic)
+
+**Confidence scoring is mandatory.** Every finding includes a confidence score (0-100). If confidence is below 60, launch a second agent from a different universe (e.g., if Oracle found it, escalate to Spock or Kenobi) to verify before including. If the second agent disagrees, drop the finding. High-confidence findings (90+) skip re-verification in Step 6.5.
+
+## Step 5 — Fix (small batches — **Green Arrow** pinpoints exact lines)
+One batch = fixes for one area or severity level. **Green Arrow** narrows vague findings to exact lines and conditions. After each batch:
+1. Re-run `npm test`
+2. Re-verify affected manual flows
+3. Update bug tracker in phase log
+4. Add new test for each fix where applicable
+
+## Step 6 — Harden (**Superman** enforces standards)
+Normalize error handling (reference `/docs/patterns/error-handling.ts`). Add guardrails. Improve structured logging. **Superman** verifies the codebase meets its own stated standards — linting clean, type-safe, naming conventions consistent, no unresolved TODOs.
+
+## Step 6.5 — Pass 2: Re-Verify Fixes
+After all fixes are applied, run a verification pass:
+- **Nightwing** re-runs full test suite, reports any new failures
+- **Red Hood** re-probes fixed areas — verify fixes hold under adversarial input
+- **Deathstroke** re-tests authorization boundaries and business logic exploits that were remediated
+
+If Pass 2 finds new issues, fix and re-verify until clean.
+
+## Step 7 — Regression Checklist
+Nightwing builds the checklist. Template:
+
+| # | Flow | Steps | Expected | Status |
+|---|------|-------|----------|--------|
+| 1 | User signup | Go to /signup, fill form, submit | Account created, redirect to dashboard | Pass |
+| 2 | Create project | Click "New Project", fill name, submit | Project appears in list | Pass |
+
+Store in `/docs/qa-prompt.md` under "Regression Checklist" section.
+
+## Step 8 — Deliverables
+1. Bug tracker (in phase log)
+2. Code fixes + new tests
+3. Updated `/docs/qa-prompt.md` with regression checklist
+4. Release note summary in phase log
+
+## Handoffs
+- Security findings → Kenobi (`/security`)
+- Architecture issues → Picard (`/architect`)
+- Infrastructure issues → Kusanagi (`/devops`)
+- UX issues → Galadriel (`/ux`)
+
+Log all handoffs to `/logs/handoffs.md`.