agents-templated 2.2.5 → 2.2.7

package/README.md

@@ -28,12 +28,14 @@ Agents Templated scaffolds your project with:
 - Deterministic slash-command standard in `AGENTS.MD` and modular contracts in `agents/commands/`
 - Implicit natural-language routing support (`slash-command-auto`) for non-technical prompts
 - New workflow/routing/hardening rule set:
-  - `.github/instructions/rules/intent-routing.mdc`
-  - `.github/instructions/rules/system-workflow.mdc`
-  - `.github/instructions/rules/hardening.mdc`
+  - `.claude/rules/intent-routing.md`
+  - `.claude/rules/system-workflow.md`
+  - `.claude/rules/hardening.md`
+  - `.claude/rules/lessons-learned.md`
 - New baseline skills:
   - `.github/skills/feature-delivery/`
   - `.github/skills/bug-triage/`
+  - `.github/skills/error-patterns/`
   - `.github/skills/app-hardening/`
 - Release and audit contracts now require hardening evidence when risk profile requires it
 
@@ -143,29 +145,33 @@ your-project/
 │   └── README.md                   # Human-readable setup guide
 │
 ├── .github/
-│   ├── instructions/                # Generated compatibility wrappers + rules
-│   │   ├── AGENTS.md
-│   │   └── rules/
-│   │   ├── core.mdc               # Core development principles
-│   │   ├── security.mdc           # Security patterns (CRITICAL)
-│   │   ├── testing.mdc            # Testing strategy
-│   │   ├── frontend.mdc           # Frontend patterns
-│   │   ├── database.mdc           # Database patterns
-│   │   ├── style.mdc              # Code style guidelines
-│   │   ├── workflows.mdc          # Workflow and quality gates
-│   │   ├── intent-routing.mdc     # Intent-to-command routing policy
-│   │   ├── system-workflow.mdc    # End-to-end delivery lifecycle gates
-│   │   └── hardening.mdc          # Hardening and obfuscation guidance
+│   ├── instructions/                # Compatibility pointer directory
 │   ├── skills/
 │   │   ├── find-skills/           # Skill discovery helper
 │   │   ├── feature-delivery/      # Scoped feature delivery workflow
 │   │   ├── bug-triage/            # Reproduction-first defect workflow
+│   │   ├── error-patterns/         # Persistent error-debugging memory workflow
 │   │   ├── app-hardening/         # Hardening and release-evidence workflow
 │   │   ├── ui-ux-pro-max/         # Advanced UI/UX design implementation skill
 │   │   ├── README.md              # Guide for creating custom skills
 │   │   └── [your-custom-skills]/  # Your project-specific skills
 │   └── copilot-instructions.md    # Compatibility shim for Copilot
 │
+├── .claude/
+│   ├── rules/                      # Canonical rules source
+│   │   ├── core.md
+│   │   ├── security.md
+│   │   ├── testing.md
+│   │   ├── frontend.md
+│   │   ├── database.md
+│   │   ├── style.md
+│   │   ├── workflows.md
+│   │   ├── intent-routing.md
+│   │   ├── system-workflow.md
+│   │   ├── hardening.md
+│   │   └── lessons-learned.md
+│   └── agents/                     # Optional subagents
+│
 ├── agents/                          # 🤖 Deterministic command contracts
 │   └── commands/
 │   │   ├── SCHEMA.md              # Global slash-command response schema
@@ -299,8 +305,8 @@ Skills define *how to execute specific tasks*, complementing rules that define *
 - **[AGENTS.MD](AGENTS.MD)** – AI assistant guide
 - **[agent-docs/ARCHITECTURE.md](agent-docs/ARCHITECTURE.md)** – Project architecture & tech stack guidance
 - **[.github/skills/README.md](.github/skills/README.md)** – Custom skills guide
-- **[.github/instructions/rules/security.mdc](.github/instructions/rules/security.mdc)** – Security patterns (CRITICAL)
-- **[.github/instructions/rules/testing.mdc](.github/instructions/rules/testing.mdc)** – Testing strategy
+- **[.claude/rules/security.md](.claude/rules/security.md)** – Security patterns (CRITICAL)
+- **[.claude/rules/testing.md](.claude/rules/testing.md)** – Testing strategy
 
 ### 5. Start Building
 
@@ -326,7 +332,7 @@ Your AI will follow the enterprise patterns automatically!
 ✅ Sanitize outputs to prevent injection attacks  
 ✅ Never expose sensitive data in error messages or logs
 
-**Reference**: [.github/instructions/rules/security.mdc](.github/instructions/rules/security.mdc)
+**Reference**: [.claude/rules/security.md](.claude/rules/security.md)
 
 ### Testing Strategy
 
@@ -334,7 +340,7 @@ Your AI will follow the enterprise patterns automatically!
 - **15% Integration Tests** – API endpoints, database operations
 - **5% E2E Tests** – Critical user journeys
 
-**Reference**: [.github/instructions/rules/testing.mdc](.github/instructions/rules/testing.mdc)
+**Reference**: [.claude/rules/testing.md](.claude/rules/testing.md)
 
 ### Agent-Based Architecture
 
@@ -421,7 +427,7 @@ await agentsTemplated.install('./my-project', {
 
 When contributing to this template:
 1. Maintain technology-agnostic patterns
-2. Update relevant rule files in `.github/instructions/rules/`
+2. Update relevant rule files in `.claude/rules/`
 3. Keep documentation synchronized with code changes
 4. Follow security and testing patterns
 5. Ensure AI assistant configurations remain compatible

package/bin/cli.js

@@ -122,7 +122,7 @@ program
             choices: [
               { name: 'All components', value: 'all' },
               { name: 'Documentation files (agent-docs/)', value: 'docs' },
-              { name: 'Agent rules (.claude/rules/*.mdc)', value: 'rules' },
+              { name: 'Agent rules (.claude/rules/*.md)', value: 'rules' },
               { name: 'Skills (.github/skills/*)', value: 'skills' },
               { name: 'AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)', value: 'github' },
               { name: 'Agent subagents (.claude/agents/*.md)', value: 'subagents' }
@@ -383,10 +383,10 @@ program
       console.log(chalk.white('   1. Review CLAUDE.md (canonical AI policy — edit this directly)'));
       console.log(chalk.white('   2. Review agent-docs/ARCHITECTURE.md for project guidelines'));
       console.log(chalk.white('   3. AGENTS.MD and .github/copilot-instructions.md are thin pointers to CLAUDE.md'));
-      console.log(chalk.white('   4. Customize agents/rules/*.mdc for your tech stack'));
+      console.log(chalk.white('   4. Customize agents/rules/*.md for your tech stack'));
       
       console.log(chalk.cyan('\n🔒 Security Reminder:\n'));
-      console.log(chalk.white('   • Review agents/rules/security.mdc'));
+      console.log(chalk.white('   • Review agents/rules/security.md'));
       console.log(chalk.white('   • Validate all inputs with schema validation'));
       console.log(chalk.white('   • Implement rate limiting on public endpoints'));
       console.log(chalk.white('   • Never expose sensitive data in errors\n'));
@@ -403,7 +403,7 @@ program
   .action(() => {
     console.log(chalk.blue.bold('\nAvailable Components:\n'));
     console.log(chalk.yellow('docs') + '    - Documentation files (agent-docs/ directory)');
-    console.log(chalk.yellow('rules') + '   - Agent rules (.claude/rules/*.mdc)');
+    console.log(chalk.yellow('rules') + '   - Agent rules (.claude/rules/*.md)');
     console.log(chalk.yellow('skills') + '  - Agent skills (.github/skills/*)');
     console.log(chalk.yellow('github') + '  - AI Agent instructions (Cursor, Copilot, Claude, Generic AGENTS)');
     console.log(chalk.yellow('subagents') + ' - Agent subagents (.claude/agents/*.md)');
@@ -455,7 +455,7 @@ program
       }
 
       // Check agent rules
-      const ruleFiles = ['core.mdc', 'security.mdc', 'testing.mdc', 'frontend.mdc', 'database.mdc', 'style.mdc'];
+      const ruleFiles = ['core.md', 'security.md', 'testing.md', 'lessons-learned.md', 'frontend.md', 'database.md', 'style.md'];
       const canonicalRulesDir = path.join(targetDir, LAYOUT.canonical.rulesDir);
       const legacyRulesDir = path.join(targetDir, LAYOUT.legacy.rulesDirs[0]);
       const rulesDir = path.join(targetDir, resolveRulesDir(targetDir));
@@ -829,11 +829,13 @@ program
       const checkFiles = [
         { targetFile: CANONICAL_INSTRUCTION_FILE, templateFile: CANONICAL_INSTRUCTION_FILE, component: 'root' },
         { targetFile: 'agent-docs/ARCHITECTURE.md', templateFile: 'agent-docs/ARCHITECTURE.md', component: 'docs' },
-        { targetFile: `${LAYOUT.canonical.rulesDir}/security.mdc`, templateFile: 'agents/rules/security.mdc', component: 'rules' },
-        { targetFile: `${LAYOUT.canonical.rulesDir}/testing.mdc`, templateFile: 'agents/rules/testing.mdc', component: 'rules' },
-        { targetFile: `${LAYOUT.canonical.rulesDir}/core.mdc`, templateFile: 'agents/rules/core.mdc', component: 'rules' },
+        { targetFile: `${LAYOUT.canonical.rulesDir}/security.md`, templateFile: 'agents/rules/security.md', component: 'rules' },
+        { targetFile: `${LAYOUT.canonical.rulesDir}/testing.md`, templateFile: 'agents/rules/testing.md', component: 'rules' },
+        { targetFile: `${LAYOUT.canonical.rulesDir}/lessons-learned.md`, templateFile: 'agents/rules/lessons-learned.md', component: 'rules' },
+        { targetFile: `${LAYOUT.canonical.rulesDir}/core.md`, templateFile: 'agents/rules/core.md', component: 'rules' },
         { targetFile: `${LAYOUT.canonical.skillsDir}/README.md`, templateFile: 'agents/skills/README.md', component: 'skills' },
         { targetFile: `${LAYOUT.canonical.skillsDir}/find-skills/SKILL.md`, templateFile: 'agents/skills/find-skills/SKILL.md', component: 'skills' },
+        { targetFile: `${LAYOUT.canonical.skillsDir}/error-patterns/SKILL.md`, templateFile: 'agents/skills/error-patterns/SKILL.md', component: 'skills' },
         { targetFile: `${LAYOUT.canonical.skillsDir}/ui-ux-pro-max/SKILL.md`, templateFile: 'agents/skills/ui-ux-pro-max/SKILL.md', component: 'skills' }
       ];
 
@@ -989,7 +991,7 @@ program
       console.log(chalk.blue('\n📚 Quick Tips:\n'));
       console.log(chalk.white('  • Run "agents-templated validate" to check setup'));
       console.log(chalk.white('  • Run "agents-templated wizard" for guided setup'));
-      console.log(chalk.white('  • Review agents/rules/security.mdc for security patterns\n'));
+      console.log(chalk.white('  • Review agents/rules/security.md for security patterns\n'));
 
     } catch (error) {
       console.error(chalk.red('Error:'), error.message);
@@ -1015,7 +1017,7 @@ program
 
 program
   .command('new-rule <name>')
-  .description('Scaffold a new rule in agents/rules/<name>.mdc')
+  .description('Scaffold a new rule in agents/rules/<name>.md')
   .action(async (name) => {
     try {
       const targetDir = process.cwd();

package/lib/instructions.js

@@ -137,10 +137,10 @@ async function scaffoldSkill(targetDir, skillName) {
 
 async function scaffoldRule(targetDir, ruleName) {
   const rulesDir = path.join(targetDir, 'agents', 'rules');
-  const ruleFile = path.join(rulesDir, `${ruleName}.mdc`);
+  const ruleFile = path.join(rulesDir, `${ruleName}.md`);
 
   if (await fs.pathExists(ruleFile)) {
-    throw new Error(`Rule already exists: agents/rules/${ruleName}.mdc`);
+    throw new Error(`Rule already exists: agents/rules/${ruleName}.md`);
   }
 
   const content = [
@@ -168,7 +168,7 @@ async function scaffoldRule(targetDir, ruleName) {
 
   await fs.ensureDir(rulesDir);
   await fs.writeFile(ruleFile, content, 'utf8');
-  return `agents/rules/${ruleName}.mdc`;
+  return `agents/rules/${ruleName}.md`;
 }
 
 async function scaffoldSubagent(targetDir, name) {

package/lib/layout.js

@@ -9,11 +9,11 @@ const LAYOUT = {
     subagentsDir: '.claude/agents'
   },
   legacy: {
-    rulesDirs: ['agents/rules', '.github/instructions/rules'],
+    rulesDirs: ['agents/rules'],
     skillsDirs: ['agents/skills']
   },
   compatible: {
-    rulesDirs: ['.github/instructions'],
+    rulesDirs: [],
     skillsDirs: ['.claude/skills', '.agents/skills']
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-templated",
-  "version": "2.2.5",
+  "version": "2.2.7",
   "description": "Technology-agnostic development template with multi-AI agent support (Cursor, Copilot, VSCode, Gemini), security-first patterns, and comprehensive testing guidelines",
   "main": "index.js",
   "bin": {

package/templates/.claude/rules/{ai-integration.mdc → ai-integration.md}

@@ -5,12 +5,6 @@ version: "1.0.0"
 tags: ["ai", "llm", "openai", "anthropic", "rag", "prompt-engineering", "safety"]
 alwaysApply: false
 globs: ["**/*llm*", "**/*openai*", "**/*anthropic*", "**/*langchain*", "**/*rag*", "**/ai/**"]
-triggers:
-  - "Integrating OpenAI, Claude, or other LLM APIs"
-  - "Building RAG (Retrieval-Augmented Generation) pipeline"
-  - "Engineering prompts or prompt chains"
-  - "Implementing LLM-powered features"
-  - "Evaluating LLM outputs or quality"
 ---
 
 ## Purpose

package/templates/.claude/rules/{core.mdc → core.md}

@@ -6,13 +6,6 @@ version: "3.0.0"
 tags: ["architecture", "core", "enterprise", "technology-agnostic"]
 globs:
   - "*"
-triggers:
-  - "Designing application architecture"
-  - "Setting up new project or module"
-  - "Defining type systems and validation"
-  - "Organizing code structure"
-  - "Improving code quality standards"
-  - "Making testing or performance decisions"
 ---
 
 ## Developer Identity

package/templates/.claude/rules/{database.mdc → database.md}

@@ -7,13 +7,6 @@ tags: ["database", "backend", "data", "orm", "schema"]
 globs:
   - "src/models/**/*"
   - "src/data/**/*"
-triggers:
-  - "Designing database schema or tables"
-  - "Creating/updating ORM models or queries"
-  - "Running database migrations"
-  - "Optimizing slow queries"
-  - "Selecting database technology"
-  - "Implementing access control for data"
 ---
 
 # Database and Data Layer Guidelines

package/templates/.claude/rules/{frontend.mdc → frontend.md}

@@ -8,13 +8,6 @@ globs:
   - "src/**/*"
   - "components/**/*"
   - "public/**/*"
-triggers:
-  - "Building user interfaces or components"
-  - "Designing responsive layouts"
-  - "Creating forms and validations"
-  - "Implementing accessibility features"
-  - "Working on user-facing features"
-  - "Optimizing performance for frontend"
 ---
 
 # Frontend Development Guidelines

package/templates/.claude/rules/{guardrails.mdc → guardrails.md}

@@ -4,14 +4,6 @@ title: "AI Agent Guardrails"
 description: "Enforce hard behavioral limits on all agents. Apply when any destructive, irreversible, or dangerous action is requested"
 version: "1.0.0"
 tags: ["guardrails", "safety", "scope", "reversibility", "agent-behavior"]
-triggers:
-  - "User requests file/folder/branch deletion"
-  - "Force pushing or hard-resetting git history"
-  - "Deploying to production"
-  - "Dropping database tables"
-  - "Disabling tests to make build pass"
-  - "Bypassing security controls"
-  - "Any action that cannot be easily undone"
 ---
 
 ## Purpose

package/templates/.claude/rules/{hardening.mdc → hardening.md}

@@ -3,12 +3,6 @@ title: "Application Hardening & Obfuscation"
 description: "Apply when building client-distributed apps, protecting IP logic, or preparing releases with anti-tamper requirements"
 version: "1.0.0"
 tags: ["hardening", "obfuscation", "anti-tamper", "security"]
-triggers:
-  - "Building mobile or desktop app for distribution"
-  - "Protecting high-value or proprietary logic"
-  - "Increasing tamper detection or anti-hooking"
-  - "Preparing production release with security concerns"
-  - "Performance and integrity validation needed"
 ---
 
 ## Purpose

package/templates/.claude/rules/{intent-routing.mdc → intent-routing.md}

@@ -3,11 +3,6 @@ title: "Intent Routing & Command Selection"
 description: "Apply when determining which rule or workflow applies to the user's request. Ensures correct execution pathway"
 version: "1.0.0"
 tags: ["routing", "deterministic", "workflow", "commands"]
-triggers:
-  - "Ambiguous or multi-intent user request"
-  - "Need to route to correct rule or workflow"
-  - "Destructive action requested"
-  - "Scope expansion detected"
 ---
 
 ## Purpose

package/templates/.claude/rules/lessons-learned.md

@@ -0,0 +1,44 @@
+---
+alwaysApply: true
+title: "Lessons Learned"
+description: "Apply before debugging: check known error patterns first, then record every new resolved fix"
+version: "1.0.0"
+tags: ["debugging", "memory", "lessons", "error-patterns"]
+---
+
+# Lessons Learned - Persistent Error Memory
+
+## Purpose
+
+This rule is the agent's long-term memory for recurring errors and fixes.
+Always check this rule before debugging. If a matching error exists, apply that known fix first.
+
+## Required Workflow
+
+1. Before debugging, check this file for matching symptoms.
+2. If a match is found, apply the known fix immediately.
+3. If no match is found, debug using the `error-patterns` skill checklist.
+4. After every successful fix, append a new lesson entry.
+
+## Lesson Entry Format
+
+```markdown
+### [CATEGORY] Short title of the error
+- **Symptom**: What the error looked like (message, behavior)
+- **Root Cause**: Why it happened
+- **Fix**: Exact steps or code that resolved it
+- **Avoid**: What NOT to do next time
+- **Date**: YYYY-MM-DD
+```
+
+Allowed categories: `[BUILD]` `[DB]` `[API/AUTH]` `[UI]` `[TYPE]` `[CONFIG]` `[OTHER]`
+
+## Enforcement
+
+- This rule is non-overrideable.
+- Lesson recording is mandatory after each resolved error.
+- Do not remove existing lessons unless explicitly requested.
+
+## Known Lessons
+
+<!-- New lessons are appended below this line. Do not remove this comment. -->

package/templates/.claude/rules/{planning.mdc → planning.md}

@@ -4,12 +4,6 @@ description: "Apply when implementing features, designing systems, or making arc
 version: "1.0.0"
 tags: ["planning", "workflow", "documentation", "prompts"]
 alwaysApply: true
-triggers:
-  - "User asks to implement a new feature"
-  - "Making design or architecture decisions"
-  - "Planning a significant refactor"
-  - "Fixing bugs that require investigation"
-  - "Discussion produces decisions affecting architecture"
 ---
 
 ## Purpose

package/templates/.claude/rules/{security.mdc → security.md}

@@ -4,14 +4,6 @@ description: "Apply when implementing authentication, authorization, API validat
 alwaysApply: true
 version: "3.0.0"
 tags: ["security", "auth", "validation", "secrets", "owasp"]
-triggers:
-  - "User adds login/authentication to project"
-  - "Building API endpoints or handling user input"
-  - "Storing passwords, tokens, or sensitive data"
-  - "Validating form inputs or API requests"
-  - "Protecting against injection, XSS, CSRF"
-  - "Adding authorization/permissions to endpoints"
-  - "Integrating third-party APIs or external services"
 ---
 
 # Security Rules & Best Practices

package/templates/.claude/rules/{style.mdc → style.md}

@@ -6,12 +6,6 @@ version: "3.0.0"
 tags: ["style", "formatting", "naming", "quality"]
 globs:
   - "**/*"
-triggers:
-  - "Writing or reviewing code"
-  - "Setting up code formatting rules"
-  - "Naming variables, functions, or files"
-  - "Organizing module structure"
-  - "Refactoring or improving readability"
 ---
 
 # Code Style and Standards

package/templates/.claude/rules/{system-workflow.mdc → system-workflow.md}

@@ -3,12 +3,6 @@ title: "System Workflow Orchestration"
 description: "Apply when planning work phases, defining acceptance criteria, or establishing delivery gates and rollback strategies"
 version: "1.0.0"
 tags: ["workflow", "gates", "delivery", "governance"]
-triggers:
-  - "Starting a new feature or major change"
-  - "Planning implementation phases"
-  - "Defining acceptance criteria"
-  - "Establishing rollback procedures"
-  - "Preparing for release or deployment"
 ---
 
 ## Purpose

package/templates/.claude/rules/{testing.mdc → testing.md}

@@ -3,14 +3,6 @@ title: "Testing Guidelines & Best Practices"
 description: "Apply when adding tests, verifying coverage, or validating quality before deployment. Always required for business logic and critical flows"
 version: "3.0.0"
 tags: ["testing", "quality", "coverage", "e2e", "a11y"]
-triggers:
-  - "User requests tests for business logic"
-  - "Implementing a new feature"
-  - "Fixing a bug"
-  - "Need to verify API endpoints work"
-  - "Checking application behavior"
-  - "Hardening release artifacts"
-  - "CI/CD validation needed before deployment"
 ---
 
 # Testing Guidelines & Best Practices

package/templates/.claude/rules/{workflows.mdc → workflows.md}

@@ -6,11 +6,6 @@ version: "1.0.0"
 tags: ["workflow", "quality", "validation", "commit"]
 globs:
   - "**/*"
-triggers:
-  - "User asks about workflow or pre-commit steps"
-  - "Need to keep project validated"
-  - "Running quality gates before merge"
-  - "Post-hardening verification needed"
 ---
 
 # Development Workflow Guidelines

package/templates/CLAUDE.md

@@ -11,19 +11,20 @@ All policy, routing, and skill governance lives here — edit this file directly
 
 | Module | File | Apply when... |
 |--------|------|---------------|
-| Security | `.claude/rules/security.mdc` | Implementing authentication, validating inputs, protecting against injection attacks |
-| Testing | `.claude/rules/testing.mdc` | Adding tests, verifying coverage, validating quality before deployment |
-| Core | `.claude/rules/core.mdc` | Designing architecture, setting up projects, defining type systems |
-| Database | `.claude/rules/database.mdc` | Designing schema, building data access layers, optimizing queries |
-| Frontend | `.claude/rules/frontend.mdc` | Building UI components, designing pages, creating forms, implementing accessibility |
-| Style | `.claude/rules/style.mdc` | Organizing code, naming variables, improving clarity and maintainability |
-| System Workflow | `.claude/rules/system-workflow.mdc` | Planning delivery phases, defining acceptance criteria, establishing rollback |
-| Workflows | `.claude/rules/workflows.mdc` | Optimizing development process, running pre-commit checks, keeping project healthy |
-| Hardening | `.claude/rules/hardening.mdc` | Building distributed apps, protecting IP logic, preparing production releases |
-| Intent Routing | `.claude/rules/intent-routing.mdc` | Determining which rule applies, routing to correct execution pathway |
-| Planning | `.claude/rules/planning.mdc` | Implementing features, designing systems, making architectural decisions |
-| AI Integration | `.claude/rules/ai-integration.mdc` | Integrating LLMs, RAG pipelines, prompt engineering, AI-powered features |
-| Guardrails | `.claude/rules/guardrails.mdc` | Any destructive/irreversible action, scope expansion, dangerous requests |
+| Security | `.claude/rules/security.md` | Implementing authentication, validating inputs, protecting against injection attacks |
+| Testing | `.claude/rules/testing.md` | Adding tests, verifying coverage, validating quality before deployment |
+| Lessons Learned | `.claude/rules/lessons-learned.md` | Debugging recurring errors and applying previously resolved fixes first |
+| Core | `.claude/rules/core.md` | Designing architecture, setting up projects, defining type systems |
+| Database | `.claude/rules/database.md` | Designing schema, building data access layers, optimizing queries |
+| Frontend | `.claude/rules/frontend.md` | Building UI components, designing pages, creating forms, implementing accessibility |
+| Style | `.claude/rules/style.md` | Organizing code, naming variables, improving clarity and maintainability |
+| System Workflow | `.claude/rules/system-workflow.md` | Planning delivery phases, defining acceptance criteria, establishing rollback |
+| Workflows | `.claude/rules/workflows.md` | Optimizing development process, running pre-commit checks, keeping project healthy |
+| Hardening | `.claude/rules/hardening.md` | Building distributed apps, protecting IP logic, preparing production releases |
+| Intent Routing | `.claude/rules/intent-routing.md` | Determining which rule applies, routing to correct execution pathway |
+| Planning | `.claude/rules/planning.md` | Implementing features, designing systems, making architectural decisions |
+| AI Integration | `.claude/rules/ai-integration.md` | Integrating LLMs, RAG pipelines, prompt engineering, AI-powered features |
+| Guardrails | `.claude/rules/guardrails.md` | Any destructive/irreversible action, scope expansion, dangerous requests |
 
 ### Skill modules (`.github/skills/`)
 
@@ -31,6 +32,7 @@ All policy, routing, and skill governance lives here — edit this file directly
 |-------|------|------------------|
 | app-hardening | `.github/skills/app-hardening/SKILL.md` | Hardening, anti-tamper, integrity controls |
 | bug-triage | `.github/skills/bug-triage/SKILL.md` | Something is broken, failing, or crashing |
+| error-patterns | `.github/skills/error-patterns/SKILL.md` | Debugging with persistent lessons memory and automatic fix recording |
 | feature-delivery | `.github/skills/feature-delivery/SKILL.md` | Build/add/implement feature work |
 | find-skills | `.github/skills/find-skills/SKILL.md` | User asks to discover a skill |
 | ui-ux-pro-max | `.github/skills/ui-ux-pro-max/SKILL.md` | UI, layout, design, visual work |
@@ -59,40 +61,45 @@ Subagents are bounded agents with limited tool access. They inherit all policy f
 
 ## Always Enforce
 
-1. **Security-first (non-overrideable)** — `.claude/rules/security.mdc`
+1. **Security-first (non-overrideable)** — `.claude/rules/security.md`
    - Validate all external inputs at boundaries.
    - Require authentication and role-based authorization for protected operations.
    - Rate-limit public APIs.
    - Never expose secrets, credentials, or PII in logs/errors/responses.
 
-2. **Testing discipline (non-overrideable)** — `.claude/rules/testing.mdc`
+2. **Testing discipline (non-overrideable)** — `.claude/rules/testing.md`
    - Coverage mix target: Unit 80% / Integration 15% / E2E 5%.
    - Business logic must have tests; critical flows need integration coverage.
    - Never disable/remove tests to pass builds.
 
-3. **Type safety and runtime boundaries** — `.claude/rules/core.mdc`
+3. **Lessons Learned (non-overrideable)** — `.claude/rules/lessons-learned.md`
+   - On any error, read lessons first; if matched, apply the known fix immediately.
+   - If new, debug via the `error-patterns` skill checklist and record the resolved fix.
+   - Keep lessons structured and persistent so future sessions reuse known solutions.
+
+4. **Type safety and runtime boundaries** — `.claude/rules/core.md`
    - Strong internal typing, runtime validation at boundaries, explicit error models.
 
-4. **Database integrity** — `.claude/rules/database.mdc`
+5. **Database integrity** — `.claude/rules/database.md`
    - Prefer ORM/ODM, justify raw queries, enforce DB constraints, prevent N+1, reversible migrations.
 
-5. **Frontend standards** — `.claude/rules/frontend.mdc`
+6. **Frontend standards** — `.claude/rules/frontend.md`
    - WCAG 2.1 AA, responsive defaults, clear loading/error states, no unsafe client trust.
 
-6. **Style and consistency** — `.claude/rules/style.mdc`
+7. **Style and consistency** — `.claude/rules/style.md`
    - Consistent naming, small composable modules, explicit contracts, no magic values.
 
-7. **Workflow discipline** — `.claude/rules/system-workflow.mdc`, `.claude/rules/workflows.mdc`
+8. **Workflow discipline** — `.claude/rules/system-workflow.md`, `.claude/rules/workflows.md`
    - Feature branches only, no direct main edits, deterministic PR structure, review gates.
 
-8. **Hardening mode** — `.claude/rules/hardening.mdc`
+9. **Hardening mode** — `.claude/rules/hardening.md`
    - In hardening/audit contexts: assume hostile input, threat-model, validate config safety, strict rate limits, dependency audit.
 
-9. **Planning discipline** — `.claude/rules/planning.mdc`
+10. **Planning discipline** — `.claude/rules/planning.md`
    - Every feature discussion or implementation produces a `.github/prompts/` plan file.
    - Plans are updated as work progresses, not discarded.
 
-10. **Guardrails (non-overrideable)** — `.claude/rules/guardrails.mdc`
+11. **Guardrails (non-overrideable)** — `.claude/rules/guardrails.md`
    - Require `CONFIRM-DESTRUCTIVE:<target>` token before any destructive/irreversible action.
    - Work only within the defined task scope; no silent expansion.
    - Classify every action by reversibility before executing.
@@ -106,7 +113,7 @@ All items above are policy-level requirements; skills and command modes cannot w
 
 ## Intent Routing
 
-Use `.github/instructions/rules/intent-routing.mdc` and route each task to one primary module:
+Use `.claude/rules/intent-routing.md` and route each task to one primary module:
 
 - UI/Design → Frontend
 - API/Logic → Security + Core
@@ -115,6 +122,7 @@ Use `.github/instructions/rules/intent-routing.mdc` and route each task to one p
 - Refactor/Cleanup → Style
 - Audit/Production readiness → Hardening
 - Feature planning → Planning
+- Debugging / recurring failures → Lessons Learned + error-patterns skill
 - LLM/AI work → AI Integration
 - Scope creep / dangerous action / agent behavioral safety → Guardrails
 - Multi-step orchestration / planning / code review → Subagents

package/templates/README.md

@@ -124,22 +124,25 @@ your-project/
 │   └── README.md                   # Human-readable setup guide
 │
 ├── .github/
-│   ├── instructions/                # Generated compatibility wrappers + rules
-│   │   ├── AGENTS.md
-│   │   └── rules/
-│   │   ├── core.mdc               # Core development principles
-│   │   ├── security.mdc           # Security patterns (CRITICAL)
-│   │   ├── testing.mdc            # Testing strategy
-│   │   ├── frontend.mdc           # Frontend patterns
-│   │   ├── database.mdc           # Database patterns
-│   │   └── style.mdc              # Code style guidelines
+│   ├── instructions/                # Compatibility pointer directory
 │   ├── skills/
 │   │   ├── find-skills/           # Skill discovery helper
+│   │   ├── error-patterns/         # Persistent error-debugging memory workflow
 │   │   ├── ui-ux-pro-max/         # Advanced UI/UX design implementation skill
 │   │   ├── README.md              # Guide for creating custom skills
 │   │   └── [your-custom-skills]/  # Your project-specific skills
 │   └── copilot-instructions.md    # Compatibility shim for Copilot
 │
+├── .claude/
+│   ├── rules/                      # Canonical rules source
+│   │   ├── core.md
+│   │   ├── security.md
+│   │   ├── testing.md
+│   │   ├── frontend.md
+│   │   ├── database.md
+│   │   ├── style.md
+│   │   └── lessons-learned.md
+│
 ├── agents/                          # 🤖 Deterministic command contracts
 │   └── commands/
 │   │   ├── SCHEMA.md              # Global slash-command response schema
@@ -273,8 +276,8 @@ Skills define *how to execute specific tasks*, complementing rules that define *
 - **[AGENTS.MD](AGENTS.MD)** – AI assistant guide
 - **[agent-docs/ARCHITECTURE.md](agent-docs/ARCHITECTURE.md)** – Project architecture & tech stack guidance
 - **[.github/skills/README.md](.github/skills/README.md)** – Custom skills guide
-- **[.github/instructions/rules/security.mdc](.github/instructions/rules/security.mdc)** – Security patterns (CRITICAL)
-- **[.github/instructions/rules/testing.mdc](.github/instructions/rules/testing.mdc)** – Testing strategy
+- **[.claude/rules/security.md](.claude/rules/security.md)** – Security patterns (CRITICAL)
+- **[.claude/rules/testing.md](.claude/rules/testing.md)** – Testing strategy
 
 ### 5. Start Building
 
@@ -300,7 +303,7 @@ Your AI will follow the enterprise patterns automatically!
 ✅ Sanitize outputs to prevent injection attacks  
 ✅ Never expose sensitive data in error messages or logs
 
-**Reference**: [.github/instructions/rules/security.mdc](.github/instructions/rules/security.mdc)
+**Reference**: [.claude/rules/security.md](.claude/rules/security.md)
 
 ### Testing Strategy
 
@@ -308,7 +311,7 @@ Your AI will follow the enterprise patterns automatically!
 - **15% Integration Tests** – API endpoints, database operations
 - **5% E2E Tests** – Critical user journeys
 
-**Reference**: [.github/instructions/rules/testing.mdc](.github/instructions/rules/testing.mdc)
+**Reference**: [.claude/rules/testing.md](.claude/rules/testing.md)
 
 ### Agent-Based Architecture
 
@@ -395,7 +398,7 @@ await agentsTemplated.install('./my-project', {
 
 When contributing to this template:
 1. Maintain technology-agnostic patterns
-2. Update relevant rule files in `.github/instructions/rules/`
+2. Update relevant rule files in `.claude/rules/`
 3. Keep documentation synchronized with code changes
 4. Follow security and testing patterns
 5. Ensure AI assistant configurations remain compatible

package/templates/agent-docs/ARCHITECTURE.md

@@ -5,7 +5,7 @@ These guidelines are for both humans and AI assistants working with any technolo
 
 - Canonical AI policy source lives in `CLAUDE.md`.
 - **Agent responsibilities** and MCP integration are documented in `AGENTS.MD`.
-- **Detailed implementation rules** live in `.github/instructions/rules/*.mdc` files.
+- **Detailed implementation rules** live in `.claude/rules/*.md` files.
 - **Custom skills** for domain-specific tasks are organized in `.github/skills/` (see [Skills Guide](../.github/skills/README.md)).
 
 Read this file first to understand the architecture, then consult `AGENTS.MD` for agent delegation.
@@ -223,7 +223,7 @@ Review the options above and select technologies that fit your:
 - **Timeline** and development velocity requirements
 
 ### 2. Adapt the Template
-- Update `.github/instructions/rules/*.mdc` files with technology-specific patterns
+- Update `.claude/rules/*.md` files with technology-specific patterns
 - Keep `.cursorrules`, `.github/copilot-instructions.md`, `AGENTS.MD`, and `CLAUDE.md` as minimal wrappers that point to `CLAUDE.md`
 - Update `CLAUDE.md` with stack-specific guidelines
 - Create appropriate configuration files for your chosen tools

package/templates/agent-docs/README.md

@@ -9,7 +9,7 @@ Depending on what you installed, you may have:
 - **AGENTS.MD**: Generic compatibility wrapper for AI assistants
 - **ARCHITECTURE.md**: Project guidelines and architecture
 - **CLAUDE.md**: Canonical policy source (single source of truth)
-- **.github/instructions/rules/**: Rule modules (`*.mdc`)
+- **.claude/rules/**: Rule modules (`*.md`)
 - **.github/skills/**: Skill modules (`*/SKILL.md`)
 - **CLAUDE.md**: Claude compatibility wrapper
 - **.github/copilot-instructions.md**: GitHub Copilot compatibility wrapper
@@ -35,7 +35,7 @@ agents-templated list
 
 ## Rules and Skills
 
-- **Rules** (`.github/instructions/rules/*.mdc`): Define *how to behave* - patterns, principles, and standards for your team
+- **Rules** (`.claude/rules/*.md`): Define *how to behave* - patterns, principles, and standards for your team
 - **Skills** (`.github/skills/*/SKILL.md`): Define *how to execute specific tasks* - domain-specific workflows and specialized knowledge
 
 ### Using Skills in Your AI Assistants

package/templates/agents/rules/{ai-integration.mdc → ai-integration.md}

@@ -5,14 +5,6 @@ version: "3.0.0"
 tags: ["ai", "llm", "openai", "anthropic", "rag", "prompt-engineering", "safety"]
 alwaysApply: false
 globs: ["**/*llm*", "**/*openai*", "**/*anthropic*", "**/*langchain*", "**/*rag*", "**/ai/**"]
-triggers:
-  - "Integrating OpenAI or other LLM API"
-  - "Building RAG pipeline or semantic search"
-  - "Implementing prompt template or engineering"
-  - "Adding AI-powered feature to application"
-  - "Evaluating LLM responses or quality"
-  - "Optimizing LLM API costs"
-  - "Implementing AI moderation or safety controls"
 ---
 
 ## Purpose

package/templates/agents/rules/{core.mdc → core.md}

@@ -6,13 +6,6 @@ version: "3.0.0"
 tags: ["architecture", "core", "enterprise", "technology-agnostic"]
 globs:
   - "*"
-triggers:
-  - "Designing application architecture"
-  - "Setting up new project or module"
-  - "Defining type systems and validation"
-  - "Organizing code structure"
-  - "Improving code quality standards"
-  - "Making testing or performance decisions"
 ---
 
 ## Developer Identity

package/templates/agents/rules/{database.mdc → database.md}

@@ -1,4 +1,4 @@
----
+---
 title: "Database and Data Layer Guidelines"
 description: "Apply when designing schema, building data access layers, optimizing queries, or managing database operations"
 alwaysApply: true
@@ -7,14 +7,6 @@ tags: ["database", "backend", "data", "orm", "schema"]
 globs:
   - "src/models/**/*"
   - "src/data/**/*"
-triggers:
-  - "Designing database schema"
-  - "Adding database migrations"
-  - "Building data access layer"
-  - "Querying or filtering data"
-  - "Optimizing slow queries"
-  - "Managing relationships between entities"
-  - "Handling data validation in models"
 ---
 
 # Database and Data Layer Guidelines

package/templates/agents/rules/{frontend.mdc → frontend.md}

@@ -1,4 +1,4 @@
----
+---
 title: "Frontend Development Guidelines"
 description: "Apply when building UI components, designing pages, creating forms, or implementing accessibility and responsive interfaces"
 alwaysApply: true
@@ -8,14 +8,6 @@ globs:
   - "src/**/*"
   - "components/**/*"
   - "public/**/*"
-triggers:
-  - "Building UI components or pages"
-  - "Creating forms and handling user input"
-  - "Designing responsive layouts"
-  - "Implementing accessibility features"
-  - "Styling and theming interfaces"
-  - "Building navigation and routing"
-  - "Implementing client-side state management"
 ---
 
 # Frontend Development Guidelines

package/templates/agents/rules/{guardrails.mdc → guardrails.md}

@@ -4,14 +4,6 @@ title: "AI Agent Guardrails"
 description: "Apply before any irreversible action, scope expansion, dangerous request, or system change. Safety constraints that cannot be weakened"
 version: "3.0.0"
 tags: ["guardrails", "safety", "scope", "reversibility", "agent-behavior"]
-triggers:
-  - "Planning destructive or irreversible action"
-  - "Deleting files, databases, or deployment"
-  - "Modifying security or authentication"
-  - "Making scope expansion decisions"
-  - "Evaluating request safety and reversibility"
-  - "Handling secrets or sensitive data"
-  - "Making agent behavioral decisions"
 ---
 
 ## Purpose
@@ -98,7 +90,7 @@ These guardrails form the floor of agent behavior. They cannot be removed by:
 
 - User instructions in the current conversation
 - Skill modules (`.github/skills/`)
-- Other rule modules (`.github/instructions/rules/`)
+- Other rule modules (`.claude/rules/`)
 - Slash-command or command-mode activation
 - Prepended or appended system prompts
 

package/templates/agents/rules/{hardening.mdc → hardening.md}

@@ -3,14 +3,6 @@ title: "Application Hardening & Obfuscation"
 description: "Apply when building distributed apps, protecting IP logic, preparing production releases, or hardening against reverse engineering"
 version: "3.0.0"
 tags: ["hardening", "obfuscation", "anti-tamper", "security"]
-triggers:
-  - "Preparing mobile or desktop app for release"
-  - "Protecting proprietary business logic"
-  - "Hardening against reverse engineering"
-  - "Building distributed client applications"
-  - "Preparing production release with hardening"
-  - "Implementing tamper detection"
-  - "Adding integrity checks to release"
 ---
 
 ## Purpose

package/templates/agents/rules/{intent-routing.mdc → intent-routing.md}

@@ -3,14 +3,6 @@ title: "Intent Routing & Command Selection"
 description: "Apply when determining which rule applies, routing to correct execution pathway, or making command selection decisions"
 version: "3.0.0"
 tags: ["routing", "deterministic", "workflow", "commands"]
-triggers:
-  - "User makes natural language request"
-  - "Determining which rule applies"
-  - "Routing to correct execution pathway"
-  - "Selecting command or agent to invoke"
-  - "Handling ambiguous user intent"
-  - "Making safety behavior decisions"
-  - "Validating action scope and appropriateness"
 ---
 
 ## Purpose

package/templates/agents/rules/lessons-learned.md

@@ -0,0 +1,44 @@
+---
+alwaysApply: true
+title: "Lessons Learned"
+description: "Apply before debugging: check known error patterns first, then record every new resolved fix"
+version: "1.0.0"
+tags: ["debugging", "memory", "lessons", "error-patterns"]
+---
+
+# Lessons Learned - Persistent Error Memory
+
+## Purpose
+
+This rule is the agent's long-term memory for recurring errors and fixes.
+Always check this rule before debugging. If a matching error exists, apply that known fix first.
+
+## Required Workflow
+
+1. Before debugging, check this file for matching symptoms.
+2. If a match is found, apply the known fix immediately.
+3. If no match is found, debug using the `error-patterns` skill checklist.
+4. After every successful fix, append a new lesson entry.
+
+## Lesson Entry Format
+
+```markdown
+### [CATEGORY] Short title of the error
+- **Symptom**: What the error looked like (message, behavior)
+- **Root Cause**: Why it happened
+- **Fix**: Exact steps or code that resolved it
+- **Avoid**: What NOT to do next time
+- **Date**: YYYY-MM-DD
+```
+
+Allowed categories: `[BUILD]` `[DB]` `[API/AUTH]` `[UI]` `[TYPE]` `[CONFIG]` `[OTHER]`
+
+## Enforcement
+
+- This rule is non-overrideable.
+- Lesson recording is mandatory after each resolved error.
+- Do not remove existing lessons unless explicitly requested.
+
+## Known Lessons
+
+<!-- New lessons are appended below this line. Do not remove this comment. -->

package/templates/agents/rules/{planning.mdc → planning.md}

@@ -4,14 +4,6 @@ description: "Apply when implementing features, designing systems, discussing ar
 version: "3.0.0"
 tags: ["planning", "workflow", "documentation", "prompts"]
 alwaysApply: true
-triggers:
-  - "User requests a new feature"
-  - "Planning implementation approach"
-  - "Discussing architectural changes"
-  - "Breaking down user stories"
-  - "Creating acceptance criteria"
-  - "Designing database schema"
-  - "Planning deployment phases"
 ---
 
 ## Purpose

package/templates/agents/rules/{security.mdc → security.md}

@@ -1,17 +1,9 @@
----
+---
 title: "Security Rules & Best Practices"
 description: "Apply when implementing authentication, authorization, API validation, secrets management, or protecting against OWASP Top 10 vulnerabilities"
 alwaysApply: true
 version: "3.0.0"
 tags: ["security", "auth", "validation", "secrets", "owasp"]
-triggers:
-  - "User adds login/authentication to project"
-  - "Building API endpoints or handling user input"
-  - "Storing passwords, tokens, or sensitive data"
-  - "Validating form inputs or API requests"
-  - "Protecting against injection, XSS, CSRF"
-  - "Adding authorization/permissions to endpoints"
-  - "Integrating third-party APIs or external services"
 ---
 
 # Security Rules & Best Practices

package/templates/agents/rules/{style.mdc → style.md}

@@ -1,4 +1,4 @@
----
+---
 title: "Code Style and Standards"
 description: "Apply when organizing code, naming variables/functions, improving clarity, formatting with consistency, and maintaining code quality"
 alwaysApply: true
@@ -6,14 +6,6 @@ version: "3.0.0"
 tags: ["style", "formatting", "naming", "quality"]
 globs:
   - "**/*"
-triggers:
-  - "Writing new code or functions"
-  - "Organizing code structure"
-  - "Naming variables, functions, or classes"
-  - "Formatting code for readability"
-  - "Improving code documentation"
-  - "Refactoring for clarity"
-  - "Following project conventions"
 ---
 
 # Code Style and Standards

package/templates/agents/rules/{system-workflow.mdc → system-workflow.md}

@@ -3,14 +3,6 @@ title: "System Workflow Orchestration"
 description: "Apply when planning delivery phases, defining acceptance criteria, establishing rollback procedures, or orchestrating multi-step workflows"
 version: "3.0.0"
 tags: ["workflow", "gates", "delivery", "governance"]
-triggers:
-  - "Implementing feature with multiple phases"
-  - "Defining deployment gates and approval"
-  - "Planning rollback strategy"
-  - "Creating acceptance criteria"
-  - "Coordinating deployment across services"
-  - "Planning database migration"
-  - "Managing breaking API changes"
 ---
 
 ## Purpose

package/templates/agents/rules/{testing.mdc → testing.md}

@@ -1,16 +1,8 @@
----
+---
 title: "Testing Guidelines & Best Practices"
 description: "Apply when adding tests, verifying coverage, or validating quality before deployment. Always required for business logic and critical flows"
 version: "3.0.0"
 tags: ["testing", "quality", "coverage", "e2e", "a11y"]
-triggers:
-  - "User requests tests for business logic"
-  - "Implementing a new feature"
-  - "Fixing a bug"
-  - "Need to verify API endpoints work"
-  - "Checking application behavior"
-  - "Hardening release artifacts"
-  - "CI/CD validation needed before deployment"
 ---
 
 # Testing Guidelines & Best Practices

package/templates/agents/rules/{workflows.mdc → workflows.md}

@@ -6,14 +6,6 @@ version: "3.0.0"
 tags: ["workflow", "quality", "validation", "commit"]
 globs:
   - "**/*"
-triggers:
-  - "Running pre-commit hooks"
-  - "Validating code quality gates"
-  - "Setting up CI/CD pipeline"
-  - "Checking code before commit"
-  - "Running linting or formatting"
-  - "Executing test suites automatically"
-  - "Maintaining project health and standards"
 ---
 
 # Development Workflow Guidelines

package/templates/agents/skills/README.md

@@ -61,6 +61,8 @@ To create a new skill for your specific domain:
 │   └── SKILL.md              # Systematic feature scoping and execution contracts
 ├── bug-triage/
 │   └── SKILL.md              # Reproduction-first debugging and regression workflows
+├── error-patterns/
+│   └── SKILL.md              # Persistent debugging memory and known-fix application
 ├── app-hardening/
 │   └── SKILL.md              # Risk-based hardening and obfuscation guidance
 ├── ui-ux-pro-max/
@@ -96,6 +98,7 @@ Consider creating skills for:
 
 - `feature-delivery`: Use when user asks are broad and you need objective, scope, acceptance criteria, and validation plan.
 - `bug-triage`: Use for defects and regressions requiring reproducible evidence, root-cause isolation, and minimal safe patches.
+- `error-patterns`: Use when errors repeat to apply known fixes from lessons-learned and automatically record new resolutions.
 - `app-hardening`: Use for high-risk/distributed runtimes to enforce hardening profile, obfuscation decisions, and release evidence.
 
 ## Using Skills in Your Project

package/templates/agents/skills/error-patterns/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: error-patterns
+description: >
+  Activate this skill whenever something is broken, failing, erroring, or crashing, especially
+  for build errors, type errors, database/migration failures, API/auth issues, and UI bugs.
+  Also activate when the user says "fix this", "it's broken", "I'm getting an error", or
+  "this keeps happening".
+---
+
+# Error Patterns
+
+You are debugging with persistent memory. Every fix should be recorded so it does not need to be solved twice.
+
+## Step 1 - Check Lessons First (Always)
+
+Before writing any fix, read `.claude/rules/lessons-learned.md`.
+
+- Search for symptoms that match the current error.
+- If a match is found, apply the known fix directly and state that the known fix was used.
+- If no match is found, continue to Step 2.
+
+## Step 2 - Diagnose by Category
+
+### [BUILD] Build / Type Errors
+- Read the full error trace, not just the first line.
+- Check for version mismatches, missing imports, circular dependencies, and config issues.
+- Verify lock file and dependency sync.
+
+### [DB] Database / Migration Errors
+- Check whether the migration already ran.
+- Verify DB URL and environment target.
+- Check for schema drift between model and database.
+- Avoid destructive migrations without a backup.
+
+### [API/AUTH] API / Auth Errors
+- Check token expiry, missing headers, and wrong scopes.
+- Verify environment variables for keys/secrets.
+- Check CORS and middleware order.
+- Log request/response safely (no secrets).
+
+### [UI] Frontend / UI Bugs
+- Check hydration mismatches.
+- Verify null/undefined guards and prop contracts.
+- Check list keys and class conflicts.
+- Confirm loading and error states are handled.
+
+## Step 3 - Apply the Fix
+
+- Make the minimum safe change needed.
+- Do not expand scope beyond the reported error.
+
+## Step 4 - Record the Lesson (Mandatory)
+
+After every successful fix, append to `.claude/rules/lessons-learned.md` using:
+
+```markdown
+### [CATEGORY] Short title of the error
+- **Symptom**: What the error looked like (message, behavior)
+- **Root Cause**: Why it happened
+- **Fix**: Exact steps or code that resolved it
+- **Avoid**: What NOT to do next time
+- **Date**: YYYY-MM-DD
+```
+
+## Step 5 - User Confirmation Message
+
+After fixing and recording, respond with one of:
+
+- `Fixed. I've saved this to lessons-learned so we won't have to solve it again.`
+- `Found this in lessons-learned and applied the known fix.`