devflow-kit 1.8.3 → 2.0.0

package/shared/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/shared/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/shared/skills/test-driven-development/SKILL.md

@@ -1,137 +0,0 @@
----
-name: test-driven-development
-description: This skill should be used when implementing new features, fixing bugs, or writing new code. Enforces RED-GREEN-REFACTOR.
-user-invocable: false
-allowed-tools: Read, Grep, Glob
-activation:
-  file-patterns:
-    - "**/*.ts"
-    - "**/*.tsx"
-    - "**/*.js"
-    - "**/*.jsx"
-    - "**/*.py"
-  exclude:
-    - "node_modules/**"
-    - "dist/**"
-    - "**/*.test.*"
-    - "**/*.spec.*"
----
-
-# Test-Driven Development
-
-Enforce the RED-GREEN-REFACTOR cycle for all implementation work. Tests define the design. Code satisfies the tests. Refactoring improves the design without changing behavior.
-
-## Iron Law
-
-> **TESTS FIRST, ALWAYS**
->
-> Write the failing test before the production code. No exceptions. If you catch
-> yourself writing production code without a failing test, stop immediately, delete
-> the production code, write the test, watch it fail, then write the minimum code
-> to make it pass. The test IS the specification.
-
----
-
-## The Cycle
-
-### Step 1: RED — Write a Failing Test
-
-Write a test that describes the behavior you want. Run it. Watch it fail. The failure message IS your specification.
-
-```
-Describe what the code SHOULD do, not how it does it.
-One behavior per test. One assertion per test (ideally).
-Name tests as sentences: "returns error when email is invalid"
-```
-
-**Checkpoint:** The test MUST fail before proceeding. A test that passes immediately proves nothing.
-
-### Step 2: GREEN — Write Minimum Code to Pass
-
-Write the simplest production code that makes the failing test pass. No more, no less.
-
-```
-Hardcode first if that's simplest. Generalize when the next test forces it.
-Don't write code "you'll need later." Write code the test demands NOW.
-Don't optimize. Don't refactor. Don't clean up. Just pass the test.
-```
-
-**Checkpoint:** All tests pass. If any test fails, fix it before moving on.
-
-### Step 3: REFACTOR — Improve Without Changing Behavior
-
-Now clean up. Extract helpers, rename variables, simplify logic. Tests stay green throughout.
-
-```
-Run tests after every refactoring step.
-If a test breaks during refactor, undo immediately — you changed behavior.
-Apply DRY, extract patterns, improve readability.
-```
-
-**Checkpoint:** All tests still pass. Code is clean. Repeat from Step 1 for next behavior.
-
----
-
-## Rationalization Prevention
-
-These are the excuses developers use to skip TDD. Recognize and reject them.
-
-| Excuse | Why It Feels Right | Why It's Wrong | Correct Action |
-|--------|-------------------|---------------|----------------|
-| "I'll write tests after" | Need to see the shape first | Tests ARE the shape — they define the interface before implementation exists | Write the test first |
-| "Too simple to test" | It's just a getter/setter | Getters break, defaults change, edge cases hide in "simple" code | Write it — takes 30 seconds |
-| "I'll refactor later" | Just get it working now | "Later" never comes; technical debt compounds silently | Refactor now in Step 3 |
-| "Test is too hard to write" | Setup is complex, mocking is painful | Hard-to-test code = bad design; the test is telling you the interface is wrong | Simplify the interface first |
-| "Need to see the whole picture" | Can't test what I haven't designed yet | TDD IS design; each test reveals the next piece of the interface | Let the test guide the design |
-| "Tests slow me down" | Faster to just write the code | Faster until the first regression; TDD is faster for anything > 50 lines | Trust the cycle |
-
-See `references/rationalization-prevention.md` for extended examples with code.
-
----
-
-## Process Enforcement
-
-When implementing any feature under ambient IMPLEMENT/GUIDED or IMPLEMENT/ORCHESTRATED:
-
-1. **Identify the first behavior** — What is the simplest thing this feature must do?
-2. **Write the test** — Describe that behavior as a failing test
-3. **Run the test** — Confirm it fails (RED)
-4. **Write minimum code** — Just enough to pass (GREEN)
-5. **Refactor** — Clean up while tests stay green (REFACTOR)
-6. **Repeat** — Next behavior, next test, next cycle
-
-### File Organization
-
-- Test file lives next to production file: `user.ts` → `user.test.ts`
-- Follow project's existing test conventions (Jest, Vitest, pytest, etc.)
-- Import the module under test, not internal helpers
-
-### What to Test
-
-| Test | Don't Test |
-|------|-----------|
-| Public API behavior | Private implementation details |
-| Error conditions and edge cases | Framework internals |
-| Integration points (boundaries) | Third-party library correctness |
-| State transitions | Getter/setter plumbing (unless non-trivial) |
-
----
-
-## When TDD Does Not Apply
-
-- **QUICK depth** — Ambient classified as QUICK (chat, exploration, trivial edits)
-- **Non-code tasks** — Documentation, configuration, CI changes
-- **Exploratory prototyping** — User explicitly says "just spike this" or "prototype"
-- **Existing test suite changes** — Modifying tests themselves (test-patterns skill applies instead)
-
-When skipping TDD, never rationalize. State clearly: "Skipping TDD because: [specific reason from list above]."
-
----
-
-## Integration with Ambient Mode
-
-- **IMPLEMENT/GUIDED** → TDD enforced in main session. Write the failing test before production code. Skill loaded directly.
-- **IMPLEMENT/ORCHESTRATED** → TDD enforced via Coder agent (skill in Coder frontmatter). Every implementation gets test-first treatment.
-- **IMPLEMENT/QUICK** → TDD skipped (trivial single-file edit).
-- **DEBUG/GUIDED** → TDD applies to the fix in main session: write a test that reproduces the bug first, then fix.
-- **DEBUG/ORCHESTRATED** → TDD applies to the fix: write a test that reproduces the bug first, then fix.

package/shared/skills/test-driven-development/references/rationalization-prevention.md

@@ -1,111 +0,0 @@
-# TDD Rationalization Prevention — Extended Examples
-
-Detailed code examples showing how each rationalization leads to worse outcomes.
-
-## "I'll write tests after"
-
-### What happens:
-
-```typescript
-// Developer writes production code first
-function calculateDiscount(price: number, tier: string): number {
-  if (tier === 'gold') return price * 0.8;
-  if (tier === 'silver') return price * 0.9;
-  return price;
-}
-
-// Then "writes tests after" — but only for the happy path they remember
-test('gold tier gets 20% off', () => {
-  expect(calculateDiscount(100, 'gold')).toBe(80);
-});
-// Missing: negative prices, unknown tiers, zero prices, NaN handling
-```
-
-### What TDD would have caught:
-
-```typescript
-// Test first — forces you to think about the contract
-test('returns error for negative price', () => {
-  expect(calculateDiscount(-100, 'gold')).toEqual({ ok: false, error: 'NEGATIVE_PRICE' });
-});
-// Now the interface includes error handling from the start
-```
-
-## "Too simple to test"
-
-### What happens:
-
-```typescript
-// "It's just a config getter, no test needed"
-function getMaxRetries(): number {
-  return parseInt(process.env.MAX_RETRIES || '3');
-}
-// 6 months later: someone sets MAX_RETRIES="three" and prod crashes with NaN retries
-```
-
-### What TDD would have caught:
-
-```typescript
-test('returns default when env var is not a number', () => {
-  process.env.MAX_RETRIES = 'three';
-  expect(getMaxRetries()).toBe(3); // Forces validation logic
-});
-```
-
-## "Test is too hard to write"
-
-### What happens:
-
-```typescript
-// "I can't test this easily because it needs database + email + filesystem"
-async function processOrder(orderId: string) {
-  const db = new Database();
-  const order = await db.find(orderId);
-  await sendEmail(order.customerEmail, 'Your order is processing');
-  await fs.writeFile(`/invoices/${orderId}.pdf`, generateInvoice(order));
-  await db.update(orderId, { status: 'processing' });
-}
-// Result: untestable monolith, test would need real DB + email + filesystem
-```
-
-### What TDD forces:
-
-```typescript
-// Hard-to-test = bad design. TDD forces dependency injection:
-async function processOrder(
-  orderId: string,
-  deps: { db: OrderRepository; emailer: Emailer; invoices: InvoiceStore }
-): Promise<Result<void, OrderError>> {
-  // Now trivially testable with mocks
-}
-```
-
-## "I'll refactor later"
-
-### What happens:
-
-```typescript
-// Sprint 1: "just get it working"
-function handleRequest(req: any) {
-  if (req.type === 'create') { /* 50 lines */ }
-  else if (req.type === 'update') { /* 50 lines */ }
-  else if (req.type === 'delete') { /* 30 lines */ }
-  // Sprint 2-10: more conditions added, function grows to 500 lines
-  // "Refactor later" never comes because nobody wants to touch it
-}
-```
-
-### What TDD enforces:
-
-Step 3 (REFACTOR) happens every cycle. The function never grows beyond what's clean because you clean it every 5-10 minutes.
-
-## "Tests slow me down"
-
-### The math:
-
-| Approach | Time to write | Time to first bug | Time to fix bug | Total (1 month) |
-|----------|:---:|:---:|:---:|:---:|
-| No TDD | 2h | 4h | 3h (no repro test) | 9h+ |
-| TDD | 3h | Caught in test | 15min (test pinpoints) | 3h 15min |
-
-TDD is slower for the first 30 minutes. It's faster for everything after that.