From 07eff22b717cbe86e04cf6bfd68cf9ab3f99f9cd Mon Sep 17 00:00:00 2001 From: Vel Lesikov Date: Fri, 14 Aug 2026 16:11:43 -0700 Subject: [PATCH] step3-implement-tasks: protect shared bookkeeping files in parallel waves MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Executors running concurrently all edit tasks.md (checkboxes) and agents-context/ (concept files + README) — files outside any plan's disjoint File operations list. Concurrent writes could clobber each other, and per-plan staging could orphan the bookkeeping from the group's atomic commit. Fix: when a wave holds 2+ groups, each executor's prompt gets a parallel-wave addendum forbidding writes to tasks.md and agents-context/. The executor instead reports completed tasks and proposed context updates in plans/group-N-updates.md; the orchestrator applies that file at commit time and stages it with the group, so every group's commit still carries its own checkboxes and context updates. The implementation-reviewer checks the updates file for wave groups. Sequential execution is unchanged. Co-Authored-By: Claude Fable 5 --- .../skills/step3-implement-tasks/SKILL.md | 2 +- .../shared/verification-agents.md | 4 ++- .../steps/execute-orchestrated.md | 26 +++++++++++++++++-- tests/test_skill_content.sh | 12 +++++++++ 4 files changed, 40 insertions(+), 4 deletions(-) diff --git a/lead-dev-os/skills/step3-implement-tasks/SKILL.md b/lead-dev-os/skills/step3-implement-tasks/SKILL.md index 2623d52..244e684 100644 --- a/lead-dev-os/skills/step3-implement-tasks/SKILL.md +++ b/lead-dev-os/skills/step3-implement-tasks/SKILL.md @@ -35,7 +35,7 @@ Shared procedures used by more than one step: - **Executor subagents never commit** — the orchestrator commits after verifying each group's work. When groups ran in parallel, stage each group's files separately so each group still gets its own atomic commit. - **Never delete tests, weaken assertions, skip migrations, or use `--no-verify`** to get to green — in your own work or by accepting it from a subagent. Surface the failure instead. - **Bounded retries everywhere.** Test-failure fixes: 2 attempts. Verification fix cycles: 2 rounds. After the limit, stop and report — the user would rather debug a stuck group with you than inherit silently disabled tests. -- **Check off tasks in `tasks.md` as each completes**, not in a batch at the end. This protects progress if the session is interrupted. +- **Check off tasks in `tasks.md` as each completes**, not in a batch at the end. This protects progress if the session is interrupted. Exception: executors running in a parallel wave never write `tasks.md` (or `agents-context/`) — they report completions via `plans/group-N-updates.md` and the orchestrator checks the boxes at commit time, so concurrent groups can't clobber each other's bookkeeping. ## Error handling diff --git a/lead-dev-os/skills/step3-implement-tasks/shared/verification-agents.md b/lead-dev-os/skills/step3-implement-tasks/shared/verification-agents.md index bb81829..c5eb2fe 100644 --- a/lead-dev-os/skills/step3-implement-tasks/shared/verification-agents.md +++ b/lead-dev-os/skills/step3-implement-tasks/shared/verification-agents.md @@ -32,7 +32,9 @@ standards: - Quality — dead code, leftover debug output, TODO stubs presented as done, swallowed errors? - Context updates — were the "Update after completing" concept files - actually updated, and agents-context/README.md kept in sync? + actually updated and agents-context/README.md kept in sync? (If this + group ran in a parallel wave, the updates are proposed in + /plans/group--updates.md instead — check that file.) Do not report style nitpicks that no loaded standards file backs. diff --git a/lead-dev-os/skills/step3-implement-tasks/steps/execute-orchestrated.md b/lead-dev-os/skills/step3-implement-tasks/steps/execute-orchestrated.md index 97f7731..3b64847 100644 --- a/lead-dev-os/skills/step3-implement-tasks/steps/execute-orchestrated.md +++ b/lead-dev-os/skills/step3-implement-tasks/steps/execute-orchestrated.md @@ -6,7 +6,7 @@ The main conversation acts as an orchestrator: each group is executed by a fresh Work through the approved execution schedule wave by wave: -1. **Parallel dispatch — one executor subagent per group in the current wave**, all in a single tool-call batch (`subagent_type: "general-purpose"`), using the prompt template below. Each executor starts with a fresh context and reads everything it needs from disk — never assume it inherits knowledge from this conversation. Dispatch a wave only when every group it depends on has been committed. If anything since planning has cast doubt on a wave's independence (a plan amended mid-run, drift reported by an earlier executor), re-check the two wave conditions — no dependency, disjoint file sets — and serialize when in doubt. +1. **Parallel dispatch — one executor subagent per group in the current wave**, all in a single tool-call batch (`subagent_type: "general-purpose"`), using the prompt template below. When the wave holds 2+ groups, append the **parallel-wave addendum** (below the prompt template) to each executor's prompt — the plans' "File operations" lists are disjoint, but `tasks.md` and `agents-context/` are shared by every group, so concurrent executors must not write them. Each executor starts with a fresh context and reads everything it needs from disk — never assume it inherits knowledge from this conversation. Dispatch a wave only when every group it depends on has been committed. If anything since planning has cast doubt on a wave's independence (a plan amended mid-run, drift reported by an earlier executor), re-check the two wave conditions — no dependency, disjoint file sets — and serialize when in doubt. 2. **Verify — trust but verify.** When an executor returns, run the group's verification command from `plans/group-.md` yourself. Do not take the executor's report at face value. @@ -14,7 +14,7 @@ Work through the approved execution schedule wave by wave: 4. **Review the diff** briefly yourself for scope creep, deleted tests, or weakened assertions — the reviewer checks this too, but the orchestrator owns the commit. -5. **Commit.** Executors never commit — the orchestrator commits after verifying. When groups ran in parallel, stage each group's files separately (use the plan's "File operations" list) so each group still gets its own atomic commit. Commit message: what the group shipped (not how), referencing the spec folder name. Don't sweep up unrelated changes — if the user has uncommitted edits outside this group's scope, ask before staging anything. +5. **Commit.** Executors never commit — the orchestrator commits after verifying. When groups ran in parallel: first apply the group's `plans/group--updates.md` yourself — check off its completed tasks in `tasks.md`, create/update the proposed concept files, and keep `agents-context/README.md` in sync — then stage the plan's "File operations" list **plus** those bookkeeping changes, so each group still gets its own atomic commit that includes its checkboxes and context updates. Commit message: what the group shipped (not how), referencing the spec folder name. Don't sweep up unrelated changes — if the user has uncommitted edits outside this group's scope, ask before staging anything. 6. **Report and continue:** - Group N complete @@ -71,3 +71,25 @@ Final report (structured): - Plan drift found and how the plan was amended (if any) - Blockers or open questions (if any) ``` + +## Parallel-wave addendum + +Append to the executor prompt only when the wave holds 2+ groups: + +``` +Parallel-wave addendum — this group runs concurrently with other groups +in the same working tree: + +- Do NOT modify tasks.md or any file under agents-context/ — they are + shared with the other groups' executors, and concurrent writes clobber + each other. This overrides steps 5 and 6 above. +- Instead, write /plans/group--updates.md with two sections: + 1. Completed tasks — the task numbers from Group N to check off in + tasks.md + 2. Context updates — each concept file to create or update, with its + full proposed content, plus the agents-context/README.md entries to + add or refresh (index entry, Load-When Cheatsheet, cross-references) + +The orchestrator applies this file and commits it together with your +group's changes. +``` diff --git a/tests/test_skill_content.sh b/tests/test_skill_content.sh index 5d6c125..d417b29 100755 --- a/tests/test_skill_content.sh +++ b/tests/test_skill_content.sh @@ -262,6 +262,18 @@ else fail "step3 does not reference Execution Waves" fi +if grep -q 'Parallel-wave addendum' "$STEP3_DIR/steps/execute-orchestrated.md" 2>/dev/null; then + pass "step3 parallel-wave executors get the shared-file addendum" +else + fail "step3 missing parallel-wave addendum" +fi + +if grep -rq 'group--updates.md' "$STEP3_DIR" 2>/dev/null; then + pass "step3 parallel-wave bookkeeping goes through group-N-updates.md" +else + fail "step3 missing group-N-updates.md bookkeeping mechanism" +fi + # --- Full-suite backstop gate --- echo ""