steps.md

Flow Plan Steps

IMPORTANT: Steps 1-3 (research, gap analysis, depth) ALWAYS run regardless of input type.

CRITICAL: If you are about to create:

• a markdown TODO list,
• a task list outside .flow/,
• or any plan files outside .flow/,

STOP and instead:

• create/update tasks in .flow/ using flowctl,
• record details in the epic/task spec markdown.

Success criteria

• Plan references existing files/patterns with line refs
• Reuse points are explicit (centralized code called out)
• Acceptance checks are testable
• Tasks are small enough for one /flow-next:work iteration (split if not)
• Open questions are listed

Step 0: Initialize .flow

CRITICAL: flowctl is BUNDLED — NOT installed globally. which flowctl will fail (expected). Always use:

# Get flowctl path
ROOT="$(git rev-parse --show-toplevel)"
OPENCODE_DIR="$ROOT/.opencode"
FLOWCTL="$OPENCODE_DIR/bin/flowctl"

# Ensure .flow exists
$FLOWCTL init --json

Step 1: Fast research (parallel)

If input is a Flow ID (fn-N or fn-N.M): First fetch it with $FLOWCTL show <id> --json and $FLOWCTL cat <id> to get the request context.

Check if memory is enabled:

$FLOWCTL config get memory.enabled --json

Based on user's choice in SKILL.md setup:

If user chose context-scout (RepoPrompt): Run these subagents in parallel using the batch tool with task calls:

• context-scout () - uses RepoPrompt builder for AI-powered file discovery
• practice-scout ()
• docs-scout ()
• memory-scout () — only if memory.enabled is true

If user chose repo-scout (default/faster) OR rp-cli unavailable: Run these subagents in parallel using the batch tool with task calls:

• repo-scout () - uses standard Grep/Glob/Read
• practice-scout ()
• docs-scout ()
• memory-scout () — only if memory.enabled is true

Example batch payload:

{
  "tool_calls": [
    {"tool": "task", "parameters": {"description": "Context scout", "prompt": "<request>", "subagent_type": "context-scout"}},
    {"tool": "task", "parameters": {"description": "Practice scout", "prompt": "<request>", "subagent_type": "practice-scout"}},
    {"tool": "task", "parameters": {"description": "Docs scout", "prompt": "<request>", "subagent_type": "docs-scout"}}
  ]
}

Max 10 tool calls per batch. Split if more. Do not include external/MCP tools in batch.

Must capture:

• File paths + line refs
• Existing centralized code to reuse
• Similar patterns / prior work
• External docs links
• Project conventions (CLAUDE.md, CONTRIBUTING, etc)
• Architecture patterns and data flow (especially with context-scout)

Step 2: Flow gap check

Run the gap analyst subagent with the task tool:

• subagent_type: flow-gap-analyst
• prompt: <request> + research_findings>

Fold gaps + questions into the plan.

Step 3: Pick depth

Default to short unless complexity demands more.

SHORT (bugs, small changes)

• Problem or goal
• Acceptance checks
• Key context

STANDARD (most features)

• Overview + scope
• Approach
• Risks / dependencies
• Acceptance checks
• Test notes
• References

DEEP (large/critical)

• Detailed phases
• Alternatives considered
• Non-functional targets
• Rollout/rollback
• Docs + metrics
• Risks + mitigations

Step 4: Write to .flow

Efficiency note: Use stdin (--file -) with heredocs to avoid temp files. Use task set-spec to set description + acceptance in one call.

Route A - Input was an existing Flow ID:

1. If epic ID (fn-N):

   # Use stdin heredoc (no temp file needed)
   $FLOWCTL epic set-plan <id> --file - --json <<'EOF'
   <plan content here>
   EOF

   • Create/update child tasks as needed

2. If task ID (fn-N.M):

   # Combined set-spec: description + acceptance in one call
   # Write to temp files only if content has single quotes
   $FLOWCTL task set-spec <id> --description /tmp/desc.md --acceptance /tmp/acc.md --json

Route B - Input was text (new idea):

1. Create epic:

   $FLOWCTL epic create --title "<Short title>" --json

   This returns the epic ID (e.g., fn-1).

2. Set epic branch_name (deterministic):

   • Default: fn-N (use epic ID)

   $FLOWCTL epic set-branch <epic-id> --branch "<epic-id>" --json

   • If user specified a branch, use that instead.

3. Write epic spec (use stdin heredoc):

   # Include: Overview, Scope, Approach, Quick commands (REQUIRED), Acceptance, References
   $FLOWCTL epic set-plan <epic-id> --file - --json <<'EOF'
   # Epic Title
   
   ## Overview
   ...
   
   ## Quick commands
   ```bash
   # At least one smoke test command

   Acceptance

   ... EOF

4. Create child tasks:

   # For each task:
   $FLOWCTL task create --epic <epic-id> --title "<Task title>" --json

5. Write task specs (use combined set-spec):

   # For each task - single call sets both sections
   # Write description and acceptance to temp files, then:
   $FLOWCTL task set-spec <task-id> --description /tmp/desc.md --acceptance /tmp/acc.md --json

   This reduces 4 atomic writes per task to 2.

6. Add dependencies:

   # If task B depends on task A:
   $FLOWCTL dep add <task-B-id> <task-A-id> --json

7. Output current state:

   $FLOWCTL show <epic-id> --json
   $FLOWCTL cat <epic-id>

Step 5: Validate

$FLOWCTL validate --epic <epic-id> --json

Fix any errors before proceeding.

Step 6: Review (if chosen at start)

If user chose "Yes" to review in SKILL.md setup question:

1. Invoke /flow-next:plan-review with the epic ID
2. If review returns "Needs Work" or "Major Rethink":
   • Re-anchor EVERY iteration (do not skip):

     $FLOWCTL show <epic-id> --json
     $FLOWCTL cat <epic-id>

   • Immediately fix the issues (do NOT ask for confirmation — user already consented)
   • Re-run /flow-next:plan-review
3. Repeat until review returns "Ship"

No human gates here — the review-fix-review loop is fully automated.

Why re-anchor every iteration? Per Anthropic's long-running agent guidance: context compresses, you forget details. Re-read before each fix pass.

Step 7: Offer next step

Show the epic summary and suggest next actions:

Epic created: fn-N with M tasks.

Next:
1) Start work: `/flow-next:work fn-N`
2) Refine via interview: `/flow-next:interview fn-N`
3) Review the plan: `/flow-next:plan-review fn-N`