aiblueprint-cli 1.4.59 → 1.4.61

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

@@ -1,300 +0,0 @@
-# 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/agents-config/skills/claude-memory/references/project-patterns.md

@@ -1,334 +0,0 @@
-<project_patterns>
-CLAUDE.md patterns optimized for specific project types.
-
-<nextjs_app_router>
-```markdown
-# [Project Name] - Next.js App Router
-
-## Tech Stack
-- Next.js 15 with App Router
-- TypeScript (strict mode)
-- TailwindCSS + shadcn/ui
-- [Database solution]
-
-## Commands
-- `pnpm dev` - Start dev server
-- `pnpm build` - Production build
-- `pnpm lint` - Check code
-- `pnpm test:ci` - Run tests
-
-## Directory Structure
-```
-app/
-├── (auth)/        # Auth routes
-├── (dashboard)/   # Dashboard routes
-├── api/           # API routes
-└── layout.tsx     # Root layout
-src/
-├── components/    # UI components
-├── lib/           # Utilities
-└── hooks/         # React hooks
-```
-
-## Conventions
-
-### Components
-- Prefer Server Components
-- Use `"use client"` only for interactivity
-- Keep components under 300 lines
-
-### Data Fetching
-- Server Components: Direct database access
-- Client Components: TanStack Query
-- Mutations: Server Actions
-
-### File Naming
-- `page.tsx` - Route pages
-- `layout.tsx` - Layouts
-- `loading.tsx` - Loading states
-- `error.tsx` - Error boundaries
-
-## Important
-- **NEVER** use `use client` for data fetching
-- Always add `loading.tsx` for async pages
-- Use `generateMetadata` for SEO
-```
-</nextjs_app_router>
-
-<nextjs_pages_router>
-```markdown
-# [Project Name] - Next.js Pages Router
-
-## Tech Stack
-- Next.js 14 with Pages Router
-- TypeScript
-- TailwindCSS
-
-## Commands
-- `pnpm dev` - Development
-- `pnpm build` - Production build
-- `pnpm test` - Run tests
-
-## Directory Structure
-```
-pages/
-├── api/           # API routes
-├── _app.tsx       # App wrapper
-├── _document.tsx  # Document
-└── index.tsx      # Home page
-src/
-├── components/    # Components
-├── lib/           # Utilities
-└── hooks/         # Hooks
-```
-
-## Data Fetching
-- `getServerSideProps` - SSR data
-- `getStaticProps` - SSG data
-- `useSWR` or TanStack Query - Client data
-
-## API Routes
-- Located in `pages/api/`
-- Use `NextApiRequest` and `NextApiResponse` types
-```
-</nextjs_pages_router>
-
-<react_vite>
-```markdown
-# [Project Name] - React + Vite
-
-## Tech Stack
-- React 18 + TypeScript
-- Vite for bundling
-- TailwindCSS
-- TanStack Query
-
-## Commands
-- `pnpm dev` - Start dev server
-- `pnpm build` - Production build
-- `pnpm preview` - Preview build
-- `pnpm test` - Run tests
-
-## Directory Structure
-```
-src/
-├── components/    # UI components
-├── features/      # Feature modules
-├── hooks/         # Custom hooks
-├── lib/           # Utilities
-├── routes/        # Route components
-└── main.tsx       # Entry point
-```
-
-## Conventions
-- Functional components only
-- Custom hooks for logic reuse
-- TanStack Query for server state
-- Zustand for client state
-```
-</react_vite>
-
-<node_express>
-```markdown
-# [Project Name] - Node.js API
-
-## Tech Stack
-- Node.js + Express
-- TypeScript
-- PostgreSQL + Prisma
-- Jest for testing
-
-## Commands
-- `pnpm dev` - Start with hot reload
-- `pnpm build` - Compile TypeScript
-- `pnpm start` - Start production
-- `pnpm test` - Run tests
-
-## Directory Structure
-```
-src/
-├── controllers/   # Route handlers
-├── middleware/    # Express middleware
-├── models/        # Data models
-├── routes/        # Route definitions
-├── services/      # Business logic
-├── utils/         # Helpers
-└── index.ts       # Entry point
-```
-
-## Conventions
-- Controllers handle HTTP only
-- Services contain business logic
-- Middleware for cross-cutting concerns
-- Always validate input with Zod
-
-## Error Handling
-- Use custom error classes
-- Central error middleware
-- Always return consistent error format
-```
-</node_express>
-
-<python_fastapi>
-```markdown
-# [Project Name] - Python FastAPI
-
-## Tech Stack
-- Python 3.11+
-- FastAPI
-- SQLAlchemy + PostgreSQL
-- Pytest
-
-## Commands
-- `uvicorn main:app --reload` - Development
-- `pytest` - Run tests
-- `ruff check .` - Lint
-- `ruff format .` - Format
-
-## Directory Structure
-```
-app/
-├── api/           # Route handlers
-├── core/          # Config, security
-├── db/            # Database models
-├── schemas/       # Pydantic models
-├── services/      # Business logic
-└── main.py        # Entry point
-```
-
-## Conventions
-- Pydantic for validation
-- Dependency injection for services
-- Async where beneficial
-- Type hints everywhere
-```
-</python_fastapi>
-
-<monorepo_turborepo>
-```markdown
-# [Project Name] - Turborepo Monorepo
-
-## Tech Stack
-- Turborepo for build orchestration
-- pnpm workspaces
-- TypeScript
-
-## Commands
-- `pnpm install` - Install all deps
-- `pnpm dev` - Start all apps
-- `pnpm build` - Build all packages
-- `pnpm test` - Test all packages
-- `pnpm --filter web dev` - Start specific app
-
-## Directory Structure
-```
-apps/
-├── web/           # Main frontend
-├── api/           # Backend API
-└── admin/         # Admin panel
-packages/
-├── ui/            # Shared components
-├── config/        # Shared config
-├── types/         # Shared types
-└── utils/         # Shared utilities
-```
-
-## Package Development
-- Changes to `packages/*` require rebuild
-- Use `pnpm --filter` for targeted commands
-- Shared types in `packages/types`
-
-## Conventions
-- Each app has its own CLAUDE.md
-- Root CLAUDE.md for universal rules
-- Keep packages focused and minimal
-```
-</monorepo_turborepo>
-
-<cli_tool>
-```markdown
-# [Tool Name] - CLI Tool
-
-## Tech Stack
-- TypeScript
-- Commander.js for CLI
-- Chalk for colors
-
-## Commands
-- `pnpm dev` - Watch mode
-- `pnpm build` - Compile
-- `pnpm link` - Link globally
-- `[tool-name] --help` - Show help
-
-## Directory Structure
-```
-src/
-├── commands/      # CLI commands
-├── lib/           # Core logic
-├── utils/         # Helpers
-└── index.ts       # Entry point
-```
-
-## Adding Commands
-1. Create command in `src/commands/`
-2. Register in `src/index.ts`
-3. Add tests in `__tests__/`
-
-## Output Conventions
-- Use chalk for colors
-- Errors to stderr
-- Progress with ora spinners
-```
-</cli_tool>
-
-<library_package>
-```markdown
-# [Library Name] - npm Package
-
-## Tech Stack
-- TypeScript
-- tsup for bundling
-- Vitest for testing
-
-## Commands
-- `pnpm build` - Build package
-- `pnpm test` - Run tests
-- `pnpm dev` - Watch mode
-- `pnpm publish` - Publish to npm
-
-## Directory Structure
-```
-src/
-├── index.ts       # Main exports
-├── utils/         # Internal helpers
-└── types.ts       # Type definitions
-```
-
-## Publishing Checklist
-1. Update version in package.json
-2. Run tests: `pnpm test`
-3. Build: `pnpm build`
-4. Publish: `pnpm publish`
-
-## Conventions
-- Export types alongside functions
-- Document with JSDoc
-- Maintain backwards compatibility
-```
-</library_package>
-</project_patterns>
-
-<customization_notes>
-<adapt_sections>
-Each pattern is a starting point. Adapt by:
-
-1. Removing irrelevant sections
-2. Adding project-specific conventions
-3. Adjusting commands for your setup
-4. Including critical architectural decisions
-</adapt_sections>
-
-<keep_minimal>
-Even for complex projects, aim for under 150 lines. Move detailed documentation to separate files and link from CLAUDE.md.
-</keep_minimal>
-</customization_notes>