Devran AI Kit

Trust-Grade AI Development Framework — Zero dependencies. 26 agents. 39 skills. 25 workflows. 15 rules. One command.

Why Devran AI Kit?

• Not a prompt collection — 41-module zero-dependency runtime engine with workflow state machine, circuit breaker, error budget, and self-healing CI
• Trust-grade governance — 15 governance rules (including Performance, Accessibility, Data Privacy, Market Awareness, Doc Freshness) enforced through a 7-phase SDLC with Scope Filters, Ethics Gates, Rigor Profiles (strict/standard/minimal), and Failure Templates on every workflow
• Intelligent agent system — 26 specialized agents with reputation scoring, domain-aware routing, Instinct System (confidence-scored pattern memory), and on-demand loading via keyword matching
• Project onboarding — /greenfield and /brownfield workflows generate master documentation (15 templates), market research, architecture diagrams, and Kit configuration from a single Socratic discovery session
• Telegram integration — Control your Claude Code session from your phone. Trigger workflows, review PRs, and deploy — all from a Telegram chat
• Cross-IDE support — One kit init configures Claude Code, Antigravity, Cursor, OpenCode, and Codex from a single manifest source of truth

Comparison

| Capability | Prompt Files | Rule Collections | Devran AI Kit | |---|---|---|---| | Agent orchestration | Manual | Manual | 26 agents with reputation scoring | | Project onboarding | None | None | /greenfield + /brownfield with 15 master templates | | Workflow governance | None | None | 7-phase SDLC state machine | | Session persistence | None | None | Full state across restarts | | Self-healing CI | None | None | Auto-diagnoses and patches failures | | Cross-IDE support | Single IDE | Single IDE | 5 IDEs from one source of truth | | Plugin marketplace | None | None | Trust-verified skill marketplace | | Telegram control | None | None | Full IDE control from your phone | | Test suite | None | None | 940 tests with security validation | | Runtime dependencies | Varies | Varies | Zero |

Quick Start

Option 1: Create New Project (Recommended)

npx create-kit-app my-project
npx create-kit-app my-api --template node-api
npx create-kit-app my-app --template nextjs

Creates a new project with .agent/ pre-configured. Templates: minimal, node-api, nextjs.

Option 2: Add to Existing Project

npx @devran-ai/kit init

How It Works in Teams

Devran AI Kit is personal developer tooling — like your IDE settings. kit init adds .agent/ to .gitignore by default so it stays local.

| Mode | Command | Behavior | |------|---------|----------| | Personal (default) | kit init | .agent/ gitignored — local only | | Team (opt-in) | kit init --shared | .agent/ committed — shared with team |

Your project's CLAUDE.md remains the single source of truth. The kit enhances your personal workflow without affecting teammates. Anyone who wants it runs npx @devran-ai/kit init.

Updating

kit update              # Non-destructive — preserves your customizations
kit update --dry-run    # Preview changes without applying

Prefer kit update over kit init --force. The update command preserves your session data, ADRs, learning contexts, and customizations. Use init --force only for clean reinstalls.

Verify Installation

kit verify    # Manifest integrity check
kit scan      # Security scan

Architecture

| Component | Count | Purpose | |---|---|---| | Agents | 26 | Specialized AI agents with reputation scoring and domain routing | | Skills | 39 | Domain knowledge modules loaded on demand via keyword matching | | Commands | 40 | Slash commands for IDE interaction (/plan, /greenfield, /deploy) | | Workflows | 25 | Process templates with quality gates, scope filters, and phase enforcement | | Runtime Modules | 41 | Engine components (state machine, circuit breaker, plugin system, onboarding engine) | | Rules | 15 | Governance constraints (security, performance, accessibility, market-awareness, and more) | | Checklists | 4 | Verification checklists (pre-commit, task-complete, session-start, session-end) | | Hooks | 9 | Lifecycle events (session start/end, phase transition, onboarding complete) |

Workflow State Machine

IDLE -> ONBOARDING -> EXPLORE -> PLAN -> IMPLEMENT -> VERIFY -> CHECKPOINT -> REVIEW -> DEPLOY
         (one-time)

Onboarding (/greenfield or /brownfield) is a one-time pre-SDLC phase. Each subsequent phase requires explicit developer approval before transitioning. The engine enforces governance rules and tracks session state across restarts.

What's New

See the full CHANGELOG for detailed release notes.

Latest (v5.1.0): Onboarding Workflow System — /greenfield and /brownfield commands for project initialization with Socratic discovery, market research (T1-T5 evidence), 15 master document templates, Mermaid architecture diagrams, quality scoring (0-100), and Kit auto-configuration. 3 new agents, 3 new skills, 2 cross-cutting rules, decision memory with /decisions command, stealth mode, 3 interaction modes (IDE/Telegram/CI), checkpoint-based resumption; 940 tests passing.

Cross-IDE Support

| IDE | Config Path | Format | |---|---|---| | Claude Code | .agent/ | Native | | Antigravity | .agent/ | Native | | Cursor | .cursor/rules/ | YAML frontmatter + Markdown | | OpenCode | .opencode/ | JSON | | Codex | .codex/ | TOML |

All generated automatically by kit init.

CLI Reference

| Command | Description | Key Flags | |---|---|---| | kit init | Install .agent/ framework into project | --force, --path <dir> | | kit update | Non-destructive framework update | --dry-run | | kit status | Dashboard with capabilities and metrics | — | | kit verify | Manifest integrity and structure checks | — | | kit scan | Security scan (secrets, injection patterns) | — | | kit plugin | Plugin management | list, install, remove | | kit market | Marketplace integration | search, info, install | | kit heal | CI failure detection and auto-fix | --file <path>, --apply | | kit health | Aggregated health check | — | | kit sync-bot-commands | Sync workflows to Telegram bot menu (all scopes) | --scope, --token, --dry-run, --clear, --limit, --source, --guard, --install-guard |

Safety Guarantees

Devran AI Kit is designed to never touch your project files. All operations are scoped to the .agent/ directory.

| Your Project Files | Safe? | Details | |---|---|---| | Source code (src/, lib/, app/) | Never touched | Init/update only operates on .agent/ | | Config files (.env, package.json) | Never touched | No project config is read or written | | Documentation (docs/, README.md) | Never touched | Only .agent/ docs are managed | | Tests (tests/, __tests__/) | Never touched | Kit tests are internal to the package | | Platform files (android/, ios/) | Never touched | No platform-specific operations |

init --force safety features:

• Auto-backup — Creates timestamped backup of existing .agent/ before overwriting
• Atomic copy — Uses temp directory + rename to prevent corruption on failure
• Symlink guard — Skips symbolic links to prevent path traversal attacks
• Session warning — Alerts if active work-in-progress would be destroyed
• Dry-run preview — --dry-run --force shows exactly which user files would be overwritten

update preserved files:

• session-context.md — Your active session notes
• session-state.json — Your session metadata
• engine/onboarding-state.json — Your onboarding progress
• engine/decisions.json — Your architectural decisions
• decisions/ — Your Architecture Decision Records
• contexts/ — Your learning data and plan quality logs
• rules/ — Your custom governance rules
• checklists/ — Your custom quality gates
• staging/ — In-progress document generation

Agents (26)

| Category | Agents | |---|---| | Onboarding | Onboarding Specialist, Market Researcher, Codebase Scanner | | Core Development | Architect, Code Reviewer, TDD Guide, Planner | | Language Reviewers | TypeScript Reviewer, Python Reviewer, Go Reviewer | | Domain Specialists | Frontend Specialist, Backend Specialist, Mobile Developer, Database Architect, DevOps Engineer | | Quality & Security | Security Reviewer, E2E Runner, Performance Optimizer, Reliability Engineer | | Support & Intelligence | Doc Updater, Build Error Resolver, Refactor Cleaner, Explorer Agent, Knowledge Agent | | Autonomy | PR Reviewer, Sprint Orchestrator |

Operating Constraints

| Principle | Description | |---|---| | Trust > Optimization | User trust is never sacrificed for metrics | | Safety > Growth | User safety overrides business goals | | Explainability > Performance | Understandable AI beats faster AI | | Completion > Suggestion | Finish current work before proposing new | | Consistency > Speed | All affected files updated, not just target |

Repository Structure

kit/
├── .agent/                 # Framework directory (installed to projects)
│   ├── agents/             # 26 specialized agent definitions
│   ├── skills/             # 39 domain knowledge modules
│   ├── commands/           # 40 slash command definitions
│   ├── workflows/          # 25 workflow templates
│   ├── rules/              # 15 governance constraints
│   ├── checklists/         # 4 lifecycle quality gates
│   ├── engine/             # Runtime config (loading-rules, MCP templates)
│   ├── decisions/          # Architecture Decision Records
│   └── manifest.json       # Definitive capability inventory
├── lib/                    # 41 runtime modules (zero dependencies)
├── bin/kit.js              # CLI entry point
├── create-kit-app/         # Project scaffolder
├── docs/                   # MkDocs documentation site
├── examples/               # Starter examples (minimal, full-stack)
└── tests/                  # 940 tests (unit, structural, integration, security)

Security

Secret detection covers API keys, tokens, AWS credentials, and private keys. The scanner checks for prompt injection patterns, path traversal attempts, and symlink abuse. Plugins are verified with SHA-256 checksums before installation.

Telegram Integration

Run your entire development workflow from your phone. Devran AI Kit turns any Telegram chat into a full Claude Code remote control.

You (Telegram)  ──>  Bot  ──>  Claude Code  ──>  Bot  ──>  You (Telegram)

| What you can do | How | |---|---| | Trigger any workflow | Type / in the chat — all 25 workflows appear as a native bot menu | | Plan a feature | /plan auth system — bot executes immediately | | Review a PR | /pr-review PR #5 — multi-perspective review runs | | Deploy to production | /deploy staging — pre-flight checks + deploy | | Check project status | /project-status — instant overview | | Debug an issue | /debug login page crashes on mobile |

Smart argument handling — Send /plan alone and the bot asks what you need. Send /plan auth system and it executes directly. No extra steps.

Menu guard — The bot menu auto-restores on every session. Your 25 workflows are always one tap away.

Get started

kit sync-bot-commands                  # Push workflows to bot menu
kit sync-bot-commands --install-guard  # Keep menu persistent across sessions

Full setup guide — Create a bot, install the plugin, pair your account, and start using workflows from Telegram in under 5 minutes.

Documentation

Full documentation: devran-ai.github.io/kit

Contributing

Fork the repo, create a feature branch, add tests, and open a PR. See CONTRIBUTING.md for branch strategy and code standards.

git clone https://github.com/devran-ai/kit.git
cd kit && npm install && npm test

Author

Emre Dursun — LinkedIn · GitHub

License

MIT