From 3e53c929b752ff6e99dd1b6d703b96072ea6395d Mon Sep 17 00:00:00 2001 From: Vel Lesikov Date: Fri, 14 Aug 2026 15:48:11 -0700 Subject: [PATCH 1/5] step1-write-spec: fan out parallel Explore subagents for multi-domain research Codebase research beyond the agents-context README can now dispatch up to 3 read-only Explore subagents in a single parallel batch (one per domain area) instead of a single agent. Co-Authored-By: Claude Fable 5 --- lead-dev-os/skills/step1-write-spec/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lead-dev-os/skills/step1-write-spec/SKILL.md b/lead-dev-os/skills/step1-write-spec/SKILL.md index 57cc111..a7ba588 100644 --- a/lead-dev-os/skills/step1-write-spec/SKILL.md +++ b/lead-dev-os/skills/step1-write-spec/SKILL.md @@ -47,7 +47,7 @@ Before asking questions, silently research available project context to inform y 3. **Concept-driven reusability scan** — The concept files you read describe existing patterns, conventions, and architectural decisions — and they reference source file paths. Use these to identify reusable code without blindly searching the entire codebase. Note any relevant concepts and the source paths they reference. -4. **If the scan must go beyond what the README indexes** (sparse concepts, or the feature touches undocumented territory), dispatch a read-only `Explore` subagent (fall back to `general-purpose`) with a bounded prompt — "find existing patterns, components, or modules related to [feature domain]; report paths and one-line descriptions, under 300 words" — instead of scanning the codebase in this conversation. Requirements gathering should keep the main context for the user's answers, not file dumps. +4. **If the scan must go beyond what the README indexes** (sparse concepts, or the feature touches undocumented territory), dispatch read-only `Explore` subagents (fall back to `general-purpose`) instead of scanning the codebase in this conversation — 1 for a single-domain feature, up to 3 in a single parallel batch when the feature spans areas (e.g. one for backend, one for frontend). Give each a bounded prompt: "find existing patterns, components, or modules related to [feature domain / area]; report paths and one-line descriptions, under 300 words". Requirements gathering should keep the main context for the user's answers, not file dumps. Use this context to ask smarter, more targeted questions in the next phase. Do NOT ask the user about things already documented in these files. From 2cc375db7f2fae470f89c55c12569979fb0799b3 Mon Sep 17 00:00:00 2001 From: Vel Lesikov Date: Fri, 14 Aug 2026 15:48:17 -0700 Subject: [PATCH 2/5] step2-scope-tasks: plan parallel execution with Execution Waves MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Research subagents now report file-contention hot spots, and grouping uses them: slices that fight over the same files get merged or an honest dependency instead of fake parallelism - tasks.md gains an Execution Waves subsection under Execution Order — waves of groups with no mutual dependencies and disjoint file sets that step3 can dispatch concurrently after validating against plans - Add a self-check phase before presenting tasks.md and a scope-boundary line (this skill produces tasks.md only, never code or plans) - Template and filled-in example updated to match Co-Authored-By: Claude Fable 5 --- lead-dev-os/skills/step2-scope-tasks/SKILL.md | 12 +++++++++--- .../examples/user-profile-feature.md | 11 +++++++++++ lead-dev-os/skills/step2-scope-tasks/template.md | 10 ++++++++++ 3 files changed, 30 insertions(+), 3 deletions(-) diff --git a/lead-dev-os/skills/step2-scope-tasks/SKILL.md b/lead-dev-os/skills/step2-scope-tasks/SKILL.md index 967c482..d10819b 100644 --- a/lead-dev-os/skills/step2-scope-tasks/SKILL.md +++ b/lead-dev-os/skills/step2-scope-tasks/SKILL.md @@ -16,6 +16,8 @@ You are a senior engineer breaking down a spec into implementable task groups. E Every task group MUST also stand on its own as a **complete user story** — a non-technical stakeholder who understands the feature's goal should be able to read the group and know (a) what value it delivers and (b) what "done" looks like, without reading any code or technical acceptance criteria. +This skill does not write code or implementation plans — it produces `tasks.md` only; execution and per-group planning belong to `/lead-dev-os:step3-implement-tasks`. + ### Phase 1: Load Context 1. **Find the spec folder.** Look for the most recent `lead-dev-os/specs/YYYY-MM-DD-*/` folder, or ask the user which spec to work from. @@ -38,6 +40,8 @@ Every task group MUST also stand on its own as a **complete user story** — a n - Shared utilities, helpers, or components to reuse instead of rebuilding - Anything that will constrain the task breakdown (migrations, feature flags, cross-cutting concerns) + - Contention hot spots: files that several parts of the feature will + all need to touch (these force sequential work) Do not propose a design — just report what exists. ``` @@ -54,7 +58,7 @@ Every task group MUST also stand on its own as a **complete user story** — a n 4. **Testing** — test review & gap analysis (always last) - **Layers.** Groups follow the stack: Database → API → Frontend → Testing. Choose this when the data model is the hard part, the feature lives in a single layer, or slices would all contend for the same few files. Trade-off: layer groups form a strict dependency chain — they always execute sequentially, and nothing is user-demoable until the top layer lands. -Whichever strategy you choose, keep each group's `Dependencies:` list minimal and honest — over-declared dependencies serialize execution for no reason. +Whichever strategy you choose, keep each group's `Dependencies:` list minimal and honest — over-declared dependencies serialize execution for no reason. Use the research reports' contention hot spots when carving groups: if two candidate slices would both rewrite the same few files, either merge them or declare the dependency, rather than pretending they're parallel. Each task group uses **hierarchical numbered subtasks**. The parent task (N.0) is the group's completion goal. Subtasks (N.1, N.2, ...) are the steps to achieve it. @@ -141,10 +145,12 @@ If a relevant concept or standard file does NOT yet exist, the directive should - Groups must have explicit **dependency ordering** - Context directives reference **general guidance, not code** — concept files describe approaches, conventions, and decision rationale, never code snippets - The **final group is always "Test Review & Gap Analysis"** — reviews previous tests, fills critical gaps (up to 10 additional tests), runs feature-specific tests, then runs the full test suite ONCE as a final backstop (fix new failures, report pre-existing ones) -- Include an **Execution Order** section at the end listing the recommended implementation sequence +- Include an **Execution Order** section at the end listing the recommended implementation sequence, with an **Execution Waves** subsection: waves of groups that can run in parallel during `/lead-dev-os:step3-implement-tasks`. Groups share a wave only when they have no dependency on each other (direct or transitive) AND their expected file sets are disjoint (per the research reports and contention hot spots). When every group depends on the previous one (e.g. layers), say so — one group per wave is an honest answer - Include an **Overview** section at the top with total task count -### Phase 4: Review & Save +### Phase 4: Self-check, Review & Save + +Before presenting the result, verify `tasks.md` against the Rules for Task Groups above — every group has description, User Story, Done-when block, context directives, honest Dependencies, test-first subtasks, and Acceptance Criteria; the final group is Test Review & Gap Analysis; Overview records the grouping strategy; Execution Order includes the Execution Waves subsection. Fix any gap before showing the file. Display the following message to the user: diff --git a/lead-dev-os/skills/step2-scope-tasks/examples/user-profile-feature.md b/lead-dev-os/skills/step2-scope-tasks/examples/user-profile-feature.md index c822a96..32f22b3 100644 --- a/lead-dev-os/skills/step2-scope-tasks/examples/user-profile-feature.md +++ b/lead-dev-os/skills/step2-scope-tasks/examples/user-profile-feature.md @@ -242,3 +242,14 @@ Recommended implementation sequence: 2. File Upload Layer (Task Group 2) 3. Frontend Components (Task Group 3) 4. Test Review & Gap Analysis (Task Group 4) + +### Execution Waves + +Groups in the same wave have no mutual dependencies and disjoint expected file sets — `/lead-dev-os:step3-implement-tasks` may run them in parallel after validating against the actual plans: + +- Wave 1: Task Group 1 +- Wave 2: Task Group 2 — depends on Group 1's model changes +- Wave 3: Task Group 3 — depends on Group 2's upload endpoint (avatar UI) +- Wave 4: Task Group 4 (Test Review & Gap Analysis — always last, always alone) + +The groups form a strict dependency chain, so each wave holds a single group — no parallel execution is available for this feature. diff --git a/lead-dev-os/skills/step2-scope-tasks/template.md b/lead-dev-os/skills/step2-scope-tasks/template.md index 296a652..e81e123 100644 --- a/lead-dev-os/skills/step2-scope-tasks/template.md +++ b/lead-dev-os/skills/step2-scope-tasks/template.md @@ -213,3 +213,13 @@ Recommended implementation sequence: 2. [Group Theme] (Task Group 2) 3. [Group Theme] (Task Group 3) 4. Test Review & Gap Analysis (Task Group 4) + +### Execution Waves + +Groups in the same wave have no mutual dependencies and disjoint expected file sets — `/lead-dev-os:step3-implement-tasks` may run them in parallel after validating against the actual plans: + +- Wave 1: Task Group 1 +- Wave 2: Task Group 2, Task Group 3 — [why they're independent, e.g. "no shared files: Group 2 touches API only, Group 3 touches UI only"] +- Wave 3: Task Group 4 (Test Review & Gap Analysis — always last, always alone) + +[If groups form a strict chain (e.g. layers strategy), list one group per wave and say so.] From 8e6ba5e7f916bf04e6de73fb35a3b1320ac6ed58 Mon Sep 17 00:00:00 2001 From: Vel Lesikov Date: Fri, 14 Aug 2026 15:48:26 -0700 Subject: [PATCH 3/5] step3-implement-tasks: verification agents + structured restructure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restructure the 273-line SKILL.md into an orchestrator (48 lines) with steps/ and shared/ files — order lives only in SKILL.md; step files are topic-named and position-agnostic. plans/group-N.md gets a real template.md instead of prose inside a prompt. New verification agents, running in every mode: - implementation-reviewer + test-verifier: a parallel read-only pair checking each group before commit (diff vs. plan/spec/standards; tests meaningful, edge cases covered, nothing weakened). Orchestrated execution drives a bounded fix cycle (max 2 rounds); L mode surfaces findings at the user's review gate - adversarial-thinker: challenges the plan batch before code is written and attacks the finished feature before delivery; only findings with a concrete failure scenario count Parallel execution is now scheduled, not ad hoc: pre-planning validates step2's Execution Waves against the plans' file operations and dispatches executors wave-by-wave. Tests: step3 content assertions became directory-recursive; 15 new assertions cover the structured shape, the agents, read-only and bounded-fix-cycle constraints, and waves. Co-Authored-By: Claude Fable 5 --- .../skills/step3-implement-tasks/SKILL.md | 271 ++---------------- .../shared/adversarial-agent.md | 74 +++++ .../shared/verification-agents.md | 97 +++++++ .../steps/execute-direct.md | 77 +++++ .../steps/execute-orchestrated.md | 73 +++++ .../step3-implement-tasks/steps/finalize.md | 17 ++ .../steps/load-context.md | 12 + .../step3-implement-tasks/steps/pre-plan.md | 69 +++++ .../steps/select-mode.md | 19 ++ .../skills/step3-implement-tasks/template.md | 37 +++ tests/test_content_bundle.sh | 4 +- tests/test_skill_content.sh | 80 +++++- 12 files changed, 576 insertions(+), 254 deletions(-) create mode 100644 lead-dev-os/skills/step3-implement-tasks/shared/adversarial-agent.md create mode 100644 lead-dev-os/skills/step3-implement-tasks/shared/verification-agents.md create mode 100644 lead-dev-os/skills/step3-implement-tasks/steps/execute-direct.md create mode 100644 lead-dev-os/skills/step3-implement-tasks/steps/execute-orchestrated.md create mode 100644 lead-dev-os/skills/step3-implement-tasks/steps/finalize.md create mode 100644 lead-dev-os/skills/step3-implement-tasks/steps/load-context.md create mode 100644 lead-dev-os/skills/step3-implement-tasks/steps/pre-plan.md create mode 100644 lead-dev-os/skills/step3-implement-tasks/steps/select-mode.md create mode 100644 lead-dev-os/skills/step3-implement-tasks/template.md diff --git a/lead-dev-os/skills/step3-implement-tasks/SKILL.md b/lead-dev-os/skills/step3-implement-tasks/SKILL.md index b0b4779..2623d52 100644 --- a/lead-dev-os/skills/step3-implement-tasks/SKILL.md +++ b/lead-dev-os/skills/step3-implement-tasks/SKILL.md @@ -1,6 +1,6 @@ --- name: step3-implement-tasks -description: Implement tasks from a scoped task breakdown. +description: Implement tasks from a scoped task breakdown — parallel executor subagents, per-group verification agents, and adversarial review before delivery. disable-model-invocation: true --- @@ -8,266 +8,41 @@ disable-model-invocation: true Execute task groups from a scoped task breakdown. Three modes — Autonomous, Lead-in-the-Loop, Hybrid — trade off speed vs. review. -**Use plan mode per task group when implementing.** The exact mechanism varies by mode: A and H produce all task-group plans up front via parallel subagents (Phase 3); L uses Claude Code's native plan mode at the start of each group (Phase 4b). Either way, every group is planned before its code is written. +You are a senior engineer implementing a feature from a scoped task breakdown, acting as the **orchestrator** of a small team of subagents: planners, executors, an implementation-reviewer, a test-verifier, and an adversarial-thinker. Work through task groups in dependency order, loading relevant context before each group and updating context when new patterns emerge. Every group is planned before its code is written — A and H modes pre-generate `plans/group-N.md` files via parallel planner subagents; L mode uses Claude Code's native plan mode at the start of each group. Every group is independently verified before it is committed. -## Instructions +This skill does not write or change specs or task breakdowns — requirements belong to `/lead-dev-os:step1-write-spec` and scoping to `/lead-dev-os:step2-scope-tasks`; when implementation reveals a gap in either, surface it instead of silently expanding scope. -You are a senior engineer implementing a feature from a scoped task breakdown. Work through task groups in dependency order, loading relevant context before each group, and updating context when new patterns emerge. +## Process -### Phase 1: Load Spec Context +Work through these steps in order. Read each step file when you reach it, not before. -1. **Find the spec folder.** Look for the most recent `lead-dev-os/specs/YYYY-MM-DD-*/` directory, or ask the user which spec to implement. +1. **Load spec context** — [steps/load-context.md](steps/load-context.md): find the spec folder; read `tasks.md`, `spec.md`, and requirements; identify incomplete groups. +2. **Select execution mode** — [steps/select-mode.md](steps/select-mode.md): recommend A / L / H from the spec's size estimate; the user decides. +3. **Pre-execution planning** (modes A and H only; L plans per group during execution) — [steps/pre-plan.md](steps/pre-plan.md): parallel planner subagents write `plans/group-N.md` for every incomplete group, the adversarial-thinker challenges the plan batch, and an execution schedule of parallel waves is derived for user approval. +4. **Execute task groups** — two paths, chosen by mode: + - **Orchestrated** (A, and H before the checkpoint) — [steps/execute-orchestrated.md](steps/execute-orchestrated.md): a fresh executor subagent per group, independent groups dispatched in parallel waves, each group verified before commit. + - **Direct** (L, and H at/after the checkpoint) — [steps/execute-direct.md](steps/execute-direct.md): plan and execute each group in the main conversation; verification findings feed the user's review gate. +5. **Finalize** — [steps/finalize.md](steps/finalize.md): adversarial delivery review, the single full-test-suite backstop run, runtime verification, acceptance-criteria check, summary, archive handoff. -2. **Read these files in order:** - - `tasks.md` — the task breakdown (your work plan) - - `spec.md` — the specification (your requirements) - - `planning/requirements.md` — original requirements and Q&A context (if present) +Shared procedures used by more than one step: -3. **Identify the next incomplete task group** (first group with unchecked tasks). +- [shared/verification-agents.md](shared/verification-agents.md) — the per-group verification pair (implementation-reviewer + test-verifier) and its bounded fix cycle. Read it the first time a group finishes executing. +- [shared/adversarial-agent.md](shared/adversarial-agent.md) — the adversarial-thinker's two prompts (plan challenge, delivery challenge) and how to triage its findings. Read it from the pre-planning and finalize steps. +- [template.md](template.md) — the format of a `plans/group-N.md` file. Planner subagents and L-mode plans both follow it. -### Phase 2: Select Execution Mode +## Hard rules (all modes, all steps) -Read the `> Size:` line from `spec.md` (written by `/lead-dev-os:step1-write-spec`) and derive a recommendation: **Small → A**, **Medium → H**, **Large → L**. If the line is absent, make your own quick size assessment from `tasks.md` (group count, integration points) and say so. +- **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. -Present the three modes with your recommendation first, and ask which to use — the user decides. +## Error handling -| Mode | Behavior | Best for | -|------|----------|----------| -| **A — Autonomous** | Pre-plan all groups in parallel → user approves batch → each group is executed by a fresh executor subagent; the orchestrator verifies and commits per group. Independent groups may run in parallel. No pauses during execution. | Small features, well-understood domains, low risk. | -| **L — Lead-in-the-Loop** | Per-group cycle in the main conversation: plan (native plan mode) → user approves → execute → review gate → repeat. | Complex features, new domains, high visibility. | -| **H — Hybrid** | Pre-plan all groups in parallel → user approves batch → orchestrated executor-subagent execution up to the checkpoint → at and after the checkpoint, switch to L behavior. | Boilerplate setup followed by tricky logic. | - -Ask **"Which execution mode?"** using the `AskUserQuestion` tool when available (options A / L / H with one-line descriptions, the recommended mode listed first and labeled "(Recommended)"); fall back to a plain-text question otherwise. - -If the user picks **H**, also ask: **"Which group is the checkpoint?"** — again via `AskUserQuestion`, offering the task groups as options. Autonomous execution runs up to but not including that group; L behavior begins at that group. - -Store the mode (and checkpoint) for the rest of the session. - -### Phase 3: Pre-execution Planning (A and H only) - -Skip this phase for L mode — L plans per group during execution (Phase 4b). - -The goal: produce a `plans/group-N.md` file for every incomplete task group before any code is written, so the user can review and edit the whole execution upfront in one batch instead of group-by-group. - -**Check for existing plans first.** If `lead-dev-os/specs//plans/` already contains files, ask the user whether to reuse, regenerate, or amend them. Don't silently overwrite plans the user may have edited. - -**Spawn one planner subagent per incomplete task group, in parallel.** Issue all subagent calls in a single tool-call batch so they run concurrently. Use `subagent_type: "general-purpose"` and give each a self-contained prompt of roughly this shape: - -``` -You are planning Task Group from /tasks.md. - -Read these files first (and only these — don't broadly scan the codebase): -- /tasks.md (focus on Group N's section) -- /spec.md -- agents-context/README.md, then load only the concept/standard files Group N's - "Read before starting" header names -- Each file Group N will modify or extend, so you know the starting state - -Write /plans/group-.md with these sections: - -1. Goal — one paragraph: what shipping this group accomplishes. -2. Sub-tasks — an ordered, atomic list. Each sub-task should be small enough - to be a coherent commit on its own. Mark which sub-tasks merit their own - commit vs. rolling into the group commit. -3. File operations — every file you'll create, modify, or delete, with a - one-line rationale per file. -4. Test approach — which test files, how many tests, what they cover, and - the patterns you'll follow from the project's test standards. -5. Verification — the exact command(s) to run this group's tests - (per the group's "Ensure tests pass" sub-task). -6. Risks — anything that could cause the group to fail or need spec - clarification before execution. If you spot a missing dependency on - another group or a gap in the spec, flag it here rather than expanding - scope. - -Constraints: -- Do NOT write code or modify any file outside /plans/. -- Stay within the scope of Group N as defined in tasks.md. -- The plan will be read cold by an executor agent; be specific about file - paths and exact patterns to follow. -``` - -When all planner subagents return, report: - -> All plans are ready in `lead-dev-os/specs//plans/`. Review and edit the files as needed. Reply **"go"** when ready to execute. -> -> - `plans/group-1.md` — -> - `plans/group-2.md` — -> - … - -Wait for explicit "go" before proceeding to Phase 4. Do not start executing on your own initiative. - -### Phase 4: Execute Task Groups - -There are two execution paths: - -- **Orchestrated — A mode, and H before the checkpoint.** The main conversation acts as an orchestrator: each group is executed by a fresh executor subagent, then the orchestrator verifies and commits. This keeps the main context small regardless of how many groups the feature has — group 6 gets the same quality of attention as group 1. Follow **4-O**. -- **Direct — L mode, and H at/after the checkpoint.** The main conversation executes the group itself so the user can watch and steer. Follow **4a–4g**. - -#### 4-O. Orchestrated execution (A, and H pre-checkpoint) - -Work through incomplete groups in dependency order: - -1. **Dispatch an executor subagent per group** (`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. - -2. **Parallel dispatch (optional).** Two or more groups may be dispatched in the same batch only when BOTH hold: (a) neither depends on the other, directly or transitively, per the `Dependencies:` headers, and (b) their plans' "File operations" lists don't overlap. When in doubt, dispatch sequentially — a serialized group is cheaper than a merge conflict. - -3. **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. - -4. **Review the diff** briefly for scope creep, deleted tests, or weakened assertions. - -5. **Commit.** Executors never commit — the orchestrator commits after verifying, per 4f. 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. - -6. **Report and continue** (A-mode gate): - - Group N complete - - Tests written / passing - - Concept files created or updated - - Next group(s) queued - Then dispatch the next group(s). In H mode, when the checkpoint group is reached, switch to the direct path (4a–4g) with L behavior. - -If an executor reports a blocker, plan-invalidating drift, or exhausted retries, stop and apply the Error Handling section — surface it to the user; don't redispatch blindly. - -**Executor prompt template:** - -``` -You are executing Task Group of /tasks.md as part of -/lead-dev-os:step3-implement-tasks. - -Read first, in this order: -- /plans/group-.md — your working plan -- /tasks.md — Group N's section (subtasks + acceptance criteria) -- agents-context/README.md, then every file Group N's "Read before - starting" header names -- Every file the plan's "File operations" section says you'll modify - -Reconcile before you code: earlier groups may have changed the code since -this plan was written. If reality has drifted (files moved, signatures -changed, patterns replaced), update plans/group-.md to match reality -first and note the drift in your final report. If the drift invalidates -the group's goal, stop and report instead of improvising. - -Then execute the group: -1. Tests first — write the group's tests before implementation; they - should fail before the code that satisfies them exists. -2. Implement to make them pass, following the conventions from the loaded - context files. Stay within Group N's scope — no scope creep. -3. Verify with the plan's verification command. Run ONLY this group's - tests, not the entire suite. -4. If a test fails: diagnose, fix the most likely cause, re-run. Retry - limit: 2 attempts. Never delete tests, weaken assertions, or skip - behavior to get green — report the failure instead. -5. Check off completed tasks in tasks.md as each one finishes, not in a - batch at the end. -6. Update context: create or update the concept files named in the - group's "Update after completing" header; keep agents-context/README.md - in sync (index entry, Load-When Cheatsheet, cross-references). - -Do NOT commit — the orchestrator commits after verifying your work. - -Final report (structured): -- Tests written / passing (counts and file paths) -- Files created / modified / deleted -- Concept files created or updated -- Plan drift found and how the plan was amended (if any) -- Blockers or open questions (if any) -``` - -#### Direct execution (L, and H at/after checkpoint) - -For each incomplete task group, in dependency order, run the 4a–4g sub-cycle in the main conversation. - -#### 4a. Load Context - -1. **Read every file listed in the group's `Read before starting:` header.** These supply project-specific guidance — concept files and standards. Don't skip. -2. **Read every file the group will modify or extend** (named in the plan's "File operations" section, or in the group's `Modifies:` header if present). Understand the starting state before changing it. -3. **Verify dependencies.** If this group depends on earlier groups, confirm those groups' tasks are checked off and their tests pass. - -#### 4b. Plan - -- **H mode (at/after the checkpoint):** read `plans/group-.md`. Treat it as the working plan. The user approved the batch in Phase 3, but they may also have edited the file — read it fresh. If earlier groups changed the code in ways the plan didn't anticipate, update the plan file to match reality before executing, and tell the user what drifted. -- **L mode:** enter Claude Code's native plan mode and produce a plan with the same structure as Phase 3 (Goal, Sub-tasks, File ops, Test approach, Verification, Risks). In the plan header, include this identifier so the agent stays aware of its workflow context after `ExitPlanMode` clears the conversation: "Running as part of `/lead-dev-os:step3-implement-tasks` for `/tasks.md`, task group N. Final step: return to tasks.md and check off completed tasks." Wait for the user to approve via `ExitPlanMode` before continuing. - -#### 4c. Execute - -Work through each task in the group sequentially: - -1. **Tests first.** Write tests before implementation. Tests should cover the specific behavior described in the task, follow the project's test patterns, and be runnable and failing before you write the code that satisfies them. - -2. **Implementation.** Write code to make the tests pass. Follow the conventions from the concept and standard files loaded in 4a. Reuse patterns identified in the spec. Stay within the task's scope — no scope creep. - -3. **Verify.** Run only this group's tests, using the verification command in the plan. Do not run the entire test suite at this stage — slow feedback loops cost more than they save here. - -4. **Mark tasks complete** by checking them off in `tasks.md` as soon as each task is done, not in a batch at the end. This protects progress if the session is interrupted. - -#### 4d. Self-fix on Test Failure - -If a test fails: - -1. Inspect the failure. Determine whether the issue is in the test, the implementation, or an assumption about the surrounding code. -2. Fix the most likely cause and re-run the group's tests. -3. **Retry limit: 2 attempts.** After two unsuccessful fixes, stop and report: - - The failing test name and message - - What you tried in each retry - - Your hypothesis on the root cause - - Whether the blocker likely sits in the spec, the existing code, or the new code - -Do not loop indefinitely, and do not "fix" by deleting tests, weakening assertions, or skipping behavior. The user would rather debug a stuck group with you than inherit a feature whose tests were silently disabled. - -#### 4e. Update Context - -After the group's tests pass: - -1. **Read `agents-context/README.md`** to see what concepts already exist. -2. **Create or update concept files** when the group's `Update after completing:` header calls for it, OR when implementation revealed a pattern future features will need to understand. -3. **Concept files capture general guidance, not code.** Describe approach, conventions, decision rationale, and file paths — not code snippets, not file-by-file documentation. -4. **Keep `agents-context/README.md` in sync.** When you create or update a concept file, add or update its entry under Core/Domain Concepts, refresh the "For AI Agents" task-to-concept mapping, and update cross-references in related concept entries. The README is the entry point — if it's stale, future agents won't find the concept. - -#### 4f. Commit - -Atomic-commit policy: - -- **Default: one commit per task group.** The commit message describes what the group shipped (not how) and references the spec folder name. -- **Optional sub-commits:** if a group has natural sub-units (e.g. a "primitives" sub-task that lands cleanly on its own, then "integration" on top), commit each sub-unit separately. Use judgment — if you can't summarize a sub-commit in one clean line, it isn't ready as its own commit. -- **Don't sweep up unrelated changes.** If the user has uncommitted edits in files outside this group's scope, ask before staging anything. - -In **L** mode you may skip the auto-commit and let the user commit manually after the review gate (4g). - -#### 4g. Review Gate - -After the group is complete (this gate applies to the direct path — L mode, and H at/after the checkpoint; A mode's gate is 4-O step 6): - -1. Report: - - Group N complete - - Tests written / passing - - Concept files created or updated - - Diff overview -2. Stop and present the review gate: - > **Review gate — Task Group N complete.** - > Changes ready for review. - > - 🔍 Review the diff in your git GUI (GitLens, GitHub Desktop, `lazygit`, `git diff`) - > - ✏️ Request changes — tell me what to modify - > - ✅ Say "commit" and I'll create a descriptive commit, or commit yourself - > - ➡️ Say "continue" to proceed to the next group -3. Wait for explicit instruction. Do not advance until the user says to continue. - -#### After all groups complete - -Regardless of mode: -- **Run the full test suite once** (if the final task group's backstop subtask didn't already). This is the only full-suite run in the workflow. Triage failures: fix NEW failures this feature caused; report pre-existing failures without fixing them. -- **Verify at runtime.** Tests passing is not the same as the feature working — exercise the feature's primary user flow in the running app where feasible (start the app, hit the endpoint, click through the UI) and confirm the observable behavior matches the spec's acceptance criteria. If runtime verification isn't feasible, say so explicitly rather than skipping silently. -- Confirm every "Acceptance Criteria" block in `tasks.md` is satisfied. -- List concept files created or updated during execution. -- Summarize what was built. -- Suggest `/lead-dev-os:step4-archive-spec` to archive the spec. - -### Error Handling (general) - -If you hit a blocker that the 2-retry loop in 4d can't resolve, or that doesn't surface as a test failure: +If you hit a blocker the bounded retries can't resolve, or one that doesn't surface as a test failure: 1. Do not skip the task or work around it silently. 2. Tell the user what's blocking you and why. 3. If the blocker exposes a gap in the spec, name the gap. 4. If the blocker exposes a gap in context, name the concept file that should be created. 5. Ask how to proceed before continuing. - -Avoid destructive shortcuts: don't delete test cases, weaken assertions, skip migrations, or use `--no-verify`. The right answer is almost always to surface the problem to the user. diff --git a/lead-dev-os/skills/step3-implement-tasks/shared/adversarial-agent.md b/lead-dev-os/skills/step3-implement-tasks/shared/adversarial-agent.md new file mode 100644 index 0000000..106ef22 --- /dev/null +++ b/lead-dev-os/skills/step3-implement-tasks/shared/adversarial-agent.md @@ -0,0 +1,74 @@ +# Adversarial-thinker + +A read-only agent whose whole job is to attack assumptions — it runs twice in the workflow: once against the **plans** (before any code exists, where problems are cheapest to fix) and once against the **finished feature** (before delivery). Prefer a read-only agent type (`Explore`) when available; fall back to `general-purpose` (the prompts forbid writes either way). + +## Plan-challenge prompt + +Dispatch after all planner subagents have returned, before the user approves the batch. + +``` +You are an adversarial reviewer challenging the implementation plans for + BEFORE any code is written. You are READ-ONLY: never modify, +create, or delete any file. + +Read: /spec.md, /tasks.md, and every file in +/plans/. + +Hunt for what the planners assumed instead of established: +- Inputs — empty, oversized, malformed, duplicate, concurrent. Which plan + handles them; which silently doesn't? +- Failure modes — partial failure mid-group, rollback of a migration, + an external service down, a retried operation running twice. +- Seams between groups — contracts two plans define differently, data one + group produces in a shape another doesn't expect. +- Security — authorization gaps, injection surfaces, data exposure. + Flag the risk and the entry point; do not write exploit code. +- Sequencing — dependencies the Dependencies headers miss; two plans + touching the same file despite being scheduled as parallel. + +Report only findings with a concrete scenario ("if X then Y breaks") — +no generic concerns. For each finding: +- Severity (high / medium / low) +- Which group(s)/plan(s) it affects +- The concrete scenario +- The cheapest fix point: amend a plan | add a test to a group's test + approach | question the user must answer (spec gap) +``` + +## Delivery-challenge prompt + +Dispatch after all task groups are complete, before the full-suite backstop run. + +``` +You are an adversarial reviewer trying to break the feature built from + before it is delivered. You are READ-ONLY: never modify, +create, or delete any file (running commands to reproduce a failure is +allowed). + +Read: /spec.md, /tasks.md, the feature's commits +(git log --oneline ..HEAD and git diff ..HEAD), and the key +implemented files. + +Try to break it: +- Concrete failure scenarios — exact input or state that produces a wrong + outcome, a crash, or data loss. Reproduce where feasible. +- Edge cases the tests don't cover — boundaries, empty states, unicode, + concurrency, permissions. +- Regressions — adjacent behavior the feature plausibly changed. +- Spec betrayals — acceptance criteria that pass the letter but not the + intent. + +Report only findings with a concrete failure scenario — no vague unease. + +Final report (structured): +- Verdict: SHIP or FINDINGS +- Findings ranked by severity, each with: the scenario, whether you + reproduced it, affected files, and whether it is in-scope for this + spec or pre-existing behavior +``` + +## Triaging its findings + +- **Plan challenge:** apply clear plan-level fixes by amending the affected `plans/group-N.md` files (add the failure mode to Risks, the scenario to the Test approach, or the missing dependency to the schedule). Spec-level questions go to the user with the plan-approval report — never answer a spec gap by inventing requirements. +- **Delivery challenge:** fix confirmed defects that are in-scope for the spec (bounded: max 2 fix rounds, then surface). Report — do not fix — pre-existing behavior and out-of-scope findings; name them explicitly in the final summary so the user can decide. +- In every mode the findings reach the user: orchestrated execution folds them into its reports; direct execution surfaces them at the review gate or final summary. 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 new file mode 100644 index 0000000..bb81829 --- /dev/null +++ b/lead-dev-os/skills/step3-implement-tasks/shared/verification-agents.md @@ -0,0 +1,97 @@ +# Verification pair: implementation-reviewer + test-verifier + +Run this procedure when a task group's implementation is complete and its tests pass, before the group is committed. Both agents are **read-only** — they never modify files. The executor must not grade its own homework; these agents start fresh and judge only what's on disk. + +## Dispatch + +Dispatch both agents **in parallel, in a single tool-call batch**. Prefer a read-only agent type (`Explore`) when available; fall back to `general-purpose` (the prompts forbid writes either way). Because other groups may be executing concurrently in the same wave, both prompts scope their review to **Group N's file list** (the plan's "File operations" section) — never to the whole working tree. + +### implementation-reviewer prompt + +``` +You are the implementation-reviewer for Task Group of +/tasks.md — implemented but not yet committed. You are +READ-ONLY: never modify, create, or delete any file. + +Read first: +- /plans/group-.md — the working plan (if present) +- /tasks.md — Group N's section (subtasks + acceptance criteria) +- /spec.md — the requirements this group serves +- agents-context/README.md, then the standard/concept files Group N's + "Read before starting" header names +- The group's uncommitted changes, scoped to its files: + git diff HEAD -- (plus git status for new files) + +Review the implementation against the plan, the spec, and the loaded +standards: +- Acceptance criteria — does the diff actually satisfy Group N's criteria? +- Completeness — is every entry in the plan's "File operations" accounted for? +- Scope — any changes beyond Group N's scope? +- Conventions — violations of the loaded standards or the patterns the plan + named as exemplars? +- 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? + +Do not report style nitpicks that no loaded standards file backs. + +Final report (structured): +- Verdict: APPROVE or REQUEST_CHANGES +- Blocking findings — file:line, what's wrong, and which criterion, + spec requirement, or standard it violates +- Advisory findings — worthwhile improvements that should not block commit +``` + +### test-verifier prompt + +``` +You are the test-verifier for Task Group of /tasks.md. +You are READ-ONLY: never modify, create, or delete any file (running the +test command is allowed). + +Read first: +- /tasks.md — Group N's section, especially its test subtasks +- /spec.md — requirements and edge cases the tests should cover +- /plans/group-.md — the "Test approach" section (if present) +- The project's test-writing standard via agents-context/README.md +- Group N's test files, and the implementation files they exercise + +Verify the tests are real: +- Meaningful assertions — each test would fail if the behavior it names + broke. Flag tautologies, assertions on mocks of the code under test, + and tests that can't fail. +- Coverage vs. intent — the critical behaviors and the edge cases the + spec calls out for this group (empty states, error paths, boundaries) + are covered within the group's 2-8 test budget. Name each uncovered + scenario concretely. +- No weakening — nothing skipped, deleted, or loosened relative to the + plan's test approach. +- Bloat — flag exhaustive-coverage creep beyond the budget too; this + workflow wants few, sharp tests. +- Execute the group's verification command from the plan and confirm the + pass/fail counts match what the tests claim. + +Final report (structured): +- Verdict: APPROVE or REQUEST_CHANGES +- Blocking findings — missing critical/edge coverage (with the exact + scenario), tautological or non-failing tests, weakened assertions +- Advisory findings — improvements that should not block commit +- Test run output summary (command, counts) +``` + +## Acting on the verdicts + +- **Both APPROVE** (advisory findings only): proceed. Include advisory findings in the group report — they are recorded, never silently dropped. +- **Any REQUEST_CHANGES:** + - **Orchestrated execution** — run the bounded fix cycle below. + - **Direct execution** — no automatic fix cycle: carry all findings into the review gate and let the user decide what gets addressed. + +## Bounded fix cycle (orchestrated execution) + +1. Dispatch a fresh executor subagent scoped to the findings: give it the standard executor context reads plus the verbatim blocking findings, with the instruction "Address these blocking findings only — no other changes. Do not commit." +2. Re-run the group's verification command yourself. +3. Re-dispatch **only the verifier(s) that requested changes**, noting what was fixed. +4. **Limit: 2 rounds.** If blocking findings remain after two rounds, stop and surface them to the user per the error-handling rules — do not commit, do not loop. + +A finding the fix cycle judges to be wrong (the verifier misread the spec) may be overridden — but say so explicitly in the group report with the reasoning, never silently. diff --git a/lead-dev-os/skills/step3-implement-tasks/steps/execute-direct.md b/lead-dev-os/skills/step3-implement-tasks/steps/execute-direct.md new file mode 100644 index 0000000..8dee547 --- /dev/null +++ b/lead-dev-os/skills/step3-implement-tasks/steps/execute-direct.md @@ -0,0 +1,77 @@ +# Direct execution + +*Applies to mode L, and mode H at/after the checkpoint.* + +The main conversation executes each group itself so the user can watch and steer. For each incomplete task group, in dependency order, run this sub-cycle: + +## a. Load group context + +1. **Read every file listed in the group's `Read before starting:` header.** These supply project-specific guidance — concept files and standards. Don't skip. +2. **Read every file the group will modify or extend** (named in the plan's "File operations" section, or in the group's `Modifies:` header if present). Understand the starting state before changing it. +3. **Verify dependencies.** If this group depends on earlier groups, confirm those groups' tasks are checked off and their tests pass. + +## b. Plan + +- **H mode (at/after the checkpoint):** read `plans/group-.md`. Treat it as the working plan. The user approved the batch, but they may also have edited the file — read it fresh. If earlier groups changed the code in ways the plan didn't anticipate, update the plan file to match reality before executing, and tell the user what drifted. +- **L mode:** enter Claude Code's native plan mode and produce a plan following [../template.md](../template.md) (Goal, Sub-tasks, File operations, Test approach, Verification, Risks). In the plan header, include this identifier so the agent stays aware of its workflow context after `ExitPlanMode` clears the conversation: "Running as part of `/lead-dev-os:step3-implement-tasks` for `/tasks.md`, task group N. Final step: return to tasks.md and check off completed tasks." Wait for the user to approve via `ExitPlanMode` before continuing. + +## c. Execute + +Work through each task in the group sequentially: + +1. **Tests first.** Write tests before implementation. Tests should cover the specific behavior described in the task, follow the project's test patterns, and be runnable and failing before you write the code that satisfies them. +2. **Implementation.** Write code to make the tests pass. Follow the conventions from the concept and standard files loaded above. Reuse patterns identified in the spec. Stay within the task's scope — no scope creep. +3. **Verify.** Run only this group's tests, using the verification command in the plan. Do not run the entire test suite at this stage — slow feedback loops cost more than they save here. +4. **Mark tasks complete** by checking them off in `tasks.md` as soon as each task is done, not in a batch at the end. + +## d. Self-fix on test failure + +If a test fails: + +1. Inspect the failure. Determine whether the issue is in the test, the implementation, or an assumption about the surrounding code. +2. Fix the most likely cause and re-run the group's tests. +3. **Retry limit: 2 attempts.** After two unsuccessful fixes, stop and report: + - The failing test name and message + - What you tried in each retry + - Your hypothesis on the root cause + - Whether the blocker likely sits in the spec, the existing code, or the new code + +Do not loop indefinitely, and do not "fix" by deleting tests, weakening assertions, or skipping behavior. + +## e. Verification pair + +Once the group's tests pass, dispatch the implementation-reviewer and test-verifier in parallel per [../shared/verification-agents.md](../shared/verification-agents.md). In direct execution the orchestrator does NOT auto-run a fix cycle — collect the verdicts and findings and carry them into the review gate below, where the user decides what gets fixed. Fix what the user asks for in the main conversation, then re-run the group's tests. + +## f. Update context + +1. **Read `agents-context/README.md`** to see what concepts already exist. +2. **Create or update concept files** when the group's `Update after completing:` header calls for it, OR when implementation revealed a pattern future features will need to understand. +3. **Concept files capture general guidance, not code.** Describe approach, conventions, decision rationale, and file paths — not code snippets, not file-by-file documentation. +4. **Keep `agents-context/README.md` in sync.** When you create or update a concept file, add or update its entry under Core/Domain Concepts, refresh the "For AI Agents" task-to-concept mapping, and update cross-references in related concept entries. The README is the entry point — if it's stale, future agents won't find the concept. + +## g. Commit + +Atomic-commit policy: + +- **Default: one commit per task group.** The commit message describes what the group shipped (not how) and references the spec folder name. +- **Optional sub-commits:** if a group has natural sub-units (e.g. a "primitives" sub-task that lands cleanly on its own, then "integration" on top), commit each sub-unit separately. Use judgment — if you can't summarize a sub-commit in one clean line, it isn't ready as its own commit. +- **Don't sweep up unrelated changes.** If the user has uncommitted edits in files outside this group's scope, ask before staging anything. + +In **L** mode you may skip the auto-commit and let the user commit manually after the review gate. + +## h. Review gate + +1. Report: + - Group N complete + - Tests written / passing + - Verification verdicts (reviewer, test-verifier) with their findings — blocking first, then advisory + - Concept files created or updated + - Diff overview +2. Stop and present the review gate: + > **Review gate — Task Group N complete.** + > Changes ready for review. Verification findings above. + > - 🔍 Review the diff in your git GUI (GitLens, GitHub Desktop, `lazygit`, `git diff`) + > - ✏️ Request changes — tell me what to modify (including any verification findings you want addressed) + > - ✅ Say "commit" and I'll create a descriptive commit, or commit yourself + > - ➡️ Say "continue" to proceed to the next group +3. Wait for explicit instruction. Do not advance until the user says to continue. 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 new file mode 100644 index 0000000..97f7731 --- /dev/null +++ b/lead-dev-os/skills/step3-implement-tasks/steps/execute-orchestrated.md @@ -0,0 +1,73 @@ +# Orchestrated execution + +*Applies to mode A, and mode H before the checkpoint.* + +The main conversation acts as an orchestrator: each group is executed by a fresh executor subagent, verified by the verification pair, then committed by the orchestrator. This keeps the main context small regardless of how many groups the feature has — group 6 gets the same quality of attention as group 1. + +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. + +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. + +3. **Dispatch the verification pair** — implementation-reviewer and test-verifier in parallel, per [../shared/verification-agents.md](../shared/verification-agents.md). On blocking findings, run that file's bounded fix cycle (redispatch an executor scoped to the findings; max 2 rounds). Advisory findings go into the group report. + +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. + +6. **Report and continue:** + - Group N complete + - Tests written / passing + - Verification verdicts (reviewer, test-verifier) + advisory findings + - Concept files created or updated + - Next wave queued + + Then dispatch the next wave. In H mode, when the checkpoint group is reached, switch to direct execution with L behavior. + +If an executor reports a blocker, plan-invalidating drift, or exhausted retries, stop and apply the error-handling rules — surface it to the user; don't redispatch blindly. + +## Executor prompt template + +``` +You are executing Task Group of /tasks.md as part of +/lead-dev-os:step3-implement-tasks. + +Read first, in this order: +- /plans/group-.md — your working plan +- /tasks.md — Group N's section (subtasks + acceptance criteria) +- agents-context/README.md, then every file Group N's "Read before + starting" header names +- Every file the plan's "File operations" section says you'll modify + +Reconcile before you code: earlier groups may have changed the code since +this plan was written. If reality has drifted (files moved, signatures +changed, patterns replaced), update plans/group-.md to match reality +first and note the drift in your final report. If the drift invalidates +the group's goal, stop and report instead of improvising. + +Then execute the group: +1. Tests first — write the group's tests before implementation; they + should fail before the code that satisfies them exists. +2. Implement to make them pass, following the conventions from the loaded + context files. Stay within Group N's scope — no scope creep. +3. Verify with the plan's verification command. Run ONLY this group's + tests, not the entire suite. +4. If a test fails: diagnose, fix the most likely cause, re-run. Retry + limit: 2 attempts. Never delete tests, weaken assertions, or skip + behavior to get green — report the failure instead. +5. Check off completed tasks in tasks.md as each one finishes, not in a + batch at the end. +6. Update context: create or update the concept files named in the + group's "Update after completing" header; keep agents-context/README.md + in sync (index entry, Load-When Cheatsheet, cross-references). + +Do NOT commit — the orchestrator commits after verifying your work. + +Final report (structured): +- Tests written / passing (counts and file paths) +- Files created / modified / deleted +- Concept files created or updated +- Plan drift found and how the plan was amended (if any) +- Blockers or open questions (if any) +``` diff --git a/lead-dev-os/skills/step3-implement-tasks/steps/finalize.md b/lead-dev-os/skills/step3-implement-tasks/steps/finalize.md new file mode 100644 index 0000000..22cea59 --- /dev/null +++ b/lead-dev-os/skills/step3-implement-tasks/steps/finalize.md @@ -0,0 +1,17 @@ +# Finalize + +Run after all task groups are complete, regardless of mode. + +1. **Adversarial delivery review.** Dispatch the **adversarial-thinker** with the delivery-challenge prompt from [../shared/adversarial-agent.md](../shared/adversarial-agent.md) — a fresh, read-only agent that tries to break the finished feature against the spec. Triage per that file's guidance: fix confirmed, in-scope defects (bounded — max 2 fix rounds, then surface); report the rest to the user with the summary. Run this before the full-suite backstop so any fixes are covered by it. + +2. **Run the full test suite once** (if the final task group's backstop subtask didn't already). This is the only full-suite run in the workflow. Triage failures: fix NEW failures this feature caused; report pre-existing failures without fixing them. + +3. **Verify at runtime.** Tests passing is not the same as the feature working — exercise the feature's primary user flow in the running app where feasible (start the app, hit the endpoint, click through the UI) and confirm the observable behavior matches the spec's acceptance criteria. If runtime verification isn't feasible, say so explicitly rather than skipping silently. + +4. **Confirm every "Acceptance Criteria" block in `tasks.md` is satisfied.** + +5. **Summarize:** + - What was built + - Adversarial findings — fixed vs. reported + - Concept files created or updated during execution + - Suggest `/lead-dev-os:step4-archive-spec` to archive the spec diff --git a/lead-dev-os/skills/step3-implement-tasks/steps/load-context.md b/lead-dev-os/skills/step3-implement-tasks/steps/load-context.md new file mode 100644 index 0000000..b97779f --- /dev/null +++ b/lead-dev-os/skills/step3-implement-tasks/steps/load-context.md @@ -0,0 +1,12 @@ +# Load spec context + +1. **Find the spec folder.** Look for the most recent `lead-dev-os/specs/YYYY-MM-DD-*/` directory, or ask the user which spec to implement. + +2. **Read these files in order:** + - `tasks.md` — the task breakdown (your work plan) + - `spec.md` — the specification (your requirements) + - `planning/requirements.md` — original requirements and Q&A context (if present) + +3. **Identify the incomplete task groups** (groups with unchecked tasks) and their `Dependencies:` headers. + +4. **Note the Execution Waves subsection** of `tasks.md`'s Execution Order, if present — it is `/lead-dev-os:step2-scope-tasks`'s proposal for which groups can run in parallel. Treat it as a starting point, to be validated against the actual plans before any parallel dispatch. diff --git a/lead-dev-os/skills/step3-implement-tasks/steps/pre-plan.md b/lead-dev-os/skills/step3-implement-tasks/steps/pre-plan.md new file mode 100644 index 0000000..207c789 --- /dev/null +++ b/lead-dev-os/skills/step3-implement-tasks/steps/pre-plan.md @@ -0,0 +1,69 @@ +# Pre-execution planning + +*Applies to modes A and H only. L mode plans per group during direct execution — skip this step entirely for L.* + +The goal: produce a `plans/group-N.md` file for every incomplete task group before any code is written, pressure-test the batch with the adversarial-thinker, and derive a parallel-wave execution schedule — so the user reviews the whole execution upfront in one batch instead of group-by-group. + +## 1. Check for existing plans + +If `lead-dev-os/specs//plans/` already contains files, ask the user whether to reuse, regenerate, or amend them. Don't silently overwrite plans the user may have edited. + +## 2. Spawn planner subagents — one per incomplete group, in parallel + +Issue all subagent calls in a single tool-call batch so they run concurrently. Use `subagent_type: "general-purpose"` and give each a self-contained prompt of roughly this shape: + +``` +You are planning Task Group from /tasks.md. + +Read these files first (and only these — don't broadly scan the codebase): +- /tasks.md (focus on Group N's section) +- /spec.md +- agents-context/README.md, then load only the concept/standard files Group N's + "Read before starting" header names +- Each file Group N will modify or extend, so you know the starting state + +Write /plans/group-.md following the plan template at +/skills/step3-implement-tasks/template.md exactly — every +section (Goal, Sub-tasks, File operations, Test approach, Verification, +Risks) filled with concrete values. + +Constraints: +- Do NOT write code or modify any file outside /plans/. +- Stay within the scope of Group N as defined in tasks.md. If you spot a + missing dependency on another group or a gap in the spec, flag it in + Risks rather than expanding scope. +- The plan will be read cold by an executor agent; be specific about file + paths and exact patterns to follow. +``` + +## 3. Adversarial plan challenge + +When all planner subagents return, dispatch the **adversarial-thinker** with the plan-challenge prompt from [../shared/adversarial-agent.md](../shared/adversarial-agent.md). It reads the spec, the task breakdown, and every plan, and hunts for what the planners assumed — unhandled inputs, failure modes, contract mismatches between groups, hidden dependencies. + +Triage its findings per that file's guidance: amend plan files directly for clear plan-level fixes, and carry spec-level questions into the report below for the user to rule on. + +## 4. Derive the execution schedule + +Group the incomplete task groups into **waves**. Two or more groups may share a wave only when BOTH hold: + +- **(a) No dependency** between them, directly or transitively, per the `Dependencies:` headers. +- **(b) Disjoint file sets** per the plans' "File operations" sections — no file appears in two plans in the same wave. + +Start from the Execution Waves subsection in `tasks.md` if present, then validate it against the actual plans — condition (b) can only be confirmed now that plans exist. If the adversarial-thinker flagged a hidden dependency or file contention, respect the flag. When in doubt, serialize — a serialized group is cheaper than a merge conflict. + +## 5. Report and wait for "go" + +> All plans are ready in `lead-dev-os/specs//plans/`. Review and edit the files as needed. Reply **"go"** when ready to execute. +> +> - `plans/group-1.md` — +> - `plans/group-2.md` — +> - … +> +> **Adversarial review:** +> +> **Execution schedule:** +> - Wave 1: Group 1, Group 2 (independent — no shared files) +> - Wave 2: Group 3 +> - … + +Wait for explicit "go" before executing anything. Do not start on your own initiative. The user may edit plans or reorder the schedule before approving. diff --git a/lead-dev-os/skills/step3-implement-tasks/steps/select-mode.md b/lead-dev-os/skills/step3-implement-tasks/steps/select-mode.md new file mode 100644 index 0000000..f93708e --- /dev/null +++ b/lead-dev-os/skills/step3-implement-tasks/steps/select-mode.md @@ -0,0 +1,19 @@ +# Select execution mode + +Read the `> Size:` line from `spec.md` (written by `/lead-dev-os:step1-write-spec`) and derive a recommendation: **Small → A**, **Medium → H**, **Large → L**. If the line is absent, make your own quick size assessment from `tasks.md` (group count, integration points) and say so. + +Present the three modes with your recommendation first, and ask which to use — the user decides. + +| Mode | Behavior | Best for | +|------|----------|----------| +| **A — Autonomous** | Pre-plan all groups in parallel → adversarial plan challenge → user approves batch + wave schedule → executor subagents run each group (independent groups in parallel waves) → verification pair checks each group before the orchestrator commits it. No pauses during execution. | Small features, well-understood domains, low risk. | +| **L — Lead-in-the-Loop** | Per-group cycle in the main conversation: plan (native plan mode) → user approves → execute → verification pair reports into the review gate → user reviews → repeat. | Complex features, new domains, high visibility. | +| **H — Hybrid** | A-style orchestrated execution up to a checkpoint group; at and after the checkpoint, switch to L behavior. | Boilerplate setup followed by tricky logic. | + +In every mode, the same verification agents run — implementation-reviewer and test-verifier on each group, the adversarial-thinker on the plans (A/H) and on the finished feature (all modes). The modes differ in who acts on the findings: in orchestrated execution the orchestrator drives a bounded fix cycle; in direct execution the findings are presented to the user at the review gate. + +Ask **"Which execution mode?"** using the `AskUserQuestion` tool when available (options A / L / H with one-line descriptions, the recommended mode listed first and labeled "(Recommended)"); fall back to a plain-text question otherwise. + +If the user picks **H**, also ask: **"Which group is the checkpoint?"** — again via `AskUserQuestion`, offering the task groups as options. Orchestrated execution runs up to but not including that group; L behavior begins at that group. + +Store the mode (and checkpoint) for the rest of the session. diff --git a/lead-dev-os/skills/step3-implement-tasks/template.md b/lead-dev-os/skills/step3-implement-tasks/template.md new file mode 100644 index 0000000..1efc278 --- /dev/null +++ b/lead-dev-os/skills/step3-implement-tasks/template.md @@ -0,0 +1,37 @@ +# Plan: Task Group [N] — [Group Name] + +> Spec: [spec-folder-name] +> Task group: [N] of [total] + +## 1. Goal + +[One paragraph: what shipping this group accomplishes.] + +## 2. Sub-tasks + +[Ordered, atomic list. Each sub-task small enough to be a coherent commit on its own. Mark which sub-tasks merit their own commit vs. rolling into the group commit.] + +1. [Sub-task] — [own commit | group commit] +2. [Sub-task] — [own commit | group commit] + +## 3. File operations + +[Every file this group will create, modify, or delete, with a one-line rationale per file. This list is also what makes parallel scheduling safe — it must be complete.] + +- `path/to/file` — [create | modify | delete] — [rationale] + +## 4. Test approach + +[Which test files, how many tests (within the group's 2-8 budget), what they cover — including the edge cases the spec calls out for this group — and the patterns to follow from the project's test standards.] + +## 5. Verification + +[The exact command(s) to run this group's tests — and only this group's tests.] + +```bash +[command] +``` + +## 6. Risks + +[Anything that could cause the group to fail or need spec clarification before execution. A missing dependency on another group or a gap in the spec gets flagged here, never absorbed as expanded scope.] diff --git a/tests/test_content_bundle.sh b/tests/test_content_bundle.sh index 379955f..7936d1f 100755 --- a/tests/test_content_bundle.sh +++ b/tests/test_content_bundle.sh @@ -215,9 +215,9 @@ fi echo "" echo "step3 README sync requirement:" -STEP3_MD="$REPO_ROOT/lead-dev-os/skills/step3-implement-tasks/SKILL.md" +STEP3_DIR="$REPO_ROOT/lead-dev-os/skills/step3-implement-tasks" -if grep -q 'Keep.*agents-context/README.md.*in sync' "$STEP3_MD" 2>/dev/null; then +if grep -rq 'Keep.*agents-context/README.md.*in sync' "$STEP3_DIR" 2>/dev/null; then pass "step3 requires keeping README.md in sync" else fail "step3 missing README.md sync requirement" diff --git a/tests/test_skill_content.sh b/tests/test_skill_content.sh index 98b1fdb..5d6c125 100755 --- a/tests/test_skill_content.sh +++ b/tests/test_skill_content.sh @@ -165,6 +165,7 @@ echo "" echo "step3 orchestrated execution:" STEP3_MD="$PLUGIN_DIR/skills/step3-implement-tasks/SKILL.md" +STEP3_DIR="$PLUGIN_DIR/skills/step3-implement-tasks" if grep -q 'executor subagent' "$STEP3_MD" 2>/dev/null; then pass "step3 delegates group execution to executor subagents" @@ -178,18 +179,89 @@ else fail "step3 missing orchestrator verify-then-commit rule" fi -if grep -q 'Reconcile before you code' "$STEP3_MD" 2>/dev/null; then +if grep -rq 'Reconcile before you code' "$STEP3_DIR" 2>/dev/null; then pass "step3 executor prompt reconciles stale plans against reality" else fail "step3 executor prompt missing stale-plan reconcile instruction" fi -if grep -q 'Parallel dispatch' "$STEP3_MD" 2>/dev/null; then +if grep -rq 'Parallel dispatch' "$STEP3_DIR" 2>/dev/null; then pass "step3 allows parallel dispatch of independent groups" else fail "step3 missing parallel dispatch of independent groups" fi +# --- step3: structured shape (orchestrator + steps/ + shared/) --- + +echo "" +echo "step3 structured shape:" + +for step_file in load-context select-mode pre-plan execute-orchestrated execute-direct finalize; do + if [ -f "$STEP3_DIR/steps/$step_file.md" ]; then + pass "step3 steps/$step_file.md exists" + else + fail "step3 steps/$step_file.md missing" + fi +done + +if [ -f "$STEP3_DIR/template.md" ]; then + pass "step3 template.md (plans/group-N.md format) exists" +else + fail "step3 template.md missing" +fi + +# --- step3: verification agents --- + +echo "" +echo "step3 verification agents:" + +if grep -rq 'implementation-reviewer' "$STEP3_DIR" 2>/dev/null; then + pass "step3 has an implementation-reviewer agent" +else + fail "step3 missing implementation-reviewer agent" +fi + +if grep -rq 'test-verifier' "$STEP3_DIR" 2>/dev/null; then + pass "step3 has a test-verifier agent" +else + fail "step3 missing test-verifier agent" +fi + +if grep -rq 'adversarial-thinker' "$STEP3_DIR" 2>/dev/null; then + pass "step3 has an adversarial-thinker agent" +else + fail "step3 missing adversarial-thinker agent" +fi + +if grep -rq 'READ-ONLY' "$STEP3_DIR/shared/verification-agents.md" 2>/dev/null; then + pass "step3 verification agents are read-only" +else + fail "step3 verification agents missing read-only constraint" +fi + +if grep -rq 'Limit: 2 rounds' "$STEP3_DIR/shared/verification-agents.md" 2>/dev/null; then + pass "step3 verification fix cycle is bounded" +else + fail "step3 verification fix cycle missing bound" +fi + +# --- Parallel execution waves --- + +echo "" +echo "Parallel execution waves:" + +if grep -q 'Execution Waves' "$PLUGIN_DIR/skills/step2-scope-tasks/template.md" 2>/dev/null; then + pass "step2 template includes Execution Waves subsection" +else + fail "step2 template missing Execution Waves subsection" +fi + +if grep -rq 'Execution Waves' "$STEP3_DIR" 2>/dev/null; then + pass "step3 consumes step2's Execution Waves" +else + fail "step3 does not reference Execution Waves" +fi + # --- Full-suite backstop gate --- echo "" @@ -203,13 +275,13 @@ else fail "step2 template missing full-suite backstop subtask" fi -if grep -q 'Run the full test suite once' "$STEP3_MD" 2>/dev/null; then +if grep -rq 'Run the full test suite once' "$STEP3_DIR" 2>/dev/null; then pass "step3 after-all-groups includes full-suite run" else fail "step3 missing full-suite run after all groups" fi -if grep -q 'Verify at runtime' "$STEP3_MD" 2>/dev/null; then +if grep -rq 'Verify at runtime' "$STEP3_DIR" 2>/dev/null; then pass "step3 includes runtime verification of the feature" else fail "step3 missing runtime verification step" From 6119d4dc7d21f997aa20766b58c77366cdffb96e Mon Sep 17 00:00:00 2001 From: Vel Lesikov Date: Fri, 14 Aug 2026 15:48:30 -0700 Subject: [PATCH 4/5] docs: describe the agent team, execution waves, and three delivery gates Sync workflow.md and implementation.md with the step2/step3 changes: verification agents (implementation-reviewer, test-verifier, adversarial-thinker), wave-based parallel execution, and the adversarial delivery review gate before the full-suite backstop. Co-Authored-By: Claude Fable 5 --- docs/implementation.md | 21 ++++++++++++--------- docs/workflow.md | 4 ++-- 2 files changed, 14 insertions(+), 11 deletions(-) diff --git a/docs/implementation.md b/docs/implementation.md index 7a3b6b3..5b9965c 100644 --- a/docs/implementation.md +++ b/docs/implementation.md @@ -8,7 +8,9 @@ nav_order: 4 The implementation phase executes task groups produced by `/lead-dev-os:step2-scope-tasks`. Each task group contains context directives (which files from `agents-context/` to load) and atomic tasks derived from the spec. Templates and examples are co-located with each skill for reference. -Three execution modes control how much human oversight the AI receives during implementation. +The main conversation acts as the orchestrator of a small agent team: **planner** subagents (pre-plan groups in parallel), **executor** subagents (implement one group each in a fresh context), and three verification agents — an **implementation-reviewer** and a **test-verifier** that check every group before it's committed, and an **adversarial-thinker** that challenges the plans before code is written and attacks the finished feature before delivery. + +Three execution modes control how much human oversight the AI receives during implementation. The verification agents run in every mode; the modes differ in who acts on their findings — the orchestrator (bounded fix cycles) or the lead (at review gates). ![Implementation modes diagram]({{ site.baseurl }}/assets/images/implementation-diagram.png) @@ -16,14 +18,14 @@ Three execution modes control how much human oversight the AI receives during im ## Mode A: Autonomous -All task groups are pre-planned in parallel (one planner subagent per group produces `plans/group-N.md`), you approve the batch, then execution runs with no human intervention. The main conversation acts as an **orchestrator**: each group is executed by a fresh executor subagent with a clean context, and the orchestrator verifies the group's tests itself, reviews the diff, and commits — one atomic commit per group. Independent groups (no dependency between them, disjoint file operations) may execute in parallel. +All task groups are pre-planned in parallel (one planner subagent per group produces `plans/group-N.md`), the adversarial-thinker challenges the plan batch, and an execution schedule of parallel **waves** is derived — groups share a wave only when they have no dependency on each other and disjoint file sets. You approve the batch and schedule, then execution runs with no human intervention. The main conversation acts as an **orchestrator**: each group is executed by a fresh executor subagent with a clean context; the orchestrator re-runs the group's tests itself, dispatches the implementation-reviewer + test-verifier pair in parallel, drives a bounded fix cycle on blocking findings (max 2 rounds, then it stops and asks you), and commits — one atomic commit per group. ``` - plan G1..G4 (parallel) → approve batch -G1 ⇒ executor → verify → commit -G2 ⇒ executor → verify → commit (G2 ∥ G3 if independent) -G3 ⇒ executor → verify → commit -G4 ⇒ executor → verify → commit → DONE + plan G1..G4 (parallel) → adversarial challenge → approve batch + waves +Wave 1 G1 ⇒ executor → verify pair → commit +Wave 2 G2 ⇒ executor → verify pair → commit ─┐ + G3 ⇒ executor → verify pair → commit ─┘ (G2 ∥ G3 — same wave) +Wave 3 G4 ⇒ executor → verify pair → commit → adversarial review → DONE ``` **Best for:** Small features, well-understood domains, no unknowns in the spec. The spec and task definitions are clear enough that the agent can ship without review. @@ -32,7 +34,7 @@ G4 ⇒ executor → verify → commit → DONE ## Mode L: Lead-in-the-Loop -The agent plans and implements one task group in the main conversation (using Claude Code's native plan mode per group), then pauses and waits for the lead developer to review before continuing. This creates a feedback loop at every group boundary — and keeps the work visible, which is why L mode does not delegate to subagents. +The agent plans and implements one task group in the main conversation (using Claude Code's native plan mode per group), then pauses and waits for the lead developer to review before continuing. This creates a feedback loop at every group boundary — and keeps the work visible, which is why L mode does not delegate execution to subagents. The verification agents still run: after each group's tests pass, the implementation-reviewer and test-verifier report into the review gate, so the lead reviews with machine-found issues already surfaced and decides what gets fixed. ``` G1 → [REVIEW] → G2 → [REVIEW] → G3 → [REVIEW] → G4 @@ -83,8 +85,9 @@ When you run `/lead-dev-os:step3-implement-tasks`, the skill reads the `> Size:` ## After Implementation -Once all task groups are complete, the skill closes with two gates before suggesting archive: +Once all task groups are complete, the skill closes with three gates before suggesting archive: +- **Adversarial delivery review** — the adversarial-thinker (a fresh, read-only agent) attacks the finished feature: concrete failure scenarios, edge cases the tests miss, regressions in adjacent behavior, acceptance criteria satisfied in letter but not intent. Confirmed in-scope defects get fixed (bounded); everything else is reported. - **Full-suite backstop** — the entire test suite runs once (the only full-suite run in the workflow; per-group runs stay feature-scoped for fast feedback). New failures caused by the feature get fixed; pre-existing failures get reported, not fixed. - **Runtime verification** — the agent exercises the feature's primary user flow in the running app where feasible, because tests passing is not the same as the feature working. diff --git a/docs/workflow.md b/docs/workflow.md index 473c2b6..e188b60 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -33,11 +33,11 @@ Interactive Q&A session to gather requirements, then formalizes into a structure ### Step 2: Scope (`/lead-dev-os:step2-scope-tasks`) -Breaks the spec into task groups with explicit context directives. Groups follow an explicit strategy recorded in `tasks.md`: **vertical slices** (preferred — each group a thin end-to-end increment that's demoable on its own and parallelizable during implementation) or **layers** (Database → API → Frontend, when the data model is the hard part). Each task group declares which files from `agents-context/` to load before executing, and reads as a complete user story — a plain-language goal and "done when" definition that a non-technical stakeholder can understand and verify. Produces `tasks.md` with atomic, implementable work items. +Breaks the spec into task groups with explicit context directives. Groups follow an explicit strategy recorded in `tasks.md`: **vertical slices** (preferred — each group a thin end-to-end increment that's demoable on its own and parallelizable during implementation) or **layers** (Database → API → Frontend, when the data model is the hard part). Each task group declares which files from `agents-context/` to load before executing, and reads as a complete user story — a plain-language goal and "done when" definition that a non-technical stakeholder can understand and verify. Produces `tasks.md` with atomic, implementable work items, including an **Execution Waves** map of which groups can safely run in parallel during implementation (no mutual dependencies, disjoint file sets). ### Step 3: Implement (`/lead-dev-os:step3-implement-tasks`) -Context-aware execution of task groups. In autonomous modes each group runs in a fresh executor subagent while the main conversation orchestrates, verifies, and commits; independent groups can run in parallel. Execution ends with a full-test-suite backstop and a runtime check of the feature's primary flow. See [Implementation]({{ site.baseurl }}/implementation) for the three execution modes. +Context-aware execution of task groups by an orchestrated agent team. In autonomous modes each group runs in a fresh executor subagent while the main conversation orchestrates; independent groups run in parallel waves. Every group is checked before commit by a parallel verification pair — an **implementation-reviewer** (diff vs. plan, spec, and standards) and a **test-verifier** (tests are meaningful, edge cases covered, nothing weakened) — and an **adversarial-thinker** challenges the plans up front and attacks the finished feature before delivery. Execution ends with a full-test-suite backstop and a runtime check of the feature's primary flow. See [Implementation]({{ site.baseurl }}/implementation) for the three execution modes. ### Step 4: Archive (`/lead-dev-os:step4-archive-spec`) From 6cead9bbde24605c7946fc515e062c81488a716e Mon Sep 17 00:00:00 2001 From: Vel Lesikov Date: Fri, 14 Aug 2026 15:48:30 -0700 Subject: [PATCH 5/5] release: bump plugin version to 1.1.0 Installed users only receive updates when plugin.json's version changes. Co-Authored-By: Claude Fable 5 --- lead-dev-os/.claude-plugin/plugin.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lead-dev-os/.claude-plugin/plugin.json b/lead-dev-os/.claude-plugin/plugin.json index 8735005..a3bf278 100644 --- a/lead-dev-os/.claude-plugin/plugin.json +++ b/lead-dev-os/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "lead-dev-os", - "version": "1.0.0", + "version": "1.1.0", "description": "Spec & context-driven framework for Claude Code development. Structured skills for product planning, spec writing, task scoping, and context-aware implementation.", "author": { "name": "CaptainMe-AI",