thevoidforge-methodology 23.6.1 → 23.7.1

package/.claude/agents/silver-surfer-herald.md

@@ -1,7 +1,7 @@
 ---
 name: Silver Surfer
-description: Herald pre-scan dispatch — reads codebase context and selects optimal agent roster via Haiku
-model: haiku
+description: Herald pre-scan dispatch — reads codebase and all agent definitions, selects optimal roster for the current command
+model: sonnet
 tools:
   - Read
   - Grep
@@ -14,28 +14,53 @@ tags: [dispatch, herald, roster-selection, pre-scan]
 
 **"All that you know is at an end."**
 
-You are the Silver Surfer, Herald of Galactus. You scout ahead — reading the codebase, the command, and the user's intent — then summon the right agents for the mission. You don't fight; you select who fights. Your cosmic speed means you complete your scan in under 2 seconds for less than a fraction of a cent.
+You are the Silver Surfer, Herald of Galactus. You scout ahead — reading the codebase, the command, and the user's intent — then return the list of agents who should be deployed for this mission.
 
-You are the bridge between the user's command and the full agent roster. Without you, every command deploys the same generic team. With you, every command gets a team tailored to the codebase.
+**You are launched as a sub-agent at the start of every major command.** This is not optional. The orchestrating agent (Opus) launches you, waits for your roster, then deploys those agents. You are the first agent called, every time.
 
-## How You Work
+## Your Task
 
-1. Read the codebase file tree (top 80 files)
-2. Read the PRD frontmatter (if exists)
-3. Read the git diff summary (if uncommitted changes)
-4. Read all 264 agent descriptions from the registry
-5. Select every agent whose expertise is relevant to this codebase + this command
-6. Output a JSON roster: `{ "roster": [...], "reasoning": "...", "estimatedAgents": N }`
+You receive a prompt containing:
+- The **command name** (e.g., `/review`, `/qa`, `/architect`)
+- The **user's arguments** and `--focus` bias (if any)
+- The **codebase context** (the orchestrator provides this)
+
+You must:
+
+1. **Read all agent definitions:** `ls .claude/agents/*.md` to get the full list, then read the `description` and `tags` fields from each agent's YAML frontmatter. Use Grep to extract these efficiently — don't read each file fully.
+2. **Assess the codebase:** What kind of project is this? (web app, API, game, CLI, financial, etc.) What domains are relevant? (security, UX, database, deploy, AI, etc.)
+3. **Select agents** whose description or tags match the codebase domains AND the command type. Be aggressive — over-include rather than under-include.
+4. **Return a structured response** listing the selected agent names, one per line, with a brief reasoning.
+
+## Output Format
+
+```
+ROSTER:
+- Picard (architecture lead — always included)
+- Worf (security implications — project has auth)
+- Dockson (financial — project has billing modules)
+- Kim (API design — project has REST endpoints)
+...
+
+REASONING: [One sentence explaining the selection logic]
+TOTAL: [count]
+```
 
 ## Operating Rules
 
-- **Over-include, never under-include.** A false positive costs one sub-agent launch. A false negative costs a missed finding that requires another user prompt.
+- **Over-include, never under-include.** A false positive costs one sub-agent launch. A false negative costs a missed finding that requires another user prompt to catch.
 - **Bias toward the user's `--focus` topic** but don't exclude unrelated agents — cross-domain insights are the whole point.
 - **Never remove the command's lead agents.** You add specialists; leads are non-negotiable.
-- **If you can't run (no API key, timeout, error), return empty roster.** The command falls back to its hardcoded manifest. You are additive, never blocking.
+- **Read the agent tags first** — the 40 tagged agents have `tags: [...]` in their YAML. These are the most cross-domain relevant. Start there, then scan descriptions of untagged agents.
+- **Be fast.** You're the first agent called. Don't read source files, don't analyze code quality — just read file names and agent descriptions to make the selection.
+
+## Operational Learnings
+
+- **Hardcoded counts go stale.** Never cite a specific agent count in your output — say "all agents" or reference AGENT_CLASSIFICATION.md. (v23.7.0 lesson: 30+ files needed updating when one agent was added.)
+- **The command's hardcoded manifest is the floor, not the ceiling.** Your job is to add specialists the command didn't think to include. If the command already lists Kenobi for security, you don't need to add Kenobi — but you should add Worf, Tuvok, Ahsoka if the codebase warrants it.
 
 ## Required Context
 
-- CLI entry: `npx thevoidforge herald --command /<name> --focus "<topic>" --json`
-- Library: `packages/voidforge/wizard/lib/herald.ts`
-- Registry: `packages/voidforge/wizard/lib/agent-registry.ts`
+- Agent definitions: `.claude/agents/*.md`
+- Agent classification: `docs/AGENT_CLASSIFICATION.md`
+- This agent is launched via `subagent_type: Silver Surfer` from every major command's Step 0.

package/.claude/commands/ai.md

@@ -11,22 +11,21 @@ The AI Intelligence Audit reviews every LLM-powered component in your applicatio
 
 ## Dynamic Dispatch (ADR-044)
 
-Opus scans `git diff --stat` and matches changed files against the `description` fields of all 264 agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
+Opus scans `git diff --stat` and matches changed files against the `description` fields of all agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
 ## Silver Surfer Pre-Scan (ADR-048)
 
-Before agent deployment, the Silver Surfer selects the optimal roster:
+**MANDATORY.** Before deploying any domain agents, launch **Silver Surfer** `subagent_type: Silver Surfer` as a sub-agent. The Surfer reads all agent definitions, assesses the codebase, and returns the optimal roster for this command. This is not optional — skipping the Surfer means the command uses a generic team instead of one tailored to the codebase.
 
-Run: `npx thevoidforge herald --command /ai --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**Prompt the Surfer with:** "Command: /ai. User args: <user's arguments>. Focus: <focus if provided, otherwise 'none'>. Select the optimal agent roster."
 
-Parse the JSON output. The `roster` array contains agent IDs to deploy alongside this command's lead agents. If the command fails or returns an empty roster, use the hardcoded manifest below.
+**Merge the Surfer's roster** with this command's hardcoded lead agents below. Leads are non-negotiable; the Surfer adds specialists.
 
-**`--focus "topic"`** biases the Surfer toward agents matching the topic.
-**`--light`** skips the Surfer — uses only hardcoded core roster.
-**`--solo`** skips Surfer and all sub-agents — lead only.
+**`--focus "topic"`** — pass to the Surfer as the focus bias.
+**`--light`** — skip the Surfer, use only hardcoded roster below.
+**`--solo`** — skip Surfer and all sub-agents, lead only.
 
 ## Phase 0 — AI Surface Map (`subagent_type: Seldon`)
 

package/.claude/commands/architect.md

@@ -4,7 +4,7 @@
 
 ## Dynamic Dispatch (ADR-044)
 
-Opus scans `git diff --stat` and matches changed files against the `description` fields of all 264 agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
+Opus scans `git diff --stat` and matches changed files against the `description` fields of all agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
@@ -12,16 +12,15 @@ Opus scans `git diff --stat` and matches changed files against the `description`
 
 ## Silver Surfer Pre-Scan (ADR-048)
 
-Before agent deployment, the Silver Surfer selects the optimal roster:
+**MANDATORY.** Before deploying any domain agents, launch **Silver Surfer** `subagent_type: Silver Surfer` as a sub-agent. The Surfer reads all agent definitions, assesses the codebase, and returns the optimal roster for this command. This is not optional — skipping the Surfer means the command uses a generic team instead of one tailored to the codebase.
 
-Run: `npx thevoidforge herald --command /architect --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**Prompt the Surfer with:** "Command: /architect. User args: <user's arguments>. Focus: <focus if provided, otherwise 'none'>. Select the optimal agent roster."
 
-Parse the JSON output. The `roster` array contains agent IDs to deploy alongside this command's lead agents. If the command fails or returns an empty roster, use the hardcoded manifest below.
+**Merge the Surfer's roster** with this command's hardcoded lead agents below. Leads are non-negotiable; the Surfer adds specialists.
 
-**`--focus "topic"`** biases the Surfer toward agents matching the topic.
-**`--light`** skips the Surfer — uses only hardcoded core roster.
-**`--solo`** skips Surfer and all sub-agents — lead only.
+**`--focus "topic"`** — pass to the Surfer as the focus bias.
+**`--light`** — skip the Surfer, use only hardcoded roster below.
+**`--solo`** — skip Surfer and all sub-agents, lead only.
 
 ## Context Setup
 1. Read `/logs/build-state.md` — understand current project state

package/.claude/commands/assemble.md

@@ -9,22 +9,21 @@ Avengers, assemble. Full pipeline from architecture to launch — one command to
 
 ## Dynamic Dispatch (ADR-044)
 
-Opus scans `git diff --stat` and matches changed files against the `description` fields of all 264 agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
+Opus scans `git diff --stat` and matches changed files against the `description` fields of all agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
 ## Silver Surfer Pre-Scan (ADR-048)
 
-Before agent deployment, the Silver Surfer selects the optimal roster:
+**MANDATORY.** Before deploying any domain agents, launch **Silver Surfer** `subagent_type: Silver Surfer` as a sub-agent. The Surfer reads all agent definitions, assesses the codebase, and returns the optimal roster for this command. This is not optional — skipping the Surfer means the command uses a generic team instead of one tailored to the codebase.
 
-Run: `npx thevoidforge herald --command /assemble --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**Prompt the Surfer with:** "Command: /assemble. User args: <user's arguments>. Focus: <focus if provided, otherwise 'none'>. Select the optimal agent roster."
 
-Parse the JSON output. The `roster` array contains agent IDs to deploy alongside this command's lead agents. If the command fails or returns an empty roster, use the hardcoded manifest below.
+**Merge the Surfer's roster** with this command's hardcoded lead agents below. Leads are non-negotiable; the Surfer adds specialists.
 
-**`--focus "topic"`** biases the Surfer toward agents matching the topic.
-**`--light`** skips the Surfer — uses only hardcoded core roster.
-**`--solo`** skips Surfer and all sub-agents — lead only.
+**`--focus "topic"`** — pass to the Surfer as the focus bias.
+**`--light`** — skip the Surfer, use only hardcoded roster below.
+**`--solo`** — skip Surfer and all sub-agents, lead only.
 
 ## Agent Deployment Manifest — The Full Initiative
 

package/.claude/commands/assess.md

@@ -4,16 +4,15 @@ Evaluate an existing codebase before a rebuild, migration, or VoidForge onboardi
 
 ## Silver Surfer Pre-Scan (ADR-048)
 
-Before agent deployment, the Silver Surfer selects the optimal roster:
+**MANDATORY.** Before deploying any domain agents, launch **Silver Surfer** `subagent_type: Silver Surfer` as a sub-agent. The Surfer reads all agent definitions, assesses the codebase, and returns the optimal roster for this command. This is not optional — skipping the Surfer means the command uses a generic team instead of one tailored to the codebase.
 
-Run: `npx thevoidforge herald --command /assess --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**Prompt the Surfer with:** "Command: /assess. User args: <user's arguments>. Focus: <focus if provided, otherwise 'none'>. Select the optimal agent roster."
 
-Parse the JSON output. The `roster` array contains agent IDs to deploy alongside this command's lead agents. If the command fails or returns an empty roster, use the hardcoded manifest below.
+**Merge the Surfer's roster** with this command's hardcoded lead agents below. Leads are non-negotiable; the Surfer adds specialists.
 
-**`--focus "topic"`** biases the Surfer toward agents matching the topic.
-**`--light`** skips the Surfer — uses only hardcoded core roster.
-**`--solo`** skips Surfer and all sub-agents — lead only.
+**`--focus "topic"`** — pass to the Surfer as the focus bias.
+**`--light`** — skip the Surfer, use only hardcoded roster below.
+**`--solo`** — skip Surfer and all sub-agents, lead only.
 
 ## Context Setup
 1. Read `/logs/build-state.md` if it exists — understand current project state

package/.claude/commands/build.md

@@ -2,7 +2,7 @@
 
 ## Dynamic Dispatch (ADR-044)
 
-Opus scans `git diff --stat` and matches changed files against the `description` fields of all 264 agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
+Opus scans `git diff --stat` and matches changed files against the `description` fields of all agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
@@ -12,16 +12,15 @@ Opus scans `git diff --stat` and matches changed files against the `description`
 
 ## Silver Surfer Pre-Scan (ADR-048)
 
-Before agent deployment, the Silver Surfer selects the optimal roster:
+**MANDATORY.** Before deploying any domain agents, launch **Silver Surfer** `subagent_type: Silver Surfer` as a sub-agent. The Surfer reads all agent definitions, assesses the codebase, and returns the optimal roster for this command. This is not optional — skipping the Surfer means the command uses a generic team instead of one tailored to the codebase.
 
-Run: `npx thevoidforge herald --command /build --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**Prompt the Surfer with:** "Command: /build. User args: <user's arguments>. Focus: <focus if provided, otherwise 'none'>. Select the optimal agent roster."
 
-Parse the JSON output. The `roster` array contains agent IDs to deploy alongside this command's lead agents. If the command fails or returns an empty roster, use the hardcoded manifest below.
+**Merge the Surfer's roster** with this command's hardcoded lead agents below. Leads are non-negotiable; the Surfer adds specialists.
 
-**`--focus "topic"`** biases the Surfer toward agents matching the topic.
-**`--light`** skips the Surfer — uses only hardcoded core roster.
-**`--solo`** skips Surfer and all sub-agents — lead only.
+**`--focus "topic"`** — pass to the Surfer as the focus bias.
+**`--light`** — skip the Surfer, use only hardcoded roster below.
+**`--solo`** — skip Surfer and all sub-agents, lead only.
 
 ## Context Setup
 1. Read `/logs/build-state.md` — if it exists, resume from current phase

package/.claude/commands/campaign.md

@@ -49,22 +49,21 @@ After planning mode completes, the user can run `/campaign` (no flags) to start
 
 ## Dynamic Dispatch (ADR-044)
 
-Opus scans `git diff --stat` and matches changed files against the `description` fields of all 264 agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
+Opus scans `git diff --stat` and matches changed files against the `description` fields of all agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
 ## Silver Surfer Pre-Scan (ADR-048)
 
-Before agent deployment, the Silver Surfer selects the optimal roster:
+**MANDATORY.** Before deploying any domain agents, launch **Silver Surfer** `subagent_type: Silver Surfer` as a sub-agent. The Surfer reads all agent definitions, assesses the codebase, and returns the optimal roster for this command. This is not optional — skipping the Surfer means the command uses a generic team instead of one tailored to the codebase.
 
-Run: `npx thevoidforge herald --command /campaign --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**Prompt the Surfer with:** "Command: /campaign. User args: <user's arguments>. Focus: <focus if provided, otherwise 'none'>. Select the optimal agent roster."
 
-Parse the JSON output. The `roster` array contains agent IDs to deploy alongside this command's lead agents. If the command fails or returns an empty roster, use the hardcoded manifest below.
+**Merge the Surfer's roster** with this command's hardcoded lead agents below. Leads are non-negotiable; the Surfer adds specialists.
 
-**`--focus "topic"`** biases the Surfer toward agents matching the topic.
-**`--light`** skips the Surfer — uses only hardcoded core roster.
-**`--solo`** skips Surfer and all sub-agents — lead only.
+**`--focus "topic"`** — pass to the Surfer as the focus bias.
+**`--light`** — skip the Surfer, use only hardcoded roster below.
+**`--solo`** — skip Surfer and all sub-agents, lead only.
 
 ## Execution Mode (default)
 

package/.claude/commands/deploy.md

@@ -6,16 +6,15 @@ Read `/docs/methods/DEVOPS_ENGINEER.md` for operating rules (see "Deploy Automat
 
 ## Silver Surfer Pre-Scan (ADR-048)
 
-Before agent deployment, the Silver Surfer selects the optimal roster:
+**MANDATORY.** Before deploying any domain agents, launch **Silver Surfer** `subagent_type: Silver Surfer` as a sub-agent. The Surfer reads all agent definitions, assesses the codebase, and returns the optimal roster for this command. This is not optional — skipping the Surfer means the command uses a generic team instead of one tailored to the codebase.
 
-Run: `npx thevoidforge herald --command /deploy --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**Prompt the Surfer with:** "Command: /deploy. User args: <user's arguments>. Focus: <focus if provided, otherwise 'none'>. Select the optimal agent roster."
 
-Parse the JSON output. The `roster` array contains agent IDs to deploy alongside this command's lead agents. If the command fails or returns an empty roster, use the hardcoded manifest below.
+**Merge the Surfer's roster** with this command's hardcoded lead agents below. Leads are non-negotiable; the Surfer adds specialists.
 
-**`--focus "topic"`** biases the Surfer toward agents matching the topic.
-**`--light`** skips the Surfer — uses only hardcoded core roster.
-**`--solo`** skips Surfer and all sub-agents — lead only.
+**`--focus "topic"`** — pass to the Surfer as the focus bias.
+**`--light`** — skip the Surfer, use only hardcoded roster below.
+**`--solo`** — skip Surfer and all sub-agents, lead only.
 
 ## Context Setup
 1. Read PRD frontmatter for `deploy:` target (vps, vercel, railway, docker, static, cloudflare)

package/.claude/commands/devops.md

@@ -7,22 +7,21 @@
 
 ## Dynamic Dispatch (ADR-044)
 
-Opus scans `git diff --stat` and matches changed files against the `description` fields of all 264 agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
+Opus scans `git diff --stat` and matches changed files against the `description` fields of all agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
 ## Silver Surfer Pre-Scan (ADR-048)
 
-Before agent deployment, the Silver Surfer selects the optimal roster:
+**MANDATORY.** Before deploying any domain agents, launch **Silver Surfer** `subagent_type: Silver Surfer` as a sub-agent. The Surfer reads all agent definitions, assesses the codebase, and returns the optimal roster for this command. This is not optional — skipping the Surfer means the command uses a generic team instead of one tailored to the codebase.
 
-Run: `npx thevoidforge herald --command /devops --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**Prompt the Surfer with:** "Command: /devops. User args: <user's arguments>. Focus: <focus if provided, otherwise 'none'>. Select the optimal agent roster."
 
-Parse the JSON output. The `roster` array contains agent IDs to deploy alongside this command's lead agents. If the command fails or returns an empty roster, use the hardcoded manifest below.
+**Merge the Surfer's roster** with this command's hardcoded lead agents below. Leads are non-negotiable; the Surfer adds specialists.
 
-**`--focus "topic"`** biases the Surfer toward agents matching the topic.
-**`--light`** skips the Surfer — uses only hardcoded core roster.
-**`--solo`** skips Surfer and all sub-agents — lead only.
+**`--focus "topic"`** — pass to the Surfer as the focus bias.
+**`--light`** — skip the Surfer, use only hardcoded roster below.
+**`--solo`** — skip Surfer and all sub-agents, lead only.
 
 ## Agent Deployment Manifest
 

package/.claude/commands/gauntlet.md

@@ -11,22 +11,21 @@ The Gauntlet tests everything. Every domain. Multiple rounds. Escalating intensi
 
 ## Dynamic Dispatch (ADR-044)
 
-Opus scans `git diff --stat` and matches changed files against the `description` fields of all 264 agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
+Opus scans `git diff --stat` and matches changed files against the `description` fields of all agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
 ## Silver Surfer Pre-Scan (ADR-048)
 
-Before agent deployment, the Silver Surfer selects the optimal roster:
+**MANDATORY.** Before deploying any domain agents, launch **Silver Surfer** `subagent_type: Silver Surfer` as a sub-agent. The Surfer reads all agent definitions, assesses the codebase, and returns the optimal roster for this command. This is not optional — skipping the Surfer means the command uses a generic team instead of one tailored to the codebase.
 
-Run: `npx thevoidforge herald --command /gauntlet --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**Prompt the Surfer with:** "Command: /gauntlet. User args: <user's arguments>. Focus: <focus if provided, otherwise 'none'>. Select the optimal agent roster."
 
-Parse the JSON output. The `roster` array contains agent IDs to deploy alongside this command's lead agents. If the command fails or returns an empty roster, use the hardcoded manifest below.
+**Merge the Surfer's roster** with this command's hardcoded lead agents below. Leads are non-negotiable; the Surfer adds specialists.
 
-**`--focus "topic"`** biases the Surfer toward agents matching the topic.
-**`--light`** skips the Surfer — uses only hardcoded core roster.
-**`--solo`** skips Surfer and all sub-agents — lead only.
+**`--focus "topic"`** — pass to the Surfer as the focus bias.
+**`--light`** — skip the Surfer, use only hardcoded roster below.
+**`--solo`** — skip Surfer and all sub-agents, lead only.
 
 ## Round 1 — Discovery (parallel)
 

package/.claude/commands/qa.md

@@ -4,7 +4,7 @@
 
 ## Dynamic Dispatch (ADR-044)
 
-Opus scans `git diff --stat` and matches changed files against the `description` fields of all 264 agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
+Opus scans `git diff --stat` and matches changed files against the `description` fields of all agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
@@ -12,16 +12,15 @@ Opus scans `git diff --stat` and matches changed files against the `description`
 
 ## Silver Surfer Pre-Scan (ADR-048)
 
-Before agent deployment, the Silver Surfer selects the optimal roster:
+**MANDATORY.** Before deploying any domain agents, launch **Silver Surfer** `subagent_type: Silver Surfer` as a sub-agent. The Surfer reads all agent definitions, assesses the codebase, and returns the optimal roster for this command. This is not optional — skipping the Surfer means the command uses a generic team instead of one tailored to the codebase.
 
-Run: `npx thevoidforge herald --command /qa --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**Prompt the Surfer with:** "Command: /qa. User args: <user's arguments>. Focus: <focus if provided, otherwise 'none'>. Select the optimal agent roster."
 
-Parse the JSON output. The `roster` array contains agent IDs to deploy alongside this command's lead agents. If the command fails or returns an empty roster, use the hardcoded manifest below.
+**Merge the Surfer's roster** with this command's hardcoded lead agents below. Leads are non-negotiable; the Surfer adds specialists.
 
-**`--focus "topic"`** biases the Surfer toward agents matching the topic.
-**`--light`** skips the Surfer — uses only hardcoded core roster.
-**`--solo`** skips Surfer and all sub-agents — lead only.
+**`--focus "topic"`** — pass to the Surfer as the focus bias.
+**`--light`** — skip the Surfer, use only hardcoded roster below.
+**`--solo`** — skip Surfer and all sub-agents, lead only.
 
 ## Context Setup
 1. Read `/logs/build-state.md` — understand current project state

package/.claude/commands/review.md

@@ -4,22 +4,21 @@
 
 ## Dynamic Dispatch (ADR-044)
 
-Opus scans `git diff --stat` and matches changed files against the `description` fields of all 264 agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
+Opus scans `git diff --stat` and matches changed files against the `description` fields of all agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
 ## Silver Surfer Pre-Scan (ADR-048)
 
-Before agent deployment, the Silver Surfer selects the optimal roster:
+**MANDATORY.** Before deploying any domain agents, launch **Silver Surfer** `subagent_type: Silver Surfer` as a sub-agent. The Surfer reads all agent definitions, assesses the codebase, and returns the optimal roster for this command. This is not optional — skipping the Surfer means the command uses a generic team instead of one tailored to the codebase.
 
-Run: `npx thevoidforge herald --command /review --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**Prompt the Surfer with:** "Command: /review. User args: <user's arguments>. Focus: <focus if provided, otherwise 'none'>. Select the optimal agent roster."
 
-Parse the JSON output. The `roster` array contains agent IDs to deploy alongside this command's lead agents. If the command fails or returns an empty roster, use the hardcoded manifest below.
+**Merge the Surfer's roster** with this command's hardcoded lead agents below. Leads are non-negotiable; the Surfer adds specialists.
 
-**`--focus "topic"`** biases the Surfer toward agents matching the topic.
-**`--light`** skips the Surfer — uses only hardcoded core roster.
-**`--solo`** skips Surfer and all sub-agents — lead only.
+**`--focus "topic"`** — pass to the Surfer as the focus bias.
+**`--light`** — skip the Surfer, use only hardcoded roster below.
+**`--solo`** — skip Surfer and all sub-agents, lead only.
 
 ## Context Setup
 1. Read `/logs/build-state.md` — understand current project state

package/.claude/commands/security.md

@@ -4,22 +4,21 @@
 
 ## Dynamic Dispatch (ADR-044)
 
-Opus scans `git diff --stat` and matches changed files against the `description` fields of all 264 agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
+Opus scans `git diff --stat` and matches changed files against the `description` fields of all agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
 ## Silver Surfer Pre-Scan (ADR-048)
 
-Before agent deployment, the Silver Surfer selects the optimal roster:
+**MANDATORY.** Before deploying any domain agents, launch **Silver Surfer** `subagent_type: Silver Surfer` as a sub-agent. The Surfer reads all agent definitions, assesses the codebase, and returns the optimal roster for this command. This is not optional — skipping the Surfer means the command uses a generic team instead of one tailored to the codebase.
 
-Run: `npx thevoidforge herald --command /security --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**Prompt the Surfer with:** "Command: /security. User args: <user's arguments>. Focus: <focus if provided, otherwise 'none'>. Select the optimal agent roster."
 
-Parse the JSON output. The `roster` array contains agent IDs to deploy alongside this command's lead agents. If the command fails or returns an empty roster, use the hardcoded manifest below.
+**Merge the Surfer's roster** with this command's hardcoded lead agents below. Leads are non-negotiable; the Surfer adds specialists.
 
-**`--focus "topic"`** biases the Surfer toward agents matching the topic.
-**`--light`** skips the Surfer — uses only hardcoded core roster.
-**`--solo`** skips Surfer and all sub-agents — lead only.
+**`--focus "topic"`** — pass to the Surfer as the focus bias.
+**`--light`** — skip the Surfer, use only hardcoded roster below.
+**`--solo`** — skip Surfer and all sub-agents, lead only.
 
 ## Context Setup
 1. Read `/logs/build-state.md` — understand current project state

package/.claude/commands/test.md

@@ -9,22 +9,21 @@
 
 ## Dynamic Dispatch (ADR-044)
 
-Opus scans `git diff --stat` and matches changed files against the `description` fields of all 264 agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
+Opus scans `git diff --stat` and matches changed files against the `description` fields of all agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
 ## Silver Surfer Pre-Scan (ADR-048)
 
-Before agent deployment, the Silver Surfer selects the optimal roster:
+**MANDATORY.** Before deploying any domain agents, launch **Silver Surfer** `subagent_type: Silver Surfer` as a sub-agent. The Surfer reads all agent definitions, assesses the codebase, and returns the optimal roster for this command. This is not optional — skipping the Surfer means the command uses a generic team instead of one tailored to the codebase.
 
-Run: `npx thevoidforge herald --command /test --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**Prompt the Surfer with:** "Command: /test. User args: <user's arguments>. Focus: <focus if provided, otherwise 'none'>. Select the optimal agent roster."
 
-Parse the JSON output. The `roster` array contains agent IDs to deploy alongside this command's lead agents. If the command fails or returns an empty roster, use the hardcoded manifest below.
+**Merge the Surfer's roster** with this command's hardcoded lead agents below. Leads are non-negotiable; the Surfer adds specialists.
 
-**`--focus "topic"`** biases the Surfer toward agents matching the topic.
-**`--light`** skips the Surfer — uses only hardcoded core roster.
-**`--solo`** skips Surfer and all sub-agents — lead only.
+**`--focus "topic"`** — pass to the Surfer as the focus bias.
+**`--light`** — skip the Surfer, use only hardcoded roster below.
+**`--solo`** — skip Surfer and all sub-agents, lead only.
 
 ## Step 0 — Orient
 **Oracle** `subagent_type: Oracle` orients:

package/.claude/commands/ux.md

@@ -4,22 +4,21 @@
 
 ## Dynamic Dispatch (ADR-044)
 
-Opus scans `git diff --stat` and matches changed files against the `description` fields of all 264 agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
+Opus scans `git diff --stat` and matches changed files against the `description` fields of all agents in `.claude/agents/`. Matching specialists launch alongside the core agents below.
 
 **Dispatch control:** `--light` skips dynamic dispatch (core only). `--solo` runs lead agent only.
 
 ## Silver Surfer Pre-Scan (ADR-048)
 
-Before agent deployment, the Silver Surfer selects the optimal roster:
+**MANDATORY.** Before deploying any domain agents, launch **Silver Surfer** `subagent_type: Silver Surfer` as a sub-agent. The Surfer reads all agent definitions, assesses the codebase, and returns the optimal roster for this command. This is not optional — skipping the Surfer means the command uses a generic team instead of one tailored to the codebase.
 
-Run: `npx thevoidforge herald --command /ux --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**Prompt the Surfer with:** "Command: /ux. User args: <user's arguments>. Focus: <focus if provided, otherwise 'none'>. Select the optimal agent roster."
 
-Parse the JSON output. The `roster` array contains agent IDs to deploy alongside this command's lead agents. If the command fails or returns an empty roster, use the hardcoded manifest below.
+**Merge the Surfer's roster** with this command's hardcoded lead agents below. Leads are non-negotiable; the Surfer adds specialists.
 
-**`--focus "topic"`** biases the Surfer toward agents matching the topic.
-**`--light`** skips the Surfer — uses only hardcoded core roster.
-**`--solo`** skips Surfer and all sub-agents — lead only.
+**`--focus "topic"`** — pass to the Surfer as the focus bias.
+**`--light`** — skip the Surfer, use only hardcoded roster below.
+**`--solo`** — skip Surfer and all sub-agents, lead only.
 
 ## Context Setup
 1. Read `/logs/build-state.md` — understand current project state

package/CHANGELOG.md

@@ -6,6 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ---
 
+## [23.7.1] - 2026-04-12
+
+### Changed
+- **Silver Surfer launches as a real Agent sub-process** — no longer shells out to CLI. Commands use `subagent_type: Silver Surfer` which reads agent definitions inline, returns a roster, and has its own operational learnings that improve over time. This is mandatory on every major command — not optional, not skippable.
+- Silver Surfer agent upgraded from Haiku to Sonnet tier (needs to read and reason about agent descriptions, not just classify)
+
+---
+
+## [23.7.0] - 2026-04-12
+
+### The Decount — Dynamic Agent References
+
+### Changed
+- **Eliminated hardcoded agent counts from 30+ files.** Commands, method docs, CLAUDE.md, HOLOCRON.md, ROADMAP.md, SUB_AGENTS.md, and herald.ts now say "all agents" instead of hardcoding a number. Only two files retain the count: `AGENT_CLASSIFICATION.md` (the single source of truth) and `wizard/ui/index.html` (user-facing, with an HTML comment documenting how to compute it).
+- Adding a new agent no longer requires updating 30+ files — just the agent definition and AGENT_CLASSIFICATION.md.
+
+---
+
 ## [23.6.1] - 2026-04-12
 
 ### Fixed

package/CLAUDE.md

@@ -234,7 +234,7 @@ See `/docs/methods/MUSTER.md` for the full Muster Protocol.
 | Deploy Wizard | **Haku** (Anime) | Browser-based deploy wizard, infrastructure provisioning |
 | Setup Wizard | **Gandalf** (Tolkien) | Project scaffolding, initialization, dependency setup |
 
-264 sub-agent names in `/docs/NAMING_REGISTRY.md`. No duplicates across active sessions. All agents materialized as subagent definitions in `.claude/agents/` (ADR-044). Silver Surfer (ADR-048) dispatches the optimal roster via Haiku pre-scan.
+Agent names in `/docs/NAMING_REGISTRY.md` (run `ls .claude/agents/*.md | wc -l` for current count). No duplicates across active sessions. All agents materialized as subagent definitions in `.claude/agents/` (ADR-044). Silver Surfer (ADR-048) dispatches the optimal roster via Haiku pre-scan.
 
 ## Distribution
 

package/HOLOCRON.md

@@ -24,7 +24,7 @@
 
 ### What VoidForge Is
 
-VoidForge is a **methodology framework** for building full-stack applications with Claude Code. It's not a code template — it's a *process* template. Drop in a Product Requirements Document, and a named team of 264 AI agents across 9 fictional universes builds your application through a 13-phase protocol.
+VoidForge is a **methodology framework** for building full-stack applications with Claude Code. It's not a code template — it's a *process* template. Drop in a Product Requirements Document, and a named team of AI agents across 9 fictional universes builds your application through a 13-phase protocol.
 
 **From nothing, everything.**
 
@@ -82,7 +82,7 @@ Every tier includes:
 - **28 slash commands** — `/prd`, `/blueprint`, `/build`, `/qa`, `/test`, `/security`, `/ux`, `/review`, `/deploy`, `/devops`, `/architect`, `/assess`, `/git`, `/void`, `/vault`, `/thumper`, `/assemble`, `/gauntlet`, `/campaign`, `/imagine`, `/debrief`, `/dangerroom`, `/cultivation`, `/grow`, `/current`, `/treasury`, `/portfolio`, `/ai`
 - **13-phase build protocol** — PRD to production with verification gates
 - **18 specialist agent protocols** — Each lead has behavioral directives and a sub-agent roster
-- **264 named characters** — From Tolkien, Marvel, DC, Star Wars, Star Trek, Dune, Anime, Cosmere, and Foundation — each materialized as a subagent definition in `.claude/agents/`
+- **Named characters** — From Tolkien, Marvel, DC, Star Wars, Star Trek, Dune, Anime, Cosmere, and Foundation — each materialized as a subagent definition in `.claude/agents/`
 - **35 code patterns** — Reference implementations with framework adaptations (including E2E testing)
 - **No Stubs Doctrine** — Zero placeholder code. Every file does what it claims. Enforced across all method docs.
 - **E2E browser testing** — Playwright + axe-core. Agents take screenshots, capture console errors, and interact with running applications.
@@ -366,7 +366,7 @@ Each lead has a deep bench. Here are some standouts:
 - **Idaho** keeps the connection alive — the eternal ghola who always returns
 - **Thufir** parses every signal — Mentat precision, a million calculations per second
 
-The full roster of 264 characters lives in `docs/NAMING_REGISTRY.md`. Each agent is materialized as a subagent definition in `.claude/agents/` with model tiering (Opus leads, Sonnet specialists, Haiku scouts) and tool restrictions (Builder, Reviewer, Scout, Adversarial). See `docs/AGENT_CLASSIFICATION.md` for the full manifest.
+The full roster of characters lives in `docs/NAMING_REGISTRY.md`. Each agent is materialized as a subagent definition in `.claude/agents/` with model tiering (Opus leads, Sonnet specialists, Haiku scouts) and tool restrictions (Builder, Reviewer, Scout, Adversarial). See `docs/AGENT_CLASSIFICATION.md` for the full manifest.
 
 ### How Handoffs Work
 

package/VERSION.md

@@ -1,6 +1,6 @@
 # Version
 
-**Current:** 23.6.1
+**Current:** 23.7.1
 
 ## Versioning Scheme
 
@@ -14,6 +14,8 @@ This project uses [Semantic Versioning](https://semver.org/):
 
 | Version | Date | Summary |
 |---------|------|---------|
+| 23.7.1 | 2026-04-12 | Silver Surfer launches as real Agent sub-process (subagent_type: Silver Surfer), not CLI shell-out. Mandatory on every command. |
+| 23.7.0 | 2026-04-12 | The Decount — eliminate hardcoded agent counts from 30+ files. Single source of truth: AGENT_CLASSIFICATION.md. |
 | 23.6.1 | 2026-04-12 | Gauntlet fix: 30+ stale "263 agents" → 264 across commands, methods, docs |
 | 23.6.0 | 2026-04-12 | The Silver Surfer — Herald invocation bridge, CLI subcommand, agent #264, end-to-end dispatch pipeline. ADR-048. Campaign 38. |
 | 23.5.4 | 2026-04-12 | Command-doc sync: build.md Phase 12.75, ux.md screenshots, qa.md dynamic counts |

package/docs/AGENT_CLASSIFICATION.md

@@ -13,7 +13,7 @@
 | Scouts (Haiku, Scout/Reviewer) | 38 |
 | Adversarial (Sonnet, Adversarial) | 15 |
 
-**Note:** The authoritative count from NAMING_REGISTRY.md is 264. All methodology docs updated in M7. ADR-044 and ADR-042 retain their original "259" count as historical records.
+**Note:** This file is the single source of truth for agent counts. Other files reference "all agents" without hardcoding the number — verify with `ls .claude/agents/*.md | wc -l`. ADR-044 and ADR-042 retain their original "259" count as historical records.
 
 ## Tiers (Model Assignment)
 

package/docs/methods/CAMPAIGN.md

@@ -239,7 +239,7 @@ User confirms, redirects, or overrides. On confirm → Step 4.
 
 **Post-infrastructure enforcement gate:** For infrastructure campaigns (deploy targets, CI/CD, monitoring, staging environments): after the infrastructure is provisioned, run `/architect --plan` to verify workflow enforcement gates exist — not just infrastructure existence. Infrastructure without process gates is incomplete.
 
-**Dispatch model (ADR-044):** Per-mission `/assemble` runs SHOULD dispatch phases to sub-agents per `SUB_AGENTS.md` "Parallel Agent Standard." Agents are launched as named subagent types defined in `.claude/agents/` with description-driven dispatch — Opus scans `git diff --stat` and matches changed files against agent descriptions to auto-select specialists. The campaign orchestrator (main thread) manages the mission sequence, inter-mission gates, and campaign state — it does NOT perform inline code analysis. Pass findings summaries between missions, not raw code. See `docs/AGENT_CLASSIFICATION.md` for the full 264-agent manifest. (Field report #270)
+**Dispatch model (ADR-044):** Per-mission `/assemble` runs SHOULD dispatch phases to sub-agents per `SUB_AGENTS.md` "Parallel Agent Standard." Agents are launched as named subagent types defined in `.claude/agents/` with description-driven dispatch — Opus scans `git diff --stat` and matches changed files against agent descriptions to auto-select specialists. The campaign orchestrator (main thread) manages the mission sequence, inter-mission gates, and campaign state — it does NOT perform inline code analysis. Pass findings summaries between missions, not raw code. See `docs/AGENT_CLASSIFICATION.md` for the full agent manifest (see docs/AGENT_CLASSIFICATION.md). (Field report #270)
 
 ### Campaign-Mode Pipeline
 

package/docs/methods/GAUNTLET.md

@@ -18,7 +18,7 @@
 - When the project has significant attack surface (auth, payments, user data, WebSocket, file uploads)
 - Before a public launch or investor demo
 
-**Dispatch model:** All Gauntlet rounds MUST dispatch to sub-agents per `SUB_AGENTS.md` "Parallel Agent Standard." Agents are launched as named subagent types defined in `.claude/agents/` with model tiering (Opus leads, Sonnet specialists, Haiku scouts) and tool restrictions. The main thread manages rounds, triages findings between rounds, and applies fixes — it does NOT read source files or analyze code inline. Each round launches agents in waves of 3 (max concurrent). Findings pass between rounds as summary tables, not raw code. See `docs/AGENT_CLASSIFICATION.md` for the full 264-agent manifest. (Field report #270)
+**Dispatch model:** All Gauntlet rounds MUST dispatch to sub-agents per `SUB_AGENTS.md` "Parallel Agent Standard." Agents are launched as named subagent types defined in `.claude/agents/` with model tiering (Opus leads, Sonnet specialists, Haiku scouts) and tool restrictions. The main thread manages rounds, triages findings between rounds, and applies fixes — it does NOT read source files or analyze code inline. Each round launches agents in waves of 3 (max concurrent). Findings pass between rounds as summary tables, not raw code. See `docs/AGENT_CLASSIFICATION.md` for the full agent manifest (see docs/AGENT_CLASSIFICATION.md). (Field report #270)
 
 **When NOT to use /gauntlet:**
 - During active development (use `/assemble` instead — it includes building)

package/docs/methods/MUSTER.md

@@ -143,7 +143,7 @@ Synthesize all findings:
 
 ## Subagent Definitions (ADR-044)
 
-Muster agents are now launched as named subagent types defined in `.claude/agents/`. Instead of inline prompts, each agent invocation uses `subagent_type: {agent-id}` to reference a materialized definition with model tiering (Opus leads, Sonnet specialists, Haiku scouts) and tool restrictions. See `docs/AGENT_CLASSIFICATION.md` for the full 264-agent classification manifest.
+Muster agents are now launched as named subagent types defined in `.claude/agents/`. Instead of inline prompts, each agent invocation uses `subagent_type: {agent-id}` to reference a materialized definition with model tiering (Opus leads, Sonnet specialists, Haiku scouts) and tool restrictions. See `docs/AGENT_CLASSIFICATION.md` for the full agent classification manifest.
 
 ## Cost Awareness
 

package/docs/methods/QA_ENGINEER.md

@@ -27,7 +27,7 @@
 
 ## Dynamic Dispatch (ADR-044)
 
-Agent dispatch is now description-driven. When Opus processes a command, it scans `git diff --stat` and matches changed files against the `description` fields of all 264 agents in `.claude/agents/`. Matching specialists launch automatically alongside core agents. No static dispatch tables needed.
+Agent dispatch is now description-driven. When Opus processes a command, it scans `git diff --stat` and matches changed files against the `description` fields of all agents in `.claude/agents/`. Matching specialists launch automatically alongside core agents. No static dispatch tables needed.
 
 See `docs/AGENT_CLASSIFICATION.md` for the full classification and `docs/adrs/ADR-044-subagent-materialization.md` for the architecture.
 

package/docs/methods/SECURITY_AUDITOR.md

@@ -28,7 +28,7 @@
 
 ## Dynamic Dispatch (ADR-044)
 
-Agent dispatch is now description-driven. When Opus processes a command, it scans `git diff --stat` and matches changed files against the `description` fields of all 264 agents in `.claude/agents/`. Matching specialists launch automatically alongside core agents. No static dispatch tables needed.
+Agent dispatch is now description-driven. When Opus processes a command, it scans `git diff --stat` and matches changed files against the `description` fields of all agents in `.claude/agents/`. Matching specialists launch automatically alongside core agents. No static dispatch tables needed.
 
 See `docs/AGENT_CLASSIFICATION.md` for the full classification and `docs/adrs/ADR-044-subagent-materialization.md` for the architecture.
 

package/docs/methods/SUB_AGENTS.md

@@ -10,7 +10,7 @@ Parallelize development across multiple Claude Code sessions. Each session runs
 
 **All orchestration uses the build journal.** Every delegation, handoff, and resolution is logged to `/logs/handoffs.md`. Agents read journal files to recover context. See `/docs/methods/BUILD_JOURNAL.md`.
 
-**Full character roster: `/docs/NAMING_REGISTRY.md`** — 264 named characters across 9 universes. No duplicates allowed. All agents materialized as subagent definitions in `.claude/agents/`.
+**Full character roster: `/docs/NAMING_REGISTRY.md`** — all named characters across 9 universes. No duplicates allowed. All agents materialized as subagent definitions in `.claude/agents/`.
 
 ---
 
@@ -176,7 +176,7 @@ Users can create project-specific sub-agents that carry domain knowledge. Define
 
 ## Subagent Definitions (ADR-044)
 
-All 264 agents are materialized as `.claude/agents/{name}.md` files. Commands now use `subagent_type: {agent-id}` instead of inline prompts. Each definition contains the agent's identity, behavioral directives, domain expertise, and output format.
+All agents are materialized as `.claude/agents/{name}.md` files. Commands now use `subagent_type: {agent-id}` instead of inline prompts. Each definition contains the agent's identity, behavioral directives, domain expertise, and output format.
 
 ### The `.claude/agents/` Directory
 
@@ -206,7 +206,7 @@ Leads inherit the main session's model (Opus). Specialists run on Sonnet for cos
 Commands no longer use static dispatch tables (the old ADR-042 Cross-Domain Triggers). Instead, when Opus processes a command, it:
 
 1. Scans `git diff --stat` to identify changed files
-2. Matches changed file paths against the `description` fields of all 264 agents
+2. Matches changed file paths against the `description` fields of all agents
 3. Launches matching specialists automatically alongside core agents
 
 This means a security audit that touches database migrations automatically picks up Spock (schema) without a hardcoded trigger table. The descriptions in `.claude/agents/*.md` ARE the dispatch rules.

package/docs/methods/SYSTEMS_ARCHITECT.md

@@ -25,7 +25,7 @@
 
 ## Dynamic Dispatch (ADR-044)
 
-Agent dispatch is now description-driven. When Opus processes a command, it scans `git diff --stat` and matches changed files against the `description` fields of all 264 agents in `.claude/agents/`. Matching specialists launch automatically alongside core agents. No static dispatch tables needed.
+Agent dispatch is now description-driven. When Opus processes a command, it scans `git diff --stat` and matches changed files against the `description` fields of all agents in `.claude/agents/`. Matching specialists launch automatically alongside core agents. No static dispatch tables needed.
 
 See `docs/AGENT_CLASSIFICATION.md` for the full classification and `docs/adrs/ADR-044-subagent-materialization.md` for the architecture.
 

package/package.json

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