@allthingsclaude/blueprints 0.1.1

package/content/commands/explain.md

@@ -0,0 +1,340 @@
+---
+description: Generate detailed explanations of code, architecture, or features
+argument-hint: [file path, component name, feature, or concept to explain]
+author: "@markoradak"
+---
+
+# Code Explainer
+
+I'll provide a detailed, educational explanation of the code, architecture, or feature you're interested in.
+
+## Current Context
+
+**Working Directory**: !`pwd`
+
+**Project Structure**:
+!`ls -la src/ 2>/dev/null | head -15`
+
+---
+
+## What to Explain
+
+$ARGUMENTS
+
+---
+
+## Explanation Framework
+
+Based on what you want to understand, I'll provide explanations at different levels:
+
+### 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
+
+### 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
+```
+
+### State Transitions
+```
+[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.

package/content/commands/finalize.md

@@ -0,0 +1,49 @@
+---
+description: Finalize work session - update plans, commit changes with proper message
+argument-hint: [optional: commit message prefix or focus area]
+author: "@markoradak"
+---
+
+# Finalize Work Session
+
+I'll finalize your work session by updating plans, creating a comprehensive git commit, and documenting any bottlenecks or key decisions.
+
+## Current Session State
+
+**Working Directory**: !`pwd`
+
+**Branch**: !`git branch --show-current`
+
+**Status**:
+!`git status --short`
+
+**Changes Summary**:
+!`git diff --stat`
+
+**Active Plans**:
+!`ls -1 .claude/temp/PLAN_*.md 2>/dev/null || echo "No active plans"`
+
+---
+
+## Additional Context
+
+$ARGUMENTS
+
+---
+
+## Launching Finalize Agent
+
+The finalize agent will systematically:
+
+- ✅ Review all changes made in this session
+- ✅ Update PLAN files by checking off completed tasks
+- ✅ Analyze commit history to understand what was accomplished
+- ✅ Generate a comprehensive commit message with `feat:` prefix
+- ✅ Identify and document any bottlenecks or key decisions
+- ✅ Create optional phase summary file for important findings
+- ✅ Stage and commit all changes with proper attribution
+- ✅ Provide session completion summary
+
+**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.

package/content/commands/flush.md

@@ -0,0 +1,29 @@
+---
+description: Flush all temporary files in .claude/temp
+argument-hint:
+author: "@markoradak"
+---
+
+# Flush Temporary Files
+
+I'll flush all temporary files from `.claude/temp/`.
+
+## Current Contents
+
+!`ls -lh .claude/temp/ 2>/dev/null || echo "Temp directory is empty or doesn't exist"`
+
+---
+
+## Flushing
+
+Now I'll remove all files from `.claude/temp/`:
+
+!`rm -rf .claude/temp/* 2>/dev/null && echo "✅ Flushed .claude/temp/" || echo "✅ Nothing to flush"`
+
+## Verification
+
+!`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.

package/content/commands/handoff.md

@@ -0,0 +1,46 @@
+---
+description: Generate comprehensive handoff documentation for context switching
+argument-hint: [optional: focus area or notes]
+author: "@markoradak"
+---
+
+# Generate Session Handoff
+
+I'll create a comprehensive handoff document to capture the current state of your work.
+
+## Current Session Context
+
+**Working Directory**: !`pwd`
+
+**Git Status**:
+!`git status --short`
+
+**Recent Commits** (last 5):
+!`git log --oneline -5`
+
+**Unstaged Changes**:
+!`git diff --stat`
+
+**Staged Changes**:
+!`git diff --cached --stat`
+
+---
+
+## Additional Context
+
+$ARGUMENTS
+
+---
+
+## Generating Handoff
+
+Launching the handoff agent to analyze your work session and generate `.claude/temp/HANDOFF.md`...
+
+The agent will:
+- ✅ Review recent commits and current changes
+- ✅ Read modified files to understand context
+- ✅ Identify what's complete vs in-progress
+- ✅ Document next steps and blockers
+- ✅ Preserve key decisions and patterns
+
+Use the Task tool to launch the handoff agent (subagent_type="handoff") which will autonomously generate the handoff document.

package/content/commands/implement.md

@@ -0,0 +1,67 @@
+---
+description: Autonomously implement a plan using subagent
+argument-hint: {NAME} [optional: starting phase or task]
+author: "@markoradak"
+---
+
+# Autonomous Plan Implementation
+
+I'll launch the implementation agent to **autonomously execute** your plan.
+
+## Plan to Execute
+
+$ARGUMENTS
+
+---
+
+## Available Plans
+
+**Plans in .claude/temp/**:
+!`ls -1 .claude/temp/PLAN_*.md 2>/dev/null || echo "No plans found"`
+
+**Current Branch**: !`git branch --show-current`
+
+**Working Directory**: !`pwd`
+
+---
+
+## Autonomous Execution Mode
+
+Launching the **implement agent** which will work independently in a separate context.
+
+### What the Agent Will Do
+
+- ✅ Load `.claude/temp/PLAN_{NAME}.md`
+- ✅ Parse all phases, tasks, and dependencies
+- ✅ Create comprehensive task tracking (TodoWrite)
+- ✅ Execute tasks systematically with validation
+- ✅ Update plan document as tasks complete
+- ✅ Run type checks and linting after each task
+- ✅ Validate each phase before proceeding
+- ✅ Handle blockers (will pause and report)
+- ✅ Adapt plan if better approaches discovered
+- ✅ Return comprehensive summary when complete
+
+### What You'll See
+
+The agent will:
+- Work autonomously in a separate context
+- Come back with a **summary report** of what was done
+- Ask for your input if it encounters blockers
+- Update you on progress periodically
+
+**This is hands-off autonomous implementation.**
+
+### When to Use This
+
+Use `/implement` when:
+- You want the work done independently
+- The plan is clear and self-contained
+- You'll check back later for results
+- You trust the autonomous execution
+
+**Want to be involved?** Use `/kickoff` instead for collaborative implementation.
+
+---
+
+Use the Task tool to launch the implement agent (subagent_type="general-purpose") with the plan name and any additional context from arguments.

package/content/commands/kickoff.md

@@ -0,0 +1,65 @@
+---
+description: Start implementing a plan interactively in main context
+argument-hint: {NAME} [optional: starting phase or task]
+author: "@markoradak"
+---
+
+# Kickoff Plan Implementation
+
+I'll load the plan and work through it **with you** in this conversation.
+
+## Plan to Execute
+
+$ARGUMENTS
+
+---
+
+## Available Plans
+
+**Plans in .claude/temp/**:
+!`ls -1 .claude/temp/PLAN_*.md 2>/dev/null || echo "No plans found"`
+
+**Current Branch**: !`git branch --show-current`
+
+**Working Directory**: !`pwd`
+
+---
+
+## Interactive Implementation
+
+I'll work through this plan collaboratively with you:
+
+### How This Works
+
+1. **Load & Review**: I'll load the plan and show you a summary
+2. **Environment Check**: Verify git status and project state
+3. **Task Tracking**: Set up TodoWrite for all plan tasks
+4. **Step-by-Step**: Execute tasks one at a time with your input
+5. **Validation**: Run type checks and lints after each task
+6. **Phase Approval**: Ask before moving between phases
+7. **Adapt Together**: Discuss blockers and adjustments as we go
+
+### Your Role
+
+- You can guide, ask questions, and make decisions as we work
+- Interrupt at any time to change direction
+- Review changes before I move to the next task
+- Stay involved throughout the implementation
+
+**This is collaborative implementation in the main conversation.**
+
+---
+
+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:
+- Objective
+- Phases and task counts
+- Key files involved
+- Any open questions or risks
+
+Then ask: "Ready to start implementing? Which phase should we tackle first?"
+
+Use TodoWrite to create todos for all tasks from the plan once user confirms.
+
+Then begin executing tasks step-by-step, staying in the main context, validating as you go.

package/content/commands/parallelize.md

@@ -0,0 +1,118 @@
+---
+description: Parallelize plan execution across multiple agents for faster development
+argument-hint: {PLAN_NAME} [optional: max-agents count]
+author: "@markoradak"
+---
+
+# Parallelize Execution
+
+I'll analyze your plan or task, identify parallelization opportunities, and spawn multiple agents to work simultaneously.
+
+## Current State
+
+**Working Directory**: !`pwd`
+
+**Branch**: !`git branch --show-current`
+
+**Available Plans**:
+!`ls -1 .claude/temp/PLAN_*.md 2>/dev/null || echo "No plans found"`
+
+---
+
+## Parallelization Target
+
+$ARGUMENTS
+
+---
+
+## How This Works
+
+1. **Analyze**: I'll examine the plan/task for independent work streams
+2. **Partition**: Group tasks that can run in parallel (no file conflicts)
+3. **Spawn**: Launch multiple agents, each handling a partition
+4. **Monitor**: Track progress across all agents
+5. **Consolidate**: Merge results and validate the combined work
+
+---
+
+## Launching Parallel Orchestrator
+
+The orchestrator agent will:
+
+- **Dependency Analysis**: Map which tasks depend on others
+- **Conflict Detection**: Identify tasks that touch the same files
+- **Optimal Partitioning**: Create work streams that maximize parallelism
+- **Agent Spawning**: Launch agents for each stream using Task tool
+- **Progress Tracking**: Monitor completion status
+- **Validation**: Run typecheck/lint on combined results
+- **Summary Report**: Show what was accomplished
+
+### Parallelization Rules
+
+**CAN Parallelize**:
+- Tasks in different files/modules
+- Independent feature implementations
+- Research/exploration tasks
+- Test writing for different areas
+- Documentation updates
+
+**CANNOT Parallelize**:
+- Tasks that modify the same file
+- Tasks with data dependencies (B needs output of A)
+- Sequential migrations/schema changes
+- Tasks requiring shared state
+
+### Agent Limits
+
+- **Default**: 3-5 agents (balances speed vs. coordination overhead)
+- **Maximum**: 8 agents (beyond this, conflicts become likely)
+- **Minimum**: 2 agents (otherwise just use `/implement`)
+
+---
+
+## Expected Output
+
+After parallel execution completes:
+
+```markdown
+# Parallel Execution Complete
+
+**Plan**: {PLAN_NAME}
+**Agents Spawned**: [X]
+**Total Duration**: [time]
+**Tasks Completed**: [Y/Z]
+
+## Stream Results
+
+### Stream 1: [Description]
+- Agent: [ID]
+- Status: Complete
+- Tasks: [list]
+- Files Modified: [list]
+
+### Stream 2: [Description]
+- Agent: [ID]
+- Status: Complete
+- Tasks: [list]
+- Files Modified: [list]
+
+## Validation
+
+- Type Check: [Pass/Fail]
+- Lint: [Pass/Fail]
+- Conflicts: [None/List]
+
+## Summary
+
+[What was accomplished across all streams]
+
+## Next Steps
+
+1. Review changes: `git diff`
+2. Run tests: `pnpm test`
+3. Continue with remaining tasks (if any)
+```
+
+---
+
+Use the Task tool to launch the parallelize orchestrator agent (subagent_type="parallelize") which will analyze the plan, partition work, spawn agents, and coordinate parallel execution.