feat: RP Orchestrate pattern adoption — parallel explore, plan-as-contract, concurrency awareness (v0.1.50)

z23cc · claude · z23cc · commit d41495c8c19c · 2026-04-10T15:43:11.000+08:00
- Brainstorm phase now spawns 3 parallel explore agents (patterns, gaps, impact)
  before context_builder call for multi-dimensional codebase analysis
- flowctl worker-prompt outputs PLAN CONTRACT preamble (workers must read epic spec
  first, implement only their task) and CONCURRENT_WORKERS block (other active tasks
  + locked files)
- worker.md Phase 2 restructured: plan-as-contract (2.0), concurrency awareness (2.1),
  read specs (2.2) — workers parse concurrent context and escalate file conflicts
- Codex step-03-find-ready.md updated with lock + worker-prompt generation

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.claude-plugin/flowctl-version b/.claude-plugin/flowctl-version
@@ -1 +1 @@
-v0.1.49
+v0.1.50
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Structured plan-first development plugin for Claude Code with .flow/ task tracking, Agent Teams, and Ralph autonomous mode",
-    "version": "0.1.49"
+    "version": "0.1.50"
   },
   "plugins": [
     {
       "name": "flow-code",
       "description": "Zero-dependency planning + execution with .flow/ task tracking. Three-layer quality (guard + RP plan-review + Codex adversarial). Full-auto, zero questions. Teams auto-parallel, DAG mutation, Codex-driven decisions, auto draft-PR, session summary. 5 prompt templates plus dedicated subagents, slash commands, and skills.",
-      "version": "0.1.49",
+      "version": "0.1.50",
       "source": "./",
       "category": "workflow",
       "tags": [
@@ -26,5 +26,5 @@
       "strict": true
     }
   ],
-  "version": "0.1.49"
+  "version": "0.1.50"
 }
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "flow-code",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "description": "Zero-dependency planning + execution with .flow/ task tracking and Ralph autonomous mode (multi-model review gates). Worker subagent per task with git worktree isolation for parallel execution. Three-layer quality system (guard + RP plan-review + Codex adversarial). Full-auto by default — AI decides from context, zero questions. Teams-default with file locking, DAG mutation, Codex-driven conflict resolution, auto draft-PR. Auto-detected stack profiles with one-command guard (test/lint/typecheck). Enhanced agent definitions with permissionMode/maxTurns/effort. Lifecycle hooks with state preservation (PreCompact injects .flow state into compaction, TaskCompleted auto-unlocks files, SubagentStart context injection). Memory v2 with atomic entries, dedup, and progressive disclosure. TDD enforcement mode. Multi-epic queue with dependency visualization. Includes dedicated subagents, slash commands, and skills for planning, execution, review, and autonomous operation.",
   "author": {
     "name": "z23cc",
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "flow-code",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "description": "Zero-dependency planning + execution with .flow/ task tracking and Ralph autonomous mode (multi-model review gates). Worker subagent per task with git worktree isolation for parallel execution. Three-layer quality system (guard + RP plan-review + Codex adversarial). Full-auto by default. Teams-default with file locking, DAG mutation, Codex-driven conflict resolution, auto draft-PR.",
   "author": {
     "name": "z23cc",
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,19 @@ All notable changes to Flow-Code are documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/). Versions use [Semantic Versioning](https://semver.org/).
 
+## [0.1.50] - 2026-04-10
+
+### Added
+- **Parallel explore agents** in brainstorm phase — 3 concurrent agents (patterns, gaps, impact) scan codebase before context_builder call
+- **PLAN CONTRACT** in worker prompts — workers must read epic spec first, implement only their task
+- **CONCURRENT_WORKERS** in worker prompts — workers see other active tasks and their locked files
+- **Concurrency awareness** in worker Phase 2 — mandatory plan citation and conflict escalation protocol
+
+### Changed
+- `flowctl worker-prompt` now outputs plan-as-contract preamble and concurrent worker context
+- Worker agent (`worker.md`) Phase 2 restructured with plan-as-contract (2.0), concurrency awareness (2.1), and read specs (2.2) sub-phases
+- Codex worker steps (`step-03-find-ready.md`) updated with lock + worker-prompt generation guidance
+
 ## [0.1.49] - 2026-04-10
 
 ### Changed
diff --git a/agents/worker.md b/agents/worker.md
@@ -157,6 +157,32 @@ When you receive a steer instruction, integrate it into your current work.
 <!-- section:core -->
 ## Phase 2: Re-anchor (CRITICAL - DO NOT SKIP)
 
+### 2.0: Plan-as-Contract (MANDATORY)
+
+Your prompt begins with a `PLAN CONTRACT` line. You MUST honor it:
+1. Read the epic spec file referenced in the contract (`.flow/specs/<EPIC_ID>.md`)
+2. Find the section relevant to YOUR task and cite it (copy the relevant paragraph)
+3. Confirm your task's scope matches the spec — if it doesn't, output `STATUS: spec_conflict`
+
+This is not optional. The spec file is the binding contract between you and the coordinator.
+
+### 2.1: Concurrency Awareness
+
+If your prompt contains a `CONCURRENT_WORKERS` section:
+1. Parse each concurrent worker's ID, title, and locked files
+2. Do NOT modify any files listed as owned by other workers
+3. If you discover you need a file owned by another worker, output:
+   ```
+   STATUS: needs_file_access
+   NEEDS_ACCESS: <file-path>
+   CONFLICT_WITH: <other-task-id>
+   ```
+4. The coordinator will resolve the conflict via `steer`
+
+If no `CONCURRENT_WORKERS` section is present, you are the only active worker — no restrictions beyond your OWNED_FILES.
+
+### 2.2: Read Specs and Context
+
 Use the FLOWCTL path and IDs from your prompt:
 
 ```bash
diff --git a/bin/flowctl b/bin/flowctl
diff --git a/codex/skills/flow-code-work/steps/step-03-find-ready.md b/codex/skills/flow-code-work/steps/step-03-find-ready.md
@@ -60,8 +60,25 @@ $FLOWCTL cat <task-id>
 # 1. Start each task
 $FLOWCTL start <task-id-1> --json
 $FLOWCTL start <task-id-2> --json
+
+# 2. Lock owned files
+$FLOWCTL lock --task <task-id-1> --files "<file1>,<file2>" --json
+$FLOWCTL lock --task <task-id-2> --files "<file3>,<file4>" --json
+```
+
+## Worker Prompt Generation
+
+Use `flowctl worker-prompt` to generate the bootstrap prompt for each worker. The generated prompt automatically includes:
+
+- **PLAN CONTRACT**: Instructs the worker to read the epic spec first and implement only their task
+- **CONCURRENT_WORKERS**: Lists other in-progress tasks and their locked files so the worker avoids conflicts
+
+```bash
+$FLOWCTL worker-prompt --task <task-id> --bootstrap --inline-skills --json
 ```
 
+The worker MUST honor the PLAN CONTRACT and CONCURRENT_WORKERS sections. See `agents/worker.md` Phase 2 for the worker's handling of these sections.
+
 ## Next Step
 
-Read `steps/step-04-spawn-workers.md` and execute.
+Spawn workers using `agent_run` with the generated prompts. Each worker runs in an isolated git worktree.
diff --git a/flowctl/Cargo.lock b/flowctl/Cargo.lock
diff --git a/flowctl/crates/flowctl-cli/Cargo.toml b/flowctl/crates/flowctl-cli/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "flowctl-cli"
-version = "0.1.49"
+version = "0.1.50"
 description = "CLI entry point for flowctl"
 edition.workspace = true
 rust-version.workspace = true
diff --git a/flowctl/crates/flowctl-cli/src/commands/admin/guard.rs b/flowctl/crates/flowctl-cli/src/commands/admin/guard.rs
@@ -630,13 +630,65 @@ pub fn cmd_worker_prompt(
         String::new()
     };
 
+    // ── Plan-as-contract preamble (RP Orchestrate pattern) ──────────
+    let plan_contract = format!(
+        "PLAN CONTRACT: Read .flow/specs/{epic}.md FIRST. You implement ONLY task {task}: \"{title}\". Do NOT modify files outside your OWNED_FILES list.",
+        epic = epic_id,
+        task = task,
+        title = {
+            let flow_dir = get_flow_dir();
+            flowctl_core::json_store::task_read(&flow_dir, &task)
+                .map(|t| t.title.clone())
+                .unwrap_or_else(|_| "(unknown)".to_string())
+        },
+    );
+
+    // ── Concurrency context (RP Orchestrate pattern) ────────────────
+    let concurrent_section = {
+        let flow_dir = get_flow_dir();
+        let mut lines = Vec::new();
+        if let Ok(tasks) = flowctl_core::json_store::task_list_by_epic(&flow_dir, &epic_id) {
+            let locks = flowctl_core::json_store::locks_read(&flow_dir).unwrap_or_default();
+            for t in &tasks {
+                if t.id != task
+                    && t.status == flowctl_core::state_machine::Status::InProgress
+                {
+                    let task_locks: Vec<&str> = locks
+                        .iter()
+                        .filter(|l| l.task_id == t.id)
+                        .map(|l| l.file_path.as_str())
+                        .collect();
+                    let lock_str = if task_locks.is_empty() {
+                        "(no locked files)".to_string()
+                    } else {
+                        task_locks.join(", ")
+                    };
+                    lines.push(format!(
+                        "- {}: \"{}\" (files: {})",
+                        t.id, t.title, lock_str
+                    ));
+                }
+            }
+        }
+        if lines.is_empty() {
+            String::new()
+        } else {
+            format!(
+                "\n\nCONCURRENT_WORKERS:\n{}\nDo NOT modify files owned by other workers. If you need a file another worker owns, output:\n  STATUS: needs_file_access\n  NEEDS_ACCESS: <file-path>",
+                lines.join("\n")
+            )
+        }
+    };
+
     let prompt_text = format!(
-        "TASK_ID: {task}\nEPIC_ID: {epic_id}\n{tdd_line}\n{review_line}\n\nPhase sequence:\n{phases}\n\nExecute phases in order. Every `flowctl worker-phase done` must include a JSON receipt (`--receipt` or `--receipt-file`). Phase 10 also requires `flowctl done` to have already marked the task done. Use flowctl worker-phase next/done to track progress.{skills}",
+        "{plan_contract}\n\nTASK_ID: {task}\nEPIC_ID: {epic_id}\n{tdd_line}\n{review_line}\n\nPhase sequence:\n{phases}\n\nExecute phases in order. Every `flowctl worker-phase done` must include a JSON receipt (`--receipt` or `--receipt-file`). Phase 10 also requires `flowctl done` to have already marked the task done. Use flowctl worker-phase next/done to track progress.{concurrent}{skills}",
+        plan_contract = plan_contract,
         task = task,
         epic_id = epic_id,
         tdd_line = tdd_line,
         review_line = review_line,
         phases = phase_list.join("\n"),
+        concurrent = concurrent_section,
         skills = skills_section,
     );
 
diff --git a/skills/flow-code-run/SKILL.md b/skills/flow-code-run/SKILL.md
@@ -111,10 +111,31 @@ $FLOWCTL graph map --json
 $FLOWCTL find "<key terms from request>" --json
 ```
 
+**MANDATORY Step 1.5: Parallel explore agents** (RP Orchestrate pattern)
+
+Spawn 3 lightweight explore agents in parallel to scan different codebase dimensions. These run concurrently while you proceed to classify complexity. Their results feed into the context_builder call.
+
+```
+# Launch ALL THREE in a single message (parallel execution):
+Agent(subagent_type="Explore", name="explore-patterns",
+  prompt="Scan the codebase for existing patterns and conventions relevant to: <request summary>. Report: key patterns found, naming conventions, architecture style, reusable utilities. Under 200 words.",
+  run_in_background=true)
+
+Agent(subagent_type="Explore", name="explore-gaps",
+  prompt="Analyze the codebase for gaps, technical debt, and missing pieces relevant to: <request summary>. Report: what's missing, what's inconsistent, what would break. Under 200 words.",
+  run_in_background=true)
+
+Agent(subagent_type="Explore", name="explore-impact",
+  prompt="Trace dependency chains and impact areas for: <request summary>. Report: which files depend on what, what changes would cascade, risk areas. Under 200 words.",
+  run_in_background=true)
+```
+
+Wait for all 3 to complete. Collect their findings into `EXPLORE_FINDINGS`.
+
 ```
-# Then use context_builder for deeper analysis — reused by Plan phase
+# Then use context_builder for deeper analysis — enriched with explore findings
 mcp__RepoPrompt__context_builder({
-  instructions: "<request summary>. Local fast-path findings: <graph map + find results>. Analyze: relevant files, existing patterns, potential approaches, complexity.",
+  instructions: "<request summary>. Local fast-path findings: <graph map + find results>. Parallel explore findings: <EXPLORE_FINDINGS>. Analyze: relevant files, existing patterns, potential approaches, complexity.",
   response_type: "question"
 })
 → save chat_id as BRAINSTORM_CHAT_ID (Plan phase will reuse this via oracle_send)

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "flow-code",`
`3`		`- "version": "0.1.49",`
	`3`	`+ "version": "0.1.50",`
`4`	`4`	"description": "Zero-dependency planning + execution with .flow/ task tracking and Ralph autonomous mode (multi-model review gates). Worker subagent per task with git worktree isolation for parallel execution. Three-layer quality system (guard + RP plan-review + Codex adversarial). Full-auto by default — AI decides from context, zero questions. Teams-default with file locking, DAG mutation, Codex-driven conflict resolution, auto draft-PR. Auto-detected stack profiles with one-command guard (test/lint/typecheck). Enhanced agent definitions with permissionMode/maxTurns/effort. Lifecycle hooks with state preservation (PreCompact injects .flow state into compaction, TaskCompleted auto-unlocks files, SubagentStart context injection). Memory v2 with atomic entries, dedup, and progressive disclosure. TDD enforcement mode. Multi-epic queue with dependency visualization. Includes dedicated subagents, slash commands, and skills for planning, execution, review, and autonomous operation.",
`5`	`5`	`"author": {`
`6`	`6`	`"name": "z23cc",`