devflow-kit 1.8.2 → 2.0.0

package/plugins/devflow-self-review/skills/self-review/references/stub-detection.md

@@ -1,135 +0,0 @@
-# Stub Detection Patterns
-
-Placeholder implementations that compile but don't deliver real functionality. Flag as **P0-Functionality** issues.
-
-Cross-reference: `core-patterns/references/code-smell-violations.md` covers hardcoded data and fake functionality labeling. This file focuses on structural stub patterns.
-
----
-
-## 1. Component Stubs
-
-Render nothing meaningful or return placeholder markup.
-
-```tsx
-// STUB — returns static text, no real rendering
-function UserProfile({ userId }: Props) {
-  return <div>Name</div>;
-}
-
-// REAL — fetches and renders actual data
-function UserProfile({ userId }: Props) {
-  const user = useUser(userId);
-  if (!user) return <Skeleton />;
-  return <div><h2>{user.name}</h2><p>{user.email}</p></div>;
-}
-```
-
-**Patterns to flag:**
-- `return null` / `return <></>` in components that should render content
-- Empty function bodies (`{}`) for handlers or lifecycle methods
-- Components returning only hardcoded strings with no data binding
-
----
-
-## 2. API / Service Stubs
-
-Functions that exist in signature but throw, return hardcoded values, or do nothing.
-
-```typescript
-// STUB — throws instead of implementing
-async function createOrder(items: CartItem[]): Promise<Order> {
-  throw new Error("TODO: implement");
-}
-
-// STUB — hardcoded return, no real logic
-async function getUser(id: string): Promise<User> {
-  return { id, name: "Test User", email: "test@test.com" };
-}
-
-// REAL — actual implementation
-async function createOrder(items: CartItem[]): Promise<Result<Order, OrderError>> {
-  const validated = validateItems(items);
-  if (!validated.ok) return validated;
-  const order = await db.orders.create({ items: validated.value });
-  await queue.publish("order.created", order);
-  return { ok: true, value: order };
-}
-```
-
-**Patterns to flag:**
-- `throw new Error("TODO")` / `throw new Error("Not implemented")`
-- Functions returning hardcoded objects (no DB/API/computation)
-- `"Not implemented"` strings in response bodies
-- Empty async functions (`async function foo() {}`)
-
----
-
-## 3. Hook / Effect Stubs
-
-State and effects declared but not wired to behavior.
-
-```typescript
-// STUB — effect does nothing
-useEffect(() => {}, [userId]);
-
-// STUB — state declared, setter never called
-const [items, setItems] = useState<Item[]>([]);
-// ... setItems never appears in the component
-
-// STUB — custom hook returns static value
-function usePermissions(): Permissions {
-  return { canEdit: true, canDelete: false };
-}
-
-// REAL — custom hook with actual logic
-function usePermissions(): Permissions {
-  const { user } = useAuth();
-  const { data } = useQuery(["permissions", user.role], fetchPermissions);
-  return data ?? DEFAULT_PERMISSIONS;
-}
-```
-
-**Patterns to flag:**
-- `useEffect(() => {}, [...])` — empty effect body
-- `useState` where the setter is never called in the component
-- Custom hooks returning static/hardcoded values
-- `useMemo`/`useCallback` wrapping static values
-
----
-
-## 4. Wiring Gaps
-
-Individual pieces exist but aren't connected to the running application. **Highest-value detection** — these pass compilation and individual tests but the feature doesn't work end-to-end.
-
-```typescript
-// GAP — fetch without await (result discarded)
-function loadDashboard() {
-  fetchMetrics(); // Promise floats, never awaited
-  return <Dashboard />;
-}
-
-// GAP — state declared but never rendered
-const [error, setError] = useState<string | null>(null);
-// ... error never appears in JSX
-
-// GAP — handler defined but not bound
-function handleSubmit(data: FormData) { /* real logic */ }
-// ... <form onSubmit={handleSubmit}> never appears
-
-// GAP — route defined with no-op handler
-app.post("/api/orders", (_req, res) => {
-  res.status(200).json({ ok: true });
-});
-
-// GAP — env var read but unused
-const API_KEY = process.env.STRIPE_API_KEY;
-// ... API_KEY never passed to any client or fetch call
-```
-
-**Patterns to flag:**
-- `fetch`/`axios`/API call without `await` or `.then` (result discarded)
-- State variable (`useState`, `useRef`) never rendered or read in output
-- Event handler defined but not bound to any element/listener
-- Route/endpoint registered with empty or no-op handler
-- Environment variable or config read but never used downstream
-- Import used only in type position but imported as value (in non-type-only import)

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

@@ -1,308 +0,0 @@
-# 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

@@ -1,25 +0,0 @@
-{
-  "name": "devflow-specify",
-  "description": "Interactive feature specification - creates well-defined GitHub issues through requirements exploration and clarification",
-  "author": {
-    "name": "Dean0x"
-  },
-  "version": "1.8.2",
-  "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

@@ -1,46 +0,0 @@
-# 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

@@ -1,143 +0,0 @@
----
-name: Skimmer
-description: Codebase orientation using rskim to identify relevant files, functions, and patterns for a feature or task
-tools: ["Bash", "Read"]
-skills: knowledge-persistence
-model: inherit
----
-
-# Skimmer Agent
-
-You are a codebase orientation specialist. You use `npx rskim` exclusively for code exploration — never Grep, Glob, or manual file searches. Your output gives implementation agents a clear map of relevant files, functions, and integration points.
-
-## Input Context
-
-You receive from orchestrator:
-- **TASK_DESCRIPTION**: What feature/task needs to be implemented or understood
-
-## Workflow
-
-Execute these steps in order. Do NOT skip steps or reorder.
-
-### Step 1: Project Overview
-
-Run `ls` on the project root via Bash to identify source directories and project type. Then Read the project manifest (`package.json`, `Cargo.toml`, `go.mod`, `pyproject.toml`, etc.) to understand the project.
-
-**CRITICAL**: Never run `npx rskim .` or `npx rskim` on the repo root — it scans ALL files including `node_modules/` and produces millions of tokens. Always target specific source directories.
-
-### Step 2: Primary Source Skim
-
-Run rskim on the main source directory with a token budget:
-
-```bash
-npx rskim src/ --tokens 15000 --show-stats
-```
-
-The `--tokens` flag auto-cascades through modes (full → minimal → structure → signatures → types) to fit within the budget. Let it choose the mode — do not specify `--mode` when using `--tokens`.
-
-If `--tokens` flag errors (older rskim version), fall back to:
-```bash
-npx rskim src/ --mode structure --show-stats
-```
-
-### Step 3: Secondary Directories (if relevant to task)
-
-Skim additional directories with smaller budgets:
-
-```bash
-npx rskim tests/ --tokens 5000 --show-stats
-npx rskim scripts/ --tokens 5000 --show-stats
-```
-
-Only skim directories relevant to the task description.
-
-### Step 4: Deep Inspection
-
-For specific files needing detailed view, use rskim with full mode:
-
-```bash
-npx rskim path/to/file.ts --mode full
-```
-
-Use this instead of Read for code files.
-
-### Step 5: Project Knowledge
-
-If `.memory/knowledge/decisions.md` exists, Read its `<!-- TL;DR: ... -->` first-line comment and include active decision count in orientation under "### Active Decisions". Only the TL;DR is read here — this is intentional for token efficiency.
-
-### Step 6: Generate Summary
-
-Produce the orientation summary in the output format below.
-
-## rskim Reference
-
-| Flag | Effect |
-|------|--------|
-| `--tokens N` | Token budget — auto-selects best mode to fit within N tokens |
-| `--mode minimal` | Maximum compression (~85-90% reduction) |
-| `--mode structure` | Architecture overview (~60-70% reduction) |
-| `--mode signatures` | API/function details (~85-92% reduction) |
-| `--mode types` | Type definitions only (~90-95% reduction) |
-| `--mode full` | Complete file content (0% reduction) |
-| `--show-stats` | Show original vs skimmed token counts |
-| `--max-lines N` | AST-aware truncation (keeps types/signatures over imports/bodies) |
-
-**Preferred**: Use `--tokens N` instead of choosing modes manually.
-
-## Output
-
-```markdown
-## Codebase Orientation
-
-### Project Type
-{Language/framework from manifest}
-
-### Token Statistics
-{From rskim --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}
-
-### Active Decisions
-{Count and key decisions from `.memory/knowledge/decisions.md` TL;DR, or "None found" if file missing}
-
-### 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 rskim token budgets and stats to show compression ratio
-5. **Task-focused** - Only explore what's relevant to the task
-
-## Boundaries
-
-**Handle autonomously:**
-- Directory structure exploration via rskim
-- Pattern identification
-- Generating orientation summaries
-
-**Escalate to orchestrator:**
-- If `npx rskim` fails, report the error (do not attempt manual fallbacks with other tools) — orchestrators should spawn an ad-hoc Explore agent if Skimmer reports rskim failure
-- No source directories found (ask user for structure)
-- Ambiguous project structure (report findings, ask for clarification)