feat: incremental reviews, timestamped dirs, worktree discovery

CLAUDE.md

@@ -50,7 +50,7 @@ Commands with Teams Variant ship as `{name}.md` (parallel subagents) and `{name}
 
 ```
 devflow/
-├── shared/skills/          # 35 skills (single source of truth)
+├── shared/skills/          # 39 skills (single source of truth)
 ├── shared/agents/          # 10 shared agents (single source of truth)
 ├── plugins/devflow-*/      # 17 plugins (8 core + 9 optional language/ecosystem)
 ├── docs/reference/         # Detailed reference documentation
@@ -90,8 +90,13 @@ All generated docs live under `.docs/` in the project root:
 
 ```
 .docs/
-├── reviews/{branch-slug}/    # Review reports per branch
-└── design/                   # Implementation plans
+├── reviews/{branch-slug}/              # Review reports per branch
+│   ├── .last-review-head              # HEAD SHA for incremental reviews
+│   └── {timestamp}/                   # Timestamped review directory
+│       ├── {focus}.md                 # Reviewer reports (security.md, etc.)
+│       ├── review-summary.md          # Synthesizer output
+│       └── resolution-summary.md      # Written by /resolve
+└── design/                            # Implementation plans
 ```
 
 Working memory files live in a dedicated `.memory/` directory:
@@ -117,7 +122,15 @@ Working memory files live in a dedicated `.memory/` directory:
 
 **Naming conventions**: Timestamps as `YYYY-MM-DD_HHMM`, branch slugs replace `/` with `-`, topic slugs are lowercase-dashes.
 
-**Persisting agents**: Reviewer → `.docs/reviews/`, Synthesizer → `.docs/reviews/` (review mode), Working Memory → `.memory/WORKING-MEMORY.md` (automatic)
+**Persisting agents**: Reviewer → `.docs/reviews/{branch-slug}/{timestamp}/{focus}.md`, Synthesizer → `.docs/reviews/{branch-slug}/{timestamp}/review-summary.md` (review mode), Resolver → `.docs/reviews/{branch-slug}/{timestamp}/resolution-summary.md`, Working Memory → `.memory/WORKING-MEMORY.md` (automatic)
+
+**Incremental Reviews**: `/code-review` writes reports into timestamped subdirectories (`YYYY-MM-DD_HHMM`) and tracks HEAD SHA in `.last-review-head` for incremental diffs. Second review only diffs from last reviewed commit. `/resolve` defaults to latest timestamped directory. Both commands auto-discover git worktrees and process all reviewable branches in parallel.
+
+**Coder Handoff Artifact**: Sequential Coder phases write `.docs/handoff.md` after each phase. Survives context compaction (unlike PRIOR_PHASE_SUMMARY). Every Coder reads it on startup. Deleted by implementation-orchestration after pipeline completes.
+
+**Universal Skill Installation**: All skills from all plugins are always installed, regardless of plugin selection. Skills are tiny markdown files. This ensures orchestration skills (review-orchestration, resolve-orchestration) can spawn agents that depend on skills from other plugins. Only commands and agents remain plugin-specific.
+
+**Model Strategy**: Explicit model assignments in agent frontmatter override the user's session model. Opus for analysis agents (reviewer, scrutinizer, shepherd), Sonnet for execution agents (coder, simplifier, resolver, skimmer), Haiku for I/O agents (git, synthesizer, validator).
 
 ## Agent & Command Roster
 
@@ -134,6 +147,8 @@ Working memory files live in a dedicated `.memory/` directory:
 
 **Plugin-specific agents** (1): claude-md-auditor
 
+**Ambient orchestration skills** (6): implementation-orchestration, debug-orchestration, plan-orchestration, review-orchestration, resolve-orchestration, pipeline-orchestration. These enable the same agent pipelines as slash commands but triggered via ambient intent classification.
+
 **Agent Teams**: 5 commands use Agent Teams (`/code-review`, `/implement`, `/debug`, `/specify`, `/resolve`). One-team-per-session constraint — must TeamDelete before creating next team.
 
 ## Key Conventions
@@ -167,7 +182,6 @@ Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore
 ## Critical Rules
 
 ### Git Safety
-- Always use `rm -f .git/index.lock &&` before git operations
 - Run git commands sequentially, never in parallel
 - Never force push without explicit user request
 

plugins/devflow-ambient/.claude-plugin/plugin.json

@@ -22,12 +22,32 @@
     "scrutinizer",
     "shepherd",
     "skimmer",
-    "reviewer"
+    "reviewer",
+    "git",
+    "synthesizer",
+    "resolver"
   ],
   "skills": [
     "ambient-router",
     "implementation-orchestration",
     "debug-orchestration",
-    "plan-orchestration"
+    "plan-orchestration",
+    "review-orchestration",
+    "resolve-orchestration",
+    "pipeline-orchestration",
+    "review-methodology",
+    "security-patterns",
+    "architecture-patterns",
+    "performance-patterns",
+    "complexity-patterns",
+    "consistency-patterns",
+    "regression-patterns",
+    "test-patterns",
+    "database-patterns",
+    "dependencies-patterns",
+    "documentation-patterns",
+    "implementation-patterns",
+    "knowledge-persistence",
+    "worktree-support"
   ]
 }

plugins/devflow-code-review/commands/code-review-teams.md

@@ -4,37 +4,67 @@ description: Comprehensive branch review using agent teams for adversarial peer
 
 # Code Review Command
 
-Run a comprehensive code review of the current branch by spawning a review team where agents debate findings, then synthesize consensus results into PR comments.
+Run a comprehensive code review of the current branch by spawning a review team where agents debate findings, then synthesize consensus results into PR comments. Supports incremental reviews, timestamped report directories, and multi-worktree auto-discovery.
 
 ## Usage
 
 ```
-/code-review           (review current branch)
+/code-review           (review current branch — or all worktrees if multiple found)
 /code-review #42       (review specific PR)
+/code-review --full    (force full-branch review, ignore previous review state)
+/code-review --path /path/to/worktree  (review a specific worktree only)
 ```
 
 ## Phases
 
-### Phase 0: Pre-Flight (Git Agent)
+### Phase 0: Worktree Discovery & Pre-Flight
 
-Spawn Git agent to validate and prepare branch:
+#### Step 0a: Discover Worktrees
+
+1. **Discover reviewable worktrees** using the `worktree-support` skill discovery algorithm:
+   - Run `git worktree list --porcelain` → parse, filter (skip protected/detached/mid-rebase), dedup by branch, sort by recent commit
+   - See `~/.claude/skills/worktree-support/SKILL.md` for the full 7-step algorithm and canonical protected branch list
+2. **If `--path` flag provided:** use only that worktree, skip discovery
+   **`--path` validation**: Before proceeding, verify the path exists as a directory and appears in `git worktree list` output. If not: report error and stop.
+3. **If only 1 reviewable worktree** (the common case): proceed as single-worktree flow — zero behavior change
+4. **If multiple reviewable worktrees:** report "Found N worktrees with reviewable branches: {list with paths and branches}" and proceed with multi-worktree flow
+
+#### Step 0b: Per-Worktree Pre-Flight (Git Agent)
+
+For each reviewable worktree, spawn Git agent:
 
 ```
 Task(subagent_type="Git", run_in_background=false):
 "OPERATION: ensure-pr-ready
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
 Validate branch, commit if needed, push, create PR if needed.
 Return: branch, base_branch, branch-slug, PR#"
 ```
 
-**If BLOCKED:** Stop and report the blocker to user.
+In multi-worktree mode, spawn all pre-flight agents **in a single message** (parallel).
+
+**If BLOCKED:** In single-worktree mode, stop and report. In multi-worktree mode, report the failure but continue with other worktrees.
 
-**Extract from response:** `branch`, `base_branch`, `branch_slug`, `pr_number` for use in subsequent phases.
+**Extract from response:** `branch`, `base_branch`, `branch_slug`, `pr_number` per worktree.
 
+#### Step 0c: Incremental Detection & Timestamp Setup
 
+For each worktree:
+
+1. Generate timestamp: `YYYY-MM-DD_HHMM`. If directory already exists (same-minute collision), append seconds (`YYYY-MM-DD_HHMMSS`).
+2. Create timestamped review directory: `mkdir -p {worktree}/.docs/reviews/{branch-slug}/{timestamp}/`
+3. Check if `{worktree}/.docs/reviews/{branch-slug}/.last-review-head` exists:
+   - **If yes AND `--full` NOT set:**
+     - Read the SHA from the file
+     - Verify reachable: `git -C {worktree} cat-file -t {sha}` (handles rebases — if unreachable, fallback to full)
+     - Check if SHA == current HEAD → if so, skip review: "No new commits since last review. Use --full for a full re-review."
+     - Set `DIFF_RANGE` to `{last-review-sha}...HEAD`
+   - **If no (first review), or `--full`:**
+     - Set `DIFF_RANGE` to `{base_branch}...HEAD`
 
 ### Phase 1: Analyze Changed Files
 
-Detect file types in diff to determine conditional reviews:
+Per worktree, detect file types in diff using `DIFF_RANGE` to determine conditional reviews:
 
 | Condition | Adds Perspective |
 |-----------|-----------------|
@@ -54,7 +84,9 @@ Detect file types in diff to determine conditional reviews:
 
 ### Phase 2: Spawn Review Team
 
-Create an agent team for adversarial review. Always include 4 core perspectives; conditionally add more based on Phase 1 analysis.
+**Per worktree**, create an agent team for adversarial review. Always include 4 core perspectives; conditionally add more based on Phase 1 analysis.
+
+**Note**: In multi-worktree mode, process worktrees sequentially for Agent Teams (one team per session constraint). Each worktree gets its own team lifecycle: create → debate → synthesize → cleanup.
 
 **Core perspectives (always):**
 - **Security**: vulnerabilities, injection, auth, crypto issues
@@ -83,65 +115,69 @@ Spawn review teammates with self-contained prompts:
 - Name: "security-reviewer"
   Prompt: |
     You are reviewing PR #{pr_number} on branch {branch} (base: {base_branch}).
+    WORKTREE_PATH: {worktree_path}  (omit if cwd)
     1. Read your skill: `Read ~/.claude/skills/security-patterns/SKILL.md`
     2. Read review methodology: `Read ~/.claude/skills/review-methodology/SKILL.md`
     3. Read `.memory/knowledge/pitfalls.md` if it exists. Check for known pitfall patterns in the diff.
-    4. Get the diff: `git diff {base_branch}...HEAD`
+    4. Get the diff: `git -C {WORKTREE_PATH} diff {DIFF_RANGE}`
     5. Apply the 6-step review process from review-methodology
     6. Focus: injection, auth bypass, crypto misuse, OWASP vulnerabilities
     7. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
     8. Include file:line references for every finding
-    9. Write your report: `Write to .docs/reviews/{branch_slug}/security.md`
+    9. Write your report: `Write to {worktree_path}/.docs/reviews/{branch_slug}/{timestamp}/security.md`
     10. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Security review done")
 
 - Name: "architecture-reviewer"
   Prompt: |
     You are reviewing PR #{pr_number} on branch {branch} (base: {base_branch}).
+    WORKTREE_PATH: {worktree_path}  (omit if cwd)
     1. Read your skill: `Read ~/.claude/skills/architecture-patterns/SKILL.md`
     2. Read review methodology: `Read ~/.claude/skills/review-methodology/SKILL.md`
     3. Read `.memory/knowledge/pitfalls.md` if it exists. Check for known pitfall patterns in the diff.
-    4. Get the diff: `git diff {base_branch}...HEAD`
+    4. Get the diff: `git -C {WORKTREE_PATH} diff {DIFF_RANGE}`
     5. Apply the 6-step review process from review-methodology
     6. Focus: SOLID violations, coupling, layering issues, modularity problems
     7. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
     8. Include file:line references for every finding
-    9. Write your report: `Write to .docs/reviews/{branch_slug}/architecture.md`
+    9. Write your report: `Write to {worktree_path}/.docs/reviews/{branch_slug}/{timestamp}/architecture.md`
     10. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Architecture review done")
 
 - Name: "performance-reviewer"
   Prompt: |
     You are reviewing PR #{pr_number} on branch {branch} (base: {base_branch}).
+    WORKTREE_PATH: {worktree_path}  (omit if cwd)
     1. Read your skill: `Read ~/.claude/skills/performance-patterns/SKILL.md`
     2. Read review methodology: `Read ~/.claude/skills/review-methodology/SKILL.md`
     3. Read `.memory/knowledge/pitfalls.md` if it exists. Check for known pitfall patterns in the diff.
-    4. Get the diff: `git diff {base_branch}...HEAD`
+    4. Get the diff: `git -C {WORKTREE_PATH} diff {DIFF_RANGE}`
     5. Apply the 6-step review process from review-methodology
     6. Focus: N+1 queries, memory leaks, algorithm issues, I/O bottlenecks
     7. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
     8. Include file:line references for every finding
-    9. Write your report: `Write to .docs/reviews/{branch_slug}/performance.md`
+    9. Write your report: `Write to {worktree_path}/.docs/reviews/{branch_slug}/{timestamp}/performance.md`
     10. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Performance review done")
 
 - Name: "quality-reviewer"
   Prompt: |
     You are reviewing PR #{pr_number} on branch {branch} (base: {base_branch}).
+    WORKTREE_PATH: {worktree_path}  (omit if cwd)
     1. Read your skills:
        - `Read ~/.claude/skills/complexity-patterns/SKILL.md`
        - `Read ~/.claude/skills/consistency-patterns/SKILL.md`
        - `Read ~/.claude/skills/test-patterns/SKILL.md`
        - `Read ~/.claude/skills/regression-patterns/SKILL.md`
     2. Read review methodology: `Read ~/.claude/skills/review-methodology/SKILL.md`
     3. Read `.memory/knowledge/pitfalls.md` if it exists. Check for known pitfall patterns in the diff.
-    4. Get the diff: `git diff {base_branch}...HEAD`
+    4. Get the diff: `git -C {WORKTREE_PATH} diff {DIFF_RANGE}`
     5. Apply the 6-step review process from review-methodology
     6. Focus: complexity, test gaps, pattern violations, regressions, naming
     7. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
     8. Include file:line references for every finding
-    9. Write your report: `Write to .docs/reviews/{branch_slug}/quality.md`
+    9. Write your report: `Write to {worktree_path}/.docs/reviews/{branch_slug}/{timestamp}/quality.md`
     10. Report completion: SendMessage(type: "message", recipient: "team-lead", summary: "Quality review done")
 
 [Add conditional perspectives based on Phase 1 — follow same pattern:
- explicit skill path, diff command, output path, SendMessage for completion]
+ explicit skill path, diff command with DIFF_RANGE, output path in timestamped dir, SendMessage for completion]
 ```
 
 ### Phase 3: Debate Round
@@ -184,13 +220,15 @@ Spawn 2 agents **in a single message**:
 ```
 Task(subagent_type="Git", run_in_background=false):
 "OPERATION: comment-pr
-Read reviews from .docs/reviews/{branch_slug}/
+WORKTREE_PATH: {worktree_path}  (omit if cwd)
+Read reviews from {worktree_path}/.docs/reviews/{branch_slug}/{timestamp}/
 Create inline PR comments. Deduplicate overlapping findings.
 Consolidate skipped findings into summary comment.
-Include confidence levels from debate consensus."
+Include confidence levels from debate consensus.
+Check for existing inline comments at same file:line before creating new ones."
 ```
 
-**Lead synthesizes review summary** (written to `.docs/reviews/{branch_slug}/review-summary.{timestamp}.md`):
+**Lead synthesizes review summary** (written to `{worktree_path}/.docs/reviews/{branch_slug}/{timestamp}/review-summary.md`):
 
 ```markdown
 ## Review Summary: {branch}
@@ -216,14 +254,21 @@ Include confidence levels from debate consensus."
 {Key exchanges that changed findings}
 ```
 
-### Phase 5: Record Pitfalls (if blocking issues found)
+### Phase 5: Write Review Head Marker
+
+Per worktree, after successful completion:
+1. Write current HEAD SHA to `{worktree_path}/.docs/reviews/{branch-slug}/.last-review-head`
+
+### Phase 6: Record Pitfalls (Sequential)
 
-If the review summary contains CRITICAL or HIGH blocking issues:
+**IMPORTANT**: Run sequentially across all worktrees (not in parallel) to avoid GitHub API conflicts.
+
+Per worktree, if the review summary contains CRITICAL or HIGH blocking issues:
 1. Read `~/.claude/skills/knowledge-persistence/SKILL.md` and follow its extraction procedure to record pitfalls to `.memory/knowledge/pitfalls.md`
 2. Source field: `/code-review {branch}`
 3. Skip entirely if no CRITICAL/HIGH blocking issues
 
-### Phase 6: Cleanup and Report
+### Phase 7: Cleanup and Report
 
 Shut down all review teammates explicitly:
 
@@ -243,18 +288,22 @@ Display results:
 - Key debate highlights
 - Artifact paths
 
+In multi-worktree mode, report results per worktree with aggregate summary.
+
 ## Architecture
 
 ```
 /code-review (orchestrator - creates team, coordinates debate)
 │
-├─ Phase 0: Pre-flight
-│  └─ Git agent (ensure-pr-ready)
+├─ Phase 0: Worktree Discovery & Pre-flight
+│  ├─ Step 0a: git worktree list → filter reviewable
+│  ├─ Step 0b: Git agent (ensure-pr-ready) per worktree [parallel]
+│  └─ Step 0c: Incremental detection + timestamp setup per worktree
 │
-├─ Phase 1: Analyze changed files
+├─ Phase 1: Analyze changed files per worktree
 │  └─ Detect file types for conditional perspectives
 │
-├─ Phase 2: Spawn review team
+├─ Phase 2: Spawn review team (per worktree, sequential for teams)
 │  ├─ Security Reviewer (teammate)
 │  ├─ Architecture Reviewer (teammate)
 │  ├─ Performance Reviewer (teammate)
@@ -265,14 +314,38 @@ Display results:
 │  └─ Reviewers challenge each other (max 2 rounds)
 │
 ├─ Phase 4: Synthesis
-│  ├─ Git agent (comment-pr with consensus findings)
+│  ├─ Git agent (comment-pr with consensus findings + dedup)
 │  └─ Lead writes review-summary with confidence levels
 │
-├─ Phase 5: Record Pitfalls (inline, if blocking issues)
+├─ Phase 5: Write .last-review-head per worktree
 │
-└─ Phase 6: Cleanup and display results
+├─ Phase 6: Record Pitfalls (SEQUENTIAL across worktrees)
+│
+└─ Phase 7: Cleanup and display results
 ```
 
+## Edge Cases
+
+| Case | Handling |
+|------|----------|
+| No new commits since last review | Skip review, report: "No new commits since last review. Use --full for a full re-review." |
+| Rebase invalidates `.last-review-head` SHA | `git cat-file -t` check fails → fallback to full diff |
+| Same-minute review collision | `mkdir` fails → retry with seconds appended (`YYYY-MM-DD_HHMMSS`) |
+| Worktree in detached HEAD | Filtered out (no branch name → not reviewable) |
+| Worktree mid-rebase or mid-merge | Filtered out by status check |
+| Two worktrees on same branch | Deduplicate by branch — review once, use first worktree's path |
+| Worktree on protected branch | Filtered out (not reviewable) |
+| Worktree pre-flight fails | Report failure, continue with other worktrees |
+| `--full` in multi-worktree mode | Applies to all worktrees (global modifier) |
+| Multi-worktree with Agent Teams | Process worktrees sequentially (one team per session) |
+| Many worktrees (5+) | Report count and proceed — user manages their worktree count |
+| Duplicate PR comments | Git agent checks for existing comments at same file:line before creating |
+
+## Backwards Compatibility
+
+- **Single worktree**: Auto-discovery finds only one worktree → proceeds exactly as before. Zero behavior change.
+- **Legacy flat layout**: New runs create timestamped subdirectories. Old flat files remain untouched.
+
 ## Principles
 
 1. **Adversarial review** - Reviewers challenge each other's findings, not just report independently
@@ -282,4 +355,5 @@ Display results:
 5. **Bounded debate** - Max 2 exchange rounds, then converge
 6. **Honest reporting** - Report disagreements with evidence, don't paper over conflicts
 7. **Cleanup always** - Team resources released even on failure
-
+8. **Incremental by default** - Only review new changes unless `--full` specified
+9. **Auto-discover worktrees** - One command handles all reviewable branches