t1k:team

Auto-generated

🔒 Auto-generated from The1Studio/[email protected] — edit the source kit, not this page.

Field	Value
Module	t1k-extended
Version	3.5.0
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

/t1k:team
<template> <context> [--devs|--researchers|--reviewers|--debuggers N] [--delegate]

---

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 / TeamDelete tool, and the Agent tool’s team_name param is deprecated and ignored — the session has a single implicit team. Orchestrate by spawning named background Agent teammates and coordinating via SendMessage, plus TaskCreate / TaskUpdate / TaskList when 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). No CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env var and no session restart is required. (Older harnesses that still register an explicit TeamCreate tool 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)

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

Follow protocol: skills/t1k-cook/references/routing-protocol.md Templates resolve roles dynamically: t1k-researcher, implementer, reviewer, t1k-debugger, t1k-tester, t1k-planner

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

Flags

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)

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.

0. Load deferred tool schemas FIRST. In long-context sessions (1M Opus), Agent and the coordination tools are commonly auto-deferred — listed in the <system-reminder> deferred-tools enumeration but with schemas not yet loaded. Direct calls fail with InputValidationError. Always run before any availability check:

   ToolSearch(query="select:Agent,TaskCreate,SendMessage", max_results=3)

   ToolSearch returns 0 matches for tools that aren’t deferred (either eagerly available OR genuinely absent). Use the deferred-tools listing as the discriminator in Step 1. (These are the implicit-team primitives; there is no TeamCreate schema to load.)

1. HARD GATE — Agent callability. Until this gate returns PASS, DO NOT call TaskCreate, spawn an Agent, or invoke any other side-effect tool.

   • PASS = Agent is in active scope (eagerly available OR loaded via Step 0’s ToolSearch). Proceed to Step 2.
   • FAIL = Agent is absent from BOTH active scope AND the deferred-tools listing. The skill is running in a forked sub-context (invoked via Skill from inside a sub-agent, or from another context: fork skill). Run the bail procedure in references/fork-context-bail.md (orphan probe + bail message + recovery hint), then STOP.

   See references/fork-context-bail.md for the full bail procedure, the orphan-detection probe, and the verbatim bail message. Issues addressed: #163, #208, #199, #146, #259.

2. HARD GATE — implicit-team coordination primitives. After Step 1 returns PASS, confirm SendMessage (inter-agent messaging) is callable. SendMessage, together with Agent (Step 1), is all that current Claude Code needs — there is no TeamCreate tool to call.

   • PASS = Agent + SendMessage are in active scope (eagerly available OR loaded via Step 0’s ToolSearch). Proceed to Step 3.
   • FAIL = SendMessage is 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 (and TaskUpdate/TaskList) is an OPTIONAL convenience, not a gate condition — #961, a recurrence of #592 one tool over. Current Claude Code (2.1.x) does not register this trio at all (TaskOutput/TaskStop survive; TaskCreate/TaskUpdate/TaskList do not), and a harness with no shared task list is still fully capable of running this skill: Agent spawns background teammates and emits completion notifications, SendMessage addresses them by name and resumes them from their transcripts, and each template’s own phase-N.md / task-assignment text carries the work self-contained per teammate (skills/t1k-team/references/lean-brief-pointer-not-payload.md). When TaskCreate IS present in active scope or the deferred-tools listing, use it for shared progress tracking; when absent, proceed anyway — progress tracking is lead-side (poll SendMessage completion notifications), exactly the same non-gating treatment already given to TeamCreate below.

   Absence of TeamCreate is NOT a failure — it is the current model. The harness moved to an implicit session team: team_name on the Agent tool is deprecated/ignored, and TeamCreate/TeamDelete no longer exist. When TeamCreate is absent, do NOT conclude “Agent Teams unavailable,” do NOT auto-edit settings.json, and do NOT ask the user to restart — that produced an unresolvable restart loop (TeamCreate never appears regardless of the env var; see #592). Proceed directly with named background Agent spawns coordinating over the implicit team.

   Legacy fallback (older harnesses only). If — and only if — TeamCreate IS present in active scope or the deferred-tools listing (an older Claude Code build that still registers the explicit tool), you MAY call TeamCreate(team_name: ...) per the template’s legacy path. Do NOT enable any env var or force a restart to make TeamCreate appear; its absence is expected and handled by the implicit-team path above.

   Then proceed to the matching template and spawn named background Agent teammates (run_in_background: true), assigning work via TaskCreate where available (else via the spawn prompt directly) and coordinating via SendMessage. If a spawn or coordination call errors AFTER passing this gate, surface the error and STOP.

3. Resolve roles — follow skills/t1k-cook/references/routing-protocol.md. For kit-specific subagent_type selection (avoid defaulting to general-purpose), see references/subagent-type-routing.md.

4. Detect modules — follow skills/t1k-modules/references/module-detection-protocol.md

5. Derive file ownership — references/manifest-ownership-resolution.md

6. Build skill injection — follow skills/t1k-cook/references/subagent-injection-protocol.md

7. 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)

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 SessionStart hook decision-tools-preload.cjs emits a [t1k:decision-tools] reminder every session 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

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

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.

Discipline	One-line for the brief	Owning rule
Budget checkpoint (SELF-MONITORED, window-relative)	“At your budget checkpoint — whichever comes first: ~75% of a ≤200K context window, ~55% of a 1M window (derive it from your own model:, never a flat token number), or ~80% of maxTurns — STOP investigation. Run git status. Commit + push any pending edits BEFORE composing your summary or reading more files. No system reminder fires at any of these — you must self-monitor. Start finalizing ~10% of the window earlier; be done committing by the checkpoint. Multi-commit per logical chunk is preferred over one big final commit.”	~/.claude/skills/t1k-team/references/agent-completion-discipline.md + gotcha below
Registry snapshot (LEAD-side)	If you edited an agent .md — including its tools: frontmatter — earlier in THIS session, that grant does NOT reach a teammate spawned later in the same session; the registry is cached at session start. Tell the affected teammate to restart, or spawn it in a fresh session, before relying on the new grant.	skills/t1k-team/references/agent-registry-snapshotted-at-session-start.md
Race-free commit (parallel-safe)	“Use git commit -m '<msg>' -- <file1> [<file2>...] (pathspec form). NEVER git add . / git add -A / git commit -a / two-step git add + git commit / git commit --amend. Concurrent teammates share the git index; sweeping commits steal other teammates’ staged work. --amend rewrites whatever HEAD points at — which may be a SIBLING’s commit if they committed after you — and commits the whole index; a pathspec does not narrow it. Do not reach for git reset --soft HEAD^: HEAD^ is positional, not ownership-aware, and drops a sibling’s commit off the branch if the amend landed on theirs. Check ownership first (git log -1 --format='%H %an %s' + git reflog -5); if HEAD is not yours, do NOT reset — your content is still staged, so commit it forward pathspec-form and tell the lead. A dropped commit is unreachable, so git log looks clean — only git reflog shows it.”	rules/parallel-teammate-git-index-race.md
No induced amend (LEAD-side)	Do NOT write “fold this into the previous commit”, “amend that in”, or “keep it to one commit” into any brief while other lanes are active — that instruction leaves the teammate no compliant option and manufactures the index race. Two commits are correct; squash later when the tree is quiet, or not at all.	modules/t1k-parallel/rules/parallel-teammate-git-index-race.md
Commit only what you wrote	”If you find uncommitted work in the shared tree that is NOT yours — however coherent, however complete it looks, even if it looks abandoned — do not commit it. Report it to the lead and name the paths; the owning lane commits its own work. A correct pathspec does NOT make this safe: the paths genuinely are the ones changing, so the commit form is right and the decision is wrong. Coherence seen from outside cannot establish completeness — only the author knows what they had not written yet. If someone else already committed YOUR work: verify what their commit captured and commit any remainder FORWARD; never amend or revert a commit you do not own.”	modules/t1k-parallel/rules/parallel-teammate-git-index-race.md
A stand-down races your work	”Under concurrency an instruction is not a guarantee — a lead’s “stand down / do not touch X” can arrive AFTER the action it forbids, and will still read as obeyed because you take no further action. Do not treat the absence of a stop message as permission. Before touching anything outside your own reserved paths, assume a sibling owns it and ask.”	modules/t1k-parallel/rules/parallel-teammate-git-index-race.md
Lean brief (pointer, not payload)	“Your brief names paths; it does not paste their contents. Read <plan-phase-path> yourself for scope, ownership globs and success criteria. Do not expect pasted file bodies, prior agent reports, or transcript excerpts — if you need one, Read it. The only verbatim items are the integration contract and exact identifiers.”	skills/t1k-team/references/lean-brief-pointer-not-payload.md
Contract-first integration	”When your output meets another teammate’s at a shared boundary (API ↔ client, producer ↔ consumer, two modules), the lead-supplied integration contract is authoritative — code against it EXACTLY: exact path/method, payload field names + types + casing, enums, success/error envelope, null semantics. Do not invent or paraphrase the shape. Flag any contract gap to the lead BEFORE implementing your side.”	skills/t1k-team/references/contract-first-integration.md
Test coverage per Gate 4	”Every new/modified system MUST have a test in the package’s Tests/EditMode/. Compile + run tests before reporting done. Zero failures required.”	project CLAUDE.md § Completion Gates (Gate 4)
Burst discipline	”Add [BurstCompile] to struct ISystem and OnUpdate/OnCreate/OnDestroy. No managed types in IComponentData. No System.Linq in runtime. No [BurstCompile] on static utility classes (BC1064).“	skill t1k-unity-dots-core-jobs-burst
Parallel-agent worktree variant (Unity submodule)	“When 3+ parallel agents target divergent branches on the same git submodule, lead MUST pre-create one worktree per agent (git worktree add -B <branch> <path> <base>) BEFORE spawning. Agents commit inside their path; HEAD races are impossible. Unity caveat: agents that need run_tests MUST stay in the main worktree — the Editor only sees main-worktree content.”	docs/parallel-teammate-git-index-race.md § “Parallel-agent worktree pattern (Unity DOTS 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

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

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 with a per-level fan-out cap (per rules/agent-security-boilerplate.md). A teammate is depth 1, so it may spawn up to 3 sub-agents, and each of those may itself spawn up to 2 — 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>

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.

Gotchas

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 TeamCreate teammates. 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 Agent sub-agent — CONFIRMED working. Spawn briefs may partition work (SA-A / SA-B / SA-C) within the depth budget’s fan-out cap.
  • TeamCreate teammate 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 with Agent 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): Agent availability is determined by the running agent’s own tools: frontmatter, not by a depth-based strip. So a teammate finding no Agent proves only that its own agent definition omits it — resolve the teammate’s .md and check tools: 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 — TeamCreate is not available lower down). Pick a teammate type that already declares Agent, or the probe tests nothing: TeamCreate a one-teammate team of that type → ask it to report whether Agent is in its own tool set → have it attempt one Explore spawn and one t1k-tester spawn with a throwaway prompt (Reply with the single word: probe) → capture verbatim results including full error text → then shut the teammate down, tmux list-panes to confirm no leftover pane (process-dead is not pane-closed), and TeamDelete.

• Teammate-emitted markers are NOT auto-collected — lesson-collector.cjs Stop 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; manually SendMessage each one explicit git checkout -b <branch> instructions right after spawn. See references/known-caveats.md § 1.

• SendMessage(type: "shutdown_request") is often ignored — teammates go idle but don’t exit; fall back to tmux kill-pane after a ~30s wait. See references/known-caveats.md § 2.

• Spawn subshell does NOT source .zshrc — interactive aliases (e.g. tcd) crash teammate launch; always use POSIX cd in any teammate-facing command string. See references/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 status checks 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 failure skills/t1k-team/references/agent-completion-discipline.md § “Budget checkpoint” exists to prevent; derive the ceiling from the teammate’s own model: window (~75% of ≤200K, ~55% of 1M) or ~80% of its maxTurns, whichever binds first. 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 explicit SendMessage reinforcement 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)

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 (gh pr view <n> --json mergedAt,state confirms)
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: ”):

1. Use gh pr merge <n> --auto --squash --delete-branch (per ~/.claude/skills/t1k-triage/SKILL.md Step 5a.5 — admin-bypass is escalation only).
2. Poll gh pr view <n> --json mergedAt --jq .mergedAt every 30s until non-null.
3. On CI failure, SendMessage the original teammate to fix — do NOT spawn a fresh agent.
4. 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.

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

• 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 Skill tool from a sub-agent (or any other forked sub-context), the Agent tool 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).