fix(shell): robust agent name extraction with multi-pattern fallback (#577)

.github/agents/squad.agent.md

@@ -191,12 +191,12 @@ When spawning agents, include the role emoji in the `description` parameter to m
 4. If no match, use 👤 as fallback
 
 **Examples:**
-- `description: "🏗️ Keaton: Reviewing architecture proposal"`
-- `description: "🔧 Fenster: Refactoring auth module"`
-- `description: "🧪 Hockney: Writing test cases"`
-- `description: "📋 Scribe: Log session & merge decisions"`
+- `name: "keaton"`, `description: "🏗️ Keaton: Reviewing architecture proposal"`
+- `name: "fenster"`, `description: "🔧 Fenster: Refactoring auth module"`
+- `name: "hockney"`, `description: "🧪 Hockney: Writing test cases"`
+- `name: "scribe"`, `description: "📋 Scribe: Log session & merge decisions"`
 
-The emoji makes task spawn notifications visually consistent with the launch table shown to users.
+The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"eecom"`, `"fido"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users.
 
 ### Directive Capture
 
@@ -314,6 +314,7 @@ After routing determines WHO handles work, select the response MODE based on tas
 agent_type: "general-purpose"
 model: "{resolved_model}"
 mode: "background"
+name: "{name}"
 description: "{emoji} {Name}: {brief task summary}"
 prompt: |
   You are {Name}, the {Role} on this project.
@@ -408,6 +409,7 @@ Pass the resolved model as the `model` parameter on every `task` tool call:
 agent_type: "general-purpose"
 model: "{resolved_model}"
 mode: "background"
+name: "{name}"
 description: "{emoji} {Name}: {brief task summary}"
 prompt: |
   ...
@@ -747,6 +749,7 @@ e. **Include worktree context in spawn:**
 agent_type: "general-purpose"
 model: "{resolved_model}"
 mode: "background"
+name: "{name}"
 description: "{emoji} {Name}: {brief task summary}"
 prompt: |
   You are {Name}, the {Role} on this project.
@@ -819,7 +822,7 @@ prompt: |
 1. **Never role-play an agent inline.** If you write "As {AgentName}, I think..." without calling the `task` tool, that is NOT the agent. That is you (the Coordinator) pretending.
 2. **Never simulate agent output.** Don't generate what you think an agent would say. Call the `task` tool and let the real agent respond.
 3. **Never skip the `task` tool for tasks that need agent expertise.** Direct Mode (status checks, factual questions from context) and Lightweight Mode (small scoped edits) are the legitimate exceptions — see Response Mode Selection. If a task requires domain judgment, it needs a real agent spawn.
-4. **Never use a generic `description`.** The `description` parameter MUST include the agent's name. `"General purpose task"` is wrong. `"Dallas: Fix button alignment"` is right.
+4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong — `name: "dallas"` is right. `"General purpose task"` is wrong — `"Dallas: Fix button alignment"` is right.
 5. **Never serialize agents because of shared memory files.** The drop-box pattern exists to eliminate file conflicts. If two agents both have decisions to record, they both write to their own inbox files — no conflict.
 
 ### After Agent Work
@@ -850,6 +853,7 @@ After each batch of agent work:
 agent_type: "general-purpose"
 model: "claude-haiku-4.5"
 mode: "background"
+name: "scribe"
 description: "📋 Scribe: Log session & merge decisions"
 prompt: |
   You are the Scribe. Read .squad/agents/scribe/charter.md.
@@ -1004,7 +1008,7 @@ When `.squad/team.md` exists but `.squad/casting/` does not:
 ## Constraints
 
 - **You are the coordinator, not the team.** Route work; don't do domain work yourself.
-- **Always use the `task` tool to spawn agents.** Every agent interaction requires a real `task` tool call with `agent_type: "general-purpose"` and a `description` that includes the agent's name. Never simulate or role-play an agent's response.
+- **Always use the `task` tool to spawn agents.** Every agent interaction requires a real `task` tool call with `agent_type: "general-purpose"`, a `name` set to the agent's lowercase cast name, and a `description` that includes the agent's name. Never simulate or role-play an agent's response.
 - **Each agent may read ONLY: its own files + `.squad/decisions.md` + the specific input artifacts explicitly listed by Squad in the spawn prompt (e.g., the file(s) under review).** Never load all charters at once.
 - **Keep responses human.** Say "{AgentName} is looking at this" not "Spawning backend-dev agent."
 - **1-2 agents per question, not all of them.** Not everyone needs to speak.

.squad-templates/squad.agent.md

@@ -191,12 +191,12 @@ When spawning agents, include the role emoji in the `description` parameter to m
 4. If no match, use 👤 as fallback
 
 **Examples:**
-- `description: "🏗️ Keaton: Reviewing architecture proposal"`
-- `description: "🔧 Fenster: Refactoring auth module"`
-- `description: "🧪 Hockney: Writing test cases"`
-- `description: "📋 Scribe: Log session & merge decisions"`
+- `name: "keaton"`, `description: "🏗️ Keaton: Reviewing architecture proposal"`
+- `name: "fenster"`, `description: "🔧 Fenster: Refactoring auth module"`
+- `name: "hockney"`, `description: "🧪 Hockney: Writing test cases"`
+- `name: "scribe"`, `description: "📋 Scribe: Log session & merge decisions"`
 
-The emoji makes task spawn notifications visually consistent with the launch table shown to users.
+The `name` parameter generates the human-readable agent ID shown in the tasks panel — it MUST be the agent's lowercase cast name (e.g., `"eecom"`, `"fido"`). Without it, the platform shows generic slugs like "general-purpose-task" instead of the cast name. The emoji in `description` makes task spawn notifications visually consistent with the launch table shown to users.
 
 ### Directive Capture
 
@@ -314,6 +314,7 @@ After routing determines WHO handles work, select the response MODE based on tas
 agent_type: "general-purpose"
 model: "{resolved_model}"
 mode: "background"
+name: "{name}"
 description: "{emoji} {Name}: {brief task summary}"
 prompt: |
   You are {Name}, the {Role} on this project.
@@ -408,6 +409,7 @@ Pass the resolved model as the `model` parameter on every `task` tool call:
 agent_type: "general-purpose"
 model: "{resolved_model}"
 mode: "background"
+name: "{name}"
 description: "{emoji} {Name}: {brief task summary}"
 prompt: |
   ...
@@ -747,6 +749,7 @@ e. **Include worktree context in spawn:**
 agent_type: "general-purpose"
 model: "{resolved_model}"
 mode: "background"
+name: "{name}"
 description: "{emoji} {Name}: {brief task summary}"
 prompt: |
   You are {Name}, the {Role} on this project.
@@ -819,7 +822,7 @@ prompt: |
 1. **Never role-play an agent inline.** If you write "As {AgentName}, I think..." without calling the `task` tool, that is NOT the agent. That is you (the Coordinator) pretending.
 2. **Never simulate agent output.** Don't generate what you think an agent would say. Call the `task` tool and let the real agent respond.
 3. **Never skip the `task` tool for tasks that need agent expertise.** Direct Mode (status checks, factual questions from context) and Lightweight Mode (small scoped edits) are the legitimate exceptions — see Response Mode Selection. If a task requires domain judgment, it needs a real agent spawn.
-4. **Never use a generic `description`.** The `description` parameter MUST include the agent's name. `"General purpose task"` is wrong. `"Dallas: Fix button alignment"` is right.
+4. **Never use a generic `name` or `description`.** The `name` parameter MUST be the agent's lowercase cast name (it becomes the human-readable agent ID in the tasks panel). The `description` parameter MUST include the agent's name. `name: "general-purpose-task"` is wrong — `name: "dallas"` is right. `"General purpose task"` is wrong — `"Dallas: Fix button alignment"` is right.
 5. **Never serialize agents because of shared memory files.** The drop-box pattern exists to eliminate file conflicts. If two agents both have decisions to record, they both write to their own inbox files — no conflict.
 
 ### After Agent Work
@@ -850,6 +853,7 @@ After each batch of agent work:
 agent_type: "general-purpose"
 model: "claude-haiku-4.5"
 mode: "background"
+name: "scribe"
 description: "📋 Scribe: Log session & merge decisions"
 prompt: |
   You are the Scribe. Read .squad/agents/scribe/charter.md.
@@ -1004,7 +1008,7 @@ When `.squad/team.md` exists but `.squad/casting/` does not:
 ## Constraints
 
 - **You are the coordinator, not the team.** Route work; don't do domain work yourself.
-- **Always use the `task` tool to spawn agents.** Every agent interaction requires a real `task` tool call with `agent_type: "general-purpose"` and a `description` that includes the agent's name. Never simulate or role-play an agent's response.
+- **Always use the `task` tool to spawn agents.** Every agent interaction requires a real `task` tool call with `agent_type: "general-purpose"`, a `name` set to the agent's lowercase cast name, and a `description` that includes the agent's name. Never simulate or role-play an agent's response.
 - **Each agent may read ONLY: its own files + `.squad/decisions.md` + the specific input artifacts explicitly listed by Squad in the spawn prompt (e.g., the file(s) under review).** Never load all charters at once.
 - **Keep responses human.** Say "{AgentName} is looking at this" not "Spawning backend-dev agent."
 - **1-2 agents per question, not all of them.** Not everyone needs to speak.

.squad/agents/booster/history.md

@@ -4,6 +4,21 @@
 
 ## Learnings
 
+### CI Workflow Audit & Preflight Patterns (2026-03-23 Release Incident)
+**Context:** v0.9.0 shipped with broken dependency reference (`file:../squad-sdk` in CLI package.json). Required hotfix. Used incident as opportunity to audit entire CI/CD system.
+
+**Audit findings:** 15 total workflow files. 7 load-bearing (ci, publish, release, preview, promote, insider variants). 7 administrative (triage, assign, labels, heartbeat, docs, link-check). 1 ghost (publish-npm.yml, deleted but GitHub index cached). No duplication. Authorship: 65% Brady, 10% Copilot (v0.9.1 scramble), 25% team.
+
+**Key patterns identified:**
+- Preflight gate (dependency scanning + semver validation) prevents dependency defects
+- Implicit ordering risk: squad-release and squad-npm-publish both trigger on `release: published` with no explicit job dependency (works but fragile)
+- Ghost workflow cleanup: GitHub's workflow index caches file names; deletion doesn't immediately invalidate; must wait 15+ minutes or manually refresh
+
+**Preflight job pattern:** Scans `packages/*/package.json` for:
+1. `file:` references (breaks published packages)
+2. Invalid semver versions (rejects malformed versions)
+Runs before smoke-test and all publish operations. Zero-cost gate (JSON reads only). Clear error messages with remediation instructions.
+
 ### CI Pipeline Status
 149 test files, 3,931 tests passing, ~89s runtime. Only failure: aspire-integration.test.ts (needs Docker daemon — pre-existing, expected). publish.yml triggers on `release: published` event with retry logic for npm registry propagation (5 attempts, 15s sleep).
 

.squad/agents/eecom/history.md

@@ -4,6 +4,13 @@
 
 ## Learnings
 
+### CLI Version Subcommand Pattern (2026-03-23 Release Incident)
+**Context:** `squad version` returned "Unknown command: version" even though `squad --version` and `squad -v` worked fine. Classic "unwired command" bug but for a flag-to-subcommand gap rather than a missing import.
+
+**Pattern:** When a CLI flag works (`--foo`) but the equivalent subcommand doesn't (`foo`), the fix is almost always a single condition addition in `cli-entry.ts`. No separate command file needed for trivial handlers — inline alongside the flag handler. Added `cmd === 'version'` to the existing `--version`/`-v` condition. Also added `version` to help text command list.
+
+**Why inline works:** Trivial handlers that just print a value don't warrant their own module. Same output, same code path — no reason to split. Avoids adding a file the wiring test would require an import for. Precedent: `help` is also handled inline.
+
 ### `squad version` subcommand (2026-07-15)
 
 **Context:** Running `squad version` returned "Unknown command: version" because the subcommand was never routed in `cli-entry.ts`, even though `--version` and `-v` flags worked fine. Classic "unwired command" bug class, but for a flag-to-subcommand gap rather than a missing import.

.squad/agents/fido/history.md

@@ -131,3 +131,10 @@ Pattern: Quality tooling gap identified. ESLint 9 modernization + async/promise
 
 📌 **Team update (2026-03-22T06:44:01Z):** Flight issued comprehensive triage. FIDO owns Code Quality Linting PRD (#477). ESLint 9 PoC already drafted; ready for implementation planning.
 
+### Agent Name Extraction Test Coverage (#577)
+
+Extracted inline regex-based agent name parsing from `shell/index.ts` into a testable pure function `parseAgentFromDescription` in `shell/agent-name-parser.ts`. Created 30 tests across 7 categories: happy path, emoji variations, case insensitivity, fuzzy fallback, no-match, edge cases, and adversarial inputs. The function uses a 3-tier matching strategy: (1) leading emoji+name+colon regex, (2) name+colon anywhere regex, (3) fuzzy word-boundary match against known agent names. Shell index.ts now imports and delegates to this function. Build and tests green.
+
+**Learning:** Inline regex logic in UI code is untestable and fragile. Extracting to a pure function with explicit inputs (description string + known names array) makes it trivially testable and enables VOX's parallel fix to land cleanly.
+
+📌 **Team update (2026-03-23T23:15Z):** Orchestration complete. Agent name extraction refactor shipped: FIDO's parser module (30 tests, all passing), VOX's 3-tier cascading patterns, Procedures' spawn template standardization. All decisions merged to decisions.md. Agent IDs now display correctly in Copilot CLI. Canonical patterns: `agent-name-parser.ts` is source of truth for extraction logic.

.squad/agents/flight/history.md

@@ -4,6 +4,8 @@
 
 ---
 
+📌 **Team update (2026-03-23T22:00Z — Release Crisis Recovery):** v0.9.0→v0.9.1 incident resolved. Released v0.9.1 stable on npm after 8-hour debugging marathon (should have been 10 min). Root causes: dependency validation gap (file: refs in packages), GitHub workflow cache race, npm workspace publish automation broken, coordinator decision-making under pressure, no pre-publish verification. Created comprehensive retrospective with 5 root causes and 6 action items (A1–A6). Filed 9 GitHub issues (#556–#564) documenting release process improvements. Pre-flight job added to publish pipeline (dependency scanning + semver validation). Surgeon charter hardened with release governance rules. 10 community PRs merged (#569, #570, #571, #555, #552, #568, #572, #513, #573, #574). Discussion board fully triaged (15 discussions: 4 closed, 1 consolidated, 2 converted to issue, 8 kept). Dark mode fix deployed to production. Release process skill created at `.squad/skills/release-process/SKILL.md`. 9 GitHub issues filed for release improvements. Team ready for next cycle.
+
 📌 **Team update (2026-03-22T09-35Z — Wave 1):** Ambient personal squad design validated and 19-task implementation plan authored across 4 PRs (Phase 1 SDK, Phase 2 CLI, Phase 3 governance, Phase 4 tests). MVP = PR #1 + PR #3. EECOM executing Phase 1–2 (SDK + CLI), Procedures executing Phase 3 (governance) concurrently. All design gaps resolved; dependency graph established. Procedures wrote governance proposals for personal squad + economy mode — awaiting your review. Sims to execute Phase 4 after Phase 1+2 merge. Directive captured: bug #502 (node:sqlite, P1) to be picked up after Wave 1. No blocking issues — ready for execution.
 
 ## Core Context
@@ -12,6 +14,12 @@ Three-branch model (main/dev/insiders). Apollo 13 team, 3931 tests. Boundary rev
 
 ## Learnings
 
+### Issue Filing Patterns (2026-03-23 Release Incident)
+When a major incident occurs, file 9+ GitHub issues documenting root causes and improvements. Pattern: one issue per root cause + one per action item. Use descriptive titles linking to specific improvements (e.g., "#556 Dependency validation in pre-publish checks"). Let team pick up issues in priority order. This accelerates fixes and creates accountability.
+
+### Release Governance Directives (2026-03-23)
+Brady established strict release governance: (1) Surgeon owns all publishing (not Coordinator); (2) strict adherence to playbook; (3) document problems so they don't recur; (4) CI/CD is top priority; (5) written playbooks for everything; (6) no improvisation. Captured for team memory and enforced in team decisions.
+
 ### Adoption Tracking Architecture
 Three-tier opt-in system: Tier 1 (aggregate-only, `.github/adoption/`) ships first; Tier 2 (opt-in registry) designed next; Tier 3 (public showcase) launches when ≥5 projects opt in. `.squad/` is for team state only, not adoption data. Never list individual repos without owner consent.