agent-task-splitter · diff
git:20261002.92631e4 to git:20261016.a802ce4
97 added, 148 removed. Audit A to A.
---
name: agent-task-splitter
- description: Use when a goal needs multiple bounded agent roles, parallel or dependent task packets, explicit scope partitions, and a provider-neutral DAG. Not for research-domain routing that owns .research, .paper, Zotero, Obsidian, or NotebookLM workflows; use research-hub-multi-ai for those.
+ description: Use when about to run two or more subagents, workflow lanes, or delegated CLI executors on one goal. Gives each lane a role, a pinned model tier, a disjoint file scope, a bounded brief, and a capped return, and fixes the merge and verification step before launch. Not for research-domain routing that owns .research, .paper, Zotero, Obsidian, or NotebookLM workflows; use research-hub-multi-ai for those.
---
- # agent-task-splitter
-
- Turn one approved goal into a provider-neutral role DAG and bounded task
- packets. This skill plans; it does not spawn agents.
-
- Read references/task_splitter_heuristics.md when role selection or DAG shape is
- not obvious. Read ../../docs/public-harness-contract.md for schemas and artifact
- policy.
-
- ## Roles
-
- - primary-agent: owns scope, architecture, and human communication.
- - delegated-executor: performs bounded implementation or mechanical work.
- - reviewer: independently tests and judges a stable candidate.
- - synthesizer: structures completed inputs without reopening discovery.
-
- The host chooses the adapter for each role. Do not put provider or model names
- in the public role field.
-
- ## Use this skill when
-
- - Two or more independent task packets can run in parallel.
- - Implementation and independent review must be separate.
- - A fan-out/fan-in or diamond DAG materially shortens the critical path.
- - Several results require explicit reconciliation and acceptance.
+ # agent-task-splitter (fan-out planner)
- Do not split exploratory debugging before the cause is known. Do not split a
- small coherent change merely to create agent activity.
+ Plan a fan-out before launching it. This skill plans; the host launches the
+ lanes. The name stays `agent-task-splitter` so existing prompts and plans keep
+ working.
- ## Inputs
+ ## Pick the mode
- - Goal and authorized scope.
- - Success criteria.
- - Files, systems, and external actions in/out of scope.
- - Available policy_ref and checkpoint_ref when any child may be spawned.
- - Existing recorded human decisions and evidence refs.
+ | Mode | Use when | Artifacts |
+ |---|---|---|
+ | Native (default) | All lanes run inside one host session: parallel or background subagents, workflow lanes, one-shot CLI delegates, with the user present | Lane table in the conversation and one brief per lane. No `.coord/` plan, packets, or checkpoint. |
+ | Harness | A round spans sessions or tools, an unattended loop runs, work must resume after an interruption, a signed human gate is needed, or `AGENT_COLLAB_POLICY` is configured | `.coord/plan.yml` (schema v2) and `.ai/task_<NNN>_<slug>.md` packets; see [references/harness-plan.md](references/harness-plan.md) |
- If scope or acceptance is ambiguous, ask one focused question. Do not invent
- permission for external writes.
+ A configured policy always selects harness mode, and an unreadable configured
+ policy fails closed. Native mode follows the host's own limits and
+ permissions and adds no numeric limits of its own. Host mechanics are in
+ [native lanes](../../docs/native-lanes.md).
- ## Workflow
+ ## Fan out only when
- 1. Confirm the repository/worktree root.
- 2. Restate the goal and scope.
- 3. Identify task boundaries by work character and evidence dependencies.
- 4. Assign one role to each task.
- 5. Build an acyclic dependency graph.
- 6. Partition write scope. Two parallel writers must not own the same file.
- 7. Add at least one runnable or objectively checkable success criterion per
- task.
- 8. Write .coord/plan.yml using schema_version 2.
- 9. Write .ai/task_<NNN>_<slug>.md for each non-inline task.
- 10. Return the ready task ids and dependency order. Do not spawn.
+ - two or more pieces are independent (none needs another's result) and each
+ has a checkable result; or
+ - implementation and independent review must be separate lanes.
- Before execution, the host captures the attributable pre-task baseline and
- states whether edits are required or unchanged output is permitted. Use the
- [task-content evidence review](../../docs/task-content-evidence.md); file times
- and a process-success status cannot establish acceptance. A read-only role
- does not need to manufacture an edit.
+ Do not split exploratory debugging before the cause is known, a small
+ coherent change, or work where every lane needs the same context in tight
+ sequence. Doing it directly is the default.
- ## Plan shape
+ ## The lane table
- schema_version: 2
- round: 1
- goal: "..."
- policy_ref: "${AGENT_COLLAB_POLICY}"
- checkpoint_ref: ".coord/task-checkpoint.json"
- created_at: "<ISO 8601 with timezone>"
- tasks:
- - id: T1
- role: primary-agent
- slug: define-contract
- description: "Freeze the public contract."
- depends_on: []
- files_in_scope: ["docs/contract.md"]
- files_out_of_scope: ["src/**"]
- success_criteria:
- - "contract is traceable to the current authorized user goal"
- - id: T2
- role: delegated-executor
- slug: implement-contract
- description: "Implement the approved contract."
- depends_on: [T1]
- files_in_scope: ["src/**", "tests/**"]
- files_out_of_scope: ["docs/contract.md"]
- success_criteria:
- - "python -m pytest tests -q"
- - id: T3
- role: reviewer
- slug: review-candidate
- description: "Review the stable T2 candidate."
- depends_on: [T2]
- files_in_scope: []
- files_out_of_scope: ["**/*"]
- success_criteria:
- - "verdict is PASS, FAIL, or NEEDS_HUMAN with evidence"
+ Write it before launching anything:
- Omit policy_ref/checkpoint_ref only when the plan cannot spawn or loop
- autonomously.
+ | Lane | Role | Executor | Model tier | May write | Must not touch | Acceptance | Return | Depends on |
+ |---|---|---|---|---|---|---|---|---|
+ | L1 | delegated-executor | subagent in a worktree | cheap | `src/a/**` | everything else | `pytest tests/a -q` | summary + paths | none |
+ | L2 | delegated-executor | CLI delegate | cheap | `docs/x.md` | `src/**` | link check passes | summary + paths | none |
+ | L3 | reviewer | read-only subagent | strong | nothing | `**/*` | verdict with evidence | verdict + findings | L1, L2 |
- ## Task packet
+ Rules:
- # Task: <id> — <description>
+ 1. Roles are `primary-agent`, `delegated-executor`, `reviewer`, and
+ `synthesizer`, defined in the
+ [public contract](../../docs/public-harness-contract.md). The executor
+ and model columns are host-adapter choices, not public plan fields.
+ 2. The orchestrator assigns the model tier; a lane never picks its own.
+ Mechanical, pattern-following work goes to a cheap tier. Review, verdicts,
+ root-cause analysis, security, governance, and anything ambiguous go to a
+ strong tier.
+ 3. Write scopes are disjoint. Two parallel writers never own the same file.
+ If scopes might touch, isolate the writers or run them in sequence.
+ 4. Every lane has at least one runnable or objectively checkable acceptance
+ criterion.
+ 5. Every lane has a capped return: a short summary plus file paths, never raw
+ logs or full diffs. `agent-context-budget` covers sizing.
+ 6. A lane cannot approve its own output. Author and reviewer are different
+ lanes.
- ## Context
- - Repo/worktree: <absolute path>
- - Plan: .coord/plan.yml
- - Role: <role>
- - Depends on: <task ids and artifact refs>
+ [references/task_splitter_heuristics.md](references/task_splitter_heuristics.md)
+ helps when a task could fit more than one role or DAG shape.
- ## Pre-task scope confirmation
- Before editing, report the exact allowed and forbidden paths. Stop if the
- brief conflicts with the plan.
+ ## Fix the merge step before launch
- ## Goal
- <one bounded deliverable>
+ Write down, before any lane starts:
- ## Scope
- - May read: <paths>
- - May write: <paths>
- - Must not touch: <paths>
- - External actions: <none or explicit authorization>
+ - who merges the results (normally the primary-agent) and in what order;
+ - the verification command run on the merged result, not only per lane;
+ - which `agent-acceptance-gate` presets the merged diff will trigger;
+ - commit boundaries: one reviewed commit per writing lane, or one commit
+ after the merged result passes. Read-only lanes need no commit.
- ## Acceptance
- - <runnable or objective criterion>
+ ## Brief per lane
- ## Return contract
- - status
- - concise summary
- - files_changed
- - tests_run
- - evidence_refs
- - baseline/candidate references bound to this task and run/attempt
- - change-required or permitted-unchanged result, with criterion evidence
- - risks
- - blockers
+ # Lane <id>: <one bounded deliverable>
+ Repo/worktree: <absolute path>
+ Role: <role>. Model tier: <tier>.
+ Depends on: <lane ids and artifact paths>
- Task packets and raw results are scratch. A task may write only its explicit
- shipping artifact; acceptance evidence is promoted separately.
+ Before editing, list the exact paths you may write and must not touch.
+ Stop and report if they conflict with this brief.
- ## Policy boundary
+ May read: <paths>
+ May write: <paths>
+ Must not touch: <paths>
+ External actions: none unless named here.
+ Edits required: yes | unchanged output allowed because <reason>
- Immediately before a host spawns a task:
+ Acceptance: <runnable check>
+ Return (capped): status; short summary; files changed; checks run and
+ results; risks; blockers. Put long output in a file and return its path.
- agent-collab policy evaluate \
- --policy <policy_ref> \
- --checkpoint <checkpoint_ref> \
- --json
+ ## Drift guards
- The host must not spawn unless decision=continue and spawn_allowed=true.
- Splitter output does not override that decision.
+ - Copy identifiers (slugs, paths, field names, version strings) verbatim into
+ the brief. Do not paraphrase them.
+ - Record the pre-lane baseline (commit or file hashes) so the result can be
+ attributed. File times and a process exit status do not prove the work was
+ done; use the [task-content evidence review](../../docs/task-content-evidence.md).
+ - State whether edits are required. A lane that reports success without
+ changing its required files has failed unless the brief allowed unchanged
+ output.
+ - Missing, null, failed, declined, cancelled, and timed-out lanes stay
+ non-success. Filter them out of synthesis but keep their records.
+ - Agent agreement never replaces running the checks.
- The host may delegate read-only exploration while planning, but must not turn
- a planning-only request into implementation. Prefer direct execution for small
- coherent work. Reserve capacity for required independent review and retain
- cumulative child usage when a v2 slice advances. Agent boundaries alone do not
- require commits or fresh human authorization.
+ ## Harness mode
- ## Invariants
+ 1. Write `.coord/plan.yml` (schema_version 2) and one packet per non-inline
+ task, using [references/harness-plan.md](references/harness-plan.md).
+ 2. Immediately before each spawn the host runs
+ `agent-collab policy evaluate --policy <policy_ref> --checkpoint <checkpoint_ref> --json`
+ and spawns only on `decision=continue` with `spawn_allowed=true`. The plan
+ never overrides that decision.
+ 3. Coordination files are scratch and gitignored. Promote only an explicit
+ checkpoint snapshot, shipping artifact, or acceptance record.
+ 4. Do not encode retries in the plan; the policy decides them.
- - Provider names are transport metadata, not public roles.
- - Reviewer and synthesizer are different: a synthesizer structures accepted
- inputs; a reviewer judges them.
- - A task cannot approve its own semantic or governance-sensitive output.
- - Missing, null, failed, declined, cancelled, and timed-out tasks stay
- non-success.
- - Every parallel result list filters absent/failed results before downstream
- synthesis while retaining their failure records.
- - Agent voting never replaces evidence verification or a human gate.
+ Historical schema-less plans and provider-specific task paths are parse-only;
+ see [migration 0.4](../../docs/migration-0.4.md).
- ## Compatibility
+ ## Output
- Historical schema-less plans and provider-specific task paths are parse-only.
- Writers emit v2 roles and generic task paths. See
- ../../docs/migration-0.4.md.
+ Return the lane table, each brief (or its path), the ready lanes in launch
+ order, and the merge-and-verify step. Do not launch lanes from this skill and
+ do not turn a planning-only request into implementation.