@devran-ai/kit 4.1.0

package/.agent/checklists/pre-commit.md

@@ -0,0 +1,93 @@
+# Pre-Commit Checklist
+
+> **Framework**: Devran AI Kit
+> **Purpose**: Quality gate before committing code  
+> **Principle**: Prevention over correction
+
+---
+
+## 🔍 Code Quality
+
+- [ ] **No debug code left**
+  - No `console.log` statements (unless intentional)
+  - No `debugger` statements
+  - No commented-out code blocks
+- [ ] **Code is self-documenting**
+  - Clear variable/function names
+  - Complex logic has comments explaining WHY
+
+---
+
+## 🧪 Testing
+
+- [ ] **All tests pass**
+  ```bash
+  npm test
+  ```
+- [ ] **New code has tests** (when applicable)
+- [ ] **Coverage maintained or improved**
+
+---
+
+## 🔨 Build & Lint
+
+- [ ] **TypeScript compiles**
+  ```bash
+  npm run build
+  ```
+- [ ] **Linting passes**
+  ```bash
+  npm run lint
+  ```
+- [ ] **Formatting correct**
+  ```bash
+  npm run format
+  ```
+
+---
+
+## 🔐 Security
+
+- [ ] **No secrets in code**
+  - No API keys
+  - No passwords
+  - No tokens
+- [ ] **Dependencies secure**
+  ```bash
+  npm audit
+  ```
+
+---
+
+## 📋 Commit Message
+
+Follow conventional commits format:
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+**Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `ci`
+
+**Examples**:
+
+```bash
+git commit -m "feat(auth): add JWT refresh token support"
+git commit -m "fix(api): handle null user in profile endpoint"
+git commit -m "docs(readme): add installation instructions"
+```
+
+---
+
+## ✅ Ready to Commit
+
+All checks passed? Proceed with:
+
+```bash
+git add -A
+git commit -m "<type>(<scope>): <description>"
+```

package/.agent/checklists/session-end.md

@@ -0,0 +1,99 @@
+# Session End Checklist
+
+> **Framework**: Devran AI Kit
+> **Purpose**: Complete this checklist before ending any work session  
+> **Principle**: Context preservation for continuity
+
+---
+
+## 📝 Context Preservation
+
+- [ ] **session-context.md** updated with:
+  - What was accomplished
+  - Open items and next steps
+  - Any blockers discovered
+- [ ] **session-state.json** updated
+  - ⚠️ **Volatile-only metadata**: Only update machine-readable fields (lastCommit, currentTask, status). Never track task progress here.
+
+---
+
+## 📋 Sprint State Sync
+
+- [ ] **docs/ROADMAP.md** updated:
+  - Completed items marked `[x]`
+  - In-progress items marked `[/]`
+  - New discovered items added under appropriate section
+- [ ] **docs/CHANGELOG.md** synced with shipped work from this session
+- [ ] **Duplicate tracking prevention**:
+  - [ ] No task status tracked outside ROADMAP.md
+  - [ ] No duplicate entries between ROADMAP ↔ CHANGELOG ↔ session-context
+- [ ] **Sync verification**: ROADMAP.md ↔ session-context.md ↔ session-state.json reflect same state
+
+---
+
+## 📊 Progress Documentation
+
+- [ ] **README.md** or docs updated (if needed)
+- [ ] **CHANGELOG.md** updated (if release-worthy changes)
+- [ ] **ADRs created** for significant decisions
+  - Use `/adr` command for new decisions
+
+---
+
+## 🔍 Quality Verification
+
+- [ ] **All tests pass**
+  ```bash
+  npm test
+  ```
+- [ ] **Build succeeds**
+  ```bash
+  npm run build
+  ```
+- [ ] **Linting clean**
+  ```bash
+  npm run lint
+  ```
+
+---
+
+## 📦 Git Status
+
+- [ ] **All changes committed**
+  ```bash
+  git status  # Should be clean
+  ```
+- [ ] **Commit messages follow convention**
+  ```
+  feat(scope): description
+  fix(scope): description
+  docs(scope): description
+  ```
+- [ ] **Pushed to remote**
+  ```bash
+  git push origin [branch]
+  ```
+
+---
+
+## 🔄 Handoff Preparation
+
+If another session will continue this work:
+
+- [ ] Clear **Next Steps** documented in session-context.md
+- [ ] **Blockers** clearly identified
+- [ ] Required **context files** listed
+- [ ] Any **environment changes** noted
+
+---
+
+## ✅ Session Complete
+
+**Final commit convention:**
+
+```bash
+git commit -m "chore(session): end session - [summary]"
+git push origin [branch]
+```
+
+Session can now be safely ended.

package/.agent/checklists/session-start.md

@@ -0,0 +1,102 @@
+# Session Start Checklist
+
+> **Framework**: Devran AI Kit
+> **Purpose**: Complete this checklist at the beginning of every work session  
+> **Principle**: Full context before new work
+
+---
+
+## 🔄 Context Loading
+
+- [ ] **session-context.md** loaded
+  - Last session summary reviewed
+  - Open items identified
+  - Handoff context verified (not just session-end boilerplate)
+- [ ] **session-state.json** loaded
+  - Last commit verified
+  - Current task identified
+  - **Staleness check**: Compare `lastCommit` with `git log --oneline -1` — if diverged, flag to user
+- [ ] **rules.md** loaded (if project has one)
+  - Project-specific rules acknowledged
+
+---
+
+## 📋 Sprint State Validation
+
+- [ ] **docs/ROADMAP.md** loaded (SSOT for sprint tracking)
+  - Current sprint identified
+  - In-progress `[/]` items from last session reviewed
+  - Completed `[x]` items acknowledged
+- [ ] **Sprint state presented** to user before starting work
+  - Summary of where we left off
+  - Proposed next items to work on
+- [ ] **docs/ARCHITECTURE.md** reviewed for structural context
+- [ ] **docs/CHANGELOG.md** reviewed for recent shipped work
+
+---
+
+## 📂 Project State
+
+- [ ] **Git status** clean or understood
+  ```bash
+  git status
+  git branch
+  ```
+- [ ] **Dependencies** up to date
+  ```bash
+  npm install  # or pnpm install
+  ```
+- [ ] **Build** passes
+  ```bash
+  npm run build
+  ```
+
+---
+
+## 🎯 Task Context
+
+Based on task type, load relevant context:
+
+**For Feature Work:**
+
+- [ ] Requirements document located
+- [ ] Related existing code identified
+- [ ] Test strategy understood
+
+**For Bug Fixes:**
+
+- [ ] Bug reproduction steps known
+- [ ] Related logs/errors reviewed
+- [ ] Affected code paths identified
+
+**For Refactoring:**
+
+- [ ] Scope of changes understood
+- [ ] Test coverage verified
+- [ ] Rollback plan considered
+
+---
+
+## ⚡ Quick Verification
+
+- [ ] Development server starts
+  ```bash
+  npm run dev
+  ```
+- [ ] Tests pass
+  ```bash
+  npm test
+  ```
+- [ ] No critical errors in console
+
+---
+
+## ✅ Ready State
+
+After completing this checklist:
+
+1. ✅ Context fully loaded
+2. ✅ Environment verified
+3. ✅ Ready to begin task
+
+**Proceed with**: `/plan` or `/implement`

package/.agent/checklists/task-complete.md

@@ -0,0 +1,81 @@
+# Task-Complete Checkpoint
+
+> **Framework**: Devran AI Kit
+> **Purpose**: Decision gate after task completion — present options before commit/push
+> **Principle**: Human-in-the-loop governance
+
+---
+
+## 🎯 Trigger Condition
+
+This checkpoint activates when:
+- Implementation work is complete AND quality gates have passed (VERIFY → CHECKPOINT transition)
+- The agent has made code changes that are ready for commit
+
+This checkpoint does NOT activate when:
+- The developer has explicitly enabled "skip checkpoint" mode for the session
+- The change is docs-only or config-only (handled by commit-type scoping)
+
+---
+
+## 📋 Decision Prompt
+
+Present these options to the developer:
+
+| # | Action | Command | When to Recommend |
+|:--|:-------|:--------|:-----------------|
+| 1 | 🔍 Quality Review | `/review` | ✅ Always (if not already run) |
+| 2 | 🛡️ Retrospective Audit | `/retrospective` | Sprint-end or milestone |
+| 3 | 📋 Update Tracking | Manual | ✅ Always |
+| 4 | 📦 Commit & Push | `git commit + push` | After review passes |
+| 5 | 🔀 Pull Request | `/pr` | Feature branch with commits |
+| 6 | 🔚 Session-End | Protocol | End of work session |
+| 7 | 🚀 Deploy | `/deploy` | Production-impacting changes |
+| 8 | 📝 Continue Working | Skip commit | Batching multiple changes |
+| 9 | ⏭️ Skip Checkpoint | Session flag | Rapid iteration mode |
+
+**Prompt format:**
+
+```
+How should we proceed?
+
+1. 🔍 /review — Run quality gates (lint, type-check, test, security, build)
+2. 🛡️ /retrospective — Tier-1 audit (architecture, market benchmark, ethics)
+3. 📋 Update tracking — Sync ROADMAP.md, session-context.md, session-state.json
+4. 📦 Commit & push — Stage, commit (conventional), push to remote
+5. 🔀 /pr — Create pull request with pre-flight checks and CI verification
+6. 🔚 Session-end protocol — Preserve context and prepare for handoff
+7. 🚀 /deploy — Production deployment with pre-flight checks
+8. 📝 Continue working — Proceed to next task without committing
+9. ⏭️ Skip checkpoint — Disable checkpoint for remainder of session
+
+> Choose options (e.g., "1, 3, 4" or "1 through 5"):
+```
+
+---
+
+## 🧠 Recommendation Intelligence
+
+Dynamically adjust recommendations based on:
+
+- [ ] **Sprint boundary**: If ROADMAP shows sprint ending → recommend `/retrospective`
+- [ ] **Production files**: If `apps/api/**` or `apps/web/**` changed → recommend `/deploy`
+- [ ] **Session duration**: If >2 hours of work → recommend session-end
+- [ ] **File count**: If >5 files changed → recommend atomic commit review
+- [ ] **New code without tests**: Flag with ⚠️ if test coverage gap detected
+- [ ] **Security-sensitive**: If auth/crypto/token files changed → recommend `/review security`
+- [ ] **Feature branch**: If on feature branch with unpushed commits → recommend `/pr`
+
+---
+
+## 🔒 Governance
+
+**PROHIBITED:**
+- Committing or pushing without presenting this checkpoint
+- Auto-selecting options without developer input
+- Skipping this checkpoint for session-end commits
+
+**REQUIRED:**
+- Present decision prompt after every task completion
+- Wait for explicit developer response
+- Log the developer's choice for session audit trail

package/.agent/commands/README.md

@@ -0,0 +1,130 @@
+# Devran AI Kit — Commands
+
+> **Purpose**: Slash commands for quick access to common operations
+> **Count**: 37 Commands
+
+---
+
+## Overview
+
+Commands are quick invocations that trigger specific actions or workflows. Type `/command-name` in chat to use.
+
+---
+
+## Command Categories
+
+### Core Workflow
+
+| Command      | Description                |
+| :----------- | :------------------------- |
+| `/plan`      | Create implementation plan |
+| `/implement` | Execute the approved plan  |
+| `/verify`    | Run all quality gates      |
+| `/status`    | Check project status       |
+
+### Development
+
+| Command     | Description                        |
+| :---------- | :--------------------------------- |
+| `/build`    | Build a new feature from scratch   |
+| `/fix`      | Fix linting, type, or build errors |
+| `/debug`    | Systematic debugging process       |
+| `/refactor` | Improve code quality               |
+| `/cook`     | Full scratch-to-done workflow      |
+
+### Documentation & Git
+
+| Command      | Description                         |
+| :----------- | :---------------------------------- |
+| `/doc`       | Generate documentation              |
+| `/adr`       | Create Architecture Decision Record |
+| `/changelog` | Generate changelog from commits     |
+| `/git`       | Git operations with best practices  |
+| `/pr`        | Create production-grade pull requests |
+
+### PR Toolkit
+
+| Command        | Description                                     |
+| :------------- | :---------------------------------------------- |
+| `/pr-review`   | Review a PR with senior engineering expertise    |
+| `/pr-fix`      | Fix PR issues based on review comments           |
+| `/pr-merge`    | Merge PR safely with dependency validation       |
+| `/pr-split`    | Split oversized PRs into focused sub-PRs         |
+| `/pr-status`   | Triage PRs with CI, staleness, and merge readiness |
+| `/pr-describe` | Auto-generate PR title, summary, and labels      |
+
+### Exploration & Research
+
+| Command     | Description                        |
+| :---------- | :--------------------------------- |
+| `/scout`    | Explore and understand codebase    |
+| `/research` | Research technologies or solutions |
+| `/ask`      | Ask questions about code           |
+
+### Quality & Security
+
+| Command          | Description                           |
+| :--------------- | :------------------------------------ |
+| `/code-review`   | Run code review                       |
+| `/tdd`           | Test-driven development workflow      |
+| `/security-scan` | Security audit and vulnerability scan |
+| `/perf`          | Performance analysis and optimization |
+
+### Integration & Deployment
+
+| Command      | Description                     |
+| :----------- | :------------------------------ |
+| `/integrate` | Third-party service integration |
+| `/db`        | Database schema and migrations  |
+| `/deploy`    | Deploy to target environment    |
+| `/design`    | UI/UX design specifications     |
+
+### Context Management
+
+| Command       | Description                   |
+| :------------ | :---------------------------- |
+| `/learn`      | Extract patterns from session |
+| `/checkpoint` | Save progress checkpoint      |
+| `/compact`    | Compress context for memory   |
+| `/eval`       | Evaluate metrics              |
+| `/setup`      | Configure project with kit    |
+| `/help`       | Show available commands       |
+
+---
+
+## Command Format
+
+```markdown
+---
+description: What this command does
+---
+
+# /command-name Command
+
+Brief description.
+
+## Usage
+
+\`\`\`
+/command-name [options]
+\`\`\`
+
+## Examples
+
+\`\`\`
+/command-name example usage
+\`\`\`
+
+## Process
+
+1. Step 1
+2. Step 2
+```
+
+---
+
+## Creating Custom Commands
+
+1. Create `commands/my-command.md`
+2. Add frontmatter with `description`
+3. Define usage, examples, and process

package/.agent/commands/adr.md

@@ -0,0 +1,29 @@
+---
+description: Create an Architecture Decision Record
+---
+
+# /adr Command
+
+Document an architecture decision.
+
+## Usage
+
+```
+/adr <decision>
+```
+
+## Examples
+
+```
+/adr Use PostgreSQL over MySQL
+/adr Adopt NestJS for backend
+/adr Choose React Query for server state
+```
+
+## ADR Format
+
+- **Title**: Decision name
+- **Status**: Proposed/Accepted/Deprecated
+- **Context**: Why this decision is needed
+- **Decision**: What we decided
+- **Consequences**: Implications

package/.agent/commands/ask.md

@@ -0,0 +1,28 @@
+---
+description: Ask questions about the codebase
+---
+
+# /ask Command
+
+Ask questions about code, architecture, or patterns.
+
+## Usage
+
+```
+/ask <question>
+```
+
+## Examples
+
+```
+/ask How does authentication work?
+/ask What's the database schema?
+/ask Where is payment processing handled?
+```
+
+## Capabilities
+
+- Code explanation
+- Architecture overview
+- Pattern identification
+- Dependency analysis

package/.agent/commands/build.md

@@ -0,0 +1,30 @@
+---
+description: Build a new feature or module from scratch
+---
+
+# /build Command
+
+Execute a comprehensive build workflow for a new feature.
+
+## Usage
+
+```
+/build <feature description>
+```
+
+## Examples
+
+```
+/build user authentication with JWT
+/build product catalog with search
+/build payment integration with Stripe
+```
+
+## Process
+
+1. Analyze requirements
+2. Design architecture
+3. Create file structure
+4. Implement core logic
+5. Add tests
+6. Document usage

package/.agent/commands/changelog.md

@@ -0,0 +1,40 @@
+---
+description: Generate changelog from commits
+---
+
+# /changelog Command
+
+Generate or update changelog from git history.
+
+## Usage
+
+```
+/changelog             # Generate from recent commits
+/changelog <version>   # Changelog for specific version
+```
+
+## Examples
+
+```
+/changelog
+/changelog v1.2.0
+/changelog since last release
+```
+
+## Output Format
+
+```markdown
+## [1.2.0] - 2026-02-06
+
+### Added
+
+- New user profile feature
+
+### Changed
+
+- Updated authentication flow
+
+### Fixed
+
+- Login error handling
+```

package/.agent/commands/checkpoint.md

@@ -0,0 +1,28 @@
+---
+description: Save a checkpoint for later recovery
+---
+
+# /checkpoint Command
+
+Create a save point for your work.
+
+## Usage
+
+```
+/checkpoint <name>     # Create named checkpoint
+/checkpoint restore    # List and restore checkpoints
+```
+
+## Examples
+
+```
+/checkpoint before-refactor
+/checkpoint auth-complete
+/checkpoint restore
+```
+
+## Purpose
+
+- Save progress before risky changes
+- Enable easy rollback
+- Track work milestones