task · diff

v1.0.0 to v1.0.0

44 added, 46 removed. Audit A to A.

---

name: task

description: >-

Use when the user wants to start, continue, or finish a backlog task — "/task <id>", "start

task X", "work on the next task", "finish this task". Runs it end-to-end as a

- token-tracked unit of work with low/high effort, plan packaging with

- mandatory integration package, MoE panels for high-effort, and automated task-ID

+ token-tracked unit of work with low/high effort, `task-decomposition` into a `task-plan`

+ whose `workflow` is a DAG of `step`s, MoE panels for high-effort, and automated task-ID

derivation ({repo-alias}-{key}). Delegates planning/review to high-reasoning models

and implementation to persona-routed agents. Project specifics from

.ai-badger/config.json; source-control and PR behaviour from config-gated extensions.

version: 1.0.0

author: ai-badger

license: MIT

platforms: [linux, macos]

scope: default

metadata:

hermes:

tags: [task, orchestration, delegation, worktree]

related_skills: [create-task-spec, commit-reminder, test-economy, multi-agent-communication]

---

# task orchestration skill

Runs one backlog task as a separated, token-tracked unit of work. High-leverage thinking —

planning and the final quality gate — is delegated to a high-reasoning model; implementation

models do the hands-on work; the orchestrating session integrates and tracks everything so a

dead session can be resumed.

**All project specifics come from `.ai-badger/config.json`** — never hardcode a build command,

a persona name, or a repository. Tracking data lives in `.ai-badger/task-tracking/` (gitignored).

- Scripts live in this skill's `scripts/`. Before hand-writing any tracking store, read `references/file-schemas.md` for its exact shape.

+ Scripts live in this skill's `scripts/`. Before hand-writing any tracking store, read `references/file-schemas.md`.

## When NOT to Use

- A single-file typo fix or one-off question — no tracking, worktree, or delegation needed

- Work the user wants done inline in this session

- Anything where the token-tracked pipeline's overhead exceeds the task — use the plain workflow

## Default Loop

Every task follows a low- or high-effort loop. The loop is the spine; the phases below

(Phase 0–6) detail its steps.

- Before starting, **ask the user whether this is a low- or high-effort task**. When autonomous,

- derive effort after analyze — a best-effort match of effort to scope.

+ Before starting, **ask the user whether the task runs the low or high `loop`**. When autonomous,

+ derive the loop after analyze — a best-effort match of loop to scope.

### Low-effort loop

prepare → analyze → plan → plan review → implementation → review implementation →

apply fixes → pr → gates → close task → reflect → merge

### High-effort loop

prepare → analyze → plan (MoE) → plan review (MoE) → implementation →

review implementation (MoE) → apply fixes → QA: test quality & coverage → pr →

gates → close task → reflect → merge

- Integration step: always required in the high-effort variant. Every plan's last package

- is the integration package.

+ Integration step: required in the high-effort variant. The plan carries a join step when the

+ `workflow` has more than one sink; it depends on every sink and carries the cross-step tests.

### Step definitions

**prepare** — Create isolated worktree from fresh `main`, push branch, create draft PR.

**analyze** — Derive `taskId` (`{repo-alias}-{key}`). Extract scope, constraints, criteria.

- **plan** — Split work into **packages** (mergable units) and **subpackages**. Last package is the

- **integration package** with cross-package tests. Every package has ACs; plan AC: all checked+met.

+ **plan** — Run `task-decomposition` into a `task-plan` whose `workflow` is a DAG of

+ `step`s. Every step has ACs; the plan AC: all steps' ACs checked+met.

**plan review (MoE)** — High-effort: MoE panel (3 experts, subject-matched). At least one expert

different from plan authoring.

**implementation** — Code phase per persona routing. TDD mandatory.

**review implementation** — Low-effort: single subagent. High-effort: MoE panel (3 experts, at

least one different from plan MoE).

**QA: test quality & coverage** — High-effort only. Assess test honesty and coverage gaps.

**apply fixes** — Fold review findings into code. Trivial directly, larger via subagent. Re-run

build/test.

**pr** — Prepare PR for review, ensure CI runs.

**gates** — Per-repo gates from `config.json`. CI decides the local budget: alive →

touched surface locally, once, CI is the gate; CI dead → gates once, else one manual

full-suite run.

**close task** — Close tracking, remove clean worktree, update state files.

**reflect** — Check memory, semantica, session history. Distil durable facts. Promote to shared

context.

**merge** — Final PR merge.

### Task-ID derivation

`taskId` is **derived during the analyze step**. Formula:

{repo-alias}-{key}

- **repo-alias:** Constant per repo. Examples: `jsaa`, `aib`, `air`, `ahp`. Determined by checking

`config.json`'s `sourceControl.repoAlias`, memory, or deriving from repo name.

- **key:** 5 words conveying purpose. Hyphenated lowercase slug.

Example: `aib-default-loop`.

## Config contract (read first)

From `.ai-badger/config.json`:

- `commands.build` / `commands.test` / `commands.lint` — the verification commands for Phase 4.

- `personaRouting` — maps kinds of work to the scaffolded personas; drives Phase 3 dispatch.

- `sourceControl` — platform + repo/project URLs; **gates the source-control extension** (PR

flow, review loop, issue/board integration). If `sourceControl.platform == "github"` and a

`repoUrl` is present, this skill's `extensions/github/` fragment is active — follow it for the

PR/review-loop steps below. Otherwise commit locally and integrate per your platform.

## Model & delegation policy

Spend high-reasoning capacity on plans and reviews, not implementations. Obtain reasoning via

delegation, not by assuming your own model.

- **Delegate to a high-reasoning agent** for planning (Phase 2) and the quality gate (Phase 4).

- **Delegate to implementation agents** per `config.json`'s `personaRouting`. TDD mandatory.

- **Delegate trivial mechanical work** (doc updates, rote refactors, test backfills) to a cheap model.

- **The orchestrating session does directly:** fetch the task, read docs, record token usage,

per-subagent completion checks, build/test, and tiny surgical fixes.

- The ten prompting rules govern every brief. Read `references/prompting-rules.md` before composing briefs.

Roles, not models. Which concrete model fills each is bound by the agent-specific extension.

### Model tier contract

- `effort` (low/high) picks the loop; `level` picks the model tier — they are independent, never bare `level` for effort.

+ The task `loop` (low|high) chooses the orchestration loop; a step's `effort` (low|medium|high) drives model-tier selection.

The `level` field is optional (`low`, `medium`, or `high`), resolved to that model tier's preferred registry entry.

- An explicit `model` always wins over `level`.

- With neither `level` nor `model`, the dispatch inherits the session (or parent) default model.

- The registry lives at `.ai-badger/model-groups.json`; it holds the IDs and prices, so this skill names neither.

- See `.ai-badger/delegation.md` (reasoning-model dispatch).

+ Precedence: explicit `model` > `level` > the step's `effort` used as the level > the session (or parent) default model.

+ An explicit `model` always wins over `level`; with neither, the dispatch inherits the session (or parent) default model.

+ Registry: `.ai-badger/model-groups.json`; see `.ai-badger/delegation.md` (reasoning-model dispatch).

Subagent prompts must be self-contained: scope, ACs, files, TDD rules, report-back shape. Parallelise

- independent subagents. **Split work so it *can* run in parallel** — name shared-file sections

- (serialise) vs disjoint ones (parallel).

+ independent subagents. **Split work so it *can* run in parallel** — name shared-file steps, which

+ serialise by a `depends_on` edge or a merge, versus disjoint steps, which parallelise.

- **Isolate every agent, at every depth: its own worktree and its own workspace id.** Disjoint files

- are not isolation — shared build output means a green run proves nothing. Two levels max.

+ **Isolate every agent, at every depth: its own worktree and its own workspace id.** Two levels max.

**Write the brief so the lane can improve on it.** Before dispatching an end-to-end lane, read

`references/lane-dispatch-brief.md`.

**Reach for what exists.** A code graph, MCP server, or existing skill beats writing from scratch.

**If you cannot spawn subagents**, work directly in-session. Note reduced rigor in your summary.

## Phase 0 — Context hygiene

1. `python3 .ai-badger/skills/task/scripts/task_tracker.py status`. If a previous task is unfinished, finish or park it.

2. Confirm `.ai-badger/state.json` reflects the last finished task; repair if not.

3. If this session carries heavy history, tell the user to `/compact` (or start fresh) and

re-invoke `/task <id>` on a clean context, then stop — unless autonomous.

## Phase 1 — Start

Entry: previous task finished or parked; clean-enough context.

- Exit: effort chosen, tracker STARTED, worktree exists, five preflight blocks present,

+ Exit: loop chosen, tracker STARTED, worktree exists, five preflight blocks present,

research record gathered, taskId derived.

- 1. **Determine effort.** Ask user low or high. When autonomous, derive after analyze.

+ 1. **Determine the loop.** Ask user low or high. When autonomous, derive after analyze.

2. **Analyze the task.** Resolve the task (issue URL or freeform scope/title). Read referenced docs.

**Derive the taskId** per the derivation formula. Determine repo alias

(check `config.json`'s `sourceControl.repoAlias`, memory, or derive from repo name).

Compose the key from 5 words conveying purpose. Validate uniqueness vs existing entries.

**If the argument is a path to a `spec.json` written by `create-task-spec`,** read it and its

companion `.feature` file instead of treating the path as a title: the manifest supplies the

scope, out-of-scope, constraints and deferred decisions, and the spec supplies the acceptance

criteria. Feed both to the planning agent in Phase 2, and hold the non-deferred scenarios as

Phase 4's pass condition.

**Preflight checklist** (Rule 1): confirm the brief has objective, constraints, known unknowns,

output contract, and stop condition. Fill missing blocks from review or ask the user.

3. Register: `python3 .ai-badger/skills/task/scripts/task_tracker.py start <taskId> --title "<title>" --branch task/<taskId>-<slug>`.

`start` must exit 0 (when it does not, follow `references/tracking-visibility.md`).

4. Ask the user to rename the session to match the task (skip if autonomous).

5. **Work in the worktree `start` just created** — it prints the path, and it is

`.ai-badger/worktrees/<taskId>` on the branch you passed to `--branch`. Every command for

the rest of the task runs there, not in the main checkout.

`start` records the branch name without creating anything (`--no-worktree` reverts to the

old in-place behaviour). Work in the worktree: sharing one checkout lets another session

switch branches mid-run. When more than one session shares the project, announce

milestones on the bus — read `multi-agent-communication` when parallel work is active.

5. **Research before you plan, and plan the review first** (`evidence-first-research`

formalises the method for non-trivial tasks; dispatch it rather than re-describing it).

List what must be checked — every point in the request, marking which need research over

guess. Gather the evidence into a research record where every finding cites its source

path and every unverified claim is labelled a hypothesis. A plan before this record is a

guess with a table around it. Run independent angles as parallel read-only lanes and

consolidate per `multi-lane-report-assembly`.

## Phase 2 — PLANNING

Entry: research record exists with sources cited.

- Exit: reviewed plan; every point carries criteria and a gate; parallelism named; plan split

- into packages and subpackages.

+ Exit: reviewed `task-plan` recorded; every step carries criteria and a gate; shared-file steps

+ serialised by an edge; join step present when >1 sink.

- 1. **Plan from what the research found.** Delegate decomposition to a high-reasoning agent (the

- `architect` persona), feeding it the task body, the research record and doc excerpts.

+ 1. **Plan from what the research found.** Delegate decomposition (the `architect` persona),

+ feeding it the task body, the research record and doc excerpts.

- **Split the plan into packages.** Each package is a unit of work delivering a mergable piece.

- Subpackages are partial units within a package. Every package contains its test scenarios.

- The **last package is always the integration package** — it ensures all packages are

- correctly integrated and includes cross-package integration tests. Each package has its own

- acceptance criteria; the plan's top-level acceptance criterion is: *all packages' ACs are

- checked and met*.

+ **Split the plan into steps.** Run `task-decomposition`; the result is one validated

+ `task-plan` whose `workflow` is a DAG of `step`s, one lane per step. Record the plan with

+ `plan_create`; with no server available, write the plan file by hand in the frozen shape and

+ say the graph is off. `depends_on` is the only ordering source; the top-level criterion:

+ *all steps' ACs are checked and met*. A task with no plan row keeps its legacy plan file and

+ manual checkboxes — never `plan_create` over an in-flight task.

In the **low-effort** variant, a single high-reasoning agent creates the plan.

In the **high-effort** variant, delegate to an MoE panel (default 3 experts) matching the

task's subject area.

- Split the plan into sections that can be worked independently, and say which may run at the

- same time. Parallelism has to be designed in; it does not arrive on its own.

+ The server derives the ready set and waves via `steps_ready` — say which steps run together;

+ parallelism is designed in via `depends_on` edges, never assumed.

- **Every point carries acceptance criteria and a quality gate** — what must be true, and the run

- that proves it. A point without them is a wish. Where a point needs a specification or a design

- before it can be built, produce one, and look for an installed skill that formalises that shape

- before writing a bespoke document. Before the first failing test, run `design-tests` on the

- acceptance criteria — the test list is part of the plan, not of the implementation. When a

- plan point changes architecture or flow, present it with `archify` (Mermaid only when its

- runtime is missing). When status cannot match the plan, follow `references/tracking-visibility.md`.

+ **Every step carries acceptance criteria and a quality gate** — what must be true, and the run

+ that proves it. A step without them is a wish. Where a step needs a specification or design

+ first, produce one — prefer an installed skill. Run `design-tests` on

+ the acceptance criteria before the first failing test — the test list is part of the plan,

+ not of the implementation. When a step changes architecture or flow, present it with

+ `archify` (Mermaid only when its runtime is missing). When status cannot match the plan,

+ follow `references/tracking-visibility.md`.

2. **Plan review before dispatch.** In the **low-effort** variant, hand the drafted plan to a

second high-reasoning agent for review. In the **high-effort** variant, delegate to an MoE

panel (default 3 experts, at least one different from the plan-authoring experts) and have it

attack structure, feasibility, budget arithmetic, and testability. Fold MUST/SHOULD findings

back into the plan before any implementation dispatch. Same join discipline as Phase 4,

applied early where defects cost least. When consolidating reviewed

- plan sections into lane briefs, follow `references/lane-dispatch-brief.md` — sections sharing

- a file serialise, the rest parallelise.

+ plan steps into lane briefs, follow `references/lane-dispatch-brief.md` — steps sharing

+ a file serialise (add a `depends_on` edge or merge them), the rest parallelise.

## Phase 3 — Execute

1. Dispatch implementation subagents per `personaRouting`. Instruct every code subagent to write

the failing test first (TDD). Name lanes per `references/tracking-visibility.md` when status

must see them.

**Operator contract** (Rule 4): each agent brief must include tool names, abort criteria,

success predicate, and handoff conditions. Persona prose is optional, one short line only.

2. Record the lane's `total_tokens`:

`python3 .ai-badger/skills/task/scripts/task_tracker.py subagent <taskId> <n>` or `--delegation <id>`.

Interactive pi delegations return receipts by default; the `delegation-result` followUp carries

`details.usage` (input+output); `background:false` blocks. Record on EVERY delegation

completion; when harness receipts differ, see `references/tracking-visibility.md`.

3. Review each result at the seams (matches plan? acceptance criteria?). Send follow-ups back

rather than rewriting, unless the fix is a few lines.

- 4. Commit and push per work package (small commits). If the source-control extension is active,

+ 4. Commit and push per step (small commits). If the source-control extension is active,

open a draft PR early per `extensions/github/`.

## Phase 4 — Quality gate

- Entry: all plan points implemented and committed in the worktree.

+ Entry: every step complete, all ACs checked and committed in the worktree.

Exit: CI green (or documented local-gate equivalent); review findings fixed or filed; QA

test quality reviewed (high-effort variant).

1. Run the modified surface's tests once.

2. **Review implementation.** In the **low-effort** variant, delegate review to a

high-reasoning agent (the `code-reviewer` persona) with the diff, acceptance criteria,

relevant architecture docs, and the build/test output. In the **high-effort** variant,

delegate to an MoE panel (default 3 experts, at least one different from the plan MoE

and plan review MoE). Ask it to judge implementation correctness (logic, edge cases, test

honesty) and architecture (layer purity, consistency with docs).

3. **QA: test quality & coverage** (high-effort variant only). After the implementation review,

delegate a dedicated quality assessment of test coverage and test honesty — can the tests

actually fail? Are there gaps in coverage? See `review-tests` skill.

4. **Apply fixes.** Fix findings (trivial yourself, substantial via a subagent), re-run the

touched suite, then proceed. If the diff adds or changes test files, also delegate

`review-tests` on those files to `qa` (or the stack's `qa-backend`/`qa-frontend`) and treat

a `blocker` finding the same as a red build. Docs-only tasks with no test changes skip

`review-tests`; projects without CI fall back to the full local lane set as the pass

condition. When push, CI, or PR trouble arises during this phase, follow the `git-work`

skill before improvising.

### Review every join, not just every part

- Each time work is combined — review findings into a plan, sections into one change, branches

+ Each time work is combined — review findings into a plan, steps into one change, branches

into one PR — check the combination. Parts that pass alone fail together: two branches pick

the same version, one renames what another calls, a guard passes on each half and fails whole.

Run checks against the combined result, not the pieces.

**Then stop checking.** Execute the plan rather than re-reading it; a third self-pass costs as

much and finds less. Re-verify after integration only when

something changed, a claim is load-bearing, or a check has never been seen to fail. **Facts

are the exception**: anything from docs, an earlier run, or another's research gets re-checked

every time — that is what goes stale while your reasoning stays put.

### The slow suites

The pre-push hook runs the cheap checks; the slow ones belong to CI. CI's

result is the pass condition, not the green pre-push. Run a slow lane yourself only as the

sole active session with CI dead or absent. One run per suite per change; repetition is

diagnosis work. Docs, comments, and lint are never skipped.

## Phase 5 — Finish protocol

Entry: Phase 4 exit held.

Exit: merged, state updated, tracking closed.

1. If the source-control extension is active, follow `extensions/github/` for PR-ready, the

review-round loop, and squash-merge. Otherwise integrate per your platform.

2. **Update state files:** prepend the finished task's lean entry to `.ai-badger/state.json`'s

`completedTasks`, refresh `next`/`lastUpdated`; write verbose notes/decisions to the

project's notes file.

3. Compaction check on CLAUDE.md if the project tracks one.

4. Close tracking: `python3 .ai-badger/skills/task/scripts/task_tracker.py finish <taskId>`. This

also removes the task's worktree — **unless it still holds work that exists nowhere else** (see

`references/tracking-visibility.md` when it refuses).

5. **Reflect.** Examine what was learned during this task. Check AiRaccoon memory for the

current workspace, query semantica entries if available, and review the session history.

Distil: what should be remembered as durable facts? Write any cross-task learnings to

memory. Promote high-value entries to shared context if applicable. Record decisions in

semantica.

6. Ask the user to grade the skill 0–5: `python3 .ai-badger/skills/task/scripts/task_tracker.py grade <taskId> <0-5>`

(skip/leave unset if autonomous).

7. Report the task's token cost and recommend `/compact` or a fresh session before the next

task — this is the default ending. **Authorized auto-continue** (only when the `auto-wm`

skill's autonomic/partner mode is active, or the invocation explicitly said to continue):

after Phase 6, compact per Phase 0, read the next task from `.ai-badger/state.json`'s `next`

field (or the next unclaimed backlog item), and invoke this skill again. Otherwise start fresh

and tell the user to re-invoke for the next task.

## Phase 6 — Documentation-gap audit

After integration, delegate a doc-audit agent (worktree-isolated) to check CLAUDE.md and the

project's docs against the merged code, fix small drift, and report gaps needing a decision.

## Gotchas

- **`start` with `--no-worktree` records a branch name nothing creates.** `status` then reports a

branch that does not exist.

- **Interactive pi delegation = receipt, not answer.** Answers land as

`delegation-result` followUps; review seams as they land.

- **Never rewrite always-loaded context files (`CLAUDE.md`, `.ai-badger/state.json`) mid-task.** Cache

reads depend on byte-stable prefix (~10× cost); rewrite only between tasks.

- **Two levels of dispatch, no deeper.** A widening agent tree starves the machine.

- **Isolated = per-agent worktree + per-agent workspace id.** Shared build output defeats isolation.

## Recovery

`task_tracker.py` records the task's session id and resume command. Pass `--cron` to `start` to

install a resume cron. After resume, run `task_tracker.py reattach <taskId>` first, then continue.

> **Extensions:** PR/review/issue behavior in `extensions/github/`, model lanes in

> `extensions/claude/extension.md` — embedded by `welcome-ai-badger` per `config.json`.

## Verification Checklist

Each phase's Entry/Exit lines above are the checklist; this list carries only the

machine-run gates that close the task.

- [ ] `python3 .ai-badger/skills/task/scripts/task_tracker.py status` shows the task finished and `.ai-badger/state.json` reflects it

- [ ] All work lives in the worktree `start` created — no stray commits on the main checkout's branch

- - [ ] Every plan point's acceptance gate ran; plan was split into packages with the last being integration

+ - [ ] Every step's acceptance gate ran; all step ACs checked; join step carried the cross-step tests

- [ ] Task-ID derived per the `{repo-alias}-{key}` formula and is unique

- - [ ] Effort was determined (low or high) before implementation began

+ - [ ] Task `loop` (low or high) was determined before implementation began

- [ ] High-effort tasks ran QA test quality & coverage step

- [ ] `reflect` step examined memory, semantica, and session history for learnings

- [ ] `finish` left no worktree with unmerged or uncommitted work — `keptBecause` empty or resolved

- [ ] Token cost reported and compact/fresh-session advice given (or the auto-continue condition held)