feat(agents): add task completion rules, skills discovery, and Edit tool

[Perlover]

Summary

Add strict task completion rules, improve skills discovery, and enable full tool inheritance for all subagents. This prevents agents from falsely marking tasks as complete without actually executing them, aligns skills usage with Claude Code's built-in mechanisms, and gives subagents access to all tools including MCP servers.

Linked item

• Closes: # (must be an open Issue) OR
• Implements: # (must be a Discussion)

Checklist

• Linked to related Issue/Discussion
• Documented steps to test (below)
• Drafted "how to use" docs (if this adds new behavior)
• Backwards compatibility considered (notes if applicable)

Documented steps to test

1. Create a spec with tasks that include "Run tests" or "Verify in browser" requirements
2. Run implementer agent on the spec
3. Verify that implementer reads CLAUDE.md from project root
4. Verify that implementer uses Skill(skill_name) tool to invoke relevant skills from <available_skills> section
5. Verify that tasks requiring test execution are NOT marked complete without actual test output
6. Verify that parent tasks remain [ ] if any subtasks are incomplete
7. Verify that subagents have access to Edit tool and other inherited tools
8. Verify that subagents have access to MCP tools (e.g., Playwright, Context7) when configured

Notes for reviewers

Problem 1: False task completion

Problem solved:
Implementer agents were marking tasks as completed without actually executing them. For example:

• Tasks saying "Run E2E tests" were marked [x] without running tests
• Parent tasks marked complete while subtasks remained [ ]
• TDD GREEN phase marked complete without test execution output

Root causes addressed:

1. Implementer did not read CLAUDE.md (project-specific rules)
2. Implementer did not leverage available skills (may contain mandatory requirements like E2E testing)
3. No explicit rules about what constitutes task completion

Changes:

1. Added instruction to read CLAUDE.md from project root

2. Added instruction to use available skills via Skill(skill_name) tool

   • Initially added hardcoded paths (.claude/skills/, ~/.claude/skills/)
   • Replaced with reference to <available_skills> section and Skill() tool
   • Reason: Claude Code already pre-loads skills as YAML frontmatter in system context, subagents inherit this context, so reading files manually is redundant

3. Added 6 critical task completion rules:

   • Rule 1: Tasks complete only when actually executed
   • Rule 2: Handle missing prerequisites (start services, but don't install deps)
   • Rule 3: Parent tasks require all subtasks complete
   • Rule 4: TDD phases require actual test execution
   • Rule 5: Verification tasks require evidence
   • Rule 6: Incomplete tasks must stay incomplete

Problem 2: Limited tool access for subagents

Problem solved:
All agent files previously had explicit tools: field in their YAML frontmatter listing only specific tools (Read, Write, etc.). This restricted subagents to only those listed tools, preventing access to:

• Edit tool - for targeted string replacements
• MCP tools - Playwright, Context7, or any user-installed MCP servers
• Future tools - any new tools added to Claude Code

Solution:
Removed the tools: field entirely from all 8 agent files:

• implementer.md
• spec-writer.md
• tasks-list-creator.md
• spec-shaper.md
• spec-verifier.md
• implementation-verifier.md
• product-planner.md
• spec-initializer.md

Rationale:
Per Claude Code documentation: "Omit the tools field to inherit all tools from the main thread (default), including MCP tools." This approach:

1. Enables full tool inheritance - subagents automatically get all tools available to main Claude Code instance
2. Includes MCP tools - Playwright for browser automation, Context7 for docs, any user-configured MCP servers
3. Zero maintenance - new tools or MCP servers don't require updating agent files
4. Edit tool now available - subagents can use targeted string replacements instead of full file rewrites

Backwards compatibility

• Fully backwards compatible
• Existing workflows continue to work
• New rules only add stricter validation, don't break existing behavior
• Rule 2 explicitly prevents dependency installation conflicts when running parallel agents
• Removing tools: field is additive - subagents gain access to more tools, not fewer

References

Documentation sources used for these changes:

Claude Code Tools Documentation

• Frontmatter Reference (tools/allowed-tools configuration):
  https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/skills/command-development/references/frontmatter-reference.md

• Agent Creator (agent file structure with tools field):
  https://github.com/anthropics/claude-code/blob/main/plugins/plugin-dev/agents/agent-creator.md

Key Documentation Excerpts

From the agent creator documentation regarding tool inheritance:

"Omit the tools field to inherit all tools from the main thread (default), including MCP tools"

This is the recommended approach for maximum flexibility, allowing subagents to access:

• All built-in Claude Code tools (Read, Write, Edit, Bash, Glob, Grep, etc.)
• All configured MCP server tools (Playwright, Context7, etc.)
• Any future tools without configuration changes

[tonydehnke]

Do you have a fork of Agent-os that has all your improvements? I've been copying over bits and pieces here and there, but with none of these getting merged into Agent-OS and no recent releases of it, it's getting harder to remember what I've updated and what has not.

@CasJam what is the plan for getting PR's reviewed for Agent-OS?

[Perlover]

Do you have a fork of Agent-os that has all your improvements? I've been copying over bits and pieces here and there, but with none of these getting merged into Agent-OS and no recent releases of it, it's getting harder to remember what I've updated and what has not.

@CasJam what is the plan for getting PR's reviewed for Agent-OS?

Yes, of course, I have a fork of this project; otherwise, I would not be able to propose patches in this issue/pull request to which you have just replied. If you want to install my agent-os (that is, my version) “very easily and simply,” then I suggest the following:

curl -sSL "https://raw.githubusercontent.com/Perlover/agent-os/fix/implementer-task-completion-rules/scripts/base-install.sh" \
    | sed 's|buildermethods/agent-os|Perlover/agent-os|g; s|/raw/main/|/raw/fix/implementer-task-completion-rules/|g; s|branch="main"|branch="fix/implementer-task-completion-rules"|g' \
    > /tmp/install-fixed.sh && bash /tmp/install-fixed.sh

[Perlover]

Also, just yesterday I added another commit that I believe is very important. The issue is that the latest code started converting skills into commands for loading. The problem is that when agent-os converts profile standards into skills, and then you additionally run the /improve-skills command, you still end up with skills whose name field exists, but whose title is represented simply as English words separated by spaces. This is exactly what causes the problem with the new feature I mentioned earlier.

When you press the slash, you will see all skills, including those standards that were converted into skills. However, you will notice that if you select at least one of those skills, it will report that the command was not found. This appears to be related to an implicit or undocumented rule in Claude Code, according to which skill names are apparently required to be in kebab-case. That requirement is not met when agent-os converts standards into skills (even when /improve-skills is invoked). The latest commit should also address this issue (patched /improve-skills command)

[Perlover]

I have also just improved the improve-skills command. In the previous version—the original one—it contained only a link to the Claude company website, stating that the rules for writing skills were located there. I consider this approach incorrect, because it implicitly assumes that every time this command is run, Claude Code will go to the internet, download those rules again, and study them. I do not think it actually does this; and even if it does, it would be in a very superficial way.

I reworked this command. I already had my own, well-developed skills for writing skills, which I had carefully refined based on the Claude Code documentation. I enhanced the command using my own skill for writing skills, so that the Improve Skills command does everything it did before, but now contains the documentation on how to act directly within the command itself. This way, it does not need to go to the internet to search for anything, and its behavior is always aligned with a single, consistent prompt.

[Perlover]

Last commit: e7856f1

Add Impact Analysis to Spec Writing Workflow

Problem

Current workflow searches for reusable code but not all affected code.

When refactoring shared constants/types, specs miss:

• Duplicate definitions in other packages
• Hardcoded values that should be updated
• Subsystems not obvious from the main codebase

Result: specs look complete but implementation breaks things.

Solution

Add impact analysis at three stages:

1. research-spec.md - Ask users about OTHER areas using the same constants (background jobs, scripts, config, tests)

2. write-spec.md - New Step 2.5 with grep commands to find ALL usages and detect duplicates

3. create-tasks-list.md - New Step 1.5 to verify spec completeness before creating tasks

Why

Without this, a spec for "modify constant X" might update the main package but miss another package that has its own copy of the same constant. The code compiles, tests pass in isolation, but production breaks.