Corbat-Coco

Autonomous Coding Agent with Self-Review, Quality Convergence, and Production-Ready Output

Quick Start • Features • Methodology • Examples • Docs

What is Corbat-Coco?

Corbat-Coco is an autonomous coding agent that transforms natural language requirements into production-ready code. Unlike other AI coding tools, it iteratively improves code until it meets senior-level quality standards.

"Every line of code must be worthy of a senior engineer's signature."

Why Corbat-Coco?

Feature	Cursor/Copilot	Claude Code	Corbat-Coco
Generate code	✅	✅	✅
Self-review loops	❌	❌	✅
Quality scoring	❌	❌	✅ (11 dimensions)
Architecture planning	Basic	Basic	✅ Full ADR system
Progress persistence	❌	Session	✅ Checkpoints
Production deployment	❌	❌	✅ CI/CD generation

Quick Start

Installation

# Using npm
npm install -g corbat-coco

# Using pnpm (recommended)
pnpm add -g corbat-coco

# Verify installation
coco --version

TL;DR (3 commands)

coco init my-project    # Initialize & describe what you want
coco plan               # Generate architecture & backlog
coco build              # Build with quality iteration

Example Session

$ coco init my-api

🚀 Welcome to Corbat-Coco!

? What would you like to build?
> A REST API for task management with user authentication

? Tech stack preferences?
> TypeScript, Express, PostgreSQL, JWT auth

📋 Specification generated!

$ coco plan

📐 Designing architecture...
✓ ADR-001: Express.js framework
✓ ADR-002: JWT authentication
✓ ADR-003: PostgreSQL with Prisma

📝 Backlog: 2 epics, 8 stories, 24 tasks

$ coco build

🔨 Building Sprint 0...

Task 1/6: User entity ✓ (3 iterations, score: 92/100)
Task 2/6: Auth service ✓ (4 iterations, score: 89/100)
...

📊 Sprint Complete!
├─ Average quality: 90/100
├─ Test coverage: 87%
└─ Security issues: 0

Example Session: Working on Existing Projects

For day-to-day development work on existing projects, use coco task to execute specific tasks:

$ cd my-existing-backend
$ coco task

? Describe your task (paste from Jira, GitHub issue, etc.):
> ## JIRA-1234: Add GET endpoint for user orders
>
> **Story Points:** 5
> **Acceptance Criteria:**
> - Create GET /api/v1/users/{userId}/orders endpoint
> - Return paginated list of orders (default: 20 items)
> - Support query params: status, fromDate, toDate, page, size
> - Include order items in response
> - Return 404 if user not found
> - Add unit tests (>80% coverage)
> - Update OpenAPI spec

🔍 Analyzing codebase...
✓ Detected: Java 17 + Spring Boot 3.2
✓ Found: OrderRepository, UserRepository, existing /api/v1/* structure
✓ Style: Following existing patterns in UserController.java

📋 Task breakdown:
1. Create OrderController with GET endpoint
2. Create OrderService with business logic
3. Create OrderDTO and OrderPageDTO
4. Add validation and error handling
5. Write unit tests for Service layer
6. Write integration tests for Controller
7. Update OpenAPI documentation

? Proceed with implementation? (Y/n) Y

🔨 Executing task...

Step 1/7: OrderController ✓ (2 iterations, score: 94/100)
  → Created: src/main/java/com/example/controller/OrderController.java
  → Follows existing controller patterns

Step 2/7: OrderService ✓ (3 iterations, score: 91/100)
  → Created: src/main/java/com/example/service/OrderService.java
  → Using existing OrderRepository

Step 3/7: DTOs ✓ (1 iteration, score: 96/100)
  → Created: OrderDTO.java, OrderPageDTO.java, OrderFilterDTO.java

Step 4/7: Error handling ✓ (2 iterations, score: 93/100)
  → Added: UserNotFoundException handling
  → Updated: GlobalExceptionHandler.java

Step 5/7: Unit tests ✓ (2 iterations, score: 89/100)
  → Created: OrderServiceTest.java (12 tests)
  → Coverage: 94%

Step 6/7: Integration tests ✓ (3 iterations, score: 88/100)
  → Created: OrderControllerIntegrationTest.java (8 tests)

Step 7/7: OpenAPI ✓ (1 iteration, score: 97/100)
  → Updated: openapi.yaml with new endpoint schema

📊 Task Complete!
├─ Files created: 6
├─ Files modified: 2
├─ Tests added: 20 (all passing)
├─ Coverage: 92%
├─ Average quality: 92/100
└─ Time: 12 minutes

? Create commit? (Y/n) Y
✓ Committed: feat(orders): add GET endpoint for user orders [JIRA-1234]

? Push to remote? (Y/n) Y
✓ Pushed to origin/feature/JIRA-1234-user-orders

Pro tips for existing projects:

Coco automatically detects your tech stack and coding patterns
Paste your Jira/GitHub issue directly - it parses acceptance criteria
Use coco task --dry-run to preview without changes
Use coco task --no-commit to skip auto-commit

Features

🔄 Iterative Quality Improvement

Code is automatically reviewed and improved until it meets quality standards:

Generate → Test → Review → Improve → Repeat until excellent

📊 Multi-Dimensional Quality Scoring

11 dimensions measured on every iteration:

Dimension	Weight	Description
Correctness	15%	Tests pass, logic correct
Completeness	10%	All requirements met
Robustness	10%	Edge cases handled
Readability	10%	Code clarity
Maintainability	10%	Easy to modify
Complexity	8%	Cyclomatic complexity
Duplication	7%	DRY score
Test Coverage	10%	Line/branch coverage
Test Quality	5%	Test meaningfulness
Security	8%	No vulnerabilities
Documentation	4%	Doc coverage
Style	3%	Linting compliance

💾 Checkpoint & Recovery

Never lose progress:

Automatic checkpoints every 5 minutes
Resume from any interruption
Full version history per task
Rollback capability

🏗️ Architecture Documentation

Generated automatically:

Architecture Decision Records (ADRs)
System diagrams (C4 model)
Backlog with epics, stories, tasks
Sprint planning

🚀 Production Ready

Outputs ready for deployment:

Dockerfile & docker-compose.yml
GitHub Actions workflows
README & API documentation
Deployment guides

The COCO Methodology

Four phases from idea to deployment:

┌──────────┐    ┌────────────┐    ┌──────────┐    ┌────────┐
│ CONVERGE │ →  │ ORCHESTRATE│ →  │ COMPLETE │ →  │ OUTPUT │
└──────────┘    └────────────┘    └──────────┘    └────────┘
     │               │                 │              │
 Understand      Plan &            Execute &      Deploy &
 Requirements    Design            Iterate        Document

Phase	Purpose	Output
Converge	Understand requirements through Q&A	Specification document
Orchestrate	Design architecture, create plan	ADRs, Backlog, Standards
Complete	Build with quality iteration	Quality code + tests
Output	Prepare for production	CI/CD, Docs, Deployment

Commands

# New projects
coco init [path]              # Initialize new project
coco plan                     # Run discovery and planning
coco build                    # Execute tasks with quality iteration
coco build --sprint=N         # Build specific sprint

# Existing projects (day-to-day workflow)
coco task                     # Execute a single task (Jira, GitHub issue, etc.)
coco task --dry-run           # Preview changes without applying
coco task --no-commit         # Skip auto-commit after task

# Utilities
coco status                   # Show current progress
coco status --verbose         # Detailed status
coco resume                   # Resume from checkpoint
coco config set <key> <value> # Configure settings
coco config get <key>         # Get configuration value

Configuration

Configuration is stored in .coco/config.json:

{
  "project": {
    "name": "my-project",
    "version": "0.1.0"
  },
  "provider": {
    "type": "anthropic",
    "model": "claude-sonnet-4-20250514"
  },
  "quality": {
    "minScore": 85,
    "minCoverage": 80,
    "maxIterations": 10,
    "convergenceThreshold": 2
  },
  "persistence": {
    "checkpointInterval": 300000,
    "maxCheckpoints": 50
  }
}

Quality Thresholds

Setting	Default	Description
`minScore`	85	Minimum quality score (0-100)
`minCoverage`	80	Minimum test coverage (%)
`maxIterations`	10	Max iterations per task
`convergenceThreshold`	2	Score delta to consider converged

Examples

See the examples/ directory for complete examples:

Example	Description	Time
REST API (TypeScript)	Task management API with auth	~30 min
CLI Tool	Image processing CLI	~25 min
Spring Boot (Java)	Order management microservice	~40 min

Requirements

Node.js: 22.0.0 or higher
Anthropic API Key: For Claude models
Git: For version control features

Environment Variables

export ANTHROPIC_API_KEY="sk-ant-..."  # Required
export COCO_CONFIG_PATH="..."          # Optional: custom config path

Documentation

Guides

Quick Start Guide - Get started in 5 minutes
Configuration Guide - Complete configuration reference
Tutorial - Detailed tutorial with examples
Troubleshooting - Common issues and solutions

Technical

API Reference - Use Corbat-Coco as a library
Architecture - System design & C4 diagrams
ADRs - Architecture Decision Records
Production Readiness - Assessment & roadmap

Development

# Clone the repository
git clone https://github.com/corbat/corbat-coco.git
cd corbat-coco

# Install dependencies
pnpm install

# Run in development
pnpm dev --help

# Run tests
pnpm test

# Run all checks
pnpm check  # typecheck + lint + test

# Build
pnpm build

Contributing

Contributions are welcome! Please read the Contributing Guide first.

Quick Contribution Steps

Fork the repository
Create a feature branch (git checkout -b feat/amazing-feature)
Write tests (80% coverage minimum)
Run checks (pnpm check)
Commit with conventional commits
Open a Pull Request

Troubleshooting

"API key not found"

export ANTHROPIC_API_KEY="sk-ant-..."

"Quality score not improving"

Check the quality report for specific issues
Review suggestions in .coco/versions/task-XXX/
Consider adjusting maxIterations

"Checkpoint recovery failed"

coco resume --from-checkpoint=<id>
# Or start fresh:
coco build --restart

For more help, see Issues.

Roadmap

License

MIT License - see LICENSE for details.

Built with ❤️ by Corbat

GitHub • Issues • Changelog

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.github		.github
cov-temp		cov-temp
coverage-temp		coverage-temp
docs		docs
examples		examples
src		src
test		test
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MASTER_PLAN.md		MASTER_PLAN.md
README.md		README.md
SECURITY.md		SECURITY.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
typedoc.json		typedoc.json
vitest.config.ts		vitest.config.ts

License

corbat-tech/corbat-coco

Folders and files

Latest commit

History

Repository files navigation

Corbat-Coco

What is Corbat-Coco?

Why Corbat-Coco?

Quick Start

Installation

TL;DR (3 commands)

Example Session

Example Session: Working on Existing Projects

Features

🔄 Iterative Quality Improvement

📊 Multi-Dimensional Quality Scoring

💾 Checkpoint & Recovery

🏗️ Architecture Documentation

🚀 Production Ready

The COCO Methodology

Commands

Configuration

Quality Thresholds

Examples

Requirements

Environment Variables

Documentation

Guides

Technical

Development

Contributing

Quick Contribution Steps

Troubleshooting

"API key not found"

"Quality score not improving"

"Checkpoint recovery failed"

Roadmap

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

Packages