From 48d6f4a5eb9beb7fdbd1a6b697002877111cda4d Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 11 Feb 2026 00:58:16 +0000 Subject: [PATCH 1/3] fix: improve pr-create and pr-status reliability, consolidate pr-merge MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit pr-create: Add existing-PR check using `gh pr list` (exits 0 when no PR exists) instead of `gh pr view` (exits non-zero). Make confirmation step resilient with the same approach. pr-status: Rewrite from snapshot-only to full readiness checker — watches CI to completion, polls for review bot comment with timestamp validation against the current CI run, scans for blocker keywords, and reports a clear READY/NOT READY verdict. pr-merge: Remove duplicated CI watching, comment polling, and blocker scanning (Steps 3-6). Delegate readiness checking to /pr-status, keeping only merge-specific logic: local verification, review feedback assessment, fix loop, merge execution, and return to main. Fixes #12 https://claude.ai/code/session_01Ch89tRMukrCMshPhYskRnC --- commands/pr-create.md | 26 +++++++-- commands/pr-merge.md | 118 ++++++++----------------------------- commands/pr-status.md | 131 +++++++++++++++++++++++++++++++++++------- 3 files changed, 157 insertions(+), 118 deletions(-) diff --git a/commands/pr-create.md b/commands/pr-create.md index f043845..a93b6ba 100644 --- a/commands/pr-create.md +++ b/commands/pr-create.md @@ -37,7 +37,22 @@ Push the current branch to origin: git push -u origin $(git branch --show-current) ``` -## Step 5: Create PR +## Step 5: Check for Existing PR + +Check if a PR already exists for this branch: + +```bash +EXISTING_PR=$(gh pr list --head "$(git branch --show-current)" --json number,url --jq '.[0]' 2>/dev/null || true) +``` + +If a PR exists, report it and skip creation: +``` +PR already exists: # — +``` + +Otherwise, continue to Step 6. + +## Step 6: Create PR Construct PR with: - Title: Brief description of changes @@ -65,12 +80,13 @@ Create the PR: gh pr create --title "TITLE" --body "BODY" ``` -## Step 6: Confirm +## Step 7: Confirm -!`gh pr view --json number,url -q '"PR #\(.number): \(.url)"'` +```bash +gh pr list --head "$(git branch --show-current)" --json number,url --jq '"PR #\(.[0].number): \(.[0].url)"' +``` ## Next Steps -- Wait for CI to complete -- Use `/pr-status` to check CI and comments +- Use `/pr-status` to watch CI and review comments - Use `/pr-merge` when ready to merge diff --git a/commands/pr-merge.md b/commands/pr-merge.md index c7c3cee..5e9e7f1 100644 --- a/commands/pr-merge.md +++ b/commands/pr-merge.md @@ -1,28 +1,29 @@ --- -description: Complete PR merge workflow - CI check, comment assessment, fix loop, merge, return to main +description: Complete PR merge workflow - readiness check via /pr-status, local verification, 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. +Complete merge workflow: readiness check, local verification, fix loop if needed, merge, return to main. -## Step 1: Get PR Info +## Step 1: Readiness Check -!`gh pr view --json number,title,state,url,headRefName -q '"\(.number)|\(.title)|\(.state)|\(.url)|\(.headRefName)"'` +Run `/pr-status` to watch CI, poll for the review comment, and scan for blockers. -Parse and display: PR number, title, state, URL, branch name. +**STOP if the verdict is NOT READY.** Fix the reported issues first. -## Step 2: Verification +Record the PR number, branch, and URL from the status output for use in later steps. + +## Step 2: Local Verification **CI Trust Mode:** Skip local verification if ALL of these are true: -1. CI passed (check in Step 3) +1. `/pr-status` reported CI PASSED 2. CI completed within the last hour -3. No local uncommitted changes +3. No local uncommitted changes (`git status` shows clean working tree) 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) @@ -30,16 +31,14 @@ if [ -n "$CI_TIME" ]; 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" + [ $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" + 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: +If CI is stale or working tree is dirty, run full verification: ```bash pnpm typecheck && pnpm build && pnpm test @@ -48,81 +47,14 @@ pnpm typecheck && pnpm build && pnpm test **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 +## Step 3: Assess Review Feedback -**Categorize:** -- BLOCKING - Must fix -- SUBSTANTIAL - Should fix, will need re-review -- MINOR/OPTIONAL - Can merge, address later if desired -- INFORMATIONAL - No action needed +Using the comments fetched by `/pr-status`, categorize each piece of feedback: -## Step 7: Decision Point +- **BLOCKING** — Must fix (CRITICAL, BLOCKER, DO NOT MERGE) +- **SUBSTANTIAL** — Should fix, will need re-review +- **MINOR/OPTIONAL** — Can merge, address later if desired +- **INFORMATIONAL** — No action needed ### If BLOCKING or SUBSTANTIAL Issues Found: @@ -138,20 +70,20 @@ SUBSTANTIAL: Implementing fixes... ``` -1. Dispatch implementer to fix issues -2. Run verification (Step 2) +1. Fix the issues +2. Run local 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) +6. **Loop back to Step 1** — run `/pr-status` again to re-check CI and 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. +Proceed to Step 4. -## Step 8: Merge +## Step 4: Merge Check project conventions for merge strategy. Default to squash: @@ -163,7 +95,7 @@ If project prefers different strategy (check CLAUDE.md or repo settings): - `--merge` for merge commit - `--rebase` for rebase -## Step 9: Return to Main +## Step 5: Return to Main ```bash git checkout main diff --git a/commands/pr-status.md b/commands/pr-status.md index 22387ed..74981f1 100644 --- a/commands/pr-status.md +++ b/commands/pr-status.md @@ -1,39 +1,130 @@ --- -description: Quick PR status check - CI, comments, blockers -allowed-tools: Bash(gh:*) +description: Watch CI, poll for 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, polls for the review comment, scans for blockers, and reports whether the PR is ready to merge. -## Current PR +## Step 1: Get PR Info !`gh pr view --json number,title,state,headRefName,url` -## CI Status +**STOP if no PR exists for this branch.** Use `/pr-create` first. -!`gh pr checks` +## Step 2: Watch CI to Completion -## Recent Comments +Check if CI is already done: -Fetch all PR comments: +```bash +gh pr checks +``` + +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** — STOP. Report which checks failed. Do not continue. + +## Step 3: Poll for Review Comment + +Review bots typically post 10-12 seconds after CI passes. Wait for it. + +```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 "Polling for review comment (up to 60s)..." + +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 + # Verify comment is from the current CI run (newer than CI completion) + 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 "Retry $RETRY_COUNT/$MAX_RETRIES — waiting 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, or this repo may not have a review bot configured." +fi +``` + +## Step 4: Scan for Blockers + +Fetch all comments and reviews: ```bash -gh api repos/$(gh repo view --json nameWithOwner -q .nameWithOwner)/issues/$(gh pr view --json number -q .number)/comments --jq '.[] | "\(.user.login): \(.body)"' +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)"' ``` -## Summary +Read every comment. Look for: +- **CRITICAL** / **BLOCKER** / **DO NOT MERGE** — Absolute blockers +- **FIX** / **MUST** — Should address before merge +- Unresolved questions + +## Step 5: Readiness Verdict + +Report a clear summary: + +``` +PR # — +Branch: <branch> + +CI: PASSED | FAILED | PENDING +Review: FOUND (current) | FOUND (stale) | NOT FOUND +Blockers: NONE | <list> + +Verdict: READY TO MERGE | NOT READY — <reason> +``` -Report: -1. PR number and branch -2. CI status: PASSED / FAILED / PENDING -3. Comment count -4. Any blockers detected (CRITICAL, FIX, BLOCKER keywords) +Rules for the verdict: +- **READY TO MERGE**: CI passed AND no blocking comments found +- **NOT READY**: CI failed, or CRITICAL/BLOCKER/DO NOT MERGE found ## Next Steps -- 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 +- If READY: Use `/pr-merge` +- If NOT READY: Fix the issues, push, then run `/pr-status` again From 6c287b7147a4e8f8d9e991d015dcdb64dc9cc5f2 Mon Sep 17 00:00:00 2001 From: Claude <noreply@anthropic.com> Date: Wed, 11 Feb 2026 01:20:09 +0000 Subject: [PATCH 2/3] =?UTF-8?q?fix:=20consolidate=20PR=20commands=20?= =?UTF-8?q?=E2=80=94=20delete=20pr-create/pr-merge,=20rewrite=20pr-status?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Delete pr-create.md: redundant with Claude Code's built-in PR creation and GitHub PR templates - Delete pr-merge.md: merge is a single gh command once status says ready - Rewrite pr-status.md as the single readiness checker: watches CI to completion, polls for the review comment with timestamp validation against the current CI run, scans for blockers, and reports a clear READY TO MERGE / CHANGES NEEDED verdict - Update agent-team-development and subagent-driven-development skills to use /pr-status in a fix loop (check → fix → push → re-check) instead of invoking /pr-merge. Agent decides when to run staff-code-reviewer on fixes. - Update context-recovery.md, git-guard.py, and CLAUDE.md to remove all references to deleted commands Fixes #12 https://claude.ai/code/session_01Ch89tRMukrCMshPhYskRnC --- CLAUDE.md | 27 ++--- commands/context-recovery.md | 4 +- commands/pr-create.md | 92 ---------------- commands/pr-merge.md | 110 -------------------- commands/pr-status.md | 55 +++++----- hooks/git-guard.py | 14 +-- skills/agent-team-development/SKILL.md | 13 ++- skills/subagent-driven-development/SKILL.md | 13 ++- 8 files changed, 67 insertions(+), 261 deletions(-) delete mode 100644 commands/pr-create.md delete mode 100644 commands/pr-merge.md diff --git a/CLAUDE.md b/CLAUDE.md index 1d8e51a..511733d 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,9 +22,7 @@ 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) @@ -81,18 +79,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 execution skills (`agent-team-development`, `subagent-driven-development`) use `/pr-status` in a loop: check status, fix if needed, push, re-check until READY TO MERGE. ### Agent Invocation @@ -115,9 +111,8 @@ Skills provide structured workflows for common development tasks: ## 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/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 a93b6ba..0000000 --- a/commands/pr-create.md +++ /dev/null @@ -1,92 +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: Check for Existing PR - -Check if a PR already exists for this branch: - -```bash -EXISTING_PR=$(gh pr list --head "$(git branch --show-current)" --json number,url --jq '.[0]' 2>/dev/null || true) -``` - -If a PR exists, report it and skip creation: -``` -PR already exists: #<number> — <url> -``` - -Otherwise, continue to Step 6. - -## Step 6: 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 -<Any additional context> - ---- -Generated with [Claude Code](https://claude.ai/claude-code) -``` - -Create the PR: -```bash -gh pr create --title "TITLE" --body "BODY" -``` - -## Step 7: Confirm - -```bash -gh pr list --head "$(git branch --show-current)" --json number,url --jq '"PR #\(.[0].number): \(.[0].url)"' -``` - -## Next Steps - -- Use `/pr-status` to watch CI and review 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 5e9e7f1..0000000 --- a/commands/pr-merge.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -description: Complete PR merge workflow - readiness check via /pr-status, local verification, 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: readiness check, local verification, fix loop if needed, merge, return to main. - -## Step 1: Readiness Check - -Run `/pr-status` to watch CI, poll for the review comment, and scan for blockers. - -**STOP if the verdict is NOT READY.** Fix the reported issues first. - -Record the PR number, branch, and URL from the status output for use in later steps. - -## Step 2: Local Verification - -**CI Trust Mode:** Skip local verification if ALL of these are true: -1. `/pr-status` reported CI PASSED -2. CI completed within the last hour -3. No local uncommitted changes (`git status` shows clean working tree) - -Check CI freshness: -```bash -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 stale or working tree is dirty, 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: Assess Review Feedback - -Using the comments fetched by `/pr-status`, categorize each piece of feedback: - -- **BLOCKING** — Must fix (CRITICAL, BLOCKER, DO NOT MERGE) -- **SUBSTANTIAL** — Should fix, will need re-review -- **MINOR/OPTIONAL** — Can merge, address later if desired -- **INFORMATIONAL** — No action needed - -### If BLOCKING or SUBSTANTIAL Issues Found: - -``` -Issues found that need addressing: - -BLOCKING: -- [issue description] - -SUBSTANTIAL: -- [issue description] - -Implementing fixes... -``` - -1. Fix the issues -2. Run local 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 1** — run `/pr-status` again to re-check CI and 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 4. - -## Step 4: 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 5: Return to Main - -```bash -git checkout main -git pull origin main -``` - -Report: -``` -PR #<number> merged successfully -Branch: <branch-name> (deleted) -Now on: main (up to date with origin) -``` diff --git a/commands/pr-status.md b/commands/pr-status.md index 74981f1..50c01da 100644 --- a/commands/pr-status.md +++ b/commands/pr-status.md @@ -1,21 +1,25 @@ --- -description: Watch CI, poll for review comment, scan for blockers, report merge readiness +description: Watch CI, find the current review comment, scan for blockers, report merge readiness allowed-tools: Bash(gh:*), Bash(sleep:*), Bash(date:*) --- # PR Status & Readiness Check -Watches CI to completion, polls for the review comment, scans for blockers, and reports whether the PR is ready to merge. +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. + +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. ## Step 1: Get PR Info -!`gh pr view --json number,title,state,headRefName,url` +```bash +gh pr view --json number,title,state,headRefName,url +``` -**STOP if no PR exists for this branch.** Use `/pr-create` first. +**STOP if no PR exists for this branch.** Create a PR first. ## Step 2: Watch CI to Completion -Check if CI is already done: +Check current CI state: ```bash gh pr checks @@ -29,11 +33,11 @@ gh pr checks --watch --fail-fast Report the final CI result: - **CI PASSED** — proceed to Step 3 -- **CI FAILED** — STOP. Report which checks failed. Do not continue. +- **CI FAILED** — report which checks failed and what needs fixing. Do not continue. -## Step 3: Poll for Review Comment +## Step 3: Find the Current Review Comment -Review bots typically post 10-12 seconds after CI passes. Wait for it. +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) @@ -44,7 +48,7 @@ MAX_RETRIES=12 RETRY_COUNT=0 FOUND=0 -echo "Polling for review comment (up to 60s)..." +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) @@ -54,7 +58,6 @@ while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do $REVIEWS" if echo "$ALL_TEXT" | grep -iq "claude\|code-review\|github-actions"; then - # Verify comment is from the current CI run (newer than CI completion) 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) @@ -74,19 +77,19 @@ $REVIEWS" fi RETRY_COUNT=$((RETRY_COUNT + 1)) - echo "Retry $RETRY_COUNT/$MAX_RETRIES — waiting 5s..." + 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, or this repo may not have a review bot configured." + echo "The review may still be processing. Try running /pr-status again." fi ``` -## Step 4: Scan for Blockers +## Step 4: Read and Assess the Review Comment -Fetch all comments and reviews: +Fetch all comments and reviews for the PR: ```bash PR_NUM=$(gh pr view --json number -q .number) @@ -100,12 +103,13 @@ echo "=== PR Reviews ===" gh api "repos/$REPO/pulls/$PR_NUM/reviews" --jq '.[] | select(.body != "") | "[\(.user.login) - \(.state)] \(.body)"' ``` -Read every comment. Look for: -- **CRITICAL** / **BLOCKER** / **DO NOT MERGE** — Absolute blockers -- **FIX** / **MUST** — Should address before merge +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: Readiness Verdict +## Step 5: Verdict Report a clear summary: @@ -113,18 +117,15 @@ Report a clear summary: PR #<number> — <title> Branch: <branch> -CI: PASSED | FAILED | PENDING +CI: PASSED | FAILED Review: FOUND (current) | FOUND (stale) | NOT FOUND -Blockers: NONE | <list> +Blockers: NONE | <list of issues to fix> -Verdict: READY TO MERGE | NOT READY — <reason> +Verdict: READY TO MERGE | CHANGES NEEDED — <what to fix> ``` -Rules for the verdict: -- **READY TO MERGE**: CI passed AND no blocking comments found -- **NOT READY**: CI failed, or CRITICAL/BLOCKER/DO NOT MERGE found +**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 READY: Use `/pr-merge` -- If NOT READY: Fix the issues, push, then run `/pr-status` again +**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/skills/agent-team-development/SKILL.md b/skills/agent-team-development/SKILL.md index 2fb27f1..af3e6be 100644 --- a/skills/agent-team-development/SKILL.md +++ b/skills/agent-team-development/SKILL.md @@ -157,8 +157,15 @@ FINAL 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) +19. Push and create PR +20. Run /pr-status to watch CI and find the review comment +21. 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. Loop back to step 20 +22. If READY TO MERGE: + a. Merge if user authorized, or report ready and wait for user ``` ## Spawn Prompt Templates @@ -357,7 +364,7 @@ git worktree prune - 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 +- `/pr-status` command - CI watch, review comment polling, readiness verdict **Falls back to:** - `dev-workflow:subagent-driven-development` - when agent teams not enabled diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index cd6abbf..f5ae12b 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -108,8 +108,15 @@ PHASE BOUNDARY 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) +15. Push and create PR +16. Run /pr-status to watch CI and find the review comment +17. 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. Loop back to step 16 +18. If READY TO MERGE: + a. Merge if user authorized, or report ready and wait for user ``` ## Fix Loop Severity @@ -323,7 +330,7 @@ Options: - `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 +- `/pr-status` command - CI watch, review comment polling, readiness verdict **Works with:** - `dev-workflow:writing-plans` - creates plans with model recommendations From f4f2baec443b6666132dd5fc91a4b02762b78d18 Mon Sep 17 00:00:00 2001 From: Claude <noreply@anthropic.com> Date: Wed, 11 Feb 2026 01:38:12 +0000 Subject: [PATCH 3/3] refactor: merge agent-team-development and subagent-driven-development into plan-execution MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The two execution skills shared ~70% of their content (task classification, fix loop severity, escalation rules, phase review logic, the final PR flow). Merge into a single `plan-execution` skill that auto-selects mode: - **Team mode** (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS set): worktrees, spawned teammates, shared task list, mailbox communication - **Subagent mode** (default): parallel dispatch via `run_in_background`, each subagent gets only what you pass it (lightweight context), independent `model` param per task Key corrections from the previous separate skills: - Subagents CAN run in parallel via `run_in_background` (not sequential) - Subagents are more efficient for well-scoped tasks (no context inheritance) - Team mode teammates inherit lead's model (noted as tradeoff) Also updates all references across CLAUDE.md, README.md, writing-plans, using-git-worktrees, systematic-debugging, implementer agent, and workflow-preferences hook. Removes /pr-create and /pr-merge references from README that were missed in previous commit. 716 lines (two files) → 502 lines (one file), -315 net across repo. https://claude.ai/code/session_01Ch89tRMukrCMshPhYskRnC --- CLAUDE.md | 8 +- README.md | 106 ++--- agents/implementer.md | 2 +- hooks/workflow-preferences.sh | 2 +- skills/agent-team-development/SKILL.md | 376 --------------- skills/plan-execution/SKILL.md | 502 ++++++++++++++++++++ skills/subagent-driven-development/SKILL.md | 340 ------------- skills/systematic-debugging/SKILL.md | 2 +- skills/using-git-worktrees/SKILL.md | 15 +- skills/writing-plans/SKILL.md | 27 +- 10 files changed, 563 insertions(+), 817 deletions(-) delete mode 100644 skills/agent-team-development/SKILL.md create mode 100644 skills/plan-execution/SKILL.md delete mode 100644 skills/subagent-driven-development/SKILL.md diff --git a/CLAUDE.md b/CLAUDE.md index 511733d..5324497 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,8 +25,7 @@ claude-code-pr-workflow/ │ ├── pr-status.md # /pr-status │ └── 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 @@ -88,7 +87,7 @@ The `/pr-status` command enforces: 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 -The review bot posts 10-12 seconds after CI completes. `/pr-status` handles this automatically by polling with timestamp validation. The execution skills (`agent-team-development`, `subagent-driven-development`) use `/pr-status` in a loop: check status, fix if needed, push, re-check until READY TO MERGE. +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 @@ -103,8 +102,7 @@ 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 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/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 af3e6be..0000000 --- a/skills/agent-team-development/SKILL.md +++ /dev/null @@ -1,376 +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. Push and create PR -20. Run /pr-status to watch CI and find the review comment -21. 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. Loop back to step 20 -22. If READY TO MERGE: - a. Merge if user authorized, or report ready and wait for user -``` - -## 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-status` command - CI watch, review comment polling, readiness verdict - -**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 f5ae12b..0000000 --- a/skills/subagent-driven-development/SKILL.md +++ /dev/null @@ -1,340 +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. Push and create PR -16. Run /pr-status to watch CI and find the review comment -17. 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. Loop back to step 16 -18. If READY TO MERGE: - a. Merge if user authorized, or report ready and wait for user -``` - -## 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-status` command - CI watch, review comment polling, readiness verdict - -**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