sync: flowctl efficiency

.opencode/skill/flow-next-interview/SKILL.md

@@ -26,7 +26,7 @@ Full request: $ARGUMENTS
 
 Accepts:
 - **Flow epic ID** `fn-N`: Fetch with `flowctl show`, write back with `flowctl epic set-plan`
-- **Flow task ID** `fn-N.M`: Fetch with `flowctl show`, write back with `flowctl task set-description/set-acceptance`
+- **Flow task ID** `fn-N.M`: Fetch with `flowctl show`, write back with `flowctl task set-spec` (preferred) or `set-description/set-acceptance`
 - **File path** (e.g., `docs/spec.md`): Read file, interview, rewrite file
 - **Empty**: Prompt for target
 
@@ -98,42 +98,52 @@ After interview complete, write everything back.
 
 ### For Flow Epic ID
 
-1. Create a temp file with the refined epic spec including:
-   - Clear problem statement
-   - Technical approach with specifics
-   - Key decisions made during interview
-   - Edge cases to handle
-   - Quick commands section (required)
-   - Acceptance criteria
-
-2. Update epic spec:
-   ```bash
-   $FLOWCTL epic set-plan <id> --file <temp-md> --json
-   ```
-
-3. Create/update tasks if interview revealed breakdown:
-   ```bash
-   $FLOWCTL task create --epic <id> --title "..." --json
-   $FLOWCTL task set-description <task-id> --file <temp-md> --json
-   $FLOWCTL task set-acceptance <task-id> --file <temp-md> --json
-   ```
+Update epic spec using stdin heredoc (preferred) or temp file:
+```bash
+# Preferred: stdin heredoc (no temp file)
+$FLOWCTL epic set-plan <id> --file - --json <<'EOF'
+# Epic Title
 
-### For Flow Task ID
+## Problem
+Clear problem statement
+
+## Approach
+Technical approach with specifics, key decisions from interview
+
+## Edge Cases
+- Edge case 1
+- Edge case 2
 
-1. Write description to temp file with:
-   - Clear task description
-   - Technical details from interview
-   - Edge cases
+## Quick commands
+```bash
+# smoke test command
+```
 
-2. Write acceptance to temp file with:
-   - Checkboxes for acceptance criteria
-   - Specific, testable conditions
+## Acceptance
+- [ ] Criterion 1
+- [ ] Criterion 2
+EOF
+```
 
-3. Update task:
-   ```bash
-   $FLOWCTL task set-description <id> --file <desc-temp.md> --json
-   $FLOWCTL task set-acceptance <id> --file <acc-temp.md> --json
-   ```
+Create/update tasks if interview revealed breakdown:
+```bash
+$FLOWCTL task create --epic <id> --title "..." --json
+# Use set-spec for combined description + acceptance (fewer writes)
+$FLOWCTL task set-spec <task-id> --description /tmp/desc.md --acceptance /tmp/acc.md --json
+```
+
+### For Flow Task ID
+
+Update task using combined set-spec (preferred) or separate calls:
+```bash
+# Preferred: combined set-spec (2 writes instead of 4)
+$FLOWCTL task set-spec <id> --description /tmp/desc.md --acceptance /tmp/acc.md --json
+
+# Or use stdin for description only:
+$FLOWCTL task set-description <id> --file - --json <<'EOF'
+Clear task description with technical details and edge cases from interview
+EOF
+```
 
 ### For File Path
 

.opencode/skill/flow-next-plan-review/SKILL.md

@@ -138,6 +138,9 @@ Run backend detection from SKILL.md above. Then branch:
 EPIC_ID="${1:-}"
 RECEIPT_PATH="${REVIEW_RECEIPT_PATH:-/tmp/plan-review-receipt.json}"
 
+# Save checkpoint before review (recovery point if context compacts)
+$FLOWCTL checkpoint save --epic "$EPIC_ID" --json
+
 # Gather plan content
 PLAN_SUMMARY="$($FLOWCTL show "$EPIC_ID" --json)"
 PLAN_SPEC="$($FLOWCTL cat "$EPIC_ID")"
@@ -157,6 +160,11 @@ Parse verdict from reviewer response (`<verdict>SHIP|NEEDS_WORK|MAJOR_RETHINK</v
 
 On NEEDS_WORK: fix plan via `$FLOWCTL epic set-plan`, then re-run review (same backend).
 
+If compaction occurs, restore with:
+```bash
+$FLOWCTL checkpoint restore --epic "$EPIC_ID" --json
+```
+
 Write receipt if `REVIEW_RECEIPT_PATH` set:
 ```bash
 mkdir -p "$(dirname "$RECEIPT_PATH")"
@@ -173,6 +181,9 @@ EOF
 $FLOWCTL show <id> --json
 $FLOWCTL cat <id>
 
+# Save checkpoint before review (recovery point if context compacts)
+$FLOWCTL checkpoint save --epic <id> --json
+
 # Step 2: Atomic setup
 eval "$($FLOWCTL rp setup-review --repo-root "$REPO_ROOT" --summary "Review plan for <EPIC_ID>: <summary>")"
 # Outputs W=<window> T=<tab>. If fails → <promise>RETRY</promise>
@@ -193,10 +204,24 @@ $FLOWCTL epic set-plan-review-status <EPIC_ID> --status ship --json
 If verdict is NEEDS_WORK, loop internally until SHIP:
 
 1. **Parse issues** from reviewer feedback
-2. **Fix plan** via `$FLOWCTL epic set-plan <EPIC_ID> --file /tmp/updated-plan.md`
+2. **Fix plan** (stdin preferred, temp file if content has single quotes):
+   ```bash
+   # Preferred: stdin heredoc
+   $FLOWCTL epic set-plan <EPIC_ID> --file - --json <<'EOF'
+   <updated plan content>
+   EOF
+
+   # Or temp file
+   $FLOWCTL epic set-plan <EPIC_ID> --file /tmp/updated-plan.md --json
+   ```
 3. **Re-review**:
    - **OpenCode**: re-run reviewer subagent with updated plan
    - **RP**: `$FLOWCTL rp chat-send --window "$W" --tab "$T" --message-file /tmp/re-review.md` (NO `--new-chat`)
 4. **Repeat** until `<verdict>SHIP</verdict>`
 
+**Recovery**: If context compaction occurred during review, restore from checkpoint:
+```bash
+$FLOWCTL checkpoint restore --epic <EPIC_ID> --json
+```
+
 **CRITICAL**: For RP, re-reviews must stay in the SAME chat so reviewer has context. Only use `--new-chat` on the FIRST review.

.opencode/skill/flow-next-plan-review/workflow.md

@@ -2,7 +2,7 @@
 
 ## Philosophy
 
-The reviewer model only sees provided context. RepoPrompt's Builder discovers context you'd miss (rp backend). OpenCode uses the provided plan content and criteria (opencode backend).
+The reviewer model only sees selected files. RepoPrompt's Builder discovers context you'd miss (rp backend). OpenCode uses the provided plan content and criteria (opencode backend).
 
 ---
 
@@ -47,10 +47,17 @@ echo "Review backend: $BACKEND"
 
 Use when `BACKEND="opencode"`.
 
-### Step 1: Gather plan content
+### Step 0: Save Checkpoint
 
+**Before review** (protects against context compaction):
 ```bash
 EPIC_ID="${1:-}"
+$FLOWCTL checkpoint save --epic "$EPIC_ID" --json
+```
+
+### Step 1: Gather plan content
+
+```bash
 RECEIPT_PATH="${REVIEW_RECEIPT_PATH:-/tmp/plan-review-receipt.json}"
 
 PLAN_SUMMARY="$($FLOWCTL show "$EPIC_ID" --json)"
@@ -100,10 +107,15 @@ EOF
 
 If `VERDICT=NEEDS_WORK`:
 1. Parse issues from output
-2. Fix plan via `$FLOWCTL epic set-plan`
+2. Fix plan via `$FLOWCTL epic set-plan` (stdin preferred)
 3. Re-run Step 3 (same backend, same `session_id`)
 4. Repeat until SHIP
 
+**Recovery**: If context compaction occurred, restore before re-review:
+```bash
+$FLOWCTL checkpoint restore --epic "$EPIC_ID" --json
+```
+
 ---
 
 ## RepoPrompt Backend Workflow
@@ -139,6 +151,12 @@ $FLOWCTL cat <id>
 
 Save output for inclusion in review prompt. Compose a 1-2 sentence summary for the setup-review command.
 
+**Save checkpoint** (protects against context compaction during review):
+```bash
+$FLOWCTL checkpoint save --epic <id> --json
+```
+This creates `.flow/.checkpoint-<id>.json`. If compaction occurs, restore with `$FLOWCTL checkpoint restore --epic <id>`.
+
 ---
 
 ## Phase 2: Augment Selection (RP)
@@ -251,13 +269,24 @@ fi
 If verdict is NEEDS_WORK:
 
 1. **Parse issues** - Extract ALL issues by severity (Critical → Major → Minor)
-2. **Fix the plan** - Address each issue. Write updated plan to temp file.
+2. **Fix the plan** - Address each issue.
 3. **Update plan in flowctl** (MANDATORY before re-review):
    ```bash
+   # Option A: stdin heredoc (preferred, no temp file)
+   $FLOWCTL epic set-plan <EPIC_ID> --file - --json <<'EOF'
+   <updated plan content>
+   EOF
+
+   # Option B: temp file (if content has single quotes)
    $FLOWCTL epic set-plan <EPIC_ID> --file /tmp/updated-plan.md --json
    ```
    **If you skip this step and re-review with same content, reviewer will return NEEDS_WORK again.**
 
+   **Recovery**: If context compaction occurred, restore from checkpoint first:
+   ```bash
+   $FLOWCTL checkpoint restore --epic <EPIC_ID> --json
+   ```
+
 4. **Re-review with fix summary** (only AFTER step 3):
 
    **IMPORTANT**: Do NOT re-add files already in the selection. RepoPrompt auto-refreshes

.opencode/skill/flow-next-plan/steps.md

@@ -45,30 +45,18 @@ $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 (<request>) - uses RepoPrompt builder for AI-powered file discovery
-- practice-scout (<request>)
-- docs-scout (<request>)
-- memory-scout (<request>) — **only if memory.enabled is true**
+Run these subagents in parallel using the Task tool:
+- Task flow-next:context-scout(<request>) - uses RepoPrompt builder for AI-powered file discovery
+- Task flow-next:practice-scout(<request>)
+- Task flow-next:docs-scout(<request>)
+- Task flow-next:memory-scout(<request>) - **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 (<request>) - uses standard Grep/Glob/Read
-- practice-scout (<request>)
-- docs-scout (<request>)
-- memory-scout (<request>) — **only if memory.enabled is true**
-
-Example batch payload:
-```json
-{
-  "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.
+Run these subagents in parallel using the Task tool:
+- Task flow-next:repo-scout(<request>) - uses standard Grep/Glob/Read
+- Task flow-next:practice-scout(<request>)
+- Task flow-next:docs-scout(<request>)
+- Task flow-next:memory-scout(<request>) - **only if memory.enabled is true**
 
 Must capture:
 - File paths + line refs
@@ -113,18 +101,25 @@ Default to short unless complexity demands more.
 
 ## 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):
-   - Write a temp file with the updated plan spec
-   - `$FLOWCTL epic set-plan <id> --file <temp-md> --json`
+   ```bash
+   # 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):
-   - Write temp file for description
-   - `$FLOWCTL task set-description <id> --file <temp-md> --json`
-   - Write temp file for acceptance
-   - `$FLOWCTL task set-acceptance <id> --file <temp-md> --json`
+   ```bash
+   # 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)**:
 
@@ -141,21 +136,38 @@ Default to short unless complexity demands more.
    ```
    - If user specified a branch, use that instead.
 
-3. Write epic spec:
-   - Create a temp file with the full plan/spec content
-   - Include: Overview, Scope, Approach, Quick commands (REQUIRED - at least one smoke test command), Acceptance, References
-   - `$FLOWCTL epic set-plan <epic-id> --file <temp-md> --json`
+3. Write epic spec (use stdin heredoc):
+   ```bash
+   # 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:
    ```bash
    # For each task:
    $FLOWCTL task create --epic <epic-id> --title "<Task title>" --json
    ```
 
-5. Write task specs:
-   - For each task, write description and acceptance to temp files
-   - `$FLOWCTL task set-description <task-id> --file <temp-md> --json`
-   - `$FLOWCTL task set-acceptance <task-id> --file <temp-md> --json`
+5. Write task specs (use combined set-spec):
+   ```bash
+   # 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:
    ```bash