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