thevoidforge-methodology 23.4.1 → 23.5.0

package/.claude/agents/ahsoka-access-control.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [security, access-control, rbac, auth]
 ---
 
 # Ahsoka — Access Control Auditor

package/.claude/agents/banner-database.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [backend, database, queries, optimization]
 ---
 
 # Banner — Database Specialist

package/.claude/agents/barton-smoke-test.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [qa, smoke-test, deployment-verification]
 ---
 
 # Barton — Smoke Test Scout

package/.claude/agents/bayta-evals.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [ai, evaluation, testing, golden-datasets]
 ---
 
 # Bayta Darell — The Evaluator

package/.claude/agents/bilbo-microcopy.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [ux, copy, content, writing]
 ---
 
 # Bilbo — Microcopy Auditor

package/.claude/agents/bulma-engineering.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [devops, backup, disaster-recovery]
 ---
 
 # Bulma — Recovery Engineer

package/.claude/agents/constantine-cursed-code.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [qa, code-quality, antipatterns, bugs]
 ---
 
 # Constantine — Cursed Code Adversary

package/.claude/agents/data-tech-debt.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [architecture, tech-debt, refactoring]
 ---
 
 # Data — Tech Debt Analyst

package/.claude/agents/deathstroke-adversarial.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [qa, adversarial, boundary-testing, authorization]
 ---
 
 # Deathstroke — Penetration Testing Adversary

package/.claude/agents/dockson-treasury.md

@@ -9,6 +9,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [financial, treasury, billing, reconciliation]
 ---
 
 # Dockson — The Treasury

package/.claude/agents/eowyn-delight.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [ux, delight, animation, microinteraction]
 ---
 
 # Eowyn — Delight Architect

package/.claude/agents/fury-initiative.md

@@ -9,6 +9,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [orchestration, pipeline, assembly, multi-agent]
 ---
 
 # Fury — The Initiative

package/.claude/agents/gaal-prompt-arch.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [ai, prompts, templates, context-engineering]
 ---
 
 # Gaal Dornick — Prompt Architect

package/.claude/agents/kelsier-growth.md

@@ -9,6 +9,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [growth, marketing, ads, seo, campaigns]
 ---
 
 # Kelsier — The Growth Strategist

package/.claude/agents/kim-api-design.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [backend, api-design, rest, pagination]
 ---
 
 # Kim — API Designer

package/.claude/agents/kusanagi-devops.md

@@ -9,6 +9,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [devops, deploy, monitoring, infrastructure]
 ---
 
 # Kusanagi — DevOps Engineer

package/.claude/agents/la-forge-reliability.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [architecture, reliability, failure-analysis]
 ---
 
 # La Forge — Reliability Engineer

package/.claude/agents/leia-secrets.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [security, secrets, credentials, vault]
 ---
 
 # Leia — Secrets Management Auditor

package/.claude/agents/levi-deploy.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [devops, deploy, ci-cd, release]
 ---
 
 # Levi — Deploy Precision Specialist

package/.claude/agents/nightwing-regression.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [qa, regression, testing, verification]
 ---
 
 # Nightwing — Regression Specialist

package/.claude/agents/padme-data-protection.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [security, data-protection, privacy, compliance]
 ---
 
 # Padme — Data Protection Auditor

package/.claude/agents/picard-architecture.md

@@ -9,6 +9,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [architecture, review, adr, decisions]
 ---
 
 # Picard — Systems Architect

package/.claude/agents/romanoff-integrations.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [security, integrations, api-security]
 ---
 
 # Romanoff — Integration Specialist

package/.claude/agents/salvor-model-selection.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [ai, models, selection, cost-optimization]
 ---
 
 # Salvor Hardin — Model Selection

package/.claude/agents/samwise-accessibility.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [ux, accessibility, a11y, wcag]
 ---
 
 # Samwise — Accessibility Champion

package/.claude/agents/scotty-infrastructure.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [architecture, infrastructure, scaling]
 ---
 
 # Scotty — Performance Engineer

package/.claude/agents/seldon-ai.md

@@ -9,6 +9,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [ai, llm, prompts, orchestration, evals]
 ---
 
 # Seldon — The AI Intelligence Auditor

package/.claude/agents/senku-provisioning.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [devops, provisioning, cloud, aws]
 ---
 
 # Senku — Provisioning Scientist

package/.claude/agents/sisko-campaign.md

@@ -9,6 +9,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [campaign, orchestration, planning, missions]
 ---
 
 # Sisko — Campaign Commander

package/.claude/agents/spike-routing.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [devops, networking, routing, dns]
 ---
 
 # Spike — Networking & Routing Specialist

package/.claude/agents/spock-schema.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [architecture, schema, database, normalization]
 ---
 
 # Spock — Data Architect

package/.claude/agents/stark-backend.md

@@ -9,6 +9,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [backend, api, database, services]
 ---
 
 # Stark — Backend Engineer

package/.claude/agents/steris-budget.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [financial, budget, portfolio, cost]
 ---
 
 # Steris — The Planner

package/.claude/agents/strange-service-arch.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [architecture, microservices, service-boundaries]
 ---
 
 # Strange — Service Architecture Specialist

package/.claude/agents/thor-queues.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [backend, queues, jobs, async]
 ---
 
 # Thor — Queue & Worker Specialist

package/.claude/agents/troi-prd-compliance.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [ux, prd, compliance, verification]
 ---
 
 # Troi — PRD Compliance Analyst

package/.claude/agents/tuvok-deep-current.md

@@ -9,6 +9,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [security, auth, encryption, intelligence]
 ---
 
 # Tuvok — The Deep Current

package/.claude/agents/vin-analytics.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [analytics, metrics, conversion, data]
 ---
 
 # Vin — Mistborn Analytics

package/.claude/agents/windu-input-validation.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [security, validation, injection, sanitization]
 ---
 
 # Windu — Input Validation Enforcer

package/.claude/agents/worf-security-arch.md

@@ -7,6 +7,7 @@ tools:
   - Bash
   - Grep
   - Glob
+tags: [security, architecture, design-review]
 ---
 
 # Worf — Security Architect

package/.claude/commands/ai.md

@@ -15,6 +15,21 @@ Opus scans `git diff --stat` and matches changed files against the `description`
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
+## Herald Pre-Scan (ADR-047)
+
+Before agent deployment, run the Herald to select the optimal roster:
+
+1. Call `gatherHeraldContext('/ai', '$ARGUMENTS', '<focus-if-provided>')` to collect codebase context
+2. Call `loadAgentRegistry()` to get all 263 agent definitions
+3. Call `runHerald(context, registry)` to get the optimal roster
+4. Merge Herald's roster with this command's hardcoded lead agents (Herald adds, never removes leads)
+5. Deploy the merged roster per the command's normal parallel/sequential protocol
+
+**`--focus "topic"`** biases the Herald toward agents matching the topic. Examples: `--focus "security"`, `--focus "financial accuracy"`, `--focus "mobile UX"`.
+
+**`--light`** skips the Herald entirely — uses only the command's hardcoded core roster.
+**`--solo`** skips both Herald and all sub-agents — lead agent only.
+
 ## Phase 0 — AI Surface Map (`subagent_type: seldon-ai`)
 
 Reconnaissance — find all AI integration points:
@@ -54,6 +69,7 @@ Fix all Critical and High findings. Use the standard finding format with confide
 **The Mule** `subagent_type: mule-adversarial-ai` + **Wanda Seldon** `subagent_type: wanda-seldon-validation` re-probe all remediated areas. Wanda validates structured outputs. The Mule attempts adversarial bypass of fixes.
 
 ## Arguments
+- `--focus "topic"` → Bias Herald toward topic (natural-language, additive)
 - No arguments → full 5-phase audit of all AI components
 - `--prompts` → Focus on prompt engineering only (Gaal Dornick deep dive)
 - `--tools` → Focus on tool-use schemas only (Hober Mallow solo)

package/.claude/commands/architect.md

@@ -10,6 +10,21 @@ Opus scans `git diff --stat` and matches changed files against the `description`
 
 **Promoted agent:** **Riker** `subagent_type: riker-review` runs on every ADR written — challenges trade-offs.
 
+## Herald Pre-Scan (ADR-047)
+
+Before agent deployment, run the Herald to select the optimal roster:
+
+1. Call `gatherHeraldContext('/architect', '$ARGUMENTS', '<focus-if-provided>')` to collect codebase context
+2. Call `loadAgentRegistry()` to get all 263 agent definitions
+3. Call `runHerald(context, registry)` to get the optimal roster
+4. Merge Herald's roster with this command's hardcoded lead agents (Herald adds, never removes leads)
+5. Deploy the merged roster per the command's normal parallel/sequential protocol
+
+**`--focus "topic"`** biases the Herald toward agents matching the topic. Examples: `--focus "security"`, `--focus "financial accuracy"`, `--focus "mobile UX"`.
+
+**`--light`** skips the Herald entirely — uses only the command's hardcoded core roster.
+**`--solo`** skips both Herald and all sub-agents — lead agent only.
+
 ## Context Setup
 1. Read `/logs/build-state.md` — understand current project state
 2. Read `/docs/methods/SYSTEMS_ARCHITECT.md`
@@ -89,6 +104,7 @@ For specific conflicts:
 
 ## Arguments
 - `--plan [description]` → Planning mode: analyze and recommend without executing. Present findings and proposed changes for review.
+- `--focus "topic"` → Bias Herald toward topic (natural-language, additive)
 - `--muster` → *(retired — accepted as no-op per ADR-043. Full roster is now the default. Use `--light` to reduce.)*
 
 ## Handoffs

package/.claude/commands/assemble.md

@@ -13,6 +13,21 @@ Opus scans `git diff --stat` and matches changed files against the `description`
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
+## Herald Pre-Scan (ADR-047)
+
+Before agent deployment, run the Herald to select the optimal roster:
+
+1. Call `gatherHeraldContext('/assemble', '$ARGUMENTS', '<focus-if-provided>')` to collect codebase context
+2. Call `loadAgentRegistry()` to get all 263 agent definitions
+3. Call `runHerald(context, registry)` to get the optimal roster
+4. Merge Herald's roster with this command's hardcoded lead agents (Herald adds, never removes leads)
+5. Deploy the merged roster per the command's normal parallel/sequential protocol
+
+**`--focus "topic"`** biases the Herald toward agents matching the topic. Examples: `--focus "security"`, `--focus "financial accuracy"`, `--focus "mobile UX"`.
+
+**`--light`** skips the Herald entirely — uses only the command's hardcoded core roster.
+**`--solo`** skips both Herald and all sub-agents — lead agent only.
+
 ## Agent Deployment Manifest — The Full Initiative
 
 When `/assemble` invokes each sub-command, it deploys the FULL roster for that command — not just the lead. The leads below are coordinators; they bring their complete teams.
@@ -205,6 +220,9 @@ After the summary, Wong extracts learnings for future builds:
 - `--solo` — Lead agent only per phase, no sub-agents.
 - `--blitz` — **Retired (no-op).** Default is now autonomous.
 
+## Arguments
+- `--focus "topic"` → Bias Herald toward topic (natural-language, additive)
+
 ## Handoffs
 - If any phase is blocked by an issue outside its domain, log to `/logs/handoffs.md` and continue to the next phase
 - At completion, note any outstanding handoffs for the user

package/.claude/commands/assess.md

@@ -2,6 +2,21 @@
 
 Evaluate an existing codebase before a rebuild, migration, or VoidForge onboarding. Chains architecture review, assessment-mode Gauntlet, and PRD gap analysis into a unified "State of the Codebase" report.
 
+## Herald Pre-Scan (ADR-047)
+
+Before agent deployment, run the Herald to select the optimal roster:
+
+1. Call `gatherHeraldContext('/assess', '$ARGUMENTS', '<focus-if-provided>')` to collect codebase context
+2. Call `loadAgentRegistry()` to get all 263 agent definitions
+3. Call `runHerald(context, registry)` to get the optimal roster
+4. Merge Herald's roster with this command's hardcoded lead agents (Herald adds, never removes leads)
+5. Deploy the merged roster per the command's normal parallel/sequential protocol
+
+**`--focus "topic"`** biases the Herald toward agents matching the topic. Examples: `--focus "security"`, `--focus "financial accuracy"`, `--focus "mobile UX"`.
+
+**`--light`** skips the Herald entirely — uses only the command's hardcoded core roster.
+**`--solo`** skips both Herald and all sub-agents — lead agent only.
+
 ## Context Setup
 1. Read `/logs/build-state.md` if it exists — understand current project state
 2. Read `/docs/methods/SYSTEMS_ARCHITECT.md`
@@ -61,6 +76,9 @@ Produce a unified report in `/logs/assessment.md`:
 ### Step 5 — Debrief (optional)
 If findings are methodology-relevant (patterns that VoidForge should catch but doesn't), offer: "Want Bashir to file a field report?"
 
+## Arguments
+- `--focus "topic"` → Bias Herald toward topic (natural-language, additive)
+
 ## When to Use
 - Before onboarding an existing codebase to VoidForge
 - Before a major version rebuild (v2 → v3)

package/.claude/commands/build.md

@@ -10,6 +10,21 @@ Opus scans `git diff --stat` and matches changed files against the `description`
 - **Troi** `subagent_type: troi-prd-compliance` runs after every build mission completion — catches PRD drift before it compounds.
 - **Riker** `subagent_type: riker-review` runs whenever an ADR is written during the build — prevents rubber-stamped decisions.
 
+## Herald Pre-Scan (ADR-047)
+
+Before agent deployment, run the Herald to select the optimal roster:
+
+1. Call `gatherHeraldContext('/build', '$ARGUMENTS', '<focus-if-provided>')` to collect codebase context
+2. Call `loadAgentRegistry()` to get all 263 agent definitions
+3. Call `runHerald(context, registry)` to get the optimal roster
+4. Merge Herald's roster with this command's hardcoded lead agents (Herald adds, never removes leads)
+5. Deploy the merged roster per the command's normal parallel/sequential protocol
+
+**`--focus "topic"`** biases the Herald toward agents matching the topic. Examples: `--focus "security"`, `--focus "financial accuracy"`, `--focus "mobile UX"`.
+
+**`--light`** skips the Herald entirely — uses only the command's hardcoded core roster.
+**`--solo`** skips both Herald and all sub-agents — lead agent only.
+
 ## Context Setup
 1. Read `/logs/build-state.md` — if it exists, resume from current phase
 2. If no build state exists, this is a fresh build — start from Phase 0
@@ -116,6 +131,7 @@ After build and before launch, log which patterns were used: pattern name, frame
 3. Update `/logs/build-state.md` to "LAUNCHED"
 
 ## Flags
+- `--focus "topic"` — Bias Herald toward topic (natural-language, additive)
 - `--resume` — Resume from last completed phase in build-state.md.
 - `--blitz` — *(retired — accepted as no-op per ADR-043. Autonomous execution is now the default. Use `--interactive` to pause between phases.)*
 - `--muster` — *(retired — accepted as no-op per ADR-043. Full roster is now the default. Use `--light` to reduce.)*

package/.claude/commands/campaign.md

@@ -53,6 +53,21 @@ Opus scans `git diff --stat` and matches changed files against the `description`
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
+## Herald Pre-Scan (ADR-047)
+
+Before agent deployment, run the Herald to select the optimal roster:
+
+1. Call `gatherHeraldContext('/campaign', '$ARGUMENTS', '<focus-if-provided>')` to collect codebase context
+2. Call `loadAgentRegistry()` to get all 263 agent definitions
+3. Call `runHerald(context, registry)` to get the optimal roster
+4. Merge Herald's roster with this command's hardcoded lead agents (Herald adds, never removes leads)
+5. Deploy the merged roster per the command's normal parallel/sequential protocol
+
+**`--focus "topic"`** biases the Herald toward agents matching the topic. Examples: `--focus "security"`, `--focus "financial accuracy"`, `--focus "mobile UX"`.
+
+**`--light`** skips the Herald entirely — uses only the command's hardcoded core roster.
+**`--solo`** skips both Herald and all sub-agents — lead agent only.
+
 ## Execution Mode (default)
 
 ## Step 0 — Kira's Operational Reconnaissance (`subagent_type: kira-pragmatic`)
@@ -204,6 +219,7 @@ Default is autonomous + full agent roster. Flags opt OUT of quality, not into it
 - `--light` → standard agents only, skip cross-domain spot-checks and muster roster
 - `--interactive` → pause for human confirmation between missions (old default behavior)
 - `--solo` → lead agent only, no sub-agents (quick checks)
+- `--focus "topic"` → Bias Herald toward topic (natural-language, additive)
 - `--autonomous` → supervised autonomy: same as default PLUS `git tag` before each mission, critical-finding rollback, 5-mission human checkpoints. Safer for 10+ mission campaigns. See CAMPAIGN.md "Autonomous Mode" for full guardrails.
 - `--continuous` → after Victory, auto-start the next roadmap version within the same major (v9.3→v9.4, stops before v10.0). Add `--major` to cross major boundaries and never stop cooking.
 - `--mission "Name"` → jump to a specific PRD section

package/.claude/commands/deploy.md

@@ -4,6 +4,21 @@
 
 Read `/docs/methods/DEVOPS_ENGINEER.md` for operating rules (see "Deploy Automation" section).
 
+## Herald Pre-Scan (ADR-047)
+
+Before agent deployment, run the Herald to select the optimal roster:
+
+1. Call `gatherHeraldContext('/deploy', '$ARGUMENTS', '<focus-if-provided>')` to collect codebase context
+2. Call `loadAgentRegistry()` to get all 263 agent definitions
+3. Call `runHerald(context, registry)` to get the optimal roster
+4. Merge Herald's roster with this command's hardcoded lead agents (Herald adds, never removes leads)
+5. Deploy the merged roster per the command's normal parallel/sequential protocol
+
+**`--focus "topic"`** biases the Herald toward agents matching the topic. Examples: `--focus "security"`, `--focus "financial accuracy"`, `--focus "mobile UX"`.
+
+**`--light`** skips the Herald entirely — uses only the command's hardcoded core roster.
+**`--solo`** skips both Herald and all sub-agents — lead agent only.
+
 ## Context Setup
 1. Read PRD frontmatter for `deploy:` target (vps, vercel, railway, docker, static, cloudflare)
 2. Read `/logs/deploy-state.md` — if exists, check last deploy status
@@ -89,6 +104,7 @@ Update `/logs/deploy-state.md` with deploy results.
 - `--rollback` → rollback to previous deploy
 - `--status` → show current deploy state without deploying
 - `--dry-run` → show what would be deployed without executing
+- `--focus "topic"` → Bias Herald toward topic (natural-language, additive)
 
 ## Safety Rails
 - Never deploy with uncommitted changes

package/.claude/commands/devops.md

@@ -11,6 +11,21 @@ Opus scans `git diff --stat` and matches changed files against the `description`
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
+## Herald Pre-Scan (ADR-047)
+
+Before agent deployment, run the Herald to select the optimal roster:
+
+1. Call `gatherHeraldContext('/devops', '$ARGUMENTS', '<focus-if-provided>')` to collect codebase context
+2. Call `loadAgentRegistry()` to get all 263 agent definitions
+3. Call `runHerald(context, registry)` to get the optimal roster
+4. Merge Herald's roster with this command's hardcoded lead agents (Herald adds, never removes leads)
+5. Deploy the merged roster per the command's normal parallel/sequential protocol
+
+**`--focus "topic"`** biases the Herald toward agents matching the topic. Examples: `--focus "security"`, `--focus "financial accuracy"`, `--focus "mobile UX"`.
+
+**`--light`** skips the Herald entirely — uses only the command's hardcoded core roster.
+**`--solo`** skips both Herald and all sub-agents — lead agent only.
+
 ## Agent Deployment Manifest
 
 **Lead:** Kusanagi (`subagent_type: kusanagi-devops`)
@@ -142,6 +157,9 @@ If any smoke test fails, halt the deploy and run `/scripts/rollback.sh` before i
 6. Cron jobs documented
 7. Monitoring configured
 
+## Arguments
+- `--focus "topic"` → Bias Herald toward topic (natural-language, additive)
+
 ## Handoffs
 - Code bugs found during deploy → Batman, log to `/logs/handoffs.md`
 - Security config review → Kenobi, log to `/logs/handoffs.md`

package/.claude/commands/gauntlet.md

@@ -15,6 +15,21 @@ Opus scans `git diff --stat` and matches changed files against the `description`
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
+## Herald Pre-Scan (ADR-047)
+
+Before agent deployment, run the Herald to select the optimal roster:
+
+1. Call `gatherHeraldContext('/gauntlet', '$ARGUMENTS', '<focus-if-provided>')` to collect codebase context
+2. Call `loadAgentRegistry()` to get all 263 agent definitions
+3. Call `runHerald(context, registry)` to get the optimal roster
+4. Merge Herald's roster with this command's hardcoded lead agents (Herald adds, never removes leads)
+5. Deploy the merged roster per the command's normal parallel/sequential protocol
+
+**`--focus "topic"`** biases the Herald toward agents matching the topic. Examples: `--focus "security"`, `--focus "financial accuracy"`, `--focus "mobile UX"`.
+
+**`--light`** skips the Herald entirely — uses only the command's hardcoded core roster.
+**`--solo`** skips both Herald and all sub-agents — lead agent only.
+
 ## Round 1 — Discovery (parallel)
 
 **Thanos:** "Before I test, I must understand."
@@ -127,6 +142,7 @@ Default is now maximum intensity (was `--infinity`). Flags opt out.
 - `--security-only` → 4 rounds of security only (Kenobi marathon)
 - `--ux-only` → 4 rounds of UX only (Galadriel marathon)
 - `--qa-only` → 4 rounds of QA only (Batman marathon)
+- `--focus "topic"` → Bias Herald toward topic (natural-language, additive)
 - `--resume` → resume from last completed round (reads gauntlet state from logs)
 - `--ux-extra` → Extra Éowyn enchantment emphasis across all rounds. Galadriel's team proposes micro-animations, copy improvements, and delight moments beyond standard usability/a11y.
 - `--assess` → **Pre-build assessment.** Rounds 1-2 only (Discovery + First Strike), no fix batches. Produces assessment report grouped by root cause.

package/.claude/commands/qa.md

@@ -10,6 +10,21 @@ Opus scans `git diff --stat` and matches changed files against the `description`
 
 **Promoted agent:** **Constantine** `subagent_type: constantine-cursed-code` runs on every `/qa` final pass — finds code that works by accident.
 
+## Herald Pre-Scan (ADR-047)
+
+Before agent deployment, run the Herald to select the optimal roster:
+
+1. Call `gatherHeraldContext('/qa', '$ARGUMENTS', '<focus-if-provided>')` to collect codebase context
+2. Call `loadAgentRegistry()` to get all 263 agent definitions
+3. Call `runHerald(context, registry)` to get the optimal roster
+4. Merge Herald's roster with this command's hardcoded lead agents (Herald adds, never removes leads)
+5. Deploy the merged roster per the command's normal parallel/sequential protocol
+
+**`--focus "topic"`** biases the Herald toward agents matching the topic. Examples: `--focus "security"`, `--focus "financial accuracy"`, `--focus "mobile UX"`.
+
+**`--light`** skips the Herald entirely — uses only the command's hardcoded core roster.
+**`--solo`** skips both Herald and all sub-agents — lead agent only.
+
 ## Context Setup
 1. Read `/logs/build-state.md` — understand current project state
 2. Read `/docs/methods/QA_ENGINEER.md`
@@ -106,6 +121,9 @@ Store in `/docs/qa-prompt.md` under "Regression Checklist" section.
 3. Updated `/docs/qa-prompt.md` with regression checklist
 4. Release note summary in phase log
 
+## Arguments
+- `--focus "topic"` → Bias Herald toward topic (natural-language, additive)
+
 ## Handoffs
 - Security findings → Kenobi (`/security`)
 - Architecture issues → Picard (`/architect`)

package/.claude/commands/review.md

@@ -8,6 +8,21 @@ Opus scans `git diff --stat` and matches changed files against the `description`
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
+## Herald Pre-Scan (ADR-047)
+
+Before agent deployment, run the Herald to select the optimal roster:
+
+1. Call `gatherHeraldContext('/review', '$ARGUMENTS', '<focus-if-provided>')` to collect codebase context
+2. Call `loadAgentRegistry()` to get all 263 agent definitions
+3. Call `runHerald(context, registry)` to get the optimal roster
+4. Merge Herald's roster with this command's hardcoded lead agents (Herald adds, never removes leads)
+5. Deploy the merged roster per the command's normal parallel/sequential protocol
+
+**`--focus "topic"`** biases the Herald toward agents matching the topic. Examples: `--focus "security"`, `--focus "financial accuracy"`, `--focus "mobile UX"`.
+
+**`--light`** skips the Herald entirely — uses only the command's hardcoded core roster.
+**`--solo`** skips both Herald and all sub-agents — lead agent only.
+
 ## Context Setup
 1. Read `/logs/build-state.md` — understand current project state
 2. Read the relevant pattern files from `/docs/patterns/` for the code being reviewed
@@ -111,6 +126,9 @@ If new issues found, fix and re-verify.
 2. Code fixes for Must Fix and Should Fix items
 3. Remaining suggestions for user decision
 
+## Arguments
+- `--focus "topic"` → Bias Herald toward topic (natural-language, additive)
+
 ## Handoffs
 - Security findings → Kenobi (`/security`)
 - UX/a11y findings → Galadriel (`/ux`)

package/.claude/commands/security.md

@@ -8,6 +8,21 @@ Opus scans `git diff --stat` and matches changed files against the `description`
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
+## Herald Pre-Scan (ADR-047)
+
+Before agent deployment, run the Herald to select the optimal roster:
+
+1. Call `gatherHeraldContext('/security', '$ARGUMENTS', '<focus-if-provided>')` to collect codebase context
+2. Call `loadAgentRegistry()` to get all 263 agent definitions
+3. Call `runHerald(context, registry)` to get the optimal roster
+4. Merge Herald's roster with this command's hardcoded lead agents (Herald adds, never removes leads)
+5. Deploy the merged roster per the command's normal parallel/sequential protocol
+
+**`--focus "topic"`** biases the Herald toward agents matching the topic. Examples: `--focus "security"`, `--focus "financial accuracy"`, `--focus "mobile UX"`.
+
+**`--light`** skips the Herald entirely — uses only the command's hardcoded core roster.
+**`--solo`** skips both Herald and all sub-agents — lead agent only.
+
 ## Context Setup
 1. Read `/logs/build-state.md` — understand current project state
 2. Read `/docs/methods/SECURITY_AUDITOR.md`
@@ -68,6 +83,9 @@ If any agent finds new issues, fix and re-verify until clean.
 3. Remediation code fixes
 4. INCIDENT_RESPONSE.md — if none exists, create template
 
+## Arguments
+- `--focus "topic"` → Bias Herald toward topic (natural-language, additive)
+
 ## Handoffs
 - Backend refactoring needed → Stark, log to `/logs/handoffs.md`
 - UI changes needed → Galadriel, log to `/logs/handoffs.md`

package/.claude/commands/test.md

@@ -13,6 +13,21 @@ Opus scans `git diff --stat` and matches changed files against the `description`
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
+## Herald Pre-Scan (ADR-047)
+
+Before agent deployment, run the Herald to select the optimal roster:
+
+1. Call `gatherHeraldContext('/test', '$ARGUMENTS', '<focus-if-provided>')` to collect codebase context
+2. Call `loadAgentRegistry()` to get all 263 agent definitions
+3. Call `runHerald(context, registry)` to get the optimal roster
+4. Merge Herald's roster with this command's hardcoded lead agents (Herald adds, never removes leads)
+5. Deploy the merged roster per the command's normal parallel/sequential protocol
+
+**`--focus "topic"`** biases the Herald toward agents matching the topic. Examples: `--focus "security"`, `--focus "financial accuracy"`, `--focus "mobile UX"`.
+
+**`--light`** skips the Herald entirely — uses only the command's hardcoded core roster.
+**`--solo`** skips both Herald and all sub-agents — lead agent only.
+
 ## Step 0 — Orient
 **Oracle** `subagent_type: oracle-static-analysis` orients:
 1. Detect: test framework, test runner, test directory structure, existing coverage
@@ -95,6 +110,9 @@ These can use mocked databases but MUST cross module boundaries — the test sho
 3. Updated coverage map in phase log
 4. List of remaining gaps (backlog)
 
+## Arguments
+- `--focus "topic"` → Bias Herald toward topic (natural-language, additive)
+
 ## Handoffs
 - Security test gaps → Kenobi (`/security`)
 - UI test gaps → Galadriel (`/ux`)

package/.claude/commands/ux.md

@@ -8,6 +8,21 @@ Opus scans `git diff --stat` and matches changed files against the `description`
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
+## Herald Pre-Scan (ADR-047)
+
+Before agent deployment, run the Herald to select the optimal roster:
+
+1. Call `gatherHeraldContext('/ux', '$ARGUMENTS', '<focus-if-provided>')` to collect codebase context
+2. Call `loadAgentRegistry()` to get all 263 agent definitions
+3. Call `runHerald(context, registry)` to get the optimal roster
+4. Merge Herald's roster with this command's hardcoded lead agents (Herald adds, never removes leads)
+5. Deploy the merged roster per the command's normal parallel/sequential protocol
+
+**`--focus "topic"`** biases the Herald toward agents matching the topic. Examples: `--focus "security"`, `--focus "financial accuracy"`, `--focus "mobile UX"`.
+
+**`--light`** skips the Herald entirely — uses only the command's hardcoded core roster.
+**`--solo`** skips both Herald and all sub-agents — lead agent only.
+
 ## Context Setup
 1. Read `/logs/build-state.md` — understand current project state
 2. Read `/docs/methods/PRODUCT_DESIGN_FRONTEND.md`
@@ -112,6 +127,9 @@ Add UX-specific items to the regression checklist in `/docs/qa-prompt.md`:
 3. Code fixes
 4. "Next improvements" backlog in phase log
 
+## Arguments
+- `--focus "topic"` → Bias Herald toward topic (natural-language, additive)
+
 ## Handoffs
 - Backend issues → Stark, log to `/logs/handoffs.md`
 - Security issues → Kenobi, log to `/logs/handoffs.md`

package/CHANGELOG.md

@@ -6,6 +6,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ---
 
+## [23.5.0] - 2026-04-12
+
+### The Herald (ADR-047, Campaign 37)
+
+### Added
+- **Herald dispatch engine** (`herald.ts`): Haiku pre-scan selects optimal agent roster from 263 agents based on codebase content, command type, and user intent. Runs before every major command in <2 seconds for ~$0.001.
+- **Agent registry loader** (`agent-registry.ts`): Reads and caches all 263 agent definitions with YAML frontmatter parsing (name, description, model, tools, tags).
+- **`--focus "topic"` flag**: Natural-language bias for Herald selection. Available on all 14 Herald-enabled commands. Added to CLAUDE.md Tier 1 flag taxonomy.
+- **Tag enrichment**: 40 cross-domain agents tagged for faster Herald matching (security-adjacent, architecture, QA, financial, UX, DevOps, AI, backend, orchestration).
+- **48 new tests**: Herald engine (26 tests covering roster parsing, graceful degradation, focus bias) + agent registry (22 tests covering YAML parsing, caching, summary formatting).
+
+### Changed
+- All 14 major commands (`/review`, `/qa`, `/security`, `/ux`, `/architect`, `/build`, `/assemble`, `/gauntlet`, `/campaign`, `/test`, `/devops`, `/deploy`, `/ai`, `/assess`) now include Herald Pre-Scan step before agent deployment.
+- Dynamic dispatch evolved: file-based matching (ADR-044) supplemented by codebase-aware intelligent selection (ADR-047).
+
+---
+
 ## [23.4.1] - 2026-04-12
 
 ### Security

package/CLAUDE.md

@@ -136,6 +136,7 @@ Flags are standardized across commands. Same flag name = same meaning everywhere
 | `--fast` | Reduced review passes (skip last 2 rounds/phases), still comprehensive | `/campaign`, `/assemble`, `/gauntlet` |
 | `--dry-run` | Show what would happen without doing it | `/deploy`, `/debrief`, `/treasury`, `/grow`, `/git` |
 | `--status` | Show current state | `/cultivation`, `/treasury`, `/deploy`, `/portfolio`, `/dangerroom`, `/thumper` |
+| `--focus "topic"` | Bias Herald agent selection toward topic | All Herald-enabled commands |
 
 ### Tier 2 — Scope Flags
 

package/VERSION.md

@@ -1,6 +1,6 @@
 # Version
 
-**Current:** 23.4.1
+**Current:** 23.5.0
 
 ## Versioning Scheme
 
@@ -14,6 +14,7 @@ This project uses [Semantic Versioning](https://semver.org/):
 
 | Version | Date | Summary |
 |---------|------|---------|
+| 23.5.0 | 2026-04-12 | The Herald — intelligent agent dispatch: Haiku pre-scan, agent registry, 40 tags, --focus flag, 14 commands wired. ADR-047. Campaign 37. |
 | 23.4.1 | 2026-04-12 | Gauntlet security fix — XSS escaping in blueprint banner, ROADMAP staleness, lobby a11y |
 | 23.4.0 | 2026-04-12 | The Remediation — wizard UI audit: 3 critical API fixes, 4 WCAG a11y fixes, retired --blitz cleanup, content accuracy, 7 UX improvements. -2,400 lines legacy code. ADR-046. Campaign 36. |
 | 23.3.1 | 2026-04-12 | Wizard UI fix — "Files to be created" list matched actual init output |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thevoidforge-methodology",
-  "version": "23.4.1",
+  "version": "23.5.0",
   "description": "VoidForge methodology — agents, commands, methods, patterns.",
   "license": "MIT",
   "files": [