flow-new-feature

Files (3)

• SKILL.md
• delegated-scout.md · references/
• pr-description-authoring.md · references/

SKILL.md (first lines)

# Goal

Guide the implementation of new user-facing features through critical analysis, upfront
acceptance criteria as `it.todo()` test specs, and mandatory test implementation.

# When to Use

- Implementing a new user-facing feature from scratch
- User asks for a structured feature implementation process
- User says "new feature", "implement feature", "build this feature"

# When NOT to Use

- For small bug fixes or single-line changes
- For refactoring without behavior change — use `/flow-refactoring`
- For adding tests to existing code — use the `flow-testing` skill directly

# How it works

This skill is a thin wrapper around a one-shot **Independent Scout
Subagent**. The wrapper itself does no codebase scouting — it spawns one
Task-tool subagent (`subagent_type: $SCOUT_SUBAGENT`, resolved to the
plugin-qualified `flow-module-core:flow-scout` on a plugin-root install,
or a guarded `general-purpose` fallback), passes the user's
verbatim description plus the absolute path to write, and waits for the
subagent to return a brief both-sides summary. The subagent does the
discovery in its own isolated context: reading source files, scanning
adjacent modules, identifying tests, surfacing public API surface, and
flagging anti-patterns / off-limits surfaces. It writes a structured
artifact to `$WORKTREE/.flow-tmp/scout.md` and returns a short summary.

The supervisor session that loads this skill (typically `/flow-pipeline`
step 5, but also any direct caller) 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. One Read of `.flow-tmp/scout.md` early in Critical Analysis (Step 2).

It never sees the scouting transcript — the source-file reads, the
adjacent-module scans, the API-surface enumeration. Those stay inside the
subagent's context. Same context-cost surgery PR #95 applied to
`/flow-product-planning`'s discovery; this is the analogous fix for
`/flow-new-feature`.

The trade-off is intentional: the supervisor cannot refer back to the
scouting exploration in later steps. The contract that absorbs the
trade-off is `.flow-tmp/scout.md` itself — the supervisor reads it once
during Critical Analysis and never re-reads.

## Independent Scout Subagent

**Task-tool fan-out is intentional.** This step ("Independent Scout
Subagent") spawns one scout agent via the Task tool. When `/flow-new-feature`
is loaded in-process by `/flow-pipeline` (the supervisor's step 5), this
fan-out is permitted by the named Task-tool exception #3 in
`skills/pipeline/flow-pipeline/SKILL.md`'s "Hard rules" section (itself
anchored on this step's heading name, not its number, so it survives
future renumbering). Outside the supervisor context (e.g. invoked
directly from a user session), the Task tool is unrestricted, so the
spawn runs identically. Either path: one subagent, returns artifact on
disk + a brief summary.

# Context

- Test files live adjacent to the component or module being built
- `it.todo()` naming format: `"should <expected observable behavior> when <trigger/condition>"`
- Skill consultation: before writing `.svelte` files, read the `svelte` skill. Before writing
  tests, read the `flow-testing` skill. Before UI/layout work, read the `tailwind-shadcn` skill.
  Before database/migrations, read the `supabase-project` skill. (Names assume the canonical stack
  skills installed by `flow install`; substitute whatever your project uses.)

# Instructions

## 1. Understand the User Flow

**Standalone-mode interview pointer.** When this skill is invoked
standalone in a live chat session — a human ran `/flow-new-feature`
directly, not `/flow-pipeline` driving it — it MAY run the intent
interview (adaptive) referenced by path at
`skills/pipeline/flow-pipeline/references/interview-playbook.md` before
scaffolding, since a live chat has a user to interview. A
`/flow-pipeline`-driven invocation never asks here — the interview
already ran (or was deliberately skipped) at the supervisor's own step
1/step 3, and this skill's job at that point is to implement the
already-approved plan, not re-open it.

- If `$ARGUMENTS` is provided, use it as the initial feature description. Ask clarifying
  questions to fill gaps rather than asking the user to describe the feature from scratch.
- If `$ARGUMENTS` is empty, ask the user to describe the feature from their perspective:
  what they click, what they see, what changes.
- Identify the entry point (page, button, trigger) and the expected end state.
- Clarify edge cases: empty states, error states, loading states, boundary conditions.
- Define **scope boundaries** — explicitly state what is out of scope to prevent scope creep.

## 1b. Scout the Codebase

**Resolve `PLAN_PATH` first**, before the hybrid threshold below — this
runs on every entry to Step 1b, not only the wider-scope spawn path, so a
supplied plan is never silently dropped when a feature is judged
description-trivial (Step 5's `/flow-coder` threshold is independent and can
still take the wider path at implement time). Resolve the working
directory absolutely: if the caller passed a `WORKTREE` value (typical
when invoked from `/flow-pipeline`), use it; otherwise use `pwd`. Define:

- `PLAN_PATH` — the absolute plan path when the invocation carried a
  `PLAN: <path>` line AND that file exists AND contains a heading (any
  level, case-insensitive) matching `Task breakdown`; the literal string
  `absent` otherwise. A supplied plan does not change the hybrid
  threshold below — it neither forces nor skips the scout spawn; on the
  skip-scout path it still feeds Step 2's contract read and Step 5's
  edit-set composition. On the spawn path it additionally switches the
  spawned scout into verify-not-rederive mode (see
  the preloaded `flow-scout-instructions` skill).

Decide whether to spawn the scout subagent based on the **hybrid threshold**:

- **Trivially scoped features** (≤3 affected files, judged from the
  verbatim user description) skip the scout entirely. Phrasing

From gavingolden/flow, MIT.

More from gavingolden/flow