devflow-kit 0.8.1 → 1.0.0

package/plugins/devflow-debug/agents/git.md

@@ -0,0 +1,272 @@
+---
+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
+---
+
+# Git Agent
+
+You are a Git/GitHub operations specialist. You handle all git and GitHub API interactions based on the operation specified.
+
+## Input
+
+The orchestrator provides:
+- **OPERATION**: Which task to perform
+- **Operation-specific parameters**: See each operation below
+
+## 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 | - |
+| `setup-task` | Create feature branch and fetch issue | `TASK_ID`, `BASE_BRANCH`, `ISSUE_INPUT` (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` |
+| `create-release` | Create GitHub release with version tag | `VERSION`, `CHANGELOG_CONTENT` |
+
+---
+
+## Operation: ensure-pr-ready
+
+Pre-flight checks and fixes for `/code-review`. Ensures branch is ready for code review.
+
+**Input:** None (uses current branch)
+
+**Process:**
+1. Verify on feature branch (not main/master/develop) - 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
+5. Get base branch from PR
+6. Derive branch-slug (replace `/` with `-`)
+
+**Output:**
+```markdown
+## Pre-Flight: Ready for Review
+
+### Branch
+- **Current**: {branch}
+- **Base**: {base_branch}
+- **Branch Slug**: {branch-slug}
+- **PR**: #{number}
+
+### Actions Taken
+- Committed: {yes/no} ({message} if yes)
+- Pushed: {yes/no}
+- PR Created: {yes/no}
+
+### Status: READY | BLOCKED
+{BLOCKED reason if applicable}
+```
+
+---
+
+## Operation: validate-branch
+
+Pre-flight validation for `/resolve`. Checks branch state without modifications.
+
+**Input:** None (uses current branch)
+
+**Process:**
+1. Verify on feature branch (not main/master/develop) - 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}/`
+6. If PR# context provided, fetch PR details
+
+**Output:**
+```markdown
+## Pre-Flight: Validation
+
+### Branch
+- **Current**: {branch}
+- **Branch Slug**: {branch-slug}
+- **PR**: #{number} (if exists)
+- **Base**: {base_branch}
+
+### Checks
+- Feature branch: {PASS/FAIL}
+- Clean working directory: {PASS/FAIL}
+- Reviews exist: {PASS/FAIL} ({n} reports found)
+
+### Status: READY | BLOCKED
+{BLOCKED reason if applicable}
+```
+
+---
+
+## Operation: setup-task
+
+Set up task environment: create feature branch and optionally fetch issue.
+
+**Input:**
+- `TASK_ID`: Unique task identifier (becomes branch name)
+- `BASE_BRANCH`: Branch to create from (track this for PR target)
+- `ISSUE_INPUT` (optional): Issue number to fetch
+
+**Process:**
+1. Record current branch as BASE_BRANCH for later PR targeting
+2. Create and checkout feature branch: `git checkout -b {TASK_ID}`
+3. If ISSUE_INPUT provided, fetch issue details via GitHub API
+4. Return setup summary with BASE_BRANCH recorded
+
+**Output:**
+```markdown
+## Task Setup: {TASK_ID}
+
+### Branch
+- **Feature branch**: {TASK_ID}
+- **Base branch**: {BASE_BRANCH} (PR target)
+
+### Issue (if fetched)
+- **Number**: #{number}
+- **Title**: {title}
+- **Description**: {description}
+- **Acceptance Criteria**: {criteria}
+```
+
+---
+
+## Operation: fetch-issue
+
+Fetch comprehensive issue details for implementation planning.
+
+**Input:** `ISSUE_INPUT` - Issue number (e.g., "123") or search term (e.g., "fix login bug")
+
+**Process:**
+1. If numeric, fetch directly; if text, search and select first open match
+2. Fetch full issue data (title, body, labels, assignees, milestone, comments)
+3. Extract acceptance criteria and dependencies from body
+
+**Output:**
+```markdown
+## Issue #{number}: {title}
+**State**: {open/closed} | **Labels**: {labels} | **Priority**: {P0-P3 or Unspecified}
+
+### Description
+{body summary}
+
+### Acceptance Criteria
+{extracted or "Not specified"}
+
+### Dependencies
+{extracted "depends on #X" references or "None"}
+
+### Suggested Branch
+{type}/{number}-{slug}
+```
+
+---
+
+## Operation: comment-pr
+
+Create inline PR comments for blocking and should-fix issues from code review.
+
+**Input:** `PR_NUMBER`, `REVIEW_BASE_DIR`, `TIMESTAMP`
+
+**Process:**
+1. Get PR context (head SHA, changed files, diff)
+2. Read review reports from `${REVIEW_BASE_DIR}/*.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
+
+**Output:**
+```markdown
+## PR Comments Created
+**PR**: #{number}
+
+### Inline Comments
+- Created: {n}
+- Skipped: {n} (lines not in diff)
+
+### Summary Comment
+{Created | Not needed}
+```
+
+---
+
+## Operation: manage-debt
+
+Update tech debt backlog with pre-existing issues from code review.
+
+**Input:** `REVIEW_DIR`, `TIMESTAMP`
+
+**Process:**
+1. Find or create "Tech Debt Backlog" issue with `tech-debt` label
+2. Check issue body size; archive if > 60000 chars (per github-patterns)
+3. Extract pre-existing issues (Category 3) from review reports
+4. Deduplicate against existing items using semantic matching
+5. Remove items that have been fixed (verify in codebase)
+6. Update issue body with changes
+
+**Output:**
+```markdown
+## Tech Debt Management
+**Issue**: #{number}
+
+### Changes
+- Added: {n} new items
+- Removed: {n} fixed items
+- Duplicates skipped: {n}
+
+### Archive Status
+{Within limits | Archived to #{n}}
+```
+
+---
+
+## Operation: create-release
+
+Create a GitHub release with version tag.
+
+**Input:** `VERSION` (semver), `CHANGELOG_CONTENT`, `RELEASE_TITLE` (optional)
+
+**Process:**
+1. Validate version format (semver: X.Y.Z)
+2. Verify clean working directory
+3. Create annotated tag with changelog content
+4. Push tag to origin
+5. Create GitHub release via `gh release create`
+
+**Output:**
+```markdown
+## Release Created
+**Version**: v{version}
+**URL**: {release_url}
+
+### Next Steps
+- Verify at: {url}
+- Check package registry (if applicable)
+```
+
+---
+
+## Principles
+
+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
+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
+
+## Boundaries
+
+**Handle autonomously:**
+- All GitHub API operations
+- Issue search and selection
+- Comment creation and deduplication
+- Tech debt management
+- Release creation
+
+**Escalate to orchestrator:**
+- Missing PR (suggest `gh pr create`)
+- Rate limit exhaustion (report and wait)
+- Authentication failures

package/plugins/devflow-debug/commands/debug-teams.md

@@ -0,0 +1,231 @@
+---
+description: Debug issues using competing hypothesis investigation with an agent team
+---
+
+# Debug Command
+
+Investigate bugs by spawning a team of agents, each pursuing a different hypothesis. Agents actively try to disprove each other's theories, converging on the root cause that survives scrutiny.
+
+## Usage
+
+```
+/debug "description of bug or issue"
+/debug "function returns undefined when called with empty array"
+/debug #42   (investigate bug from GitHub issue)
+```
+
+## Input
+
+`$ARGUMENTS` contains whatever follows `/debug`:
+- Bug description: "login fails after session timeout"
+- GitHub issue: "#42"
+- Empty: use conversation context
+
+## Phases
+
+### Phase 1: Context Gathering
+
+If `$ARGUMENTS` starts with `#`, fetch the GitHub issue:
+
+```
+Task(subagent_type="Git"):
+"OPERATION: fetch-issue
+ISSUE: {issue number}
+Return issue title, body, labels, and any linked error logs."
+```
+
+Analyze the bug description (from arguments or issue) and identify 3-5 plausible hypotheses. Each hypothesis must be:
+- **Specific**: Points to a concrete mechanism (not "something is wrong")
+- **Testable**: Can be confirmed or disproved by reading code/logs
+- **Distinct**: Does not overlap significantly with other hypotheses
+
+### Phase 2: Spawn Investigation Team
+
+Create an agent team with one investigator per hypothesis:
+
+```
+Create a team named "debug-{bug-slug}" to investigate: {bug_description}
+
+Spawn investigator teammates with self-contained prompts:
+
+- Name: "investigator-a"
+  Prompt: |
+    You are investigating a bug: {bug_description}
+    Your hypothesis: {hypothesis A description}
+    Focus area: {specific code area, mechanism, or condition}
+
+    Steps:
+    1. Read relevant code files in your focus area
+    2. Trace data flow related to your hypothesis
+    3. Collect evidence FOR your hypothesis (with file:line references)
+    4. Collect evidence AGAINST your hypothesis (with file:line references)
+    5. Document all findings
+    6. Report completion:
+       SendMessage(type: "message", recipient: "team-lead",
+         summary: "Hypothesis A: initial findings ready")
+
+- Name: "investigator-b"
+  Prompt: |
+    You are investigating a bug: {bug_description}
+    Your hypothesis: {hypothesis B description}
+    Focus area: {specific code area, mechanism, or condition}
+
+    Steps:
+    1. Read relevant code files in your focus area
+    2. Trace data flow related to your hypothesis
+    3. Collect evidence FOR your hypothesis (with file:line references)
+    4. Collect evidence AGAINST your hypothesis (with file:line references)
+    5. Document all findings
+    6. Report completion:
+       SendMessage(type: "message", recipient: "team-lead",
+         summary: "Hypothesis B: initial findings ready")
+
+- Name: "investigator-c"
+  Prompt: |
+    You are investigating a bug: {bug_description}
+    Your hypothesis: {hypothesis C description}
+    Focus area: {specific code area, mechanism, or condition}
+
+    Steps:
+    1. Read relevant code files in your focus area
+    2. Trace data flow related to your hypothesis
+    3. Collect evidence FOR your hypothesis (with file:line references)
+    4. Collect evidence AGAINST your hypothesis (with file:line references)
+    5. Document all findings
+    6. Report completion:
+       SendMessage(type: "message", recipient: "team-lead",
+         summary: "Hypothesis C: initial findings ready")
+
+(Add more investigators if bug complexity warrants 4-5 hypotheses — same pattern)
+```
+
+### Phase 3: Investigation
+
+Teammates investigate in parallel:
+- Read relevant source files
+- Trace execution paths
+- Check error handling
+- Look for edge cases and race conditions
+- Build evidence for or against their hypothesis
+
+### Phase 4: Adversarial Debate
+
+Lead initiates debate via broadcast:
+
+```
+SendMessage(type: "broadcast", summary: "Debate: share findings and challenge hypotheses"):
+"Investigation complete. Share your findings:
+1. State your hypothesis
+2. Present evidence FOR (with file:line references)
+3. Present evidence AGAINST
+4. Challenge at least one other investigator's hypothesis
+
+Rules:
+- You must try to DISPROVE other hypotheses, not just support your own
+- Cite specific code when challenging
+- If your hypothesis is disproved, acknowledge it
+- Max 2 exchange rounds before we converge"
+```
+
+Teammates challenge each other directly using SendMessage:
+- `SendMessage(type: "message", recipient: "investigator-b", summary: "Challenge: evidence at auth.ts:42")`
+  "My evidence at `src/auth.ts:42` disproves your hypothesis because..."
+- `SendMessage(type: "message", recipient: "investigator-a", summary: "Counter: Tuesday-only failure")`
+  "Your theory doesn't explain why this only fails on Tuesdays..."
+- `SendMessage(type: "message", recipient: "team-lead", summary: "Updated hypothesis")`
+  "I've updated my hypothesis based on investigator-b's finding at..."
+
+### Phase 5: Convergence
+
+After debate (max 2 rounds), lead collects results:
+
+```
+Lead broadcast:
+"Debate complete. Each investigator: submit final status.
+- CONFIRMED: Your hypothesis survived scrutiny (evidence summary)
+- DISPROVED: Your hypothesis was invalidated (what disproved it)
+- PARTIAL: Some aspects confirmed, others not (details)"
+```
+
+### Phase 6: Cleanup
+
+Shut down all investigator teammates explicitly:
+
+```
+For each teammate in [investigator-a, investigator-b, investigator-c, ...]:
+  SendMessage(type: "shutdown_request", recipient: "{name}", content: "Investigation complete")
+  Wait for shutdown_response (approve: true)
+
+TeamDelete
+Verify TeamDelete succeeded. If failed, retry once after 5s. If retry fails, HALT.
+```
+
+### Phase 7: Report
+
+Lead produces final report:
+
+```markdown
+## Root Cause Analysis: {bug description}
+
+### Root Cause (Consensus)
+{Description of the root cause that survived peer scrutiny}
+{Key evidence with file:line references}
+
+### Investigation Summary
+
+| Hypothesis | Status | Key Evidence |
+|-----------|--------|-------------|
+| A: {description} | CONFIRMED/DISPROVED/PARTIAL | {file:line + summary} |
+| B: {description} | CONFIRMED/DISPROVED/PARTIAL | {file:line + summary} |
+| C: {description} | CONFIRMED/DISPROVED/PARTIAL | {file:line + summary} |
+
+### Key Debate Exchanges
+{2-3 most important exchanges that led to the conclusion}
+
+### Recommended Fix
+{Concrete action items with file references}
+
+### Confidence Level
+{HIGH/MEDIUM/LOW based on consensus strength}
+```
+
+## Architecture
+
+```
+/debug (orchestrator)
+│
+├─ Phase 1: Context gathering
+│  └─ Git agent (fetch issue, if #N provided)
+│
+├─ Phase 2: Spawn investigation team
+│  └─ Create team with 3-5 hypothesis investigators
+│
+├─ Phase 3: Parallel investigation
+│  └─ Each teammate investigates independently
+│
+├─ Phase 4: Adversarial debate
+│  └─ Teammates challenge each other directly (max 2 rounds)
+│
+├─ Phase 5: Convergence
+│  └─ Teammates submit final hypothesis status
+│
+├─ Phase 6: Cleanup
+│  └─ Shut down teammates, release resources
+│
+└─ Phase 7: Root cause report with confidence level
+```
+
+## Principles
+
+1. **Competing hypotheses** - Never investigate a single theory; always have alternatives
+2. **Adversarial debate** - Agents must actively try to disprove each other
+3. **Evidence-based** - Every claim requires file:line references
+4. **Bounded debate** - Max 2 exchange rounds, then converge
+5. **Honest uncertainty** - If no hypothesis survives, report that clearly
+6. **Cleanup always** - Team resources released even on failure
+
+## Error Handling
+
+- If fewer than 3 hypotheses can be generated: proceed with 2, note limited scope
+- If all hypotheses are disproved: report "No root cause identified" with investigation summary
+- If a teammate errors: continue with remaining teammates, note the gap

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

@@ -0,0 +1,160 @@
+---
+description: Debug issues using competing hypothesis investigation with parallel agents
+---
+
+# Debug Command
+
+Investigate bugs by spawning parallel agents, each pursuing a different hypothesis. Evidence is aggregated and synthesized to identify the root cause.
+
+## Usage
+
+```
+/debug "description of bug or issue"
+/debug "function returns undefined when called with empty array"
+/debug #42   (investigate bug from GitHub issue)
+```
+
+## Input
+
+`$ARGUMENTS` contains whatever follows `/debug`:
+- Bug description: "login fails after session timeout"
+- GitHub issue: "#42"
+- Empty: use conversation context
+
+## Phases
+
+### Phase 1: Context Gathering
+
+If `$ARGUMENTS` starts with `#`, fetch the GitHub issue:
+
+```
+Task(subagent_type="Git"):
+"OPERATION: fetch-issue
+ISSUE: {issue number}
+Return issue title, body, labels, and any linked error logs."
+```
+
+Analyze the bug description (from arguments or issue) and identify 3-5 plausible hypotheses. Each hypothesis must be:
+- **Specific**: Points to a concrete mechanism (not "something is wrong")
+- **Testable**: Can be confirmed or disproved by reading code/logs
+- **Distinct**: Does not overlap significantly with other hypotheses
+
+### Phase 2: Investigate (Parallel)
+
+Spawn one Explore agent per hypothesis in a **single message** (parallel execution):
+
+```
+Task(subagent_type="Explore", name="investigator-a"):
+"Investigate this bug: {bug_description}
+
+Hypothesis: {hypothesis A description}
+Focus area: {specific code area, mechanism, or condition}
+
+Steps:
+1. Read relevant code files in your focus area
+2. Trace data flow related to this hypothesis
+3. Collect evidence FOR this hypothesis (with file:line references)
+4. Collect evidence AGAINST this hypothesis (with file:line references)
+
+Return a structured report:
+- Hypothesis: {restate}
+- Status: CONFIRMED / DISPROVED / PARTIAL
+- Evidence FOR: [list with file:line refs]
+- Evidence AGAINST: [list with file:line refs]
+- Key finding: {one-sentence summary}"
+
+Task(subagent_type="Explore", name="investigator-b"):
+"Investigate this bug: {bug_description}
+
+Hypothesis: {hypothesis B description}
+Focus area: {specific code area, mechanism, or condition}
+
+[same steps and return format]"
+
+Task(subagent_type="Explore", name="investigator-c"):
+"Investigate this bug: {bug_description}
+
+Hypothesis: {hypothesis C description}
+Focus area: {specific code area, mechanism, or condition}
+
+[same steps and return format]"
+
+(Add more investigators if bug complexity warrants 4-5 hypotheses)
+```
+
+### Phase 3: Synthesize
+
+Once all investigators return, spawn a Synthesizer agent to aggregate findings:
+
+```
+Task(subagent_type="general-purpose", name="synthesizer"):
+"You are a root cause analyst. Synthesize these investigation reports:
+
+{paste all investigator reports}
+
+Instructions:
+1. Compare evidence across all hypotheses
+2. Identify which hypothesis has the strongest evidence
+3. Note contradictions between investigators
+4. Determine overall root cause (may combine partial findings)
+5. Assess confidence level based on evidence strength"
+```
+
+### Phase 4: Report
+
+Produce the final report:
+
+```markdown
+## Root Cause Analysis: {bug description}
+
+### Root Cause
+{Description of the root cause supported by evidence}
+{Key evidence with file:line references}
+
+### Investigation Summary
+
+| Hypothesis | Status | Key Evidence |
+|-----------|--------|-------------|
+| A: {description} | CONFIRMED/DISPROVED/PARTIAL | {file:line + summary} |
+| B: {description} | CONFIRMED/DISPROVED/PARTIAL | {file:line + summary} |
+| C: {description} | CONFIRMED/DISPROVED/PARTIAL | {file:line + summary} |
+
+### Key Findings
+{2-3 most important discoveries across all investigators}
+
+### Recommended Fix
+{Concrete action items with file references}
+
+### Confidence Level
+{HIGH/MEDIUM/LOW based on evidence strength and investigator agreement}
+```
+
+## Architecture
+
+```
+/debug (orchestrator)
+│
+├─ Phase 1: Context gathering
+│  └─ Git agent (fetch issue, if #N provided)
+│
+├─ Phase 2: Parallel investigation
+│  └─ 3-5 Explore agents, one per hypothesis (single message)
+│
+├─ Phase 3: Synthesize
+│  └─ Synthesizer aggregates and compares findings
+│
+└─ Phase 4: Root cause report with confidence level
+```
+
+## Principles
+
+1. **Competing hypotheses** - Never investigate a single theory; always have alternatives
+2. **Parallel execution** - All investigators run simultaneously for speed
+3. **Evidence-based** - Every claim requires file:line references
+4. **Honest uncertainty** - If no hypothesis survives, report that clearly
+
+## Error Handling
+
+- If fewer than 3 hypotheses can be generated: proceed with 2, note limited scope
+- If all hypotheses are disproved: report "No root cause identified" with investigation summary
+- If an investigator errors: continue with remaining results, note the gap