reliquary/plugins/g4b_ai/skills/implementation-orchestration/SKILL.md

---
name: implementation-orchestration
description: Orchestrate non-trivial implementation work across one or more agents — deciding what to do inline, what to delegate, in what order, and how to verify. Use this skill whenever the user asks you to "implement", "build", "ship", "fix this bug", "make this work", or hands you a plan / spec / ticket to execute. Trigger especially for multi-step changes, anything involving compilation or test failures, hard-to-reproduce bugs, or work that spans multiple files or subsystems. Composes with the `workpad` skill (for any plans / journals / reports produced) and runs alongside `superpowers` and similar orchestration helpers.
---

# Implementation Orchestration

This skill is about **how to drive implementation work**, not about how to write code. It covers: when to delegate to subagents vs. work inline, how to sequence agents, how to handle test/compile failures, and how to approach bugs without thrashing.

## Default to sequence, not parallel

Implementation work is almost always **sequential** by nature — later changes depend on earlier ones, even when they look independent on paper. Two agents editing the same file in parallel is a merge conflict; two agents touching adjacent abstractions in parallel is a subtle integration bug.

Run subagents in parallel only when the work is **genuinely** parallelizable:
- Touching disjoint files / modules with no behavioral coupling.
- Independent investigations or read-only exploration.
- Test runs across separate test suites.

If you have to think hard about whether two tasks are independent, they probably aren't. Default to sequencing.

## Delegate compile / test fixes — but verify

A common, useful pattern: when the build is broken or tests are failing after a change, dispatch a subagent to fix it. They're tight, well-scoped tasks with a clear pass/fail signal, and they free up the main thread for higher-level decisions.

But: **always verify the fix yourself before trusting it.** Subagents fixing tests have a strong incentive to make the test pass, and the easiest way to make a test pass is sometimes the wrong way (deleting the assertion, weakening the expected value, mocking out the thing being tested, catching-and-ignoring the failing path). When the agent reports green:

1. Read the diff they produced — not just the report.
2. Confirm the fix matches the intent of the original test, not just its letter.
3. Re-run the relevant tests yourself if there's any doubt.

If you can't tell from the diff whether the fix is real, push back. "Tests pass" from a subagent is a hypothesis, not a conclusion.

## Bugs: prove before fixing, explore before focusing

Two patterns that prevent the worst kinds of bug-fix thrash.

**Hard bugs should be proven by a test first.** Before changing production code to fix a bug, write the test that reproduces the bug and watch it fail. This does three things at once: it confirms you actually understand the bug, it gives you an unambiguous signal when the fix works, and it leaves a regression guard behind. If you cannot write a failing test, you do not yet understand the bug well enough to fix it — keep investigating.

For trivial / obvious bugs (typo, off-by-one in an unambiguous spot, missing null check), skip this. The test-first rule is for anything you'd describe as "I think the issue is…" rather than "the issue is…".

**Bugfixing starts with exploration, not focus.** When handed a bug, the temptation is to dive into the suspected file and start poking. Resist for a few minutes:

- Look at the surrounding code paths, not just the suspected one. Bugs often live one or two layers up from where the symptom manifests.
- Skim recent commits to that area — was something changed recently that might explain it?
- Check whether the same pattern appears elsewhere — if it does, the fix may need to be applied in multiple places, or the abstraction itself is the problem.
- Reproduce the bug yourself end-to-end before changing anything.

A short exploration phase pays for itself many times over against fixing-then-discovering-it-was-the-wrong-place.

## Sequencing implementation agents

When a task needs multiple implementation agents, plan the sequence before launching:

1. **One agent owns each coherent change.** Don't split a single logical change across two agents — they'll fight over the boundary.
2. **Each agent receives the changes from the previous one as committed code, not as a description.** Either commit between agents or hand the diff over explicitly.
3. **Run tests between agents, not just at the end.** Catching a regression at agent N+1 is much cheaper than catching it at agent N+5.
4. **The orchestrator (you) is responsible for keeping the high-level plan coherent.** Subagents see only their slice.

For changes small enough that a single agent could do the whole thing, just do it inline. The orchestration overhead is only worth paying when the work genuinely doesn't fit.

## When to write things down

Use the `workpad` skill for placement. The implementation-specific cases:

- **Plan first** for anything more than a few files or a few hours of work. Write it to `plans/` and confirm with the user before touching code. A wrong plan caught at planning time costs minutes; caught at code-review time costs days.
- **Journal a hard bug** — long bug hunts with multiple dead ends should be captured in `journals/` as you go (append-only). The journey is the value; the final fix alone won't tell future-you why obvious-looking alternatives didn't work.
- **Spec frozen contracts.** If implementation reveals an invariant that other code will need to rely on (an event shape, an error code, a state-machine transition), promote it to `specs/` so it doesn't quietly drift.

## Composition with other skills

- **`workpad`** governs where any markdown artifacts go. Defer to it.
- **`research-tree`** is the right tool when the question "how should I implement this" is itself unsettled and decomposes into multiple investigations. Run that first; come back to this skill once you have a plan to execute.
- **`superpowers`** and project-specific skills (e.g. ticket workflows, review skills) layer on top of this — they handle domain specifics; this skill handles the orchestration shape.

## What this skill does *not* govern

- Code style, language conventions, or framework choices — that's the project's call.
- Specific test frameworks, CI configuration, or branch strategy.
- The internal structure of a plan / journal / spec — see `workpad`.