@softspark/ai-toolkit 1.0.0

package/app/.claude-plugin/plugin.json

@@ -0,0 +1,44 @@
+{
+  "name": "ai-toolkit",
+  "description": "Professional-grade Claude Code toolkit: 81 skills, 47 agents, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
+  "version": "1.0.0",
+  "author": {
+    "name": "SoftSpark",
+    "url": "https://github.com/softspark"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/softspark/ai-toolkit"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/softspark/ai-toolkit",
+  "npm": "@softspark/ai-toolkit",
+  "install": "npx @softspark/ai-toolkit install",
+  "keywords": [
+    "development",
+    "testing",
+    "deployment",
+    "security",
+    "architecture",
+    "multi-agent",
+    "orchestration",
+    "devops",
+    "code-review",
+    "ai-toolkit",
+    "constitution",
+    "quality-gates",
+    "skills",
+    "agents",
+    "cursor",
+    "codex"
+  ],
+  "marketplace": {
+    "category": "developer-tools",
+    "tags": ["productivity", "code-quality", "agents", "safety"],
+    "listing-url": "https://smithery.ai/plugin/ai-toolkit",
+    "pricing": "free"
+  },
+  "claude-code": {
+    "min-version": "1.0.33"
+  }
+}

package/app/ARCHITECTURE.md

@@ -0,0 +1,306 @@
+# AI Toolkit Architecture
+
+Universal multi-agent system for software development. Works across all repositories.
+
+## Quick Stats
+
+| Component | Count |
+|-----------|-------|
+| Agents | 47 |
+| Skills | 85 |
+| Hooks | 12 events / 15 entries (SessionStart, Notification, PreToolUse ×2, UserPromptSubmit ×2, PostToolUse, Stop ×2, TaskCompleted, TeammateIdle, SubagentStart, SubagentStop, PreCompact, SessionEnd) |
+
+---
+
+## Agents (47)
+
+### Orchestration & Planning (4)
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| `orchestrator` | opus | Multi-agent coordination, minimum 3 agents per task |
+| `project-planner` | opus | Task breakdown, plan creation |
+| `product-manager` | opus | Requirements, user stories, PRDs, backlog prioritization |
+| `tech-lead` | opus | Code quality authority, architecture patterns, stack decisions |
+
+### Development (5)
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| `backend-specialist` | opus | Node.js, Python, PHP, APIs |
+| `frontend-specialist` | opus | React, Next.js, Vue, Nuxt |
+| `mobile-developer` | opus | React Native, Flutter, native |
+| `game-developer` | opus | Unity, Godot, Unreal, Phaser |
+| `database-architect` | opus | Schema design, migrations, query optimization, operations |
+
+### AI/ML (7)
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| `ai-engineer` | opus | LLM integration, vector search |
+| `ml-engineer` | opus | Model training, MLOps |
+| `nlp-engineer` | opus | NLP pipelines, text processing |
+| `data-scientist` | opus | Statistics, analysis, visualization |
+| `data-analyst` | sonnet | SQL, analytics, reporting |
+| `prompt-engineer` | opus | Prompt design, optimization |
+| `rag-engineer` | opus | RAG pipelines, retrieval |
+
+### Quality & Security (6)
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| `code-reviewer` | opus | Code review, standards |
+| `test-engineer` | opus | Test strategy, implementation |
+| `qa-automation-engineer` | opus | E2E, API, performance testing |
+| `security-auditor` | opus | Security audit, pen testing, OWASP, vulnerability assessment |
+| `security-architect` | opus | Threat modeling, secure design, AuthN/AuthZ |
+| `system-governor` | opus | Constitution guardian, VETO power |
+
+### Infrastructure & DevOps (6)
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| `devops-implementer` | opus | CI/CD, automation |
+| `infrastructure-architect` | opus | Cloud architecture, IaC |
+| `infrastructure-validator` | sonnet | Infrastructure validation |
+| `incident-responder` | sonnet | Incident management |
+| `performance-optimizer` | opus | Performance tuning |
+| `llm-ops-engineer` | opus | LLM operations, monitoring |
+
+### Research & Documentation (6)
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| `explorer-agent` | sonnet | Codebase discovery (READ-ONLY) |
+| `research-synthesizer` | opus | Research coordination, synthesis, reports |
+| `technical-researcher` | opus | Deep technical investigation |
+| `search-specialist` | sonnet | Search optimization |
+| `fact-checker` | sonnet | Verification, source checking |
+| `documenter` | sonnet | Documentation, KB management, SOPs, API docs |
+
+### Management & Evolution (4)
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| `chief-of-staff` | sonnet | Executive summaries, daily briefings |
+| `meta-architect` | opus | Self-optimization, agent definition updates |
+| `predictive-analyst` | sonnet | Impact prediction, regression forecasting |
+| `business-intelligence` | sonnet | Opportunity discovery, KPI gaps |
+
+### Autonomous (2)
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| `night-watchman` | sonnet | Autonomous maintenance: dependency updates, dead code |
+| `chaos-monkey` | opus | Resilience testing: fault injection, failure verification |
+
+### MCP (3)
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| `mcp-expert` | opus | MCP protocol expertise |
+| `mcp-server-architect` | opus | MCP server design |
+| `mcp-testing-engineer` | sonnet | MCP testing |
+
+### Specialist (4)
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| `debugger` | opus | Bug investigation, root cause |
+| `code-archaeologist` | sonnet | Legacy code investigation |
+| `command-expert` | sonnet | CLI, bash, automation |
+| `seo-specialist` | sonnet | SEO optimization |
+
+---
+
+## Skills (85)
+
+### Task Skills (27)
+| Skill | Slash Command | Purpose |
+|-------|---------------|---------|
+| `commit` | `/commit` | Create well-structured git commits (Conventional Commits) |
+| `pr` | `/pr` | Create GitHub pull request with template and checks |
+| `test` | `/test` | Run tests (pytest, vitest, phpunit, flutter, go, cargo) |
+| `build` | `/build` | Build project (auto-detects type) |
+| `lint` | `/lint` | Run linting and type checking |
+| `fix` | `/fix` | Auto-fix failing tests or lint errors |
+| `deploy` | `/deploy` | Deploy to target environment with pre-checks |
+| `rollback` | `/rollback` | Safe rollback (git, database, deployment) |
+| `migrate` | `/migrate` | Database migration workflow |
+| `ci` | `/ci` | Generate/manage CI/CD pipeline configuration |
+| `panic` | `/panic` | Emergency halt all autonomous operations |
+| `index` | `/index` | Reindex knowledge base with change detection |
+| `onboard` | `/onboard` | Guided project setup with the toolkit |
+| `night-watch` | `/night-watch` | Trigger autonomous maintenance cycle |
+| `evolve` | `/evolve` | Trigger meta-architect self-optimization |
+| `chaos` | `/chaos` | Run chaos engineering experiment |
+| `predict` | `/predict` | Analyze code changes for impact and risks |
+| `biz-scan` | `/biz-scan` | Scan for business value opportunities |
+| `briefing` | `/briefing` | Generate executive summary of system status |
+| `evaluate` | `/evaluate` | Evaluate RAG quality |
+| `health` | `/health` | Health check (auto-detect services) |
+| `skill-creator` | `/skill-creator` | Create new skills following Agent Skills standard |
+| `hook-creator` | `/hook-creator` | Create new hooks with guided workflow and validation |
+| `command-creator` | `/command-creator` | Create new slash commands with frontmatter and workflow guidance |
+| `agent-creator` | `/agent-creator` | Create new specialized agents with tools and trigger guidance |
+| `plugin-creator` | `/plugin-creator` | Create experimental opt-in plugin packs with manifests, conventions, and optional modules |
+| `prd-to-issues` | `/prd-to-issues` | Break PRD into GitHub issues with vertical slices and HITL/AFK tagging |
+
+### Hybrid Skills (27)
+| Skill | Slash Command | Purpose |
+|-------|---------------|---------|
+| `explore` | `/explore` | Codebase exploration and tech stack discovery |
+| `debug` | `/debug` | Systematic debugging with logs and diagnostics |
+| `review` | `/review` | Code review for quality, security, performance |
+| `plan` | `/plan` | Create structured plan with task breakdown |
+| `refactor` | `/refactor` | Plan and execute code refactoring with safety checks |
+| `analyze` | `/analyze` | Analyze code quality, complexity, and patterns |
+| `docs` | `/docs` | Generate/update documentation (README, API docs, architecture notes) |
+| `search` | `/search` | Search knowledge base (MCP + local fallback) |
+| `explain` | `/explain` | Explain file/module architecture with Mermaid diagrams |
+| `orchestrate` | `/orchestrate` | Multi-agent coordination for complex tasks |
+| `swarm` | `/swarm` | Massive parallelism via Agent Teams |
+| `workflow` | `/workflow` | Run agent workflow |
+| `instinct-review` | `/instinct-review` | Review, curate, and manage learned instincts |
+| `teams` | `/teams` | Launch pre-configured Agent Teams compositions |
+| `write-a-prd` | `/write-a-prd` | Create PRD through interactive interview and module design |
+| `prd-to-plan` | `/prd-to-plan` | Convert PRD into phased vertical-slice implementation plan |
+| `tdd` | `/tdd` | Test-driven development with red-green-refactor loop |
+| `design-an-interface` | `/design-an-interface` | Generate 3+ radically different interface designs |
+| `grill-me` | `/grill-me` | Stress-test a plan through relentless Socratic questioning |
+| `ubiquitous-language` | `/ubiquitous-language` | Extract DDD-style ubiquitous language glossary |
+| `refactor-plan` | `/refactor-plan` | Create detailed refactor plan with tiny commits |
+| `qa-session` | `/qa-session` | Interactive QA session with GitHub issue filing |
+| `triage-issue` | `/triage-issue` | Triage bug with deep investigation and TDD fix plan |
+| `architecture-audit` | `/architecture-audit` | Discover shallow modules and propose deepening refactors |
+| `subagent-development` | `/subagent-development` | Execute plans with 2-stage review (spec + quality) per task |
+| `repeat` | `/repeat` | Autonomous loop with safety controls (Ralph Wiggum pattern) |
+| `mem-search` | `/mem-search` | Search past coding sessions via natural language (memory-pack) |
+
+### Knowledge Skills - Development (15)
+| Skill | Purpose |
+|-------|---------|
+| `app-builder` | Project scaffolding, tech stack |
+| `api-patterns` | REST, GraphQL, JSON-RPC |
+| `database-patterns` | Schema, queries, migrations |
+| `flutter-patterns` | Flutter/Dart patterns |
+| `ecommerce-patterns` | Magento, PrestaShop, etc. |
+| `clean-code` | Multi-language code quality principles |
+| `typescript-patterns` | TypeScript/JavaScript patterns for frontend and backend |
+| `design-engineering` | UI polish, animation craft, easing, transforms, accessibility |
+| `documentation-standards` | KB document conventions, frontmatter spec, category taxonomy |
+| `rust-patterns` | Ownership, borrowing, Cargo, tokio, serde |
+| `java-patterns` | Records, sealed classes, Spring Boot, JUnit 5 |
+| `csharp-patterns` | Nullable refs, async/await, ASP.NET Core, EF Core |
+| `kotlin-patterns` | Coroutines, DSLs, sealed classes, Ktor, MockK |
+| `swift-patterns` | Protocol-oriented, SwiftUI, async/await, SPM |
+| `ruby-patterns` | Blocks, Rails conventions, RSpec, ActiveRecord |
+
+### Knowledge Skills - Infrastructure (6)
+| Skill | Purpose |
+|-------|---------|
+| `docker-devops` | Docker, CI/CD |
+| `security-patterns` | Auth, validation, security |
+| `ci-cd-patterns` | GitHub Actions, GitLab CI, Kubernetes |
+| `observability-patterns` | Logging, metrics, tracing, monitoring |
+| `testing-patterns` | Multi-language testing strategies |
+| `migration-patterns` | Database & API migration patterns |
+
+### Knowledge Skills - AI/RAG (2)
+| Skill | Purpose |
+|-------|---------|
+| `rag-patterns` | RAG, retrieval optimization |
+| `mcp-patterns` | MCP server patterns |
+
+### Knowledge Skills - Process (7)
+| Skill | Purpose |
+|-------|---------|
+| `plan-writing` | Task breakdown, planning |
+| `debugging-tactics` | Iron Law 4-phase debugging: root cause → pattern → hypothesis → fix |
+| `git-mastery` | Safe history rewriting, bisect, complex merges |
+| `architecture-decision` | Trade-off analysis, architecture note templates |
+| `performance-profiling` | CPU, memory, I/O, database bottleneck profiling |
+| `research-mastery` | Hierarchy of Truth protocol |
+| `verification-before-completion` | Iron Law: evidence-before-claims, no completion without fresh verification |
+
+### Knowledge Skills - Orchestration (1)
+| Skill | Purpose |
+|-------|---------|
+| `hive-mind` | Swarm intelligence: Consensus, Aggregation |
+
+---
+
+## Orchestration Model
+
+### 2-Phase Orchestration
+```
+Phase 1: PLANNING
+├── Decompose task
+├── Select agents (minimum 3)
+├── Create dependencies
+└── USER CHECKPOINT <- Approval required
+
+Phase 2: IMPLEMENTATION
+├── Execute in dependency order
+├── Collect results
+└── Generate report
+```
+
+### Agent Selection Matrix
+| Task Type | Primary | Supporting |
+|-----------|---------|------------|
+| New Feature | backend/frontend | test-engineer, code-reviewer |
+| Bug Fix | debugger | backend/frontend, test-engineer |
+| Performance | performance-optimizer | database-architect |
+| Security | security-auditor | code-reviewer |
+| Research | research-synthesizer | technical-researcher, search-specialist |
+| Documentation | documenter | explorer-agent |
+
+---
+
+## Directory Structure
+
+```
+.claude/
+├── ARCHITECTURE.md      # This file
+├── agents/              # Agent definitions (47)
+├── hooks.json           # Quality gate hooks (multi-language)
+├── skills/              # All skills: task, hybrid, knowledge (85)
+├── output-styles/       # System prompt output style overrides (e.g. golden-rules)
+├── constitution.md      # Immutable safety rules (5 articles)
+└── settings.local.json  # Local settings + Agent Teams config
+```
+
+---
+
+## Agent Teams Mode (Native Parallelism)
+
+When `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is enabled:
+
+```
+Lead Session (You)
+├── Teammate 1 (security-auditor) -> tmux pane 1
+├── Teammate 2 (backend-specialist) -> tmux pane 2
+├── Teammate 3 (test-engineer) -> tmux pane 3
+└── Shared Task List
+```
+
+### Quality Hooks (`.claude/settings.json` → `hooks`)
+| Hook | Trigger | Action |
+|------|---------|--------|
+| `SessionStart` | Session begins | Loads session context + active instincts |
+| `PreToolUse` | Before Bash execution | Guards against destructive commands |
+| `PreToolUse` | Before file ops (Read/Edit/Write/Glob/Grep) | Guards against wrong-user path hallucination |
+| `UserPromptSubmit` | Before prompt execution | Prompt governance reminder |
+| `UserPromptSubmit` | Before prompt execution | Usage tracking (skill invocations) |
+| `PostToolUse` | After edit/write tools | Lightweight validation reminder |
+| `Stop` | After Claude response | Multi-language quality check + saves session context |
+| `TaskCompleted` | Teammate marks task done | Multi-language lint + type check (blocking) |
+| `TeammateIdle` | Teammate goes idle | Reminds to verify completeness |
+| `SubagentStart` | Subagent starts | Scope reminder for spawned subagents |
+| `SubagentStop` | Subagent completes | Handoff checklist for spawned subagents |
+| `Notification` | Claude notification | OS notification |
+| `PreCompact` | Before compaction | Saves context before compaction boundary |
+| `SessionEnd` | Claude session ends | Writes handoff snapshot for the next session |
+
+---
+
+## Principles
+
+1. **Universal**: No project-specific references
+2. **KB-First**: Always search before answering
+3. **Multi-Agent**: Minimum 3 agents for complex tasks
+4. **2-Phase**: Plan -> Approve -> Implement
+5. **Read-Only Exploration**: Explorer agent never writes
+6. **Cite Sources**: Always include `[PATH: ...]`
+7. **Multi-Language**: All tools, hooks, and skills support multiple tech stacks

package/app/CLAUDE.md.template

@@ -0,0 +1,23 @@
+# [Project Name]
+
+## Overview
+<!-- One sentence: what this does and for whom -->
+
+## Tech Stack
+- **Language**:
+- **Framework**:
+- **Database**:
+
+## Commands
+```bash
+# Dev:
+# Test:
+# Lint:
+# Build:
+```
+
+## Key Conventions
+<!-- Only non-obvious rules that can't be inferred from code -->
+
+## MCP Servers
+<!-- Which servers are configured and one-line when to use each -->

package/app/agents/ai-engineer.md

@@ -0,0 +1,128 @@
+---
+name: ai-engineer
+description: "AI/ML integration specialist. Use for LLM integration, vector databases, RAG pipelines, embeddings, and AI agent orchestration. Triggers: ai, ml, llm, embedding, vector, rag, agent, openai, anthropic."
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: opus
+color: blue
+skills: clean-code, rag-patterns
+---
+
+# AI Engineer
+
+AI/ML integration specialist for production systems.
+
+## Expertise
+- LLM integration (OpenAI, Anthropic, local models)
+- Vector databases (Qdrant, Pinecone, Weaviate, pgvector)
+- RAG pipelines and retrieval optimization
+- Embedding models and fine-tuning
+- AI agent orchestration
+
+## Responsibilities
+
+### LLM Integration
+- Model selection for task requirements
+- Prompt engineering and optimization
+- Context window management
+- Streaming and batching strategies
+
+### Vector Search
+- Embedding model selection
+- Index optimization and sharding
+- Hybrid search (dense + sparse)
+- Relevance tuning
+
+### Production AI
+- Latency optimization
+- Cost management (token usage)
+- Caching strategies
+- Fallback and error handling
+
+## Decision Framework
+
+### Model Selection
+| Task | Model Type | Example |
+|------|------------|---------|
+| Classification | Small, fast | GPT-4o-mini, Claude Haiku |
+| Generation | Medium | GPT-4o, Claude Sonnet |
+| Complex reasoning | Large | Claude Opus, GPT-4 |
+| Local/private | Open | Llama, Mistral |
+
+### Embedding Selection
+| Use Case | Model |
+|----------|-------|
+| General text | text-embedding-3-small |
+| Code search | code-embedding models |
+| Multilingual | multilingual-e5-large |
+| Cost-sensitive | local sentence-transformers |
+
+## KB Integration
+```python
+smart_query("LLM integration patterns")
+hybrid_search_kb("RAG pipeline optimization")
+```
+
+## Anti-Patterns
+- Sending unnecessary context to LLM
+- Missing error handling for API failures
+- No token usage monitoring
+- Hardcoded prompts without versioning
+
+## 🔴 MANDATORY: Post-Code Validation
+
+After editing ANY AI/ML code, run validation before proceeding:
+
+### Step 1: Static Analysis (ALWAYS)
+| Language | Commands |
+|----------|----------|
+| **Python** | `ruff check . && mypy .` |
+| **TypeScript** | `tsc --noEmit && eslint .` |
+
+### Step 2: Run Tests (FOR FEATURES)
+```bash
+# Python
+docker exec rag-mcp-core make test-pytest
+
+# TypeScript/Node
+npm test
+```
+
+### Validation Protocol
+```
+Code written
+    ↓
+Static analysis → Errors? → FIX IMMEDIATELY
+    ↓
+Run tests → Failures? → FIX IMMEDIATELY
+    ↓
+Proceed to next task
+```
+
+> **⚠️ NEVER proceed with lint errors or failing tests!**
+
+## 📚 MANDATORY: Documentation Update
+
+After AI/ML integration changes, update documentation:
+
+### When to Update
+- New models → Update model catalog
+- Integration changes → Update integration docs
+- Prompt changes → Update prompt library
+- Configuration → Update setup guides
+
+### What to Update
+| Change Type | Update |
+|-------------|--------|
+| Models | Model configuration docs |
+| Prompts | Prompt engineering docs |
+| Embeddings | Embedding model docs |
+| Pipelines | Pipeline architecture docs |
+
+### Delegation
+For large documentation tasks, hand off to `documenter` agent.
+
+## Limitations
+
+- **LLM operations** → Use `llm-ops-engineer`
+- **MCP server** → Use `mcp-server-architect`
+- **RAG optimization** → Use `rag-engineer`

package/app/agents/backend-specialist.md

@@ -0,0 +1,193 @@
+---
+name: backend-specialist
+description: "Expert backend architect for Node.js, Python, PHP, and modern serverless systems. Use for API development, server-side logic, database integration, and security. Triggers: backend, server, api, endpoint, database, auth, fastapi, express, laravel."
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: opus
+color: blue
+skills: clean-code, api-patterns, testing-patterns
+---
+
+# Backend Development Architect
+
+You are a Backend Development Architect who designs and builds server-side systems with security, scalability, and maintainability as top priorities.
+
+## ⚡ INSTANT ACTION RULE (SOP Compliance)
+
+**BEFORE any implementation:**
+```python
+# MANDATORY: Search KB FIRST - NO TEXT BEFORE
+smart_query("[task description]")
+hybrid_search_kb("[API patterns, best practices]")
+```
+- NEVER skip, even if you "think you know"
+- Cite sources: `[PATH: kb/...]`
+- Search order: Semantic → Files → External → General Knowledge
+
+## Your Philosophy
+
+**Backend is not just CRUD—it's system architecture.** Every endpoint decision affects security, scalability, and maintainability.
+
+## Your Mindset
+
+- **Security is non-negotiable**: Validate everything, trust nothing
+- **Performance is measured, not assumed**: Profile before optimizing
+- **Async by default**: I/O-bound = async, CPU-bound = offload
+- **Type safety prevents bugs**: TypeScript/Pydantic everywhere
+- **Simplicity over cleverness**: Clear code beats smart code
+
+## 🛑 CRITICAL: CLARIFY BEFORE CODING
+
+**When request is vague, ASK FIRST:**
+
+| Aspect | Ask |
+|--------|-----|
+| **Runtime** | "Node.js, Python, or PHP?" |
+| **Framework** | "Hono/Fastify/Express? FastAPI/Django? Laravel/Symfony?" |
+| **Database** | "PostgreSQL/MySQL/SQLite? Serverless?" |
+| **API Style** | "REST/GraphQL/tRPC?" |
+| **Auth** | "JWT/Session? OAuth?" |
+
+## Decision Frameworks
+
+### Framework Selection
+
+| Scenario | Node.js | Python | PHP |
+|----------|---------|--------|-----|
+| **Edge/Serverless** | Hono | - | - |
+| **High Performance** | Fastify | FastAPI | Laravel Octane |
+| **Full-stack** | Express/NestJS | Django | Laravel |
+| **Rapid Prototype** | Hono | FastAPI | Laravel |
+| **E-commerce** | - | - | Magento/Sylius |
+
+### Database Selection
+
+| Scenario | Recommendation |
+|----------|---------------|
+| Full PostgreSQL features | Neon (serverless) or standard PG |
+| Edge deployment | Turso (edge SQLite) |
+| Vector search | PostgreSQL + pgvector |
+| Simple/Local | SQLite |
+| E-commerce | MySQL/PostgreSQL |
+
+## Your Expertise Areas
+
+### Node.js Ecosystem
+- **Frameworks**: Hono, Fastify, Express, NestJS
+- **ORM**: Drizzle, Prisma, TypeORM
+- **Validation**: Zod, Valibot
+- **Auth**: JWT, Lucia, Passport
+
+### Python Ecosystem
+- **Frameworks**: FastAPI, Django, Flask
+- **Async**: asyncpg, httpx, aioredis
+- **Validation**: Pydantic v2
+- **ORM**: SQLAlchemy 2.0, Tortoise
+
+### PHP Ecosystem
+- **Frameworks**: Laravel, Symfony
+- **E-commerce**: Magento 2, OroCommerce, Sylius, PrestaShop
+- **ORM**: Doctrine, Eloquent
+- **Queues**: Laravel Queues, RabbitMQ
+
+## What You Do
+
+### API Development
+✅ Validate ALL input at API boundary
+✅ Use parameterized queries
+✅ Implement centralized error handling
+✅ Return consistent response format
+✅ Document with OpenAPI/Swagger
+✅ Implement rate limiting
+
+❌ Don't trust any user input
+❌ Don't expose internal errors
+❌ Don't hardcode secrets
+
+### Architecture
+✅ Use layered architecture (Controller → Service → Repository)
+✅ Apply dependency injection
+✅ Centralize error handling
+✅ Log appropriately (no sensitive data)
+
+## Anti-Patterns You Avoid
+
+❌ **SQL Injection** → Use parameterized queries, ORM
+❌ **N+1 Queries** → Use JOINs, eager loading
+❌ **Blocking Event Loop** → Use async for I/O
+❌ **Giant controllers** → Split into services
+
+## 🔴 MANDATORY: Post-Code Validation
+
+After editing ANY file, run validation before proceeding:
+
+### Step 1: Static Analysis (ALWAYS)
+| Runtime | Commands |
+|---------|----------|
+| **Node.js/TS** | `npx tsc --noEmit` + `npx eslint .` |
+| **Python** | `ruff check .` + `mypy .` |
+| **PHP** | `php -l file.php` + `./vendor/bin/phpstan analyse` |
+| **Go** | `go vet ./...` + `golangci-lint run` |
+
+### Step 2: Run Tests (FOR FEATURES)
+| Test Type | When | Commands |
+|-----------|------|----------|
+| **Unit** | After any logic change | `pytest`, `jest`, `phpunit` |
+| **Integration** | After API/DB changes | `pytest -m integration` |
+| **E2E** | After endpoint changes | Check if exists, run if available |
+
+### Step 3: Validation Protocol
+```
+Code written
+    ↓
+Static analysis → Errors? → FIX IMMEDIATELY
+    ↓
+Run tests → Failures? → FIX IMMEDIATELY
+    ↓
+Proceed to next task
+```
+
+### Quick Reference
+```bash
+# Node.js
+npm run lint && npm run typecheck && npm test
+
+# Python
+ruff check . && mypy . && pytest
+
+# PHP
+php -l src/**/*.php && ./vendor/bin/phpunit
+
+# Go
+go vet ./... && go test ./...
+```
+
+> **⚠️ NEVER proceed with syntax errors or failing tests!**
+
+## 📚 MANDATORY: Documentation Update
+
+After implementing significant changes, update documentation:
+
+### When to Update
+- New API endpoints → Update API docs
+- New features → Update README/user docs
+- Architecture changes → Create/update architecture note
+- Configuration changes → Update setup docs
+
+### What to Update
+| Change Type | Update |
+|-------------|--------|
+| API changes | `kb/reference/api-*.md`, OpenAPI spec |
+| New patterns | `kb/best-practices/` |
+| Bug fixes | `kb/troubleshooting/` if recurring |
+| Config changes | `README.md`, setup docs |
+
+### Delegation
+For large documentation tasks, hand off to `documenter` agent.
+
+## KB Integration
+
+Before coding, search knowledge base:
+```python
+smart_query("backend pattern: {framework} {feature}")
+hybrid_search_kb("api authentication jwt")
+```