Skip to content

Getting Started

Get up and running with Devran AI Kit in 30 seconds.

⚡ Quick Start

npx @devran-ai/kit init

This automatically copies the .agent/ folder to your project and adds it to .gitignore. Done!

Note: .agent/ is gitignored by default — it's personal dev tooling. For team-wide sharing, use kit init --shared.

Warning: npx @devran-ai/kit init --force is a Catastrophic Repair command. It will overwrite your customizations and session state. Do not use it for regular updates.

🔄 Updating

AI Agents and Users MUST use kit update for standard framework upgrades. This is a non-destructive AST merger.

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

Preservation Contract: The kit update command explicitly protects your customized .agent/rules/, .agent/checklists/, session-state.json, session-context.md, identity.json, and ADR files.

Option 2: Manual Installation

# 1. Clone the repository
git clone https://github.com/devran-ai/kit.git

# 2. Copy .agent/ to your project
cp -r kit/.agent/ your-project/.agent/

# 3. Start your session
/project-status

✅ Verify Installation

After installing, validate your setup with the built-in CLI checks:

kit verify     # Manifest integrity check
kit scan       # Security scan

Both should return clean results. If they report issues, refer to the troubleshooting guide or run kit update to repair missing core dependencies.

Safety Guarantees

Devran AI Kit only operates within the .agent/ directory. Your project files — source code, configs, tests, platform files — are never touched by init, update, or any CLI command.

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
  • decisions/ — Your Architecture Decision Records
  • contexts/ — Your learning data and plan quality logs
  • rules/ — Your custom governance rules
  • checklists/ — Your custom quality gates

Gitignore Management

kit init automatically configures .gitignore to keep all generated artifacts local:

Entry Purpose
.agent/ Framework directory
.claude/commands/ Claude Code slash command bridges
.cursor/commands/ Cursor slash command bridges
.cursor/rules/ Cursor governance config
.opencode/commands/ OpenCode slash command bridges
.codex/ Codex config
.worktreeinclude Worktree support config

kit update also runs the full gitignore pipeline — if you upgrade from an older Kit version, missing entries are added automatically.

Blanket .claude/ pattern: If your .gitignore has a blanket .claude/ entry (which breaks Claude CLI slash command discovery), Kit automatically narrows it to .claude/commands/.

Auto-untrack (v5.2.8+)

If Kit artifacts were accidentally committed to your repo before .gitignore was configured (e.g. an agent ran git add -A too early), kit init and kit update will actively remove them from the git index while keeping working-tree copies intact. You only need to commit the resulting index changes.

The auto-untrack covers: - .agent/ — framework directory - .claude/commands/, .cursor/commands/, .opencode/commands/, .windsurf/workflows/, .github/prompts/ — bridge files - .cursor/rules/kit-governance.mdc, .opencode/opencode.json, .codex/instructions.md — IDE configs (specific Kit-written files only; user-authored files under the same parent dirs are left alone) - .worktreeinclude — worktree support - dev/null/ — Windows literal-path artifact created when git config core.hooksPath dev/null is run without a leading slash

The cleanup uses git rm -r --cached under the hood — no working-tree files are ever deleted. A two-gate safety net protects user data: (1) git check-ignore --no-index verifies each path is actually in your .gitignore before touching it, and (2) kit update detects shared mode (.agent/ intentionally committed with your team via kit init --shared) and skips the entire gitignore pipeline for those projects.

Worktree Support

Kit works seamlessly with git worktree — both Claude Code worktrees and manual git worktree add:

  • Claude Code worktrees — A .worktreeinclude file tells Claude Code to copy .agent/ and bridge directories into new worktrees automatically.
  • Manual worktrees — A post-checkout git hook copies .agent/ from the main worktree and regenerates bridge files. User customizations (decisions, rules, identity) are preserved.

Both are installed automatically by kit init. To skip: kit init --skip-worktree.

Cross-IDE Bridge Generation

kit init auto-detects your IDE and generates native slash command bridges:

IDE Bridge Location Auto-Detected?
Claude Code .claude/commands/*.md Always
Cursor .cursor/commands/*.md Yes
OpenCode .opencode/commands/*.md Yes
Windsurf .windsurf/workflows/*.md Yes
VS Code Copilot .github/prompts/*.prompt.md Opt-in (--ide vscode)

Bridge files include a provenance header so kit update only overwrites Kit-generated files, never your custom commands. See IDE Support for details.

First Session

  1. Open your project in your AI-powered IDE (VS Code, Cursor, Windsurf, etc.)
  2. Run the status command:
/project-status

You should see:

📊 Session Status
├── Active: Yes
├── Context: Loaded
└── Ready for commands

Basic Workflow

1. Plan Your Feature

/plan Add user authentication

The Planner agent creates a validated implementation plan with quality scoring, cross-cutting concerns (security, testing, documentation), and tiered detail based on task complexity.

2. Review the Plan

Review the generated plan in your working directory.

3. Implement

/implement

4. Verify

/verify

Runs all quality gates: build, lint, test, coverage.

Session Management

Devran AI Kit includes a Session Management Architecture that ensures continuity across work sessions.

Component Purpose Location
Session Context Live session state, resumable .agent/session-context.md
Session Start Checklist Pre-flight verification .agent/checklists/session-start.md
Session End Checklist Wrap-up and handoff .agent/checklists/session-end.md
Pre-Commit Checklist Quality gate before commits .agent/checklists/pre-commit.md

Starting a session: Follow the session-start checklist. The AI loads previous context, verifies git status, checks dependencies, and resumes from the last open task.

Ending a session: Follow the session-end checklist. The AI updates session-context.md, documents open items, commits changes, and creates handoff notes.

Next Steps