feat: add agent-team-development skill with parallel execution

[tombakerjr]

Summary

• Adds agent-team-development skill as the preferred plan execution method, enabling true parallel implementation with multiple agent teammates in git worktrees, a dedicated reviewer, and lead coordinator
• Adds task-completed-gate.py hook to prevent implementation tasks from being marked complete before review (only active when agent teams are enabled)
• Updates all documentation, config, and sibling skill cross-references for consistency
• Automatic fallback to subagent-driven-development when CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env var is not set

Test plan

• Verify skill file loads correctly when plugin is active
• Test hook with sample JSON input piped to stdin (with and without env var)
• Verify SessionStart hook shows updated preference message
• Confirm writing-plans references point to correct skill
• Check all documentation references are consistent
• End-to-end: invoke skill on a multi-task plan with agent teams enabled

🤖 Generated with Claude Code

[claude]

Claude finished @tombakerjr's task in 1m 23s —— View job

---

Code Review

• Read project context (CLAUDE.md)
• Review new skill file (agent-team-development/SKILL.md)
• Review new hook (task-completed-gate.py)
• Review hook configuration (hooks.json)
• Review documentation updates
• Check for security/bugs/tests/considerations
• Post final review

---

Review Findings

FIX: hooks/task-completed-gate.py:74 - Environment variable check may fail silently in edge cases

if not os.environ.get("CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS"):

The check only verifies the env var exists but doesn't validate it's actually set to a truthy value. An empty string "" would pass get() but fail the not check correctly, but there's ambiguity. Consider explicit check: if os.environ.get("CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS") != "true" if the var is meant to be a boolean flag.

CONSIDER: skills/agent-team-development/SKILL.md:26-32 - Fallback check logic duplication
The fallback check bash snippet shows manual checking, but the actual implementation might be automated. If this is guidance for Claude following the skill, consider clarifying whether Claude should execute this check or if it's handled by infrastructure. If Claude must check, the pattern could be error-prone (what if they forget?).

CONSIDER: hooks/task-completed-gate.py:18-22 - Implementation patterns could have false positives
The regex r'\b(implement|create|add|build|write|update|refactor|fix|migrate)\b' will match many legitimate non-implementation tasks like "Review and update documentation" or "Fix typos in comments". The REVIEW_PATTERNS help filter these out, but the ordering matters (line 48-51 checks subject for review patterns before checking for impl patterns). This could incorrectly classify tasks.

Example edge case: A task with subject "Update authentication module" would match IMPL_PATTERNS but may not match REVIEW_PATTERNS, triggering the review gate even if it's just a documentation update.

TEST: No automated tests for task-completed-gate.py
The hook script has complex regex matching logic but no test coverage. Consider adding unit tests to verify:

• Implementation task detection accuracy
• Review pattern filtering works correctly
• Edge cases like "Review and update code" (which is implementation despite containing "review")
• Empty/missing subject/description handling

CONSIDER: skills/agent-team-development/SKILL.md:286-305 - Worktree cleanup not in error paths
The worktree cleanup (lines 300-305) is only shown in the "FINAL" section of the flow. If the workflow fails mid-execution (e.g., escalation to user, unrecoverable error), orphaned worktrees could remain. Consider documenting cleanup-on-error handling or making this more prominent.

---

Summary

The PR adds valuable parallel execution capabilities with good design. The main concerns are:

1. Fix recommended: Environment variable validation in the hook could be more explicit
2. Tests needed: Hook script has no automated test coverage despite complex logic
3. Consider: Task classification regex may have edge cases causing false positives
4. Consider: Error-path worktree cleanup not explicitly documented

The implementation is solid overall, but the hook script would benefit from test coverage before merge to catch classification edge cases.

---