@devran-ai/kit 4.1.0

package/.agent/engine/mcp-servers/github.json

@@ -0,0 +1,11 @@
+{
+  "name": "github",
+  "description": "GitHub API — issues, PRs, repos, code search",
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-github"],
+  "env": {
+    "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
+  },
+  "capabilities": ["issues", "pull-requests", "repos", "code-search"]
+}

package/.agent/engine/mcp-servers/postgres.json

@@ -0,0 +1,11 @@
+{
+  "name": "postgres",
+  "description": "PostgreSQL — query execution, schema inspection, migrations",
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-postgres"],
+  "env": {
+    "DATABASE_URL": "${DATABASE_URL}"
+  },
+  "capabilities": ["query", "schema-inspect", "migrations"]
+}

package/.agent/engine/mcp-servers/supabase.json

@@ -0,0 +1,11 @@
+{
+  "name": "supabase",
+  "description": "Supabase — database, auth, storage, edge functions",
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["-y", "@supabase/mcp-server-supabase"],
+  "env": {
+    "SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}"
+  },
+  "capabilities": ["database", "auth", "storage", "edge-functions"]
+}

package/.agent/engine/mcp-servers/vercel.json

@@ -0,0 +1,11 @@
+{
+  "name": "vercel",
+  "description": "Vercel — deployments, domains, environment variables",
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["-y", "@vercel/mcp"],
+  "env": {
+    "VERCEL_TOKEN": "${VERCEL_TOKEN}"
+  },
+  "capabilities": ["deployments", "domains", "env-vars", "logs"]
+}

package/.agent/engine/reliability-config.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": "1.0.0",
+  "description": "SRE reliability configuration — error budget tracking and operational thresholds",
+  "errorBudget": {
+    "enabled": true,
+    "description": "When error budget is exhausted, reliability work takes priority over feature work. Projects opt-in when monitoring infrastructure exists.",
+    "thresholds": {
+      "testFailureRatePercent": 5,
+      "buildFailureRatePercent": 2,
+      "deployRollbackRatePercent": 10
+    },
+    "resetCadence": "monthly"
+  }
+}

package/.agent/engine/sdlc-map.json

@@ -0,0 +1,50 @@
+{
+  "schemaVersion": "1.0.0",
+  "description": "Machine-readable SDLC phase-to-workflow mapping with bidirectional traversal",
+  "phases": {
+    "discover": {
+      "description": "Requirement exploration and validation",
+      "workflows": ["brainstorm", "quality-gate"],
+      "previous": null,
+      "next": "plan"
+    },
+    "plan": {
+      "description": "Structured implementation planning",
+      "workflows": ["plan"],
+      "previous": "discover",
+      "next": "build"
+    },
+    "build": {
+      "description": "Feature implementation and scaffolding",
+      "workflows": ["create", "enhance", "preview", "ui-ux-pro-max"],
+      "previous": "plan",
+      "next": "verify"
+    },
+    "verify": {
+      "description": "Testing and quality gate validation",
+      "workflows": ["test", "review"],
+      "previous": "build",
+      "next": "checkpoint"
+    },
+    "checkpoint": {
+      "description": "Developer decision gate with intelligence-driven recommendations",
+      "workflows": [],
+      "previous": "verify",
+      "next": "ship"
+    },
+    "ship": {
+      "description": "Production deployment with pre-flight checks",
+      "workflows": ["deploy"],
+      "previous": "checkpoint",
+      "next": "evaluate"
+    },
+    "evaluate": {
+      "description": "Post-sprint retrospective audit",
+      "workflows": ["retrospective"],
+      "previous": "ship",
+      "next": "discover"
+    }
+  },
+  "reactive": ["debug", "orchestrate"],
+  "crossCutting": ["status"]
+}

package/.agent/engine/workflow-state.json

@@ -0,0 +1,167 @@
+{
+  "schemaVersion": "1.0.0",
+  "currentPhase": "IDLE",
+  "startedAt": null,
+  "phases": {
+    "EXPLORE": {
+      "status": "pending",
+      "description": "Codebase discovery and requirement analysis",
+      "agent": "explorer-agent",
+      "artifact": null,
+      "startedAt": null,
+      "completedAt": null
+    },
+    "PLAN": {
+      "status": "pending",
+      "description": "Structured task breakdown with Socratic gate",
+      "agent": "planner",
+      "artifact": null,
+      "startedAt": null,
+      "completedAt": null,
+      "requiresApproval": true
+    },
+    "IMPLEMENT": {
+      "status": "pending",
+      "description": "Code implementation following the approved plan",
+      "agent": null,
+      "artifact": null,
+      "startedAt": null,
+      "completedAt": null
+    },
+    "VERIFY": {
+      "status": "pending",
+      "description": "Quality gates, tests, and build verification",
+      "agent": "tdd-guide",
+      "skill": "verification-loop",
+      "artifact": null,
+      "startedAt": null,
+      "completedAt": null
+    },
+    "CHECKPOINT": {
+      "status": "pending",
+      "description": "Developer decision gate — presents completion options before commit/push",
+      "checklist": "checklists/task-complete.md",
+      "artifact": null,
+      "startedAt": null,
+      "completedAt": null,
+      "requiresApproval": true
+    },
+    "REVIEW": {
+      "status": "pending",
+      "description": "Code review and security audit",
+      "agent": "code-reviewer",
+      "artifact": null,
+      "startedAt": null,
+      "completedAt": null
+    },
+    "DEPLOY": {
+      "status": "pending",
+      "description": "Production deployment with pre-flight checks",
+      "workflow": "deploy",
+      "artifact": null,
+      "startedAt": null,
+      "completedAt": null
+    },
+    "MAINTAIN": {
+      "status": "pending",
+      "description": "Post-deploy monitoring and operational handoff",
+      "workflow": "status",
+      "artifact": null,
+      "startedAt": null,
+      "completedAt": null
+    }
+  },
+  "transitions": [
+    {
+      "from": "IDLE",
+      "to": "EXPLORE",
+      "trigger": "New task started",
+      "guard": "No active workflow in progress"
+    },
+    {
+      "from": "IDLE",
+      "to": "PLAN",
+      "trigger": "Task with known requirements",
+      "guard": "Requirements are clear"
+    },
+    {
+      "from": "EXPLORE",
+      "to": "PLAN",
+      "trigger": "Discovery complete",
+      "guard": "Exploration artifact exists"
+    },
+    {
+      "from": "PLAN",
+      "to": "IMPLEMENT",
+      "trigger": "Plan approved",
+      "guard": "Plan approved by user (explicit yes/approval)"
+    },
+    {
+      "from": "IMPLEMENT",
+      "to": "VERIFY",
+      "trigger": "Implementation complete",
+      "guard": "All plan items marked complete"
+    },
+    {
+      "from": "VERIFY",
+      "to": "CHECKPOINT",
+      "trigger": "Quality gates pass",
+      "guard": "All quality gates pass (build, lint, test)"
+    },
+    {
+      "from": "VERIFY",
+      "to": "IMPLEMENT",
+      "trigger": "Quality gates fail",
+      "guard": "One or more quality gates failed"
+    },
+    {
+      "from": "CHECKPOINT",
+      "to": "REVIEW",
+      "trigger": "Developer chooses review/commit",
+      "guard": "Developer selects review or commit option"
+    },
+    {
+      "from": "CHECKPOINT",
+      "to": "IMPLEMENT",
+      "trigger": "Developer chooses continue working",
+      "guard": "Developer selects continue or batch option"
+    },
+    {
+      "from": "REVIEW",
+      "to": "DEPLOY",
+      "trigger": "Review approved",
+      "guard": "No critical findings remain"
+    },
+    {
+      "from": "REVIEW",
+      "to": "IMPLEMENT",
+      "trigger": "Review requires changes",
+      "guard": "Critical findings require code changes"
+    },
+    {
+      "from": "DEPLOY",
+      "to": "MAINTAIN",
+      "trigger": "Deployment health check passes",
+      "guard": "Health check verified healthy"
+    },
+    {
+      "from": "DEPLOY",
+      "to": "REVIEW",
+      "trigger": "Deployment health check fails",
+      "guard": "Health check failure detected"
+    },
+    {
+      "from": "IMPLEMENT",
+      "to": "PLAN",
+      "trigger": "Unexpected complexity discovered",
+      "guard": "Implementation reveals plan inadequacy"
+    },
+    {
+      "from": "MAINTAIN",
+      "to": "IDLE",
+      "trigger": "Monitoring period complete",
+      "guard": "No issues detected during observation"
+    }
+  ],
+  "history": []
+}

package/.agent/hooks/README.md

@@ -0,0 +1,101 @@
+# Devran AI Kit — Hooks
+
+> **Purpose**: Event-driven automation triggered by specific actions  
+> **Count**: 8 Event Hooks
+
+---
+
+## Overview
+
+Hooks are automated actions triggered by events during development sessions. They form the **operational backbone** of Trust-Grade AI governance.
+
+---
+
+## Available Hooks
+
+| Hook               | Trigger           | Action                | Status |
+| :----------------- | :---------------- | :-------------------- | :----- |
+| `session-start`      | Session begins       | Load context            | Active |
+| `session-end`        | Session ends         | Save state              | Active |
+| `pre-commit`         | Before git commit    | Run verification        | Active |
+| `secret-detection`   | After file write     | Block exposed secrets   | Active |
+| `phase-transition`   | Workflow phase change| Enforce SDLC gates      | Active |
+| `sprint-checkpoint`  | Sprint milestone     | Progress verification   | Active |
+| `plan-complete`      | Plan finalized       | Plan validation trigger | Active |
+| `task-complete`      | Task finished        | Completion verification | Active |
+
+---
+
+## Hook Templates
+
+Detailed implementation guides are available in `templates/`:
+
+| Template                                       | Purpose                               |
+| :--------------------------------------------- | :------------------------------------ |
+| [session-start.md](templates/session-start.md) | Context loading and environment setup |
+| [session-end.md](templates/session-end.md)     | State preservation and handoff        |
+
+---
+
+## Configuration
+
+Hooks are defined in `hooks.json`:
+
+```json
+{
+  "hooks": [
+    {
+      "name": "hook-name",
+      "trigger": "TriggerType",
+      "matcher": "condition",
+      "action": "what to do"
+    }
+  ]
+}
+```
+
+---
+
+## Trigger Types
+
+| Trigger        | When Activated            |
+| :------------- | :------------------------ |
+| `SessionStart` | New session begins        |
+| `SessionEnd`   | Session ends              |
+| `PreToolUse`   | Before tool execution     |
+| `PostToolUse`  | After tool execution      |
+| `FileWrite`    | After writing to any file |
+| `GitCommit`    | Before git commit         |
+
+---
+
+## Trust-Grade Principles
+
+Hooks implement Trust-Grade governance:
+
+1. **Automatic**: No manual discipline required
+2. **Consistent**: Same quality gates every time
+3. **Transparent**: Actions are documented
+4. **Non-Blocking**: Warnings over hard blocks (when safe)
+
+---
+
+## Creating Custom Hooks
+
+Add to `hooks.json`:
+
+```json
+{
+  "name": "my-custom-hook",
+  "trigger": "PostToolUse",
+  "matcher": "tool == 'Write' && file.endsWith('.ts')",
+  "action": "Run TypeScript type check"
+}
+```
+
+Create implementation in `templates/my-custom-hook.md` with:
+
+- Purpose
+- Actions (with code examples)
+- Expected output
+- Customization options

package/.agent/hooks/hooks.json

@@ -0,0 +1,104 @@
+{
+  "schemaVersion": "1.1.0",
+  "hooks": [
+    {
+      "event": "session-start",
+      "description": "Executed at the beginning of every AI session",
+      "enforcement": "runtime",
+      "actions": [
+        { "action": "Load session-context.md and session-state.json", "severity": "critical", "onFailure": "block" },
+        { "action": "Read engine/loading-rules.json for context budget", "severity": "high", "onFailure": "warn" },
+        { "action": "Read engine/workflow-state.json for lifecycle phase", "severity": "high", "onFailure": "warn" },
+        { "action": "Verify git status is clean or understood", "severity": "medium", "onFailure": "warn" },
+        { "action": "Load domain-relevant agents and skills via loading-rules.json", "severity": "high", "onFailure": "warn" },
+        { "action": "Present session state to user before proceeding", "severity": "critical", "onFailure": "block" }
+      ]
+    },
+    {
+      "event": "session-end",
+      "description": "Executed at the end of every AI session",
+      "enforcement": "runtime",
+      "actions": [
+        { "action": "Update session-context.md with handoff notes", "severity": "critical", "onFailure": "block" },
+        { "action": "Update session-state.json with metadata", "severity": "critical", "onFailure": "block" },
+        { "action": "Update engine/workflow-state.json with phase progress", "severity": "high", "onFailure": "warn" },
+        { "action": "Trigger continuous-learning skill for pattern extraction", "severity": "low", "onFailure": "log" },
+        { "action": "Update docs/ROADMAP.md if sprint items changed", "severity": "medium", "onFailure": "warn" },
+        { "action": "Commit tracking files together", "severity": "high", "onFailure": "warn" }
+      ]
+    },
+    {
+      "event": "pre-commit",
+      "description": "Verification before any git commit",
+      "enforcement": "runtime",
+      "actions": [
+        { "action": "Verify build passes (npm run build)", "severity": "critical", "onFailure": "block" },
+        { "action": "Verify lint passes (npm run lint)", "severity": "critical", "onFailure": "block" },
+        { "action": "Verify tests pass (npm test)", "severity": "critical", "onFailure": "block" },
+        { "action": "Check for console.log statements in production code", "severity": "medium", "onFailure": "warn" },
+        { "action": "Verify no TypeScript errors (npx tsc --noEmit)", "severity": "critical", "onFailure": "block" }
+      ]
+    },
+    {
+      "event": "secret-detection",
+      "description": "Scan for accidentally committed secrets",
+      "enforcement": "git-hook",
+      "severity": "critical",
+      "onFailure": "block",
+      "referenceScript": ".githooks/pre-commit",
+      "patterns": [
+        "sk-[a-zA-Z0-9]{20,}",
+        "AKIA[A-Z0-9]{16}",
+        "api_key\\s*=\\s*['\"][^'\"]+",
+        "password\\s*=\\s*['\"][^'\"]+",
+        "AWS_SECRET_ACCESS_KEY",
+        "PRIVATE_KEY",
+        "ghp_[a-zA-Z0-9]{36}",
+        "gho_[a-zA-Z0-9]{36}"
+      ]
+    },
+    {
+      "event": "phase-transition",
+      "description": "Triggered when workflow lifecycle phase changes",
+      "enforcement": "runtime",
+      "actions": [
+        { "action": "Validate transition guard from engine/workflow-state.json", "severity": "critical", "onFailure": "block" },
+        { "action": "Record transition in workflow-state.json history", "severity": "high", "onFailure": "warn" },
+        { "action": "Load/unload agents appropriate for new phase", "severity": "high", "onFailure": "warn" },
+        { "action": "Notify user of phase change with next suggested action", "severity": "medium", "onFailure": "warn" }
+      ]
+    },
+    {
+      "event": "sprint-checkpoint",
+      "description": "Triggered at sprint boundaries for health assessment",
+      "enforcement": "runtime",
+      "actions": [
+        { "action": "Sprint orchestrator generates health report", "severity": "high", "onFailure": "warn" },
+        { "action": "Review velocity metrics against plan", "severity": "medium", "onFailure": "warn" },
+        { "action": "Identify carry-over candidates", "severity": "medium", "onFailure": "log" },
+        { "action": "Produce sprint retrospective if ending", "severity": "high", "onFailure": "warn" }
+      ]
+    },
+    {
+      "event": "plan-complete",
+      "description": "Triggered when a planned task reaches VERIFY phase. Runs plan retrospective to measure accuracy and feed learnings back into future planning.",
+      "enforcement": "runtime",
+      "actions": [
+        { "action": "Run plan-retrospective against original plan document (compare predicted vs actual files, tasks, estimates)", "severity": "medium", "onFailure": "log" },
+        { "action": "Append retrospective findings to contexts/plan-quality-log.md", "severity": "low", "onFailure": "log" },
+        { "action": "Extract learnings for continuous-learning skill (PAAL cycle)", "severity": "low", "onFailure": "log" }
+      ]
+    },
+    {
+      "event": "task-complete",
+      "description": "Triggered after quality gates pass. Presents developer with structured decision options before commit/push.",
+      "enforcement": "runtime",
+      "actions": [
+        { "action": "Present task completion decision prompt to developer", "severity": "critical", "onFailure": "block" },
+        { "action": "Evaluate change scope for recommendations (sprint boundary, production impact, session duration)", "severity": "high", "onFailure": "warn" },
+        { "action": "Check if tracking files (ROADMAP, session-context, session-state) need updating", "severity": "medium", "onFailure": "warn" },
+        { "action": "Suggest session-end protocol if session has accumulated significant changes", "severity": "low", "onFailure": "log" }
+      ]
+    }
+  ]
+}

package/.agent/hooks/templates/session-end.md

@@ -0,0 +1,110 @@
+# Session End Hook
+
+> **Trigger**: SessionEnd  
+> **Priority**: 1 (Highest)  
+> **Status**: Active
+
+---
+
+## 🎯 Purpose
+
+Save context and preserve state when a session ends. This hook ensures **continuity** for future sessions and proper **handoff** documentation.
+
+---
+
+## 🔄 Actions
+
+### 1. Update Session Context
+
+Save current session summary:
+
+```javascript
+// Update session-context.md
+const summary = generateSessionSummary({
+  accomplishments: getAccomplishments(),
+  openItems: getOpenItems(),
+  commits: getSessionCommits(),
+});
+await writeFile(".agent/session-context.md", summary);
+```
+
+### 2. Save Session State
+
+Persist machine-readable state:
+
+```javascript
+// Update session-state.json
+const state = {
+  lastUpdated: new Date().toISOString(),
+  currentTask: getCurrentTask(),
+  branch: await exec("git branch --show-current"),
+  lastCommit: await exec("git rev-parse --short HEAD"),
+};
+await writeJSON(".agent/session-state.json", state);
+```
+
+### 3. Verify Clean State
+
+Check for uncommitted changes:
+
+```javascript
+const gitStatus = await exec("git status --short");
+if (gitStatus.length > 0) {
+  warn(
+    "Uncommitted changes detected. Consider committing before ending session.",
+  );
+}
+```
+
+### 4. Generate Handoff Notes
+
+Create handoff documentation if needed:
+
+```javascript
+if (hasOpenItems()) {
+  const handoff = generateHandoffNotes({
+    nextPriority: getNextPriority(),
+    blockers: getBlockers(),
+    contextFiles: getRelevantFiles(),
+  });
+  appendToSessionContext(handoff);
+}
+```
+
+---
+
+## 📋 Output
+
+```
+[Session End]
+✓ session-context.md updated
+✓ session-state.json saved
+✓ Git status: clean
+✓ Handoff notes: Generated
+
+Session ended successfully. Ready for next session.
+```
+
+---
+
+## 🔧 Customization
+
+Extend this hook for project-specific needs:
+
+```json
+{
+  "name": "session-end-custom",
+  "trigger": "SessionEnd",
+  "action": "Run project-specific cleanup tasks"
+}
+```
+
+---
+
+## ⚖️ Trust-Grade Integration
+
+This hook supports Trust-Grade principles:
+
+- **Context Preservation**: Never lose work context
+- **Explainability**: Document what was done and why
+- **Handoff-Ready**: Future sessions can resume seamlessly