diff --git a/CLAUDE.md b/CLAUDE.md index 1d8e51a..5324497 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,8 +7,8 @@ This file provides guidance to Claude Code when working with this plugin. This is a comprehensive Claude Code plugin that supports the full development workflow: - **Planning**: Brainstorming, specification, and implementation planning - **Implementation**: Test-driven development, systematic debugging, and subagent-driven execution -- **Review**: Comprehensive code reviews with multiple agent tiers -- **Merge**: Pre-commit verification, PR merge checklists with delayed comment detection, and git guardrails +- **Review**: Comprehensive code reviews with multiple agent tiers, CI watching, and review comment polling +- **Merge**: Git guardrails, readiness checks via `/pr-status`, and review-driven fix loops ## Plugin Structure @@ -22,13 +22,10 @@ claude-code-pr-workflow/ │ ├── code-verifier.md # Pre-commit checks │ └── pr-verifier.md # Pre-merge checks ├── commands/ # Slash commands -│ ├── pr-create.md # /pr-create │ ├── pr-status.md # /pr-status -│ ├── pr-merge.md # /pr-merge │ └── context-recovery.md # /context-recovery ├── skills/ # Workflow skills -│ ├── agent-team-development/ # Parallel agent teams (preferred) -│ ├── subagent-driven-development/ # Sequential subagent execution (fallback) +│ ├── plan-execution/ # Execute plans (agent teams or subagents) │ ├── test-driven-development/ # TDD workflow │ ├── systematic-debugging/ # Debug root cause analysis │ ├── writing-plans/ # Create implementation plans @@ -81,18 +78,16 @@ When releasing: ## Key Workflows -### The Merge Checklist (Why This Matters) +### The PR Readiness Check (Why This Matters) -The `/pr-merge` command enforces: +The `/pr-status` command enforces: -1. **Typecheck** - Catch type errors before merge -2. **CI passes** - All checks must show passed -3. **Wait 10-12 seconds** - Review comments post AFTER CI passes -4. **Fetch ALL comments** - Don't miss delayed bot comments -5. **Scan for blockers** - CRITICAL, FIX, BLOCKER, DO NOT MERGE -6. **Only merge when clear** - Human verification required +1. **CI passes** - Watch all checks to completion +2. **Find the review comment** - Poll until the review bot's comment from the current CI run is found +3. **Read and assess** - Check for CRITICAL, FIX, BLOCKER, DO NOT MERGE +4. **Never report ready without the comment** - The review always posts; wait for it -**Never skip this checklist.** The 10-12 second wait catches review bot comments that post after CI completes. +The review bot posts 10-12 seconds after CI completes. `/pr-status` handles this automatically by polling with timestamp validation. The `plan-execution` skill uses `/pr-status` in a loop: check status, fix if needed, push, re-check until READY TO MERGE. ### Agent Invocation @@ -107,17 +102,15 @@ 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: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:plan-execution" - Execute plans with agent teams or subagents (auto-selects based on availability) - "Use dev-workflow:test-driven-development" - TDD workflow with test-first approach - "Use dev-workflow:using-git-worktrees" - Isolated git worktrees for complex features ## Customization Users should customize: -1. Typecheck commands in `/pr-create` and `/pr-merge` -2. Review criteria in `staff-code-reviewer.md` -3. Blocked patterns in `git-guard.py` +1. Review criteria in `staff-code-reviewer.md` +2. Blocked patterns in `git-guard.py` ## Compaction Hints diff --git a/README.md b/README.md index 6039274..8da6dbe 100644 --- a/README.md +++ b/README.md @@ -5,11 +5,10 @@ A comprehensive Claude Code plugin for feature development, bug fixes, and PR wo ## Features - **Upfront planning** - Brainstorming and structured implementation plans before code -- **Agent team execution** - True parallel implementation with multiple agents, dedicated reviewer, and mailbox communication -- **Subagent execution** - Sequential execution with fresh context per task (fallback) +- **Plan execution** - Parallel implementation via agent teams (worktrees + mailbox) or subagents (`run_in_background`), auto-selected - **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 +- **PR readiness checks** - CI verification, review comment polling, blocker scanning - **Git guardrails** - Blocks direct pushes to main, warns on raw merge commands - **Code review agents** - Staff-level comprehensive reviews - **Context recovery** - Restore state after context compaction @@ -21,21 +20,14 @@ 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. 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 - -### 4. Parallelization Through Isolation +### 2. Parallel Execution with Mode Selection +**Plan execution** automatically selects the best execution mode: +- **Team mode** (when agent teams enabled): Multiple implementers in worktrees, dedicated reviewer with mailbox communication, lead in delegate mode +- **Subagent mode** (default): Parallel dispatch via `run_in_background`, each subagent gets only what you pass it (lightweight context), independent model selection per task + +Subagent mode is more efficient for well-scoped tasks — subagents start fresh with just their prompt, avoiding full context loading overhead. + +### 3. Parallelization Through Isolation **Git worktrees** + agents enable true parallel development: - Multiple features/experiments in isolated workspaces - Agents work independently without blocking @@ -53,11 +45,11 @@ flowchart TD E --> F[Writing-plans skill] F --> G["Break into tasks with acceptance criteria"] G --> H{Agent teams enabled?} - H -->|Yes| I1[Agent-team-development skill] + H -->|Yes| I1["Plan-execution: team mode"] 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"] + H -->|No| I3["Plan-execution: subagent mode"] + I3 --> I4["Parallel dispatch with lightweight context"] + I2 --> J["Push + create PR"] I4 --> J J --> K[PR ready] end @@ -68,7 +60,7 @@ flowchart TD N --> O[Test-driven-development skill] O --> P["Red → Green → Refactor"] P --> Q[Commit fix] - Q --> R["/pr-create"] + Q --> R["Push + create PR"] R --> K end @@ -77,8 +69,8 @@ flowchart TD S --> T{Approved?} T -->|No| U[Address feedback] U --> S - T -->|Yes| V["/pr-merge"] - V --> W["Checklist: typecheck, CI, poll for review comment, scan"] + T -->|Yes| V["/pr-status"] + V --> W["Watch CI, find review comment, scan for blockers"] W --> X{Blockers?} X -->|Yes| U X -->|No| Y[Merge & cleanup] @@ -96,9 +88,8 @@ 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** | `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 | +| **4. Execute** | `plan-execution` | Parallel via agent teams or subagents (auto-selected) | +| **5. PR & Merge** | `/pr-status` | Watch CI, find review comment, fix loop until ready, merge | ### Bug Fix Path @@ -107,8 +98,7 @@ flowchart TD | **1. Analyze** | `systematic-debugging` | 4-phase root cause analysis (gather, hypothesize, verify, fix) | | **2. Test** | `test-driven-development` | Red-green-refactor discipline | | **3. Commit** | N/A | Commit fix with conventional message | -| **4. PR** | `/pr-create` | Create PR for review | -| **5. Merge** | `/pr-merge` | Full merge checklist | +| **4. PR & Merge** | `/pr-status` | Create PR, watch CI, review comment check, merge | ### Git Guards @@ -118,17 +108,14 @@ The plugin prevents common mistakes: |--------|---------|-------------------| | `git commit` | Blocked | Allowed | | `git push origin main` | Blocked | N/A | -| `gh pr merge` | Warned (use /pr-merge) | Warned (use /pr-merge) | +| `gh pr merge` | Warned (run /pr-status first) | Warned (run /pr-status first) | ### Execution Preference -When executing implementation plans (from `writing-plans` or similar), this plugin enforces: - -- **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 +When executing implementation plans (from `writing-plans` or similar), use `dev-workflow:plan-execution`. It automatically selects the best mode: -Agent-team-development automatically detects whether agent teams are enabled and falls back to subagent-driven-development when they aren't. +- **Team mode** (agent teams enabled): parallel teammates in worktrees with mailbox communication +- **Subagent mode** (default): parallel dispatch via `run_in_background` with lightweight context per task ## Installation @@ -157,9 +144,7 @@ Then restart Claude Code. | Command | Description | |---------|-------------| -| `/pr-create` | Verify branch, typecheck, push, create PR with template | -| `/pr-status` | Quick CI + comments + blockers overview | -| `/pr-merge` | **Full merge checklist** - never skip this | +| `/pr-status` | **Watch CI, find review comment, scan for blockers, report readiness** | | `/context-recovery` | Recover git/PR state after context compaction | ### Agents @@ -178,8 +163,7 @@ Then restart Claude Code. | Skill | Description | |-------|-------------| -| `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) | +| `plan-execution` | Execute implementation plans — agent teams (worktrees + mailbox) or subagents (`run_in_background`), auto-selected | | `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 | @@ -193,38 +177,31 @@ Then restart Claude Code. | `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 agent-team-development) | +| `workflow-preferences.sh` | SessionStart | Injects execution preferences (use plan-execution) | -## The Merge Checklist +## The PR Readiness Check -The `/pr-merge` command enforces this critical workflow: +The `/pr-status` command enforces this critical workflow: -1. **Typecheck** - Catch type errors before merge -2. **CI passes** - Use `gh pr checks --watch` to wait for completion -3. **Poll for review comment** - Claude review ALWAYS posts a comment -4. **Scan for blockers** - CRITICAL, FIX, BLOCKER, DO NOT MERGE -5. **Only merge when clear** - Human verification required +1. **CI passes** — Watch all checks to completion with `gh pr checks --watch` +2. **Find the review comment** — Poll until the review bot's comment from the current CI run is found +3. **Read and assess** — Check for CRITICAL, FIX, BLOCKER, DO NOT MERGE +4. **Report verdict** — READY TO MERGE or CHANGES NEEDED with specifics -**Why poll for the review comment?** Claude code review ALWAYS posts a comment (either approving or requesting fixes). The absence of this comment is NOT tacit approval - we poll until found to ensure no review feedback is missed. +**Why poll for the review comment?** The review workflow ALWAYS posts a comment (either approving or requesting changes). The absence of this comment is NOT tacit approval — `/pr-status` polls with timestamp validation to ensure no review feedback is missed. ## Usage Examples -### Creating a PR +### Checking PR Readiness ``` -> Create a PR for my changes -# Claude runs /pr-create, which typechecks and creates PR -``` - -### Checking PR Status -``` -> What's the status of my PR? -# Claude runs /pr-status +> Is my PR ready to merge? +# Claude runs /pr-status — watches CI, finds review comment, reports verdict ``` ### Merging a PR ``` > Merge my PR -# Claude runs /pr-merge with full checklist +# Claude runs /pr-status first, then merges if READY TO MERGE ``` ### Code Review @@ -241,13 +218,6 @@ The `/pr-merge` command enforces this critical workflow: ## Customization -### Typecheck Commands - -Commands default to trying `pnpm run typecheck || npm run typecheck || yarn typecheck`. Edit the commands to match your project: - -- `commands/pr-create.md` -- `commands/pr-merge.md` - ### Review Criteria Add organization-specific review criteria to `agents/staff-code-reviewer.md`: diff --git a/agents/implementer.md b/agents/implementer.md index 1de5a52..011c4ba 100644 --- a/agents/implementer.md +++ b/agents/implementer.md @@ -1,6 +1,6 @@ --- name: implementer -description: Implementation agent with tooling conventions. Use for task implementation in subagent-driven-development workflow. +description: Implementation agent with tooling conventions. Use for task implementation in plan-execution workflow (subagent mode). model: sonnet --- diff --git a/commands/context-recovery.md b/commands/context-recovery.md index 1233252..029a488 100644 --- a/commands/context-recovery.md +++ b/commands/context-recovery.md @@ -45,9 +45,7 @@ If there's a CLAUDE.md, read it for project-specific workflow rules. - Fetch and review ALL comments - Check for CRITICAL/FIX/BLOCKER items 3. **Use workflow commands:** - - `/pr-create` - Create PR (runs typecheck) - - `/pr-status` - Check CI and comments - - `/pr-merge` - Safe merge with full checklist + - `/pr-status` - Watch CI, find review comment, report readiness ## Step 6: Summary diff --git a/commands/pr-create.md b/commands/pr-create.md deleted file mode 100644 index f043845..0000000 --- a/commands/pr-create.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -description: Create PR with typecheck verification and proper formatting -allowed-tools: Bash(git:*), Bash(gh:*), Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(tsc:*) ---- - -# Create Pull Request - -This command creates a PR after verifying code quality. - -## Step 1: Verify Branch - -!`git branch --show-current` - -**STOP if on main/master.** Create a feature branch first. - -## Step 2: Run Type Check - -Run your project's typecheck command. Try these in order until one works: - -```bash -pnpm run typecheck || npm run typecheck || yarn typecheck || tsc --noEmit -``` - -**STOP if typecheck fails.** Fix all errors before creating PR. - -## Step 3: Check for Uncommitted Changes - -!`git status --short` - -If there are uncommitted changes, commit them first with proper attribution. - -## Step 4: Push Branch - -Push the current branch to origin: - -```bash -git push -u origin $(git branch --show-current) -``` - -## Step 5: Create PR - -Construct PR with: -- Title: Brief description of changes -- Body: Summary, testing notes, attribution - -Format: -```markdown -## Summary -- Change 1 -- Change 2 - -## Testing -- [ ] Type check passes -- [ ] Manual testing completed - -## Notes - - ---- -Generated with [Claude Code](https://claude.ai/claude-code) -``` - -Create the PR: -```bash -gh pr create --title "TITLE" --body "BODY" -``` - -## Step 6: Confirm - -!`gh pr view --json number,url -q '"PR #\(.number): \(.url)"'` - -## Next Steps - -- Wait for CI to complete -- Use `/pr-status` to check CI and comments -- Use `/pr-merge` when ready to merge diff --git a/commands/pr-merge.md b/commands/pr-merge.md deleted file mode 100644 index c7c3cee..0000000 --- a/commands/pr-merge.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -description: Complete PR merge workflow - CI check, comment assessment, fix loop, merge, return to main -allowed-tools: Bash(gh:*), Bash(sleep:*), Bash(git:*), Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(tsc:*) ---- - -# PR Merge Workflow - -Complete merge workflow with CI verification, comment assessment, and fix loop if needed. - -## Step 1: Get PR Info - -!`gh pr view --json number,title,state,url,headRefName -q '"\(.number)|\(.title)|\(.state)|\(.url)|\(.headRefName)"'` - -Parse and display: PR number, title, state, URL, branch name. - -## Step 2: Verification - -**CI Trust Mode:** Skip local verification if ALL of these are true: -1. CI passed (check in Step 3) -2. CI completed within the last hour -3. No local uncommitted changes - -Check CI freshness: -```bash -# Get CI completion time and check if within 1 hour -CI_TIME=$(gh pr checks --json completedAt -q '.[0].completedAt' 2>/dev/null) -if [ -n "$CI_TIME" ]; then - CI_EPOCH=$(date -d "$CI_TIME" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%SZ" "$CI_TIME" +%s 2>/dev/null) - if [ -n "$CI_EPOCH" ]; then - NOW_EPOCH=$(date +%s) - AGE_MINS=$(( (NOW_EPOCH - CI_EPOCH) / 60 )) - echo "CI completed $AGE_MINS minutes ago" - [ $AGE_MINS -lt 60 ] && echo "CI is fresh - can use trust mode" || echo "CI is stale - run local verification" - else - echo "Unable to parse CI completion time - running local verification" - fi -fi -``` - -If CI is fresh and `git status` shows clean working tree, skip to Step 3. - -Otherwise, run full verification: - -```bash -pnpm typecheck && pnpm build && pnpm test -# or equivalent for project -``` - -**If verification fails:** Fix errors before proceeding. Do not continue. - -## Step 3: Check CI Status - -!`gh pr checks` - -**If checks pending:** Wait for all checks to complete. - -!`gh pr checks --watch` - -**If checks failed:** Stop. CI must pass before merge. - -## Step 4: Poll for Claude Review Comment - -The Claude code review ALWAYS posts a comment. Wait for it before proceeding. - -```bash -# Poll for Claude review comment -MAX_RETRIES=12 -RETRY_COUNT=0 -FOUND=0 - -echo "Polling for Claude code review comment..." - -while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do - # Fetch all comments and reviews - COMMENTS=$(gh api repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/pulls/$(gh pr view --json number -q .number)/comments --jq '.[] | .user.login + ": " + .body' 2>/dev/null) - REVIEWS=$(gh api repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/pulls/$(gh pr view --json number -q .number)/reviews --jq '.[] | select(.body != "") | .user.login + ": " + .body' 2>/dev/null) - - ALL_TEXT="$COMMENTS $REVIEWS" - - # Look for Claude review indicators (bot username or review keywords) - if echo "$ALL_TEXT" | grep -iq "claude\|code-review\|github-actions"; then - echo "✓ Claude review comment found" - FOUND=1 - break - fi - - RETRY_COUNT=$((RETRY_COUNT + 1)) - echo "Retry $RETRY_COUNT/$MAX_RETRIES - waiting 5 seconds..." - sleep 5 -done - -if [ $FOUND -eq 0 ]; then - echo "⚠️ WARNING: No Claude review comment found after 60 seconds" - echo "This is unexpected. The review may still be processing." - echo "" - echo "Do you want to:" - echo "1. Wait longer (another 60 seconds)" - echo "2. Proceed without review comment (NOT RECOMMENDED)" - echo "3. Abort merge" - exit 1 -fi -``` - -## Step 5: Fetch All Comments - -```bash -gh api repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/pulls/$(gh pr view --json number -q .number)/comments --jq '.[] | "[\(.user.login)] \(.body)"' -gh api repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/pulls/$(gh pr view --json number -q .number)/reviews --jq '.[] | select(.body != "") | "[\(.user.login) - \(.state)] \(.body)"' -``` - -## Step 6: Assess Comments - -Read every comment. Look for: -- **CRITICAL** / **BLOCKER** / **DO NOT MERGE** - Absolute blockers -- **FIX** / **MUST** - Should address before merge -- Actionable suggestions vs informational notes -- Unresolved questions - -**Categorize:** -- BLOCKING - Must fix -- SUBSTANTIAL - Should fix, will need re-review -- MINOR/OPTIONAL - Can merge, address later if desired -- INFORMATIONAL - No action needed - -## Step 7: Decision Point - -### If BLOCKING or SUBSTANTIAL Issues Found: - -``` -Issues found that need addressing: - -BLOCKING: -- [issue description] - -SUBSTANTIAL: -- [issue description] - -Implementing fixes... -``` - -1. Dispatch implementer to fix issues -2. Run verification (Step 2) -3. Commit fixes: `fix: address PR review feedback` -4. Push to PR branch -5. Run staff-code-reviewer on the fixes -6. **Loop back to Step 3** (re-check CI, wait for new comments) - -Max 2 fix loops. If still blocked after 2 attempts, escalate to user. - -### If All Clear (only MINOR or INFORMATIONAL): - -Proceed to Step 8. - -## Step 8: Merge - -Check project conventions for merge strategy. Default to squash: - -```bash -gh pr merge --squash --delete-branch -``` - -If project prefers different strategy (check CLAUDE.md or repo settings): -- `--merge` for merge commit -- `--rebase` for rebase - -## Step 9: Return to Main - -```bash -git checkout main -git pull origin main -``` - -Report: -``` -PR # merged successfully -Branch: (deleted) -Now on: main (up to date with origin) -``` diff --git a/commands/pr-status.md b/commands/pr-status.md index 22387ed..50c01da 100644 --- a/commands/pr-status.md +++ b/commands/pr-status.md @@ -1,39 +1,131 @@ --- -description: Quick PR status check - CI, comments, blockers -allowed-tools: Bash(gh:*) +description: Watch CI, find the current review comment, scan for blockers, report merge readiness +allowed-tools: Bash(gh:*), Bash(sleep:*), Bash(date:*) --- -# PR Status Check +# PR Status & Readiness Check -Quick overview of current PR status. +Watches CI to completion, finds and reads the review comment from the current CI run, scans for blockers, and reports whether the PR is ready to merge. -## Current PR +The CI review workflow ALWAYS posts a comment — either with recommended changes or an approval. This command must find that comment before reporting a verdict. -!`gh pr view --json number,title,state,headRefName,url` +## Step 1: Get PR Info -## CI Status +```bash +gh pr view --json number,title,state,headRefName,url +``` -!`gh pr checks` +**STOP if no PR exists for this branch.** Create a PR first. -## Recent Comments +## Step 2: Watch CI to Completion -Fetch all PR comments: +Check current CI state: ```bash -gh api repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/issues/$(gh pr view --json number -q .number)/comments --jq '.[] | "\(.user.login): \(.body)"' +gh pr checks ``` -## Summary +If any checks are still pending, watch until they complete: + +```bash +gh pr checks --watch --fail-fast +``` + +Report the final CI result: +- **CI PASSED** — proceed to Step 3 +- **CI FAILED** — report which checks failed and what needs fixing. Do not continue. + +## Step 3: Find the Current Review Comment + +The review bot posts after CI completes. Find the comment whose timestamp is newer than the CI workflow completion time. + +```bash +PR_NUM=$(gh pr view --json number -q .number) +REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner) +CI_COMPLETED=$(gh pr checks --json completedAt -q '.[0].completedAt' 2>/dev/null) + +MAX_RETRIES=12 +RETRY_COUNT=0 +FOUND=0 + +echo "Waiting for review comment from current CI run..." + +while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do + COMMENTS=$(gh api "repos/$REPO/issues/$PR_NUM/comments" --jq '.[] | .user.login + "|" + .created_at + "|" + .body' 2>/dev/null) + REVIEWS=$(gh api "repos/$REPO/pulls/$PR_NUM/reviews" --jq '.[] | select(.body != "") | .user.login + "|" + .submitted_at + "|" + .body' 2>/dev/null) + + ALL_TEXT="$COMMENTS +$REVIEWS" + + if echo "$ALL_TEXT" | grep -iq "claude\|code-review\|github-actions"; then + if [ -n "$CI_COMPLETED" ]; then + CI_EPOCH=$(date -d "$CI_COMPLETED" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%SZ" "$CI_COMPLETED" +%s 2>/dev/null) + LATEST_COMMENT_TIME=$(echo "$ALL_TEXT" | grep -i "claude\|code-review\|github-actions" | tail -1 | cut -d'|' -f2) + COMMENT_EPOCH=$(date -d "$LATEST_COMMENT_TIME" +%s 2>/dev/null || date -j -f "%Y-%m-%dT%H:%M:%SZ" "$LATEST_COMMENT_TIME" +%s 2>/dev/null) + if [ -n "$COMMENT_EPOCH" ] && [ -n "$CI_EPOCH" ] && [ "$COMMENT_EPOCH" -ge "$CI_EPOCH" ]; then + echo "Review comment found (timestamp verified against current CI run)" + FOUND=1 + break + else + echo "Found review comment but it's from a previous CI run — still waiting..." + fi + else + echo "Review comment found" + FOUND=1 + break + fi + fi + + RETRY_COUNT=$((RETRY_COUNT + 1)) + echo "Attempt $RETRY_COUNT/$MAX_RETRIES — sleeping 5s..." + sleep 5 +done + +if [ $FOUND -eq 0 ]; then + echo "WARNING: No review comment found after 60 seconds." + echo "The review may still be processing. Try running /pr-status again." +fi +``` + +## Step 4: Read and Assess the Review Comment + +Fetch all comments and reviews for the PR: + +```bash +PR_NUM=$(gh pr view --json number -q .number) +REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner) + +echo "=== PR Comments ===" +gh api "repos/$REPO/issues/$PR_NUM/comments" --jq '.[] | "[\(.user.login)] \(.body)"' + +echo "" +echo "=== PR Reviews ===" +gh api "repos/$REPO/pulls/$PR_NUM/reviews" --jq '.[] | select(.body != "") | "[\(.user.login) - \(.state)] \(.body)"' +``` + +Read every comment carefully. Look for: +- **CRITICAL** / **BLOCKER** / **DO NOT MERGE** — absolute blockers +- **FIX** / **MUST** — should address before merge +- Actionable change requests vs approval/LGTM +- Unresolved questions + +## Step 5: Verdict + +Report a clear summary: + +``` +PR # +Branch: <branch> + +CI: PASSED | FAILED +Review: FOUND (current) | FOUND (stale) | NOT FOUND +Blockers: NONE | <list of issues to fix> + +Verdict: READY TO MERGE | CHANGES NEEDED — <what to fix> +``` -Report: -1. PR number and branch -2. CI status: PASSED / FAILED / PENDING -3. Comment count -4. Any blockers detected (CRITICAL, FIX, BLOCKER keywords) +**READY TO MERGE** — CI passed, review comment found from current run, no blocking feedback. -## Next Steps +**CHANGES NEEDED** — CI failed, or review comment contains actionable change requests. List exactly what needs to be fixed. -- If CI pending: Wait and check again -- If CI failed: Fix issues and push -- If CI passed with no blockers: Use `/pr-merge` -- If blockers found: Address them first +**Never report READY TO MERGE without having found and read the review comment from the current CI run.** diff --git a/hooks/git-guard.py b/hooks/git-guard.py index 7e1a8c1..71d01fe 100755 --- a/hooks/git-guard.py +++ b/hooks/git-guard.py @@ -6,7 +6,7 @@ This hook scans bash commands and: 1. BLOCKS direct pushes to main/master branches 2. BLOCKS commits when on main/master branch -3. WARNS when using raw `gh pr merge` (recommends /pr-merge command) +3. WARNS when using raw `gh pr merge` (recommends running /pr-status first) Usage: Configure in hooks/hooks.json """ @@ -79,18 +79,18 @@ def main(): print("Or use /feature-start if available", file=sys.stderr) sys.exit(2) - # Warn on gh pr merge without using /pr-merge command + # Warn on gh pr merge without running /pr-status first if re.search(r'gh\s+pr\s+merge', command): output = { "hookSpecificOutput": { "hookEventName": "PreToolUse", "additionalContext": ( - "WARNING: You are merging a PR. Did you complete the checklist?\n" + "WARNING: You are merging a PR. Did you run /pr-status first?\n" "1) Wait for CI to pass\n" - "2) Wait 10-12 seconds for delayed review comments\n" - "3) Fetch and review all comments\n" - "4) Address any blockers (CRITICAL, FIX, BLOCKER)\n" - "Consider using /pr-merge command instead for safe merging." + "2) Wait for the review comment from the current CI run\n" + "3) Read and assess all comments for blockers\n" + "4) Only merge when /pr-status reports READY TO MERGE\n" + "Run /pr-status before merging." ) } } diff --git a/hooks/workflow-preferences.sh b/hooks/workflow-preferences.sh index b6f8ddb..0a5c5b1 100755 --- a/hooks/workflow-preferences.sh +++ b/hooks/workflow-preferences.sh @@ -3,7 +3,7 @@ cat << 'EOF' { "hookSpecificOutput": { "hookEventName": "SessionStart", - "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." + "additionalContext": "Use plan-execution for executing implementation plans (selects agent teams or subagents automatically). 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 deleted file mode 100644 index 2fb27f1..0000000 --- a/skills/agent-team-development/SKILL.md +++ /dev/null @@ -1,369 +0,0 @@ ---- -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: .worktrees/team-BRANCH-impl-N - - Example for branch "feature/auth": - .worktrees/team-feature-auth-impl-1 - .worktrees/team-feature-auth-impl-2 - .worktrees/team-feature-auth-impl-3 - - Commands: - git worktree add .worktrees/team-feature-auth-impl-1 HEAD - git worktree add .worktrees/team-feature-auth-impl-2 HEAD - ... - - Ensure `.worktrees/` is in `.gitignore`. - -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 .worktrees/team-BRANCH-impl-1 - git worktree remove .worktrees/team-BRANCH-impl-2 - ... - git worktree prune -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] - -IMPORTANT: cd into your worktree directory and work from there. -All git and file operations should happen from within the worktree. -Only fall back to `git -C` if you cannot cd into the worktree. - -## Workflow -1. cd into your worktree: cd [WORKTREE_PATH] -2. Check the shared task list for unclaimed tasks -3. Claim a task by marking it in_progress -4. Before starting: git pull to get latest changes -5. Implement the task following its acceptance criteria -6. Run tests and verify your changes -7. Commit with conventional message: feat|fix|refactor: description -8. Push to remote: git push -9. Mark the task as ready for review (add "READY FOR REVIEW" to task) -10. Wait for reviewer feedback via mailbox -11. If reviewer requests fixes: fix, commit, push, notify reviewer -12. Once approved: move to next task - -## Guidelines -- Work from within your worktree directory (cd into it first) -- 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 branch name for worktree naming -BRANCH_NAME=$(git branch --show-current | tr '/' '-') - -# Create worktrees inside .worktrees/ -git worktree add ".worktrees/team-${BRANCH_NAME}-impl-1" HEAD -git worktree add ".worktrees/team-${BRANCH_NAME}-impl-2" HEAD -# Add impl-3 if 5+ tasks - -# Ensure .worktrees/ is in .gitignore -``` - -### Cleanup (during final) - -```bash -git worktree remove ".worktrees/team-${BRANCH_NAME}-impl-1" -git worktree remove ".worktrees/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/plan-execution/SKILL.md b/skills/plan-execution/SKILL.md new file mode 100644 index 0000000..e01f228 --- /dev/null +++ b/skills/plan-execution/SKILL.md @@ -0,0 +1,502 @@ +--- +name: plan-execution +description: Use when executing implementation plans. Selects between agent teams (parallel teammates in worktrees) and subagents (parallel Task tool dispatch) based on availability. +--- + +# Plan Execution + +Execute implementation plans with parallel workers. Automatically selects between **team mode** (agent teams with worktrees) and **subagent mode** (Task tool with `run_in_background`). + +**Core principle:** Implement -> Verify -> Review -> Fix (if needed) -> Loop until pass + +## Mode Selection + +```bash +if [ -z "$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" ]; then + # → Subagent mode +else + # → Team mode +fi +``` + +### Mode Tradeoffs + +| | Team Mode | Subagent Mode | +|---|---|---| +| Parallelism | Worktrees + spawned teammates | `run_in_background` on Task tool | +| Communication | Bidirectional mailbox | None — orchestrator relays all feedback | +| Context | Teammates inherit lead's full context | Subagents only see what you pass them (lightweight) | +| Model control | Teammates inherit lead's model | Each subagent gets its own `model` param | +| Best for | Complex, interdependent tasks needing direct communication | Well-scoped, independent tasks | + +**Subagent mode is more efficient for simpler tasks** — subagents start with only the prompt you give them, avoiding the overhead of loading the full conversation context. Use team mode when tasks are tightly coupled and benefit from shared context and direct reviewer-implementer communication. + +## Task Classification + +Classify each task before execution: + +| 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 | + +## Model Selection + +| Role | Default Model | Notes | +|------|---------------|-------| +| Lead (orchestration) | opus | — | +| Implementer (standard) | sonnet | Team mode: inherits lead's model. Subagent mode: pass `model` param. | +| Implementer (simple) | sonnet | Override to haiku if plan recommends | +| Quick reviewer | haiku | Subagent mode only | +| Spec reviewer | sonnet | Subagent mode only | +| Quality reviewer | sonnet | Subagent mode only | +| Reviewer teammate | inherits lead | Team mode only | +| Staff reviewer (phase/final) | opus | Both modes | + +## The Complete Flow + +``` +SETUP +====================================================================== +1. Check CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS → select mode +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 + +TEAM MODE SETUP (skip if subagent mode) +====================================================================== +4. Determine implementer count (2 for ≤4 tasks, 3 for 5+) +5. Create git worktrees for each implementer: + Pattern: .worktrees/team-BRANCH-impl-N + Ensure `.worktrees/` is in `.gitignore` +6. Enter delegate mode (Shift+Tab) +7. Spawn implementer teammates (one per worktree) +8. Spawn reviewer teammate +9. Create shared tasks from plan + +SUBAGENT MODE SETUP (skip if team mode) +====================================================================== +4. Create TodoWrite with all tasks + +EXECUTION +====================================================================== + +Team mode: + Implementers self-claim tasks from shared task list. + Each implementer: pull → implement → test → commit → push → mark ready + Reviewer watches for ready tasks: + SIMPLE: quick combined review → PASS/FAIL via mailbox + STANDARD+: spec + quality review → PASS/FAIL via mailbox + Fix loops via mailbox (max 3 rounds, then escalate to lead) + +Subagent mode: + For each task (parallel where independent via run_in_background): + a. Mark task in_progress in TodoWrite + b. Dispatch implementer subagent (model from plan) + c. Run verification (typecheck, build, tests) + If FAILS → dispatch implementer with error output (max 3 attempts) + d. Review: + SIMPLE: dispatch quick-reviewer (haiku) — single pass + STANDARD+: dispatch spec-reviewer then quality-reviewer (sonnet) + If ISSUES → dispatch implementer with feedback (max 3 attempts) + e. Mark task completed + +PHASE BOUNDARY +====================================================================== +Wait for all tasks in phase to complete + pass review. +Skip phase review if ALL tasks in phase were SIMPLE. +Otherwise: staff-code-reviewer (opus) on phase commits + Commits: [phase_start_sha]..[current_sha] + + If CRITICAL/IMPORTANT: + → Assign fix (shared task or subagent dispatch) + → Re-verify after fix + → Re-run staff-code-reviewer (max 2 attempts) + +FINAL +====================================================================== +[Team mode] Clean up worktrees: + git worktree remove .worktrees/team-BRANCH-impl-N + git worktree prune + +Final staff-code-reviewer (opus) on entire implementation. + +Push and create PR. +Run /pr-status to watch CI and find the review comment. +If CHANGES NEEDED: + a. Fix the issues reported in the review comment + b. Optionally run staff-code-reviewer on the fixes (agent's judgment) + c. Commit and push + d. Re-run /pr-status +If READY TO MERGE: + a. Merge if user authorized, or report ready and wait for user +``` + +--- + +## Team Mode Details + +### Team Structure + +| Role | Count | Responsibility | +|------|-------|----------------| +| **Lead (you)** | 1 | Orchestration-only (delegate mode). Reads plan, creates shared tasks, monitors progress, performs phase/final reviews. | +| **Implementers** | 2-3 | Each in own git worktree. Self-claim tasks from shared task list. Pull latest before each task. Commit to shared feature branch. | +| **Reviewer** | 1 | Persistent teammate. Watches for completed tasks. Reviews and sends feedback directly to implementers via mailbox. | + +### Worktree Setup + +```bash +BRANCH_NAME=$(git branch --show-current | tr '/' '-') + +git worktree add ".worktrees/team-${BRANCH_NAME}-impl-1" HEAD +git worktree add ".worktrees/team-${BRANCH_NAME}-impl-2" HEAD +# Add impl-3 if 5+ tasks + +# Ensure .worktrees/ is in .gitignore +``` + +### Worktree Cleanup + +```bash +git worktree remove ".worktrees/team-${BRANCH_NAME}-impl-1" +git worktree remove ".worktrees/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 + +### 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] + +IMPORTANT: cd into your worktree directory and work from there. +All git and file operations should happen from within the worktree. +Only fall back to `git -C` if you cannot cd into the worktree. + +## Workflow +1. cd into your worktree: cd [WORKTREE_PATH] +2. Check the shared task list for unclaimed tasks +3. Claim a task by marking it in_progress +4. Before starting: git pull to get latest changes +5. Implement the task following its acceptance criteria +6. Run tests and verify your changes +7. Commit with conventional message: feat|fix|refactor: description +8. Push to remote: git push +9. Mark the task as ready for review (add "READY FOR REVIEW" to task) +10. Wait for reviewer feedback via mailbox +11. If reviewer requests fixes: fix, commit, push, notify reviewer +12. Once approved: move to next task + +## Guidelines +- Work from within your worktree directory (cd into it first) +- 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 + +## 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 +``` + +--- + +## Subagent Mode Details + +### Dispatch: Implementer (Initial) + +``` +Task tool: + subagent_type: implementer + model: [MODEL from plan, default: sonnet] + run_in_background: [true if parallelizable, false otherwise] + description: "Implement Task N: [brief name]" + prompt: | + ## Task N: [task name] + [FULL TEXT of task from plan] + + ## Context + [Where this fits, dependencies] + + ## Working Directory + [path] +``` + +### Dispatch: Implementer (Fix — MINOR) + +``` +Task tool: + subagent_type: implementer + model: haiku # override for MINOR fixes + description: "Fix minor issue: [description]" + prompt: | + ## Minor Fix Required + [structured feedback] +``` + +### Dispatch: Implementer (Fix — STANDARD/COMPLEX) + +``` +Task tool: + subagent_type: implementer + model: [same as original, or escalate to opus for COMPLEX] + description: "Fix [spec/quality/build] issues for Task N" + prompt: | + ## Fix Required + The [spec/quality/build] review found issues. + + ## Original Task + [task text for context] + + ## Issues to Fix + [structured feedback] + + ## Instructions + 1. Fix ONLY the issues mentioned + 2. Don't refactor unrelated code + 3. Run tests to verify + 4. Commit: fix: address [spec/quality] review feedback +``` + +### Dispatch: Quick Reviewer (SIMPLE tasks) + +``` +Task tool: + subagent_type: quick-reviewer + description: "Quick review for Task N" + prompt: | + ## What Was Requested + [task text] + + ## What Was Built + [implementer's report] + + ## Files to Inspect + [list] +``` + +### Dispatch: Spec Reviewer (STANDARD+ tasks) + +``` +Task tool: + subagent_type: spec-reviewer + description: "Spec review for Task N" + prompt: | + ## What Was Requested + [task text] + + ## What Was Built + [implementer's report] + + ## Files to Inspect + [list] +``` + +### Dispatch: Quality Reviewer (STANDARD+ tasks) + +``` +Task tool: + subagent_type: quality-reviewer + description: "Quality review for Task N" + prompt: | + ## Task Context + [brief description of what was implemented] + + ## Files Changed + [list] +``` + +### Dispatch: Staff Code Reviewer (Phase/Final) + +``` +Task tool: + subagent_type: staff-code-reviewer + model: opus + description: "Phase N review" or "Final review" + prompt: | + Comprehensive review. + Commits: [BASE_SHA]..[HEAD_SHA] +``` + +### Structured Fix Feedback Format + +When dispatching implementer for fixes, use this format: + +```json +{ + "iteration": N, + "status": "review_failure|test_failure|build_failure", + "file": "path/to/file.ts", + "issues": [ + {"line": 47, "issue": "description", "fix": "suggested fix"} + ], + "previous_fix": "what was tried last", + "max_attempts": 3 +} +``` + +If JSON validation fails, fall back to plain text: + +``` +## Fix Required (Attempt N of 3) +Status: [review_failure|test_failure|build_failure] +File: path/to/file.ts +Issues: +1. Line 47: [issue] -> [fix] +Previous attempt: [what was tried] +``` + +--- + +## Fix Loop Severity (Both Modes) + +| 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 for COMPLEX fixes:** +After 2 failed sonnet attempts, ask user for approval: + +``` +ESCALATION: Complex fix failing after 2 attempts. +Issue: [description] +Options: +1. Escalate to opus (higher cost, better reasoning) +2. Skip and document as known issue +3. Manual intervention +``` + +## Escalation (Both Modes) + +**Escalate to user when:** +- Fix loop exceeds max attempts (3 task-level, 2 phase-level) +- Reviewer and implementer disagree (team mode: after 3 rounds) +- Security concern needs judgment +- Architectural decision needed +- Merge conflicts between worktrees that can't be auto-resolved (team mode) + +``` +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 +``` + +## Red Flags + +**Never:** +- 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 (team mode) +- Skip the env var check for mode selection + +**Always:** +- Classify task complexity before execution +- Use quick-reviewer for SIMPLE tasks (subagent mode) +- Pass specific feedback to fix agents +- Re-verify after every fix +- Track attempts per task +- Escalate when stuck +- Clean up worktrees during final step (team mode) +- Enter delegate mode before spawning teammates (team mode) + +## Integration + +**Uses:** +- `dev-workflow:staff-code-reviewer` — phase/final reviews (opus) +- `/pr-status` command — CI watch, review comment polling, readiness verdict +- Git worktrees — workspace isolation (team mode) +- Shared task list + mailbox — work coordination (team mode) +- Task tool with `run_in_background` — parallel dispatch (subagent mode) +- `dev-workflow:implementer` — task implementation (subagent mode) +- `dev-workflow:quick-reviewer` — fast combined review for simple tasks (subagent mode) +- `dev-workflow:spec-reviewer` — spec compliance check (subagent mode) +- `dev-workflow:quality-reviewer` — quality gate (subagent mode) + +**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 +- `dev-workflow:using-git-worktrees` — isolated workspaces diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md deleted file mode 100644 index cd6abbf..0000000 --- a/skills/subagent-driven-development/SKILL.md +++ /dev/null @@ -1,333 +0,0 @@ ---- -name: subagent-driven-development -description: Use when executing implementation plans with independent tasks in the current session ---- - -# Subagent-Driven Development - -Execute plan by dispatching implementer agent per task, with verification gates and review loops. - -**Core principle:** Implement -> Verify -> Review -> Fix (if needed) -> Loop until pass - -## When to Use - -- Have an implementation plan with tasks and recommended models -- Tasks are mostly independent -- Want to stay in current session - -## Task Classification - -Classify each task before dispatching: - -| Complexity | Impl Model | Review Path | Indicators | -|------------|------------|-------------|------------| -| SIMPLE | haiku (via Task tool model param) | quick-reviewer only | ≤2 files, config, boilerplate, mechanical | -| STANDARD | sonnet (default) | spec → quality → (phase) | Multi-file, business logic, error handling | -| COMPLEX | sonnet or opus (via Task tool) | spec → quality → phase | Only if plan explicitly requires | - -**Note:** The implementer agent defaults to sonnet. To use haiku for simple tasks, pass `model: haiku` in the Task tool call. Planning should recommend models per task. - -## Model Selection - -**Planning stage** should include model recommendation per task (usually haiku or sonnet). -**Opus** is reserved for: -- Main conversation orchestration -- Staff-code-reviewer (phase/final reviews) -- Only for implementation if plan explicitly says so (rare) - -| Role | Agent | Default Model | Override | -|------|-------|---------------|----------| -| Implementer (standard) | implementer | sonnet | haiku if plan says | -| Implementer (simple) | implementer | sonnet | haiku if plan says | -| Quick reviewer | quick-reviewer | haiku | - | -| Spec reviewer | spec-reviewer | sonnet | - | -| Quality reviewer | quality-reviewer | sonnet | - | -| Staff reviewer | staff-code-reviewer | opus | - | - -## The Complete Flow - -``` -SETUP -====================================================================== -1. Ensure on feature branch (create if needed) -2. Read plan, extract ALL tasks with: - - Full task text - - Recommended model (default: sonnet) - - Complexity classification (SIMPLE/STANDARD/COMPLEX) - - Context/dependencies -3. Create TodoWrite with all tasks - -PER TASK -====================================================================== - -+-- IMPLEMENT --------------------------------------------------+ -| 4. Mark task in_progress in TodoWrite | -| 5. Dispatch implementer agent (model from plan) | -| 6. If implementer asks questions -> answer -> resume | -| 7. Implementer: implement -> test -> self-review -> commit | -+---------------------------------------------------------------+ - | - v -+-- VERIFY -----------------------------------------------------+ -| 8. Run verification (typecheck, build, tests) | -| | -| If FAILS -> dispatch implementer with error output | -| -> "Fix these build/type errors" | -| -> Loop back to VERIFY (max 3 attempts, then escalate) | -+---------------------------------------------------------------+ - | - v -+-- REVIEW (conditional based on complexity) -------------------+ -| SIMPLE tasks: | -| 9a. Dispatch quick-reviewer (haiku) - single pass | -| | -| STANDARD+ tasks: | -| 9b. Dispatch spec-reviewer (sonnet) | -| 10. Dispatch quality-reviewer (sonnet) | -| | -| If ISSUES -> dispatch implementer with feedback | -| -> Loop to VERIFY then REVIEW (max 3 attempts) | -+---------------------------------------------------------------+ - | - v -| 11. Mark task completed in TodoWrite | -| 12. Continue to next task... | - -PHASE BOUNDARY -====================================================================== -+-- PHASE REVIEW -----------------------------------------------+ -| 13. Skip phase review if ALL tasks in phase were SIMPLE | -| | -| Otherwise: Dispatch staff-code-reviewer (opus) | -| Commits: [phase_start_sha]..[current_sha] | -| | -| If CRITICAL/IMPORTANT -> implementer fixes -> re-verify | -| -> Re-run staff-code-reviewer (max 2 attempts) | -+---------------------------------------------------------------+ - -FINAL -====================================================================== -14. Final staff-code-reviewer (opus) - entire implementation -15. Create PR (follow repo template if exists) -16. Invoke /pr-merge workflow (or user invokes manually) -``` - -## Fix Loop Severity - -Classify fix complexity to optimize model usage: - -| 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 for COMPLEX fixes:** -After 2 failed sonnet attempts on a COMPLEX fix, ask user for approval: - -``` -ESCALATION: Complex fix failing after 2 attempts. -Issue: [description] -Options: -1. Escalate to opus (higher cost, better reasoning) -2. Skip and document as known issue -3. Manual intervention -``` - -## Structured Fix Feedback Format - -When dispatching implementer for fixes, use this JSON format: - -```json -{ - "iteration": N, - "status": "review_failure|test_failure|build_failure", - "file": "path/to/file.ts", - "issues": [ - {"line": 47, "issue": "description", "fix": "suggested fix"} - ], - "previous_fix": "what was tried last", - "max_attempts": 3 -} -``` - -**Validation:** Before passing feedback JSON to implementer, verify it's valid: -```bash -echo "$FEEDBACK_JSON" | python3 -c "import json,sys; json.load(sys.stdin)" && echo "Valid JSON" -``` - -If validation fails, fall back to plain text feedback with clear structure: -``` -## Fix Required (Attempt N of 3) -Status: [review_failure|test_failure|build_failure] -File: path/to/file.ts -Issues: -1. Line 47: [issue] → [fix] -Previous attempt: [what was tried] -``` - -## Dispatching Subagents - -### Implementer (Initial) -``` -Task tool: - subagent_type: implementer - model: [MODEL from plan, default: sonnet] - description: "Implement Task N: [brief name]" - prompt: | - ## Task N: [task name] - [FULL TEXT of task from plan] - - ## Context - [Where this fits, dependencies] - - ## Working Directory - [path] -``` - -### Implementer (Fix Mode - MINOR) -``` -Task tool: - subagent_type: implementer - model: haiku # override for MINOR fixes - description: "Fix minor issue: [description]" - prompt: | - ## Minor Fix Required - [structured feedback JSON] -``` - -### Implementer (Fix Mode - STANDARD/COMPLEX) -``` -Task tool: - subagent_type: implementer - model: [same as original, or escalate to opus for COMPLEX] - description: "Fix [spec/quality/build] issues for Task N" - prompt: | - ## Fix Required - The [spec/quality/build] review found issues. - - ## Original Task - [task text for context] - - ## Issues to Fix - [structured feedback JSON] - - ## Instructions - 1. Fix ONLY the issues mentioned - 2. Don't refactor unrelated code - 3. Run tests to verify - 4. Commit: fix: address [spec/quality] review feedback -``` - -### Quick Reviewer (SIMPLE tasks only) -``` -Task tool: - subagent_type: quick-reviewer - description: "Quick review for Task N" - prompt: | - ## What Was Requested - [task text] - - ## What Was Built - [implementer's report] - - ## Files to Inspect - [list] -``` - -### Spec Reviewer (STANDARD+ tasks) -``` -Task tool: - subagent_type: spec-reviewer - description: "Spec review for Task N" - prompt: | - ## What Was Requested - [task text] - - ## What Was Built - [implementer's report] - - ## Files to Inspect - [list] -``` - -### Quality Reviewer (STANDARD+ tasks) -``` -Task tool: - subagent_type: quality-reviewer - description: "Quality review for Task N" - prompt: | - ## Task Context - [brief description of what was implemented] - - ## Files Changed - [list] -``` - -### Staff Code Reviewer (Phase/Final) -``` -Task tool: - subagent_type: staff-code-reviewer - model: opus - description: "Phase N review" or "Final review" - prompt: | - Comprehensive review. - Commits: [BASE_SHA]..[HEAD_SHA] -``` - -## Escalation - -**Escalate to user when:** -- Fix loop exceeds max attempts (3 task-level, 2 phase-level) -- Reviewer and implementer disagree -- Security concern needs judgment -- Architectural decision needed - -``` -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 -``` - -## Red Flags - -**Never:** -- Skip verification step -- Skip re-verification after fixes -- Let fix loops run indefinitely -- Proceed with CRITICAL issues -- Use opus for every implementation task - -**Always:** -- Classify task complexity before dispatching -- Use quick-reviewer for SIMPLE tasks -- Pass specific feedback to fix subagents (use JSON format) -- Re-verify after every fix -- Re-review after fixes -- Track attempts -- Escalate when stuck - -## Integration - -**Uses:** -- `dev-workflow:implementer` - task implementation (sonnet, or haiku if plan specifies) -- `dev-workflow:quick-reviewer` - fast combined review for simple tasks (haiku) -- `dev-workflow:spec-reviewer` - spec compliance check (sonnet) -- `dev-workflow:quality-reviewer` - quick quality gate (sonnet) -- `dev-workflow:staff-code-reviewer` - comprehensive phase/final reviews (opus) -- `/pr-merge` command - CI check, comment assessment, merge - -**Works with:** -- `dev-workflow:writing-plans` - creates plans with model recommendations -- `dev-workflow:brainstorming` - design exploration before planning -- `dev-workflow:systematic-debugging` - bug investigation workflow -- `dev-workflow:test-driven-development` - TDD discipline for implementation -- `dev-workflow:using-git-worktrees` - isolated workspaces for parallel execution diff --git a/skills/systematic-debugging/SKILL.md b/skills/systematic-debugging/SKILL.md index 8f2966d..91aa504 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:agent-team-development` / `dev-workflow:subagent-driven-development`:** +**Works with `dev-workflow:plan-execution`:** - 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 d20638d..2708f48 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:agent-team-development` (or `subagent-driven-development` fallback) +- Executing implementation plans with `dev-workflow:plan-execution` - Running multiple implementer agents in parallel - Starting feature work that needs isolation from main workspace - Working on multiple features simultaneously without switching branches @@ -210,15 +210,10 @@ git push origin branch-name - 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 -- Each task in plan works in same worktree context +**Works with `dev-workflow:plan-execution`:** +- Team mode creates per-implementer worktrees automatically +- Subagent mode can use a worktree as isolated workspace +- Prevents git index conflicts between parallel workers **Works with `dev-workflow:implementer`:** - Implementer agents work in dedicated worktree diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md index ecc1de9..7c139a9 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 agent-team-development (or subagent-driven-development) for execution. +Create structured plans that chain to plan-execution for execution. **Core principle:** Plan with bite-sized tasks, model recommendations, and TDD embedded. @@ -26,7 +26,7 @@ Create structured plans that chain to agent-team-development (or subagent-driven ```markdown # Implementation Plan: [Feature/Component Name] -**Skill:** `dev-workflow:agent-team-development` +**Skill:** `dev-workflow:plan-execution` ## Overview [1-2 sentences on what we're building and why] @@ -224,7 +224,7 @@ If dependencies exist: ```markdown # Implementation Plan: Add Health Check Endpoint -**Skill:** `dev-workflow:agent-team-development` +**Skill:** `dev-workflow:plan-execution` ## Overview Add GET /health endpoint that returns service status and dependencies. @@ -300,7 +300,7 @@ Document the health check endpoint in API docs. ```markdown # Implementation Plan: User Profile Management -**Skill:** `dev-workflow:agent-team-development` +**Skill:** `dev-workflow:plan-execution` ## Overview Implement CRUD operations for user profiles with validation and permissions. @@ -430,8 +430,7 @@ Create endpoint to search profiles by name or email. ## Integration **Creates plans for:** -- `dev-workflow:agent-team-development` - preferred execution (parallel agent teams) -- `dev-workflow:subagent-driven-development` - fallback execution (sequential subagents) +- `dev-workflow:plan-execution` - executes with agent teams or subagents based on availability **Works with:** - `dev-workflow:brainstorming` - use before planning if requirements unclear @@ -447,20 +446,18 @@ Create endpoint to search profiles by name or email. ✅ Tasks that write code include testing approach ✅ Acceptance criteria are specific and testable ✅ Review checkpoints identified -✅ Plan chains to agent-team-development for execution +✅ Plan chains to plan-execution for execution ## Chains To After writing plan, invoke: ``` -/skill dev-workflow:agent-team-development +/skill dev-workflow:plan-execution ``` -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. Set up parallel implementers (or sequential subagents for fallback) -4. Run verification and reviews at specified checkpoints -5. Complete implementation following the plan structure +1. Select mode (agent teams if enabled, subagents otherwise) +2. Read this plan and extract all tasks with model recommendations +3. Execute tasks in parallel with verification and review gates +4. Run staff-code-reviewer at phase boundaries and final +5. Create PR and run /pr-status loop until ready