@devran-ai/kit 4.1.0

package/.agent/CheatSheet.md

@@ -0,0 +1,350 @@
+# Devran AI Kit — CheatSheet
+
+> **Version**: v4.1.0 | **Quick Reference** for all capabilities
+> **Session**: Start with `/status`, end with session-end checklist
+
+---
+
+## 🚀 Session Lifecycle
+
+### Start a Session
+
+1. Run `/status` to load context
+2. Review sprint state from `docs/ROADMAP.md`
+3. Verify Git state and dependencies
+4. Confirm direction with user
+
+### End a Session
+
+1. Update `docs/ROADMAP.md` with completed/in-progress items
+2. Sync `docs/CHANGELOG.md` with shipped work
+3. Update `.agent/session-context.md` with handoff notes
+4. Update `.agent/session-state.json`
+5. Commit all tracking files
+6. Push (triggers LOCAL-CI-GATE)
+
+---
+
+## 📋 Commands (37)
+
+### Core Workflow
+
+| Command | Description |
+|:--------|:------------|
+| `/plan` | Create implementation plan |
+| `/implement` | Execute the approved plan |
+| `/verify` | Run all quality gates |
+| `/status` | Check project status |
+
+### Development
+
+| Command | Description |
+|:--------|:------------|
+| `/build` | Build a new feature from scratch |
+| `/fix` | Fix linting, type, or build errors |
+| `/debug` | Systematic debugging process |
+| `/refactor` | Improve code quality |
+| `/cook` | Full scratch-to-done workflow |
+
+### Documentation & Git
+
+| Command | Description |
+|:--------|:------------|
+| `/doc` | Generate documentation |
+| `/adr` | Create Architecture Decision Record |
+| `/changelog` | Generate changelog from commits |
+| `/git` | Git operations with best practices |
+| `/pr` | Create production-grade pull requests |
+
+### PR Toolkit
+
+| Command | Description |
+|:--------|:------------|
+| `/pr-review` | Review a PR with senior engineering expertise |
+| `/pr-fix` | Fix PR issues based on review comments |
+| `/pr-merge` | Merge PR safely with dependency validation |
+| `/pr-split` | Split oversized PRs into focused sub-PRs |
+| `/pr-status` | Triage PRs with CI, staleness, and merge readiness |
+| `/pr-describe` | Auto-generate PR title, summary, and labels |
+
+### Exploration & Research
+
+| Command | Description |
+|:--------|:------------|
+| `/scout` | Explore and understand codebase |
+| `/research` | Research technologies or solutions |
+| `/ask` | Ask questions about code |
+
+### Quality & Security
+
+| Command | Description |
+|:--------|:------------|
+| `/code-review` | Run code review |
+| `/tdd` | Test-driven development workflow |
+| `/security-scan` | Security audit and vulnerability scan |
+| `/perf` | Performance analysis and optimization |
+
+### Integration & Deployment
+
+| Command | Description |
+|:--------|:------------|
+| `/integrate` | Third-party service integration |
+| `/db` | Database schema and migrations |
+| `/deploy` | Deploy to target environment |
+| `/design` | UI/UX design specifications |
+
+### Context Management
+
+| Command | Description |
+|:--------|:------------|
+| `/learn` | Extract patterns from session |
+| `/checkpoint` | Save progress checkpoint |
+| `/compact` | Compress context for memory |
+| `/eval` | Evaluate metrics |
+| `/setup` | Configure project with kit |
+| `/help` | Show available commands |
+
+---
+
+## 🤖 Agents (23)
+
+### Core Development
+
+| Agent | Purpose |
+|:------|:--------|
+| 📋 Planner | Feature planning, risk assessment |
+| 🏛️ Architect | System design, ADR creation |
+| 🔍 Code Reviewer | Quality + security review |
+| 🧪 TDD Guide | Test-first enforcement |
+| 🔧 Build Error Resolver | Rapid build fixes |
+| 🎨 Frontend Specialist | React, Next.js, UI architecture |
+| ⚙️ Backend Specialist | Node.js, Python, API design |
+
+### Quality & Security
+
+| Agent | Purpose |
+|:------|:--------|
+| 🔐 Security Reviewer | Vulnerability analysis |
+| 🎭 E2E Runner | End-to-end testing |
+| ⚡ Performance Optimizer | Core Web Vitals optimization |
+
+### Infrastructure
+
+| Agent | Purpose |
+|:------|:--------|
+| 📱 Mobile Developer | React Native/Expo development |
+| 🗄️ Database Architect | Schema design, queries |
+| 🚀 DevOps Engineer | CI/CD, deployment |
+| 🛡️ Reliability Engineer | SRE, production readiness |
+
+### Maintenance & Discovery
+
+| Agent | Purpose |
+|:------|:--------|
+| 🧹 Refactor Cleaner | Dead code cleanup |
+| 📚 Doc Updater | Documentation sync |
+| 🧠 Knowledge Agent | RAG retrieval |
+| 🔭 Explorer Agent | Codebase discovery |
+| 📊 Sprint Orchestrator | Sprint planning & velocity |
+
+### PR & Code Review
+
+| Agent | Purpose |
+|:------|:--------|
+| 👀 PR Reviewer | PR review, branch strategy, code quality |
+
+### Language-Specific Reviewers
+
+| Agent | Purpose |
+|:------|:--------|
+| 📘 TypeScript Reviewer | Type safety & TS patterns |
+| 🐍 Python Reviewer | PEP 8 & Python best practices |
+| 🔷 Go Reviewer | Go idioms & concurrency |
+
+---
+
+## 🧩 Skills (34)
+
+### Operational (7)
+
+| Skill | Purpose |
+|:------|:--------|
+| verification-loop | Continuous quality gates |
+| continuous-learning | Pattern extraction (PAAL) |
+| strategic-compact | Context window management |
+| eval-harness | Performance evaluation |
+| context-budget | LLM token budget management |
+| plan-validation | Plan quality gate with scoring |
+| production-readiness | Preflight audit and readiness checks |
+
+### Orchestration (4)
+
+| Skill | Purpose |
+|:------|:--------|
+| intelligent-routing | Automatic agent selection |
+| parallel-agents | Multi-agent orchestration |
+| behavioral-modes | Adaptive AI operation modes |
+| mcp-integration | MCP server integration |
+
+### Domain — Architecture & Design (6)
+
+| Skill | Purpose |
+|:------|:--------|
+| architecture | System design patterns |
+| api-patterns | RESTful API design |
+| database-design | Schema optimization |
+| frontend-patterns | React/component patterns |
+| nodejs-patterns | Backend patterns |
+| i18n-localization | Internationalization |
+
+### Domain — Code Quality (4)
+
+| Skill | Purpose |
+|:------|:--------|
+| clean-code | Code quality principles |
+| typescript-expert | Advanced TypeScript |
+| testing-patterns | TDD, unit, integration |
+| debugging-strategies | Systematic debugging |
+
+### Domain — Operations (4)
+
+| Skill | Purpose |
+|:------|:--------|
+| docker-patterns | Containerization |
+| git-workflow | Branching, commits |
+| security-practices | OWASP, vulnerability prevention |
+| pr-toolkit | PR lifecycle, review, merge, split |
+
+### Development (9)
+
+| Skill | Purpose |
+|:------|:--------|
+| app-builder | Full-stack scaffolding |
+| mobile-design | Mobile UI/UX patterns |
+| webapp-testing | E2E and Playwright testing |
+| deployment-procedures | CI/CD and rollback strategies |
+| performance-profiling | Core Web Vitals optimization |
+| brainstorming | Socratic discovery protocol |
+| plan-writing | Structured task breakdown |
+| shell-conventions | PowerShell/Bash conventions |
+| ui-ux-pro-max | Premium UI/UX design system |
+
+---
+
+## 🔄 Workflows (21)
+
+| Workflow | Command | Phase |
+|:---------|:--------|:------|
+| brainstorm | `/brainstorm` | Discover |
+| quality-gate | `/quality-gate` | Discover |
+| plan | `/plan` | Plan |
+| create | `/create` | Build |
+| enhance | `/enhance` | Build |
+| preview | `/preview` | Build |
+| ui-ux-pro-max | `/ui-ux-pro-max` | Build |
+| pr-fix | `/pr-fix` | Build |
+| pr-split | `/pr-split` | Build |
+| test | `/test` | Verify |
+| review | `/review` | Verify |
+| preflight | `/preflight` | Verify |
+| pr-review | `/pr-review` | Verify |
+| pr | `/pr` | Ship |
+| pr-merge | `/pr-merge` | Ship |
+| deploy | `/deploy` | Ship |
+| debug | `/debug` | Reactive |
+| orchestrate | `/orchestrate` | Reactive |
+| retrospective | `/retrospective` | Evaluate |
+| status | `/status` | Cross-cutting |
+| upgrade | `/upgrade` | Maintenance |
+
+---
+
+## ✅ Checklists (4)
+
+| Checklist | When to Use |
+|:----------|:------------|
+| `session-start.md` | Beginning of every work session |
+| `session-end.md` | Before ending any work session |
+| `pre-commit.md` | Before every commit |
+| `task-complete.md` | After completing any task |
+
+---
+
+## ⚖️ Governance Rules (9)
+
+| Rule File | Scope |
+|:----------|:------|
+| `coding-style.md` | TypeScript + Python conventions |
+| `security.md` | Secrets, auth, data protection, AI safety |
+| `testing.md` | TDD, pytest, Jest/Vitest patterns |
+| `git-workflow.md` | Commits, branches, push policy |
+| `documentation.md` | Doc hierarchy, SSOT, preservation |
+| `sprint-tracking.md` | ROADMAP.md as SSOT, session protocols |
+| `quality-gate.md` | Pre-task validation and quality standards |
+| `architecture.md` | System design patterns and ADR governance |
+| `agent-upgrade-policy.md` | Framework upgrade preservation rules |
+
+---
+
+## 🎯 Common Scenarios
+
+### 1. Starting a New Feature
+
+```
+/status → /plan → /create → /test → /review → /pr → /deploy
+```
+
+### 2. Fixing a Bug
+
+```
+/status → /debug → /fix → /test → /review
+```
+
+### 3. UI/UX Design Work
+
+```
+/brainstorm → /quality-gate → /ui-ux-pro-max → /preview → /review
+```
+
+### 4. Code Quality Improvement
+
+```
+/status → /review → /refactor → /test → /verify
+```
+
+### 5. Sprint Planning
+
+```
+/status → /plan → /brainstorm → update ROADMAP.md
+```
+
+### 6. PR Lifecycle
+
+```
+/pr → /pr-review → /pr-fix → /pr-merge
+```
+
+---
+
+## 📁 Directory Structure
+
+```
+.agent/
+├── rules.md                 # Core governance & identity
+├── session-state.json       # Machine-readable state
+├── session-context.md       # Human-readable session context
+├── CheatSheet.md            # This file
+├── manifest.json            # Capability registry
+│
+├── agents/                  # 23 specialized agents
+├── commands/                # 37 slash commands
+├── skills/                  # 34 capability extensions
+├── workflows/               # 21 slash command workflows
+├── hooks/                   # Event-driven automation
+├── rules/                   # 9 modular governance rules
+├── contexts/                # Mode switching (brainstorm, debug, etc.)
+├── checklists/              # Session & pre-commit verification
+├── templates/               # Feature, ADR, bug-report templates
+├── decisions/               # Architecture Decision Records
+└── engine/                  # Runtime engine configs
+```

package/.agent/README.md

@@ -0,0 +1,76 @@
+# Devran AI Kit — .agent/ Directory
+
+> **Purpose**: Core agent architecture for AI-assisted development
+> **Quick Start**: Copy this folder to your project root
+
+---
+
+## 🚀 Session Initialization
+
+Every new AI session, run:
+
+```
+/status
+```
+
+This loads your session context and activates the orchestrator.
+
+---
+
+## 📁 Directory Structure
+
+```
+.agent/
+├── rules.md                # Core governance & identity
+├── session-state.json      # Machine-readable state
+│
+├── agents/                 # 23 specialized agents
+├── commands/               # 37 slash commands
+├── skills/                 # 34 capability extensions
+├── workflows/              # 21 slash command workflows
+├── hooks/                  # Event-driven automation
+├── rules/                  # Modular governance
+├── contexts/               # Mode switching
+├── checklists/             # Verification lists
+├── templates/              # Feature templates
+└── decisions/              # ADR system
+```
+
+---
+
+## ⚡ Quick Reference
+
+### Core Commands
+
+| Command        | Purpose                    |
+| :------------- | :------------------------- |
+| `/status`      | Current session status     |
+| `/plan`        | Create implementation plan |
+| `/tdd`         | Test-driven development    |
+| `/verify`      | Full verification loop     |
+| `/code-review` | Quality review             |
+
+### Session Files
+
+| File                 | Purpose                    |
+| :------------------- | :------------------------- |
+| `rules.md`           | Core identity & governance |
+| `session-state.json` | Machine-readable state     |
+
+---
+
+## ⚖️ Operating Constraints
+
+| Constraint              | Meaning                          |
+| :---------------------- | :------------------------------- |
+| Trust > Optimization    | User trust is never sacrificed   |
+| Safety > Growth         | Safety overrides business goals  |
+| Completion > Suggestion | Finish work before proposing new |
+
+---
+
+## 🔗 Documentation
+
+- [Full README](../README.md)
+- [Commands Reference](commands/README.md)
+- [Agents Reference](agents/README.md)

package/.agent/agents/README.md

@@ -0,0 +1,155 @@
+# Agents
+
+> **Purpose**: Specialized sub-agents for task delegation
+> **Count**: 23 Agents
+
+---
+
+## Overview
+
+Agents are specialized personas that handle delegated tasks with focused expertise. Each agent has:
+
+- **Defined responsibilities** — What it handles
+- **Specific tools** — What it can use
+- **Constraints** — What it cannot do
+
+---
+
+## Agent Roster
+
+### Core Development Agents
+
+| Agent                       | File                      | Purpose                         |
+| :-------------------------- | :------------------------ | :------------------------------ |
+| 📋 **Planner**              | `planner.md`              | Feature implementation planning |
+| 🏛️ **Architect**            | `architect.md`            | System design decisions         |
+| 🔍 **Code Reviewer**        | `code-reviewer.md`        | Quality & security review       |
+| 🧪 **TDD Guide**            | `tdd-guide.md`            | Test-driven development         |
+| 🔧 **Build Error Resolver** | `build-error-resolver.md` | Rapid build fixes               |
+| 🖥️ **Backend Specialist**   | `backend-specialist.md`   | Node.js, NestJS, API design     |
+| 🎨 **Frontend Specialist**  | `frontend-specialist.md`  | React, Next.js, UI architecture |
+
+### Quality & Security Agents
+
+| Agent                        | File                       | Purpose                      |
+| :--------------------------- | :------------------------- | :--------------------------- |
+| 🔐 **Security Reviewer**     | `security-reviewer.md`     | Vulnerability analysis       |
+| 🎭 **E2E Runner**            | `e2e-runner.md`            | End-to-end testing           |
+| ⚡ **Performance Optimizer** | `performance-optimizer.md` | Core Web Vitals optimization |
+
+### Infrastructure Agents
+
+| Agent                        | File                       | Purpose                       |
+| :--------------------------- | :------------------------- | :---------------------------- |
+| 📱 **Mobile Developer**      | `mobile-developer.md`      | React Native/Expo development |
+| 🗄️ **Database Architect**    | `database-architect.md`    | Schema design, queries        |
+| 🚀 **DevOps Engineer**       | `devops-engineer.md`       | CI/CD, deployment             |
+| 🛡️ **Reliability Engineer**  | `reliability-engineer.md`  | SRE, production readiness     |
+
+### Maintenance & Discovery Agents
+
+| Agent                      | File                     | Purpose                     |
+| :------------------------- | :----------------------- | :-------------------------- |
+| 🧹 **Refactor Cleaner**    | `refactor-cleaner.md`    | Dead code cleanup           |
+| 📚 **Doc Updater**         | `doc-updater.md`         | Documentation sync          |
+| 🧠 **Knowledge Agent**     | `knowledge-agent.md`     | RAG retrieval               |
+| 🔭 **Explorer Agent**      | `explorer-agent.md`      | Codebase discovery          |
+| 📊 **Sprint Orchestrator** | `sprint-orchestrator.md` | Sprint planning & velocity  |
+
+### PR & Code Review Agents
+
+| Agent                      | File                     | Purpose                     |
+| :------------------------- | :----------------------- | :-------------------------- |
+| 👀 **PR Reviewer**         | `pr-reviewer.md`         | PR review, branch strategy, code quality |
+
+### Language-Specific Reviewers
+
+| Agent                          | File                        | Purpose                     |
+| :----------------------------- | :-------------------------- | :-------------------------- |
+| 📘 **TypeScript Reviewer**    | `typescript-reviewer.md`    | Type safety & TS patterns   |
+| 🐍 **Python Reviewer**        | `python-reviewer.md`        | PEP 8 & Python best practices |
+| 🔷 **Go Reviewer**            | `go-reviewer.md`            | Go idioms & concurrency     |
+
+---
+
+## Agent Selection Matrix
+
+The `intelligent-routing` skill automatically selects agents based on request keywords:
+
+| Intent       | Keywords                            | Agent(s)                  |
+| ------------ | ----------------------------------- | ------------------------- |
+| Architecture | "design", "structure", "pattern"    | `architect`               |
+| Planning     | "plan", "roadmap", "sprint"         | `planner`                 |
+| Security     | "security", "vulnerability", "auth" | `security-reviewer`       |
+| Testing      | "test", "coverage", "e2e"           | `tdd-guide`, `e2e-runner` |
+| Mobile       | "mobile", "react native", "expo"    | `mobile-developer`        |
+| Database     | "schema", "migration", "query"      | `database-architect`      |
+| Deployment   | "deploy", "CI/CD", "production"     | `devops-engineer`         |
+| Performance  | "slow", "optimize", "performance"   | `performance-optimizer`   |
+| Discovery    | "explore", "map", "understand"      | `explorer-agent`          |
+| Frontend     | "frontend", "react", "css", "ui"    | `frontend-specialist`     |
+| Backend      | "backend", "api", "server", "node"  | `backend-specialist`      |
+| Sprint       | "sprint", "velocity", "backlog"     | `sprint-orchestrator`     |
+| Reliability  | "SRE", "incident", "production"     | `reliability-engineer`    |
+| PR Review    | "PR", "pull request", "review PR"   | `pr-reviewer`             |
+| TypeScript | "typescript", ".ts", "type"   | `typescript-reviewer` |
+| Python     | "python", "django", "flask"   | `python-reviewer`     |
+| Go         | "golang", "goroutine", "go"   | `go-reviewer`         |
+
+---
+
+## How to Use Agents
+
+Agents are invoked automatically by the orchestrator based on context. You can also explicitly request them:
+
+```
+Use the architect agent to design the database schema.
+```
+
+```
+Delegate this security review to the security-reviewer agent.
+```
+
+---
+
+## Agent Specification Format
+
+Each agent file follows this structure:
+
+```markdown
+# [Agent Name]
+
+> **Platform**: Devran AI Kit
+> **Purpose**: [Brief description]
+
+---
+
+## Identity
+
+[Agent persona and core responsibility]
+
+## Capabilities
+
+- [What the agent can do]
+
+## Constraints
+
+- [What the agent cannot do]
+
+## Workflow
+
+1. [Step 1]
+2. [Step 2]
+```
+
+---
+
+## Extending Agents
+
+To add a custom agent:
+
+1. Create a new `.md` file in this directory
+2. Follow the specification format above
+3. Reference it in your workflows
+
+Custom agents inherit the Operating Constraints from `rules.md`.