@devran-ai/kit 4.1.0

package/.agent/skills/api-patterns/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: api-patterns
+description: RESTful API design patterns and best practices
+triggers: [context, api, backend, endpoint]
+---
+
+# API Patterns Skill
+
+> **Purpose**: Apply professional RESTful API design principles
+
+---
+
+## Overview
+
+This skill provides guidance for designing clean, consistent, and scalable APIs following industry best practices.
+
+---
+
+## Core Principles
+
+### 1. Resource-Oriented Design
+
+- Use **nouns** for resources: `/users`, `/orders`, `/products`
+- Use HTTP verbs for actions: GET, POST, PUT, PATCH, DELETE
+- Avoid verbs in URLs: ❌ `/getUsers` → ✅ `/users`
+
+### 2. Consistent Naming
+
+```
+GET    /api/v1/users          # List users
+POST   /api/v1/users          # Create user
+GET    /api/v1/users/:id      # Get user
+PATCH  /api/v1/users/:id      # Update user
+DELETE /api/v1/users/:id      # Delete user
+```
+
+### 3. Versioning
+
+- Use URL versioning: `/api/v1/`, `/api/v2/`
+- Or header versioning: `Accept: application/vnd.api+json;version=1`
+
+---
+
+## Response Structure
+
+### Success Response
+
+```json
+{
+  "data": { ... },
+  "meta": {
+    "timestamp": "2026-02-06T00:00:00Z",
+    "requestId": "uuid"
+  }
+}
+```
+
+### Error Response
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Email is required",
+    "details": [{ "field": "email", "issue": "required" }]
+  }
+}
+```
+
+---
+
+## Status Codes
+
+| Code | Usage                 |
+| :--- | :-------------------- |
+| 200  | Success               |
+| 201  | Created               |
+| 204  | No Content (delete)   |
+| 400  | Bad Request           |
+| 401  | Unauthorized          |
+| 403  | Forbidden             |
+| 404  | Not Found             |
+| 409  | Conflict              |
+| 422  | Unprocessable Entity  |
+| 500  | Internal Server Error |
+
+---
+
+## Pagination
+
+```json
+{
+  "data": [...],
+  "pagination": {
+    "page": 1,
+    "limit": 20,
+    "total": 100,
+    "totalPages": 5
+  }
+}
+```
+
+---
+
+## Quick Reference
+
+| Pattern | Example                      |
+| :------ | :--------------------------- |
+| List    | `GET /users`                 |
+| Create  | `POST /users`                |
+| Get     | `GET /users/123`             |
+| Update  | `PATCH /users/123`           |
+| Delete  | `DELETE /users/123`          |
+| Nested  | `GET /users/123/orders`      |
+| Filter  | `GET /users?status=active`   |
+| Search  | `GET /users?q=john`          |
+| Sort    | `GET /users?sort=-createdAt` |

package/.agent/skills/app-builder/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: app-builder
+description: Application scaffolding orchestrator. Creates full-stack applications from requirements, selects tech stack, coordinates agents.
+version: 1.0.0
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent
+---
+
+# App Builder — Application Building Orchestrator
+
+> Analyzes requirements, determines tech stack, plans structure, and coordinates agents.
+
+---
+
+## 🎯 Process Overview
+
+```
+User Request → Analyze → Select Stack → Plan → Scaffold → Coordinate → Verify
+```
+
+---
+
+## 📦 Recommended Default Stack
+
+| Layer            | Technology                    | Alternative |
+| ---------------- | ----------------------------- | ----------- |
+| **Web Frontend** | Next.js 14+                   | Nuxt 3      |
+| **Mobile**       | Expo (React Native)           | Flutter     |
+| **Backend**      | NestJS                        | FastAPI     |
+| **Database**     | PostgreSQL + Prisma           | Supabase    |
+| **Auth**         | NextAuth / Firebase Auth      | Clerk       |
+| **Hosting**      | Vercel                        | Firebase    |
+| **Storage**      | Cloudinary / Firebase Storage | S3          |
+
+---
+
+## 🔗 Agent Coordination
+
+| Agent               | Role                         | When to Invoke               |
+| ------------------- | ---------------------------- | ---------------------------- |
+| `planner`           | Task breakdown, dependencies | Starting any project         |
+| `architect`         | System design, patterns      | Architecture decisions       |
+| `code-reviewer`     | Quality, patterns            | After implementation         |
+| `security-reviewer` | Security posture             | Auth, payment features       |
+| `tdd-guide`         | Test specifications          | Before/during implementation |
+
+---
+
+## 📋 Project Type Detection
+
+| Keywords                          | Project Type      | Default Stack           |
+| --------------------------------- | ----------------- | ----------------------- |
+| "web app", "website", "dashboard" | Web Application   | Next.js + Prisma        |
+| "mobile app", "iOS", "Android"    | Mobile App        | Expo + NestJS API       |
+| "API", "backend", "server"        | API Service       | NestJS + Prisma         |
+| "landing page", "marketing"       | Static Site       | Next.js (static export) |
+| "CLI", "command line"             | CLI Tool          | Node.js + Commander     |
+| "extension", "plugin"             | Browser Extension | Chrome MV3              |
+
+---
+
+## 🏗️ Scaffolding Process
+
+### Step 1: Clarify Requirements
+
+```markdown
+Before scaffolding, confirm:
+
+1. Project type (web/mobile/API/etc.)
+2. Core features (3-5 max for MVP)
+3. Auth requirements (none/social/email)
+4. Database needs (none/simple/complex)
+```
+
+### Step 2: Create Plan
+
+```markdown
+## Project Plan: [Name]
+
+### Core Features
+
+1. [Feature 1]
+2. [Feature 2]
+3. [Feature 3]
+
+### Tech Stack
+
+- Frontend: [choice]
+- Backend: [choice]
+- Database: [choice]
+
+### File Structure
+
+[directory tree]
+
+### Implementation Order
+
+1. Setup & configuration
+2. Database schema
+3. API endpoints
+4. Frontend pages
+5. Authentication
+6. Testing
+```
+
+### Step 3: Scaffold
+
+```bash
+# Example: Next.js project
+npx create-next-app@latest ./project-name \
+  --typescript \
+  --eslint \
+  --tailwind \
+  --app \
+  --src-dir
+```
+
+### Step 4: Coordinate Agents
+
+```
+1. Invoke planner → Task breakdown
+2. Invoke architect → Design decisions
+3. Execute tasks sequentially
+4. Invoke tdd-guide → Add tests
+5. Invoke code-reviewer → Final review
+```
+
+---
+
+## 📁 Standard Directory Structures
+
+### Next.js Full-Stack
+
+```
+src/
+├── app/              # Pages & routes
+│   ├── api/          # API routes
+│   └── (auth)/       # Auth pages
+├── components/       # React components
+├── lib/              # Utilities
+├── server/           # Server-side logic
+│   ├── db/           # Prisma client
+│   └── services/     # Business logic
+└── types/            # TypeScript types
+```
+
+### NestJS API
+
+```
+src/
+├── modules/          # Feature modules
+│   ├── auth/
+│   ├── users/
+│   └── [feature]/
+├── common/           # Shared utilities
+│   ├── decorators/
+│   ├── guards/
+│   └── interceptors/
+└── config/           # Configuration
+```
+
+### Expo Mobile
+
+```
+src/
+├── app/              # Expo Router screens
+├── components/       # UI components
+├── hooks/            # Custom hooks
+├── services/         # API clients
+├── stores/           # Zustand stores
+└── utils/            # Helpers
+```
+
+---
+
+## ✅ Post-Scaffold Checklist
+
+- [ ] Dependencies installed
+- [ ] Environment variables documented
+- [ ] README updated
+- [ ] Git initialized
+- [ ] Basic tests passing
+- [ ] Development server runs
+
+---
+
+## Usage Example
+
+```
+User: "Create a task management app with user auth"
+
+App Builder Process:
+1. Project type: Web Application
+2. Tech stack: Next.js + Prisma + NextAuth
+3. Create plan:
+   ├─ Database schema (users, tasks, lists)
+   ├─ API routes (CRUD for tasks)
+   ├─ Pages (dashboard, tasks, settings)
+   └─ Components (TaskCard, TaskList, etc.)
+4. Scaffold project
+5. Coordinate agents for implementation
+6. Run verification loop
+```

package/.agent/skills/architecture/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: architecture
+description: "System design patterns, DDD, 12-Factor App, SOLID principles, event-driven architecture, and architectural decision frameworks"
+triggers: [context, architecture, design, system]
+---
+
+# Architecture Skill
+
+> **Purpose**: Apply proven architectural patterns for scalable, maintainable systems
+
+---
+
+## Architectural Patterns — When to Use
+
+| Pattern | When to Use |
+|:--------|:-----------|
+| Layered | Simple apps with clear separation; each layer imports only from below |
+| Clean Architecture | Complex domains; dependency rule: source code deps always point inward |
+| Hexagonal (Ports & Adapters) | Testable domain cores; domain defines ports, adapters implement them |
+| Monolith | MVP, small team, simple domain |
+| Modular Monolith | Growing team, clear bounded contexts, not ready for distributed |
+| Microservices | Large team, independent scaling, domain maturity |
+| Serverless | Variable load, cost optimization, simple functions |
+
+---
+
+## Domain-Driven Design (DDD)
+
+### Strategic DDD
+
+- **Bounded Context**: Boundary where a domain model is consistent ("Order" differs in Sales vs Shipping)
+- **Ubiquitous Language**: Shared vocabulary within a bounded context
+- **Context Map**: Visual map of relationships between contexts
+- **Anti-Corruption Layer**: Translation layer between contexts with different models
+
+### Tactical DDD Building Blocks
+
+| Block | Purpose | Key Rule |
+|:------|:--------|:---------|
+| Entity | Object with identity over time | Has unique ID, mutable state |
+| Value Object | Immutable, defined by attributes | No ID, compared by value |
+| Aggregate | Cluster with root enforcing invariants | External access through root only |
+| Repository | Interface for aggregate persistence | One per aggregate |
+| Domain Service | Stateless logic spanning aggregates | When logic doesn't belong to one entity |
+| Domain Event | Record of something that happened | Immutable, past tense (OrderPlaced) |
+| Factory | Complex creation logic | Encapsulates invariant enforcement |
+
+### Aggregate Design Rules
+
+1. Protect invariants within aggregate boundaries
+2. Reference other aggregates by ID only
+3. One transaction per aggregate
+4. Design small aggregates
+5. Eventual consistency between aggregates via domain events
+
+---
+
+## 12-Factor App
+
+Apply all 12 factors (codebase in VCS, explicit deps, config in env, backing services as resources, separate build/release/run, stateless processes, port binding, process-model concurrency, fast startup + graceful shutdown, dev/prod parity, logs as event streams, admin tasks as one-off processes). Reference the 12-Factor methodology for implementation details.
+
+---
+
+## Event-Driven Architecture — Pattern Selection
+
+| Pattern | Use When | Consistency |
+|:--------|:---------|:-----------|
+| Request/Response | Synchronous, simple ops | Strong |
+| Event Notification | Inform services something happened | Eventual |
+| Event-Carried State Transfer | Share data without coupling | Eventual |
+| Event Sourcing | Full audit trail, state reconstruction | Strong (per aggregate) |
+| CQRS | Different read/write models needed | Eventual (between models) |
+
+**Event design**: Events are immutable facts (past tense), carry sufficient data, have versioned schemas, ordered within aggregate.
+
+---
+
+## Design Principles
+
+Apply SOLID principles: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion. Also DRY (but avoid premature abstraction), KISS, YAGNI.
+
+---
+
+## Module Structure (DDD-Aligned)
+
+```
+src/
+├── domain/           # Core business logic (no framework imports)
+│   ├── entities/     # value-objects/ events/ services/ repositories/ (ports)
+├── application/      # Use cases: commands/ queries/ handlers/
+├── infrastructure/   # Adapters: database/ messaging/ external-apis/ config/
+└── interfaces/       # Entry points: http/ events/ cli/
+```
+
+---
+
+## Architecture Decision Records (ADRs)
+
+Write when choosing between approaches, technologies, patterns, or making trade-offs.
+
+Template: Status (Proposed/Accepted/Deprecated/Superseded) → Date → Context → Decision → Consequences → Alternatives Considered.

package/.agent/skills/behavioral-modes/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: behavioral-modes
+description: AI operational modes (brainstorm, implement, debug, review, teach, ship). Adapts behavior based on task type for Trust-Grade execution.
+version: 1.0.0
+allowed-tools: Read, Glob, Grep
+---
+
+# Behavioral Modes — Adaptive AI Operating Modes
+
+> **Purpose**: Define distinct behavioral modes that optimize AI performance for specific tasks while maintaining Trust-Grade governance.
+
+---
+
+## Available Modes
+
+### 1. 🧠 BRAINSTORM Mode
+
+**When to use:** Early project planning, feature ideation, architecture decisions
+
+**Behavior:**
+
+- Ask clarifying questions before assumptions
+- Offer multiple alternatives (at least 3)
+- Think divergently - explore unconventional solutions
+- No code yet - focus on ideas and options
+- Use visual diagrams (mermaid) to explain concepts
+- Apply Socratic questioning patterns
+
+**Output style:**
+
+```
+"Let's explore this together. Here are some approaches:
+
+Option A: [description]
+  ✅ Pros: ...
+  ❌ Cons: ...
+
+Option B: [description]
+  ✅ Pros: ...
+  ❌ Cons: ...
+
+What resonates with you? Or should we explore a different direction?"
+```
+
+---
+
+### 2. ⚡ IMPLEMENT Mode
+
+**When to use:** Writing code, building features, executing plans
+
+**Behavior:**
+
+- **CRITICAL: Use `clean-code` skill standards**
+- Fast execution - minimize questions
+- Use established patterns and best practices
+- Write complete, production-ready code
+- Include error handling and edge cases
+- **NO tutorial-style explanations** - just code
+- **NO unnecessary comments** - let code self-document
+- **Quality > Speed** - Read ALL references before coding
+
+**Output style:**
+
+```
+[Code block]
+
+[Brief summary, max 1-2 sentences]
+```
+
+---
+
+### 3. 🔍 DEBUG Mode
+
+**When to use:** Fixing bugs, troubleshooting errors, investigating issues
+
+**Behavior:**
+
+- Ask for error messages and reproduction steps
+- Think systematically - check logs, trace data flow
+- Form hypothesis → test → verify
+- Explain the root cause, not just the fix
+- Prevent future occurrences
+- Apply systematic-debugging skill
+
+**Output style:**
+
+```
+"Investigating...
+
+🔍 Symptom: [what's happening]
+🎯 Root cause: [why it's happening]
+✅ Fix: [the solution]
+🛡️ Prevention: [how to avoid in future]
+```
+
+---
+
+### 4. 📋 REVIEW Mode
+
+**When to use:** Code review, architecture review, security audit
+
+**Behavior:**
+
+- Be thorough but constructive
+- Categorize by severity (Critical/High/Medium/Low)
+- Explain the "why" behind suggestions
+- Offer improved code examples
+- Acknowledge what's done well
+
+**Output style:**
+
+```markdown
+## Code Review: [file/feature]
+
+### 🔴 Critical
+
+- [issue with explanation]
+
+### 🟠 Improvements
+
+- [suggestion with example]
+
+### 🟢 Good
+
+- [positive observation]
+```
+
+---
+
+### 5. 📚 TEACH Mode
+
+**When to use:** Explaining concepts, documentation, onboarding
+
+**Behavior:**
+
+- Explain from fundamentals
+- Use analogies and examples
+- Progress from simple to complex
+- Include practical exercises
+- Check understanding
+
+**Output style:**
+
+```markdown
+## Understanding [Concept]
+
+### What is it?
+
+[Simple explanation with analogy]
+
+### How it works
+
+[Technical explanation with diagram]
+
+### Example
+
+[Code example with comments]
+
+### Try it yourself
+
+[Exercise or task]
+```
+
+---
+
+### 6. 🚀 SHIP Mode
+
+**When to use:** Production deployment, final polish, release preparation
+
+**Behavior:**
+
+- Focus on stability over features
+- Check for missing error handling
+- Verify environment configs
+- Run all tests
+- Create deployment checklist
+- Apply verification-loop skill
+
+**Output style:**
+
+```markdown
+## Pre-Ship Checklist
+
+### ✅ Code Quality
+
+- [ ] No TypeScript errors
+- [ ] ESLint passing
+- [ ] All tests passing
+
+### ✅ Security
+
+- [ ] No exposed secrets
+- [ ] Input validation complete
+
+### ✅ Performance
+
+- [ ] Bundle size acceptable
+- [ ] No console.logs
+
+### 🚀 Ready to deploy
+```
+
+---
+
+## Mode Detection
+
+The AI should automatically detect the appropriate mode based on:
+
+| Trigger                                   | Mode       |
+| ----------------------------------------- | ---------- |
+| "what if", "ideas", "options", "explore"  | BRAINSTORM |
+| "build", "create", "add", "implement"     | IMPLEMENT  |
+| "not working", "error", "bug", "fix"      | DEBUG      |
+| "review", "check", "audit", "assess"      | REVIEW     |
+| "explain", "how does", "learn", "teach"   | TEACH      |
+| "deploy", "release", "production", "ship" | SHIP       |
+
+---
+
+## Multi-Agent Collaboration Patterns
+
+### 1. 🔭 EXPLORE Mode
+
+**When to use:** Codebase discovery, dependency mapping
+
+**Behavior:**
+
+- Map file structure systematically
+- Identify patterns and conventions
+- Document findings for future reference
+- No modifications - read-only analysis
+
+### 2. 🗺️ PLAN-EXECUTE-CRITIC (PEC)
+
+**When to use:** Complex multi-step tasks
+
+**Flow:**
+
+1. **Plan**: Break down into atomic steps
+2. **Execute**: Implement one step at a time
+3. **Critic**: Verify each step before proceeding
+
+### 3. 🧠 MENTAL MODEL SYNC
+
+**When to use:** Aligning understanding with user
+
+**Behavior:**
+
+- State current understanding explicitly
+- Ask for confirmation or correction
+- Update model based on feedback
+- Document in session state
+
+---
+
+## Combining Modes
+
+Modes can transition during a task:
+
+```
+BRAINSTORM → IMPLEMENT → DEBUG → REVIEW → SHIP
+```
+
+Each transition should be announced:
+
+```
+"Switching to IMPLEMENT mode to build the solution we discussed."
+```
+
+---
+
+## Manual Mode Switching
+
+Users can explicitly request a mode:
+
+```
+"Switch to DEBUG mode"
+"Use BRAINSTORM mode for this"
+"Let's REVIEW the code"
+```
+
+---
+
+## Trust-Grade Integration
+
+Each mode inherits Trust-Grade governance:
+
+| Mode       | Governance Focus                               |
+| ---------- | ---------------------------------------------- |
+| BRAINSTORM | Load governance rules, consider constraints     |
+| IMPLEMENT  | Apply clean-code, follow architecture patterns |
+| DEBUG      | Use systematic-debugging, document root causes |
+| REVIEW     | Apply security standards, check compliance     |
+| TEACH      | Reference official docs, maintain accuracy     |
+| SHIP       | Run verification-loop, update documentation    |