Skip to content

t1k:team

FieldValue
Modulet1k-delegation
Version2.12.24
Efforthigh
ToolsAgent, AskUserQuestion, Bash, Edit, Glob, Grep, Read, SendMessage, Skill, TaskCreate, TaskList, TaskUpdate, TeamCreate, ToolSearch, Write

Keywords: concurrent, delegate, multi-agent, orchestrate, parallel, teammates

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

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.

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

TemplatePurposeRiskReference
researchN researchers, module-scoped anglesLow (read-only)references/research-template.md
reviewN reviewers, registry-routed, module boundary checksLow (read-only)references/review-template.md
cookN implementers, worktree-isolated, manifest ownershipMedium (writes code)references/cook-template.md
debugN debuggers, adversarial hypotheses, worktree-isolatedMedium (may add debug code)references/debug-template.md
triageParallel issue/PR processing across kit reposLow (read + GitHub API)references/triage-template.md
FlagDefaultDescription
--researchers N3Number of researchers
--reviewers N3Number of reviewers
--devs NautoNumber of devs (auto = one per module)
--debuggers N3Number of debuggers
--delegateoffLead only coordinates, never touches code
--no-plan-approvaloffSkip plan approval gate (cook template)
--resume <team-name>offSpawn-only recovery mode — read existing team/tasks from disk and spawn missing teammates. No TeamCreate, no TaskCreate. See references/resume-template.md.

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.

  1. Load deferred tool schemas FIRST (Agent and coordination tools are often auto-deferred): ToolSearch(query="select:Agent,TaskCreate,SendMessage", max_results=3). Details: references/pre-flight-gate-details.md.

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

  3. 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/TaskUpdate/TaskList are OPTIONAL, not a gate condition. Absence of TeamCreate is NOT a failure (implicit session team via team_name on Agent). On the legacy TeamCreate path ONLY, the launcher MUST export T1K_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 background Agent teammates (run_in_background: true).

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

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

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

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

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

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.

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

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.

ScenarioSubagentsAgent Teams
Focused single taskYesOverkill
Sequential chainYesNo
3+ independent parallel workstreamsMaybeYes
Competing debug hypothesesNoYes
Cross-module implementationMaybeYes
Token budget is tightYesNo

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.

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.

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.
    • 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 detection is a legacy-only gap now — do not generalise it (#1155). A named background Agent teammate (the current implicit-team model) IS detected: an ephemeral one ends on SubagentStop, and its hook payload carries agent_type / agent_id — signals 1/3/4 of isTeammateContext(). The undetectable shape is specifically the legacy TeamCreate teammate above. Swept on origin/main 2026-09-07: git grep "T1K_TEAMMATE_CONTEXT" -- '.claude/' matched hooks/telemetry-utils.cjs and 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_SOCKET and the other candidate discriminators #1155 lists remain unverified — git grep -c "MESSAGING_SOCKET" -- '.claude/' → 0.

  • 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) — there is no turn-based second ceiling (maxTurns is 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 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.

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 outputTerminal 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 blockedDocumented 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). The PR head MUST be a topic branch, never a linked worktree’s home branch (skills/t1k-git/references/worktree-home-branch.md).
  2. Wait via ONE background t1k-pr-watch.cjs for the batch, not a per-PR poll (skills/t1k-git/references/github-api-limits.md).
  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.

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.

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