FSD

Coordinate coding agents from implementation through review and integration.

Illustration of the review loop: one builder, then a fresh hardened reviewer, each in its own Herdr tab. Drawn from the role files, not screen-recorded; for a real trace see the worked example.

FSD is an agent skill for organizing coding work across specialized builders, reviewers and scouts. A coordinator — the coding agent you are already talking to — assigns focused tasks, checks the results itself, and integrates the changes. Small tasks stay with one agent; larger ones use parallel workers and independent review, each in its own visible terminal that you can watch and steer.

FSD runs through tools you already have. Herdr, a terminal multiplexer for coding agents, runs each worker in its own tab; Git worktrees keep concurrent implementation apart; plain files carry assignments and reports. FSD adds no runtime or service of its own: FSD 1.9.0 is instructions, references, role files and record templates that any skill-capable coding agent (the harness — Claude Code, Pi, Codex) can follow.

What it looks like

Use FSD: fix the parser regression, run the tests, and stop. No public API changes.

The coordinator does small work itself. Before delegation, it presents the proposed roster and waits for your explicit confirmation, including for replacements or fallbacks. It then opens one [FSD]-labeled Herdr tab per fresh worker: a builder in an isolated worktree, fresh reviewers with distinct angles, a scout when the code is unfamiliar. Each worker gets a role file and a short packet, publishes an immutable report, and the coordinator is woken when it finishes rather than polling for it. Results are verified by the coordinator, not taken on trust.

Codex coordinators use active-turn waits by default through existing terminal tools. Codex keeps the turn open, collects bounded Herdr waits, and verifies the reports. See Codex as coordinator; this mode needs no extra service and makes no claim to wake an idle session.

For a complete trace of a real goal, including two coordinator mistakes and how they were corrected, see the worked example.

Quick start

Install once per harness. Installing grants no authority and launches nothing.

FSD is available on skills.sh. Install with the skills CLI:

npx skills add ptshih/fsd --skill fsd

Alternatively, use your harness's native package manager:

# Pi — the first line only where Pi will coordinate; workers do not need it
pi install npm:pi-interactive-shell
pi install git:github.com/ptshih/fsd

# Claude Code
claude plugin marketplace add ptshih/fsd
claude plugin install fsd@fsd

Then ask in plain language: Use FSD: <outcome>, <constraints>, and stop. Supervised is the default. Request unsupervised work explicitly; that changes how in-scope decisions are handled, not permissions or available host capabilities. Steer, pause or cancel through the conversation.

Prerequisites: Herdr with its harness integrations installed, at least one supported harness, and Git where your project requires it. Delegation across idle coordinator turns also needs a way to wake it: the harness's background-task notifications (native in Claude Code; on Pi, from the pi-interactive-shell extension, which also watches files) or a native file watcher for the report inboxes. Owner preferences (model routing per role, approval policy, standing limits) live at $XDG_CONFIG_HOME/fsd/preferences.json.

The same Use FSD: <outcome>, <constraints>, and stop. request selects active-turn waits when the coordinator is Codex; no extra mode selection is needed. An explicit request for idle wakeup still requires a verified native facility.

Workflow options

Five shipped roles — scout, builder, workhorse, reviewer, judge — each a markdown file that fixes a worker's scope, harness launch arguments and report shape; your preferences supply the model. Common shapes are in compositions: parallel review, review loop, scout → build → review, judge, mechanical batch. None is mandatory; the coordinator picks the smallest shape that earns its cost, or does the work directly.

How it works

Native-wakeup mode: Herdr tabs → filesystem reports → existing native wakeup → coordinator verification. Codex follows the same handoffs and verification, collecting terminal-tool waits in its active turn.

• One coordinator. One implementation writer per working directory; concurrent writers get separate worktrees. Readers can share a checkout.
• Every goal pins its own copy of the skill in runbook/, so updating FSD never changes a running goal. Goal records live at $XDG_STATE_HOME/fsd/goals/<project-slug>/<goal-id>/, outside every repository.
• The wake is Herdr's settled-state agent wait, run through the harness's own background facility; an inbox file watch is the fallback. Files preserve state; they do not wake an idle agent by themselves.
• Only an assignment's first submission types into a worker's pane. Later messages go through the worker harness's own inbox where the coordinator can reach it, and an inbox never types into the pane.
• Receipt, verification, integration and the final outcome are kept distinct. The coordinator ends with delivered, blocked, limit reached or cancelled, with evidence.

The skill gives the full workflow.

Limitations

FSD is cooperative: it provides no hard spending limits, guaranteed interruption, exactly-once effects, automatic deadline enforcement or crash-proof continuation, and it claims only what it verified. Hardened (read-only) workers rely on the harness's own permission modes. Cross-machine coordination is not supported.

References

• Setup and preferences: first use, role files, upgrades.
• Worker guide: focused execution, escalation and reporting.
• Compositions: named shapes built from the roles.
• Worked example: one hardened reviewer end to end.
• Filesystem protocol: goal directory, ownership, messages, recovery.
• Filesystem examples: tested one-shot commands.
• Native wakeup: settled-state waits and inbox watches.
• Codex coordinator: default bounded waits in the active turn.
• Pi coordinator: the required background-dispatch extension and its per-call parameters.
• Herdr operations: launch, dispatch, inspection, cleanup.
• Messaging running workers: follow-ups through each harness's own inbox, the pane fallback, and the Claude Code–Codex routes.

Development

From a source checkout with Node 22 or later, run npm test and npm run check. No dependency installation is needed. These validate packaging, documentation, role files, templates and exact filesystem examples in disposable local fixtures — not agent compliance or end-to-end delivery. Update the installed skill between goals (pi update git:github.com/ptshih/fsd or claude plugin update fsd@fsd), or rely on the per-goal runbook pin; pin a release through the package manager when reproducibility matters. Update a coordinating Pi's extension the same way (pi update npm:pi-interactive-shell), between goals, and expect its contract to have moved.

MIT © 2026 ptshih.