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

[Perlover]

Summary

Add strict task completion rules, improve skills discovery, and enable Edit tool for all implementer agents. This prevents agents from falsely marking tasks as complete without actually executing them, aligns skills usage with Claude Code's built-in mechanisms, and allows efficient file modifications.

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 agents can use Edit tool for targeted file modifications (not just full file rewrites)

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: Missing Edit tool

Problem solved:
All agent files previously had only Write and Read tools in their YAML frontmatter, which meant agents could only:

• Write - create or overwrite entire files
• Read - read files

But they couldn't use Edit for targeted string replacements (old_string → new_string). This was inefficient when working with existing code, forcing agents to rewrite entire files for small changes.

Changes:
Added Edit tool to 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:
The Edit tool is the preferred approach in Claude Code for modifying existing files, as documented in the official Claude Code tool reference. It allows precise modifications without rewriting entire files, reducing the risk of accidentally losing content.

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
• Edit tool is additive - agents can still use Write when full file replacement is needed

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 frontmatter reference, the correct format for specifying multiple tools:

allowed-tools: Read, Write, Edit

From the agent creator documentation, agent files support a tools field:

---
name: [identifier]
description: [Use this agent when...]
model: inherit
color: [chosen-color]
tools: ["Tool1", "Tool2"]  # Optional
---

Important: Write and Edit are separate tools with different purposes:

• Write - creates or completely overwrites a file
• Edit - performs targeted string replacements (old_string → new_string)

Both should be included when agents need full file manipulation capabilities.