t1k:team
| Field | Value |
|---|---|
| Module | t1k-delegation |
| Version | 2.12.24 |
| Effort | high |
| Tools | Agent, AskUserQuestion, Bash, Edit, Glob, Grep, Read, SendMessage, Skill, TaskCreate, TaskList, TaskUpdate, TeamCreate, ToolSearch, Write |
Keywords: concurrent, delegate, multi-agent, orchestrate, parallel, teammates
How to invoke
Section titled “How to invoke”/t1k:team<template> <context> [--devs|--researchers|--reviewers|--debuggers N] [--delegate]TheOneKit Team — Registry-Aware Agent Teams
Section titled “TheOneKit Team — Registry-Aware Agent Teams”Orchestrate parallel Claude Code Agent Teams with T1K infrastructure: registry-routed agents, module-scoped skill injection, manifest-derived file ownership, mandatory worktree isolation.
Model: teammates run the model declared in their resolved agent frontmatter (Opus for orchestration-tier work). Requires: CLI terminal — agent-team coordination is limited in the VSCode extension.
Implicit single-team model (current Claude Code). There is no
TeamCreate/TeamDeletetool, and theAgenttool’steam_nameparam is deprecated and ignored — the session has a single implicit team. Orchestrate by spawning named backgroundAgentteammates and coordinating viaSendMessage, plusTaskCreate/TaskUpdate/TaskListwhen available (current Claude Code 2.1.x does not register this trio at all — it is an optional convenience, not a required primitive; see Pre-flight Step 2). NoCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMSenv var and no session restart is required. (Older harnesses that still register an explicitTeamCreatetool are handled as a legacy fallback — see Pre-flight Step 2.)
Before spawning: read ## Gotchas (below) for known harness-level gaps — isolation flag unreliability, shutdown_request often ignored, spawn-subshell alias quirks, fan-out below the lead (works for sub-agents; unverified for teammates), teammate-marker collection gap.
Pre-flight Step 0 — Fuzzy plan/path arg resolution (MANDATORY)
Section titled “Pre-flight Step 0 — Fuzzy plan/path arg resolution (MANDATORY)”If the user provides a fuzzy plan/path/phase arg (e.g. chaosforge-demo, plans/chaosforge-demo, phase-3), an empty arg, or natural-language ref like “active plan” / “current plan” / “this plan”, run the Fuzzy Plan / Path Resolution Protocol at skills/t1k-cook/references/fuzzy-plan-resolution.md BEFORE bail. Skill MUST NOT emit “no path matching” / “exact path required” until that protocol has been applied and Step 6 reached.
Agent Routing
Section titled “Agent Routing”Follow protocol: skills/t1k-cook/references/routing-protocol.md
Templates resolve roles dynamically: t1k-researcher, implementer, reviewer, t1k-debugger, t1k-tester, t1k-planner
Templates
Section titled “Templates”| Template | Purpose | Risk | Reference |
|---|---|---|---|
research | N researchers, module-scoped angles | Low (read-only) | references/research-template.md |
review | N reviewers, registry-routed, module boundary checks | Low (read-only) | references/review-template.md |
cook | N implementers, worktree-isolated, manifest ownership | Medium (writes code) | references/cook-template.md |
debug | N debuggers, adversarial hypotheses, worktree-isolated | Medium (may add debug code) | references/debug-template.md |
triage | Parallel issue/PR processing across kit repos | Low (read + GitHub API) | references/triage-template.md |
| Flag | Default | Description |
|---|---|---|
--researchers N | 3 | Number of researchers |
--reviewers N | 3 | Number of reviewers |
--devs N | auto | Number of devs (auto = one per module) |
--debuggers N | 3 | Number of debuggers |
--delegate | off | Lead only coordinates, never touches code |
--no-plan-approval | off | Skip plan approval gate (cook template) |
--resume <team-name> | off | Spawn-only recovery mode — read existing team/tasks from disk and spawn missing teammates. No TeamCreate, no TaskCreate. See references/resume-template.md. |
Pre-flight Protocol (MANDATORY)
Section titled “Pre-flight Protocol (MANDATORY)”At the start of team cook <plan> run bun .claude/scripts/t1k-spawn-eta.cjs plan-eta <plan-dir> --auto (no project copy → bun ~/.claude/scripts/t1k-spawn-eta.cjs) (read-only, no --record, zero tokens, silent when disabled), print its first line and continue; it never blocks.
Strict gate sequence — DO NOT invert. Steps 0+1+2 (introspection) MUST pass before Steps 3-7 (resolution) and template execution (Agent spawns / TaskCreate). Inverting this order is the root cause of #259 — side-effect tools ran inside a forked sub-context before the Agent gate fired, leaving orphan files on disk.
0.0. Resolve fuzzy plan/path arg BEFORE the gate sequence. If the user’s arg is not an exact existing path (e.g. chaosforge-demo, plans/chaosforge-demo, phase-3, empty / “active plan”), run the Fuzzy Plan / Path Resolution Protocol at skills/t1k-cook/references/fuzzy-plan-resolution.md BEFORE Step 0 (deferred-tool schema load) and BEFORE any bail. Skill MUST NOT emit “no plan matching” / “no team-slug found” / “exact path required” until that protocol has been applied and its Step 6 reached.
-
Load deferred tool schemas FIRST (
Agentand coordination tools are often auto-deferred):ToolSearch(query="select:Agent,TaskCreate,SendMessage", max_results=3). Details:references/pre-flight-gate-details.md. -
HARD GATE —
Agentcallability. Until this gate returns PASS, DO NOT callTaskCreate, spawn anAgent, or invoke any other side-effect tool.- PASS =
Agentis in active scope (eagerly available OR loaded via Step 0’sToolSearch). Proceed to Step 2. - FAIL =
Agentis absent from BOTH active scope AND the deferred-tools listing. The skill is running in a forked sub-context (invoked viaSkillfrom inside a sub-agent, or from anothercontext: forkskill). Run the bail procedure inreferences/fork-context-bail.md(orphan probe + bail message + recovery hint), then STOP.
See
references/fork-context-bail.mdfor the full bail procedure, the orphan-detection probe, and the verbatim bail message. Issues addressed: #163, #208, #199, #146, #259. - PASS =
-
HARD GATE — implicit-team coordination primitives. After Step 1 returns PASS, confirm
SendMessage(inter-agent messaging) is callable.SendMessage, together withAgent(Step 1), is all that current Claude Code needs — there is noTeamCreatetool to call.- PASS =
Agent+SendMessageare in active scope (eagerly available OR loaded via Step 0’sToolSearch). Proceed to Step 3. - FAIL =
SendMessageis absent from BOTH active scope AND the deferred-tools listing. Treat this as a genuinely coordination-less harness: surface the gap and STOP (do NOT edit settings.json, do NOT loop on a restart).
TaskCreate/TaskUpdate/TaskListare OPTIONAL, not a gate condition. Absence ofTeamCreateis NOT a failure (implicit session team viateam_nameonAgent). On the legacyTeamCreatepath ONLY, the launcher MUST exportT1K_TEAMMATE_CONTEXT=1(#1155) in the teammate’s launch command (the teammate cannot set it for itself). Full text, legacy fallback and launch example:references/pre-flight-gate-details.md. Then proceed to the matching template and spawn named backgroundAgentteammates (run_in_background: true). - PASS =
-
Resolve roles — follow
skills/t1k-cook/references/routing-protocol.md. For kit-specificsubagent_typeselection (avoid defaulting togeneral-purpose), seereferences/subagent-type-routing.md. -
Detect modules — follow
skills/t1k-modules/references/module-detection-protocol.md -
Derive file ownership —
references/manifest-ownership-resolution.md -
Build skill injection — follow
skills/t1k-cook/references/subagent-injection-protocol.md -
Cost warning — inform user of teammate count and estimated token cost
Every teammate spawn prompt MUST include the T1K Context Block: references/t1k-context-block.md
Decision Discipline (MANDATORY)
Section titled “Decision Discipline (MANDATORY)”When this skill (or any sub-protocol it spawns) needs the user to make a multi-option choice — including yes/no, A-or-B, or any “pick one of these” prompt — you MUST call AskUserQuestion. Prose option lists are forbidden, including from skill output that arrives via <local-command-stdout>.
If AskUserQuestion appears in the deferred-tools list: load it FIRST via ToolSearch(query="select:AskUserQuestion", max_results=1) before constructing the question. The schema is auto-deferred in 1M-context Opus sessions; the decision-tools-preload.cjs hook emits a [t1k:decision-tools] reminder at session start and on every turn as a backup signal.
Forbidden prose patterns in this skill’s output AND in any teammate’s output:
- “Pick one (reply with the number): 1. … 2. … 3. …”
- “Want me to do A or B?”
- “Should I proceed?”
- Any bulleted/numbered choice list followed by a question mark
- “I cannot use AskUserQuestion right now, so please reply with…” — there is no such fallback; load the schema instead
When THIS skill body needs a user decision (not just the calling lead): call AskUserQuestion directly from the skill body — do NOT emit a prose option list and rely on the lead to convert it. The lead-side conversion is a fallback for legacy skill output, not the contract. If the schema is deferred, run ToolSearch(query="select:AskUserQuestion", max_results=1) first, then call the tool from inside this skill.
Plan-Fit Assessment Gate (cook template): before spawning N implementer teammates, the lead MUST present the proposed plan-to-team fit (which modules each dev owns, file-conflict risk, estimated tokens) via AskUserQuestion with at least these options: proceed, re-shape teams, reduce scope, abort.
Why this matters: prose option lists bypass the structured-answer contract — the user must re-type the choice and the skill cannot reliably parse the reply. Full failure-mode catalog + concrete miss examples: docs/decision-discipline-examples.md § “Forbidden prose patterns (full list)” and § “Historical incidents”.
Cross-reference: ~/.claude/rules/always-ask-on-unresolved.md.
Execution Protocol
Section titled “Execution Protocol”Pre-flight first. Phase A (Steps 0+1+2) and Phase B (Steps 3-7) are MANDATORY before any side-effect tool call. Once Phase A returns PASS and Phase B completes, IMMEDIATELY execute the matching template sequence. Do NOT ask for confirmation between Phase B and Phase C. Report after each major step.
--resume <team-name> short-circuit. If the user passes --resume <team-name>, route to references/resume-template.md after Phase A passes. Resume mode skips Phase B’s plan/module resolution (the team and tasks are already on disk) and runs only the Agent spawn calls against the pre-populated state.
Details on all operational protocols: references/team-operations.md
Spawn Brief — Mandatory Inclusions
Section titled “Spawn Brief — Mandatory Inclusions”Every teammate spawn prompt MUST include the following discipline reminders. These are owned by other rules; the skill body’s job is to ensure orchestrators include them by default — not to duplicate the rule bodies.
Mandatory inclusions (each with its verbatim one-line brief text and owning rule in references/spawn-brief-table.md — copy from there, do not paraphrase): Budget checkpoint (SELF-MONITORED, window-relative); Registry snapshot (LEAD-side); Race-free commit (parallel-safe); No induced amend (LEAD-side); Commit only what you wrote; A stand-down races your work; Lean brief (pointer, not payload); Contract-first integration; Micro-task contract pointer (fan-out lanes); Test coverage per Gate 4; Burst discipline; Parallel-agent worktree variant (Unity submodule).
The teammate brief should reference these rules by name rather than restating the full rule body — keeps briefs short and lets future rule updates flow through automatically. See references/team-operations.md for the full T1K Context Block which already includes a slot for these.
When to Use Teams vs Subagents
Section titled “When to Use Teams vs Subagents”| Scenario | Subagents | Agent Teams |
|---|---|---|
| Focused single task | Yes | Overkill |
| Sequential chain | Yes | No |
| 3+ independent parallel workstreams | Maybe | Yes |
| Competing debug hypotheses | No | Yes |
| Cross-module implementation | Maybe | Yes |
| Token budget is tight | Yes | No |
Merge-up tree (opt-in, features.mergeUpTree)
Section titled “Merge-up tree (opt-in, features.mergeUpTree)”For a feature large enough to trip mergeUpTree.minLeaves / mergeUpTree.minFiles, children merge
locally into their parent instead of each opening a PR — one PR at the root, one CI run.
- Flow:
references/merge-up-tree.md. - Node-file shape:
references/node-file-contract.md.
Intra-phase sub-agent fan-out (optional)
Section titled “Intra-phase sub-agent fan-out (optional)”A teammate owning a single phase can spawn background Agent sub-agents to parallelize impl + tests within that phase. Requires an interface-freeze pass first to prevent file collisions. See references/intra-phase-fanout.md for the 5-step workflow + guardrail template + opt-in/opt-out guidance.
Constraint: the depth budget is 3 levels (per rules/agent-security-boilerplate.md); width per level is not capped. A teammate is depth 1 and may spawn sub-agents, and those may spawn their own — but depth 3 is a leaf and spawns nothing. Everything below the lead uses plain Agent, never TeamCreate (the “no recursive teams” constraint below still applies).
Resume Mode — /t1k:team --resume <team-name>
Section titled “Resume Mode — /t1k:team --resume <team-name>”Spawn-only recovery for orphan team state. Reads ~/.claude/teams/<name>/config.json + ~/.claude/tasks/<name>/*.json, then spawns Agent calls for ownerless tasks. No TeamCreate, no TaskCreate. Pre-flight Step 1 still applies (resume must run from main session).
Full procedure + subject-line → subagent_type resolution: references/resume-template.md.
Hard rules
Section titled “Hard rules”Known harness-level gaps. Read these before spawning. Full detection + workaround + upstream-issue refs for the consumer-side mitigations: references/known-caveats.md.
-
Fan-out below the lead works for background sub-agents; unverified for
TeamCreateteammates. Keep the two cases distinct — conflating them is how an earlier, now-retracted claim spread. Full probe evidence and retraction history:references/known-caveats.md§ 4.- Depth-1 background
Agentsub-agent — CONFIRMED working. Spawn briefs may partition work (SA-A / SA-B / SA-C) within the depth budget. TeamCreateteammate context — UNVERIFIED. No probe has tested a teammate, so do not assert either way. Write briefs that attempt fan-out within the cap; if a spawn ever fails withAgent type 'X' not found, single-thread the scope and report a handoff request to team-lead (who spawns a follow-up teammate at depth 1). Treat that as a contingency note, not an expected outcome — and if it fires, capture it as evidence and file it.
The governing mechanism (use this before blaming the harness):
Agentavailability is determined by the running agent’s owntools:frontmatter, not by a depth-based strip. So a teammate finding noAgentproves only that its own agent definition omits it — resolve the teammate’s.mdand checktools:before concluding anything about teammate context. Probe evidence for this claim:references/known-caveats.md§ 4.To close the teammate case, probe like this (must run from depth 0 —
TeamCreateis not available lower down). Pick a teammate type that already declaresAgent, or the probe tests nothing:TeamCreatea one-teammate team of that type → ask it to report whetherAgentis in its own tool set → have it attempt oneExplorespawn and onet1k-testerspawn with a throwaway prompt (Reply with the single word: probe) → capture verbatim results including full error text → then shut the teammate down,tmux list-panesto confirm no leftover pane (process-dead is not pane-closed), andTeamDelete. - Depth-1 background
-
Teammate detection is a legacy-only gap now — do not generalise it (#1155). A named background
Agentteammate (the current implicit-team model) IS detected: an ephemeral one ends onSubagentStop, and its hook payload carriesagent_type/agent_id— signals 1/3/4 ofisTeammateContext(). The undetectable shape is specifically the legacyTeamCreateteammate above. Swept onorigin/main2026-09-07:git grep "T1K_TEAMMATE_CONTEXT" -- '.claude/'matchedhooks/telemetry-utils.cjsand three__tests__/files and no spawn site, so as a pure opt-in the flag measured nothing; the fix is the launcher-side export in Pre-flight Step 2, and the residual (harness-owned launch line, no env channel) is unfixable from the kit.MESSAGING_SOCKETand the other candidate discriminators #1155 lists remain unverified —git grep -c "MESSAGING_SOCKET" -- '.claude/'→ 0. -
Teammate-emitted markers are NOT auto-collected —
lesson-collector.cjsStop hook parses the team-lead’s transcript only.[t1k:lesson …]/[t1k:skill-bug …]/[t1k:mcp-gap …]markers inside<teammate-message>blocks are silently dropped, so the auto-issue / auto-sync-back pipeline never fires for team-based workflows. Until that’s fixed (https://github.com/The1Studio/theonekit-core/issues/272), team-lead MUST manually invoke/t1k:issue(background sub-agent) for each unique marker observed in teammate output. -
isolation: "worktree"is unreliable — silently no-ops for some teammates; manuallySendMessageeach one explicitgit checkout -b <branch>instructions right after spawn. Seereferences/known-caveats.md§ 1. -
SendMessage(type: "shutdown_request")is often ignored — teammates go idle but don’t exit; fall back totmux kill-paneafter a ~30s wait. Seereferences/known-caveats.md§ 2. -
Spawn subshell does NOT source
.zshrc— interactive aliases (e.g.tcd) crash teammate launch; always use POSIXcdin any teammate-facing command string. Seereferences/known-caveats.md§ 3. -
No automatic teammate context capping / checkpoint — the harness does NOT emit any system reminder, warning, or notification when a teammate approaches its context limit. Teammates are responsible for self-monitoring their own token budget. The window-relative checkpoint above is a HARD CEILING that the teammate must observe via self-discipline (multi-commit cadence, “start finalizing ~10% of the window before the checkpoint”, explicit
git statuschecks before context-growing reads). Never brief a flat token number — a flat absolute ceiling fires at ~15% of a 1M window and in practice never fires at all, which is the failureskills/t1k-team/references/agent-completion-discipline.md§ “Budget checkpoint” exists to prevent; derive the ceiling from the teammate’s ownmodel:window (~75% of ≤200K, ~55% of 1M) — there is no turn-based second ceiling (maxTurnsis retired). This is the #1 root cause of tail-of-thought stops with uncommitted work — incident evidence:references/known-caveats.md§ 5. Lead MUST include the SELF-MONITORED checkpoint row from the Spawn Brief table verbatim in every spawn brief; an explicitSendMessagereinforcement after spawn (e.g. “no checkpoint hook — self-manage; commit per logical chunk; start finalizing one notch below your window-relative checkpoint; by the checkpoint you MUST be done committing”) is recommended for any teammate expected to run long enough to approach either ceiling.
Definition of Done (lead contract)
Section titled “Definition of Done (lead contract)”A /t1k:team run is NOT done when teammates report TaskUpdate(status: completed) or when their PRs are opened. The lead MUST drive every teammate PR to the terminal state below before the team’s overall work is “done”:
| Teammate output | Terminal state |
|---|---|
| PR opened (any teammate) | PR merged in GitHub (bun "$S" pr <o/r> <n> --fresh --json confirms: cleanup follows, so a direct read; skills/t1k-git/references/gh-status-lookup.md) |
| PR opened but blocked | Documented merge-blocked: <reason> in final report; PR left open with comment |
| No PR (research/review only) | Findings written to plans/reports/... and committed |
Lead’s babysit loop (after each teammate reports “PR opened:
- Use
gh pr merge <n> --auto --squash --delete-branch(per~/.claude/skills/t1k-triage/SKILL.mdStep 5a.5 — admin-bypass is escalation only). The PR head MUST be a topic branch, never a linked worktree’s home branch (skills/t1k-git/references/worktree-home-branch.md). - Wait via ONE background
t1k-pr-watch.cjsfor the batch, not a per-PR poll (skills/t1k-git/references/github-api-limits.md). - On CI failure,
SendMessagethe original teammate to fix — do NOT spawn a fresh agent. - Cleanup procedure (next section) ONLY fires once every PR is MERGED or explicitly
merge-blocked.
Anti-pattern: declaring “all teammates shipped” based on TaskUpdate(status: completed) notifications. Those mean “I finished my part.” The team’s part isn’t done until the PR is merged + main pulled + branch deleted.
A lane’s own done check is its phase’s one-command Accept:: skills/t1k-cook/references/accept-gate.md.
Cleanup (lead contract — runs BEFORE final user summary)
Section titled “Cleanup (lead contract — runs BEFORE final user summary)”After every PR reaches its terminal state (per Definition of Done above), the lead MUST execute the cleanup pass before composing the user-facing victory summary. Full checklist (graceful-shutdown loop, tmux pane kill, worktree prune, sentinel-file removal, branch cleanup, main verification): references/team-operations.md § “Successful Completion Cleanup”.
The cleanup pass is non-optional even when individual PRs were merge-blocked or deferred — orphan state (idle tmux panes, temp worktrees, sentinel files, stale local branches) accumulates fast in multi-agent runs and confuses the next session’s git ops.
Constraints
Section titled “Constraints”- Teammates inherit the lead’s permission settings at spawn time.
- No recursive spawning: teammates MUST NOT spawn their own Agent Teams.
- Invoke from the main session only. When this skill is invoked via the
Skilltool from a sub-agent (or any other forked sub-context), theAgenttool is stripped from scope and teammates cannot be spawned. Pre-flight Step 1 (HARD GATE — Agent callability) bails cleanly in that case with a recovery hint pointing at--resume. See issues #163 (original fork-detection), #208 (deferred-tool false-positive fix in v1.91.0), and #259 (orphan-prevention + recovery mode shipped in this version).