diff --git a/CLAUDE.md b/CLAUDE.md index 5318ce48..13adf5e2 100644 --- a/CLAUDE.md +++ b/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 diff --git a/plugins/devflow-ambient/.claude-plugin/plugin.json b/plugins/devflow-ambient/.claude-plugin/plugin.json index 7deb0e44..452719d5 100644 --- a/plugins/devflow-ambient/.claude-plugin/plugin.json +++ b/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" ] } diff --git a/plugins/devflow-code-review/commands/code-review-teams.md b/plugins/devflow-code-review/commands/code-review-teams.md index def2ca72..aabace72 100644 --- a/plugins/devflow-code-review/commands/code-review-teams.md +++ b/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,48 +115,52 @@ 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` @@ -132,16 +168,16 @@ Spawn review teammates with self-contained prompts: - `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 diff --git a/plugins/devflow-code-review/commands/code-review.md b/plugins/devflow-code-review/commands/code-review.md index af7d2747..bddc4f03 100644 --- a/plugins/devflow-code-review/commands/code-review.md +++ b/plugins/devflow-code-review/commands/code-review.md @@ -4,37 +4,67 @@ description: Comprehensive branch review using specialized sub-agents for PR rea # Code Review Command -Run a comprehensive code review of the current branch by spawning parallel review agents, then synthesizing results into PR comments. +Run a comprehensive code review of the current branch by spawning parallel review agents, then synthesizing 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). -**Extract from response:** `branch`, `base_branch`, `branch_slug`, `pr_number` for use in subsequent phases. +**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` 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 Review | |-----------|-------------| @@ -83,43 +113,58 @@ Task(subagent_type="Reviewer", run_in_background=false): "Review focusing on {focus}. Apply {focus}-patterns. Follow 6-step process from review-methodology. PR: #{pr_number}, Base: {base_branch} -IMPORTANT: Write report to .docs/reviews/{branch-slug}/{focus}.md using Write tool" +WORKTREE_PATH: {worktree_path} (omit if cwd) +DIFF_COMMAND: git -C {WORKTREE_PATH} diff {DIFF_RANGE} (omit -C flag if no WORKTREE_PATH) +IMPORTANT: Write report to {worktree_path}/.docs/reviews/{branch-slug}/{timestamp}/{focus}.md using Write tool" ``` +In multi-worktree mode, spawn ALL reviewers for ALL worktrees in one parallel message. + ### Phase 3: Synthesis (Parallel) -**WAIT** for Phase 2, then spawn 3 agents **in a single message**: +**WAIT** for Phase 2, then spawn agents per worktree **in a single message**: -**Git Agent (PR Comments)**: +**Git Agent (PR Comments)** per worktree: ``` 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 for findings with ≥80% confidence only. Lower-confidence suggestions (60-79%) go in the summary comment, not as inline comments. -Deduplicate findings across reviewers, consolidate skipped into summary." +Deduplicate findings across reviewers, consolidate skipped into summary. +Check for existing inline comments at same file:line before creating new ones to avoid duplicates." ``` -**Synthesizer Agent**: +**Synthesizer Agent** per worktree: ``` Task(subagent_type="Synthesizer", run_in_background=false): "Mode: review +WORKTREE_PATH: {worktree_path} (omit if cwd) +REVIEW_BASE_DIR: {worktree_path}/.docs/reviews/{branch-slug}/{timestamp} +TIMESTAMP: {timestamp} Aggregate findings, determine merge recommendation -Output: .docs/reviews/{branch-slug}/review-summary.{timestamp}.md" +Output: {worktree_path}/.docs/reviews/{branch-slug}/{timestamp}/review-summary.md" ``` -### Phase 4: Report +### Phase 4: Write Review Head Marker & Report -Display results from all agents: -- Merge recommendation (from Synthesizer) -- Issue counts by category (🔴 blocking / ⚠️ should-fix / ℹ️ pre-existing) -- PR comments created/skipped (from Git) -- Artifact paths +Per worktree, after successful completion: +1. Write current HEAD SHA to `{worktree_path}/.docs/reviews/{branch-slug}/.last-review-head` +2. Display results from all agents: + - Merge recommendation (from Synthesizer) + - Issue counts by category (🔴 blocking / ⚠️ should-fix / ℹ️ pre-existing) + - PR comments created/skipped (from Git) + - Artifact paths -### Phase 5: Record Pitfalls (if blocking issues found) +In multi-worktree mode, report results per worktree. -If the review summary contains CRITICAL or HIGH blocking issues: +### Phase 5: Record Pitfalls (Sequential) + +**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 @@ -129,31 +174,54 @@ If the review summary contains CRITICAL or HIGH blocking issues: ``` /code-review (orchestrator - spawns agents only) │ -├─ 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 reviews │ -├─ Phase 2: Reviews (PARALLEL) -│ ├─ Reviewer: security -│ ├─ Reviewer: architecture -│ ├─ Reviewer: performance -│ ├─ Reviewer: complexity -│ ├─ Reviewer: consistency -│ ├─ Reviewer: regression -│ ├─ Reviewer: tests -│ └─ Reviewer: [conditional: typescript, react, a11y, design, go, java, python, rust, database, deps, docs] +├─ Phase 2: Reviews (PARALLEL — all worktrees in one message) +│ ├─ Reviewer: security (per worktree) +│ ├─ Reviewer: architecture (per worktree) +│ ├─ Reviewer: performance (per worktree) +│ ├─ Reviewer: complexity (per worktree) +│ ├─ Reviewer: consistency (per worktree) +│ ├─ Reviewer: regression (per worktree) +│ ├─ Reviewer: tests (per worktree) +│ └─ Reviewer: [conditional per worktree] │ -├─ Phase 3: Synthesis (PARALLEL) -│ ├─ Git agent (comment-pr) +├─ Phase 3: Synthesis (PARALLEL per worktree) +│ ├─ Git agent (comment-pr with dedup) │ └─ Synthesizer agent (mode: review) │ -├─ Phase 4: Display results +├─ Phase 4: Write .last-review-head + display results per worktree │ -└─ Phase 5: Record Pitfalls (inline, if blocking issues) +└─ Phase 5: Record Pitfalls (SEQUENTIAL across worktrees) ``` +## 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) | +| 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**: If `.docs/reviews/{branch-slug}/` contains flat `*.md` files (no timestamped subdirectories), new runs create timestamped subdirectories. Old flat files remain untouched. + ## Principles 1. **Orchestration only** - Command spawns agents, doesn't do git/review work itself @@ -161,3 +229,5 @@ If the review summary contains CRITICAL or HIGH blocking issues: 3. **Git agent for git work** - All git operations go through Git agent 4. **Clear ownership** - Each agent owns its output completely 5. **Honest reporting** - Display agent outputs directly +6. **Incremental by default** - Only review new changes unless `--full` specified +7. **Auto-discover worktrees** - One command handles all reviewable branches diff --git a/plugins/devflow-resolve/commands/resolve-teams.md b/plugins/devflow-resolve/commands/resolve-teams.md index efb81da8..13d207a5 100644 --- a/plugins/devflow-resolve/commands/resolve-teams.md +++ b/plugins/devflow-resolve/commands/resolve-teams.md @@ -4,35 +4,69 @@ description: Process review issues using agent teams with cross-validation debat # Resolve Command -Process issues from code review reports: validate them (false positive check), assess risk for FIX vs TECH_DEBT decision, and implement fixes for low-risk issues. +Process issues from code review reports: validate them (false positive check), assess risk for FIX vs TECH_DEBT decision, and implement fixes for low-risk issues. Defaults to the latest timestamped review directory. Supports multi-worktree auto-discovery. ## Usage ``` -/resolve (resolve issues on current branch) -/resolve #42 (resolve issues for specific PR) +/resolve (resolve latest review on current branch — or all worktrees) +/resolve #42 (resolve issues for specific PR) +/resolve --review 2026-03-28_0900 (resolve a specific review run by timestamp) +/resolve --path /path/to/worktree (resolve a specific worktree only) ``` ## Phases -### Phase 0: Pre-Flight (Git Agent) +### Phase 0: Worktree Discovery & Pre-Flight -Spawn Git agent to validate branch state: +#### Step 0a: Discover Worktrees + +1. **Discover resolvable 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 + - Additional filter: must have unresolved reviews (latest review directory has no `resolution-summary.md`) +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 resolvable worktree** (the common case): proceed as single-worktree flow — zero behavior change +4. **If multiple resolvable worktrees:** report "Found N worktrees with unresolved reviews: {list}" and proceed with multi-worktree flow + +#### Step 0b: Per-Worktree Pre-Flight (Git Agent) + +For each resolvable worktree, spawn Git agent: ``` Task(subagent_type="Git", run_in_background=false): "OPERATION: validate-branch +WORKTREE_PATH: {worktree_path} (omit if cwd) Check feature branch, clean working directory, reviews exist. Return: branch, branch-slug, PR#, review count" ``` -**If BLOCKED:** Stop and report the blocker to user. If no reviews found, suggest `/code-review` first. +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 failure, continue with other worktrees. + +**Extract from response:** `branch`, `branch_slug`, `pr_number`, `review_count` per worktree. + +#### Step 0c: Target Review Directory + +For each worktree: -**Extract from response:** `branch`, `branch_slug`, `pr_number`, `review_count` for use in subsequent phases. +1. List directories in `{worktree}/.docs/reviews/{branch-slug}/` +2. **If `--review {timestamp}` provided:** use that specific directory (not supported in multi-worktree mode) +3. **Otherwise:** sort directories by name (timestamps are naturally sortable), select the latest that contains `review-summary.md` (complete review) +4. **If latest directory already has `resolution-summary.md`:** skip worktree — already resolved +5. **Legacy fallback:** if no timestamped subdirectories exist but flat `*.md` files do, read them directly (backwards compatible) + +Set `TARGET_DIR` to the selected review directory path. ### Phase 1: Parse Issues -Read all review reports from `.docs/reviews/{branch-slug}/*.md` and extract: +Read review reports from `{TARGET_DIR}/*.md` and extract: + +**Exclude from issue extraction:** +- `review-summary.md` (synthesizer output, not individual findings) +- `resolution-summary.md` (if it exists from a previous partial run) **Include only:** - Blocking issues (CRITICAL, HIGH) @@ -72,6 +106,8 @@ Create execution plan: **With Agent Teams:** +**Note**: In multi-worktree mode, process worktrees sequentially for Agent Teams (one team per session constraint). + Create a resolution team for cross-validated fixes: ``` @@ -82,11 +118,12 @@ Spawn resolver teammates with self-contained prompts (one per independent batch) - Name: "resolver-batch-1" Prompt: | You are resolving review issues on branch {branch} (PR #{pr_number}). + WORKTREE_PATH: {worktree_path} (omit if cwd) 1. Read your skill: `Read ~/.claude/skills/implementation-patterns/SKILL.md` 2. Your issues to resolve: {batch 1 issues — full structured list with id, file, line, severity, type, description, suggested_fix} 3. For each issue: - a. Read the code context around file:line + a. Read the code context around file:line (use WORKTREE_PATH prefix if provided) b. Validate: is this a real issue or false positive? c. If real: assess risk (LOW → FIX now, HIGH → defer to TECH_DEBT) d. If FIX: implement the fix, commit with descriptive message @@ -98,11 +135,12 @@ Spawn resolver teammates with self-contained prompts (one per independent batch) - Name: "resolver-batch-2" Prompt: | You are resolving review issues on branch {branch} (PR #{pr_number}). + WORKTREE_PATH: {worktree_path} (omit if cwd) 1. Read your skill: `Read ~/.claude/skills/implementation-patterns/SKILL.md` 2. Your issues to resolve: {batch 2 issues — full structured list with id, file, line, severity, type, description, suggested_fix} 3. For each issue: - a. Read the code context around file:line + a. Read the code context around file:line (use WORKTREE_PATH prefix if provided) b. Validate: is this a real issue or false positive? c. If real: assess risk (LOW → FIX now, HIGH → defer to TECH_DEBT) d. If FIX: implement the fix, commit with descriptive message @@ -150,7 +188,9 @@ Aggregate from all Resolvers: - **Deferred**: High-risk issues marked for tech debt - **Blocked**: Issues that couldn't be fixed -### Phase 6: Record Pitfalls (from tech debt deferrals) +### Phase 6: Record Pitfalls (Sequential) + +**IMPORTANT**: Run sequentially across all worktrees (not in parallel) to avoid GitHub API conflicts. For each issue deferred as TECH_DEBT: 1. Read `~/.claude/skills/knowledge-persistence/SKILL.md` and follow its extraction procedure to record pitfalls to `.memory/knowledge/pitfalls.md` @@ -164,31 +204,35 @@ If any fixes were made, spawn Simplifier agent to refine the changed code: ``` Task(subagent_type="Simplifier", run_in_background=false): "TASK_DESCRIPTION: Issue resolution fixes +WORKTREE_PATH: {worktree_path} (omit if cwd) FILES_CHANGED: {list of files modified by Resolvers} Simplify and refine the fixes for clarity and consistency" ``` -### Phase 8: Manage Tech Debt +### Phase 8: Manage Tech Debt (Sequential) + +**IMPORTANT**: Run sequentially across all worktrees (not in parallel) to avoid GitHub API conflicts. If any issues were deferred, spawn Git agent: ``` Task(subagent_type="Git"): "OPERATION: manage-debt -REVIEW_DIR: .docs/reviews/{branch-slug}/ +WORKTREE_PATH: {worktree_path} (omit if cwd) +REVIEW_DIR: {TARGET_DIR} TIMESTAMP: {timestamp} -Note: Deferred issues from resolution are already in resolution-summary.{timestamp}.md" +Note: Deferred issues from resolution are already in resolution-summary.md" ``` ### Phase 9: Report -**Write the resolution summary** to `.docs/reviews/{branch-slug}/resolution-summary.{timestamp}.md` using Write tool, then display: +**Write the resolution summary** to `{TARGET_DIR}/resolution-summary.md` using Write tool, then display: ``` ## Resolution Summary **Branch**: {branch} -**Reviews Processed**: {n} reports +**Reviews Processed**: {n} reports from {TARGET_DIR} **Total Issues**: {n} ### Results @@ -206,19 +250,23 @@ Note: Deferred issues from resolution are already in resolution-summary.{timesta - {n} items added to backlog ### Artifacts -- Resolution report: .docs/reviews/{branch}/resolution-summary.{timestamp}.md +- Resolution report: {TARGET_DIR}/resolution-summary.md ``` +In multi-worktree mode, report results per worktree with aggregate summary. + ## Architecture ``` /resolve (orchestrator - spawns teams and agents) │ -├─ Phase 0: Pre-flight -│ └─ Git agent (validate-branch) +├─ Phase 0: Worktree Discovery & Pre-flight +│ ├─ Step 0a: git worktree list → filter resolvable +│ ├─ Step 0b: Git agent (validate-branch) per worktree [parallel] +│ └─ Step 0c: Target latest review directory per worktree │ -├─ Phase 1: Parse issues -│ └─ Extract Blocking + Should-Fix (skip Pre-existing) +├─ Phase 1: Parse issues from TARGET_DIR +│ └─ Extract Blocking + Should-Fix (skip Pre-existing, exclude summaries) │ ├─ Phase 2: Analyze dependencies │ └─ Build dependency graph @@ -226,7 +274,7 @@ Note: Deferred issues from resolution are already in resolution-summary.{timesta ├─ Phase 3: Plan batches │ └─ Group issues, determine parallel vs sequential │ -├─ Phase 4: Resolve (Agent Teams with cross-validation) +├─ Phase 4: Resolve (Agent Teams with cross-validation, per worktree sequential) │ ├─ Resolver: Batch 1 (teammate) │ ├─ Resolver: Batch 2 (teammate) │ ├─ Resolver: Batch 3 (teammate, waits if depends on 1 or 2) @@ -235,15 +283,15 @@ Note: Deferred issues from resolution are already in resolution-summary.{timesta ├─ Phase 5: Collect results │ └─ Aggregate fixed, false positives, deferred, blocked │ -├─ Phase 6: Record Pitfalls (inline, from tech debt deferrals) +├─ Phase 6: Record Pitfalls (SEQUENTIAL across worktrees) │ ├─ Phase 7: Simplify │ └─ Simplifier agent (refine fixes) │ -├─ Phase 8: Git agent (manage-debt) +├─ Phase 8: Git agent (manage-debt) — SEQUENTIAL across worktrees │ └─ Add deferred items to Tech Debt Backlog │ -└─ Phase 9: Display resolution summary +└─ Phase 9: Write resolution-summary.md + display results ``` ## Edge Cases @@ -255,6 +303,11 @@ Note: Deferred issues from resolution are already in resolution-summary.{timesta | Fix attempt fails | Revert changes, mark BLOCKED, continue others | | Issue dependencies | Sequential chain, skip dependents if predecessor blocked | | No actionable issues | Report "No issues to resolve" (all were pre-existing or LOW) | +| Incomplete review directory | Skip — resolve only targets complete reviews | +| Latest review already resolved | Skip worktree, suggest /code-review first | +| Legacy flat layout | Read flat *.md files directly (backwards compatible) | +| `--review` in multi-worktree mode | Not supported — use `--path` + `--review` for specific worktree | +| Multi-worktree with Agent Teams | Process worktrees sequentially (one team per session) | ## Principles @@ -264,16 +317,19 @@ Note: Deferred issues from resolution are already in resolution-summary.{timesta 4. **Conservative risk** - When Resolvers are unsure, defer to tech debt 5. **Honest reporting** - Display agent outputs directly 6. **Complete tracking** - Every issue gets a decision recorded +7. **Latest review by default** - Only process the most recent complete review +8. **Auto-discover worktrees** - One command handles all resolvable branches ## Output Artifact -Written by orchestrator in Phase 9 to `.docs/reviews/{branch-slug}/resolution-summary.{timestamp}.md`: +Written by orchestrator in Phase 9 to `{TARGET_DIR}/resolution-summary.md`: ```markdown # Resolution Summary **Branch**: {branch} -> {base} **Date**: {timestamp} +**Review**: {TARGET_DIR} **Command**: /resolve ## Statistics diff --git a/plugins/devflow-resolve/commands/resolve.md b/plugins/devflow-resolve/commands/resolve.md index 37e78289..b4e75e0e 100644 --- a/plugins/devflow-resolve/commands/resolve.md +++ b/plugins/devflow-resolve/commands/resolve.md @@ -4,35 +4,69 @@ description: Process review issues - validate, assess risk, fix low-risk issues, # Resolve Command -Process issues from code review reports: validate them (false positive check), assess risk for FIX vs TECH_DEBT decision, and implement fixes for low-risk issues. +Process issues from code review reports: validate them (false positive check), assess risk for FIX vs TECH_DEBT decision, and implement fixes for low-risk issues. Defaults to the latest timestamped review directory. Supports multi-worktree auto-discovery. ## Usage ``` -/resolve (resolve issues on current branch) -/resolve #42 (resolve issues for specific PR) +/resolve (resolve latest review on current branch — or all worktrees) +/resolve #42 (resolve issues for specific PR) +/resolve --review 2026-03-28_0900 (resolve a specific review run by timestamp) +/resolve --path /path/to/worktree (resolve a specific worktree only) ``` ## Phases -### Phase 0: Pre-Flight (Git Agent) +### Phase 0: Worktree Discovery & Pre-Flight -Spawn Git agent to validate branch state: +#### Step 0a: Discover Worktrees + +1. **Discover resolvable 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 + - Additional filter: must have unresolved reviews (latest review directory has no `resolution-summary.md`) +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 resolvable worktree** (the common case): proceed as single-worktree flow — zero behavior change +4. **If multiple resolvable worktrees:** report "Found N worktrees with unresolved reviews: {list}" and proceed with multi-worktree flow + +#### Step 0b: Per-Worktree Pre-Flight (Git Agent) + +For each resolvable worktree, spawn Git agent: ``` Task(subagent_type="Git", run_in_background=false): "OPERATION: validate-branch +WORKTREE_PATH: {worktree_path} (omit if cwd) Check feature branch, clean working directory, reviews exist. Return: branch, branch-slug, PR#, review count" ``` -**If BLOCKED:** Stop and report the blocker to user. If no reviews found, suggest `/code-review` first. +In multi-worktree mode, spawn all pre-flight agents **in a single message** (parallel). + +**If BLOCKED:** In single-worktree mode, stop and report the blocker to user. If no reviews found, suggest `/code-review` first. In multi-worktree mode, report the failure but continue with other worktrees. + +**Extract from response:** `branch`, `branch_slug`, `pr_number`, `review_count` per worktree. + +#### Step 0c: Target Review Directory -**Extract from response:** `branch`, `branch_slug`, `pr_number`, `review_count` for use in subsequent phases. +For each worktree: + +1. List directories in `{worktree}/.docs/reviews/{branch-slug}/` +2. **If `--review {timestamp}` provided:** use that specific directory (not supported in multi-worktree mode) +3. **Otherwise:** sort directories by name (timestamps are naturally sortable), select the latest that contains `review-summary.md` (complete review) +4. **If latest directory already has `resolution-summary.md`:** skip worktree — already resolved. Report: "Latest review already resolved. Run /code-review for a new review first." +5. **Legacy fallback:** if no timestamped subdirectories exist but flat `*.md` files do in `{worktree}/.docs/reviews/{branch-slug}/`, read them directly (backwards compatible) + +Set `TARGET_DIR` to the selected review directory path. ### Phase 1: Parse Issues -Read all review reports from `.docs/reviews/{branch-slug}/*.md` and extract: +Read review reports from `{TARGET_DIR}/*.md` and extract: + +**Exclude from issue extraction:** +- `review-summary.md` (synthesizer output, not individual findings) +- `resolution-summary.md` (if it exists from a previous partial run) **Include only:** - Blocking issues (CRITICAL, HIGH) @@ -77,6 +111,7 @@ Task(subagent_type="Resolver"): "ISSUES: [{issue1}, {issue2}, ...] BRANCH: {branch-slug} BATCH_ID: batch-{n} +WORKTREE_PATH: {worktree_path} (omit if cwd) Validate, decide FIX vs TECH_DEBT, implement fixes" ``` @@ -90,7 +125,9 @@ Aggregate from all Resolvers: - **Deferred**: High-risk issues marked for tech debt - **Blocked**: Issues that couldn't be fixed -### Phase 6: Record Pitfalls (from tech debt deferrals) +### Phase 6: Record Pitfalls (Sequential) + +**IMPORTANT**: Run sequentially across all worktrees (not in parallel) to avoid GitHub API conflicts. For each issue deferred as TECH_DEBT: 1. Read `~/.claude/skills/knowledge-persistence/SKILL.md` and follow its extraction procedure to record pitfalls to `.memory/knowledge/pitfalls.md` @@ -104,31 +141,35 @@ If any fixes were made, spawn Simplifier agent to refine the changed code: ``` Task(subagent_type="Simplifier", run_in_background=false): "TASK_DESCRIPTION: Issue resolution fixes +WORKTREE_PATH: {worktree_path} (omit if cwd) FILES_CHANGED: {list of files modified by Resolvers} Simplify and refine the fixes for clarity and consistency" ``` -### Phase 8: Manage Tech Debt +### Phase 8: Manage Tech Debt (Sequential) + +**IMPORTANT**: Run sequentially across all worktrees (not in parallel) to avoid GitHub API conflicts. If any issues were deferred, spawn Git agent: ``` Task(subagent_type="Git"): "OPERATION: manage-debt -REVIEW_DIR: .docs/reviews/{branch-slug}/ +WORKTREE_PATH: {worktree_path} (omit if cwd) +REVIEW_DIR: {TARGET_DIR} TIMESTAMP: {timestamp} -Note: Deferred issues from resolution are already in resolution-summary.{timestamp}.md" +Note: Deferred issues from resolution are already in resolution-summary.md" ``` ### Phase 9: Report -**Write the resolution summary** to `.docs/reviews/{branch-slug}/resolution-summary.{timestamp}.md` using Write tool, then display: +**Write the resolution summary** to `{TARGET_DIR}/resolution-summary.md` using Write tool, then display: ``` ## Resolution Summary **Branch**: {branch} -**Reviews Processed**: {n} reports +**Reviews Processed**: {n} reports from {TARGET_DIR} **Total Issues**: {n} ### Results @@ -146,19 +187,23 @@ Note: Deferred issues from resolution are already in resolution-summary.{timesta - {n} items added to backlog ### Artifacts -- Resolution report: .docs/reviews/{branch}/resolution-summary.{timestamp}.md +- Resolution report: {TARGET_DIR}/resolution-summary.md ``` +In multi-worktree mode, report results per worktree with aggregate summary. + ## Architecture ``` /resolve (orchestrator - spawns agents only) │ -├─ Phase 0: Pre-flight -│ └─ Git agent (validate-branch) +├─ Phase 0: Worktree Discovery & Pre-flight +│ ├─ Step 0a: git worktree list → filter resolvable +│ ├─ Step 0b: Git agent (validate-branch) per worktree [parallel] +│ └─ Step 0c: Target latest review directory per worktree │ -├─ Phase 1: Parse issues -│ └─ Extract Blocking + Should-Fix (skip Pre-existing) +├─ Phase 1: Parse issues from TARGET_DIR +│ └─ Extract Blocking + Should-Fix (skip Pre-existing, exclude summaries) │ ├─ Phase 2: Analyze dependencies │ └─ Build dependency graph @@ -174,15 +219,15 @@ Note: Deferred issues from resolution are already in resolution-summary.{timesta ├─ Phase 5: Collect results │ └─ Aggregate fixed, false positives, deferred, blocked │ -├─ Phase 6: Record Pitfalls (inline, from tech debt deferrals) +├─ Phase 6: Record Pitfalls (SEQUENTIAL across worktrees) │ ├─ Phase 7: Simplify │ └─ Simplifier agent (refine fixes) │ -├─ Phase 8: Git agent (manage-debt) +├─ Phase 8: Git agent (manage-debt) — SEQUENTIAL across worktrees │ └─ Add deferred items to Tech Debt Backlog │ -└─ Phase 9: Display resolution summary +└─ Phase 9: Write resolution-summary.md + display results ``` ## Edge Cases @@ -194,6 +239,11 @@ Note: Deferred issues from resolution are already in resolution-summary.{timesta | Fix attempt fails | Revert changes, mark BLOCKED, continue others | | Issue dependencies | Sequential chain, skip dependents if predecessor blocked | | No actionable issues | Report "No issues to resolve" (all were pre-existing or LOW) | +| Incomplete review directory (no review-summary.md) | Skip — resolve only targets complete reviews | +| Latest review already resolved | Skip worktree, report suggestion to run /code-review first | +| Legacy flat layout (no subdirectories) | Read flat *.md files directly (backwards compatible) | +| `--review {timestamp}` in multi-worktree mode | Not supported — use `--path` + `--review` to target specific worktree + review | +| Worktree pre-flight fails | Report failure, continue with other worktrees | ## Principles @@ -203,16 +253,19 @@ Note: Deferred issues from resolution are already in resolution-summary.{timesta 4. **Conservative risk** - When Resolvers are unsure, defer to tech debt 5. **Honest reporting** - Display agent outputs directly 6. **Complete tracking** - Every issue gets a decision recorded +7. **Latest review by default** - Only process the most recent complete review +8. **Auto-discover worktrees** - One command handles all resolvable branches ## Output Artifact -Written by orchestrator in Phase 9 to `.docs/reviews/{branch-slug}/resolution-summary.{timestamp}.md`: +Written by orchestrator in Phase 9 to `{TARGET_DIR}/resolution-summary.md`: ```markdown # Resolution Summary **Branch**: {branch} -> {base} **Date**: {timestamp} +**Review**: {TARGET_DIR} **Command**: /resolve ## Statistics diff --git a/scripts/hooks/ambient-prompt b/scripts/hooks/ambient-prompt index cdecad01..dd9d1a1a 100755 --- a/scripts/hooks/ambient-prompt +++ b/scripts/hooks/ambient-prompt @@ -36,14 +36,20 @@ fi # No fast-path filtering — the LLM handles QUICK classification reliably and # shell-level regex was causing false positives that silently broke ambient mode. # SYNC: must match tests/ambient.test.ts preamble drift detection -PREAMBLE="AMBIENT MODE: Classify depth then act. QUICK=chat/explore/git/config/trivial: respond normally. GUIDED=implement(1-2 files)/debug(clear error)/plan(focused)/review: load skills. ORCHESTRATED=implement(3+ files)/debug(vague)/architecture: load skills+agents. Prefer GUIDED for code changes. +PREAMBLE="AMBIENT MODE: Classify depth then act. QUICK=chat/explore/git/config/trivial: respond normally. GUIDED=implement(1-2 files)/debug(clear error)/plan(focused)/review(small scope): load skills. ORCHESTRATED=implement(3+ files)/debug(vague)/architecture/review(full/branch/PR)/resolve/pipeline: load skills+agents. Prefer GUIDED for code changes. +REVIEW depth: continuation-aware (match prior IMPLEMENT depth) or signal-word based (full/branch/PR→ORCHESTRATED, check this/specific file→GUIDED). +RESOLVE: always ORCHESTRATED. PIPELINE (end-to-end/implement and review): always ORCHESTRATED. +MULTI_WORKTREE: all worktrees/branches, each worktree, review everything, resolve all → ORCHESTRATED. Follow code-review/resolve command flow (auto-discovers worktrees). GUIDED/ORCHESTRATED: Call Skill tool for ALL skills listed for intent — one Skill call per skill, before ANY text. IMPLEMENT → test-driven-development, implementation-patterns, search-first DEBUG → core-patterns, test-patterns -REVIEW → self-review, core-patterns +REVIEW/GUIDED → self-review, core-patterns +REVIEW/ORCHESTRATED → review-orchestration +RESOLVE → resolve-orchestration, core-patterns +PIPELINE → pipeline-orchestration, implementation-patterns PLAN → implementation-patterns, core-patterns Also add if file type matches: typescript, react, go, java, python, rust, input-validation, security-patterns, frontend-design -ORCHESTRATED also add: implementation-orchestration / debug-orchestration / plan-orchestration +ORCHESTRATED also add: implementation-orchestration / debug-orchestration / plan-orchestration / review-orchestration / resolve-orchestration / pipeline-orchestration State: Ambient: INTENT/DEPTH. Loading: skills. Then proceed." json_prompt_output "$PREAMBLE" diff --git a/shared/agents/coder.md b/shared/agents/coder.md index f5485989..5a7474b5 100644 --- a/shared/agents/coder.md +++ b/shared/agents/coder.md @@ -1,8 +1,8 @@ --- name: Coder description: Autonomous task implementation on feature branch. Implements, tests, and commits. -model: inherit -skills: core-patterns, git-safety, implementation-patterns, git-workflow, test-patterns, test-driven-development, search-first, input-validation +model: sonnet +skills: core-patterns, git-safety, implementation-patterns, git-workflow, test-patterns, test-driven-development, search-first, input-validation, worktree-support --- # Coder Agent @@ -22,6 +22,8 @@ You receive from orchestrator: **Domain hint** (optional): - **DOMAIN**: `backend` | `frontend` | `tests` | `fullstack` - Load/apply relevant domain skills +**Worktree Support**: If `WORKTREE_PATH` is provided, follow the `worktree-support` skill for path resolution. If omitted, use cwd. + **Sequential execution context** (when part of multi-Coder chain): - **PRIOR_PHASE_SUMMARY**: Implementation summary from previous Coder (see format below) - **FILES_FROM_PRIOR_PHASE**: Files created that must be read and understood @@ -37,6 +39,7 @@ You receive from orchestrator: - If PRIOR_PHASE_SUMMARY is provided, use it to validate your understanding — actual code is authoritative, summaries are supplementary - If `.memory/knowledge/decisions.md` exists, read it. Apply prior architectural decisions relevant to this task. Avoid contradicting accepted decisions without documenting a new ADR. - If `.memory/knowledge/pitfalls.md` exists, scan for pitfalls in files you're about to modify. + - If `.docs/handoff.md` exists, read it for prior phase context. Cross-reference against actual code — code is authoritative, handoff is supplementary. 2. **Load domain skills**: Based on DOMAIN hint and files in scope, dynamically load relevant language/ecosystem skills by reading their SKILL.md. Only load skills that are installed: - `backend` (TypeScript): Read `~/.claude/skills/typescript/SKILL.md`, `~/.claude/skills/input-validation/SKILL.md` diff --git a/shared/agents/git.md b/shared/agents/git.md index 3f718033..0c30662a 100644 --- a/shared/agents/git.md +++ b/shared/agents/git.md @@ -2,7 +2,7 @@ name: Git description: Unified agent for all git/GitHub operations - issues, PR comments, tech debt, releases model: haiku -skills: github-patterns, git-safety, git-workflow +skills: github-patterns, git-safety, git-workflow, worktree-support --- # Git Agent @@ -15,16 +15,18 @@ The orchestrator provides: - **OPERATION**: Which task to perform - **Operation-specific parameters**: See each operation below +**Worktree Support**: If `WORKTREE_PATH` is provided, follow the `worktree-support` skill for path resolution. If omitted, use cwd. + ## Operations | Operation | Purpose | Key Parameters | |-----------|---------|----------------| -| `ensure-pr-ready` | Pre-flight for /review: commit, push, create PR | - | -| `validate-branch` | Pre-flight for /resolve: check branch state | - | +| `ensure-pr-ready` | Pre-flight for /review: commit, push, create PR | `WORKTREE_PATH` (optional) | +| `validate-branch` | Pre-flight for /resolve: check branch state | `WORKTREE_PATH` (optional) | | `setup-task` | Create feature branch and fetch issue | `BASE_BRANCH`, `ISSUE_INPUT` (optional), `TASK_DESCRIPTION` (optional) | | `fetch-issue` | Fetch GitHub issue for implementation | `ISSUE_INPUT` (number or search term) | -| `comment-pr` | Create PR inline comments for review findings | `PR_NUMBER`, `REVIEW_BASE_DIR`, `TIMESTAMP` | -| `manage-debt` | Update tech debt backlog with pre-existing issues | `REVIEW_DIR`, `TIMESTAMP` | +| `comment-pr` | Create PR inline comments for review findings | `PR_NUMBER`, `REVIEW_BASE_DIR`, `TIMESTAMP`, `WORKTREE_PATH` (optional) | +| `manage-debt` | Update tech debt backlog with pre-existing issues | `REVIEW_DIR`, `TIMESTAMP`, `WORKTREE_PATH` (optional) | | `create-release` | Create GitHub release with version tag | `VERSION`, `CHANGELOG_CONTENT` | --- @@ -33,10 +35,10 @@ The orchestrator provides: Pre-flight checks and fixes for `/code-review`. Ensures branch is ready for code review. -**Input:** None (uses current branch) +**Input:** `WORKTREE_PATH` (optional) **Process:** -1. Verify on feature branch (not main/master/develop) - error if not +1. Verify on feature branch (not main/master/develop/release/*/staging/production) - error if not 2. Check for uncommitted changes - if any, create atomic commit using `git-workflow` patterns 3. Check if branch pushed to remote - if not, push with `-u` flag 4. Check if PR exists - if not, create PR using `git-workflow` patterns @@ -68,14 +70,14 @@ Pre-flight checks and fixes for `/code-review`. Ensures branch is ready for code Pre-flight validation for `/resolve`. Checks branch state without modifications. -**Input:** None (uses current branch) +**Input:** `WORKTREE_PATH` (optional) **Process:** -1. Verify on feature branch (not main/master/develop) - error if not +1. Verify on feature branch (not main/master/develop/release/*/staging/production) - error if not 2. Verify working directory is clean - error if uncommitted changes 3. Get current branch name 4. Derive branch-slug (replace `/` with `-`) -5. Check if reviews exist at `.docs/reviews/{branch-slug}/` +5. Check if reviews exist at `{WORKTREE_PATH}/.docs/reviews/{branch-slug}/` (or `.docs/reviews/{branch-slug}/` if no WORKTREE_PATH) 6. If PR# context provided, fetch PR details **Output:** @@ -171,16 +173,18 @@ Fetch comprehensive issue details for implementation planning. Create inline PR comments for blocking and should-fix issues from code review. -**Input:** `PR_NUMBER`, `REVIEW_BASE_DIR`, `TIMESTAMP` +**Input:** `PR_NUMBER`, `REVIEW_BASE_DIR`, `TIMESTAMP`, `WORKTREE_PATH` (optional) **Process:** 1. Get PR context (head SHA, changed files, diff) -2. Read review reports from `${REVIEW_BASE_DIR}/*.md` +2. Read review reports from `${REVIEW_BASE_DIR}/*.md` (exclude `review-summary.md` and `resolution-summary.md`) 3. Extract issues - only comment on blocking (CRITICAL/HIGH) and should-fix (HIGH/MEDIUM) 4. Skip pre-existing issues (these go to tech debt) 5. Deduplicate issues by file:line -6. Create inline comments for lines in diff; consolidate others into summary comment -7. Include 1-second delay between API calls for rate limiting +6. **Deduplicate efficiently**: Fetch all existing PR review comments once via `gh api repos/{owner}/{repo}/pulls/{pr_number}/comments`. Build a lookup set of `{path}:{line}` pairs from the response. For each new comment, check the lookup — skip if already present. This replaces per-comment checking. +7. Create inline comments for lines in diff; consolidate others into summary comment +8. Include 1-second delay between API calls for rate limiting +9. **Rate limit awareness**: Before posting a batch of comments, check `X-RateLimit-Remaining` from the last API response header. If remaining < 50: warn user and reduce posting rate (add 3s delay between calls). If remaining < 10: stop posting, report which comments were skipped due to rate limits. **Output:** ```markdown @@ -189,7 +193,8 @@ Create inline PR comments for blocking and should-fix issues from code review. ### Inline Comments - Created: {n} -- Skipped: {n} (lines not in diff) +- Skipped (already exists): {n} +- Skipped (lines not in diff): {n} ### Summary Comment {Created | Not needed} @@ -201,7 +206,7 @@ Create inline PR comments for blocking and should-fix issues from code review. Update tech debt backlog with pre-existing issues from code review. -**Input:** `REVIEW_DIR`, `TIMESTAMP` +**Input:** `REVIEW_DIR`, `TIMESTAMP`, `WORKTREE_PATH` (optional) **Process:** 1. Find or create "Tech Debt Backlog" issue with `tech-debt` label @@ -257,7 +262,7 @@ Create a GitHub release with version tag. 1. **Rate limit aware** - Always throttle API calls (1s delay between comments) 2. **Fail gracefully** - Log errors but continue with remaining operations -3. **Deduplicate** - Never spam duplicate comments or issues +3. **Deduplicate** - Never spam duplicate comments or issues; check for existing comments before creating 4. **Actionable output** - Every response includes next steps 5. **Clear attribution** - Include Claude Code footer on PR comments 6. **Be decisive** - Make confident choices about categorization diff --git a/shared/agents/resolver.md b/shared/agents/resolver.md index 723c5615..04e3431a 100644 --- a/shared/agents/resolver.md +++ b/shared/agents/resolver.md @@ -1,13 +1,13 @@ --- name: Resolver -description: Validates review issues, decides FIX vs TECH_DEBT based on risk, implements fixes -model: inherit -skills: core-patterns, git-safety, implementation-patterns, git-workflow +description: Validates review issues, implements fixes with risk-proportional care. Tech debt only for architectural overhauls. +model: sonnet +skills: core-patterns, git-safety, implementation-patterns, git-workflow, worktree-support --- # Resolver Agent -You are an issue resolution specialist. You validate review issues, decide whether to fix or defer based on risk, and implement low-risk fixes. You make conservative risk assessments - when in doubt, defer to tech debt. +You are an issue resolution specialist. You validate review issues and implement fixes with risk-proportional care. You fix everything that can be fixed safely. Tech debt is the absolute last resort — only for issues requiring complete architectural redesign. ## Input Context @@ -16,6 +16,8 @@ You receive from orchestrator: - **BRANCH**: Current branch slug - **BATCH_ID**: Identifier for this batch of issues +**Worktree Support**: If `WORKTREE_PATH` is provided, follow the `worktree-support` skill for path resolution. If omitted, use cwd. + ## Responsibilities 1. **Validate each issue**: Read file context (30 lines around the line number). Check: @@ -38,7 +40,7 @@ You receive from orchestrator: ## Risk Assessment -**LOW_RISK (fix now):** +**Standard fixes** (fix directly): - Adding null checks, validation - Fixing documentation/typos - Adding error handling (no flow change) @@ -48,15 +50,22 @@ You receive from orchestrator: - Improving logging - Security fixes in isolated scope -**HIGH_RISK (defer to tech debt):** -- Refactoring working functionality -- Changing function signatures with callers -- Modifying shared state/data models -- Architectural pattern changes -- Database migrations -- Multi-service changes -- Auth flow changes +**Careful fixes** (test-first approach): +- Changes to public APIs or function signatures +- Modifications to shared state or data models - Changes touching >3 files +- Core business logic modifications +- Multi-service interface changes +- Auth flow changes + +For careful fixes: write tests first covering current behavior → apply fix → verify tests still pass → commit. + +**Architectural overhaul** (defer to tech debt — LAST RESORT): +- Requires complete system redesign (e.g., fundamentally different architecture) +- Database schema migrations requiring coordinated multi-service deployment +- Changes that cannot be safely validated with tests alone + +This is the ONLY case where deferral is appropriate. "Touches many files" or "changes public API" are NOT reasons to defer — they're reasons to be careful. ## Decision Flow @@ -66,19 +75,21 @@ For each issue: ├─ Still present? NO → FALSE_POSITIVE ├─ Reviewer understood correctly? NO → FALSE_POSITIVE ├─ Code is intentional? YES → FALSE_POSITIVE (document reasoning) +├─ Understand existing design/behavior/UX before changing anything └─ Risk Assessment: - ├─ Changes public API? → HIGH_RISK → TECH_DEBT - ├─ Modifies core business logic? → HIGH_RISK → TECH_DEBT - ├─ Touches >3 files? → HIGH_RISK → TECH_DEBT - ├─ Changes data structures? → HIGH_RISK → TECH_DEBT - ├─ Requires migration? → HIGH_RISK → TECH_DEBT - └─ Otherwise → LOW_RISK → FIX + ├─ Requires complete architectural redesign? → TECH_DEBT (last resort) + ├─ Changes public API / shared state / >3 files / core logic? → CAREFUL FIX + │ ├─ Write tests covering current behavior first + │ ├─ Apply fix + │ ├─ Verify tests pass + │ └─ Commit + └─ Otherwise → STANDARD FIX → implement directly ``` ## Principles 1. **Validate before acting** - Never fix an issue without confirming it exists -2. **Conservative risk assessment** - When uncertain, defer to tech debt +2. **Risk-proportional care** - Standard fixes go fast, careful fixes get tests first, only architectural overhauls get deferred 3. **Document all decisions** - Every issue gets reasoning recorded 4. **Atomic commits** - One commit per batch with clear message 5. **Follow existing patterns** - Match codebase style exactly diff --git a/shared/agents/reviewer.md b/shared/agents/reviewer.md index 6eac4a0b..4beb8465 100644 --- a/shared/agents/reviewer.md +++ b/shared/agents/reviewer.md @@ -1,8 +1,8 @@ --- name: Reviewer description: Universal code review agent with parameterized focus. Dynamically loads pattern skill for assigned focus area. -model: inherit -skills: review-methodology +model: opus +skills: review-methodology, worktree-support --- # Reviewer Agent @@ -14,7 +14,10 @@ You are a universal code review agent. Your focus area is specified in the promp The orchestrator provides: - **Focus**: Which review type to perform - **Branch context**: What changes to review -- **Output path**: Where to save findings (e.g., `.docs/reviews/{branch}/{focus}.md`) +- **Output path**: Where to save findings (e.g., `.docs/reviews/{branch}/{timestamp}/{focus}.md`) +- **DIFF_COMMAND** (optional): Specific diff command to use (e.g., `git diff {sha}...HEAD` for incremental reviews). If not provided, default to `git diff {base_branch}...HEAD`. + +**Worktree Support**: If `WORKTREE_PATH` is provided, follow the `worktree-support` skill for path resolution. If omitted, use cwd. ## Focus Areas diff --git a/shared/agents/scrutinizer.md b/shared/agents/scrutinizer.md index 1e26154a..79925a58 100644 --- a/shared/agents/scrutinizer.md +++ b/shared/agents/scrutinizer.md @@ -1,8 +1,8 @@ --- name: Scrutinizer description: Self-review agent that evaluates and fixes implementation issues using 9-pillar framework. Runs in fresh context after Coder completes. -model: inherit -skills: self-review, core-patterns +model: opus +skills: self-review, core-patterns, worktree-support --- # Scrutinizer Agent @@ -15,6 +15,8 @@ You receive from orchestrator: - **TASK_DESCRIPTION**: What was implemented - **FILES_CHANGED**: List of modified files from Coder output +**Worktree Support**: If `WORKTREE_PATH` is provided, follow the `worktree-support` skill for path resolution. If omitted, use cwd. + ## Responsibilities 1. **Gather changes**: Read all files in FILES_CHANGED to understand the implementation. diff --git a/shared/agents/shepherd.md b/shared/agents/shepherd.md index 936daa04..6f17c379 100644 --- a/shared/agents/shepherd.md +++ b/shared/agents/shepherd.md @@ -1,8 +1,8 @@ --- name: Shepherd description: Validates implementation aligns with original request and plan. Catches missed requirements, scope creep, and intent drift. Reports misalignments for Coder to fix. -model: inherit -skills: core-patterns +model: opus +skills: core-patterns, worktree-support --- # Shepherd Agent @@ -17,6 +17,8 @@ You receive from orchestrator: - **FILES_CHANGED**: List of modified files from Coder output - **ACCEPTANCE_CRITERIA**: Extracted acceptance criteria (if any) +**Worktree Support**: If `WORKTREE_PATH` is provided, follow the `worktree-support` skill for path resolution. If omitted, use cwd. + ## Responsibilities 1. **Understand intent**: Read ORIGINAL_REQUEST and EXECUTION_PLAN to understand what was requested diff --git a/shared/agents/simplifier.md b/shared/agents/simplifier.md index b6a71e07..8fefdc3d 100644 --- a/shared/agents/simplifier.md +++ b/shared/agents/simplifier.md @@ -1,8 +1,8 @@ --- name: Simplifier description: Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. Focuses on recently modified code unless instructed otherwise. -skills: core-patterns -model: inherit +skills: core-patterns, worktree-support +model: sonnet --- # Simplifier Agent @@ -15,6 +15,8 @@ You receive from orchestrator: - **TASK_DESCRIPTION**: What was implemented - **FILES_CHANGED**: List of modified files from Coder output (optional) +**Worktree Support**: If `WORKTREE_PATH` is provided, follow the `worktree-support` skill for path resolution. If omitted, use cwd. + ## Responsibilities Analyze recently modified code and apply refinements that: diff --git a/shared/agents/skimmer.md b/shared/agents/skimmer.md index de6238a8..a80800d5 100644 --- a/shared/agents/skimmer.md +++ b/shared/agents/skimmer.md @@ -2,8 +2,8 @@ name: Skimmer description: Codebase orientation using rskim to identify relevant files, functions, and patterns for a feature or task tools: ["Bash", "Read"] -skills: knowledge-persistence -model: inherit +skills: knowledge-persistence, worktree-support +model: sonnet --- # Skimmer Agent @@ -15,6 +15,8 @@ You are a codebase orientation specialist. You use `npx rskim` exclusively for c You receive from orchestrator: - **TASK_DESCRIPTION**: What feature/task needs to be implemented or understood +**Worktree Support**: If `WORKTREE_PATH` is provided, follow the `worktree-support` skill for path resolution. If omitted, use cwd. + ## Workflow Execute these steps in order. Do NOT skip steps or reorder. diff --git a/shared/agents/synthesizer.md b/shared/agents/synthesizer.md index bffa931a..56f4b573 100644 --- a/shared/agents/synthesizer.md +++ b/shared/agents/synthesizer.md @@ -2,7 +2,7 @@ name: Synthesizer description: Combines outputs from multiple agents into actionable summaries (modes: exploration, planning, review) model: haiku -skills: review-methodology, docs-framework +skills: review-methodology, docs-framework, worktree-support --- # Synthesizer Agent @@ -16,6 +16,8 @@ The orchestrator provides: - **Agent outputs**: Results from parallel agents to synthesize - **Output path**: Where to save synthesis (if applicable) +**Worktree Support**: If `WORKTREE_PATH` is provided, follow the `worktree-support` skill for path resolution. If omitted, use cwd. + --- ## Mode: Exploration @@ -128,7 +130,7 @@ Analyze 3 axes to determine strategy: Synthesize outputs from multiple Reviewer agents. Apply strict merge rules. **Process:** -1. Read all review reports from `${REVIEW_BASE_DIR}/*.md` (exclude your own output `review-summary.*.md`) +1. Read all review reports from `${REVIEW_BASE_DIR}/*.md` (exclude `review-summary.md` and `resolution-summary.md`) 2. Extract confidence percentages from each finding 3. Apply confidence-aware aggregation: when multiple reviewers flag the same file:line, boost confidence by 10% per additional reviewer (cap at 100%) @@ -153,7 +155,7 @@ Synthesize outputs from multiple Reviewer agents. Apply strict merge rules. **Output:** **CRITICAL**: Write the summary to disk using the Write tool: 1. Create directory: `mkdir -p ${REVIEW_BASE_DIR}` -2. Write to `${REVIEW_BASE_DIR}/review-summary.${TIMESTAMP}.md` using Write tool +2. Write to `${REVIEW_BASE_DIR}/review-summary.md` using Write tool (the directory name provides the timestamp) 3. Confirm file written in final message Report format: diff --git a/shared/agents/validator.md b/shared/agents/validator.md index fc1be5b1..6072021f 100644 --- a/shared/agents/validator.md +++ b/shared/agents/validator.md @@ -2,7 +2,7 @@ name: Validator description: Dedicated agent for running validation commands (build, typecheck, lint, test). Reports pass/fail with structured failure details - never fixes. model: haiku -skills: test-patterns +skills: test-patterns, worktree-support --- # Validator Agent @@ -15,6 +15,8 @@ You receive from orchestrator: - **FILES_CHANGED**: List of modified files - **VALIDATION_SCOPE**: `full` | `changed-only` (hints for test filtering if supported) +**Worktree Support**: If `WORKTREE_PATH` is provided, follow the `worktree-support` skill for path resolution. If omitted, use cwd. + ## Responsibilities 1. **Discover validation commands**: Check package.json scripts, Makefile, Cargo.toml, or similar for available commands diff --git a/shared/skills/ambient-router/SKILL.md b/shared/skills/ambient-router/SKILL.md index 66c2c8b9..5851cc9e 100644 --- a/shared/skills/ambient-router/SKILL.md +++ b/shared/skills/ambient-router/SKILL.md @@ -32,6 +32,9 @@ Determine what the user is trying to do from their prompt. | **IMPLEMENT** | "add", "create", "implement", "build", "write", "make" | "add a login form", "create an API endpoint" | | **DEBUG** | "fix", "bug", "broken", "failing", "error", "why does" | "fix the auth error", "why is this test failing" | | **REVIEW** | "check", "look at", "review", "is this ok", "any issues" | "check this function", "any issues with this?" | +| **RESOLVE** | "resolve", "fix review issues", "address feedback", "fix findings" | "resolve the review issues", "fix the findings" | +| **PIPELINE** | "end to end", "implement and review", "build and review", "full pipeline" | "implement this end to end", "build and review this" | +| **MULTI_WORKTREE** | "all worktrees/branches", "each worktree/branch", "review everything", "resolve all" | "review all my worktrees", "resolve all branches", "review everything that needs review" | | **PLAN** | "how should", "design", "architecture", "approach", "strategy" | "how should I structure auth?", "what's the approach for caching?" | | **EXPLORE** | "what is", "where is", "find", "show me", "explain", "how does" | "where is the config?", "explain this function" | | **CHAT** | greetings, meta-questions, confirmations, short responses | "thanks", "yes", "what can you do?" | @@ -45,8 +48,8 @@ Determine how much enforcement the prompt warrants. | Depth | Criteria | Action | |-------|----------|--------| | **QUICK** | CHAT intent. EXPLORE intent. Git/devops operations (commit, push, merge, branch, pr, deploy, reinstall). Single-word continuations. Small edits, config changes, trivial single-file tweaks. | Respond normally. Zero overhead. Do not state classification. | -| **GUIDED** | IMPLEMENT with small scope (≤2 files, single module). DEBUG with clear error location (stack trace, specific file, known function). PLAN for focused design questions (specific area/pattern). REVIEW (always GUIDED). | Load skills via Skill tool. Main session implements directly. Spawn Simplifier after code changes. State classification. | -| **ORCHESTRATED** | IMPLEMENT with larger scope (>2 files, multi-module, complex). DEBUG with vague/cross-cutting bug (no clear location, multiple possible causes). PLAN for system-level architecture (caching layer, auth system, multi-module design). | Load skills via Skill tool, then orchestrate agents per Step 5. State classification. | +| **GUIDED** | IMPLEMENT with small scope (≤2 files, single module). DEBUG with clear error location (stack trace, specific file, known function). PLAN for focused design questions (specific area/pattern). REVIEW (small scope — see below). | Load skills via Skill tool. Main session implements directly. Spawn Simplifier after code changes. State classification. | +| **ORCHESTRATED** | IMPLEMENT with larger scope (>2 files, multi-module, complex). DEBUG with vague/cross-cutting bug (no clear location, multiple possible causes). PLAN for system-level architecture (caching layer, auth system, multi-module design). REVIEW (large scope — see below). RESOLVE (always). PIPELINE (always). | Load skills via Skill tool, then orchestrate agents per Step 5. State classification. | **Scope-based decision criteria:** @@ -55,7 +58,10 @@ Determine how much enforcement the prompt warrants. | **IMPLEMENT** | ≤2 files, single module, clear task | >2 files, multi-module, complex | | **DEBUG** | Clear error with known location (stack trace, specific file) | Vague/cross-cutting bug, multiple possible causes | | **PLAN** | Focused question about specific area/pattern | System-level architecture, multi-module design | -| **REVIEW** | Always GUIDED | — | +| **REVIEW** | Continuation: match prior IMPLEMENT depth. Standalone: "check this"/"review this file" → GUIDED | Continuation: match prior IMPLEMENT depth. Standalone: "full review"/"branch review"/"PR review" → ORCHESTRATED | +| **RESOLVE** | — | Always ORCHESTRATED | +| **PIPELINE** | — | Always ORCHESTRATED | +| **MULTI_WORKTREE** | Always ORCHESTRATED — triggers code-review/resolve command flow | — | **Classification conservatism:** When choosing between GUIDED and ORCHESTRATED, prefer GUIDED — escalate only when scope clearly exceeds main-session capacity. When choosing between QUICK and GUIDED, prefer GUIDED if the prompt involves code changes (implement, debug, fix, add, create code). Reserve QUICK for truly zero-overhead prompts: chat, exploration, git ops, config changes, trivial edits. @@ -79,8 +85,11 @@ Based on classified intent and depth, invoke each selected skill using the Skill | **IMPLEMENT** | implementation-orchestration, implementation-patterns | typescript (.ts), react (.tsx/.jsx), go (.go), java (.java), python (.py), rust (.rs), frontend-design (CSS/UI), input-validation (forms/API), security-patterns (auth/crypto) | | **DEBUG** | debug-orchestration, core-patterns | git-safety (if git operations involved) | | **PLAN** | plan-orchestration, implementation-patterns, core-patterns | — | +| **REVIEW** | review-orchestration | — (reviewers load their own pattern skills) | +| **RESOLVE** | resolve-orchestration, core-patterns | — | +| **PIPELINE** | pipeline-orchestration, implementation-patterns | — | -**Excluded from ambient** (review-command-only): review-methodology, complexity-patterns, consistency-patterns, database-patterns, dependencies-patterns, documentation-patterns, regression-patterns, architecture-patterns, accessibility, performance-patterns. +**Excluded from ambient loading** (loaded by agents internally): review-methodology, complexity-patterns, consistency-patterns, database-patterns, dependencies-patterns, documentation-patterns, regression-patterns, architecture-patterns, accessibility, performance-patterns. These skills are always installed (universal skill installation) but loaded by Reviewer agents at runtime, not by the router. See `references/skill-catalog.md` for the full skill-to-intent mapping with file pattern triggers. @@ -109,7 +118,7 @@ to all tools (Edit, Write, Bash, Agent, etc.) for implementation work. | **IMPLEMENT** | Implement directly with loaded skills. Follow TDD cycle. | Spawn Simplifier on changed files. | | **DEBUG** | Investigate directly — reproduce bug, diagnose from stack trace/error, fix. | Spawn Simplifier on changed files. | | **PLAN** | Explore relevant code and design directly. The area is focused enough for main session. | No Simplifier (no code changes). | -| **REVIEW** | Review directly with loaded skills. | No Simplifier. | +| **REVIEW** | Review directly with loaded skills (self-review in main session). | No Simplifier. | ## Step 5: Orchestrate Agents (ORCHESTRATED depth only) @@ -120,6 +129,11 @@ After loading skills via Step 3-4, execute the agent pipeline for the classified | **IMPLEMENT** | Follow implementation-orchestration skill pipeline: pre-flight → plan synthesis → Coder → quality gates | | **DEBUG** | Follow debug-orchestration skill pipeline: hypotheses → parallel Explores → convergence → report → offer fix | | **PLAN** | Follow plan-orchestration skill pipeline: Skimmer → Explores → Plan agent → gap validation | +| **REVIEW** | Follow review-orchestration skill pipeline: pre-flight → incremental detection → parallel reviewers → synthesis | +| **RESOLVE** | Follow resolve-orchestration skill pipeline: find review → parse issues → batch → parallel resolvers → simplify | +| **PIPELINE** | Follow pipeline-orchestration skill pipeline: implement → gate → review → gate → resolve | +| **MULTI_WORKTREE + REVIEW** | Follow `devflow:code-review` command flow (auto-discovers worktrees natively) | +| **MULTI_WORKTREE + RESOLVE** | Follow `devflow:resolve` command flow (auto-discovers worktrees natively) | | **EXPLORE** | No agents — respond in main session | | **CHAT** | No agents — respond in main session | @@ -143,5 +157,12 @@ After loading skills via Step 3-4, execute the agent pipeline for the classified | User explicitly requests no enforcement | Respect immediately — classify as QUICK | | Prompt references specific DevFlow command | Skip ambient — the command has its own orchestration | | Scope ambiguous between GUIDED and ORCHESTRATED | Default to GUIDED; escalate if complexity emerges during work | -| REVIEW intent | Always GUIDED — single Reviewer focus, no orchestration pipeline | +| REVIEW after IMPLEMENT/GUIDED | GUIDED (continuation — match prior depth) | +| REVIEW after IMPLEMENT/ORCHESTRATED | ORCHESTRATED (continuation — match prior depth) | +| REVIEW standalone, large scope ("full review", "branch", "PR") | ORCHESTRATED | +| REVIEW standalone, small scope ("check this", specific file) | GUIDED | +| REVIEW standalone, ambiguous | GUIDED (conservative) | +| RESOLVE intent | Always ORCHESTRATED | +| PIPELINE intent | Always ORCHESTRATED | +| MULTI_WORKTREE intent | Always ORCHESTRATED — follow code-review/resolve command flow which auto-discovers worktrees | | Multiple triggers per session | Each runs independently; context compaction handles accumulation | diff --git a/shared/skills/ambient-router/references/skill-catalog.md b/shared/skills/ambient-router/references/skill-catalog.md index f822c69c..39abb7b7 100644 --- a/shared/skills/ambient-router/references/skill-catalog.md +++ b/shared/skills/ambient-router/references/skill-catalog.md @@ -40,6 +40,27 @@ These skills may be loaded during GUIDED and ORCHESTRATED-depth ambient routing. | self-review | Always for REVIEW | GUIDED | Any code file | | core-patterns | Always for REVIEW | GUIDED | Any code file | | test-patterns | Test files in scope | GUIDED | `*.test.*`, `*.spec.*` | +| review-orchestration | ORCHESTRATED only | ORCHESTRATED | Any — orchestrates multi-agent review pipeline | + +**REVIEW depth is continuation-aware**: If the prior classification in the same conversation was IMPLEMENT/GUIDED → REVIEW stays GUIDED. If prior was IMPLEMENT/ORCHESTRATED → REVIEW becomes ORCHESTRATED. Standalone REVIEW uses signal words: "full review"/"branch review"/"PR review" → ORCHESTRATED, "check this"/"review this file" → GUIDED. Ambiguous → GUIDED. + +### RESOLVE Intent + +| Skill | When to Load | Depth | File Patterns | +|-------|-------------|-------|---------------| +| resolve-orchestration | Always for RESOLVE | ORCHESTRATED | Any — orchestrates issue resolution pipeline | +| core-patterns | Always for RESOLVE | ORCHESTRATED | Any code file | + +RESOLVE is always ORCHESTRATED — it requires multi-agent resolution with Resolver agents and Simplifier. + +### PIPELINE Intent + +| Skill | When to Load | Depth | File Patterns | +|-------|-------------|-------|---------------| +| pipeline-orchestration | Always for PIPELINE | ORCHESTRATED | Any — meta-orchestrator for implement → review → resolve | +| implementation-patterns | Always for PIPELINE | ORCHESTRATED | Any code file | + +PIPELINE is always ORCHESTRATED — it chains multiple orchestration stages with user gates. ### PLAN Intent @@ -49,9 +70,9 @@ These skills may be loaded during GUIDED and ORCHESTRATED-depth ambient routing. | implementation-patterns | Always for PLAN | GUIDED + ORCHESTRATED | Any planning context | | core-patterns | Always for PLAN | GUIDED + ORCHESTRATED | System design discussions | -## Skills Excluded from Ambient +## Skills Excluded from Ambient Router Loading -These skills are loaded only by explicit DevFlow commands (primarily `/code-review`): +These skills are always installed (universal skill installation) but loaded by agents internally at runtime, not by the ambient router. Reviewer agents load their pattern skill based on their focus area: - review-methodology — Full review process (6-step, 3-category classification) - complexity-patterns — Cyclomatic complexity, deep nesting analysis @@ -64,10 +85,23 @@ These skills are loaded only by explicit DevFlow commands (primarily `/code-revi - accessibility — WCAG compliance, ARIA roles, keyboard navigation - performance-patterns — N+1 queries, memory leaks, caching opportunities +## Multi-Worktree Detection + +When the user's prompt contains multi-worktree signals ("all worktrees", "all branches", "each worktree", "review everything", "resolve all"), classify as MULTI_WORKTREE intent combined with REVIEW or RESOLVE. This always routes to ORCHESTRATED depth. + +| Signal | Combined Intent | Action | +|--------|----------------|--------| +| "review all worktrees/branches" | MULTI_WORKTREE + REVIEW | Follow `devflow:code-review` command flow (auto-discovers worktrees) | +| "resolve all worktrees/branches" | MULTI_WORKTREE + RESOLVE | Follow `devflow:resolve` command flow (auto-discovers worktrees) | +| "review everything that needs review" | MULTI_WORKTREE + REVIEW | Follow `devflow:code-review` command flow | +| "run code review on each branch" | MULTI_WORKTREE + REVIEW | Follow `devflow:code-review` command flow | + +No additional skills needed — the code-review and resolve commands handle all orchestration internally, including worktree discovery, incremental detection, and parallel agent spawning. + ## Selection Limits - **Maximum 3 knowledge skills** per ambient response (primary + up to 2 secondary) -- **Orchestration skills** (implementation-orchestration, debug-orchestration, plan-orchestration) are loaded only at ORCHESTRATED depth — they don't count toward the knowledge skill limit +- **Orchestration skills** (implementation-orchestration, debug-orchestration, plan-orchestration, review-orchestration, resolve-orchestration, pipeline-orchestration) are loaded only at ORCHESTRATED depth — they don't count toward the knowledge skill limit - **Primary skills** are always loaded for the classified intent at both GUIDED and ORCHESTRATED depth - **Secondary skills** are loaded only when file patterns match conversation context - **GUIDED depth** loads knowledge skills only (no orchestration skills) — main session works directly diff --git a/shared/skills/debug-orchestration/SKILL.md b/shared/skills/debug-orchestration/SKILL.md index 6c52a986..a47e8102 100644 --- a/shared/skills/debug-orchestration/SKILL.md +++ b/shared/skills/debug-orchestration/SKILL.md @@ -21,6 +21,10 @@ This is a lightweight variant of `/debug` for ambient ORCHESTRATED mode. Exclude --- +## Worktree Support + +If the orchestrator receives a `WORKTREE_PATH` context (e.g., from multi-worktree workflows), pass it through to all spawned agents. Each agent's "Worktree Support" section handles path resolution. + ## Phase 1: Hypothesize Analyze the bug description, error messages, and conversation context. Generate 3-5 hypotheses that are: diff --git a/shared/skills/docs-framework/SKILL.md b/shared/skills/docs-framework/SKILL.md index c8af66d9..94ef94f4 100644 --- a/shared/skills/docs-framework/SKILL.md +++ b/shared/skills/docs-framework/SKILL.md @@ -26,8 +26,14 @@ All generated documentation lives under `.docs/` in the project root: ``` .docs/ ├── reviews/{branch-slug}/ # Code review reports per branch -│ ├── {type}-report.{timestamp}.md -│ └── review-summary.{timestamp}.md +│ ├── .last-review-head # HEAD SHA of last completed review (for incremental) +│ ├── {timestamp}/ # Timestamped review directory (YYYY-MM-DD_HHMM) +│ │ ├── {focus}.md # Reviewer report (e.g., security.md, architecture.md) +│ │ ├── review-summary.md # Synthesizer output +│ │ └── resolution-summary.md # Written by /resolve (if run) +│ └── {timestamp}/ # Second review (incremental) +│ ├── {focus}.md +│ └── review-summary.md ├── status/ # Development logs │ ├── {timestamp}.md │ ├── compact/{timestamp}.md @@ -71,7 +77,10 @@ TOPIC_SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | sed 's/[^ | Type | Pattern | Example | |------|---------|---------| | Special indexes | `UPPERCASE.md` | `WORKING-MEMORY.md`, `INDEX.md` | -| Reports | `{type}-report.{timestamp}.md` | `security-report.2025-12-26_1430.md` | +| Review reports | `{focus}.md` in timestamped dir | `2025-12-26_1430/security.md` | +| Review summary | `review-summary.md` in timestamped dir | `2025-12-26_1430/review-summary.md` | +| Resolution summary | `resolution-summary.md` in timestamped dir | `2025-12-26_1430/resolution-summary.md` | +| Review head marker | `.last-review-head` | Plain text file with SHA | | Status logs | `{timestamp}.md` | `2025-12-26_1430.md` | --- @@ -97,7 +106,10 @@ source .devflow/scripts/docs-helpers.sh 2>/dev/null || { | Agent | Output Location | Behavior | |-------|-----------------|----------| -| Reviewer | `.docs/reviews/{branch-slug}/{type}-report.{timestamp}.md` | Creates new | +| Reviewer | `.docs/reviews/{branch-slug}/{timestamp}/{focus}.md` | Creates new in timestamped dir | +| Synthesizer (review) | `.docs/reviews/{branch-slug}/{timestamp}/review-summary.md` | Creates new in timestamped dir | +| Resolver | `.docs/reviews/{branch-slug}/{timestamp}/resolution-summary.md` | Creates new in timestamped dir | +| Code-review cmd | `.docs/reviews/{branch-slug}/.last-review-head` | Overwrites with HEAD SHA | | Working Memory | `.memory/WORKING-MEMORY.md` | Overwrites (auto-maintained by Stop hook) | | Knowledge (decisions) | `.memory/knowledge/decisions.md` | Append-only (ADR-NNN sequential IDs) | | Knowledge (pitfalls) | `.memory/knowledge/pitfalls.md` | Append-only (PF-NNN sequential IDs) | diff --git a/shared/skills/docs-framework/references/patterns.md b/shared/skills/docs-framework/references/patterns.md index 779b03ac..8dad676b 100644 --- a/shared/skills/docs-framework/references/patterns.md +++ b/shared/skills/docs-framework/references/patterns.md @@ -11,8 +11,13 @@ Correct patterns for DevFlow documentation artifacts with templates and helper f ``` .docs/ ├── reviews/{branch-slug}/ # Code review reports per branch -│ ├── {type}-report.{timestamp}.md -│ └── review-summary.{timestamp}.md +│ ├── .last-review-head # HEAD SHA of last completed review +│ ├── {timestamp}/ # Timestamped review directory +│ │ ├── {focus}.md # Reviewer reports (security.md, architecture.md, etc.) +│ │ ├── review-summary.md # Synthesizer output +│ │ └── resolution-summary.md # Written by /resolve (if run) +│ └── {timestamp}/ # Incremental review +│ └── ... ├── design/ # Implementation plans │ └── {topic-slug}.{timestamp}.md ├── status/ # Development logs @@ -32,18 +37,45 @@ Correct patterns for DevFlow documentation artifacts with templates and helper f └── CATCH_UP.md ``` -**With Reviews:** +**With Reviews (single review):** ``` .docs/ ├── reviews/feat-auth/ -│ ├── security-report.2025-01-05_1430.md -│ └── review-summary.2025-01-05_1430.md +│ ├── .last-review-head +│ └── 2025-01-05_1430/ +│ ├── security.md +│ ├── architecture.md +│ ├── performance.md +│ ├── complexity.md +│ ├── consistency.md +│ ├── regression.md +│ ├── tests.md +│ └── review-summary.md ├── status/ │ ├── 2025-01-05_1430.md │ └── INDEX.md └── CATCH_UP.md ``` +**With Multiple Reviews (incremental):** +``` +.docs/ +├── reviews/feat-auth/ +│ ├── .last-review-head +│ ├── 2025-01-05_1430/ +│ │ ├── security.md +│ │ ├── ... +│ │ ├── review-summary.md +│ │ └── resolution-summary.md +│ └── 2025-01-06_0900/ +│ ├── security.md +│ ├── ... +│ └── review-summary.md +├── status/ +│ └── INDEX.md +└── CATCH_UP.md +``` + --- ## Naming Conventions @@ -103,13 +135,15 @@ Always UPPERCASE, overwritten or appended: - `INDEX.md` - Chronological log index - `KNOWLEDGE_BASE.md` - Searchable debug solutions -### Artifact Files (lowercase + timestamp) +### Artifact Files (lowercase) -Always lowercase with timestamp: +Always lowercase: - `2025-01-05_1430.md` - Status log -- `security-report.2025-01-05_1430.md` - Review report -- `review-summary.2025-01-05_1430.md` - Combined summary +- `security.md` - Review report (in timestamped directory) +- `review-summary.md` - Combined summary (in timestamped directory) +- `resolution-summary.md` - Resolution summary (in timestamped directory) +- `.last-review-head` - SHA marker for incremental reviews - `jwt-authentication.2025-01-05_1430.md` - Design doc --- @@ -169,14 +203,15 @@ get_status_path() { get_doc_path "status" "${timestamp}.md" } -# Create review report path +# Create timestamped review directory and return path for a focus report get_review_path() { - local type="$1" + local focus="$1" local branch_slug local timestamp branch_slug=$(get_branch_slug) timestamp=$(get_timestamp) - get_doc_path "reviews/$branch_slug" "${type}-report.${timestamp}.md" + ensure_docs_dir "reviews/$branch_slug/$timestamp" + echo ".docs/reviews/$branch_slug/$timestamp/${focus}.md" } ``` diff --git a/shared/skills/git-safety/SKILL.md b/shared/skills/git-safety/SKILL.md index 0beade62..6fa03037 100644 --- a/shared/skills/git-safety/SKILL.md +++ b/shared/skills/git-safety/SKILL.md @@ -77,7 +77,7 @@ Only use `--amend` when ALL conditions are met: ## Branch Safety -Never force push to: `main`, `master`, `develop` +Never force push to: `main`, `master`, `develop`, `release/*`, `staging`, `production` **Branch naming**: `feat/`, `fix/`, `release/`, `hotfix/` prefixes with short descriptions. diff --git a/shared/skills/git-safety/references/patterns.md b/shared/skills/git-safety/references/patterns.md index 54027af1..20673a0c 100644 --- a/shared/skills/git-safety/references/patterns.md +++ b/shared/skills/git-safety/references/patterns.md @@ -116,7 +116,7 @@ git push -u origin $(git branch --show-current) ## Protected Branch Check ```bash -PROTECTED_BRANCHES="main master develop" +PROTECTED_BRANCHES="main master develop staging production" check_protected_branch() { local branch="$1" @@ -126,6 +126,10 @@ check_protected_branch() { return 1 fi done + # Check release/* glob + case "$branch" in + release/*) echo "ERROR: Cannot force push to $branch"; return 1 ;; + esac return 0 } ``` diff --git a/shared/skills/implementation-orchestration/SKILL.md b/shared/skills/implementation-orchestration/SKILL.md index b46ba3e9..a474fad5 100644 --- a/shared/skills/implementation-orchestration/SKILL.md +++ b/shared/skills/implementation-orchestration/SKILL.md @@ -38,6 +38,10 @@ Synthesize conversation context into a structured EXECUTION_PLAN for Coder: Format as structured markdown with: Goal, Steps, Files, Constraints, Decisions. +## Worktree Support + +If the orchestrator receives a `WORKTREE_PATH` context (e.g., from multi-worktree workflows), pass it through to all spawned agents. Each agent's "Worktree Support" section handles path resolution. + ## Phase 3: Coder Execution Record git SHA before first Coder: `git rev-parse HEAD` @@ -55,6 +59,8 @@ Spawn `Task(subagent_type="Coder")` with input variables: If Coder returns **BLOCKED**, halt the pipeline and report to user. +**Handoff artifact** (when HANDOFF_REQUIRED=true): After Coder completes, write the phase summary to `.docs/handoff.md` using the Write tool. The next Coder reads this on startup (see Coder agent Responsibility 1). This survives context compaction — unlike PRIOR_PHASE_SUMMARY which is context-mediated. + ## Phase 4: FILES_CHANGED Detection After Coder completes, detect changed files: @@ -79,6 +85,8 @@ If any gate exhausts retries, halt pipeline and report what passed and what fail ## Phase 6: Completion +Cleanup: delete `.docs/handoff.md` if it exists (no longer needed after pipeline completes). + Report results: - Commits created (from Coder) - Files changed diff --git a/shared/skills/pipeline-orchestration/SKILL.md b/shared/skills/pipeline-orchestration/SKILL.md new file mode 100644 index 00000000..1e22d8ad --- /dev/null +++ b/shared/skills/pipeline-orchestration/SKILL.md @@ -0,0 +1,77 @@ +--- +name: pipeline-orchestration +description: End-to-end meta-orchestrator chaining implement → review → resolve with user gates between stages +user-invocable: false +allowed-tools: Read, Grep, Glob, Bash, Task, AskUserQuestion +--- + +# Pipeline Orchestration + +Meta-orchestrator chaining implement → review → resolve with user gates between stages. For ambient PIPELINE intent ("implement this end to end", "build and review"). + +## Iron Law + +> **USER GATES BETWEEN STAGES** +> +> Never auto-chain from review to resolve without user confirmation. +> Critical findings require human judgment. Each gate is mandatory. + +--- + +## Cost Communication + +Classification statement must warn about scope: +`Ambient: PIPELINE/ORCHESTRATED. This runs implement → review → resolve (15+ agents across stages).` + +## Phase 1: Implement + +Follow implementation-orchestration pipeline (Phases 1-6). + +If implementation returns **BLOCKED**: halt entire pipeline, report blocker. + +Cleanup: delete `.docs/handoff.md` if it exists (no longer needed before review). + +## Phase 2: Gate — Review Decision + +Use AskUserQuestion: +> "Implementation complete ({n} files changed, all quality gates passed). Proceed with multi-agent review? (This spawns 7+ reviewer agents)" + +- **User says NO** → stop pipeline, report implementation results only +- **User says YES** → continue to Phase 3 + +## Phase 3: Review + +Follow review-orchestration pipeline (Phases 1-6). + +Report review results (merge recommendation, issue counts). + +## Phase 4: Gate — Resolve Decision + +If **blocking issues found**: +> Use AskUserQuestion: "Found {n} blocking issues. Auto-resolve? (Spawns resolver agents per batch)" + +If **no blocking issues**: +> "Review clean — no resolution needed." → stop pipeline with success summary + +- **User says NO** → stop pipeline, report implementation + review results +- **User says YES** → continue to Phase 5 + +## Phase 5: Resolve + +Follow resolve-orchestration pipeline (Phases 1-6). + +## Phase 6: Summary + +End-to-end report: +- **Implementation**: files changed, commits, quality gate results +- **Review**: issue counts by severity, merge recommendation +- **Resolution**: issues fixed vs deferred vs false positives +- **Final state**: branch status, remaining work (if any) + +## Error Handling + +- **Implementation BLOCKED**: Halt at Phase 1, report blocker +- **User declines gate**: Stop cleanly, report completed stages +- **Review finds no changes**: Skip review, report implementation only +- **All issues resolved**: Report full success +- **Partial resolution**: Report what was fixed and what remains diff --git a/shared/skills/plan-orchestration/SKILL.md b/shared/skills/plan-orchestration/SKILL.md index c9e9184d..6625851e 100644 --- a/shared/skills/plan-orchestration/SKILL.md +++ b/shared/skills/plan-orchestration/SKILL.md @@ -21,6 +21,10 @@ This is a lightweight variant of the Plan phase in `/implement` for ambient ORCH --- +## Worktree Support + +If the orchestrator receives a `WORKTREE_PATH` context (e.g., from multi-worktree workflows), pass it through to all spawned agents. Each agent's "Worktree Support" section handles path resolution. + ## Phase 1: Orient Spawn `Task(subagent_type="Skimmer")` to get codebase overview relevant to the planning question: diff --git a/shared/skills/resolve-orchestration/SKILL.md b/shared/skills/resolve-orchestration/SKILL.md new file mode 100644 index 00000000..d24aea99 --- /dev/null +++ b/shared/skills/resolve-orchestration/SKILL.md @@ -0,0 +1,89 @@ +--- +name: resolve-orchestration +description: Agent orchestration for RESOLVE intent in ambient mode — issue resolution from review reports +user-invocable: false +allowed-tools: Read, Grep, Glob, Bash, Task, AskUserQuestion +--- + +# Resolve Orchestration + +Agent pipeline for RESOLVE intent in ambient mode. Parses review reports, validates issues, batches resolutions, and runs Simplifier cleanup. + +This is a lightweight variant of `/resolve` for ambient mode. Excluded: pitfall recording, tech debt management, Agent Teams debate, multi-worktree flow, CLI flags. + +## Iron Law + +> **VALIDATE FIRST, FIX EVERYTHING POSSIBLE** +> +> Every issue must be validated in current file context before any fix. +> Read first, decide second, fix third. Never apply a suggested fix blindly. +> Tech debt deferral is the LAST RESORT — only for complete architectural overhauls. + +--- + +## Phase 1: Target Review Directory + +Find the latest timestamped directory under `.docs/reviews/` that: +1. Contains a `review-summary.md` (has been reviewed) +2. Does NOT contain a `resolution-summary.md` (hasn't been resolved yet) + +If no unresolved review found: halt with "No unresolved review found. Run a review first." + +Extract branch slug from the directory path. + +## Phase 2: Parse Issues + +Read all `{focus}.md` files in the timestamped directory (exclude `review-summary.md` and `resolution-summary.md`). + +Extract issues at **Blocking** and **Should-Fix** severity only. Skip Pre-existing and Suggestions. + +For each issue, extract: id (generated), file, line, severity, type (from focus), description, suggested_fix. + +If no actionable issues found: "Review is clean — no blocking or should-fix issues to resolve." → stop. + +## Phase 3: Analyze & Batch + +Group issues by file/function for efficient resolution: +- Issues in the same file → same batch +- Issues with cross-file dependencies → same batch +- Max 5 issues per batch + +Determine execution: batches with no shared files can run in parallel. + +## Phase 4: Resolve (Parallel) + +Spawn `Task(subagent_type="Resolver")` agents — one per batch, parallel where possible. + +Each receives: +- **ISSUES**: Array of issues in the batch +- **BRANCH**: Branch slug +- **BATCH_ID**: Identifier for this batch + +Resolvers follow a 3-tier risk approach: +- **Standard fixes**: Applied directly +- **Careful fixes** (public API, shared state, >3 files): Test-first — write tests covering current behavior, apply fix, verify tests pass +- **Architectural overhaul**: Defer to tech debt (LAST RESORT — only when complete system redesign required) + +## Phase 5: Collect & Simplify + +Aggregate results from all Resolver agents: +- Count: fixed, false positives, deferred + +Spawn `Task(subagent_type="Simplifier")` on all files modified by Resolvers. + +## Phase 6: Report + +Write `resolution-summary.md` to the same timestamped review directory. + +Report to user: +- Issues resolved vs deferred vs false positives +- Files modified +- Commits created +- Remaining issues (if any deferred) + +## Error Handling + +- **No review directory**: Halt, suggest running review first +- **All issues false positive**: Report findings, write resolution-summary noting no changes needed +- **Resolver BLOCKED**: Report which batch blocked, continue with remaining +- **Simplifier fails**: Resolution still valid — report that simplification was skipped diff --git a/shared/skills/review-orchestration/SKILL.md b/shared/skills/review-orchestration/SKILL.md new file mode 100644 index 00000000..ba37f699 --- /dev/null +++ b/shared/skills/review-orchestration/SKILL.md @@ -0,0 +1,99 @@ +--- +name: review-orchestration +description: Agent orchestration for REVIEW intent in ambient ORCHESTRATED mode — multi-agent code review with parallel reviewers +user-invocable: false +allowed-tools: Read, Grep, Glob, Bash, Task, AskUserQuestion +--- + +# Review Orchestration + +Agent pipeline for REVIEW intent in ambient ORCHESTRATED mode. Full multi-agent review with parallel specialized reviewers, incremental detection, and disk-persisted reports. + +This is a lightweight variant of `/code-review` for ambient ORCHESTRATED mode. Excluded: pitfall recording, tech debt management, Agent Teams debate, multi-worktree flow (routes to full command via MULTI_WORKTREE intent), CLI flag parsing. + +## Iron Law + +> **EVERY REVIEWER WRITES TO DISK** +> +> A review that exists only in agent output disappears on compaction. +> No disk artifact, no review. The Synthesizer reads from disk, not memory. + +--- + +## Phase 1: Pre-flight + +Spawn `Task(subagent_type="Git")` with action `ensure-pr-ready`: +- Extract: branch, base_branch, branch_slug, pr_number +- If BLOCKED (detached HEAD, no commits ahead of base): halt with message + +Determine base branch: use PR target if PR exists, otherwise `main`/`master`. + +## Phase 2: Incremental Detection + +Check `.docs/reviews/{branch_slug}/.last-review-head`: +- If file exists and SHA matches HEAD: "No new commits since last review. Nothing to do." → stop +- If file exists and SHA differs: set `DIFF_RANGE={sha}...HEAD` (incremental) +- If file doesn't exist: set `DIFF_RANGE={base_branch}...HEAD` (full review) + +Generate timestamp: `YYYY-MM-DD_HHMM` +Create directory: `mkdir -p .docs/reviews/{branch_slug}/{timestamp}` + +## Phase 3: File Analysis + +Run `git diff --name-only {DIFF_RANGE}` to get changed files. + +Detect conditional reviewers from file types: + +| File Pattern | Reviewer Focus | +|-------------|---------------| +| `*.ts`, `*.tsx` | typescript | +| `*.tsx`, `*.jsx` | react | +| `*.go` | go | +| `*.java` | java | +| `*.py` | python | +| `*.rs` | rust | +| `*.css`, `*.scss` | frontend-design | +| `*.tsx`, `*.jsx` (with UI) | accessibility | +| migration/schema files | database | +| `package.json`, lock files | dependencies | +| `*.md`, doc files | documentation | + +## Phase 4: Reviews (Parallel) + +Spawn all reviewers in a single message (parallel execution): + +**7 core reviewers** (always): +- security, architecture, performance, complexity, consistency, tests, regression + +**Conditional reviewers** (from Phase 3 file analysis): +- typescript, react, database, dependencies, documentation, go, java, python, rust, accessibility, frontend-design + +Each reviewer receives: +- **Focus**: Their review type +- **Branch context**: branch → base_branch +- **Output path**: `.docs/reviews/{branch_slug}/{timestamp}/{focus}.md` +- **DIFF_COMMAND**: `git diff {DIFF_RANGE}` (incremental or full) + +## Phase 5: Synthesis (Parallel) + +After all reviewers complete, spawn in parallel: + +1. `Task(subagent_type="Git")` with action `comment-pr` — post review summary as PR comment (deduplicate: check existing comments first) +2. `Task(subagent_type="Synthesizer")` in review mode — reads all `{focus}.md` files from disk, writes `review-summary.md` + +## Phase 6: Finalize + +Write HEAD SHA to `.docs/reviews/{branch_slug}/.last-review-head` for next incremental review. + +Report to user: +- Merge recommendation (from Synthesizer) +- Issue counts by severity +- Artifacts: list of report files written +- Next steps: suggest `/resolve` or `resolve the review issues` if blocking issues found + +## Error Handling + +- **Git pre-flight BLOCKED**: Halt immediately, report to user +- **No changed files**: "No changes to review." → stop +- **Reviewer fails**: Report which reviewer failed, continue with remaining +- **Synthesizer fails**: Reports are still on disk — user can read them directly diff --git a/shared/skills/worktree-support/SKILL.md b/shared/skills/worktree-support/SKILL.md new file mode 100644 index 00000000..9022d44e --- /dev/null +++ b/shared/skills/worktree-support/SKILL.md @@ -0,0 +1,91 @@ +--- +name: worktree-support +description: Canonical worktree path resolution and discovery algorithm for agents and commands +user-invocable: false +allowed-tools: Bash, Read +--- + +# Worktree Support + +Canonical patterns for worktree-aware agents and multi-worktree discovery in commands. + +## Iron Law + +> **WORKTREE_PATH IS A PREFIX, NOT A FLAG** +> +> When WORKTREE_PATH is provided, it changes how you resolve ALL paths — git commands, +> file reads, .docs/ paths. It's not a toggle; it's a coordinate system shift. + +--- + +## Agent Path Resolution + +When `WORKTREE_PATH` is provided to an agent: + +| Operation | Without WORKTREE_PATH | With WORKTREE_PATH | +|-----------|----------------------|-------------------| +| Git commands | `git ...` | `git -C {WORKTREE_PATH} ...` | +| .docs/ paths | `.docs/...` | `{WORKTREE_PATH}/.docs/...` | +| Source files | `{file}` | `{WORKTREE_PATH}/{file}` | +| Default | Use cwd | Use WORKTREE_PATH as root | + +If `WORKTREE_PATH` is omitted, behavior is unchanged (use cwd). This is the common case. + +--- + +## Worktree Discovery Algorithm (Commands) + +For commands that auto-discover worktrees (`/code-review`, `/resolve`): + +### Step 1: List Worktrees + +Run `git worktree list --porcelain` + +### Step 2: Parse Each Entry + +Extract: `worktree {path}`, `HEAD {sha}`, `branch refs/heads/{name}` + +### Step 3: Filter + +Exclude: +- **Bare worktrees** (no branch) +- **Detached HEAD** (no named branch) +- **Protected branches**: `main`, `master`, `develop`, `release/*`, `staging`, `production` +- **Mid-rebase or mid-merge**: check `git -C {path} status` for "rebase in progress" or "merging" + +### Step 4: Check for Work + +Each worktree must have commits ahead of base branch. Skip those that are clean/up-to-date. + +### Step 5: Deduplicate + +If two worktrees are on the same branch, use only the first worktree's path. + +### Step 6: Sort + +Sort by last commit date (most recent first). + +### Step 7: Return + +Return list of reviewable worktrees with path, branch, HEAD SHA. + +--- + +## Protected Branches (Canonical List) + +`main`, `master`, `develop`, `release/*`, `staging`, `production` + +All components (agents, commands, skills) must use this exact list when checking for protected branches. + +--- + +## Multi-Worktree Mode + +| Condition | Behavior | +|-----------|----------| +| 0 reviewable worktrees | Error: no reviewable branches found | +| 1 worktree (common case) | Single-worktree flow, zero behavior change | +| 2+ worktrees | Report count, process all in parallel where possible | +| 5+ worktrees | Report count and proceed — user manages their worktree count | +| `--path` flag provided | Use only that worktree, skip discovery | +| Same branch in 2 worktrees | Deduplicate — review once using first worktree's path | diff --git a/src/cli/commands/init.ts b/src/cli/commands/init.ts index 4d8e1879..5f00ce42 100644 --- a/src/cli/commands/init.ts +++ b/src/cli/commands/init.ts @@ -20,7 +20,7 @@ import { migrateMemoryFiles, type SecurityMode, } from '../utils/post-install.js'; -import { DEVFLOW_PLUGINS, LEGACY_SKILL_NAMES, LEGACY_COMMAND_NAMES, buildAssetMaps, type PluginDefinition } from '../plugins.js'; +import { DEVFLOW_PLUGINS, LEGACY_SKILL_NAMES, LEGACY_COMMAND_NAMES, buildAssetMaps, buildFullSkillsMap, type PluginDefinition } from '../plugins.js'; import { detectPlatform, detectShell, getProfilePath, getSafeDeleteInfo, hasSafeDelete } from '../utils/safe-delete.js'; import { generateSafeDeleteBlock, installToProfile, removeFromProfile, getInstalledVersion, SAFE_DELETE_BLOCK_VERSION } from '../utils/safe-delete-install.js'; import { addAmbientHook } from './ambient.js'; @@ -749,7 +749,11 @@ export const initCommand = new Command('init') pluginsToInstall.push(ambientPlugin); } - const { skillsMap, agentsMap } = buildAssetMaps(pluginsToInstall); + // Skills: install ALL from ALL plugins (skills are tiny markdown files; + // orchestration skills need skills from other plugins to function) + const skillsMap = buildFullSkillsMap(); + // Agents: install only from selected plugins + const { agentsMap } = buildAssetMaps(pluginsToInstall); // Install: try native CLI first, fall back to file copy const cliAvailable = isClaudeCliAvailable(); diff --git a/src/cli/plugins.ts b/src/cli/plugins.ts index 9e15c233..c93ebf37 100644 --- a/src/cli/plugins.ts +++ b/src/cli/plugins.ts @@ -38,42 +38,64 @@ export const DEVFLOW_PLUGINS: PluginDefinition[] = [ description: 'Complete task implementation workflow with exploration, planning, and coding', commands: ['/implement'], agents: ['git', 'skimmer', 'synthesizer', 'coder', 'simplifier', 'scrutinizer', 'shepherd', 'validator'], - skills: ['agent-teams', 'implementation-patterns', 'knowledge-persistence', 'self-review'], + skills: ['agent-teams', 'implementation-patterns', 'knowledge-persistence', 'self-review', 'worktree-support'], }, { name: 'devflow-code-review', description: 'Comprehensive code review with parallel specialized agents', commands: ['/code-review'], agents: ['git', 'reviewer', 'synthesizer'], - skills: ['agent-teams', 'architecture-patterns', 'complexity-patterns', 'consistency-patterns', 'database-patterns', 'dependencies-patterns', 'documentation-patterns', 'knowledge-persistence', 'performance-patterns', 'regression-patterns', 'review-methodology', 'security-patterns', 'test-patterns'], + skills: ['agent-teams', 'architecture-patterns', 'complexity-patterns', 'consistency-patterns', 'database-patterns', 'dependencies-patterns', 'documentation-patterns', 'knowledge-persistence', 'performance-patterns', 'regression-patterns', 'review-methodology', 'security-patterns', 'test-patterns', 'worktree-support'], }, { name: 'devflow-resolve', description: 'Process and fix code review issues with risk assessment', commands: ['/resolve'], agents: ['git', 'resolver', 'simplifier'], - skills: ['agent-teams', 'implementation-patterns', 'knowledge-persistence', 'security-patterns'], + skills: ['agent-teams', 'implementation-patterns', 'knowledge-persistence', 'security-patterns', 'worktree-support'], }, { name: 'devflow-debug', description: 'Debugging workflows with competing hypothesis investigation using agent teams', commands: ['/debug'], agents: ['git', 'synthesizer'], - skills: ['agent-teams', 'git-safety', 'knowledge-persistence'], + skills: ['agent-teams', 'git-safety', 'knowledge-persistence', 'worktree-support'], }, { name: 'devflow-self-review', description: 'Self-review workflow: Simplifier + Scrutinizer for code quality', commands: ['/self-review'], agents: ['simplifier', 'scrutinizer', 'validator'], - skills: ['self-review', 'core-patterns'], + skills: ['self-review', 'core-patterns', 'worktree-support'], }, { name: 'devflow-ambient', description: 'Ambient mode — intent classification with proportional agent orchestration', commands: ['/ambient'], - agents: ['coder', 'validator', 'simplifier', 'scrutinizer', 'shepherd', 'skimmer', 'reviewer'], - skills: ['ambient-router', 'implementation-orchestration', 'debug-orchestration', 'plan-orchestration'], + agents: ['coder', 'validator', 'simplifier', 'scrutinizer', 'shepherd', 'skimmer', 'reviewer', 'git', 'synthesizer', 'resolver'], + skills: [ + 'ambient-router', + 'implementation-orchestration', + 'debug-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', + ], }, { name: 'devflow-audit-claude', @@ -252,3 +274,21 @@ export function buildAssetMaps(plugins: PluginDefinition[]): { } return { skillsMap, agentsMap }; } + +/** + * Build a skills map from ALL plugins (regardless of selection). + * Skills are tiny markdown files — always install all of them so orchestration + * skills (review-orchestration, resolve-orchestration) can spawn agents that + * depend on skills from other plugins. + */ +export function buildFullSkillsMap(): Map { + const skillsMap = new Map(); + for (const plugin of DEVFLOW_PLUGINS) { + for (const skill of plugin.skills) { + if (!skillsMap.has(skill)) { + skillsMap.set(skill, plugin.name); + } + } + } + return skillsMap; +} diff --git a/src/cli/utils/installer.ts b/src/cli/utils/installer.ts index 6a2b4f2d..b1ad1833 100644 --- a/src/cli/utils/installer.ts +++ b/src/cli/utils/installer.ts @@ -161,7 +161,7 @@ export async function installViaFileCopy(options: FileCopyOptions): Promise { expect(shellPreamble).toContain('IMPLEMENT'); expect(shellPreamble).toContain('DEBUG'); expect(shellPreamble).toContain('REVIEW'); + expect(shellPreamble).toContain('RESOLVE'); + expect(shellPreamble).toContain('PIPELINE'); expect(shellPreamble).toContain('PLAN'); + // Must contain multi-worktree awareness + expect(shellPreamble).toContain('MULTI_WORKTREE'); + // Must reference core skills by name expect(shellPreamble).toContain('implementation-patterns'); expect(shellPreamble).toContain('test-driven-development'); @@ -279,6 +284,14 @@ describe('preamble drift detection', () => { expect(shellPreamble).toContain('self-review'); expect(shellPreamble).toContain('search-first'); + // Must reference all 6 orchestration skills + expect(shellPreamble).toContain('implementation-orchestration'); + expect(shellPreamble).toContain('debug-orchestration'); + expect(shellPreamble).toContain('plan-orchestration'); + expect(shellPreamble).toContain('review-orchestration'); + expect(shellPreamble).toContain('resolve-orchestration'); + expect(shellPreamble).toContain('pipeline-orchestration'); + // Must instruct Skill tool invocation expect(shellPreamble).toContain('Skill tool'); diff --git a/tests/plugins.test.ts b/tests/plugins.test.ts index 9a1a7688..cf2844e5 100644 --- a/tests/plugins.test.ts +++ b/tests/plugins.test.ts @@ -4,6 +4,7 @@ import { getAllSkillNames, getAllAgentNames, buildAssetMaps, + buildFullSkillsMap, type PluginDefinition, } from '../src/cli/plugins.js'; @@ -86,6 +87,33 @@ describe('buildAssetMaps', () => { }); }); +describe('buildFullSkillsMap', () => { + it('includes skills from ALL plugins regardless of selection', () => { + const fullMap = buildFullSkillsMap(); + // Must include skills from optional plugins too + expect(fullMap.has('accessibility')).toBe(true); + expect(fullMap.has('typescript')).toBe(true); + expect(fullMap.has('go')).toBe(true); + // Must include all orchestration skills + expect(fullMap.has('review-orchestration')).toBe(true); + expect(fullMap.has('resolve-orchestration')).toBe(true); + expect(fullMap.has('pipeline-orchestration')).toBe(true); + }); + + it('covers more skills than buildAssetMaps with only non-optional plugins', () => { + const nonOptional = DEVFLOW_PLUGINS.filter(p => !p.optional); + const { skillsMap: partialMap } = buildAssetMaps(nonOptional); + const fullMap = buildFullSkillsMap(); + expect(fullMap.size).toBeGreaterThan(partialMap.size); + }); + + it('matches getAllSkillNames count', () => { + const fullMap = buildFullSkillsMap(); + const allNames = getAllSkillNames(); + expect(fullMap.size).toBe(allNames.length); + }); +}); + describe('DEVFLOW_PLUGINS integrity', () => { it('has no duplicate plugin names', () => { const names = DEVFLOW_PLUGINS.map(p => p.name); @@ -169,6 +197,25 @@ describe('optional plugin flag', () => { expect(DEVFLOW_PLUGINS.find(p => p.name === 'devflow-audit-claude')).toBeDefined(); }); + it('devflow-ambient declares review/resolve skill dependencies', () => { + const ambient = DEVFLOW_PLUGINS.find(p => p.name === 'devflow-ambient'); + expect(ambient).toBeDefined(); + // Ambient must declare review skills so uninstalling code-review doesn't break ambient review + expect(ambient!.skills).toContain('review-methodology'); + expect(ambient!.skills).toContain('security-patterns'); + // Ambient must declare orchestration skills + expect(ambient!.skills).toContain('review-orchestration'); + expect(ambient!.skills).toContain('resolve-orchestration'); + expect(ambient!.skills).toContain('pipeline-orchestration'); + // Ambient must declare resolve dependencies + expect(ambient!.skills).toContain('implementation-patterns'); + expect(ambient!.skills).toContain('knowledge-persistence'); + // Ambient must declare all needed agents + expect(ambient!.agents).toContain('git'); + expect(ambient!.agents).toContain('synthesizer'); + expect(ambient!.agents).toContain('resolver'); + }); + it('devflow-core-skills does not contain language/ecosystem skills', () => { const coreSkills = DEVFLOW_PLUGINS.find(p => p.name === 'devflow-core-skills'); expect(coreSkills).toBeDefined(); diff --git a/tests/uninstall-logic.test.ts b/tests/uninstall-logic.test.ts index 2604c173..07388fc3 100644 --- a/tests/uninstall-logic.test.ts +++ b/tests/uninstall-logic.test.ts @@ -51,6 +51,15 @@ describe('computeAssetsToRemove', () => { expect(commands.length).toBeGreaterThan(0); }); + it('retains review-methodology when code-review uninstalled (ambient declares it)', () => { + const reviewPlugin = DEVFLOW_PLUGINS.find(p => p.name === 'devflow-code-review')!; + const { skills } = computeAssetsToRemove([reviewPlugin], DEVFLOW_PLUGINS); + // review-methodology is also declared by devflow-ambient, so it must NOT be removed + expect(skills).not.toContain('review-methodology'); + // security-patterns is also declared by devflow-ambient + expect(skills).not.toContain('security-patterns'); + }); + it('handles custom plugin lists', () => { const plugins: PluginDefinition[] = [ { name: 'a', description: '', commands: ['/a'], agents: ['shared', 'only-a'], skills: ['shared-skill', 'only-a-skill'] },