flow-coder

Files (1)

• SKILL.md

SKILL.md (first lines)

# Goal

The `/flow-coder` skill applies a caller-provided edit-set to files inside
an isolated Task-tool subagent context, runs `flow-pre-commit --json`
against the post-edit worktree, and returns a structured artifact at
`<worktree>/.flow-tmp/coder-result.json`. The supervisor never sees the
per-edit `Edit`/`Write` calls or the pre-commit transcript — it only sees
the wrapper's brief return summary and reads the artifact once.

# When to Use

- `/flow-new-feature` step 5 (Implement) on the wider-scope path of its hybrid
  threshold — the caller composes an edit-set from the approved plan's
  per-task Contract blocks when a plan with a Task breakdown heading
  (any level, case-insensitive) was supplied (entries then carry the
  optional `contract` / `acceptance`
  fields), falling back to the `it.todo()` list and the scout's
  `## affected_modules` when no plan applies.
- `/flow-verify` step 3 (Fix Failures) per outer attempt — the caller composes
  an edit-set from the `failure` JSON object emitted by `flow-pre-commit
--json` (one entry per failed check, naming the source file + the issue
  the fix should resolve).
- `/flow-refactoring` step 3 (Apply Transformations) on the wider-scope path of
  its hybrid threshold — the caller composes an edit-set from the Step 2
  refactor plan and the affected modules.
- The `/flow-pipeline` supervisor's interactive code-change redirect path —
  when a user types a non-trivial code-change redirect (e.g. "rename foo to
  bar") at a worktree-existing phase, the supervisor composes a structured
  edit-set `{file, intent, expected_outcome}` from the verbatim redirect and
  invokes `/flow-coder` rather than editing inline (bare triples — a free-form
  redirect has no plan contract to source the optional fields from). See
  `skills/pipeline/flow-pipeline/references/redirect-handling.md` and the
  "Mid-flight code-change redirects" section of
  `skills/pipeline/flow-pipeline/references/phases/mid-flight-redirects.md`.

Every caller composes the required `{file, intent, expected_outcome}`
triple. **Optional** per-entry fields extend it: `contract` — the
task's interface spec (files / signatures / exported symbols / call-site
edits, or the change-type surgical form) copied from an approved plan's
Contract block — `acceptance` — a runnable per-edit check — and
`skill_docs` — absolute skill/reference paths the subagent Reads before
that entry's first edit and records in the artifact's `skills_read`. Today
`/flow-new-feature` step 5's plan-contract path and `/flow-verify`'s UI fix
rounds compose them (both pass the UI rule paths as per-entry
`skill_docs`; the Layout Intent rides `DESIGN_CONTEXT`); `/flow-refactoring`
and the redirect path keep composing bare triples, and the
subagent treats an entry without them exactly as before (see
`flow-coder-instructions/SKILL.md` for how `contract` is honored as a
strong prior via a mechanical pre-check).

# When NOT to Use

- Trivially scoped edits where the caller's own hybrid threshold says
  inline is cheaper. `/flow-coder` itself does not apply a threshold — its
  callers decide whether to invoke it. The four known callers use
  different bars: `/flow-new-feature` step 5 stays inline at ≤1 file AND ≤30
  LOC AND every file named in the prompt; `/flow-verify` step 3 stays inline
  on single-line type/lint errors in one file; `/flow-refactoring` step 3
  uses the same bar as `/flow-new-feature` step 5; and the `/flow-pipeline`
  supervisor's interactive code-change redirect path reuses
  `/flow-new-feature` step 5's `≤1 file AND ≤30 LOC AND every file named`
  bar to keep trivial redirects inline. See each caller's
  "Spawn procedure (wider-scope path only)" section for the canonical
  threshold. The Task-tool round trip costs more than the bytes saved
  on a one-line fix; the threshold exists to preserve the inline path
  for those cases.
- Direct user invocation. `/flow-coder` is invoked by other skills, not by
  humans — the spawn prompt expects a structured edit-set the user is not
  going to compose by hand. A human typing `/flow-coder` by hand is still
  forbidden; but the `/flow-pipeline` supervisor routing a user's free-form
  redirect through `/flow-coder` is NOT direct user invocation — the supervisor
  composes the edit-set, not the human, so it is a skill-initiated
  invocation like the other three callers.
- Multi-turn refinement. Each `/flow-coder` invocation is one-shot — applies the
  requested edits, runs verify, returns the artifact, exits. Iterative
  refinement is the caller's job (compose a new edit-set, re-invoke).
- Discovery / scouting / review work. `/flow-product-planning`'s discovery,
  `/flow-new-feature`'s scout, `/flow-pr-review`'s multi-agent review, and
  `/flow-pr-review`'s fix-applier already own those concerns; `/flow-coder` only
  applies edits that have already been decided.

# How it works

This skill is a thin wrapper around a one-shot **Independent Edit-Applier
Subagent**. The wrapper itself does no file reads and no edits — it spawns
one Task-tool subagent (`subagent_type: $CODER_SUBAGENT`, resolved to the
plugin-qualified `flow-module-core:flow-edit-applier` on a plugin-root
install, or a guarded `general-purpose` fallback), passes the
caller's structured edit-set plus the absolute paths to write, and waits
for the subagent to return a brief both-sides summary. The subagent does
the heavy lifting in its own isolated context: opening each cited file,
making the edits, running `flow-pre-commit --json`, and writing the
structured artifact at `<worktree>/.flow-tmp/coder-result.json`.

The supervisor session that loads this skill (typically `/flow-pipeline`
step 5 or step 6 via `/flow-new-feature`, `/flow-verify`, or `/flow-refactoring`) only
ever sees:

1. The prose of this SKILL.md (the wrapper).
2. The Task-tool call's prompt and brief result envelope.
3. The one-paragraph summary the subagent returns.
4. The caller's single read of `.flow-tmp/coder-result.json` body when it
   needs `verify_status` or per-edit dispositions.

It never sees the per-edit `Edit`/`Write` tool calls, the diff-bearing
tool_results, the `flow-pre-commit` transcript, or the file reads. Those
stay inside the subagent's context. Same context-cost surgery PR #95
applied to `/flow-product-planning`'s discovery and the fix-applier refactor
applied to `/flow-pr-review`'s address loop — `/flow-coder` is the analogous fix for
the implement phase itself.

The trade-off is intentional: the caller cannot refer back to the
edit-application transcript in later steps. The contract that absorbs the
trade-off is `coder-result.json` itself — its typed fields (`status`,
`edits`, `verify_status`, `rejected_alternatives`, `anti_patterns_found`,
`summary`) are what `/flow-new-feature` step 5, `/flow-verify` step 3, and
`/flow-refactoring` step 3 consume.

## Independent Edit-Applier Subagent

From gavingolden/flow, MIT.

More from gavingolden/flow