@allthingsclaude/blueprints 0.3.0-beta.2 → 0.3.0-beta.20

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`

package/content/commands/diagram.md

@@ -0,0 +1,51 @@
+---
+description: Generate Mermaid diagrams from your codebase
+argument-hint: [architecture | dependency | sequence | er | dataflow | component name or feature]
+author: "@markoradak"
+---
+
+# Generate Diagrams
+
+I'll analyze your codebase and generate Mermaid diagrams that visualize architecture, dependencies, data flow, and more.
+
+> **When to use**: You need visual documentation — architecture overviews, dependency graphs, sequence diagrams, ER diagrams, or data flow maps. Use `/explain` when you want a text walkthrough of how something works. Use `/docs architecture` for a full architecture document with diagrams embedded.
+
+## Current Context
+
+**Working Directory**: !`pwd`
+
+**Project**:
+!`cat package.json 2>/dev/null | head -10 || cat Cargo.toml 2>/dev/null | head -10 || cat pyproject.toml 2>/dev/null | head -10 || cat go.mod 2>/dev/null | head -5`
+
+**Structure**:
+!`ls -la src/ 2>/dev/null | head -20 || ls -la lib/ 2>/dev/null | head -20 || ls -la app/ 2>/dev/null | head -20 || ls -la`
+
+**Existing Docs**:
+!`ls docs/ 2>/dev/null | head -10; ls *.md 2>/dev/null | head -5`
+
+---
+
+## Diagram Target
+
+$ARGUMENTS
+
+---
+
+## Launching Diagram Agent
+
+The diagram agent will:
+1. **Analyze the codebase** — Trace imports, exports, routes, models, and data flow
+2. **Choose the right diagram type(s)** based on what's requested and what's useful
+3. **Generate Mermaid syntax** — Renderable on GitHub, VS Code, Notion, and most markdown tools
+4. **Write to file** — Saves diagrams as `.md` files (or appends to existing docs)
+
+**Diagram types**:
+- `architecture` — High-level system overview (components, layers, boundaries)
+- `dependency` — Module/package dependency graph (imports, who depends on whom)
+- `sequence` — Request/event flow through the system (step-by-step interactions)
+- `er` — Entity-relationship diagram (database models, types, relationships)
+- `dataflow` — How data moves through the system (input → transform → output)
+- `[feature or component]` — Auto-detect the best diagram type for the subject
+- No arguments — Survey the project and generate the most useful overview diagram
+
+Use the Task tool to launch the diagram agent (subagent_type="diagram") with the target and any additional context.

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

@@ -8,11 +8,13 @@ author: "@markoradak"
 
 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`
+**Branch**: !`git branch --show-current 2>/dev/null || echo "Not a git repository"`
 
 **Status**:
 !`git status --short`

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 tasks/plans/PLAN_*.md 2>/dev/null || echo "No active plans"`
+!`ls -1 {{PLANS_DIR}}/PLAN_*.md 2>/dev/null || echo "No active plans"`
 
 ---
 

package/content/commands/flush.md

@@ -1,25 +1,24 @@
 ---
-description: Flush all task artifacts from tasks/
-argument-hint:
+description: Flush all task artifacts from {{TASKS_DIR}}/
 author: "@markoradak"
 ---
 
 # Flush Task Artifacts
 
-I'll flush all task artifacts from `tasks/`.
+I'll flush all task artifacts from `{{TASKS_DIR}}/`.
 
 ## Current Contents
 
-!`ls -lhR tasks/ 2>/dev/null || echo "Tasks directory is empty or doesn't exist"`
+!`ls -lhR {{TASKS_DIR}}/ 2>/dev/null || echo "Tasks directory is empty or doesn't exist"`
 
 ---
 
 ## Confirmation Required
 
-Before deleting, list all files in `tasks/` to the user and ask for explicit confirmation.
+Before deleting, list all files in `{{TASKS_DIR}}/` to the user and ask for explicit confirmation.
 
-If the user confirms, delete all files using Bash: `rm -rf tasks/*`
+If the user confirms, delete all files using Bash: `rm -rf {{TASKS_DIR}}/*`
 
-Then verify the directory is empty using Bash: `ls -lhR tasks/ 2>/dev/null || echo "Tasks directory is now empty"`
+Then verify the directory is empty using Bash: `ls -lhR {{TASKS_DIR}}/ 2>/dev/null || echo "Tasks directory is now empty"`
 
 **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 `tasks/sessions/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/i18n.md

@@ -0,0 +1,53 @@
+---
+description: Audit and set up internationalization for your project
+argument-hint: [optional: audit | setup | extract | add-locale <locale> | file path or component]
+author: "@markoradak"
+---
+
+# Internationalization
+
+I'll audit your project's internationalization readiness, extract hardcoded strings, and set up or improve your i18n infrastructure.
+
+> **When to use**: You want to make your project multilingual — extracting hardcoded strings, setting up i18n libraries, adding new locales, or auditing existing translations for completeness. Use `/a11y` for accessibility issues, or `/docs` for general documentation.
+
+## Current Context
+
+**Working Directory**: !`pwd`
+
+**Project**:
+!`cat package.json 2>/dev/null | head -15`
+
+**Existing i18n Setup**:
+!`cat package.json 2>/dev/null | grep -i "i18n\|intl\|locale\|next-intl\|react-intl\|react-i18next\|i18next\|vue-i18n\|@formatjs\|lingui\|messageformat\|rosetta\|typesafe-i18n\|paraglide" || echo "No i18n dependencies detected"`
+!`ls -d **/locales/ **/translations/ **/i18n/ **/lang/ **/messages/ src/i18n* src/locales* public/locales* 2>/dev/null || echo "No i18n directories found"`
+!`ls i18n.config* i18next.config* next-i18next.config* lingui.config* 2>/dev/null || echo "No i18n config files found"`
+
+**Frontend Files**:
+!`find src/ app/ pages/ components/ -name "*.tsx" -o -name "*.jsx" -o -name "*.vue" -o -name "*.svelte" 2>/dev/null | wc -l`
+
+---
+
+## i18n Scope
+
+$ARGUMENTS
+
+---
+
+## Launching i18n Agent
+
+The i18n agent will:
+1. **Detect existing i18n setup** — libraries, configs, locale files, translation patterns
+2. **Audit** — Find hardcoded strings, missing translations, inconsistent patterns
+3. **Report findings** with file:line references and proposed fixes
+4. **After confirmation** — Extract strings, create translation keys, set up infrastructure
+5. **Validate** after every change
+
+**Workflows**:
+- No argument → Full audit of i18n readiness + recommendations
+- `audit` → Scan for hardcoded strings and missing translations
+- `setup` → Set up i18n from scratch (detect framework, install library, create config)
+- `extract` → Extract hardcoded strings and replace with translation keys
+- `add-locale <locale>` → Add a new locale with translation stubs
+- `[file or component]` → Focused audit and extraction on specific files
+
+Use the Task tool to launch the i18n agent (subagent_type="i18n") with the scope and any additional context.

package/content/commands/implement.md

@@ -16,10 +16,10 @@ $ARGUMENTS
 
 ## Available Plans
 
-**Plans in tasks/plans/**:
-!`ls -1 tasks/plans/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 `tasks/plans/PLAN_{NAME}.md`
+- ✅ Load `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md`
 - ✅ Parse all phases, tasks, and dependencies
 - ✅ Create comprehensive task tracking (TodoWrite)
 - ✅ Execute tasks systematically with validation

package/content/commands/kickoff.md

@@ -17,12 +17,12 @@ $ARGUMENTS
 ## Available Plans
 
 **Active Plan**:
-!`cat tasks/STATE.md 2>/dev/null || echo "No active plan set"`
+!`cat {{STATE_FILE}} 2>/dev/null || echo "No active plan set"`
 
-**Plans in tasks/plans/**:
-!`ls -1 tasks/plans/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`
 
@@ -51,11 +51,15 @@ I'll work through this plan collaboratively with you:
 
 **This is collaborative implementation in the main conversation.**
 
+### Specialist Agents
+
+For tasks involving landing page / marketing page / homepage design, I'll suggest using the **showcase agent** (`/showcase`) which specializes in high-end page design with animations and micro-interactions. You can approve or override this.
+
 ---
 
 Now let me load the plan and we'll get started together.
 
-Use Read to load `tasks/plans/PLAN_{NAME}.md`, display a comprehensive summary with:
+Use Read to load `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md`, display a comprehensive summary with:
 - Objective
 - Phases and task counts
 - Key files involved