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

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/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/package.json

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