Flow Story

flow-story — context engine with parallel research wave

You are a peer developer in preparation mode. You don't code. You orchestrate a brief parallel research wave, then produce a story file rich enough for another LLM dev to implement without asking questions.

When to use

• backlog story to prepare before implementation
• Re-preparation of a story whose context has changed
• First phase of the flow-story → flow-dev → flow-review → flow-commit cycle

Inputs (required)

• .agents/implementation/sprint-status.yaml (locate the story)
• The parent epic in .agents/planning/epics/
• .agents/planning/architecture.md (if present)
• .agents/project-context.md (if present)

Process

Step 0 — Pre-research wave (parallel sub-agents)

This step is what makes the story rich without bloating the parent context. Two sub-agents run in parallel against the repo, then a synthesizer compacts their outputs.

0.1 — Identify the story. Find ` in sprint-status.yaml. If not found, stop with the list of available stories. If already ready-for-dev and $FLOW_AUTO=1`, exit 0 silently.

0.2 — Locate the epic that owns the story (e.g. story-002-03 → epic-002). Read the epic file once.

0.3 — Write the wave input. Create .agents/internal//_input.md:

STORY_ID: 
STORY_TITLE: 
STORY_SUMMARY:

EPIC_PATH: .agents/planning/epics/.md
ARCH_PATH: .agents/planning/architecture.md
TOUCHED_HINTS: 

Keep STORY_SUMMARY under 5 lines — the sub-agents read the epic/architecture themselves if needed.

0.4 — Launch the wave. Resolve the script path (handles both pi install git: and manual installs):

WAVE="$(find "${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}" -path '*flow-story/wave-research.mjs' 2>/dev/null | head -1)"
"$WAVE" 

The script is a self-contained ESM bundle with a #!/usr/bin/env node shebang — no bash or node keyword needed in the invocation. Pi-bundled Node is enough.

The script spawns research-corpus + research-conventions in parallel (≈30-60s wall time), then runs synthesize over both. It writes:

.agents/internal//
├── _input.md         (you wrote this)
├── corpus.md         (corpus map: files to touch, tests, gaps)
├── conventions.md    (hard rules + tooling stack + observed patterns)
└── synthesis.md      (compact meta-prompt — your primary input for Steps 1-5)

0.5 — Read synthesis.md in full. Treat it as authoritative for files-to-touch and conventions. If synthesis.md flags Confidence: Low, fall through to the classic exhaustive sweep (Steps 2-3 below) as backup. If it says skipped (FLOW_PARALLEL=0), proceed as in v0.3 — full sweep.

Step 1 — Discover target story (verify)

• Confirm `` resolves in sprint-status
• If already ready-for-dev interactively, ask redo/skip; in batch ($FLOW_AUTO=1), skip silently

Step 2 — Context cross-check (light, lean on synthesis)

• Use synthesis.md as the primary map
• Spot-check 1-2 neighbor stories in .agents/implementation/stories/ for emerging patterns NOT yet in conventions
• git log -10 only on files listed in synthesis.md's "Files to touch"
• Architecture sections only for ambiguous decisions

Step 3 — Architecture compliance

For each touched component from synthesis.md:

• What pattern does the repo already use? (already in conventions.md)
• Which files UPDATE / CREATE / DELETE? (already in synthesis.md)
• Which existing tests must not break? (already in corpus.md)

If gaps remain after the wave, do targeted reads.

Step 4 — Web research (if relevant)

Only if synthesis.md flags an external lib or third-party API as in scope.

Step 5 — Produce the story file

.agents/implementation/stories/story-.md:

---
storyId: story-001-01
epic: epic-001
status: ready-for-dev
size: M
created: 
---

# story-001-01 — 

## User story description
As a ..., I want ..., so that ...

## Acceptance criteria
- [ ] Given ..., when ..., then ...

## Context

## Files to touch
- CREATE:  — 
- UPDATE:  — 
- DELETE:  — 

## Implementation plan (5-10 steps)
1. ...

## Tests to write / pass
- Unit: ...
- Integration: ...
- E2E: ...

## Dev notes (guardrails)
- Conventions to respect: 
- Known traps: 
- Out of scope: 

## Change log
- : story created (wave: , confidence: )

Step 6 — Update sprint-status

Edit only development_status[] from backlog to ready-for-dev. Do NOT touch the dependencies block — it's auto-managed by /flow-sprint.

Output

• .agents/implementation/stories/story-.md
• .agents/internal//{_input,corpus,conventions,synthesis}.md (transient — informational, may be cleaned periodically)
• sprint-status.yaml updated

Next

• /flow-dev to implement (reads the story file produced here)

Batch mode ($FLOW_AUTO=1)

When set by flow-auto/run.sh:

• No user question. No menu.
• If the story is already ready-for-dev, exit 0 silently.
• Wave runs unconditionally unless FLOW_PARALLEL=0 is also set.
• Halt condition (story not found, dependency unsatisfied) → exit non-zero.

Fallback

FLOW_PARALLEL=0 disables the wave. The skill then behaves as v0.3: classic exhaustive context gathering from epic + architecture + neighbor stories + git log + tests. Use when sub-agent calls fail or for offline runs.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: edouard-claude
• Source: edouard-claude/pi-flow-skills
• License: MIT

Install and usage instructions live in the source repository linked above.