@devran-ai/kit 4.1.0

package/.agent/skills/brainstorming/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: brainstorming
+description: Socratic questioning and discovery protocol. Ensures requirements clarity before implementation.
+version: 1.0.0
+allowed-tools: Read, Glob, Grep
+---
+
+# Brainstorming & Communication Protocol
+
+> Understand before building. Ask before assuming.
+
+---
+
+## 🛑 SOCRATIC GATE (MANDATORY)
+
+### When to Trigger
+
+| Pattern                                     | Action                             |
+| ------------------------------------------- | ---------------------------------- |
+| "Build/Create/Make [thing]" without details | 🛑 ASK 3 questions                 |
+| Complex feature or architecture             | 🛑 Clarify before implementing     |
+| Update/change request                       | 🛑 Confirm scope                   |
+| Vague requirements                          | 🛑 Ask purpose, users, constraints |
+
+### 3 Questions Before Implementation
+
+1. **STOP** — Do NOT start coding
+2. **ASK** — Minimum 3 questions:
+   - 🎯 **Purpose**: What problem are you solving?
+   - 👥 **Users**: Who will use this?
+   - 📦 **Scope**: Must-have vs nice-to-have?
+3. **WAIT** — Get response before proceeding
+
+---
+
+## 🧠 Dynamic Question Generation
+
+> **⛔ NEVER use static templates.** Generate questions based on context.
+
+### Core Principles
+
+| Principle           | Application                  |
+| ------------------- | ---------------------------- |
+| **Context-aware**   | Questions match the domain   |
+| **Prioritized**     | Ask most important first     |
+| **Open-ended**      | Encourage detailed responses |
+| **Assumption-free** | Don't lead the answer        |
+
+### Question Generation Process
+
+```
+1. Identify domain (frontend, backend, mobile, etc.)
+2. Detect ambiguities in request
+3. Generate 3-5 clarifying questions
+4. Order by impact on implementation
+5. Present clearly with formatting
+```
+
+### Question Format
+
+```markdown
+Before I proceed, I have a few questions:
+
+1. **[Topic]**: [Specific question]?
+2. **[Topic]**: [Specific question]?
+3. **[Topic]**: [Specific question]?
+
+Feel free to answer all at once, and I'll start implementing.
+```
+
+---
+
+## 📊 Progress Reporting
+
+### Status Icons
+
+| Icon | Meaning                  |
+| ---- | ------------------------ |
+| ✅   | Complete                 |
+| 🔄   | In progress              |
+| ⏳   | Pending                  |
+| ❌   | Failed/Blocked           |
+| ⚠️   | Warning/Attention needed |
+
+### Status Board Format
+
+```markdown
+## Status Update
+
+| Task            | Status | Notes    |
+| --------------- | ------ | -------- |
+| Database schema | ✅     | Migrated |
+| API endpoints   | 🔄     | 3/5 done |
+| Frontend pages  | ⏳     | Next up  |
+```
+
+---
+
+## ⚠️ Error Handling
+
+### Error Response Pattern
+
+```markdown
+🔍 **Symptom**: [What happened]
+🎯 **Root cause**: [Why it happened]
+✅ **Fix**: [The solution]
+🛡️ **Prevention**: [How to avoid in future]
+```
+
+---
+
+## ✅ Completion Message
+
+### Structure
+
+```markdown
+## ✅ Complete: [Task Name]
+
+### What was done
+
+- [Deliverable 1]
+- [Deliverable 2]
+
+### How to verify
+
+[Specific steps to test]
+
+### Next steps (suggested)
+
+1. [Optional follow-up]
+2. [Optional follow-up]
+```
+
+---
+
+## Communication Principles
+
+| Principle        | Implementation                     |
+| ---------------- | ---------------------------------- |
+| **Concise**      | No unnecessary details             |
+| **Visual**       | Use emojis for quick scanning      |
+| **Specific**     | "~2 minutes" not "wait a bit"      |
+| **Alternatives** | Offer paths when stuck             |
+| **Proactive**    | Suggest next step after completion |
+
+---
+
+## Anti-Patterns (AVOID)
+
+| ❌ Don't            | ✅ Do            |
+| ------------------- | ---------------- |
+| Jump to solutions   | Understand first |
+| Assume requirements | Ask questions    |
+| Over-engineer v1    | MVP first        |
+| Ignore constraints  | Factor them in   |
+| "I think" phrases   | Ask for clarity  |

package/.agent/skills/clean-code/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: clean-code
+description: Code quality principles and best practices
+triggers: [context, code, quality, review]
+---
+
+# Clean Code Skill
+
+> **Purpose**: Write maintainable, readable, and professional code
+
+---
+
+## Overview
+
+This skill applies Robert C. Martin's Clean Code principles and industry best practices for writing professional-grade code.
+
+---
+
+## Naming Conventions
+
+### Variables
+
+```typescript
+// ❌ Bad
+const d = new Date();
+const u = users.filter((x) => x.active);
+
+// ✅ Good
+const currentDate = new Date();
+const activeUsers = users.filter((user) => user.isActive);
+```
+
+### Functions
+
+```typescript
+// ❌ Bad
+function process(data) { ... }
+function handle(x) { ... }
+
+// ✅ Good
+function validateUserInput(formData) { ... }
+function calculateTotalPrice(orderItems) { ... }
+```
+
+### Classes
+
+```typescript
+// ❌ Bad
+class Data { ... }
+class Manager { ... }
+
+// ✅ Good
+class UserRepository { ... }
+class OrderService { ... }
+```
+
+---
+
+## Functions
+
+### Single Responsibility
+
+```typescript
+// ❌ Bad - does too much
+function processOrder(order) {
+  validateOrder(order);
+  calculateTotal(order);
+  saveToDatabase(order);
+  sendEmail(order);
+}
+
+// ✅ Good - one responsibility each
+function validateOrder(order) { ... }
+function calculateOrderTotal(order) { ... }
+function persistOrder(order) { ... }
+function notifyCustomer(order) { ... }
+```
+
+### Keep Small (≤20 lines)
+
+- Each function should do ONE thing
+- Extract helper functions when growing
+
+### Minimize Parameters
+
+```typescript
+// ❌ Bad
+function createUser(name, email, age, address, phone, role) { ... }
+
+// ✅ Good
+function createUser(userData: CreateUserDto) { ... }
+```
+
+---
+
+## Error Handling
+
+```typescript
+// ❌ Bad
+try {
+  doSomething();
+} catch (e) {
+  console.log(e);
+}
+
+// ✅ Good
+try {
+  await processPayment(order);
+} catch (error) {
+  logger.error("Payment processing failed", { orderId: order.id, error });
+  throw new PaymentFailedError(order.id, error.message);
+}
+```
+
+---
+
+## Comments
+
+```typescript
+// ❌ Bad - obvious comment
+// Increment counter by 1
+counter++;
+
+// ✅ Good - explains WHY
+// Offset for 0-based index when displaying to users
+const displayIndex = arrayIndex + 1;
+```
+
+---
+
+## Quick Reference
+
+| Principle      | Guideline             |
+| :------------- | :-------------------- |
+| Names          | Intention-revealing   |
+| Functions      | Small, single purpose |
+| Parameters     | ≤3 ideally            |
+| Comments       | Explain why, not what |
+| Formatting     | Consistent, readable  |
+| Error Handling | Explicit, informative |
+| DRY            | Don't repeat yourself |
+| KISS           | Keep it simple        |

package/.agent/skills/context-budget/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: context-budget
+description: Context window budget management and selective capability loading for LLM token optimization.
+version: 1.0.0
+triggers: [context-warning, session-start, manual]
+---
+
+# Context Budget Skill
+
+> **Purpose**: Manage LLM context window as a finite resource. Ensure the right agents and skills are loaded for each task while preventing context overflow.
+
+---
+
+## Overview
+
+LLM context windows have hard token limits. Loading all 19 agents and 27 skills simultaneously consumes context that should be reserved for the actual work. This skill implements intelligent selective loading to maximize usable context for code and reasoning.
+
+---
+
+## How It Works
+
+### 1. Domain Detection
+
+At the start of each task, analyze the user request to identify which domains are involved:
+
+```
+User: "Add JWT authentication to the API"
+→ Detected domains: security, backend, testing
+→ Load: security-reviewer, backend-specialist, tdd-guide
+→ Load: security-practices, api-patterns, testing-patterns
+```
+
+### 2. Selective Loading
+
+Consult `engine/loading-rules.json` to determine which agents and skills to load:
+
+- **Always loaded** (core): `rules.md`, `manifest.json`, `workflow-state.json`
+- **Session context**: `session-context.md`, `session-state.json`
+- **Domain-specific**: Only agents/skills matching detected domains
+
+### 3. Budget Limits
+
+| Resource | Default Limit | Rationale |
+|:---------|:-------------|:----------|
+| Agents per session | 4 | Each agent ~200-500 tokens of context |
+| Skills per session | 6 | Each skill ~200-800 tokens of context |
+| Maximum loaded context | ~30% of window | Reserve 70% for code and reasoning |
+
+### 4. Overflow Prevention
+
+When approaching context limits:
+
+1. **Warn**: Alert that context is nearing capacity
+2. **Compact**: Apply `strategic-compact` skill to summarize completed work
+3. **Unload**: Release agents/skills no longer needed for current phase
+4. **Persist**: Save important context to `session-state.json` before compaction
+
+---
+
+## Task-Based Loading Profiles
+
+| Task Type | Agents Loaded | Skills Loaded |
+|:----------|:-------------|:-------------|
+| **Security audit** | security-reviewer, architect | security-practices, architecture |
+| **Feature build** | planner, architect, tdd-guide | plan-writing, testing-patterns, clean-code |
+| **Bug fix** | build-error-resolver | debugging-strategies |
+| **Sprint planning** | sprint-orchestrator, planner | plan-writing, brainstorming |
+| **Code review** | code-reviewer, security-reviewer | clean-code, security-practices |
+| **Deployment** | devops-engineer, reliability-engineer | deployment-procedures, docker-patterns |
+
+---
+
+## Integration
+
+- Triggered at session start by reading `engine/loading-rules.json`
+- Enforced by `reliability-engineer` agent
+- Monitored throughout session lifecycle
+- Compaction delegated to `strategic-compact` skill

package/.agent/skills/continuous-learning/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: continuous-learning
+description: Extract reusable patterns from sessions and save them as knowledge
+triggers: [session-end, manual]
+---
+
+# Continuous Learning Skill
+
+> **Purpose**: Learn from development sessions to improve future assistance
+
+---
+
+## Overview
+
+This skill implements the PAAL (Perceive-Analyze-Adapt-Learn) cycle to extract reusable patterns from development sessions.
+
+---
+
+## PAAL Cycle
+
+### 1. Perceive
+
+Monitor session for significant events:
+
+- User corrections
+- Repeated patterns
+- Error resolutions
+- Decision rationale
+
+### 2. Analyze
+
+Identify learning opportunities:
+
+- What went wrong?
+- What went right?
+- What patterns emerged?
+- What knowledge was missing?
+
+### 3. Adapt
+
+Apply learnings immediately:
+
+- Update mental models
+- Adjust approach
+- Incorporate feedback
+
+### 4. Learn
+
+Persist knowledge for future:
+
+- Document patterns in `decisions/`
+- Update knowledge base
+- Create reusable templates
+
+---
+
+## Pattern Extraction Format
+
+```markdown
+# Pattern: [Name]
+
+## Context
+
+When: [Situation]
+Problem: [What problem this solves]
+
+## Solution
+
+[How to apply the pattern]
+
+## Example
+
+[Concrete example]
+
+## Anti-patterns
+
+[What NOT to do]
+```
+
+---
+
+## Confidence Scoring
+
+Patterns are scored 0-5 based on reinforcement frequency:
+
+| Score | Label | Criteria |
+|-------|-------|----------|
+| 1 | Observed | Seen once |
+| 2 | Emerging | Confirmed 2-3 times |
+| 3 | Established | Confirmed 4-5 times |
+| 4 | Proven | Confirmed 6-9 times |
+| 5 | Battle-tested | 10+ reinforcements |
+
+Runtime: `lib/learning-engine.js` → `scoreConfidence(reinforcementCount)`
+
+---
+
+## Domain Clustering
+
+Patterns are grouped by `loading-rules.json` domains (security, testing, architecture, frontend, backend, database, devops, performance, reliability, mobile, documentation, planning, debugging, refactoring).
+
+When a cluster reaches 3+ proven patterns (confidence >= 4), recommend promotion to a new skill or rule.
+
+Runtime: `lib/learning-engine.js` → `clusterPatterns(patterns, domainRules)`
+
+---
+
+## Decay Model
+
+Patterns that are not reinforced lose confidence over time:
+- Every 10 sessions without reinforcement: -1 confidence
+- Confidence reaches 0: pattern is archived (not deleted)
+- Archived patterns can be restored if re-observed
+
+This prevents stale patterns from consuming context budget.
+
+Runtime: `lib/learning-engine.js` → `decayPatterns(patterns)`
+
+---
+
+## Pattern Extraction Format
+
+```markdown
+# Pattern: [Name]
+
+## Context
+When: [Situation]
+Problem: [What problem this solves]
+Confidence: [1-5]
+Keywords: [domain keywords for clustering]
+
+## Solution
+[How to apply the pattern]
+
+## Anti-patterns
+[What NOT to do]
+```
+
+---
+
+## Integration
+
+- Runs at session end via `/learn` or automatically
+- Outputs to `decisions/` directory
+- Runtime engine: `lib/learning-engine.js` (pure functions, zero I/O)