Skip to content

Commit 21c0a59

Browse files
committed
docs(flow-next): wire strategy + prospect into Quick Start, route map, and Workflow phases
- Quick Start step 3 shows strategy + prospect as optional upstream steps - TOC: fix broken #the-workflow-ladder anchor → #the-workflow; lifecycle blurb leads with "Strategy" - When to Use What: new "strategic anchor" row in summary table; (Strategy) prefix on prospect-driven routes; new Strategy section in skill comparison list; capture source-tag list updated to mention [strategy:<track>]; interview + plan blurbs note strategy grounding - The Workflow: new Strategy Phase + Prospecting Phase + Maintenance Phase sections; Planning Phase research bullet notes 0.40.0 STRATEGY.md grounding + ## Strategy Alignment output
1 parent eb7d998 commit 21c0a59

1 file changed

Lines changed: 48 additions & 10 deletions

File tree

plugins/flow-next/README.md

Lines changed: 48 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@
3030
## Table of Contents
3131

3232
- [What Is This?](#what-is-this)
33-
- [The Workflow](#the-workflow-ladder)Idea → spec → tasks → ship → maintain
33+
- [The Workflow](#the-workflow)Strategy → idea → spec → tasks → ship → maintain
3434
- [Why It Works](#why-it-works)
3535
- [Quick Start](#quick-start) — Install, setup, use
3636
- [When to Use What](#when-to-use-what) — Prospect / Capture / Interview / Plan
@@ -204,8 +204,11 @@ flowctl ready --epic fn-1 # What's ready to work on
204204
### 3. Use
205205

206206
```bash
207-
# Spec: "create a spec for X" — writes epic with structured requirements
208-
# Then plan or interview to refine
207+
# (Optional) Strategy: anchor problem/approach/tracks for downstream grounding
208+
/flow-next:strategy
209+
210+
# (Optional) Prospect: rank candidate ideas grounded in repo + strategy
211+
/flow-next:prospect
209212

210213
# Plan: research, create epic with tasks
211214
/flow-next:plan Add a contact form with validation
@@ -219,6 +222,8 @@ flowctl ready --epic fn-1 # What's ready to work on
219222

220223
That's it. Flow-Next handles research, task ordering, reviews, and audit trails.
221224

225+
**Already know what you want to build?** Skip strategy and prospect — go straight to plan or work. Strategy and prospect are upstream grounding tools, not gates. See [When to Use What](#when-to-use-what) for the full route map.
226+
222227
### When to Use What
223228

224229
Flow-next is flexible. There's no single "correct" order — the right sequence depends on how well-defined your spec already is.
@@ -287,8 +292,9 @@ Best for: bug fixes, small features, well-scoped changes that don't need task sp
287292

288293
| Starting point | Recommended sequence |
289294
|----------------|---------------------|
290-
| No target yet, want ranked candidates | Prospect → (promote) → Plan → Work ([details](#prospecting)) |
291-
| Prospect survivor needs richer spec | Prospect → Capture → Interview/Plan → Work |
295+
| Want a strategic anchor for the whole repo | Strategy → (everything below grounds against it) ([details](#project-strategy)) |
296+
| No target yet, want ranked candidates | (Strategy) → Prospect → (promote) → Plan → Work ([details](#prospecting)) |
297+
| Prospect survivor needs richer spec | (Strategy) → Prospect → Capture → Interview/Plan → Work |
292298
| Conversation already in flight | Capture → Interview/Plan → Work |
293299
| Free-form discussion, lock it down | Capture → Plan → Work |
294300
| New feature, want solid spec first | Spec → Interview/Plan → Work |
@@ -297,12 +303,15 @@ Best for: bug fixes, small features, well-scoped changes that don't need task sp
297303
| Well-understood, needs task splitting | Plan → Work |
298304
| Small single-task, spec complete | Work directly (creates 1 epic + 1 task) |
299305

300-
**Prospect vs Capture vs Spec vs Interview vs Plan:**
306+
Strategy is **upstream of every route** — set it once, every downstream skill (prospect / plan / interview / capture / sync) reads `STRATEGY.md` as advisory grounding. Skip it if you don't want a strategic anchor; everything still works the same way as before 0.40.0. See [Project Strategy](#project-strategy) for details.
307+
308+
**Strategy vs Prospect vs Capture vs Spec vs Interview vs Plan:**
309+
- **Strategy** (`/flow-next:strategy`) writes/maintains a repo-root `STRATEGY.md` (target problem, approach, personas, key metrics, tracks). Run once early, revisit per-section as direction shifts. Downstream skills read it as advisory grounding (never auto-supersedes). Optional — skip if your repo has no strategic intent worth recording.
301310
- **Prospect** (`/flow-next:prospect [hint]`) generates many candidate ideas, critiques each one, and writes a ranked artifact under `.flow/prospects/`. Use when you don't have a target yet. Promote a survivor to an epic via `flowctl prospect promote` (direct path to plan), or hand the survivor to `/flow-next:capture` for a richer conversation-driven spec.
302-
- **Capture** (`/flow-next:capture`) synthesizes conversation context into an epic spec — the automated alternative to manual `flowctl epic create + epic set-plan`. Use after prospect-promotion or after a free-form design discussion. Source-tags every acceptance criterion (`[user]` / `[paraphrase]` / `[inferred]`); mandatory read-back loop; never silently invents requirements. Output goes to `.flow/specs/<epic-id>.md`.
311+
- **Capture** (`/flow-next:capture`) synthesizes conversation context into an epic spec — the automated alternative to manual `flowctl epic create + epic set-plan`. Use after prospect-promotion or after a free-form design discussion. Source-tags every acceptance criterion (`[user]` / `[paraphrase]` / `[inferred]` / `[strategy:<track>]`); mandatory read-back loop; never silently invents requirements. Output goes to `.flow/specs/<epic-id>.md`.
303312
- **Spec** (just ask "create a spec") creates an epic with structured requirements (goal, architecture, API contracts, edge cases, acceptance criteria, boundaries). Same destination as capture, but the manual heredoc path — useful for scripted callers.
304-
- **Interview** refines an epic via deep Q&A (40+ questions). Writes back to the epic spec only — no tasks.
305-
- **Plan** researches best practices, analyzes existing patterns, and creates sized tasks with dependencies.
313+
- **Interview** refines an epic via deep Q&A (40+ questions). Doc-aware mode reads glossary + decisions + strategy and surfaces conflicts. Writes back to the epic spec only — no tasks.
314+
- **Plan** researches best practices, analyzes existing patterns, and creates sized tasks with dependencies. Reads strategy if present and emits a `## Strategy Alignment` section listing which active tracks the plan serves.
306315

307316
You can always run interview again after planning to catch anything missed. Interview writes back to the epic spec only — it won't modify existing tasks.
308317

@@ -2125,9 +2134,32 @@ Flow-Next uses the same defaults in manual and Ralph runs. Ralph bypasses prompt
21252134

21262135
Override via flags or `scripts/ralph/config.env`.
21272136

2137+
### Strategy Phase (optional, upstream of everything)
2138+
2139+
Run once early or whenever direction shifts. Sets a repo-wide strategic anchor that downstream skills read as advisory grounding.
2140+
2141+
1. **Run** `/flow-next:strategy` — interview-driven Q&A populates 5 required sections (Target problem / Our approach / Who it's for / Key metrics / Tracks) + 2 optional (Milestones / Not working on). 2-round pushback per section against fluff / vanity / feature-list answers
2142+
2. **Re-run anytime** with section name (e.g., `/flow-next:strategy metrics`) to revisit one block — preserves the rest byte-identical, bumps `last_updated`
2143+
3. **Downstream consumers** auto-detect and ground against `STRATEGY.md`:
2144+
- Prospect — Phase 0 grounding scan emits approach + tracks verbatim into the candidate-generation prompt; adds `out-of-scope-vs-strategy` to the rejection taxonomy
2145+
- Plan — research scan reads strategy; epic spec gets a `## Strategy Alignment` section listing tracks served + read-only `## Strategy drift flagged for review` block on conflict
2146+
- Interview — doc-aware mode adds a `## Strategy Conflicts` section parallel to `## Glossary Conflicts`; throttled to ≤1 strategy question per turn
2147+
- Capture — Phase 0 reads strategy; tags strategy-derived acceptance criteria as `[strategy:<track-name>]`; refuses to write contradicting specs without `--override-strategy` (which prompts for a decision-record write)
2148+
- Plan-sync — surfaces strategy drift read-only; renames update inline with breadcrumb; never auto-supersedes
2149+
2150+
Skip this phase entirely if your repo has no strategic intent worth recording. All downstream skills run identically when `STRATEGY.md` is absent or empty (husk).
2151+
2152+
### Prospecting Phase (optional, when no target yet)
2153+
2154+
Run when you don't know what to build next. Generates ranked candidates grounded in repo + strategy + memory + open epics.
2155+
2156+
1. **Run** `/flow-next:prospect [focus hint]` — generates 15-25 candidates, critiques each, writes ranked artifact to `.flow/prospects/<slug>-<date>.md`
2157+
2. **Promote** a survivor: `flowctl prospect promote <id> --idea N` allocates an epic with prospect-context spec inlined
2158+
3. **Continue** with Capture / Interview / Plan as appropriate (see [When to Use What](#when-to-use-what))
2159+
21282160
### Planning Phase
21292161

2130-
1. **Research (parallel subagents)**: `repo-scout` (or `context-scout` if rp-cli) + `practice-scout` + `docs-scout` + `github-scout` + `epic-scout` + `docs-gap-scout` (v0.39.0+: also reads `GLOSSARY.md` on the ancestor chain + `knowledge/decisions/` to surface canonical terminology + prior load-bearing choices in the planning context)
2162+
1. **Research (parallel subagents)**: `repo-scout` (or `context-scout` if rp-cli) + `practice-scout` + `docs-scout` + `github-scout` + `epic-scout` + `docs-gap-scout` (v0.39.0+: also reads `GLOSSARY.md` on the ancestor chain + `knowledge/decisions/` to surface canonical terminology + prior load-bearing choices in the planning context; v0.40.0+: also reads `STRATEGY.md` when present and writes `## Strategy Alignment` listing tracks served)
21312163
2. **Gap analysis**: `flow-gap-analyst` finds edge cases + missing requirements
21322164
3. **Epic creation**: Writes spec to `.flow/specs/fn-N.md`, sets epic dependencies from `epic-scout` findings
21332165
4. **Task breakdown**: Creates tasks + explicit dependencies in `.flow/tasks/`, adds doc update acceptance criteria from `docs-gap-scout`
@@ -2143,6 +2175,12 @@ Override via flags or `scripts/ralph/config.env`.
21432175
5. **Review** (optional): `/flow-next:impl-review` via RepoPrompt, Codex, or Copilot
21442176
6. **Loop**: Next ready task → repeat until no ready tasks. Close epic manually (`flowctl epic close fn-N`) or let Ralph close at loop end.
21452177

2178+
### Maintenance Phase (optional, ongoing)
2179+
2180+
- `/flow-next:audit [mode:autofix] [scope hint]` — review `.flow/memory/` entries against current code, decide Keep / Update / Consolidate / Replace / Delete per entry
2181+
- `/flow-next:memory-migrate` — one-time migration from legacy flat memory files (pre-0.33.0)
2182+
- `/flow-next:resolve-pr [PR# | comment URL]` — fetch unresolved PR review threads, dispatch resolver agents, validate, commit, reply, resolve via GraphQL
2183+
21462184
---
21472185

21482186
## Ralph Mode (Autonomous, Opt-In)

0 commit comments

Comments
 (0)