diff --git a/.claude/commands/implement/SKILL.md b/.claude/commands/implement/SKILL.md index cf44a57..712c902 100644 --- a/.claude/commands/implement/SKILL.md +++ b/.claude/commands/implement/SKILL.md @@ -1,32 +1,31 @@ --- name: implement description: | - Orchestrate task implementation with dependency-aware batching, parallel subagents, and integrated code review. + Implement tasks sequentially with dependency-aware batching and integrated code review. Reads flat task files and _dependencies_table.md from TASKS_DIR, computes execution batches via topological sort, - launches up to 4 implementer subagents in parallel, runs code-review skill after each batch, and loops until done. + implements tasks one at a time in dependency order, runs code-review skill after each batch, and loops until done. Use after /decompose has produced task files. Trigger phrases: - "implement", "start implementation", "implement tasks" - - "run implementers", "execute tasks" + - "execute tasks" category: build -tags: [implementation, orchestration, batching, parallel, code-review] +tags: [implementation, batching, code-review] disable-model-invocation: true --- -# Implementation Orchestrator +# Implementation Runner -Orchestrate the implementation of all tasks produced by the `/decompose` skill. This skill is a **pure orchestrator** — it does NOT write implementation code itself. It reads task specs, computes execution order, delegates to `implementer` subagents, validates results via the `/code-review` skill, and escalates issues. +Implement all tasks produced by the `/decompose` skill. This skill reads task specs, computes execution order, writes the code and tests for each task **sequentially** (no subagents, no parallel execution), validates results via the `/code-review` skill, and escalates issues. -The `implementer` agent is the specialist that writes all the code — it receives a task spec, analyzes the codebase, implements the feature, writes tests, and verifies acceptance criteria. +For each task the main agent reads the task spec, analyzes the codebase, implements the feature, writes tests, and verifies acceptance criteria — then moves on to the next task. ## Core Principles -- **Orchestrate, don't implement**: this skill delegates all coding to `implementer` subagents -- **Dependency-aware batching**: tasks run only when all their dependencies are satisfied -- **Max 4 parallel agents**: never launch more than 4 implementer subagents simultaneously -- **File isolation**: no two parallel agents may write to the same file +- **Sequential execution**: implement one task at a time. Do NOT spawn subagents and do NOT run tasks in parallel. +- **Dependency-aware ordering**: tasks run only when all their dependencies are satisfied +- **Batching for review, not parallelism**: tasks are grouped into batches so `/code-review` and commits operate on a coherent unit of work — all tasks inside a batch are still implemented one after the other - **Integrated review**: `/code-review` skill runs automatically after each batch -- **Auto-start**: batches launch immediately — no user confirmation before a batch +- **Auto-start**: batches start immediately — no user confirmation before a batch - **Gate on failure**: user confirmation is required only when code review returns FAIL - **Commit and push per batch**: after each batch is confirmed, commit and push to remote @@ -61,8 +60,8 @@ The `implementer` agent is the specialist that writes all the code — it receiv - Topological sort remaining tasks - Select tasks whose dependencies are ALL satisfied (completed) -- If a ready task depends on any task currently being worked on in this batch, it must wait for the next batch -- Cap the batch at 4 parallel agents +- A batch is simply a coherent group of tasks for review + commit. Within the batch, tasks are implemented sequentially in topological order. +- Cap the batch size at a reasonable review scope (default: 4 tasks) - If the batch would exceed 20 total complexity points, suggest splitting and let the user decide ### 4. Assign File Ownership @@ -70,33 +69,34 @@ The `implementer` agent is the specialist that writes all the code — it receiv For each task in the batch: - Parse the task spec's Component field and Scope section - Map the component to directories/files in the project -- Determine: files OWNED (exclusive write), files READ-ONLY (shared interfaces, types), files FORBIDDEN (other agents' owned files) -- If two tasks in the same batch would modify the same file, schedule them sequentially instead of in parallel +- Determine: files OWNED (exclusive write), files READ-ONLY (shared interfaces, types), files FORBIDDEN (other components' owned files) + +Since execution is sequential, there is no parallel-write conflict to resolve; ownership here is a **scope discipline** check — it stops a task from drifting into unrelated components even when alone. ### 5. Update Tracker Status → In Progress -For each task in the batch, transition its ticket status to **In Progress** via the configured work item tracker (Jira MCP or Azure DevOps MCP — see `protocols.md` for detection) before launching the implementer. If `tracker: local`, skip this step. +For each task in the batch, transition its ticket status to **In Progress** via the configured work item tracker (Jira MCP — see `protocols.md` for detection) before starting work. If `tracker: local`, skip this step. -### 6. Launch Implementer Subagents +### 6. Implement Tasks Sequentially -For each task in the batch, launch an `implementer` subagent with: -- Path to the task spec file -- List of files OWNED (exclusive write access) -- List of files READ-ONLY -- List of files FORBIDDEN +For each task in the batch **in topological order, one at a time**: +1. Read the task spec file. +2. Respect the file-ownership envelope computed in Step 4 (OWNED / READ-ONLY / FORBIDDEN). +3. Implement the feature and write/update tests for every acceptance criterion in the spec. +4. Run the relevant tests locally before moving on to the next task in the batch. If tests fail, fix in-place — do not defer. +5. Capture a short per-task status line (files changed, tests pass/fail, any blockers) for the batch report. -Launch all subagents immediately — no user confirmation. +Do NOT spawn subagents and do NOT attempt to implement two tasks simultaneously, even if they touch disjoint files. -### 7. Monitor +### 7. Collect Status -- Wait for all subagents to complete -- Collect structured status reports from each implementer -- If any implementer reports "Blocked", log the blocker and continue with others +- After all tasks in the batch are finished, aggregate the per-task status lines into a structured batch status. +- If any task reported "Blocked", log the blocker with the failing task's ID and continue — the batch report will surface it. -**Stuck detection** — while monitoring, watch for these signals per subagent: -- Same file modified 3+ times without test pass rate improving → flag as stuck, stop the subagent, report as Blocked -- Subagent has not produced new output for an extended period → flag as potentially hung -- If a subagent is flagged as stuck, do NOT let it continue looping — stop it and record the blocker in the batch report +**Stuck detection** — while implementing a task, watch for these signals in your own progress: +- The same file has been rewritten 3+ times without tests going green → stop, mark the task Blocked, and move to the next task in the batch. +- You have tried 3+ distinct approaches without evidence-driven progress → stop, mark Blocked, move on. +- Do NOT loop indefinitely on a single task. Record the blocker and proceed. ### 8. Code Review @@ -162,7 +162,7 @@ After each batch, produce a structured report: ## Code Review Verdict: [PASS/FAIL/PASS_WITH_WARNINGS] ## Auto-Fix Attempts: [0/1/2] -## Stuck Agents: [count or None] +## Blocked Tasks: [count or None] ## Next Batch: [task list] or "All tasks complete" ``` @@ -171,9 +171,9 @@ After each batch, produce a structured report: | Situation | Action | |-----------|--------| -| Implementer fails same approach 3+ times | Stop it, escalate to user | +| Same task rewritten 3+ times without green tests | Mark Blocked, continue batch, escalate at batch end | | Task blocked on external dependency (not in task list) | Report and skip | -| File ownership conflict unresolvable | ASK user | +| File ownership violated (task wrote outside OWNED) | ASK user | | Test failures exceed 50% of suite after a batch | Stop and escalate | | All tasks complete | Report final summary, suggest final commit | | `_dependencies_table.md` missing | STOP — run `/decompose` first | @@ -188,7 +188,7 @@ Each batch commit serves as a rollback checkpoint. If recovery is needed: ## Safety Rules -- Never launch tasks whose dependencies are not yet completed -- Never allow two parallel agents to write to the same file -- If a subagent fails or is flagged as stuck, stop it and report — do not let it loop indefinitely +- Never start a task whose dependencies are not yet completed +- Never run tasks in parallel and never spawn subagents +- If a task is flagged as stuck, stop working on it and report — do not let it loop indefinitely - Always run tests after each batch completes diff --git a/.claude/commands/implement/references/batching-algorithm.md b/.claude/commands/implement/references/batching-algorithm.md index 74a1c29..f012509 100644 --- a/.claude/commands/implement/references/batching-algorithm.md +++ b/.claude/commands/implement/references/batching-algorithm.md @@ -3,29 +3,31 @@ ## Topological Sort with Batch Grouping The `/implement` skill uses a topological sort to determine execution order, -then groups tasks into batches for parallel execution. +then groups tasks into batches for code review and commit. Execution within a +batch is **sequential** — no subagents, no parallelism. ## Algorithm 1. Build adjacency list from `_dependencies_table.md` 2. Compute in-degree for each task node -3. Initialize batch 0 with all nodes that have in-degree 0 +3. Initialize the ready set with all nodes that have in-degree 0 4. For each batch: - a. Select up to 4 tasks from the ready set - b. Check file ownership — if two tasks would write the same file, defer one to the next batch - c. Launch selected tasks as parallel implementer subagents - d. When all complete, remove them from the graph and decrement in-degrees of dependents - e. Add newly zero-in-degree nodes to the next batch's ready set + a. Select up to 4 tasks from the ready set (default batch size cap) + b. Implement the selected tasks one at a time in topological order + c. When all tasks in the batch complete, remove them from the graph and + decrement in-degrees of dependents + d. Add newly zero-in-degree nodes to the ready set 5. Repeat until the graph is empty -## File Ownership Conflict Resolution +## Ordering Inside a Batch -When two tasks in the same batch map to overlapping files: -- Prefer to run the lower-numbered task first (it's more foundational) -- Defer the higher-numbered task to the next batch -- If both have equal priority, ask the user +Tasks inside a batch are executed in topological order — a task is only +started after every task it depends on (inside the batch or in a previous +batch) is done. When two tasks have the same topological rank, prefer the +lower-numbered (more foundational) task first. ## Complexity Budget Each batch should not exceed 20 total complexity points. If it does, split the batch and let the user choose which tasks to include. +The budget exists to keep the per-batch code review scope reviewable.