What is KAIROS?
"The Right Moment for Development"
Intelligent multi-agent SDLC orchestration
KAIROS is a framework that wires specialized AI agents into a single, human-controlled pipeline. You describe what you want to build; KAIROS breaks it into phases — requirements, design, code, review, tests, deployment — and each phase ends in a written artifact you approve before the next one starts. The point is not to reach code faster; it is that nothing reaches code unreviewed.
The human never loses control: every phase ends at a checkpoint where you approve, redirect, or skip before anything moves forward. Three of them (after the bug triage, the requirements and the finished implementation) continue on their own when the Orchestrator's checks find nothing for you to decide, and every gate asks at all of them (see Gates that continue on their own).
The Problem It Solves
A single AI conversation accumulates context fast. Feed it a feature request and by the time it writes code, it's also carrying the requirements analysis, the architecture discussion, every revision you made — thousands of tokens that inflate every subsequent call and blur focus.
KAIROS solves this with subagents: isolated AI agent instances, each with a focused role and a fresh context window.
WITHOUT SUBAGENTS:
PM analysis → stays in main context (+10 KB)
Arch design → stays in main context (+8 KB)
Code draft → stays in main context (+20 KB)
─────────────────────────────
38 KB+ bloating every token call
WITH SUBAGENTS:
PM analysis → pm-agent context → only the Markdown artifact returned
Arch design → architect context → only the Markdown artifact returned
Code draft → implementer context → only files + coverage returned
─────────────────────────────
Main context stays small and cheapEach subagent:
- Receives only what the orchestrator passes it
- Works in isolation — no access to the parent conversation
- Returns only the final artifact — intermediate reasoning stays local
The Core Pipeline
| # | Agent | Role | Output |
|---|---|---|---|
| pre | Context Extractor (standalone — you run it) | Full-repo scan → stack, patterns, conventions | 00-context.md |
| pre | Impact Assessment (started by the Orchestrator) | Issue-scoped grounding → effort, domains, test suite, contract change — the facts the pipeline is derived from | 00b-impact.md |
| 0 | Orchestrator | Coordinates the pipeline, manages HITL | Routes & aggregates |
| 1 | PM Agent | Requirements, constraints, acceptance criteria | 01-requirements.md |
| 2 | Architect Agent | design options → recommended choice, API contracts, DB schema, threat model, migration safety | 02-architecture.md |
| 3 | Implementer Agent | Implementation plan → TDD cycle (tests first, then code) — default when the project has a test suite; a code-first variant (code, then the tests the project calls for) runs for simple_fix, for projects without a suite, and when the design says test_first: no | Code + 03-implementation.md |
| 4 | Code Reviewer | Standards, security, performance, contract compliance | 04-review.md |
| 4b | Security Reviewer (optional) | Adversarial security pass — IDOR, auth, injection, secrets, data exposure | 04b-security-review.md |
| 5 | Test Verifier | Coverage reported (threshold only if declared), over-testing, assertion quality | 05-test-verification.md |
| 5b | QA Plan Agent (optional) | Manual & exploratory cases, regression retest list, test data/environment, UAT sign-off | 05b-qa-plan.md |
| 6 | Release Planner | Deployment steps, rollback strategy, monitoring thresholds | 06-deployment-plan.md |
| 6b | Documentation Agent (optional) | Feature-facing docs in the target project — README, API reference, CHANGELOG | 06b-documentation.md |
All output files are saved to .kairos/<feature-folder>/ — one subfolder per feature, named from the issue reference (e.g. PROJ-42_add-stripe-payments). Each phase writes a single Markdown file: a small YAML frontmatter header carrying only what the Orchestrator branches on — a verdict, the tallies its status rules threshold, and a loop signal where a loop exists — followed by the human-readable report (data model, issues, findings, runbook) — see the Workflow page for why.
The two pre rows differ. Context Extractor is standalone: you launch it yourself before the run, and the Orchestrator only reads the 00-context.md it leaves on disk. Impact Assessment is started by the Orchestrator at every run, because the pipeline is derived from its facts; if you already ran it yourself, its 00b-impact.md is reused. Counting Context Extractor, five of the seventeen agents are yours to start; the twelve others are the Orchestrator's.
The other four sit outside this table entirely, all invoked directly by you rather than scheduled by the pipeline. Bug Triage is the entry point when what you have is a defect rather than a feature: it reproduces, finds the root cause, and recommends where the fix re-enters the pipeline. It is also a standalone agent the Orchestrator may dispatch itself — when your input reads as a bug report and no triage exists, it offers to run it and then gates the result like any phase artifact. Dependency Audit runs every few months outside any feature, turning dependencies and accumulated debt into a prioritized backlog at .kairos/_tech-debt.md. Retrospective Agent distills a finished feature's own artifacts into lessons, appended to the project-root .kairos/_lessons.md; Improvement Advisor reads that file back every few features and proposes framework changes as ADR records, never editing an agent file itself. See All Agents for all four.
Layered Mode: optional extension (Claude Code only)
For complex multi-layer features, the Orchestrator offers Layered Mode when the TDD path was chosen, two or more of backend/frontend/db are touched and the host is Claude Code. On your confirmation it replaces the single Implementer Agent with a lead and up to four layer agents, which the Orchestrator runs in stages (tests first and alone, then the layers in parallel, then one verification against the contracts):
| Agent | Role |
|---|---|
| Implementer Lead | Creates binding contracts, verifies every layer against them and runs the tests (the whole suite on the first pass) |
| Teammate Tests | Generates full test suite (RED phase first) |
| Teammate Backend | Implements APIs per contract |
| Teammate Frontend | Implements UI per contract |
| Teammate Database | Creates schema and migrations per contract |
A Layered Mode run makes more calls than a single implementer (one lead call to plan, one to verify and one to close, plus a call per layer for each stage); what that costs is not measured, so read _usage.md after the first runs. It is available only in Claude Code. The Orchestrator coordinates plain subagent calls, with no Agent Teams, no peer messaging and no live progress, and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is no longer needed. It asks for confirmation before activating the mode. It was called Team Mode until v9.5.0.
Human-in-the-Loop (HITL)
KAIROS is not fully automated. Every active agent presents its output and waits for your decision before the pipeline moves forward.
Agent completes its phase
↓
Presents artifact to user
↓
✅ Approve → pass artifact to next active agent
✏️ Changes → agent revises based on your feedback
⏭️ Skip next → approve this, jump past the next agent
⛔ Stop → abort and keep everything so farThis gives you:
- Zero surprises — you review every decision before code is written
- Course correction at any point — steer direction without restarting
- Full audit trail — every artifact is saved locally and optionally posted as a comment to the issue (Jira, GitLab, Bitbucket)
Two places ask less often than one gate per agent, because the gate there carries no decision of its own. Code review, security review and test verification run together as one review wave and share one gate, with one fix pass for everything you choose to fix. And the waves of a large implementation plan continue on their own unless one of them raises a new risk, a new constraint, a failing test or a file outside the plan. Throughout the run, _tracking.md in the feature folder shows where the run is, what blocks it, what is still open and how far the work has moved from the issue, with a log of every step.
Selective Pipeline
Not every task needs the full pipeline, and you don't pick agents from a menu. The Orchestrator derives which agents run from facts about the change — the effort, the domains touched, whether the project has a test suite, whether a contract changes — reported by the Impact Assessment and, later, by the Architect. Each agent is decided at the point in the run where its facts exist:
| Decided | Agents |
|---|---|
| At the start | pm-agent, architect-agent, whether code is written at all, code-reviewer-agent |
| Right before the plan | which implementer: implementer-tdd-agent, the code-first implementer-coder-agent, or Layered Mode (offered, with a note that its cost is not measured) |
| At the implementation gate | test-verifier-agent (the diff has a test file), security-reviewer-agent |
| At the review gate | qa-plan-agent, release-planner-agent, documentation-agent |
Before the first agent runs, the Start Gate shows the derived pipeline, the rule behind each agent, the effort and the auto-fix budget, and asks one question: start, change the pipeline, request changes, or stop. Every later decision is printed at the gate before it, with the rule that fired. A free-text reply at any of those gates is a correction (skip release-planner, add security-reviewer, effort medium): it holds for the rest of the run and is logged in _tracking.md. In IDEs without the interactive prompt (Cursor, JetBrains/Copilot, Codex CLI, OpenCode) the same gate is printed as a typed menu.
If the issue already contains a ## KAIROS Pipeline section, the Orchestrator reads it first and starts without asking: you already decided, so it only prints what is about to run. An override block (Size:, Effort:, Epic:, Analysis:, Areas:, Auto-fix:, Skip:, Add:) is applied on top of the derivation, and an older checklist still wins over it. The one question a run still asks before any code is read is which areas it covers (analysis, development, review, delivery; the default is all, one click), because what a run is for is your intent, not a fact in the code.
The full rule table and override examples (hotfix, security-sensitive, refactor, docs-only) are in Pipeline Templates.
What You Get
A typical KAIROS feature run produces:
- ✅ Code following your project's existing patterns, reviewed at a gate before it lands
- ✅ Test suite sized to the acceptance criteria, coverage reported (when using
implementer-tdd-agent) - ✅ Architecture decision record with sound API contracts (via pre-contract checklist gate)
- ✅ Code review report (security, performance, standards)
- ✅ Adversarial security report with exploitable findings and attack scenarios (when using
security-reviewer-agent) - ✅ Deployment plan with rollback procedure
- ✅ Full issue tracker comment trail (Jira / GitLab / Bitbucket)
When using
implementer-coder-agent(code-first path), tests are written after the code and only as its plan's Test Decision calls for; with no test suite in the project, none are produced.
How Files Are Organized
agents/
├── orchestrator-agent.md ← Coordinator
├── context-extractor-agent.md ← Pre-pipeline: full-repo context
├── impact-assessment-agent.md ← Pre-pipeline: issue-scoped grounding, facts for the derivation
├── bug-triage-agent.md ← Standalone: bug reproduction + root cause
├── pm-agent.md ← Requirements
├── architect-agent.md ← System design
├── implementer-tdd-agent.md ← TDD code generation (default)
├── implementer-coder-agent.md ← Code-first: code, then the tests the project calls for
├── code-reviewer-agent.md ← Quality review
├── security-reviewer-agent.md ← Adversarial security review (optional, read-only)
├── test-verifier-agent.md ← Test quality
├── qa-plan-agent.md ← Manual & exploratory QA plan
├── release-planner-agent.md ← Deployment planning
├── documentation-agent.md ← Feature-facing docs (optional, Phase 6b)
├── retrospective-agent.md ← Standalone, post-pipeline: lessons capture
├── improvement-advisor-agent.md ← Standalone, infrequent: framework change proposals (ADRs)
├── dependency-audit-agent.md ← Standalone, periodic: dependency + tech-debt backlog
└── team/ ← Layered Mode agents (lead + layer agents)
├── implementer-lead-agent.md
├── teammate-tests-agent.md
├── teammate-backend-agent.md
├── teammate-frontend-agent.md
└── teammate-database-agent.md
skills/ ← Shared checklists/formats reused across agents — see Skills & MCP
├── agent-contract/SKILL.md
├── analysis-discipline/SKILL.md
├── artifact-bookkeeping/SKILL.md
├── artifact-template/SKILL.md
├── code-simplification/SKILL.md
├── coding-discipline/SKILL.md
├── constraint-taxonomy/SKILL.md
├── contract-checklist/SKILL.md
├── issue-tracker-comment/SKILL.md
├── migration-safety/SKILL.md
├── test-scope/SKILL.md
└── threat-model/SKILL.md
commands/ ← Claude Code slash commands (/kairos:setup, /kairos:view, /kairos:usage)Each agent file is self-contained — YAML frontmatter for tool and model configuration, markdown body for the agent prompt. How you get these three directories into your tool depends on the tool: Claude Code installs all three together via claude plugin install (recommended) or a manual copy; other tools copy agents/ (and skills//commands/ where supported) into their own subagent directory. See Setup for the exact steps per tool.
Ready to start? → Set up KAIROS with your IDE
Want the full picture? → Use cases · Workflow walkthrough · All Agents