Task Swarm

---
name: task-swarm
description: "Lightweight autonomous feature pipeline: self-healing plan-decompose → preflight → autonomy-grant → feature-implement --autonomous. DRY sequencing only; child skills own all machinery."
version: "3.3.0"
allowed-tools:
  - Read
  - Write
  - Bash
  - Glob
  - Skill
  - AskUserQuestion
---

# /task-swarm "<task description>"

## Host dispatch contract

- Codex: `$skill`, Codex collaboration roles, and GPT-5.6 tiers.
- Claude: `/skill`, Agent/Skill tools, and Claude aliases.
- A bare `/skill` in this shared source denotes the Claude form; Codex dispatches the same named skill as `$skill`.

## Init gate

Before any other step, run the advisory init guard and relay its output
verbatim:

```bash
bash "$(git rev-parse --show-toplevel)/scripts/gsd/init-guard.sh" || true
```

If it printed `INIT-GUARD:` warnings, offer `/ffs-init` before proceeding in
interactive sessions (declining proceeds anyway); headless, spawned, and
autonomous runs relay the warnings once and continue. Advisory only — never
a block, never an exit-code change.

At entry, make one opportunistic, fail-soft `bash scripts/gsd/reconcile.sh` pass; never block on its result.

One command from free-text instruction to shipped, canaried change. It is the
lightweight sibling of `/feature-spec`: no speckit specify/plan/clarify ceremony,
but the same operational spine after planning. Pure sequencing front-end —
every stage IS an existing skill (`plan-decompose`,
`preflight`, `autonomy-grant`, `feature-implement`); this skill owns only the
ordering, the spec-id capture, and the results.md wrapper line. `/fix` is the
sibling front-end for the no-planning case (`/feature-implement --adhoc`).
MAX-AUTH auto-grant by default — zero planned stops; `--gated` restores the
review stop.

```
/task-swarm "add rate limiting to the webhook endpoints"
     │
     ├─ 1. /plan-decompose  (create → review → bounded self-repair →
     │      spec-decompose → score → bounded self-repair)
     ├─ 2. preflight        (emit specs/NNN/preflight.json → gates.py preflight → PASS)
     ├─ 3. grant ledger     (enumerate typed gates from tasks.md → AUTO-GRANT
     │                       [--gated: operator yes first] → ledger)
     └─ 4. /feature-implement NNN --autonomous
            (roster swarm impl → QA loop → review-gate → ship → canary, ledger-gated)
```

## Flags

```
/task-swarm "<task>"                 # full autonomous run (ZERO stops — MAX-AUTH auto-grant)
/task-swarm "<task>" --gated         # review + approve the gate list at Step 3
/task-swarm "<task>" --attended     # skip grant; gates prompt during implement
/task-swarm "<task>" --no-swarm     # single-planner decomposition passthrough
/task-swarm "<task>" --dry-run     # print the stage plan, execute nothing
```

## Procedure

**Managed-ingress gate (check first).** If `FFS_MANAGED_INGRESS=1`, do not run
Steps 0–5 or delegate anything: go straight to
[Managed ingress](#managed-ingress-release-b-opt-in-spec-014) and invoke
`scripts/gsd/ffs-frontend.sh task-swarm`. Any refusal it prints is the result.

Cross-session coordination (spec-009) is inherited, not re-implemented: the
execution step routes through `/feature-implement`, whose Step 1.5
claim-or-stop claims the run id (interactive) or defers to `gsd-run.sh`'s own
claim (headless). A REFUSED claim means another live session owns this work —
stop and inspect `python3 scripts/coord/coord.py status`.

### Step 0 — continuity + recall (fail-soft)

- Continuity is gsd-native: `.planning/STATE.md` survives context resets.
  Resume with Claude `/gsd-resume-work`, Codex `$gsd-resume-work`, or the
  host-preserving headless runner. No external checkpoint call needed.
- If gbrain is present (`command -v gbrain` + `env -u DATABASE_URL gbrain doctor`
  healthy): `env -u DATABASE_URL gbrain query "<task topic>"` for prior
  decisions. Fail-soft — absence never blocks.

### Step 1 — plan + decompose

Invoke the `plan-decompose` skill with the task description. It runs
`/plan-eng-review` (autonomous mode), the opposite-host plan gate, then
`/spec-decompose` (gsd project seed + `/gsd-plan-phase`). Output: a seeded
`.planning/` project keyed to spec ID NNN.

`plan-decompose` owns all plan/task gate remediation. It automatically repairs
and rechecks rejected plans and under-scoring task decompositions within its
bounded retry budget. `/task-swarm` MUST NOT duplicate that loop or stop on the
first gate failure. Continue when the child returns PASS/WARN; stop only on its
terminal `PLAN-DECOMPOSE-BLOCKED` result after the repair budget is exhausted,
and surface the concrete findings artifact and exact resume command.

Operator authorization and quality are separate: MAX-AUTH covers outward
actions later in the pipeline, while plan quality is satisfied through bounded
self-repair—not bypassed and not turned into a planned operator stop.

### Step 2 — preflight (always; while the operator is still around)

Capture the spec id from Step 1's output: `NNN` = BARE NUMERIC id (strip any
`-name` suffix — ledger convention is `spec-057`, never `spec-057-name`);
`RUN_ID="spec-${NNN}"`.

Then invoke the `preflight` skill for `RUN_ID` — it owns the whole contract
(author `specs/NNN/preflight.json` from the RUN's real footprint, env/secret
NAMES + real probes — never values; `gates.py preflight` fail-closed). Fail →
fix now (fetch secret, start service, re-auth), re-run until `PREFLIGHT-PASS`.
`--autonomous` later refuses to start without this.

Model ladder comes from the seeded `.planning/config.json`; feature-implement's
walls re-run `model-fallback.sh` before any spawn. Nothing to do here — just
don't hand-pin models in prompts.

### Step 3 — grant ledger (MAX-AUTH auto-grant DEFAULT; --gated to review; skip with --attended)

Invoke the `autonomy-grant` skill for `RUN_ID` — it owns enumeration (typed
`type:target` actions walked from the plan, each with a one-line rollback),
MAX-AUTH mode (default here: record ALL immediately, list + rollbacks go in the
Step 5 report), the `--gated` review screen, and the recording command. In BOTH
modes the safety floor holds: entries are exact typed actions, and an action
not enumerated still stops + records `pending`.

### Step 4 — autonomous implement + finish tail

Invoke the `feature-implement` skill: `NNN --autonomous` (or bare `NNN` when
`--attended`). It enforces `check-preflight`, drives `/gsd-execute-phase` with
gates.py as completion authority, then runs the finish tail (review-gate →
ship → canary), each outward action behind `check-grant`.

**Anti-early-stop (hold every turn of the autonomous loop):** before ending
your turn, check your last paragraph. If it is a plan, an analysis, a question,
a list of next steps, or a promise about work you have not done ("I'll…"), do
that work now with tool calls. End your turn only when the task is complete or
you are blocked on input only the user can provide.

### Step 5 — report + retro

feature-implement's proof artifact + final report are the record. Add this
skill's wrapper line to `.feature-fix-swarm/results.md`:
`TASK-SWARM "<task slug>" spec={NNN} outcome={shipped|stopped:<action>|failed} tiers={frontier:N,judgment:N,execution:N,volume:N,exact:N,inline-mechanical:N}`.
The `tiers=` histogram counts host-native subagent spawns by typed request and resolved model over the
whole run (`inline-mechanical` = trip-wire work the host drained inline —
see `feature-spec` SKILL.md § Orchestrator self-discipline; target 0).
Cross-check with `python3 lib/gates.py delegation-audit <transcript>`.
Report `pending` actions (if any) with the exact resume command:
`python3 lib/gates.py grant $RUN_ID --action <a>` (resolve gates.py per
feature-implement Step 1's 3 install shapes) then `/feature-implement NNN --autonomous`.
Close the loop with GSD extract-learnings (fail-soft). Use Claude
`/gsd-extract-learnings` or Codex `$gsd-extract-learnings`; a headless call goes
through `scripts/gsd/gsd-run.sh`: a fixed pre-launch probe prefers the invoking
host and may select the other host before work begins. A started drive is never
replayed across vendors. Review gates try the opposite family first and may use
one explicitly degraded, read-only active-host fallback.

### Managed ingress (Release B opt-in, spec-014)

With `FFS_MANAGED_INGRESS=1` the legacy `gsd-run.sh` refuses (exit 78) and the
drive enters the managed frontend instead:

```bash
python3 -m run_state.cli describe-upstream-runtime \
  --module-root node_modules/@opengsd/gsd-core/gsd-core/bin/lib --node "$(command -v node)" \
  --output .planning/run-state/upstream-runtime.json          # prints sha256
FFS_UPSTREAM_RUNTIME_MANIFEST=.planning/run-state/upstream-runtime.json \
FFS_UPSTREAM_RUNTIME_SHA256=<sha256> FFS_PHASE_SCOPE=<N> \
FFS_ACCEPTANCE_DRAFT=<draft.json> FFS_REVIEW_MODEL_CATALOG=<models.json> \
FFS_HOST_KIND=codex FFS_CODEX_RUNTIME_HOME=... CODEX_BIN=... GSD_MODEL_REQUEST='{"kind":"tier","name":"execution"}' \
FFS_HOST_TOKEN_RESERVATION=<tokens, e.g. 100K> \
bash scripts/gsd/ffs-frontend.sh task-swarm --select-file <path> ...
```

The descriptor SHA-256 is bound at start and revalidated on every resume
(`UPSTREAM_RUNTIME_DRIFT`); the sealed draft's criterion ids must be the run's
accepted requirement ids (`objective:<sha256(objective)>`). The lifecycle runs
execute -> mapped checks -> one native final review -> DONE; a failed check with
no repair producer hands back and refuses `RECOVERY_PRODUCER_UNAVAILABLE`.
`FFS_ACCEPTANCE_DRAFT` is required (`ACCEPTANCE_DRAFT_REQUIRED` otherwise), and
task-swarm must deliver its work through a supervised GSD wave
(`WAVE_EXECUTION_UNPROVEN` otherwise).

## Rules

- **Zero planned stops (MAX-AUTH default); one with `--gated`.** Any
  unplanned stop means either preflight was skipped or a gate wasn't
  enumerated — both are defects, name them in the report.
- **Never bypass a child skill's gate.** This skill sequences; it holds no
  authority of its own. `SKIP_OPERATOR_GATES=1` is not this skill's business.
- **Stops are cheap, silent failure is not.** An ungranted gate stops that path
  and records `pending`; independent tasks continue. Morning resume is one
  `grant` command.

## Anti-patterns

- Re-implementing planning/decompose/implement logic inline — invoke the skills.
- Stopping on the first plan/task review failure — `plan-decompose` owns bounded
  repair and returns only success or a terminal evidence-backed block.
- Granting `push:*` style blankets — typed exact actions only (ledger rejects
  wildcards by design).
- Running with `--attended` overnight — that's just an unattended stall with
  extra steps; use the grant ledger (default auto-grant, or `--gated`).