Agent Task Splitter

agent-task-splitter

Bridge between a high-level goal and the multi-agent execution pipeline. You write .coord/plan.yml (the DAG) and the per-agent task files. The delegate skills (codex-delegate, gemini-delegate) invoke the agents using those task files. The reconciler reads what they produce.

This skill does not invoke any agent. It only plans and writes files.

Why use this instead of hand-rolling briefs

The supervisor (Claude) writing 2-3 brief files by hand looks cheap but costs token + drift in two specific ways:

| Hand-rolled briefs | This skill | |---|---| | Same context block (file paths, conventions, in-scope list) repeated across 3 task files — 3× redundant token cost in main session. | Splitter writes once into .coord/plan.yml, references it from each task file. | | Subtle drift between briefs ("Codex was told to update README, Gemini was told to mirror Stage 6" — but Codex's scope quietly included Stage 6 too). F11 incident shipped because of this. | Splitter computes the file-scope set once and propagates the disjoint partition. | | Operator forgets which agent gets which task type (codex for mechanical, gemini for long-context CJK). | Routing rules baked in — same agent gets the same shape of work every time. |

Measured impact (real dogfood, 2026-05-14)

| Setup | Main session tokens | Notes | |---|---|---| | With splitter (R2 + R4 combined: 2 parallel Codex + 1 mirror sync Gemini) | ~9k tokens (R2 ~5k + R4 ~4k, measured) | Splitter wrote 5 KB of plan.yml + briefs; main session read only structured summaries | | Hand-rolled equivalent (estimated counterfactual) | ~107-127k tokens (R2 control ~37k + R4 control ~70-90k) | Operator inlines all context per brief, parses each agent's raw stdout, reconciles by hand | | Saving | ~12-14× combined (R2 ~7× + R4 ~17-22× per round) | Plus the splitter's disjoint-scope partition prevented F11-class drift |

The skill earns its keep when ≥ 2 subtasks go to different agents (or same agent in parallel). For 1-shot delegation, call the delegate skill directly.

Anti-patterns this skill prevents

• F11 (cross-agent scope creep): Agent A sweeps a rule into files

that were Agent B's responsibility. Prevented by .coord/plan.yml's explicit files_in_scope partition per task.

• F14 (skipping the splitter for "small enough" 2-agent runs):

Operator decides to hand-roll because "it's only 2 tasks", and the drift catches them later. The CLAUDE.md template below makes the trigger mechanical: ≥ 2 parallel delegates → splitter is mandatory, no judgment call.

CLAUDE.md snippet to enforce routing

## Multi-agent routing rule (enforced)

If a single round needs ≥ 2 delegate agents running in parallel (e.g.,
codex + gemini, or 2 codex on independent subtasks): invoke
`Skill("agent-collab-workspace:agent-task-splitter", args="round=N ...")`
FIRST. Do NOT hand-roll briefs into `.ai/codex_task_*.md` directly when
≥ 2 are needed in the same round.

Decision rule (no judgment): 1 delegate per round → call delegate
directly. ≥ 2 parallel → splitter first, then per-tool delegate.

When to use

Trigger phrases:

• "Split this task across Claude / Codex / Gemini."
• "Plan a multi-agent run for ``."
• "Break this down into parallel agent tasks."
• "Decompose this goal into Codex + Gemini subtasks."
• "Make a .coord/plan.yml for this work."

Not for:

• Running the agents themselves — that's codex-delegate /

gemini-delegate.

• Reconciling agent outputs after they run — that's

agent-output-reconciler.

• Single-agent tasks — if the whole job is one Codex run, just use

codex-delegate directly. This skill earns its keep when there are ≥ 2 subtasks plausibly going to different agents.

Inputs

The user provides one or both of:

1. The goal: a sentence or paragraph describing what they want.
2. Constraints (optional): which agents are available, time

budget, files in / out of scope, success criteria they already know.

You may also read existing project context if relevant:

• .coord/memory.yml — prior decisions / open questions (if

agent-shared-memory has run before).

• .research/project_manifest.yml — research project context (if

research-context-compressor from ai-research-skills has run).

If the goal is large, cross-session, or likely to involve parallel Codex + Gemini work, use agent-context-budget before writing task files. It sets the bounded handoff policy that prevents context overflow.

Workflow

0. Verify cwd is the project root before writing anything

.coord/plan.yml, .ai/_task_*.md, and all downstream artifacts go to the project the agents will modify, not whatever directory Claude currently happens to be in. Before writing anything, confirm:

1. The cwd matches the repo the user actually means.
2. If the user is in a worktree (.git is a file pointing to

a worktree dir, not a real .git/ directory), confirm they want .coord/ in the worktree or the main checkout — these can differ.

1. If working across multiple repos in one conversation, ask which

one the multi-agent run targets.

This step takes 5 seconds and prevents writing .coord/plan.yml to the wrong filesystem location, which silently breaks downstream agents that look for it relative to their own -C/cwd.

1. Understand the goal

Restate the goal back to the user in 1-2 sentences before planning. If anything is ambiguous (which files, which tests count as success), ask one focused clarifying question before producing the plan. Don't ask 5 questions; ask the single question that most narrows the design space.

2. Decompose into subtasks

Break the goal into 2-7 subtasks. For each subtask, decide:

| Property | How to determine | |---|---| | id | T1, T2, ... contiguous | | agent | One of codex / gemini / claude (see classification below) | | slug | kebab-case task identifier (≤ 30 chars) | | description | one line | | depends_on | list of T_n ids that must complete first; [] if none | | files_in_scope | glob list of files this task may modify | | files_out_of_scope | glob list this task must NOT touch | | success_criteria | 1-3 bullets, each a runnable check (pytest, ls, grep) or a checkable assertion |

Guidance on subtask granularity: if a subtask exceeds ~50 lines of expected diff or requires more than one round of tool calls, it's too big — split further. If a subtask is 50 page sources), bilingual / CJK long-form writing, second-opinion reviewing of generated output, terminology alignment across documents | Bulk code generation, mechanical implementation with no reading required | | claude | API contract design, bug diagnosis, acceptance review, design judgment, anything needing project memory / cross-conversation context | Token-heavy mechanical work, very-long-context single reading passes |

A useful sanity check: if the subtask is "do X to many files in roughly the same way", that's Codex. If the subtask is "read this big thing carefully and tell me what's there", that's Gemini. If the subtask is "decide whether X is right", that's Claude.

4. Identify dependencies (DAG)

For each subtask, list which other subtasks must finish before it can start (depends_on). Common patterns:

• Linear chain: T1 → T2 → T3 (each depends on previous).
• Fan-out: T1 → [T2, T3, T4] (T2/3/4 parallel after T1).
• Fan-in: [T2, T3] → T4 (T4 needs both).
• Independent: all depends_on: [] — runnable fully parallel.

Avoid cycles. If you have one, redesign.

5. Write .coord/plan.yml

Schema (full reference: references/task_splitter_heuristics.md):

round: 1
goal: "Refactor the auth module into plugin-based architecture"
budget:
  tokens: 200000          # optional, gate skill checks against this
  duration_min: 60        # optional advisory
context_policy:
  main_session_token_budget: 3000
  task_packet_token_budget: 6000
  result_summary_word_budget: 250
  memory_digest_token_budget: 1200
  log_tail_lines_on_error: 50
  raw_log_policy: path-only
  agentmemory: optional
created_utc: "2026-04-28T09:00:00Z"
tasks:
  - id: T1
    agent: codex
    slug: extract-interfaces
    description: "Define abstract base classes in src/auth/interfaces.py"
    depends_on: []
    files_in_scope:
      - "src/auth/interfaces.py"
    files_out_of_scope:
      - "src/auth/legacy.py"
      - "tests/**"
    success_criteria:
      - "src/auth/interfaces.py exists and defines AuthProvider ABC"
      - "no other source files modified"
  - id: T2
    agent: codex
    slug: refactor-providers
    description: "Move existing provider classes to inherit from new ABC"
    depends_on: [T1]
    files_in_scope:
      - "src/auth/providers/*.py"
    success_criteria:
      - "pytest tests/auth/test_providers.py passes"
      - "no imports of src.auth.legacy from other modules"
  - id: T3
    agent: gemini
    slug: review-doc-coverage
    description: "Read all public APIs in src/auth and verify docstrings reflect new architecture"
    depends_on: [T1, T2]
    success_criteria:
      - "every public symbol in src/auth has a docstring"
      - "report flags any docstring still mentioning the legacy class"
  - id: T4
    agent: claude
    slug: design-review
    description: "Read T1-T3 outputs, verify the architecture choice survives the implementation"
    depends_on: [T1, T2, T3]
    success_criteria:
      - "explicit YES/NO verdict + rationale in chat"

6. Write per-agent task files

Codex and Gemini have different task file conventions. Don't use a single template for both — each delegate skill expects its own shape.

Every task brief MUST include a pre-task scope confirmation block (W1, prevents drift):

## Pre-task scope confirmation (REQUIRED — your first action)

Before any file edit, echo back the scope you understand:

  Confirmed scope: will touch
    - 
    - 
  Will NOT touch
    - 
    - any file not listed under "Files in scope" above
    - any meta-documentation table (F11)
    - any unrequested metadata line (F12)

If your understanding doesn't match the brief's "Files in scope"
section, STOP and ask for clarification before editing anything.

This block is verified post-task by agent-acceptance-gate §6.6 (scope diff check via git diff --name-only).

6a. Codex task files (agent: codex)

Path: .ai/codex_task__.md. ` is the zero-padded round (001 for round 1). Format follows codex-delegate`'s "Supervisor Workflow" section:

# Task: 

## Context
- Repo: 
- Plan: .coord/plan.yml (round , task )
- Read these files first:
  - 
- Only modify (files_in_scope):
  - 
  - .ai/codex_result__.md   ← REQUIRED: the result-summary file
- Do NOT touch (files_out_of_scope):
  - 
- Depends on outputs of: 

## Goal

## Constraints
- Follow adjacent code style.
- Do not make architectural changes beyond the scope.
- Do not edit files outside the allowed list.

## Acceptance
- Required tests: 
- Required result summary: write a concise summary to
  .ai/codex_result__.md
- Summary limit:  **Critical**: `.ai/codex_result__.md` MUST appear in
> `files_in_scope`. The Acceptance section requires writing there;
> if it's not in scope, codex flags a self-conflict and may refuse
> to write it.

> **Critical (Codex invocation)**: when launching codex directly
> (not via the `codex-delegate` wrapper script), **close stdin
> with ` "Reading additional input from stdin..." indefinitely. Pattern:
>
> ```bash
> # Preferred: structured result via -o flag (bounded, machine-readable)
> codex exec --sandbox workspace-write -m gpt-5.5 \
>   -o .ai/codex_result__.jsonl \
>   "Read .ai/codex_task__.md and execute all instructions inside." \
>   
> # Fallback (only if you need raw stdout for diagnostics): MUST cap with head
> # WITHOUT this cap, codex retries + verbose tool calls can grow logs to
> # multi-GB (real incident: 7 GB in .ai/ on 2026-04-17). Never use bare
> # `> file.log 2>&1`.
> codex exec --sandbox workspace-write -m gpt-5.5 \
>   "Read .ai/codex_task__.md and execute all instructions inside." \
>   &1 | head -c 10485760 > .ai/codex_log__.txt
> ```
>
> The `codex-delegate` wrapper script (`run_codex.sh`) handles both
> the `-o` flag and the 10 MB log cap internally; only direct
> `codex exec` calls need to set these explicitly.

#### 6b. Gemini task files (`agent: gemini`)

Path: `.ai/gemini_task__.md`. Format follows
`gemini-delegate`'s "Supervisor Workflow" — different sections from
codex:

```markdown
# Task: 

## Context
- Repo: 
- Plan: .coord/plan.yml (round , task )
- Read these files first:
  - 
- Output file(s):
  - 
  - .ai/gemini_result__.md   ← REQUIRED: the result-summary file
- Depends on outputs of: 

## Goal

## Language
- Output language: 
- Tone: 
- Audience: 

## Constraints
- Preserve dates, proper nouns, code identifiers exactly.
- Keep terminology consistent with referenced sources.
- Do not invent facts missing from the inputs.

## Acceptance
- Required verification files: 
- Required sentinel strings: 
- Required result summary: write a concise summary to
  .ai/gemini_result__.md
- Summary limit:  **Critical (Gemini-specific, F1 in `docs/observed-failure-modes.md`)**:
> gemini-cli **refuses to read gitignored files by default**. Since
> `.ai/` is conventionally gitignored to keep transient task files
> out of commits, this means
> `gemini -p "Read .ai/gemini_task__.md and execute"`
> **WILL FAIL** with `"File path '.ai/...' is ignored by configured
> ignore patterns."` — this is the single most common Gemini failure
> mode observed in dogfooding.
>
> **Default invocation pattern** (use this, not the `gemini -p "Read .ai/..."`
> pattern):
>
> ```bash
> # Pipe task content via stdin to bypass gitignore restriction.
> # Cap stdout at 10 MB to prevent runaway logs (incident pattern from
> # global CLAUDE.md).
> cat .ai/gemini_task__.md | gemini --yolo -p \
>   "Below is your full task brief via stdin. Execute it. Report
>    PASS/FAIL of the acceptance checks at end. Don't ask questions,
>    just do it." \
>   2>&1 | head -c 10485760 > .ai/gemini_log__.txt
> ```
>
> Avoid the older "inline TASK=$(cat)" pattern — it's longer and
> the `cat | gemini --yolo -p ...` pipe is what actually got tested
> on 2026-05-13. The ` is piped (the pipe satisfies stdin closure).
>
> When you produce the gemini task file, also produce a sibling
> shell snippet `.ai/gemini_run__.sh` with the inlined
> invocation, so the user can run it directly without manual
> assembly. Side effect of the inline mode: gemini doesn't have
> file-system context for the task file's referenced inputs — make
> sure the prompt body itself contains all critical context, not
> just paths.

#### 6c. Claude tasks (`agent: claude`)

**Don't write a task file.** Claude executes inline in the current
conversation. The plan.yml entry serves as the spec.

### 6d. Task-shape guidance (prevents F6 over-tabularization)

Before writing the task body, classify the task by **output shape**:

| Task shape | Format guidance to include in brief |
|---|---|
| **Pedagogical** (curriculum, tutorial, explainer) | "Prefer prose. A table is justified ONLY if (a) data is genuinely comparative (≥3 attributes per row) AND (b) reader will use it as decision tool, not inventory. 'Catalog of N variants' is anti-pattern — replace with prose covering 2-3 axes + `` for long tail." |
| **Reference** (API docs, schema definitions) | "Tables OK for structured data. Each table should answer one specific question." |
| **Catalog** (project listings, comparisons) | "Tables OK but include: (a) ≤ 10 entries in primary table; (b) `` collapsible for long tail; (c) live `gh api` verification step for stars/license/pushed_at — required in `result.md`." |
| **Migration / mechanical edit** (rename, replace pattern) | "No tables. Concrete file list + diff summary." |
| **Translation / mirror-sy

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [WenyuChiou](https://github.com/WenyuChiou)
- **Source:** [WenyuChiou/agent-collab-skills](https://github.com/WenyuChiou/agent-collab-skills)
- **License:** MIT
- **Homepage:** https://github.com/WenyuChiou/agent-collab-skills

Install and usage instructions live in the source repository linked above.