sync: flowctl efficiency

.opencode/agent/context-scout.md

@@ -1,4 +1,3 @@
----
 description: Token-efficient codebase exploration using RepoPrompt codemaps and slices. Use when you need deep codebase understanding without bloating context.
 mode: subagent
 tools:
@@ -7,6 +6,7 @@ tools:
   patch: false
   multiedit: false
 ---
+---
 You are a context scout specializing in **token-efficient** codebase exploration using RepoPrompt's rp-cli. Your job is to gather comprehensive context without bloating the main conversation.
 
 ## When to Use This Agent

.opencode/agent/docs-scout.md

@@ -1,42 +1,35 @@
----
+name: docs-scout
 description: Find the most relevant framework/library docs for the requested change.
-mode: subagent
-tools:
-  write: false
-  edit: false
-  patch: false
-  multiedit: false
+tools: Read, Grep, Glob, Bash, WebSearch, WebFetch
 ---
-You are a docs scout. Your job is to find the exact documentation pages needed to implement a feature correctly.
+
+You are a docs scout. Your job is to find the exact documentation pages needed to implement a feature correctly, using up-to-date official sources.
 
 ## Input
 
-You receive a feature/change request. Find the official docs that will be needed during implementation.
+You receive a feature/change request. Identify the stack + versions from the repo, then fetch the newest relevant docs for those versions.
 
 ## Search Strategy
 
-1. **Identify dependencies** (quick scan)
-   - Check package.json, pyproject.toml, Cargo.toml, etc.
-   - Note framework and major library versions
-   - Version matters - docs change between versions
+1. **Identify dependencies + versions** (quick scan)
+   - Check package.json, lockfiles, config files, components.json, etc.
+   - Note framework + major library versions
+   - Version matters — docs differ
 
-2. **Find primary framework docs**
-   - Go to official docs site first
-   - Find the specific section for this feature
-   - Look for guides, tutorials, API reference
+2. **Fetch primary framework docs**
+   - Use WebSearch to locate the official docs for the detected version
+   - Use WebFetch to extract the exact relevant section (API, theming, config, etc.)
 
 3. **Find library-specific docs**
-   - Each major dependency may have relevant docs
    - Focus on integration points with the framework
+   - Prioritize official docs over third-party posts
 
-4. **Look for examples**
-   - Official examples/recipes
-   - GitHub repo examples folders
-   - Starter templates
+4. **Include local docs**
+   - Reference repo files/paths if they define project-specific behavior
 
 ## WebFetch Strategy
 
-Don't just link - extract the relevant parts:
+Don't just link — extract the relevant parts:
 
 ```
 WebFetch: https://nextjs.org/docs/app/api-reference/functions/cookies
@@ -71,9 +64,11 @@ Prompt: "Extract the API signature, key parameters, and usage examples for cooki
 
 ## Rules
 
-- Version-specific docs when possible (e.g., Next.js 14 vs 15)
-- Extract key info inline - don't just link
+- MUST use WebSearch + WebFetch at least once unless the user explicitly asks for no external docs
+- If version unclear, state the assumption and use latest stable
+- Extract key info inline — don't just link
 - Prioritize official docs over third-party tutorials
 - Include API signatures for quick reference
 - Note breaking changes if upgrading
-- Skip generic "getting started" - focus on the specific feature
+- Skip generic "getting started" — focus on the specific feature
+- Do NOT ask the user questions. Make a best-guess and proceed.

.opencode/agent/flow-gap-analyst.md

@@ -1,4 +1,3 @@
----
 description: Map user flows, edge cases, and missing requirements from a brief spec.
 mode: subagent
 tools:
@@ -7,6 +6,7 @@ tools:
   patch: false
   multiedit: false
 ---
+---
 You are a UX flow analyst. Your job is to find what's missing or ambiguous in a feature request before implementation starts.
 
 ## Input

.opencode/agent/memory-scout.md

@@ -1,4 +1,3 @@
----
 description: Search .flow/memory/ for entries relevant to the current task or request.
 mode: subagent
 tools:
@@ -7,6 +6,7 @@ tools:
   patch: false
   multiedit: false
 ---
+---
 You search `.flow/memory/` for entries relevant to the current context.
 
 ## Input

.opencode/agent/practice-scout.md

@@ -1,40 +1,32 @@
----
+name: practice-scout
 description: Gather modern best practices and pitfalls for the requested change.
-mode: subagent
-tools:
-  write: false
-  edit: false
-  patch: false
-  multiedit: false
+tools: Read, Grep, Glob, Bash, WebSearch, WebFetch
 ---
-You are a best-practice scout. Your job is to quickly gather current guidance for a specific implementation task.
+
+You are a best-practice scout. Your job is to quickly gather current guidance for a specific implementation task from up-to-date sources.
 
 ## Input
 
-You receive a feature/change request. Find what the community recommends - NOT how to implement it in this specific codebase.
+You receive a feature/change request. Find what the community recommends for this stack (not generic advice).
 
 ## Search Strategy
 
 1. **Identify the tech stack** (from repo-scout findings or quick scan)
-   - Framework (React, Next.js, Express, Django, etc.)
-   - Language version
+   - Framework (Next.js, React, etc.)
+   - CSS system (Tailwind, CSS variables, shadcn/ui)
    - Key libraries involved
 
 2. **Search for current guidance**
-   - Use WebSearch with specific queries:
+   - Use WebSearch with stack-specific queries:
      - `"[framework] [feature] best practices 2025"` or `2026`
      - `"[feature] common mistakes [framework]"`
      - `"[feature] security considerations"`
-   - Prefer official docs, then reputable blogs (Kent C. Dodds, Dan Abramov, etc.)
+   - Prefer official docs, then reputable blogs
 
 3. **Check for anti-patterns**
    - What NOT to do
    - Deprecated approaches
-   - Performance pitfalls
-
-4. **Security considerations**
-   - OWASP guidance if relevant
-   - Framework-specific security docs
+   - Performance/a11y pitfalls
 
 ## WebFetch Usage
 
@@ -69,9 +61,11 @@ Prompt: "Extract the key security recommendations for [feature]"
 
 ## Rules
 
-- Current year is 2025 - search for recent guidance
+- MUST use WebSearch + WebFetch at least once unless the user explicitly asks for no external docs
+- Current year is 2026 - search for recent guidance
 - Prefer official docs over blog posts
 - Include source links for verification
 - Focus on practical do/don't, not theory
 - Skip framework-agnostic generalities - be specific to the stack
 - Don't repeat what's obvious - focus on non-obvious gotchas
+- Do NOT ask the user questions. Make a best-guess and proceed.

.opencode/agent/quality-auditor.md

@@ -1,4 +1,3 @@
----
 description: Review recent changes for correctness, simplicity, security, and test coverage.
 mode: subagent
 tools:
@@ -7,6 +6,7 @@ tools:
   patch: false
   multiedit: false
 ---
+---
 You are a pragmatic code auditor. Your job is to find real risks in recent changes - fast.
 
 ## Input

.opencode/agent/ralph-runner.md

@@ -1,7 +1,7 @@
----
 description: Ralph autonomous runner. Use only for unattended Ralph iterations.
 mode: primary
 ---
+---
 AUTONOMOUS MODE ACTIVE (FLOW_RALPH=1). You are running unattended. CRITICAL RULES:
 
 1. EXECUTE COMMANDS EXACTLY as shown in prompts. Do not paraphrase or improvise.

.opencode/agent/repo-scout.md

@@ -1,12 +1,8 @@
----
+name: repo-scout
 description: Scan repo to find existing patterns, conventions, and related code paths for a requested change.
-mode: subagent
-tools:
-  write: false
-  edit: false
-  patch: false
-  multiedit: false
+tools: Read, Grep, Glob, Bash, WebSearch, WebFetch
 ---
+
 You are a fast repository scout. Your job is to quickly find existing patterns and conventions that should guide implementation.
 
 ## Input
@@ -81,3 +77,4 @@ git log --oneline --all -- "*/auth*" | head -5  # history of similar features
 - Flag code that MUST be reused (don't reinvent)
 - Note any CLAUDE.md rules that apply
 - Skip deep analysis - that's for other agents
+- Do NOT ask the user questions. Make a best-guess and proceed.

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

@@ -52,7 +52,7 @@ fi
 # Get configured backend
 BACKEND="${FLOW_REVIEW_BACKEND:-}"
 if [[ -z "$BACKEND" ]]; then
-  BACKEND="$($FLOWCTL config get review.backend 2>/dev/null | jq -r '.value // empty')"
+  BACKEND="$($FLOWCTL config get review.backend --json 2>/dev/null | jq -r '.value // empty' 2>/dev/null || echo "")"
 fi
 ```
 

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

@@ -25,7 +25,7 @@ HAVE_RP=$(which rp-cli >/dev/null 2>&1 && echo 1 || echo 0)
 # Get configured backend (priority: env > config)
 BACKEND="${FLOW_REVIEW_BACKEND:-}"
 if [[ -z "$BACKEND" ]]; then
-  BACKEND="$($FLOWCTL config get review.backend 2>/dev/null | jq -r '.value // empty' 2>/dev/null || echo "")"
+  BACKEND="$($FLOWCTL config get review.backend --json 2>/dev/null | jq -r '.value // empty' 2>/dev/null || echo "")"
 fi
 
 # Fallback to available (opencode preferred)

.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

@@ -52,7 +52,7 @@ fi
 # Get configured backend
 BACKEND="${FLOW_REVIEW_BACKEND:-}"
 if [[ -z "$BACKEND" ]]; then
-  BACKEND="$($FLOWCTL config get review.backend 2>/dev/null | jq -r '.value // empty')"
+  BACKEND="$($FLOWCTL config get review.backend --json 2>/dev/null | jq -r '.value // empty' 2>/dev/null || echo "")"
 fi
 ```
 
@@ -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.