flow-coder-instructions

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- flow-instructions-sentinel: flow-coder-instructions -->

# Edit-applier instructions

These instructions are read by the edit-applier subagent that `/flow-coder`'s
SKILL.md spawns via the Task tool. The subagent runs in an isolated context
— its file reads, per-edit `Edit`/`Write` tool calls, and `flow-pre-commit`
output stay inside its own session and are never returned to the caller.
The only outputs it produces are the side effects on the worktree (file
edits) and the structured artifact it writes to disk
(`.flow-tmp/coder-result.json`), plus a brief one-paragraph summary it
returns on completion.

The wrapper passes you these inputs in its spawn prompt:

- The verbatim edit-set as a JSON-shaped array of `{file, intent,
expected_outcome}` entries. Each entry names a file (repo-relative
  path), the intent of the edit (1–2 lines naming what the change is
  meant to achieve), and the expected outcome (1–2 lines naming the
  observable post-edit state — what test should pass, what error
  should disappear, what behaviour should change). An entry may also
  carry two **optional** fields sourced from an approved plan's per-task
  Contract block: `contract` — the interface spec (files / signatures /
  exported symbols / call-site edits, or the change-type surgical form)
  — and `acceptance` — a runnable per-edit check. Entries without them
  behave exactly as before.
- An **optional** "Design context" block (the `{{DESIGN_CONTEXT}}`
  placeholder in the wrapper's spawn prompt template) naming the absolute
  paths of a committed `.flow/design/foundation.md` and, when the plan
  froze one, the ephemeral `.flow-tmp/design/spec.json`. The block is
  omitted entirely on non-UI invocations.
- The absolute worktree path (your working directory).
- The absolute skill base directory (`SKILL_DIR`). Resolve every sibling
  reference path under it. Those files do not exist relative to the
  worktree you `cd`'d into — they live in the skill directory, which is
  somewhere else on disk (typically `~/.flow/claude-home/.claude/skills/flow-coder/` or
  `<flow-checkout>/skills/pipeline/flow-coder/`).
- The absolute path to write the artifact (`ARTIFACT_PATH` —
  `.flow-tmp/coder-result.json` under the worktree).

Follow the steps below in order.

## 0. Write the skeleton artifact first

Before applying any edit, write the artifact at `ARTIFACT_PATH` as a
`status: "partial"` skeleton: every key from the schema in step 4 present,
`edits`/`rejected_alternatives`/`anti_patterns_found` as empty arrays, and
placeholder `verify_status`/`summary` strings. This guarantees an
interruption at any point still leaves a consumable artifact. After every
edit-set entry is processed (applied, rejected-alternatives / anti-patterns
recorded), refresh that entry's disposition in the artifact with a short,
targeted `Edit` — never a full rewrite of the file. `status` moves to
`"complete"` only once every entry has been attempted and `verify_status`
is `"pass"`; otherwise it stays `"partial"`. Writing `status: "complete"`
is your final artifact write — record `skills_read`, `skills_read_late`,
`rejected_alternatives` and `anti_patterns_found` before it, and never edit
the artifact after it unless a continuation message from the wrapper asks
you to; then set `status` back to `partial` first, make targeted edits, and
write `complete` last again.

## 1. Load context

Before drafting any edit, load the inputs:

- Parse the edit-set from the wrapper's spawn prompt. Validate that every
  entry has the three required fields (`file`, `intent`,
  `expected_outcome`); the optional fields (`contract`, `acceptance`,
  `skill_docs`) may be present or absent per entry. If any entry is missing a required
  field, record it in `anti_patterns_found` with a
  recommendation for the caller and proceed with the well-formed entries.
- Read the project's `AGENTS.md` (or `CLAUDE.md`) to understand commit
  conventions, comment policy, and any project-specific constraints
  relevant to the edits you're about to make.
- When the spawn prompt carries a "Design context" block
  (`DESIGN_CONTEXT`), it is **REQUIRED context, not advisory**: read the
  named `foundation.md` (and `spec.json` when supplied) BEFORE the first
  UI edit, and **conform every edit to them** — use the foundation's
  semantic token roles (type/surface/elevation/chrome) rather than ad-hoc
  values, and implement toward the spec's expected computed values. When
  an edit cannot conform (a token is missing, the spec conflicts with the
  edit-set's intent), apply the best conforming approximation and record
  the deviation in `anti_patterns_found` (see step 2). Absent the block,
  skip this bullet entirely. When the Design context block carries a
  ratified **Layout Intent**, treat it as a structural constraint —
  regions, nesting, source order, sizing policy, relative positioning,
  breakpoint reflow, overflow/sticky/z-order — and conform every UI edit
  to it; you may never silently drop it. When an edit cannot conform,
  apply the best conforming approximation and record the deviation in
  `anti_patterns_found`, same discipline as the foundation/spec sentence
  above.
- For each edit-set entry, read the named file enough times to understand
  the surrounding context (typically ±20 lines around the area the intent
  describes). These reads stay in your context — they are read-only
  background.

## 2. Apply each edit

You are in **fix-now mode** — you MUST attempt the edits. Specifically:

- Do **not** preemptively decide that a hook, permission rule, or
  read-only filesystem state will block writes. Don't assume one applies;
  attempt the edit and rely on the tool-call result.
- Make a real `Edit` / `Write` tool call for each entry. If — and only if
  — the tool returns an error, record the verbatim error in the artifact's
  `edits[].tool_error` field. Do not fabricate a "the hook denied edits"
  rationale.

For each entry in the edit-set:

1. Open the named file at the location the intent describes.
2. **Skill-docs pre-check (entries with skill_docs).** Before the entry's
   first edit, Read each `skill_docs` path not already in `skills_read`
   with the Read tool, one file per call, in full — never `cat`, `sed`,
   `head`, or `>/dev/null`: piped or ranged output is truncated or
   discarded, and a discarded read is not a read. Add each path to
   `skills_read` with a targeted artifact `Edit` at once, and apply the
   docs while writing. A path that cannot be read goes to
   `anti_patterns_found`, never silently skipped. A doc read only AFTER
   edits it governs already landed is ALSO added to `skills_read_late`

From gavingolden/flow, MIT.

More from gavingolden/flow