thevoidforge-methodology 23.7.0 → 23.7.2

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

@@ -17,16 +17,17 @@ 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 the Silver Surfer as a sub-agent to select the optimal roster for this command. **Do NOT skip this step.**
 
-Run: `npx thevoidforge herald --command /ai --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**How to launch:** Use the Agent tool with these exact parameters:
+- `description`: "Silver Surfer roster scan"
+- `prompt`: "You are the Silver Surfer, Herald of Galactus. Read your instructions from .claude/agents/silver-surfer-herald.md, then execute your task. Command: /ai. User args: <ARGS>. Focus: <FOCUS or 'none'>. Scan the .claude/agents/ directory, read agent descriptions and tags, and return the optimal roster for this command on this codebase."
 
-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.
+**After the Surfer returns**, merge its 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"`** — include in the Surfer's prompt 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

@@ -12,16 +12,17 @@ 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 the Silver Surfer as a sub-agent to select the optimal roster for this command. **Do NOT skip this step.**
 
-Run: `npx thevoidforge herald --command /architect --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**How to launch:** Use the Agent tool with these exact parameters:
+- `description`: "Silver Surfer roster scan"
+- `prompt`: "You are the Silver Surfer, Herald of Galactus. Read your instructions from .claude/agents/silver-surfer-herald.md, then execute your task. Command: /architect. User args: <ARGS>. Focus: <FOCUS or 'none'>. Scan the .claude/agents/ directory, read agent descriptions and tags, and return the optimal roster for this command on this codebase."
 
-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.
+**After the Surfer returns**, merge its 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"`** — include in the Surfer's prompt 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

@@ -15,16 +15,17 @@ 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 the Silver Surfer as a sub-agent to select the optimal roster for this command. **Do NOT skip this step.**
 
-Run: `npx thevoidforge herald --command /assemble --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**How to launch:** Use the Agent tool with these exact parameters:
+- `description`: "Silver Surfer roster scan"
+- `prompt`: "You are the Silver Surfer, Herald of Galactus. Read your instructions from .claude/agents/silver-surfer-herald.md, then execute your task. Command: /assemble. User args: <ARGS>. Focus: <FOCUS or 'none'>. Scan the .claude/agents/ directory, read agent descriptions and tags, and return the optimal roster for this command on this codebase."
 
-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.
+**After the Surfer returns**, merge its 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"`** — include in the Surfer's prompt 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,17 @@ 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 the Silver Surfer as a sub-agent to select the optimal roster for this command. **Do NOT skip this step.**
 
-Run: `npx thevoidforge herald --command /assess --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**How to launch:** Use the Agent tool with these exact parameters:
+- `description`: "Silver Surfer roster scan"
+- `prompt`: "You are the Silver Surfer, Herald of Galactus. Read your instructions from .claude/agents/silver-surfer-herald.md, then execute your task. Command: /assess. User args: <ARGS>. Focus: <FOCUS or 'none'>. Scan the .claude/agents/ directory, read agent descriptions and tags, and return the optimal roster for this command on this codebase."
 
-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.
+**After the Surfer returns**, merge its 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"`** — include in the Surfer's prompt 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

@@ -12,16 +12,17 @@ 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 the Silver Surfer as a sub-agent to select the optimal roster for this command. **Do NOT skip this step.**
 
-Run: `npx thevoidforge herald --command /build --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**How to launch:** Use the Agent tool with these exact parameters:
+- `description`: "Silver Surfer roster scan"
+- `prompt`: "You are the Silver Surfer, Herald of Galactus. Read your instructions from .claude/agents/silver-surfer-herald.md, then execute your task. Command: /build. User args: <ARGS>. Focus: <FOCUS or 'none'>. Scan the .claude/agents/ directory, read agent descriptions and tags, and return the optimal roster for this command on this codebase."
 
-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.
+**After the Surfer returns**, merge its 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"`** — include in the Surfer's prompt 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

@@ -55,16 +55,17 @@ 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 the Silver Surfer as a sub-agent to select the optimal roster for this command. **Do NOT skip this step.**
 
-Run: `npx thevoidforge herald --command /campaign --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**How to launch:** Use the Agent tool with these exact parameters:
+- `description`: "Silver Surfer roster scan"
+- `prompt`: "You are the Silver Surfer, Herald of Galactus. Read your instructions from .claude/agents/silver-surfer-herald.md, then execute your task. Command: /campaign. User args: <ARGS>. Focus: <FOCUS or 'none'>. Scan the .claude/agents/ directory, read agent descriptions and tags, and return the optimal roster for this command on this codebase."
 
-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.
+**After the Surfer returns**, merge its 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"`** — include in the Surfer's prompt 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,17 @@ 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 the Silver Surfer as a sub-agent to select the optimal roster for this command. **Do NOT skip this step.**
 
-Run: `npx thevoidforge herald --command /deploy --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**How to launch:** Use the Agent tool with these exact parameters:
+- `description`: "Silver Surfer roster scan"
+- `prompt`: "You are the Silver Surfer, Herald of Galactus. Read your instructions from .claude/agents/silver-surfer-herald.md, then execute your task. Command: /deploy. User args: <ARGS>. Focus: <FOCUS or 'none'>. Scan the .claude/agents/ directory, read agent descriptions and tags, and return the optimal roster for this command on this codebase."
 
-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.
+**After the Surfer returns**, merge its 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"`** — include in the Surfer's prompt 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

@@ -13,16 +13,17 @@ 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 the Silver Surfer as a sub-agent to select the optimal roster for this command. **Do NOT skip this step.**
 
-Run: `npx thevoidforge herald --command /devops --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**How to launch:** Use the Agent tool with these exact parameters:
+- `description`: "Silver Surfer roster scan"
+- `prompt`: "You are the Silver Surfer, Herald of Galactus. Read your instructions from .claude/agents/silver-surfer-herald.md, then execute your task. Command: /devops. User args: <ARGS>. Focus: <FOCUS or 'none'>. Scan the .claude/agents/ directory, read agent descriptions and tags, and return the optimal roster for this command on this codebase."
 
-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.
+**After the Surfer returns**, merge its 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"`** — include in the Surfer's prompt 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

@@ -17,16 +17,17 @@ 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 the Silver Surfer as a sub-agent to select the optimal roster for this command. **Do NOT skip this step.**
 
-Run: `npx thevoidforge herald --command /gauntlet --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**How to launch:** Use the Agent tool with these exact parameters:
+- `description`: "Silver Surfer roster scan"
+- `prompt`: "You are the Silver Surfer, Herald of Galactus. Read your instructions from .claude/agents/silver-surfer-herald.md, then execute your task. Command: /gauntlet. User args: <ARGS>. Focus: <FOCUS or 'none'>. Scan the .claude/agents/ directory, read agent descriptions and tags, and return the optimal roster for this command on this codebase."
 
-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.
+**After the Surfer returns**, merge its 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"`** — include in the Surfer's prompt 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

@@ -12,16 +12,17 @@ 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 the Silver Surfer as a sub-agent to select the optimal roster for this command. **Do NOT skip this step.**
 
-Run: `npx thevoidforge herald --command /qa --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**How to launch:** Use the Agent tool with these exact parameters:
+- `description`: "Silver Surfer roster scan"
+- `prompt`: "You are the Silver Surfer, Herald of Galactus. Read your instructions from .claude/agents/silver-surfer-herald.md, then execute your task. Command: /qa. User args: <ARGS>. Focus: <FOCUS or 'none'>. Scan the .claude/agents/ directory, read agent descriptions and tags, and return the optimal roster for this command on this codebase."
 
-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.
+**After the Surfer returns**, merge its 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"`** — include in the Surfer's prompt 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

@@ -10,16 +10,17 @@ 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 the Silver Surfer as a sub-agent to select the optimal roster for this command. **Do NOT skip this step.**
 
-Run: `npx thevoidforge herald --command /review --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**How to launch:** Use the Agent tool with these exact parameters:
+- `description`: "Silver Surfer roster scan"
+- `prompt`: "You are the Silver Surfer, Herald of Galactus. Read your instructions from .claude/agents/silver-surfer-herald.md, then execute your task. Command: /review. User args: <ARGS>. Focus: <FOCUS or 'none'>. Scan the .claude/agents/ directory, read agent descriptions and tags, and return the optimal roster for this command on this codebase."
 
-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.
+**After the Surfer returns**, merge its 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"`** — include in the Surfer's prompt 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

@@ -10,16 +10,17 @@ 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 the Silver Surfer as a sub-agent to select the optimal roster for this command. **Do NOT skip this step.**
 
-Run: `npx thevoidforge herald --command /security --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**How to launch:** Use the Agent tool with these exact parameters:
+- `description`: "Silver Surfer roster scan"
+- `prompt`: "You are the Silver Surfer, Herald of Galactus. Read your instructions from .claude/agents/silver-surfer-herald.md, then execute your task. Command: /security. User args: <ARGS>. Focus: <FOCUS or 'none'>. Scan the .claude/agents/ directory, read agent descriptions and tags, and return the optimal roster for this command on this codebase."
 
-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.
+**After the Surfer returns**, merge its 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"`** — include in the Surfer's prompt 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

@@ -15,16 +15,17 @@ 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 the Silver Surfer as a sub-agent to select the optimal roster for this command. **Do NOT skip this step.**
 
-Run: `npx thevoidforge herald --command /test --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**How to launch:** Use the Agent tool with these exact parameters:
+- `description`: "Silver Surfer roster scan"
+- `prompt`: "You are the Silver Surfer, Herald of Galactus. Read your instructions from .claude/agents/silver-surfer-herald.md, then execute your task. Command: /test. User args: <ARGS>. Focus: <FOCUS or 'none'>. Scan the .claude/agents/ directory, read agent descriptions and tags, and return the optimal roster for this command on this codebase."
 
-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.
+**After the Surfer returns**, merge its 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"`** — include in the Surfer's prompt 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

@@ -10,16 +10,17 @@ 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 the Silver Surfer as a sub-agent to select the optimal roster for this command. **Do NOT skip this step.**
 
-Run: `npx thevoidforge herald --command /ux --json`
-(Add `--focus "<topic>"` if the user provided `--focus`)
+**How to launch:** Use the Agent tool with these exact parameters:
+- `description`: "Silver Surfer roster scan"
+- `prompt`: "You are the Silver Surfer, Herald of Galactus. Read your instructions from .claude/agents/silver-surfer-herald.md, then execute your task. Command: /ux. User args: <ARGS>. Focus: <FOCUS or 'none'>. Scan the .claude/agents/ directory, read agent descriptions and tags, and return the optimal roster for this command on this codebase."
 
-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.
+**After the Surfer returns**, merge its 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"`** — include in the Surfer's prompt 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,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ---
 
+## [23.7.2] - 2026-04-12
+
+### Fixed
+- **Silver Surfer invocation made explicit and guaranteed** — commands now provide exact Agent tool parameters (`description` + `prompt` with `.claude/agents/silver-surfer-herald.md` read instruction) instead of the non-functional `subagent_type: Silver Surfer`. Works 100% of the time in every Claude Code environment.
+
+---
+
+## [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

package/VERSION.md

@@ -1,6 +1,6 @@
 # Version
 
-**Current:** 23.7.0
+**Current:** 23.7.2
 
 ## Versioning Scheme
 
@@ -14,6 +14,8 @@ This project uses [Semantic Versioning](https://semver.org/):
 
 | Version | Date | Summary |
 |---------|------|---------|
+| 23.7.2 | 2026-04-12 | Silver Surfer explicit Agent tool invocation — guaranteed to work in every environment |
+| 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. |

package/package.json

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