@allthingsclaude/blueprints 0.2.0 → 0.3.0-beta.10

package/content/commands/cleanup.md

@@ -4,18 +4,20 @@ argument-hint: [optional: "imports" | "dead-code" | "types" | "todos" | focus ar
 author: "@markoradak"
 ---
 
-# Code Cleanup Assistant
+# Code Cleanup
 
-I'll help identify and clean up dead code, unused imports, and technical debt in your codebase.
+I'll scan your codebase for dead code, unused imports, and technical debt.
+
+> **When to use**: You want to remove things that shouldn't be there (unused imports, dead exports, stale TODOs, console.logs). Use `/dry` to consolidate duplicated code, `/refactor` for structural changes, or `/audit` to review changes before committing.
 
 ## Current State
 
 **Working Directory**: !`pwd`
 
-**Branch**: !`git branch --show-current`
+**Branch**: !`git branch --show-current 2>/dev/null || echo "Not a git repository"`
 
 **Files to Analyze**:
-!`find src -name "*.ts" -o -name "*.tsx" 2>/dev/null | wc -l` TypeScript files
+!`find . -maxdepth 5 -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" 2>/dev/null | grep -v node_modules | wc -l` source files
 
 ---
 
@@ -25,302 +27,13 @@ $ARGUMENTS
 
 ---
 
-## Cleanup Workflow
-
-Based on the arguments, I'll focus on specific cleanup tasks:
-
-### If "imports" or no argument:
-- Find and remove unused imports
-- Organize import order
-- Remove duplicate imports
-
-### If "dead-code":
-- Find unreferenced exports
-- Identify unused functions/components
-- Detect unreachable code
-
-### If "types":
-- Audit `any` usage
-- Find implicit any
-- Identify redundant type assertions
-
-### If "todos":
-- Inventory all TODO/FIXME/HACK comments
-- Categorize by priority
-- Suggest which to address or remove
-
-### If specific file/folder provided:
-- Deep cleanup of that area only
-
----
-
-## Cleanup Categories
-
-### 1. Unused Imports
-
-**Detection**:
-```bash
-# ESLint can find these
-pnpm eslint src --rule '@typescript-eslint/no-unused-vars: error' --format compact 2>&1 | grep "no-unused-vars"
-
-# Or check specific file
-grep -E "^import" path/to/file.ts
-```
-
-**Cleanup Strategy**:
-- Remove imports not referenced in the file
-- Remove type-only imports if types aren't used
-- Consolidate multiple imports from same module
-
-### 2. Dead Code
-
-**Detection Patterns**:
-
-**Unreferenced Exports**:
-```bash
-# Find all exports
-grep -rn "export " src/ --include="*.ts" --include="*.tsx"
-
-# Check if each is imported anywhere
-grep -rn "import.*{.*ExportName" src/
-```
-
-**Unused Functions**:
-- Functions defined but never called
-- Event handlers attached to removed elements
-- Utility functions from old features
-
-**Unreachable Code**:
-- Code after return/throw statements
-- Conditions that can never be true
-- Catch blocks for errors that can't occur
-
-### 3. Type Cleanup
-
-**`any` Audit**:
-```bash
-# Find explicit any
-grep -rn ": any" src/ --include="*.ts" --include="*.tsx"
-
-# Find any in function parameters
-grep -rn "(.*any.*)" src/ --include="*.ts"
-```
-
-**Categories**:
-- **Justified**: External library types, truly dynamic data
-- **Lazy**: Should be properly typed
-- **Accidental**: Implicit any from missing types
-
-### 4. TODO/FIXME Inventory
-
-**Detection**:
-```bash
-# Find all TODOs
-grep -rn "TODO\|FIXME\|HACK\|XXX" src/ --include="*.ts" --include="*.tsx"
-```
-
-**Categories**:
-- **Stale**: Old TODOs that are no longer relevant
-- **Completed**: Work is done but comment remains
-- **Valid**: Still needs to be done
-- **Won't Do**: Decided against implementing
-
-### 5. Console Statements
-
-**Detection**:
-```bash
-# Find console.log/warn/error
-grep -rn "console\." src/ --include="*.ts" --include="*.tsx"
-```
-
-**Categories**:
-- **Debug**: Should be removed
-- **Intentional**: Error logging, should use proper logger
-- **Temporary**: Left from debugging session
-
-### 6. Commented Code
-
-**Detection**:
-- Large blocks of commented-out code
-- Commented function definitions
-- "Old" or "backup" comments
-
-**Policy**:
-- If it's in git history, delete it
-- If it might be needed, create a branch
-- Never commit commented-out code
-
----
-
-## Cleanup Report Format
-
-```markdown
-# Cleanup Report
-
-**Scanned**: [X] files in [path]
-**Date**: [timestamp]
-**Focus**: [area or "all"]
-
----
-
-## Summary
-
-| Category | Found | Auto-fixable | Manual Review |
-|----------|-------|--------------|---------------|
-| Unused Imports | X | X | 0 |
-| Dead Code | X | 0 | X |
-| `any` Types | X | 0 | X |
-| TODOs | X | N/A | X |
-| Console Statements | X | X | 0 |
-| Commented Code | X | X | 0 |
-
-**Estimated Impact**: -[X] lines of code
-
----
-
-## Unused Imports
-
-### `src/components/Example.tsx`
-
-**Remove**:
-```typescript
-// Line 3: unused
-import { unusedFunction } from '@/lib/utils'
-
-// Line 5: only 'used' is used, remove 'unused'
-import { used, unused } from '@/lib/helpers'
-```
-
-**After**:
-```typescript
-import { used } from '@/lib/helpers'
-```
-
----
-
-## Dead Code
-
-### Unreferenced Exports
-
-| Export | File | Last Modified | Recommendation |
-|--------|------|---------------|----------------|
-| `oldHelper` | `src/lib/utils.ts:45` | 3 months ago | Remove |
-| `deprecatedFn` | `src/lib/api.ts:123` | 6 months ago | Remove |
-
-### Unused Functions
-
-**`src/lib/helpers.ts:78`** - `formatOldDate()`
-- Not imported anywhere
-- Last modified: [date]
-- **Recommendation**: Remove
-
----
-
-## Type Issues
-
-### `any` Usage
-
-| Location | Context | Recommendation |
-|----------|---------|----------------|
-| `src/api/route.ts:23` | API response | Type as `ApiResponse` |
-| `src/utils/parse.ts:45` | JSON parse | Use `unknown` + validation |
-| `src/lib/external.ts:12` | 3rd party | Justified - add comment |
-
----
-
-## TODO Inventory
-
-### Stale (Remove)
-
-- `src/old.ts:45`: "TODO: refactor this" (file deleted 2 months ago)
-- `src/api.ts:23`: "FIXME: temporary" (been there 6 months)
-
-### Valid (Keep/Address)
-
-- `src/auth.ts:89`: "TODO: add rate limiting" - Still needed
-- `src/db.ts:34`: "FIXME: optimize query" - Performance issue
-
-### Completed (Remove)
-
-- `src/user.ts:56`: "TODO: add validation" - Validation exists
-
----
-
-## Console Statements
-
-| Location | Type | Action |
-|----------|------|--------|
-| `src/debug.ts:12` | `console.log` | Remove (debug) |
-| `src/api.ts:45` | `console.error` | Replace with logger |
-
----
-
-## Commented Code
+## Launching Cleanup Agent
 
-| Location | Lines | Age | Action |
-|----------|-------|-----|--------|
-| `src/old.tsx:34-56` | 22 | 4 months | Remove |
-| `src/utils.ts:78-89` | 11 | 2 months | Remove |
-
----
-
-## Recommended Actions
-
-### Auto-fix (Safe)
-
-These can be automatically cleaned up:
-
-1. [ ] Remove unused imports
-2. [ ] Remove console.log statements
-3. [ ] Remove commented-out code
-
-Run: "Would you like me to auto-fix these?"
-
-### Manual Review Required
-
-These need human decision:
-
-1. [ ] Review dead code exports before removal
-2. [ ] Decide on TODO items
-3. [ ] Type the `any` usages appropriately
-
----
-
-## Next Steps
-
-1. Review this report
-2. Approve auto-fixes
-3. Address manual review items
-4. Run `pnpm typecheck && pnpm lint` to verify
-5. Commit cleanup: `git commit -m "chore: code cleanup"`
-```
-
----
-
-## Auto-Fix Capabilities
-
-When user approves, I can automatically:
-
-- **Remove unused imports**: Edit files to remove
-- **Remove console statements**: Edit to remove (except console.error in catch blocks)
-- **Remove commented code**: Edit to remove blocks
-- **Organize imports**: Sort and group imports
-
-I will NOT automatically:
-- Remove functions (might have dynamic usage)
-- Change `any` types (needs proper typing)
-- Remove TODOs (needs human decision)
-- Remove exports (might be used externally)
-
----
-
-## Safety Guidelines
-
-1. **Always validate after cleanup**: Run typecheck and lint
-2. **Review before committing**: Show git diff
-3. **Don't break functionality**: When in doubt, leave it
-4. **Track what was removed**: Clear commit message
-
----
+The cleanup agent will:
+- Detect your toolchain (package manager, available scripts)
+- Scan for unused imports, dead code, `any` types, stale TODOs, console statements, and commented-out code
+- Generate a structured report with file:line references
+- Offer auto-fix for safe changes (with your approval)
+- Validate that nothing breaks after cleanup
 
-Begin cleanup analysis based on the focus area provided. Use Grep to find patterns, Read to analyze context, and Edit to apply fixes (with user approval).
+Use the Task tool to launch the cleanup agent (subagent_type="cleanup") with the focus area and any additional context from arguments.

package/content/commands/commit.md

@@ -0,0 +1,45 @@
+---
+description: Create a well-crafted git commit from your current changes
+argument-hint: [optional: commit message hint or scope]
+author: "@markoradak"
+---
+
+# Commit Changes
+
+I'll analyze your changes and create a clean, well-structured git commit.
+
+> **When to use**: You have changes ready to commit and want a good commit message without the full session finalization. Use `/finalize` when closing out a work session with plan updates and phase summaries. Use `/audit` to review changes before committing.
+
+## Current State
+
+**Working Directory**: !`pwd`
+
+**Branch**: !`git branch --show-current 2>/dev/null || echo "Not a git repository"`
+
+**Status**:
+!`git status --short`
+
+**Changes Summary**:
+!`git diff --stat`
+
+---
+
+## Context
+
+$ARGUMENTS
+
+---
+
+## Launching Commit Agent
+
+The commit agent will:
+- Review all staged and unstaged changes
+- Understand the intent and scope of the changes
+- Determine the appropriate commit type (`feat`, `fix`, `refactor`, etc.)
+- Draft a concise, well-formatted commit message
+- Stage the relevant files and create the commit
+- Verify the commit was created successfully
+
+**This will create a git commit.** The agent will show you the proposed message before committing.
+
+Use the Task tool to launch the commit agent (subagent_type="commit") with any additional context from arguments.

package/content/commands/critique.md

@@ -1,5 +1,6 @@
 ---
 description: Critique Mode
+argument-hint: [optional: code, design, or approach to critique]
 author: "@markoradak"
 ---
 
@@ -31,4 +32,10 @@ You are now in "CRITIQUE" mode. Provide direct, unfiltered feedback without suga
 - Unrealistic expectations or timelines
 - Missing critical considerations
 
+## Scope
+
+This mode applies to the current task or topic. Once the critique is delivered, normal conversation resumes.
+
+---
+
 $ARGUMENTS

package/content/commands/debug.md

@@ -12,7 +12,7 @@ I'll systematically investigate and diagnose the issue you're experiencing.
 
 **Working Directory**: !`pwd`
 
-**Branch**: !`git branch --show-current`
+**Branch**: !`git branch --show-current 2>/dev/null || echo "Not a git repository"`
 
 **Recent Changes** (potential cause):
 !`git log --oneline -5`
@@ -28,256 +28,14 @@ $ARGUMENTS
 
 ---
 
-## Debugging Methodology
+## Launching Debug Agent
 
-I'll follow a systematic approach to diagnose this issue:
+The debug agent will follow a systematic 4-phase methodology:
+1. **Reproduce & Understand** — Clarify the issue, gather context
+2. **Isolate the Problem** — Narrow scope, trace data flow
+3. **Root Cause Analysis** — Identify candidates, verify hypothesis
+4. **Resolution** — Develop fix, suggest prevention
 
-### Phase 1: Reproduce & Understand
+It will produce a structured diagnosis report with root cause, investigation trail, recommended fixes, and verification steps.
 
-1. **Clarify the Issue**
-   - What is the expected behavior?
-   - What is the actual behavior?
-   - When did this start happening?
-   - Is it reproducible consistently?
-
-2. **Gather Context**
-   - Check error messages and stack traces
-   - Review relevant logs
-   - Identify affected files/components
-
-### Phase 2: Isolate the Problem
-
-3. **Narrow Down the Scope**
-   - Which layer is the issue in? (UI, API, DB, external service)
-   - Is it environment-specific? (dev, prod, test)
-   - Does it affect all users/data or specific cases?
-
-4. **Trace Data Flow**
-   - Follow the execution path
-   - Check input/output at each step
-   - Identify where behavior diverges from expected
-
-### Phase 3: Root Cause Analysis
-
-5. **Identify Candidates**
-   - Recent code changes (git blame, git log)
-   - Configuration changes
-   - Dependency updates
-   - External factors (API changes, data issues)
-
-6. **Verify Hypothesis**
-   - Test each candidate systematically
-   - Use console.log/debugger strategically
-   - Check edge cases and boundary conditions
-
-### Phase 4: Resolution
-
-7. **Develop Fix**
-   - Address root cause, not symptoms
-   - Consider side effects
-   - Validate fix doesn't break other things
-
-8. **Prevent Recurrence**
-   - Add test coverage
-   - Improve error handling
-   - Update documentation if needed
-
----
-
-## Diagnostic Commands
-
-### Error Analysis
-```bash
-# Search for error patterns in logs
-grep -r "error" .next/server/ 2>/dev/null | tail -20
-
-# Check recent console output
-# (User should provide if available)
-
-# TypeScript errors
-pnpm typecheck 2>&1 | head -50
-```
-
-### Code Investigation
-```bash
-# Find where something is defined
-grep -rn "functionName" src/
-
-# Check recent changes to a file
-git log -p --follow -5 -- path/to/file.ts
-
-# Find all usages of a function/component
-grep -rn "ComponentName" src/
-```
-
-### Runtime Investigation
-```bash
-# Check if dev server is running
-lsof -i :3000 2>/dev/null || echo "Port 3000 not in use"
-
-# Check environment
-env | grep -E "^(DATABASE|NEXT|NODE)" | head -10
-```
-
-### Database Investigation
-```bash
-# Check Prisma schema
-cat prisma/schema.prisma | grep -A5 "model"
-
-# Verify database connection
-pnpm prisma db pull --print 2>&1 | head -20
-```
-
----
-
-## Common Issue Patterns
-
-### TypeScript Errors
-- **"Cannot find module"**: Check imports, paths, tsconfig
-- **"Type X is not assignable"**: Verify types match at boundaries
-- **"Property does not exist"**: Check object shape, optional chaining
-
-### React/Next.js Issues
-- **Hydration mismatch**: Server/client rendering differences
-- **"use client" missing**: Server component using client features
-- **Stale data**: Cache invalidation, revalidation issues
-
-### API/tRPC Issues
-- **401/403**: Authentication/authorization check
-- **500**: Server-side error, check logs
-- **Network error**: CORS, URL configuration
-
-### Database Issues
-- **Connection refused**: Check DATABASE_URL, server running
-- **Unique constraint**: Duplicate data, check upsert logic
-- **Foreign key violation**: Related record doesn't exist
-
-### Build Issues
-- **Module not found**: Check dependencies, imports
-- **Out of memory**: Increase Node memory, check for loops
-- **Type errors**: Run `pnpm typecheck` for details
-
----
-
-## Output Format
-
-After investigation, provide a structured diagnosis:
-
-```markdown
-# Diagnosis Report
-
-**Issue**: [One-line summary]
-**Severity**: [Critical/High/Medium/Low]
-**Category**: [TypeScript/Runtime/Database/Network/Configuration]
-
----
-
-## Summary
-
-[2-3 sentence overview of what's happening and why]
-
----
-
-## Root Cause
-
-**Location**: `path/to/file.ts:123`
-
-**Problem**: [Detailed explanation of the root cause]
-
-**Evidence**:
-- [Finding 1 that supports this diagnosis]
-- [Finding 2]
-- [Relevant code snippet or error message]
-
----
-
-## Investigation Trail
-
-1. **Checked**: [What was investigated]
-   - **Finding**: [What was found]
-
-2. **Checked**: [Next investigation step]
-   - **Finding**: [Result]
-
-3. **Conclusion**: [How findings led to root cause]
-
----
-
-## Recommended Fix
-
-### Option 1: [Primary fix] (Recommended)
-
-**File**: `path/to/file.ts:123`
-
-**Current Code**:
-```typescript
-// problematic code
-```
-
-**Fixed Code**:
-```typescript
-// corrected code
-```
-
-**Why This Works**: [Explanation]
-
-### Option 2: [Alternative fix]
-
-[If there's a reasonable alternative approach]
-
----
-
-## Verification Steps
-
-1. [ ] Apply the fix
-2. [ ] Run `pnpm typecheck` - should pass
-3. [ ] Run `pnpm lint` - should pass
-4. [ ] Test the specific scenario that was failing
-5. [ ] Run related tests: `pnpm test [pattern]`
-
----
-
-## Prevention
-
-- [ ] Add test case for this scenario
-- [ ] Consider adding validation at [location]
-- [ ] Update documentation if behavior was unclear
-
----
-
-## Related Files
-
-- `path/to/related.ts` - [Why relevant]
-- `path/to/another.ts` - [Why relevant]
-```
-
----
-
-## Investigation Strategies by Issue Type
-
-### "It was working before"
-1. Check `git log` for recent changes
-2. Use `git bisect` to find breaking commit
-3. Review dependency updates in package.json
-
-### "It works locally but not in production"
-1. Compare environment variables
-2. Check build output differences
-3. Review deployment logs
-4. Verify database state
-
-### "It works sometimes"
-1. Look for race conditions
-2. Check for timing-dependent logic
-3. Review caching behavior
-4. Check for data-dependent paths
-
-### "The error message doesn't make sense"
-1. Find where the error is thrown
-2. Check what condition triggers it
-3. Add logging to trace the path
-4. Look for error transformation/wrapping
-
----
-
-Begin systematic investigation based on the issue description provided. Use Read to examine files, Grep to search for patterns, and Bash for diagnostics. Ask clarifying questions if the issue description is insufficient.
+Use the Task tool to launch the debug agent (subagent_type="debug") with the issue description and any additional context from arguments.