tdmcp-backlog-campaign

Files (1)

• SKILL.md

SKILL.md (first lines)

# tdmcp-backlog-campaign — whole-backlog delivery

A single feature-build wave is already handled well by **`tdmcp-pipeline`** (the
five specialists) and **`tdmcp-feature-lead`** (parallel builders + single-writer
integrate). This skill is the layer they do not provide: driving an entire **backlog**
of dozens of features to completion across **multiple themed releases**, *resumably*.
It is a thin, ledger-driven loop over the existing pipeline — it adds idempotency,
resilience, shared-schema sequencing, and a checkpoint/release policy; it does **not**
re-implement building.

> **When NOT to use this:** one feature, or one small ad-hoc batch → `tdmcp-pipeline`.
> A whole survey/backlog file, "all the features", or "continue the campaign" → here.

## The two things this skill owns

1. **The ledger** (`_workspace/campaign_<id>/ledger.json`, in the **main repo
   checkout** — resolve with `dirname "$(git rev-parse --path-format=absolute
   --git-common-dir)"`, never the worktree, so state survives worktree cleanup and is
   shared across sessions). One row per feature; `build-ledger.mjs` beside it
   regenerates the static plan **merge-safely** (preserves live state). This is the
   idempotency + resilience substrate. Status vocabulary:
   ```
   pending → designing → building → integrating → qa → shipped
   side: blocked-dep | blocked-td | quarantined | merged | tracked-elsewhere
   ```
2. **The wave/release loop** — pick the next ready wave (via `tdmcp-backlog-planner`),
   run it through the pipeline foundations-first, release it under policy, fold the
   results back into the ledger, then checkpoint or continue.

## Execution policy — read it from `ledger.policy`, do not assume

The ledger carries the policy the user chose; honor it literally. For the current
campaign (`beyond_20260530`):

| Policy | Value | Meaning |
|---|---|---|
| `scope` | `staged-by-priority` | Run waves in order; **pause after `checkpoint_after_wave`** for a go/no-go before continuing. |
| `checkpoint_after_wave` | `1` | After wave 1 (P0 + Top-12) ships, **stop and report**; wait for the user to say continue. |
| `release` | `commit-and-push-NO-tag` | The releaser writes CHANGELOG + bumps version + commits + **pushes the branch**, but must **NOT `git tag`** (the repo's tags diverged; tagging is held). |
| `td_required_before_build_waves` | `true` | A wave touching `needs_td` features only runs when `get_td_info` reports connected. If offline, hold those features (`blocked-td`) and say so; never fake a live pass. |
| `builder_retry` | `1` | One retry per failing builder/feature. |
| `on_repeat_fail` | `quarantine-and-continue` | After the retry, mark `quarantined`, record the gap, and **keep the wave moving** — one stuck tool never blocks the rest. |

## Agent roster (all reused except the planner)

| Role | Agent / skill | New? |
|---|---|---|
| Campaign brain / ledger steward | `tdmcp-backlog-planner` | **NEW** |
| Per-feature design spec | `td-architect` (`td-feature-design`) | reused |
| Isolated tool builder (×N parallel) | `td-builder` / `tdmcp-tool-builder` | reused |
| Single-writer integrator | `td-integrator` (`td-feature-integrate`) | reused |
| Live + gate QA (incremental) | `td-qa` (`td-feature-qa`) | reused |
| Release (CHANGELOG/bump/commit/push) | `td-releaser` (`td-feature-release`) | reused |

All `Agent` calls use `model: "opus"` for design/integrate/QA/release/planner;
**builders** follow the project convention — `sonnet` for prescriptive tools, `opus`
for the ones needing design judgment (probe-live / novel topology). This env has **no
`TeamCreate`** — the integrate↔QA↔fix loop runs as coordinated `Agent`-tool sub-agents
(spawn integrator, then QA, then a builder-fixer on each defect), exactly as
`tdmcp-feature-lead` and `tdmcp-submission` do.

## Workflow

### Phase 0 — locate + decide run mode (idempotency entry point)

1. Resolve `CAMPAIGN_DIR = <main-root>/_workspace/campaign_<id>/`. If no `ledger.json`,
   run `build-ledger.mjs` to create it (or, for a brand-new backlog, author a
   `build-ledger.mjs` for it first — see "Starting a campaign for a new backlog").
2. Read `ledger.json`. Decide:
   - **All buildable features `shipped`** → campaign complete; report and stop.
   - **A wave is mid-flight** (features in `designing`/`building`/`integrating`/`qa`)
     → resume: spawn the planner to reconcile reality first (it verifies files/wiring
     against the tree and repairs lying statuses), then continue that wave.
   - **Otherwise** → start the next ready wave.
3. Ensure a working branch exists and record it in `ledger.policy.branch` (commits land
   here; never commit straight to `main`).

### Phase 1 — plan the wave

Spawn **`tdmcp-backlog-planner`** (`model: "opus"`). It reconciles the ledger against
the tree, computes the next ready wave (deps + shared-schema-first satisfied,
`needs_td` honored against live bridge state), and writes `wave_<N>_manifest.json` +
`wave_<N>_planner_report.md`. Read the manifest; respect its `foundations` →
`parallel` sub-batch order and its `blocked[]` exclusions.

### Phase 2 — TD gate

If the wave has `needs_td` features, call `get_td_info`. Connected → proceed with full
live validation. Offline → build only the wave's offline-safe features now, mark the
`needs_td` ones `blocked-td`, and tell the user which tools await TD (per
`td_required_before_build_waves`). Never block the whole campaign on a missing bridge,
and never claim a live pass you could not observe.

### Phase 3 — run the wave (foundations first, then fan out)

For the **foundations** sub-batch (shared schemas / promoted primitives), run them
**first and serially-ish** so their contract is fixed before dependents consume it:
`td-architect` spec → 1 builder → integrate → QA → mark `shipped`. Update the ledger
after each transition.

Then the **parallel** sub-batch, exactly the `tdmcp-pipeline` Phase 2–4 loop:
1. `td-architect` fan-out (one per feature, `run_in_background`), specs to
   `_workspace/01_design_<id>.md`. Resolve any flagged cross-feature contention
   (especially shared-schema consumers) before building.
2. `td-builder` fan-out in a **single message** (~4–6 at a time; a larger ready set
   becomes ordered sub-batches). Each: **new files only**, green-in-isolation (vitest
   + biome + typecheck). Set each feature `building`.
3. `td-integrator` as the **single writer** wires every built tool into the layer
   `index.ts` / `src/cli/agent.ts` / `src/prompts/index.ts`, then the four gates
   (`typecheck`, `build`, `./node_modules/.bin/biome check .`, `test`; +
   `validate:recipes` if a recipe changed). Set features `integrating`.
4. `td-qa` **incrementally** as each feature integrates — gate pass + (TD up) live
   create→cook→`get_td_node_errors`→`get_preview`. Defects go back to a builder-fixer
   (`file:line` + fix), re-validate, cap ~2–3 rounds. Set `qa`, then `shipped` on PASS.
5. Update each feature's `status/qa/files/history` in the ledger as it resolves.

### Phase 4 — release the wave, fold results, checkpoint

1. **Docs/CHANGELOG/ROADMAP** for everything that shipped this wave (the integrator/QA

From hybridlabor-api/aos, Apache-2.0.

More from hybridlabor-api/aos