devflow-kit 0.8.1 → 1.0.0

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

@@ -0,0 +1,262 @@
+---
+description: Comprehensive branch review using agent teams for adversarial peer review with debate and consensus
+---
+
+# 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.
+
+## Usage
+
+```
+/code-review           (review current branch)
+/code-review #42       (review specific PR)
+```
+
+## Phases
+
+### Phase 0: Pre-Flight (Git Agent)
+
+Spawn Git agent to validate and prepare branch:
+
+```
+Task(subagent_type="Git", run_in_background=false):
+"OPERATION: ensure-pr-ready
+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.
+
+**Extract from response:** `branch`, `base_branch`, `branch_slug`, `pr_number` for use in subsequent phases.
+
+
+
+### Phase 1: Analyze Changed Files
+
+Detect file types in diff to determine conditional reviews:
+
+| Condition | Adds Perspective |
+|-----------|-----------------|
+| .ts/.tsx files | typescript |
+| .tsx/.jsx files | react |
+| .tsx/.jsx files | accessibility |
+| .tsx/.jsx/.css/.scss files | frontend-design |
+| DB/migration files | database |
+| Dependency files changed | dependencies |
+| Docs or significant code | documentation |
+
+### 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.
+
+**Core perspectives (always):**
+- **Security**: vulnerabilities, injection, auth, crypto issues
+- **Architecture**: SOLID violations, coupling, layering, modularity
+- **Performance**: queries, algorithms, caching, I/O bottlenecks
+- **Quality**: complexity, tests, consistency, regression, naming
+
+**Conditional perspectives (based on changed files):**
+- **TypeScript**: type safety, generics, utility types (if .ts/.tsx changed)
+- **React**: hooks, state, rendering, composition (if .tsx/.jsx changed)
+- **Accessibility**: ARIA, keyboard nav, focus management (if .tsx/.jsx changed)
+- **Frontend Design**: visual consistency, spacing, typography (if .tsx/.jsx/.css changed)
+- **Database**: schema, queries, migrations, indexes (if DB files changed)
+- **Dependencies**: CVEs, versions, licenses, supply chain (if package files changed)
+- **Documentation**: doc drift, missing docs, stale comments (if docs or significant code changed)
+
+```
+Create a team named "review-{branch_slug}" to review PR #{pr_number}.
+
+Spawn review teammates with self-contained prompts:
+
+- Name: "security-reviewer"
+  Prompt: |
+    You are reviewing PR #{pr_number} on branch {branch} (base: {base_branch}).
+    1. Read your skill: `Read ~/.claude/skills/security-patterns/SKILL.md`
+    2. Read review methodology: `Read ~/.claude/skills/review-methodology/SKILL.md`
+    3. Get the diff: `git diff {base_branch}...HEAD`
+    4. Apply the 6-step review process from review-methodology
+    5. Focus: injection, auth bypass, crypto misuse, OWASP vulnerabilities
+    6. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
+    7. Include file:line references for every finding
+    8. Write your report: `Write to .docs/reviews/{branch_slug}/security.md`
+    9. 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}).
+    1. Read your skill: `Read ~/.claude/skills/architecture-patterns/SKILL.md`
+    2. Read review methodology: `Read ~/.claude/skills/review-methodology/SKILL.md`
+    3. Get the diff: `git diff {base_branch}...HEAD`
+    4. Apply the 6-step review process from review-methodology
+    5. Focus: SOLID violations, coupling, layering issues, modularity problems
+    6. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
+    7. Include file:line references for every finding
+    8. Write your report: `Write to .docs/reviews/{branch_slug}/architecture.md`
+    9. 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}).
+    1. Read your skill: `Read ~/.claude/skills/performance-patterns/SKILL.md`
+    2. Read review methodology: `Read ~/.claude/skills/review-methodology/SKILL.md`
+    3. Get the diff: `git diff {base_branch}...HEAD`
+    4. Apply the 6-step review process from review-methodology
+    5. Focus: N+1 queries, memory leaks, algorithm issues, I/O bottlenecks
+    6. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
+    7. Include file:line references for every finding
+    8. Write your report: `Write to .docs/reviews/{branch_slug}/performance.md`
+    9. 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}).
+    1. Read your skills:
+       - `Read ~/.claude/skills/complexity-patterns/SKILL.md`
+       - `Read ~/.claude/skills/consistency-patterns/SKILL.md`
+       - `Read ~/.claude/skills/test-patterns/SKILL.md`
+       - `Read ~/.claude/skills/regression-patterns/SKILL.md`
+    2. Read review methodology: `Read ~/.claude/skills/review-methodology/SKILL.md`
+    3. Get the diff: `git diff {base_branch}...HEAD`
+    4. Apply the 6-step review process from review-methodology
+    5. Focus: complexity, test gaps, pattern violations, regressions, naming
+    6. Classify each finding: 🔴 BLOCKING / ⚠️ SHOULD-FIX / ℹ️ PRE-EXISTING
+    7. Include file:line references for every finding
+    8. Write your report: `Write to .docs/reviews/{branch_slug}/quality.md`
+    9. 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]
+```
+
+### Phase 3: Debate Round
+
+After all reviewers complete initial analysis, lead initiates adversarial debate:
+
+Lead initiates debate via broadcast:
+
+```
+SendMessage(type: "broadcast", summary: "Debate: share and challenge findings"):
+"All reviewers: Share your top 3-5 findings. Then challenge findings
+from other reviewers you disagree with. Provide counter-evidence with
+file:line references.
+
+Rules:
+- Security: challenge architecture claims that affect attack surface
+- Architecture: challenge performance suggestions that break separation
+- Performance: challenge complexity assessments with benchmarking context
+- Quality: validate whether tests cover security and performance concerns
+
+Max 2 exchange rounds. Then submit final findings with confidence:
+- HIGH: Unchallenged or survived challenge with evidence
+- MEDIUM: Majority agreed, dissent noted
+- LOW: Genuinely split, both perspectives included"
+```
+
+Reviewers message each other directly using SendMessage:
+- `SendMessage(type: "message", recipient: "{reviewer-name}", summary: "Challenge: {topic}")` to challenge a specific finding
+- `SendMessage(type: "message", recipient: "{reviewer-name}", summary: "Validate: {topic}")` to validate alignment
+- `SendMessage(type: "message", recipient: "team-lead", summary: "Escalation: {topic}")` for unresolvable disagreements
+- Update or withdraw findings based on peer evidence
+
+### Phase 4: Synthesis and PR Comments
+
+**WAIT** for debate to complete, then lead produces outputs.
+
+Spawn 2 agents **in a single message**:
+
+**Git Agent (PR Comments)**:
+```
+Task(subagent_type="Git", run_in_background=false):
+"OPERATION: comment-pr
+Read reviews from .docs/reviews/{branch_slug}/
+Create inline PR comments. Deduplicate overlapping findings.
+Consolidate skipped findings into summary comment.
+Include confidence levels from debate consensus."
+```
+
+**Lead synthesizes review summary** (written to `.docs/reviews/{branch_slug}/review-summary.{timestamp}.md`):
+
+```markdown
+## Review Summary: {branch}
+
+### Merge Recommendation
+{APPROVE / REQUEST_CHANGES / BLOCK}
+
+### Consensus Findings (HIGH confidence)
+{Findings all reviewers agreed on or that survived challenge}
+
+### Majority Findings (MEDIUM confidence)
+{Findings most agreed on, with dissenting view noted}
+
+### Split Findings (LOW confidence)
+{Genuinely contested, both perspectives with evidence}
+
+### Issue Counts
+- 🔴 Blocking: {count}
+- ⚠️ Should-fix: {count}
+- ℹ️ Pre-existing: {count}
+
+### Debate Summary
+{Key exchanges that changed findings}
+```
+
+### Phase 5: Cleanup and Report
+
+Shut down all review teammates explicitly:
+
+```
+For each teammate in [security-reviewer, architecture-reviewer, performance-reviewer, quality-reviewer, ...conditional]:
+  SendMessage(type: "shutdown_request", recipient: "{name}", content: "Review complete")
+  Wait for shutdown_response (approve: true)
+
+TeamDelete
+Verify TeamDelete succeeded. If failed, retry once after 5s. If retry fails, HALT.
+```
+
+Display results:
+- Merge recommendation with confidence level
+- Issue counts by category (🔴 blocking / ⚠️ should-fix / ℹ️ pre-existing)
+- PR comments created/skipped (from Git agent)
+- Key debate highlights
+- Artifact paths
+
+## Architecture
+
+```
+/code-review (orchestrator - creates team, coordinates debate)
+│
+├─ Phase 0: Pre-flight
+│  └─ Git agent (ensure-pr-ready)
+│
+├─ Phase 1: Analyze changed files
+│  └─ Detect file types for conditional perspectives
+│
+├─ Phase 2: Spawn review team
+│  ├─ Security Reviewer (teammate)
+│  ├─ Architecture Reviewer (teammate)
+│  ├─ Performance Reviewer (teammate)
+│  ├─ Quality Reviewer (teammate)
+│  └─ [Conditional: TypeScript, React, A11y, Design, DB, Deps, Docs]
+│
+├─ Phase 3: Debate round
+│  └─ Reviewers challenge each other (max 2 rounds)
+│
+├─ Phase 4: Synthesis
+│  ├─ Git agent (comment-pr with consensus findings)
+│  └─ Lead writes review-summary with confidence levels
+│
+└─ Phase 5: Cleanup and display results
+```
+
+## Principles
+
+1. **Adversarial review** - Reviewers challenge each other's findings, not just report independently
+2. **Consensus confidence** - Findings classified by agreement level (HIGH/MEDIUM/LOW)
+3. **Orchestration only** - Command spawns team, coordinates debate, doesn't do review work itself
+4. **Git agent for git work** - All git operations go through Git agent
+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
+

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

@@ -0,0 +1,141 @@
+---
+description: Comprehensive branch review using specialized sub-agents for PR readiness
+---
+
+# Code Review Command
+
+Run a comprehensive code review of the current branch by spawning parallel review agents, then synthesizing results into PR comments.
+
+## Usage
+
+```
+/code-review           (review current branch)
+/code-review #42       (review specific PR)
+```
+
+## Phases
+
+### Phase 0: Pre-Flight (Git Agent)
+
+Spawn Git agent to validate and prepare branch:
+
+```
+Task(subagent_type="Git", run_in_background=false):
+"OPERATION: ensure-pr-ready
+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.
+
+**Extract from response:** `branch`, `base_branch`, `branch_slug`, `pr_number` for use in subsequent phases.
+
+
+
+### Phase 1: Analyze Changed Files
+
+Detect file types in diff to determine conditional reviews:
+
+| Condition | Adds Review |
+|-----------|-------------|
+| .ts/.tsx files | typescript |
+| .tsx/.jsx files | react |
+| .tsx/.jsx files | accessibility |
+| .tsx/.jsx/.css/.scss files | frontend-design |
+| DB/migration files | database |
+| Dependency files changed | dependencies |
+| Docs or significant code | documentation |
+
+### Phase 2: Run Reviews (Parallel)
+
+Spawn Reviewer agents **in a single message**. Always run 7 core reviews; conditionally add up to 4 more:
+
+| Focus | Always | Pattern Skill |
+|-------|--------|---------------|
+| security | ✓ | security-patterns |
+| architecture | ✓ | architecture-patterns |
+| performance | ✓ | performance-patterns |
+| complexity | ✓ | complexity-patterns |
+| consistency | ✓ | consistency-patterns |
+| regression | ✓ | regression-patterns |
+| tests | ✓ | test-patterns |
+| typescript | conditional | typescript |
+| react | conditional | react |
+| accessibility | conditional | accessibility |
+| frontend-design | conditional | frontend-design |
+| database | conditional | database-patterns |
+| dependencies | conditional | dependencies-patterns |
+| documentation | conditional | documentation-patterns |
+
+Each Reviewer invocation (all in one message, **NOT background**):
+```
+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"
+```
+
+### Phase 3: Synthesis (Parallel)
+
+**WAIT** for Phase 2, then spawn 3 agents **in a single message**:
+
+**Git Agent (PR Comments)**:
+```
+Task(subagent_type="Git", run_in_background=false):
+"OPERATION: comment-pr
+Read reviews from .docs/reviews/{branch-slug}/
+Create inline PR comments, deduplicate, consolidate skipped into summary"
+```
+
+**Synthesizer Agent**:
+```
+Task(subagent_type="Synthesizer", run_in_background=false):
+"Mode: review
+Aggregate findings, determine merge recommendation
+Output: .docs/reviews/{branch-slug}/review-summary.{timestamp}.md"
+```
+
+### Phase 4: 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
+
+## Architecture
+
+```
+/code-review (orchestrator - spawns agents only)
+│
+├─ Phase 0: Pre-flight
+│  └─ Git agent (ensure-pr-ready)
+│
+├─ Phase 1: Analyze changed files
+│  └─ 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, database, deps, docs]
+│
+├─ Phase 3: Synthesis (PARALLEL)
+│  ├─ Git agent (comment-pr)
+│  └─ Synthesizer agent (mode: review)
+│
+└─ Phase 4: Display results
+```
+
+## Principles
+
+1. **Orchestration only** - Command spawns agents, doesn't do git/review work itself
+2. **Parallel, not background** - Multiple agents in one message, but `run_in_background=false` so phases complete before proceeding
+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

package/plugins/devflow-code-review/skills/accessibility/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: accessibility
+description: This skill should be used when the user asks to "add accessibility", "check ARIA", "handle keyboard navigation", "add focus management", or creates UI components, forms, or interactive elements. Provides WCAG 2.1 AA patterns for keyboard navigation, ARIA roles and states, focus management, color contrast, and screen reader support.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.tsx"
+    - "**/*.jsx"
+    - "**/*.css"
+    - "**/*.scss"
+  exclude:
+    - "node_modules/**"
+    - "**/*.test.*"
+    - "**/*.spec.*"
+---
+
+# Accessibility Patterns
+
+Reference for web accessibility (WCAG 2.1 AA compliance), keyboard navigation, screen reader support, and inclusive design.
+
+## Iron Law
+
+> **EVERY INTERACTION MUST BE POSSIBLE WITHOUT A MOUSE**
+>
+> If a user cannot complete an action using only keyboard, the feature is broken.
+> Mouse-only interactions exclude users with motor disabilities, power users,
+> and anyone navigating with assistive technology. Tab order, focus management,
+> and keyboard shortcuts are not optional enhancements.
+
+## When This Skill Activates
+
+- Creating interactive UI components
+- Building forms and inputs
+- Working with React/JSX code
+- Discussing focus, ARIA, or screen readers
+- Reviewing color schemes or contrast
+
+---
+
+## Keyboard Navigation
+
+### Focus Management
+
+```tsx
+// CORRECT: Focus trap in modal
+function Modal({ isOpen, onClose, children }) {
+  const firstFocusable = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    if (isOpen) firstFocusable.current?.focus();
+  }, [isOpen]);
+
+  return (
+    <div role="dialog" aria-modal="true" onKeyDown={(e) => {
+      if (e.key === 'Escape') onClose();
+    }}>
+      <button ref={firstFocusable}>First action</button>
+      {children}
+    </div>
+  );
+}
+
+// VIOLATION: No focus management, no escape handler
+function BadModal({ children }) {
+  return <div className="modal">{children}</div>;
+}
+```
+
+### Skip Links
+
+```tsx
+// CORRECT: Skip to main content
+<a href="#main-content" className="sr-only focus:not-sr-only">
+  Skip to main content
+</a>
+<main id="main-content" tabIndex={-1}>...</main>
+```
+
+---
+
+## ARIA and Semantic HTML
+
+### Prefer Semantic Elements
+
+```tsx
+// CORRECT: Native semantics
+<button onClick={handleClick}>Submit</button>
+<nav aria-label="Main"><ul>...</ul></nav>
+<article><header>...</header></article>
+
+// VIOLATION: Div with role instead of semantic element
+<div role="button" onClick={handleClick}>Submit</div>
+<div role="navigation">...</div>
+```
+
+### Live Regions
+
+```tsx
+// CORRECT: Announce dynamic changes
+<div aria-live="polite" aria-atomic="true">
+  {message && <p>{message}</p>}
+</div>
+
+// For errors (assertive)
+<div role="alert">{errorMessage}</div>
+```
+
+---
+
+## Color and Contrast
+
+| Element | Minimum Ratio | WCAG Level |
+|---------|--------------|------------|
+| Normal text (<18px) | 4.5:1 | AA |
+| Large text (>=18px bold, >=24px) | 3:1 | AA |
+| UI components | 3:1 | AA |
+| Enhanced | 7:1 | AAA |
+
+### Never Color-Only Meaning
+
+```tsx
+// VIOLATION: Only color indicates error
+<input style={{ borderColor: hasError ? 'red' : 'gray' }} />
+
+// CORRECT: Icon + text + color
+<input aria-invalid={hasError} aria-describedby="error-msg" />
+{hasError && <span id="error-msg" role="alert">Required field</span>}
+```
+
+---
+
+## Motion and Animation
+
+```tsx
+// CORRECT: Respect user preferences
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+<div className={prefersReduced ? 'no-animation' : 'animate-fade'}>
+  Content
+</div>
+
+// CSS approach
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+---
+
+## Touch and Pointer
+
+### Minimum Target Size
+
+```css
+/* CORRECT: 44x44px minimum touch target */
+.button {
+  min-width: 44px;
+  min-height: 44px;
+  padding: 12px 16px;
+}
+
+/* VIOLATION: Tiny tap targets */
+.icon-button {
+  width: 20px;
+  height: 20px;
+}
+```
+
+---
+
+## Forms and Errors
+
+```tsx
+// CORRECT: Associated labels and error linking
+<div>
+  <label htmlFor="email">Email</label>
+  <input
+    id="email"
+    type="email"
+    aria-invalid={!!error}
+    aria-describedby={error ? 'email-error' : undefined}
+  />
+  {error && <span id="email-error" role="alert">{error}</span>}
+</div>
+
+// VIOLATION: Placeholder as label
+<input placeholder="Enter email" />
+```
+
+---
+
+## Extended References
+
+For additional patterns and detection rules:
+- `references/violations.md` - Extended accessibility violations
+- `references/patterns.md` - Extended correct patterns
+- `references/detection.md` - Grep patterns for finding issues
+
+---
+
+## Severity Guidelines
+
+| Severity | Criteria |
+|----------|----------|
+| CRITICAL | No keyboard access, missing form labels, zero contrast |
+| HIGH | Missing focus indicators, no skip links, color-only meaning |
+| MEDIUM | Missing ARIA labels, poor focus order, small touch targets |
+| LOW | Missing optional enhancements, could improve announcements |
+
+---
+
+## Checklist
+
+- [ ] All interactive elements reachable via Tab
+- [ ] Visible focus indicators on all focusable elements
+- [ ] Escape closes modals/dropdowns
+- [ ] Skip link to main content
+- [ ] All form inputs have associated labels
+- [ ] Errors linked via aria-describedby
+- [ ] Color contrast meets 4.5:1 (text) / 3:1 (UI)
+- [ ] No color-only meaning
+- [ ] prefers-reduced-motion respected
+- [ ] Touch targets minimum 44x44px
+- [ ] aria-live for dynamic content
+- [ ] Semantic HTML preferred over ARIA roles