{"id":51380992,"url":"https://github.com/mharoon1578/kodro","last_synced_at":"2026-07-03T16:09:05.873Z","repository":{"id":359632118,"uuid":"1246575929","full_name":"mharoon1578/kodro","owner":"mharoon1578","description":"Spec-Driven Development Framework for production. Prevents \"Vibe Coding\" with a disciplined 6-phase autonomous pipeline Lowers token costes by 84%.","archived":false,"fork":false,"pushed_at":"2026-05-30T14:06:35.000Z","size":384,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T15:21:37.257Z","etag":null,"topics":["agents","ai","ai-agents","ai-coding","automation","bdd","code-generation","developer-tools","llm","multi-agents","prompt-engineering","python","sdd","spec-driven-development"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mharoon1578.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-22T10:29:30.000Z","updated_at":"2026-05-30T14:03:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mharoon1578/kodro","commit_stats":null,"previous_names":["mharoon1578/kodro"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/mharoon1578/kodro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mharoon1578%2Fkodro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mharoon1578%2Fkodro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mharoon1578%2Fkodro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mharoon1578%2Fkodro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mharoon1578","download_url":"https://codeload.github.com/mharoon1578/kodro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mharoon1578%2Fkodro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35092322,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","ai-agents","ai-coding","automation","bdd","code-generation","developer-tools","llm","multi-agents","prompt-engineering","python","sdd","spec-driven-development"],"created_at":"2026-07-03T16:09:05.342Z","updated_at":"2026-07-03T16:09:05.864Z","avatar_url":"https://github.com/mharoon1578.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- \n\n```\n    ██╗  ██╗ ██████╗ ██████╗ ██████╗  ██████╗ \n    ██║ ██╔╝██╔═══██╗██╔══██╗██╔══██╗██╔═══██╗\n    █████╔╝ ██║   ██║██║  ██║██████╔╝██║   ██║\n    ██╔═██╗ ██║   ██║██║  ██║██╔══██╗██║   ██║\n    ██║  ██╗╚██████╔╝██████╔╝██║  ██║╚██████╔╝\n    ╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ \n```\n\n**One-Command Spec-Driven Development Engine** --\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/mharoon1578/kodro\"\u003e\n    \u003cpicture\u003e\n      \u003csource srcset=\"assets/kodro_bg.png\"\u003e\n      \u003cimg src=\"assets/kodro_bg.png\" alt=\"Kodro - AI Development Framework for Production LLM Applications\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://pypi.org/project/kodro\"\u003e\n    \u003cimg src=\"https://img.shields.io/pypi/v/kodro.svg\" alt=\"PyPI version\"\u003e\n\u003c/a\u003e    \n\u003ca href=\"https://www.python.org\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/python-3.10+-blue.svg\" alt=\"Python 3.10+\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/psf/black\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/code%20style-black-000000.svg\" alt=\"Code style: black\"\u003e\n\u003c/a\u003e\n\u003ca href=\"https://github.com/mharoon1578/kodro\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/status-beta-orange.svg\" alt=\"Status: Beta\"\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eKodro: Production-Ready AI Development Framework\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\nTransform 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.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003cstrong\u003eOne command. Six phases. Production-ready code.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003e [!NOTE]\n\u003e **Beta Software:** Kodro is in active development. You may encounter bugs, incomplete features, or breaking changes. Please report issues at [GitHub Issues](https://github.com/mharoon1578/kodro/issues).\n\n\u003e [!TIP]\n\u003e **New to Kodro?** Start with the [Getting Started Guide](docs/getting-started.md). For detailed configuration options see [Configuration](docs/configuration.md). For a deep dive into the pipeline phases see [Pipeline](docs/pipeline.md).\n\n\n---\n\n## Table of Contents\n- [What is Kodro?](#what-is-kodro)\n- [Why Kodro?](#why-kodro)\n- [Quick Start](#quick-start)\n- [How It Works](#how-it-works)\n- [Token Efficiency Architecture](#token-efficiency-architecture)\n- [Features](#features)\n- [Use Cases](#use-cases)\n- [Post-Delivery Changes](#post-delivery-making-changes)\n- [Supported AI Agents](#supported-integrations)\n- [CLI Commands](#cli-commands)\n- [Comparison](#kodro-vs-alternatives)\n\n\n---\n\n## What is Kodro?\n\nKodro 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.\n\nUnlike 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.\n\n**The pipeline:**\n```mermaid\nflowchart LR\n\nA[Your Idea] --\u003e B[\\/kodro\\]\nB --\u003e C(P1 Clarify)\nC --\u003e D(P2 Specify)\nD --\u003e G1{GATEKEEPER}\nG1 --\u003e|Approved| E(P3 Plan)\nE --\u003e G2{GATEKEEPER}\nG2 --\u003e|Approved| F(P4 Implement)\nF --\u003e H(P5 Validate)\nH --\u003e I(P6 Deliver)\nI --\u003e J[Production-Ready Code]\n```\nAt 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.\n\n---\n\n## Why Kodro?\n\n### **Built for Production LLM Applications**\n- ✅ Formal BDD specifications (not just comments)\n- ✅ Gatekeeper checkpoints prevent runaway AI\n- ✅ Self-healing validation with decision trees\n- ✅ Cost tracking per phase\n- ✅ Rollback and resume state machine\n\n### **84% Token Cost Reduction**\nKodro's modular constitution system loads only what's needed per phase:\n- **~1,060 tokens/turn** vs. ~6,750 tokens for monolithic prompts\n- Pay for what you use, not what you don't\n\n### **Designed for AI Agents**\nNative integrations with:\n- OpenCode, Claude, Cursor, GitHub Copilot, Gemini, Aider\n\n### **Spec-Driven, Not Prompt-Driven**\nGenerate formal specifications before code. Change requirements? Update the spec and regenerate—don't rewrite prompts.\n\n---\n\n## Quick Start\n\n```bash\n# Install Kodro\npip install kodro\n\n# Initialize a project\nmkdir my-weather-app \u0026\u0026 cd my-weather-app\nkodro init --integration opencode --framework react-typescript\n\n# In your AI agent (OpenCode, Claude, Cursor, etc.):\n/kodro \"Build a weather dashboard with 7-day forecast and location search\"\n```\n\n**The agent will:**\n\n1. **Phase 1 (Clarify):** Ask 3-5 clarifying questions about your requirements\n2. **Phase 2 (Specify):** Generate formal spec.md with BDD scenarios (DQI ≥80%)\n3. **Gatekeeper:** Pause—type \"Continue\" to review spec.md\n4. **Phase 3 (Plan):** Create task registry with dependency graph\n5. **Gatekeeper:** Pause—type \"Continue\" to review tasks.md\n6. **Phase 4 (Implement):** Write all code following the plan\n7. **Phase 5 (Validate):** Run tests, self-heal failures (5 attempts)\n8. **Phase 6 (Deliver):** Generate run instructions + cost report\n\n**Result:** Production-ready code with tests, documentation, and specifications—from one command.\n\n---\n\n## How It Works\n\nKodro implements **Spec-Driven Development (SDD)** for AI agents:\n\n```mermaid\njourney\n    title Kodro Spec-Driven Development SDD Pipeline\n    section Phase 1 CLARIFY\n      Ask domain questions: 5: AI, User\n      Identify ambiguities: 4: AI, User\n      Capture user intent: 5: AI, User\n    section Phase 2 SPECIFY\n      Generate formal spec.md: 5: AI\n      Write BDD scenarios: 4: AI\n      Define DQI criteria: 4: AI, User\n    section GATEKEEPER 1\n      Review spec.md: 5: User\n    section Phase 3 PLAN\n      Decompose into tasks: 5: AI\n      Build dependency graph: 4: AI\n      Estimate complexity: 3: AI\n    section GATEKEEPER 2\n      Review tasks.md: 5: User\n    section Phase 4 IMPLEMENT\n      Execute tasks sequentially: 5: AI\n      Generate code and tests: 5: AI\n      Follow conventions: 4: AI\n    section Phase 5 VALIDATE\n      Run test suite: 5: AI\n      Self-heal failures 5 attempts: 4: AI\n      Verify specifications: 5: AI\n    section Phase 6 DELIVER\n      Generate run instructions: 5: AI\n      Document next steps: 4: AI\n      Report token costs: 3: AI\n```\n---\n\n## Token Efficiency Architecture\n\nKodro uses a **modular constitution system** for massive token savings in prompt engineering:\n\n| Component | Size | Load Strategy |\n|-----------|------|---------------|\n| **Kernel** | ~560 tokens | Always loaded |\n| **Phase Module** | ~110-280 tokens | On-demand per phase |\n| **Framework Spec** | ~120-230 tokens | Once per project |\n| **Total/turn** | **~1,060 tokens** | vs ~6,750 monolithic |\n\n**Results:** Active context consumption falls to ~1,060 tokens per turn instead of ~6,750 tokens—yielding **84% savings** in LLM API costs.\n\n**Why this matters for production AI:**\n- Lower costs for enterprise LLM applications\n- Faster response times (less context to process)\n- Scale to larger projects without hitting context limits\n\n---\n\n## Features\n\n| Feature | Status |\n|---------|--------|\n| One-command pipeline (`/kodro`) | ✅ |\n| 6-phase SDD with formal BDD | ✅ |\n| Gatekeeper checkpoints (manual approval) | ✅ |\n| Resume / Rollback state machine | ✅ |\n| Self-healing validation (5 attempts) | ✅ |\n| Per-phase cost tracking | ✅ |\n| Post-delivery changes workflow | ✅ |\n| Modular token-efficient constitution | ✅ |\n| 6 AI agent integrations | ✅ |\n| 7 framework constitutions | ✅ |\n\n---\n\n## Use Cases\n\n### **Perfect for:**\n- 🚀 **Rapid prototyping** with production-quality output\n- 🏢 **Enterprise AI development** with cost control\n- 📚 **Learning projects** with clear specifications\n- 🔄 **Iterative development** with spec-first approach\n- 🤖 **AI agent workflows** requiring structure and gates\n\n### **Real-world applications:**\n- Build full-stack web applications (React, Vue, Next.js)\n- Create REST/GraphQL APIs with OpenAPI specs\n- Develop CLI tools with comprehensive testing\n- Generate data pipelines with validation\n- Prototype ML applications with proper architecture\n\n### **Who uses Kodro:**\n- AI-assisted developers who need production quality\n- Teams managing LLM costs at scale\n- Indie hackers building products with AI agents\n- Engineers learning prompt engineering best practices\n\n---\n\n## Post-Delivery: Making Changes\n\nAfter your project is delivered (Phase 6), request changes without starting from scratch:\n\n```bash\n# Log a change request\nkodro changes -p ~/projects/my-api \"Add OAuth2 Google login\"\n\n# Then in your AI agent:\n/kodro \"Implement change CHANGE-20260522-001\"\n```\n\n**The agent will:**\n1. Read `.kodro/CHANGES.md` and current specifications\n2. Propose changes in `.kodro/changes/`\n3. Wait for your approval (gatekeeper)\n4. Implement approved changes\n5. Re-run validation suite\n6. Update specifications\n\n**No need to regenerate the entire project.** Kodro's state machine handles incremental changes intelligently.\n\n---\n\n## Supported Integrations\n\nKodro works with all major AI coding agents:\n\n| Agent | Command | Configuration File |\n|-------|---------|-------------------|\n| **OpenCode** | `/kodro` | `.opencode/commands/kodro.md` |\n| **Claude** | `$kodro` | `.claude/CLAUDE.md` |\n| **Cursor** | Auto-read | `.cursor/rules/kodro.mdc` |\n| **GitHub Copilot** | Context | `.github/prompts/kodro.prompt.md` |\n| **Gemini** | Instructions | `.gemini/instructions.md` |\n| **Aider** | Conventions | `.aider/CONVENTIONS.md` |\n\n**No API keys required.** Kodro generates configuration files that work with your existing agent setup.\n\n---\n\n## CLI Commands\n\n| Command | Purpose |\n|---------|---------|\n| `kodro init` | Initialize project with modular constitution |\n| `kodro plan` | Generate tasks from spec |\n| `kodro status` | Show pipeline progress |\n| `kodro resume` | Continue from last phase |\n| `kodro rollback` | Revert N phases |\n| `kodro doctor` | Check project health |\n| `kodro changes` | Request post-delivery changes |\n| `kodro agent` | Get agent command syntax |\n\n---\n\n## Kodro vs Alternatives\n\n| Feature | Kodro | LangChain | Direct API | Aider |\n|---------|-------|-----------|-----------|-------|\n| **One-command pipeline** | ✅ `/kodro` | ❌ Manual | ❌ Manual | ⚠️ Partial |\n| **Formal specifications** | ✅ BDD | ❌ | ❌ | ❌ |\n| **Gatekeeper checkpoints** | ✅ Built-in | ❌ | ❌ | ❌ |\n| **Token efficiency** | ✅ 84% savings | ❌ High cost | ⚠️ Varies | ⚠️ Moderate |\n| **Self-healing validation** | ✅ 5 attempts | ❌ | ❌ | ⚠️ Manual |\n| **State management** | ✅ Resume/Rollback | ❌ | ❌ | ⚠️ Limited |\n| **Cost tracking** | ✅ Per phase | ❌ | ⚠️ Manual | ❌ |\n| **Learning curve** | Low | High | High | Medium |\n\n**When to use Kodro:**\n- You want production-quality code from AI agents\n- You need cost control for enterprise LLM usage\n- You value formal specifications over ad-hoc prompts\n- You want automated quality gates and validation\n\n**When to use alternatives:**\n- LangChain: Building complex LLM chains and agents\n- Direct API: Maximum control, custom workflows\n- Aider: Quick iterative changes to existing code\n\n---\n\n## Architecture\n\n```\nUser Idea → /kodro → Kernel (560tok) + P-Module (250tok) + FW-Spec (180tok)\n    ↓\nP1 Clarify → P2 Specify (DQI≥80) → [GATEKEEPER: type \"Continue\"]\n→ P3 Plan → [GATEKEEPER: type \"Continue\"]\n→ P4 Implement → P5 Validate → P6 Deliver → Next Steps \u0026 Run Guide\n```\n\n---\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n**Areas we need help:**\n- Additional framework constitutions (Svelte, Angular, Django, etc.)\n- More AI agent integrations (Windsurf, Replit, etc.)\n- Performance optimizations for large projects\n- Documentation improvements\n- Bug reports and feature requests\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/mharoon1578/kodro.git\ncd kodro\npip install -e \".[dev]\"\npytest tests/ -v\n```\n\n---\n\n\n## Roadmap\n\n- [x] PyPI package publication (v2.0.0)\n- [ ] GitHub Pages documentation site\n- [ ] VS Code extension\n- [ ] Cost analytics dashboard\n- [ ] Multi-agent collaboration support\n- [ ] Cloud deployment integrations (Vercel, Railway, etc.)\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n\u003cp align=\"center\"\u003e\n\u003cstrong\u003eBuilt with ❤️ for the AI development community\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n⭐ Star this repo if Kodro helps your projects! ⭐\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmharoon1578%2Fkodro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmharoon1578%2Fkodro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmharoon1578%2Fkodro/lists"}