refactor(flowctl): unify CLI arg style — positional for primary entity, flag for filters

z23cc · claude · z23cc · commit 83152ac81068 · 2026-04-08T00:55:28.000+08:00
4 commands (estimate, ready, events, files) now accept epic ID as positional arg
while keeping --epic flag for backwards compatibility. Added --spec inline alias
to epic plan. Updated all 14 docs/skill files (25 occurrences) to use new style.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -83,7 +83,7 @@ Rust: clippy for linting, cargo test for tests. No TypeScript, no npm. Skills an
 - **Epic archival**: `flowctl epic archive <id>` moves closed epic + tasks + specs + reviews to `.flow/.archive/`; `flowctl epic clean` archives all closed epics at once
 - **Learning loop**: plan injects memory (Step 6), worker saves lessons (Phase 11, included in default sequence when memory.enabled is true), epic close prompts retro, retro verifies stale entries via `flowctl memory verify <id>`
 - **Task duration**: `flowctl done` auto-tracks `duration_seconds` from start to completion, rendered in evidence
-- **File ownership**: `flowctl task create --files <paths>` declares owned files; `flowctl files --epic <id>` shows ownership map + conflict detection
+- **File ownership**: `flowctl task create --files <paths>` declares owned files; `flowctl files <id>` shows ownership map + conflict detection
 - **File locking (Teams)**: `flowctl lock --task <id> --files <paths>` acquires runtime file locks; `flowctl unlock --task <id>` releases on completion; `flowctl lock-check --file <path>` inspects lock state; `flowctl unlock --all` clears all locks between waves
 - **Agent Teams mode**: `/flow-code:run` (or legacy `/flow-code:work`) spawns workers as Agent Team teammates with plain-text protocol messages (summary-prefix routing: "Task complete:", "Spec conflict:", "Blocked:", "Need file access:", "New task:", "Access granted/denied:", native `shutdown_request`) and file lock enforcement
 - **Adversarial review**: `flowctl codex adversarial --base main [--focus "area"]` runs Codex in adversarial mode — tries to break the code, not validate it. Returns SHIP/NEEDS_WORK with grounded findings
diff --git a/README.md b/README.md
@@ -195,7 +195,7 @@ export PATH=".flow/bin:$PATH"
 flowctl --help
 flowctl epics                # List all epics
 flowctl tasks --epic fn-1    # List tasks for epic
-flowctl ready --epic fn-1    # What's ready to work on
+flowctl ready fn-1           # What's ready to work on
 ```
 
 ### 3. Use
@@ -1663,7 +1663,7 @@ flowctl task set-acceptance fn-1.1 --file accept.md
 flowctl dep add fn-1.3 fn-1.2             # fn-1.3 depends on fn-1.2
 
 # Workflow
-flowctl ready --epic fn-1                 # Show ready/in_progress/blocked
+flowctl ready fn-1                        # Show ready/in_progress/blocked
 flowctl next                              # Select next plan/work unit
 flowctl start fn-1.1                      # Claim and start task
 flowctl done fn-1.1 --summary-file s.md --evidence-json e.json
@@ -1862,7 +1862,7 @@ This project uses Flow-Code for task tracking. `flowctl` must be in PATH (`~/.fl
 
 Quick commands:
 - `flowctl list` — list epics + tasks
-- `flowctl ready --epic fn-N` — what's ready
+- `flowctl ready fn-N` — what's ready
 - `flowctl start fn-N.M` — claim task
 - `flowctl done fn-N.M --summary-file s.md --evidence-json e.json`
 
diff --git a/README_CN.md b/README_CN.md
@@ -187,7 +187,7 @@ export PATH=".flow/bin:$PATH"
 flowctl --help
 flowctl epics                # 列出所有 epic
 flowctl tasks --epic fn-1    # 列出 epic 的任务
-flowctl ready --epic fn-1    # 查看准备就绪的任务
+flowctl ready fn-1           # 查看准备就绪的任务
 ```
 
 ### 3. 使用
@@ -1545,7 +1545,7 @@ flowctl task set-acceptance fn-1.1 --file accept.md
 flowctl dep add fn-1.3 fn-1.2             # fn-1.3 依赖 fn-1.2
 
 # 工作流
-flowctl ready --epic fn-1                 # 显示就绪/进行中/已阻塞
+flowctl ready fn-1                        # 显示就绪/进行中/已阻塞
 flowctl next                              # 选择下一个 plan/work 单元
 flowctl start fn-1.1                      # 认领并开始任务
 flowctl done fn-1.1 --summary-file s.md --evidence-json e.json
@@ -1736,7 +1736,7 @@ flowctl config set review.backend codex
 
 快速命令：
 - `flowctl list` — 列出 epic + 任务
-- `flowctl ready --epic fn-N` — 查看就绪任务
+- `flowctl ready fn-N` — 查看就绪任务
 - `flowctl start fn-N.M` — 认领任务
 - `flowctl done fn-N.M --summary-file s.md --evidence-json e.json`
 
diff --git a/codex/skills/flow-code-plan/steps.md b/codex/skills/flow-code-plan/steps.md
@@ -286,7 +286,7 @@ Default to standard unless complexity demands more or less.
 
    # Task with file ownership (recommended for parallel execution):
    $FLOWCTL task create --epic <epic-id> --title "<Task title>" --files "src/auth.ts,src/routes.ts" --json
-   # Enables flowctl files --epic <id> to detect conflicts before parallel execution
+   # Enables flowctl files <id> to detect conflicts before parallel execution
    ```
 
    **TIP**: Use `--deps` to declare dependencies inline when creating tasks. Tasks must exist before being referenced, so create in dependency order. Use `--domain` when the task clearly belongs to a specific area. Use `--files` to declare file ownership for teams/parallel conflict prevention.
diff --git a/codex/skills/flow-code-setup/templates/claude-md-snippet.md b/codex/skills/flow-code-setup/templates/claude-md-snippet.md
@@ -8,7 +8,7 @@ This project uses Flow-Code for task tracking. Use `.flow/bin/flowctl` instead o
 .flow/bin/flowctl list                # List all epics + tasks
 .flow/bin/flowctl epics               # List all epics
 .flow/bin/flowctl tasks --epic fn-N   # List tasks for epic
-.flow/bin/flowctl ready --epic fn-N   # What's ready
+.flow/bin/flowctl ready fn-N          # What's ready
 .flow/bin/flowctl show fn-N.M         # View task
 .flow/bin/flowctl start fn-N.M        # Claim task
 .flow/bin/flowctl done fn-N.M --summary-file s.md --evidence-json e.json
diff --git a/codex/skills/flow-code-setup/templates/usage.md b/codex/skills/flow-code-setup/templates/usage.md
@@ -46,7 +46,7 @@ Task tracking for AI agents. All state lives in `.flow/`.
 .flow/bin/flowctl cat fn-1-add-oauth.2          # Task spec (markdown)
 
 # Status
-.flow/bin/flowctl ready --epic fn-1-add-oauth   # What's ready to work on
+.flow/bin/flowctl ready fn-1-add-oauth           # What's ready to work on
 .flow/bin/flowctl validate --all                # Check structure
 .flow/bin/flowctl state-path                    # Show state directory (for worktrees)
 
@@ -67,7 +67,7 @@ Task tracking for AI agents. All state lives in `.flow/`.
 ## Workflow
 
 1. `.flow/bin/flowctl epics` - list all epics
-2. `.flow/bin/flowctl ready --epic fn-N-slug` - find available tasks
+2. `.flow/bin/flowctl ready fn-N-slug` - find available tasks
 3. `.flow/bin/flowctl start fn-N-slug.M` - claim task
 4. Implement the task
 5. `.flow/bin/flowctl done fn-N-slug.M --summary-file ... --evidence-json ...` - complete
diff --git a/codex/skills/flow-code-work/phases.md b/codex/skills/flow-code-work/phases.md
@@ -42,7 +42,7 @@ Detect input type in this order (first match wins):
 - Clear auto-execute marker (confirms work has started): `$FLOWCTL epic auto-exec <id> --done --json`
 - Read epic: `$FLOWCTL show <id> --json`
 - Read spec: `$FLOWCTL cat <id>`
-- Get first ready task: `$FLOWCTL ready --epic <id> --json`
+- Get first ready task: `$FLOWCTL ready <id> --json`
 
 **Spec file start (.md path that exists)**:
 1. Check file exists: `test -f "<path>"` — if not, treat as idea text
@@ -107,7 +107,7 @@ $FLOWCTL restart <stale-task-id> --json
 After restarts, find ready tasks normally:
 
 ```bash
-$FLOWCTL ready --epic <epic-id> --json
+$FLOWCTL ready <epic-id> --json
 ```
 
 Collect ALL ready tasks (no unresolved dependencies). If no ready tasks, check for completion review gate (see Step 10 below).
diff --git a/codex/skills/flow-code/SKILL.md b/codex/skills/flow-code/SKILL.md
@@ -52,7 +52,7 @@ $FLOWCTL show fn-1-add-oauth.2 --json
 $FLOWCTL cat fn-1-add-oauth.2            # Task spec
 
 # What's ready to work on?
-$FLOWCTL ready --epic fn-1-add-oauth --json
+$FLOWCTL ready fn-1-add-oauth --json
 
 # Create task under existing epic
 $FLOWCTL task create --epic fn-1-add-oauth --title "Fix bug X" --json
@@ -125,7 +125,7 @@ $FLOWCTL tasks --json
 $FLOWCTL tasks --epic fn-1-add-oauth --json
 
 # Ready tasks for an epic
-$FLOWCTL ready --epic fn-1-add-oauth --json
+$FLOWCTL ready fn-1-add-oauth --json
 ```
 
 ### "Show me task X"
diff --git a/docs/flowctl.md b/docs/flowctl.md
@@ -384,9 +384,11 @@ flowctl cat fn-1.2    # Task spec
 List tasks ready to start, in progress, and blocked.
 
 ```bash
-flowctl ready --epic fn-1 [--json]
+flowctl ready fn-1 [--json]
 ```
 
+> `--epic` flag is still accepted for backwards compatibility.
+
 Output:
 ```json
 {
@@ -929,9 +931,11 @@ Also available via `flowctl status --dag --epic fn-1`.
 Estimate remaining time for an epic based on historical task durations.
 
 ```bash
-flowctl estimate --epic fn-1 [--json]
+flowctl estimate fn-1 [--json]
 ```
 
+> `--epic` flag is still accepted for backwards compatibility.
+
 ### replay
 
 Replay an epic: reset all tasks to `todo` for re-execution.
@@ -1106,9 +1110,11 @@ flowctl stats cleanup [--json]   # Delete old events/rollups
 Show file ownership map for an epic.
 
 ```bash
-flowctl files --epic fn-1 [--json]
+flowctl files fn-1 [--json]
 ```
 
+> `--epic` flag is still accepted for backwards compatibility.
+
 Shows which tasks own which files and detects ownership conflicts.
 
 ### lock
diff --git a/docs/token-optimization-audit.md b/docs/token-optimization-audit.md
@@ -257,7 +257,7 @@ The orchestrator context is the **true bottleneck** — it accumulates across th
 | 35 | Worker completion messages: compact format `done: fn-15.3 files=3 build=ok 120s` | `agents/worker.md` Phase 5 | P0 |
 | 36 | Evidence stored to file by default (`.flow/evidence/<task>.json`); orchestrator reads on demand | `agents/worker.md` Phase 4 | P0 |
 | 37 | Orchestrator polling `tasks` defaults to compact output | `skills/flow-code-work/SKILL.md` | P0 |
-| 38 | `flowctl files --epic X` compact (Teams lock-conflict hot path) | Same as #3 | P0 |
+| 38 | `flowctl files X` compact (Teams lock-conflict hot path) | Same as #3 | P0 |
 | 39 | `flowctl lock-check --file X` minimal output (`free` / `held:X`) | `commands/lock.rs` | P0 |
 
 ### 2.8 rtk integration layer
diff --git a/flowctl/crates/flowctl-cli/src/commands/epic/crud.rs b/flowctl/crates/flowctl-cli/src/commands/epic/crud.rs
@@ -107,14 +107,20 @@ pub fn cmd_create(title: &str, branch: &Option<String>, json_mode: bool, dry_run
     }
 }
 
-pub fn cmd_set_plan(id: &str, file: &str, json_mode: bool) {
+pub fn cmd_set_plan(id: &str, file: Option<&str>, spec: Option<&str>, json_mode: bool) {
     let flow_dir = ensure_flow_exists();
     validate_epic_id(id);
 
     let mut doc = load_epic(id);
 
-    // Read content from file or stdin
-    let content = read_file_or_stdin(file);
+    // Read content from --spec (inline), --file, or error
+    let content = if let Some(text) = spec {
+        text.to_string()
+    } else if let Some(f) = file {
+        read_file_or_stdin(f)
+    } else {
+        error_exit("Either --file or --spec is required");
+    };
 
     // Validate: reject duplicate headings
     let heading_re = regex::Regex::new(r"(?m)^(##\s+.+?)\s*$").expect("valid regex");
diff --git a/flowctl/crates/flowctl-cli/src/commands/epic/mod.rs b/flowctl/crates/flowctl-cli/src/commands/epic/mod.rs
@@ -18,7 +18,7 @@ pub use types::EpicCmd;
 pub fn dispatch(cmd: &EpicCmd, json: bool, dry_run: bool) {
     match cmd {
         EpicCmd::Create { title, branch } => crud::cmd_create(title, branch, json, dry_run),
-        EpicCmd::Plan { id, file } => crud::cmd_set_plan(id, file, json),
+        EpicCmd::Plan { id, file, spec } => crud::cmd_set_plan(id, file.as_deref(), spec.as_deref(), json),
         EpicCmd::Review { id, status } => crud::cmd_set_plan_review_status(id, status, json),
         EpicCmd::Completion { id, status } => {
             crud::cmd_set_completion_review_status(id, status, json)
diff --git a/flowctl/crates/flowctl-cli/src/commands/epic/types.rs b/flowctl/crates/flowctl-cli/src/commands/epic/types.rs
@@ -13,13 +13,16 @@ pub enum EpicCmd {
         #[arg(long)]
         branch: Option<String>,
     },
-    /// Set epic spec from file (use '-' for stdin).
+    /// Set epic spec from file or inline text.
     Plan {
         /// Epic ID.
         id: String,
         /// Markdown file (use '-' for stdin).
         #[arg(long)]
-        file: String,
+        file: Option<String>,
+        /// Inline spec text (alternative to --file).
+        #[arg(long)]
+        spec: Option<String>,
     },
     /// Set plan review status.
     Review {
diff --git a/flowctl/crates/flowctl-cli/src/main.rs b/flowctl/crates/flowctl-cli/src/main.rs
@@ -144,9 +144,11 @@ enum Commands {
     },
     /// Estimate remaining time for an epic based on historical durations.
     Estimate {
-        /// Epic ID.
-        #[arg(long)]
-        epic: String,
+        /// Epic ID (positional).
+        id: Option<String>,
+        /// Epic ID (flag, kept for compatibility).
+        #[arg(long = "epic")]
+        epic_flag: Option<String>,
     },
     /// Replay an epic: reset all tasks to todo for re-execution.
     Replay {
@@ -307,9 +309,11 @@ enum Commands {
     },
     /// Show file ownership map for epic.
     Files {
-        /// Epic ID.
-        #[arg(long)]
-        epic: String,
+        /// Epic ID (positional).
+        id: Option<String>,
+        /// Epic ID (flag, kept for compatibility).
+        #[arg(long = "epic")]
+        epic_flag: Option<String>,
     },
     /// Lock files for a task (Teams mode).
     Lock {
@@ -351,9 +355,11 @@ enum Commands {
     // ── Workflow commands ─────────────────────────────────────────────
     /// List ready tasks.
     Ready {
-        /// Epic ID.
-        #[arg(long)]
-        epic: String,
+        /// Epic ID (positional).
+        id: Option<String>,
+        /// Epic ID (flag, kept for compatibility).
+        #[arg(long = "epic")]
+        epic_flag: Option<String>,
     },
     /// Select next plan/work unit.
     Next {
@@ -436,9 +442,11 @@ enum Commands {
 
     /// Show event store history for an epic (all streams).
     Events {
-        /// Epic ID.
-        #[arg(long)]
-        epic: String,
+        /// Epic ID (positional).
+        id: Option<String>,
+        /// Epic ID (flag, kept for compatibility).
+        #[arg(long = "epic")]
+        epic_flag: Option<String>,
     },
 
     // ── Data exchange ────────────────────────────────────────────────
@@ -492,6 +500,13 @@ fn main() {
     let json = cli.output.json;
     let dry_run = cli.dry_run;
 
+    /// Resolve dual-mode argument: positional `id` takes precedence over `--epic` flag.
+    fn resolve_epic(id: Option<String>, epic_flag: Option<String>, cmd_name: &str) -> String {
+        id.or(epic_flag).unwrap_or_else(|| {
+            output::error_exit(&format!("{cmd_name} requires an epic ID (positional or --epic)"));
+        })
+    }
+
     match cli.command {
         // Admin / top-level
         Commands::Init => admin::cmd_init(json),
@@ -521,7 +536,10 @@ fn main() {
         }
 
         Commands::Dag { id } => commands::stats::cmd_dag(json, Some(id)),
-        Commands::Estimate { epic } => commands::stats::cmd_estimate(json, &epic),
+        Commands::Estimate { id, epic_flag } => {
+            let epic = resolve_epic(id, epic_flag, "estimate");
+            commands::stats::cmd_estimate(json, &epic);
+        }
         Commands::Replay { epic_id, dry_run, force } => commands::epic::cmd_replay(json, &epic_id, dry_run, force),
         Commands::Diff { epic_id } => commands::epic::cmd_diff(json, &epic_id),
 
@@ -559,14 +577,20 @@ fn main() {
         } => query::cmd_tasks(json, epic, status, domain),
         Commands::List => query::cmd_list(json),
         Commands::Cat { id } => query::cmd_cat(id),
-        Commands::Files { epic } => query::cmd_files(json, epic),
+        Commands::Files { id, epic_flag } => {
+            let epic = resolve_epic(id, epic_flag, "files");
+            query::cmd_files(json, epic);
+        }
         Commands::Lock { task, files, mode } => query::cmd_lock(json, task, files, mode),
         Commands::Unlock { task, files, all } => query::cmd_unlock(json, task, files, all),
         Commands::LockCheck { file } => query::cmd_lock_check(json, file),
         Commands::Heartbeat { task } => query::cmd_heartbeat(json, task),
 
         // Workflow
-        Commands::Ready { epic } => workflow::cmd_ready(json, epic),
+        Commands::Ready { id, epic_flag } => {
+            let epic = resolve_epic(id, epic_flag, "ready");
+            workflow::cmd_ready(json, epic);
+        }
         Commands::Next {
             epics_file,
             require_plan_review,
@@ -609,7 +633,10 @@ fn main() {
             workflow::cmd_block(json, id, reason_text)
         }
         Commands::Fail { id, reason, force } => workflow::cmd_fail(json, id, reason, force),
-        Commands::Events { epic } => workflow::cmd_events(json, epic),
+        Commands::Events { id, epic_flag } => {
+            let epic = resolve_epic(id, epic_flag, "events");
+            workflow::cmd_events(json, epic);
+        }
 
         // Data exchange
         Commands::Export { epic, format } => admin::cmd_export(json, epic, format),
diff --git a/flowctl/tests/cmd/ready_missing_epic.toml b/flowctl/tests/cmd/ready_missing_epic.toml
@@ -1,6 +1,6 @@
 bin.name = "flowctl"
 args = ["ready"]
-status.code = 2
-stderr = """
+status.code = 1
+stdout = """
 ...
 """
diff --git a/skills/flow-code-run/SKILL.md b/skills/flow-code-run/SKILL.md
@@ -59,7 +59,7 @@ Loop until all phases complete:
 4. If backend is none, skip and advance
 
 ### Work (work)
-1. Find ready tasks: $FLOWCTL ready --epic $EPIC_ID --json
+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>"
 4. Spawn ALL ready workers in ONE parallel Agent call with isolation worktree and team_name
diff --git a/skills/flow-code-setup/templates/claude-md-snippet.md b/skills/flow-code-setup/templates/claude-md-snippet.md
@@ -8,7 +8,7 @@ This project uses Flow-Code for task tracking. Use `.flow/bin/flowctl` instead o
 .flow/bin/flowctl list                # List all epics + tasks
 .flow/bin/flowctl epics               # List all epics
 .flow/bin/flowctl tasks --epic fn-N   # List tasks for epic
-.flow/bin/flowctl ready --epic fn-N   # What's ready
+.flow/bin/flowctl ready fn-N          # What's ready
 .flow/bin/flowctl show fn-N.M         # View task
 .flow/bin/flowctl start fn-N.M        # Claim task
 .flow/bin/flowctl done fn-N.M --summary-file s.md --evidence-json e.json
diff --git a/skills/flow-code-setup/templates/usage.md b/skills/flow-code-setup/templates/usage.md
diff --git a/skills/flow-code/SKILL.md b/skills/flow-code/SKILL.md
