fix(flowctl): improve review-backend defaults and skill docs clarity (v0.1.34)

- Default review backend to "rp" instead of "ASK" for zero-config experience
- Enable crossEpic planSync and github scouts in default config
- Simplify review-backend config resolution (no deep_merge, direct fallback)
- Clarify flowctl CLI arg patterns in SKILL.md (positional vs flag usage)
- Add ASK/none handling guidance in preamble

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: z23cc

bin/flowctl

@@ -1,6 +1,6 @@
 [package]
 name = "flowctl-cli"
-version = "0.1.33"
+version = "0.1.34"
 description = "CLI entry point for flowctl"
 edition.workspace = true
 rust-version.workspace = true

flowctl/crates/flowctl-cli/Cargo.toml

@@ -16,9 +16,9 @@ fn get_default_config() -> serde_json::Value {
     json!({
         "memory": {"enabled": true},
         "outputs": {"enabled": true},
-        "planSync": {"enabled": true, "crossEpic": false},
-        "review": {"backend": null},
-        "scouts": {"github": false},
+        "planSync": {"enabled": true, "crossEpic": true},
+        "review": {"backend": "rp"},
+        "scouts": {"github": true},
         "stack": {},
     })
 }

flowctl/crates/flowctl-cli/src/commands/admin/mod.rs

@@ -9,18 +9,23 @@ use crate::output::{error_exit, json_output};
 
 use flowctl_core::types::{CONFIG_FILE, REVIEWS_DIR};
 
-use super::{deep_merge, get_default_config, get_flow_dir};
+use super::{get_default_config, get_flow_dir};
 
 // ── Review-backend command ─────────────────────────────────────────
 
 pub fn cmd_review_backend(json_mode: bool, compare: Option<String>, epic: Option<String>) {
-    // Priority: FLOW_REVIEW_BACKEND env > config > ASK
+    // Priority: FLOW_REVIEW_BACKEND env > config (non-null) > default config
+    let default_backend = get_default_config()
+        .pointer("/review/backend")
+        .and_then(|v| v.as_str().map(String::from))
+        .unwrap_or_else(|| "rp".to_string());
+
     let (backend, source) = if let Ok(env_val) = std::env::var("FLOW_REVIEW_BACKEND") {
         let trimmed = env_val.trim().to_string();
         if ["rp", "codex", "none"].contains(&trimmed.as_str()) {
             (trimmed, "env".to_string())
         } else {
-            ("ASK".to_string(), "none".to_string())
+            (default_backend.clone(), "default".to_string())
         }
     } else {
         let flow_dir = get_flow_dir();
@@ -29,27 +34,27 @@ pub fn cmd_review_backend(json_mode: bool, compare: Option<String>, epic: Option
             let config = if config_path.exists() {
                 match fs::read_to_string(&config_path) {
                     Ok(content) => {
-                        let raw = serde_json::from_str::<serde_json::Value>(&content)
-                            .unwrap_or(json!({}));
-                        deep_merge(&get_default_config(), &raw)
+                        serde_json::from_str::<serde_json::Value>(&content)
+                            .unwrap_or(json!({}))
                     }
-                    Err(_) => get_default_config(),
+                    Err(_) => json!({}),
                 }
             } else {
-                get_default_config()
+                json!({})
             };
 
+            // Read from user config; if null or missing, fall back to default
             let cfg_val = config
                 .pointer("/review/backend")
                 .and_then(|v| v.as_str())
                 .unwrap_or("");
             if ["rp", "codex", "none"].contains(&cfg_val) {
                 (cfg_val.to_string(), "config".to_string())
             } else {
-                ("ASK".to_string(), "none".to_string())
+                (default_backend, "default".to_string())
             }
         } else {
-            ("ASK".to_string(), "none".to_string())
+            (default_backend, "default".to_string())
         }
     };
 

flowctl/crates/flowctl-cli/src/commands/admin/review.rs

@@ -43,14 +43,16 @@ If memory returns critical-severity pitfalls, **pause and review them** before p
 Verify review backends are reachable before entering work/review phases:
 
 ```bash
-# Check configured review backend
+# Check configured review backend (returns "rp", "codex", "none", or "ASK")
 REVIEW_BACKEND=$($FLOWCTL review-backend 2>/dev/null || echo "none")
 
 if [ "$REVIEW_BACKEND" = "rp" ]; then
   # Check if rp-cli or RP MCP is available
   which rp-cli >/dev/null 2>&1 || echo "WARNING: review backend is 'rp' but rp-cli not found. Reviews will fail. Set to 'none' via: $FLOWCTL config set review.backend none"
 elif [ "$REVIEW_BACKEND" = "codex" ]; then
   which codex >/dev/null 2>&1 || echo "WARNING: review backend is 'codex' but codex CLI not found. Reviews will fail."
+elif [ "$REVIEW_BACKEND" = "ASK" ] || [ "$REVIEW_BACKEND" = "none" ]; then
+  echo "INFO: No review backend configured. Reviews will be skipped. To enable: $FLOWCTL config set review.backend rp"
 fi
 ```
 

skills/_shared/preamble.md

@@ -70,29 +70,31 @@ Detect input type to decide whether to execute or skip:
 
 ### Plan (plan)
 1. Spawn research scouts in parallel (repo-scout, context-scout, practice-scout)
-2. Write epic spec via $FLOWCTL epic plan
-3. Create tasks via $FLOWCTL task create with dependencies
+2. Write epic spec via `$FLOWCTL epic plan $EPIC_ID --spec "..." --json` (ID is positional, not a flag)
+3. Create tasks via `$FLOWCTL task create --epic $EPIC_ID --title "..." --deps "task1,task2" --json` (use `--deps` for dependencies, `--epic` is required)
 4. Validate: $FLOWCTL validate --epic $EPIC_ID --json
 
 ### Plan Review (plan_review)
-1. Detect review backend: $FLOWCTL review-backend
-2. Run review via RP context_builder or Codex
-3. Fix issues until SHIP verdict (max 3 iterations)
-4. If backend is none, skip and advance
+1. Detect review backend: `$FLOWCTL review-backend` (returns "rp", "codex", "none", or "ASK")
+2. If backend is "none" or "ASK", skip review and advance with `$FLOWCTL phase done`
+3. Otherwise run review via RP context_builder or Codex
+4. Fix issues until SHIP verdict (max 3 iterations)
 
 ### Work (work)
-1. Find ready tasks: $FLOWCTL ready $EPIC_ID --json
-2. Start tasks: $FLOWCTL start <task-id> --json
-3. Lock files: $FLOWCTL lock --task <id> --files "<files>"
+1. Find ready tasks: `$FLOWCTL ready $EPIC_ID --json`
+2. Start tasks: `$FLOWCTL start <task-id> --json`
+3. Lock files: `$FLOWCTL lock --task <task-id> --files "file1,file2" --json`
 4. Spawn ALL ready workers in ONE parallel Agent call with isolation worktree and team_name
 5. Wait for workers, merge worktree branches back
-6. Wave checkpoint: verify done, run guards
-7. Repeat waves until no ready tasks remain
+6. Mark tasks complete: `$FLOWCTL done <task-id> --summary "what was done" --json`
+7. Wave checkpoint: verify done, run guards
+8. Repeat waves until no ready tasks remain
 
 ### Impl Review (impl_review)
-1. Run adversarial review via Codex or RP
-2. Fix issues until SHIP (max 2 iterations)
-3. If no review backend, skip and advance
+1. Detect review backend: `$FLOWCTL review-backend` (same as plan_review)
+2. If backend is "none" or "ASK", skip review and advance with `$FLOWCTL phase done`
+3. Otherwise run adversarial review via Codex or RP
+4. Fix issues until SHIP (max 2 iterations)
 
 ### Close (close)
 1. Validate: $FLOWCTL validate --epic $EPIC_ID --json