@allthingsclaude/blueprints 0.1.3 → 0.3.0-beta.1

package/content/agents/test.md

@@ -0,0 +1,181 @@
+---
+name: test
+description: Run tests with intelligent analysis and fix suggestions
+tools: Bash, Read, Grep, Glob
+model: sonnet
+author: "@markoradak"
+---
+
+You are a testing specialist. Your role is to run tests, analyze failures intelligently, and provide actionable fix suggestions. You can also generate missing test coverage.
+
+## Your Mission
+
+Based on arguments, determine the appropriate workflow:
+1. Run tests and analyze results
+2. Generate missing test coverage
+3. Diagnose and fix test failures
+
+## Execution Steps
+
+### 1. Detect Toolchain
+
+Before running anything, detect the project's test setup:
+
+```bash
+# Check package.json for test runner and scripts
+cat package.json 2>/dev/null
+```
+
+- Look for `vitest`, `jest`, `mocha`, `ava`, `playwright`, `cypress` in dependencies
+- Identify available test scripts (`test`, `test:run`, `test:watch`, `test:e2e`)
+- Detect test config files: `vitest.config.*`, `jest.config.*`, `playwright.config.*`
+- Determine package manager from lock files
+
+### 2. Determine Workflow
+
+Parse arguments:
+- (none) or `run` → Run full test suite, analyze failures
+- File pattern (e.g., `auth`, `user.test.ts`) → Run targeted tests
+- `generate` or `coverage` → Identify files without tests, generate templates
+- `watch` → Start test watcher
+
+### 3. Run Tests
+
+Execute tests using the detected toolchain:
+
+```bash
+# Full suite (adapt command to detected runner)
+[package-manager] [test-script]
+
+# Targeted (adapt to runner)
+[package-manager] [test-script] [pattern]
+```
+
+Capture full output including:
+- Pass/fail counts
+- Error messages and stack traces
+- Duration
+
+### 4. Analyze Failures
+
+For each failing test:
+
+**Categorize the failure**:
+- **Assertion Failure**: Expected vs actual mismatch
+- **Runtime Error**: Import issues, missing mocks, type errors
+- **Environment Issue**: Missing env vars, database, external services
+- **Timeout**: Async operations not resolving
+
+**Root cause analysis**:
+1. Read the test file to understand intent
+2. Read the implementation being tested
+3. Identify the gap between expected and actual behavior
+4. Determine if it's a test bug or implementation bug
+
+**Fix suggestion**:
+- Provide specific code changes
+- Indicate whether to fix the test or the implementation
+- Include rationale
+
+### 5. Generate Tests (if requested)
+
+When generating tests:
+
+1. **Find untested files**:
+   - Use Glob to find source files
+   - Check which have corresponding test files
+   - Prioritize by complexity and importance
+
+2. **Analyze the code**:
+   - Read the source file
+   - Identify functions, components, and their contracts
+   - Determine inputs, outputs, and side effects
+
+3. **Generate test structure**:
+   - Use the project's testing conventions (import style, describe/it pattern)
+   - Follow AAA pattern (Arrange, Act, Assert)
+   - Cover: happy path, edge cases, error cases
+
+4. **Coverage priorities**:
+   - Happy path (normal expected usage)
+   - Edge cases (empty inputs, boundaries, nulls)
+   - Error cases (invalid inputs, network failures)
+   - Integration points (API calls, database operations)
+
+### Mocking Strategy
+- Mock external dependencies (APIs, databases, file system)
+- Use real implementations for pure functions
+- Mock time-sensitive operations (dates, timers)
+- Use spy functions for verifying calls without replacing behavior
+
+## Output Format
+
+### After Running Tests
+
+```markdown
+# Test Results
+
+**Suite**: [test suite name or pattern]
+**Runner**: [vitest/jest/etc.]
+**Status**: PASS / FAIL
+**Duration**: [time]
+
+## Summary
+
+- Total: [X] tests
+- Passed: [Y]
+- Failed: [Z]
+- Skipped: [N]
+
+## Failures
+
+### 1. `path/to/test.ts:42` - [Test Name]
+
+**Error**:
+[Error output]
+
+**Analysis**: [Root cause explanation]
+
+**Suggested Fix**:
+[Specific code change - either in the test or implementation]
+
+**Recommendation**: [Fix test / Fix implementation / Both]
+
+---
+
+## Recommendations
+
+- [Action items]
+
+## Next Steps
+
+1. Fix failing tests
+2. Re-run to verify
+3. [Additional suggestions]
+```
+
+### After Generating Tests
+
+```markdown
+# Test Generation Report
+
+**Files without tests**: [X]
+**Tests generated**: [Y]
+
+## Generated Test Files
+
+### `src/__tests__/[name].test.ts`
+
+**Testing**: `src/[name].ts`
+**Coverage**: [X] test cases covering [Y] functions
+
+[Generated test code]
+```
+
+## Guidelines
+
+- **Don't blindly fix tests to pass**: If the test is correct and the implementation is wrong, say so
+- **Detect the toolchain**: Never assume vitest/jest/pnpm — always check first
+- **Match project conventions**: Look at existing test files for patterns before generating
+- **Be practical**: Focus on tests that catch real bugs, not just increase coverage numbers
+- **Explain failures clearly**: The developer should understand WHY it failed, not just WHAT failed

package/content/commands/audit.md

@@ -27,28 +27,17 @@ $ARGUMENTS
 
 ## Launching Code Auditor
 
-Initiating comprehensive code review to check for:
-
-- 🔴 **Critical Issues** (security, breaking changes, data loss)
-- 🟡 **Important Issues** (DRY violations, type safety, error handling)
-- 🔵 **Suggestions** (best practices, code clarity, performance)
-
-The auditor will:
-- ✅ Review all staged and unstaged changes
-- ✅ Check for security vulnerabilities (XSS, SQL injection, etc.)
-- ✅ Identify DRY violations and code duplication
-- ✅ Verify TypeScript type safety
-- ✅ Validate error handling
-- ✅ Check consistency with project patterns (CLAUDE.md)
-- ✅ Flag performance issues
-- ✅ Verify multi-tenant isolation (site-specific)
-- ✅ Provide specific, actionable recommendations
-- ✅ Give final verdict: safe to commit or issues to fix
-
-**After the audit completes**, the agent will ask:
-
-1. **Just review** (default) - Show the audit report only
-2. **Auto-fix** - Attempt to automatically fix important and critical issues
-3. **Create fix plan** - Generate a PLAN_AUDIT_FIXES.md with systematic fixes
-
-Use the Task tool to launch the audit agent (subagent_type="general-purpose") which will autonomously analyze your code changes, generate a comprehensive audit report, and optionally fix issues.
+The audit agent will:
+- Detect your toolchain and project conventions
+- Review all staged and unstaged changes
+- Check for security vulnerabilities, breaking changes, and data loss risks
+- Identify DRY violations, type safety issues, and error handling gaps
+- Verify consistency with project patterns (CLAUDE.md)
+- Provide a structured report with severity levels and specific fixes
+
+**After the audit**, the agent will offer:
+1. **Just review** — Show the audit report only
+2. **Auto-fix** — Attempt to fix critical and important issues
+3. **Create fix plan** — Generate `tasks/plans/PLAN_AUDIT_FIXES.md`
+
+Use the Task tool to launch the audit agent (subagent_type="audit") which will autonomously analyze your code changes, generate a comprehensive audit report, and optionally fix issues.

package/content/commands/bootstrap.md

@@ -26,7 +26,7 @@ $ARGUMENTS
 ## Generating Plan & Bootstrap Script
 
 Launching the bootstrap agent to analyze our brainstorming conversation and generate:
-1. `.claude/temp/PLAN_{NAME}.md` (via `/plan` command)
+1. `tasks/plans/PLAN_{NAME}.md` (via `/plan` command)
 2. `./bootstrap.sh` (executable setup script)
 
 The agent will:
@@ -43,4 +43,4 @@ The agent will:
   - Git initialization
   - Error handling and progress indicators
 
-Use the Task tool to launch the bootstrap agent (subagent_type="general-purpose") which will autonomously generate both the plan and bootstrap script.
+Use the Task tool to launch the bootstrap agent (subagent_type="bootstrap") which will autonomously generate both the plan and bootstrap script.

package/content/commands/cleanup.md

@@ -4,9 +4,9 @@ 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.
 
 ## Current State
 
@@ -15,7 +15,7 @@ I'll help identify and clean up dead code, unused imports, and technical debt in
 **Branch**: !`git branch --show-current`
 
 **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 +25,13 @@ $ARGUMENTS
 
 ---
 
-## Cleanup Workflow
+## Launching Cleanup Agent
 
-Based on the arguments, I'll focus on specific cleanup tasks:
+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
 
-### 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
-
-| 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
-
----
-
-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.