> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_03/prd_phase_03.md).

# PRD Phase 03: Agent Orchestration

**Status**: Complete **Sessions**: 7 **Estimated Duration**: 7-14 days

**Progress**: 7/7 sessions (100%)

***

## Overview

Phase 03 turns the shipped observability runtime into a local-first agent orchestration layer. It defines and implements task queues, agent templates, subagent lineage, guarded local action proposals, web cockpit orchestration controls, and CLI diagnostics while preserving the privacy and permission boundaries established in Phases 01 and 02.

This phase does not wire web-to-Worker War Room federation, hosted collaboration, inbound chat commands, public replay hosting, analytics, broad remote execution, Docker isolation, or final legacy decommission gates.

***

## Progress Tracker

| Session | Name                                                | Status    | Est. Tasks | Validated |
| ------- | --------------------------------------------------- | --------- | ---------- | --------- |
| 01      | Orchestration Requirements and Safety Baseline      | Completed | \~14-18    | PASS      |
| 02      | Task Queue and Agent Template Contracts             | Completed | \~16-22    | PASS      |
| 03      | Subagent Lineage and Mission Graph Runtime          | Completed | \~18-24    | PASS      |
| 04      | Guarded Local Action Runtime                        | Completed | \~18-24    | PASS      |
| 05      | Web Orchestration Cockpit Controls                  | Completed | \~16-24    | PASS      |
| 06      | CLI Diagnostics and Recovery Controls               | Completed | \~14-20    | PASS      |
| 07      | Orchestration Validation and Documentation Closeout | Completed | \~12-18    | PASS      |

***

## Completed Sessions

1. Session 01: Orchestration Requirements and Safety Baseline
2. Session 02: Task Queue and Agent Template Contracts
3. Session 03: Subagent Lineage and Mission Graph Runtime
4. Session 04: Guarded Local Action Runtime
5. Session 05: Web Orchestration Cockpit Controls
6. Session 06: CLI Diagnostics and Recovery Controls
7. Session 07: Orchestration Validation and Documentation Closeout

***

## Upcoming Sessions

None for Phase 03. Phase transition workflow follows.

***

## Objectives

1. Define a source-backed local orchestration contract for queues, templates, subagents, and guarded actions.
2. Promote orchestration shapes through `packages/protocol` before wiring server, hooks, CLI, or web behavior.
3. Provide explicit, permission-aware controls for spawn, resume, stop, fork, handoff, queue, and local action workflows.
4. Keep prompts, paths, commands, terminal output, transcripts, local state, and replay data bounded and redacted.
5. Validate Phase 03 behavior with focused tests, browser evidence where UI changes land, and stable documentation.

***

## Prerequisites

* Phase 02 completed.
* Stable Phase 01 local runtime contracts remain the implementation baseline.
* Phase 02 browser surface and public demo boundaries remain documented.
* `EXAMPLES/` remains evidence only and must not be copied into runtime code.

***

## Technical Considerations

### Architecture

Protocol contracts lead this phase. Queue, template, subagent, action proposal, and orchestration state shapes should start in `packages/protocol`, then flow through `apps/server`, `apps/hooks`, `apps/cli`, and `apps/web`. Local server authorization, WebSocket origin checks, rate limits, redaction, and explicit unsupported-route behavior remain release-critical defaults.

### Technologies

* TypeScript protocol contracts in `packages/protocol`
* Express, WebSocket, and in-memory managers in `apps/server`
* Dependency-light Claude Code hook handlers in `apps/hooks`
* Node built-ins and local state helpers in `apps/cli`
* React 18, Vite, TypeScript, Tailwind, and Zustand in `apps/web`
* Vitest, Testing Library, Playwright, Biome, and npm workspace scripts

### Risks

* Scope bleed: keep War Room federation, hosted collaboration, inbound chat commands, public sharing, and analytics out of Phase 03.
* Command safety: orchestration actions must be proposals or explicitly approved local actions, not hidden remote control.
* Privacy drift: prompts, paths, commands, transcripts, and terminal output need redaction before display, export, replay, or adapter transfer.
* Protocol drift: duplicating queue or action shapes inside app packages will make later collaboration work harder.
* Historical parity pressure: use historical files only as traceability evidence, not as runtime authority.

### Relevant Considerations

* \[P01] **Redaction is boundary-specific**: future orchestration, hosted, and sharing work must reuse the existing privacy posture before external transfer.
* \[P01-apps/server] **Local server boundary must stay conservative**: loopback bind, non-loopback opt-in, CORS allowlists, optional auth token, WebSocket origin checks, request validation, and explicit 501s stay default.
* \[P01-packages/protocol] **Protocol leads cross-package work**: add or change shared event, REST, WebSocket, and domain types before wiring app behavior.
* \[P01-apps/warroom+apps/web] **War Room is not wired into the web runtime yet**: keep Phase 03 orchestration local and do not imply room federation.
* \[P01] **Unified erasure still missing**: orchestration state should be easy to include in later trusted reset and erasure workflows.

***

## Success Criteria

Phase complete when:

* [x] All 7 sessions completed.
* [x] Queue, template, subagent, and guarded-action contracts are represented in protocol types and stable docs.
* [x] Local server orchestration routes and WebSocket frames are validated, bounded, and protected by existing local security defaults.
* [x] Hook and CLI orchestration flows degrade cleanly when the server, listener, or local state is unavailable.
* [x] Web orchestration controls expose clear pending, accepted, rejected, unavailable, and failed states without implying hosted collaboration.
* [x] Stable docs identify shipped Phase 03 behavior and keep Phase 04-08 scope deferred.

***

## Dependencies

### Depends On

* Phase 02: Product Surface and 2D Battlefield Completion

### Enables

* Phase 04: Media Catalog and Audio/Visual Pipeline
* Phase 05: War Room Worker Integration


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_03/prd_phase_03.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.