flow-product-planning

Files (12)

• SKILL.md
• architecture-patterns.md · references/
• discovery-instructions.md · references/
• discovery-playbook.md · references/
• discovery-prompt-interpretation.md · references/
• discovery-research.md · references/
• discovery-revision.md · references/
• discovery-survey-epic.md · references/
• discovery-ui.md · references/
• epic-discovery-instructions.md · references/
• example-prd.md · references/
• prd-template.md · templates/

SKILL.md (first lines)

# Goal

Distill a user's feature idea into a structured PRD + ordered task breakdown +
PR-description draft, written to `.flow-tmp/plan.md` and
`.flow-tmp/pr-description-draft.md` for downstream consumers (`/flow-new-feature`,
`/flow-pr-review`, `/flow-pipeline`).

# When to Use

- User has a vague or high-level feature idea that needs scoping.
- User wants to plan a multi-step feature before implementation.
- User wants architecture recommendations before writing code.
- User asks "how should I approach this?" about a new capability.
- User describes something complex that spans multiple domain modules or skills.
- User evaluates a proposed change ("what do you think", "am I missing anything").

# When NOT to Use

- User is asking for a direct code change or bug fix (just do it).
- The task is already well-defined and implementation-ready (just do it).
- User is asking for a refactor or optimization (defer to `refactoring`).

# How it works

This skill is a thin wrapper around a one-shot **Independent Discovery
Subagent**. The wrapper itself does no discovery — it spawns one Task-tool
subagent (`subagent_type: $DISCOVERY_SUBAGENT`, resolved to the
plugin-qualified `flow-module-core:flow-discovery` on a plugin-root
install, or a guarded `general-purpose` fallback), passes the user's verbatim
description plus the absolute paths to write, and waits for the subagent to
return a brief summary. The subagent does all the heavy lifting in its own
isolated context: reading the codebase, scanning the skill directory,
examining domain models, drafting the PRD, generating the task breakdown, and
writing both artifacts to disk.

The supervisor session that loads this skill (typically `/flow-pipeline` step
3, 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 labeled-bullet summary the subagent returns.

It never sees the discovery transcript — the file reads, the codebase scans,
the PRD drafting prose. Those stay inside the subagent's context. This is the
single largest context-cost win for `/flow-pipeline` runs and applies to
manual users equally.

The trade-off is intentional: the supervisor cannot refer back to the
discovery exploration in later steps. The contract that absorbs the trade-off
is `.flow-tmp/plan.md` itself — that file is already the only handoff the
supervisor reads downstream, so losing the transcript costs nothing
practical.

## Independent Discovery Subagent

**Task-tool fan-out is intentional.** This step ("Independent Discovery
Subagent") spawns one discovery agent via the Task tool. When `/flow-product-planning`
is loaded in-process by `/flow-pipeline` (the supervisor's step 3), this
fan-out is permitted by the named Task-tool exception 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 artifacts on disk + a brief summary.

**Optional web-grounded research pre-check (config-gated).** When `~/.flow/config.json` has `research.discovery: true` and `agy` is available, the discovery subagent may OPTIONALLY run a relevance-gated, web-grounded research pass before planning — see `references/discovery-instructions.md` "Step 1.5". That research is a **subagent-driven Bash fan-out** (the subagent drives `flow-delegate-fanout` directly via Bash — discovery deliberately does not load `/flow-research` via the `Skill` tool — that skill's default budget and report shape suit an interactive caller, and discovery needs a tightened budget — so it follows that skill's procedure, which it reads), **NOT a Task spawn**. The single discovery Task call below and the nine-exemption invariant in `flow-pipeline/SKILL.md` are therefore unchanged — no new exemption is added.

# Spawn procedure

**Load the Task tool before spawning.** In Claude Code sessions where neither `Task` nor its alias `Agent` is surfaced top-level by the harness (both are aliases of the same one-shot subagent-spawn primitive: identical `subagent_type` / `prompt` / `description` schema), the spawn will silently fall through to in-line execution unless the schema is loaded first. Before the Task call below, run `ToolSearch query="select:Task"` and confirm the response contains either a `<function>{"name": "Task", ...}</function>` or a `<function>{"name": "Agent", ...}</function>` line. If it does not, **do not fall back to in-line execution** — escalate `NEEDS HUMAN: task-tool-unavailable: product-planning-discovery` and exit. The fan-out's value is its context isolation; an in-line fallback breaks the contract that this exemption is justified by.

1. Resolve the working directory absolutely. If the caller passed a `WORKTREE`
   value (typical when invoked from `/flow-pipeline`), use it. Otherwise use
   `pwd`. Then define the output paths **by `MODE`** — feature mode and epic
   mode emit different artifacts, so the spawn template and the post-spawn
   existence check (step 4) follow the same `MODE` branch:
   - Default (no `MODE`, or `MODE: feature`) — two `.flow-tmp/` artifacts:
     - `PLAN_PATH = <workdir>/.flow-tmp/plan.md`
     - `DRAFT_PATH = <workdir>/.flow-tmp/pr-description-draft.md`
   - `MODE: epic` — two epic artifacts under the caller-provided epic-output
     directory (`EPIC_DIR = <workdir>/.flow/epics/<slug>/`, resolved by the
     `MODE: epic` caller — F5's `flow epic create`, out of scope here):
     - `DESIGN_PATH = <EPIC_DIR>/design.md`
     - `MANIFEST_PATH = <EPIC_DIR>/manifest.json`
2. Resolve the skill base directory absolutely. The Skill tool prints the
   "Base directory for this skill" at the top of this SKILL.md when loaded
   — capture it as `SKILL_DIR`. Then derive `INSTRUCTIONS_PATH` by `MODE`:
   - Default (no `MODE`, or `MODE: feature`):
     `INSTRUCTIONS_PATH = <SKILL_DIR>/references/discovery-instructions.md`
   - `MODE: epic` (epic-grain decomposition — one node = one PR-sized
     feature, emitting `design.md` + `manifest.json` under
     `.flow/epics/<slug>/`):
     `INSTRUCTIONS_PATH = <SKILL_DIR>/references/epic-discovery-instructions.md`

   This is a file-path switch through the SAME single discovery spawn site —
   same machinery, same one Task call. It is not a new fan-out site or a new
   Task-tool exemption.

   The subagent reads sibling templates and references via absolute paths
   under `SKILL_DIR` (`templates/prd-template.md`,
   `references/architecture-patterns.md`, `references/discovery-playbook.md`,
   `references/example-prd.md`). Pass `SKILL_DIR` so the subagent never
   has to resolve those relative to its `cd`'d worktree, where they don't
   exist. Also create the consumer-side `.flow-tmp/` directory now so the
   subagent never has to:

   ```bash
   mkdir -p "$WORKTREE/.flow-tmp"
   ```

3. Resolve the subagent type. The `agents/flow-discovery.md` definition
   (no `tools:` allowlist — deliberately inherits every tool; no
   `effort:`/`model:` pins) resolves in two tiers so the pipeline never
   fails on an unknown agent type. Plugin-hosted agents are addressable
   ONLY by the plugin-qualified name `<pluginRootName>:<agentBasename>` —
   a bare `flow-discovery` subagent_type fails Task-tool resolution
   outright (measured: "Agent type 'flow-scout' not found"):

   ```bash

From gavingolden/flow, MIT.

More from gavingolden/flow