devflow-kit 0.9.0 → 1.0.0

package/plugins/devflow-implement/skills/self-review/references/violations.md

@@ -0,0 +1,308 @@
+# Self-Review Violations
+
+Common anti-patterns and code violations organized by the 9 pillars.
+
+---
+
+## Self-Review Process Violations
+
+| Violation | Problem | Fix |
+|-----------|---------|-----|
+| Skipping pillars | Incomplete review | Check all 9 pillars |
+| Ignoring P0/P1 issues | Returning broken code | Fix before returning |
+| Surface-level review | Missing deep issues | Review each pillar thoroughly |
+| No evidence | Unverifiable claims | Reference specific code |
+| Deferring critical fixes | Technical debt | Fix CRITICAL/HIGH immediately |
+
+---
+
+## P0 Pillars (MUST Fix)
+
+### 1. Design Violations
+
+**Question**: Does the implementation fit the architecture?
+
+**Red Flags**:
+```typescript
+// BAD: Direct database access in controller
+class UserController {
+  async getUser(req, res) {
+    const user = await db.query('SELECT * FROM users WHERE id = ?', [req.params.id]);
+  }
+}
+
+// BAD: God class doing everything
+class ApplicationManager {
+  createUser() {}
+  processPayment() {}
+  sendEmail() {}
+  generateReport() {}
+  // 500 more methods...
+}
+
+// BAD: Circular dependencies
+// a.ts imports b.ts, b.ts imports a.ts
+```
+
+**Checklist**:
+- [ ] Follows existing patterns in codebase
+- [ ] Respects layer boundaries (controller/service/repository)
+- [ ] Dependencies injected, not instantiated
+- [ ] Not over-engineering (YAGNI)
+- [ ] Not under-engineering (technical debt)
+- [ ] Interactions with other components are sound
+
+---
+
+### 2. Functionality Violations
+
+**Question**: Does the code work as intended?
+
+**Red Flags**:
+```typescript
+// BAD: Missing null check
+function getDisplayName(user: User) {
+  return user.profile.displayName;  // user.profile could be undefined!
+}
+
+// BAD: Race condition
+let balance = await getBalance();
+if (balance >= amount) {
+  await withdraw(amount);  // Balance could change between check and withdraw!
+}
+
+// BAD: Off-by-one error
+for (let i = 0; i <= array.length; i++) {  // Should be < not <=
+  process(array[i]);
+}
+```
+
+**Checklist**:
+- [ ] Happy path works correctly
+- [ ] Edge cases handled (null, empty, boundary values)
+- [ ] Error cases handled gracefully
+- [ ] No race conditions in concurrent code
+- [ ] No infinite loops or recursion without base case
+- [ ] State mutations are intentional and correct
+
+---
+
+### 3. Security Violations
+
+**Question**: Are there security vulnerabilities?
+
+**Red Flags**:
+```typescript
+// BAD: SQL injection
+const query = `SELECT * FROM users WHERE email = '${email}'`;
+
+// BAD: Command injection
+exec(`ls ${userInput}`);
+
+// BAD: Hardcoded secret
+const API_KEY = 'sk-abc123xyz789';
+
+// BAD: Missing auth check
+app.delete('/api/users/:id', async (req, res) => {
+  await deleteUser(req.params.id);  // No auth!
+});
+```
+
+**Checklist**:
+- [ ] No SQL/NoSQL injection
+- [ ] No command injection
+- [ ] No XSS vulnerabilities
+- [ ] Input validated at boundaries
+- [ ] No hardcoded secrets
+- [ ] Authentication/authorization checked
+- [ ] Sensitive data not logged
+
+---
+
+## P1 Pillars (SHOULD Fix)
+
+### 4. Complexity Violations
+
+**Question**: Can a reader understand this in 5 minutes?
+
+**Red Flags**:
+```typescript
+// BAD: Deep nesting
+if (a) {
+  if (b) {
+    if (c) {
+      if (d) {
+        if (e) {
+          // actual logic buried here
+        }
+      }
+    }
+  }
+}
+
+// BAD: Magic numbers
+setTimeout(callback, 86400000);
+if (status === 3) { }
+```
+
+**Checklist**:
+- [ ] Functions are < 50 lines
+- [ ] Nesting depth < 4 levels
+- [ ] Cyclomatic complexity < 10
+- [ ] No magic numbers/strings
+- [ ] Single responsibility per function
+- [ ] Complex logic has explanatory comments
+
+---
+
+### 5. Error Handling Violations
+
+**Question**: Are errors handled explicitly and consistently?
+
+**Red Flags**:
+```typescript
+// BAD: Swallowed exception
+try {
+  await riskyOperation();
+} catch (e) {
+  // silently ignored!
+}
+
+// BAD: Generic error message
+throw new Error('Something went wrong');
+
+// BAD: Resource leak on error
+const file = await openFile(path);
+await processFile(file);  // If this throws, file never closed!
+await file.close();
+```
+
+**Checklist**:
+- [ ] Errors are caught and handled appropriately
+- [ ] Error messages are helpful (not generic)
+- [ ] No silent failures (swallowed exceptions)
+- [ ] Consistent error handling pattern (Result types or throws)
+- [ ] Resources cleaned up in error paths
+- [ ] Errors logged with context
+
+---
+
+### 6. Tests Violations
+
+**Question**: Is the new functionality tested?
+
+**Red Flags**:
+```typescript
+// BAD: No tests for new function
+export function calculateDiscount(price, type) {
+  // 20 lines of logic with no tests
+}
+
+// BAD: Test that doesn't verify behavior
+it('creates user', async () => {
+  await createUser(data);
+  expect(mockDb.insert).toHaveBeenCalled();  // Only checks mock was called
+});
+
+// BAD: Missing edge case tests
+describe('divide', () => {
+  it('divides numbers', () => {
+    expect(divide(10, 2)).toBe(5);
+  });
+  // No test for divide by zero!
+});
+```
+
+**Checklist**:
+- [ ] New code has corresponding tests
+- [ ] Tests cover happy path
+- [ ] Tests cover error cases
+- [ ] Tests cover edge cases
+- [ ] Tests are not brittle (test behavior, not implementation)
+- [ ] Tests would fail if code breaks
+
+---
+
+## P2 Pillars (FIX if Time Permits)
+
+### 7. Naming Violations
+
+**Question**: Are names clear and descriptive?
+
+**Red Flags**:
+```typescript
+// BAD: Cryptic names
+const d = new Date();
+const r = items.filter(i => i.t > d);
+const x = r.reduce((a, b) => a + b.p, 0);
+
+// BAD: Misleading name
+function getUser(id) {
+  return db.users.findAll();  // Returns ALL users, not one!
+}
+```
+
+**Checklist**:
+- [ ] Variable names describe content
+- [ ] Function names describe action
+- [ ] No single-letter names (except loop indices)
+- [ ] No abbreviations that aren't universal
+- [ ] Consistent naming style (camelCase/snake_case)
+
+---
+
+### 8. Consistency Violations
+
+**Question**: Does this match existing patterns?
+
+**Red Flags**:
+```typescript
+// BAD: Different style than rest of codebase
+// Existing code uses Result types
+function existingFunction(): Result<User, Error> { }
+
+// Your code throws instead
+function yourFunction(): User {
+  throw new Error('...');  // Inconsistent!
+}
+```
+
+**Checklist**:
+- [ ] Follows existing code style
+- [ ] Uses same patterns as surrounding code
+- [ ] Error handling matches project conventions
+- [ ] Import organization matches existing files
+- [ ] No unnecessary divergence from norms
+
+---
+
+### 9. Documentation Violations
+
+**Question**: Will others understand this code?
+
+**Red Flags**:
+```typescript
+// BAD: Missing docs on complex function
+export function calculateProratedBilling(plan, start, end, previous) {
+  // 50 lines of complex billing logic with no explanation
+}
+
+// BAD: Outdated comment
+// Returns user's full name
+function getDisplayName(user) {
+  return user.username;  // Actually returns username!
+}
+```
+
+**Checklist**:
+- [ ] Complex logic has explanatory comments
+- [ ] Public APIs have JSDoc/docstrings
+- [ ] README updated if behavior changes
+- [ ] No outdated comments
+- [ ] Comments explain "why", not "what"
+
+---
+
+## Quick Reference
+
+See [patterns.md](patterns.md) for correct patterns and [report-template.md](report-template.md) for self-review format.

package/plugins/devflow-resolve/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "devflow-resolve",
+  "description": "Process and fix code review issues with risk assessment - decides FIX vs TECH_DEBT based on impact",
+  "author": {
+    "name": "DevFlow Contributors",
+    "email": "dean@keren.dev"
+  },
+  "version": "1.0.0",
+  "homepage": "https://github.com/dean0x/devflow",
+  "repository": "https://github.com/dean0x/devflow",
+  "license": "MIT",
+  "keywords": ["issues", "fixes", "tech-debt", "resolution", "review"],
+  "agents": ["git", "resolver", "simplifier"],
+  "skills": [
+    "implementation-patterns",
+    "security-patterns",
+    "agent-teams"
+  ]
+}

package/plugins/devflow-resolve/README.md

@@ -0,0 +1,65 @@
+# devflow-resolve
+
+Review issue resolution plugin for Claude Code. Processes review findings, assesses risk, and implements fixes or defers to tech debt.
+
+## Installation
+
+```bash
+# Via DevFlow CLI
+npx devflow-kit init --plugin=resolve
+
+# Via Claude Code (when available)
+/plugin install dean0x/devflow-resolve
+```
+
+## Usage
+
+```
+/resolve                           # Resolve issues from latest review
+/resolve .docs/reviews/feature-x/  # Resolve from specific review
+```
+
+## Workflow
+
+1. **Load Issues** - Parse review reports for actionable items
+2. **Validate** - Confirm issues are real and still present
+3. **Risk Assessment** - Evaluate fix complexity and impact
+4. **Decision** - FIX (low risk) or TECH_DEBT (high risk)
+5. **Implementation** - Resolver agent implements fixes
+6. **Simplification** - Simplifier refines the changes
+7. **Tech Debt Tracking** - Git agent manages deferred items
+
+## Risk Assessment Criteria
+
+| Decision | Criteria |
+|----------|----------|
+| FIX | Localized change, low regression risk, clear solution |
+| TECH_DEBT | Cross-cutting change, high complexity, needs design |
+
+## Components
+
+### Command
+- `/resolve` - Process and fix review issues
+
+### Agents
+- `git` - GitHub operations (tech debt management)
+- `resolver` - Validates and implements fixes
+- `simplifier` - Code refinement after fixes
+
+### Skills (5)
+- `core-patterns` - Result types, DI
+- `git-safety` - Safe git operations
+- `commit` - Atomic commit patterns
+- `implementation-patterns` - Implementation guidance
+- `security-patterns` - Security fix patterns
+
+## Output
+
+- Fixed issues committed to branch
+- Tech debt items tracked in GitHub
+- Resolution summary with fix/defer breakdown
+
+## Related Plugins
+
+- [devflow-code-review](../devflow-code-review) - Generate review issues
+- [devflow-implement](../devflow-implement) - Original implementation

package/plugins/devflow-resolve/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