From 4eee835ca64740e6d27b2224a350291ebd1ef8b7 Mon Sep 17 00:00:00 2001 From: Perlover Date: Wed, 17 Dec 2025 16:20:30 +0100 Subject: [PATCH 1/6] fix(implement-tasks): clarify separate implementer subagent per task group MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit With Claude Opus 4.5, the previous wording caused two issues: 1. Multiple task groups in single implementer - Claude often attempted to pass all task groups to a single implementer subagent, exhausting context 2. No subagent at all - Sometimes Claude implemented task groups directly in the current conversation window without spawning any implementer This fix adds: - CRITICAL instruction to spawn SEPARATE implementer for EACH task group - Execution strategy based on task group dependencies - Examples of parallel execution (independent groups) - Examples of sequential execution (dependent groups) Each subagent now gets its own context window for focused implementation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .../multi-agent/implement-tasks.md | 31 ++++++++++++++----- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/profiles/default/commands/implement-tasks/multi-agent/implement-tasks.md b/profiles/default/commands/implement-tasks/multi-agent/implement-tasks.md index f5db2775..e74d454d 100644 --- a/profiles/default/commands/implement-tasks/multi-agent/implement-tasks.md +++ b/profiles/default/commands/implement-tasks/multi-agent/implement-tasks.md @@ -3,7 +3,7 @@ Now that we have a spec and tasks list ready for implementation, we will proceed with implementation of this spec by following this multi-phase process: PHASE 1: Determine which task group(s) from tasks.md should be implemented -PHASE 2: Delegate implementation to the implementer subagent +PHASE 2: Delegate implementation to implementer subagents (one per task group) PHASE 3: After ALL task groups have been implemented, delegate to implementation-verifier to produce the final verification report. Follow each of these phases and their individual workflows IN SEQUENCE: @@ -14,7 +14,7 @@ Follow each of these phases and their individual workflows IN SEQUENCE: First, check if the user has already provided instructions about which task group(s) to implement. -**If the user HAS provided instructions:** Proceed to PHASE 2 to delegate implementation of those specified task group(s) to the **implementer** subagent. +**If the user HAS provided instructions:** Proceed to PHASE 2 to delegate implementation of those specified task group(s) to **implementer** subagents (one per task group). **If the user has NOT provided instructions:** @@ -26,22 +26,39 @@ Should we proceed with implementation of all task groups in tasks.md? If not, then please specify which task(s) to implement. ``` -### PHASE 2: Delegate implementation to the implementer subagent +### PHASE 2: Delegate implementation to implementer subagents -Delegate to the **implementer** subagent to implement the specified task group(s): +**CRITICAL: Spawn a SEPARATE implementer subagent for EACH task group.** Each subagent gets its own context window, enabling focused and effective implementation. -Provide to the subagent: -- The specific task group(s) from `agent-os/specs/[this-spec]/tasks.md` including the parent task, all sub-tasks, and any sub-bullet points +**Execution strategy based on task group dependencies:** + +1. **Analyze dependencies** - Check for "Dependencies:" annotations in tasks.md for each task group +2. **Independent task groups** (no dependencies, or all dependencies already completed): Launch their implementer subagents **IN PARALLEL** by issuing multiple Task tool calls in a single message +3. **Dependent task groups**: Wait for the required dependency to complete before launching + +**For EACH task group, spawn a dedicated implementer subagent providing:** + +- **ONE specific task group** from `agent-os/specs/[this-spec]/tasks.md` (including the parent task, all sub-tasks, and any sub-bullet points) - The path to this spec's documentation: `agent-os/specs/[this-spec]/spec.md` - The path to this spec's requirements: `agent-os/specs/[this-spec]/planning/requirements.md` - The path to this spec's visuals (if any): `agent-os/specs/[this-spec]/planning/visuals` -Instruct the subagent to: +Instruct each subagent to: 1. Analyze the provided spec.md, requirements.md, and visuals (if any) 2. Analyze patterns in the codebase according to its built-in workflow 3. Implement the assigned task group according to requirements and standards 4. Update `agent-os/specs/[this-spec]/tasks.md` to mark completed tasks with `- [x]` +**Example: Parallel execution** +If Task Group 1 and Task Group 2 have no dependencies on each other, launch both implementer subagents in a single message: +- Task tool call #1: implementer for Task Group 1 +- Task tool call #2: implementer for Task Group 2 + +**Example: Sequential execution** +If Task Group 3 depends on Task Group 1: +1. Wait for Task Group 1 implementer to complete +2. Then launch Task Group 3 implementer + ### PHASE 3: Produce the final verification report IF ALL task groups in tasks.md are marked complete with `- [x]`, then proceed with this step. Otherwise, return to PHASE 1. From f53df532548d77dde8b97cf2db654f61d16c5a28 Mon Sep 17 00:00:00 2001 From: Perlover Date: Thu, 18 Dec 2025 15:30:04 +0100 Subject: [PATCH 2/6] feat(implementer): add CLAUDE.md/skills reading and strict task completion rules Problem: Implementer agents were marking tasks as completed without actually executing them. For example, tasks requiring "Run E2E tests" were marked done without running tests, and parent tasks were marked complete while subtasks remained incomplete. This led to false completion reports and unverified implementations. Root causes identified: 1. Implementer did not read CLAUDE.md which contains project-specific rules 2. Implementer did not read project or global skills which may contain mandatory requirements (e.g., E2E testing requirements) 3. No explicit rules about what constitutes task completion 4. No rules about parent/subtask relationships Changes: 1. Added instruction to read CLAUDE.md from project root 2. Added instruction to read project skills from .claude/skills/ 3. Added instruction to read global skills from ~/.claude/skills/ 4. Added 6 critical task completion rules: - Rule 1: Tasks complete only when actually executed - Rule 2: Start services yourself, but don't install dependencies (may conflict with parallel agents) - Rule 3: Parent tasks require all subtasks complete - Rule 4: TDD phases require actual test execution output - Rule 5: Verification tasks require evidence (screenshots) - Rule 6: Incomplete tasks must stay marked incomplete with explanation This ensures implementer agents: - Follow project-specific conventions and requirements - Don't falsely mark tasks as complete - Provide evidence for verification tasks - Handle parallel execution safely (no dependency conflicts) --- .../implementation/implement-tasks.md | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/profiles/default/workflows/implementation/implement-tasks.md b/profiles/default/workflows/implementation/implement-tasks.md index 048741e2..8a38f446 100644 --- a/profiles/default/workflows/implementation/implement-tasks.md +++ b/profiles/default/workflows/implementation/implement-tasks.md @@ -11,6 +11,9 @@ Implement all tasks assigned to you and ONLY those task(s) that have been assign - **The existing patterns** that you've found and analyzed in the codebase. - **Specific notes provided in requirements.md, spec.md AND/OR tasks.md** - **Visuals provided (if any)** which would be located in `agent-os/specs/[this-spec]/planning/visuals/` +- **CLAUDE.md** in the project root (if exists) - contains project-specific rules, conventions, and requirements that you MUST follow. +- **Project skills** in `.claude/skills/` directory (if exists) - read and follow skills relevant to your task (e.g., testing skills when writing tests, frontend skills when writing UI code). +- **Global skills** in `~/.claude/skills/` directory (if exists) - read and follow globally defined skills relevant to your task. - **User Standards & Preferences** which are defined below. ## Self-verify and test your work by: @@ -18,3 +21,44 @@ Implement all tasks assigned to you and ONLY those task(s) that have been assign - IF your task involves user-facing UI, and IF you have access to browser testing tools, open a browser and use the feature you've implemented as if you are a user to ensure a user can use the feature in the intended way. - Take screenshots of the views and UI elements you've tested and store those in `agent-os/specs/[this-spec]/verification/screenshots/`. Do not store screenshots anywhere else in the codebase other than this location. - Analyze the screenshot(s) you've taken to check them against your current requirements. + +## CRITICAL: Task Completion Rules + +### Rule 1: A Task Is Complete ONLY When Actually Executed +- If a task says "Run tests" - you MUST execute the tests and see the output +- If a task says "Verify X works" - you MUST actually verify it +- Do NOT mark tasks as complete based on intent or assumption +- "I wrote the code" ≠ "task complete" - you must perform the actual action described + +### Rule 2: Handle Missing Prerequisites +- If a task requires a running service (dev server, database) that is not running: + - Start the service yourself (safe for parallel execution in isolated environments) +- If a task requires dependencies that are not installed: + - Do NOT install them yourself (may conflict with parallel agents) + - Report the blocker and keep task as `[ ]` + - Dependency installation is the responsibility of planning/setup phase +- If you cannot determine how to proceed, ask the user for guidance + +### Rule 3: Parent Tasks Require All Subtasks Complete +- A parent task (e.g., "5.0 Complete verification") can ONLY be marked `[x]` when ALL its subtasks are `[x]` +- If subtasks 5.2, 5.3, 5.4 are `[ ]`, then 5.0 MUST remain `[ ]` +- Never mark a parent task complete while leaving subtasks incomplete + +### Rule 4: TDD Phases Require Actual Test Execution +- If tasks.md specifies TDD workflow: + - RED phase: Tests must be written AND executed to verify they fail + - GREEN phase: Tests must be executed AND pass +- Do NOT mark TDD phases complete without actual test execution output + +### Rule 5: Verification Tasks Require Evidence +- If a task says "Manual verification" or "Verify in browser": + - Actually perform the verification using available tools + - Take screenshots as evidence when possible + - Store evidence in the designated location (e.g., verification/screenshots/) +- Do NOT mark verification tasks complete without performing verification + +### Rule 6: Incomplete Tasks Must Stay Incomplete +- If you cannot complete a task after attempting to resolve blockers: + - Keep the task marked as `[ ]` (incomplete) + - Add a comment in tasks.md explaining what you tried and what blocked you + - NEVER mark a task `[x]` if you did not actually complete it From 88370ee0d965a89fdfdc4f71baf874e383cd9326 Mon Sep 17 00:00:00 2001 From: Perlover Date: Fri, 19 Dec 2025 12:58:25 +0100 Subject: [PATCH 3/6] fix(implementer): replace hardcoded skills paths with Skill() tool reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Problem: The previous commit added instructions for implementer to read skills from specific directories (.claude/skills/ and ~/.claude/skills/). However, this approach has issues: 1. Hardcoded paths are Claude Code internal implementation details 2. Claude Code already pre-loads available skills as YAML frontmatter in the section of the system context 3. Subagents inherit the same context with available skills already visible 4. Reading files manually duplicates what Claude Code already provides Solution: Replace the two lines with specific paths with a single instruction that: - Points to section in system context - Instructs to use the Skill(skill_name) tool to invoke relevant skills - Removes dependency on internal Claude Code directory structure This makes the instructions more portable and aligned with how Claude Code actually handles skills discovery and invocation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- profiles/default/workflows/implementation/implement-tasks.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/profiles/default/workflows/implementation/implement-tasks.md b/profiles/default/workflows/implementation/implement-tasks.md index 8a38f446..f0925ff6 100644 --- a/profiles/default/workflows/implementation/implement-tasks.md +++ b/profiles/default/workflows/implementation/implement-tasks.md @@ -12,8 +12,7 @@ Implement all tasks assigned to you and ONLY those task(s) that have been assign - **Specific notes provided in requirements.md, spec.md AND/OR tasks.md** - **Visuals provided (if any)** which would be located in `agent-os/specs/[this-spec]/planning/visuals/` - **CLAUDE.md** in the project root (if exists) - contains project-specific rules, conventions, and requirements that you MUST follow. -- **Project skills** in `.claude/skills/` directory (if exists) - read and follow skills relevant to your task (e.g., testing skills when writing tests, frontend skills when writing UI code). -- **Global skills** in `~/.claude/skills/` directory (if exists) - read and follow globally defined skills relevant to your task. +- **Available Skills** - check available skills in your system context (listed in `` section). Use the `Skill(skill_name)` tool to invoke relevant skills for your task (e.g., testing skills when writing tests). Skills contain important requirements you MUST follow. - **User Standards & Preferences** which are defined below. ## Self-verify and test your work by: From a1c426d1602ed66b1f472c24f1834813c0ef7b1a Mon Sep 17 00:00:00 2001 From: Perlover Date: Fri, 19 Dec 2025 16:09:38 +0100 Subject: [PATCH 4/6] feat(agents): add Edit tool to all agents for efficient file modifications MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit All agent files previously had only Write and Read tools, which meant agents could only create/overwrite entire files but couldn't make targeted edits. This was inefficient when working with existing code. The Edit tool allows precise string replacements (old_string → new_string) without rewriting entire files. This is the preferred approach in Claude Code for modifying existing files, as documented in the official Claude Code skills reference. Changes: - implementer.md: added Edit tool - spec-writer.md: added Edit tool - tasks-list-creator.md: added Edit tool - spec-shaper.md: added Edit tool - spec-verifier.md: added Edit tool - implementation-verifier.md: added Edit tool - product-planner.md: added Edit tool - spec-initializer.md: added Edit tool 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- profiles/default/agents/implementation-verifier.md | 2 +- profiles/default/agents/implementer.md | 2 +- profiles/default/agents/product-planner.md | 2 +- profiles/default/agents/spec-initializer.md | 2 +- profiles/default/agents/spec-shaper.md | 2 +- profiles/default/agents/spec-verifier.md | 2 +- profiles/default/agents/spec-writer.md | 2 +- profiles/default/agents/tasks-list-creator.md | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/profiles/default/agents/implementation-verifier.md b/profiles/default/agents/implementation-verifier.md index ddf1e60d..cb1a2054 100644 --- a/profiles/default/agents/implementation-verifier.md +++ b/profiles/default/agents/implementation-verifier.md @@ -1,7 +1,7 @@ --- name: implementation-verifier description: Use proactively to verify the end-to-end implementation of a spec -tools: Write, Read, Bash, WebFetch, Playwright +tools: Write, Read, Edit, Bash, WebFetch, Playwright color: green model: inherit --- diff --git a/profiles/default/agents/implementer.md b/profiles/default/agents/implementer.md index 0a2e413a..92b71f73 100644 --- a/profiles/default/agents/implementer.md +++ b/profiles/default/agents/implementer.md @@ -1,7 +1,7 @@ --- name: implementer description: Use proactively to implement a feature by following a given tasks.md for a spec. -tools: Write, Read, Bash, WebFetch, Playwright, Skill +tools: Write, Read, Edit, Bash, WebFetch, Playwright, Skill color: red model: inherit --- diff --git a/profiles/default/agents/product-planner.md b/profiles/default/agents/product-planner.md index 12c52f74..abad46bf 100644 --- a/profiles/default/agents/product-planner.md +++ b/profiles/default/agents/product-planner.md @@ -1,7 +1,7 @@ --- name: product-planner description: Use proactively to create product documentation including mission, and roadmap -tools: Write, Read, Bash, WebFetch +tools: Write, Read, Edit, Bash, WebFetch color: cyan model: inherit --- diff --git a/profiles/default/agents/spec-initializer.md b/profiles/default/agents/spec-initializer.md index ac8ec04b..9c1ac18d 100644 --- a/profiles/default/agents/spec-initializer.md +++ b/profiles/default/agents/spec-initializer.md @@ -1,7 +1,7 @@ --- name: spec-initializer description: Use proactively to initialize spec folder and save raw idea -tools: Write, Bash +tools: Write, Edit, Bash color: green model: sonnet --- diff --git a/profiles/default/agents/spec-shaper.md b/profiles/default/agents/spec-shaper.md index 451490db..ccf15a11 100644 --- a/profiles/default/agents/spec-shaper.md +++ b/profiles/default/agents/spec-shaper.md @@ -1,7 +1,7 @@ --- name: spec-shaper description: Use proactively to gather detailed requirements through targeted questions and visual analysis -tools: Write, Read, Bash, WebFetch, Skill +tools: Write, Read, Edit, Bash, WebFetch, Skill color: blue model: inherit --- diff --git a/profiles/default/agents/spec-verifier.md b/profiles/default/agents/spec-verifier.md index 1e6117a8..aab7488f 100644 --- a/profiles/default/agents/spec-verifier.md +++ b/profiles/default/agents/spec-verifier.md @@ -1,7 +1,7 @@ --- name: spec-verifier description: Use proactively to verify the spec and tasks list -tools: Write, Read, Bash, WebFetch, Skill +tools: Write, Read, Edit, Bash, WebFetch, Skill color: pink model: sonnet --- diff --git a/profiles/default/agents/spec-writer.md b/profiles/default/agents/spec-writer.md index f0ebf8c7..6c486d6b 100644 --- a/profiles/default/agents/spec-writer.md +++ b/profiles/default/agents/spec-writer.md @@ -1,7 +1,7 @@ --- name: spec-writer description: Use proactively to create a detailed specification document for development -tools: Write, Read, Bash, WebFetch, Skill +tools: Write, Read, Edit, Bash, WebFetch, Skill color: purple model: inherit --- diff --git a/profiles/default/agents/tasks-list-creator.md b/profiles/default/agents/tasks-list-creator.md index d007507f..9852a98f 100644 --- a/profiles/default/agents/tasks-list-creator.md +++ b/profiles/default/agents/tasks-list-creator.md @@ -1,7 +1,7 @@ --- name: task-list-creator description: Use proactively to create a detailed and strategic tasks list for development of a spec -tools: Write, Read, Bash, WebFetch, Skill +tools: Write, Read, Edit, Bash, WebFetch, Skill color: orange model: inherit --- From e40f2e7554f693ea50ea99cd33b23a5f2966e88d Mon Sep 17 00:00:00 2001 From: Perlover Date: Fri, 19 Dec 2025 16:28:03 +0100 Subject: [PATCH 5/6] implementation-verifier.md: Added the Skill tools too. --- profiles/default/agents/implementation-verifier.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/profiles/default/agents/implementation-verifier.md b/profiles/default/agents/implementation-verifier.md index cb1a2054..64ebeb52 100644 --- a/profiles/default/agents/implementation-verifier.md +++ b/profiles/default/agents/implementation-verifier.md @@ -1,7 +1,7 @@ --- name: implementation-verifier description: Use proactively to verify the end-to-end implementation of a spec -tools: Write, Read, Edit, Bash, WebFetch, Playwright +tools: Write, Read, Edit, Bash, WebFetch, Playwright, Skill color: green model: inherit --- From c2462772bd9b8059a5f8e7e67f3079876b5d0efd Mon Sep 17 00:00:00 2001 From: Perlover Date: Thu, 25 Dec 2025 18:40:51 +0100 Subject: [PATCH 6/6] refactor(agents): remove explicit tools field to enable full tool inheritance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove the `tools:` field from all 8 subagent YAML frontmatter configurations. Why this change was made: 1. **Default behavior is better**: When the `tools` field is omitted, subagents automatically inherit ALL tools from the main thread, including all MCP tools from user-configured MCP servers. 2. **MCP tools access**: With explicit `tools` field, subagents were restricted only to the listed tools. This meant MCP tools (like Playwright, Context7, or any user-installed MCP servers) required manual addition to each agent. 3. **Maintenance burden eliminated**: Previously, every new tool or MCP server required updating all agent files. Now subagents automatically get access to any tools available to the main Claude Code instance. 4. **Per Claude Code docs**: "Omit the tools field to inherit all tools from the main thread (default), including MCP tools" - this is the recommended approach for maximum flexibility. Affected agents: - implementer.md - implementation-verifier.md - spec-initializer.md - spec-shaper.md - spec-verifier.md - spec-writer.md - tasks-list-creator.md - product-planner.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- profiles/default/agents/implementation-verifier.md | 1 - profiles/default/agents/implementer.md | 1 - profiles/default/agents/product-planner.md | 1 - profiles/default/agents/spec-initializer.md | 1 - profiles/default/agents/spec-shaper.md | 1 - profiles/default/agents/spec-verifier.md | 1 - profiles/default/agents/spec-writer.md | 1 - profiles/default/agents/tasks-list-creator.md | 1 - 8 files changed, 8 deletions(-) diff --git a/profiles/default/agents/implementation-verifier.md b/profiles/default/agents/implementation-verifier.md index 64ebeb52..3acec7ce 100644 --- a/profiles/default/agents/implementation-verifier.md +++ b/profiles/default/agents/implementation-verifier.md @@ -1,7 +1,6 @@ --- name: implementation-verifier description: Use proactively to verify the end-to-end implementation of a spec -tools: Write, Read, Edit, Bash, WebFetch, Playwright, Skill color: green model: inherit --- diff --git a/profiles/default/agents/implementer.md b/profiles/default/agents/implementer.md index 92b71f73..dda9768c 100644 --- a/profiles/default/agents/implementer.md +++ b/profiles/default/agents/implementer.md @@ -1,7 +1,6 @@ --- name: implementer description: Use proactively to implement a feature by following a given tasks.md for a spec. -tools: Write, Read, Edit, Bash, WebFetch, Playwright, Skill color: red model: inherit --- diff --git a/profiles/default/agents/product-planner.md b/profiles/default/agents/product-planner.md index abad46bf..43ab6f65 100644 --- a/profiles/default/agents/product-planner.md +++ b/profiles/default/agents/product-planner.md @@ -1,7 +1,6 @@ --- name: product-planner description: Use proactively to create product documentation including mission, and roadmap -tools: Write, Read, Edit, Bash, WebFetch color: cyan model: inherit --- diff --git a/profiles/default/agents/spec-initializer.md b/profiles/default/agents/spec-initializer.md index 9c1ac18d..37712761 100644 --- a/profiles/default/agents/spec-initializer.md +++ b/profiles/default/agents/spec-initializer.md @@ -1,7 +1,6 @@ --- name: spec-initializer description: Use proactively to initialize spec folder and save raw idea -tools: Write, Edit, Bash color: green model: sonnet --- diff --git a/profiles/default/agents/spec-shaper.md b/profiles/default/agents/spec-shaper.md index ccf15a11..2c58927c 100644 --- a/profiles/default/agents/spec-shaper.md +++ b/profiles/default/agents/spec-shaper.md @@ -1,7 +1,6 @@ --- name: spec-shaper description: Use proactively to gather detailed requirements through targeted questions and visual analysis -tools: Write, Read, Edit, Bash, WebFetch, Skill color: blue model: inherit --- diff --git a/profiles/default/agents/spec-verifier.md b/profiles/default/agents/spec-verifier.md index aab7488f..4af9addc 100644 --- a/profiles/default/agents/spec-verifier.md +++ b/profiles/default/agents/spec-verifier.md @@ -1,7 +1,6 @@ --- name: spec-verifier description: Use proactively to verify the spec and tasks list -tools: Write, Read, Edit, Bash, WebFetch, Skill color: pink model: sonnet --- diff --git a/profiles/default/agents/spec-writer.md b/profiles/default/agents/spec-writer.md index 6c486d6b..465798d8 100644 --- a/profiles/default/agents/spec-writer.md +++ b/profiles/default/agents/spec-writer.md @@ -1,7 +1,6 @@ --- name: spec-writer description: Use proactively to create a detailed specification document for development -tools: Write, Read, Edit, Bash, WebFetch, Skill color: purple model: inherit --- diff --git a/profiles/default/agents/tasks-list-creator.md b/profiles/default/agents/tasks-list-creator.md index 9852a98f..378e573e 100644 --- a/profiles/default/agents/tasks-list-creator.md +++ b/profiles/default/agents/tasks-list-creator.md @@ -1,7 +1,6 @@ --- name: task-list-creator description: Use proactively to create a detailed and strategic tasks list for development of a spec -tools: Write, Read, Edit, Bash, WebFetch, Skill color: orange model: inherit ---