Orchestration commands

Four commands are available in the platform repo session. All live in D:\git\platform\.claude\commands\.

---

/dispatch

Classify a task, resolve target repos from master-registry.db, spawn the right validators and the security gate, and aggregate a status report.

Syntax:

/dispatch                          # all pilot repos, all types
/dispatch iac-terraform            # all repos of type iac-terraform
/dispatch turner-infrastructure    # one specific repo by registry name
/dispatch --dry-run                # show wave plan without running any agents

What it does:

1. Reads master-registry.db to identify target repos.
2. For each target repo, reads its validation_profile → reads profiles/<type>.yaml → extracts the ordered check list.
3. Groups repos into waves (max 8 concurrent, max 1 per repo per wave).
4. For each wave: spawns the appropriate validator agents in parallel.
5. After structural validators pass for a repo, spawns security-waf-caf.
6. Emits a status report in this format:

STATUS — Wave N of M
Repos: X total | Y passed | Z failed | W in-progress
---
PASSED:  <repo-name> (<type>) — all checks green
FAILED:  <repo-name> (<type>) — <check-id>: <one-line finding>
BLOCKED: <repo-name> — <reason> | ACTION: <recommendation>

Hard rules:

• Nothing passes without security-waf-caf approval. No exceptions.
• A repo that fails any structural validator does NOT proceed to the security gate.
• Max 8 concurrent agents, max 1 per repo.

---

/sweep

Run a cross-repo read-only scan. Used for pattern discovery, drift detection, or bulk analysis without running the full validator stack.

Syntax:

/sweep <dimension>

Example dimensions:

/sweep caf-naming               # check CAF naming patterns across all terraform repos
/sweep secrets-grep             # scan for hardcoded secret patterns
/sweep docs-style               # check docs repos for MkDocs admonition syntax drift
/sweep module-header-check      # check PS script header conformance

What it does:

• Routes the dimension to the appropriate agents (validator or reviewer).
• For high-volume scans, routes to gemini-runner to use the Gemini REST API.
• Returns a summary of findings organized by repo.
• Does NOT run security-waf-caf (sweep is advisory/read-only).

---

/second-opinion

Send a single artifact (file, diff, or snippet) to Gemini for an independent second-opinion analysis.

Syntax:

/second-opinion <file-path> [-- <question>]

Examples:

/second-opinion main.tf -- "Any WAF security concerns with this configuration?"
/second-opinion scripts/Deploy-Environment.ps1
/second-opinion .github/workflows/ci.yml -- "Is this pipeline least-privilege?"

What it does:

1. Reads the specified file.
2. Passes the file content + question to gemini-runner, which calls scripts/Invoke-HCSGeminiPrompt.ps1.
3. The script resolves the Gemini API key from kv-hcs-vault-01 at runtime.
4. Returns the Gemini response as-is.

Prerequisites:

• kv-hcs-vault-01 must have the gemini-api-key secret set (done in Phase 0b).
• Google AI account must have billing enabled (free-tier quota = 0).
• Azure CLI session must be authenticated (az login) so the key can be resolved.

See Gemini integration for setup details.

---

/persona

List available personas or switch the orchestration PM's active persona.

Syntax:

/persona                # list available personas, show which is active
/persona <name>         # switch to the named persona

Examples:

/persona                # shows: jarvis (active), neutral, brain
/persona neutral        # switches to neutral professional voice
/persona jarvis         # switches back to J.A.R.V.I.S.

What it does:

• /persona with no argument: reads all .md files in .claude/agents/personas/, reads ACTIVE, and displays the list with the active one marked.
• /persona <name>: validates that .claude/agents/personas/<name>.md exists, then writes <name> to .claude/agents/personas/ACTIVE. The change takes effect on the next orchestration PM session start.

Rules:

• If the named persona file does not exist, the command lists available personas and stops — it does NOT write ACTIVE.
• Switching persona does NOT change orchestration behavior. Wave limits, gate rules, and dispatch logic are invariant. Only the PM's voice and sign-off change.

See Personas for the available personalities.