A framework for running a multi-agent software development team — autonomously or semi-autonomously. Six specialized agents collaborate through a shared database pipeline: requirements → planning → architecture → implementation → QA → human review. Works with GitHub Issues, ships real PRs.
Shipping software is a coordination problem. PMs write requirements, architects validate feasibility, developers write code, QA tests it, and a human reviews everything — each step a handoff that introduces delays, miscommunication, and dropped context.
Traditional project management tools automate the tracking of this process. ACO automates the execution of it.
GitHub Issue
│
▼
┌─────────┐ writes ┌─────────┐ breaks down ┌───────────┐ validates ┌───────────┐
│ PM │ ──────────► │ Planner │ ─────────────► │ Architect │ ────────────► │ Developer │
│ (Sonnet)│ user story │ (Opus) │ into tasks │ (Opus) │ feasibility │ (Sonnet) │
└─────────┘ └─────────┘ └───────────┘ & security └───────────┘
(hard gate) │
│ creates
│ branch + PR
▼
┌─────────┐
│ QA │
│(Sonnet) │──► runs tests
└─────────┘
│
▼
┌──────────┐
│ Human │
│ Reviewer │──► escalation / merge
└──────────┘
Every agent runs independently, polls for work, and writes results to a shared database. No message passing. No shared context window. No degradation as stories get complex.
| ACO System | LangChain Agents | AutoGen | CrewAI | |
|---|---|---|---|---|
| Structured pipeline | ✅ 6-agent gate chain | ❌ | ❌ | |
| Deterministic security gate | ✅ Hard pre-commit checks | ❌ | ❌ | ❌ |
| Real-time dashboard | ✅ Kanban + live feed + alerts | ❌ | ❌ | ❌ |
| Human escalation | ✅ Configurable at any stage | |||
| Multi-LLM support | ✅ Per-agent model override | |||
| File-based extensibility | ✅ Prompts, rules, hooks, skills | ❌ | ❌ |
The Architect agent is the key difference. Before any code is written, it runs deterministic validation — no LLM involved, no hallucination risk:
- ✅ No hardcoded secrets (
api_key,password,token,secretscanned) - ✅ Story has
tech_stackandacceptance_criteria - ✅ All tasks are assigned and estimated
If these fail, the story is rejected at the gate — it never reaches the developer. No bad PRs, no leaked credentials, no incomplete features.
- Engineering teams that want to automate repetitive development workflows
- AI/agent researchers building on a proven multi-agent collaboration pattern
- Solo developers who want a "virtual team" handling the boilerplate
- Platform builders who need extensible agent primitives
# 1. Clone
git clone https://github.com/aniketkarne/aco-system.git
cd aco-system
# 2. Python dependencies
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# 3. Frontend dependencies
cd frontend && npm install && cd ..
# 4. Configure
cp .env.example .env
# Edit .env: add your GITHUB_TOKEN, LLM provider key, and repo details
# 5. Run dashboard
cd frontend && npm run dev
# → http://localhost:3001
# 6. Run the agent pipeline
python run_all_agents_final.pyThat's it. The dashboard shows the live pipeline — Kanban board, agent status, story timeline, and a streaming event feed.
| Agent | Model | Role |
|---|---|---|
| PM | Sonnet | Writes user stories from GitHub Issues, does web research |
| Planner | Opus | Breaks stories into tasks, estimates effort, maps dependencies |
| Architect | Opus | Hard gate: validates feasibility, security, schema — blocks bad stories |
| Developer | Sonnet | Writes code, creates branches and PRs, follows coding standards |
| QA | Sonnet | Reviews PRs, writes and runs tests, validates acceptance criteria |
| Human | — | Escalation point for edge cases, final merge sign-off |
All agents communicate through a shared SQLite (dev) or PostgreSQL (prod) database. Each agent polls for work, acquires a story lock, executes its step, writes results, and releases the lock. No shared context window. No agent-to-agent API calls. Complexity stays in the database schema, not in the agent logic.
ACO System does not replace GitHub — it builds on top of it. Every story in the pipeline automatically creates or links to a GitHub Issue, giving you full history, labels, and search without any additional tooling.
| Pipeline Stage | GitHub Action |
|---|---|
| PM creates story | GitHub Issue opened with full description, acceptance criteria, and CEO/Founder analysis |
| Planner breaks down tasks | Issue body updated with task checklist |
| Architect approves | Issue labeled approved, ready for development |
| Developer starts | Feature branch created, issue assigned, work begins |
| Developer finishes | Pull Request opened against main, linked to the issue |
| QA reviews | PR checks run, QA feedback posted as PR review comments |
| Human approves | PR merged or manual merge requested |
Each pipeline stage has a corresponding label. The dashboard Kanban board mirrors these labels — the board and GitHub Issues always stay in sync:
pm-review → ready-planner → ready-architect → approved → dev → qa → human-review → done
- Branches —
feat/story-42-stripe-payments,fix/story-15-email-verification - Issues — One per story, with full context in the body, updated as the story moves through the pipeline
- Pull Requests — One per story, with linked tasks, description from acceptance criteria, and test instructions
Using GitHub as the collaboration layer means:
- No lock-in — The data is yours. Close the dashboard, the agents still work through the GitHub API alone
- Your existing tools — Search, filter, and triage using GitHub's UI. Get notifications through GitHub's settings
- Full audit trail — Every agent action is in the issue comments. Every decision is timestamped and attributable
- CI/CD ready — GitHub Actions triggers on PR creation, running your test suite automatically before QA reviews
A real-time Next.js dashboard provides visual oversight of the entire pipeline. It is not a static tracker — it reflects live agent activity as it happens.
Kanban Board — Stories move through columns representing each pipeline stage. Each card shows the story title, priority badge (critical / high / medium / low), time since last update, and rejection count. Columns include PM Review, Planner, Architect, Dev, QA, Human Review, Done, and Blocked.
Agent Activity Panel — Each of the six agents shows as a live card: current status (idle / working / blocked), the story it is handling, and which LLM model it is using. A streaming event log below shows timestamped agent actions in real time — "aco-pm: New story created", "aco-architect: Approved story #12", "aco-dev: PR opened for task #4". An alert panel surfaces rejections, escalations, and failures immediately.
Story Detail — Clicking any card opens a side panel with the full story context: description, acceptance criteria, task list with status, conversation history, and linked GitHub issue. The human reviewer uses this view for final sign-off.
Everything is file-based and hot-reloadable. No code changes needed to influence agent behavior:
| Extension | Format | What It Changes |
|---|---|---|
| Agent prompts | Markdown + YAML frontmatter | How each agent thinks and decides |
| Coding rules | Markdown in rules/common/ |
Mandatory standards (security, git workflow, testing) |
| Validation hooks | JSON in hooks/ |
Deterministic pre/post transition checks |
| Domain skills | Markdown in skills/ |
Python patterns, FastAPI, React, etc. |
| Project context | Markdown in contexts/ |
Project-specific background knowledge |
aco-system/
├── agents/ # Agent Python implementations
│ └── base_agent.py # Inherit to add new agents
├── agent_prompts/ # Markdown prompts (hot-reloadable)
│ ├── pm.md / planner.md / architect.md / developer.md / qa.md / human.md
├── core/
│ ├── database.py # SQLite/PostgreSQL ORM layer
│ ├── event_bus.py # Agent event pub/sub
│ ├── prompt_loader.py # Runtime prompt loading
│ ├── rule_loader.py # Rule injection into agent context
│ ├── context_trimmer.py # Token budget management
│ └── validation_hooks.py # Deterministic gate validators
├── hooks/ # JSON configs for hard validation gates
├── rules/common/ # Mandatory rules for all agents
│ ├── security.md
│ ├── coding-standards.md
│ ├── git-workflow.md
│ └── testing.md
├── skills/ # Domain knowledge
├── contexts/ # Project-specific context
├── integrations/ # GitHub sync, external APIs
├── frontend/ # Dashboard (Next.js 15 + Tailwind CSS)
│ ├── app/api/ # API routes (stories, agents, feed, alerts)
│ └── components/ # Kanban, timeline, live feed, alerts
└── run_all_agents_final.py # Main entry point
# PostgreSQL for multi-instance deployments
DATABASE_URL=postgresql://user:password@host:5432/aco
# Optional Redis for distributed task queue
REDIS_URL=redis://localhost:6379/0
# Per-agent model override
ACO-ARCHITECT_MODEL=anthropic/claude-opus-4-20250514
ACO-DEV_MODEL=openai/gpt-4oMIT License — see LICENSE.
Built by Aniket Karne