diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 8283924..9c4f975 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -8,7 +8,7 @@ "plugins": [ { "name": "dev-workflow", - "description": "Complete development workflow: brainstorming, planning, TDD, debugging, subagent execution, code review, PR merge", + "description": "Complete development workflow: brainstorming, planning, TDD, debugging, agent team execution, subagent fallback, code review, PR merge", "source": "./" } ] diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index a14ceb6..f0ecbf4 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-workflow", "version": "2.2.0", - "description": "Complete development workflow: brainstorming, planning, TDD, debugging, subagent execution, code review, PR merge", + "description": "Complete development workflow: brainstorming, planning, TDD, debugging, agent team execution, subagent fallback, code review, PR merge", "author": { "name": "Tom Baker", "url": "https://github.com/tombakerjr" @@ -12,6 +12,7 @@ "keywords": [ "workflow", "code-review", + "agent-teams", "subagent", "implementation", "development" diff --git a/CLAUDE.md b/CLAUDE.md index 603d5b7..1d8e51a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -27,7 +27,8 @@ claude-code-pr-workflow/ │ ├── pr-merge.md # /pr-merge │ └── context-recovery.md # /context-recovery ├── skills/ # Workflow skills -│ ├── subagent-driven-development/ # Execute implementation plans +│ ├── agent-team-development/ # Parallel agent teams (preferred) +│ ├── subagent-driven-development/ # Sequential subagent execution (fallback) │ ├── test-driven-development/ # TDD workflow │ ├── systematic-debugging/ # Debug root cause analysis │ ├── writing-plans/ # Create implementation plans @@ -37,6 +38,7 @@ claude-code-pr-workflow/ │ ├── hooks.json # Hook configuration │ ├── run-hook.cmd # Cross-platform wrapper │ ├── git-guard.py # PreToolUse: block main push +│ ├── task-completed-gate.py # TaskCompleted: review gate for agent teams │ └── stop-check.sh # Stop: warn on uncommitted ├── CLAUDE.md └── README.md @@ -105,7 +107,8 @@ Skills provide structured workflows for common development tasks: - "Use dev-workflow:brainstorming" - Start design dialogue for new features - "Use dev-workflow:systematic-debugging" - Debug with root cause analysis - "Use dev-workflow:writing-plans" - Create implementation plan with tasks -- "Use dev-workflow:subagent-driven-development" - Execute implementation plans with independent tasks +- "Use dev-workflow:agent-team-development" - Execute plans with parallel agent teams (preferred, falls back to subagent-driven-development) +- "Use dev-workflow:subagent-driven-development" - Execute implementation plans with sequential subagents (fallback) - "Use dev-workflow:test-driven-development" - TDD workflow with test-first approach - "Use dev-workflow:using-git-worktrees" - Isolated git worktrees for complex features @@ -123,6 +126,7 @@ When compacting conversation history, preserve: - Git branch and last commit SHA - Any blockers or review feedback not yet addressed - PR number if one exists +- Active teammate names and worktree paths (if using agent teams) Discard: - Full file contents (can re-read) diff --git a/README.md b/README.md index 9e78670..6039274 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,8 @@ A comprehensive Claude Code plugin for feature development, bug fixes, and PR wo ## Features - **Upfront planning** - Brainstorming and structured implementation plans before code -- **Subagent execution** - Parallelized work with fresh context per task +- **Agent team execution** - True parallel implementation with multiple agents, dedicated reviewer, and mailbox communication +- **Subagent execution** - Sequential execution with fresh context per task (fallback) - **Git worktree support** - Isolated workspaces for parallel development - **Pre-commit verification** - Type checking, security scans, debug code detection - **PR merge checklist** - CI verification, delayed comment detection, blocker scanning @@ -20,17 +21,24 @@ This plugin enforces three core principles: ### 1. Planning Before Implementation Features start with **brainstorming** (Socratic exploration of requirements and design), followed by **writing plans** that break work into bite-sized, verifiable tasks. This catches issues early and provides clear success criteria. -### 2. Subagents for Context Hygiene -Implementation uses **subagent-driven development** where: +### 2. Agent Teams for True Parallelism +When agent teams are enabled, **agent-team-development** provides: +- Multiple implementers working simultaneously in separate git worktrees +- Dedicated reviewer communicating feedback directly via mailbox +- Lead coordinator in delegate mode for orchestration-only +- Automatic fallback to subagent-driven-development when teams aren't available + +### 3. Subagents for Context Hygiene +**Subagent-driven development** (fallback) provides: - Main conversation stays clean (planning and orchestration) - Each task gets fresh context (implementer subagent reads files it needs) - Prevents context bloat from 50k+ token file dumps - Enables independent work verification -### 3. Parallelization Through Isolation -**Git worktrees** + subagents enable true parallel development: +### 4. Parallelization Through Isolation +**Git worktrees** + agents enable true parallel development: - Multiple features/experiments in isolated workspaces -- Subagents work independently without blocking +- Agents work independently without blocking - Easy cleanup (delete worktree, no branch pollution) ## Complete Development Workflow @@ -44,9 +52,13 @@ flowchart TD D --> E[Create isolated workspace] E --> F[Writing-plans skill] F --> G["Break into tasks with acceptance criteria"] - G --> H[Subagent-driven-development skill] - H --> I["Parallel execution with fresh context"] - I --> J["/pr-create"] + G --> H{Agent teams enabled?} + H -->|Yes| I1[Agent-team-development skill] + I1 --> I2["Parallel implementers + reviewer in worktrees"] + H -->|No| I3[Subagent-driven-development skill] + I3 --> I4["Sequential execution with fresh context"] + I2 --> J["/pr-create"] + I4 --> J J --> K[PR ready] end @@ -84,7 +96,7 @@ flowchart TD | **1. Design** | `brainstorming` | Socratic exploration of requirements and design trade-offs | | **2. Isolate** | `using-git-worktrees` | Create isolated workspace (optional, for parallel work) | | **3. Plan** | `writing-plans` | Break feature into bite-sized tasks with acceptance criteria | -| **4. Execute** | `subagent-driven-development` | Parallel execution with fresh context per task | +| **4. Execute** | `agent-team-development` | Parallel agent teams (falls back to `subagent-driven-development`) | | **5. PR** | `/pr-create` | Typecheck, push, create PR | | **6. Merge** | `/pr-merge` | Full checklist with delayed comment detection | @@ -112,10 +124,11 @@ The plugin prevents common mistakes: When executing implementation plans (from `writing-plans` or similar), this plugin enforces: -- **Use**: `dev-workflow:subagent-driven-development` +- **Preferred**: `dev-workflow:agent-team-development` - parallel agent teams with worktree isolation +- **Fallback**: `dev-workflow:subagent-driven-development` - sequential subagents (when agent teams not enabled) - **Not**: Alternative execution methods that cause context bloat -Subagent-driven development keeps work in the current session with fresh context per task, avoiding context bloat from long-running executions. +Agent-team-development automatically detects whether agent teams are enabled and falls back to subagent-driven-development when they aren't. ## Installation @@ -165,7 +178,8 @@ Then restart Claude Code. | Skill | Description | |-------|-------------| -| `subagent-driven-development` | Execute implementation plans with parallel subagents and fresh context | +| `agent-team-development` | Execute plans with parallel agent teams, dedicated reviewer, and worktree isolation (preferred) | +| `subagent-driven-development` | Execute implementation plans with sequential subagents and fresh context (fallback) | | `test-driven-development` | Red-green-refactor discipline for features and bug fixes | | `systematic-debugging` | 4-phase root cause analysis: gather, hypothesize, verify, fix | | `writing-plans` | Create bite-sized task plans with acceptance criteria | @@ -177,8 +191,9 @@ Then restart Claude Code. | Hook | Event | Function | |------|-------|----------| | `git-guard.py` | PreToolUse:Bash | Blocks commits on main/master, blocks push to main/master, warns on raw `gh pr merge` | +| `task-completed-gate.py` | TaskCompleted | Prevents implementation tasks from being marked complete before review | | `stop-check.sh` | Stop | Warns about uncommitted changes, open PRs, changes on main | -| `workflow-preferences.sh` | SessionStart | Injects execution preferences (use subagent-driven-development) | +| `workflow-preferences.sh` | SessionStart | Injects execution preferences (use agent-team-development) | ## The Merge Checklist diff --git a/hooks/hooks.json b/hooks/hooks.json index f08e4e7..04edb99 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -24,6 +24,17 @@ ] } ], + "TaskCompleted": [ + { + "hooks": [ + { + "type": "command", + "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" task-completed-gate.py", + "timeout": 5 + } + ] + } + ], "SessionStart": [ { "hooks": [ diff --git a/hooks/task-completed-gate.py b/hooks/task-completed-gate.py new file mode 100755 index 0000000..3db55a6 --- /dev/null +++ b/hooks/task-completed-gate.py @@ -0,0 +1,110 @@ +#!/usr/bin/env python3 +""" +Task Completed Gate Hook - TaskCompleted hook for agent team development. +Prevents implementation tasks from being marked complete before review. + +When a teammate marks a task as complete, this hook checks whether +the task appears to be an implementation task that hasn't been reviewed. +If so, it blocks completion with a message directing review. + +Usage: Configure in hooks/hooks.json as a TaskCompleted hook. +""" +import json +import os +import sys +import re + + +# Patterns indicating an implementation task (matched against lowercased text) +IMPL_PATTERNS = [ + r'\b(implement|create|add|build|write|update|refactor|fix|migrate)\b', + r'\btask\s+\d+\.\d+\b', +] + +# Patterns indicating the task is primarily a review/meta task (not subject to review gate) +# These are narrow to avoid false negatives on implementation tasks containing "check" etc. +REVIEW_PATTERNS = [ + r'^review\b', + r'\breview\s+(this|the|task|code|changes|implementation)\b', + r'\bready\s+for\s+review\b', + r'^(meta|setup|cleanup|housekeeping)\b', + r'\b(spec|quality|staff)\s+review\b', +] + +# Patterns indicating task has already been reviewed (matched against lowercased text) +REVIEWED_INDICATORS = [ + r'\breviewed\b', + r'\bapproved\b', + r'\bpass\b', + r'\breview\s+passed\b', +] + + +def is_implementation_task(subject, description): + """Check if the task looks like an implementation task.""" + text = f"{subject} {description}".lower() + + # Check if subject primarily matches review/meta patterns (exclude from gate) + subject_lower = subject.lower() + for pattern in REVIEW_PATTERNS: + if re.search(pattern, subject_lower): + return False + + # Check if it matches implementation patterns + for pattern in IMPL_PATTERNS: + if re.search(pattern, text): + return True + + return False + + +def is_already_reviewed(subject, description): + """Check if the task shows signs of having been reviewed.""" + text = f"{subject} {description}".lower() + + for pattern in REVIEWED_INDICATORS: + if re.search(pattern, text): + return True + + return False + + +def main(): + # Only enforce review gate when agent teams are active + if not os.environ.get("CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS"): + sys.exit(0) + + try: + input_data = json.load(sys.stdin) + except (json.JSONDecodeError, IOError): + # Graceful fallback - don't block if we can't parse input + sys.exit(0) + + # Extract task information from the hook payload + tool_input = input_data.get("tool_input", {}) + subject = tool_input.get("subject", "") + description = tool_input.get("description", "") + + # If we can't determine task details, don't block + if not subject and not description: + sys.exit(0) + + # Check if this is an implementation task + if not is_implementation_task(subject, description): + sys.exit(0) + + # Check if it's already been reviewed + if is_already_reviewed(subject, description): + sys.exit(0) + + # Block completion - implementation task needs review first + print( + "Task requires review before completion. " + "Reviewer: please review this task before marking it complete.", + file=sys.stderr + ) + sys.exit(2) + + +if __name__ == "__main__": + main() diff --git a/hooks/workflow-preferences.sh b/hooks/workflow-preferences.sh index f41a60c..b6f8ddb 100755 --- a/hooks/workflow-preferences.sh +++ b/hooks/workflow-preferences.sh @@ -3,7 +3,7 @@ cat << 'EOF' { "hookSpecificOutput": { "hookEventName": "SessionStart", - "additionalContext": "Use subagent-driven-development for plan execution. Never commit to main. For new features: dev-workflow:brainstorming. For bugs: dev-workflow:systematic-debugging." + "additionalContext": "Use agent-team-development for plan execution (falls back to subagent-driven-development if agent teams not enabled). Never commit to main. For new features: dev-workflow:brainstorming. For bugs: dev-workflow:systematic-debugging." } } EOF diff --git a/skills/agent-team-development/SKILL.md b/skills/agent-team-development/SKILL.md new file mode 100644 index 0000000..00462c9 --- /dev/null +++ b/skills/agent-team-development/SKILL.md @@ -0,0 +1,359 @@ +--- +name: agent-team-development +description: Use when executing implementation plans with parallel agent teams (falls back to subagent-driven-development if agent teams not enabled) +--- + +# Agent Team Development + +Execute plans with parallel agent teams: multiple implementers in git worktrees, a dedicated reviewer, and a lead coordinator. Falls back to subagent-driven-development when agent teams aren't available. + +**Core principle:** True parallel execution with bidirectional communication via mailbox. + +## When to Use + +- Have an implementation plan with tasks and recommended models +- Tasks are parallelizable (multiple can run simultaneously) +- Want true parallel execution across worktrees +- Agent teams enabled (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` env var set) + +**Automatic fallback:** If the env var is not set, invoke `dev-workflow:subagent-driven-development` instead. + +## Fallback Check + +Before anything else: + +```bash +if [ -z "$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" ]; then + # Agent teams not enabled - fall back + # Invoke: dev-workflow:subagent-driven-development +fi +``` + +If the env var is not set, immediately invoke `dev-workflow:subagent-driven-development` with the same plan. Do not proceed with team setup. + +## Team Structure + +| Role | Count | Model | Responsibility | +|------|-------|-------|----------------| +| **Lead (you)** | 1 | opus | Orchestration-only (delegate mode). Reads plan, creates shared tasks, monitors progress, performs phase/final reviews. | +| **Implementers** | 2-3 | sonnet (or per plan) | Each in own git worktree. Self-claim tasks from shared task list. Pull latest before each task. Commit to shared feature branch. | +| **Reviewer** | 1 | sonnet | Persistent teammate. Watches for completed implementation tasks. Reviews and sends feedback directly to implementers via mailbox. | + +**Implementer count:** +- 2 implementers for plans with ≤4 tasks +- 3 implementers for plans with 5+ tasks + +## Task Classification + +Classify each task before creating shared tasks: + +| Complexity | Impl Model | Review Path | Indicators | +|------------|------------|-------------|------------| +| SIMPLE | haiku (if plan says) | quick-reviewer only | ≤2 files, config, boilerplate, mechanical | +| STANDARD | sonnet (default) | spec + quality review | Multi-file, business logic, error handling | +| COMPLEX | sonnet or opus | spec + quality + extra scrutiny | Only if plan explicitly requires | + +## The Complete Flow + +``` +FALLBACK CHECK +====================================================================== +1. Check CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env var + If NOT set → invoke dev-workflow:subagent-driven-development instead + If set → continue with team setup + +SETUP +====================================================================== +2. Ensure on feature branch (create if needed) +3. Read plan, extract ALL tasks with: + - Full task text + - Recommended model (default: sonnet) + - Complexity classification (SIMPLE/STANDARD/COMPLEX) + - Dependencies between tasks + - Parallelizable: yes/no +4. Determine implementer count (2 for ≤4 tasks, 3 for 5+) + +WORKTREE SETUP +====================================================================== +5. Create git worktrees for each implementer: + Pattern: ../REPO-team-BRANCH-impl-N + + Example for repo "my-app" on branch "feature/auth": + ../my-app-team-feature-auth-impl-1 + ../my-app-team-feature-auth-impl-2 + ../my-app-team-feature-auth-impl-3 + + Commands: + git worktree add ../REPO-team-BRANCH-impl-1 HEAD + git worktree add ../REPO-team-BRANCH-impl-2 HEAD + ... + +DELEGATE MODE +====================================================================== +6. Enter delegate mode (Shift+Tab) + Lead becomes orchestration-only from this point. + +SPAWN TEAMMATES +====================================================================== +7. Spawn implementer teammates (one per worktree) +8. Spawn reviewer teammate + +CREATE SHARED TASKS +====================================================================== +9. Create shared tasks from plan (all phases or current phase) + Each task includes: + - Task title from plan + - Full description with acceptance criteria + - Complexity classification + - Model recommendation + - Phase number + +EXECUTION +====================================================================== +10. Implementers self-claim tasks from shared task list +11. Each implementer: + a. Pull latest from feature branch + b. Implement the task in their worktree + c. Run tests and self-verify + d. Commit to feature branch + e. Push to remote + f. Mark task ready for review + +12. Reviewer watches for ready-for-review tasks: + SIMPLE tasks: + - Quick review (spec + quality combined) + - Send PASS/FAIL via mailbox to implementer + + STANDARD+ tasks: + - Spec review (does it match acceptance criteria?) + - Quality review (code quality, patterns, tests) + - Send PASS/FAIL via mailbox to implementer + +13. Fix loops (via mailbox): + - Reviewer sends feedback directly to implementer + - Implementer fixes, re-commits, re-pushes + - Reviewer re-reviews + - Max 3 attempts, then escalate to lead + +PHASE BOUNDARY +====================================================================== +14. Wait for all tasks in phase to complete + pass review +15. Skip phase review if ALL tasks in phase were SIMPLE +16. Otherwise: Lead performs staff-code-reviewer on phase commits + Commits: [phase_start_sha]..[current_sha] + + If CRITICAL/IMPORTANT issues: + → Assign fix to an implementer via shared task + → Re-verify after fix + → Re-run staff-code-reviewer (max 2 attempts) + +FINAL +====================================================================== +17. Lead performs final staff-code-reviewer (opus) on entire implementation +18. Clean up worktrees: + git worktree remove ../REPO-team-BRANCH-impl-1 + git worktree remove ../REPO-team-BRANCH-impl-2 + ... +19. Create PR (follow repo template if exists) +20. Invoke /pr-merge workflow (or user invokes manually) +``` + +## Spawn Prompt Templates + +### Implementer Spawn Prompt + +``` +You are an implementer on an agent team. Your role is to pick up tasks +from the shared task list, implement them, and commit your work. + +## Your Worktree +Working directory: [WORKTREE_PATH] +Feature branch: [BRANCH_NAME] + +## Workflow +1. Check the shared task list for unclaimed tasks +2. Claim a task by marking it in_progress +3. Before starting: git pull to get latest changes +4. Implement the task following its acceptance criteria +5. Run tests and verify your changes +6. Commit with conventional message: feat|fix|refactor: description +7. Push to remote: git push +8. Mark the task as ready for review (add "READY FOR REVIEW" to task) +9. Wait for reviewer feedback via mailbox +10. If reviewer requests fixes: fix, commit, push, notify reviewer +11. Once approved: move to next task + +## Guidelines +- Follow project conventions from CLAUDE.md +- Write tests as specified in the task's testing approach +- Keep commits focused on the task +- Pull before each new task to avoid conflicts +- If blocked or confused, message the lead for guidance +- Use the model recommended in the task (haiku for SIMPLE, sonnet for STANDARD) + +## Task Claiming +- Only claim tasks that are not blocked by incomplete dependencies +- Prefer tasks in the current phase +- If all remaining tasks have dependencies, wait or ask lead +``` + +### Reviewer Spawn Prompt + +``` +You are the reviewer on an agent team. Your role is to review completed +implementation tasks and provide feedback directly to implementers. + +## Workflow +1. Watch the shared task list for tasks marked "READY FOR REVIEW" +2. For each ready task: + + SIMPLE tasks (≤2 files, config, boilerplate): + - Quick combined spec + quality review + - Check: Does it match acceptance criteria? + - Check: Code quality acceptable? + - Send PASS or feedback via mailbox to the implementer + + STANDARD+ tasks: + - Spec review: Does implementation match acceptance criteria exactly? + - Quality review: Code quality, patterns, test coverage, error handling + - Send PASS or detailed feedback via mailbox to the implementer + +3. If you send feedback (FAIL): + - Be specific: file, line, issue, suggested fix + - Use structured format: + ## Review Feedback (Attempt N of 3) + Status: [spec_failure|quality_failure] + File: path/to/file + Issues: + 1. Line N: [issue] -> [fix] + - Wait for implementer to fix and re-submit + - Re-review the fixes + - Max 3 review rounds per task + +4. If fixes fail after 3 attempts: + - Message the lead with escalation details + - Include: task name, issue description, what was tried + +## Review Standards +- Match acceptance criteria exactly (spec) +- No security vulnerabilities (quality) +- Tests present and meaningful (quality) +- Follows project patterns from CLAUDE.md (quality) +- No over-engineering or scope creep (quality) + +## Communication +- Use mailbox to communicate with implementers +- Be concise but specific in feedback +- Acknowledge good work on PASS +``` + +## Fix Loop Severity + +Classify fix complexity (same as subagent-driven-development): + +| Fix Type | Model | Max Attempts | Indicators | +|----------|-------|--------------|------------| +| MINOR | haiku (override) | 2 | Typo, missing import, lint fix | +| STANDARD | sonnet | 2 | Logic error, error handling, test fix | +| COMPLEX | sonnet -> opus (with approval) | 2 + escalate | Architectural feedback, multi-file fix | + +## Escalation + +**Escalate to user (lead asks) when:** +- Fix loop exceeds max attempts (3 task-level, 2 phase-level) +- Reviewer and implementer disagree after 3 rounds +- Security concern needs judgment +- Architectural decision needed +- Merge conflicts between worktrees that can't be auto-resolved + +``` +ESCALATION NEEDED + +Task: [N name] +Issue: [what's blocking] +Attempts: [N of max] +Last feedback: [reviewer's comment] + +Options: +1. [suggested approach] +2. [alternative] +3. Skip and document as known issue +``` + +## Worktree Management + +### Creation (during setup) + +```bash +# Get repo name and branch for naming +REPO_NAME=$(basename "$(git rev-parse --show-toplevel)") +BRANCH_NAME=$(git branch --show-current | tr '/' '-') + +# Create worktrees +git worktree add "../${REPO_NAME}-team-${BRANCH_NAME}-impl-1" HEAD +git worktree add "../${REPO_NAME}-team-${BRANCH_NAME}-impl-2" HEAD +# Add impl-3 if 5+ tasks +``` + +### Cleanup (during final) + +```bash +git worktree remove "../${REPO_NAME}-team-${BRANCH_NAME}-impl-1" +git worktree remove "../${REPO_NAME}-team-${BRANCH_NAME}-impl-2" +# Remove impl-3 if it exists +git worktree prune +``` + +### Conflict Prevention + +- Each implementer pulls before starting a new task +- Tasks should be designed to minimize file overlap +- If conflicts arise: implementer pulls, resolves, recommits +- Lead can reassign conflicting tasks to a single implementer + +## Red Flags + +**Never:** +- Skip the fallback check +- Skip verification after fixes +- Let fix loops run indefinitely +- Proceed with CRITICAL issues from phase review +- Use opus for every implementation task +- Leave worktrees behind after completion + +**Always:** +- Check for agent teams env var before proceeding +- Enter delegate mode before spawning teammates +- Classify task complexity before creating shared tasks +- Use structured feedback format for reviews +- Clean up worktrees during final step +- Track review attempts per task +- Escalate when stuck + +## Model Selection + +| Role | Default Model | Override | +|------|---------------|---------| +| Lead (orchestration) | opus | - | +| Implementer (standard) | sonnet | haiku if plan says | +| Implementer (simple) | sonnet | haiku if plan says | +| Reviewer | sonnet | - | +| Staff reviewer (phase/final) | opus | - | + +## Integration + +**Uses:** +- Shared task list (agent teams feature) for work coordination +- Mailbox (agent teams feature) for reviewer <-> implementer communication +- Git worktrees for workspace isolation +- `dev-workflow:staff-code-reviewer` - phase/final reviews (run by lead) +- `/pr-merge` command - CI check, comment assessment, merge + +**Falls back to:** +- `dev-workflow:subagent-driven-development` - when agent teams not enabled + +**Works with:** +- `dev-workflow:writing-plans` - creates plans with model recommendations and parallelizable field +- `dev-workflow:brainstorming` - design exploration before planning +- `dev-workflow:systematic-debugging` - bug investigation workflow +- `dev-workflow:test-driven-development` - TDD discipline for implementation diff --git a/skills/systematic-debugging/SKILL.md b/skills/systematic-debugging/SKILL.md index 81ce63d..8f2966d 100644 --- a/skills/systematic-debugging/SKILL.md +++ b/skills/systematic-debugging/SKILL.md @@ -112,7 +112,7 @@ Don't keep trying variations. If 3 attempts failed, your understanding is incomp - Follows 4-phase framework to understand failure - Uses TDD to implement fix -**Works with `dev-workflow:subagent-driven-development`:** +**Works with `dev-workflow:agent-team-development` / `dev-workflow:subagent-driven-development`:** - When verification step fails, orchestrator may invoke debugger - Debugger identifies root cause, TDD implements fix - Re-verify in main workflow loop diff --git a/skills/using-git-worktrees/SKILL.md b/skills/using-git-worktrees/SKILL.md index b73789f..49f7a0c 100644 --- a/skills/using-git-worktrees/SKILL.md +++ b/skills/using-git-worktrees/SKILL.md @@ -14,7 +14,7 @@ When running multiple implementer agents in parallel or executing implementation ## When to Use This Skill **Always use for:** -- Executing implementation plans with `dev-workflow:subagent-driven-development` +- Executing implementation plans with `dev-workflow:agent-team-development` (or `subagent-driven-development` fallback) - Running multiple implementer agents in parallel - Starting feature work that needs isolation from main workspace - Working on multiple features simultaneously without switching branches @@ -224,6 +224,11 @@ cd /home/tbaker/workspace/claude-code-workflows - Then invoke writing-plans in the worktree context - Implementation plan executes in clean, isolated environment +**Works with `dev-workflow:agent-team-development`:** +- Agent teams create per-implementer worktrees automatically +- Provides true parallel execution with worktree isolation +- Reviewer and implementers communicate via mailbox + **Works with `dev-workflow:subagent-driven-development`:** - Worktree provides isolated workspace for plan execution - Prevents git index conflicts between parallel implementers diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md index 6416894..ecc1de9 100644 --- a/skills/writing-plans/SKILL.md +++ b/skills/writing-plans/SKILL.md @@ -5,7 +5,7 @@ description: Use when you have a spec or requirements for a multi-step task, bef # Writing Implementation Plans -Create structured plans that chain to subagent-driven-development for execution. +Create structured plans that chain to agent-team-development (or subagent-driven-development) for execution. **Core principle:** Plan with bite-sized tasks, model recommendations, and TDD embedded. @@ -26,7 +26,7 @@ Create structured plans that chain to subagent-driven-development for execution. ```markdown # Implementation Plan: [Feature/Component Name] -**Skill:** `dev-workflow:subagent-driven-development` +**Skill:** `dev-workflow:agent-team-development` ## Overview [1-2 sentences on what we're building and why] @@ -40,6 +40,7 @@ Create structured plans that chain to subagent-driven-development for execution. ### Task 1.1: [Brief imperative title] **Model:** haiku | sonnet | opus **Complexity:** SIMPLE | STANDARD | COMPLEX +**Parallelizable:** yes | no [Description of what to implement] @@ -92,6 +93,7 @@ Choose model based on task complexity: ### Task 1.1: Add user authentication endpoint **Model:** sonnet **Complexity:** STANDARD +**Parallelizable:** yes Create POST /auth/login endpoint that validates credentials and returns JWT token. @@ -222,7 +224,7 @@ If dependencies exist: ```markdown # Implementation Plan: Add Health Check Endpoint -**Skill:** `dev-workflow:subagent-driven-development` +**Skill:** `dev-workflow:agent-team-development` ## Overview Add GET /health endpoint that returns service status and dependencies. @@ -236,6 +238,7 @@ Add GET /health endpoint that returns service status and dependencies. ### Task 1.1: Create health check endpoint **Model:** haiku **Complexity:** SIMPLE +**Parallelizable:** yes Add GET /health that returns 200 OK with JSON status. @@ -251,6 +254,7 @@ Add GET /health that returns 200 OK with JSON status. ### Task 1.2: Add database health check **Model:** sonnet **Complexity:** STANDARD +**Parallelizable:** no Extend health endpoint to check database connectivity. @@ -270,6 +274,7 @@ Extend health endpoint to check database connectivity. ### Task 1.3: Add documentation **Model:** haiku **Complexity:** SIMPLE +**Parallelizable:** yes Document the health check endpoint in API docs. @@ -295,7 +300,7 @@ Document the health check endpoint in API docs. ```markdown # Implementation Plan: User Profile Management -**Skill:** `dev-workflow:subagent-driven-development` +**Skill:** `dev-workflow:agent-team-development` ## Overview Implement CRUD operations for user profiles with validation and permissions. @@ -309,6 +314,7 @@ Implement CRUD operations for user profiles with validation and permissions. ### Task 1.1: Create profile data model **Model:** haiku **Complexity:** SIMPLE +**Parallelizable:** yes Define TypeScript interface and database schema for user profiles. @@ -324,6 +330,7 @@ Define TypeScript interface and database schema for user profiles. ### Task 1.2: Implement GET /profile/:id **Model:** sonnet **Complexity:** STANDARD +**Parallelizable:** yes Create endpoint to fetch user profile by ID. @@ -342,6 +349,7 @@ Create endpoint to fetch user profile by ID. ### Task 1.3: Implement PUT /profile/:id **Model:** sonnet **Complexity:** STANDARD +**Parallelizable:** yes Create endpoint to update user profile with permission checks. @@ -366,6 +374,7 @@ Create endpoint to update user profile with permission checks. ### Task 2.1: Add profile picture upload **Model:** sonnet **Complexity:** STANDARD +**Parallelizable:** yes Allow users to upload profile pictures with validation. @@ -388,6 +397,7 @@ Allow users to upload profile pictures with validation. ### Task 2.2: Add profile search **Model:** sonnet **Complexity:** STANDARD +**Parallelizable:** yes Create endpoint to search profiles by name or email. @@ -420,7 +430,8 @@ Create endpoint to search profiles by name or email. ## Integration **Creates plans for:** -- `dev-workflow:subagent-driven-development` - executes the plan +- `dev-workflow:agent-team-development` - preferred execution (parallel agent teams) +- `dev-workflow:subagent-driven-development` - fallback execution (sequential subagents) **Works with:** - `dev-workflow:brainstorming` - use before planning if requirements unclear @@ -432,21 +443,24 @@ Create endpoint to search profiles by name or email. ✅ Plan has clear phases and bite-sized tasks ✅ Every task specifies model (haiku/sonnet/opus) ✅ Every task classified by complexity (SIMPLE/STANDARD/COMPLEX) +✅ Every task specifies parallelizable (yes/no) ✅ Tasks that write code include testing approach ✅ Acceptance criteria are specific and testable ✅ Review checkpoints identified -✅ Plan chains to subagent-driven-development for execution +✅ Plan chains to agent-team-development for execution ## Chains To After writing plan, invoke: ``` -/skill dev-workflow:subagent-driven-development +/skill dev-workflow:agent-team-development ``` +This will automatically fall back to `subagent-driven-development` if agent teams are not enabled. + The execution skill will: 1. Read this plan 2. Extract all tasks with model recommendations -3. Dispatch implementer per task (using recommended model) +3. Set up parallel implementers (or sequential subagents for fallback) 4. Run verification and reviews at specified checkpoints 5. Complete implementation following the plan structure