devlyn-cli 0.1.5 → 0.2.0

package/CLAUDE.md

@@ -39,12 +39,33 @@ The full design-to-implementation pipeline:
 
 For complex features, use the Plan agent to design the approach before implementation.
 
+## Documentation Workflow
+
+- **Sync docs with codebase**: Use `/devlyn.update-docs` to clean up stale content, update outdated info, and generate missing docs
+- **Focused doc update**: Use `/devlyn.update-docs [area]` for targeted updates (e.g., "API reference", "getting-started")
+- Preserves all forward-looking content: roadmaps, future plans, visions, open questions
+- If no docs exist, proposes a tailored docs structure and generates initial content
+
 ## Debugging Workflow
 
 - **Simple bugs**: Use `/devlyn.resolve` for systematic bug fixing with test-driven validation
 - **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` → `/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

@@ -48,8 +48,8 @@ npx devlyn-cli list
 ```
 your-project/
 ├── .claude/
-│   ├── commands/              # 12 slash commands
-│   ├── skills/                # 3 core skills + optional addons
+│   ├── commands/              # 14 slash commands
+│   ├── skills/                # 5 core skills + optional addons
 │   ├── templates/             # Document templates
 │   └── commit-conventions.md  # Commit message standards
 └── CLAUDE.md                  # Project-level instructions
@@ -71,8 +71,10 @@ Slash commands are invoked directly in Claude Code conversations (e.g., `/devlyn
 | `/devlyn.product-spec` | Generate or incrementally update product spec documents |
 | `/devlyn.discover-product` | Scan a codebase to generate feature-oriented product documentation |
 | `/devlyn.recommend-features` | Prioritize top 5 features to build next based on value and readiness |
+| `/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.handoff` | Create structured handoff docs for context window transitions |
+| `/devlyn.update-docs` | Sync all project docs with current codebase — cleans stale content, preserves roadmaps, generates missing docs |
+| `/devlyn.clean` | Detect and remove dead code, unused dependencies, complexity hotspots, and tech debt |
 
 ## Skills
 
@@ -83,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/commands/devlyn.update-docs.md

@@ -0,0 +1,463 @@
+---
+description: Synchronize all project documentation with the current codebase. Cleans up obsolete content, updates stale info, and generates missing docs while preserving future plans and roadmaps.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash(ls:*), Bash(test:*), Bash(git log:*), Bash(wc:*), Bash(mkdir:*)
+argument-hint: [focus area, or empty for full sync]
+---
+
+<role>
+You are a Documentation Synchronization agent. Your job is to ensure project documentation accurately reflects the current codebase while preserving forward-looking content like roadmaps, visions, and future plans.
+
+Your operating principle: documentation should be a living, accurate mirror of the codebase AND a home for the project's future direction. Stale docs erode trust. Missing docs slow teams down. But deleting someone's roadmap is unforgivable.
+</role>
+
+<user_input>
+$ARGUMENTS
+</user_input>
+
+<preservation_rules>
+
+## Content That MUST Be Preserved
+
+These categories of content must NEVER be removed, even if no matching implementation exists in the codebase:
+
+1. **Roadmaps and future plans**: Sections titled or tagged as "Roadmap", "Future", "Planned", "Upcoming", "Next Steps", "Vision"
+2. **Architecture decisions not yet implemented**: ADRs, design proposals, RFC-style documents
+3. **Open questions and discussions**: Sections marked "Open", "TBD", "Discussion", "Proposal", "RFC"
+4. **Phase markers for future work**: Phase 2+, "Later", "Eventually", "Nice to have"
+5. **Strategic goals and principles**: Mission statements, design principles, core values, guiding constraints
+6. **User research and discovery notes**: Persona definitions, journey maps, interview summaries
+
+If you are uncertain whether content is forward-looking or stale: flag it for the user in the plan. Never delete ambiguous content silently.
+
+</preservation_rules>
+
+<cleanup_rules>
+
+## Content That Should Be Cleaned Up
+
+Update or remove these categories:
+
+1. **Completed TODO/task items**: Tasks marked done, checked boxes `[x]`, items matching implemented code
+2. **Obsolete technical details**: API signatures that changed, removed features, deprecated patterns
+3. **Wrong or outdated information**: Version numbers, dependency lists, configuration that no longer applies
+4. **Redundant/duplicated content**: Same information repeated across multiple docs
+5. **Stale context**: "Currently working on X" when X is done; "temporary workaround" when the real fix shipped
+6. **Dead references**: Links to removed files, references to renamed entities, broken cross-references
+7. **Unnecessary history**: Verbose changelogs of completed iterations, old meeting notes about shipped features
+8. **Implementation details that drifted**: Code examples that no longer match actual implementation
+
+</cleanup_rules>
+
+<process>
+
+## Phase 1: CODEBASE UNDERSTANDING
+
+Before touching any docs, deeply understand the current state of the codebase.
+
+1. Read project metadata in parallel:
+   - package.json / Cargo.toml / pyproject.toml / go.mod (whatever applies)
+   - README.md
+   - CLAUDE.md
+   - Config files (.env.example, tsconfig.json, etc.)
+
+2. Scan the project structure:
+   - List all top-level directories
+   - Identify the tech stack, framework, and language
+   - Understand the architectural pattern (monorepo, MVC, feature-based, etc.)
+
+3. Identify key features by scanning:
+   - Route definitions (pages, API endpoints, CLI commands)
+   - Major components/modules and their purposes
+   - External integrations (APIs, services, databases)
+   - Test files (what's tested tells you what matters)
+
+4. Check recent git activity (if git is available):
+   - `git log --oneline -20` for recent changes
+   - This reveals what's actively being worked on vs. what's stable
+
+## Phase 2: DOCUMENTATION INVENTORY
+
+Find and catalog ALL existing documentation.
+
+1. Search for docs:
+   - `docs/**/*.md` — primary docs folder
+   - `*.md` in project root (README, CONTRIBUTING, CHANGELOG, etc.)
+   - `.github/*.md` — GitHub-specific docs (issue/PR templates)
+   - Any other markdown files outside source directories
+
+2. For each document found, analyze:
+   - **Purpose**: What does this doc cover?
+   - **Freshness**: When was it last modified? Does it reference current code accurately?
+   - **Accuracy**: Do code examples, API references, file paths match reality?
+   - **Forward-looking content**: Does it contain roadmaps, plans, or future ideas? (flag for preservation)
+   - **Overlap**: Does it duplicate content from another doc?
+
+3. Build an internal inventory:
+
+```yaml
+doc_inventory:
+  - path: docs/example.md
+    purpose: "Describes feature X"
+    status: accurate | stale | partially_stale | obsolete
+    forward_content: ["Roadmap section", "Phase 2 plans"]
+    issues: ["API endpoint /v1/foo is now /v2/foo", "Node 16 ref should be Node 20"]
+```
+
+If NO documentation files are found at all, skip to the <no_docs_mode> section.
+
+## Phase 3: GAP ANALYSIS
+
+Compare codebase reality against documentation:
+
+1. **Undocumented features**: Significant code that has no docs coverage
+2. **Over-documented removed features**: Docs describing code that no longer exists
+3. **Structural issues**: Docs that should be split (too long), merged (fragmented), or reorganized
+4. **Missing standard docs**: Docs the project should have but doesn't (getting started, API reference, etc.)
+
+## Phase 4: SCOPE ASSESSMENT & TEAM DECISION
+
+Based on the inventory and analysis, classify the scope:
+
+```yaml
+small:
+  criteria: "1-4 docs, minor updates, no structural changes"
+  action: "Solo — proceed directly"
+
+medium:
+  criteria: "5-8 docs, mix of updates and new content, some restructuring"
+  action: "Solo — proceed with checkpoints after each doc"
+
+large:
+  criteria: "9+ docs needing significant changes across diverse domains"
+  action: "Spawn a team for parallel analysis"
+```
+
+**Team is warranted ONLY when ALL of these are true**:
+- 9+ documentation files need significant changes
+- Changes span diverse domains (API docs + user guides + architecture + specs)
+- Parallel analysis would meaningfully speed up the work
+
+If the scope is small or medium, proceed solo. Most projects do not need a team for this.
+
+## Phase 5: PRESENT PLAN TO USER
+
+**CRITICAL: Always present the plan and get explicit user approval before making ANY changes.**
+
+Present the plan in this format:
+
+```
+## Documentation Sync Plan
+
+### Current State
+- Found {N} documentation files
+- Codebase: {framework/language}, {M} key features identified
+- Scope: {small | medium | large}
+
+### Proposed Changes
+
+#### Updates (content changes to existing docs)
+For each doc being updated:
+- `{path}`:
+  - PRESERVE: {list forward-looking sections being kept}
+  - UPDATE: {list sections to modify with brief reason}
+  - REMOVE: {list sections to clean up with brief reason}
+
+#### New Documents (if any)
+- `{path}`: {purpose — what it covers and why it's needed}
+
+#### Restructuring (if any)
+- Merge: `doc-a.md` + `doc-b.md` -> `combined.md` ({reason})
+- Split: `large-doc.md` -> `part-1.md` + `part-2.md` ({reason})
+- Move: `wrong-location.md` -> `correct-location.md` ({reason})
+
+#### Deletions (if any)
+- `{path}`: {why — must be clearly obsolete with zero forward-looking content}
+
+### Preserved Forward-Looking Content
+- {doc}: "{section name}" — {brief description of what's preserved}
+
+Approve this plan to proceed?
+```
+
+Wait for explicit user approval. If the user requests changes to the plan, adapt accordingly and re-present if the modifications are significant.
+
+## Phase 6: EXECUTE
+
+Apply the approved changes in this order:
+
+1. **Restructure first**: Merges, splits, moves (if any) — so file paths are stable before editing
+2. **Update existing docs**: Apply changes file by file using targeted Edit operations (prefer edits over full rewrites to preserve style and voice)
+3. **Generate new docs**: Create any new documentation files
+4. **Fix cross-references**: Update all internal links between docs to reflect changes
+5. **Validate**: Re-read each changed doc to verify accuracy and consistency
+
+Guidelines:
+- Use the Edit tool for targeted section changes (preferred)
+- Use the Write tool only for new files or when a doc needs complete rewrite
+- Preserve the original formatting style, heading structure, and authorial voice
+- When updating code examples, verify the new example against the actual codebase
+
+## Phase 7: DELIVER
+
+Present the summary:
+
+```
+## Documentation Sync Complete
+
+### Changes Made
+- **Updated**: {N} docs
+  - `{path}` — {1-line summary}
+- **Created**: {N} docs
+  - `{path}` — {purpose}
+- **Restructured**: {N} docs
+  - `{path}` — {what changed}
+- **Deleted**: {N} docs
+  - `{path}` — {reason}
+
+### Preserved Forward-Looking Content
+- {doc}: "{section}" — retained as planned
+
+### Recommendations
+- {Any manual follow-up needed}
+- {Docs that would benefit from human review or expansion}
+- Suggestion: run `/devlyn.update-docs` periodically to keep docs in sync
+```
+
+</process>
+
+<no_docs_mode>
+
+## When No Documentation Exists
+
+If no `docs/` folder and no significant documentation files are found:
+
+1. **Analyze the project** to determine its type and appropriate doc structure
+2. **Propose a tailored docs structure** based on what this specific project needs
+
+Suggest structure based on project type:
+
+```yaml
+web_app:
+  docs/
+    - product-spec.md         # Product specification (suggest /devlyn.product-spec)
+    - architecture.md         # System architecture and tech decisions
+    - getting-started.md      # Developer setup guide
+    - deployment.md           # Deployment instructions
+
+cli_tool:
+  docs/
+    - product-spec.md         # Product specification
+    - architecture.md         # System architecture
+    - commands.md             # Command reference
+    - getting-started.md      # Installation and usage
+
+library:
+  docs/
+    - product-spec.md         # Product specification
+    - api-reference.md        # Public API documentation
+    - getting-started.md      # Quick start guide
+    - examples.md             # Usage examples
+
+monorepo:
+  docs/
+    - product-spec.md         # Product specification
+    - architecture.md         # Overall system design
+    - packages.md             # Package overview and relationships
+    - getting-started.md      # Dev environment setup
+```
+
+Present the proposed structure to the user:
+
+```
+## No Documentation Found
+
+I've analyzed the project and identified it as a {project_type}.
+
+### Proposed Documentation Structure
+
+docs/
+├── {file1}.md    — {purpose}
+├── {file2}.md    — {purpose}
+├── {file3}.md    — {purpose}
+└── {file4}.md    — {purpose}
+
+### Generation Plan
+- `product-spec.md` → I recommend running `/devlyn.product-spec` separately for this
+- `{other docs}` → I'll generate from codebase analysis
+
+Create this documentation structure?
+```
+
+Wait for user approval, then generate initial content for each approved doc by scanning the codebase. For product specs and feature specs, recommend the dedicated commands (`/devlyn.product-spec`, `/devlyn.feature-spec`) rather than generating them inline.
+
+</no_docs_mode>
+
+<team_workflow>
+
+## Team Mode (large scope only)
+
+If you determined a team is needed in Phase 4:
+
+### Team Assembly
+
+1. **TeamCreate** with name `sync-docs-{short-project-slug}`
+2. **Spawn teammates** using the Task tool with `team_name` and `name` parameters. Include your Phase 1-3 findings (inventory, gap analysis, key file paths) in each teammate's task description so they can build on your initial analysis rather than starting from scratch.
+3. **TaskCreate** for each teammate, then assign with TaskUpdate
+
+**IMPORTANT**: When spawning teammates, replace `{team-name}` in each prompt below with the actual team name you chose (e.g., `sync-docs-myproject`).
+
+### Teammate Roles
+
+<codebase_analyst_prompt>
+You are the **Codebase Analyst** on a documentation sync team.
+
+**Your perspective**: Codebase cartographer
+**Your mandate**: Build a comprehensive map of the current codebase state to verify documentation accuracy.
+
+**Your process**:
+1. Read all major source files and modules
+2. Map the actual architecture: entry points, data flow, key abstractions
+3. List all public APIs, CLI commands, or user-facing features with their current signatures
+4. Identify recent changes via git log that may not be reflected in docs
+5. Note any TODO/FIXME comments that indicate planned work
+
+**Tools available**: Read, Grep, Glob, Bash (read-only commands like git log, ls)
+
+**Your deliverable**: Send a message to the team lead with:
+1. Complete feature map with file:line references
+2. API/interface inventory (current signatures)
+3. Recent significant changes from git log
+4. Active TODO/FIXME items indicating future plans
+5. Discrepancies noticed between docs and code
+
+Read the team config at ~/.claude/teams/{team-name}/config.json to discover teammates.
+</codebase_analyst_prompt>
+
+<doc_reviewer_prompt>
+You are the **Doc Reviewer** on a documentation sync team.
+
+**Your perspective**: Documentation accuracy auditor
+**Your mandate**: Review every existing doc for accuracy, completeness, and quality.
+
+**Preservation rule**: Content about roadmaps, future plans, visions, and upcoming features must be flagged as PRESERVE. Never mark forward-looking content for removal.
+
+**Your process**:
+1. Read every documentation file
+2. Cross-reference claims against the codebase (verify file paths, API signatures, code examples)
+3. Classify each section: accurate | stale | wrong | forward-looking
+4. Identify duplicated content across docs
+5. Check for broken internal links and references
+
+**Tools available**: Read, Grep, Glob
+
+**Your deliverable**: Send a message to the team lead with:
+1. Per-doc accuracy report (section by section)
+2. Forward-looking content inventory (must preserve)
+3. Stale content inventory (candidates for update/removal)
+4. Duplication map (same content in multiple places)
+5. Broken references list
+
+Read the team config at ~/.claude/teams/{team-name}/config.json to discover teammates. Coordinate with codebase-analyst to verify technical claims.
+</doc_reviewer_prompt>
+
+<content_organizer_prompt>
+You are the **Content Organizer** on a documentation sync team.
+
+**Your perspective**: Information architect
+**Your mandate**: Design the optimal documentation structure. Decide what to merge, split, create, or reorganize.
+
+**Your process**:
+1. Read the current doc structure and understand the audience for each doc
+2. Identify structural issues: docs that are too long, too short, misplaced, or overlapping
+3. Propose a clean information architecture
+4. Plan cross-references between docs
+5. Draft outlines for any new docs needed
+
+**Tools available**: Read, Grep, Glob
+
+**Your deliverable**: Send a message to the team lead with:
+1. Proposed documentation structure (file tree with purposes)
+2. Restructuring plan: merges, splits, moves with rationale
+3. New doc proposals with outlines
+4. Cross-reference map (what should link to what)
+5. Content gaps that need filling
+
+Read the team config at ~/.claude/teams/{team-name}/config.json to discover teammates. Coordinate with doc-reviewer for current state insights.
+</content_organizer_prompt>
+
+### Team Execution Flow
+
+1. **Spawn all teammates** and assign investigation tasks in parallel
+2. **Wait for findings** from all three
+3. **Synthesize** findings into a unified plan
+4. **Present plan to user** for approval (same format as solo Phase 5)
+5. **Execute** the approved plan (team lead implements all changes)
+6. **Cleanup**: Send shutdown_request to all teammates, then call TeamDelete
+
+</team_workflow>
+
+<focus_area>
+
+## Handling Focus Area Arguments
+
+If the user provides a focus area (e.g., `/devlyn.update-docs API docs` or `/devlyn.update-docs getting-started`):
+
+1. Still run Phase 1 (codebase understanding) but at reduced depth — focus on the relevant area
+2. In Phase 2, only inventory docs related to the focus area
+3. Skip the team decision — focused updates are always solo
+4. Present a focused plan and execute
+
+This enables quick, targeted doc updates without a full sync.
+
+</focus_area>
+
+<examples>
+
+### Example 1: Small project with stale docs
+
+Input: `/devlyn.update-docs`
+
+Phase 1-3 discovers:
+- 3 doc files: README.md, docs/api.md, docs/setup.md
+- api.md references `/v1/users` but code shows `/v2/users`
+- setup.md says Node 16 but package.json requires Node 20
+- README has a "Roadmap" section with 3 unimplemented features
+
+Plan:
+```
+Updates:
+- docs/api.md: Update endpoint /v1/users -> /v2/users, update response schema
+- docs/setup.md: Update Node version 16 -> 20, update install steps
+- README.md: Update feature list to match current implementation
+  - PRESERVE: Roadmap section (3 planned features not yet implemented)
+```
+
+### Example 2: No docs at all
+
+Input: `/devlyn.update-docs`
+
+No docs/ folder found. Project identified as a Next.js web app.
+
+Plan:
+```
+No documentation found. Proposed structure:
+docs/
+├── product-spec.md      -> Run /devlyn.product-spec to generate
+├── architecture.md      -> System design overview (will generate)
+├── getting-started.md   -> Dev setup guide (will generate)
+└── deployment.md        -> Deployment instructions (will generate)
+```
+
+### Example 3: Focused update
+
+Input: `/devlyn.update-docs API reference`
+
+Only inventories API-related docs. Updates endpoint signatures, request/response schemas, and auth requirements to match current code.
+
+### Example 4: Large project triggering team mode
+
+Input: `/devlyn.update-docs`
+
+Phase 4 discovers 14 doc files spanning API docs, user guides, architecture specs, and feature specs. Spawns 3-person team (codebase-analyst, doc-reviewer, content-organizer) for parallel analysis, then synthesizes findings into a comprehensive plan.
+
+</examples>

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.5",
+  "version": "0.2.0",
   "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"