# Task

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

- Skill: `arasz/task-2` (Agent Skill, multi-file: 34 files)
- Install (CLI): `npx skillmds@latest add arasz/task-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arasz/task-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: Arasz (https://skillmd.com/u/arasz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/arasz/task-2

---


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

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

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

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

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

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

**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,
research record gathered, taskId derived.

1. **Determine effort.** 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.

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.

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

   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.

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

## 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,
   open a draft PR early per `extensions/github/`.

## Phase 4 — Quality gate

Entry: all plan points implemented 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
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
- [ ] Task-ID derived per the `{repo-alias}-{key}` formula and is unique
- [ ] Effort was determined (low or high) 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)