[automagik-genie]

Closes #1166. Carved-out doc deliverable from the `tui-spawn-dx` wish (PR #1172). Code-only — zero `.ts`/`.tsx`/`.js` in the diff; all changes under `docs/`.

Summary

Documents the single-verb state-gated spawn semantics and the five-tier team-resolution precedence that landed across PRs #1164 (tmux fallback), #1172 (four-tier resolver), and `40ec8bbd` + #1174 (on-disk fallback + auto-team-of-one). The canonical-UUID-per-name invariant established by `perfect-spawn-hierarchy` / `fix-ghost-approval-p0` is now discoverable from the docs rather than only from source.

Files

• New: `docs/SPAWN-TEAM-RESOLUTION.md` — single-source page for the four identities (canonical / parallel / team / generic spawn), the state machine (missing → create; dead → resume; alive → parallel `-`), the 5-tier precedence, the short-id collision policy, and a worked "simone reproducer" example. Every claim cites source file + line number.
• Updated: `docs/CLI-REFERENCE.md` — `genie spawn` section now carries a state-gated outcome table, the precedence table, and canonical/parallel examples. Links to the new authoritative page.
• Updated: `docs/SPAWN-AUTO-RESUME.md` — callout tying auto-resume to the canonical-UUID invariant; flags parallels as off the bare-name resume path.
• Updated: `docs/ARCHITECTURE.md` — one-liner in the TUI section: "a skin over the CLI, not an alternate control plane".

Source citations (re-verify if source moves)

Symbol	File	Line
`resolveTeamName`	`src/term-commands/agents.ts`	1675
`pickParallelShortId`	`src/term-commands/agents.ts`	1725
`resolveSpawnIdentity`	`src/term-commands/agents.ts`	1783
`findTeamsContainingAgent`	`src/lib/claude-native-teams.ts`	195

Validation

• Every cited symbol grep-findable in source.
• `git diff --name-only dev...HEAD` contains only `.md` files.
• Markdown fences balanced across all 4 files.
• Pre-push full suite: 2630 pass / 0 fail.

Test plan

• CI Quality Gate green.
• Reader unfamiliar with the codebase can answer "what happens if I run `genie spawn simone` while simone is alive?" after reading only `SPAWN-TEAM-RESOLUTION.md`.
• No claim in the docs contradicts current behavior on `dev` HEAD.

Wish: `.genie/wishes/tui-spawn-dx-docs/WISH.md` (workspace-local).

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 09b22f08-f985-4fdc-8afc-87a37d4d9cae

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/tui-spawn-dx-canonical-parallel-model

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gemini-code-assist]

Code Review

This pull request introduces comprehensive documentation for the genie spawn command and the team resolution logic, centered around the new SPAWN-TEAM-RESOLUTION.md file. The changes detail the state-gated spawn model (canonical vs. parallel), the five-tier team-resolution precedence chain, and the handling of short-ID collisions. Updates were also made to existing documentation to ensure consistency. Review feedback identified several areas for technical clarification, specifically regarding the definition of generic spawns, the orchestration of the spawn state machine, and the use of clearer terminology to distinguish between ID prefix lengths and resolution tiers.

[gemini-code-assist]

The description of 'Generic spawn' as <team>-<role> is slightly inaccurate for the default behavior. In the current implementation, genie agent spawn <role> --team <t> follows the state machine (canonical/parallel). The <team>-<role> scheme is only used when an explicit --role is provided (legacy path).

Suggested change

	| **Generic spawn** | `<team>-<role>` via `genie agent spawn <role> --team <t>` | fresh | depends on role | ad-hoc workers within a team |
	| **Generic spawn** | <team>-<role> via explicit --role | fresh | depends on role | legacy multi-worker deployments |

[gemini-code-assist]

The text attributes the following state machine diagram to resolveSpawnIdentity, but that function specifically handles the branches where a fresh UUID is minted (Canonical Create or Parallel Create). The 'RESUME' path is actually handled upstream by findDeadResumable. It would be clearer to state that the diagram represents the overall genie spawn <name> logic.

Suggested change

	`resolveSpawnIdentity` in `src/term-commands/agents.ts:1783` is the state machine. It decides, based on the current `agents` table, whether `genie spawn <name>` creates canonical, resumes canonical, or creates a parallel.
	The overall logic for genie spawn <name> follows this state machine (orchestrated by handleWorkerSpawn using findDeadResumable and resolveSpawnIdentity):

[gemini-code-assist]

The term tier-4 is confusing here as it might be mistaken for 'Tier 4' of the team-resolution precedence. Since this refers to the 4-character hex prefix length, using 4-char or similar would be more precise.

Suggested change

	slice = uuid.slice(0, 4) // tier-4 (s4): 65 536 possibilities per name
	slice = uuid.slice(0, 4) // 4-char prefix (s4): 65 536 possibilities per name