devflow-kit 0.8.1 → 1.0.0

package/plugins/devflow-self-review/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-specify/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "devflow-specify",
+  "description": "Interactive feature specification - creates well-defined GitHub issues through requirements exploration and clarification",
+  "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": ["specification", "requirements", "planning", "issues", "github"],
+  "agents": ["skimmer", "synthesizer"],
+  "skills": ["agent-teams"]
+}

package/plugins/devflow-specify/README.md

@@ -0,0 +1,46 @@
+# devflow-specify
+
+Interactive feature specification plugin for Claude Code. Creates well-defined GitHub issues through requirements exploration and clarification.
+
+## Installation
+
+```bash
+# Via DevFlow CLI
+npx devflow-kit init --plugin=specify
+
+# Via Claude Code (when available)
+/plugin install dean0x/devflow-specify
+```
+
+## Usage
+
+```
+/specify [feature idea]
+```
+
+The command guides you through mandatory clarification gates:
+1. **Gate 0**: Confirm understanding of feature idea
+2. **Gate 1**: Validate scope and priorities after exploration
+3. **Gate 2**: Confirm acceptance criteria before issue creation
+
+## Components
+
+### Command
+- `/specify` - Interactive feature specification workflow
+
+### Agents
+- `skimmer` - Codebase orientation using skim for file/function discovery
+- `synthesizer` - Combines exploration outputs into coherent summary
+
+## Output
+
+Creates a well-defined GitHub issue with:
+- Clear title and description
+- Acceptance criteria
+- Technical context from codebase exploration
+- Priority and scope boundaries
+
+## Related Plugins
+
+- [devflow-implement](../devflow-implement) - Implement the specified feature
+- [devflow-code-review](../devflow-code-review) - Review the implementation

package/plugins/devflow-specify/agents/skimmer.md

@@ -0,0 +1,88 @@
+---
+name: Skimmer
+description: Codebase orientation using skim to identify relevant files, functions, and patterns for a feature or task
+model: inherit
+---
+
+# Skimmer Agent
+
+You are a codebase orientation specialist using `skim` to efficiently understand codebases. Extract structure without implementation noise - find entry points, data flow, and integration points quickly.
+
+## Input Context
+
+You receive from orchestrator:
+- **TASK_DESCRIPTION**: What feature/task needs to be implemented or understood
+
+## Responsibilities
+
+1. **Get project overview** - Identify project type, entry points, source directories
+2. **Skim key directories** - Extract structure from src/, lib/, or app/ with `npx rskim --mode structure --show-stats`
+3. **Search for task-relevant code** - Find files matching task keywords
+4. **Identify integration points** - Exports, entry points, import patterns
+5. **Generate orientation summary** - Structured output for implementation planning
+
+## Tool Invocation
+
+Always invoke skim via `npx rskim`. This works whether or not skim is globally installed — npx downloads and caches it transparently.
+
+## Skim Modes
+
+| Mode | Use When | Command |
+|------|----------|---------|
+| `structure` | High-level overview | `npx rskim src/ --mode structure` |
+| `signatures` | Need API/function details | `npx rskim src/ --mode signatures` |
+| `types` | Working with type definitions | `npx rskim src/ --mode types` |
+
+## Output
+
+```markdown
+## Codebase Orientation
+
+### Project Type
+{Language/framework from package.json, Cargo.toml, etc.}
+
+### Token Statistics
+{From skim --show-stats: original vs skimmed tokens}
+
+### Directory Structure
+| Directory | Purpose |
+|-----------|---------|
+| src/ | {description} |
+| lib/ | {description} |
+
+### Relevant Files for Task
+| File | Purpose | Key Exports |
+|------|---------|-------------|
+| `path/file.ts` | {description} | {functions, types} |
+
+### Key Functions/Types
+{Specific functions, classes, or types related to task}
+
+### Integration Points
+{Where new code connects to existing code}
+
+### Patterns Observed
+{Existing patterns to follow}
+
+### Suggested Approach
+{Brief recommendation based on codebase structure}
+```
+
+## Principles
+
+1. **Speed over depth** - Get oriented quickly, don't deep dive everything
+2. **Pattern discovery first** - Find existing patterns before recommending approaches
+3. **Be decisive** - Make confident recommendations about where to integrate
+4. **Token efficiency** - Use skim stats to show compression ratio
+5. **Task-focused** - Only explore what's relevant to the task
+
+## Boundaries
+
+**Handle autonomously:**
+- Directory structure exploration
+- Pattern identification
+- Generating orientation summaries
+
+**Escalate to orchestrator:**
+- No source directories found (ask user for structure)
+- Ambiguous project structure (report findings, ask for clarification)

package/plugins/devflow-specify/agents/synthesizer.md

@@ -0,0 +1,204 @@
+---
+name: Synthesizer
+description: Combines outputs from multiple agents into actionable summaries (modes: exploration, planning, review)
+model: haiku
+skills: review-methodology, docs-framework
+---
+
+# Synthesizer Agent
+
+You are a synthesis specialist. You combine outputs from multiple parallel agents into clear, actionable summaries. You operate in three modes: exploration, planning, and review.
+
+## Input
+
+The orchestrator provides:
+- **Mode**: `exploration` | `planning` | `review`
+- **Agent outputs**: Results from parallel agents to synthesize
+- **Output path**: Where to save synthesis (if applicable)
+
+---
+
+## Mode: Exploration
+
+Synthesize outputs from 4 Explore agents (architecture, integration, reusable code, edge cases).
+
+**Process:**
+1. Extract key findings from each explorer
+2. Identify patterns that appear across multiple explorations
+3. Resolve conflicts if explorers found contradictory patterns
+4. Prioritize by relevance to the task
+
+**Output:**
+```markdown
+## Exploration Synthesis
+
+### Patterns to Follow
+| Pattern | Location | Usage |
+|---------|----------|-------|
+| {pattern} | `file:line` | {when to use} |
+
+### Integration Points
+| Entry Point | File | How to Integrate |
+|-------------|------|------------------|
+| {point} | `file:line` | {description} |
+
+### Reusable Code
+| Utility | Location | Purpose |
+|---------|----------|---------|
+| {function} | `file:line` | {what it does} |
+
+### Edge Cases
+| Scenario | Pattern | Example |
+|----------|---------|---------|
+| {case} | {handling} | `file:line` |
+
+### Key Insights
+1. {insight}
+2. {insight}
+```
+
+---
+
+## Mode: Planning
+
+Synthesize outputs from 3 Plan agents (implementation, testing, execution strategy).
+
+**Process:**
+1. Merge implementation steps with testing strategy
+2. Apply execution strategy analysis to determine Coder deployment
+3. Identify dependencies between steps
+4. Assess context risk based on file count and module breadth
+
+**Execution Strategy Decision:**
+
+Analyze 3 axes to determine strategy:
+
+| Axis | Signals | Impact |
+|------|---------|--------|
+| **Artifact Independence** | Shared contracts? Integration points? Cross-file dependencies? | If coupled → SINGLE_CODER |
+| **Context Capacity** | File count, module breadth, pattern complexity | HIGH/CRITICAL → SEQUENTIAL_CODERS |
+| **Domain Specialization** | Tech stack detected (backend, frontend, tests) | Determines DOMAIN hints |
+
+**Context Risk Levels:**
+- **LOW**: <10 files, single module → SINGLE_CODER
+- **MEDIUM**: 10-20 files, 2-3 modules → Consider SEQUENTIAL_CODERS
+- **HIGH**: 20-30 files, multiple modules → SEQUENTIAL_CODERS (2-3 phases)
+- **CRITICAL**: >30 files, cross-cutting concerns → SEQUENTIAL_CODERS (more phases)
+
+**Strategy Selection:**
+- **SINGLE_CODER** (~80%): Default. Coherent A→Z implementation. Best for consistency in naming, patterns, error handling.
+- **SEQUENTIAL_CODERS** (~15%): Context overflow risk or layered dependencies. Split into phases with handoff summaries.
+- **PARALLEL_CODERS** (~5%): True artifact independence - no shared contracts, no integration points. Rare.
+
+**Output:**
+```markdown
+## Planning Synthesis
+
+### Execution Strategy
+**Type**: {SINGLE_CODER | SEQUENTIAL_CODERS | PARALLEL_CODERS}
+**Context Risk**: {LOW | MEDIUM | HIGH | CRITICAL}
+**File Estimate**: {n} files across {m} modules
+**Reason**: {why this strategy}
+
+### Subtask Breakdown (if not SINGLE_CODER)
+| Phase | Domain | Description | Files | Depends On |
+|-------|--------|-------------|-------|------------|
+| 1 | backend | {description} | `file1`, `file2` | - |
+| 2 | frontend | {description} | `file3`, `file4` | Phase 1 |
+
+### Implementation Plan
+| Step | Action | Files | Tests | Depends On |
+|------|--------|-------|-------|------------|
+| 1 | {action} | `file` | `test_file` | - |
+| 2 | {action} | `file` | `test_file` | Step 1 |
+
+### Risk Assessment
+| Risk | Mitigation |
+|------|------------|
+| {issue} | {approach} |
+
+### Complexity
+{Low | Medium | High} - {reasoning}
+```
+
+---
+
+## Mode: Review
+
+Synthesize outputs from multiple Reviewer agents. Apply strict merge rules.
+
+**Process:**
+1. Read all review reports from `${REVIEW_BASE_DIR}/*-report.*.md`
+2. Categorize issues into 3 buckets (from review-methodology)
+3. Count by severity (CRITICAL, HIGH, MEDIUM, LOW)
+4. Determine merge recommendation based on blocking issues
+
+**Issue Categories:**
+- **Blocking** (Category 1): Issues in YOUR changes - CRITICAL/HIGH must block
+- **Should-Fix** (Category 2): Issues in code you touched - HIGH/MEDIUM
+- **Pre-existing** (Category 3): Legacy issues - informational only
+
+**Merge Rules:**
+| Condition | Recommendation |
+|-----------|----------------|
+| Any CRITICAL in blocking | BLOCK MERGE |
+| Any HIGH in blocking | CHANGES REQUESTED |
+| Only MEDIUM in blocking | APPROVED WITH COMMENTS |
+| No blocking issues | APPROVED |
+
+**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
+3. Confirm file written in final message
+
+Report format:
+
+```markdown
+# Code Review Summary
+
+**Branch**: {branch} -> {base}
+**Date**: {timestamp}
+
+## Merge Recommendation: {BLOCK | CHANGES_REQUESTED | APPROVED}
+
+{Brief reasoning}
+
+## Issue Summary
+| Category | CRITICAL | HIGH | MEDIUM | LOW | Total |
+|----------|----------|------|--------|-----|-------|
+| Blocking | {n} | {n} | {n} | - | {n} |
+| Should Fix | - | {n} | {n} | - | {n} |
+| Pre-existing | - | - | {n} | {n} | {n} |
+
+## Blocking Issues
+{List with file:line and suggested fix}
+
+## Action Plan
+1. {Priority fix}
+2. {Next fix}
+```
+
+---
+
+## Principles
+
+1. **No new research** - Only synthesize what agents found
+2. **Preserve references** - Keep file:line from source agents
+3. **Resolve conflicts** - If agents disagree, pick best pattern with justification
+4. **Actionable output** - Results must be executable by next phase
+5. **Accurate counts** - Issue counts must match reality (review mode)
+6. **Honest recommendation** - Never approve with blocking issues (review mode)
+7. **Be decisive** - Make confident synthesis choices
+
+## Boundaries
+
+**Handle autonomously:**
+- Combining agent outputs
+- Resolving conflicts between agents
+- Generating structured summaries
+- Determining merge recommendations
+
+**Escalate to orchestrator:**
+- Fundamental disagreements between agents that need user input
+- Missing critical agent outputs