diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index cbbcd16..a2a5b31 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,331 +1,343 @@ { - "name": "claude-code-skills", - "owner": { - "name": "Alireza Rezvani", - "url": "https://alirezarezvani.com" + "name": "claude-code-skills", + "owner": { + "name": "Alireza Rezvani", + "url": "https://alirezarezvani.com" + }, + "description": "Production-ready skill packages for Claude AI - 86 expert skills across marketing, engineering, product, C-level advisory, project management, regulatory compliance, business growth, and finance", + "homepage": "https://github.com/alirezarezvani/claude-skills", + "repository": "https://github.com/alirezarezvani/claude-skills", + "metadata": { + "description": "87+ production-ready skill packages across 9 domains: marketing, engineering, engineering-advanced, product, C-level advisory, project management, regulatory compliance, business growth, and finance", + "version": "2.1.0" + }, + "plugins": [ + { + "name": "marketing-skills", + "source": "./marketing-skill", + "description": "6 marketing skills: content creator, demand generation, product marketing, ASO, social media analytics, campaign analytics", + "version": "1.0.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "marketing", + "content", + "seo", + "demand-gen", + "social-media" + ], + "category": "marketing" }, - "description": "Production-ready skill packages for Claude AI - 86 expert skills across marketing, engineering, product, C-level advisory, project management, regulatory compliance, business growth, and finance", - "homepage": "https://github.com/alirezarezvani/claude-skills", - "repository": "https://github.com/alirezarezvani/claude-skills", - "metadata": { - "description": "87+ production-ready skill packages across 9 domains: marketing, engineering, engineering-advanced, product, C-level advisory, project management, regulatory compliance, business growth, and finance", - "version": "2.0.0" + { + "name": "engineering-skills", + "source": "./engineering-team", + "description": "21 engineering skills: architecture, frontend, backend, fullstack, QA, DevOps, security, AI/ML, data engineering", + "version": "1.0.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "engineering", + "architecture", + "frontend", + "backend", + "devops", + "security", + "ai", + "ml", + "data" + ], + "category": "development" }, - "plugins": [ - { - "name": "marketing-skills", - "source": "./marketing-skill", - "description": "6 marketing skills: content creator, demand generation, product marketing, ASO, social media analytics, campaign analytics", - "version": "1.0.0", - "author": { - "name": "Alireza Rezvani" - }, - "keywords": [ - "marketing", - "content", - "seo", - "demand-gen", - "social-media" - ], - "category": "marketing" - }, - { - "name": "engineering-skills", - "source": "./engineering-team", - "description": "21 engineering skills: architecture, frontend, backend, fullstack, QA, DevOps, security, AI/ML, data engineering", - "version": "1.0.0", - "author": { - "name": "Alireza Rezvani" - }, - "keywords": [ - "engineering", - "architecture", - "frontend", - "backend", - "devops", - "security", - "ai", - "ml", - "data" - ], - "category": "development" - }, - { - "name": "engineering-advanced-skills", - "source": "./engineering", - "description": "25 POWERFUL-tier engineering skills: agent designer, RAG architect, database designer, migration architect, observability designer, dependency auditor, release manager, API reviewer, CI/CD pipeline builder, MCP server builder, skill security auditor, and more", - "version": "2.0.0", - "author": { - "name": "Alireza Rezvani" - }, - "keywords": [ - "powerful", - "agent-design", - "rag", - "database", - "migration", - "observability", - "dependency-audit", - "release", - "api-review", - "ci-cd", - "mcp", - "monorepo", - "performance", - "runbook", - "changelog", - "onboarding", - "worktree", - "security-audit", - "vulnerability-scanner" - ], - "category": "development" - }, - { - "name": "product-skills", - "source": "./product-team", - "description": "8 product skills: product manager toolkit, agile product owner, product strategist, UX researcher, UI design system, and 3 more", - "version": "1.0.0", - "author": { - "name": "Alireza Rezvani" - }, - "keywords": [ - "product", - "pm", - "agile", - "ux", - "design-system" - ], - "category": "product" - }, - { - "name": "c-level-skills", - "source": "./c-level-advisor", - "description": "2 C-level advisory skills: CEO advisor, CTO advisor", - "version": "1.0.0", - "author": { - "name": "Alireza Rezvani" - }, - "keywords": [ - "ceo", - "cto", - "executive", - "strategy", - "leadership" - ], - "category": "leadership" - }, - { - "name": "pm-skills", - "source": "./project-management", - "description": "6 project management skills: senior PM, scrum master, Jira expert, Confluence expert, Atlassian admin, template creator", - "version": "1.0.0", - "author": { - "name": "Alireza Rezvani" - }, - "keywords": [ - "project-management", - "scrum", - "agile", - "jira", - "confluence", - "atlassian" - ], - "category": "project-management" - }, - { - "name": "ra-qm-skills", - "source": "./ra-qm-team", - "description": "12 regulatory affairs & quality management skills for HealthTech/MedTech: ISO 13485, MDR, FDA, GDPR, ISO 27001 compliance", - "version": "1.0.0", - "author": { - "name": "Alireza Rezvani" - }, - "keywords": [ - "regulatory", - "quality", - "compliance", - "iso-13485", - "mdr", - "fda", - "gdpr", - "medtech" - ], - "category": "compliance" - }, - { - "name": "business-growth-skills", - "source": "./business-growth", - "description": "4 business & growth skills: customer success manager, sales engineer, revenue operations, and more", - "version": "1.0.0", - "author": { - "name": "Alireza Rezvani" - }, - "keywords": [ - "customer-success", - "sales-engineering", - "revenue-operations", - "business-growth" - ], - "category": "business-growth" - }, - { - "name": "finance-skills", - "source": "./finance", - "description": "1 finance skill: financial analyst with ratio analysis, DCF valuation, budgeting, and forecasting", - "version": "1.0.0", - "author": { - "name": "Alireza Rezvani" - }, - "keywords": [ - "finance", - "dcf", - "valuation", - "budgeting", - "forecasting" - ], - "category": "finance" - }, - { - "name": "content-creator", - "source": "./marketing-skill/content-creator", - "description": "Brand voice analysis, SEO optimization, content frameworks for marketing content creation", - "version": "1.0.0", - "author": { - "name": "Alireza Rezvani" - }, - "keywords": [ - "content", - "seo", - "brand-voice", - "marketing" - ], - "category": "marketing" - }, - { - "name": "demand-gen", - "source": "./marketing-skill/marketing-demand-acquisition", - "description": "Demand generation, paid media, SEO, partnerships for Series A+ startups", - "version": "1.0.0", - "author": { - "name": "Alireza Rezvani" - }, - "keywords": [ - "demand-gen", - "paid-media", - "acquisition", - "marketing" - ], - "category": "marketing" - }, - { - "name": "fullstack-engineer", - "source": "./engineering-team/senior-fullstack", - "description": "End-to-end application development with Next.js, GraphQL, PostgreSQL", - "version": "1.0.0", - "author": { - "name": "Alireza Rezvani" - }, - "keywords": [ - "fullstack", - "nextjs", - "graphql", - "postgresql" - ], - "category": "development" - }, - { - "name": "aws-architect", - "source": "./engineering-team/aws-solution-architect", - "description": "AWS solution architecture with serverless, cost optimization, and security best practices", - "version": "1.0.0", - "author": { - "name": "Alireza Rezvani" - }, - "keywords": [ - "aws", - "cloud", - "serverless", - "architecture" - ], - "category": "development" - }, - { - "name": "product-manager", - "source": "./product-team/product-manager-toolkit", - "description": "RICE prioritization, customer interview analysis, PRD templates for product managers", - "version": "1.0.0", - "author": { - "name": "Alireza Rezvani" - }, - "keywords": [ - "product-management", - "rice", - "prd", - "prioritization" - ], - "category": "product" - }, - { - "name": "scrum-master", - "source": "./project-management/scrum-master", - "description": "Agile facilitation, sprint planning, retrospectives for Scrum teams", - "version": "1.0.0", - "author": { - "name": "Alireza Rezvani" - }, - "keywords": [ - "scrum", - "agile", - "sprint", - "retrospective" - ], - "category": "project-management" - }, - { - "name": "skill-security-auditor", - "source": "./engineering/skill-security-auditor", - "description": "Security audit and vulnerability scanner for AI agent skills. Scans for malicious code, prompt injection, data exfiltration, supply chain risks, and privilege escalation before installation. Zero dependencies, PASS/WARN/FAIL verdicts with remediation guidance.", - "version": "2.0.0", - "author": { - "name": "Alireza Rezvani" - }, - "keywords": [ - "security", - "audit", - "vulnerability", - "scanner", - "malware", - "prompt-injection", - "supply-chain", - "code-review", - "safety", - "pre-install" - ], - "category": "security" - }, - { - "name": "playwright-pro", - "source": "./engineering-team/playwright-pro", - "description": "Production-grade Playwright testing toolkit. 9 skills, 3 agents, 55 templates, TestRail + BrowserStack MCP integrations. Generate tests, fix flaky failures, migrate from Cypress/Selenium.", - "version": "1.0.0", - "author": { - "name": "Alireza Rezvani" - }, - "keywords": [ - "playwright", - "testing", - "e2e", - "qa", - "test-automation", - "browserstack", - "testrail", - "cross-browser", - "migration", - "cypress", - "selenium" - ], - "category": "development" - } - ] -} \ No newline at end of file + { + "name": "engineering-advanced-skills", + "source": "./engineering", + "description": "25 POWERFUL-tier engineering skills: agent designer, RAG architect, database designer, migration architect, observability designer, dependency auditor, release manager, API reviewer, CI/CD pipeline builder, MCP server builder, skill security auditor, and more", + "version": "2.0.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "powerful", + "agent-design", + "rag", + "database", + "migration", + "observability", + "dependency-audit", + "release", + "api-review", + "ci-cd", + "mcp", + "monorepo", + "performance", + "runbook", + "changelog", + "onboarding", + "worktree", + "security-audit", + "vulnerability-scanner" + ], + "category": "development" + }, + { + "name": "product-skills", + "source": "./product-team", + "description": "8 product skills: product manager toolkit, agile product owner, product strategist, UX researcher, UI design system, and 3 more", + "version": "1.0.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "product", + "pm", + "agile", + "ux", + "design-system" + ], + "category": "product" + }, + { + "name": "c-level-skills", + "source": "./c-level-advisor", + "description": "2 C-level advisory skills: CEO advisor, CTO advisor", + "version": "1.0.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "ceo", + "cto", + "executive", + "strategy", + "leadership" + ], + "category": "leadership" + }, + { + "name": "pm-skills", + "source": "./project-management", + "description": "6 project management skills: senior PM, scrum master, Jira expert, Confluence expert, Atlassian admin, template creator", + "version": "1.0.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "project-management", + "scrum", + "agile", + "jira", + "confluence", + "atlassian" + ], + "category": "project-management" + }, + { + "name": "ra-qm-skills", + "source": "./ra-qm-team", + "description": "12 regulatory affairs & quality management skills for HealthTech/MedTech: ISO 13485, MDR, FDA, GDPR, ISO 27001 compliance", + "version": "1.0.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "regulatory", + "quality", + "compliance", + "iso-13485", + "mdr", + "fda", + "gdpr", + "medtech" + ], + "category": "compliance" + }, + { + "name": "business-growth-skills", + "source": "./business-growth", + "description": "4 business & growth skills: customer success manager, sales engineer, revenue operations, and more", + "version": "1.0.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "customer-success", + "sales-engineering", + "revenue-operations", + "business-growth" + ], + "category": "business-growth" + }, + { + "name": "finance-skills", + "source": "./finance", + "description": "1 finance skill: financial analyst with ratio analysis, DCF valuation, budgeting, and forecasting", + "version": "1.0.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "finance", + "dcf", + "valuation", + "budgeting", + "forecasting" + ], + "category": "finance" + }, + { + "name": "content-creator", + "source": "./marketing-skill/content-creator", + "description": "Brand voice analysis, SEO optimization, content frameworks for marketing content creation", + "version": "1.0.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "content", + "seo", + "brand-voice", + "marketing" + ], + "category": "marketing" + }, + { + "name": "demand-gen", + "source": "./marketing-skill/marketing-demand-acquisition", + "description": "Demand generation, paid media, SEO, partnerships for Series A+ startups", + "version": "1.0.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "demand-gen", + "paid-media", + "acquisition", + "marketing" + ], + "category": "marketing" + }, + { + "name": "fullstack-engineer", + "source": "./engineering-team/senior-fullstack", + "description": "End-to-end application development with Next.js, GraphQL, PostgreSQL", + "version": "1.0.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "fullstack", + "nextjs", + "graphql", + "postgresql" + ], + "category": "development" + }, + { + "name": "aws-architect", + "source": "./engineering-team/aws-solution-architect", + "description": "AWS solution architecture with serverless, cost optimization, and security best practices", + "version": "1.0.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "aws", + "cloud", + "serverless", + "architecture" + ], + "category": "development" + }, + { + "name": "product-manager", + "source": "./product-team/product-manager-toolkit", + "description": "RICE prioritization, customer interview analysis, PRD templates for product managers", + "version": "1.0.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "product-management", + "rice", + "prd", + "prioritization" + ], + "category": "product" + }, + { + "name": "scrum-master", + "source": "./project-management/scrum-master", + "description": "Agile facilitation, sprint planning, retrospectives for Scrum teams", + "version": "1.0.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "scrum", + "agile", + "sprint", + "retrospective" + ], + "category": "project-management" + }, + { + "name": "skill-security-auditor", + "source": "./engineering/skill-security-auditor", + "description": "Security audit and vulnerability scanner for AI agent skills. Scans for malicious code, prompt injection, data exfiltration, supply chain risks, and privilege escalation before installation. Zero dependencies, PASS/WARN/FAIL verdicts with remediation guidance.", + "version": "2.0.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "security", + "audit", + "vulnerability", + "scanner", + "malware", + "prompt-injection", + "supply-chain", + "code-review", + "safety", + "pre-install" + ], + "category": "security" + }, + { + "name": "playwright-pro", + "source": "./engineering-team/playwright-pro", + "description": "Production-grade Playwright testing toolkit. 9 skills, 3 agents, 55 templates, TestRail + BrowserStack MCP integrations. Generate tests, fix flaky failures, migrate from Cypress/Selenium.", + "version": "1.0.0", + "author": { + "name": "Alireza Rezvani" + }, + "keywords": [ + "playwright", + "testing", + "e2e", + "qa", + "test-automation", + "browserstack", + "testrail", + "cross-browser", + "migration", + "cypress", + "selenium" + ], + "category": "development" + }, + { + "name": "self-improving-agent", + "source": "./engineering-team/self-improving-agent", + "description": "Curate auto-memory, promote learnings to CLAUDE.md and rules, extract patterns into skills.", + "category": "development", + "tags": [ + "memory", + "auto-memory", + "self-improvement", + "learning" + ] + } + ] +} diff --git a/.codex/skills-index.json b/.codex/skills-index.json index ccabbda..f51af2a 100644 --- a/.codex/skills-index.json +++ b/.codex/skills-index.json @@ -3,7 +3,7 @@ "name": "claude-code-skills", "description": "Production-ready skill packages for AI agents - Marketing, Engineering, Product, C-Level, PM, and RA/QM", "repository": "https://github.com/alirezarezvani/claude-skills", - "total_skills": 62, + "total_skills": 63, "skills": [ { "name": "contract-and-proposal-writer", @@ -77,6 +77,12 @@ "category": "engineering", "description": "Production-grade Playwright testing toolkit. Generate tests, fix flaky failures, migrate from Cypress/Selenium, sync with TestRail, run on BrowserStack. 55 templates, 3 agents, smart reporting." }, + { + "name": "self-improving-agent", + "source": "../../engineering-team/self-improving-agent", + "category": "engineering", + "description": "Curate Claude Code's auto-memory into durable project knowledge. Analyze MEMORY.md for patterns, promote proven learnings to CLAUDE.md and .claude/rules/, extract recurring solutions into reusable skills. Use when: (1) reviewing what Claude has learned about your project, (2) graduating a pattern from notes to enforced rules, (3) turning a debugging solution into a skill, (4) checking memory health and capacity." + }, { "name": "senior-architect", "source": "../../engineering-team/senior-architect", @@ -390,7 +396,7 @@ "description": "Executive leadership and advisory skills" }, "engineering": { - "count": 22, + "count": 23, "source": "../../engineering-team", "description": "Software engineering and technical skills" }, diff --git a/.codex/skills/self-improving-agent b/.codex/skills/self-improving-agent new file mode 120000 index 0000000..f204e9e --- /dev/null +++ b/.codex/skills/self-improving-agent @@ -0,0 +1 @@ +../../engineering-team/self-improving-agent \ No newline at end of file diff --git a/README.md b/README.md index 2cc6b81..fc80564 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # Claude Skills Library -**87+ production-ready skill packages for Claude Code, OpenAI Codex, and OpenClaw** β€” reusable expertise bundles that transform AI agents into specialized professionals across engineering, product, marketing, compliance, and more. +**88+ production-ready skill packages for Claude Code, OpenAI Codex, and OpenClaw** β€” reusable expertise bundles that transform AI agents into specialized professionals across engineering, product, marketing, compliance, and more. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) -[![Skills](https://img.shields.io/badge/Skills-87-brightgreen.svg)](#skills-overview) +[![Skills](https://img.shields.io/badge/Skills-88-brightgreen.svg)](#skills-overview) [![Stars](https://img.shields.io/github/stars/alirezarezvani/claude-skills?style=flat)](https://github.com/alirezarezvani/claude-skills/stargazers) [![SkillCheck Validated](https://img.shields.io/badge/SkillCheck-Validated-4c1)](https://getskillcheck.com) @@ -41,6 +41,7 @@ Skills are modular instruction packages that give AI agents domain expertise the # Or install individual skills /plugin install skill-security-auditor@claude-code-skills # Security scanner /plugin install playwright-pro@claude-code-skills # Playwright testing toolkit +/plugin install self-improving-agent@claude-code-skills # Auto-memory curation /plugin install content-creator@claude-code-skills # Single skill ``` @@ -68,12 +69,13 @@ git clone https://github.com/alirezarezvani/claude-skills.git ## Skills Overview -**87+ skills across 9 domains:** +**88+ skills across 9 domains:** | Domain | Skills | Highlights | Details | |--------|--------|------------|---------| | **πŸ”§ Engineering β€” Core** | 21 | Architecture, frontend, backend, fullstack, QA, DevOps, SecOps, AI/ML, data | [engineering-team/](engineering-team/) | | **🎭 Playwright Pro** | 9+3 | Test generation, flaky fix, Cypress/Selenium migration, TestRail, BrowserStack, 55 templates | [engineering-team/playwright-pro](engineering-team/playwright-pro/) | +| **🧠 Self-Improving Agent** | 5+2 | Auto-memory curation, pattern promotion, skill extraction, memory health | [engineering-team/self-improving-agent](engineering-team/self-improving-agent/) | | **⚑ Engineering β€” POWERFUL** | 25 | Agent designer, RAG architect, database designer, CI/CD builder, security auditor, MCP builder | [engineering/](engineering/) | | **🎯 Product** | 8 | Product manager, agile PO, strategist, UX researcher, UI design, landing pages, SaaS scaffolder | [product-team/](product-team/) | | **πŸ“£ Marketing** | 7 | Content creator, demand gen, PMM strategy, ASO, social media, campaign analytics, prompt engineering | [marketing-skill/](marketing-skill/) | diff --git a/engineering-team/self-improving-agent/.claude-plugin/plugin.json b/engineering-team/self-improving-agent/.claude-plugin/plugin.json new file mode 100644 index 0000000..c556aea --- /dev/null +++ b/engineering-team/self-improving-agent/.claude-plugin/plugin.json @@ -0,0 +1,67 @@ +{ + "name": "si", + "version": "1.0.0", + "displayName": "Self-Improving Agent", + "description": "Curate auto-memory, promote learnings to CLAUDE.md and rules, extract proven patterns into reusable skills.", + "skills": [ + { + "name": "review", + "path": "skills/review", + "command": "/si:review", + "description": "Analyze auto-memory for promotion candidates, stale entries, and health" + }, + { + "name": "promote", + "path": "skills/promote", + "command": "/si:promote", + "description": "Elevate a proven pattern from MEMORY.md to CLAUDE.md or .claude/rules/" + }, + { + "name": "extract", + "path": "skills/extract", + "command": "/si:extract", + "description": "Turn a recurring pattern into a standalone reusable skill" + }, + { + "name": "status", + "path": "skills/status", + "command": "/si:status", + "description": "Memory health dashboard with line counts, topic files, and recommendations" + }, + { + "name": "remember", + "path": "skills/remember", + "command": "/si:remember", + "description": "Explicitly save important knowledge to auto-memory with context" + } + ], + "agents": [ + { + "name": "memory-analyst", + "path": "agents/memory-analyst.md" + }, + { + "name": "skill-extractor", + "path": "agents/skill-extractor.md" + } + ], + "hooks": { + "PostToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "./hooks/error-capture.sh" + } + ] + } + ] + }, + "settings": { + "memoryDir": "~/.claude/projects", + "maxMemoryLines": 200, + "promotionThreshold": 3, + "promotionWindowDays": 30 + } +} diff --git a/engineering-team/self-improving-agent/CLAUDE.md b/engineering-team/self-improving-agent/CLAUDE.md new file mode 100644 index 0000000..cbd9993 --- /dev/null +++ b/engineering-team/self-improving-agent/CLAUDE.md @@ -0,0 +1,79 @@ +# Self-Improving Agent β€” Claude Code Instructions + +This plugin helps you curate Claude Code's auto-memory into durable project knowledge. + +## Commands + +Use the `/si:` namespace for all commands: + +- `/si:review` β€” Analyze auto-memory health and find promotion candidates +- `/si:promote ` β€” Graduate a learning to CLAUDE.md or `.claude/rules/` +- `/si:extract ` β€” Create a reusable skill from a proven pattern +- `/si:status` β€” Quick memory health dashboard +- `/si:remember ` β€” Explicitly save something to auto-memory + +## How auto-memory works + +Claude Code maintains `~/.claude/projects//memory/MEMORY.md` automatically. The first 200 lines load into every session. When it grows too large, Claude moves details into topic files like `debugging.md` or `patterns.md`. + +This plugin reads that directory β€” it never creates its own storage. + +## When to use each command + +### After completing a feature or debugging session +``` +/si:review +``` +Check if anything Claude learned should become a permanent rule. + +### When a pattern keeps coming up +``` +/si:promote "Always run migrations before tests in this project" +``` +Moves it from MEMORY.md (background note) to CLAUDE.md (enforced rule). + +### When you solved something non-obvious that could help other projects +``` +/si:extract "Docker build fix for ARM64 platform mismatch" +``` +Creates a standalone skill with SKILL.md, ready to install elsewhere. + +### To check memory capacity +``` +/si:status +``` +Shows line counts, topic files, stale entries, and recommendations. + +## Key principle + +**Don't fight auto-memory β€” orchestrate it.** + +- Auto-memory is great at capturing patterns. Let it do its job. +- This plugin adds judgment: what's worth keeping, what should be promoted, what's stale. +- Promoted rules in CLAUDE.md have higher priority than MEMORY.md entries. +- Removing promoted entries from MEMORY.md frees space for new learnings. + +## Agents + +- **memory-analyst**: Spawned by `/si:review` to analyze patterns across memory files +- **skill-extractor**: Spawned by `/si:extract` to generate complete skill packages + +## Hooks + +The `error-capture.sh` hook fires on `PostToolUse` (Bash only). It detects command failures and appends structured entries to auto-memory. Zero overhead on successful commands. + +To enable: +```json +// .claude/settings.json +{ + "hooks": { + "PostToolUse": [{ + "matcher": "Bash", + "hooks": [{ + "type": "command", + "command": "./skills/self-improving-agent/hooks/error-capture.sh" + }] + }] + } +} +``` diff --git a/engineering-team/self-improving-agent/LICENSE b/engineering-team/self-improving-agent/LICENSE new file mode 100644 index 0000000..d06c943 --- /dev/null +++ b/engineering-team/self-improving-agent/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Reza Rezvani + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/engineering-team/self-improving-agent/README.md b/engineering-team/self-improving-agent/README.md new file mode 100644 index 0000000..414ed30 --- /dev/null +++ b/engineering-team/self-improving-agent/README.md @@ -0,0 +1,92 @@ +# Self-Improving Agent + +> Auto-memory captures. This plugin curates. + +A Claude Code plugin that turns auto-memory into a structured self-improvement loop. Analyze what Claude has learned, promote proven patterns to enforced rules, and extract recurring solutions into reusable skills. + +## Why + +Claude Code's auto-memory (v2.1.32+) automatically records project patterns in `MEMORY.md`. But it has no judgment about what to keep, what to promote, or when entries go stale. This plugin adds the intelligence layer. + +**The difference:** +- **MEMORY.md**: "I noticed this project uses pnpm" (background note, truncated at 200 lines) +- **CLAUDE.md**: "Use pnpm, not npm" (enforced instruction, loaded in full) + +Promoting a pattern from memory to rules fundamentally changes how Claude treats it. + +## Commands + +| Command | What it does | +|---------|-------------| +| `/si:review` | Analyze auto-memory β€” find promotion candidates, stale entries, health metrics | +| `/si:promote` | Graduate a pattern from MEMORY.md β†’ CLAUDE.md or `.claude/rules/` | +| `/si:extract` | Turn a recurring pattern into a standalone reusable skill | +| `/si:status` | Memory health dashboard β€” line counts, capacity, recommendations | +| `/si:remember` | Explicitly save important knowledge to auto-memory | + +## Install + +### Claude Code +``` +/plugin marketplace add alirezarezvani/claude-skills +/plugin install self-improving-agent@claude-code-skills +``` + +### OpenClaw +```bash +clawhub install self-improving-agent +``` + +### Codex CLI +```bash +./scripts/codex-install.sh --skill self-improving-agent +``` + +## How It Works + +``` +Claude discovers pattern β†’ auto-memory (MEMORY.md) + ↓ +Pattern recurs 2-3x β†’ /si:review flags it + ↓ +You approve β†’ /si:promote graduates it to CLAUDE.md + ↓ +Pattern becomes enforced rule, memory entry removed + ↓ +Space freed for new learnings +``` + +## What's Included + +| Component | Count | Description | +|-----------|-------|-------------| +| Skills | 5 | review, promote, extract, status, remember | +| Agents | 2 | memory-analyst, skill-extractor | +| Hooks | 1 | PostToolUse error capture (zero overhead on success) | +| Reference docs | 3 | memory architecture, promotion rules, rules directory patterns | +| Templates | 2 | rule template, skill template | + +## Design Principles + +1. **Don't fight auto-memory β€” orchestrate it.** Auto-memory captures. This plugin curates. +2. **No duplicate storage.** Reads from `~/.claude/projects/` directly. No `.learnings/` directory. +3. **Zero capture overhead.** Auto-memory handles capture. Hook only fires on errors. +4. **Promotion = graduation.** Moving a pattern from MEMORY.md to CLAUDE.md changes its priority. +5. **Respect the 200-line limit.** Actively manages MEMORY.md capacity. + +## Platform Support + +| Platform | Memory System | Support | +|----------|--------------|---------| +| Claude Code | Auto-memory (MEMORY.md) | βœ… Full | +| OpenClaw | workspace/MEMORY.md | βœ… Adapted | +| Codex CLI | AGENTS.md | βœ… Adapted | +| GitHub Copilot | copilot-instructions.md | ⚠️ Manual | + +## Credits + +Inspired by [pskoett/self-improving-agent](https://clawhub.ai/pskoett/self-improving-agent) β€” a structured learning loop for AI coding agents. This plugin builds on that concept by integrating natively with Claude Code's auto-memory system. + +## License + +MIT β€” see [LICENSE](LICENSE) diff --git a/engineering-team/self-improving-agent/SKILL.md b/engineering-team/self-improving-agent/SKILL.md new file mode 100644 index 0000000..3dce2a3 --- /dev/null +++ b/engineering-team/self-improving-agent/SKILL.md @@ -0,0 +1,162 @@ +--- +name: self-improving-agent +description: "Curate Claude Code's auto-memory into durable project knowledge. Analyze MEMORY.md for patterns, promote proven learnings to CLAUDE.md and .claude/rules/, extract recurring solutions into reusable skills. Use when: (1) reviewing what Claude has learned about your project, (2) graduating a pattern from notes to enforced rules, (3) turning a debugging solution into a skill, (4) checking memory health and capacity." +--- + +# Self-Improving Agent + +> Auto-memory captures. This plugin curates. + +Claude Code's auto-memory (v2.1.32+) automatically records project patterns, debugging insights, and your preferences in `MEMORY.md`. This plugin adds the intelligence layer: it analyzes what Claude has learned, promotes proven patterns into project rules, and extracts recurring solutions into reusable skills. + +## Quick Reference + +| Command | What it does | +|---------|-------------| +| `/si:review` | Analyze MEMORY.md β€” find promotion candidates, stale entries, consolidation opportunities | +| `/si:promote` | Graduate a pattern from MEMORY.md β†’ CLAUDE.md or `.claude/rules/` | +| `/si:extract` | Turn a proven pattern into a standalone skill | +| `/si:status` | Memory health dashboard β€” line counts, topic files, recommendations | +| `/si:remember` | Explicitly save important knowledge to auto-memory | + +## How It Fits Together + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Claude Code Memory Stack β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ CLAUDE.md β”‚ Auto Memory β”‚ Session Memory β”‚ +β”‚ (you write)β”‚ (Claude writes)β”‚ (Claude writes) β”‚ +β”‚ Rules & β”‚ MEMORY.md β”‚ Conversation logs β”‚ +β”‚ standards β”‚ + topic files β”‚ + continuity β”‚ +β”‚ Full load β”‚ First 200 linesβ”‚ Contextual load β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ ↑ /si:promote ↑ /si:review β”‚ +β”‚ Self-Improving Agent (this plugin) β”‚ +β”‚ ↓ /si:extract ↓ /si:remember β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ .claude/rules/ β”‚ New Skills β”‚ Error Logs β”‚ +β”‚ (scoped rules) β”‚ (extracted) β”‚ (auto-captured)β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +## Installation + +### Claude Code (Plugin) +``` +/plugin marketplace add alirezarezvani/claude-skills +/plugin install self-improving-agent@claude-code-skills +``` + +### OpenClaw +```bash +clawhub install self-improving-agent +``` + +### Codex CLI +```bash +./scripts/codex-install.sh --skill self-improving-agent +``` + +## Memory Architecture + +### Where things live + +| File | Who writes | Scope | Loaded | +|------|-----------|-------|--------| +| `./CLAUDE.md` | You (+ `/si:promote`) | Project rules | Full file, every session | +| `~/.claude/CLAUDE.md` | You | Global preferences | Full file, every session | +| `~/.claude/projects//memory/MEMORY.md` | Claude (auto) | Project learnings | First 200 lines | +| `~/.claude/projects//memory/*.md` | Claude (overflow) | Topic-specific notes | On demand | +| `.claude/rules/*.md` | You (+ `/si:promote`) | Scoped rules | When matching files open | + +### The promotion lifecycle + +``` +1. Claude discovers pattern β†’ auto-memory (MEMORY.md) +2. Pattern recurs 2-3x β†’ /si:review flags it as promotion candidate +3. You approve β†’ /si:promote graduates it to CLAUDE.md or rules/ +4. Pattern becomes an enforced rule, not just a note +5. MEMORY.md entry removed β†’ frees space for new learnings +``` + +## Core Concepts + +### Auto-memory is capture, not curation + +Auto-memory is excellent at recording what Claude learns. But it has no judgment about: +- Which learnings are temporary vs. permanent +- Which patterns should become enforced rules +- When the 200-line limit is wasting space on stale entries +- Which solutions are good enough to become reusable skills + +That's what this plugin does. + +### Promotion = graduation + +When you promote a learning, it moves from Claude's scratchpad (MEMORY.md) to your project's rule system (CLAUDE.md or `.claude/rules/`). The difference matters: + +- **MEMORY.md**: "I noticed this project uses pnpm" (background context) +- **CLAUDE.md**: "Use pnpm, not npm" (enforced instruction) + +Promoted rules have higher priority and load in full (not truncated at 200 lines). + +### Rules directory for scoped knowledge + +Not everything belongs in CLAUDE.md. Use `.claude/rules/` for patterns that only apply to specific file types: + +```yaml +# .claude/rules/api-testing.md +--- +paths: + - "src/api/**/*.test.ts" + - "tests/api/**/*" +--- +- Use supertest for API endpoint testing +- Mock external services with msw +- Always test error responses, not just happy paths +``` + +This loads only when Claude works with API test files β€” zero overhead otherwise. + +## Agents + +### memory-analyst +Analyzes MEMORY.md and topic files to identify: +- Entries that recur across sessions (promotion candidates) +- Stale entries referencing deleted files or old patterns +- Related entries that should be consolidated +- Gaps between what MEMORY.md knows and what CLAUDE.md enforces + +### skill-extractor +Takes a proven pattern and generates a complete skill: +- SKILL.md with proper frontmatter +- Reference documentation +- Examples and edge cases +- Ready for `/plugin install` or `clawhub publish` + +## Hooks + +### error-capture (PostToolUse β†’ Bash) +Monitors command output for errors. When detected, appends a structured entry to auto-memory with: +- The command that failed +- Error output (truncated) +- Timestamp and context +- Suggested category + +**Token overhead:** Zero on success. ~30 tokens only when an error is detected. + +## Platform Support + +| Platform | Memory System | Plugin Works? | +|----------|--------------|---------------| +| Claude Code | Auto-memory (MEMORY.md) | βœ… Full support | +| OpenClaw | workspace/MEMORY.md | βœ… Adapted (reads workspace memory) | +| Codex CLI | AGENTS.md | βœ… Adapted (reads AGENTS.md patterns) | +| GitHub Copilot | `.github/copilot-instructions.md` | ⚠️ Manual promotion only | + +## Related + +- [Claude Code Memory Docs](https://code.claude.com/docs/en/memory) +- [pskoett/self-improving-agent](https://clawhub.ai/pskoett/self-improving-agent) β€” inspiration +- [playwright-pro](../playwright-pro/) β€” sister plugin in this repo diff --git a/engineering-team/self-improving-agent/agents/memory-analyst.md b/engineering-team/self-improving-agent/agents/memory-analyst.md new file mode 100644 index 0000000..e3e0451 --- /dev/null +++ b/engineering-team/self-improving-agent/agents/memory-analyst.md @@ -0,0 +1,74 @@ +# Memory Analyst Agent + +You are a memory analyst for Claude Code projects. Your job is to analyze the auto-memory directory and produce actionable insights. + +## Your Role + +You analyze `~/.claude/projects//memory/` to find: +1. **Promotion candidates** β€” entries proven enough to become CLAUDE.md rules +2. **Stale entries** β€” references to files, tools, or patterns that no longer apply +3. **Consolidation opportunities** β€” multiple entries about the same topic +4. **Conflicts** β€” memory entries that contradict CLAUDE.md rules +5. **Health metrics** β€” capacity, freshness, organization + +## Analysis Process + +### 1. Read all memory files +- `MEMORY.md` (main file, first 200 lines loaded at startup) +- Any topic files (`debugging.md`, `patterns.md`, etc.) +- Note total line counts and file sizes + +### 2. Cross-reference with CLAUDE.md +- Read `./CLAUDE.md` and `~/.claude/CLAUDE.md` +- Read all files in `.claude/rules/` +- Identify duplicates, contradictions, and gaps + +### 3. Detect patterns +For each MEMORY.md entry, evaluate: + +**Recurrence signals:** +- Same concept in multiple entries (paraphrased) +- Words like "again", "still", "always", "every time" +- Similar entries in topic files + +**Staleness signals:** +- File paths that don't exist on disk (verify with `find` or `ls`) +- Version numbers that are outdated +- References to removed dependencies +- Patterns that contradict current CLAUDE.md + +**Promotion signals:** +- Actionable (can be written as "Do X" / "Never Y") +- Broadly applicable (not a one-time debugging note) +- Not already in CLAUDE.md or rules/ +- High impact (prevents common mistakes) + +### 4. Score each entry + +Rate each entry on three dimensions: +- **Durability** (0-3): Will this still be true in a month? +- **Impact** (0-3): How much does this affect daily work? +- **Scope** (0-3): Project-wide (3) vs. one-file (1) vs. one-time (0) + +Promotion candidates: total score β‰₯ 6 + +### 5. Generate report + +Organize findings into: +1. Promotion candidates (sorted by score, highest first) +2. Stale entries (with reason for staleness) +3. Consolidation groups (which entries to merge) +4. Conflicts (with both sides shown) +5. Health metrics (capacity, freshness) +6. Recommendations (top 3 actions) + +## Output Format + +Use the format defined in the `/si:review` skill. Be specific β€” include line numbers, exact text, and concrete suggestions. + +## Constraints + +- Never modify files directly β€” only analyze and report +- Don't invent entries β€” only report what's actually in the memory files +- Be concise β€” the report should be shorter than the memory files it analyzes +- Prioritize actionable findings over completeness diff --git a/engineering-team/self-improving-agent/agents/skill-extractor.md b/engineering-team/self-improving-agent/agents/skill-extractor.md new file mode 100644 index 0000000..99e8578 --- /dev/null +++ b/engineering-team/self-improving-agent/agents/skill-extractor.md @@ -0,0 +1,110 @@ +# Skill Extractor Agent + +You are a skill extraction specialist. Your job is to transform proven patterns and debugging solutions into standalone, portable skills. + +## Your Role + +Given a pattern description (and optionally auto-memory entries), generate a complete skill package that: +- Solves a specific, recurring problem +- Works in any project (no hardcoded paths, credentials, or project-specific values) +- Is self-contained (readable without the original context) +- Follows the claude-skills format specification + +## Extraction Process + +### 1. Understand the pattern + +From the input, identify: +- **The problem**: What goes wrong? What's the symptom? +- **The root cause**: Why does it happen? +- **The solution**: What's the fix? Are there multiple approaches? +- **The edge cases**: When does the solution NOT work? +- **The trigger conditions**: When should an agent use this skill? + +### 2. Generate skill name + +Rules: +- Lowercase, hyphens between words +- 2-4 words, descriptive +- Match the problem, not the project +- Examples: `docker-arm64-fixes`, `api-timeout-patterns`, `pnpm-monorepo-setup` + +### 3. Create SKILL.md + +Required structure: + +```markdown +--- +name: {{skill-name}} +description: "{{One sentence}}. Use when: {{trigger conditions}}." +--- + +# {{Skill Title}} + +> {{One-line value proposition}} + +## Quick Reference + +| Problem | Solution | +|---------|----------| +| {{error/symptom}} | {{fix}} | + +## The Problem + +{{2-3 sentences. Include the error message or symptom people would search for.}} + +## Solutions + +### Option 1: {{Name}} (Recommended) + +{{Step-by-step instructions with code blocks.}} + +### Option 2: {{Alternative}} {{if applicable}} + +{{When Option 1 doesn't apply.}} + +## Trade-offs + +| Approach | Pros | Cons | +|----------|------|------| +| {{option}} | {{pros}} | {{cons}} | + +## Edge Cases + +- {{When this approach breaks and what to do instead}} + +## Related + +- {{Links to official docs or related skills}} +``` + +### 4. Create README.md + +Brief human-readable overview: +- What the skill does (1 paragraph) +- Installation instructions +- When to use it +- Credits/source + +### 5. Quality checks + +Before delivering, verify: + +- [ ] YAML frontmatter is valid (`name` and `description` present) +- [ ] `name` in frontmatter matches folder name +- [ ] Description includes "Use when:" trigger +- [ ] No project-specific paths, URLs, or credentials +- [ ] Code examples are complete and runnable +- [ ] Error messages are exact (copy-pasteable for searching) +- [ ] Solutions work without additional context +- [ ] Trade-offs table helps users choose between options +- [ ] Skill is useful in a project you've never seen before + +## Constraints + +- **One problem per skill** β€” don't create omnibus guides +- **Show, don't tell** β€” code examples over prose +- **Include the error** β€” people search by error message +- **Be portable** β€” no `npm` vs `pnpm` assumptions +- **Keep it short** β€” under 200 lines for SKILL.md +- **No unnecessary files** β€” only SKILL.md is required. Add reference/ only if the topic is complex enough to warrant it diff --git a/engineering-team/self-improving-agent/hooks/error-capture.sh b/engineering-team/self-improving-agent/hooks/error-capture.sh new file mode 100755 index 0000000..393cfe8 --- /dev/null +++ b/engineering-team/self-improving-agent/hooks/error-capture.sh @@ -0,0 +1,110 @@ +#!/bin/bash +# Self-Improving Agent β€” Error Capture Hook +# Fires on PostToolUse (Bash) to detect command failures. +# Zero output on success β€” only captures when errors are detected. +# +# Install: Add to .claude/settings.json: +# { +# "hooks": { +# "PostToolUse": [{ +# "matcher": "Bash", +# "hooks": [{ +# "type": "command", +# "command": "./skills/self-improving-agent/hooks/error-capture.sh" +# }] +# }] +# } +# } + +set -e + +OUTPUT="${CLAUDE_TOOL_OUTPUT:-}" + +# Exit silently if no output or empty +[ -z "$OUTPUT" ] && exit 0 + +# Error patterns β€” ordered by specificity +ERROR_PATTERNS=( + "error:" + "Error:" + "ERROR:" + "FATAL:" + "fatal:" + "FAILED" + "failed" + "command not found" + "No such file or directory" + "Permission denied" + "Module not found" + "ModuleNotFoundError" + "ImportError" + "SyntaxError" + "TypeError" + "ReferenceError" + "Cannot find module" + "ENOENT" + "EACCES" + "ECONNREFUSED" + "ETIMEDOUT" + "npm ERR!" + "pnpm ERR!" + "Traceback (most recent call last)" + "panic:" + "segmentation fault" + "core dumped" + "exit code" + "non-zero exit" + "Build failed" + "Compilation failed" + "Test failed" +) + +# False positive exclusions β€” don't trigger on these +EXCLUSIONS=( + "error-capture" # Don't trigger on ourselves + "error_handler" # Code that handles errors + "errorHandler" + "error.log" # Log file references + "console.error" # Code that logs errors + "catch (error" # Error handling code + "catch (err" + ".error(" # Logger calls + "no error" # Absence of error + "without error" + "error-free" +) + +# Check exclusions first +for excl in "${EXCLUSIONS[@]}"; do + if [[ "$OUTPUT" == *"$excl"* ]]; then + exit 0 + fi +done + +# Check for error patterns +contains_error=false +matched_pattern="" +for pattern in "${ERROR_PATTERNS[@]}"; do + if [[ "$OUTPUT" == *"$pattern"* ]]; then + contains_error=true + matched_pattern="$pattern" + break + fi +done + +# Exit silently if no error +[ "$contains_error" = false ] && exit 0 + +# Extract relevant error context (first 5 lines containing the pattern) +error_context=$(echo "$OUTPUT" | grep -i -m 5 "$matched_pattern" | head -5) + +# Output a concise reminder β€” ~40 tokens +cat << EOF + +Command error detected (pattern: "$matched_pattern"). +If this was unexpected or required investigation to fix, save the solution: + /si:remember "explanation of what went wrong and the fix" +Or if this is a known pattern, check: /si:review +Context: $(echo "$error_context" | head -2 | tr '\n' ' ' | cut -c1-200) + +EOF diff --git a/engineering-team/self-improving-agent/hooks/hooks.json b/engineering-team/self-improving-agent/hooks/hooks.json new file mode 100644 index 0000000..a164465 --- /dev/null +++ b/engineering-team/self-improving-agent/hooks/hooks.json @@ -0,0 +1,11 @@ +{ + "hooks": [ + { + "name": "error-capture", + "event": "PostToolUse", + "matcher": "Bash", + "command": "./hooks/error-capture.sh", + "description": "Detects command failures and appends structured entries to auto-memory. Zero overhead on successful commands." + } + ] +} diff --git a/engineering-team/self-improving-agent/reference/memory-architecture.md b/engineering-team/self-improving-agent/reference/memory-architecture.md new file mode 100644 index 0000000..dc15acd --- /dev/null +++ b/engineering-team/self-improving-agent/reference/memory-architecture.md @@ -0,0 +1,131 @@ +# Claude Code Memory Architecture + +A complete reference for how Claude Code's memory systems work together. + +## Three Memory Systems + +### 1. CLAUDE.md Files (You β†’ Claude) + +**Purpose:** Persistent instructions you write to guide Claude's behavior. + +**Locations (in priority order):** +| Scope | Path | Shared | +|-------|------|--------| +| Managed policy | `/etc/claude-code/CLAUDE.md` (Linux) | All users | +| Project | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Team (git) | +| User | `~/.claude/CLAUDE.md` | Just you | +| Local | `./CLAUDE.local.md` | Just you | + +**Loading:** Full file, every session. Files higher in the directory tree load first. + +**Key facts:** +- Target under 200 lines per file +- Use `@path/to/file` syntax to import additional files (max 5 hops deep) +- More specific locations take precedence over broader ones +- Can import with `@README` or `@docs/guide.md` +- CLAUDE.local.md is auto-added to .gitignore + +### 2. Auto Memory (Claude β†’ Claude) + +**Purpose:** Notes Claude writes to itself about project patterns and learnings. + +**Location:** `~/.claude/projects//memory/` + +**Structure:** +``` +~/.claude/projects//memory/ +β”œβ”€β”€ MEMORY.md # Main file (first 200 lines loaded) +β”œβ”€β”€ debugging.md # Topic file (loaded on demand) +β”œβ”€β”€ patterns.md # Topic file (loaded on demand) +└── ... # More topic files as needed +``` + +**Key facts:** +- Enabled by default (since v2.1.32) +- Only the first 200 lines of MEMORY.md load at startup +- Claude creates topic files automatically when MEMORY.md gets long +- Git repo root determines the project path +- Git worktrees get separate memory directories +- Local only β€” not shared via git +- Toggle with `/memory`, settings, or `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` +- Subagents can have their own auto memory + +**What it captures:** +- Build commands and test conventions +- Debugging solutions and error patterns +- Code style preferences and architecture notes +- Your communication preferences and workflow habits + +### 3. Session Memory (Claude β†’ Claude) + +**Purpose:** Conversation summaries for cross-session continuity. + +**Location:** `~/.claude/projects///session-memory/` + +**Key facts:** +- Saves what was discussed and decided in specific sessions +- "What did we do yesterday?" context +- Loaded contextually (relevant past sessions, not all) +- Use `/remember` to turn session memory into permanent project knowledge + +### 4. Rules Directory (You β†’ Claude, scoped) + +**Purpose:** Modular instructions scoped to specific file types. + +**Location:** `.claude/rules/*.md` + +**Key facts:** +- Uses YAML frontmatter with `paths` field for scoping +- Only loads when Claude works with matching files +- Recursive β€” can organize into subdirectories +- Same priority as `.claude/CLAUDE.md` +- Great for keeping CLAUDE.md under 200 lines + +```yaml +--- +paths: + - "src/api/**/*.ts" +--- +# API rules only load when working with API files +``` + +## Memory Priority + +When entries conflict: + +1. CLAUDE.md (highest β€” explicit instructions) +2. `.claude/rules/` (high β€” scoped instructions) +3. Auto-memory MEMORY.md (medium β€” learned patterns) +4. Session memory (low β€” historical context) + +## The Self-Improving Agent's Role + +``` +Auto-memory captures β†’ This plugin curates β†’ CLAUDE.md enforces + +MEMORY.md (raw notes) β†’ /si:review (analyze) β†’ /si:promote (graduate) + ↓ + CLAUDE.md or + .claude/rules/ + (enforced rules) +``` + +**Why this matters:** MEMORY.md entries are background context truncated at 200 lines. CLAUDE.md entries are high-priority instructions loaded in full. Promoting a pattern from memory to rules fundamentally changes how Claude treats it. + +## Capacity Planning + +| File | Soft limit | Hard limit | What happens at limit | +|------|-----------|------------|----------------------| +| MEMORY.md | 150 lines | 200 lines | Lines after 200 not loaded at startup | +| CLAUDE.md | 150 lines | No hard limit | Adherence decreases with length | +| Topic files | No limit | No limit | Loaded on demand, not at startup | +| Rules files | No limit per file | No limit | Only loaded when paths match | + +## Best Practices + +1. **Keep MEMORY.md lean** β€” promote proven patterns, delete stale ones +2. **Keep CLAUDE.md under 200 lines** β€” split into rules/ if growing +3. **Don't duplicate** β€” if it's in CLAUDE.md, remove it from MEMORY.md +4. **Scope rules** β€” use `.claude/rules/` with paths for file-type-specific patterns +5. **Review quarterly** β€” memory files go stale after refactors +6. **Use /si:status** β€” monitor capacity before it becomes a problem diff --git a/engineering-team/self-improving-agent/reference/promotion-rules.md b/engineering-team/self-improving-agent/reference/promotion-rules.md new file mode 100644 index 0000000..67bc417 --- /dev/null +++ b/engineering-team/self-improving-agent/reference/promotion-rules.md @@ -0,0 +1,83 @@ +# Promotion Rules + +When to promote a learning from auto-memory (MEMORY.md) to the project's rule system (CLAUDE.md or `.claude/rules/`). + +## Promotion Criteria + +A learning should be promoted when **all three** are true: + +1. **Proven** β€” appeared in 2+ sessions or confirmed correct after testing +2. **Actionable** β€” can be written as a concrete instruction ("Use X", "Never Y") +3. **Durable** β€” will still be true in 30+ days + +## Scoring Guide + +| Dimension | Score 0 | Score 1 | Score 2 | Score 3 | +|-----------|---------|---------|---------|---------| +| **Durability** | One-time fix | Temporary workaround | Stable pattern | Architectural truth | +| **Impact** | Nice-to-know | Saves 1 minute | Prevents mistakes | Prevents breakage | +| **Scope** | One file only | One directory | Entire project | All your projects | + +**Promote when total β‰₯ 6.** Watch when total = 4-5. Ignore when total ≀ 3. + +## Target Selection + +### Use CLAUDE.md when: +- The rule applies to the entire project +- It's a build command, test convention, or architecture decision +- Any contributor (human or AI) needs to know it +- It's short enough to add without exceeding 200 lines + +### Use .claude/rules/ when: +- The rule only applies to specific file types +- CLAUDE.md is already near 200 lines +- The rule needs detailed explanation (multiple paragraphs) +- You want it to load only when relevant files are open + +### Use ~/.claude/CLAUDE.md when: +- The rule applies to all your projects +- It's a personal preference, not a project convention +- Examples: "Prefer explicit returns over implicit", "Use descriptive variable names" + +## Distillation Rules + +When promoting, transform the learning: + +### From descriptive to prescriptive + +❌ "I noticed the project uses pnpm workspaces. npm install fails because of the lock file." +βœ… "Use `pnpm install`, not npm. Lock file: `pnpm-lock.yaml`." + +### From verbose to concise + +❌ "When modifying API endpoints in the OpenAPI spec file, you need to regenerate the TypeScript client by running the generate command, otherwise the types won't match at runtime and you'll get errors." +βœ… "After editing `openapi.yaml`: run `pnpm run generate:api` to regenerate TS client." + +### From conditional to absolute + +❌ "Sometimes you need to restart the dev server after changing environment variables." +βœ… "Restart dev server after any `.env` change β€” hot reload doesn't pick up env vars." + +## Anti-Patterns + +### Don't promote: +- **One-time debugging notes** β€” "Fixed the CORS issue by adding header X" (unless it recurs) +- **Session-specific context** β€” "We decided to use Approach A in today's meeting" +- **Unstable patterns** β€” "Currently using v3 of the API" (will change) +- **Obvious things** β€” "Run tests before committing" (Claude knows this) +- **Credentials or secrets** β€” never store in any memory file + +### Don't duplicate: +- If CLAUDE.md already says "Use pnpm", don't also keep it in MEMORY.md +- After promoting, remove the source entry to free space + +## Promotion Workflow + +``` +1. /si:review identifies candidate +2. Confirm the pattern is still valid +3. Distill into one-line instruction +4. /si:promote writes to CLAUDE.md or rules/ +5. Remove from MEMORY.md +6. Verify with /si:status +``` diff --git a/engineering-team/self-improving-agent/reference/rules-directory-patterns.md b/engineering-team/self-improving-agent/reference/rules-directory-patterns.md new file mode 100644 index 0000000..0d5bd76 --- /dev/null +++ b/engineering-team/self-improving-agent/reference/rules-directory-patterns.md @@ -0,0 +1,137 @@ +# Rules Directory Patterns + +Best practices for organizing `.claude/rules/` files β€” the scoped instruction system that loads rules only when relevant files are open. + +## Directory Structure + +``` +.claude/ +β”œβ”€β”€ CLAUDE.md # Main project instructions (always loaded) +└── rules/ + β”œβ”€β”€ code-style.md # No paths β†’ loads always (like CLAUDE.md) + β”œβ”€β”€ testing.md # Scoped to test files + β”œβ”€β”€ api-design.md # Scoped to API source files + β”œβ”€β”€ database.md # Scoped to migration/model files + └── frontend/ + β”œβ”€β”€ components.md # Scoped to React components + └── styling.md # Scoped to CSS/styled files +``` + +## Path Scoping + +### Basic patterns + +```yaml +--- +paths: + - "**/*.test.ts" # All TypeScript test files + - "src/api/**/*.ts" # API source files + - "*.md" # Root-level markdown + - "src/components/**/*.tsx" # React components +--- +``` + +### Brace expansion + +```yaml +--- +paths: + - "src/**/*.{ts,tsx}" # All TypeScript + TSX + - "tests/**/*.{test,spec}.ts" # Test and spec files +--- +``` + +### Multiple scopes + +```yaml +--- +paths: + - "src/api/**/*.ts" + - "tests/api/**/*" + - "openapi.yaml" +--- +``` + +## Common Rule Files + +### testing.md +```yaml +--- +paths: + - "**/*.test.{ts,tsx,js,jsx}" + - "**/*.spec.{ts,tsx,js,jsx}" + - "tests/**/*" + - "__tests__/**/*" +--- + +# Testing Rules + +- Use `describe` blocks to group related tests +- One assertion per test when possible +- Mock external services; never hit real APIs in tests +- Use factories for test data, not inline objects +- Run `pnpm test` before committing +``` + +### api-design.md +```yaml +--- +paths: + - "src/api/**/*.ts" + - "src/routes/**/*.ts" + - "src/handlers/**/*.ts" +--- + +# API Design Rules + +- Validate all input with Zod schemas +- Use `ApiError` class for error responses +- Include OpenAPI JSDoc on all handlers +- Return consistent error format: `{ error: string, code: string }` +``` + +### database.md +```yaml +--- +paths: + - "src/db/**/*" + - "migrations/**/*" + - "prisma/**/*" + - "drizzle/**/*" +--- + +# Database Rules + +- Always create a migration for schema changes +- Never modify existing migrations β€” create new ones +- Use transactions for multi-table operations +- Index foreign keys and frequently queried columns +``` + +### security.md (unscoped β€” always loads) +```markdown +# Security Rules + +- Never log sensitive data (tokens, passwords, PII) +- Sanitize all user input before database queries +- Use parameterized queries, never string interpolation +- Validate file uploads: type, size, content +- Environment variables for all secrets β€” never hardcode +``` + +## When to Create a Rule File + +| Signal | Action | +|--------|--------| +| CLAUDE.md over 150 lines | Move scoped patterns to rules/ | +| Same instruction repeated for different file types | Create a scoped rule | +| `/si:promote` suggests a file-type-specific pattern | Create or append to a rule file | +| Team adds a new convention for a specific area | New rule file | + +## Organization Tips + +1. **One topic per file** β€” `testing.md`, not `testing-and-linting.md` +2. **Use subdirectories for large projects** β€” `rules/frontend/`, `rules/backend/` +3. **Keep unscoped rules minimal** β€” they load every session like CLAUDE.md +4. **Review after refactors** β€” paths may change when directories are reorganized +5. **Share via git** β€” rules/ should be version-controlled (unlike auto-memory) diff --git a/engineering-team/self-improving-agent/settings.json b/engineering-team/self-improving-agent/settings.json new file mode 100644 index 0000000..06b5282 --- /dev/null +++ b/engineering-team/self-improving-agent/settings.json @@ -0,0 +1,28 @@ +{ + "name": "self-improving-agent", + "displayName": "Self-Improving Agent", + "version": "1.0.0", + "description": "Curate auto-memory, promote learnings to rules, extract skills from patterns.", + "author": "Reza Rezvani", + "license": "MIT", + "platforms": ["claude-code", "openclaw", "codex"], + "category": "development", + "tags": ["memory", "auto-memory", "self-improvement", "learning", "rules", "skills"], + "repository": "https://github.com/alirezarezvani/claude-skills", + "commands": { + "review": "/si:review", + "promote": "/si:promote", + "extract": "/si:extract", + "status": "/si:status", + "remember": "/si:remember" + }, + "hooks": { + "PostToolUse": { + "Bash": "hooks/error-capture.sh" + } + }, + "agents": [ + "memory-analyst", + "skill-extractor" + ] +} diff --git a/engineering-team/self-improving-agent/skills/extract/SKILL.md b/engineering-team/self-improving-agent/skills/extract/SKILL.md new file mode 100644 index 0000000..c43f4ad --- /dev/null +++ b/engineering-team/self-improving-agent/skills/extract/SKILL.md @@ -0,0 +1,179 @@ +--- +name: extract +description: "Turn a proven pattern or debugging solution into a standalone reusable skill with SKILL.md, reference docs, and examples." +command: /si:extract +--- + +# /si:extract β€” Create Skills from Patterns + +Transforms a recurring pattern or debugging solution into a standalone, portable skill that can be installed in any project. + +## Usage + +``` +/si:extract # Interactive extraction +/si:extract --name docker-m1-fixes # Specify skill name +/si:extract --output ./skills/ # Custom output directory +/si:extract --dry-run # Preview without creating files +``` + +## When to Extract + +A learning qualifies for skill extraction when ANY of these are true: + +| Criterion | Signal | +|---|---| +| **Recurring** | Same issue across 2+ projects | +| **Non-obvious** | Required real debugging to discover | +| **Broadly applicable** | Not tied to one specific codebase | +| **Complex solution** | Multi-step fix that's easy to forget | +| **User-flagged** | "Save this as a skill", "I want to reuse this" | + +## Workflow + +### Step 1: Identify the pattern + +Read the user's description. Search auto-memory for related entries: + +```bash +MEMORY_DIR="$HOME/.claude/projects/$(pwd | sed 's|/|%2F|g; s|%2F|/|; s|^/||')/memory" +grep -rni "" "$MEMORY_DIR/" +``` + +If found in auto-memory, use those entries as source material. If not, use the user's description directly. + +### Step 2: Determine skill scope + +Ask (max 2 questions): +- "What problem does this solve?" (if not clear) +- "Should this include code examples?" (if applicable) + +### Step 3: Generate skill name + +Rules for naming: +- Lowercase, hyphens between words +- Descriptive but concise (2-4 words) +- Examples: `docker-m1-fixes`, `api-timeout-patterns`, `pnpm-workspace-setup` + +### Step 4: Create the skill files + +**Spawn the `skill-extractor` agent** for the actual file generation. + +The agent creates: + +``` +/ +β”œβ”€β”€ SKILL.md # Main skill file with frontmatter +β”œβ”€β”€ README.md # Human-readable overview +└── reference/ # (optional) Supporting documentation + └── examples.md # Concrete examples and edge cases +``` + +### Step 5: SKILL.md structure + +The generated SKILL.md must follow this format: + +```markdown +--- +name: +description: ". Use when: ." +--- + +# + +> One-line summary of what this skill solves. + +## Quick Reference + +| Problem | Solution | +|---------|----------| +| {{problem 1}} | {{solution 1}} | +| {{problem 2}} | {{solution 2}} | + +## The Problem + +{{2-3 sentences explaining what goes wrong and why it's non-obvious.}} + +## Solutions + +### Option 1: {{Name}} (Recommended) + +{{Step-by-step with code examples.}} + +### Option 2: {{Alternative}} + +{{For when Option 1 doesn't apply.}} + +## Trade-offs + +| Approach | Pros | Cons | +|----------|------|------| +| Option 1 | {{pros}} | {{cons}} | +| Option 2 | {{pros}} | {{cons}} | + +## Edge Cases + +- {{edge case 1 and how to handle it}} +- {{edge case 2 and how to handle it}} +``` + +### Step 6: Quality gates + +Before finalizing, verify: + +- [ ] SKILL.md has valid YAML frontmatter with `name` and `description` +- [ ] `name` matches the folder name (lowercase, hyphens) +- [ ] Description includes "Use when:" trigger conditions +- [ ] Solutions are self-contained (no external context needed) +- [ ] Code examples are complete and copy-pasteable +- [ ] No project-specific hardcoded values (paths, URLs, credentials) +- [ ] No unnecessary dependencies + +### Step 7: Report + +``` +βœ… Skill extracted: {{skill-name}} + +Files created: + {{path}}/SKILL.md ({{lines}} lines) + {{path}}/README.md ({{lines}} lines) + {{path}}/reference/examples.md ({{lines}} lines) + +Install: /plugin install (copy to your skills directory) +Publish: clawhub publish {{path}} + +Source: MEMORY.md entries at lines {{n, m, ...}} (retained β€” the skill is portable, the memory is project-specific) +``` + +## Examples + +### Extracting a debugging pattern + +``` +/si:extract "Fix for Docker builds failing on Apple Silicon with platform mismatch" +``` + +Creates `docker-m1-fixes/SKILL.md` with: +- The platform mismatch error message +- Three solutions (build flag, Dockerfile, docker-compose) +- Trade-offs table +- Performance note about Rosetta 2 emulation + +### Extracting a workflow pattern + +``` +/si:extract "Always regenerate TypeScript API client after modifying OpenAPI spec" +``` + +Creates `api-client-regen/SKILL.md` with: +- Why manual regen is needed +- The exact command sequence +- CI integration snippet +- Common failure modes + +## Tips + +- Extract patterns that would save time in a *different* project +- Keep skills focused β€” one problem per skill +- Include the error messages people would search for +- Test the skill by reading it without the original context β€” does it make sense? diff --git a/engineering-team/self-improving-agent/skills/promote/SKILL.md b/engineering-team/self-improving-agent/skills/promote/SKILL.md new file mode 100644 index 0000000..2b7fa0f --- /dev/null +++ b/engineering-team/self-improving-agent/skills/promote/SKILL.md @@ -0,0 +1,145 @@ +--- +name: promote +description: "Graduate a proven pattern from auto-memory (MEMORY.md) to CLAUDE.md or .claude/rules/ for permanent enforcement." +command: /si:promote +--- + +# /si:promote β€” Graduate Learnings to Rules + +Moves a proven pattern from Claude's auto-memory into the project's rule system, where it becomes an enforced instruction rather than a background note. + +## Usage + +``` +/si:promote # Auto-detect best target +/si:promote --target claude.md # Promote to CLAUDE.md +/si:promote --target rules/testing.md # Promote to scoped rule +/si:promote --target rules/api.md --paths "src/api/**/*.ts" # Scoped with paths +``` + +## Workflow + +### Step 1: Understand the pattern + +Parse the user's description. If vague, ask one clarifying question: +- "What specific behavior should Claude follow?" +- "Does this apply to all files or specific paths?" + +### Step 2: Find the pattern in auto-memory + +```bash +# Search MEMORY.md for related entries +MEMORY_DIR="$HOME/.claude/projects/$(pwd | sed 's|/|%2F|g; s|%2F|/|; s|^/||')/memory" +grep -ni "" "$MEMORY_DIR/MEMORY.md" +``` + +Show the matching entries and confirm they're what the user means. + +### Step 3: Determine the right target + +| Pattern scope | Target | Example | +|---|---|---| +| Applies to entire project | `./CLAUDE.md` | "Use pnpm, not npm" | +| Applies to specific file types | `.claude/rules/.md` | "API handlers need validation" | +| Applies to all your projects | `~/.claude/CLAUDE.md` | "Prefer explicit error handling" | + +If the user didn't specify a target, recommend one based on scope. + +### Step 4: Distill into a concise rule + +Transform the learning from auto-memory's note format into CLAUDE.md's instruction format: + +**Before** (MEMORY.md β€” descriptive): +> The project uses pnpm workspaces. When I tried npm install it failed. The lock file is pnpm-lock.yaml. Must use pnpm install for dependencies. + +**After** (CLAUDE.md β€” prescriptive): +```markdown +## Build & Dependencies +- Package manager: pnpm (not npm). Use `pnpm install`. +``` + +**Rules for distillation:** +- One line per rule when possible +- Imperative voice ("Use X", "Always Y", "Never Z") +- Include the command or example, not just the concept +- No backstory β€” just the instruction + +### Step 5: Write to target + +**For CLAUDE.md:** +1. Read existing CLAUDE.md +2. Find the appropriate section (or create one) +3. Append the new rule under the right heading +4. If file would exceed 200 lines, suggest using `.claude/rules/` instead + +**For `.claude/rules/`:** +1. Create the file if it doesn't exist +2. Add YAML frontmatter with `paths` if scoped +3. Write the rule content + +```markdown +--- +paths: + - "src/api/**/*.ts" + - "tests/api/**/*" +--- + +# API Development Rules + +- All endpoints must validate input with Zod schemas +- Use `ApiError` class for error responses (not raw Error) +- Include OpenAPI JSDoc comments on handler functions +``` + +### Step 6: Clean up auto-memory + +After promoting, remove or mark the original entry in MEMORY.md: + +```bash +# Show what will be removed +grep -n "" "$MEMORY_DIR/MEMORY.md" +``` + +Ask the user to confirm removal. Then edit MEMORY.md to remove the promoted entry. This frees space for new learnings. + +### Step 7: Confirm + +``` +βœ… Promoted to {{target}} + +Rule: "{{distilled rule}}" +Source: MEMORY.md line {{n}} (removed) +MEMORY.md: {{lines}}/200 lines remaining + +The pattern is now an enforced instruction. Claude will follow it in all future sessions. +``` + +## Promotion Decision Guide + +### Promote when: +- Pattern appeared 3+ times in auto-memory +- You corrected Claude about it more than once +- It's a project convention that any contributor should know +- It prevents a recurring mistake + +### Don't promote when: +- It's a one-time debugging note (leave in auto-memory) +- It's session-specific context (session memory handles this) +- It might change soon (e.g., during a migration) +- It's already covered by existing rules + +### CLAUDE.md vs .claude/rules/ + +| Use CLAUDE.md for | Use .claude/rules/ for | +|---|---| +| Global project rules | File-type-specific patterns | +| Build commands | Testing conventions | +| Architecture decisions | API design rules | +| Team conventions | Framework-specific gotchas | + +## Tips + +- Keep CLAUDE.md under 200 lines β€” use rules/ for overflow +- One rule per line is easier to maintain than paragraphs +- Include the concrete command, not just the concept +- Review promoted rules quarterly β€” remove what's no longer relevant diff --git a/engineering-team/self-improving-agent/skills/remember/SKILL.md b/engineering-team/self-improving-agent/skills/remember/SKILL.md new file mode 100644 index 0000000..a793994 --- /dev/null +++ b/engineering-team/self-improving-agent/skills/remember/SKILL.md @@ -0,0 +1,99 @@ +--- +name: remember +description: "Explicitly save important knowledge to auto-memory with timestamp and context. Use when a discovery is too important to rely on auto-capture." +command: /si:remember +--- + +# /si:remember β€” Save Knowledge Explicitly + +Writes an explicit entry to auto-memory when something is important enough that you don't want to rely on Claude noticing it automatically. + +## Usage + +``` +/si:remember +/si:remember "This project's CI requires Node 20 LTS β€” v22 breaks the build" +/si:remember "The /api/auth endpoint uses a custom JWT library, not passport" +/si:remember "Reza prefers explicit error handling over try-catch-all patterns" +``` + +## When to Use + +| Situation | Example | +|-----------|---------| +| Hard-won debugging insight | "CORS errors on /api/upload are caused by the CDN, not the backend" | +| Project convention not in CLAUDE.md | "We use barrel exports in src/components/" | +| Tool-specific gotcha | "Jest needs `--forceExit` flag or it hangs on DB tests" | +| Architecture decision | "We chose Drizzle over Prisma for type-safe SQL" | +| Preference you want Claude to learn | "Don't add comments explaining obvious code" | + +## Workflow + +### Step 1: Parse the knowledge + +Extract from the user's input: +- **What**: The concrete fact or pattern +- **Why it matters**: Context (if provided) +- **Scope**: Project-specific or global? + +### Step 2: Check for duplicates + +```bash +MEMORY_DIR="$HOME/.claude/projects/$(pwd | sed 's|/|%2F|g; s|%2F|/|; s|^/||')/memory" +grep -ni "" "$MEMORY_DIR/MEMORY.md" 2>/dev/null +``` + +If a similar entry exists: +- Show it to the user +- Ask: "Update the existing entry or add a new one?" + +### Step 3: Write to MEMORY.md + +Append to the end of `MEMORY.md`: + +```markdown +- {{concise fact or pattern}} +``` + +Keep entries concise β€” one line when possible. Auto-memory entries don't need timestamps, IDs, or metadata. They're notes, not database records. + +If MEMORY.md is over 180 lines, warn the user: + +``` +⚠️ MEMORY.md is at {{n}}/200 lines. Consider running /si:review to free space. +``` + +### Step 4: Suggest promotion + +If the knowledge sounds like a rule (imperative, always/never, convention): + +``` +πŸ’‘ This sounds like it could be a CLAUDE.md rule rather than a memory entry. + Rules are enforced with higher priority. Want to /si:promote it instead? +``` + +### Step 5: Confirm + +``` +βœ… Saved to auto-memory + + "{{entry}}" + + MEMORY.md: {{n}}/200 lines + Claude will see this at the start of every session in this project. +``` + +## What NOT to use /si:remember for + +- **Temporary context**: Use session memory or just tell Claude in conversation +- **Enforced rules**: Use `/si:promote` to write directly to CLAUDE.md +- **Cross-project knowledge**: Use `~/.claude/CLAUDE.md` for global rules +- **Sensitive data**: Never store credentials, tokens, or secrets in memory files + +## Tips + +- Be concise β€” one line beats a paragraph +- Include the concrete command or value, not just the concept + - βœ… "Build with `pnpm build`, tests with `pnpm test:e2e`" + - ❌ "The project uses pnpm for building and testing" +- If you're remembering the same thing twice, promote it to CLAUDE.md diff --git a/engineering-team/self-improving-agent/skills/review/SKILL.md b/engineering-team/self-improving-agent/skills/review/SKILL.md new file mode 100644 index 0000000..2417953 --- /dev/null +++ b/engineering-team/self-improving-agent/skills/review/SKILL.md @@ -0,0 +1,127 @@ +--- +name: review +description: "Analyze auto-memory for promotion candidates, stale entries, consolidation opportunities, and health metrics." +command: /si:review +--- + +# /si:review β€” Analyze Auto-Memory + +Performs a comprehensive audit of Claude Code's auto-memory and produces actionable recommendations. + +## Usage + +``` +/si:review # Full review +/si:review --quick # Summary only (counts + top 3 candidates) +/si:review --stale # Focus on stale/outdated entries +/si:review --candidates # Show only promotion candidates +``` + +## What It Does + +### Step 1: Locate memory directory + +```bash +# Find the project's auto-memory directory +MEMORY_DIR="$HOME/.claude/projects/$(pwd | sed 's|/|%2F|g; s|%2F|/|; s|^/||')/memory" + +# Fallback: check common path patterns +# ~/.claude/projects///memory/ +# ~/.claude/projects//memory/ + +# List all memory files +ls -la "$MEMORY_DIR"/ +``` + +If memory directory doesn't exist, report that auto-memory may be disabled. Suggest checking with `/memory`. + +### Step 2: Read and analyze MEMORY.md + +Read the full `MEMORY.md` file. Count lines and check against the 200-line startup limit. + +Analyze each entry for: + +1. **Recurrence indicators** + - Same concept appears multiple times (different wording) + - References to "again" or "still" or "keeps happening" + - Similar entries across topic files + +2. **Staleness indicators** + - References files that no longer exist (`find` to verify) + - Mentions outdated tools, versions, or commands + - Contradicts current CLAUDE.md rules + +3. **Consolidation opportunities** + - Multiple entries about the same topic (e.g., three lines about testing) + - Entries that could merge into one concise rule + +4. **Promotion candidates** β€” entries that meet ALL criteria: + - Appeared in 2+ sessions (check wording patterns) + - Not project-specific trivia (broadly useful) + - Actionable (can be written as a concrete rule) + - Not already in CLAUDE.md or `.claude/rules/` + +### Step 3: Read topic files + +If `MEMORY.md` references or the directory contains additional files (`debugging.md`, `patterns.md`, etc.): +- Read each one +- Cross-reference with MEMORY.md for duplicates +- Check for entries that belong in the main file (high value) vs. topic files (details) + +### Step 4: Cross-reference with CLAUDE.md + +Read the project's `CLAUDE.md` (if it exists) and compare: +- Are there MEMORY.md entries that duplicate CLAUDE.md rules? (β†’ remove from memory) +- Are there MEMORY.md entries that contradict CLAUDE.md? (β†’ flag conflict) +- Are there MEMORY.md patterns not yet in CLAUDE.md that should be? (β†’ promotion candidate) + +Also check `.claude/rules/` directory for existing scoped rules. + +### Step 5: Generate report + +Output format: + +``` +πŸ“Š Auto-Memory Review + +Memory Health: + MEMORY.md: {{lines}}/200 lines ({{percent}}%) + Topic files: {{count}} ({{names}}) + CLAUDE.md: {{lines}} lines + Rules: {{count}} files in .claude/rules/ + +🎯 Promotion Candidates ({{count}}): + 1. "{{pattern}}" β€” seen {{n}}x, applies broadly + β†’ Suggest: {{target}} (CLAUDE.md / .claude/rules/{{name}}.md) + 2. ... + +πŸ—‘οΈ Stale Entries ({{count}}): + 1. Line {{n}}: "{{entry}}" β€” {{reason}} + 2. ... + +πŸ”„ Consolidation ({{count}} groups): + 1. Lines {{a}}, {{b}}, {{c}} all about {{topic}} β†’ merge into 1 entry + 2. ... + +⚠️ Conflicts ({{count}}): + 1. MEMORY.md line {{n}} contradicts CLAUDE.md: {{detail}} + +πŸ’‘ Recommendations: + - {{actionable suggestion}} + - {{actionable suggestion}} +``` + +## When to Use + +- After completing a major feature or debugging session +- When `/si:status` shows MEMORY.md is over 150 lines +- Weekly during active development +- Before starting a new project phase +- After onboarding a new team member (review what Claude learned) + +## Tips + +- Run `/si:review --quick` frequently (low overhead) +- Full review is most valuable when MEMORY.md is getting crowded +- Act on promotion candidates promptly β€” they're proven patterns +- Don't hesitate to delete stale entries β€” auto-memory will re-learn if needed diff --git a/engineering-team/self-improving-agent/skills/status/SKILL.md b/engineering-team/self-improving-agent/skills/status/SKILL.md new file mode 100644 index 0000000..0e6f595 --- /dev/null +++ b/engineering-team/self-improving-agent/skills/status/SKILL.md @@ -0,0 +1,104 @@ +--- +name: status +description: "Memory health dashboard showing line counts, topic files, capacity, stale entries, and recommendations." +command: /si:status +--- + +# /si:status β€” Memory Health Dashboard + +Quick overview of your project's memory state across all memory systems. + +## Usage + +``` +/si:status # Full dashboard +/si:status --brief # One-line summary +``` + +## What It Reports + +### Step 1: Locate all memory files + +```bash +# Auto-memory directory +MEMORY_DIR="$HOME/.claude/projects/$(pwd | sed 's|/|%2F|g; s|%2F|/|; s|^/||')/memory" + +# Count lines in MEMORY.md +wc -l "$MEMORY_DIR/MEMORY.md" 2>/dev/null || echo "0" + +# List topic files +ls "$MEMORY_DIR/"*.md 2>/dev/null | grep -v MEMORY.md + +# CLAUDE.md +wc -l ./CLAUDE.md 2>/dev/null || echo "0" +wc -l ~/.claude/CLAUDE.md 2>/dev/null || echo "0" + +# Rules directory +ls .claude/rules/*.md 2>/dev/null | wc -l +``` + +### Step 2: Analyze capacity + +| Metric | Healthy | Warning | Critical | +|--------|---------|---------|----------| +| MEMORY.md lines | < 120 | 120-180 | > 180 | +| CLAUDE.md lines | < 150 | 150-200 | > 200 | +| Topic files | 0-3 | 4-6 | > 6 | +| Stale entries | 0 | 1-3 | > 3 | + +### Step 3: Quick stale check + +For each MEMORY.md entry that references a file path: +```bash +# Verify referenced files still exist +grep -oE '[a-zA-Z0-9_/.-]+\.(ts|js|py|md|json|yaml|yml)' "$MEMORY_DIR/MEMORY.md" | while read f; do + [ ! -f "$f" ] && echo "STALE: $f" +done +``` + +### Step 4: Output + +``` +πŸ“Š Memory Status + + Auto-Memory (MEMORY.md): + Lines: {{n}}/200 ({{bar}}) {{emoji}} + Topic files: {{count}} ({{names}}) + Last updated: {{date}} + + Project Rules: + CLAUDE.md: {{n}} lines + Rules: {{count}} files in .claude/rules/ + User global: {{n}} lines (~/.claude/CLAUDE.md) + + Health: + Capacity: {{healthy/warning/critical}} + Stale refs: {{count}} (files no longer exist) + Duplicates: {{count}} (entries repeated across files) + + {{if recommendations}} + πŸ’‘ Recommendations: + - {{recommendation}} + {{endif}} +``` + +### Brief mode + +``` +/si:status --brief +``` + +Output: `πŸ“Š Memory: {{n}}/200 lines | {{count}} rules | {{status_emoji}} {{status_word}}` + +## Interpretation + +- **Green (< 60%)**: Plenty of room. Auto-memory is working well. +- **Yellow (60-90%)**: Getting full. Consider running `/si:review` to promote or clean up. +- **Red (> 90%)**: Near capacity. Auto-memory may start dropping older entries. Run `/si:review` now. + +## Tips + +- Run `/si:status --brief` as a quick check anytime +- If capacity is yellow+, run `/si:review` to identify promotion candidates +- Stale entries waste space β€” delete references to files that no longer exist +- Topic files are fine β€” Claude creates them to keep MEMORY.md under 200 lines diff --git a/engineering-team/self-improving-agent/templates/rule-template.md b/engineering-team/self-improving-agent/templates/rule-template.md new file mode 100644 index 0000000..3e87d51 --- /dev/null +++ b/engineering-team/self-improving-agent/templates/rule-template.md @@ -0,0 +1,17 @@ +--- +paths: + - "{{glob-pattern}}" +--- + +# {{Topic}} Rules + +## Conventions +- {{convention 1}} +- {{convention 2}} + +## Patterns +- {{preferred pattern with example}} +- {{anti-pattern to avoid}} + +## Commands +- {{relevant command}}: `{{command}}` diff --git a/engineering-team/self-improving-agent/templates/skill-template.md b/engineering-team/self-improving-agent/templates/skill-template.md new file mode 100644 index 0000000..ce596a2 --- /dev/null +++ b/engineering-team/self-improving-agent/templates/skill-template.md @@ -0,0 +1,53 @@ +--- +name: {{skill-name}} +description: "{{One-line description}}. Use when: {{trigger conditions}}." +--- + +# {{Skill Title}} + +> {{One-line value proposition}} + +## Quick Reference + +| Problem | Solution | +|---------|----------| +| {{error/symptom 1}} | {{fix 1}} | +| {{error/symptom 2}} | {{fix 2}} | + +## The Problem + +{{2-3 sentences explaining what goes wrong and why. +Include the exact error message if applicable.}} + +## Solutions + +### Option 1: {{Name}} (Recommended) + +{{Step-by-step instructions.}} + +```{{language}} +{{code example}} +``` + +### Option 2: {{Alternative}} + +{{When Option 1 doesn't apply.}} + +```{{language}} +{{code example}} +``` + +## Trade-offs + +| Approach | Pros | Cons | +|----------|------|------| +| Option 1 | {{pros}} | {{cons}} | +| Option 2 | {{pros}} | {{cons}} | + +## Edge Cases + +- {{edge case and how to handle it}} + +## Related + +- {{link to official docs}}