<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/architecture/multi-agent-orchestration/">
  <id>https://docs.spec-kitty.ai/architecture/multi-agent-orchestration/</id>
  <title>Multi-Agent Orchestration</title>
  <updated>2026-09-30T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/architecture/multi-agent-orchestration/"/>
  <summary>Coordination model for multi-agent delivery with a host-owned workflow state and external orchestration providers.</summary>
  <content type="html">&lt;span id=&quot;multi-agent-orchestration&quot;&gt;&lt;/span&gt;
&lt;p&gt;Spec Kitty supports multi-agent delivery through a host/provider split:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; owns workflow state, lane validation, and git-safe mutations.&lt;/li&gt;
&lt;li&gt;external providers such as &lt;code dir=&quot;auto&quot;&gt;spec-kitty-orchestrator&lt;/code&gt; run agents and call
&lt;code dir=&quot;auto&quot;&gt;spec-kitty orchestrator-api&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This replaces in-core orchestration commands. The core CLI does not provide &lt;code dir=&quot;auto&quot;&gt;spec-kitty orchestrate&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;why-this-model-exists&quot;&gt;Why this model exists&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Security boundary: autonomous orchestration is optional and can be disallowed by policy.&lt;/li&gt;
&lt;li&gt;Extensibility: multiple provider strategies can exist without branching core CLI behavior.&lt;/li&gt;
&lt;li&gt;Operational clarity: one host contract for state transitions and lifecycle events.&lt;/li&gt;
&lt;li&gt;Review independence: one agent can implement while a different agent reviews
without either agent owning the mission state machine.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;core-principles&quot;&gt;Core Principles&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Planning in main, implementation in worktrees.&lt;/li&gt;
&lt;li&gt;One worktree per WP.&lt;/li&gt;
&lt;li&gt;Lane transitions validated by the host state model.&lt;/li&gt;
&lt;li&gt;External providers drive automation through API calls, not direct file edits.&lt;/li&gt;
&lt;li&gt;Activity logs and run state are audit artifacts, not the source of truth.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;two-orchestration-styles&quot;&gt;Two orchestration styles&lt;/h2&gt;
&lt;h3 id=&quot;1-manual-human--or-agent-driven&quot;&gt;1) Manual (human- or agent-driven)&lt;/h3&gt;
&lt;p&gt;Manual coordination still works via normal commands:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;next&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;agent&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;&amp;#x3C;slug&gt;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# Your agent calls: spec-kitty agent action implement WP01 --agent &amp;#x3C;name&gt;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tasks&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;move-task&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP01&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--to&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;for_review&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;tasks&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;move-task&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;WP01&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--to&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;done&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;2-external-automated-orchestration&quot;&gt;2) External automated orchestration&lt;/h3&gt;
&lt;p&gt;Automated coordination is run by external providers such as &lt;code dir=&quot;auto&quot;&gt;spec-kitty-orchestrator&lt;/code&gt;.
Use a provider build that explicitly supports the current host API. The PyPI
&lt;code dir=&quot;auto&quot;&gt;spec-kitty-orchestrator&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;0.1.0&lt;/code&gt; release appends &lt;code dir=&quot;auto&quot;&gt;--json&lt;/code&gt; to host API calls
and is not compatible with current hosts.&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;orchestrator-api&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;contract-version&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty-orchestrator&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;orchestrate&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;034-my-feature&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--dry-run&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty-orchestrator&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;orchestrate&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;034-my-feature&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Host-compatible provider loop responsibilities:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Discover ready WPs via host API.&lt;/li&gt;
&lt;li&gt;Start implementation, prepare usable worktrees, and run agents there.&lt;/li&gt;
&lt;li&gt;Transition WPs through review cycles.&lt;/li&gt;
&lt;li&gt;Accept when WPs are accepted-ready (&lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;), then merge.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;The common local pattern is:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;spec-kitty-orchestrator&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;orchestrate&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--mission&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;034-my-feature&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--impl-agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;claude-code&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--review-agent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;codex&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;\&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--max-concurrent&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;1&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;That means Claude Code receives the WP prompt and writes the implementation;
Codex receives the same WP context after implementation and acts as reviewer.
The host, not either agent, decides which lane transitions are legal.&lt;/p&gt;
&lt;h2 id=&quot;host-api-boundary&quot;&gt;Host API boundary&lt;/h2&gt;
&lt;p&gt;All state-changing automation calls flow through &lt;code dir=&quot;auto&quot;&gt;spec-kitty orchestrator-api&lt;/code&gt;.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;start-implementation&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;start-review&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;transition&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;append-history&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;accept-mission&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;merge-mission&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The host returns a stable JSON envelope with &lt;code dir=&quot;auto&quot;&gt;success&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;error_code&lt;/code&gt; for deterministic provider control flow.&lt;/p&gt;
&lt;p&gt;The provider can be replaced. The boundary cannot. A custom orchestrator may
use a different scheduler, model router, queue, or CI runner, but it still must
call the same host API.&lt;/p&gt;
&lt;h2 id=&quot;lane-semantics&quot;&gt;Lane semantics&lt;/h2&gt;
&lt;p&gt;Public API lanes:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;blocked&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;canceled&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Compatibility mapping:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;API &lt;code dir=&quot;auto&quot;&gt;in_progress&lt;/code&gt; maps to internal &lt;code dir=&quot;auto&quot;&gt;doing&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;planned&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;for_review&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;in_review&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;approved&lt;/code&gt;, and &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; map directly.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Current host review flow is:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;in_progress -&gt; for_review -&gt; in_review -&gt; done&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;A rejected review moves back to implementation:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;text&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;in_review -&gt; in_progress -&gt; for_review&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Providers should preserve a review reference for both approval and rejection so
humans can trace why a WP moved.&lt;/p&gt;
&lt;h2 id=&quot;worktrees-and-protected-branches&quot;&gt;Worktrees and Protected Branches&lt;/h2&gt;
&lt;p&gt;The orchestrator model assumes protected branches stay clean:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;mission planning artifacts live on the main project branch&lt;/li&gt;
&lt;li&gt;implementation runs in WP worktrees&lt;/li&gt;
&lt;li&gt;provider state lives under &lt;code dir=&quot;auto&quot;&gt;.kittify/&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;host lane events are appended by the host API&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This matters because activity-log updates may be committed by the host. A
provider that invokes mutation commands directly from protected &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt; can hit
branch-protection errors. A compatible provider must create or reuse the
mission and WP worktrees before mutating state or spawning agents.&lt;/p&gt;
&lt;h2 id=&quot;policy-metadata-and-mutation-authority&quot;&gt;Policy metadata and mutation authority&lt;/h2&gt;
&lt;p&gt;Run-affecting operations require policy metadata (&lt;code dir=&quot;auto&quot;&gt;--policy&lt;/code&gt;) and are validated by the host.&lt;/p&gt;
&lt;p&gt;This ensures:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;identity and mode are explicit for each mutation&lt;/li&gt;
&lt;li&gt;malformed or secret-like policy payloads are rejected&lt;/li&gt;
&lt;li&gt;orchestrators cannot bypass host transition rules&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;what-this-means-for-teams&quot;&gt;What this means for teams&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Teams that want full automation can run an external provider.&lt;/li&gt;
&lt;li&gt;Teams with strict security constraints can keep orchestration manual.&lt;/li&gt;
&lt;li&gt;Teams can build custom providers while preserving a consistent workflow model.&lt;/li&gt;
&lt;li&gt;Teams can test automation safely with deterministic fake-agent e2e before
enabling real agent CLIs on a trusted machine.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;see-also&quot;&gt;See Also&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/guides/tutorials/orchestrator-quickstart/&quot;&gt;Orchestrator Quickstart&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/collaboration/run-external-orchestrator/&quot;&gt;Run the External Orchestrator&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/guides/how-to/collaboration/build-custom-orchestrator/&quot;&gt;Build a Custom Orchestrator&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/api/orchestrator-api/&quot;&gt;Orchestrator API Reference&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/architecture/kanban-workflow/&quot;&gt;Kanban Workflow&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
