@allthingsclaude/blueprints 0.2.0 → 0.3.0-beta.10

package/content/commands/docs.md

@@ -0,0 +1,48 @@
+---
+description: Generate or update project documentation
+argument-hint: [readme | api | architecture | file path or component to document]
+author: "@markoradak"
+---
+
+# Generate Documentation
+
+I'll analyze your codebase and generate or update documentation.
+
+> **When to use**: You need to create or update documentation — READMEs, API references, architecture overviews, or inline docstrings. Use `/explain` when you want to understand code yourself rather than document it for others.
+
+## Current Context
+
+**Working Directory**: !`pwd`
+
+**Project**:
+!`ls README* 2>/dev/null; ls docs/ 2>/dev/null | head -10; echo "---"; cat package.json 2>/dev/null | head -5`
+
+**Existing Docs**:
+!`find . -maxdepth 3 -name "*.md" -not -path "*/node_modules/*" -not -path "*/.git/*" 2>/dev/null | head -15`
+
+---
+
+## Documentation Target
+
+$ARGUMENTS
+
+---
+
+## Launching Documentation Agent
+
+The docs agent will:
+- Analyze the codebase structure, exports, and public interfaces
+- Read existing documentation to understand current state
+- Identify gaps between code and documentation
+- Generate accurate, well-structured documentation
+- Use real code examples from the codebase (not invented ones)
+- Preserve existing documentation where it's still accurate
+
+**Workflows**:
+- `readme` — Generate or update the project README
+- `api` — Document public APIs, endpoints, or exported functions
+- `architecture` — Create an architecture overview with diagrams
+- `[file or component]` — Generate docs for a specific file or component
+- No arguments — Scan for documentation gaps and suggest what to document
+
+Use the Task tool to launch the docs agent (subagent_type="docs") with the documentation target and any additional context.

package/content/commands/dry.md

@@ -0,0 +1,48 @@
+---
+description: Eliminate DRY violations without changing behavior
+argument-hint: [optional: file/folder path, "functions" | "components" | "hooks" | "types" | "constants"]
+author: "@markoradak"
+---
+
+# DRY Optimization
+
+I'll find and eliminate DRY violations across your codebase while guaranteeing identical behavior.
+
+> **When to use**: You suspect duplicated code and want to consolidate it. Use `/cleanup` to remove unused/dead code, `/refactor` for renames, moves, or extractions, or `/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`
+
+**Files to Analyze**:
+!`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
+
+---
+
+## Focus Area
+
+$ARGUMENTS
+
+---
+
+## Launching DRY Agent
+
+The DRY agent will:
+- Detect your toolchain and capture a baseline (typecheck, lint, tests, build)
+- Scan for exact, structural, and logical duplications
+- Present a prioritized report with line counts and savings estimates
+- Apply optimizations one at a time (with your approval)
+- Validate after each change — revert immediately on failure
+- Guarantee zero behavior change
+
+**Scoping options**:
+- No argument → Full source scan
+- `functions` / `components` / `hooks` / `types` / `constants` → Category-specific scan
+- File/folder path → Scoped deep scan
+
+Use the Task tool to launch the DRY agent (subagent_type="dry") which will capture the baseline, scan for DRY violations, present a prioritized report, and — with user approval — apply optimizations one at a time with validation after each change.

package/content/commands/explain.md

@@ -4,7 +4,7 @@ argument-hint: [file path, component name, feature, or concept to explain]
 author: "@markoradak"
 ---
 
-# Code Explainer
+# Explain Code
 
 I'll provide a detailed, educational explanation of the code, architecture, or feature you're interested in.
 
@@ -23,318 +23,21 @@ $ARGUMENTS
 
 ---
 
-## Explanation Framework
+## Launching Explanation Agent
 
-Based on what you want to understand, I'll provide explanations at different levels:
+Launching the explain agent to analyze the code and generate a comprehensive explanation...
 
-### For a **File**:
-1. **Purpose**: Why this file exists
-2. **Structure**: How it's organized
-3. **Key Components**: Main functions/classes/exports
-4. **Data Flow**: How data moves through it
-5. **Dependencies**: What it imports and why
-6. **Usage**: Where and how it's used
+Use the Task tool to launch the explain agent:
 
-### For a **Component/Function**:
-1. **Purpose**: What problem it solves
-2. **Interface**: Inputs, outputs, props
-3. **Implementation**: How it works step-by-step
-4. **State Management**: What state it manages
-5. **Side Effects**: External interactions
-6. **Usage Examples**: How to use it
-
-### For a **Feature**:
-1. **Overview**: What the feature does
-2. **Architecture**: Components involved
-3. **Data Flow**: End-to-end flow
-4. **Key Files**: Where the implementation lives
-5. **Entry Points**: Where it starts
-6. **Integration Points**: How it connects to rest of system
-
-### For an **Architecture Concept**:
-1. **Definition**: What the concept means
-2. **Why It's Used**: Benefits in this project
-3. **Implementation**: How it's applied here
-4. **Examples**: Concrete examples from codebase
-5. **Trade-offs**: Pros and cons
-6. **Related Patterns**: Connected concepts
-
----
-
-## Explanation Output Format
-
-```markdown
-# Understanding: [Topic]
-
-## Quick Summary
-
-[2-3 sentence overview for someone in a hurry]
-
----
-
-## The Big Picture
-
-### What Is This?
-
-[Plain English explanation of what this is and why it exists]
-
-### Why Does It Matter?
-
-[Why this is important in the context of the project]
-
-### Where Does It Fit?
-
-```
-[ASCII diagram showing where this fits in the architecture]
-
-┌─────────────────────────────────────────────┐
-│                  Application                 │
-├─────────────────────────────────────────────┤
-│  ┌─────────┐   ┌─────────┐   ┌─────────┐   │
-│  │   UI    │ → │  State  │ → │   API   │   │
-│  └─────────┘   └─────────┘   └─────────┘   │
-│       ↑             ↑             ↓         │
-│       └─────────────┴─────────────┘         │
-│                                             │
-│  [THIS COMPONENT] ←── You are here          │
-└─────────────────────────────────────────────┘
-```
-
----
-
-## Deep Dive
-
-### How It Works
-
-#### Step 1: [First thing that happens]
-
-```typescript
-// Relevant code snippet with annotations
-const example = doThing() // <- This does X because Y
-```
-
-**What's happening**: [Explanation]
-
-#### Step 2: [Second thing]
-
-```typescript
-// Next relevant code
-```
-
-**What's happening**: [Explanation]
-
-#### Step 3: [And so on...]
-
----
-
-### Key Concepts
-
-#### [Concept 1 Name]
-
-**Definition**: [What it means]
-
-**In This Code**: [How it's applied]
-
-**Example**:
-```typescript
-// Example from the actual codebase
-```
-
-#### [Concept 2 Name]
-
-[Same structure...]
-
----
-
-### Data Flow
-
-```
-[Input]
-    ↓
-┌───────────────┐
-│ [Process 1]   │  "Transforms X into Y"
-└───────────────┘
-    ↓
-┌───────────────┐
-│ [Process 2]   │  "Validates and enriches"
-└───────────────┘
-    ↓
-┌───────────────┐
-│ [Process 3]   │  "Persists to database"
-└───────────────┘
-    ↓
-[Output]
-```
-
----
-
-### File Structure
-
-```
-src/
-├── feature/
-│   ├── components/     # UI components
-│   │   ├── Thing.tsx   # [purpose] ← THIS FILE
-│   │   └── Other.tsx   # [purpose]
-│   ├── hooks/          # Custom hooks
-│   │   └── useThing.ts # [purpose]
-│   ├── lib/            # Business logic
-│   │   └── thing.ts    # [purpose]
-│   └── types/          # TypeScript types
-│       └── thing.ts    # [purpose]
-```
-
----
-
-## Code Walkthrough
-
-### `path/to/file.ts`
-
-```typescript
-// Line 1-10: Imports
-import { x } from 'y'  // We need X because...
-
-// Line 12-25: Types
-interface Props {      // Defines what this component accepts
-  name: string         // The user's display name
-  onSubmit: () => void // Called when form is submitted
-}
-
-// Line 27-50: Main Component
-export function Component({ name, onSubmit }: Props) {
-  // Line 28: State setup
-  const [value, setValue] = useState('')  // Tracks input value
-
-  // Line 31-35: Effect for side effects
-  useEffect(() => {
-    // This runs when X changes because we need to Y
-  }, [dependency])
-
-  // Line 37-45: Event handler
-  const handleClick = () => {
-    // Validates input, then calls onSubmit
-  }
-
-  // Line 47-60: Render
-  return (
-    // JSX that displays the UI
-  )
-}
-```
-
----
-
-## Common Questions
-
-### "Why is it done this way?"
-
-[Explain the reasoning behind key design decisions]
-
-### "What would break if I changed X?"
-
-[Explain dependencies and ripple effects]
-
-### "How do I modify this?"
-
-[Guide for making common changes]
-
-### "Where should I add new feature Y?"
-
-[Point to the right location based on the architecture]
-
----
-
-## Related Files
-
-| File | Relationship | Purpose |
-|------|--------------|---------|
-| `path/to/related.ts` | Imports from | Provides utility functions |
-| `path/to/parent.tsx` | Uses this | Parent component that renders this |
-| `path/to/types.ts` | Types from | Type definitions |
-
----
-
-## Key Takeaways
-
-1. **[Takeaway 1]**: [One sentence summary]
-2. **[Takeaway 2]**: [One sentence summary]
-3. **[Takeaway 3]**: [One sentence summary]
-
----
-
-## Next Steps for Learning
-
-- [ ] Read `related/file.ts` to understand [concept]
-- [ ] Try modifying [small thing] to see how it works
-- [ ] Look at how [similar feature] is implemented
-- [ ] Check the tests in `__tests__/` for usage examples
-```
-
----
-
-## Explanation Depth Levels
-
-### Quick (1-2 minutes to read)
-- Purpose and key points only
-- Good for: "What is this file?"
-
-### Standard (5-10 minutes to read)
-- Full explanation with code walkthrough
-- Good for: "How does this work?"
-
-### Deep (15+ minutes to read)
-- Architecture, history, design decisions
-- Good for: "I need to maintain/extend this"
-
-**Ask**: "Would you like a quick, standard, or deep explanation?"
-
----
-
-## Visual Explanation Tools
-
-### ASCII Architecture Diagrams
-```
-┌─────────────────────────────────────┐
-│             Frontend                 │
-│  ┌─────────┐      ┌─────────┐       │
-│  │ React   │ ───→ │ Hooks   │       │
-│  └─────────┘      └─────────┘       │
-└─────────────────────────────────────┘
-         │
-         ↓ tRPC / REST
-┌─────────────────────────────────────┐
-│             Backend                  │
-│  ┌─────────┐      ┌─────────┐       │
-│  │ Routes  │ ───→ │ Prisma  │       │
-│  └─────────┘      └─────────┘       │
-└─────────────────────────────────────┘
-```
-
-### Data Flow Arrows
-```
-User Input → Validation → Transform → API Call → Response → UI Update
-                ↓
-           Error Handling → Error Display
 ```
+Task: subagent_type="explain"
+prompt: "Explain the following: $ARGUMENTS
 
-### State Transitions
+Working directory context has been gathered above. Research the codebase thoroughly, read all relevant files, and produce a clear, educational explanation."
 ```
-[Initial] ──load──→ [Loading] ──success──→ [Ready]
-                        │
-                        └──error──→ [Error] ──retry──→ [Loading]
-```
-
----
-
-## Explanation Best Practices
-
-1. **Start with WHY** before HOW
-2. **Use analogies** for complex concepts
-3. **Show real code** from the codebase
-4. **Highlight patterns** that repeat
-5. **Connect to the big picture**
-6. **Anticipate questions**
-
----
 
-Read the relevant files, analyze the structure, and provide a comprehensive explanation. Use Read to examine code, Grep to find related files, and Glob to understand file organization. Tailor the explanation depth to what seems most useful.
+The agent will:
+1. **Find the code** — Locate the relevant files using Glob and Grep
+2. **Read the context** — Read the full implementation plus related files
+3. **Trace connections** — Follow imports, consumers, and test files
+4. **Build the explanation** — Structured walkthrough with visual aids and file:line references

package/content/commands/finalize.md

@@ -12,7 +12,7 @@ I'll finalize your work session by updating plans, creating a comprehensive git
 
 **Working Directory**: !`pwd`
 
-**Branch**: !`git branch --show-current`
+**Branch**: !`git branch --show-current 2>/dev/null || echo "Not a git repository"`
 
 **Status**:
 !`git status --short`
@@ -21,7 +21,7 @@ I'll finalize your work session by updating plans, creating a comprehensive git
 !`git diff --stat`
 
 **Active Plans**:
-!`ls -1 .claude/temp/PLAN_*.md 2>/dev/null || echo "No active plans"`
+!`ls -1 {{PLANS_DIR}}/PLAN_*.md 2>/dev/null || echo "No active plans"`
 
 ---
 
@@ -46,4 +46,4 @@ The finalize agent will systematically:
 
 **This will create a git commit with all your work.**
 
-Use the Task tool to launch the finalize agent (subagent_type="general-purpose") which will autonomously finalize your session and create the commit.
+Use the Task tool to launch the finalize agent (subagent_type="finalize") which will autonomously finalize your session and create the commit.

package/content/commands/flush.md

@@ -1,29 +1,24 @@
 ---
-description: Flush all temporary files in .claude/temp
-argument-hint:
+description: Flush all task artifacts from {{TASKS_DIR}}/
 author: "@markoradak"
 ---
 
-# Flush Temporary Files
+# Flush Task Artifacts
 
-I'll flush all temporary files from `.claude/temp/`.
+I'll flush all task artifacts from `{{TASKS_DIR}}/`.
 
 ## Current Contents
 
-!`ls -lh .claude/temp/ 2>/dev/null || echo "Temp directory is empty or doesn't exist"`
+!`ls -lhR {{TASKS_DIR}}/ 2>/dev/null || echo "Tasks directory is empty or doesn't exist"`
 
 ---
 
-## Flushing
+## Confirmation Required
 
-Now I'll remove all files from `.claude/temp/`:
+Before deleting, list all files in `{{TASKS_DIR}}/` to the user and ask for explicit confirmation.
 
-!`rm -rf .claude/temp/* 2>/dev/null && echo "✅ Flushed .claude/temp/" || echo "✅ Nothing to flush"`
+If the user confirms, delete all files using Bash: `rm -rf {{TASKS_DIR}}/*`
 
-## Verification
+Then verify the directory is empty using Bash: `ls -lhR {{TASKS_DIR}}/ 2>/dev/null || echo "Tasks directory is now empty"`
 
-!`ls -lh .claude/temp/ 2>/dev/null || echo "Temp directory is now empty"`
-
----
-
-**Done!** All temporary handoffs, plans, and other temp files have been flushed.
+**Do NOT delete anything without user confirmation.**

package/content/commands/handoff.md

@@ -34,7 +34,7 @@ $ARGUMENTS
 
 ## Generating Handoff
 
-Launching the handoff agent to analyze your work session and generate `.claude/temp/HANDOFF.md`...
+Launching the handoff agent to analyze your work session and generate `{{SESSIONS_DIR}}/HANDOFF.md`...
 
 The agent will:
 - ✅ Review recent commits and current changes

package/content/commands/implement.md

@@ -16,10 +16,10 @@ $ARGUMENTS
 
 ## Available Plans
 
-**Plans in .claude/temp/**:
-!`ls -1 .claude/temp/PLAN_*.md 2>/dev/null || echo "No plans found"`
+**Plans in {{PLANS_DIR}}/**:
+!`ls -1 {{PLANS_DIR}}/PLAN_*.md 2>/dev/null || echo "No plans found"`
 
-**Current Branch**: !`git branch --show-current`
+**Current Branch**: !`git branch --show-current 2>/dev/null || echo "Not a git repository"`
 
 **Working Directory**: !`pwd`
 
@@ -31,7 +31,7 @@ Launching the **implement agent** which will work independently in a separate co
 
 ### What the Agent Will Do
 
-- ✅ Load `.claude/temp/PLAN_{NAME}.md`
+- ✅ Load `{{PLANS_DIR}}/PLAN_{NAME}.md`
 - ✅ Parse all phases, tasks, and dependencies
 - ✅ Create comprehensive task tracking (TodoWrite)
 - ✅ Execute tasks systematically with validation
@@ -64,4 +64,4 @@ Use `/implement` when:
 
 ---
 
-Use the Task tool to launch the implement agent (subagent_type="general-purpose") with the plan name and any additional context from arguments.
+Use the Task tool to launch the implement agent (subagent_type="implement") with the plan name and any additional context from arguments.

package/content/commands/kickoff.md

@@ -16,10 +16,13 @@ $ARGUMENTS
 
 ## Available Plans
 
-**Plans in .claude/temp/**:
-!`ls -1 .claude/temp/PLAN_*.md 2>/dev/null || echo "No plans found"`
+**Active Plan**:
+!`cat {{STATE_FILE}} 2>/dev/null || echo "No active plan set"`
 
-**Current Branch**: !`git branch --show-current`
+**Plans in {{PLANS_DIR}}/**:
+!`ls -1 {{PLANS_DIR}}/PLAN_*.md 2>/dev/null || echo "No plans found"`
+
+**Current Branch**: !`git branch --show-current 2>/dev/null || echo "Not a git repository"`
 
 **Working Directory**: !`pwd`
 
@@ -52,7 +55,7 @@ I'll work through this plan collaboratively with you:
 
 Now let me load the plan and we'll get started together.
 
-Use Read to load `.claude/temp/PLAN_{NAME}.md`, display a comprehensive summary with:
+Use Read to load `{{PLANS_DIR}}/PLAN_{NAME}.md`, display a comprehensive summary with:
 - Objective
 - Phases and task counts
 - Key files involved

package/content/commands/migrate.md

@@ -0,0 +1,54 @@
+---
+description: Upgrade dependencies or migrate between framework versions
+argument-hint: [package@version, "all", or migration description]
+author: "@markoradak"
+---
+
+# Migration Assistant
+
+I'll help you upgrade dependencies or migrate between framework versions safely.
+
+> **When to use**: You need to upgrade a dependency, migrate to a new major version, or handle breaking changes. Use `/refactor` for structural code changes that aren't dependency-driven.
+
+## Current State
+
+**Working Directory**: !`pwd`
+
+**Branch**: !`git branch --show-current 2>/dev/null || echo "Not a git repository"`
+
+**Status**:
+!`git status --short`
+
+**Current Dependencies**:
+!`cat package.json 2>/dev/null | head -40`
+
+**Lock File**:
+!`ls pnpm-lock.yaml yarn.lock bun.lockb package-lock.json 2>/dev/null | head -1 || echo "No lock file found"`
+
+---
+
+## Migration Target
+
+$ARGUMENTS
+
+---
+
+## Launching Migration Agent
+
+The migration agent will:
+- Identify current versions and target versions
+- Research breaking changes and migration guides
+- Capture a baseline (typecheck, lint, tests, build)
+- Create a step-by-step migration plan
+- Apply changes incrementally with validation after each step
+- Update code to handle breaking API changes
+- Verify the full test suite passes after migration
+
+**Workflows**:
+- `react@19` → Upgrade React to v19 with breaking change resolution
+- `next@15` → Upgrade Next.js with migration guide steps
+- `all` → Check all dependencies for available updates
+- `typescript@5.5` → Upgrade TypeScript with new strict checks
+- Description → Handle a described migration (e.g., "move from Jest to Vitest")
+
+Use the Task tool to launch the migrate agent (subagent_type="migrate") with the migration target and any constraints.

package/content/commands/parallelize.md

@@ -12,10 +12,10 @@ I'll analyze your plan or task, identify parallelization opportunities, and spaw
 
 **Working Directory**: !`pwd`
 
-**Branch**: !`git branch --show-current`
+**Branch**: !`git branch --show-current 2>/dev/null || echo "Not a git repository"`
 
 **Available Plans**:
-!`ls -1 .claude/temp/PLAN_*.md 2>/dev/null || echo "No plans found"`
+!`ls -1 {{PLANS_DIR}}/PLAN_*.md 2>/dev/null || echo "No plans found"`
 
 ---
 

package/content/commands/pickup.md

@@ -8,7 +8,7 @@ author: "@markoradak"
 
 Loading the handoff document from your previous session:
 
-@.claude/temp/HANDOFF.md
+{{SESSIONS_DIR}}/HANDOFF.md
 
 ---
 

package/content/commands/plan.md

@@ -25,7 +25,7 @@ $ARGUMENTS
 
 ## Generating Plan
 
-Launching the plan agent to analyze our conversation and generate `.claude/temp/PLAN_{NAME}.md`...
+Launching the plan agent to analyze our conversation and generate `{{PLANS_DIR}}/PLAN_{NAME}.md`...
 
 The agent will:
 - ✅ Summarize key findings from our discussion
@@ -35,4 +35,4 @@ The agent will:
 - ✅ Note technical considerations and constraints
 - ✅ List relevant files and references
 
-Use the Task tool to launch the plan agent (subagent_type="general-purpose") which will autonomously generate the plan document.
+Use the Task tool to launch the plan agent (subagent_type="plan") which will autonomously generate the plan document.