@devran-ai/kit 4.1.0

package/.agent/skills/i18n-localization/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: i18n-localization
+description: Internationalization and localization patterns for multi-language applications
+triggers:
+  [
+    i18n,
+    internationalization,
+    localization,
+    l10n,
+    translation,
+    multi-language,
+    locale,
+    rtl,
+  ]
+---
+
+# Internationalization & Localization
+
+## Overview
+
+This skill provides patterns and best practices for building multi-language applications with proper internationalization (i18n) and localization (l10n) support.
+
+## Core Principles
+
+1. **Separate content from code**: All user-facing strings must be externalized
+2. **Use ICU message format**: Support plurals, gender, and context
+3. **Plan for RTL**: Layout should adapt to right-to-left languages
+4. **Locale-aware formatting**: Dates, numbers, currencies must respect locale
+5. **Fallback strategy**: Always have a default language fallback chain
+
+## Recommended Libraries
+
+### React / Next.js
+
+| Library                     | Use Case                              |
+| --------------------------- | ------------------------------------- |
+| `next-intl`                 | Next.js App Router (recommended)      |
+| `react-intl` / `formatjs`   | React apps with ICU support           |
+| `i18next` + `react-i18next` | Feature-rich, plugin ecosystem        |
+| `lingui`                    | Compile-time extraction, small bundle |
+
+### React Native / Expo
+
+| Library                     | Use Case                      |
+| --------------------------- | ----------------------------- |
+| `i18next` + `react-i18next` | Cross-platform (web + native) |
+| `expo-localization`         | Device locale detection       |
+| `react-native-localize`     | Native locale detection       |
+
+### Backend (Node.js)
+
+| Library         | Use Case                 |
+| --------------- | ------------------------ |
+| `i18next`       | Server-side translations |
+| `messageformat` | ICU message compilation  |
+| `globalize`     | CLDR-based formatting    |
+
+## File Structure
+
+```
+src/
+├── locales/
+│   ├── en/
+│   │   ├── common.json       # Shared translations
+│   │   ├── auth.json          # Auth-related strings
+│   │   ├── dashboard.json     # Dashboard strings
+│   │   └── errors.json        # Error messages
+│   ├── tr/
+│   │   ├── common.json
+│   │   ├── auth.json
+│   │   ├── dashboard.json
+│   │   └── errors.json
+│   └── de/
+│       └── ...
+├── i18n/
+│   ├── config.ts              # i18n configuration
+│   ├── types.ts               # Type-safe key definitions
+│   └── middleware.ts          # Locale detection middleware
+```
+
+## Translation Key Naming Convention
+
+```json
+{
+  "namespace.component.element": "Translation",
+
+  "auth.login.title": "Sign In",
+  "auth.login.emailLabel": "Email Address",
+  "auth.login.passwordLabel": "Password",
+  "auth.login.submitButton": "Sign In",
+  "auth.login.forgotPassword": "Forgot your password?",
+
+  "errors.validation.required": "{field} is required",
+  "errors.validation.minLength": "{field} must be at least {min} characters",
+  "errors.network.timeout": "Request timed out. Please try again."
+}
+```
+
+## Key Patterns
+
+### 1. Type-Safe Translations (TypeScript)
+
+```typescript
+// types.ts — Generate from default locale JSON
+type TranslationKeys = keyof typeof import('./locales/en/common.json');
+
+// Usage with next-intl
+import { useTranslations } from 'next-intl';
+
+function LoginForm() {
+  const t = useTranslations('auth.login');
+  return <h1>{t('title')}</h1>; // Type-checked!
+}
+```
+
+### 2. Pluralization (ICU Format)
+
+```json
+{
+  "notifications.count": "{count, plural, =0 {No notifications} one {# notification} other {# notifications}}"
+}
+```
+
+### 3. Date/Number Formatting
+
+```typescript
+// Always use Intl API or library formatters
+const formatted = new Intl.DateTimeFormat(locale, {
+  year: "numeric",
+  month: "long",
+  day: "numeric",
+}).format(date);
+
+const price = new Intl.NumberFormat(locale, {
+  style: "currency",
+  currency: "EUR",
+}).format(amount);
+```
+
+### 4. RTL Support
+
+```css
+/* Use logical properties instead of physical */
+.container {
+  padding-inline-start: 1rem; /* Not padding-left */
+  margin-inline-end: 2rem; /* Not margin-right */
+  border-inline-start: 2px solid;
+}
+```
+
+### 5. Next.js App Router Integration
+
+```typescript
+// middleware.ts
+import createMiddleware from "next-intl/middleware";
+
+export default createMiddleware({
+  locales: ["en", "tr", "de"],
+  defaultLocale: "en",
+  localeDetection: true,
+});
+
+export const config = {
+  matcher: ["/((?!api|_next|.*\\..*).*)"],
+};
+```
+
+## Quality Checklist
+
+- [ ] All user-facing strings externalized (no hardcoded text)
+- [ ] Pluralization rules applied for countable items
+- [ ] Date/time/number formatting uses locale-aware APIs
+- [ ] RTL layout tested (if supporting RTL languages)
+- [ ] Fallback language chain configured
+- [ ] Translation keys are descriptive and namespaced
+- [ ] Missing translation handling defined (fallback vs error)
+- [ ] SEO: `<html lang="">` and `hreflang` tags set
+- [ ] URL structure supports locale (`/en/about` or subdomain)
+
+## Anti-Patterns to Avoid
+
+❌ Hardcoding strings in components
+❌ Using string concatenation for translated sentences
+❌ Assuming left-to-right layout
+❌ Using physical CSS properties (left/right) instead of logical (start/end)
+❌ Formatting dates/numbers without locale context
+❌ Storing translations in code instead of separate files
+
+---
+
+> **Source**: Devran AI Kit — [@devran-ai/kit](https://github.com/devran-ai/kit)

package/.agent/skills/intelligent-routing/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: intelligent-routing
+description: Automatic agent selection and intelligent task routing. Analyzes user requests and selects the best specialist agent(s) for Trust-Grade execution.
+version: 1.0.0
+---
+
+# Intelligent Agent Routing
+
+> **Purpose**: Automatically analyze user requests and route them to the most appropriate specialist agent(s) without requiring explicit user mentions.
+
+## Core Principle
+
+> **The AI should act as an intelligent Project Manager**, analyzing each request and automatically selecting the best specialist(s) for the job while maintaining Trust-Grade governance.
+
+---
+
+## How It Works
+
+### 1. Request Analysis
+
+Before responding to ANY user request, perform automatic analysis:
+
+```mermaid
+graph TD
+    A[User Request] --> B[ANALYZE]
+    B --> C[Keywords]
+    B --> D[Domains]
+    B --> E[Complexity]
+    C --> F[SELECT AGENT]
+    D --> F
+    E --> F
+    F --> G[Apply Trust-Grade Context]
+    G --> H[AUTO-INVOKE with governance]
+```
+
+### 2. Agent Selection Matrix
+
+| User Intent       | Keywords                            | Selected Agent(s)          | Auto-invoke? |
+| ----------------- | ----------------------------------- | -------------------------- | ------------ |
+| **Architecture**  | "design", "structure", "pattern"    | `architect`                | ✅ YES       |
+| **Planning**      | "plan", "roadmap", "sprint"         | `planner`                  | ✅ YES       |
+| **Code Review**   | "review", "check", "audit"          | `code-reviewer`            | ✅ YES       |
+| **Security**      | "security", "vulnerability", "auth" | `security-reviewer`        | ✅ YES       |
+| **Testing**       | "test", "coverage", "e2e"           | `tdd-guide` + `e2e-runner` | ✅ YES       |
+| **Build Errors**  | "error", "build", "compile"         | `build-error-resolver`     | ✅ YES       |
+| **Refactoring**   | "refactor", "clean", "improve"      | `refactor-cleaner`         | ✅ YES       |
+| **Documentation** | "docs", "readme", "document"        | `doc-updater`              | ✅ YES       |
+| **Knowledge**     | "learn", "remember", "pattern"      | `knowledge-agent`          | ✅ YES       |
+| **Complex Task**  | Multiple domains detected           | `planner` → multi-agent    | ⚠️ ASK FIRST |
+
+---
+
+## Domain Detection Rules
+
+### Single-Domain Tasks (Auto-invoke Single Agent)
+
+| Domain           | Patterns                              | Agent                      |
+| ---------------- | ------------------------------------- | -------------------------- |
+| **Architecture** | design, pattern, structure, layer     | `architect`                |
+| **Planning**     | plan, task, sprint, milestone         | `planner`                  |
+| **Security**     | auth, jwt, password, vulnerability    | `security-reviewer`        |
+| **Testing**      | test, jest, coverage, e2e, playwright | `tdd-guide` / `e2e-runner` |
+| **Build**        | error, compile, typescript, lint      | `build-error-resolver`     |
+| **Refactor**     | clean, refactor, improve, optimize    | `refactor-cleaner`         |
+| **Docs**         | readme, document, api-docs            | `doc-updater`              |
+
+### Multi-Domain Tasks (Orchestration Required)
+
+If request matches **2+ domains from different categories**, escalate to `planner` for orchestration:
+
+```
+Example: "Create a secure login with tests"
+→ Detected: Security + Testing + Backend
+→ Auto-invoke: planner (orchestration mode)
+→ Planner will handle: security-reviewer, architect, tdd-guide
+```
+
+---
+
+## Complexity Assessment
+
+### SIMPLE (Direct agent invocation)
+
+- Single file edit
+- Clear, specific task
+- One domain only
+- Example: "Fix the TypeScript error in auth.ts"
+
+**Action**: Auto-invoke respective agent
+
+### MODERATE (2-3 agents)
+
+- 2-3 files affected
+- Clear requirements
+- 2 domains max
+- Example: "Add API endpoint with tests"
+
+**Action**: Auto-invoke relevant agents sequentially
+
+### COMPLEX (Orchestration required)
+
+- Multiple files/domains
+- Architectural decisions needed
+- Unclear requirements
+- Example: "Build a new feature vertical"
+
+**Action**: Auto-invoke `planner` → will ask Socratic questions
+
+---
+
+## Implementation Rules
+
+### Rule 1: Silent Analysis
+
+**DO NOT announce "I'm analyzing your request..."**
+
+- ✅ Analyze silently
+- ✅ Inform which agent is being applied
+- ❌ Avoid verbose meta-commentary
+
+### Rule 2: Inform Agent Selection
+
+**DO inform which expertise is being applied:**
+
+```markdown
+🤖 **Applying `@security-reviewer` expertise...**
+
+I will review the authentication implementation with the following focus:
+[Continue with specialized response]
+```
+
+### Rule 3: Trust-Grade Context
+
+**Always apply project governance context:**
+
+- Load relevant governance rules
+- Apply session state context
+- Enforce pre-task checklists
+
+### Rule 4: Override Capability
+
+**User can still explicitly mention agents:**
+
+```
+User: "Use @architect to review this"
+→ Override auto-selection
+→ Use explicitly mentioned agent
+```
+
+---
+
+## Integration with Project Governance
+
+### With Session State
+
+- Check `session-state.json` for active context
+- Inherit project-specific configurations
+- Maintain Trust-Grade continuity
+
+### With Governance Rules
+
+- Apply relevant governance rules
+- Enforce professional standards
+- Maintain project architecture alignment
+
+### With Checklists
+
+- Trigger pre-task checks for complex operations
+- Validate against session-end protocols
+- Ensure documentation updates
+
+---
+
+## Summary
+
+1. **Analyze every request** before responding
+2. **Select best agent(s)** using the matrix
+3. **Inform user** which expertise is applied
+4. **Maintain governance** through Trust-Grade protocols
+5. **Stay seamless** - user shouldn't notice the routing

package/.agent/skills/mcp-integration/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: mcp-integration
+description: Model Context Protocol (MCP) integration patterns for extending AI capabilities with external tools and data sources.
+version: 1.0.0
+triggers: [mcp, tool, server, protocol, integration, external]
+---
+
+# MCP Integration Skill
+
+> **Purpose**: Guide the integration and effective use of Model Context Protocol (MCP) servers to extend AI agent capabilities with external tools, data sources, and services.
+
+---
+
+## Overview
+
+The Model Context Protocol (MCP) is an open standard that connects AI systems with external tools and data sources through a unified interface. MCP servers act as capability providers — each server exposes a set of tools that the AI can invoke to perform actions beyond its native abilities.
+
+This skill ensures that MCP integrations follow Trust-Grade principles: secure, reliable, and properly governed.
+
+---
+
+## Core Concepts
+
+### MCP Architecture
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
+│    AI Agent      │────▶│   MCP Client     │────▶│   MCP Server    │
+│  (LLM + Kit)    │◀────│  (IDE/Runtime)   │◀────│  (Tool Provider)│
+└─────────────────┘     └──────────────────┘     └─────────────────┘
+                                                         │
+                                                    ┌────┴────┐
+                                                    │ External │
+                                                    │ Service  │
+                                                    └─────────┘
+```
+
+### Key Components
+
+| Component | Role | Example |
+|:----------|:-----|:--------|
+| **MCP Server** | Exposes tools via protocol | GitHub MCP, GitKraken MCP, Database MCP |
+| **MCP Client** | Connects AI to servers | VS Code extension, Cursor, IDE runtime |
+| **Tools** | Individual capabilities | `create_issue`, `git_commit`, `run_query` |
+| **Resources** | Data endpoints | File contents, database schemas, API docs |
+| **Prompts** | Reusable templates | Code review template, deployment checklist |
+
+---
+
+## Integration Patterns
+
+### Pattern 1: Git Operations via MCP
+
+**When to use**: Git operations that benefit from structured API access rather than raw CLI commands.
+
+**Available servers**: GitKraken MCP, GitHub MCP
+
+```
+Preferred for:
+- Creating branches, commits, PRs (structured data)
+- Reading git status, blame, diff (parsed output)
+- Managing issues and reviews (API access)
+
+Still use CLI for:
+- Complex git operations (rebase, cherry-pick)
+- Local-only operations (stash, worktree)
+- Performance-critical batch operations
+```
+
+### Pattern 2: Issue and Project Management
+
+**When to use**: Creating, updating, and querying issues across platforms.
+
+```
+GitHub MCP Server provides:
+- issue_write (create/update issues)
+- issue_read (get details, comments, labels)
+- search_issues (query with GitHub syntax)
+- list_issues (paginated browsing)
+
+Best practices:
+- Use search_* for targeted queries with criteria
+- Use list_* for broad retrieval with pagination
+- Batch reads in groups of 5-10 items
+```
+
+### Pattern 3: Code Search and Analysis
+
+**When to use**: Finding code patterns across repositories.
+
+```
+GitHub MCP provides:
+- search_code (cross-repo code search)
+- get_file_contents (read specific files)
+- get_commit (commit details with diff)
+
+Usage guidance:
+- Use search_code for finding symbols, functions, patterns
+- Use get_file_contents for reading specific known files
+- Combine with local grep_search for current workspace
+```
+
+### Pattern 4: Pull Request Workflow
+
+**When to use**: Full PR lifecycle management.
+
+```
+Workflow:
+1. create_branch → Create feature branch
+2. push_files → Push code changes
+3. create_pull_request → Open PR
+4. request_copilot_review → Automated review
+5. pull_request_read(get_status) → Check CI status
+6. merge_pull_request → Merge when ready
+
+Trust-Grade rules:
+- Always create PR (never push directly to main)
+- Always request review before merge
+- Always check CI status before merge
+```
+
+---
+
+## Security Guidelines
+
+### Authentication
+
+- MCP servers use token-based authentication
+- Tokens are managed by the IDE/runtime, never by the AI agent
+- Never log, display, or store authentication tokens
+- Verify server identity before sending sensitive operations
+
+### Permission Model
+
+| Operation Type | Risk Level | Verification Required |
+|:---------------|:-----------|:---------------------|
+| Read (list, get, search) | Low | None |
+| Create (new issue, branch, file) | Medium | Confirm with user |
+| Modify (update, edit) | Medium | Confirm with user |
+| Delete (remove file, close issue) | High | Explicit user approval |
+| Deploy (merge, publish) | Critical | Double confirmation |
+
+### Data Handling
+
+- Never pass secrets through MCP tool parameters
+- Sanitize user data before including in tool calls
+- Respect repository visibility (public vs private)
+- Log operations for audit trail (session-context.md)
+
+---
+
+## Server Selection Guide
+
+| Task | Recommended Server | Why |
+|:-----|:-------------------|:----|
+| Git operations (commit, branch, status) | GitKraken MCP | Richer git-specific tools |
+| GitHub issues and PRs | GitHub MCP | Native GitHub API access |
+| Code review and analysis | GitHub MCP | PR review tools |
+| Repository management | GitHub MCP | Repo CRUD operations |
+| Complex git workflows | GitKraken MCP | Worktree, stash, blame |
+
+---
+
+## Error Handling
+
+### Common MCP Errors
+
+| Error | Cause | Resolution |
+|:------|:------|:-----------|
+| `ENEEDAUTH` | Token expired/missing | Re-authenticate via IDE settings |
+| `403 Forbidden` | Insufficient permissions | Check token scopes |
+| `404 Not Found` | Resource doesn't exist | Verify owner/repo/branch names |
+| `422 Unprocessable` | Invalid parameters | Check required fields and formats |
+| `Rate Limited` | Too many requests | Implement exponential backoff |
+
+### Fallback Strategy
+
+When an MCP server is unavailable:
+1. Log the failure in session context
+2. Fall back to CLI equivalent if available
+3. Notify user of degraded capability
+4. Continue with remaining available tools
+
+---
+
+## Pre-configured Server Templates
+
+Templates are available in `.agent/engine/mcp-servers/`:
+
+| Server | Package | Required Env Var |
+|--------|---------|-----------------|
+| GitHub | `@modelcontextprotocol/server-github` | `GITHUB_TOKEN` |
+| Supabase | `@supabase/mcp-server-supabase` | `SUPABASE_ACCESS_TOKEN` |
+| Vercel | `@vercel/mcp` | `VERCEL_TOKEN` |
+| Filesystem | `@modelcontextprotocol/server-filesystem` | (none) |
+| PostgreSQL | `@modelcontextprotocol/server-postgres` | `DATABASE_URL` |
+
+Templates use `${VAR}` placeholders — set the environment variable before starting the server.
+
+---
+
+## Integration with Devran AI Kit
+
+### Loading Rules Integration
+
+MCP capabilities are registered in `engine/loading-rules.json` under domain rules:
+
+```json
+{
+  "domain": "git-operations",
+  "keywords": ["git", "commit", "branch", "pr", "merge"],
+  "loadAgents": ["devops-engineer"],
+  "loadSkills": ["git-workflow", "mcp-integration"],
+  "mcpServers": ["GitKraken", "github-mcp-server"]
+}
+```
+
+### Session Context Tracking
+
+Log MCP operations in session context for continuity:
+
+```markdown
+## MCP Operations This Session
+- Created branch `feature/auth` via GitKraken MCP
+- Opened PR #42 via GitHub MCP
+- Requested Copilot review via GitHub MCP
+```
+
+### Workflow State Integration
+
+MCP operations map to workflow phases:
+
+| Phase | MCP Operations |
+|:------|:--------------|
+| EXPLORE | `search_code`, `get_file_contents`, `list_issues` |
+| PLAN | `issue_write` (create tracking issue) |
+| IMPLEMENT | `create_branch`, `push_files` |
+| VERIFY | `pull_request_read(get_status)` |
+| REVIEW | `request_copilot_review`, `pull_request_review_write` |
+| DEPLOY | `merge_pull_request` |