kodro 2.1.0

One-Command Spec-Driven Development Engine

Kodro: Production-Ready AI Development Framework

Transform natural language prompts into production software with an intelligent 6-phase pipeline. Kodro is a prompt engineering framework that delivers token-efficient, spec-driven development for AI agents—reducing costs by 84% while maintaining production quality.

One command. Six phases. Production-ready code.

[!NOTE] Beta Software: Kodro is in active development. You may encounter bugs, incomplete features, or breaking changes. Please report issues at GitHub Issues.

[!TIP] New to Kodro? Start with the Getting Started Guide. For detailed configuration options see Configuration. For a deep dive into the pipeline phases see Pipeline.

---

Table of Contents

• What is Kodro?
• Why Kodro?
• Quick Start
• How It Works
• Token Efficiency Architecture
• Features
• Use Cases
• Post-Delivery Changes
• Supported AI Agents
• CLI Commands
• Comparison

---

What is Kodro?

Kodro is an AI development framework that transforms a single natural language prompt into production software through a 6-phase Spec-Driven Development (SDD) pipeline. Built for AI agents like Claude, Cursor, OpenCode, and GitHub Copilot, Kodro brings structure, quality control, and massive token savings to LLM-powered development.

Unlike traditional AI coding tools that require multiple prompts and manual orchestration, Kodro collapses the entire software development lifecycle into one /kodro command—with built-in quality gates, formal specifications, and automated testing.

The pipeline:

flowchart LR

A[Your Idea] --> B[\/kodro\]
B --> C(P1 Clarify)
C --> D(P2 Specify)
D --> G1{GATEKEEPER}
G1 -->|Approved| E(P3 Plan)
E --> G2{GATEKEEPER}
G2 -->|Approved| F(P4 Implement)
F --> H(P5 Validate)
H --> I(P6 Deliver)
I --> J[Production-Ready Code]

At each gatekeeper, the AI agent pauses for your review. Type "Continue" to proceed. No code is written until Phase 4—the agent first clarifies your intent, writes a formal specification, and creates a dependency-aware task plan.

---

Why Kodro?

Built for Production LLM Applications

• ✅ Formal BDD specifications (not just comments)
• ✅ Gatekeeper checkpoints prevent runaway AI
• ✅ Self-healing validation with decision trees
• ✅ Cost tracking per phase
• ✅ Rollback and resume state machine

84% Token Cost Reduction

Kodro's modular constitution system loads only what's needed per phase:

• ~1,060 tokens/turn vs. ~6,750 tokens for monolithic prompts
• Pay for what you use, not what you don't

Designed for AI Agents

Native integrations with:

• OpenCode, Claude, Cursor, GitHub Copilot, Gemini, Aider

Spec-Driven, Not Prompt-Driven

Generate formal specifications before code. Change requirements? Update the spec and regenerate—don't rewrite prompts.

---

Quick Start

# Install Kodro
pip install kodro

# Initialize a project
mkdir my-weather-app && cd my-weather-app
kodro init --integration opencode --framework react-typescript

# In your AI agent (OpenCode, Claude, Cursor, etc.):
/kodro "Build a weather dashboard with 7-day forecast and location search"

The agent will:

1. Phase 1 (Clarify): Ask 3-5 clarifying questions about your requirements
2. Phase 2 (Specify): Generate formal spec.md with BDD scenarios (DQI ≥80%)
3. Gatekeeper: Pause—type "Continue" to review spec.md
4. Phase 3 (Plan): Create task registry with dependency graph
5. Gatekeeper: Pause—type "Continue" to review tasks.md
6. Phase 4 (Implement): Write all code following the plan
7. Phase 5 (Validate): Run tests, self-heal failures (5 attempts)
8. Phase 6 (Deliver): Generate run instructions + cost report

Result: Production-ready code with tests, documentation, and specifications—from one command.

---

How It Works

Kodro implements Spec-Driven Development (SDD) for AI agents:

journey
    title Kodro Spec-Driven Development SDD Pipeline
    section Phase 1 CLARIFY
      Ask domain questions: 5: AI, User
      Identify ambiguities: 4: AI, User
      Capture user intent: 5: AI, User
    section Phase 2 SPECIFY
      Generate formal spec.md: 5: AI
      Write BDD scenarios: 4: AI
      Define DQI criteria: 4: AI, User
    section GATEKEEPER 1
      Review spec.md: 5: User
    section Phase 3 PLAN
      Decompose into tasks: 5: AI
      Build dependency graph: 4: AI
      Estimate complexity: 3: AI
    section GATEKEEPER 2
      Review tasks.md: 5: User
    section Phase 4 IMPLEMENT
      Execute tasks sequentially: 5: AI
      Generate code and tests: 5: AI
      Follow conventions: 4: AI
    section Phase 5 VALIDATE
      Run test suite: 5: AI
      Self-heal failures 5 attempts: 4: AI
      Verify specifications: 5: AI
    section Phase 6 DELIVER
      Generate run instructions: 5: AI
      Document next steps: 4: AI
      Report token costs: 3: AI

---

Token Efficiency Architecture

Kodro uses a modular constitution system for massive token savings in prompt engineering:

Component	Size	Load Strategy
Kernel	~560 tokens	Always loaded
Phase Module	~110-280 tokens	On-demand per phase
Framework Spec	~120-230 tokens	Once per project
Total/turn	~1,060 tokens	vs ~6,750 monolithic

Results: Active context consumption falls to ~1,060 tokens per turn instead of ~6,750 tokens—yielding 84% savings in LLM API costs.

Why this matters for production AI:

• Lower costs for enterprise LLM applications
• Faster response times (less context to process)
• Scale to larger projects without hitting context limits

---

Features

Feature	Status
One-command pipeline (/kodro)	✅
6-phase SDD with formal BDD	✅
Gatekeeper checkpoints (manual approval)	✅
Resume / Rollback state machine	✅
Self-healing validation (5 attempts)	✅
Per-phase cost tracking	✅
Post-delivery changes workflow	✅
Modular token-efficient constitution	✅
6 AI agent integrations	✅
7 framework constitutions	✅

---

Use Cases

Perfect for:

• 🚀 Rapid prototyping with production-quality output
• 🏢 Enterprise AI development with cost control
• 📚 Learning projects with clear specifications
• 🔄 Iterative development with spec-first approach
• 🤖 AI agent workflows requiring structure and gates

Real-world applications:

• Build full-stack web applications (React, Vue, Next.js)
• Create REST/GraphQL APIs with OpenAPI specs
• Develop CLI tools with comprehensive testing
• Generate data pipelines with validation
• Prototype ML applications with proper architecture

Who uses Kodro:

• AI-assisted developers who need production quality
• Teams managing LLM costs at scale
• Indie hackers building products with AI agents
• Engineers learning prompt engineering best practices

---

Post-Delivery: Making Changes

After your project is delivered (Phase 6), request changes without starting from scratch:

# Log a change request
kodro changes -p ~/projects/my-api "Add OAuth2 Google login"

# Then in your AI agent:
/kodro "Implement change CHANGE-20260522-001"

The agent will:

1. Read .kodro/CHANGES.md and current specifications
2. Propose changes in .kodro/changes/
3. Wait for your approval (gatekeeper)
4. Implement approved changes
5. Re-run validation suite
6. Update specifications

No need to regenerate the entire project. Kodro's state machine handles incremental changes intelligently.

---

Supported Integrations

Kodro works with all major AI coding agents:

Agent	Command	Configuration File
OpenCode	/kodro	.opencode/commands/kodro.md
Claude	$kodro	.claude/CLAUDE.md
Cursor	Auto-read	.cursor/rules/kodro.mdc
GitHub Copilot	Context	.github/prompts/kodro.prompt.md
Gemini	Instructions	.gemini/instructions.md
Aider	Conventions	.aider/CONVENTIONS.md

No API keys required. Kodro generates configuration files that work with your existing agent setup.

---

CLI Commands

Command	Purpose
kodro init	Initialize project with modular constitution
kodro plan	Generate tasks from spec
kodro status	Show pipeline progress
kodro resume	Continue from last phase
kodro rollback	Revert N phases
kodro doctor	Check project health
kodro changes	Request post-delivery changes
kodro agent	Get agent command syntax

---

Kodro vs Alternatives

Feature	Kodro	LangChain	Direct API	Aider
One-command pipeline	✅ /kodro	❌ Manual	❌ Manual	⚠️ Partial
Formal specifications	✅ BDD	❌	❌	❌
Gatekeeper checkpoints	✅ Built-in	❌	❌	❌
Token efficiency	✅ 84% savings	❌ High cost	⚠️ Varies	⚠️ Moderate
Self-healing validation	✅ 5 attempts	❌	❌	⚠️ Manual
State management	✅ Resume/Rollback	❌	❌	⚠️ Limited
Cost tracking	✅ Per phase	❌	⚠️ Manual	❌
Learning curve	Low	High	High	Medium

When to use Kodro:

• You want production-quality code from AI agents
• You need cost control for enterprise LLM usage
• You value formal specifications over ad-hoc prompts
• You want automated quality gates and validation

When to use alternatives:

• LangChain: Building complex LLM chains and agents
• Direct API: Maximum control, custom workflows
• Aider: Quick iterative changes to existing code

---

Architecture

User Idea → /kodro → Kernel (560tok) + P-Module (250tok) + FW-Spec (180tok)
    ↓
P1 Clarify → P2 Specify (DQI≥80) → [GATEKEEPER: type "Continue"]
→ P3 Plan → [GATEKEEPER: type "Continue"]
→ P4 Implement → P5 Validate → P6 Deliver → Next Steps & Run Guide

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Areas we need help:

• Additional framework constitutions (Svelte, Angular, Django, etc.)
• More AI agent integrations (Windsurf, Replit, etc.)
• Performance optimizations for large projects
• Documentation improvements
• Bug reports and feature requests

---

Development

git clone https://github.com/mharoon1578/kodro.git
cd kodro
pip install -e ".[dev]"
pytest tests/ -v

---

Roadmap

• PyPI package publication (v2.0.0)
• GitHub Pages documentation site
• VS Code extension
• Cost analytics dashboard
• Multi-agent collaboration support
• Cloud deployment integrations (Vercel, Railway, etc.)

---

License

MIT License - see LICENSE for details.

---

Built with ❤️ for the AI development community

⭐ Star this repo if Kodro helps your projects! ⭐