@allthingsclaude/blueprints 0.3.0-beta.22 → 0.3.0-beta.24

package/content/agents/audit.md

@@ -93,6 +93,20 @@ Go through each change systematically:
   - Type coercion bugs
 
 #### 🟡 Important Issues (Should Fix)
+- **Convention consistency**
+  - Do the changes introduce a different pattern for a concern the codebase already solves? (e.g., different styling method, different error feedback mechanism, different data fetching approach)
+  - Scan the codebase to identify authoritative patterns: styling method, error/notification system, state management, data fetching, component structure
+  - Flag any new code that uses a parallel approach for the same concern (e.g., inline styles in a CSS modules project, `alert()` in a project with a toast library, raw fetch in a project with custom hooks)
+  - Check that all new code is internally consistent (same approach used across all changed files)
+
+- **Accessibility** (for changes involving UI — components, pages, modals, forms, dialogs)
+  - Labels associated with inputs
+  - ARIA roles on overlays, modals, and interactive widgets
+  - Keyboard handling (Escape to close, focus trap in modals, Tab order)
+  - Visible focus indicators
+  - Color contrast (if new colors introduced)
+  - Screen reader considerations (meaningful alt text, aria-labels)
+
 - **DRY violations**
   - Duplicated code that should be extracted
   - Repeated logic across files
@@ -112,7 +126,7 @@ Go through each change systematically:
   - Missing error logging
 
 - **Performance issues**
-  - N+1 queries
+  - N+1 queries — per-item database calls inside loops or list transformations
   - Missing database indexes
   - Inefficient algorithms
   - Memory leaks
@@ -136,7 +150,6 @@ Go through each change systematically:
   - Missing const/readonly
   - Use of deprecated APIs
   - Suboptimal patterns
-  - Missing accessibility (a11y)
 
 - **Testing**
   - Missing test coverage for new code

package/content/agents/finalize.md

@@ -227,9 +227,6 @@ Files modified:
 - path/to/file.ts - what changed
 - path/to/other.ts - what changed
 
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-Co-Authored-By: Claude <noreply@anthropic.com>
 ```
 
 **Commit Message Guidelines**:
@@ -263,9 +260,6 @@ Files modified:
 - src/lib/jwt.ts - Token generation and validation
 - src/types/auth.ts - Auth type definitions
 
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-Co-Authored-By: Claude <noreply@anthropic.com>
 ```
 
 ```
@@ -285,9 +279,6 @@ Files modified:
 - src/components/FeaturedProduct.tsx - Now uses ProductCard
 - src/app/[domain]/products/ProductGrid.tsx - Simplified to use ProductCard
 
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-Co-Authored-By: Claude <noreply@anthropic.com>
 ```
 
 ### 8. Create Git Commit
@@ -317,9 +308,6 @@ Detailed explanation:
 Files modified:
 - path/file.ts - what changed
 
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
-Co-Authored-By: Claude <noreply@anthropic.com>
 EOF
 )"
 ```

package/content/agents/implement.md

@@ -37,6 +37,31 @@ Extract the plan name from the arguments (first word after /kickoff):
 - If file doesn't exist, list available plans and ask user to specify
 - Parse the plan structure (Objective, Phases, Tasks, Files)
 
+### 1.5 Discover Codebase Conventions
+
+Before writing any code, scan the existing codebase to understand established patterns. This prevents introducing inconsistent approaches (e.g., inline styles in a SCSS project, `alert()` in a project with a toast library).
+
+**What to look for:**
+- **Error handling / user feedback**: Search for toast libraries, error boundaries, notification systems, `alert(` usage
+- **Styling method**: Check for CSS modules (`.module.css`), SCSS (`.scss`), Tailwind, styled-components, inline styles — which is dominant?
+- **State management**: Context, stores, reducers, signals — what pattern does the project use?
+- **Component structure**: File naming, export patterns, colocation conventions
+- **Data fetching**: Custom hooks, direct API calls, query libraries — what's the established pattern?
+- **Test infrastructure**: Search for `describe(`, `it(`, `test(`, check for test config files — what framework exists and where do tests live?
+
+**Method**: Use Grep/Glob to sample patterns:
+```bash
+# Examples — adapt to the project
+grep -r "toast\|alert(" src/ --include="*.ts" --include="*.tsx" -l
+ls src/**/*.module.css src/**/*.scss 2>/dev/null
+grep -r "describe(\|it(\|test(" --include="*.test.*" -l
+```
+
+**Store findings** as a mental checklist to reference throughout implementation:
+- Note which patterns are **authoritative** (used consistently across the codebase) vs. **one-off** (used in a single file)
+- Authoritative patterns are mandatory to follow; one-offs can be ignored
+- If the project has no established pattern for a concern, note that too — you have freedom to choose
+
 ### 2. Initial Assessment
 
 Before starting implementation:
@@ -102,6 +127,9 @@ For each task in the current phase:
 - Run linter (if applicable, using detected package manager)
 - Check git diff to review changes
 - Verify the change works as expected
+- **Convention adherence**: Does this code follow the patterns discovered in Step 1.5? If the project uses a specific styling method, did you use it? If there's an established feedback/notification system, did you use it instead of a raw alternative? If there's a custom hook or data fetching pattern, did you follow it?
+- **Accessibility basics** (for UI tasks — modals, forms, dialogs, interactive elements): Labels associated with inputs, ARIA roles on overlays/modals, keyboard handling (Escape to close, focus trap in modals), visible focus indicators
+- **Data access patterns** (for tasks involving data fetching or transformation): No per-item queries inside loops or list iterations, batch operations where possible, efficient relationship loading
 
 #### D. Update Progress
 - Mark current task as `completed` in TodoWrite
@@ -133,7 +161,13 @@ At the end of each phase:
 1. **Run validation checks** from the plan's "Validation" section
 2. **Review all changes** in the phase: `git diff`
 3. **Run full checks**: typecheck and lint using the detected package manager
-4. **Ask user for approval** before moving to next phase:
+4. **Consistency review**: Before presenting to the user, review all code written in this phase as a cohesive whole. Check for:
+   - Same error handling approach across all new code
+   - Same styling method throughout
+   - No unnecessary duplication (e.g., identical handler functions across components that could be shared)
+   - Consistent component structure and naming
+   - If any inconsistencies are found, fix them before moving on
+5. **Ask user for approval** before moving to next phase:
 
 ```markdown
 🎯 **Phase 1 Complete**
@@ -253,6 +287,7 @@ Use Edit tool to update checkboxes in the plan.
 - Match existing code style and patterns
 - Use the same libraries and approaches as existing code
 - Check similar implementations in the codebase
+- When you encounter a concern that already has a solved pattern in the codebase (error feedback, styling, data fetching, state management), always use the existing pattern. Never introduce a parallel approach for the same concern — if the project uses a particular styling method, don't use inline styles; if it has a notification system, don't use `alert()`; if it has a data fetching pattern, don't make raw calls
 
 ### Handle Dependencies
 - If Task B depends on Task A, complete A first

package/content/agents/parallelize.md

@@ -65,7 +65,23 @@ Parse the plan and create a comprehensive task list:
 | T4 | Add settings component | 2 | src/components/Settings.tsx | None |
 ```
 
-#### 1.3 Build Dependency Graph
+#### 1.3 Discover Codebase Conventions
+
+Before partitioning work, scan the existing codebase to understand established patterns. These conventions will be injected into every stream prompt so all agents produce consistent code.
+
+**Scan for:**
+- **Error handling / user feedback**: Toast libraries, error boundaries, notification systems vs. raw `alert()`
+- **Styling method**: CSS modules, SCSS, Tailwind, styled-components, inline styles — which is dominant?
+- **State management**: Context, stores, reducers, signals — what pattern does the project use?
+- **Data fetching**: Custom hooks, direct API calls, query libraries
+- **Component structure**: File naming, export patterns, colocation conventions
+- **Test infrastructure**: Test framework, file naming conventions (`.test.`, `.spec.`), test location
+
+**Method**: Use Grep/Glob to sample patterns across the codebase. Note which patterns are authoritative (used consistently) vs. one-off.
+
+Store these findings — they'll be included in every stream prompt in Phase 3.
+
+#### 1.4 Build Dependency Graph
 
 Identify dependencies between tasks:
 
@@ -84,7 +100,7 @@ T4 (independent)
 - **File**: Tasks modify the same file (MUST be sequential)
 - **Logical**: Task B assumes Task A's changes exist
 
-#### 1.4 Identify File Conflicts
+#### 1.5 Identify File Conflicts
 
 ```bash
 # For each task, list files it will modify
@@ -168,6 +184,12 @@ You are implementing Stream [N] of a parallelized plan execution.
    - Details: [What to implement]
    - Validation: [How to verify]
 
+## Codebase Conventions (MUST follow)
+
+[Inject discovered conventions from Phase 1.3 here — e.g., "This project uses SCSS modules for styling (not inline styles)", "Error feedback uses the toast system (not alert())", "Data fetching uses custom hooks in src/hooks/", "Tests use Vitest and live in __tests__/ directories"]
+
+These are authoritative patterns from the existing codebase. Always follow them — never introduce a parallel approach for the same concern.
+
 ## Important Context
 
 - Other streams are running in parallel
@@ -299,7 +321,17 @@ git status
 git diff --stat
 ```
 
-#### 5.3 Conflict Resolution
+#### 5.3 Cross-Stream Consistency Review
+
+After type check and lint pass, review code from all streams for pattern alignment. Different agents may have solved the same concern differently despite receiving convention instructions. Check for:
+- **Styling consistency**: All streams using the same styling approach
+- **Error handling consistency**: Same feedback/notification pattern across streams
+- **Component structure**: Consistent naming, export patterns, file organization
+- **Data patterns**: Same fetching/state management approach
+
+If any drift is found between streams, fix it to match the project's established conventions before reporting results.
+
+#### 5.4 Conflict Resolution
 
 If conflicts exist (shouldn't if partitioning was correct):
 1. Identify conflicting changes
@@ -307,7 +339,7 @@ If conflicts exist (shouldn't if partitioning was correct):
 3. Apply manual fix
 4. Document what happened
 
-#### 5.4 Update Plan
+#### 5.5 Update Plan
 
 Mark completed tasks in the plan document:
 

package/content/commands/auto.md

@@ -254,12 +254,28 @@ Review security report:
 **COMMIT CHECKPOINT**: If security fixes were made, commit them:
 - Use the commit agent with context: "fix: address security findings for {NAME}"
 
+#### 5d. Accessibility
+
+**Conditional** — only when frontend/UI code was modified in this plan.
+
+**Detection**: Check if any modified files (from `git diff --name-only main...HEAD` or the plan's file list) are in typical frontend paths (`.tsx`, `.jsx`, `.vue`, `.svelte`, `.html`, component directories).
+
+- **If frontend code exists**: Use the Task tool to launch the a11y agent (`subagent_type="a11y"`).
+  - Review the a11y report
+  - If critical findings → attempt auto-fix (max 2 retries)
+  - If still failing → report to user and ask whether to proceed
+- **If no frontend code was touched**: Skip with note "No frontend changes — skipping accessibility audit"
+
+**COMMIT CHECKPOINT**: If accessibility fixes were made, commit them:
+- Use the commit agent with context: "fix: address accessibility findings for {NAME}"
+
 **If ALL validation passes cleanly**, report:
 ```markdown
 **Validation Complete**
 - Audit: Passed
 - Tests: Passed
 - Security: Passed
+- Accessibility: Passed (or Skipped — no frontend changes)
 ```
 
 ---
@@ -337,7 +353,7 @@ Auto mode commits **early and often** using the commit agent (`subagent_type="co
 - Never force-push, delete branches, or make destructive changes without asking
 
 ### Compose Existing Agents
-- Use the existing subagent types: `bootstrap`, `plan`, `implement`, `parallelize`, `showcase`, `audit`, `test`, `secure`, `commit`, `update`
+- Use the existing subagent types: `bootstrap`, `plan`, `implement`, `parallelize`, `showcase`, `audit`, `test`, `secure`, `a11y`, `commit`, `update`
 - Do NOT try to do their jobs inline — delegate to specialists
 - Always use the commit agent for commits — it writes proper conventional commit messages (`feat:`, `fix:`, `refactor:`, etc.)
 

package/content/commands/commit.md

@@ -40,6 +40,8 @@ The commit agent will:
 - Stage the relevant files and create the commit
 - Verify the commit was created successfully
 
+**IMPORTANT: Do NOT add a `Co-Authored-By` line to the commit message.**
+
 **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/history.md

@@ -0,0 +1,72 @@
+---
+description: Tell the narrative story of a file or function through its git history
+argument-hint: <file path> [optional: :function or symbol name]
+author: "@markoradak"
+---
+
+# File History
+
+Investigating the history of: **$ARGUMENTS**
+
+> **When to use**: You want to understand how a file evolved over time — who created it, what major changes shaped it, and whether it's a hot spot or stable code.
+
+## Context
+
+**Working Directory**: !`pwd`
+
+**File Exists**: !`test -f "$ARGUMENTS" && echo "Yes" || echo "File not found — check the path"`
+
+**File Size**: !`wc -l < "$ARGUMENTS" 2>/dev/null || echo "N/A"`
+
+## Git History
+
+**Full Log (following renames)**:
+!`git log --follow --format="%h|%an|%ar|%s" -- "$ARGUMENTS" 2>/dev/null || echo "No git history available"`
+
+**File Creation**:
+!`git log --follow --diff-filter=A --format="%h %an (%ar): %s" -- "$ARGUMENTS" 2>/dev/null || echo "Unable to determine creation"`
+
+**Contributors**:
+!`git log --follow --format="%an" -- "$ARGUMENTS" 2>/dev/null | sort | uniq -c | sort -rn || echo "N/A"`
+
+**Recent Activity (last 30 days)**:
+!`git log --since="30 days ago" --follow --format="%h %s (%ar)" -- "$ARGUMENTS" 2>/dev/null || echo "No recent changes"`
+
+**Change Frequency**:
+!`echo "Total commits: $(git log --follow --oneline -- "$ARGUMENTS" 2>/dev/null | wc -l | tr -d ' ')"`
+
+---
+
+## Instructions
+
+Using the git history data above, tell the story of this file as a narrative. Don't just list commits — interpret the history.
+
+### 1. Origin
+
+When was the file created, by whom, and why? Use the creation commit message and context to explain what purpose it originally served.
+
+### 2. Evolution
+
+Group commits into phases or themes. For example:
+- "Initial implementation" (first few commits)
+- "Feature expansion" (when significant functionality was added)
+- "Refactoring" (structural changes without new features)
+- "Bug fixes" (corrections and patches)
+
+Summarize each phase in 1-2 sentences rather than listing individual commits.
+
+### 3. Key Contributors
+
+Who has shaped this file the most? Mention the top 2-3 contributors and what kind of work each contributed.
+
+### 4. Current State
+
+- **Activity level** — Is this file actively changing or has it stabilized?
+- **Hot spot or stable?** — High commit frequency = hot spot (may need attention). Low frequency = stable (likely reliable).
+- **Size context** — Is the file large enough to consider splitting?
+
+### 5. Function Focus (if specified)
+
+If `$ARGUMENTS` includes a `:function` or symbol name after the file path, narrow the story to just that symbol. Use `git log -p` mentally to focus on commits that touched that specific function.
+
+**This is read-only. Do not modify any files.**

package/content/commands/kickoff.md

@@ -36,11 +36,12 @@ I'll work through this plan collaboratively with you:
 
 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
+3. **Convention Discovery**: Scan the codebase for established patterns (error handling, styling, state management, data fetching, test infrastructure) and share findings so we're aligned on which patterns to follow
+4. **Task Tracking**: Set up TodoWrite for all plan tasks
+5. **Step-by-Step**: Execute tasks one at a time with your input
+6. **Validation**: Run type checks and lints after each task
+7. **Phase Approval**: Ask before moving between phases
+8. **Adapt Together**: Discuss blockers and adjustments as we go
 
 ### Your Role
 
@@ -59,6 +60,8 @@ For tasks involving landing page / marketing page / homepage design, I'll sugges
 
 Now let me load the plan and we'll get started together.
 
+**Before implementing**, scan the codebase for established conventions (error handling approach, styling method, state management, data fetching patterns, test infrastructure). Share the findings with the user so you're aligned on which patterns to follow throughout implementation. Use Grep/Glob to sample patterns — look for things like toast/notification usage, CSS module vs SCSS vs inline patterns, custom hooks, test frameworks, etc. Present a brief summary of discovered conventions before starting tasks.
+
 Use Read to load `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md`, display a comprehensive summary with:
 - Objective
 - Phases and task counts

package/content/commands/standup.md

@@ -0,0 +1,71 @@
+---
+description: Generate a standup summary from recent git activity
+argument-hint: [optional: timeframe like "3 days" or "this week"]
+author: "@markoradak"
+---
+
+# Standup Summary
+
+Generating a standup summary from recent activity.
+
+> **When to use**: You need a quick done/doing/next summary for a standup meeting, status update, or just to remind yourself what you've been working on.
+
+## Recent Activity
+
+**Current Branch**: !`git branch --show-current 2>/dev/null || echo "Not a git repository"`
+
+**Author**: !`git config user.name 2>/dev/null || echo "Unknown"`
+
+**Commits (last 48 hours)**:
+!`git log --since="48 hours ago" --author="$(git config user.name)" --format="%h %s (%ar)" 2>/dev/null || echo "No recent commits"`
+
+**Uncommitted Changes**:
+!`git diff --stat 2>/dev/null || echo "None"`
+
+**Staged Changes**:
+!`git diff --cached --stat 2>/dev/null || echo "None"`
+
+**Stashed Work**:
+!`git stash list 2>/dev/null || echo "No stashes"`
+
+**Active Plan Files**:
+!`ls -1 {{TASKS_DIR}}/*.md 2>/dev/null || echo "No plan files found"`
+
+## Timeframe Override
+
+$ARGUMENTS
+
+---
+
+## Instructions
+
+Using the activity data above, generate a clean standup summary in this format:
+
+### Output Format
+
+```markdown
+## Standup — [date]
+
+### Done
+- [completed work items from commits, grouped by theme]
+
+### In Progress
+- [current branch context and uncommitted changes]
+
+### Up Next
+- [items from plan files, or next logical steps]
+```
+
+### Rules
+
+1. **Done** — Synthesize commits into meaningful work items. Don't list every commit — group related commits into a single bullet (e.g., three auth-related commits become "Implemented user authentication flow"). Use the commit messages to understand what was accomplished.
+
+2. **In Progress** — Describe what the current branch and uncommitted changes suggest you're working on. If there are stashes, mention them as paused work.
+
+3. **Up Next** — Pull from plan files if they exist. If not, infer reasonable next steps from the in-progress work or leave as "TBD — no active plan."
+
+4. **Timeframe** — If `$ARGUMENTS` specifies a different timeframe (e.g., "3 days", "this week"), adjust the "Done" section scope accordingly. The shell commands captured the last 48 hours; if the user wants a wider window, note that some older work may not appear.
+
+5. **Tone** — Keep it concise and factual. No filler. Ready to paste into Slack or Teams.
+
+**This is read-only. Do not modify any files.**

package/content/commands/todo.md

@@ -0,0 +1,64 @@
+---
+description: Scan codebase for TODO/FIXME/HACK markers and present an organized summary
+argument-hint: [optional: directory, file, or keyword to filter]
+author: "@markoradak"
+---
+
+# TODO Scanner
+
+Scanning the codebase for code markers and annotations.
+
+> **When to use**: You want a quick overview of outstanding TODOs, FIXMEs, and other code markers scattered across the project — without grepping manually.
+
+## Current State
+
+**Working Directory**: !`pwd`
+
+**Git Root**: !`git rev-parse --show-toplevel 2>/dev/null || echo "Not a git repository"`
+
+## Marker Scan
+
+**High Priority (FIXME, HACK, XXX)**:
+!`git grep -rn -E '\b(FIXME|HACK|XXX)\b' -- ':!node_modules' ':!.git' 2>/dev/null || grep -rn -E '\b(FIXME|HACK|XXX)\b' --include='*' --exclude-dir=node_modules --exclude-dir=.git . 2>/dev/null || echo "No high-priority markers found"`
+
+**Standard (TODO, TASK, TEMP, DEPRECATED)**:
+!`git grep -rn -E '\b(TODO|TASK|TEMP|DEPRECATED)\b' -- ':!node_modules' ':!.git' 2>/dev/null || grep -rn -E '\b(TODO|TASK|TEMP|DEPRECATED)\b' --include='*' --exclude-dir=node_modules --exclude-dir=.git . 2>/dev/null || echo "No standard markers found"`
+
+**Informational (NOTE, WARN)**:
+!`git grep -rn -E '\b(NOTE|WARN)\b' -- ':!node_modules' ':!.git' 2>/dev/null || grep -rn -E '\b(NOTE|WARN)\b' --include='*' --exclude-dir=node_modules --exclude-dir=.git . 2>/dev/null || echo "No informational markers found"`
+
+## User Filter
+
+$ARGUMENTS
+
+---
+
+## Instructions
+
+Using the marker scan results above, present an organized summary:
+
+### 1. Summary counts
+
+Show a table of marker types and their total counts. Order by priority: FIXME > HACK > XXX > TODO > TASK > TEMP > DEPRECATED > NOTE > WARN.
+
+### 2. Organize by priority
+
+Group results into three tiers:
+- **Needs attention** — FIXME, HACK, XXX (things that are broken or fragile)
+- **Planned work** — TODO, TASK, TEMP, DEPRECATED (things that need doing)
+- **Informational** — NOTE, WARN (context for future readers)
+
+Within each tier, group by file or directory so related items stay together.
+
+### 3. Apply user filter
+
+If `$ARGUMENTS` was provided, filter results to only show markers matching that directory, file, or keyword. Ignore results outside the filter scope.
+
+### 4. Highlight patterns
+
+Call out anything notable:
+- Files with an unusually high concentration of markers
+- Very old TODOs (if recognizable from surrounding context)
+- FIXMEs that reference specific bugs or issues
+
+**This is read-only. Do not modify any files.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allthingsclaude/blueprints",
-  "version": "0.3.0-beta.22",
+  "version": "0.3.0-beta.24",
   "description": "Claude Code commands and agents for enhanced AI-assisted development workflows",
   "type": "module",
   "main": "dist/index.js",