@devran-ai/kit 4.1.0

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

@@ -0,0 +1,95 @@
+# Session Start Hook
+
+> **Trigger**: SessionStart  
+> **Priority**: 1 (Highest)  
+> **Status**: Active
+
+---
+
+## 🎯 Purpose
+
+Load context and prepare the environment when a new session begins. This hook ensures **continuity** and **full context** before any work starts.
+
+---
+
+## 🔄 Actions
+
+### 1. Load Session Context
+
+Read and apply previous session context:
+
+```javascript
+// Load session-context.md
+const context = await loadFile(".agent/session-context.md");
+injectSystemPrompt(context);
+```
+
+### 2. Check Session State
+
+Load machine-readable state:
+
+```javascript
+// Load session-state.json
+const state = await loadJSON(".agent/session-state.json");
+if (state.currentTask) {
+  notify(`Resuming task: ${state.currentTask}`);
+}
+```
+
+### 3. Verify Git Status
+
+Check current branch and any uncommitted changes:
+
+```javascript
+const gitStatus = await exec("git status --short");
+if (gitStatus.length > 0) {
+  warn(`Uncommitted changes detected: ${gitStatus.split("\n").length} files`);
+}
+```
+
+### 4. Check Dependencies
+
+Ensure project dependencies are installed:
+
+```javascript
+const lockfileChanged = await exec("git diff HEAD package-lock.json");
+if (lockfileChanged) {
+  suggest("Dependencies may have changed. Consider running npm install.");
+}
+```
+
+---
+
+## 📋 Output
+
+```
+[Session Start]
+✓ Context loaded from session-context.md
+✓ State restored: currentTask = "Implementing feature X"
+✓ Git branch: main (clean)
+✓ Dependencies: Up to date
+```
+
+---
+
+## 🔧 Customization
+
+Extend this hook for project-specific needs:
+
+```json
+{
+  "name": "session-start-custom",
+  "trigger": "SessionStart",
+  "action": "Load project-specific context files"
+}
+```
+
+---
+
+## ⚖️ Trust-Grade Integration
+
+This hook supports Trust-Grade principles:
+
+- **Consistency > Speed**: Full context before new work
+- **Completion > Suggestion**: Resume unfinished tasks
+- **Explainability**: Clear session state visibility

package/.agent/manifest.json

@@ -0,0 +1,466 @@
+{
+  "schemaVersion": "1.0.0",
+  "kitVersion": "4.1.0",
+  "lastAuditedAt": null,
+  "description": "Devran AI Kit — Trust-Grade AI Development Framework",
+  "repository": "https://github.com/devran-ai/kit",
+  "capabilities": {
+    "agents": {
+      "count": 23,
+      "items": [
+        {
+          "name": "architect",
+          "file": "agents/architect.md",
+          "domain": "System design, DDD, Hexagonal"
+        },
+        {
+          "name": "backend-specialist",
+          "file": "agents/backend-specialist.md",
+          "domain": "Node.js, NestJS, API design"
+        },
+        {
+          "name": "build-error-resolver",
+          "file": "agents/build-error-resolver.md",
+          "domain": "Rapid build fixes"
+        },
+        {
+          "name": "code-reviewer",
+          "file": "agents/code-reviewer.md",
+          "domain": "Quality + security review"
+        },
+        {
+          "name": "database-architect",
+          "file": "agents/database-architect.md",
+          "domain": "Schema, queries, optimization"
+        },
+        {
+          "name": "devops-engineer",
+          "file": "agents/devops-engineer.md",
+          "domain": "CI/CD, Docker, deployment"
+        },
+        {
+          "name": "doc-updater",
+          "file": "agents/doc-updater.md",
+          "domain": "Documentation sync"
+        },
+        {
+          "name": "e2e-runner",
+          "file": "agents/e2e-runner.md",
+          "domain": "End-to-end testing"
+        },
+        {
+          "name": "explorer-agent",
+          "file": "agents/explorer-agent.md",
+          "domain": "Codebase discovery"
+        },
+        {
+          "name": "frontend-specialist",
+          "file": "agents/frontend-specialist.md",
+          "domain": "React, Next.js, UI architecture"
+        },
+        {
+          "name": "knowledge-agent",
+          "file": "agents/knowledge-agent.md",
+          "domain": "RAG retrieval"
+        },
+        {
+          "name": "mobile-developer",
+          "file": "agents/mobile-developer.md",
+          "domain": "React Native, Expo"
+        },
+        {
+          "name": "performance-optimizer",
+          "file": "agents/performance-optimizer.md",
+          "domain": "Core Web Vitals"
+        },
+        {
+          "name": "planner",
+          "file": "agents/planner.md",
+          "domain": "Task breakdown, Socratic analysis"
+        },
+        {
+          "name": "pr-reviewer",
+          "file": "agents/pr-reviewer.md",
+          "domain": "PR review, branch strategy, code quality"
+        },
+        {
+          "name": "refactor-cleaner",
+          "file": "agents/refactor-cleaner.md",
+          "domain": "Dead code cleanup"
+        },
+        {
+          "name": "reliability-engineer",
+          "file": "agents/reliability-engineer.md",
+          "domain": "SRE, production readiness"
+        },
+        {
+          "name": "security-reviewer",
+          "file": "agents/security-reviewer.md",
+          "domain": "Vulnerability analysis"
+        },
+        {
+          "name": "sprint-orchestrator",
+          "file": "agents/sprint-orchestrator.md",
+          "domain": "Sprint planning, velocity"
+        },
+        {
+          "name": "tdd-guide",
+          "file": "agents/tdd-guide.md",
+          "domain": "Test-first enforcement"
+        },
+        {
+          "name": "typescript-reviewer",
+          "file": "agents/typescript-reviewer.md",
+          "domain": "TypeScript type safety review"
+        },
+        {
+          "name": "python-reviewer",
+          "file": "agents/python-reviewer.md",
+          "domain": "Python best practices review"
+        },
+        {
+          "name": "go-reviewer",
+          "file": "agents/go-reviewer.md",
+          "domain": "Go idioms and concurrency review"
+        }
+      ]
+    },
+    "commands": {
+      "count": 37,
+      "directory": "commands/"
+    },
+    "skills": {
+      "count": 34,
+      "items": [
+        {
+          "name": "api-patterns",
+          "directory": "skills/api-patterns/"
+        },
+        {
+          "name": "app-builder",
+          "directory": "skills/app-builder/"
+        },
+        {
+          "name": "architecture",
+          "directory": "skills/architecture/"
+        },
+        {
+          "name": "behavioral-modes",
+          "directory": "skills/behavioral-modes/"
+        },
+        {
+          "name": "brainstorming",
+          "directory": "skills/brainstorming/"
+        },
+        {
+          "name": "clean-code",
+          "directory": "skills/clean-code/"
+        },
+        {
+          "name": "context-budget",
+          "directory": "skills/context-budget/"
+        },
+        {
+          "name": "continuous-learning",
+          "directory": "skills/continuous-learning/"
+        },
+        {
+          "name": "database-design",
+          "directory": "skills/database-design/"
+        },
+        {
+          "name": "debugging-strategies",
+          "directory": "skills/debugging-strategies/"
+        },
+        {
+          "name": "deployment-procedures",
+          "directory": "skills/deployment-procedures/"
+        },
+        {
+          "name": "docker-patterns",
+          "directory": "skills/docker-patterns/"
+        },
+        {
+          "name": "eval-harness",
+          "directory": "skills/eval-harness/"
+        },
+        {
+          "name": "frontend-patterns",
+          "directory": "skills/frontend-patterns/"
+        },
+        {
+          "name": "git-workflow",
+          "directory": "skills/git-workflow/"
+        },
+        {
+          "name": "intelligent-routing",
+          "directory": "skills/intelligent-routing/"
+        },
+        {
+          "name": "i18n-localization",
+          "directory": "skills/i18n-localization/"
+        },
+        {
+          "name": "mcp-integration",
+          "directory": "skills/mcp-integration/"
+        },
+        {
+          "name": "mobile-design",
+          "directory": "skills/mobile-design/"
+        },
+        {
+          "name": "nodejs-patterns",
+          "directory": "skills/nodejs-patterns/"
+        },
+        {
+          "name": "parallel-agents",
+          "directory": "skills/parallel-agents/"
+        },
+        {
+          "name": "performance-profiling",
+          "directory": "skills/performance-profiling/"
+        },
+        {
+          "name": "plan-validation",
+          "directory": "skills/plan-validation/"
+        },
+        {
+          "name": "plan-writing",
+          "directory": "skills/plan-writing/"
+        },
+        {
+          "name": "pr-toolkit",
+          "directory": "skills/pr-toolkit/"
+        },
+        {
+          "name": "production-readiness",
+          "directory": "skills/production-readiness/"
+        },
+        {
+          "name": "security-practices",
+          "directory": "skills/security-practices/"
+        },
+        {
+          "name": "strategic-compact",
+          "directory": "skills/strategic-compact/"
+        },
+        {
+          "name": "testing-patterns",
+          "directory": "skills/testing-patterns/"
+        },
+        {
+          "name": "typescript-expert",
+          "directory": "skills/typescript-expert/"
+        },
+        {
+          "name": "ui-ux-pro-max",
+          "directory": "skills/ui-ux-pro-max/"
+        },
+        {
+          "name": "verification-loop",
+          "directory": "skills/verification-loop/"
+        },
+        {
+          "name": "webapp-testing",
+          "directory": "skills/webapp-testing/"
+        },
+        {
+          "name": "shell-conventions",
+          "directory": "skills/shell-conventions/"
+        }
+      ]
+    },
+    "workflows": {
+      "count": 21,
+      "items": [
+        {
+          "name": "brainstorm",
+          "file": "workflows/brainstorm.md"
+        },
+        {
+          "name": "create",
+          "file": "workflows/create.md"
+        },
+        {
+          "name": "debug",
+          "file": "workflows/debug.md"
+        },
+        {
+          "name": "deploy",
+          "file": "workflows/deploy.md"
+        },
+        {
+          "name": "enhance",
+          "file": "workflows/enhance.md"
+        },
+        {
+          "name": "orchestrate",
+          "file": "workflows/orchestrate.md"
+        },
+        {
+          "name": "plan",
+          "file": "workflows/plan.md"
+        },
+        {
+          "name": "pr",
+          "file": "workflows/pr.md"
+        },
+        {
+          "name": "pr-review",
+          "file": "workflows/pr-review.md"
+        },
+        {
+          "name": "pr-fix",
+          "file": "workflows/pr-fix.md"
+        },
+        {
+          "name": "pr-merge",
+          "file": "workflows/pr-merge.md"
+        },
+        {
+          "name": "pr-split",
+          "file": "workflows/pr-split.md"
+        },
+        {
+          "name": "preflight",
+          "file": "workflows/preflight.md"
+        },
+        {
+          "name": "preview",
+          "file": "workflows/preview.md"
+        },
+        {
+          "name": "quality-gate",
+          "file": "workflows/quality-gate.md"
+        },
+        {
+          "name": "retrospective",
+          "file": "workflows/retrospective.md"
+        },
+        {
+          "name": "review",
+          "file": "workflows/review.md"
+        },
+        {
+          "name": "status",
+          "file": "workflows/status.md"
+        },
+        {
+          "name": "test",
+          "file": "workflows/test.md"
+        },
+        {
+          "name": "ui-ux-pro-max",
+          "file": "workflows/ui-ux-pro-max.md"
+        },
+        {
+          "name": "upgrade",
+          "file": "workflows/upgrade.md"
+        }
+      ]
+    },
+    "rules": {
+      "count": 10,
+      "items": [
+        {
+          "name": "agent-upgrade-policy",
+          "file": "rules/agent-upgrade-policy.md"
+        },
+        {
+          "name": "architecture",
+          "file": "rules/architecture.md"
+        },
+        {
+          "name": "coding-style",
+          "file": "rules/coding-style.md"
+        },
+        {
+          "name": "documentation",
+          "file": "rules/documentation.md"
+        },
+        {
+          "name": "git-workflow",
+          "file": "rules/git-workflow.md"
+        },
+        {
+          "name": "quality-gate",
+          "file": "rules/quality-gate.md"
+        },
+        {
+          "name": "security",
+          "file": "rules/security.md"
+        },
+        {
+          "name": "sprint-tracking",
+          "file": "rules/sprint-tracking.md"
+        },
+        {
+          "name": "testing",
+          "file": "rules/testing.md"
+        },
+        {
+          "name": "workflow-standards",
+          "file": "rules/workflow-standards.md"
+        }
+      ]
+    },
+    "checklists": {
+      "count": 4,
+      "items": [
+        {
+          "name": "pre-commit",
+          "file": "checklists/pre-commit.md"
+        },
+        {
+          "name": "session-start",
+          "file": "checklists/session-start.md"
+        },
+        {
+          "name": "session-end",
+          "file": "checklists/session-end.md"
+        },
+        {
+          "name": "task-complete",
+          "file": "checklists/task-complete.md"
+        }
+      ]
+    },
+    "hooks": {
+      "count": 8,
+      "items": [
+        {
+          "name": "session-start",
+          "event": "session-start"
+        },
+        {
+          "name": "session-end",
+          "event": "session-end"
+        },
+        {
+          "name": "pre-commit",
+          "event": "pre-commit"
+        },
+        {
+          "name": "secret-detection",
+          "event": "secret-detection"
+        },
+        {
+          "name": "phase-transition",
+          "event": "phase-transition"
+        },
+        {
+          "name": "sprint-checkpoint",
+          "event": "sprint-checkpoint"
+        },
+        {
+          "name": "plan-complete",
+          "event": "plan-complete"
+        },
+        {
+          "name": "task-complete",
+          "event": "task-complete"
+        }
+      ]
+    }
+  }
+}

package/.agent/rules/agent-upgrade-policy.md

@@ -0,0 +1,56 @@
+# Agent Upgrade Policy
+
+> **Priority**: CRITICAL — Inviolable
+> **Scope**: All AI Agent interactions related to framework initialization, upgrading, and state mutation.
+
+---
+
+## 1. The Preservation Contract
+
+The Devran AI Kit exists organically alongside user code. User customizations must survive framework upgrades.
+
+The following files and directories are **STRICTLY PROTECTED**:
+
+| Protected Item | Type | Reason |
+| :--- | :--- | :--- |
+| `.agent/session-state.json` | File | Active session metadata |
+| `.agent/session-context.md` | File | Session narrative context |
+| `.agent/identity.json` | File | User/project identity (may contain PII) |
+| `.agent/rules/` | Directory | User-customized governance rules |
+| `.agent/checklists/` | Directory | User-customized quality gates |
+| `.agent/decisions/` | Directory | Architecture Decision Records |
+| `.agent/contexts/` | Directory | Learning data and plan quality logs |
+
+This is the **canonical list**. The `/upgrade` workflow references this list — do not duplicate or abbreviate it elsewhere.
+
+---
+
+## 2. Non-Destructive Upgrades Only
+
+| Command | Purpose | Safety |
+| :--- | :--- | :--- |
+| `kit update` | Non-destructive AST merger | Safe — preserves protected items |
+| `kit update --dry-run` | Preview upgrade changes | Safe — read-only |
+| `init --force` | Catastrophic repair | **DESTRUCTIVE** — wipes protected items |
+
+- **Mandated**: Use `kit update` for all routine upgrades
+- **Prohibited**: Never use `init --force` for routine upgrades. This is a last-resort catastrophic repair command that wipes protected files
+
+---
+
+## 3. Upgrade Governance
+
+The `/upgrade` workflow follows the standard EWS v1.0 governance model:
+
+- **Human confirmation required** before executing `kit update`
+- **Post-upgrade verification** via `kit verify` is mandatory
+- **Preservation verification** — all 7 protected items must be confirmed intact after upgrade
+- **Rollback available** — `git checkout -- .agent/` restores pre-upgrade state if uncommitted
+
+---
+
+## Related Resources
+
+- **Workflow**: `.agent/workflows/upgrade.md` (`/upgrade`)
+- **Skill**: `.agent/skills/verification-loop/SKILL.md`
+- **See also**: `.agent/rules/security.md` (secrets in upgrade payloads), `.agent/rules/git-workflow.md` (commit conventions after upgrade)