Changelog

All notable changes to KAIROS Framework are documented in this file.

v9.7.1 — November 14, 2026

A project reported a 25 minute wait for its tests, caused less by how many tests the agents wrote than by how they wrote them, and by a suite that ran in full at every stop: the TDD implementer once, Test Verifier on every recheck, the Layered Mode lead at verify and again at close. The agents now pick how much of the suite to run from what the change touched, and write tests that are cheap to run.

Added

skills/test-scope/SKILL.md: a shared reference for the three rungs (the test files the change touches, the tests related to the changed files, the whole suite), which stage owns the full run, the triggers that force a full run (a manifest, lockfile, build or test configuration, a shared helper or fixture, a migration, a runner with no related selection), the runner defaults for Jest, Vitest, pytest and Go, how a targeted run reports coverage, and six rules for writing tests that are cheap to run. It is read by the agents that run tests, never launched by hand.
.kairos-cfg/config: a test-changed key, project only: the project's own command for running the tests related to some files, with {files} standing for them, or off to run the whole suite at every stop. The agents read it; the orchestrator ignores it, as it ignores any key it does not know.
docs/workflow.md: a Test Scope section with the rungs, the owner of each full run, what a related run leaves open, and what has not been measured.

Changed

agents/implementer-tdd-agent.md (and both mirrors): PHASE 6 runs the whole suite with coverage only in the last planned wave. An earlier planned wave runs the test files it touched, any other pass runs the related tests, and neither writes a partial coverage number: both carry coverage_summary forward. The Test budget adds the rules for tests that are cheap to run, and the ## Test Execution — GREEN section opens with a scope: line.
agents/implementer-coder-agent.md (and both mirrors): runs the related tests, not the whole suite, because Test Verifier owns the full run on this path and a second one repeated it. Its report states the scope it ran, and the tests it writes follow the same cost rules.
agents/test-verifier-agent.md (and both mirrors): the whole suite runs on the first invocation with no run to reuse, on a standalone invocation and when the prompt says final_pass: true. A loop re-check or a recheck after a fix pass runs the tests related to the files the latest pass wrote, copies coverage_summary from the latest full run and writes execution.scope: targeted. Reusing the implementer's run now also requires that run to be of the whole suite. The Hygiene check gains a medium Cost item for a concrete real sleep, real network call, per-test application or database start, or one behaviour asserted at three levels.
agents/orchestrator-agent.md (and both mirrors): the review loop's final pass is dispatched with final_pass: true, so Test Verifier can tell it from an iteration re-check. The sentence was shortened at the same time: the file is 29 bytes smaller and stays under its budget.
agents/team/implementer-lead-agent.md: verify round 0 and the close of the first pass run the whole suite. A later verify round, a loop iteration and a post-gate fix pass run the related tests. This file has no mirror.
docs/customizing.md, docs/agents.md, docs/overview.md, docs/skills-mcp.md, CLAUDE.md: the new key, the changed suite runs and the new skill.

Fixed

agents/orchestrator-agent.md (and both mirrors), commands/setup.md, docs/customizing.md: the text said the single config file replaced the older files in 9.8.0. It shipped in 9.7.0; the references now say so.

What this leaves open: a related run can miss a test that reaches the changed code without an import (dynamic loading, runtime registration, a data file). After a fix pass outside a review loop, in a simple_fix, and when the code-first implementer wrote no test file, the related tests are the last test run before merge, so keep the whole suite in CI. On OpenCode and Kimi Code, copy skills/ again into .opencode/skills/ or .kimi-code/skills/ so the new skill resolves. Not measured: no run has used the rungs. The runner defaults come from the runners' documentation and were not run here.

v9.7.0 — October 23, 2026

A run on a child issue cut from an earlier design run started from nothing: the design lived in a folder with no issue key, the child got a folder of its own, and nothing connected the two. The impact assessment measured again what the design already said. A new Analysis: line points the child's run at the design.

Added

agents/orchestrator-agent.md (and both mirrors): an Analysis: <folder> key in the ## KAIROS Pipeline override block, read in an inline section and in a checklist too. When the folder exists on this machine, every agent of the run is given the paths of its 01-requirements.md, 02-architecture.md, 00b-impact.md and ledger/, read-only, and the impact assessment is told to measure this issue's slice starting from them. The line adds no skip and no agent, sets no corrected, and a missing folder prints one line and runs as before. The Start Gate shows the folder, and run.md keeps it as analysis_ref, so a resume restores it.
docs/setup/templates.md, docs/workflow.md, docs/overview.md: the Analysis: key, with what it does and what it does not do.

Changed

agents/orchestrator-agent.md (and both mirrors): a manual pipeline that holds only analysis agents (the run that makes an issue ready) no longer saves itself at the Start Gate, where the checklist would hold the agents that ran and none of the ones the later run needs. The save waits until the last analysis gate resolves, then asks the Development, Review and Delivery questions again with the agents the rules derive from the facts now on disk marked (Recommended), and writes the checklist with the analysis agents unticked and the chosen later agents ticked. The file stays at 251,997 bytes (budget 252,000): the new paragraph is paid for by shortening the write-back text around it.
agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md, agents/test-verifier-agent.md, agents/code-reviewer-agent.md, agents/team/implementer-lead-agent.md (and mirrors, except the team file): the fixed 80% coverage bar is gone. Coverage is reported and fails a review only when a constraint row or the project's own config declares a threshold. The TDD implementer gets a test budget (one test per behaviour an AC-n or a risk names, extend an existing test before adding one, assert what a caller observes and not how the code is built, no tests for getters or wiring) and runs only the test files it touches in RED, GREEN and REFACTOR, with the whole suite and coverage once at the end. The coder extends existing tests only for the behaviour it changed. test-verifier-agent flags redundant and structure-bound tests as low Issues. Reported from a project where running and repairing tests after each change of direction cost more than the development. Not measured: compare test counts and suite time in the next runs.
docs/agents.md, docs/index.md, docs/metrics.md, docs/overview.md, docs/workflow.md: the 80% claims now say coverage is reported.
agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md (and both mirrors): a wave is now capped by the output it will write, not by how many files it holds. The plan gives every file, tests included, an Est. tokens figure (new lines written times 12; a modified file counts only the lines it adds or changes), the ## Waves table sums it per wave, and a wave holds at most 10,000 estimated tokens and 12 files. The old rule was 6 files per wave whatever their size, so the number of waves followed the file count and not the work: 13 one-line edits cost three waves, five large new files fit in one. A file that alone exceeds the cap takes a wave of its own with a medium risk row and is never split. The 12-file ceiling is a backstop for plans of many tiny edits, where the output is small but every file still costs a read and an edit turn. Not measured: 10,000 tokens and the factor 12 are a first cut chosen so that six files of about 140 lines land on the old limit, and the figures are the agent's own estimate. Compare Est. tokens with the waves' real output in later _usage.md files before moving either number.
docs/workflow.md: the paragraph on large plans states the new wave size.
.claude/CLAUDE.md: a size budget for agents/orchestrator-agent.md. The file went from 58 KB to 252 KB in two months and is read on every turn, so it now stays at or under 252,000 bytes: a change that adds text removes at least as much, and deterministic rules move to the kairos-cli runner instead of into new code here.
README.md: the line on internal/ now says it holds local, unpublished notes. The cost, routing and provider guides it named were removed as out of date.
.kairos-cfg/config: every project setting now lives in one file of key: value lines (model.<agent>, manual-qa, qa-dir) instead of one file per setting. Blank and # lines are ignored, unknown keys are skipped, and a new setting is a new line, not a new file. The older files (.kairos-cfg/models, manual-qa, qa-dir and the .kairos/ ones) are still read, so nothing has to be migrated; config wins over them.
agents/orchestrator-agent.md (and both mirrors): reads settings from config first with the older files as fallback; the manual QA read command handles both formats.
commands/setup.md, commands/usage.md, scripts/usage.mjs: /kairos:setup replaces only the model. lines of the chosen config and removes the older model files at that scope; /kairos:usage and the script read the expected model in the same order.
docs/customizing.md, docs/setup/*.md, docs/faq.md, docs/workflow.md: document the single file and the lookup order.

v9.6.4 — October 21, 2026

v9.6.3 did not stop teammate-tests-agent from ending blocked. Reading the same run again, with the person's report that it still happens, found a different cause and a gap in the v9.6.3 rule. At 12:47 the agent ran a shell command with a stray heredoc and a cat > file with no input; cat waited on stdin forever, the host moved the command to the background after its default 120 s timeout, and the agent edited the file another way and went on without stopping it. That shell is the "1 shell still running": the host reported the agent as completed with the summary "waiting on its own background work" and a note that the result may be interim. The orchestrator had that notice in its context, so the v9.6.3 trigger (no notice, or a continue) never fired and it waited on the summary's wording. The pipes and test runners named in v9.6.3 were not involved. Not measured: one run.

Fixed

agents/orchestrator-agent.md (and both mirrors): a completion notice marked interim (summary "waiting on its own background work", note that the agent stopped with background work still running) now counts as a trigger of Hand-back without a return, next to "no notice after two calls" and a continue. With the hand-back received, a report with a final status, no test runner or build process working in the worktree and git status stable, the orchestrator treats the call as returned, logs returned by hand-back and names the leftover shell in its line so the person can stop it.
agents/team/teammate-tests-agent.md, teammate-backend-agent.md, teammate-frontend-agent.md, teammate-database-agent.md: a Shell hygiene paragraph. Files are created with Write and Edit, never with cat > or a heredoc; a command that may pass two minutes gets an explicit timeout; a command the host moved to the background is a hung command, not work, and goes in the report's ## Notes. The v9.6.3 rule about piping test output through head and tail is removed from the tests agent, since it named the wrong cause.

v9.6.3 — October 21, 2026

A Layered Mode run on a downstream project sat for about 70 minutes between RED and GREEN. teammate-tests-agent finished at 12:52 and delivered its report with SubagentHandback, but the host kept its call open ("1 shell still running") and the orchestrator waited for a completion notice that did not come, as the v9.1.0 rule tells it to, until the person said it looked stuck. The agent's transcript shows four foreground test runs with a timeout and no run_in_background, so the shell that held the call is not identified; pipes into head and tail and the child processes of dotnet test and npx craco are the candidates. The parallel part of the stage worked: backend and frontend GREEN started in the same second. Not measured: one run, one agent.

Fixed

agents/orchestrator-agent.md (and both mirrors): a [Subagent hand-back] is now enough to close the call when the host holds it open. With the hand-back received, no completion notice after the two bookkeeping calls (or a continue from the person), a report with a final status, no test runner or build process working in the worktree and no file changing in git status, the orchestrator removes the in_flight entry, logs returned by hand-back and goes on instead of waiting or asking. Any other case, a partial report, a live process or no hand-back, keeps the question about whether the agent was stopped.
agents/team/teammate-tests-agent.md: the RED run of its own tests is foreground, non-watch and with a timeout, never piped into head or tail (the output goes to a file that it reads), and it checks that none of its processes is left before it reports.

v9.6.2 — October 19, 2026

An Add: line that arrives in the invocation prompt was not applied in 4 runs of 5. The kairos-cli runner starts the orchestrator on Haiku with the issue text and its ## KAIROS Pipeline section in the prompt, on a fixture with no tracker remote. The five launch prompts are identical (read from the session transcripts); in four runs run.md holds add: [] and the log calls test-verifier-agent a caller proposal that was not applied, so the 9.6.1 fix to the order of the Decision Announcement never saw the override. The cause is read from the text and from those artifacts, and has two parts. The Caller-supplied selection check matched an Add: line as a list of agents dictated by the caller, and the only text that let a pasted block count (Template Parsing) covered a reply at the Start Gate, not the prompt. And Step 0d, the one place that reads a section, runs only when the input names an issue reference (the model decided that per run, three runs yes, two no), and when its tracker read failed it said the section was unknown, which three runs repeated while the section sat in their own prompt. One run applied the block on its own, so the behaviour is reachable; the text did not ask for it. Not measured: no run has used the new rule, and the same Step 0e line gave 4 runs of 5 applying the override on the 9.5.0 discount fixture, so the model's reading of it varies with the fixture.

Fixed

agents/orchestrator-agent.md (and both mirrors): a ## KAIROS Pipeline override block carried in the invocation prompt is the issue's own section, not a caller's list. A new Inline section step runs first in Step 0e, with or without an issue reference and whether or not the tracker could be read, and applies the block's Add:, Skip:, Effort:, Size:, Areas:, Epic: and Auto-fix lines as an issue's section would. The Start Gate prints 📋 ## KAIROS Pipeline found in the prompt. A section read from the tracker wins, an unknown line under the heading is reported and dropped, and an inline section makes no fast start and sets no corrected. An agent list written as a sentence by the caller, with no such heading, is still a caller proposal that nothing applies without the human, and the Important Notes rule "never take an agent list from a caller" is unchanged apart from a pointer to the new step.
agents/orchestrator-agent.md (and both mirrors): the message printed when the tracker read fails now says the prompt's section is used when there is one, instead of saying the Start Gate will not know it.

v9.6.1 — October 17, 2026

Three misses reported by the kairos-cli runner, which drives the orchestrator on Haiku: the two Step 0e dispatches ignored the models setting, one run in five ignored manual-qa, and one run in five skipped an agent the issue had added. The causes are read from the orchestrator text and the reports, not reproduced: each rule existed but sat far from the place a smaller model acts, or left the order of checks to the reader. No behaviour changes on a model that already followed them.

Fixed

agents/orchestrator-agent.md (and both mirrors): the models setting now applies to the first two dispatches of a run. Model override lived under Calling Subagents, after the Step 0e dispatches of bug-triage-agent and impact-assessment-agent, which never pointed at it, so both ran on their own model:. A new Hard Constraint 6 names the rule for every Agent call and both dispatch sites repeat it.
agents/orchestrator-agent.md (and both mirrors): manual-qa is read with a command at the gate that needs it, not recalled, and a value is compared after trimming spaces and line endings and ignoring case. A file saved on Windows ends in \r\n and Yes is a natural thing to type, and either made a valid file read as unusable. The question is no longer asked when the file holds an answer.
agents/orchestrator-agent.md (and both mirrors): an agent named in Add: runs at its decision point whatever its rule says. The Decision Announcement now decides each agent in a fixed order (skipped, added, then the row and the area) and the review wave checks that every added reviewer is in its call list, so test-verifier-agent is no longer dropped on a rule that did not fire.

v9.6.0 — October 16, 2026

Six complaints from real runs, one release. The impact assessment started on every run, including runs that only review code that already exists, so a run's cost and first question were not in the person's hands. There was no way to say what a run is for ("analyse this issue now, build it later") except typing area names. Choosing every agent by hand was possible only through typed add/skip replies and was never saved where a colleague could find it. Escalate filed a question and made the person answer it in a second session. Questions put to a person cited internal ids ("Q2: dove vive T5 (consegna G13 dopo la dispose dello scope)?") that only the artifact explains. And the end-of-run project summary was composed by the orchestrator, the one agent that should not also write documents.

One rule runs through all of it and was fixed by the maintainer: a pipeline that already exists wins over anything the person types. A saved ## KAIROS Pipeline section, a resumed run and a hand-picked pipeline all beat a phrase in the prompt.

Not done on purpose: handing a half-finished issue to another developer when .kairos/ is gitignored. The analysis is kept in a local, unpublished note under internal/ for a later release. Not measured: none of the new rules has run on a real run yet, and the phrase table is a first cut.

Added

agents/orchestrator-agent.md, docs/setup/templates.md, docs/workflow.md: run intent. Phrases in the prompt that starts a run answer the area question in advance: analizziamo/analyse covers analysis, rendi ready covers analysis with pm-agent and architect-agent forced on, implementiamo covers all areas, finalizziamo/wrap up covers review. The start gate names the phrase that fired. A phrase is a per-run intent and is never offered for saving.
agents/orchestrator-agent.md, docs/setup/templates.md, docs/workflow.md: Choose the pipeline myself. One dialog with a group per area lets you tick the agents, the impact assessment among them. The pipeline is exactly your selection and is saved to the issue as a checklist without asking (GitLab and Bitbucket). On Jira the block goes in as a comment and is printed paste-ready, because the plugin cannot write a Jira description. A failed write prints the block and never stops the run.
agents/orchestrator-agent.md, agents/pm-agent.md, agents/impact-assessment-agent.md, docs/workflow.md: an Escalate asks one follow-up in the same gate: up to two alternatives from the row's own mitigation, Keep it open and go on, Stop here, or your own words. An answer settles the row now (Mitigate now with your answer in its note, or Accept) instead of a second session. A kept-open row still holds Escalate, so the stop signals that read it keep firing.
skills/artifact-template/SKILL.md, agents/pm-agent.md, agents/architect-agent.md, agents/impact-assessment-agent.md, agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md, agents/documentation-agent.md: new §6 "Rows a person answers". A row opens with what is undecided in product or code words, offers two or three alternatives with their cost, and carries internal ids (T5, G13, AC-2) only as a trace in parentheses. The orchestrator resolves an id it cannot place from the reports it holds before it asks.
agents/documentation-agent.md, docs/agents.md, docs/agent-files.md: step: summary. The agent drafts the project summary from each report's ## Summary and the ledger, redacts security detail, proposes a target path from the project's own docs layout and writes the draft inside .kairos/ only.

Changed

agents/orchestrator-agent.md, docs/setup/templates.md, docs/workflow.md, docs/agents.md: impact-assessment-agent is started only when a fact is needed: a derived run that covers analysis or development, or a pipeline that names it. A run limited to review and delivery reads the effort from an Effort: line, else the issue's size: label, else medium, derives the domains from the changed files and says so at the start gate. documentation-agent is not derived there, and the gate says how to add it. No size label is set when no size was measured.
agents/orchestrator-agent.md, docs/setup/templates.md, docs/workflow.md: the area question's options are now All areas, Choose the pipeline myself and Decide each step. Area names typed in the free field still work. A phrase of the intent table is ignored, with one line, when a pipeline already exists.
agents/orchestrator-agent.md, agents/pm-agent.md, agents/impact-assessment-agent.md: an escalated row no longer flips the gate's recommendation to Request changes. The recommendation follows the rows and your answer.
agents/orchestrator-agent.md, docs/workflow.md: the Step 10d project summary is drafted by documentation-agent and no longer composed by the orchestrator. The orchestrator keeps the gate and the cleanup question. The summary ends with a ## Target line, and a different path is a Request changes.
agents/orchestrator-agent.md, docs/workflow.md: ledger/run.md gains manual_pipeline (pending until the hand-picked pipeline is saved or printed), restored on resume.
.opencode/agents/, .kimi-code/agents/: bodies synced for the seven changed agents; the documentation-agent description now mentions the summary step.

Fixed

agents/orchestrator-agent.md, docs/workflow.md, docs/setup/templates.md, .opencode/agents/, .kimi-code/agents/: Decide each step no longer lets the run take off before the first agent question (reported on v9.5.0, on a bug report). The bug triage and the impact assessment belong to no area and ran before the start gate: a lone yes or no for the triage, then the triage and the assessment back to back, with the first question about the other agents only afterwards. The orchestrator now names both in one block before the first of them, and the triage gate stops instead of continuing on its own, so you read the triage before the assessment starts.
agents/orchestrator-agent.md, docs/workflow.md, docs/setup/templates.md, .opencode/agents/, .kimi-code/agents/: Decide each step no longer asks about code-reviewer-agent at the start gate. Its rule only reads whether an implementer runs, so it showed up beside pm-agent and architect-agent for a person who had come for an analysis, with a reason that named a rule and not a consequence. It is now asked at the implementation gate with the other two reviewers, and every option in this mode says in plain words what the agent does and why it is recommended.
agents/orchestrator-agent.md, docs/workflow.md, docs/setup/templates.md, .opencode/agents/, .kimi-code/agents/: Decide each step is now a second setting and not an area. Written in the area question's free field (analysis, decide each step) or next to a phrase in the prompt (analizziamo e decidi tu ogni step), it keeps the areas you named and only adds the question per agent. Before, an analysis run with a question per agent was possible only by typing it at the start gate, and a phrase together with those words was not defined.
scripts/usage.mjs, agents/orchestrator-agent.md, .opencode/agents/, .kimi-code/agents/: _usage.md no longer goes missing when the feature folder is renamed during a run, and the orchestrator no longer reports its absence. The script finds an agent's calls by the Feature folder: line of the prompt it was dispatched with, which keeps the name the folder had that day: a run that triaged a bug under feature_<slug> and then renamed the folder to issue-<n>_<slug> once the issue was created matched nothing, and the script found no transcripts. --feature can now be repeated, and run.md records the old names in earlier_names for the orchestrator to pass. The end-of-run summary names _usage.md only when the file exists.

Team Mode could not start under the orchestrator. The orchestrator dispatches implementer-lead-agent through its Agent tool, so the lead ran as a subagent, and a subagent cannot create an Agent Team: only the main session can. In a real run the orchestrator reported the mode as unable to start, the pipeline fell back to one TDD implementer in nine waves, and the human had already confirmed a cost warning for a mode that could not run.

The mode is rebuilt as Layered Mode. The orchestrator is the coordinator and the stages are plain subagent calls, as in the review wave: no Agent Teams, no flag, no peer messaging. The agent ids and the agents/team/ folder keep their names, so saved checklists and Add: overrides that name them still work.

Not measured: the cost of Layered Mode against a single implementer (the old 3.5x figure came from the Agent Teams design and no longer applies), the quality of GREEN stages that run without the full suite, the cap of two FIX rounds and max_retries of 2. Read _usage.md after the first runs. Whether CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS set to 1 changes anything when the orchestrator dispatches named subagents is also unverified: KAIROS no longer reads it, and the docs say it is no longer needed.

Added

agents/orchestrator-agent.md, docs/workflow.md, docs/setup/templates.md, CLAUDE.md, .opencode/agents/, .kimi-code/agents/ — a third answer to the area question, Decide each step, for a run where you want the last word on every agent. The rules still run and print what they say, and then the Orchestrator asks which agents of that point should run, with the rules' answer marked as recommended, at the start gate, at the implementation gate and at the review gate. What you tick against the rules is stored as an Add: or Skip: override, so the issue write-back and the resume work as before. Before, the later gates only announced the rules' decision and you could correct it by typing. It is asked even at a gate that would continue on its own and it leaves the implementer out. An issue that already carries a ## KAIROS Pipeline section (override block or checklist) never gets the agent question: a decide each step in the prompt is ignored with one line, and choosing All areas (full) skips the agent question at every gate. Write decide each step in the prompt to answer the area question in advance, or reply it or derive at the start gate. Not measured: how often people want it on; read the chosen by you lines of _tracking.md before making it a default.
agents/orchestrator-agent.md, docs/workflow.md, docs/agentic-loop.md, CLAUDE.md — Phase 3b in Layered Mode runs as stages the orchestrator drives: RED (tests layer alone), GREEN (one call per in-scope layer, in parallel), VERIFY (the lead checks every layer against the contracts and is the only stage that runs the full suite), FIX (only the layers VERIFY named, then VERIFY again), REFACTOR and CLOSE. A review-loop or QA fix pass is the lead's scope, the layers' fix, then the lead's close. No gate sits between stages: each stage adds one line to _tracking.md.
agents/orchestrator-agent.md, docs/workflow.md — a contract gap the lead cannot settle stops the run with a "Contract gap" question: accept it as a documented gap, say you fixed it by hand, or stop the pipeline. A blocked layer asks to retry the stage or stop. The answer reaches the lead as a human_decision: line.
agents/orchestrator-agent.md, skills/artifact-template/SKILL.md, skills/artifact-bookkeeping/SKILL.md — new artifacts 03-layer-<layer>.md (one report per layer) and 03-verify.md (the lead's verdict: pass, fix or human), and layered_stage and layered_round in ledger/run.md, so an interrupted run resumes at the stage it stopped in. A missing layered_stage resumes at RED when the plan is approved and at 3a otherwise.
agents/team/implementer-lead-agent.md — a contract mismatch found in Step 2b becomes a row of the plan's ## Risks table (kind "Contract divergence"), so the plan gate shows it: Mitigate now is applied by the lead at the next step, Escalate stops for the architect.

Changed

agents/team/implementer-lead-agent.md — rewritten for the orchestrator: steps 3a, verify, scope and close, 03-contracts.md as the binding record, implementation_type: layered and layers_summary in 03-implementation.md. It has no AskUserQuestion and no Test Plan Gate: whatever needs a person is a row the orchestrator turns into a gate.
agents/team/teammate-tests-agent.md, agents/team/teammate-backend-agent.md, agents/team/teammate-frontend-agent.md, agents/team/teammate-database-agent.md — the layer agents run one stage per call (red, green, fix, refactor) and write 03-layer-<layer>.md. They do static checks only: no full suite, no build, no migration applied. The database layer writes migrations and never runs them.
agents/orchestrator-agent.md, docs/setup/claude-code.md, docs/agents.md, docs/faq.md, README.md — the Team Mode check is now the Layered Mode check. It needs Claude Code and two or more of backend, frontend and database among the domains. It no longer reads CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, and the cost warning says the cost is not measured instead of quoting a multiple.
agents/orchestrator-agent.md — .kairos-cfg/models now reaches the four layer agents too, because the orchestrator dispatches them, and a stage run by several layers in parallel takes each one's own line. Before, the teammates were started by the lead and kept their frontmatter model (haiku).
agents/impact-assessment-agent.md, .opencode/agents/, .kimi-code/agents/ — the impact assessment, the orchestrator mirrors and the Layered Mode wording carry the same body changes.
docs/setup/opencode.md, docs/setup/kimi-code.md, AGENTS.md, .claude/CLAUDE.md — the "no mirror" notes for agents/team/ now say why it holds today: nobody has run Layered Mode on those hosts, so porting is a separate decision. The old reason, the dependence on Agent Teams, is gone.

Removed

agents/team/implementer-lead-agent.md, docs/setup/claude-code.md — the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS setup, the shared task list and peer messages between agents, and the Test Plan Gate with its AskUserQuestion. Starting the lead directly, which was never a documented path, now makes it say that the orchestrator dispatches it and stop.

v9.4.0 — October 10, 2026

Three gates now continue by themselves on a simple_fix, and nothing said how to tell whether that is safe. An approval rate cannot: a gate that continued is approved by construction. The log now carries the two keys that count what changed after a gate instead, and the rule for reading them is written down.

The start gate also stopped treating what you say to it as noise. In a real run, an answer that widened the work never reached the impact assessment, and a question typed at the gate had nowhere to go but a regenerated report or an open question nobody owned.

Token use became something you can read and act on. The usage report now includes the orchestrator, which was the largest line of the bill in 19 real runs, and the peak context of every call, because tokens are turns times context. The one lever the data supports, compacting earlier through Claude Code's own setting, is documented with its simulated effect and what is still unverified.

Fixed

agents/orchestrator-agent.md, docs/workflow.md, CLAUDE.md — a question typed at the start gate is answered by the Orchestrator from the impact assessment, the ledger and the files it cites, then the gate is shown again. It is no longer sent to the assessment as feedback or filed as an open question.
agents/orchestrator-agent.md, docs/workflow.md — answering an open question at the start gate re-runs the impact assessment when the answer adds, removes or replaces a file, a test, a flow or a criterion, or names another size, effort, domain, test suite, contract change or change kind. Before, no answer ever did, so a size measured before the answer stayed in force.
agents/impact-assessment-agent.md, docs/workflow.md — a re-run reads the previous report and the ledger, answers every point of the feedback in one Feedback: line (accepted, or not accepted with a file:line), applies answered questions instead of asking them again, and opens the files an objection names even when the read-in-proportion limit would have stopped earlier. The standalone gate answers a question instead of filing it.

Added

agents/orchestrator-agent.md, docs/workflow.md, CLAUDE.md — a gate that asked now ends its ## Log note with auto-accepted: <ids, or none> (the rows accepted for you) and off-recommendation: <ids, or none> (the rows you dispositioned differently from the (Recommended) option), the same auto-accepted: key a continued gate already wrote. A row accepted for you that a later gate promotes to MUST — from <phase> R<id> is then countable on both kinds of gate. CLAUDE.md records how to compare the two: rework after the gate, over the asked gates the continuation predicate would also have passed.
scripts/usage.mjs, commands/usage.md, docs/workflow.md, docs/faq.md, CLAUDE.md — /kairos:usage --feature and the _usage.md the Orchestrator writes now end with a second table: the primary session (the orchestrator) of every session that dispatched an agent for that feature, with its model, turns and token buckets. It was the one line the file left out, and in a sample of 19 real runs it was the largest, about 41% of the bill at current prices against 33% for the implementers. The row is a session total, kept out of the agent total, and also covers other features run in that session and any conversation after the run, so read it as an upper bound. Its model check uses the orchestrator's own model:, and only when the transcript shows it was started as kairos:orchestrator-agent. --json appends the same rows.
agents/test-verifier-agent.md, CLAUDE.md — suites that share nothing (a backend and a frontend runner, each with its own coverage directory) start together in one message and are read as each finishes. Suites that share a database, a port or a build directory, and an end-to-end suite that needs the application running, still run in sequence, the end-to-end one last. The gain is a ceiling and small: in 19 real runs the suite commands were 15% of test-verifier's time and overlapping all of them saved at most 9%, so no setting declares which suites are safe.
scripts/usage.mjs, commands/usage.md, docs/workflow.md, docs/faq.md, CLAUDE.md — the usage table has a Peak ctx column, the largest prompt one request of an agent carried (also peak in --json). Tokens are turns times context and 97% of them are cache reads, so a growing context is where they go: in 19 real runs the orchestrator's grew from about 90K to 300K-650K inside one session. CLAUDE.md records what the same data ruled out (a model swap is token-neutral, trimming the orchestrator's spec saves under 3.5%, fewer waves points the wrong way) and a fix-pass count that corrects an earlier estimate.
docs/customizing.md, CLAUDE.md — a new section, "Keeping token use down", on Claude Code's auto-compact window (autoCompactWindow, --autocompact, CLAUDE_CODE_AUTO_COMPACT_WINDOW). Replaying the real sessions with a 250K window saves 42% of the orchestrator's tokens and, if subagents compact too, 27% of the sample. It is a simulation, and the section says what is unverified: that an --agent body survives a compaction, and that an implementer compacting mid-wave keeps what it needs.
agents/orchestrator-agent.md — after the host compacts its conversation, the orchestrator reads ledger/run.md (in_flight, gate_pending) before it answers and trusts it over the summary.

Changed

.opencode/agents/, .kimi-code/agents/ — the orchestrator, impact assessment and test-verifier mirrors carry the same body changes.

v9.3.1 — October 10, 2026

A last check of QA plan size against real plans found two defects. A plan had no way to say it asked nothing of a person, and on a simple_fix, where test-verifier does not run, the agent treated every acceptance criterion as unverified even when tests covered it. The size limits are unchanged: they are the same from M to XL, and no L or XL plan written under the current rules exists to tune them against.

Added

agents/qa-plan-agent.md, agents/orchestrator-agent.md, docs/workflow.md, docs/agents.md, CLAUDE.md — a plan whose tester's part is empty (no manual case, no regression retest, no existing case, no charter) is delivery: none. It keeps Summary, Core, Coverage Complement, Risks when it has rows and UAT Sign-off for the gate, writes no _qa-file.md or _qa-comment.md, and posts nothing. The orchestrator skips the delivery question and prints QA plan: nothing to verify by hand. The gate is unchanged, since a risk row may still need a decision there.

Changed

agents/qa-plan-agent.md, docs/workflow.md, docs/agents.md, CLAUDE.md — with no test verification artifact, the agent reads the tests the implementer wrote and the existing tests of the changed files instead of treating every criterion as unverified. A criterion that an assertion it opened covers is cited as covered by <file:line> and leaves the plan, the covered ones sharing one row; one no test names stays. A test it did not open is not evidence.
.opencode/agents/, .kimi-code/agents/ — the orchestrator and QA plan mirrors carry the same body changes.

v9.3.0 — October 10, 2026

KAIROS had no place to configure it and no page that said how. Its three project settings lived in .kairos/, which the first run gitignores, so a "project setting" meant this machine and this project: nothing a team could share, nothing a person could set once for every repository. A .kairos-cfg/ folder, in the project and in the home directory, now holds them, and one docs page lists every setting.

Added

docs/customizing.md, docs/.vitepress/config.js, docs/faq.md — a "Customizing KAIROS" page: what to use for which change, the two folders, every setting, the order the files are read in, which hosts read what, and what has no setting (an agent's behaviour, which still means editing its file). The FAQ answer on customizing points to it.
agents/orchestrator-agent.md, docs/workflow.md, docs/setup/claude-code.md, CLAUDE.md — .kairos-cfg/ holds models (project and home folder), manual-qa and qa-dir (project only). The project folder is meant to be committed and the Gitignore check leaves it alone. For each setting the first source wins: .kairos-cfg/ in the project, then the old .kairos/ file, then, for models, the home folder, then the default. models merges per agent line. A value that cannot be used is reported once and ignored. A value held by .kairos-cfg/ stops the manual QA and QA directory questions.

Changed

agents/orchestrator-agent.md, agents/qa-plan-agent.md, docs/workflow.md — the Start Gate's Models: line names the place each line came from (project, local, user). The orchestrator still writes only inside .kairos/: the answers it asks for stay there, and it never writes .kairos-cfg/.
commands/setup.md, docs/setup/claude-code.md — /kairos:setup asks whether the models are for you (~/.kairos-cfg/models, the recommended choice because nothing is committed) or for the project (.kairos-cfg/models), writes that file, removes the old .kairos/.models when it replaces a project choice, and reports the models in effect with the file each came from.
commands/usage.md, scripts/usage.mjs — the expected model is read from the same three files in the same order, so a mismatch flag names the file it was expected from. An alias outside opus, sonnet, haiku and fable is ignored, as the orchestrator does.
docs/setup/kimi-code.md, docs/setup/opencode.md — they say the models files have no effect on those hosts.
.opencode/agents/, .kimi-code/agents/ — the orchestrator and QA plan mirrors carry the same body changes.

Notes

Nothing has to be migrated. Every old path is still read, as the v8.4.0 ledger move did, and the new file wins when both exist, so a stale local .kairos/.models cannot override what a team committed.
No secret belongs in .kairos-cfg/: it is committed and no setting needs a credential. The orchestrator reads only the three named files and ignores anything else in the folder.

v9.2.1 — October 10, 2026

Testers said QA plans did not make clear what to do and where (web or app), and that steps did not lead to the expected result. The plan they read was written before v9.2.0, so its length and matrix problems are already limited; these two were not. Nothing told a case where each step happens or after which step to look, and v9.2.0's one-line Setup and short steps left even less room for it.

Changed

agents/qa-plan-agent.md, docs/workflow.md, docs/agents.md, CLAUDE.md — every step of a QA case says where it happens. Setup names each surface once with a short label (Phone: Android app · PC: web app in a desktop browser), and a case on more than one surface opens every step with that label. Regression retests and charters name their surface the same way.
agents/qa-plan-agent.md, docs/workflow.md, docs/agents.md, CLAUDE.md — the expected result is tied to the step that produces it: at most two parts, each opening with the number of the step after which the tester looks (after 2: …; after 3: …). Something no step triggers or reads is a precondition, not an expected result, and a case whose expected result only restates its preconditions is not a case. A case that needs more than two places to look becomes two cases, so a plan may report more items over the case limit.
agents/qa-plan-agent.md, CLAUDE.md — a developer's preparation happens before step 1 and its undoing after the last step, never between two steps. A case that needs a developer in the middle is split or becomes a risk row.
.opencode/agents/, .kimi-code/agents/ — the QA plan mirrors carry the same body changes.

v9.2.0 — October 7, 2026

Two things read badly in a real run. The Start Gate offered no visible way to choose agents, only Start, Request changes and Stop, so the choice looked gone; add <agent> and skip <agent> existed only as typed text, and on a resumed run even Request changes was missing. And the first run of a project asked "Does a person verify features by hand in this project (QA, UAT)?" before any code had been read, which reads as "does a QA phase exist?" and was asked even in runs that could never write a QA plan. Testers also kept complaining that manual plans were long and complicated: real downstream plans ran to 90 to 287 lines per issue and an epic file to 6,700 words, with a small bug fix carrying eight cases, and projects differ in where a tester wants to find the plan.

Added

agents/qa-plan-agent.md, agents/orchestrator-agent.md, skills/issue-tracker-comment/SKILL.md, docs/workflow.md, docs/agents.md, CLAUDE.md — you choose how the QA plan reaches the tester when you approve it: a comment on the issue, a file attached to the issue, or a file in the repository. The attachment is offered on GitLab when glab is installed (upload, then the link in the comment); Jira and Bitbucket do not offer it. An epic keeps its cumulative repository file, and a run with no issue reference keeps the old behaviour. The agent now always writes _qa-file.md (the tester's part in full) and _qa-comment.md (the Core and a {qa_pointer} line), and its delivery field is only the recommendation. Plans written before this version still deliver. The GitLab upload is read from its documentation and has not been run against a real instance; when it fails the Orchestrator prints the path to attach by hand and a paste-ready comment.
agents/qa-plan-agent.md, docs/workflow.md, CLAUDE.md — a fifth ## Risks row kind, automatable gap: a coverage-complement item that a unit, component or integration test could close, named in one clause. It never reaches the tester; Mitigate now on it sends it through the fix pass to the implementer and the test verifier. An item that an existing test already asserts is labelled covered by <test>, with the test's file:line, and produces neither a case nor a risk row.
agents/orchestrator-agent.md, docs/workflow.md, docs/setup/templates.md, docs/overview.md — the Start Gate always offers Change the pipeline, on a resumed run too. It asks what to change (add an agent, skip an agent, or areas, effort and review loop in your own words), then lists the agents that can be added or skipped with the state each has now, as buttons, and stores the choice as an override. Agents decided later can be added or skipped there too. Typed add <agent> / skip <agent> keep working.

Changed

agents/qa-plan-agent.md, docs/workflow.md, docs/agents.md, CLAUDE.md — the tester's part of a QA plan is short and simple. A check is manual only when no assertion can see its outcome or no developer environment can stage it. At most 5 cases (3 in a simple_fix), each with a one-line setup, at most three repeat with variants instead of a matrix in the cell, at most three short steps and a one-sentence result. At most 3 one-line regression retests, kept only where no existing test exercises the caller, 4 data rows with no run order, 3 behaviour-change rows and 1 or 2 charters. The sign-off table stays with the gate: each case names the AC-n it checks. What was left out stays in the coverage complement, and the Summary says how many items went over the case limit. A check that a ledger row or decision names as needing a real device or setup enters the plan like any other item, and only code this change wrote can become an automatable gap. The numbers are a first cut calibrated on two downstream projects: regenerated from the same inputs, the tester's part of one run went from 64 lines and 1,989 words to 39 and 703, and of another from 84 lines and 2,441 words to 38 and 692.
agents/orchestrator-agent.md, docs/workflow.md, docs/setup/templates.md — the manual QA question moves from the start of the first run to the gate that decides the QA plan (the review gate normally). It is asked only when the answer can change that decision: the delivery area is selected, qa-plan-agent is not skipped, no VERIFICATION constraint already put the plan in, and the change leaves something for a person to check. The question names that fact, so a run that never reaches that point never asks. .kairos/.manual-qa keeps its meaning and its place.
agents/orchestrator-agent.md, docs/workflow.md — Request changes at the Start Gate no longer lists "Change the pipeline" as one of its follow-ups, because it is now a button of its own.
agents/impact-assessment-agent.md, agents/orchestrator-agent.md, docs/workflow.md, docs/agents.md, CLAUDE.md — the impact assessment costs less on small issues and no longer reads a bug twice. It reads in proportion to the change: with one or two named production files it reads those and the tests that cover them, and widens only when a criterion of a larger size shows up. For an XS or S change the artifact is short, with one line each for assets and gaps. When a bug triage exists, the Orchestrator passes its path and the assessment takes the files, callers and domains from the triage's evidence, reading only what sizing the change still needs. In three real runs the assessment took 1m23s to 5m27s on Opus, 2% to 21% of the agents' time, and weighed most on the smallest runs. The effect of these rules is not measured yet: read it from _usage.md over the next runs. Skipping the assessment when the issue or the triage already says simple_fix was considered and left out. It would have saved 1m23s on one of those three runs, the other two had neither a triage nor a Size: line, and without 00b-impact.md the unknown-fact rule would run the security review and a documentation draft on every simple_fix.
.opencode/agents/, .kimi-code/agents/ — the orchestrator and impact assessment mirrors carry the same body changes.

v9.1.1 — October 6, 2026

A real run stopped at the Start Gate after the human picked Request changes, the option marked (Recommended) because the impact assessment had escalated two open questions. The button carries no text, so the Orchestrator answered with a list of the accepted correction forms and waited, and the human had to ask Claude what the button was for. Re-running the assessment cannot close an escalated question, so the recommendation pointed at the one action that does not help, and a button pick without feedback had no branch at all.

Fixed

agents/orchestrator-agent.md, docs/workflow.md — the Start Gate never marks Request changes as (Recommended). Start keeps the recommendation when the assessment escalated a risk and names the open rows in its description, because those are questions only a person can close.
agents/orchestrator-agent.md, docs/workflow.md — Request changes picked as a button, with no text, asks what should change instead of waiting for text. At the Start Gate the options are answering the open questions now (each asked on its own, the answer written into ledger/open-questions.md), correcting a measured fact, changing the pipeline, or going back to the gate. At every other gate they are answering an open question from the Summary, describing the change, or going back. The agent is never re-invoked with empty feedback.
.opencode/agents/, .kimi-code/agents/ — both orchestrator mirrors carry the same body changes.

v9.1.0 — October 6, 2026

Three real runs of a downstream project showed where the pipeline spent a person's time and where it caught defects. The review gate is where the human changed decisions (rows the loop had auto-accepted as low were promoted to Mitigate now), so it stays. The gates that resolved as a bare "Approve" are the ones that can continue on their own. Two rules that read wrongly on the short path are fixed in the same release.

Added

agents/orchestrator-agent.md, docs/workflow.md, docs/faq.md, docs/overview.md, CLAUDE.md — phase continuation (HITL step 2b): after the bug triage, the requirements and the last wave of Phase 3, the orchestrator runs every check the gate would run and continues without asking when none of them turns something up. It prints one line with the rows it accepted for you (low, and medium in a simple_fix) and logs it. A significant_rework run, the architecture, the implementation plan, the review gate, a recheck that stopped, the QA plan, the release plan and the documentation draft keep asking. run.md gains phase_gates (on_signal for simple_fix and medium, every_gate otherwise and on an older checklist), and every gate at any gate restores a question at each one. The Start Gate says so in one Gates: line.
docs/use-cases.md, docs/.vitepress/config.js, docs/overview.md — a use-cases page: five shapes of work (a contained bug, a bug that hides a product decision, a medium feature, analysis now and build later, a short path with stronger tests) and, for each, what gets derived, which gates ask and which continue, and what the checks are for. The first three are shaped after real runs of a downstream project, without names or figures.
docs/setup/templates.md — "Short path with stronger tests": Effort: simple_fix plus Add: implementer-tdd-agent, test-verifier-agent keeps the short pipeline with test-first code and a test review.
skills/artifact-bookkeeping/SKILL.md — "Verdict values per phase": the exact phase: and status: values every agent writes, with the mixed case documented as it is, and the note on open_dispositions.

Changed

agents/orchestrator-agent.md, agents/bug-triage-agent.md, docs/workflow.md, docs/agents.md, docs/agent-files.md, docs/setup/templates.md, CLAUDE.md — a bug triage can raise the effort the impact assessment measured and never lower it: quick-fix against a medium or larger measurement keeps the measured effort, and the Start Gate names the conflict and the Effort: simple_fix line that takes the triage's word instead. The triage came from reproducing one symptom, the measurement from reading the code that would change.
agents/orchestrator-agent.md — a resume re-invokes an interrupted agent with recovery: true only when it defines that mode (implementer-tdd-agent, implementer-coder-agent, implementer-lead-agent, documentation-agent). Every other agent is re-run from the start with its first prompt and a line telling it to write its report again and check that a ledger row is not already there.
docs/index.md, docs/metrics.md, docs/workflow.md, CLAUDE.md — the claims that a human sits at every gate are qualified where three gates now continue on their own, and the resume text says which agents have a recovery mode.
skills/artifact-bookkeeping/SKILL.md — total in risk_counts is an optional key, because only one of the six templates writes it.
.opencode/agents/, .kimi-code/agents/ — both orchestrator mirrors carry the same body changes.

Fixed

agents/orchestrator-agent.md, docs/setup/templates.md, CLAUDE.md — threat_rows and behaviour_delta are absent by design, not unknown, when architect-agent did not run. The unknown-fact rule had them count as the value that runs the agent, so every simple_fix (which never has an architecture) ran the security review and a documentation draft. They now count as none, the two rules fall back to their other conditions, and at the Phase 3 gate the domains are compared with the files the implementation wrote.
agents/orchestrator-agent.md — the review loop's state no longer carries blocking_prev, which was written every iteration and never read.
agents/orchestrator-agent.md — in a real run the orchestrator ended its turn on one line of text after an implementer handed back its report, and the completion notification queued behind it never woke it: the run sat silent for 21 minutes. A message headed [Subagent hand-back] is no longer answered with text alone. The orchestrator first makes a tool call it needs anyway and treats a notification that arrives meanwhile as the return, and makes a second call when none has arrived before it ends the turn. In the run, the same sequence with a tool call in between delivered the notification inside the turn.
agents/orchestrator-agent.md — at the start of every turn the orchestrator checks in_flight against the notifications in its context, so a completion that landed without waking it is still acted on.
agents/orchestrator-agent.md — the wait line now says what to do when nothing follows (reply continue). A continue with no notification does not re-invoke the agent at once: the original may still be running, so the orchestrator asks once whether it was stopped, then uses the recovery: true path.
docs/workflow.md, CLAUDE.md — the wait rules and the evidence behind them, including why treating the hand-back as the return was rejected.

v9.0.0 — September 28, 2026

The start of a run asked the human to decide, before any code had been read, things an agent was about to establish with evidence: how big the change was, which agents should run, which implementer. The pipeline is now derived from facts, at the point in the run where each fact exists, and the human confirms or corrects it at a gate. Major version because implementer-coder-agent changes meaning: an issue that checked it to avoid tests now gets the tests its touched modules call for.

Added

agents/orchestrator-agent.md — one rule table derives every agent from facts: pm-agent, architect-agent, whether code is written and code-reviewer-agent at the start; the implementer right before the plan; test-verifier-agent and security-reviewer-agent at the implementation gate; qa-plan-agent, release-planner-agent and documentation-agent at the review gate. Each decision is printed at the gate before it with the rule that fired, and a correction there holds for the rest of the run and is logged in _tracking.md.
agents/orchestrator-agent.md — the start gate: one question per run showing the derived pipeline, effort and auto-fix budget, replacing the four-question agent menu and the "How big is this change?" question. Free text corrects any of them.
agents/orchestrator-agent.md — a project setting, asked once and stored in .kairos/.manual-qa, says whether a person verifies features by hand; it is the input to the QA plan rule no code can supply.
agents/implementer-coder-agent.md — ## Test Decision in the plan: whether the project has a suite, which touched modules already have tests, and what the coder will add or update. Skipping tests needs a written reason, visible at the plan gate.
agents/architect-agent.md — facts in the frontmatter (domains, test_first, contract_change, behaviour_delta, threat_rows) that choose the implementer, Team Mode, the security review and the documentation phase.
agents/impact-assessment-agent.md — orchestrated mode: started by the orchestrator on every derived run, it skips its own disposition loop and gate, which the orchestrator presents at the start gate.
agents/orchestrator-agent.md — a project file, .kairos/.models, sets the model of each agent the orchestrator dispatches: before every call it passes the listed alias as the call's model, which outranks the agent's own model:. With no file, or on a host whose Agent call takes no model parameter, every agent keeps its shipped model. The Start Gate shows the lines in effect.
agents/impact-assessment-agent.md, agents/orchestrator-agent.md, docs/setup/templates.md — a T-shirt size (XS to XL) for every issue, measured before any code is written from the same facts as the effort, which now follows from it (XS/S are simple_fix, M/L medium, XL significant_rework). The start gate shows it and, when you confirm, sets a size: label on the issue so the tracker can group an epic's issues by size. A Size: line in the ## KAIROS Pipeline block overrides it and the effort with it. It measures how much of the codebase moves, not hours.
agents/qa-plan-agent.md, agents/orchestrator-agent.md, docs/workflow.md — a QA plan above three checks is written as a Markdown file in the repository instead of a long issue comment, and the comment points to it. The directory is asked once per project and stored in .kairos/.qa-dir. Up to three checks and no epic, the comment carries the plan as before.
agents/qa-plan-agent.md, agents/orchestrator-agent.md, docs/setup/templates.md — an epic gets one cumulative QA plan: every issue of the epic writes its own section into the same file, next to a table of the epic's issues with their sizes, and the comment goes on the epic. The epic is read from the tracker when its CLI exposes one, or from an Epic: line in the ## KAIROS Pipeline block.
agents/orchestrator-agent.md, docs/setup/templates.md, docs/workflow.md, docs/overview.md — areas: the run can be limited to analysis, development, review or delivery, asked once at the start (all areas is the default, one click) or read from an Areas: line in the issue. Inside the chosen areas the rules still derive each agent, so nobody scrolls an agent list. Reviewing or delivering without a build uses the git diff against the default branch as the change surface, and running the same issue again offers the areas that were not run.
scripts/usage.mjs, commands/usage.md, agents/orchestrator-agent.md, skills/artifact-template/SKILL.md — /kairos:usage and _usage.md: after every agent that returns, the orchestrator has the script rewrite .kairos/<feature_folder>/_usage.md with one row per agent call (the model that actually answered; input, output, cache-write and cache-read tokens; time), a total, and a flag when the model differs from .kairos/.models or the agent's model:. The figures are read from the subagent transcripts Claude Code writes, counted once per response, and written by the script itself, never retyped by a model or reported by an agent. Claude Code only; the transcript format is undocumented, so it is best effort.
skills/artifact-template/SKILL.md — §5, the ## Ledger Update block a reviewer returns instead of writing the ledger in a review wave.
agents/orchestrator-agent.md, docs/workflow.md, docs/faq.md, CLAUDE.md — one issue, one folder: on a finished run, Start a new run archives the run's reports to runs/run-<k>/ (with snapshots of its _tracking.md and run.md), keeps the ledger, the triage and the tracking log, re-runs the impact assessment for the next slice and tells every agent where the earlier runs are. run.md gains run, started, scope and earlier_runs, and _usage.md counts only the current run. Create new folder is no longer offered for an issue.
agents/test-verifier-agent.md, agents/qa-plan-agent.md, agents/orchestrator-agent.md — a fourth acceptance-criteria state, later — <slice>: a criterion the requirements' slice table or the approved plan assigns to a slice this run does not build is neither covered nor a gap. The tracking file shows it as later and the QA plan adds no case for it.
agents/pm-agent.md, agents/test-verifier-agent.md, agents/orchestrator-agent.md — pm-agent writes a ## Slices table when the issue says the work lands in several steps (or is XL with independent parts): every acceptance criterion belongs to exactly one slice, and a later run keeps the earlier slices and IDs. It is what the later — <slice> criterion state reads, and the orchestrator passes the run's scope: to the agents.

Changed

agents/implementer-coder-agent.md — code-first instead of code-only: it writes the code, then extends the tests of the modules it touched when the project has them. A simple_fix routes here, so the quick path no longer drops tests on a repo that has them, and test-verifier-agent runs whenever it wrote a test.
agents/impact-assessment-agent.md — reports facts (domains, test_suite, contract_change, change_kind) instead of a recommended_agents list, so no decision has two sources.
agents/orchestrator-agent.md — Team Mode is offered on the TDD path when two or more of backend/frontend/db are touched (was three), Agent Teams is enabled and the host is Claude Code. The cost confirmation stays.
agents/orchestrator-agent.md, docs/setup/templates.md — a ## KAIROS Pipeline section now carries corrections: Effort:, Auto-fix:, Skip:, Add:. An older checklist still wins over the derivation and runs exactly as before, with a one-time Derive instead option. The issue write-back is offered only when you corrected something, and its options no longer mention internal files.
agents/code-reviewer-agent.md, agents/test-verifier-agent.md, agents/qa-plan-agent.md, agents/bug-triage-agent.md, agents/implementer-tdd-agent.md — read whether the coder wrote tests from its own report instead of assuming it never does.
skills/artifact-bookkeeping/SKILL.md, skills/code-simplification/SKILL.md — required frontmatter fields for the new facts; the no-test refactor rule applies when no test covers the code, not whenever the coder ran.
.opencode/agents/, .kimi-code/agents/ — both mirrors carry the same changes.
CLAUDE.md, README.md, docs/workflow.md, docs/agents.md, docs/overview.md, docs/agent-files.md, docs/agent-files-team.md, docs/agentic-loop.md, docs/faq.md, docs/index.md, docs/setup/ — describe the derived pipeline and the code-first coder.
docs/.vitepress/config.js — Impact Assessment moves from the "Standalone — you run these" sidebar group to the pipeline group, and "Code Only" becomes "Code First".
commands/setup.md — writes .kairos/.models (Default, Economy or Custom, aliases only) instead of copying the agents into the project and editing their frontmatter, so it works on a plugin install and nothing needs re-applying after an update. inherit, full model IDs and models for agents the file does not cover stay on an Advanced path that edits frontmatter or settings.json.
docs/setup/claude-code.md — "Customizing models" describes the file and its limits (aliases only, dispatched agents only, Claude Code only). The tier counts match the 17 agents (7 reasoning, 10 execution), the QA plan agent is added to the per-agent defaults, and a note separates Claude Code's effort: frontmatter field from KAIROS's effort.
docs/workflow.md, docs/setup/opencode.md, docs/setup/kimi-code.md, CLAUDE.md — describe the file and say OpenCode and Kimi Code ignore it.
.opencode/agents/, .kimi-code/agents/ — both orchestrator mirrors carry the same body change.
agents/qa-plan-agent.md — a tester is never sent to the developer's tools. A precondition is reached through the product, prepared by a developer and named as such in Setup, or written up as a risk; dev tools, scripts and hand edits to the database are no longer steps a plan can contain. The example charter that throttled the network in the browser is replaced.
agents/qa-plan-agent.md, agents/orchestrator-agent.md — the QA plan is delivered after you approve it, not before: in an orchestrated run the orchestrator posts the comment and hands the file to documentation-agent once the QA gate resolves. The agent leaves two files in the feature folder for that, _qa-comment.md and, above the threshold, _qa-file.md. Standalone, it prints where to copy the file.
agents/documentation-agent.md — in verbatim passthrough it no longer runs a gate of its own: it checks that the target is a documentation file and writes what the orchestrator hands over. The QA plan file uses the same path as the project summary.
skills/issue-tracker-comment/SKILL.md — the QA plan's extract body is posted by the orchestrator from _qa-comment.md in an orchestrated run.
skills/artifact-bookkeeping/SKILL.md — the required frontmatter table gains size for the impact assessment and delivery for the QA plan, on artifacts written from now on; older ones keep resuming without them.
agents/orchestrator-agent.md, agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md — the presets that follow the effort are called effort presets (they were size presets), so the T-shirt size has one meaning in every file.
.opencode/agents/, .kimi-code/agents/ — both mirrors carry the same changes.
CLAUDE.md, docs/workflow.md, docs/agents.md, docs/overview.md, docs/agent-files.md, docs/setup/templates.md, docs/setup/claude-code.md, docs/skills-mcp.md — describe the size, the QA plan file, the epic plan and the project summary gate.
agents/orchestrator-agent.md, docs/setup/templates.md, docs/workflow.md, docs/overview.md — a run starts without asking when the answer is already on record. An issue with a ## KAIROS Pipeline section gets an announcement instead of the Start Gate question (and no checklist question; say derive in the prompt to ignore a checklist), unless the issue could not be read, the impact assessment left an escalation or failed, a gating fact is unknown, the architect was skipped against its rule or nothing would run. A folder left in_progress or stopped resumes without the folder question and without the resume confirmation, and a folder with only context, impact or triage files is reused instead of resumed. A gate the earlier session left open is recorded in run.md as gate_pending and shown again first, so removing the confirmation cannot skip an approval.
agents/code-reviewer-agent.md, agents/test-verifier-agent.md, agents/security-reviewer-agent.md, agents/orchestrator-agent.md — in a review wave the three reviewers no longer write constraints.md, decisions.md and open-questions.md: each returns a ## Ledger Update block in its own report and the orchestrator applies the three one after another, allocating the new ids itself and keeping a row 🔴 open when two reviewers disagree. Two reviewers that read the same row and wrote it back in the same minute could overwrite each other. The same step applies to loop iterations and recheck waves.
agents/orchestrator-agent.md, docs/setup/templates.md — the derived pipeline is smaller. architect-agent at medium no longer runs just because backend and frontend both change (it still runs for db, auth or a contract change), and test-verifier-agent does not run on a simple_fix, where no pm-agent means no acceptance criteria to map and code review already reads the tests. Add: restores either.
agents/impact-assessment-agent.md, docs/agents.md — the size counts production files only (tests, docs, lockfiles and generated files follow a change, they do not size it) and takes the smaller of two adjacent sizes when nothing forces the larger; a small change with its tests no longer reaches M.
agents/orchestrator-agent.md — the Start Gate lists the agents decided now and folds every later decision into one line, with the areas that were not selected in another, instead of nine lines of which five said "decided later".
.opencode/agents/, .kimi-code/agents/ — both mirrors carry the same changes.
CLAUDE.md, docs/workflow.md, docs/agents.md, docs/overview.md, docs/faq.md, docs/setup/claude-code.md, docs/setup/templates.md — describe areas, the runs that start without asking, the single ledger writer in a review wave, the smaller pipeline and /kairos:usage; CLAUDE.md also records why QA plan, release planner and documentation do not run as a wave.

Fixed

agents/orchestrator-agent.md — resuming a run whose implementer was interrupted near its end started the review wave before the implementer had reported back. The implementer writes 03-implementation.md before its ledger update and before it returns, and the resume rule read that file as proof the phase was done. An agent now counts as complete only when its call returns: the orchestrator records every dispatch in ledger/run.md (in_flight), opens no gate and starts no other agent while one is running, and a resume that finds an agent still in flight re-invokes it in recovery mode instead of trusting the report on disk.
agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md, agents/team/implementer-lead-agent.md — a recovery run (recovery: true) checks git status, the approved plan and the earlier report first, keeps the files that already match the plan and finishes only what is missing, instead of starting again on a half-written change. The report is now the last file an implementer writes, after the ledger update, so its presence means the pass is finished.
docs/workflow.md, CLAUDE.md — describe the in-flight record and the recovery run.
.opencode/agents/, .kimi-code/agents/ — both mirrors carry the same changes.
commands/setup.md, docs/setup/claude-code.md — the "global subagent model" option said CLAUDE_CODE_SUBAGENT_MODEL overrides every agent's frontmatter. Claude Code ranks the per-call parameter first, frontmatter second and the variable third, so with every KAIROS agent declaring model: the variable changed nothing. The option now also sets CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1, and the docs give the real order.
agents/orchestrator-agent.md, agents/documentation-agent.md — the project summary at the end of a run promised a second Approve / Request changes / Stop gate run by documentation-agent, which is a subagent and cannot ask you anything. The orchestrator improvised the gate, and the file was already written under docs/ before you approved it. The orchestrator now owns the gate: it writes the draft inside .kairos/, prints the path, and hands it to documentation-agent only after you approve.
agents/orchestrator-agent.md — on GitLab the issue was read with glab issue view <id> --json description, but that command has no --json flag (JSON comes from --output json), so the read failed and a ## KAIROS Pipeline section was silently ignored. It now reads --output json, which also carries the epic and the labels.
agents/orchestrator-agent.md, agents/documentation-agent.md — the documentation phase never wrote the README or CHANGELOG in an orchestrated run: the agent skipped its own gate, the orchestrator ran the real one, and the agent had already returned when you approved, so its write step never ran. The phase is now two calls, like the implementer's: a draft that writes only 06b-documentation.md, and, after you approve it, a write that applies the approved text to the documentation files and records what it wrote under ## Docs Written. A file that changed since the draft is skipped and reported, and a resume between the gate and the write shows the gate again.
docs/workflow.md, docs/agents.md, CLAUDE.md — describe Phase 6b, which had no section in the workflow page, and its two calls.
agents/orchestrator-agent.md — a reworded prompt for the same issue started the issue again: the folder was matched by its exact slug, which follows the wording of the prompt, so the existing folder and the triage in it were missed. The folder is now found by the issue reference, and the issue is read before the folder is named. Step 0a also read files inside a folder that Step 0b had not named yet.
agents/orchestrator-agent.md — a failed read of the issue was silent, so a saved ## KAIROS Pipeline section was ignored and then offered again at the write-back. A failed read prints one line, a successful one says what it found, and the section heading is matched case-insensitively at any level.
agents/orchestrator-agent.md — the issue write-back offered to save choices the issue already held, and composed the block from this run's corrections alone, so accepting it would have deleted the issue's other lines (a Skip:, an Auto-fix:). It now re-reads the description first, merges the issue's lines with the corrections, shows what is new, and offers nothing when the result equals what the issue says.
agents/orchestrator-agent.md, agents/security-reviewer-agent.md — nothing applied the ledger update block security-reviewer-agent returns, so its constraint re-openings and decisions never reached the ledger. The review wave's merge step applies it.
agents/orchestrator-agent.md — 00c-bug-triage.md was missing from the files Step 0b treats as pre-pipeline, so a folder holding only a triage had no defined resume point.
agents/orchestrator-agent.md — _tracking.md contradicted itself after a run ended: ## Open Questions, ## Open Constraints and ## Accepted Risks were written once at Step 10 and never refreshed, so answered questions and closed constraints stayed listed (and an open one went missing) under a ## Status that was current. They are derived views, rewritten with the status from one read of the ledger on every event, and events after the run are logged as after run. The log keeps one line per event with no blank lines between them.
agents/orchestrator-agent.md — a second run on an issue offered only Create new folder, so a large issue built slice by slice ended with two folders and two ledgers that drifted apart.

Removed

agents/orchestrator-agent.md — the agent selection menu, the effort question, the "Which implementer?" question and the fixed Quick fix agent list.

v8.6.0 — September 25, 2026

A real run showed the recheck after review re-running every reviewer on a correction of a few lines, and a correction asked outside the review gate following no rule at all, so the orchestrator improvised which reviewers to run again.

Changed

agents/orchestrator-agent.md — the recheck after a fix pass runs only the reviewers the fix calls for, read from the files the pass wrote and the reports its rows came from: code review when it touched non-test code, test verification when it touched tests or fixed a test-verification finding, security review when it fixed a security finding or touched a file that review cited. Every skip is logged in _tracking.md, and a fix whose files cannot be read still gets every reviewer. A recheck that turns up nothing continues without a gate, under the same rule as implementation waves.
agents/orchestrator-agent.md — a code change asked at a recheck gate or at the QA plan gate goes through the same fix pass and the same recheck, instead of an unruled re-run of the implementer.
agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md — a fix pass can also carry rows bound at a recheck gate or at the QA plan gate (MUST — from 05b).
.opencode/agents/, .kimi-code/agents/ — both mirrors carry the same body changes.
CLAUDE.md, docs/workflow.md, docs/agentic-loop.md — describe the recheck selection and why it reads the fix's files rather than the issue's size.

v8.5.0 — September 25, 2026

Measured on a real epic (three issues, 8, 23 and 29 gates), the time a large change took was not spent in automatic retries: the Loop Actuator never fired once. It went into gates with no decision in them (fourteen waves answered "Continue"), fix passes run one review phase at a time (four after review on one issue, each with its own recheck), defects on already-shipped flows found only by the QA plan, and phase reports of up to 81KB opened in the editor at every gate while the only consolidated view arrived at the end of the run.

Added

agents/orchestrator-agent.md — _tracking.md in the feature folder, created before Phase 1, opened once and kept current for the whole run: status, blockers, open questions and constraints, issue alignment (every AC-n as pending, covered, manual, gap, changed or dropped, plus every scope change) and an append-only log of every gate, wave, fix pass, loop exit, resume and stop. It replaces _recap.md, which was written only at the end, and absorbs ledger/audit-log.md.
agents/orchestrator-agent.md — review wave: code review, security review and test verification start together on the same code, in parallel where the host supports it, and share one gate, one Risk Disposition Loop and one fix pass for every row marked Mitigate now, followed by one recheck.
agents/architect-agent.md — Behaviour Delta section, only when the change alters what a user of an already-shipped flow can observe: what the user sees before and after, including on a new rejection or limit, and every new limit recorded as a constraint that names its unit.
agents/pm-agent.md, agents/architect-agent.md, agents/orchestrator-agent.md — a decision that widens or narrows what the issue asked opens with Scope: in decisions.md, which is what _tracking.md's issue alignment reads.

Changed

agents/orchestrator-agent.md — a wave that ends partial continues on its own after the usual checks, and stops at a gate only on a new medium+ risk, a new constraint, a failing test, a file outside the plan, an Escalate or a malformed artifact. wave_gates: every_wave in ledger/run.md restores a gate per wave.
agents/orchestrator-agent.md — gates no longer open the phase report in the editor: they print its path, and replying open or apri opens it and shows the same gate again. The implementation plan still opens automatically.
agents/orchestrator-agent.md, docs/agentic-loop.md — the two Loop Actuators become one review loop with one auto-fix budget, driven by code review's and test verification's critical/high findings plus acceptance-criteria gaps; security findings still wait for the gate. A final pass of every active reviewer replaces both regression Guards. A run.md or an issue with the older two budgets uses the larger one.
agents/code-reviewer-agent.md — in a review wave it keeps its static checks but leaves test execution to test verification, so the two never build into the same output at once. Pre-existing: rows no longer count toward the loop's convergence signal: they reach the gate, where they can be fixed or deferred, instead of making the implementer loop on code the change did not write.
agents/orchestrator-agent.md, docs/agentic-loop.md — test verification's coverage figure no longer restarts the implementer on its own: only critical/high findings and acceptance-criteria gaps count. A coverage below target, or one that could not be measured, reaches the gate as a finding.
agents/orchestrator-agent.md — at the review gate, Approve is recommended once every row is dispositioned, because approving is what sends the Mitigate now rows to the fix pass; free text asking for a code change joins the fix pass instead of re-running the reviewers. Skip next at the Phase 3 gate skips the whole review wave.
agents/security-reviewer-agent.md — runs without 04-review.md in a review wave, without the missing-input warning; the orchestrator de-duplicates what both reviewers raise.
agents/test-verifier-agent.md, agents/qa-plan-agent.md — read the architecture's Behaviour Delta, when present, as input.
docs/setup/templates.md — Auto-fix: N covers the whole review wave; the Refactor / Rework preset uses the single line. The older Auto-fix after review / Auto-fix after tests pair still parses.
agents/documentation-agent.md, skills/artifact-template/SKILL.md, commands/view.md — name _tracking.md, and _recap.md in folders from before v8.5.0. Like _recap.md before it, _tracking.md is read by the human only: no agent takes it as input.
agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md, agents/team/implementer-lead-agent.md — a fix pass after the review gate arrives with the human's Mitigate now rows as its only scope; the implementer addresses exactly those, marks each resolved and logs the pass as a fix pass.
agents/retrospective-agent.md — counts as friction a defect found by a later phase than the one whose job it was (a code fix bound by the QA plan, a recheck after it) and every Scope: decision.
agents/orchestrator-agent.md — whether a run finished is recorded as run_status in ledger/run.md, so resuming a folder never depends on the human-facing file.
.opencode/agents/, .kimi-code/agents/ — both mirrors carry the same body changes.
CLAUDE.md, docs/workflow.md, docs/agents.md, docs/overview.md, docs/setup/claude-code.md — describe the review wave, the wave rule, the Behaviour Delta and the tracking file.

Fixed

agents/code-reviewer-agent.md, agents/test-verifier-agent.md — both now write convergence_signal.issues_critical_high in their frontmatter. The orchestrator's loop read that value to decide whether a retry made progress, but neither reviewer ever wrote it, so the progress check had no number to compare.

Removed

agents/orchestrator-agent.md — ledger/audit-log.md is no longer written; an existing one is read for the pre-v8.4.0 effort fallback and copied into _tracking.md's log on first touch. A finished folder's _recap.md is left as it is.

v8.4.0 — September 24, 2026

The ## KAIROS Pipeline block in an issue could not say everything the orchestrator's own menu asks. Team Mode was missing from it, the optional agents looked like every other line, and there was no way to set how many times the agents may fix their own problems, so a large change driven from an issue still stopped to ask. The block now covers all of it in words an issue author understands. Issues written in the old format select the same agents and run exactly as they did: the new Auto-fix: line is the only switch to the new behaviour.

The ledger lost state between sessions and mixed four kinds of record in one file. A resumed pipeline recovered only the effort: the auto-fix budgets, the quick-fix mode and the agent selection were gone, and the resume point could offer a phase nobody had selected. Retry bookkeeping lived in open-questions.md beside the real questions, deferred risks counted as open questions forever, an Escalate left two unlinked rows to close, and a legitimate change of decision was flagged as a contradiction at every later gate. Each is fixed, and feature folders written before this version keep resuming: readers fall back to the older location or format, and the orchestrator migrates on first touch.

Nothing in the plugin wrote the ## KAIROS Pipeline section itself: whoever installed KAIROS had to type the block by hand. The orchestrator now offers to write back the selection the human just confirmed.

Added

docs/setup/templates.md — Auto-fix: N line, or the pair Auto-fix after review: N / Auto-fix after tests: N: how many times the agents may fix their own problems before stopping to ask. 0 means always ask. The line also turns on the defaults that come with the chosen effort; a block without it is an older template and keeps every problem for you.
docs/setup/templates.md — implementer-lead-agent (Team Mode) joins the checklist, and the list is grouped into Analysis, Build (pick one), Review and After build, with a table saying when each optional agent is worth adding.
agents/orchestrator-agent.md — Issue Write-back at Step 0f: when the run started from an issue and the selection came from the menu, the orchestrator shows the block it would write and asks Add to the issue, Keep it local, or Don't ask again in this project. It appends the section or replaces only that section, re-reading the description first and writing nothing if that read fails. The block carries the agents, Effort: and Auto-fix: values the run resolved, and a section already in the issue and confirmed unchanged is never rewritten. GitLab and Bitbucket are written; on Jira, and whenever a tool or credential is missing, it prints a paste-ready block and the run continues.
agents/orchestrator-agent.md — new ledger/run.md, written at Step 0f and read back on resume: effort, active agents, auto-fix budgets, quick-fix mode. A resumed run keeps the human's settings and skips the phases they never selected. A folder without it falls back to the effort in the audit log's header, asks once for the auto-fix budgets when an implementer phase is still ahead, and behaves as before otherwise.
agents/orchestrator-agent.md — new ledger/loops.md holds the auto-fix state while a retry runs and the history of retries that did not converge. On resume, loop sections an older run left in open-questions.md move there, and a retry the earlier session never finished is recorded as interrupted instead of being picked up as live by the next implementer.
agents/orchestrator-agent.md — decisions.md gains a Supersedes column. When a human accepts a decision conflict at a gate, the orchestrator records which decision was replaced, and later conflict scans stop flagging it. No phase agent writes that column, so the agent being checked cannot switch the check off.
agents/orchestrator-agent.md — Template Parsing rules at Step 0d: group headings are ignored, the older flat checklist parses identically, more than one checked implementer falls back to the selection menu instead of picking one, and the Auto-fix lines are read and capped at the same ceiling as the retry prompt. A block with no Auto-fix line runs as before: both retry budgets manual, the plan gate kept at simple_fix, and the retry question asked only at significant_rework.

Changed

agents/orchestrator-agent.md — a template that sets both auto-fix values skips the retry question even for significant_rework; one that sets a single value is asked only about the other. The pipeline announcement and the issue-selection preview state the retry budget as "Auto-fix: N after review, N after tests" instead of loop and phase names.
docs/setup/templates.md — every preset carries an Effort: line and, where a build agent is checked, an Auto-fix: line; Hotfix is simple_fix, and Refactor / Rework shows the two-line auto-fix form.
.opencode/agents/, .kimi-code/agents/ — both mirrors carry the same body changes.
docs/workflow.md — documents the Auto-fix lines and the size presets on the template path.
agents/orchestrator-agent.md, agents/pm-agent.md, agents/impact-assessment-agent.md, agents/team/implementer-lead-agent.md — a Defer writes ⚠ deferred instead of 🔴 open, so a risk shipped knowingly no longer counts as an open question at every gate and at pipeline end. Older deferred rows are recognised by their deferred risk note. An Escalate writes the constraint and the question with references to each other (BLOCKING — see Q7).
agents/architect-agent.md, agents/release-planner-agent.md — the two full re-walks close an escalated constraint from its question's answer. The release plan lists deferred questions as accepted risks, never as release blockers, and its ledger summary counts them apart.
agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md, agents/team/implementer-lead-agent.md, agents/code-reviewer-agent.md, agents/test-verifier-agent.md — read and update auto-fix state in ledger/loops.md. agents/retrospective-agent.md reads loop history there, or in open-questions.md for an older folder.
agents/architect-agent.md and every other decisions.md writer (implementer-tdd-agent, implementer-coder-agent, implementer-lead-agent, code-reviewer-agent, security-reviewer-agent, test-verifier-agent, qa-plan-agent, release-planner-agent) — migrate an older five-column table before appending, and leave Supersedes to the orchestrator.
CLAUDE.md, docs/workflow.md, docs/agentic-loop.md — describe the six ledger files, the new statuses and the compatibility rule.
CLAUDE.md, docs/setup/templates.md, docs/workflow.md — document the issue write-back, the orchestrator's second narrow exception to writing only inside .kairos/.

Fixed

agents/orchestrator-agent.md — on runs without release-planner-agent (the Bug Fix, Hotfix and Refactor presets), a constraint left 🔴 open — an unmet MUST from a Mitigate now, or a BLOCKING escalation — reached neither the end-of-pipeline warning nor _recap.md, which read only the open questions. Both now list open constraints, and the recap's cleanup keeps the phase files while one remains.
agents/orchestrator-agent.md — _recap.md gains an ## Accepted Risks section for deferred risks, which would otherwise have vanished from it once Defer stopped writing 🔴 open. Deferred risks no longer hold back the cleanup recommendation. The Audit Trail now lists every retry that did not converge and every decision replaced at a gate, and a header line records the run's effort and auto-fix settings from run.md.
agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md, agents/team/implementer-lead-agent.md — the ## Summary of 03-implementation.md described only the last wave or fix pass, while the rest of that cumulative file described the whole feature, so the Phase 3 gate showed what the final wave did instead of the feature. It now states the feature's state with the current pass named at the end, and Next follows status instead of always naming code-reviewer-agent, which contradicted the gate's own "continue with the next wave" question.
skills/artifact-template/SKILL.md — a cumulative artifact gets a cumulative Summary.
agents/orchestrator-agent.md — on the template path the retry budget was left unset while the retry question was still skipped, so what happened on a failed review depended on how the model read an undefined value. An older template now sets both budgets to manual explicitly, matching how those runs actually behaved, and a template with an Auto-fix line gets the effort's size presets, with the template's own checks still deciding which agents run.
docs/setup/templates.md — the Documentation preset checked only pm-agent, so it never ran documentation-agent.

v8.3.0 — September 23, 2026

A real Phase 5b plan for a concurrency fix ran to sixteen manual cases, four charters and eight risks, and its steps told the tester to hold SQL application locks in a database console, derive lock resource names by hand, and build raw request bodies. It was written for a developer. The plan now writes for two readers in two languages, opens with the change's core, and keeps code evidence where only the gate reads it.

A review found a format defect on one field of a validator, the fix for it touched the same method, and the identical defect on the field beside it survived both code review and test verification. Nothing in the reviewing agents asked them to look for a finding's siblings, and nothing said that unchanged lines inside a touched function are part of the review. Both gaps are closed.

Added

agents/qa-plan-agent.md — new step 0 Name the Core and ## Core block: one sentence on what the change fixes, the one to three behaviours that mean it failed, and the cases that prove them. For a bug, the reported scenario comes first. Core cases lead the Manual Test Cases table, and the step runs in Lean Mode too.
agents/qa-plan-agent.md — reads 00c-bug-triage.md when present: its observed-vs-expected and reproduction steps become the plan's core.
agents/qa-plan-agent.md — new optional ## Expected Behaviour Changes section (step 2a): at most five rows telling the tester which visible differences are intended, including out-of-scope behaviour a tester might mistake for a defect of this change, so none of it gets filed as a bug or turned into a test case.

Changed

agents/qa-plan-agent.md — tester-facing sections are written in product language only: screens, actions, visible outcomes, never a class, file, SQL object, key format or pipeline ID. Code evidence stays in Coverage Complement and Risks. Complement rows get CCn IDs, so a case's Source cites AC-n, bug or CCn instead of a file:line.
agents/qa-plan-agent.md — a manual case checks an outcome a person observes through the product, never the mechanism behind it. A check that only a database console or a hand-built request can perform becomes one gate risk instead of a tester's step. UAT Sign-off gains the matching answer, not verifiable by hand, rated high like not verifiable as written. An uncovered line that no user action reaches produces no case. One case per behaviour, with screens and modes listed as variants; at most two cases per uncovered AC-n in Full Mode; at most four steps and a one-sentence expected result per case. Field-data questions go to open questions, not to test cases.
agents/qa-plan-agent.md — ## Risks admits four row kinds only: a regression retest citing a caller, an AC-n that cannot be checked by hand, an uncovered VERIFICATION row, and an open question the release depends on. Automated-suite gaps stay test-verifier-agent's, and code defects get a one-sentence pointer to code review instead of a trace. A regression row's Mitigation/Fix is the tester's instruction in product language.
agents/qa-plan-agent.md — the issue comment leads with the Core and drops every empty or N/A section, the cases' Source column, the retests' code-level Description, the evidence columns, and the UAT rows already accepted by automation. Test Data & Environment lists only what the manual cases need.
skills/artifact-template/SKILL.md — Expected Behaviour Changes joins qa-plan's Disposition-exempt tables.
.opencode/agents/, .kimi-code/agents/ — both mirrors carry the same body changes.
CLAUDE.md, docs/workflow.md, docs/agents.md — document the two-reader split, the Core block and the narrowed Risks table.

Fixed

skills/analysis-discipline/SKILL.md — new principle 6, Sweep the Defect Class Before Recording a Finding: before writing a finding's row, check the enclosing function or class and every other use of the same pattern in the reviewed files for the same defect, and record every occurrence. An occurrence the diff did not introduce is reported with a Pre-existing: prefix so the gate can fix it now or defer it, never omitted. Principle 3 (scope-bounded investigation) now says that a found defect bounds this sweep rather than conflicting with it.
agents/code-reviewer-agent.md — a function the diff touches is reviewed whole, unchanged lines included, and on a loop iteration every unit the fix touched is re-reviewed in full, not only checked for the closed issue. Correctness gains an explicit malformed-input check: a presence check such as [Required] guarantees non-empty, never well-formed, and the resulting exception must reach a handler that maps it to the documented error instead of escaping as a 500.
agents/test-verifier-agent.md — for a validator, parser, or converter, every input field it accepts needs at least one malformed-value test, with the fields enumerated from the code under test rather than from the tests. A field covered only by a presence check is an issue even when no AC-n names it, and in Lean Mode too, since a malformed value is an error path.
.opencode/agents/, .kimi-code/agents/ — both mirrors carry the same body changes.
docs/skills-mcp.md, docs/agent-files.md — the analysis-discipline summaries name the new sweep.

v8.2.0 — September 21, 2026

Separates what the developer must satisfy from what a tester must stage. Acceptance criteria were absorbing both, and a criterion that needs two applications, a particular configuration, or two concurrent sessions on two machines to be checked stops being readable as a requirement — so the setup now travels in Phase 5b's QA comment on the issue, while the AC-n stays exactly where it was.

Nothing is dropped or renumbered for this: test-verifier-agent maps tests against those IDs and qa-plan-agent's own UAT Sign-off iterates them, so a criterion that existed only as a QA case would have no ID to be signed off against. The requirement stays in the issue; the choreography moves to the comment.

Added

agents/qa-plan-agent.md — Manual Test Cases gain a Setup column: the applications that must be running, the configuration or flag the case needs, how many concurrent sessions and on which machines, and the role each session is signed in as. Filled only where the case needs it (single session, standard config is a complete answer), and kept in Lean Mode too — a case whose setup a tester has to guess is not executable. The agent now also names the two reasons a check is manual: no assertion can see it, or no single developer environment can stage it.
skills/constraint-taxonomy/SKILL.md — twelfth category VERIFICATION: a check no single developer environment can stage. It is the third tenant of the declared-obligation mechanism, after ACCESSIBILITY and PRIVACY/COMPLIANCE, and it records how something is checked, never what the system must do — the requirement stays an acceptance criterion.
agents/qa-plan-agent.md — new conditional step 2b Cross-Environment Verification, gated on a declared VERIFICATION row exactly like the existing accessibility and privacy checks: it names which manual case covers each declared row, or raises a high risk when none does. Undeclared prints one N/A line, which is the normal case, and the step is never skipped by Lean or Trimmed Mode — the gate is the declaration, not the size of the change.
agents/pm-agent.md — elicits VERIFICATION where the human's own description already implies more than one actor or system in the same scenario, and never manufactures it otherwise.
agents/pm-agent.md — a criterion states a trigger and an observable outcome, never the setup needed to produce it. A criterion whose verification needs heavy choreography is still written and still keeps its AC-n; the choreography is planned in Phase 5b instead of being folded into the criterion or used as a reason to drop it.

Changed

agents/qa-plan-agent.md — the Issue Tracker Comment step now opens the posted comment with a line saying what it is: the manual half beside the issue's acceptance criteria, not a replacement for them. Same line in the paste-ready fallback used when no jira/glab is installed.
agents/qa-plan-agent.md, skills/issue-tracker-comment/SKILL.md — that comment now carries an extract instead of the whole artifact: manual cases with their setup, the cross-environment line, charters, regression retests, test data and UAT sign-off. The ## Summary and ## Coverage Complement sections stay in .kairos/, where the gate reads them; the Disposition column, which is the orchestrator's gate record, never reaches the tester. New Extract body variant in the shared skill, composed inline through a heredoc so Markdown tables survive quoting. Only risk rows citing a caller at a file:line become regression retests; an AC-n that is not verifiable as written, or an uncovered VERIFICATION row, reaches the tester through the section that owns it instead of under a "retest this" heading.
docs/workflow.md, docs/agents.md, CLAUDE.md — document the split at both ends of the pipeline: Phase 1's acceptance-criteria bullet and Phase 5b's QA-comment note.
.kairos/_qa-regression.md (new project-root artifact, written by agents/qa-plan-agent.md) — the cumulative catalogue of manual cases, fourth file to sit beside _lessons.md, _tech-debt.md and decisions/ because it outlives the feature that wrote it. 5b appends the reusable cases it writes with stable QA-n IDs and an Area, retires those the current change automated or removed, and at the next feature selects the active cases whose area that change touched — each row citing the changed file that puts it there. Until now a manual case died with its feature folder, so the retest a QA person actually performs, re-running old manual cases against a new change, had nothing to draw from. Grepping callers finds what the code can show; it cannot find the two-operator scenario someone wrote three features ago.
agents/test-verifier-agent.md, skills/artifact-bookkeeping/SKILL.md — the Acceptance Criteria Mapping table now has three states instead of two: covered by automation (at any level), verified outside the suite (manual — <Cn> → 5b, only when a declared VERIFICATION row names that AC-n), and gap. Only the third counts in gapIds and convergence_signal.ac_gaps, so only a real gap can drive the Phase 3 loop. A criterion needing two machines used to be reported as a coverage gap, which left the implementer two options: mock the second actor and fake the coverage, or let the loop exit on the thrash check. A unit test proves the code does what it was meant to do; it is not the level at which a use case is verified.

Fixed

skills/issue-tracker-comment/SKILL.md, agents/qa-plan-agent.md, docs/workflow.md, docs/setup/claude-code.md — every GitLab example used glab issue note --body, a flag that does not exist: the command takes -m / --message, so a copy-pasted post failed on the spot. Corrected everywhere, mirrors included.
agents/pm-agent.md, docs/agents.md, docs/skills-mcp.md — the optional skill hint still named outcome-issue-generator, a skill superseded by the merged issues-generator, and labelled it a Claude Code built-in. It is neither: the name is stale, and the merged skill is user-installed, so the docs promised something the plugin does not ship. Renamed everywhere, mirrors included, and moved into its own "User-installed skills" table instead of the built-in one.
agents/pm-agent.md — a standalone run asked "how do you want to proceed?" with Approve recommended even when the analysis carried a high risk, and resolved the whole Risks table as one bundle. It now runs the same per-row Risk Disposition Loop the orchestrator runs — Accept / Mitigate now / Escalate / Defer per row, low rows auto-accepted, the same on-demand explain when you ask why instead of choosing — and Approve stops being the recommended option once a row was Escalated. impact-assessment-agent already worked this way; pm-agent was the outlier.
agents/orchestrator-agent.md — at the whole-artifact gate, a critical/high row that the disposition loop had already resolved stripped Approve of its recommendation without giving it to any other option, so a requirements analysis naming one high risk reached the gate with nothing recommended at all. The phases with no pass/fail state (pm-agent, impact-assessment-agent, context-extractor-agent, bug-triage-agent, dependency-audit-agent) now follow the same carve-out the Phase 3a plan already had: a dispositioned high risk is a bound requirement for the next phase, not a reason to regenerate the artifact.
docs/workflow.md, docs/setup/claude-code.md — the pre-pipeline step told you to run @context-extractor-agent and @impact-assessment-agent, the exact @-mention that dispatches an agent as a subagent and strips AskUserQuestion — the defect already fixed for the orchestrator. Both now say to launch them as the session's primary agent, and the Claude Code warning covers every agent that asks something mid-run, not just the orchestrator.
docs/overview.md, docs/agents.md, docs/agent-files.md, docs/setup/vscode.md, docs/.vitepress/config.js — which agents you start yourself was stated differently on every page: the overview counted four standalone agents and the FAQ six, the two pre rows sat inside the pipeline table unmarked, two of the six sections never used the word standalone, one setup tree left the context extractor unannotated, and the sidebar was a flat 17-item list. The agent list is now split into Standalone — you run these and Pipeline — the Orchestrator runs these, the copy page's Quick jump gains a Started by column (and the Dependency Audit row it was missing), and both counts are reconciled in one sentence.

v8.1.0 — September 17, 2026

Makes the effort classification actually reach the agents that were written to act on it, and cuts the two costs a run pays regardless of size: a Full process on a small change, and a gate question nobody can answer. It also stops open questions being invisible until the pipeline is over.

The effort field and its Lean Mode have existed since 7.x, but they were emitted only by impact-assessment-agent — an optional pre-pipeline step most runs skip. With no 00b-impact.md on disk, every agent fell through to its own "treat as medium+" fallback and ran the Full process, on every change, forever. The orchestrator now resolves effort itself at Step 0e and states it in every subagent invocation, and medium finally has a behaviour of its own instead of being an alias for "as large as possible".

Added

agents/orchestrator-agent.md — Step 0e's Quick-Fix Check becomes a three-band Effort Check (simple_fix / medium / significant_rework), with 00b-impact.md's value pre-selected when that file exists. A new mandatory Effort Propagation rule states the resolved value verbatim in the invocation prompt of every subagent, which is what makes Lean and Trimmed Mode fire at all.
agents/orchestrator-agent.md — Step 0f's pipeline announcement now always shows the resolved effort, the mode it implies, and the resolved loop policy, marked (preset — reply to change) when either came from a preset rather than a prompt. A run no longer starts with its two cost-driving settings invisible.
agents/orchestrator-agent.md — the whole-artifact gate (HITL step 5) gains the on-demand explain trigger that until now existed only on Risk Disposition rows. Asking "why" or "non capisco" at a phase gate returns what the phase produced, what changes if you approve versus request changes, and whether the choice is cheap to revisit — then re-shows the same gate instead of advancing.
agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md, agents/code-reviewer-agent.md, agents/test-verifier-agent.md, agents/qa-plan-agent.md — new Trimmed Mode for effort: medium, until now present only in pm-agent and architect-agent. Each names exactly what gets shorter: waves only when the change spans more than one domain, boundary tests instead of the full category set, a one-line Performance check on a diff with no loop or query, a single exploratory charter. Coverage bars, assertion grading, rollback, and every ledger accounting pass stay full.
agents/orchestrator-agent.md — Effort Persistence: the resolved value is written into ledger/audit-log.md's header line, and Step 0b's Resume-existing flow reads it back before invoking the next phase. A pipeline routinely spans sessions; without this, a resumed run entered past Step 0e with no effort set and silently reverted every remaining phase to Full.
docs/setup/templates.md — the ## KAIROS Pipeline template block gains an optional Effort: line (simple_fix / medium / significant_rework), read at Step 0e. A template-driven run no longer has to default to medium.
agents/release-planner-agent.md — gains an Effort Detection section, having had none. In Lean Mode the runbook collapses to a single-stage rollout when the change carries no endpoint, schema, migration, or config change, and Monitoring names the existing alert instead of proposing new metrics. Rollback Strategy, Scope Coverage, and the final ledger re-walk are unchanged at every size.
skills/artifact-template/SKILL.md — the mandatory ## Summary head block gains a fifth line, **Open:**, carrying the ledger/open-questions.md IDs of the questions that phase left unanswered (Q3, Q7 — see ledger), or none. Same discipline as Needs your attention: IDs only, never restated text that drifts the moment someone answers, capped at three plus and N more. Since the orchestrator prints this block verbatim at every gate, open questions go from end-of-pipeline visibility to every-gate visibility.
skills/artifact-template/SKILL.md — new writer rule: an open point written in prose but not in open-questions.md does not exist. A question raised in a paragraph and nowhere else is invisible to every later phase, to the end-of-run ledger audit, and to _recap.md. Every agent now checks its body against the ledger before writing the Summary.
agents/orchestrator-agent.md — the gate print gains a second count line of the orchestrator's own: N question(s) still 🔴 open in ledger, read from the ledger rather than from the artifact. It is a cross-check, not a repeat: the artifact's Open: line says what this phase left open, this count says what is unresolved across every phase so far. When they disagree, the human is looking at questions an earlier phase raised and nobody closed.
agents/bug-triage-agent.md, agents/orchestrator-agent.md — a bug report can now be triaged without leaving the run. The orchestrator's Bug-Input Check stops being a text advisory and becomes a two-option offer at Step 0e; on accept it dispatches bug-triage-agent with the new mode: orchestrated, where the agent reproduces, finds the root cause, writes 00c-bug-triage.md, and returns without a gate of its own — the orchestrator then presents that artifact at its own HITL gate and carries recommended_entry into the Effort Check. Until now the advisory named an agent the orchestrator was forbidden to call, so the only way to act on it was to abandon the session, run the agent, and start over.

Changed

agents/pm-agent.md — step 2 is rewritten from a flat list of eight technical questions into derive first, ask second, record third. Answers already visible in the repo or 00-context.md are derived rather than asked, questions are capped at 3 and ranked by what would change the requirements document, each one states the consequence of its answer, and "I don't know" produces a labelled assumption plus an open-questions.md row instead of a stalled phase. Performance and scale targets are no longer routine fields — a number nobody has measured becomes binding the moment it is written down.
agents/orchestrator-agent.md — every Risk Disposition row now carries exactly one (Recommended) option, derived mechanically from the row itself (no concrete fix → Escalate, high/critical → Mitigate now, medium → Accept), and every option states its consequence in plain language. Escalate and Defer are explicitly distinguished: Escalate means someone else still has to decide, Defer means the decision is made and the answer is "we ship with it".
agents/orchestrator-agent.md — the Loop Policy prompt no longer runs for simple_fix or medium. Both preset phase4 to auto 1, announced at Step 0f where it can still be changed. Choosing a retry budget before anyone has seen a finding is a decision with no information behind it; only significant_rework still gets asked.
agents/pm-agent.md, agents/architect-agent.md, agents/implementer-tdd-agent.md, agents/test-verifier-agent.md, agents/qa-plan-agent.md, agents/security-reviewer-agent.md, agents/release-planner-agent.md — all now read effort in the same three-step priority order already used by implementer-coder-agent and code-reviewer-agent: the orchestrator's stated value first, 00b-impact.md second, own inference last, explicitly labelled a last resort.
docs/workflow.md — Phase 0 documents the Effort Check and its propagation rule; the Lean Mode tip becomes a three-mode block covering Lean, Trimmed, and Full.
docs/agentic-loop.md — "Both default to manual" is no longer true: the page now documents the per-effort presets and states that only significant_rework still sees the loop-policy prompt.
agents/team/implementer-lead-agent.md — the Team Mode Lead writes the same 03-implementation.md and is reachable by both Loop Actuators, so it gets the same cumulative rule: a ## Pass Log and a ## Files Generated union with a Pass column.
agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md — 03-implementation.md is now cumulative per feature, not per pass. A new ## Pass Log records every invocation against the same implementation (planned wave, Loop Actuator iteration, manual re-run after Request changes) and ## Files Written gains a Pass column and becomes the union across all of them.
agents/code-reviewer-agent.md, agents/release-planner-agent.md, agents/orchestrator-agent.md — all three readers of that table now name the cumulative union explicitly, instead of reading whatever the last pass happened to leave behind.
agents/*.md (all 16 artifact-writing agents) and agents/team/implementer-lead-agent.md — every rendered ## Summary template gains the **Open:** line, 20 blocks in total. impact-assessment-agent keeps pointing at its own ## Open Questions table, since it runs before the ledger exists.
skills/artifact-template/SKILL.md, agents/orchestrator-agent.md — the block's line cap moves from six to seven and the gate print cap from ~5 to ~7 lines, so the contract and the printer do not contradict each other.
docs/workflow.md — describes the five-line Summary block and the orchestrator's two count lines.
.opencode/agents/, .kimi-code/agents/ — both mirrors updated for every touched agent; bodies verified byte-for-byte identical to their agents/ sources.

Fixed

agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md — a multi-wave implementation lost every earlier wave's record. orchestrator-agent.md documented the defect rather than fixing it: "per-wave artifact bookkeeping is not automated — wave 2 overwrites 03-implementation.md unless the human is told, so tell them." Three readers consumed that file as the complete list of what the feature shipped, so a 3-wave feature was reviewed, scope-checked, and recapped against the last wave alone.
agents/orchestrator-agent.md — the same loss on the second axis: the Loop Actuator archived each iteration as 03-implementation-iter{N}.md and nothing ever folded those fixes back into the base file, so after any auto-retry loop the canonical artifact described the pre-loop code. The archives are now explicitly copies, and the base file stays cumulative.
agents/orchestrator-agent.md — Step 0b's resume flow never read status: partial. A multi-wave run resumed in a later session found 03-implementation.md on disk, concluded Phase 3 was complete, and advanced to code-reviewer — the remaining waves were never implemented at all.
agents/orchestrator-agent.md — Step 0a loaded 00-context.md and 00b-impact.md but never 00c-bug-triage.md. Only the Quick fix branch ever read a triage, so a triage that concluded full-pipeline — the case where the evidence matters most — reached no phase agent at all, and pm-agent, architect-agent, and the implementer each re-derived a root cause a human had already approved. The triage is now loaded at Step 0a and attached to every subagent prompt.
CLAUDE.md, AGENTS.md — both described Vercel as the primary host, auto-deploying on every push to main. Nothing in the repository does that: the only deploy automation is .github/workflows/deploy-docs.yml, which fires a Netlify hook on v* tags, and vercel.json is referenced by no workflow and no secret. Contributors reading either file were told the site redeploys on a push that in fact deploys nothing.
.claude-plugin/plugin.json, AGENTS.md, internal/DEPLOYMENT.md — the plugin's homepage and both docs pointed at kairos-docs.vercel.app, which is not where the site lives. All three now point at https://kairos-agents.netlify.app, and the deployment guide states up front that this repo redeploys only on a v* tag rather than on a push.
internal/DEPLOYMENT.md — the guide's Repository Structure block still described a 7-agent repo with filenames that no longer exist (orchestrator.md, implementer-agent.md, a flat docs/setup.md). It now matches the real tree: 17 core agents plus agents/team/, both tool mirrors, skills/, commands/, and the per-tool docs/setup/ directory. The build settings it quotes also said Node 20 where netlify.toml pins 22.
AGENTS.md, .claude/CLAUDE.md, commands/setup.md, commands/view.md, docs/agents.md, docs/index.md, docs/setup/claude-code.md, docs/setup/kimi-code.md, docs/setup/opencode.md — the agent count said 16 in some places and 17 in others, against the 17 files actually shipped in agents/ since v8.0.0 took the count from 14 to 17. /kairos:setup copies files by that number, so the low count was not only cosmetic. All of them now say 17, and the home page's feature card, which listed the agents by name, had been missing QA Plan Agent since 8.0.0.
docs/overview.md — three stale claims: the artifact header was still described as carrying next agent, a field 8.0.0 removed; the standalone agents were introduced as "two more" when there are four (Bug Triage and Dependency Audit arrived in 8.0.0, and the Orchestrator can now offer Bug Triage itself); and the skills/ tree listed 6 of the 11 shipped skills.
docs/faq.md — rewritten. It still asked whether you need to learn "all 7 agents" and recommended "Claude Teams", and said nothing about how a run is actually started, the effort bands, where artifacts land, the bug-report entry point, or the deliberate deployment boundary.
docs/setup/templates.md — the Bug Fix preset handed you a checklist with no mention of triage, two versions after bug-triage-agent shipped. It now says to reproduce and find the root cause first, since that is what decides whether this preset or the full one fits.

Removed

vercel.json — deleted. Nothing referenced it: no workflow, no secret, no deploy hook. It survived a host migration and made every reader believe a push to main redeployed the site. The Vercel walkthrough in internal/DEPLOYMENT.md now hands you the file's contents to create yourself, for deploying your own copy.
docs/metrics.md — the published quality figures are gone: "80-90% correct on first pass", "~70% fewer bugs", and the page's claim that these came "from teams using KAIROS in production". Nothing in the project measured them. The page is now Quality: what the framework actually enforces, each line naming the agent or skill that enforces it, what it explicitly does not promise, and how to measure the rest in your own repository.
docs/index.md — the home page promised "40-50% faster development, 80-90% quality output" and "from 8 hours per feature down to 2-3 hours". All three are unmeasured. The hero and the feature cards now state the actual proposition: a gate after every phase, a written trail on disk, and quality of what ships rather than speed of getting there.
docs/overview.md — the opening paragraph promised "production-ready output at every step" and the What You Get list led with "production-ready code". Both now describe what the pipeline actually guarantees: a written artifact at every phase and a gate before anything lands.

v8.0.0 — September 14, 2026

Closes the SDLC coverage gaps that are reachable from a terminal session: design-time threat modelling, bug intake, dependency and tech-debt auditing, migration safety, and a reusable mechanism for quality obligations that apply to some projects and not others. Deployment execution and operations stay deliberately out of scope, now documented as such.

BREAKING CHANGE: the core agent count goes from 14 to 17, and /kairos:setup materializes and rewrites @kairos: calls for all of them — a project set up under 7.x has 14 agent copies in .claude/agents/ and will not pick up the three new ones until /kairos:setup is re-run. The ledger's constraints.md also gains a Category column; existing .kairos/ folders keep working (a legacy 6-column table reads as "no obligation declared") and are migrated in place the first time an agent appends a row.

Added

agents/bug-triage-agent.md — new standalone agent, the entry point for a bug report rather than a feature request. Reproduces the defect, isolates it, states the root cause with an evidence trail, rates severity on observed impact, and recommends where the fix re-enters the pipeline in 00c-bug-triage.md. Its recommended_entry feeds the orchestrator's Quick fix path. Never edits a source file.
agents/dependency-audit-agent.md — new standalone periodic agent. Audits the whole project's dependencies and accumulated debt — known CVEs with a reachability judgment, version currency, license conflicts, unused and duplicated packages, debt hotspots — into a prioritized backlog at the project-root .kairos/_tech-debt.md. Never applies an upgrade.
skills/constraint-taxonomy/SKILL.md — new shared skill defining the closed Category vocabulary of ledger/constraints.md plus the reader, writer, and gating rules that let a review section run only when its obligation was declared upstream. An obligation is never inferred from the code.
skills/threat-model/SKILL.md — new shared skill for design-time threat modelling, invoked by architect-agent's new Step 5b: trust boundaries, attack surface, authority, what the attacker controls, blast radius. Findings land in that phase's existing Risks table, so they flow through the Risk Disposition Loop unchanged.
skills/migration-safety/SKILL.md — new shared skill for schema and data migrations, invoked by architect-agent when the data model changes and by release-planner-agent when it writes the rollback strategy: expand/contract sequencing, lock duration at production row counts, restartable backfill, reversibility, and what a code rollback does to data already written in the new shape.
agents/code-reviewer-agent.md — new conditional Accessibility check (check 6). Runs only when an ACCESSIBILITY constraint was declared in the ledger, and reports N/A otherwise, so a project with no accessibility obligation never sees a section it would waive every time.
agents/security-reviewer-agent.md — new conditional Compliance & Privacy check (check 8), gated the same way on a declared PRIVACY or COMPLIANCE constraint. Findings become normal Findings rows, inheriting severity and Disposition.
agents/pm-agent.md — new outcome criterion, written alongside the acceptance criteria but deliberately separate from them: one statement checkable some time after release, with metric, direction, magnitude, and when someone looks. Acceptance criteria are all true the moment the tests pass and cannot say whether the feature was worth building. Carries no AC-n ID and no test maps to it — it exists for the human at the gate. Step 1 also gains a one-line problem check that asks what goes wrong today when the request arrives as a solution with no stated problem, and records an open question rather than inventing one.
agents/qa-plan-agent.md — new optional Phase 5b agent, the manual counterpart to test-verifier-agent. It plans the verification an automated suite structurally cannot give: manual and exploratory test cases, regression retest selection, test data and environment needs, and UAT sign-off per acceptance criterion. Every row must trace to an AC-n, an uncovered range reported by test-verifier-agent, or a caller found at a real file:line — a regression risk with no caller in the codebase is dropped rather than written. Runs only after the Phase 3 loop has exited, so the plan describes settled code; its NEEDS_ATTENTION never re-invokes an implementer. Selected in the orchestrator's post-implementation question, alongside release-planner-agent and documentation-agent.
skills/issue-tracker-comment/SKILL.md — new "No tracker CLI available" section covering every agent that posts to an issue. jira and glab are frequently absent on a corporate machine; the post is now guarded by a command -v check and degrades to a paste-ready comment body instead of failing a phase gate. qa-plan-agent is the first agent for which this step is recommended rather than optional — its reader is a human tester who works in the tracker, not in .kairos/.
agents/impact-assessment-agent.md — new Work Breakdown section: ordered tasks with explicit dependencies and a per-task estimate, so the aggregate effort rests on something inspectable. A breakdown spread across domains is the signal to recommend Team Mode. Produces a work list, never tickets.

Changed

agents/pm-agent.md — acceptance criteria now carry explicit, stable AC-n IDs assigned at the source and never renumbered. Previously test-verifier-agent numbered them positionally downstream, so inserting or removing a criterion silently changed what AC-3 referred to, invalidating every reference already written in other phases. Constraint elicitation now uses the closed category vocabulary and splits SECURITY, PRIVACY, and COMPLIANCE, with an accessibility question asked only where it can plausibly apply.
agents/context-extractor-agent.md — the codebase scan now reports accessibility-investment signals (a11y linter, test tooling, CI job, consistent aria- usage) so pm-agent can default its accessibility question instead of asking cold. Reports evidence, never a constraint row.
agents/release-planner-agent.md — the rollback strategy now reads the architecture artifact's migration-safety resolutions rather than restating them generically, and must state explicitly when a migration is not reversible without data loss.
agents/orchestrator-agent.md — new Bug-Input Check at Step 0e: when the input reads as a bug report and no triage artifact exists, the orchestrator points at bug-triage-agent before the Quick-fix-or-full-feature choice, so that choice is made from evidence rather than from the report's own wording. Advisory only — printed above the menu, never an option, never pre-selected, never blocking, in the same shape as the existing 00b-impact.md advisory. Hard Constraint 4 covers seven standalone agents instead of four; the Quick fix path reads 00c-bug-triage.md when present and hands its root cause to the implementer instead of re-deriving it; the .kairos/ tree and the project-root write rule now cover _tech-debt.md as a third exception with a third owner.
agents/orchestrator-agent.md — Phase 5b wired in: agent roster, resume phase order, both selection paths (checkbox question and typed fallback), the announce block, phase execution, artifact tree, and the HITL blocking-status list, which now recognises NEEDS_ATTENTION. The new phase runs only after the Phase 3 Loop Actuator and its Guard have resolved, so the QA plan is written against settled code.
agents/impact-assessment-agent.md — recommended_agents can now recommend qa-plan-agent, with the mirror-image rule to test-verifier-agent's: it earns its place where automated verification is thin or absent (the coder path, or behavior a person must judge by eye), and is not recommended for a simple_fix already covered by tests.
skills/artifact-bookkeeping/SKILL.md, skills/artifact-template/SKILL.md — status derivation and required frontmatter fields for the new phase. qa-plan-agent's status is purely count-derived from its ## Risks table; an acceptance criterion that cannot be verified as written becomes a high row there rather than a separate status condition, so one mechanism resolves both.
ledger/constraints.md schema — gains a Category column between Constraint and Source, written once at row creation and never rewritten. Every agent that creates or updates a constraint row now supplies or preserves it.
docs/ — agents.md, agent-files.md, overview.md, workflow.md, agentic-loop.md, skills-mcp.md, every setup guide, and the VitePress sidebar cover the four new agents and three new skills. New "Deliberately Out of Scope" section in CLAUDE.md records why deployment execution, post-deploy verification, observability, incident response, load testing, and cost analysis are not part of the framework.
Phase artifact frontmatter — a field now earns its place only if the orchestrator branches on it. Removed open_dispositions from every phase (it equalled the row count at write time and was zeroed by the Risk Disposition Loop, so it never carried information the Disposition cells didn't already hold), along with next_agent, checks, error_codes_count, database_changes_summary, selected_option, contract_enforcement_summary, monitoring_summary, rollback_summary, docs_touched, coverage_basis, manual_cases, and uat_summary — each of which existed only to be presence-checked by the contract check that required it. convergence_signal keeps only the terms the loop cannot derive from issues_summary. Artifacts written before this change stay readable; nothing read the removed fields.
agents/code-reviewer-agent.md, agents/test-verifier-agent.md — the per-check pass/fail results now live in one place, a ## Checks table in the body, instead of a frontmatter map the body restated (code-reviewer) or a frontmatter map with no body counterpart at all (test-verifier, which now gains the table).
agents/pm-agent.md — the body ## Constraints table is now a one-line pointer to ledger/constraints.md. Every downstream agent already read the ledger and none read the body table, so the two copies only gave a reader the job of working out which one was current.
Ledger accounting — the full re-walk of every constraints.md row is now mandatory at architect-agent (first accounting pass) and release-planner-agent (final accounting) only. Every phase in between updates the rows its own work touched and leaves the rest alone, which is what Lean Mode already did. Rows still reach a terminal state before release, so release-planner-agent's blocked rule is unaffected.
agents/pm-agent.md, agents/architect-agent.md — new Trimmed Mode at effort: medium, between Lean Mode (simple_fix) and the full process. Use Cases collapse to one line each with no Main Flow, and the architect proposes two design options instead of three. Constraints, acceptance criteria, ## Outcome Criterion, the data model, API contracts, and error codes stay in full at every effort level — they are contract, and a downstream agent reads each one.
agents/architect-agent.md — ## Performance Targets now runs only when a PERFORMANCE or SCALE constraint row was declared, the same gating already used for the accessibility and compliance checks. An undeclared target is no longer invented for the implementer to build against and the reviewer to check.
agents/orchestrator-agent.md — the HITL gate prints the artifact's ## Summary block, the dispositioned-row count, and the artifact path, then opens the full file only if asked. Each agent's own "Open in Editor" step is skipped when the orchestrator invoked it, and still runs standalone.

Fixed

skills/artifact-bookkeeping/SKILL.md — §4 required risk_counts and open_dispositions on the phase: implementer execution artifact, which neither implementer has ever written — the orchestrator's Artifact Contract Check would have read every implementer run as malformed and re-run the phase. Both fields are gone from that row; the Phase 3a plan artifact, which does carry risk_counts, still requires it.
skills/analysis-discipline/SKILL.md — was shipped but registered nowhere. Now listed in docs/skills-mcp.md, the VitePress sidebar, CLAUDE.md, docs/agent-files.md, and AGENTS.md.
CLAUDE.md — line 13 claimed .opencode/agents/ mirrors agents/team/ as well, contradicting the OpenCode Mirror section and the actual filesystem. Team Mode is excluded from both mirrors.
docs/setup/claude-code.md — the repository tree listed 11 of the core agents, silently omitting Documentation, Retrospective, and Improvement Advisor.
docs/setup/templates.md — documentation-agent was missing from all six issue-template checkbox blocks and from the phase table, though the orchestrator offers it at agent selection.

v7.9.0 — September 11, 2026

Added

skills/artifact-template/SKILL.md — New shared reference fixing the body shape of every phase artifact. It defines the mandatory four-line ## Summary head block (What / Decision / Needs your attention / Next) that each artifact now opens with, and the exact column sets of every table the Risk Disposition Loop parses. A gate is now readable in seconds without scrolling the whole file; the detail stays underneath, unchanged, for the next agent that needs it.
every agent that writes a .kairos/ artifact — Each output template now opens with the ## Summary block described above, filled by the agent that did the work. Needs your attention names row IDs (R1, R3 — see Risks) rather than restating descriptions, so it cannot drift once the Disposition Loop edits those rows.

Changed

agents/orchestrator-agent.md — HITL step 3 now prints the artifact's own ## Summary block verbatim instead of synthesizing its own verdict summary, plus one appended line with the number of rows dispositioned in step 2. Artifacts without a Summary heading fall back to the previous behavior; a missing Summary is a presentation fallback, never a malformed artifact.
agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md, agents/team/implementer-lead-agent.md — Both templates each agent emits (the Phase 3a plan and the Phase 3b implementation report) carry the Summary block.
docs/workflow.md, docs/skills-mcp.md — Document the Summary block and the new skill.
agents/orchestrator-agent.md — Agent selection is now a checkbox prompt instead of a typed list of numbers. Where AskUserQuestion is available (Claude Code), Step 0e asks four grouped questions — Analysis (multi-select), Implementer (single-select, TDD marked recommended), Review (multi-select), Release (multi-select) — and assembles active_agents from the answers. The numbered menu and the 1 3 4 5 / agent-name / template-block input formats stay as the fallback for IDEs without the tool.
agents/orchestrator-agent.md — Loop Policy no longer asks you to type "phase3: auto 3 / phase4: manual". It prints the cost estimate, then asks one question per loop with four fixed buttons: Manual (recommended), Auto 1, Auto 2, Auto 3. Under Team Mode the Auto 3 option is not offered at all, since the retry ceiling there is 2.
agents/orchestrator-agent.md — The Team Mode cost confirmation and the Loop Actuator's prior-exhaustion prompt are now button choices too, each with an explicit recommended option (Switch to Single Agent, Skip auto-loop), instead of printed numbered menus.
docs/overview.md, docs/agentic-loop.md, docs/setup/claude-code.md — Updated to show the new checkbox prompts and to state that typed numbers remain the fallback outside Claude Code.
.opencode/agents/*.md, .kimi-code/agents/*.md — All 14 mirrors on both sides resynced with the canonical bodies.

Fixed

agents/pm-agent.md, agents/documentation-agent.md — Their Disposition tables spelled the remediation column Mitigation and Fix respectively, while every other phase and the Orchestrator's own Constraint & Decision Conflict Scan use Mitigation/Fix. A conflict row appended by that scan therefore landed in a table whose header did not match it. Both now use Mitigation/Fix.

v7.8.2 — September 10, 2026

Added

skills/coding-discipline/SKILL.md — Scope Discipline (principle 1) now calls out bug-type work explicitly: default to the most surgical fix that leaves working code alone, and if the minimal fix isn't enough, surface the wider scope as a Phase 0 Risk (or ask directly when standalone) instead of expanding it unilaterally. Applies to every agent that references the shared skill — both implementers, implementer-lead-agent, and all four teammate agents.

v7.8.1 — September 9, 2026

Added

agents/pm-agent.md (and its .opencode/agents/ and .kimi-code/agents/ mirrors) — new step 4b, Use Cases: 2-5 short functional flows (Actor/Goal/Main Flow) captured from the client-facing requirement, before any technical design happens. Success Criteria (step 6) now tag each acceptance criterion with the UC it belongs to (AC-N (UC-N)), giving the pipeline a functional anchor that survives into architecture and implementation instead of getting lost once technical contracts take over. Skipped in Lean Mode (simple_fix).
agents/architect-agent.md (and mirrors) — "Recommend Best Option" now names which UC(s) the selected design serves, referencing PM's Use Cases rather than re-deriving them, so the technical design stays traceable to the functional goal it's meant to satisfy.
agents/implementer-tdd-agent.md (and mirrors) — the Wave Splitting table gains a UC column: each wave of a multi-wave (>6 files) implementation restates which use case it serves, re-anchoring the work on the functional objective at the exact point — complex, multi-wave builds — where technical decisions accumulate fastest and drift is easiest to miss.

Fixed

netlify.toml — removed a hardcoded ignore = "exit 0" build-ignore command that skipped every deploy regardless of actual content changes on the branch. Netlify was returning "Canceled build due to no content change" on every push.

v7.7.0 — September 9, 2026

Added

agents/retrospective-agent.md (and its .opencode/agents/ and .kimi-code/agents/ mirrors) — new conditional Step 3b, Durable Lessons Copy: when the target project gitignores .kairos/ (the orchestrator's Step 0c recommends it), the accumulated _lessons.md would never reach the project's own git history. After the retrospective is approved, the agent now offers to also append the same condensed Feature Log entry to a durable in-project file, discovered from the project's own docs (README.md/CLAUDE.md/docs folder) or chosen by the user. .kairos/_lessons.md stays the canonical store that the orchestrator and improvement-advisor-agent read; the durable copy is append-only and mirrors the Step 10d escape hatch already available for _recap.md. When .kairos/ is tracked, the step stays silent.
docs/agents.md — the Retrospective Agent section now documents the Durable Lessons Copy step.

v7.8.0 — September 9, 2026

Added

skills/analysis-discipline/SKILL.md — new principle 5, Premise Falsification Outranks Scope: evidence contradicting the input issue's stated reachability or severity must be reported as a premise refutation (Premise refutation: prefix in the finding's Description), never filed as a scope question or folded into a lesser category. Applies to all seven analysis/review agents that reference the skill.
agents/architect-agent.md (and its .opencode/agents/ and .kimi-code/agents/ mirrors) — new step 2b, Premise Check: for bug-type inputs that state a reachability or severity claim, the claim is verified against the actual code before designing — including in Lean Mode / simple_fix, where pm-agent may be absent. A refuted claim becomes a Premise refutation: risk row (Impact: high, never omitted even in a Lean Mode design with no other risks) plus a premise-tagged ledger row; the standalone gate recommends Stop when one is present. The architect never silently rescopes the issue itself.
agents/orchestrator-agent.md (and mirrors) — the Risk Disposition Loop gains a fifth disposition for premise rows: Refute premise (Recommended) / Accept / Escalate. Premise rows are never auto-disposed (exempt from the low/medium auto-accept and quick_fix_mode widening) and are deliberately not offered Defer — deferring a premise refutation is the failure mode this closes; a human can still defer via free text. A Refute premise disposition writes BLOCKING ledger rows and flips the whole-artifact gate's recommendation to Stop pipeline with guidance to rescope or close the issue. Nothing auto-aborts.
.kairos/decisions/ADR-001-premise-refutation-disposition.md — ADR recording this decision (Status: Accepted), including why the alternatives (a fourteenth agent, a skill-only rule, an orchestrator-side input scan, reusing Escalate) were rejected. Filed directly by the human because improvement-advisor-agent's Bootstrap Check requires 3+ Feature Log entries and the log has 1.
docs/agents.md — the Architect Agent section now documents the Premise Check and the Refute-premise disposition.

v7.6.0 — September 8, 2026

Added

skills/analysis-discipline/SKILL.md — new shared skill for the pipeline's analysis/review agents: a finding must trace to evidence read or run in the same invocation, cosmetic nits are skipped instead of generated-then-auto-accepted, investigation stays scoped to what the task names or implies, and disagreement with the requested approach is stated once, briefly, with an alternative, then dropped once the human decides.
agents/context-extractor-agent.md, agents/impact-assessment-agent.md, agents/pm-agent.md, agents/architect-agent.md, agents/code-reviewer-agent.md, agents/security-reviewer-agent.md, agents/test-verifier-agent.md (and their .opencode/agents/ and .kimi-code/agents/ mirrors) — each now points to analysis-discipline in its Role section, so requirement, architecture, and review output stays grounded in evidence instead of padding every pass with unrequested nitpicks or broader-than-asked codebase sweeps.

v7.5.1 — September 4, 2026

Added

agents/orchestrator-agent.md, CLAUDE.md — Step 0c gains a one-time-per-project Gitignore check: if .kairos/ isn't already covered by the target project's .gitignore, ask once whether to add it (its artifacts — security-review findings, ledger notes — aren't meant to sit in the project's own git history indefinitely, even redacted). A .kairos/.gitignore-prompted marker keeps this from asking on every subsequent feature run. Documented as the orchestrator's one narrow exception to never writing outside .kairos/.
agents/orchestrator-agent.md, agents/documentation-agent.md — Feature Recap gains a new Step 10d, Project Summary: since .kairos/ may now be gitignored, _recap.md might never reach the project's own git history. On request, the orchestrator composes a further-redacted digest (security findings collapsed to category + non-exploitable takeaway, no attack-scenario detail) and hands it to documentation-agent's new Verbatim passthrough input mode, which writes that exact content to docs/kairos-summaries/$feature_folder.md after its own Approve/Request changes/Stop gate — a second explicit confirmation beyond the orchestrator's own.

Fixed

agents/code-reviewer-agent.md, agents/security-reviewer-agent.md, agents/orchestrator-agent.md — a hardcoded-secret finding had no instruction against quoting the matched value in the report itself, so a discovered API key/token could end up copied verbatim into 04-review.md or 04b-security-review.md — Markdown files the target project may commit like any other artifact, permanently, even after the secret is later rotated. Both agents now report type and file:line only, never the value; the orchestrator's on-demand row-explain branch got the same rule, since it can pull the same value into a ledger note.

v7.5.0 — September 4, 2026

Added

agents/orchestrator-agent.md — Phase 3 now runs as two invocations of the same implementer with a human gate in between: step 3a produces the implementation plan and writes no code, step 3b executes the approved plan. The plan gets the full gate treatment every other phase already had — Artifact Contract Check, Constraint & Decision Conflict Scan, row-by-row Risk Disposition Loop, editor open, 4-option menu.
agents/team/implementer-lead-agent.md — new Step 2c writes 03-implementation-plan.md (layer scoping, per-layer file ownership, the Test Contract's full test-case list, risks) after the contracts and stops. Team Mode splits at the same 3a/3b boundary as the solo implementers, so no Agent Team is ever spawned against an unapproved plan.

Fixed

agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md — the Phase 0 plan was saved to 03-implementation-plan.md only after approval. Under the orchestrator that approval never arrived (a spawned subagent has no channel to the human), so the file was never written and the plan stayed buried in the run's transcript under RED/GREEN output. The plan is now written unconditionally, before any gate, and opened in the editor — a reviewable artifact like every other phase output.
agents/orchestrator-agent.md — pending_approval and partial are now documented as non-advancing statuses. A plan artifact used to pass the gate with Approve recommended and advance straight to the code reviewer; a completed wave used to advance instead of continuing. Loop Actuator iterations are pinned to step 3b so a fix round can never re-enter the plan step.
agents/orchestrator-agent.md — the Resume-existing matcher now maps 03-implementation-plan.md to step 3b and ignores 03-contracts.md, which has matched the 0*.md glob with no phase slot since Team Mode started writing it.
agents/team/implementer-lead-agent.md — the mid-run Test Plan Gate pointed at the orchestrator for gate presentation, but no such gate existed there, so it silently vanished on every orchestrated run. It is now explicitly dropped under the orchestrator (covered earlier by the 3a plan gate, which carries the same test-case list) and kept for standalone runs.
skills/artifact-bookkeeping/SKILL.md — §4's required-field lookup is keyed on the artifact's phase: value instead of the invoking agent, with a new implementer-plan row. Without this, every plan artifact failed the presence check on execution-only fields like coverage_summary and triggered a pointless re-run.
agents/orchestrator-agent.md — the Feature Recap's Audit Trail section copied ledger/audit-log.md verbatim, so a long or heavily-iterated feature grew _recap.md unbounded (observed at 72KB). The recap now stays a condensed digest on every write, including a regen on a reopened folder — no full artifact bodies, diffs, or verbatim log copy; the audit trail collapses to counts plus only Escalate/Stop/deviation rows.
agents/orchestrator-agent.md — the Loop Actuator's cumulative_issues was appended every iteration and handed to the implementer as its full work backlog, so by iteration 3+ the fix mandate still listed issues the checker's own re-scan no longer flagged as present. This wasted iteration budget re-touching already-fixed code and diluted the real signal, driving both loop thrash and drift off the original ask. cumulative_issues is now replaced with the checker's fresh critical/high issues[] each iteration instead of appended.
skills/artifact-bookkeeping/SKILL.md, agents/test-verifier-agent.md, agents/orchestrator-agent.md — test-verifier-agent's READY/NEEDS_FIXES status ignored Acceptance Criteria gaps entirely, so the Implementer ↔ Test Verifier loop could converge (and the Phase 5 gate could recommend Approve) while a 01-requirements.md Success Criterion was still unmapped to any test. Status now also fails on a non-empty Acceptance Criteria gap list; the Loop Actuator's tracked count and work list fold these gaps in for the Phase 3 loop (Phase 4's code-reviewer loop has no AC concept and is unaffected).

Changed

agents/orchestrator-agent.md — the Quick-Fix path is exempt from the 3a/3b split: the implementer runs once (step: 3ab), still writing the plan file but without stopping for a second gate. A change the human already classified as small does not earn one.
docs/workflow.md, docs/agents.md, CLAUDE.md — Phase 3 documented as two invocations with the plan artifact named, for both the solo implementers and Team Mode.

v7.4.2 — August 28, 2026

Fixed

commands/view.md — allowed-tools frontmatter was missing Skill and AskUserQuestion, both required by the command's own steps (Step 1's folder/file picker, Step 3's mandatory artifact-design load); added both, matching the pattern already used by commands/setup.md. Also added an explicit warning that /kairos:view must run from the session's primary agent — a subagent invoked mid-conversation (e.g. @kairos:orchestrator-agent) is restricted to that agent's own tools: frontmatter, none of which grant Artifact or Skill.
docs/setup/claude-code.md — added a warning under "Viewing a phase artifact as HTML" cross-referencing the same primary-session requirement, so the failure mode is documented next to the command's usage instructions and not only inferable from the general subagent/AskUserQuestion caveat in Step 3.

v7.4.1 — August 28, 2026

Documentation accuracy pass: removed unmaintained/marketing content, promoted Skills into their own chapter, and fixed a batch of stale claims found while reviewing every setup guide (wrong install method, wrong model tiers, stale JSON-artifact references, duplicated file paths).

Added

docs/license.md — new dedicated License & Support page (previously buried inside the now-removed docs/roadmap.md), linked from the sidebar's Project section.
docs/.vitepress/config.js — new "Skills & MCP" top-level sidebar chapter, promoted out from under "Core Agents"; adds the agent-contract skill page, which was built by VitePress but had no navigation link anywhere. New "Commands (Claude Code only)" chapter links /kairos:setup and /kairos:view, both previously unreachable orphan pages.
docs/skills-mcp.md — new "How a Skill Actually Works" section explaining the actual mechanism (on-demand SKILL.md load via the Skill tool vs. a live MCP connection) and why KAIROS authors its own internal skills instead of duplicating checklists across agent files. Both skill tables gained a "what it does/enforces" column instead of just naming agents; added the missing agent-contract row to the internal-skills table.

Changed

docs/index.md, docs/faq.md, docs/metrics.md, docs/overview.md — removed the "70-180x ROI per Feature" / "$5-8 in API costs replaces $400+ in developer time" marketing framing, the ROI FAQ entry, and the "Typical time savings per feature" table; docs/metrics.md trimmed to quality-only stats (code quality, coverage, bug rate) — cost/time-saved/headcount framing dropped throughout. Team Mode's functional $0.068-vs-$0.242 cost warning is untouched — that's a real runtime disclosure gate, not marketing.
docs/workflow.md — replaced the illegible mermaid pipeline flowchart with a plain phase/agent/gate table; added a callout on the primary-agent requirement for AskUserQuestion gates to actually fire (previously only documented in the Claude Code setup guide, never cross-referenced here where every gate is promised); fixed 5 "Saved to:" lines that listed the same output file path twice; fixed stale JSON-artifact references (KAIROS phase outputs have been Markdown-with-frontmatter since the v5.x format split, never JSON).
docs/agentic-loop.md — rewritten for readability: plain-language problem statement plus a concrete worked example (a /login rate-limiting feature walking through an actual Phase 3 auto-retry and a Phase 4 manual gate).
docs/overview.md — fixed the "How Files Are Organized" tree, which still showed agents/shared/contract-checklist.md (a path that hasn't existed since the skills refactor) instead of the real skills/ and commands/ directories; fixed the closing "just copy agents/ and you're ready" line, which contradicted the Claude Code plugin-install fix below; clarified the Implementer pipeline row (TDD default vs. code-only variant, previously implied as the only option); fixed stale "JSON summary" wording in the subagent-isolation diagram.
docs/setup/index.md — the "Repository layout" diagram was labeled your-project/ but actually showed the KAIROS source repo's own layout (agents/ + .opencode/agents/ mirror + .kimi-code/agents/ mirror together — a combination that only exists inside this repo). Retitled to "Where the files come from," clarified it's the source layout, added the missing skills//commands/ directories, and split out a second diagram showing the actual .kairos/ runtime output that lands in any consumer project.
docs/setup/claude-code.md — Step 1 rewrote to present claude plugin marketplace add + claude plugin install as the recommended path (previously the guide only documented manual copy to .claude/agents/, with plugin install mentioned nowhere until a parenthetical deep in the "Customizing models" section); Step 3 and Troubleshooting updated to branch the --agent invocation and settings example by install method. Fixed the "Suggested Models" per-agent table, which contradicted the correct tier list stated earlier on the same page (implementer-tdd-agent and context-extractor-agent marked as the wrong tier, architect-agent marked as the wrong tier, 5 of 14 agents missing entirely).
docs/setup/cursor.md, docs/setup/vscode.md — same stale "Suggested Models" tier bug as above, fixed against the actual shipped agents/*.md frontmatter; filled in the incomplete agent-file trees (both were missing 3-5 of the 14 core agents).
docs/setup/codex.md — fixed "Repeat for all 7 agent files" (stale count from before the pre/post-pipeline agents were added — it's 14) and two stale claims that phase output is JSON (.kairos/0X-*.json, "the agent's JSON output") — both corrected to Markdown.
README.md — Quick Start now leads with plugin install (with the verified CLI commands) alongside manual copy, matching the Claude Code guide fix; --agent invocation example branches by install method.
AGENTS.md — removed the docs/distribution/ layout line (directory removed, see below).

Removed

docs/roadmap.md — public product roadmap page removed, along with both of its nav links; it wasn't being kept up to date.
docs/distribution-roadmap.md, docs/distribution/00-discovery.md, docs/distribution/01-plugin-mapping.md, docs/distribution/02-plugin-install.md — internal distribution-planning docs and their "Distribution" sidebar section removed; this was planning material for KAIROS's own rollout, not user-facing framework documentation.
vitepress-plugin-mermaid, mermaid — removed from package.json and the withMermaid config wrapper in docs/.vitepress/config.js; the only diagram using them (in docs/workflow.md) was replaced with a table, leaving the dependency unused.

v7.4.0 — August 27, 2026

New auto-generated feature recap at the end of every pipeline run, with an optional cleanup of the intermediate phase files it replaces.

Added

agents/orchestrator-agent.md (+ both mirrors) — new Step 10, "Feature Recap": once the last active phase's gate resolves (not on a mid-run Stop pipeline), the orchestrator reads every phase artifact plus the ledger's audit trail and any still-open question back off disk and writes .kairos/<feature_folder>/_recap.md — a single condensed summary, no frontmatter contract, no Disposition table. It opens the file for review, then offers a Keep/Delete cleanup choice for the phase files the recap replaces (never the ledger, _recap.md, or 07-retrospective.md itself), recommending Keep whenever retrospective-agent hasn't run yet for that feature or an open question remains.
CLAUDE.md — documents _recap.md in the Pipeline Overview: auto-invoked by the orchestrator (unlike retrospective-agent/improvement-advisor-agent), and why its underscore prefix keeps it out of the numbered-phase resume glob.

Changed

agents/orchestrator-agent.md (+ both mirrors) — Step 0b's resume flow now checks for _recap.md before falling back to "fresh start at Phase 1": a feature folder with no 0*.md files but a _recap.md present already completed a prior run and had its phase files cleaned up (Step 10c), so resuming it now re-shows the folder-exists menu (steering toward Create new folder or Stop) instead of silently re-running the whole pipeline over already-shipped work.

Fixed

commands/view.md — /kairos:view assumed every phase file has frontmatter with a status/promptable verdict field. Verified live against a synthetic _recap.md (which deliberately has neither): the header step now explicitly drops the verdict badge instead of inventing one when a file — _recap.md, _lessons.md — carries no frontmatter, and skips the stat-tile row rather than rendering an empty one.
docs/setup/claude-code.md — documents that _recap.md is reachable via /kairos:view _recap.md (named explicitly — it's excluded from the no-argument phase-file list) and renders without a status header or stat tiles.
agents/orchestrator-agent.md (+ both mirrors) — closes a real scope-creep gap found in a live v7.1.2 run: after a crash-and-resume, the orchestrator ran a full build, tsc --noEmit, and a tree-wide sweep itself at the post-implementer gate — work that belongs exclusively to code-reviewer-agent (Phase 4). Collapse Detection now has a second trigger alongside "about to write code/create files": about to run a build, typecheck, or tree-wide verification sweep during HITL step 0 (Artifact Contract Check) or step 1b (Constraint & Decision Conflict Scan). Both gate steps are a semantic read of the artifact and ledger already on disk, never new tooling execution — so the orchestrator now stops, flags it, and continues the gate using only what's already readable from disk instead of duplicating Phase 4's job or invoking code-reviewer-agent out of turn.
README.md, docs/setup/index.md, docs/setup/claude-code.md, docs/distribution/02-plugin-install.md — closes the actual root cause behind the same live incident's AskUserQuestion failures: docs/distribution/02-plugin-install.md's own "Starting a Pipeline Run" section (and README's Quick Start) instructed typing @kairos:orchestrator-agent inside an already-open chat, which Claude Code dispatches through the Agent tool as a subagent — subagents unconditionally lose AskUserQuestion, degrading every HITL gate to the text-menu fallback, and are orphaned if the parent session ends mid-pipeline. All four docs now instruct starting the session with the orchestrator as its primary agent instead (claude --agent kairos:orchestrator-agent / claude --agent orchestrator-agent for copy-installs), note --agent is startup-only (exit and relaunch to switch), and show the .claude/settings.local.json "agent" key as an optional per-project default. docs/setup/claude-code.md also gains two new Troubleshooting rows for gates degrading to a text menu and the orchestrator vanishing mid-pipeline, both pointing at the same fix.

v7.3.0 — August 27, 2026

New /kairos:view command for a synthetic HTML view of a single phase artifact, and a fix for the editor command KAIROS shells out to when opening phase outputs.

Added

commands/view.md — new /kairos:view slash command (Claude Code only): reads one .kairos/<feature_folder>/ phase artifact and publishes a synthesized, human-readable HTML page via the Artifact tool (stat tiles for the frontmatter tallies, real tables for Risks/Issues/Findings with Disposition badges), instead of requiring a raw Markdown read. Scoped to one file per invocation — never the whole feature folder. With no argument it resolves in two steps — which feature folder, then which phase file inside it — rather than listing every phase file across every feature .kairos/ has ever accumulated.
docs/setup/claude-code.md — new "Viewing a phase artifact as HTML" section documenting /kairos:view on the published site: usage example, what it lists when called with no argument, what the resulting page contains.
AGENTS.md, CLAUDE.md — document the commands/ directory and both slash commands (/kairos:setup, /kairos:view); CLAUDE.md previously didn't mention commands/ at all.
docs/roadmap.md — new "Commands" entry for both slash commands, and an Exploration-tier note recording a deferred idea (auto-updating tracker board/status after gates) that was explored twice and shelved for lack of a concrete tracker/workflow example.

Fixed

agents/*.md (+ both mirrors, 12 core agent files, 36 files total) — the "open output file" step no longer hardcodes code "path"; it now runs ${KAIROS_EDITOR:-code} "path", so anyone on VS Code Insiders, Cursor, or another editor can point it at the right binary via the KAIROS_EDITOR environment variable instead of always launching plain VS Code.
docs/setup/index.md — documents the new KAIROS_EDITOR environment variable.
skills/coding-discipline/SKILL.md — new principle 6, "Comments: WHY Only, Never Process Narration": generated code (and tests, from PHASE 1 onward) must never narrate the KAIROS pipeline itself — ledger IDs (C2/D7/Q3), phase names, "per requirement R4" — that traceability already lives in the ledger and phase artifacts. Found in a real implementation: heavy XML-doc comments on test blocks, mostly KAIROS process history instead of technical WHY.
agents/implementer-tdd-agent.md (+ both mirrors) — PHASE 5 (Refactor) now explicitly covers the tests written in PHASE 1, not just PHASE 3's implementation; tests were the one artifact never revisited by the simplification pass, which is why comment bloat concentrated there.

v7.2.0 — August 27, 2026

CASE B agent selection now always comes with a recommendation, even when the pre-pipeline impact assessment was never run.

Added

agents/orchestrator-agent.md (+ both mirrors) — in CASE B (manual agent selection), when no 00b-impact.md advisory is available the orchestrator now derives its own suggested selection from the feature request (and 00-context.md if loaded) and shows it as a 💡 Suggested selection (unconfirmed) line above the menu. Same advisory status as the impact advisory and the caller-proposed selection: it never narrows, pre-checks, or reorders the menu, and never substitutes for the user's explicit choice. When the request is too ambiguous to suggest with confidence, the orchestrator says so and recommends running impact-assessment-agent (Pre-B) first — its recommendation is grounded in the actual code.
docs/workflow.md, docs/overview.md — document the suggested-selection behavior alongside the impact advisory and the caller-supplied selection check.

v7.1.3 — August 27, 2026

Closes the caller-side control gaps found during a real v7.1.2 pipeline run (issue #104), where the calling session dictated the agent list, skipped impact-assessment-agent, and launched the orchestrator as a background task — all before the orchestrator's own rules could apply. Also clears a batch of stale documentation left over from the v2.0 era.

Added

agents/orchestrator-agent.md (+ both mirrors) — new Caller-supplied selection check at the top of Step 0e: if the invocation prompt already dictates active_agents or a phase/agent list, the orchestrator now treats it as an unconfirmed proposal (same status as the 00b-impact.md advisory), shows it, and still requires explicit human confirmation through the normal CASE A/B menu. Callers can no longer short-circuit agent selection.
README.md, docs/setup/index.md — new Invocation Contract section: invoke the orchestrator with the bare feature request only, never pre-select phases/agents in the prompt, never launch it backgrounded/detached (spawned subagents have no AskUserQuestion, so gates degrade to a text menu nobody reads), and invoke the standalone pre-/post-pipeline agents directly.

Changed

agents/orchestrator-agent.md (+ both mirrors) — Constraint 5 (never run headless) no longer asks the orchestrator to "detect you're running non-interactively", a signal a spawned subagent cannot reliably observe. Enforcement is now explicitly caller-side via the Invocation Contract; orchestrator-side, a gate with no reply falls back to Constraint 3's do-nothing-and-wait.

Fixed

README.md — dropped the stale "v2.0" title and "8 core agents" count (now 14), replaced the obsolete convert.ps1/convert.py website-generation instructions with the real npm run docs:build flow, rewrote the deployment section to match reality (Vercel auto-deploy on main, Netlify on v* tags), and fixed the teammates/ folder reference (now team/).
docs/.vitepress/config.js — og: meta tags no longer hardcode "v2.0" / "7-agent" (title now injects the live package.json version); removed five srcExclude entries pointing at files that no longer exist. The same pass found a real leak: internal/** and root CLAUDE.md were being built into the public site (including the fix backlog itself) despite internal/ being documented as unpublished — both are now in srcExclude.
docs/roadmap.md — rewritten to match the actual shipped state: 14-agent ecosystem including security-reviewer, documentation, retrospective, and improvement-advisor; dropped the v2.x version scheme disconnected from package.json; fixed the "one JSON file per phase" claim (artifacts are Markdown).
docs/overview.md — "all six agents" corrected (the selection menu lists 9 entries).
docs/distribution-roadmap.md — "~12 agents" corrected to 14 core + 5 team.
docs/setup/opencode.md — customization example now uses anthropic/claude-opus-5, matching the model ids actually shipped in .opencode/agents/.
.github/workflows/deploy-docs.yml — the Netlify deploy-hook call now uses curl -sf, so a failed hook fails the workflow run instead of reporting green.

Removed

docs/SUMMARY.md — deleted: a 2-line GitBook leftover pointing at a moved file.
internal/START-HERE-SIMPLE.txt — moved to internal/archive/: it described a v2.0 zip with 7 agents and filenames that no longer exist. (internal/ is git-ignored, so this is a local-only move.)

v7.1.2 — August 26, 2026

Follow-up to v7.1.1's delegation fix: while evaluating whether Team Mode's implementer-lead-agent needed the same Agent-tool fix (it didn't — Agent Teams already grants it regardless of tools: declaration), live probing against real kairos agents found that AskUserQuestion is unavailable to any spawned subagent — a general Claude Code fact, not specific to Agent Teams or to any particular IDE.

Fixed

agents/team/implementer-lead-agent.md (single file, not mirrored) — its Contract Mismatch Disposition Loop and Test Plan Gate both called AskUserQuestion unconditionally, one of them explicitly forbidding the text-menu fallback ("do not print a text menu"), on the stated assumption that AskUserQuestion is always available "in this Claude-Code-only agent." Confirmed empirically that this is false: AskUserQuestion is unavailable to any spawned subagent, in Claude Code or otherwise. Both gates now have the same conditional text-menu fallback every other kairos gate already uses, so a real Team Mode run no longer stalls or errors at either checkpoint.

v7.1.1 — August 26, 2026

Fixes a Claude-Code-specific gap that let a live pipeline run silently skip agent-selection and human-in-the-loop gates: the orchestrator itself had no way to invoke other agents.

Fixed

agents/orchestrator-agent.md (+ Kimi Code mirror) — tools: was missing the Agent tool (Claude Code's Task-style delegation tool), so a spawned orchestrator subagent could describe calling @kairos:implementer-tdd-agent etc. in text but had no way to actually do it — it would simply end its turn, leaving the parent session to improvise the next call itself, bypassing every HITL gate the orchestrator's own Workflow defines. OpenCode's mirror already sidesteps this via mode: primary and needed no change; docs/setup/opencode.md and docs/setup/kimi-code.md gained a note explaining the asymmetry so it isn't mistaken for missed mirror sync later.
agents/context-extractor-agent.md, agents/impact-assessment-agent.md (+ both mirrors) — both standalone pre-pipeline agents could drift into presenting their own invented "what next" menu (e.g. offering to launch a specific implementer directly) instead of stopping at their documented Approve/Request changes/Stop gate. Both now explicitly name @kairos:orchestrator-agent as the only next step after Approve, and state they have no authority to invoke or recommend any other specific agent — closing the gap that let a pipeline run skip straight to an implementer with no agent-selection gate ever shown.

Reduces roundtrips and per-phase overhead for small fixes, without touching the pipeline's behavior on real features. Four changes target four distinct sources of friction: the orchestrator's own gate machinery, test-verifier-agent being pulled in regardless of size, code-reviewer-agent running full-depth checks on trivial diffs, and per-agent prompt size inflated by boilerplate repeated across every phase file.

Added

agents/orchestrator-agent.md (+ both mirrors) — new Quick-Fix Check at Step 0e, asked once before the agent-selection menu (skipped only when the issue body already carries a ## KAIROS Pipeline template section). Choosing "Quick fix" presets active_agents to implementer-coder-agent + code-reviewer-agent, sets loop_policy to auto 1, and sets quick_fix_mode for the run — skipping the full 9-item selection menu and the separate loop-policy prompt entirely. Choosing "Full feature" proceeds exactly as before. Trades TDD discipline for speed by design; pick "Full feature" (or hand-pick implementer-tdd-agent from the menu) when tests should be generated.
agents/orchestrator-agent.md (+ both mirrors) — Risk Disposition Loop's auto-accept now also covers medium-impact rows when quick_fix_mode is active, on top of the existing low-only auto-accept. high/critical rows are never auto-disposed, in or out of quick-fix mode.
skills/issue-tracker-comment/SKILL.md (new) — consolidates the jira/glab/bitbucket comment-posting commands that 12 agents each repeated near-verbatim (~20-25 lines apiece, ~270 duplicate lines total), parameterized by {output_file}/{title} plus plain/title-prefixed body variants and no-Bash/read-only agent variants. Registered in docs/skills-mcp.md, docs/.vitepress/config.js sidebar (which also gained the pre-existing missing coding-discipline entry, caught in the same pass), and root CLAUDE.md.

Changed

agents/impact-assessment-agent.md (+ both mirrors) — test-verifier-agent is now only recommended when a TDD implementer is selected AND effort is medium or significant_rework. Previously it was recommended whenever TDD was selected regardless of effort, pulling a full extra phase + gate into every simple fix in a tested repo. code-reviewer-agent's own Testing check covers this signal at lighter weight for simple_fix.
agents/code-reviewer-agent.md (+ both mirrors) — Lean Mode now actually trims check content for simple_fix, not just the Ledger Update: Architecture Compliance and Performance collapse to a one-line N/A absent real signal (no new endpoint/schema/integration point, no loop/query/hot-path change), and the dependency-changelog/lockfile sub-check only runs when a dependency version actually changed in the diff. Correctness, Security, Simplicity, and Standards Compliance always run in full — these are what actually catch bugs on a small diff.
agents/test-verifier-agent.md (+ both mirrors) — PHASE 0 no longer blindly re-executes the test suite. implementer-tdd-agent already runs it twice (RED and GREEN) and reports coverage in 03-implementation.md; on the first test-verifier invocation for a feature with no prior 05-test-verification.md and a clean GREEN pass, Test Verifier reuses those results instead of shelling out again. Any loop re-check, Phase 4 Guard regression check, or standalone invocation still always re-executes — reuse is scoped to the one case where nothing could have touched the code since. PHASE 1's static audit (comprehensiveness, assertion strength, determinism, hygiene, mocking, TDD reality check) is unaffected and always runs in full — this only cuts the redundant command re-run, not the independent quality check.
docs/workflow.md — documents the Quick-Fix Check in the Phase 0 section (with a tip on its TDD tradeoff), the effort-gated test-verifier-agent recommendation, code-reviewer-agent's real Lean Mode behavior in the Phase 4 section, and Test Verifier's reuse-fresh-execution behavior in the Phase 5 section.
agents/architect-agent.md, agents/code-reviewer-agent.md, agents/context-extractor-agent.md, agents/documentation-agent.md, agents/impact-assessment-agent.md, agents/implementer-coder-agent.md, agents/implementer-tdd-agent.md, agents/pm-agent.md, agents/release-planner-agent.md, agents/retrospective-agent.md, agents/security-reviewer-agent.md, agents/test-verifier-agent.md (+ both mirrors, 12 agents) — each agent's own "Issue Tracker Comment" section shrinks from a full ~20-25 line jira/glab/bitbucket block to a one-line pointer at skills/issue-tracker-comment/SKILL.md, stating just its two parameters ({output_file}, {title}) and any variant (title-prefixed body, no-Bash hand-off, read-only). No behavior change — same commands, same conditions, now defined once instead of twelve times.

Fixed

.opencode/agents/impact-assessment-agent.md, .kimi-code/agents/impact-assessment-agent.md — both mirrors were missing the documentation-agent row from the Recommend Active Agents table (pre-existing drift from an earlier release, caught by this change's mirror-sync diff check, unrelated to the effort-gating change above).
agents/implementer-coder-agent.md (+ both mirrors) — its Effort Detection only read effort from 00b-impact.md in Pipeline mode, and only self-inferred effort in Standalone mode. Since the Quick-Fix Check (above) invokes it in Pipeline mode without ever producing 00b-impact.md (it skips Pre-B), effort fell through to unknown → Full Mode, silently defeating the point of choosing "Quick fix". Fixed by giving the orchestrator's own effort: simple_fix (now passed explicitly in the invocation prompt when quick_fix_mode is active) top priority, ahead of the file read and the self-inference fallback — which now also applies regardless of mode.
agents/code-reviewer-agent.md (+ both mirrors) — same explicit-effort-first priority added for consistency and certainty, though its existing self-inference fallback already worked regardless of mode (no functional bug here, just alignment with implementer-coder-agent's fix above).
.opencode/agents/release-planner-agent.md, .kimi-code/agents/release-planner-agent.md — both mirrors were missing a clarifying sentence about retrospective-agent being a separate, standalone, non-orchestrated follow-up not chained to by this agent (pre-existing drift, caught by this change's mirror-sync diff check, unrelated to the Issue Tracker Comment extraction above).

v7.0.0 — August 24, 2026

KAIROS no longer recommends or depends on any third-party Skill marketplace. karpathy-guidelines (plugin multica-ai/andrej-karpathy-skills) and all 11 approved Trail of Bits plugins (differential-review, insecure-defaults, supply-chain-risk-auditor, static-analysis, variant-analysis, sharp-edges, property-based-testing, mutation-testing, fp-check, ask-questions-if-underspecified, audit-context-building) are removed from every agent file, mirror, and doc that referenced them. Anthropic's own Claude Code built-ins (code-review, security-review, verify/run, deep-research, outcome-issue-generator) and MCP servers (Chrome DevTools MCP, Playwright MCP) are unaffected — this only removes third-party Skill dependencies. Every removed skill's guidance was rewritten as a native, unconditional instruction in the consuming agent — nothing is lost by not installing a plugin, and the new internal skill below ships automatically with the KAIROS plugin itself (same skills/ auto-discovery as the 3 existing internal skills), so it is never a separate install.

Added

skills/coding-discipline/SKILL.md — new internal, KAIROS-authored skill replacing karpathy-guidelines: scope discipline, no speculative abstraction, surfacing assumptions, verifiable success criteria, and trust-boundary validation. Referenced by agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md (+ .opencode/agents/ and .kimi-code/agents/ mirrors), and by agents/team/implementer-lead-agent.md and all four agents/team/teammate-*-agent.md files (no mirror — Team Mode is out of scope for both mirrors).

Changed

agents/security-reviewer-agent.md (+ mirrors) — the 3 conditional Trail of Bits trigger lines (insecure-defaults, supply-chain-risk-auditor, variant-analysis) are removed; the 7-check OWASP-style checklist that was already the stated inline fallback now runs unconditionally.
agents/code-reviewer-agent.md (+ mirrors) — removed the differential-review/static-analysis/fp-check/karpathy-guidelines trigger block. Check 1 (Correctness) gains a known-error-prone-pattern bullet (sharp-edges' intent); check 4 (Security) gains a first-pass grep-for-risky-patterns bullet (semgrep's intent); check 7 (Simplicity) now points at coding-discipline; a false-positive-verification instruction (fp-check's intent) is added near Output Format. static-analysis/codeql and sarif-parsing are dropped outright — no inline equivalent without the external CLI/tool itself.
agents/test-verifier-agent.md (+ mirrors) — removed the 4 Trail of Bits bullets from Optional Enhancements (none had a trigger line). Check 1 (Test Comprehensiveness) gains a property-based-testing-style bullet for pure functions with a defined input domain; check 3 (Assertion Strength) gains an explicit mutation-style reasoning step; a false-positive-verification instruction is added near Output Format; sarif-parsing is dropped outright.
agents/pm-agent.md (+ mirrors) — removed the ask-questions-if-underspecified trigger and bullet; step 2 ("Ask Clarifying Questions") already covers this unconditionally.
agents/context-extractor-agent.md (+ mirrors) — removed the audit-context-building trigger and bullet; step 1 (Codebase Scan) gains a call-graph/entry-point tracing bullet, matching architect-agent.md's existing inline-fallback pattern.
agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md (+ mirrors) — the conditional karpathy-guidelines trigger at PHASE 0 is now an unconditional pointer to coding-discipline.
agents/team/implementer-lead-agent.md — karpathy-guidelines trigger replaced with an unconditional coding-discipline pointer, preserving the "share the principles with all teammate agents in your coordination prompt" clause. The now-empty ## Optional Enhancements section is removed.
agents/team/teammate-backend-agent.md — karpathy-guidelines trigger replaced with coding-discipline; sharp-edges and insecure-defaults folded into two new rows in the existing Contract Compliance Checklist (no hardcoded secrets; no error-prone patterns).
agents/team/teammate-database-agent.md — karpathy-guidelines trigger replaced with coding-discipline; the **Skills** sub-header (now empty) is removed, keeping the existing database-MCP gap note.
agents/team/teammate-frontend-agent.md — karpathy-guidelines trigger replaced with coding-discipline.
agents/team/teammate-tests-agent.md — karpathy-guidelines trigger replaced with coding-discipline; property-based-testing folded into the RED Phase's Edge Cases step (generated/systematically-varied inputs for pure functions).
docs/skills-mcp.md — removed the karpathy-guidelines and Trail of Bits plugins subsections, their install-command blocks, and the "Trail of Bits plugins" column from the agent × enhancement map. Added an "Internal (KAIROS-authored) skills" subsection listing all 4 internal skills, including the new coding-discipline.
docs/agents.md — every per-agent Optional enhancements callout has its karpathy-guidelines/Trail-of-Bits names and Install: lines removed; coding-discipline (internal) replaces karpathy-guidelines where applicable.
docs/agent-files.md, docs/agent-files-team.md — added a pointer to the new skills/coding-discipline/SKILL.md, matching the existing contract-checklist/code-simplification/artifact-bookkeeping pointers.
README.md — removed the karpathy-guidelines and Trail of Bits security plugins bullets from "Recommended installs"; added a line stating KAIROS has no third-party skill dependency.

v6.9.1 — August 24, 2026

Fixed

agents/test-verifier-agent.md, agents/team/teammate-tests-agent.md, agents/team/teammate-frontend-agent.md — added mcp__chrome-devtools__*, mcp__playwright__* to tools: frontmatter. These agents' bodies have told them to use Chrome DevTools MCP / Playwright MCP since v3.3.0, but the tools were never actually granted in tools: — since that field is a strict allowlist for Claude Code subagents, the tools were unreachable regardless of whether the MCP was connected. Mirrored to .opencode/agents/test-verifier-agent.md (as permission: { "chrome-devtools_*": allow, "playwright_*": allow }) and .kimi-code/agents/test-verifier-agent.md.
docs/setup/opencode.md, docs/setup/kimi-code.md — documented the tools:/permission: mapping for MCP-server wildcard grants, so future MCP additions don't repeat this gap.
docs/skills-mcp.md — added a note explaining that granting an MCP to a subagent requires the tools: frontmatter entry, not just installing the server.

v6.9.0 — August 17, 2026

Re-audit of the v6.7.0 harness-audit follow-up list (4 remaining structural items) against current code. One item — ledger archiving/digest — was scoped, found to have no safe trigger point without contradicting an existing agent's own stated read-only contract for a thin payoff, and cut rather than shipped speculatively. The other three:

Added

agents/orchestrator-agent.md (+ mirrors) — HITL step 1b, previously Constraint-Conflict Scan, is now Constraint & Decision Conflict Scan: it also reads ledger/decisions.md and checks the current phase's output against every decision an earlier phase already recorded, not just constraints. decisions.md has no Status column, so the predicate there is simply "recorded before this phase ran," not "already resolved." Also fixes a drift between this step's own instructions and artifact-bookkeeping §1: the step previously told the orchestrator to hand-increment a single tally bucket by 1 when appending a conflict row — now it re-runs the full recount instead, per the skill's own "never hand-increment" rule.
skills/artifact-bookkeeping/SKILL.md — new §4, a per-phase table of required frontmatter fields (beyond the verdict field already checked), derived from each agent's own Output Format block. Wired into orchestrator-agent.md's Step 0 Artifact Contract Check (+ mirrors): a phase artifact missing one of its required fields is now treated as malformed — same one-time re-run behavior as an invalid verdict field — instead of only checking that the verdict field itself parses.
agents/team/implementer-lead-agent.md — Step 4 gains Cross-domain change requests, the receiver-side handling that was missing for the escalation message every teammate-*-agent.md already sends (message [lead]: "<path> needs a change outside my domain") when it needs to touch a file outside its own Owned Paths. The Lead never writes code itself (Rule 1), so it routes: relay to the in-scope teammate that actually owns the path, escalate to the human if the owning layer wasn't spawned this pass, or — for a genuinely shared file with no single owner (a shared type/interface, a barrel/index, root config, a package manifest) — assign exactly one teammate as sole owner for the rest of the pass and record the assignment in 03-contracts.md under a new ## File Ownership Overrides section, so it survives past a mid-pass broadcast and is visible to a later Iteration Mode re-spawn. New Important Rule 13 summarizes it. No mirrors — agents/team/ is out of scope for both mirrors.

Changed

docs/workflow.md — Shared Ledger section documents the Constraint & Decision Conflict Scan (previously undocumented even for the v6.7.0 constraints-only version).
docs/agent-files.md, CLAUDE.md — artifact-bookkeeping pointer sentences updated to mention its new §4 frontmatter-fields table and the Orchestrator's Artifact Contract Check as a consumer.

v6.8.0 — August 17, 2026

Added

agents/team/implementer-lead-agent.md — Team Mode's Lead agent now supports Iteration Mode, the last of the five structural items deferred from the v6.7.0 harness audit (deferred since v5.2.0). Detected automatically from ## Loop State in open-questions.md, mirroring the solo implementers' existing mechanism. On a fix iteration the Lead skips RED phase, the Test Plan HITL gate, and REFACTOR entirely, narrows layers_in_scope to only the layers touched by loop_state.cumulative_issues, and spawns only those teammates with a targeted fix prompt instead of the full GREEN implementation prompt — replacing the previous "re-spawn the whole team from scratch" behavior that made Team Mode ineligible for auto-retry. The four binding contracts are now persisted to a new .kairos/<feature_folder>/03-contracts.md at the end of Step 2b so a fix iteration reads them back verbatim instead of re-deriving them (re-deriving would silently skip the Step 2b drift-check gate a second time, risking contract drift between the initiating pass and the fix). Output gains an optional changes_this_iteration[] frontmatter field.
agents/orchestrator-agent.md (+ mirrors) — the Step 0e loop-policy gate no longer forces manual when implementer-lead-agent (Team Mode) is the active Phase-3 implementer; it now shows the same auto-retry prompt as the solo implementers, with a Team-Mode-specific cost callout (each iteration is a full opus Lead + narrowed team spawn, not a single sonnet call) and a lower max_retries ceiling of 2 (vs. 5 for solo implementers) to bound worst-case cost. Both Loop Actuators (Phase 3 and Phase 4) are now reachable with Team Mode active.

Changed

docs/agentic-loop.md — documents Team Mode's Iteration Mode support, its lower retry ceiling, and adds a Team Mode row to the cost-estimate table.

v6.7.0 — August 17, 2026

Added

skills/artifact-bookkeeping/SKILL.md — new shared reference consolidating the arithmetic every phase agent restated by hand: the risk_counts/issues_summary/findings_summary per-Impact tally, the open_dispositions empty-cell count, the per-phase status threshold rule, and test-verifier-agent's acceptance-criteria coverage count. Wired via a one-line pointer (same "follow X" pattern already used for contract-checklist/code-simplification) into pm-agent.md, architect-agent.md, impact-assessment-agent.md, implementer-tdd-agent.md, implementer-coder-agent.md, code-reviewer-agent.md, security-reviewer-agent.md, test-verifier-agent.md, release-planner-agent.md, and documentation-agent.md. Not mirrored to .opencode//.kimi-code/ — the mirror-sync rule scopes to agents/*.md, not skills/.
agents/orchestrator-agent.md (+ mirrors) — three additions surfaced by a harness-compliance audit: (1) an Artifact Contract Check, new HITL step 0, that verifies a subagent's output actually has a parseable frontmatter and a valid phase-appropriate verdict field before that verdict is read, instead of a missing/malformed field silently reading as "no blocking status found"; (2) explicit resume-point detection in Step 0b — when the user picks "Resume existing" on an already-populated feature folder, the orchestrator now lists which 0N-*.md phase files exist and states the resume point for confirmation, rather than inferring it silently; (3) a Ledger Audit-Log Append (new HITL step 5b) writing one line per gate — phase, verdict, human's choice, timestamp — to the new ledger/audit-log.md, the only durable record of which whole-artifact option (Approve/Skip next/Stop pipeline) was chosen at each gate. The timestamp prefers a date/time signal already visible in the environment over shelling out; date via Bash is only a fallback, so this doesn't force a bash: ask permission prompt on every gate on hosts like OpenCode.
agents/release-planner-agent.md (+ mirrors) — new planning step 5, Scope Coverage Check: cross-references 01-requirements.md's Scope against what 03-implementation.md actually shipped, producing a ## Scope Gaps table for any requested item with no traceable implementation. Closes the gap where a partial active_agents selection (e.g. implementer + code-reviewer only, no architect/pm) could reach a fully "green" pipeline while missing part of the original request. Wired into the status rule: an unresolved Scope Gap now blocks ready the same way a critical risk does.

Changed

docs/agent-files.md, docs/.vitepress/config.js, CLAUDE.md — registered artifact-bookkeeping alongside the existing contract-checklist/code-simplification pointers: a consumer-naming sentence on the agent-files index page, a sidebar nav entry, and an updated sentence in the root ### Skills (skills/) section.
agents/context-extractor-agent.md (+ mirrors) — tools: narrowed from Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion to Read, Write, Grep, Glob, AskUserQuestion. This agent's own contract is read-only scanning plus a single new output file; it never needed Edit, and its two remaining Bash uses — shelling out to code in "Open in Editor" and running jira/glab/curl in the optional "Issue Tracker Comment" step — are rewritten to print the path/command for the user or orchestrator to run instead of self-executing, so the narrowed grant doesn't strand either step.
agents/documentation-agent.md (+ mirrors) — tools: narrowed to drop Bash only; every action this agent takes is a file read or a Markdown/doc write, never a command. Same rewrite as above applied to its "Open in Editor" and "Issue Tracker Comment" steps, which previously shelled out via code/jira/glab/curl.
agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md (+ mirrors) — the standalone-mode feature_folder derivation rule now points to orchestrator-agent.md's Step 0b as the canonical definition instead of independently restating it, closing a 3-way duplication of the same slug/prefix rule.

v6.6.0 — August 4, 2026

Added

agents/code-reviewer-agent.md (+ .opencode/agents/, .kimi-code/agents/ mirrors) — added a 7th review dimension, "Correctness" (implementation logic matches spec, edge cases and error paths handled in the code itself, off-by-one/race-condition/state-consistency checks), inserted ahead of the existing six and wired into the checks: frontmatter block and the Checks table example. Closed a gap surfaced while comparing the pipeline's review flow against a general-purpose code-review skill: no existing check read the implementation's own logic for correctness — Testing checks test coverage, and test-verifier-agent (Phase 5) checks test quality, but neither substitutes for it. Architecture Compliance (check 3) gained three bullets on duplication, dependency direction, and refactors that relocate rather than reduce complexity, plus feature logic leaking into shared modules. Security (check 4) gained a dependency-upgrade bullet (changelog read, one package per bump, lockfile diff reviewed). Simplicity (check 7) gained a bullet on diffs that push a file past a healthy size without decomposing it. The Issues table in Output Format now states an explicit severity ordering (critical → high → medium → low), matching the rule security-reviewer-agent.md already had.
agents/orchestrator-agent.md (+ mirrors) — the Risk Disposition Loop (HITL step 2) now auto-dispositions every low-impact Issues/Findings/Risks row as Accept without prompting, before the per-row AskUserQuestion loop runs on the remaining medium/high/critical rows. Closes a friction gap: a review with a dozen style-level low findings previously forced a dozen individual human decisions at the gate, one per row, with no "this one doesn't matter" fast path.

Fixed

.opencode/agents/orchestrator-agent.md, .kimi-code/agents/orchestrator-agent.md — resynced bodies against agents/orchestrator-agent.md. Both mirrors were missing the entire v6.4.0 addition (documentation-agent/retrospective-agent/improvement-advisor-agent references, the project-root _lessons.md/decisions/ carve-out, Phase 6b wiring) despite that release's changelog claiming mirrors were updated — discovered via the pre-commit body diff this same change's mirror sync required.

v6.5.0 — August 4, 2026

Added

skills/code-simplification/SKILL.md — new shared reference for the REFACTOR step of implementation, adapted from Anthropic's official code-simplifier plugin into a stack-agnostic checklist: five simplification principles (preserve behavior exactly, follow project conventions, clarity over cleverness, maintain balance against over-simplification, scope to what changed), a pattern table for structural/naming/redundancy issues, and a verification checklist that branches on whether the project has a test suite. Wired into agents/implementer-tdd-agent.md (PHASE 5) and agents/implementer-coder-agent.md (PHASE 2), plus their .opencode/agents/ and .kimi-code/agents/ mirrors — same "work through X while doing this" pattern already used for contract-checklist in architect-agent.md.

Changed

docs/agent-files.md, docs/.vitepress/config.js, CLAUDE.md — registered the new skill alongside the existing contract-checklist pointer: a consumer-naming sentence on the agent-files index page, a sidebar nav entry, and a paragraph in the root ### Skills (skills/) section.

v6.4.0 — August 4, 2026

Added

agents/retrospective-agent.md (+ .opencode/agents/, .kimi-code/agents/ mirrors) — new standalone, post-pipeline agent closing the "remember" gap: the pipeline previously stopped at Release Planning with no mechanism to capture what was learned from a finished feature. Invoked directly by the user any time after work on a feature stops (not gated on Phase 6 running), it reads a feature's own artifacts and ledger — especially Loop History thrash/exhausted entries and Escalate/Defer dispositions — and distills 3–8 lessons, split Diataxis-style into Why This Happened (root cause) and What To Do Differently (actionable). Produces 07-retrospective.md and appends one dated entry to the new project-root .kairos/_lessons.md — the one write in the framework that targets a path outside the current feature folder.
agents/improvement-advisor-agent.md (+ mirrors) — new standalone, infrequent agent closing the "improve" gap: reads the accumulated .kairos/_lessons.md across all past features and, for any friction pattern confirmed in 3 or more of them, drafts a new .kairos/decisions/ADR-*.md (Status: Proposed) proposing a concrete framework change, and refreshes _lessons.md's curated Recurring Patterns table (hard-capped at 10 rows — the only section the Orchestrator injects into every subagent prompt going forward). Carries an explicit Hard Constraint: it never writes to agents/*.md, .opencode/, .kimi-code/, or docs/ — every proposal is Markdown a human applies by hand, the same "never self-implement" principle the Orchestrator already follows for source code.
agents/documentation-agent.md (+ mirrors) — new optional Phase 6b, runs after Release Planning (same "optional phase with its own HITL gate" shape as the existing Phase 4b Security Reviewer). Writes feature-facing documentation in the target project — README updates, API reference entries, a CHANGELOG entry, migration notes for breaking changes — detecting the project's existing doc conventions before writing rather than imposing KAIROS's own. The second agent in the framework, after the Phase 3 implementer, permitted to write real files outside .kairos/; scoped strictly to documentation, enforced via its own Hard Constraint section. Produces 06b-documentation.md, including a Documentation Gaps table (same 5-column shape as every other Risks/Findings table) for anything it can't confidently write without inventing details.

Changed

agents/orchestrator-agent.md (+ mirrors) — Hard Constraint 4 and the Available Subagents list now name all four standalone agents (previously only named context-extractor-agent); Step 0a additionally checks for .kairos/_lessons.md and, if present, injects only its Recurring Patterns section into every subagent prompt (never the unbounded Feature Log below it); Step 0e's agent-selection menu and the Phase Execution list gained a 6b. documentation-agent row/step, mirroring the existing 4b shape; the Output To User template gained a DOCUMENTATION block; the Pipeline Outputs tree now shows _lessons.md and decisions/ at the .kairos/ project root alongside 06b-documentation.md and 07-retrospective.md inside the feature folder, with an explicit carve-out sentence naming these as the framework's only project-root (cross-feature) persistence and which two agents may touch them.
agents/release-planner-agent.md (+ mirrors) and docs/workflow.md — the "this is the final phase, approval closes the KAIROS run" language now scopes that claim to the numbered pipeline (1–6, or 1–6b when Documentation Agent is selected) and explicitly names retrospective-agent as a separate, optional, non-orchestrated follow-up that isn't precluded by it.
agents/impact-assessment-agent.md (+ mirrors) — added a Recommended Agents criteria row: an API contract change or any user-facing behavior change now recommends documentation-agent.
AGENTS.md, CLAUDE.md, .claude/CLAUDE.md, commands/setup.md, docs/agent-files.md, docs/agents.md, docs/overview.md, docs/skills-mcp.md, docs/setup/opencode.md, docs/setup/kimi-code.md, docs/setup/claude-code.md, docs/setup/index.md, docs/index.md, docs/distribution/02-plugin-install.md, docs/.vitepress/config.js — registration sweep for the three new agents: core-agent count updated from 11 to 14 throughout, including the model tier map (improvement-advisor-agent → Reasoning/opus; documentation-agent, retrospective-agent → Execution/sonnet), the docs/agent-files.md copy-paste page, the agent overview page, the skills/MCP enhancement map, all three per-tool setup guides, the plugin's Agent Namespacing table, and the site sidebar. docs/distribution/01-plugin-mapping.md and docs/distribution-roadmap.md were deliberately left untouched — both are dated, checked-off historical records of the v3.2.0 plugin migration, not a live agent registry.

v6.3.0 — August 4, 2026

Added

agents/code-reviewer-agent.md (+ .opencode/agents/, .kimi-code/agents/ mirrors) — added a 6th review dimension, "Simplicity / Over-Engineering" (unjustified abstraction, dead code, complexity disproportionate to the requirement). Wired in as a simplicity frontmatter check field, a Checks-table row, and an optional karpathy-guidelines skill invocation backing it — closes a gap where over-engineered code had no review dimension to be flagged under.
agents/architect-agent.md (+ mirrors) — added a YAGNI guardrail to Step 3 (Propose 3 Design Options): the simplest option satisfying every Step-1 constraint is preferred, and added complexity must trace to a specific constraint rather than a hypothetical future one.

v6.2.1 — August 4, 2026

Fixed

agents/orchestrator-agent.md (+ .opencode/agents/, .kimi-code/agents/ mirrors) — the HITL section's step 1 pointed to "step 4" for where the Approve/Request-changes recommended-option logic lives; that logic is actually in step 5. Corrected the cross-reference.
agents/code-reviewer-agent.md (+ mirrors) — the frontmatter example's issues_summary declared critical: 0, but the worked Issues-table row directly below it (I1) was tagged Impact: critical, contradicting the count it's meant to illustrate. Changed I1 to high so the example is internally consistent.
agents/security-reviewer-agent.md (+ mirrors) — the frontmatter example asserted status: SECURE alongside contract_enforcement_summary.gaps_count: 1 and a critical-severity finding row, both of which the file's own status rule (a few lines below) says force VULNERABILITIES_FOUND. Changed the example to status: VULNERABILITIES_FOUND and the finding's severity to high, matching findings_summary.
agents/test-verifier-agent.md (+ mirrors) — same category of bug: status: READY co-occurred with high: 1 in issues_summary and a critical-tagged Issues row, both violating the file's own READY rule (zero critical/high). Changed the example to status: NEEDS_FIXES and the row's Impact to high. Also fixed the Important Notes' stale "loop back with a structured issues[], not prose" line, left over from a pre-Markdown-migration design and contradicting the file's own Markdown-table output format — it now points at the actual, already-documented loop-back mechanism (Issues table rows, filtered by disposition when orchestrator-invoked).
agents/impact-assessment-agent.md (+ mirrors) — the effort-classification table had simple_fix: ≤ 3 files and medium: 3–10 files, overlapping at exactly 3 files and leaving a small change with a new endpoint matching neither row (file count too low for medium, endpoint criterion disqualifying simple_fix). Narrowed simple_fix to ≤ 2 files and added an explicit rule: all criteria in a row must hold, and a higher-impact criterion (new endpoint, schema change, auth impact) always escalates past simple_fix regardless of file count. Also fixed the worked frontmatter example: risk_counts.medium was 1 with no medium-severity row in the table below it (the only Risks row shown is high), and open_dispositions was 3 against only 2 actual undispositioned rows (1 Risk + 1 Open Question) — corrected to medium: 0 and open_dispositions: 2.
agents/context-extractor-agent.md (+ mirrors) — the Output Format skeleton listed Stack, Reusable Components, Patterns, Conventions, No-Touch Zones, Technical Context, Out-of-Scope, and AI Validation Criteria as flat ## siblings of ## Context and ## Issue Technical Section, contradicting the Section Descriptions immediately below which describe them as contents of those two sections — no consumer could tell where one section ended and the next began. Demoted them to properly nested ###/#### headings. Also fixed three stale/ambiguous lines: "You do NOT modify files" (contradicted by the Write/Edit tools and the file's own "Write to Project" step — scoped to "any file other than your own output"), a leftover "building context JSON" reference from before the JSON→Markdown output migration (now "00-context.md"), and "omit it or mark it as not found" (a free choice on grounding-critical behavior that let a scan gap look identical to a deliberate omission — now mandates "not found", never silent omission).
agents/team/implementer-lead-agent.md — the Contract Mismatch Disposition Loop had an "if AskUserQuestion is unavailable, print a text menu" fallback branch, while the Test Plan Gate a few sections later flatly states "do not print a text menu and wait for a typed reply" — a direct contradiction on whether the tool can be assumed present. Since this agent is Claude-Code-only (unlike the core pipeline agents, which also run in Cursor/JetBrains/Codex CLI/OpenCode), AskUserQuestion is always available; removed the dead fallback branch and made the loop's AskUserQuestion usage unconditional.
agents/team/teammate-database-agent.md — the worked CREATE TABLE example mixed Postgres (gen_random_uuid()) with MySQL-only syntax (inline ENUM(...), ON UPDATE CURRENT_TIMESTAMP), and would not run on either engine as written. Standardized on Postgres: the enum column is now VARCHAR + CHECK (... IN (...)) (consistent with the file's existing CHECK (amount > 0)), and the ON UPDATE clause was replaced with a one-line note that Postgres needs a BEFORE UPDATE trigger for the same effect. Added a comment directing the agent to confirm the project's actual engine before assuming this dialect.
agents/team/teammate-frontend-agent.md — the fetch example omitted the Content-Type: application/json header (wire-incompatible with a JSON body-parsing backend), and destructured client_secret from the response body unconditionally before checking status — fetch only rejects on network failure, not on 4xx/5xx, so an error response would be parsed as if it were a success. Added the header and unified the previously-disconnected "Call Backend APIs" / "Handle Responses" snippets into one flow: parse the body once, then branch on status via a handleResponse helper before touching any success-only field.
agents/release-planner-agent.md (+ mirrors) — the only phase with no machine-checkable status: status: ready was the sole value ever emitted, and "Approve (Recommended by default — this agent has no pass/fail status)" was unconditional even when the Ledger Update step had just flagged a 🔴 open constraint as "a release blocker" in prose. Added status: ready|blocked, derived from release-blocking constraints/open-questions or any critical risk, and made the Approve/Request-changes recommendation conditional on it. orchestrator-agent.md needed no change — its HITL status-reading logic already treats blocked as a generic recognized value.
agents/implementer-tdd-agent.md (+ mirrors) — RED and GREEN phases were entirely self-reported ("When user runs tests: ALL FAIL/PASS"), so tdd_verification.red_phase_verified/green_phase_verified were unfalsifiable — the agent holds Bash but never actually ran the suite itself. PHASE 2 and PHASE 4 now run the project's test command directly (same framework-detection table as test-verifier-agent), paste the raw output into new ## Test Execution — RED/GREEN sections, and only set the verification flags to true when that output actually shows the expected result. Added unknown as a third value for when the command can't run at all (missing deps, no runner) — never fabricate true, never silently claim false for a check that never ran.
agents/orchestrator-agent.md (+ mirrors) — the Phase 4 loop (Code Reviewer ↔ Implementer) re-checks for test regressions after it runs (Guard 3 → test-verifier-agent), but the Phase 3 loop (Implementer ↔ Test Verifier) had no equivalent: code changed to satisfy test-verifier's fixes was never re-checked by code-reviewer-agent, so a quality/security regression introduced mid-loop could ship unnoticed. Added a symmetric Guard step to the Phase 3 loop (output to 04-review-recheck.md, distinct from Phase 4's own 04-review.md, since code-reviewer already ran earlier in the pipeline sequence here). Also fixed an ambiguity in the Phase 4 guard: "skip Phase 5 invocation" was only stated for the failing branch — it now states explicitly that the guard's own run replaces the normal Phase 5 invocation regardless of outcome. While rewriting both loops for this, deduplicated their ~30-line-each shared procedure (prior-exhaustion check, Loop State, monotonic-progress check, cleanup) into one parameterized "Loop Actuator Procedure," with only the phase-specific Guard step kept separate — the two guards differ in kind, not just in which agent they call.

Added

agents/team/teammate-backend-agent.md, teammate-frontend-agent.md, teammate-database-agent.md, teammate-tests-agent.md — added an "Owned Paths" section to each: the file paths that belong to that teammate, and an instruction to message the lead rather than edit outside them — previously nothing stopped one teammate from touching another's domain (e.g. teammate-tests "fixing" backend code). Also added a "Progress Signals" section: each teammate now messages the lead at task start, at defined per-unit checkpoints (per endpoint/component/table), and at completion — a teammate that went silent for an entire GREEN-phase task previously looked identical to a stalled one, with no visibility until the Lead's own stall-detection polling kicked in.
agents/team/implementer-lead-agent.md — added a "Progress relay" instruction: the Lead now surfaces teammates' progress signals to the human as short status lines as they arrive (e.g. 🔧 teammate-backend: 2/3 endpoints done), instead of only reporting at phase boundaries — this is what actually gives the human visibility into a running Team Mode session, complementing (not replacing) the existing stall-detection polling.

v6.2.0 — July 30, 2026

Added

.kimi-code/agents/ — new, hand-maintained mirror of the 11 core KAIROS agent files (agents/, not agents/team/), translated to Kimi Code's frontmatter schema. This mirror is far closer to the canonical format than the OpenCode one: name:, description:, and the tools: CSV copy over unchanged (Kimi Code accepts Claude-Code-style frontmatter natively and shares the same tool names, AskUserQuestion included); the only translation is model: opus → model_preference: primary and model: sonnet → model_preference: secondary — symbolic preferences that resolve to the user's configured Kimi models (default_model / [secondary_model] in config.toml), so the pack contains no Claude/Anthropic model ids at all. Every body is byte-for-byte identical to its agents/ source — only frontmatter changed. The 5 Team Mode files (agents/team/) are deliberately excluded, same rationale as the OpenCode mirror: their coordination logic is Claude-Code-specific, and a frontmatter-only port would ship a non-functional agent.
docs/setup/kimi-code.md — new setup guide for Kimi Code: copying the shipped .kimi-code/agents/ pack into a project (or user-level ~/.kimi-code/agents/), the frontmatter mapping table with a worked pm-agent.md example, optional Kimi model configuration for the primary/secondary split (default_model + [secondary_model], experimental KIMI_CODE_EXPERIMENTAL_SECONDARY_MODEL=1 flag, /secondary_model TUI command), AGENTS.md project-context setup, session startup via kimi --agent orchestrator-agent, HITL via Kimi Code's native AskUserQuestion (gates take the same primary branch as Claude Code — no text-menu fallback, unlike OpenCode), copying skills/contract-checklist/ into .kimi-code/skills/, a note on ${VAR} template rendering (unknown variables stay verbatim, so the Bitbucket curl examples are safe), a feature-comparison table, and troubleshooting. Verified against the official Kimi Code docs (kimi-code-cli/customization/agents.html, kimi-code-cli/configuration/config-files.html).
docs/.vitepress/config.js, docs/setup/index.md, docs/index.md, docs/roadmap.md — wired Kimi Code into the Setup nav/sidebar, the tool-comparison table (✅ native HITL via AskUserQuestion), and the "works with" / multi-tool-support enumerations alongside the other supported tools.
AGENTS.md, CLAUDE.md, .claude/CLAUDE.md — documented the .kimi-code/agents/ mirror and the mandatory rule that any change to an agents/*.md file must update its .kimi-code/agents/ counterpart in the same commit, alongside the existing OpenCode mirror rule and with the same Team Mode exclusion.
docs/setup/opencode.md — new "Customize models without forking the pack" section: per-agent model overrides via opencode.json's agent.<name>.model (with a full 11-agent, two-tier example using {env:...} substitution), so users can point each KAIROS tier at any provider OpenCode gateways to without editing the shipped .opencode/agents/*.md files.
docs/setup/claude-code.md — new "Customizing models" section documenting the three available override paths (edit model: frontmatter, the global CLAUDE_CODE_SUBAGENT_MODEL env override, project-scope shadow copies over plugin agents) and noting that no plugin-install-time configuration mechanism exists.
docs/setup/kimi-code.md — model configuration section extended with [secondary_model] patch fields (default_effort, max_output_size) and the KIMI_SECONDARY_MODEL / KIMI_SECONDARY_EFFORT env overrides.
commands/setup.md — new Claude Code plugin slash command /kairos:setup: guided model configuration that asks for a strategy (Default opus/sonnet split, Economy, Inherit, or Custom per tier) and applies it. On copy-installs it rewrites the model: frontmatter of .claude/agents/ files per tier; on plugin-only installs it either materializes project copies (rewriting the scoped @kairos: calls to bare names so routing stays self-contained, full two-tier control) or sets a single global CLAUDE_CODE_SUBAGENT_MODEL in settings.json. Plugin root is the repo root, so commands/ is auto-discovered.
docs/distribution/02-plugin-install.md, docs/distribution/01-plugin-mapping.md, AGENTS.md — documented the new commands/ plugin component and the /kairos:setup post-install step.

v6.1.0 — July 30, 2026

Added

.opencode/agents/ — new, hand-maintained mirror of the 11 core KAIROS agent files (agents/, not agents/team/), translated to OpenCode's frontmatter schema: tools: CSV → granular permission: object (edit/bash set per agent's actual write/exec access), model: alias → provider-prefixed model id, new mode: primary|subagent field (orchestrator-agent is the only primary), name: dropped (no equivalent). Every body is byte-for-byte identical to its agents/ source — only frontmatter changed. The 5 Team Mode files (agents/team/) are deliberately excluded: their bodies depend on Claude Code's Agent Teams feature throughout (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, spawning via Claude Code's agent tool, an unconditional AskUserQuestion call in implementer-lead-agent.md's Test Plan Gate with no fallback) — a frontmatter-only port would ship a non-functional agent. No conversion script ships in this repo; the mirror is maintained by hand on purpose (see .claude/CLAUDE.md's new "OpenCode Mirror Sync" rule and root CLAUDE.md's "OpenCode Mirror" section).
docs/setup/opencode.md — new setup guide for OpenCode: copying the shipped .opencode/agents/ pack into a project, the frontmatter mapping table (for re-deriving the mirror by hand after an agent edit), a worked pm-agent.md example, AGENTS.md project-context setup, HITL via the existing text-menu fallback (OpenCode has no AskUserQuestion), a feature-comparison table, troubleshooting, and an explicit note on why Team Mode has no mirror. Verified against the current official OpenCode docs (opencode.ai/docs/agents/, /docs/permissions/, /docs/tools/, /docs/rules/), not the unofficial open-code.ai mirror.
docs/.vitepress/config.js, docs/setup/index.md, docs/index.md, docs/roadmap.md — wired OpenCode into the Setup nav/sidebar, the tool-comparison table, and the "works with" / multi-tool-support enumerations alongside the other supported tools.
11 gated agent files (architect-agent.md, code-reviewer-agent.md, context-extractor-agent.md, impact-assessment-agent.md, implementer-coder-agent.md, implementer-tdd-agent.md, orchestrator-agent.md, pm-agent.md, release-planner-agent.md, security-reviewer-agent.md, test-verifier-agent.md) — added "OpenCode" to the AskUserQuestion-unavailable fallback's example-host parenthetical, for consistency with the other non-Claude-Code hosts already listed. Cosmetic only — the fallback behavior was already host-agnostic. (agents/team/implementer-lead-agent.md has no equivalent host-listing text to edit, and its AskUserQuestion calls are intentionally left as-is — see above.)
CLAUDE.md, .claude/CLAUDE.md — documented the .opencode/agents/ mirror, the mandatory rule that any change to an agents/*.md file must update its .opencode/agents/ counterpart in the same commit, and the explicit Team Mode exclusion.

v6.0.1 — July 29, 2026

Fixed

agents/orchestrator-agent.md — added Hard Constraint 5: the orchestrator must never run headless (inside a backgrounded/detached task, a scripted multi-agent workflow, or a scheduled/cron run). HITL gates assume a live human either answers AskUserQuestion or reads/replies to the text-menu fallback (Constraint 3) — a fully non-interactive invocation has neither, so a gate would hang forever or get silently bypassed by the driving automation. Constraint 3's existing fallback wording was narrowed to make clear it covers a different case (a live human in a non-Claude-Code chat IDE), not headless execution.

v6.0.0 — July 23, 2026

Added

agents/implementer-tdd-agent.md, agents/test-verifier-agent.md — the Phase 0 Test Cases table gained a declared Intent column (one line: the specific behavior the test locks in, not a restatement of its name), and test-verifier-agent's Assertion Strength check gained an intent-consistency sub-check that flags a test whose actual assertion is narrower than (medium) or unrelated to (high) its declared intent. Missing intent data is skipped and noted once, never fabricated or flagged as its own issue. Operationalizes the PROOF methodology's "ogni test con intent dichiarato" requirement, closing a gap confirmed by direct comparison against internal/PROOF_Constitution_v2.md — the prior format had no place to declare why a test exists, only its name and category.
agents/pm-agent.md — the Success Criteria step and output section now guide EARS-style phrasing (When <trigger>, the <system> shall <response>) wherever a criterion genuinely has a trigger and a response, instead of free-form prose only. Criteria that aren't trigger/response pairs stay plain prose — the template is guidance, not a mandatory mold — and Lean Mode (simple_fix) doesn't manufacture EARS-shaped criteria where none would otherwise exist. Tightens the same artifact test-verifier-agent already maps tests against (AC-1, AC-2, ...) and aligns with the Spec-Driven-Delivery positioning internal/PROOF_v2_Proposta_Unificata.md §5 stakes out (EARS is the notation Kiro/Spec-Kit converge on).
agents/architect-agent.md — the existing Pre-Contract Resolution step (§5) now derives an explicit promptable: yes|no frontmatter signal: yes when every applicable contract question is resolved (or N/A) and no blocking ledger item remains; no otherwise, with a new ## Promptable Gaps table naming exactly what's missing. Operationalizes PROOF's "Promptable" signature (an issue executable by an agent without further questions) at the point in the pipeline where enough is actually known to judge it — piggybacks on work Pre-Contract Resolution was already doing, rather than adding a new pass.
agents/orchestrator-agent.md — the Architect Gate's default recommendation now reads promptable: no as a blocking signal (alongside NEEDS_FIXES/VULNERABILITIES_FOUND/blocked), flipping the default from Approve to Request changes and forwarding the Promptable Gaps table as re-run feedback. The final Present step gained an optional RUN METRICS block that surfaces the Phase 3/4 Loop Actuators' existing convergence data (first-pass vs. N-iterations-to-converge, thrash/exhausted outcomes) and the ledger's open-question count — explicitly labeled as this-run-only, not a substitute for PROOF's cross-run Velocity/Rework Ratio/Gate Pass Rate metrics, which need aggregation KAIROS's per-feature-folder model doesn't have.

This release is the outcome of a full PROOF↔KAIROS fit panorama (every PROOF Constitution/Proposta concept checked against actual agent behavior, not assumed) — see the session's plan artifact for the complete mapping, including what was already matched, what's confirmed out of KAIROS's reach (team cadence, role/capacity limits, the cross-run metrics dashboard), and what was deliberately skipped (a literal Gate 1/3 two-signature split would need a real second human reviewer or would be theater — neither is a KAIROS agent-file change).

v5.4.0 — July 23, 2026

Added

agents/orchestrator-agent.md, agents/impact-assessment-agent.md, agents/team/implementer-lead-agent.md — the Risk/Contract-Mismatch Disposition Loops gained an on-demand explain trigger: if a human replies "explain"/"why"/"perché"/"spiega" instead of picking Accept/Mitigate/Escalate/Defer for a row, the loop now writes 2-4 plain-language sentences grounded in that row's actual file/code/design content — what could concretely go wrong, why it matters, what someone with no prior context on the row needs to know — then re-asks the same row instead of advancing or misfiling the reply as fix feedback. Every row stays terse by default; the depth is generated only when asked for, so review output doesn't grow for rows nobody needs explained. Closes the readability gap where dense one-line Risk/Issue/Finding rows (tuned for fast disposition) gave a junior dev no path to the reasoning behind a row before deciding.
agents/pm-agent.md, agents/architect-agent.md, agents/code-reviewer-agent.md, agents/test-verifier-agent.md, agents/release-planner-agent.md, agents/impact-assessment-agent.md, agents/team/implementer-lead-agent.md — every Risks/Issues/Findings/Contract-Drift table gained the "see below" overflow pattern (previously only on security-reviewer-agent.md's Findings table): when a row's reasoning doesn't fit one line, keep a one-line Description with a pointer and add a short prose paragraph under the table, instead of losing the reasoning to table-cell truncation. The explain trigger above reads from this same prose when present.

Changed

agents/architect-agent.md — the ## API Contracts section's Request/Response examples changed from raw json code blocks to Markdown tables (Field | Type | Required | Constraints for requests; Status | Body for responses), matching the table style ## Data Model already used in the same document. The two sections previously used two different conventions for structurally identical information.
agents/team/implementer-lead-agent.md — the 4 Team Mode contracts (TEST, API, DATABASE, PATTERN), previously defined as raw JSON blocks pasted into teammate spawn prompts, are now Markdown: TEST as grouped bullet lists, API as per-endpoint request/response tables, DATABASE as one table per entity (matching architect's Data Model style) plus a compact Indexes line, PATTERN as nested bullets. Spawn-prompt wording updated from "paste CONTRACT JSON here" to "paste CONTRACT section here". No behavior change — these contracts are read as prompt text by other agents, never machine-parsed, so the format carries no compatibility burden (same rationale as the v5.0.0 artifact-format migration, applied here to in-body content that migration didn't reach). The .claude/settings.json example in the same file is unchanged — that one is a real config file, not KAIROS's own artifact format.

v5.3.0 — July 18, 2026

Added

agents/implementer-tdd-agent.md and agents/implementer-coder-agent.md — gained Lean Mode, scaled to task effort: when 00b-impact.md classifies the task as effort: simple_fix (or the agent's own standalone judgment agrees — ≤2 files, no new endpoint/schema/auth surface, no new dependency), the Phase 0 plan drops to Approach + file list (plus test names in the TDD agent), the Risks table and Waves section are omitted unless something genuinely surfaces, TDD test generation narrows to HAPPY PATH + ERROR CASES only, and the mandatory 2b Ledger Update becomes additive-only instead of a full re-walk of every row. Closes the gap where a 1-file fix paid the same fixed process cost as a multi-file feature — both implementers previously ran the same unconditional heavyweight process regardless of size, even though impact-assessment-agent already computes the effort classification needed to branch on. The Phase 0 HITL gate itself is unchanged — Lean Mode trims plan content, not the approval step.
agents/pm-agent.md, agents/architect-agent.md, agents/test-verifier-agent.md, agents/code-reviewer-agent.md, agents/security-reviewer-agent.md, agents/context-extractor-agent.md — gained the same effort-scaled Lean Mode pattern, tuned per agent: pm-agent and architect-agent skip constraint/design categories that plainly don't apply and drop the Risks table when empty; architect-agent's "Propose 3 Design Options" collapses to one recommended approach with no real design fork; test-verifier-agent's Lean Mode specifically mirrors implementer-tdd-agent's narrowed test categories (boundary/edge coverage isn't required for tests that were never supposed to exist under Lean Mode, avoiding the same category of mismatch fixed below for code-reviewer/coder-agent) while leaving its assertion-strength/determinism/hygiene/mocking checks untouched since those already scale with actual test count; security-reviewer-agent's 7 adversarial checks are deliberately not trimmed by effort (it only runs when already judged sensitive) — only its ledger-update verbosity scales; context-extractor-agent (which runs before any effort classification exists) judges scope itself from the issue draft. Every agent's mandatory full-ledger-rewalk becomes additive-only in Lean Mode, matching the implementer pattern above.
agents/team/implementer-lead-agent.md — gained Layer Scoping (new Step 1b): only spawns teammates for backend/frontend/database layers the architecture spec actually touches, instead of unconditionally spawning all three plus tests for every feature. A frontend-only UI change no longer spawns teammate-database-agent/teammate-backend-agent against empty contracts. Added stall handling to the three previously-unbounded N-of-N waits (RED-phase test wait, GREEN-phase parallel wait, REFACTOR re-verify wait): two silent progress checks trigger a direct message to the teammate, a third with no response surfaces the stall to the human instead of blocking indefinitely. Added a 2-repeat cap on the contract-mismatch correction loop before escalating to the human, mirroring the orchestrator's own monotonic-progress check.

Fixed

agents/code-reviewer-agent.md — the mandatory "Coverage >80%?" Testing check had no branch on which implementer produced the code, so every review of implementer-coder-agent output (which by design returns "no test files, no coverage report") failed this check by construction. The Testing check now first reads whether 03-implementation.md's frontmatter carries tdd_verification/coverage_summary fields; if absent (no-TDD path), it's marked N/A — no-TDD path and never counts toward NEEDS_FIXES.
agents/orchestrator-agent.md — the Phase 3/4 Loop Actuators' max_retries came from unvalidated user input ("recommended max: 3" was a hint, never enforced), so a value like auto 500 defeated the iteration cap; N is now clamped to a hard ceiling of 5. Both actuators also deleted their ## Loop State unconditionally on exit, including after thrash/exhausted outcomes — with no memory of a failed loop, a human clicking "Request changes" at the HITL gate could silently re-arm a fresh full-budget auto-loop with no signal that this exact loop already failed to converge earlier in the same pipeline run. Thrash/exhausted exits now also write a persistent ## Loop History entry (separate from ## Loop State, survives its cleanup); re-arming when one exists now requires an explicit human choice instead of looping silently. The generic Error Handling fallback (used by non-actuated retries) now flags the 3rd consecutive no-progress retry instead of allowing indefinite silent retries with no monotonic-progress signal at all.

v5.2.0 — July 18, 2026

Added

agents/implementer-coder-agent.md — gained Iteration Mode, mirroring implementer-tdd-agent.md: detected automatically from ## Loop State in ledger/open-questions.md, skips the Phase 0 plan gate, scopes work to loop_state.cumulative_issues, and emits a ## Changes This Iteration section plus an iteration_mode frontmatter field. Closes the gap where this agent had no way to do a targeted fix pass — a full re-run would re-plan from scratch every time.

Fixed

agents/orchestrator-agent.md — Phase 3 and Phase 4 Loop Actuators — both auto-retry loops hardcoded a re-invocation of implementer-tdd-agent, regardless of which implementer variant actually ran Phase 3. If the user had picked implementer-coder-agent (explicitly for a project with no test suite) or Team Mode's implementer-lead-agent (after confirming its 3.5× cost gate) and enabled auto loop policy, a NEEDS_FIXES verdict would silently re-invoke implementer-tdd-agent instead — abandoning the chosen implementation strategy mid-pipeline with no warning. Both actuators now re-invoke whichever of implementer-tdd-agent / implementer-coder-agent was selected in Step 3's routing decision (both now support Iteration Mode). Step 0e's Loop Policy prompt is gated the same way: Team Mode forces loop_policy to manual for both phases with an explanation shown to the user, since implementer-lead-agent has no Iteration Mode yet — a full re-run there would re-spawn the whole team from scratch rather than apply a targeted fix. Building that (re-spawning only the teammates needed for a fix, with contracts pinned) is a larger design task, deferred as a follow-up rather than built this pass.
agents/team/implementer-lead-agent.md — Step 1 "Analyze Architect Output" still showed a JSON example for the architect's output, stale since v5.0.0 moved 02-architecture.md to Markdown+frontmatter (Step 2b's Contract Consistency Check already read it correctly — Step 1's example didn't). Updated to point at the actual Markdown sections (## API Contracts, ## Data Model, ## Integration Points, ## Error Codes & Handling).

v5.1.0 — July 18, 2026

Added

agents/architect-agent.md — gained a ## Risks table (universal 5-column shape, risk_counts/open_dispositions frontmatter fields), closing the one gap in v5.0.0's Risk Disposition Loop rollout: architecture-level trade-offs (single points of failure, vendor lock-in, migration risk) now resolve row-by-row at the gate like every other phase's risks, instead of living only as prose in "Selected Option".
agents/orchestrator-agent.md HITL section — Constraint-Conflict Scan (step 1b) — after each phase's own Ledger Update and before the Risk Disposition Loop, the orchestrator now reads ledger/constraints.md against the phase's actual output and checks whether it contradicts a constraint an earlier phase already marked resolved — a semantic read, not a status-symbol diff, since a constraint's Status cell records only what the acting agent claims, and no agent currently cross-checks its own output against constraints older than the immediately preceding phase. A genuine conflict is appended as a high-impact row to the phase's own Risks/Issues/Findings/Contract-Drift table (creating a minimal one under ## Flagged Conflicts if the phase has none), feeding straight into the existing Risk Disposition Loop with no separate menu.

v5.0.0 — July 18, 2026

Changed

BREAKING: every pipeline artifact is now a single Markdown file with a YAML frontmatter header, replacing every .json contract and .json+.md pair. Nothing in this repo parses these files programmatically — every consumer is either another agent reading the file as prompt text or a human at a HITL gate — so JSON bought nothing and actively hurt legibility (a real 01-requirements.json came back with 8 risk objects full of paragraph-length prose, unreadable as raw JSON — the finding that started this change). Filenames: 00-context.json → 00-context.md, 00b-impact.json → 00b-impact.md, 01-requirements.json → 01-requirements.md, 02-architecture.json + 02-architecture.md → single 02-architecture.md, 03-implementation.json → 03-implementation.md (the implementer's Phase 0 plan now saves separately to 03-implementation-plan.md, restoring the separation the old 03-implementation-plan.json had — a shared filename would make a wave-2+ resume read wave 1's final summary instead of the original plan), 04-review.json + .md → single 04-review.md, 04b-security-review.json + .md → single 04b-security-review.md, 05-test-verification.json + .md → single 05-test-verification.md, 06-deployment-plan.json + .md → single 06-deployment-plan.md. Frontmatter carries only what the orchestrator branches on (status, count fields, next_agent); everything else is a Markdown body. Affects all 11 agent files, agents/orchestrator-agent.md, and every page under docs/ plus CLAUDE.md that named these files.
Every Risks/Issues/Findings table now carries a universal 5-column shape — ID | Description | Impact | Mitigation/Fix | Disposition — normalizing formats that previously varied per agent: pm-agent's {risk, impact, mitigation}, impact-assessment's {risk, implication} (no impact rating), implementer's flat risk strings (no impact or mitigation), code-reviewer's Severity|Category|File:Line|Description (no fix column), security-reviewer's per-finding H3 blocks, release-planner's Risk|Detection|Response (no severity).

Added

Risk Disposition Loop (agents/orchestrator-agent.md HITL section) — when a phase's output has a Risks/Issues/Findings table with undispositioned rows, the human now resolves each one — Accept / Mitigate now / Escalate / Defer — before the whole-artifact Approve/Request changes/Skip next/Stop gate, instead of approving or rejecting every item as a single bundle. Mitigate now and Escalate write directly to ledger/constraints.md / ledger/open-questions.md, sourced from the human's per-row choice rather than the agent silently authoring the disposition itself. An unresolved Escalate biases the following gate's recommended default to Request changes without blocking Approve. agents/impact-assessment-agent.md and agents/team/implementer-lead-agent.md carry a local copy of the same mechanic, since both agents' gates never route through the orchestrator's HITL section.

v4.2.0 — July 17, 2026

Added

agents/architect-agent.md, agents/code-reviewer-agent.md, agents/security-reviewer-agent.md, agents/test-verifier-agent.md, agents/release-planner-agent.md — each now writes two files instead of one: a lean JSON contract (status, counts, short refs) and a Markdown report (full data model, issues table, security findings, or deployment runbook). Fixes reports like a full data-model dump landing as one giant, unreadable nested-JSON file at the architecture gate — the same content renders as scannable Markdown tables in the new companion .md file. Downstream consumers (implementer-tdd-agent.md, implementer-coder-agent.md, security-reviewer-agent.md, code-reviewer-agent.md, team/implementer-lead-agent.md) and the orchestrator's file-open/issue-tracker-comment steps were updated to read/post the .md instead of the raw JSON.
agents/orchestrator-agent.md — HITL gates and the Step 0b feature-folder collision check now use AskUserQuestion only where it's actually available (Claude Code), and fall back to the pre-4.1.0 printed text-menu everywhere else. All 10 phase-agent gates and the orchestrator's canonical HITL section gained the same fallback.

Fixed

All 12 gated agent files — the v4.1.0 gate rewrite made AskUserQuestion mandatory unconditionally, which silently broke HITL enforcement on Cursor, JetBrains/Copilot, and Codex CLI (none of which have that tool — see docs/setup/cursor.md and docs/setup/jetbrains.md, which document HITL there as printed-menu-only). Restored the text-menu fallback for every gate.
CLAUDE.md, docs/workflow.md, docs/overview.md, docs/agents.md, docs/setup/*.md — pipeline tables, file-tree examples, and HITL checkpoint descriptions updated to reflect the new .json + .md output pairs and the AskUserQuestion-or-fallback gate mechanism; a stale security-reviewer output filename in CLAUDE.md's pipeline table (04b-security.json → 04b-security-review.json) corrected to match what every agent file actually uses.
agents/team/implementer-lead-agent.md — Step 2b's Contract Consistency Check still pointed the API/database contract verification at 02-architecture.json alone; the data it compares against (API contracts, full schema) moved to 02-architecture.md.
agents/test-verifier-agent.md — acceptance-criteria mapping pointed at 02-architecture.json, a field architect-agent never produces (in either the .json or the new .md). Repointed to success_criteria[] in 01-requirements.json (pm-agent), the field that actually holds them; since that list has no IDs, test-verifier now numbers them AC-1, AC-2, ... in list order.

v4.1.0 — July 17, 2026

Added

agents/*.md, agents/team/implementer-lead-agent.md — all 12 pipeline agents (plus the orchestrator) now gate on the AskUserQuestion tool instead of printing a text menu and waiting for a typed reply. Each gate marks a (Recommended) option derived from the agent's own status field (NEEDS_FIXES, VULNERABILITIES_FOUND, blocked, critical/high issues), and free-text answers are folded into change-request feedback or a ledger note. Fixes the inconsistent, improvised gate presentation reported across agents.
agents/orchestrator-agent.md — feature-folder collision check in Step 0b: if .kairos/<feature_folder>/ already exists, asks the user (Resume existing / Create new folder / Stop) instead of silently overwriting prior phase outputs on repeat runs.

Fixed

agents/orchestrator-agent.md — two Step 0b sections existed with duplicate numbering; the ledger-init step referenced feature_folder before the derive-folder step that defines it. Merged and reordered into a single 0a–0f sequence (derive folder → init ledger → read issue → select agents → announce pipeline).
agents/orchestrator-agent.md — Step 0c ("Read Issue Body") referred to itself ("go to Step 0c") instead of the next step; corrected to point at Step 0e.
agents/pm-agent.md, agents/architect-agent.md, agents/implementer-tdd-agent.md, agents/implementer-coder-agent.md, agents/code-reviewer-agent.md, agents/security-reviewer-agent.md, agents/test-verifier-agent.md, agents/release-planner-agent.md, agents/context-extractor-agent.md, agents/impact-assessment-agent.md — each agent's own standalone gate ("Present for Validation") had drifted from the orchestrator's canonical HITL option set (3 options and a literal "show the JSON" instruction vs. the orchestrator's 5). Standardized and marked as standalone-only — the orchestrator owns gate presentation whenever it's driving the pipeline.

v4.0.0 — June 28, 2026

Added

agents/orchestrator-agent.md — agentic loop actuator: optional auto-retry loops for Phase 3 (Implementer ↔ Test Verifier) and Phase 4 (Code Reviewer ↔ Implementer). Consent gate with cost estimate shown at agent selection. Loop state stored in the ledger (## Loop State section of open-questions.md), not in agent prompts.
agents/orchestrator-agent.md — Guard 3: mandatory single-pass test-verifier invocation after any Phase 4 loop run, to detect regressions introduced by code-review-driven fixes before the Phase 4 HITL gate.
agents/implementer-tdd-agent.md — Iteration Mode: detected automatically from ledger when ## Loop State with status: in_progress exists. In this mode the Phase 0 plan gate is skipped and focus is scoped to cumulative_issues only.
agents/test-verifier-agent.md — convergence_signal field added to JSON output and written to ## Loop State in ledger (when present). Provides issues_critical_high, issues_total, coverage_delta, and iteration for orchestrator loop decisions.
agents/code-reviewer-agent.md — same convergence_signal output field and ledger write for Phase 4 loop convergence tracking.
docs/agentic-loop.md — new documentation page covering loop mechanics, termination guarantees, HITL preservation, ledger state store, Guard 3, cost estimates, and backward compatibility.

Changed

Pipeline paradigm — KAIROS shifts from purely linear HITL to optional intra-phase agentic loops. Default remains manual (backward compatible with v3.x). Loops are opt-in per pipeline run.
docs/.vitepress/config.js — added "Agentic Loop" entry to sidebar under Development.

v3.4.0 — June 26, 2026

Added

agents/*.md, agents/team/implementer-lead-agent.md — shared ledger system across all 12 pipeline agents. Each agent now reads .kairos/<feature_folder>/ledger/ at phase start and updates it at phase end with mandatory accounting: every existing constraint row must be marked resolved / deferred / open / modified / dropped before adding new ones.
agents/orchestrator-agent.md — ledger lifecycle management: creates ledger/ directory on pipeline init, offers optional human annotation at each HITL gate, and warns about unresolved open-questions at pipeline end.
agents/pm-agent.md — primary ledger seeder: populates ledger/constraints.md and ledger/open-questions.md from requirement analysis.
agents/architect-agent.md — seeds ledger/decisions.md, performs the first full accounting pass over all PM constraints.
agents/context-extractor-agent.md — optional early ledger seeder: creates ledger/constraints.md with codebase-derived constraints (naming rules, no-touch zones, compatibility requirements) before the main pipeline starts.

Changed

Pipeline structure — .kairos/<feature_folder>/ now includes a ledger/ subdirectory containing three living files: constraints.md (table of constraints with per-phase status), decisions.md (table of architectural and implementation decisions), open-questions.md (table of cross-phase questions with answers). Phase JSON files (01–06) are unchanged.
Forced accounting model — each agent must update the Status column of every existing constraint row before adding new ones. Unaddressed constraints remain 🔴 open and are visible to all downstream agents. This eliminates silent information loss between phases (the "telephone game" problem).
Team Mode — only implementer-lead-agent reads and writes the ledger; teammates work via binding contracts and never touch ledger/ directly.

v3.3.0 — June 6, 2026

Added

agents/*.md, agents/team/*.md — optional-enhancement sections across all 15 agents; each agent declares which skills and MCP tools enhance it, with inline conditional instructions (> If skill X is available, invoke it; else apply inline checklist). KAIROS remains fully functional without any external install — all enhancements are additive only.
docs/skills-mcp.md — new VitePress page documenting the full skills/MCP ecosystem: MCP table, skills table, Trail of Bits plugin breakdown, copy-paste install commands, full agent × enhancement map, and gap section (database MCP, deploy MCP, LSP).
docs/.vitepress/config.js — Skills & MCP Enhancements page added to sidebar under Core Agents.
docs/agents.md — per-agent VitePress tip callouts listing declared skills and MCP tools with install commands.
README.md — Optional Enhancements section with recommended installs and link to the new docs page.

Changed

Trail of Bits plugin scope — 11 plugins declared as optional enhancements in agent files (differential-review, insecure-defaults, supply-chain-risk-auditor, static-analysis, variant-analysis, sharp-edges, property-based-testing, mutation-testing, fp-check, ask-questions-if-underspecified, audit-context-building). testing-handbook-skills and trailmark excluded: those plugins bundle 15 and 10 skills respectively; only 1 skill from each was needed, so inline fallback instructions are used instead.
MCP wiring — Chrome DevTools MCP and Playwright MCP declared in test-verifier-agent, teammate-tests-agent, teammate-frontend-agent.
karpathy-guidelines — declared in all implementer and teammate agents.

v3.2.3 — June 2, 2026

Added

docs/distribution/02-plugin-install.md — Phase 1.3 canonical install guide: prerequisites, install commands (kairos@kairos-agents-framework), full agent namespace reference tables (core and Team Mode), contract checklist skill access, global-scope clarification for /plugin commands, per-project isolation note, and Phase 1.4 routing test requirements.
docs/.vitepress/config.js — Phase 1.3 install guide added to Distribution sidebar.

Changed

.claude-plugin/marketplace.json — marketplace name set to kairos-agents-framework; install commands use kairos@kairos-agents-framework.
docs/setup/claude-code.md — "Enable Agent Teams" section expanded: all three scopes for CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS documented (project-level .claude/settings.json, global ~/.claude/settings.json, shell session export).
docs/distribution/01-plugin-mapping.md — marketplace manifest example updated to match renamed name field.

Fixed

docs/.vitepress/config.js — dead sidebar link for Contract Checklist (agents/shared/contract-checklist → skills/contract-checklist/SKILL).
docs/agent-files.md — dead link for Contract Checklist (agents/shared/contract-checklist.md → skills/contract-checklist/SKILL.md).

v3.2.0 — June 1, 2026

Added

.claude-plugin/plugin.json — plugin manifest enabling KAIROS as an installable Claude Code plugin (name: kairos, defaultEnabled: false, version: 3.2.0).
.claude-plugin/marketplace.json — self-hosted marketplace manifest pointing to the GitHub repo for distribution.
skills/contract-checklist/SKILL.md — contract checklist migrated from agents/shared/ into a Claude Code skill; accessible as /kairos:contract-checklist.

Changed

agents/orchestrator-agent.md — all 9 agent invocation calls updated to use kairos: namespace prefix (e.g. @pm-agent → @kairos:pm-agent, implementer-lead → @kairos:team:implementer-lead-agent); required for plugin-installed agent routing.
agents/team/implementer-lead-agent.md — all 4 teammate spawn type names updated to kairos:team: prefix (e.g. teammate-tests-agent → kairos:team:teammate-tests-agent); checklist path updated to new skills/ location.
agents/architect-agent.md — checklist path updated from agents/shared/contract-checklist.md to skills/contract-checklist/SKILL.md.

Removed

agents/shared/contract-checklist.md — replaced by skills/contract-checklist/SKILL.md.

v3.1.3 — June 1, 2026

Added

docs/distribution/01-plugin-mapping.md — Phase 1.1 mapping: full KAIROS component inventory mapped to plugin slots, three Phase 0 review decisions applied, complete agent-to-agent invocation list (9 @-notation calls in orchestrator, 4 Agent Teams spawn type names in implementer-lead), namespacing blocker documented with verification method and required test scope.
docs/.vitepress/config.js — Phase 1.1 mapping page added to Distribution sidebar.

Changed

docs/distribution-roadmap.md — Phase 0 checkboxes marked complete with verified answers; Phase 0 review decisions (CLAUDE.md exclusion, defaultEnabled: false, namespacing as primary risk) documented as a dedicated section; Phase 1.1 marked complete with output link; Phase 1.2 updated with namespacing hard blocker and mandatory routing test requirement for Phase 1.4.

v3.1.2 — June 1, 2026

Added

docs/distribution/00-discovery.md — Phase 0 Discovery findings: verified Claude Code plugin anatomy (manifest fields, folder layout, marketplace distribution, install steps), MCP server SDK options (TypeScript/Python/C#/Go tier 1), transport choices (stdio vs Streamable HTTP), user config blocks for both local and remote servers, and a "where does it live" summary table. Five open questions for Phase 1 captured at end of document.
docs/.vitepress/config.js — new "Distribution" sidebar section linking to the roadmap and Phase 0 discovery page.

v3.1.1 — June 1, 2026

Added

docs/distribution-roadmap.md — distribution roadmap (Plugin → MCP Server) published to the docs site; covers Phase 0 (discovery), Phase 1 (Claude Code plugin), and Phase 2 (MCP server re-architecture) with guiding principles and a "where things live" reference table.

v3.1.0 — June 1, 2026

Added

agents/security-reviewer-agent.md — new adversarial security reviewer (read-only: tools: Read, Grep, Glob, model: opus). Posture is "how do I break this" rather than checklist compliance. Covers 7 categories: authorization/IDOR (including writes through nested payloads where a PUT on a parent can mutate a child belonging to a different parent), authentication on sensitive endpoints, injection (SQL/command/template/NoSQL), secret handling, data over-exposure in responses, input validation at server boundary, and dependency risks. Output is 04b-security-review.json ranked by exploitable severity, each finding with a concrete attack scenario. Includes a mandatory contract_enforcement block that verifies ownership constraints defined in 02-architecture.json are actually present in the implementation code. Because this agent is read-only, the orchestrator handles writing the output file and opening it in the editor.
agents/impact-assessment-agent.md — new standalone grounding agent (read-only: tools: Read, Grep, Glob, model: opus). User-triggered before the orchestrator, same pattern as context-extractor-agent (Hard Constraint #4 preserved — the orchestrator never invokes it). Reads the issue and only the code it directly touches — not a full-repo rescan. Consumes 00-context.json if already present. Outputs 00b-impact.json with: effort estimate (simple_fix / medium / significant_rework) with file-level reasoning, domains touched (backend / frontend / db / auth / integrations), existing reusable assets with real file paths, gaps, risks visible from current code, open questions, and a recommended_agents block with per-agent justification. The recommendation is advisory only — it is displayed to the user as a 💡 Impact Assessment block above the Step 0d selection menu; nothing is pre-selected. Because this agent is read-only, the orchestrator (or user) handles writing and opening the file.
agents/shared/contract-checklist.md — new shared reference encoding the critical questions every API or database contract must resolve before finalization: entity lifecycle, payload shape for master-detail (nested aggregate vs separate endpoints), ownership and IDOR risk (including nested updates that mutate a child belonging to a different parent), idempotency and retry behavior, delete behavior (soft/hard, cascade), aggregate update diff (how the payload signals existing vs new vs deleted children), pagination/filter/sort, versioning, and error response shape. Referenced by both architect-agent and implementer-lead-agent.

Changed

agents/orchestrator-agent.md — security-reviewer-agent and impact-assessment-agent added to Available Subagents; Case A and Case B selection menus include security-reviewer as option 4b; Phase Execution adds Phase 4b (Security Review) between Review and Test Verification, with the orchestrator persisting 04b-security-review.json; Step 0a now checks for 00b-impact.json alongside 00-context.json; Hard Constraint #4 extended to cover impact-assessment-agent; Step 0d displays a 💡 Impact Assessment advisory block when 00b-impact.json is present — advisory only, no auto-selection; HITL file map, Pipeline Outputs tree, and Output To User block updated.
agents/architect-agent.md — new Step 5 "Pre-Contract Resolution" inserted before Detailed Design: before emitting api_contracts, the Architect must work through agents/shared/contract-checklist.md and resolve every applicable item, preventing silent drift from reaching the Implementer.
agents/team/implementer-lead-agent.md — Step 2 (Create Binding Contracts) now opens with a mandatory checklist gate referencing agents/shared/contract-checklist.md; new Step 2b "Contract Consistency Check" verifies the 4 Lead contracts are faithful to the Architect's api_contracts and database_changes before any teammate is spawned — mismatches surface as a HITL gate rather than silently diverging.

v3.0.1 — May 7, 2026

Changed

agents/test-verifier-agent.md — rewritten to match the depth of code-reviewer-agent. The agent now executes the project's test+coverage command (Jest, Vitest, pytest, Go) instead of inferring results from code, and audits seven distinct dimensions: comprehensiveness, coverage (line + branch + function), assertion strength, determinism / flakiness, hygiene (.only / .skip / empty bodies), mocking discipline, and TDD reality (cross-checks red_phase_verified from 03-implementation.json). Output schema now includes status: READY|NEEDS_FIXES, an execution block, an ac_mapping array against architecture acceptance criteria, and an issues[] list with severity, category, file, line, description, and fix — directly consumable by implementer-tdd-agent on the "Request fixes" HITL path.

v3.0.0 — May 7, 2026

Added

agents/implementer-coder-agent.md — new code-only implementer — lightweight alternative to implementer-tdd-agent for projects without a test suite or when tests are explicitly out of scope. Follows the same two-gate HITL workflow (plan approval → implementation approval) but skips all TDD phases, test-file generation, RED/GREEN cycles, and coverage measurement. Frontmatter description: "Code-only implementer — use ONLY when the project has no test suite or tests are explicitly out of scope. For projects with a test suite, use implementer-tdd-agent instead."
orchestrator-agent — implementer-coder-agent routing — the orchestrator presents implementer-coder-agent as option 3b (code-only, no TDD) in both Case A and Case B selection menus, with implementer-lead-agent promoted to 3c. Implementation Phase routing block handles all three paths.
docs/agents.md — new Implementer Agent — Code Only section with a note directing users back to implementer-tdd-agent when a test suite exists.
docs/agent-files.md — implementer-coder-agent added to the quick-jump table and as a copy-block embed section.
docs/setup/templates.md — implementer-coder-agent added to blank template block and agent role reference table (row 3b).

Changed

Agent files renamed for clarity — agents/implementer-agent.md → agents/implementer-tdd-agent.md; agents/coder-agent.md → agents/implementer-coder-agent.md. The implementer- prefix is now consistent across all three single-agent implementers. All docs, orchestrator references, VitePress sidebar, and template blocks updated accordingly.
Naming and purpose clarified across all docs — every reference to implementer-agent was audited and the TDD nature made explicit; every reference to coder-agent was labelled "code-only / no TDD". Affected files:
- docs/index.md — agent count updated (8 → 9); feature tiles revised to distinguish TDD vs code-only output
- docs/overview.md — selection menu, file tree, and "What You Get" list all updated
- docs/setup/index.md — file tree updated
- docs/setup/claude-code.md — file tree, implementer-choice tip, troubleshooting, pipeline diagram, model table
- docs/setup/cursor.md — file tree, model table
- docs/setup/vscode.md — file tree, model table

v2.1.2 — April 11, 2026

Changed

orchestrator-agent — orchestrator collapse prevention — addresses a failure mode where the orchestrator bypassed subagent delegation and the HITL gates, writing code directly.
- "Your Role" strengthened: explicit statement that the orchestrator does NOT write source code, test files, architecture documents, or any project file. "You are a coordinator, not an implementer."
- New ## Hard Constraints section with 4 absolute prohibitions:
  1. Never write source code (with a file-extension list as a trigger check).
  2. Never self-implement — specific collapse phrases ("I'll proceed with implementation", "proceeding with implementation") identified as failure signals requiring immediate redirection to the correct subagent.
  3. Never skip a HITL gate — silence or ambiguity from the user = do nothing and wait.
  4. Never auto-invoke context-extractor-agent from inside a pipeline run.
- HITL section — "STOP" language added: step 3 now reads "STOP. Do not read files, do not prepare the next prompt, do not take any action." to prevent the orchestrator from queuing work while waiting for approval.
- New ### Collapse Detection rule: before writing any response, the orchestrator self-checks whether it is about to produce implementation output; if so, it emits a visible warning (⚠️ Orchestrator self-check) and delegates immediately.
- Step 0a clarified: the prohibition on invoking context-extractor-agent is now a standalone bolded statement — "You have no authority to trigger it."
- Important Notes: added "If you are unsure which subagent to call, call none and ask the user — never guess and proceed."

v2.1.1 — April 11, 2026

Added

Open in Editor after each phase — all 7 writing agents now run code ".kairos/$feature_folder/<phase>.json" immediately after saving the output file, so the JSON is opened in the editor for inspection before the user approves — mirroring the plan-mode diff-preview pattern. Affected agents: context-extractor-agent, pm-agent, architect-agent, implementer-agent, code-reviewer-agent, test-verifier-agent, release-planner-agent.
Orchestrator HITL updated — the HITL loop now includes an explicit "open in editor" step (step 2) with the full phase-to-filename mapping (01-requirements.json → … → 06-deployment-plan.json), acting as fallback if the sub-agent cannot run the command itself.

Changed

Agent frontmatter — bash and write tools added where previously missing, required by the new code open command:
- pm-agent: [read, write] → [read, write, bash]
- architect-agent: [read, write] → [read, write, bash, grep]
- code-reviewer-agent: [read, grep] → [read, write, bash, grep]
- test-verifier-agent: [read] → [read, write, bash, grep]
- release-planner-agent: [read] → [read, write, bash]
- context-extractor-agent: [read, grep] → [read, write, bash, grep]
- Platform-specific config blocks in each agent updated to match.
Open in Editor path syntax — uses $feature_folder (shell variable) instead of <feature_folder> (ambiguous placeholder that conflicts with the bash redirection operator <). Each step is annotated with "Run from the project root, substituting the actual feature_folder value received from the orchestrator".

v2.1.0 — April 11, 2026

Changed

Team Mode now uses Claude Code's experimental Agent Teams feature (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) instead of the previous agent-tool subagent mechanism. Requires Claude Code v2.1.32+.
- Each teammate now runs as a separate Claude Code session with its own context window, rather than as a nested subagent reporting back to the caller.
- Teammates communicate peer-to-peer via a shared mailbox. The Lead can message specific teammates directly or broadcast to all.
- Work is coordinated via a shared task list with dependency management and automatic unblocking.
- Compliance feedback is sent via teammate messaging (message [teammate-name]: [feedback]) instead of re-spawning.
- Team cleanup is now explicit: the Lead shuts down teammates gracefully, then runs "Clean up the team".
agents/team/implementer-lead-agent.md — removed agent from tools: (now tools: [read, write]); updated all spawn instructions, compliance monitoring, and REFACTOR phase to use Agent Teams API; added cleanup step and experimental-flag requirement note.
Claude Code Setup — Team Mode section rewritten: replaces agent-tool verification with Agent Teams setup (settings.json env var, version check); updates cost warning, comparison table, and activation flow.
Workflow — Team Mode warning block updated: replaces agent-tool description with Agent Teams feature explanation and updated compatibility table.
Agents — "Why Claude Code only?" paragraph updated to describe Agent Teams instead of the agent tool.
Orchestrator cost warning — now mentions CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 requirement and marks Team Mode as experimental.

Notes

The TDD methodology (RED → HITL → GREEN → REFACTOR), binding contracts, and HITL gate are unchanged.
The four teammate agent files (teammate-tests-agent.md, teammate-backend-agent.md, teammate-frontend-agent.md, teammate-database-agent.md) updated: "Signal Team Lead" replaced with explicit message [lead]: "..." syntax; task completion step added (mark task as completed on shared task list); teammate-tests-agent GREEN phase now messages the Lead directly instead of passive monitoring. tools: [write] unchanged — Agent Teams coordination tools (SendMessage, task management) are always available regardless of the tools filter.
Agent Teams is experimental and disabled by default. Single Agent mode is unaffected.

v2.0.9 — April 11, 2026

Changed

Team Mode Files — removed the Contributor rule warning block; it only applies to contributors editing source files and was out of context on the copy page.

v2.0.8 — April 11, 2026

Changed

Agent Files — now contains only the 8 Core Agents. Team Mode entries removed; a note links to the new dedicated page.
Team Mode Files — new standalone page for the 5 Team Mode agent files, with its own quick-jump table, Claude Code info callout, and mandatory changelog warning. Fully separate from the Core Agents page.
Sidebar and nav updated: Team Files (copy) links to /agent-files-team; top-nav Agents dropdown gains a Team Mode Files (copy) entry.
Team Mode (optional) sidebar section expanded by default (collapsed: false) — visually distinct from Core Agents.

v2.0.7 — April 11, 2026

Added

Agent Files — new page that embeds the full raw content of every agent file (13 agents) as ready-to-copy code blocks. Content is auto-synced from source files at build time via VitePress code-snippet imports — no manual drift possible.
Changelog contribution rule — every modification to any agent file must produce an entry in CHANGELOG.md. Rule enforced via warning admonitions on the Agent Files page and the Agents overview page.
Navigation updated: Agents top-nav entry is now a dropdown; sidebar adds Agent Files (copy) as a collapsible parent per agent and Team Files (copy) for the Team Mode section.

Changed

agents/teammates/ folder renamed to agents/team/.
agents/implementer-lead.md moved into agents/team/ — it is Team Mode specific.
All agent files renamed to include the -agent suffix consistently: orchestrator-agent.md, context-extractor-agent.md, code-reviewer-agent.md, test-verifier-agent.md, release-planner-agent.md, implementer-lead-agent.md, teammate-*-agent.md. Files already named correctly (pm-agent, architect-agent, implementer-agent) are unchanged.
All name: frontmatter fields updated to match new file names.
All @agent-call references inside agent files updated.
All path and link references updated across docs and setup guides.

v2.0.6 — April 9, 2026

Added

Version number shown dynamically in the nav bar and footer, read from package.json — updating the version in one place propagates everywhere automatically

v2.0.5 — April 9, 2026

Changed

Claude Code Setup — added complete Team Mode setup instructions:
- Copy command and directory tree now include implementer-lead.md and teammates/
- New section explaining why Team Mode requires Claude Code (agent spawning comparison table vs Cursor, VS Code, etc.)
- Step-by-step activation flow with the Orchestrator cost warning
- Visual diagram of the RED → HITL → GREEN (parallel) → REFACTOR spawn sequence
- agent tool verification for implementer-lead.md
- Full pipeline diagram updated to show both implementation paths

v2.0.4 — April 9, 2026

Changed

Implementer Lead — restructured to apply real TDD methodology across the team:
- RED phase — teammate-tests is spawned first; the full test suite is written against the binding contracts before any implementation exists
- HITL test-plan gate — user reviews and approves the test plan before backend/frontend/database are spawned
- GREEN phase — teammate-backend, teammate-frontend, teammate-database spawn in parallel with the explicit goal of making the pre-existing tests pass
- REFACTOR phase — quality improvements coordinated across all layers, tests must remain green
Workflow and Agents documentation updated to reflect the three-phase TDD flow

v2.0.3 — April 9, 2026

Changed

Team Mode documentation — all references to “Claude Code only” now explain the technical reason: Claude Code’s agent tool allows an agent to spawn other agents programmatically at runtime; Cursor, VS Code, JetBrains, and Codex CLI only support user-triggered agent calls and cannot support Team Mode
- Workflow — new tool compatibility table inside the Team Mode warning block
- Agents — explanation added to the Team Mode section intro
- Overview — inline mention in the Team Mode paragraph
Overview — removed Claude-specific language from provider-agnostic sections: "isolated Claude instances" → "isolated AI agent instances"; model names removed from the file tree

v2.0.2 — April 9, 2026

Added

Pipeline diagram in Workflow — Mermaid flowchart showing all 6 phases with the Phase 3 biforcation between Single Agent and Team Mode, HITL gates on every transition
Mermaid rendering support (vitepress-plugin-mermaid)

Fixed

Implementer Agent — restored full agent definition: Phase 0 implementation plan (files, test cases, TDD order, risks) with its own HITL gate before any file is written; TDD phases 1–6 (generate tests → RED → implement → GREEN → refactor → coverage); model claude-opus-4-6; platform-specific configuration for Claude Code, Cursor, and VS Code

Removed

implementer-coordinator — removed from the framework; it was not part of the active pipeline

v2.0.1 — April 9, 2026

Added

Implementer Team Pattern (Claude Code only, optional)

A new optional execution mode for complex multi-layer features. When explicitly requested, the Orchestrator activates a coordinated team of 5 specialized agents instead of the single Implementer Agent:

Agent	Role
Implementer Lead	Team coordinator — creates binding contracts, spawns and monitors teammates
Teammate Tests	Test specialist — generates full test suite (RED phase first)
Teammate Backend	Backend specialist — implements APIs per contract
Teammate Frontend	Frontend specialist — implements UI per contract
Teammate Database	Database specialist — creates schema and migrations per contract

Also added:

Team Mode routing in the Orchestrator Phase 3 — shows explicit cost warning before activating Team Mode

Changed

Orchestrator — Phase 3 now routes to implementer-agent (default) or implementer-lead (Team Mode, explicit request only)
Implementer Agent — clarified as the default for all features, simple and complex alike

Cost Transparency

Mode	Cost/feature	When to use
Single Agent (default)	~$0.068	All features — works everywhere
Team Mode	~$0.242 (3.5×)	Critical systems, only on explicit request

Team Mode is Claude Code only. The single Implementer Agent works everywhere.

v2.0.0 — April 8, 2026

Added

7-agent orchestration pipeline — Orchestrator, PM Agent, Architect Agent, Implementer Agent, Code Reviewer, Test Verifier, Release Planner
Context Extractor — standalone pre-pipeline agent producing 00-context.json for downstream agents
Human-in-the-Loop (HITL) gates — explicit user approval after every pipeline phase
Selective pipeline — activate only the agents you need per run
Issue tracker integration — Jira, GitLab Issues, Bitbucket Issues
Multi-tool support — Claude Code, Cursor, VS Code, JetBrains AI Assistant, OpenAI Codex CLI
Feature folder isolation — each run writes to .kairos/<feature_folder>/ for a complete audit trail
VitePress documentation site with full agent reference and tool-specific setup guides
Deployment configs for Vercel, Netlify, GitHub Pages

Notes

Initial public release
Licensed under AGPL-3.0

Changed

docs/agent-files-team.md — removed redundant Contributor rule warning block (applies only to contributors editing source files; out of context on the Team Mode copy page).

[v2.0.8] — 2026-04-11

Changed

docs/agent-files.md — Core Agents only (8 agents). Team Mode entries removed from quick-jump table; note added linking to the new team page.
docs/agent-files-team.md — new standalone page for the 5 Team Mode agent files, with its own quick-jump table, Claude Code info callout, and mandatory changelog warning.
Sidebar: Team Files (copy) and its children now link to /agent-files-team — a fully separate page from Core Agents.
Top-nav Agents dropdown: added Team Mode Files (copy) entry pointing to /agent-files-team.
Team Mode (optional) sidebar section: changed from collapsed: true to collapsed: false so it renders as a visible section header, clearly separated from Core Agents.

[v2.0.7] — 2026-04-11

Added

docs/agent-files.md — new Agent Files page: embeds the full raw content of every agent file as copy-ready code blocks using VitePress code-snippet imports. Auto-synced from source files at build time.
Contributor rule: every modification to any agent file must produce an entry in CHANGELOG.md.
Sidebar restructured: Agent Files (copy) collapsible parent per agent, Team Files (copy) collapsible parent in Team Mode section.

Changed

agents/teammates/ renamed to agents/team/.
agents/implementer-lead.md moved into agents/team/ — Team Mode specific.
All agent files renamed with consistent -agent suffix: orchestrator-agent.md, context-extractor-agent.md, code-reviewer-agent.md, test-verifier-agent.md, release-planner-agent.md, implementer-lead-agent.md, teammate-*-agent.md. Already-correct names (pm-agent, architect-agent, implementer-agent) unchanged.
All name: frontmatter fields, @agent-call references, and path/link references updated across all files.

[v2.0.6] — 2026-04-09

Added

Version number displayed dynamically in nav bar (v2.0.6 dropdown) and footer, read from package.json — updating the version in one place propagates everywhere automatically

[v2.0.5] — 2026-04-09

Changed

docs/setup/claude-code.md — added Team Mode setup section:
- Step 1 now includes implementer-lead.md and teammates/ in the copy command and directory tree
- New "Team Mode — additional setup" section: why Claude Code only (tool comparison table), how to activate, the RED/GREEN/REFACTOR spawn sequence with HITL test-plan gate, agent tool verification
- Full pipeline diagram updated to show both implementation paths

[v2.0.4] — 2026-04-09

Changed

agents/implementer-lead.md — restructured to apply real TDD methodology: RED phase (teammate-tests spawned first, all tests written before any implementation), HITL test-plan gate before GREEN phase, GREEN phase (backend + frontend + database spawned in parallel to make tests pass), REFACTOR phase. Added agent tool to frontmatter.
docs/workflow.md — Team Mode description updated to reflect the three-phase TDD flow with the additional HITL gate between RED and GREEN
docs/agents.md — Implementer Lead description updated to reflect RED/GREEN/REFACTOR coordination

[v2.0.3] — 2026-04-09

Changed

docs/workflow.md — Team Mode warning block now includes a tool compatibility table explaining why Claude Code is required (agent-to-agent spawning via agent tool) vs Cursor, VS Code, JetBrains, Codex CLI (user-triggered only)
docs/agents.md — Team Mode section now explains the technical reason for the Claude Code requirement
docs/overview.md — Team Mode paragraph now mentions the technical distinction inline
docs/overview.md — removed Claude-specific language from "The Problem It Solves" ("isolated Claude instances" → "isolated AI agent instances") and from the file tree (removed model name comments)

[v2.0.2] — 2026-04-09

Added

Mermaid diagram in docs/workflow.md — interactive flowchart showing the full pipeline with Phase 3 biforcation (Single Agent vs Team Mode)
mermaid and vitepress-plugin-mermaid installed and configured in docs/.vitepress/config.js

Fixed

agents/implementer-agent.md — restored full content lost in v2.0.1: Phase 0 (implementation plan + HITL plan gate), TDD phases 1–6, model claude-opus-4-6, platform configurations (Claude Code / Cursor / VS Code), .kairos/ output, issue tracker comments

Removed

agents/implementer-coordinator.md — removed; not referenced by the orchestrator and not part of the active pipeline

[v2.0.1] — 2026-04-09

Added

Implementer Team Pattern (Claude Code only, optional)
- agents/implementer-lead.md — Team coordinator (not a coder; creates binding contracts and spawns teammates)
- agents/teammates/teammate-tests.md — Test specialist (RED phase first)
- agents/teammates/teammate-backend.md — Backend specialist
- agents/teammates/teammate-frontend.md — Frontend specialist
- agents/teammates/teammate-database.md — Database specialist
Team Mode routing in Orchestrator Phase 3 with explicit cost warning before activation
Internal documentation guides:
- internal/COST-REALITY-CHECK.md — Honest cost analysis (single agent vs team)
- internal/TEAM-MODE-PROVIDER-SPECIFICS.md — Provider compatibility matrix
- internal/ROUTING-LOGIC-AGNOSTIC.md — Why routing is agent decision logic, not code
- internal/IMPLEMENTER-TEAM-PATTERN.md — Team pattern design rationale

Changed

agents/orchestrator.md — Phase 3 now routes to implementer-agent (default) or implementer-lead (Team Mode, only on explicit user request with cost warning)
agents/implementer-agent.md — Clarified as default for all features, simple and complex alike
Documentation updated to reflect the full 13-agent ecosystem (8 core + 5 team specialists)

Notes

Team Mode is Claude Code only; implementer-agent works everywhere (Claude Code, API, Local)
Default remains single implementer-agent at ~$0.068/feature
Team Mode costs ~$0.242/feature (3.5×) — only activated on explicit user request after confirming the cost warning

[v2.0.0] — 2026-04-08

Added

7-agent orchestration pipeline: Orchestrator, PM Agent, Architect Agent, Implementer Agent, Code Reviewer, Test Verifier, Release Planner
Context Extractor — standalone pre-pipeline agent that produces 00-context.json
Human-in-the-Loop (HITL) gates after every pipeline phase
Selective pipeline — users choose which agents to activate per run
Issue tracker integration: Jira, GitLab Issues, Bitbucket Issues
VitePress documentation site with full agent reference and setup guides
Deployment configurations for Vercel, Netlify, GitHub Pages
Pipeline Templates in setup guides
Multi-tool support: Claude Code, Cursor, VS Code, JetBrains AI Assistant, OpenAI Codex CLI
Feature folder isolation under .kairos/<feature_folder>/ for audit trail

Notes

Initial public release
Licensed under AGPL-3.0

Changelog ​

v9.7.1 — November 14, 2026 ​

Added ​

Changed ​

Fixed ​

v9.7.0 — October 23, 2026 ​

Added ​

Changed ​

v9.6.4 — October 21, 2026 ​

Fixed ​

v9.6.3 — October 21, 2026 ​

Fixed ​

v9.6.2 — October 19, 2026 ​

Fixed ​

v9.6.1 — October 17, 2026 ​

Fixed ​

v9.6.0 — October 16, 2026 ​

Added ​

Changed ​

Fixed ​

Added ​

Changed ​

Removed ​

v9.4.0 — October 10, 2026 ​

Fixed ​

Added ​

Changed ​

v9.3.1 — October 10, 2026 ​

Added ​

Changed ​

v9.3.0 — October 10, 2026 ​

Added ​

Changed ​

Notes ​

v9.2.1 — October 10, 2026 ​

Changed ​

v9.2.0 — October 7, 2026 ​

Added ​

Changed ​

v9.1.1 — October 6, 2026 ​

Fixed ​

v9.1.0 — October 6, 2026 ​

Added ​

Changed ​

Fixed ​

v9.0.0 — September 28, 2026 ​

Added ​

Changed ​

Fixed ​

Removed ​

v8.6.0 — September 25, 2026 ​

Changed ​

v8.5.0 — September 25, 2026 ​

Added ​

Changed ​

Fixed ​

Removed ​

v8.4.0 — September 24, 2026 ​

Added ​

Changed ​

Fixed ​

v8.3.0 — September 23, 2026 ​

Added ​

Changed ​

Fixed ​

v8.2.0 — September 21, 2026 ​

Added ​

Changed ​

Fixed ​

v8.1.0 — September 17, 2026 ​

Added ​

Changed ​

Fixed ​

Removed ​

v8.0.0 — September 14, 2026 ​

Added ​

Changed ​

Fixed ​

v7.9.0 — September 11, 2026 ​

Added ​

Changelog

v9.7.1 — November 14, 2026

Added

Changed

Fixed

v9.7.0 — October 23, 2026

Added

Changed

v9.6.4 — October 21, 2026

Fixed

v9.6.3 — October 21, 2026

Fixed

v9.6.2 — October 19, 2026

Fixed

v9.6.1 — October 17, 2026

Fixed

v9.6.0 — October 16, 2026

Added

Changed

Fixed

Added

Changed

Removed

v9.4.0 — October 10, 2026

Fixed

Added

Changed

v9.3.1 — October 10, 2026

Added

Changed

v9.3.0 — October 10, 2026

Added

Changed

Notes

v9.2.1 — October 10, 2026

Changed

v9.2.0 — October 7, 2026

Added

Changed

v9.1.1 — October 6, 2026

Fixed

v9.1.0 — October 6, 2026

Added

Changed

Fixed

v9.0.0 — September 28, 2026

Added

Changed

Fixed

Removed

v8.6.0 — September 25, 2026

Changed

v8.5.0 — September 25, 2026

Added

Changed

Fixed

Removed

v8.4.0 — September 24, 2026

Added

Changed

Fixed

v8.3.0 — September 23, 2026

Added

Changed

Fixed

v8.2.0 — September 21, 2026

Added

Changed

Fixed

v8.1.0 — September 17, 2026

Added

Changed

Fixed

Removed

v8.0.0 — September 14, 2026

Added

Changed

Fixed

v7.9.0 — September 11, 2026

Added