fix: improve pr-create and pr-status reliability, consolidate pr-merge

CLAUDE.md

@@ -7,8 +7,8 @@ This file provides guidance to Claude Code when working with this plugin.
 This is a comprehensive Claude Code plugin that supports the full development workflow:
 - **Planning**: Brainstorming, specification, and implementation planning
 - **Implementation**: Test-driven development, systematic debugging, and subagent-driven execution
-- **Review**: Comprehensive code reviews with multiple agent tiers
-- **Merge**: Pre-commit verification, PR merge checklists with delayed comment detection, and git guardrails
+- **Review**: Comprehensive code reviews with multiple agent tiers, CI watching, and review comment polling
+- **Merge**: Git guardrails, readiness checks via `/pr-status`, and review-driven fix loops
 
 ## Plugin Structure
 
@@ -22,13 +22,10 @@ claude-code-pr-workflow/
 │   ├── code-verifier.md        # Pre-commit checks
 │   └── pr-verifier.md          # Pre-merge checks
 ├── commands/               # Slash commands
-│   ├── pr-create.md           # /pr-create
 │   ├── pr-status.md           # /pr-status
-│   ├── pr-merge.md            # /pr-merge
 │   └── context-recovery.md    # /context-recovery
 ├── skills/                 # Workflow skills
-│   ├── agent-team-development/        # Parallel agent teams (preferred)
-│   ├── subagent-driven-development/   # Sequential subagent execution (fallback)
+│   ├── plan-execution/                # Execute plans (agent teams or subagents)
 │   ├── test-driven-development/       # TDD workflow
 │   ├── systematic-debugging/          # Debug root cause analysis
 │   ├── writing-plans/                 # Create implementation plans
@@ -81,18 +78,16 @@ When releasing:
 
 ## Key Workflows
 
-### The Merge Checklist (Why This Matters)
+### The PR Readiness Check (Why This Matters)
 
-The `/pr-merge` command enforces:
+The `/pr-status` command enforces:
 
-1. **Typecheck** - Catch type errors before merge
-2. **CI passes** - All checks must show passed
-3. **Wait 10-12 seconds** - Review comments post AFTER CI passes
-4. **Fetch ALL comments** - Don't miss delayed bot comments
-5. **Scan for blockers** - CRITICAL, FIX, BLOCKER, DO NOT MERGE
-6. **Only merge when clear** - Human verification required
+1. **CI passes** - Watch all checks to completion
+2. **Find the review comment** - Poll until the review bot's comment from the current CI run is found
+3. **Read and assess** - Check for CRITICAL, FIX, BLOCKER, DO NOT MERGE
+4. **Never report ready without the comment** - The review always posts; wait for it
 
-**Never skip this checklist.** The 10-12 second wait catches review bot comments that post after CI completes.
+The review bot posts 10-12 seconds after CI completes. `/pr-status` handles this automatically by polling with timestamp validation. The `plan-execution` skill uses `/pr-status` in a loop: check status, fix if needed, push, re-check until READY TO MERGE.
 
 ### Agent Invocation
 
@@ -107,17 +102,15 @@ Skills provide structured workflows for common development tasks:
 - "Use dev-workflow:brainstorming" - Start design dialogue for new features
 - "Use dev-workflow:systematic-debugging" - Debug with root cause analysis
 - "Use dev-workflow:writing-plans" - Create implementation plan with tasks
-- "Use dev-workflow:agent-team-development" - Execute plans with parallel agent teams (preferred, falls back to subagent-driven-development)
-- "Use dev-workflow:subagent-driven-development" - Execute implementation plans with sequential subagents (fallback)
+- "Use dev-workflow:plan-execution" - Execute plans with agent teams or subagents (auto-selects based on availability)
 - "Use dev-workflow:test-driven-development" - TDD workflow with test-first approach
 - "Use dev-workflow:using-git-worktrees" - Isolated git worktrees for complex features
 
 ## Customization
 
 Users should customize:
-1. Typecheck commands in `/pr-create` and `/pr-merge`
-2. Review criteria in `staff-code-reviewer.md`
-3. Blocked patterns in `git-guard.py`
+1. Review criteria in `staff-code-reviewer.md`
+2. Blocked patterns in `git-guard.py`
 
 ## Compaction Hints
 

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`:

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
 ---
 

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