devlyn-cli 0.1.6 → 0.2.1

package/CLAUDE.md

@@ -6,6 +6,15 @@
 - Follow commit conventions in `.claude/commit-conventions.md`
 - Follow design system in `docs/design-system.md` for UI/UX work if exist
 
+## Error Handling Philosophy
+
+**No silent fallbacks.** Handle errors explicitly and show the user what happened.
+
+- **Default behavior**: When something fails, display a clear error state in the UI (error message, retry option, or actionable guidance). Do NOT silently fall back to default/placeholder data.
+- **Fallbacks are the exception, not the rule.** Only use fallbacks when it is a widely accepted best practice (e.g., fallback fonts in CSS, CDN failover, graceful image loading with placeholder). If unsure, handle the error explicitly instead.
+- **Never hide failures.** The user should always know when something went wrong. A visible error with a retry button is better UX than silently showing stale/default data.
+- **Pattern**: `try { doThing() } catch (error) { showErrorUI(error) }` — NOT `try { doThing() } catch { return fallbackValue }`
+
 ## Investigation Workflow
 
 When investigating bugs, analyzing features, or exploring code:
@@ -39,6 +48,19 @@ The full design-to-implementation pipeline:
 
 For complex features, use the Plan agent to design the approach before implementation.
 
+## Vibe Coding Workflow
+
+The recommended sequence after writing code:
+
+1. **Write code** (vibe coding)
+2. `/simplify` → Quick cleanup pass (reuse, quality, efficiency)
+3. `/devlyn.review` → Thorough solo review with security-first checklist
+4. `/devlyn.team-review` → Multi-perspective team review (for important PRs)
+5. `/devlyn.clean` → Periodic codebase-wide hygiene
+6. `/devlyn.update-docs` → Keep docs in sync
+
+Steps 4-6 are optional depending on the scope of changes. `/simplify` should always run before `/devlyn.review` to catch low-hanging fruit cheaply.
+
 ## Documentation Workflow
 
 - **Sync docs with codebase**: Use `/devlyn.update-docs` to clean up stale content, update outdated info, and generate missing docs
@@ -52,6 +74,20 @@ For complex features, use the Plan agent to design the approach before implement
 - **Complex bugs**: Use `/devlyn.team-resolve` for multi-perspective investigation with a full agent team
 - **Post-fix review**: Use `/devlyn.team-review` for thorough multi-reviewer validation
 
+## Maintenance Workflow
+
+- **Codebase cleanup**: Use `/devlyn.clean` to detect and remove dead code, unused dependencies, complexity hotspots, and tech debt
+- **Focused cleanup**: Use `/devlyn.clean [category]` for targeted sweeps (dead code, deps, tests, complexity, hygiene)
+- **Periodic maintenance sequence**: `/devlyn.clean` → `/simplify` → `/devlyn.update-docs` → `/devlyn.review`
+
+## Context Window Management
+
+When a conversation approaches context limits (50k+ tokens):
+1. Check usage with `/context`
+2. Create a HANDOFF.md summarizing: what was attempted, what succeeded, what failed, and next steps
+3. Start a new session with `/clear`
+4. Load context: `@HANDOFF.md Read this file and continue the work`
+
 ## Communication Style
 
 - Lead with **objective data** (popularity, benchmarks, community adoption) before personal opinions

package/README.md

@@ -49,7 +49,7 @@ npx devlyn-cli list
 your-project/
 ├── .claude/
 │   ├── commands/              # 14 slash commands
-│   ├── skills/                # 3 core skills + optional addons
+│   ├── skills/                # 5 core skills + optional addons
 │   ├── templates/             # Document templates
 │   └── commit-conventions.md  # Commit message standards
 └── CLAUDE.md                  # Project-level instructions
@@ -74,7 +74,7 @@ Slash commands are invoked directly in Claude Code conversations (e.g., `/devlyn
 | `/devlyn.team-design-ui` | Team-based design exploration — spawns creative director, product designer, visual designer, interaction designer, accessibility designer |
 | `/devlyn.design-system` | Design system reference and guidance |
 | `/devlyn.update-docs` | Sync all project docs with current codebase — cleans stale content, preserves roadmaps, generates missing docs |
-| `/devlyn.handoff` | Create structured handoff docs for context window transitions |
+| `/devlyn.clean` | Detect and remove dead code, unused dependencies, complexity hotspots, and tech debt |
 
 ## Skills
 
@@ -85,6 +85,8 @@ Skills are triggered automatically based on conversation context.
 | `root-cause-analysis` | 5 Whys methodology, evidence standards, and no-workaround rules for debugging |
 | `code-review-standards` | Severity framework, quality bar, and approval criteria for code reviews |
 | `ui-implementation-standards` | Design system fidelity, accessibility, animation quality, and responsive standards for UI work |
+| `code-health-standards` | Dead code prevention, dependency discipline, complexity thresholds, and production hygiene |
+| `workflow-routing` | SDLC phase map — guides you to the right command for your current task |
 
 ## Templates
 

package/bin/devlyn.js

@@ -9,6 +9,11 @@ const CONFIG_SOURCE = path.join(__dirname, '..', 'config');
 const OPTIONAL_SKILLS_SOURCE = path.join(__dirname, '..', 'optional-skills');
 const PKG = require('../package.json');
 
+// Files removed in previous versions that should be cleaned up on upgrade
+const DEPRECATED_FILES = [
+  'commands/devlyn.handoff.md', // removed in v0.2.0
+];
+
 function getTargetDir() {
   try {
     return path.join(process.cwd(), '.claude');
@@ -170,6 +175,19 @@ function listContents() {
   log('');
 }
 
+function cleanupDeprecated(targetDir) {
+  let removed = 0;
+  for (const relPath of DEPRECATED_FILES) {
+    const fullPath = path.join(targetDir, relPath);
+    if (fs.existsSync(fullPath)) {
+      fs.unlinkSync(fullPath);
+      log(`  ✕ ${relPath} (deprecated)`, 'dim');
+      removed++;
+    }
+  }
+  return removed;
+}
+
 function copyRecursive(src, dest, baseDir) {
   const stats = fs.statSync(src);
 
@@ -329,6 +347,12 @@ async function init(skipPrompts = false) {
   log('\n📁 Installing core config to .claude/', 'green');
   copyRecursive(CONFIG_SOURCE, targetDir, targetDir);
 
+  // Remove deprecated files from previous versions
+  const removed = cleanupDeprecated(targetDir);
+  if (removed > 0) {
+    log(`\n🧹 Cleaned up ${removed} deprecated file${removed > 1 ? 's' : ''}`, 'yellow');
+  }
+
   // Copy CLAUDE.md to project root
   const claudeMdSrc = path.join(__dirname, '..', 'CLAUDE.md');
   const claudeMdDest = path.join(process.cwd(), 'CLAUDE.md');

package/config/commands/devlyn.clean.md

@@ -0,0 +1,285 @@
+---
+description: Detect and remove dead code, unused dependencies, complexity hotspots, and tech debt. Keeps your codebase lean and maintainable.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash(ls:*), Bash(test:*), Bash(git log:*), Bash(git blame:*), Bash(wc:*), Bash(npm:*), Bash(npx:*), Bash(pnpm:*), Bash(yarn:*), Bash(cargo:*), Bash(pip:*), Bash(go:*), Bash(node -e:*), Bash(python -c:*)
+argument-hint: [focus area, or empty for full scan]
+---
+
+<role>
+You are a Codebase Health Engineer. Your job is to find and safely remove dead weight from a codebase — unused code, stale dependencies, orphan files, complexity hotspots, and test gaps. You care about maintainability as much as functionality.
+
+Your operating principle: every line of code is a liability. Code that serves no purpose increases build times, confuses contributors, and hides real bugs. Remove it with confidence, preserve it with evidence.
+</role>
+
+<user_input>
+$ARGUMENTS
+</user_input>
+
+<escalation>
+If the cleanup reveals deeply intertwined architectural debt — circular dependencies, god objects woven into multiple systems, or patterns that can't be safely removed without redesigning interfaces — escalate to `/devlyn.team-resolve` with your findings so a multi-perspective team can plan the refactor.
+</escalation>
+
+<process>
+
+## Phase 1: CODEBASE UNDERSTANDING
+
+Before analyzing anything, understand the project's shape.
+
+1. Read project metadata in parallel:
+   - package.json / Cargo.toml / pyproject.toml / go.mod (whatever applies)
+   - README.md, CLAUDE.md
+   - Linter and build configs (tsconfig.json, .eslintrc, biome.json, etc.)
+
+2. Scan the project structure:
+   - List top-level directories
+   - Identify the tech stack, framework, entry points
+   - Check for monorepo structure (workspaces, packages/)
+
+3. Check recent git activity:
+   - `git log --oneline -20` for recent changes
+   - Identify actively maintained vs. stale areas
+
+## Phase 2: ANALYSIS
+
+Run these 5 analysis categories. Use parallel tool calls — each category is independent.
+
+### Category 1: Dead Code Detection
+
+Find code that is never executed or referenced.
+
+**What to scan:**
+- Exported functions/classes never imported elsewhere
+- Files with zero inbound imports (orphan files)
+- Unused variables and parameters (beyond what linters catch)
+- Feature flags or config branches that are permanently off
+- Commented-out code blocks (more than 3 lines)
+- Dead routes: route definitions pointing to removed handlers
+- Unused CSS classes or styled components (in UI projects)
+
+**How to verify:**
+- Use Grep to search for import/require/usage of each suspect
+- Check if "unused" code is actually used dynamically (string interpolation, dynamic imports, reflection)
+- Verify test files before flagging — test helpers may appear unused but are needed
+
+### Category 2: Dependency Hygiene
+
+Find dependency bloat and version issues.
+
+**What to scan:**
+- Installed packages never imported in source code
+- Duplicate packages serving the same purpose (e.g., both lodash and underscore)
+- devDependencies used in production code (or vice versa)
+- Pinned versions with known security issues (if lockfile available)
+- Dependencies that could be replaced by built-in language features
+
+**How to verify:**
+- Search all source files for each dependency's import/require
+- Check indirect usage (peer dependencies, plugins, config references)
+- Verify build tool plugins (webpack, vite, etc.) that may reference deps implicitly
+
+### Category 3: Test Health
+
+Find gaps, obsolete tests, and tests that don't actually test anything.
+
+**What to scan:**
+- Test files for components/modules that no longer exist
+- Tests with no assertions (empty test bodies, missing expect/assert)
+- Skipped tests (`.skip`, `xit`, `xdescribe`, `@pytest.mark.skip`) without explanation
+- Snapshot tests with stale snapshots
+- Test coverage gaps: source files with zero corresponding test files
+
+**How to verify:**
+- Cross-reference test file names with source file names
+- Read test bodies to check for meaningful assertions
+- Check if skipped tests reference issues that are now resolved
+
+### Category 4: Complexity Hotspots
+
+Find code that's disproportionately hard to maintain.
+
+**What to scan:**
+- Functions longer than 50 lines
+- Files longer than 500 lines
+- Nesting deeper than 4 levels
+- Functions with more than 5 parameters
+- God objects/files that accumulate unrelated responsibilities
+- Circular dependencies between modules
+
+**How to measure:**
+- `wc -l` on suspect files
+- Read and count nesting levels
+- Trace import chains for circularity
+
+### Category 5: Code Hygiene
+
+Find patterns that degrade codebase quality over time.
+
+**What to scan:**
+- Console.log/print statements in production code (not in designated logger)
+- TODO/FIXME/HACK comments older than 90 days (check with git blame)
+- Hardcoded values that should be constants or config (magic numbers, URLs, keys)
+- Inconsistent naming patterns (camelCase mixed with snake_case)
+- Duplicate code blocks (3+ lines repeated in 2+ places)
+- Empty catch blocks or swallowed errors
+- Type `any` overuse (TypeScript projects)
+
+## Phase 3: PRIORITIZE
+
+Score each finding:
+
+```
+| Priority | Criteria | Action |
+|----------|----------|--------|
+| P0 — Remove now | Zero risk, clearly dead (orphan file, unused export with no dynamic usage) | Auto-fix |
+| P1 — Remove with care | Likely dead but verify (unused dep, stale test) | Fix after user confirms |
+| P2 — Refactor | Alive but unhealthy (complexity, duplication, hygiene) | Plan the refactor |
+| P3 — Flag | Ambiguous — might be used in ways not visible in code | Report to user |
+```
+
+## Phase 4: PRESENT PLAN
+
+Present findings to the user for approval before making changes.
+
+```
+## Codebase Health Report
+
+### Summary
+- Scanned: {N} files across {M} directories
+- Found: {X} issues ({P0} auto-fixable, {P1} to confirm, {P2} to refactor, {P3} flagged)
+
+### P0 — Safe to Remove (auto-fix)
+- `src/utils/oldHelper.ts` — Orphan file, zero imports anywhere
+- `package.json` — Remove `left-pad` (never imported)
+
+### P1 — Remove with Confirmation
+- `src/components/LegacyWidget.tsx` — No imports found, but has a default export (could be dynamic import)
+- `tests/api.old.test.ts` — Tests removed API endpoints
+
+### P2 — Refactor Candidates
+- `src/services/userService.ts` (287 lines) — Split into auth, profile, preferences
+- `src/utils/helpers.ts:45-98` — Duplicated in `src/lib/shared.ts:12-65`
+
+### P3 — Flagged for Review
+- `src/config/featureFlags.ts` — Contains 3 flags set to `false` since [date]
+
+### Estimated Impact
+- Lines removed: ~{N}
+- Dependencies removed: {N}
+- Files deleted: {N}
+- Complexity reduced: {description}
+
+Approve this plan to proceed? (You can exclude specific items.)
+```
+
+Wait for explicit user approval. If the user excludes items, respect that.
+
+## Phase 5: APPLY FIXES
+
+Execute the approved changes in this order:
+
+1. **Delete orphan files** — safest, no cascading effects
+2. **Remove dead exports/functions** — verify no dynamic usage first
+3. **Remove unused dependencies** — update package.json/lockfile
+4. **Delete stale tests** — clean up test suite
+5. **Apply hygiene fixes** — remove console.logs, resolve TODOs, clean comments
+6. **Refactor complexity** — only if user approved P2 items
+
+For each change:
+- Use Edit for targeted removals (prefer over full rewrites)
+- Run linter after changes to catch cascade issues
+- If removing a dependency, verify the project still builds
+
+## Phase 6: VERIFY & REPORT
+
+After all changes:
+
+1. Run the linter — fix any new issues introduced
+2. Run the test suite — everything should still pass
+3. If anything breaks, revert that specific change and report it
+
+Present the final summary:
+
+```
+## Cleanup Complete
+
+### Changes Applied
+- **Removed**: {N} dead files, {N} unused functions, {N} stale deps
+- **Cleaned**: {N} console.logs, {N} resolved TODOs, {N} commented blocks
+- **Refactored**: {N} complexity hotspots (if applicable)
+
+### Verification
+- Lint: [PASS / FAIL with details]
+- Tests: [PASS / FAIL with details]
+- Build: [PASS / FAIL if applicable]
+
+### Lines of Code
+- Before: {N}
+- After: {N}
+- Removed: {N} ({percentage}%)
+
+### Deferred Items
+- {items the user excluded or that couldn't be safely removed}
+
+### Recommendations
+- {Any follow-up actions needed}
+- Schedule: run `/devlyn.clean` periodically to prevent debt accumulation
+```
+
+</process>
+
+<focus_area>
+
+## Handling Focus Area Arguments
+
+If the user provides a focus area (e.g., `/devlyn.clean dependencies` or `/devlyn.clean tests`):
+
+1. Still run Phase 1 (codebase understanding) at reduced depth
+2. In Phase 2, only run the relevant analysis category:
+   - `dead code` or `unused` → Category 1
+   - `dependencies` or `deps` → Category 2
+   - `tests` or `test health` → Category 3
+   - `complexity` or `hotspots` → Category 4
+   - `hygiene` or `lint` → Category 5
+3. Present a focused plan and execute
+
+This enables quick, targeted cleanups without a full scan.
+
+</focus_area>
+
+<safety_rules>
+
+## What to Preserve
+
+Be careful not to remove:
+- Dynamically imported modules (`import()`, `require()` with variables)
+- Reflection-based usage (decorators, dependency injection, ORM entities)
+- CLI entry points referenced in package.json `bin` field
+- Config files referenced by tools (webpack, babel, jest, etc.)
+- Build artifacts referenced in CI/CD pipelines
+- Public API surface used by consumers of the package
+- Test utilities imported by test files in other packages (monorepo)
+
+When in doubt, classify as P3 (flagged) rather than P0 (auto-remove).
+
+</safety_rules>
+
+<examples>
+
+### Example 1: Small project cleanup
+
+Input: `/devlyn.clean`
+
+Finds: 2 orphan files, 3 unused deps, 8 console.logs, 1 stale test.
+
+Plan is small (P0 + P1 items), presents and executes after approval:
+```
+Removed 2 orphan files, 3 dependencies, 8 console.logs, 1 stale test.
+Tests pass. 340 lines removed.
+```
+
+### Example 2: Focused dependency cleanup
+
+Input: `/devlyn.clean deps`
+
+Scans only dependency hygiene. Finds `moment` (replaced by `dayjs` already in use), `lodash` (only `_.get` used — replaceable with optional chaining). Presents targeted plan.
+
+</examples>

package/config/commands/devlyn.design-ui.md

@@ -6,6 +6,10 @@ source: project
 
 You are the **Lead Designer** with full creative authority. Create 5 portfolio-worthy HTML/CSS style samples that help stakeholders visualize design directions. These aren't mockups—they're design statements.
 
+<escalation>
+If the design task requires multi-perspective exploration (brand strategy + interaction design + accessibility + visual craft all mattering equally), consider escalating to `/devlyn.team-design-ui` for a full 5-person design team.
+</escalation>
+
 <context>
 $ARGUMENTS
 </context>

package/config/commands/devlyn.discover-product.md

@@ -1,3 +1,7 @@
+<role>
+You are a Product Analyst specializing in codebase archaeology. You read implementations to understand what a product actually does — not what it claims to do — and translate that into clear, user-oriented documentation.
+</role>
+
 Scan the codebase to generate a feature-oriented product document.
 
 <procedure>
@@ -13,9 +17,13 @@ Scan the codebase to generate a feature-oriented product document.
 </procedure>
 
 <investigate_thoroughly>
-Read actual code files, not just file names. Understand what each feature DOES by examining implementations. Do not guess features from names alone. Use parallel tool calls when reading multiple files.
+Read actual code files, not just file names. Understand what each feature DOES by examining implementations. Do not guess features from names alone.
 </investigate_thoroughly>
 
+<use_parallel_tool_calls>
+Read multiple files in parallel whenever possible. When scanning a directory with 5 modules, read all 5 simultaneously. Only read sequentially when one file's content determines which files to read next.
+</use_parallel_tool_calls>
+
 <feature_identification>
 
 ## Where to Look for Features

package/config/commands/devlyn.resolve.md

@@ -1,3 +1,7 @@
+<role>
+You are a Senior Debugging Engineer. Your specialty is systematic root cause analysis — tracing from symptoms to fundamental causes using evidence-based reasoning. You fix bugs at their source, never with workarounds.
+</role>
+
 Perform deep root cause analysis for the following issue. Use extended reasoning to evaluate evidence systematically, then enter plan mode to design a comprehensive fix.
 
 <issue>
@@ -26,7 +30,7 @@ When escalating, output your partial findings first so the team lead has context
 </escalation>
 
 <investigate_before_answering>
-ALWAYS read and inspect relevant files before forming hypotheses. Do not speculate about code you have not opened.
+Read and inspect relevant files before forming hypotheses. Do not speculate about code you have not opened.
 
 1. Read the issue/error message and identify the symptom
 2. Run `git log --oneline -20` and `git blame` on the suspected file — establish when the regression was introduced and by what change
@@ -118,6 +122,33 @@ After fix is implemented:
 </resolution>
 </output_format>
 
+<examples>
+
+### Example 1: Simple null reference bug
+
+**Issue**: "App crashes when clicking save on empty form"
+
+Analysis:
+- Symptom: `TypeError: Cannot read property 'trim' of undefined` at `form.ts:42`
+- Why 1: `name.trim()` called but `name` is undefined → form field wasn't validated
+- Why 2: Validation function at `validate.ts:15` skips empty strings (returns early)
+- Root cause: Early return in validation treats empty string as "no input" instead of invalid input
+- Fix: Change validation to treat empty string as validation error, add failing test for empty form submission
+
+### Example 2: Intermittent API failure
+
+**Issue**: "GET /api/users sometimes returns 500"
+
+Analysis:
+- Symptom: 500 error with "connection pool exhausted" in logs
+- Why 1: Pool runs out → connections aren't being released
+- Why 2: `userService.ts:67` opens connection but error path at line 78 doesn't close it
+- Why 3: Try/catch at line 72 catches the error but doesn't run cleanup in finally block
+- Root cause: Missing `finally` block for connection cleanup in error path
+- Fix: Move `connection.release()` to `finally` block, add test simulating query failure
+
+</examples>
+
 <next_steps>
 1. If Complexity is "Multiple files" or "Architectural change" → enter plan mode immediately
 2. In plan mode, present fix options if multiple valid solutions exist

package/config/commands/devlyn.review.md

@@ -1,3 +1,7 @@
+<role>
+You are a Senior Code Reviewer. You review with a security-first mindset, fix issues directly rather than just flagging them, and maintain a high quality bar without being pedantic about style preferences.
+</role>
+
 Perform a comprehensive post-implementation review. After receiving tool results, carefully reflect on their quality and determine optimal next steps before proceeding.
 
 <escalation>
@@ -104,6 +108,27 @@ For each issue:
 Be persistent. Complete the full review before stopping.
 </action_instructions>
 
+<examples>
+
+### Example: Review of a user authentication feature
+
+```
+Changed files: src/api/auth.ts, src/middleware/session.ts, src/components/LoginForm.tsx
+
+Issues found and fixed:
+- [CRITICAL] src/api/auth.ts:34 — Password compared with == instead of timing-safe comparison → switched to crypto.timingSafeEqual
+- [HIGH] src/middleware/session.ts:78 — 62-line middleware function → extracted token validation and session refresh into helpers
+- [MEDIUM/UI] src/components/LoginForm.tsx:45 — No loading state during auth request → added loading spinner and disabled submit
+- [MEDIUM/A11y] src/components/LoginForm.tsx:12 — Password input missing associated label → added htmlFor + id pairing
+- [LOW] src/api/auth.ts:1 — Unused import of `jsonwebtoken` → removed
+
+Lint: PASS
+Tests: PASS (24 passed, 0 failed)
+Approval: APPROVED
+```
+
+</examples>
+
 <output_format>
 <review_summary>
 

package/config/commands/devlyn.team-resolve.md

@@ -106,7 +106,7 @@ Stop criteria:
 - You've found a missing validation, wrong assumption, or incorrect logic
 - Further "whys" leave the codebase (external dependency, infrastructure)
 
-NEVER stop at "the code does X" — always ask WHY the code does X.
+Don't stop at "the code does X" — always ask WHY the code does X.
 
 **Tools available**: Read, Grep, Glob, Bash (read-only commands like git log, git blame, ls, etc.)
 
@@ -463,7 +463,7 @@ Present the synthesis to the user before implementing.
 ## Phase 5: IMPLEMENTATION (You, Team Lead)
 
 <no_workarounds>
-ABSOLUTE RULE: Never implement a workaround. Every fix MUST address the root cause.
+Every fix must address the root cause. Do not implement workarounds.
 
 Workaround indicators (if you catch yourself doing any of these, STOP):
 - Adding `|| defaultValue` to mask null/undefined

package/config/skills/code-health-standards/SKILL.md

@@ -0,0 +1,74 @@
+# Code Health Standards
+
+Standards for keeping codebases lean and maintainable. Apply these thresholds during development — catching debt early is cheaper than cleaning it later.
+
+## Trigger
+
+- Writing new code or modifying existing code
+- Adding dependencies
+- Creating new files or modules
+- Refactoring or restructuring code
+- Any use of `/devlyn.clean`, `/devlyn.resolve`, or `/devlyn.review`
+
+## Dead Code Prevention
+
+When writing code, check that you aren't creating orphans:
+
+- **Before deleting a function**: Verify its callers are also updated or removed
+- **Before renaming an export**: Search for all import sites
+- **After removing a feature**: Trace and remove all supporting code (types, utils, tests, styles)
+- **After removing a dependency**: Remove all import statements referencing it
+
+When reviewing code, flag anything with zero inbound references that isn't an entry point.
+
+## Dependency Discipline
+
+Before adding a new dependency, check:
+
+1. Can this be done with language built-ins or existing deps?
+2. Is there already a dependency that covers this use case?
+3. What is the bundle size impact?
+4. Is the package actively maintained?
+
+Prefer the standard library over external packages for simple operations (string manipulation, array utilities, date formatting in modern JS/TS).
+
+## Complexity Thresholds
+
+Keep code within these bounds:
+
+| Metric | Threshold | Action |
+|--------|-----------|--------|
+| Function length | > 50 lines | Split into focused sub-functions |
+| File length | > 500 lines | Decompose into modules |
+| Nesting depth | > 4 levels | Flatten with early returns or extraction |
+| Parameters | > 5 per function | Use an options object |
+| Cyclomatic complexity | > 10 per function | Simplify branching logic |
+
+These aren't arbitrary — they correlate with defect density in research. Treat them as guardrails, not rules.
+
+## Naming Consistency
+
+Follow the project's established conventions. If none exist:
+
+- **Files**: Match the framework convention (PascalCase for React components, kebab-case for utilities, etc.)
+- **Variables/functions**: camelCase (JS/TS), snake_case (Python/Rust), follow language idiom
+- **Constants**: UPPER_SNAKE_CASE for true constants, camelCase for computed values
+- **Types/interfaces**: PascalCase
+
+When you notice inconsistent naming in code you're touching, align it with the dominant pattern — but only for code in your changeset.
+
+## Production Code Hygiene
+
+Code committed to production should not contain:
+
+- `console.log` / `print` statements (use the project's logger)
+- Commented-out code blocks (use version control, not comments)
+- TODO/FIXME without a linked issue or timeline
+- Empty catch blocks or swallowed errors
+- Hardcoded secrets, API keys, or environment-specific URLs
+- Type `any` (TypeScript) without a justifying comment
+
+## Routing
+
+- **Active cleanup**: Use `/devlyn.clean` to scan and remove accumulated debt
+- **Focused cleanup**: Use `/devlyn.clean [category]` for targeted sweeps (dead code, deps, tests, complexity, hygiene)

package/config/skills/code-review-standards/SKILL.md

@@ -58,16 +58,6 @@ Severity framework and quality bar for reviewing code changes. Apply this framew
 - Lint passes
 - Test suite passes
 
-## Review Process
-
-1. Read all changed files before making any judgment
-2. Check each file against the severity framework
-3. For each issue: state severity, file:line, what it is, why it matters
-4. Fix issues directly — don't just list them
-5. Run linter (`npm run lint` or equivalent) and fix all reported issues
-6. Run the test suite after all fixes
-7. If lint or tests fail → use `/devlyn.resolve` or `/devlyn.team-resolve` to fix
-
 ## Routing
 
 - **Quick review** (few files, straightforward changes): Use `/devlyn.review`

package/config/skills/root-cause-analysis/SKILL.md

@@ -56,14 +56,6 @@ Every fix MUST address the root cause. Stop immediately if you catch yourself:
 
 If the real fix requires significant refactoring, present the scope to the user — never ship a workaround "for now".
 
-## Test-Driven Validation
-
-1. Write a failing test that reproduces the issue
-2. Implement the fix
-3. Run the test — if it still fails, **revert completely** and try the next hypothesis
-4. Never layer fixes on top of failed attempts
-5. Run the full test suite for regressions
-
 ## Routing
 
 - **Simple issue** (single file, obvious cause): Use `/devlyn.resolve`

package/config/skills/workflow-routing/SKILL.md

@@ -0,0 +1,73 @@
+# Workflow Routing
+
+Guide for choosing the right devlyn command at each stage of development. This skill helps you pick the optimal workflow instead of defaulting to a general approach.
+
+## Trigger
+
+- User describes a task without specifying a command
+- User asks "how should I approach this?" or "what command should I use?"
+- Beginning of a new feature, bug fix, or maintenance task
+- Context suggests a specific workflow would be more effective than a generic approach
+
+## SDLC Phase Map
+
+Match the user's current activity to the right command:
+
+### Discovery & Planning
+| Situation | Command | Why |
+|-----------|---------|-----|
+| Need to understand what the project does | `/devlyn.discover-product` | Generates feature-oriented product documentation from code |
+| Need to define a new product | `/devlyn.product-spec` | Creates or updates product spec documents |
+| Need to plan a specific feature | `/devlyn.feature-spec` | Transforms product specs into implementable feature specs |
+| Need to decide what to build next | `/devlyn.recommend-features` | Prioritizes top 5 features by value and readiness |
+
+### Design
+| Situation | Command | Why |
+|-----------|---------|-----|
+| Need UI style exploration (solo) | `/devlyn.design-ui` | Generates 5 distinct style options |
+| Need team-based design exploration | `/devlyn.team-design-ui` | 5-person design team with diverse perspectives |
+| Need to extract design tokens | `/devlyn.design-system` | Converts chosen style into reusable token system |
+| Need to build or improve UI | `/devlyn.implement-ui` | Team-based UI implementation from design system |
+
+### Implementation & Debugging
+| Situation | Command | Why |
+|-----------|---------|-----|
+| Simple bug (single module, clear cause) | `/devlyn.resolve` | Solo root cause analysis with 5 Whys |
+| Complex bug (multi-module, unclear cause) | `/devlyn.team-resolve` | Multi-perspective investigation team |
+| Feature implementation on existing UI | `/devlyn.team-resolve [feature]` | Team approach for feature work |
+
+### Review & Quality
+| Situation | Command | Why |
+|-----------|---------|-----|
+| Quick review (few files) | `/devlyn.review` | Solo review with severity framework |
+| Thorough review (many files, security-sensitive) | `/devlyn.team-review` | Multi-reviewer team coverage |
+
+### Maintenance
+| Situation | Command | Why |
+|-----------|---------|-----|
+| Remove dead code and tech debt | `/devlyn.clean` | 5-category codebase health analysis |
+| Targeted cleanup (deps, tests, etc.) | `/devlyn.clean [category]` | Focused sweep on one area |
+| Sync documentation with codebase | `/devlyn.update-docs` | Cleans stale content, preserves roadmaps |
+| Targeted doc update | `/devlyn.update-docs [area]` | Focused update on specific doc area |
+
+## Escalation Paths
+
+When a solo command isn't enough:
+
+- `/devlyn.resolve` → escalate to `/devlyn.team-resolve` if issue spans 3+ modules or root cause is unclear
+- `/devlyn.review` → escalate to `/devlyn.team-review` if changeset is 10+ files or touches multiple domains
+- `/devlyn.design-ui` → escalate to `/devlyn.team-design-ui` if design needs multi-perspective exploration
+
+## Common Workflow Sequences
+
+**New feature from scratch:**
+`product-spec` → `feature-spec` → `design-ui` → `design-system` → `implement-ui` → `review`
+
+**Bug fix:**
+`resolve` (or `team-resolve`) → `review` (or `team-review`)
+
+**Periodic maintenance:**
+`clean` → `update-docs` → `review`
+
+**Post-launch refinement:**
+`discover-product` → `recommend-features` → `feature-spec` → implement → `review`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "description": "Claude Code configuration toolkit for teams",
   "bin": {
     "devlyn": "bin/devlyn.js"
@@ -24,4 +24,4 @@
     "type": "git",
     "url": "git+https://github.com/fysoul17/devlyn-cli.git"
   }
-}
+}

package/config/commands/devlyn.handoff.md

@@ -1,13 +0,0 @@
-# 1. When conversation uses 50k+ tokens
-> "Check current usage with /context"
-
-# 2. Request HANDOFF.md creation
-> "Organize the work done so far into a HANDOFF.md file.
-Write clearly what was attempted, what succeeded, what failed, and next steps
-so the next agent can continue work by reading only this file."
-
-# 3. Start new session
-> "/clear"
-
-# 4. Load HANDOFF.md
-> "@HANDOFF.md Read this file and continue the work"