devflow-kit 0.9.0 → 1.0.0

package/plugins/devflow-resolve/commands/resolve.md

@@ -0,0 +1,237 @@
+---
+description: Process review issues - validate, assess risk, fix low-risk issues, defer high-risk to tech debt
+---
+
+# 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.
+
+## Usage
+
+```
+/resolve           (resolve issues on current branch)
+/resolve #42       (resolve issues for specific PR)
+```
+
+## Phases
+
+### Phase 0: Pre-Flight (Git Agent)
+
+Spawn Git agent to validate branch state:
+
+```
+Task(subagent_type="Git", run_in_background=false):
+"OPERATION: validate-branch
+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.
+
+**Extract from response:** `branch`, `branch_slug`, `pr_number`, `review_count` for use in subsequent phases.
+
+### Phase 1: Parse Issues
+
+Read all review reports from `.docs/reviews/{branch-slug}/*.md` and extract:
+
+**Include only:**
+- Blocking issues (CRITICAL, HIGH)
+- Should-Fix issues (HIGH, MEDIUM)
+
+**Skip:**
+- Pre-existing issues (belong in tech debt, not resolution)
+- LOW severity (informational only)
+
+**Extract per issue:**
+- `id`: Generated from file:line:type
+- `file`: Full path
+- `line`: Line number
+- `severity`: CRITICAL/HIGH/MEDIUM
+- `type`: Issue type from review
+- `description`: Problem statement
+- `suggested_fix`: From review report
+
+### Phase 2: Analyze Dependencies
+
+Group issues by relationship:
+
+1. **Same file** - Issues in same file go in same batch
+2. **Same function** - Issues affecting same function go together
+3. **Independent** - No relationship, can run in parallel
+
+Build dependency graph to determine execution order.
+
+### Phase 3: Plan Batches
+
+Create execution plan:
+- **Independent batches** - Mark for PARALLEL execution
+- **Dependent batches** - Mark for SEQUENTIAL execution
+- **Max 5 issues per batch** - Keep batches manageable
+
+### Phase 4: Resolve (Parallel where possible)
+
+Spawn Resolver agents based on dependency analysis. For independent batches, spawn **in a single message**:
+
+```
+Task(subagent_type="Resolver"):
+"ISSUES: [{issue1}, {issue2}, ...]
+BRANCH: {branch-slug}
+BATCH_ID: batch-{n}
+Validate, decide FIX vs TECH_DEBT, implement fixes"
+```
+
+For dependent batches, spawn sequentially and wait for completion before spawning dependents.
+
+### Phase 5: Collect Results
+
+Aggregate from all Resolvers:
+- **Fixed**: Issues resolved with commits
+- **False positives**: Issues that don't exist or were misunderstood
+- **Deferred**: High-risk issues marked for tech debt
+- **Blocked**: Issues that couldn't be fixed
+
+### Phase 6: Simplify
+
+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
+FILES_CHANGED: {list of files modified by Resolvers}
+Simplify and refine the fixes for clarity and consistency"
+```
+
+### Phase 7: Manage Tech Debt
+
+If any issues were deferred, spawn Git agent:
+
+```
+Task(subagent_type="Git"):
+"OPERATION: manage-debt
+REVIEW_DIR: .docs/reviews/{branch-slug}/
+TIMESTAMP: {timestamp}
+Note: Deferred issues from resolution are already in resolution-summary.{timestamp}.md"
+```
+
+### Phase 8: Report
+
+**Write the resolution summary** to `.docs/reviews/{branch-slug}/resolution-summary.{timestamp}.md` using Write tool, then display:
+
+```
+## Resolution Summary
+
+**Branch**: {branch}
+**Reviews Processed**: {n} reports
+**Total Issues**: {n}
+
+### Results
+| Outcome | Count |
+|---------|-------|
+| Fixed | {n} |
+| False Positive | {n} |
+| Tech Debt | {n} |
+| Blocked | {n} |
+
+### Commits Created
+- {sha} {message}
+
+### Tech Debt Added
+- {n} items added to backlog
+
+### Artifacts
+- Resolution report: .docs/reviews/{branch}/resolution-summary.{timestamp}.md
+```
+
+## Architecture
+
+```
+/resolve (orchestrator - spawns agents only)
+│
+├─ Phase 0: Pre-flight
+│  └─ Git agent (validate-branch)
+│
+├─ Phase 1: Parse issues
+│  └─ Extract Blocking + Should-Fix (skip Pre-existing)
+│
+├─ Phase 2: Analyze dependencies
+│  └─ Build dependency graph
+│
+├─ Phase 3: Plan batches
+│  └─ Group issues, determine parallel vs sequential
+│
+├─ Phase 4: Resolve (PARALLEL where independent)
+│  ├─ Resolver: Batch 1 (file-a issues)
+│  ├─ Resolver: Batch 2 (file-b issues)
+│  └─ Resolver: Batch 3 (waits if depends on 1 or 2)
+│
+├─ Phase 5: Collect results
+│  └─ Aggregate fixed, false positives, deferred, blocked
+│
+├─ Phase 6: Simplify
+│  └─ Simplifier agent (refine fixes)
+│
+├─ Phase 7: Git agent (manage-debt)
+│  └─ Add deferred items to Tech Debt Backlog
+│
+└─ Phase 8: Display resolution summary
+```
+
+## Edge Cases
+
+| Case | Handling |
+|------|----------|
+| No reviews exist | Error message, suggest `/code-review` first |
+| All false positives | Normal completion, report shows 0 fixes |
+| 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) |
+
+## Principles
+
+1. **Orchestration only** - Command spawns agents, doesn't do git/resolve work itself
+2. **Git agent for git work** - All git operations go through Git agent
+3. **Parallel execution** - Run independent batches in parallel
+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
+
+## Output Artifact
+
+Written by orchestrator in Phase 8 to `.docs/reviews/{branch-slug}/resolution-summary.{timestamp}.md`:
+
+```markdown
+# Resolution Summary
+
+**Branch**: {branch} -> {base}
+**Date**: {timestamp}
+**Command**: /resolve
+
+## Statistics
+| Metric | Value |
+|--------|-------|
+| Total Issues | {n} |
+| Fixed | {n} |
+| False Positive | {n} |
+| Deferred | {n} |
+| Blocked | {n} |
+
+## Fixed Issues
+| Issue | File:Line | Commit |
+|-------|-----------|--------|
+| {description} | {file}:{line} | {sha} |
+
+## False Positives
+| Issue | File:Line | Reasoning |
+|-------|-----------|-----------|
+| {description} | {file}:{line} | {why} |
+
+## Deferred to Tech Debt
+| Issue | File:Line | Risk Factor |
+|-------|-----------|-------------|
+| {description} | {file}:{line} | {criteria} |
+
+## Blocked
+| Issue | File:Line | Blocker |
+|-------|-----------|---------|
+| {description} | {file}:{line} | {why} |
+```

package/plugins/devflow-resolve/skills/agent-teams/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: agent-teams
+description: This skill should be used when the user asks to "create an agent team", "spawn teammates", "set up debate protocol", "coordinate agents", or discusses peer-to-peer agent collaboration, consensus formation, or team-based workflows. Provides patterns for team spawning, message passing, adversarial debate, and quality gates driven by multi-agent consensus.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+---
+
+# Agent Teams Patterns
+
+Patterns for collaborative multi-agent workflows using Claude Code's Agent Teams feature. Teams enable peer-to-peer communication between agents, replacing one-way subagent reporting with adversarial debate and consensus.
+
+## Iron Law
+
+> **TEAMMATES CHALLENGE EACH OTHER**
+>
+> Every finding must survive peer scrutiny. No unchallenged claims reach the final
+> report. A single agent's opinion is a hypothesis; consensus from debate is a finding.
+
+---
+
+## When This Activates
+
+- Creating agent teams for review, implementation, or debugging
+- Spawning teammates with distinct perspectives
+- Coordinating multi-agent debate rounds
+- Forming consensus from conflicting findings
+
+## Core Patterns
+
+### Team Spawning
+
+Size team to task complexity. Assign distinct, non-overlapping perspectives.
+
+| Task Complexity | Team Size | Rationale |
+|----------------|-----------|-----------|
+| Simple review | 2-3 | Security + architecture sufficient |
+| Full review | 4-5 | Core perspectives covered |
+| Debug investigation | 3-5 | One per hypothesis |
+| Implementation | 2-4 | Domain-separated work units |
+| Specification | 3-4 | Debate requirements before user gates |
+| Resolution | 2-4 | Cross-validate fixes across batches |
+
+**Model guidance**: Explorers/Reviewers inherit parent model. Validators use `model: haiku`.
+
+### Detection and Fallback
+
+Attempt `TeamCreate`. If it fails or the tool is unavailable, fall back to parallel subagents:
+
+```
+try TeamCreate → success → proceed with team workflow
+                → failure → fall back to parallel Task() calls
+```
+
+Always document which mode was used in the final report.
+
+### Task List Coordination
+
+Use `TaskCreate` to give each teammate a trackable work unit. Lead checks `TaskList` for structured progress visibility beyond ad-hoc messages:
+
+```
+1. Lead creates tasks for each teammate's work unit
+2. Teammates claim tasks via TaskUpdate (owner: self)
+3. Teammates mark tasks completed when done
+4. Lead checks TaskList before proceeding to next phase
+```
+
+### Challenge Protocol
+
+1. **Initial work**: Each teammate completes independent analysis
+2. **Exchange**: Lead broadcasts "Share findings and challenge others"
+3. **Direct debate**: Teammates message each other with evidence
+4. **Resolution**: Contradictions resolved through 1-2 exchanges
+5. **Escalation**: Unresolved after 2 exchanges → report disagreement to lead
+
+### Consensus Formation
+
+| Agreement Level | Confidence | Report As |
+|----------------|------------|-----------|
+| Unanimous | HIGH | Confirmed finding |
+| Majority (>50%) | MEDIUM | Finding with noted dissent |
+| Split (50/50) | LOW | Disagreement with both perspectives |
+
+### Team Cleanup
+
+Lead MUST always handle cleanup:
+1. Ensure all teammates have completed or been shut down
+2. Call `TeamDelete` to release resources
+3. Verify no orphaned sessions remain
+4. **CRITICAL**: Confirm cleanup completed before creating next team
+
+---
+
+## Limitations
+
+| Limitation | Impact | Guidance |
+|-----------|--------|----------|
+| One team per session | Cannot run two teams concurrently | Shut down and verify cleanup before creating next team |
+| No nested teams | Teammates cannot spawn sub-teams | Keep hierarchy flat; only lead creates teams |
+| No session resumption | Teammate state lost if interrupted | Start fresh; don't rely on teammate state persistence |
+| Shutdown can be slow | Cleanup may take several seconds | Wait for confirmation; don't race to create next team |
+| Task status may lag | Task list updates aren't instant | Use direct messages for time-sensitive coordination |
+| Permissions inherited | Teammates get lead's permissions at spawn | Cannot escalate permissions mid-session |
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Approach |
+|-------------|-----------------|
+| Overlapping perspectives | Assign distinct, non-overlapping focus areas |
+| Skipping debate round | Always require peer challenge before synthesis |
+| Unlimited debate | Cap at 2 exchanges per topic, then escalate |
+| Lead does analysis work | Lead coordinates only; teammates do analysis |
+| Ignoring minority opinion | Report dissent with evidence in final output |
+| Creating team before prior cleanup | Wait for TeamDelete confirmation, then create |
+| Messaging-only coordination | Use task list for structured progress tracking |
+
+---
+
+## Extended References
+
+- `references/team-patterns.md` - Team structures for review, implement, debug, specify, resolve workflows
+- `references/communication.md` - Message protocols, broadcast patterns, debate formats
+- `references/cleanup.md` - Session management, orphan detection, resource cleanup

package/plugins/devflow-resolve/skills/agent-teams/references/cleanup.md

@@ -0,0 +1,104 @@
+# Session Management and Cleanup
+
+## Team Lifecycle
+
+```
+1. Lead creates team
+2. Lead spawns teammates
+3. Teammates work independently
+4. Debate rounds (teammates message directly)
+5. Lead collects consensus
+6. Lead shuts down teammates
+7. Lead calls cleanup
+8. Lead verifies no orphans
+```
+
+---
+
+## Cleanup Rules
+
+### Lead Responsibilities
+
+1. **Always call cleanup** - Even if team work was interrupted or errored
+2. **Shut down teammates first** - Before calling cleanup
+3. **Verify completion** - Check that no orphaned sessions remain
+
+### Error Handling
+
+If a teammate errors or hangs:
+1. Send shutdown message to the teammate
+2. Wait briefly for graceful shutdown
+3. Proceed with cleanup for remaining team
+4. Report the failed teammate in final output
+
+### Orphan Detection
+
+After cleanup, verify:
+- No tmux sessions from the team remain (split-pane mode)
+- No background processes from teammates
+- Team config at `~/.claude/teams/{team-name}/` is cleaned up
+
+---
+
+## Known Limitations
+
+| Limitation | Mitigation |
+|-----------|------------|
+| No session resumption for teammates | Start fresh; don't rely on teammate state persistence |
+| One team per session | Queue team work sequentially if needed |
+| Task status may lag | Use direct messages for time-sensitive coordination |
+| No nested teams | Teammates cannot spawn sub-teams; keep hierarchy flat |
+| Split-pane requires tmux/iTerm2 | Fall back to in-process mode if unavailable |
+
+---
+
+## Cost Management
+
+### Token Optimization
+
+| Strategy | Savings |
+|----------|---------|
+| Use haiku for validation teammates | ~70% per validation agent |
+| Limit debate to 2 rounds | Prevents runaway token usage |
+| Size teams to task (don't over-spawn) | Fewer agents = fewer tokens |
+| Shut down teammates promptly | No idle token consumption |
+
+### When NOT to Use Teams
+
+- Simple, single-focus tasks (use regular subagent)
+- Tasks requiring sequential dependency (no parallelism benefit)
+- Cost-sensitive operations where subagent is sufficient
+- Tasks where debate adds no value (e.g., formatting, simple fixes)
+
+---
+
+## Sequential Team Transition Protocol
+
+Commands that create multiple teams (e.g., `/implement`, `/specify`) MUST follow this 4-step protocol between teams. Skipping steps causes silent failures due to the one-team-per-session constraint.
+
+```
+Step 1: SHUTDOWN — Send shutdown_request to each teammate by name
+  SendMessage(type: "shutdown_request", recipient: "{name}", content: "Phase complete")
+  Wait for each shutdown_response (approve: true)
+
+Step 2: DELETE — Remove team resources
+  TeamDelete
+
+Step 3: VERIFY — Confirm cleanup succeeded
+  If TeamDelete returned success → proceed
+  If TeamDelete failed → retry once after 5s
+  If retry fails → HALT and report to user:
+    "Team cleanup failed for {team-name}. Cannot create next team."
+
+Step 4: CREATE — Only now create the next team
+  TeamCreate(team_name: "{next-team-name}")
+```
+
+### Failure Modes
+
+| Failure | Action |
+|---------|--------|
+| Teammate ignores shutdown_request | Wait 30s, then proceed to TeamDelete (force cleanup) |
+| TeamDelete fails | Retry once after 5s delay |
+| TeamDelete retry fails | HALT execution, report to user |
+| TeamCreate fails after successful delete | Retry once; if fails, fall back to parallel Task() subagents |

package/plugins/devflow-resolve/skills/agent-teams/references/communication.md

@@ -0,0 +1,122 @@
+# Communication Protocols
+
+## Message Types
+
+### Direct Message (one-to-one)
+
+Use when challenging a specific teammate's finding:
+
+```
+To [Security Reviewer]:
+"Your finding about SQL injection at api/users.ts:42 - I disagree.
+The parameterized query at line 45 handles this. Check the query builder
+pattern used throughout this codebase."
+```
+
+### Broadcast (one-to-all)
+
+Use when sharing findings that affect all teammates:
+
+```
+Broadcast:
+"I found that the auth middleware is bypassed for /api/internal/* routes.
+This affects security, architecture, and testing perspectives."
+```
+
+---
+
+## Debate Protocol
+
+### Round Structure
+
+```
+Round 1: Initial findings (each teammate shares top findings)
+Round 2: Challenge round (teammates dispute or validate)
+Round 3: Resolution (update, withdraw, or escalate)
+```
+
+**Cap: 2 challenge exchanges per topic.** If unresolved, escalate to lead.
+
+### Challenge Format
+
+When challenging another teammate:
+
+```
+CHALLENGE to [Teammate]:
+- Finding: [what they claimed]
+- Evidence against: [your counter-evidence with file:line references]
+- Suggested resolution: [what you think is correct]
+```
+
+### Concession Format
+
+When accepting a challenge:
+
+```
+UPDATED based on [Teammate]'s challenge:
+- Original: [what I originally claimed]
+- Revised: [updated finding incorporating their evidence]
+```
+
+### Escalation Format
+
+When debate is unresolved after 2 exchanges:
+
+```
+ESCALATION to Lead:
+- Topic: [what we disagree about]
+- Position A: [first perspective with evidence]
+- Position B: [second perspective with evidence]
+- Recommendation: [which has stronger evidence, or "genuinely split"]
+```
+
+---
+
+## Lead Coordination Messages
+
+### Initiating Debate
+
+```
+Lead broadcast:
+"All teammates: Share your top 3-5 findings. After sharing, challenge
+any finding you disagree with. Provide evidence (file:line references).
+You have 2 exchange rounds to resolve disagreements."
+```
+
+### Ending Debate
+
+```
+Lead broadcast:
+"Debate round complete. Submit final findings with confidence levels:
+- HIGH: Unanimous or unchallenged with evidence
+- MEDIUM: Majority agreed, dissent noted
+- LOW: Split opinion, both perspectives included"
+```
+
+### Requesting Clarification
+
+```
+Lead to [Teammate]:
+"Your finding about X contradicts [Other Teammate]'s finding about Y.
+Can you address their evidence at [file:line]?"
+```
+
+---
+
+## Output Aggregation
+
+### Consensus Report Structure
+
+```markdown
+## Confirmed Findings (HIGH confidence)
+[Findings all teammates agreed on or that survived challenge]
+
+## Majority Findings (MEDIUM confidence)
+[Findings most agreed on, with dissenting view noted]
+
+## Split Findings (LOW confidence)
+[Genuinely contested findings with both perspectives and evidence]
+
+## Withdrawn Findings
+[Findings that were disproved during debate]
+```