aiblueprint-cli 1.4.38 → 1.4.40

package/README.md

@@ -136,6 +136,38 @@ npx aiblueprint-cli@latest claude-code symlink
 - `cc` - Claude Code with permissions skipped
 - `ccc` - Claude Code with continue mode
 
+### Skills
+
+Install individual skills directly into `~/.claude/skills/`:
+
+```bash
+# Install a single skill
+npx skills add Melvynx/aiblueprint --skill ultrathink
+
+# Install multiple skills
+npx skills add Melvynx/aiblueprint --skill claude-memory
+npx skills add Melvynx/aiblueprint --skill fix-errors
+```
+
+**Available skills:**
+
+| Skill | Description |
+|-------|-------------|
+| `commit` | Quick commit and push with clean messages |
+| `create-pr` | Auto-generated pull requests |
+| `fix-pr-comments` | Resolve PR review comments |
+| `merge` | Context-aware branch merging |
+| `claude-memory` | CLAUDE.md and .claude/rules management |
+| `prompt-creator` | Expert prompt engineering |
+| `skill-creator` | Guide for creating Claude Code skills |
+| `subagent-creator` | Guide for building subagents |
+| `ralph-loop` | Autonomous AI coding loop |
+| `fix-errors` | Fix ESLint and TypeScript errors |
+| `fix-grammar` | Fix grammar and spelling |
+| `oneshot` | Ultra-fast feature implementation |
+| `ultrathink` | Deep thinking mode for elegant solutions |
+| `apex-free` | APEX methodology (Analyze-Plan-Execute-eXamine) |
+
 ## 💎 Premium
 
 Unlock advanced features at [mlv.sh/claude-cli](https://mlv.sh/claude-cli)

package/claude-code-config/skills/meta-claude-memory/SKILL.md

@@ -1,694 +1,235 @@
 ---
 name: claude-memory
 description: Create and optimize CLAUDE.md memory files or .claude/rules/ modular rules for Claude Code projects. Comprehensive guidance on file hierarchy, content structure, path-scoped rules, best practices, and anti-patterns. Use when working with CLAUDE.md files, .claude/rules directories, setting up new projects, or improving Claude Code's context awareness.
-argument-hint: [task description]
+argument-hint: [task description or "optimize"]
 ---
 
-<objective>
-Master the creation of effective Claude Code memory systems using either CLAUDE.md files or the modular `.claude/rules/` directory. This skill covers file hierarchy, content structure, path-scoped rules, formatting, emphasis techniques, and common anti-patterns to avoid.
+<core_principle>
+Memory files consume tokens from the context window. ~100-150 instruction slots available for your customizations. Keep files minimal — only include what the agent cannot discover on its own.
 
-Memory files are automatically loaded at session startup, consuming tokens from your 200k context window. Every instruction competes with Claude Code's ~50 built-in instructions, leaving ~100-150 effective instruction slots for your customizations.
-
-**Two approaches available:**
-
-- **CLAUDE.md** - Single file, simpler, best for small projects
-- **.claude/rules/** - Modular files with optional path-scoping, best for large projects
-  </objective>
+**Two approaches:**
+- **CLAUDE.md** — Single file, best for small projects (< 100 lines)
+- **.claude/rules/** — Modular files with optional path-scoping, best for large projects
+</core_principle>
 
 <quick_start>
-<bootstrap_new_project>
-Run `/init` in Claude Code to auto-generate a CLAUDE.md with project structure.
-
-Or create manually at project root:
+Run `/init` to auto-generate a CLAUDE.md. Or create manually:
 
 ```markdown
 # Project Name
 
 ## Tech Stack
-
-- [Primary language/framework]
-- [Key libraries]
+- [Primary framework]
+- [Key non-obvious libraries]
 
 ## Commands
-
-- `npm run dev` - Start development
+- `npm run dev` - Dev server
 - `npm test` - Run tests
-- `npm run build` - Build for production
-
-## Code Conventions
+- `npm run build` - Build
 
-- [2-3 critical conventions]
-
-## Important Context
-
-- [1-2 architectural decisions worth knowing]
+## Rules
+- [2-3 critical project-specific rules]
 ```
 
-</bootstrap_new_project>
-
-<quick_add_memory>
-Press `#` during a Claude Code session to quickly add new memory items without editing the file directly.
-</quick_add_memory>
-
-<edit_memory>
-Use `/memory` command to open CLAUDE.md in your system editor.
-</edit_memory>
+- Press `#` during a session to add memory items quickly
+- Use `/memory` to open CLAUDE.md in your editor
 </quick_start>
 
 <file_hierarchy>
-Claude Code loads CLAUDE.md files in a specific order. Higher priority files are loaded first and take precedence.
-
-<loading_order>
-| Priority | Location | Purpose | Scope |
-|----------|----------|---------|-------|
-| 1 (Highest) | `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS) | Enterprise policy (managed by IT) | All org users |
-| 2 | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Project memory (git-tracked) | Team via git |
-| 2 | `./.claude/rules/*.md` | Modular rules (git-tracked) | Team via git |
-| 3 | `~/.claude/CLAUDE.md` | User preferences (global) | All your projects |
-| 3 | `~/.claude/rules/*.md` | Personal modular rules (global) | All your projects |
-| 4 (Lowest) | `./CLAUDE.local.md` | Personal project prefs (auto-gitignored) | Just you |
-</loading_order>
 
-<recursive_loading>
-Claude recurses UP from current directory to root, loading all CLAUDE.md files found.
+| Priority | Location | Scope |
+|----------|----------|-------|
+| 1 (Highest) | Enterprise policy (managed by IT) | All org users |
+| 2 | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Team via git |
+| 2 | `./.claude/rules/*.md` | Team via git |
+| 3 | `~/.claude/CLAUDE.md` | All your projects |
+| 3 | `~/.claude/rules/*.md` | All your projects |
+| 4 (Lowest) | `./CLAUDE.local.md` (auto-gitignored) | Just you |
 
-Running Claude in `foo/bar/` loads:
-
-1. `foo/bar/CLAUDE.md`
-2. `foo/CLAUDE.md`
-3. Root-level files
-
-Claude also discovers CLAUDE.md in SUBTREES when reading files in those directories.
-</recursive_loading>
-
-<monorepo_strategy>
-For monorepos, use layered approach:
+Claude recurses UP from current directory, loading all CLAUDE.md files found. Also discovers CLAUDE.md in subtrees when reading files in those directories.
 
+**Monorepo strategy:** Root file defines WHEN; subtree files define HOW.
 ```
-root/
-├── CLAUDE.md              # Universal: tech stack, git workflow
-├── apps/
-│   ├── web/CLAUDE.md      # Frontend-specific patterns
-│   └── api/CLAUDE.md      # Backend-specific patterns
-└── packages/
-    └── shared/CLAUDE.md   # Shared library conventions
+root/CLAUDE.md           # Universal: tech stack, git workflow
+apps/web/CLAUDE.md       # Frontend-specific
+apps/api/CLAUDE.md       # Backend-specific
 ```
-
-Root file defines WHEN to use patterns; subtree files define HOW.
-</monorepo_strategy>
 </file_hierarchy>
 
 <rules_directory>
-The `.claude/rules/` directory provides a **modular alternative** to monolithic CLAUDE.md files. Instead of one large file, you organize instructions into multiple focused markdown files.
-
-<when_to_use_rules>
-**Use `.claude/rules/` when:**
-
-- Project has many distinct concerns (testing, security, API, frontend)
-- Different rules apply to different file types
-- Team members maintain different areas
-- You want to update one concern without touching others
+The `.claude/rules/` directory splits instructions into focused markdown files.
 
-**Use CLAUDE.md when:**
-
-- Project is small/simple
-- All rules are universal
-- You prefer a single source of truth
-  </when_to_use_rules>
-
-<rules_structure>
-
-```
-.claude/rules/
-├── code-style.md      # Formatting and conventions
-├── testing.md         # Test requirements
-├── security.md        # Security checklist
-├── frontend/
-│   ├── react.md       # React-specific patterns
-│   └── styles.md      # CSS conventions
-└── backend/
-    ├── api.md         # API development rules
-    └── database.md    # Database conventions
-```
-
-**Key points:**
-
-- All `.md` files are discovered recursively
-- No imports or configuration needed
-- Same priority as CLAUDE.md
-- Supports symlinks for sharing rules across projects
-  </rules_structure>
-
-<path_scoped_rules>
-Rules can be scoped to specific files using YAML frontmatter:
+**Use `.claude/rules/` when:** many concerns, different rules for different file types, team maintains different areas.
+**Use CLAUDE.md when:** small project, universal rules, single source of truth.
 
+Path-scoped rules use YAML frontmatter:
 ```yaml
 ---
 paths:
   - "src/api/**/*.ts"
 ---
-# API Development Rules
-
-- All API endpoints must include input validation
-- Use the standard error response format
+# API Rules
+- All endpoints must include input validation
 ```
 
-**Path patterns supported:**
-
-| Pattern                | Matches                                    |
-| ---------------------- | ------------------------------------------ |
-| `**/*.ts`              | All TypeScript files in any directory      |
-| `src/**/*`             | All files under `src/` directory           |
-| `src/components/*.tsx` | React components in specific directory     |
-| `src/**/*.{ts,tsx}`    | TypeScript and TSX files (brace expansion) |
-| `{src,lib}/**/*.ts`    | Files in multiple directories              |
-
-**Syntax note:** The `paths` field must be a YAML array (list format with `-` prefix and quoted strings).
-
-**Rules without `paths` frontmatter** load unconditionally for all files.
-</path_scoped_rules>
-
-<user_level_rules>
-Create personal rules that apply to all your projects:
-
-```
-~/.claude/rules/
-├── preferences.md    # Your coding preferences
-├── workflows.md      # Your preferred workflows
-└── git.md            # Your git conventions
-```
+Supported patterns: `**/*.ts`, `src/**/*`, `src/**/*.{ts,tsx}`, `{src,lib}/**/*.ts`
 
-User-level rules load before project rules, giving project rules higher priority for overrides.
-</user_level_rules>
+Rules without `paths` frontmatter load unconditionally.
 
-<symlinks_support>
-Share common rules across multiple projects using symlinks:
-
-```bash
-# Symlink a shared rules directory
-ln -s ~/shared-claude-rules .claude/rules/shared
-
-# Symlink individual rule files
-ln -s ~/company-standards/security.md .claude/rules/security.md
-```
-
-Circular symlinks are detected and handled gracefully.
-</symlinks_support>
+See [references/rules-directory-guide.md](references/rules-directory-guide.md) for complete guide including symlinks, user-level rules, and migration.
 </rules_directory>
 
-<content_framework>
-Structure your CLAUDE.md using the WHAT-WHY-HOW framework:
-
-**WHAT** - Project Context: Tech stack, directory structure, architecture
-**WHY** - Purpose: Architectural decisions, why patterns exist
-**HOW** - Workflow: Commands, testing, git workflow, verification steps
-
-```markdown
-## Tech Stack
-
-- Next.js 15 with App Router
-- PostgreSQL via Prisma ORM
-
-## Architecture Decisions
-
-- Server Components for data fetching
-- All forms use TanStack Form
-
-## Commands
-
-- `pnpm dev` - Start dev server
-- `pnpm test:ci` - Run tests
-- `pnpm build` - Production build
-
-## Git Workflow
-
-- Branch: `feature/name` or `fix/name`
-- Run tests before committing
-```
-
-See [references/section-templates.md](references/section-templates.md) for complete templates.
-</content_framework>
-
-<emphasis_techniques>
-Claude follows emphasized instructions more reliably. Use these techniques strategically for critical rules.
-
-<keyword_hierarchy>
-Use emphasis keywords in order of severity:
-
-| Keyword       | Use For               | Example                                      |
-| ------------- | --------------------- | -------------------------------------------- |
-| **CRITICAL**  | Non-negotiable rules  | `**CRITICAL**: Never commit secrets`         |
-| **NEVER**     | Absolute prohibitions | `NEVER: Push directly to main`               |
-| **ALWAYS**    | Mandatory behaviors   | `ALWAYS: Run tests before pushing`           |
-| **IMPORTANT** | Significant guidance  | `IMPORTANT: Keep components under 300 lines` |
-| **YOU MUST**  | Explicit requirements | `YOU MUST: Use TanStack Form for forms`      |
-
-</keyword_hierarchy>
-
-<formatting_patterns>
-**Bold + CRITICAL keyword:**
-
-```markdown
-**CRITICAL**: Always run tests before pushing code
-```
-
-**Capitalized emphasis:**
-
-```markdown
-IMPORTANT: Do not commit environment variables
-YOU MUST: Follow the git workflow outlined below
-NEVER: Include API keys in code
-ALWAYS: Use TypeScript strict mode
-```
-
-**Strikethrough for forbidden options:**
-
-```markdown
-- `pnpm test:ci` - Run tests (use this)
-- ~~`pnpm test`~~ - NEVER use (interactive mode)
-```
-
-**Visual markers (use sparingly):**
-
-```markdown
-⚠️ WARNING: This affects production data
-🔒 SECURITY: Never commit secrets to git
-```
-
-</formatting_patterns>
-
-<placement_strategy>
-Order matters. Claude pays more attention to:
-
-1. **First items** in each section (put critical rules first)
-2. **Repeated items** across sections (repeat critical rules in context)
-3. **Emphasized items** with CRITICAL/NEVER/ALWAYS keywords
-
-Structure your file with critical rules first:
-
-```markdown
-## Code Conventions
-
-### Critical Rules
-
-- **NEVER** commit .env files
-- **ALWAYS** run tests before pushing
-- **CRITICAL**: Use TanStack Form for ALL forms
-
-### General Guidelines
-
-- Prefer Server Components
-- Keep components under 300 lines
-```
-
-</placement_strategy>
-
-<repetition_for_emphasis>
-For extremely important rules, repeat in multiple relevant contexts:
-
-```markdown
-## Forms
-
-**CRITICAL**: Use TanStack Form for ALL forms
-
-## Before Editing
-
-- **CRITICAL**: Use TanStack Form for forms
-
-## Code Review Checklist
-
-- [ ] Forms use TanStack Form (**CRITICAL**)
-```
-
-</repetition_for_emphasis>
-</emphasis_techniques>
-
-<writing_effective_instructions>
-<golden_rule>
-Show your CLAUDE.md to someone with minimal project context. If they're confused, Claude will be too.
-</golden_rule>
-
-<be_specific>
-Vague instructions cause inconsistent behavior:
-
-```markdown
-❌ VAGUE:
-
-- Format code properly
-- Write good tests
-- Follow best practices
-
-✅ SPECIFIC:
-
-- Run `pnpm lint` before committing (Prettier configured)
-- Write tests in `__tests__/` using Vitest
-- Use TanStack Form for all forms (see `src/features/form/`)
-```
+<content_structure>
+Structure CLAUDE.md with only these sections:
 
-</be_specific>
+1. **Project purpose** (1-3 lines) — What the project is
+2. **Tech stack** (compact) — Only non-obvious technologies
+3. **Commands** — Non-obvious dev, build, and test commands
+4. **Important files** — Architecture-critical, non-obvious files only
+5. **Rules** — Prohibitions and constraints that prevent mistakes (highest-value lines)
+6. **Workflow** (optional) — Only if non-standard
 
-<show_dont_tell>
-When format matters, show examples:
+**Do NOT include:**
+- Repository overviews (agent discovers structure itself)
+- Code style rules (linters enforce these)
+- Generic best practices ("write clean code", "DRY", "SOLID")
+- Redundant specs (copies of config files, env vars, schema descriptions)
+- Marketing/goals (vision statements, KPIs, roadmaps)
+- Verbose explanations (paragraphs where one line suffices)
 
-```markdown
-❌ TELLING:
-Use conventional commits with type and description.
+See [references/section-templates.md](references/section-templates.md) for ready-to-use templates.
+See [references/project-patterns.md](references/project-patterns.md) for framework-specific patterns.
+</content_structure>
 
-✅ SHOWING:
+<writing_rules>
+**Golden rule:** If someone with zero project context reads your CLAUDE.md and gets confused, Claude will too.
 
-## Commit Format
+**Be specific, never vague:**
 ```
-
-feat(auth): implement JWT authentication
-
-Add login endpoint and token validation
-
-```
-Types: feat, fix, refactor, docs, test, chore
-```
-
-</show_dont_tell>
-
-<eliminate_ambiguity>
-Replace vague phrases with clear directives:
-
-| Ambiguous            | Clear Alternative                   |
-| -------------------- | ----------------------------------- |
-| "Try to..."          | "Always..." or "Never..."           |
-| "Should probably..." | "Must..." or "May optionally..."    |
-| "Generally..."       | "Always... except when [condition]" |
-| "Consider..."        | "If [condition], then [action]"     |
-
-</eliminate_ambiguity>
-
-<define_edge_cases>
-Anticipate questions and answer them:
-
-```markdown
-❌ INCOMPLETE:
-Run tests before pushing.
-
-✅ COMPLETE:
-
-## Testing
-
-- Run `pnpm test:ci` before pushing
-- If tests fail, fix before committing
-- New features require tests in `__tests__/`
-- Minimum 80% coverage for new code
-```
-
-</define_edge_cases>
-
-<provide_decision_criteria>
-When Claude must make choices, give criteria:
-
-```markdown
-## Component Choice
-
-**Use Server Component when:**
-
-- Data fetching only
-- No user interaction needed
-
-**Use Client Component when:**
-
-- User interaction required
-- Browser APIs needed (localStorage, window)
-```
-
-</provide_decision_criteria>
-
-<separate_obligation_levels>
-Clearly distinguish requirements from suggestions:
-
-```markdown
-## API Development
-
-### Must Have
-
-- Input validation with Zod
-- Error handling for all endpoints
-
-### Nice to Have
-
-- Pagination for list endpoints
-- Caching headers
-
-### Must Not
-
-- Expose internal errors to clients
-- Log sensitive data
+❌ "Format code properly" / "Write good tests" / "Follow best practices"
+✅ "Run `pnpm lint` before committing" / "Tests in `__tests__/` using Vitest"
 ```
 
-</separate_obligation_levels>
-</writing_effective_instructions>
-
-<size_constraints>
-<limits>
-
-- **Ideal**: 100-200 lines maximum
-- **Practical max**: 300 lines before splitting
-- **Universal items**: Under 60 lines
-
-**Why these limits matter:**
-
-- Claude reliably follows ~150-200 total instructions
-- Claude Code's system prompt uses ~50 instructions
-- Leaves ~100-150 slots for YOUR instructions
-- Irrelevant content degrades instruction-following
-  </limits>
-
-<scaling_strategy>
-When exceeding limits:
-
-1. Move task-specific details to separate files
-2. Link from CLAUDE.md with descriptions
-3. Use progressive disclosure pattern
-
-```markdown
-## Detailed Guides
-
-- **API Routes**: See [docs/api-patterns.md](docs/api-patterns.md)
-- **Testing**: See [docs/testing-guide.md](docs/testing-guide.md)
-- **Deployment**: See [docs/deployment.md](docs/deployment.md)
+**Prohibitions > positive guidance:**
 ```
-
-</scaling_strategy>
-</size_constraints>
-
-<imports_feature>
-CLAUDE.md supports importing other markdown files:
-
-```markdown
-## External References
-
-@docs/coding-standards.md
-@~/.claude/my-global-preferences.md
-@./team-conventions.md
+❌ "Try to use TanStack Form for forms"
+✅ "NEVER use native form/useState for forms — ALWAYS use TanStack Form"
 ```
 
-<import_rules>
+**Show, don't tell:** When format matters, show a concrete example (3-5 lines max).
 
-- Supports relative and absolute paths
-- Home directory expansion with `~`
-- Recursive imports up to 5 levels deep
-- NOT evaluated inside code blocks or backticks
-  </import_rules>
-  </imports_feature>
+**Emphasis hierarchy:** CRITICAL > NEVER > ALWAYS > IMPORTANT > YOU MUST
+- Put critical rules **first** in each section
+- Use **bold + keyword** for non-negotiable rules: `**CRITICAL**: Never commit secrets`
 
-<anti_patterns>
-<never_include>
-**Code Style Rules** - Use linters instead (LLMs are expensive, linters are free)
+See [references/prompting-techniques.md](references/prompting-techniques.md) for advanced techniques.
+</writing_rules>
 
-**Secrets** - NEVER include API keys, database URLs, tokens, credentials
-
-**Too Much Content** - Link to docs instead of embedding 500+ lines
-
-**Extensive Code** - Reference files instead (code examples become outdated)
-
-**Vague Instructions** - Be specific (see `<writing_effective_instructions>`)
-</never_include>
-
-<examples_what_to_avoid>
+<size_limits>
+- **Ideal:** < 100 lines
+- **Maximum:** 150 lines before performance degrades
+- **Over 200 lines:** directives start getting lost
 
+When exceeding limits, split into `.claude/rules/` files or link to separate docs:
 ```markdown
-❌ BAD:
-
-- Use 2-space indentation (use Prettier instead)
-- DATABASE_URL=postgresql://... (never include secrets)
-- [500 lines of API docs] (link to external file)
-- Format code properly (too vague)
-
-✅ GOOD:
-
-- ESLint/Prettier configured (see .eslintrc)
-- Credentials in `.env` (never committed)
-- API guide: See [docs/api.md](docs/api.md)
-- Run `pnpm lint` before committing
+- **API patterns**: See [docs/api-patterns.md](docs/api-patterns.md)
+- **Testing guide**: See [docs/testing-guide.md](docs/testing-guide.md)
 ```
 
-</examples_what_to_avoid>
-</anti_patterns>
-
-<examples>
-For complete examples, see reference files:
-
-- **Minimal example**: [references/section-templates.md](references/section-templates.md) (templates section)
-- **Comprehensive SaaS**: [references/comprehensive-example.md](references/comprehensive-example.md)
-- **Project-specific**: [references/project-patterns.md](references/project-patterns.md) (Next.js, Express, Python, Monorepo)
-  </examples>
+CLAUDE.md supports importing: `@docs/coding-standards.md` (relative/absolute paths, `~` expansion, up to 5 levels deep, not evaluated inside code blocks).
+</size_limits>
 
 <workflow>
-<decision_point>
 **ALWAYS ASK FIRST: Storage Strategy**
 
-Before creating or updating memory files, ask the user:
-
-> Do you want to use a single CLAUDE.md file or split into separate `.claude/rules/` files?
->
-> **Option 1: Single CLAUDE.md** - All instructions in one file (simpler, best for small projects)
-> **Option 2: Modular .claude/rules/** - Split by concern with optional path-scoping (better for large projects)
-
-Use AskUserQuestion to present these options before proceeding.
-
-**Decision guide:**
-
-- **Choose CLAUDE.md** if: < 100 lines of instructions, simple project, universal rules
-- **Choose .claude/rules/** if: 100+ lines, multiple file types with different rules, team maintains different areas
-  </decision_point>
-
-<creating_new>
-**Creating New Memory (CLAUDE.md approach)**
+Before creating or updating memory files, use AskUserQuestion:
+- **Option 1: Single CLAUDE.md** — < 100 lines, simple project, universal rules
+- **Option 2: Modular .claude/rules/** — 100+ lines, different rules for different files
 
+**Creating new memory:**
 1. Start with `/init` or minimal template
 2. Add tech stack and commands first
-3. Add conventions as you encounter friction
-4. Test with real tasks
-5. Iterate based on Claude's behavior
-   </creating_new>
-
-<creating_rules>
-**Creating New Memory (.claude/rules/ approach)**
-
-1. Create `.claude/rules/` directory
-2. Start with one file per major concern:
-   - `general.md` - Universal project rules
-   - `testing.md` - Testing conventions
-   - `code-style.md` - Code conventions
-3. Add path-scoped rules as needed:
-   ```yaml
-   ---
-   paths:
-     - "src/api/**/*.ts"
-   ---
-   # API rules here
-   ```
-4. Test with real tasks in different file contexts
-5. Split or merge files based on usage patterns
-   </creating_rules>
-
-<maintaining>
-**Maintaining Memory Files**
-
-1. Review quarterly (or when project changes significantly)
+3. Add rules only as you encounter friction
+4. Test with real tasks, iterate based on Claude's behavior
+
+**Maintaining:**
+1. Review quarterly or when project changes significantly
 2. Remove outdated instructions
 3. Add patterns that required repeated explanation
-4. Keep CLAUDE.md under 200 lines (or split to .claude/rules/)
-5. Use `#` for quick additions during work
-   </maintaining>
+4. Use `#` for quick additions during work
 
-<migrating_to_rules>
-**Migrating from CLAUDE.md to .claude/rules/**
+**Troubleshooting:**
 
-When CLAUDE.md exceeds 200 lines:
+| Problem | Solution |
+|---------|----------|
+| Claude ignores instructions | Reduce file size, add emphasis (CRITICAL, NEVER) |
+| Context overflow | Use `/clear`, split into .claude/rules/ |
+| Instructions conflict | Consolidate, use hierarchy (root vs subtree) |
+| Path rules not applying | Verify glob pattern matches target files |
+</workflow>
 
-1. Identify distinct sections (testing, API, frontend, etc.)
-2. Create `.claude/rules/` directory
-3. Move each section to its own file
-4. Add `paths` frontmatter where rules are file-type specific
-5. Keep only universal essentials in CLAUDE.md (or delete it)
-6. Test to ensure rules load correctly
-   </migrating_to_rules>
+<optimize_workflow>
+## `/claude-memory optimize` — Deep CLAUDE.md Cleanup
 
-<troubleshooting>
-**Common Issues**
+When the user argument contains "optimize", execute this workflow.
 
-| Problem                     | Solution                                         |
-| --------------------------- | ------------------------------------------------ |
-| Claude ignores instructions | Reduce file size, add emphasis (CRITICAL, NEVER) |
-| Context overflow            | Use `/clear`, split into .claude/rules/ files    |
-| Outdated information        | Review quarterly, remove stale content           |
-| Instructions conflict       | Consolidate, use hierarchy (root vs subtree)     |
-| Rules not loading           | Check file is `.md`, in correct directory        |
-| Path rules not applying     | Verify glob pattern matches target files         |
+**CRITICAL — Step 0 is MANDATORY. Do NOT skip it. Do NOT start optimizing without reading the guide first.**
 
-</troubleshooting>
-</workflow>
+### Step 0: Read the optimization guide (REQUIRED FIRST)
 
-<advanced_features>
-<local_overrides>
-Use `CLAUDE.local.md` for personal preferences (auto-gitignored):
+YOU MUST use the Read tool on `{SKILL_PATH}/references/optimize-guide.md` BEFORE doing anything else.
+This file contains the research data (ETH Zurich study), the 6 bloat categories with specific examples, target metrics, and before/after examples. Without reading it, you will miss removal criteria and produce a subpar optimization.
 
-- Personal shortcuts and aliases
-- Editor-specific settings
-- Local testing commands
-  </local_overrides>
+### Step 1: Inventory
 
-<settings_integration>
-CLAUDE.md works alongside `settings.json`:
+Read every CLAUDE.md, CLAUDE.local.md, and `.claude/rules/*.md` in the project. Count total lines.
 
-- `settings.json`: Permissions, allowed tools, environment variables
-- `CLAUDE.md`: Context, conventions, workflow instructions
-  </settings_integration>
+### Step 2: Read linter configs
 
-<progressive_disclosure>
-For complex projects, link to detailed docs. Claude only loads when relevant:
+Read ESLint/Biome/Prettier/TypeScript configs. Any CLAUDE.md line duplicating an enforced rule → delete.
 
-```markdown
-## References
+### Step 3: Apply the 6 bloat categories from the guide
 
-- **Database**: See [docs/database.md](docs/database.md)
-- **API**: See [docs/api.md](docs/api.md)
-```
+For each line ask: "Can the agent discover this by reading the project, or does a linter enforce this?" If yes → delete.
 
-</progressive_disclosure>
-</advanced_features>
+Remove everything matching:
+1. Linter-enforced rules (ESLint, Prettier, Biome, TypeScript strict)
+2. Marketing / goals / vision (zero code value)
+3. Obvious info the agent discovers itself (directory structure, framework defaults, deps from package.json)
+4. Verbose explanations (paragraphs where 1 line suffices, tutorials, history)
+5. Redundant specs (copies of config files, schema descriptions, env var lists)
+6. Generic best practices ("write clean code", "DRY", "SOLID")
 
-<success_criteria>
-A well-crafted Claude memory system:
+### Step 4: Keep only essentials
 
-**For CLAUDE.md approach:**
+- Project purpose (1-3 lines)
+- Tech stack (compact, non-obvious only)
+- Core commands (non-obvious only)
+- Testing commands
+- Important files (non-obvious only)
+- Project-specific rules (prohibitions + constraints)
+- Workflow (only if non-standard)
 
-- Loads in under 200 lines
-- Contains only project-specific context (not general knowledge)
-- Uses emphasis for critical rules (CRITICAL, NEVER, ALWAYS)
-- Avoids code style rules (use linters)
-- Contains NO secrets or credentials
-- Provides clear commands for common tasks
-- Follows WHAT-WHY-HOW structure
+### Step 5: Compress
 
-**For .claude/rules/ approach:**
+- Paragraphs → bullet points
+- 3-line rules → 1-line rules
+- Zero filler words ("In order to", "It's important to note that")
+- Merge related items
 
-- Each file focused on one concern (testing, API, security, etc.)
-- Path-scoped rules use accurate glob patterns
-- No duplicate rules across files
-- Files organized in logical subdirectories
-- Symlinks used for shared rules across projects
+### Step 6: Present diff
 
-**Both approaches:**
+Show before/after with line counts. For each removal, cite which bloat category it falls under.
+Let user approve before applying changes.
 
-- Gets updated as project evolves
-- Improves Claude's first-try accuracy on tasks
-- User was asked which approach they prefer before implementation
-  </success_criteria>
+**Target:** < 100 lines ideal, < 150 max.
+</optimize_workflow>
 
 <reference_guides>
-For deeper topics:
-
-- **Rules directory guide**: [references/rules-directory-guide.md](references/rules-directory-guide.md) - Complete guide to .claude/rules/ with official documentation, path-scoping, YAML syntax, and examples
-- **Prompting techniques**: [references/prompting-techniques.md](references/prompting-techniques.md) - Master guide for writing effective instructions, emphasis strategies, clarity techniques
-- **Comprehensive example**: [references/comprehensive-example.md](references/comprehensive-example.md) - Full production SaaS CLAUDE.md
-- **Section templates**: [references/section-templates.md](references/section-templates.md) - Copy-paste templates for each section
-- **Common patterns by project type**: [references/project-patterns.md](references/project-patterns.md) - Next.js, Express, Python, Monorepo patterns
-  </reference_guides>
+- **Optimization guide**: [references/optimize-guide.md](references/optimize-guide.md) — Research-backed bloat checklist, 6 removal categories, before/after examples
+- **Rules directory**: [references/rules-directory-guide.md](references/rules-directory-guide.md) — Complete .claude/rules/ guide with path-scoping, YAML syntax, symlinks, migration
+- **Prompting techniques**: [references/prompting-techniques.md](references/prompting-techniques.md) — Emphasis strategies, clarity techniques, constraint patterns
+- **Section templates**: [references/section-templates.md](references/section-templates.md) — Copy-paste templates for each section type
+- **Comprehensive example**: [references/comprehensive-example.md](references/comprehensive-example.md) — Full production SaaS CLAUDE.md
+- **Project patterns**: [references/project-patterns.md](references/project-patterns.md) — Next.js, Express, Python, Monorepo patterns
+</reference_guides>

package/claude-code-config/skills/meta-claude-memory/references/optimize-guide.md

@@ -0,0 +1,300 @@
+# CLAUDE.md Optimization Guide
+
+## Research Foundation
+
+Based on "Evaluating AGENTS.md" (ETH Zurich, arXiv 2602.11988, Feb 2026) — the first rigorous study of repository context files for coding agents:
+
+**Key findings:**
+- Context files with unnecessary specs **reduce** task success rates vs no context at all
+- LLM-generated context files reduced success by 0.5-2% and increased costs 20-23%
+- Developer-written **minimal** files improved performance by 4%
+- Repository overviews are useless — agents discover structure themselves
+- Removing redundant documentation improved performance by 2.7%
+- Instructions ARE reliably followed (mentioned tools used 1.6-2.5x more) — the problem is **what** you instruct, not **whether** it's followed
+- Files averaging 641 words performed; files with unnecessary complexity degraded
+
+**The paradox:** More instructions = worse performance. The agent follows your instructions faithfully, but unnecessary constraints make the task harder.
+
+**Conclusion:** Write only what the agent cannot discover on its own. Everything else is noise that actively hurts.
+
+## Additional Metrics (SFEIR Institute, Feb 2026)
+
+- Files over 200 lines: 30% of directives silently lost
+- Vague instructions: +45% manual corrections needed
+- Explicit prohibitions: more effective than positive guidance
+- Modular `.claude/rules/` with path-scoping: 40% noise reduction, 35% relevance increase
+- Documented test/build commands: 30% reduction in back-and-forth
+- 3-5 concrete code examples: 40% reduction in correction requests
+
+## The 7 Essential Sections
+
+Every optimized CLAUDE.md should contain ONLY these. Nothing else.
+
+### 1. Project Purpose (1-3 lines)
+What the project is. One sentence is ideal. The agent doesn't need your vision or goals.
+
+```markdown
+# MyApp
+SaaS invoice management platform with Stripe billing.
+```
+
+**Kill:** Vision statements, goals, target audience, roadmaps, business metrics, "why we built this."
+
+### 2. Tech Stack (compact)
+Only technologies the agent can't detect from package.json/config files.
+
+```markdown
+## Tech Stack
+- Next.js 15 (App Router) + TypeScript
+- Prisma + PostgreSQL
+- TanStack Form + Zod
+- Tailwind + shadcn/ui
+```
+
+**Kill:** Version numbers from lockfiles, obvious deps (React in Next.js), descriptions of what each lib does.
+
+### 3. Core Commands
+Commands the agent needs. Only non-obvious ones.
+
+```markdown
+## Commands
+- `pnpm dev` - Dev server
+- `pnpm build` - Production build
+- `pnpm db:push` - Push schema changes
+- `pnpm db:seed` - Seed database
+```
+
+**Kill:** `pnpm install` (obvious), `pnpm start` (obvious), self-explanatory package.json scripts.
+
+### 4. Testing Commands
+How to run tests. The research shows documented test commands reduce back-and-forth 30%.
+
+```markdown
+## Testing
+- `pnpm test` - Run all tests
+- `pnpm test:e2e` - E2E tests (needs running dev server)
+- Single file: `pnpm vitest run path/to/file.test.ts`
+```
+
+### 5. Important Files
+Only files the agent wouldn't find naturally. Architecture-critical, non-obvious files.
+
+```markdown
+## Important Files
+- `src/lib/auth.ts` - Auth config (Better Auth)
+- `src/lib/safe-actions.ts` - Server action wrapper
+```
+
+**Kill:** `package.json`, `tsconfig.json`, `next.config.js`, any standard framework file the agent already knows.
+
+### 6. Project-Specific Rules (Highest Value)
+Prohibitions and constraints that prevent recurring mistakes. Research shows explicit prohibitions are more effective than positive guidance.
+
+```markdown
+## Rules
+- NEVER import from `@/features/*/server` in client components
+- ALWAYS use `safe-action` wrapper for server actions
+- Use TanStack Form for ALL forms (not native form/useState)
+- Errors must use `ActionError` not `throw new Error`
+```
+
+**These are the most valuable lines in the entire file.** Each rule should encode a mistake that was made before and must not be repeated.
+
+### 7. Workflow (optional)
+Only if the project has a non-standard workflow.
+
+```markdown
+## Workflow
+- Start with plan mode for features touching 3+ files
+- Run `pnpm build` after changes (strict TypeScript)
+```
+
+**Kill:** Standard git workflows, obvious PR processes.
+
+## The 6 Bloat Categories (What to Remove)
+
+### Category 1: Linter-Enforced Rules
+The research is clear: if a tool enforces it, the context file shouldn't mention it.
+
+Delete anything ESLint, Prettier, Biome, or TypeScript strict mode handles:
+- Indentation, semicolons, trailing commas, quote style
+- Import ordering, max line length
+- Naming conventions in ESLint rules
+- "Use const over let" / "Prefer arrow functions"
+- "No unused variables" / "No any type"
+- Type annotation rules
+
+**Test:** Does `.eslintrc`, `biome.json`, or `tsconfig.json` enforce this? → Delete from CLAUDE.md.
+
+### Category 2: Repository Overviews
+The paper proved these are useless — agents discover repo structure themselves with zero performance benefit:
+
+- Directory structure descriptions (agent can `ls`)
+- Folder explanations (`src/components/ contains React components`)
+- Architecture diagrams in text
+- "This is a monorepo" (agent sees `packages/` or `apps/`)
+- Framework defaults ("Next.js uses file-based routing")
+- Feature descriptions ("The auth module handles login")
+
+### Category 3: Marketing / Goals / Vision
+Zero value for code generation:
+- Mission statements, vision, goals
+- Target audience, competitive positioning
+- Feature roadmaps, business metrics
+- "Why we built this" narratives
+
+### Category 4: Redundant Specifications
+The paper found removing redundant docs improved performance by 2.7%:
+
+- Copy of TypeScript config settings
+- Copy of ESLint config
+- Environment variable names (agent reads `.env.example`)
+- Database schema prose (agent reads `schema.prisma`)
+- API route docs (agent reads the code)
+- Component prop docs (TypeScript types handle this)
+- README content repeated in CLAUDE.md
+
+### Category 5: Verbose Explanations
+Multi-paragraph explanations actively hurt — they consume context budget and add complexity:
+
+- Paragraphs explaining why a pattern exists (one line is enough)
+- Tutorials, onboarding guides, historical context
+- Code examples longer than 5 lines (reference the file instead)
+- Filler phrases: "In order to", "It's important to note that", "Please make sure to"
+
+### Category 6: Generic Best Practices
+The agent already knows these. Adding them wastes instruction slots:
+- "Write clean code" / "Follow SOLID principles"
+- "Write tests" (without specific commands)
+- "Use meaningful variable names" / "Keep functions small"
+- "DRY principle" / "Handle errors properly"
+
+## Optimization Process
+
+### Step 1: Inventory
+Read every CLAUDE.md and `.claude/rules/*.md` in the project.
+Count total lines across all files.
+
+### Step 2: Cross-check linter configs
+Read ESLint/Biome/Prettier/TypeScript configs. Any CLAUDE.md line duplicating an enforced rule → delete.
+
+### Step 3: Apply the 6 bloat categories
+For each line ask: **"Can the agent discover this by reading the project, or does a linter enforce this?"**
+If yes → delete.
+
+### Step 4: Check for redundancy
+- Information duplicated across files → consolidate
+- Information in README also in CLAUDE.md → remove from CLAUDE.md
+- Information derivable from config files → remove
+
+### Step 5: Compress survivors
+- Paragraphs → bullet points
+- 3-line rules → 1-line rules
+- Remove all filler words
+- Merge related items
+
+### Step 6: Verify essentials remain
+- [ ] Project purpose (1-3 lines)
+- [ ] Tech stack (compact, non-obvious only)
+- [ ] Core commands (non-obvious only)
+- [ ] Testing commands
+- [ ] Important files (non-obvious only)
+- [ ] Project-specific rules (prohibitions + constraints)
+- [ ] Workflow (only if non-standard)
+
+### Step 7: Present changes
+Show before/after with line counts. Explain what was removed and why (cite category). Let user approve.
+
+## Target Metrics
+
+| Metric | Target | Research Basis |
+|--------|--------|----------------|
+| Total lines | < 100 ideal, < 150 max | >200 lines = 30% directive loss |
+| Sections | 5-7 | Minimal requirements only |
+| Filler words | 0 | +45% corrections when vague |
+| Linter-duplicate rules | 0 | Already enforced = wasted tokens |
+| Marketing/goals text | 0 | Zero value for code generation |
+| Generic best practices | 0 | Agent already knows them |
+| Repository overviews | 0 | Research: zero navigation benefit |
+
+## Before vs After Example
+
+### Before (bloated — 47 lines, typical file is 200+)
+```markdown
+# MyApp - AI-Powered Invoice Management
+
+## Vision
+MyApp aims to simplify invoicing for small businesses worldwide.
+
+## Goals
+- Reach 10,000 users by Q3 2025
+- Achieve 99.9% uptime
+
+## Tech Stack
+- Next.js 15 with App Router for server-side rendering
+- React 19 for building user interfaces
+- TypeScript for type safety
+- Prisma ORM for database access
+- PostgreSQL database hosted on Neon
+- Tailwind CSS for styling
+- shadcn/ui component library
+- Stripe for payment processing
+
+## Directory Structure
+- src/app/ - Next.js app router pages
+- src/components/ - Reusable React components
+- src/lib/ - Utility functions
+- src/features/ - Feature modules
+- prisma/ - Database schema
+
+## Code Style
+- Use 2-space indentation
+- Use semicolons
+- Use single quotes
+- Use const over let
+- No unused variables
+- Prefer arrow functions
+- Use PascalCase for components
+- Use camelCase for functions
+
+## Important Notes
+In order to maintain code quality, it's important to note that
+all developers should follow clean code principles and ensure
+that the codebase remains maintainable and readable.
+```
+
+### After (optimized — complete file, 22 lines)
+```markdown
+# MyApp
+SaaS invoice management platform.
+
+## Tech Stack
+- Next.js 15 (App Router) + TypeScript
+- Prisma + PostgreSQL (Neon)
+- Stripe payments
+- Tailwind + shadcn/ui
+
+## Commands
+- `pnpm dev` - Dev server
+- `pnpm build` - Build
+- `pnpm test` - Tests
+- `pnpm db:push` - Push schema
+
+## Important Files
+- `src/lib/auth.ts` - Auth config
+- `src/lib/safe-actions.ts` - Server action wrapper
+
+## Rules
+- ALWAYS use safe-action wrapper for server actions
+- NEVER import server modules in client components
+- Use TanStack Form for ALL forms
+```
+
+**What was removed and why:**
+- Vision/Goals (Category 3: marketing — zero code value)
+- React 19, TypeScript descriptions (Category 2: obvious from package.json)
+- Directory structure (Category 2: agent discovers via `ls`)
+- All code style rules (Category 1: ESLint/Prettier enforces these)
+- "Important Notes" paragraph (Category 6: generic best practices + Category 5: filler)
+
+**Result:** 47 → 22 lines. Research predicts ~4% better task completion and ~20% cost reduction.

package/claude-code-config/skills/meta-subagent-creator/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: skill-workflow-creator
+name: subagent-creator
 description: Expert guidance for creating, building, and using Claude Code subagents and the Task tool. Use when working with subagents, setting up agent configurations, understanding how agents work, or using the Task tool to launch specialized agents.
 ---
 

package/claude-code-config/skills/ralph-loop/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: setup-ralph
+name: ralph-loop
 description: Setup the Ralph autonomous AI coding loop - ships features while you sleep
 argument-hint: "<project-path> [-i/--interactive] [-f/--feature <name>]"
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiblueprint-cli",
-  "version": "1.4.38",
+  "version": "1.4.40",
   "description": "AIBlueprint CLI for setting up Claude Code configurations",
   "author": "AIBlueprint",
   "license": "MIT",