{
  "id": "2026-04-21-orchestration-design-86732c4244",
  "scope": "redkey",
  "source_of_truth": "repo",
  "source_path": "docs/specs/2026-04-21-orchestration-design.md",
  "source_kind": "markdown",
  "visibility": "internal",
  "renderer_id": "design_doc.dreamborn-forge.generated.v1",
  "design_system": "dreamborn-design-system:forge",
  "generated_at": "2026-05-09T13:00:55.657Z",
  "artifact_type": "design_doc",
  "schema_version": "design_doc.generated.v1",
  "title": "Orchestration Design",
  "summary": "Orchestration Design Date: 2026 04 21 Status: Approved What This Covers The orchestration layer for CCOS2 — how work enters the system, how it gets routed, how it gets decomposed, and what templates govern each type of work. Dev templates are fully defined here. Other department templates are deferred pending further design sessions. Orchestration Hierarchy ...",
  "format_source": "markdown",
  "sections": [
    {
      "title": "Orchestration Design",
      "level": 1,
      "body": "**Date:** 2026-04-21\n**Status:** Approved\n\n---"
    },
    {
      "title": "What This Covers",
      "level": 2,
      "body": "The orchestration layer for CCOS2 — how work enters the system, how it gets routed, how it gets decomposed, and what templates govern each type of work. Dev templates are fully defined here. Other department templates are deferred pending further design sessions.\n\n---"
    },
    {
      "title": "Orchestration Hierarchy",
      "level": 2,
      "body": "Three tiers:\n\n```\nCOO (future)        — cross-department DAG coordination, parallel workstream management\n  └── Claire        — department-level routing, template selection, decomposition, brief validation\n        └── Workers — execute one step, post result, know nothing about the workflow\n```\n\n**COO** is future-state. When cross-department projects need dependency tracking across departments, the COO decomposes them and posts department-scoped tasks to `roles.orchestrator`. Claire handles everything within a department.\n\n**Claire** is active now. She pulls from `roles.orchestrator`, validates the brief, selects the template, assesses size, decomposes if needed, and dispatches work to role topics. She is the only agent that advances workflow state.\n\n---"
    },
    {
      "title": "Department Taxonomy",
      "level": 2,
      "body": "Five departments. Each owns a set of roles. Agents fill roles — Justin fills exec roles today; other departments have dedicated agents (current or planned).\n\n| Department | Roles |\n|---|---|\n| dev | `ba`, `developer`, `reviewer`, `architect` |\n| sales_and_marketing | `bdr`, `sales`, `customer_success`, `content`, `designer`, `podcast` |\n| governance | `finance`, `legal` |\n| knowledge | `researcher`, `librarian` |\n| exec | `justin`, `coo` (future) |\n\n---"
    },
    {
      "title": "Project Payload Schema",
      "level": 2,
      "body": "Work arrives on `roles.orchestrator` as a `task.available` message:\n\n```json\n{\n  \"type\": \"task.available\",\n  \"task_id\": \"uuid\",\n  \"department\": \"dev\",\n  \"work_type\": \"dev_task\",\n  \"brief\": \"...\",\n  \"priority\": \"low | normal | high | urgent\",\n  \"depends_on\": [],\n  \"posted_at\": \"ISO8601\"\n}\n```\n\n- `department` + `work_type` together select the template. Claire does not infer either.\n- `depends_on` is optional. Array of `task_id`s that must complete before this task dispatches.\n- `priority` flows through to all sub-tasks Claire creates.\n- Cross-department projects arrive as multiple messages — one per department, each with their own `depends_on` if sequencing is needed.\n\n---"
    },
    {
      "title": "Brief Quality Requirements",
      "level": 2,
      "body": "Claire validates the brief before dispatching to brainstorm. She checks for **presence only** — not quality. Missing fields block the task and route to `justin` for completion.\n\n| work_type | Required fields |\n|---|---|\n| `hotfix` | What is broken, what done looks like |\n| `dev_task` | Goals, who it serves |\n| `initiative` | Goals, who it serves, timeline, context |\n\nValidation is inline behavior — not a formal template step. If the brief passes, Claire dispatches. If not, she posts to `justin` with the specific missing fields.\n\n**Brainstorm handles quality.** Claire only checks presence. If a stated goal is vague or a timeline is unrealistic, brainstorm surfaces that — not Claire.\n\n---"
    },
    {
      "title": "hotfix",
      "level": 3,
      "body": "Single isolated bug fix. No spec, no architect.\n\n| Step | Role |\n|---|---|\n| 1. brainstorm | `ba` |\n| 2. code | `developer` |\n| 3. pr | `developer` |\n| 4. review | `reviewer` |"
    },
    {
      "title": "dev_task",
      "level": 3,
      "body": "Standard feature or improvement.\n\n| Step | Role |\n|---|---|\n| 1. brainstorm | `ba` |\n| 2. spec | `ba` |\n| 3. arch | `architect` |\n| 4. code | `developer` |\n| 5. pr | `developer` |\n| 6. review | `reviewer` |"
    },
    {
      "title": "initiative",
      "level": 3,
      "body": "Multi-phase project. Claire decomposes into phases after arch completes.\n\n| Step | Role |\n|---|---|\n| 1. brainstorm | `ba` |\n| 2. arch | `architect` |\n| 3. decompose | Claire (inline) |\n| 4+ | Each phase = `dev_task` workflow |\n\n**Phase rules:**\n- Each phase is a full `dev_task` (brainstorm → spec → arch → code → pr → review)\n- Phases declare `depends_on` other phases\n- Claire dispatches phases as their dependencies resolve — parallel where possible, sequential where declared\n- Phases are the unit of dependency, not individual steps\n\n---"
    },
    {
      "title": "Template JSON Schema",
      "level": 2,
      "body": "```json\n{\n  \"slug\": \"dev_task\",\n  \"name\": \"Dev Task\",\n  \"department\": \"dev\",\n  \"description\": \"Standard feature: brainstorm → spec → arch → code → pr → review\",\n  \"steps\": [\n    { \"step_num\": 1, \"name\": \"brainstorm\", \"role\": \"ba\" },\n    { \"step_num\": 2, \"name\": \"spec\",       \"role\": \"ba\" },\n    { \"step_num\": 3, \"name\": \"arch\",       \"role\": \"architect\" },\n    { \"step_num\": 4, \"name\": \"code\",       \"role\": \"developer\" },\n    { \"step_num\": 5, \"name\": \"pr\",         \"role\": \"developer\" },\n    { \"step_num\": 6, \"name\": \"review\",     \"role\": \"reviewer\" }\n  ]\n}\n```\n\n---"
    },
    {
      "title": "Deferred: Non-Dev Templates",
      "level": 2,
      "body": "Templates for `sales_and_marketing`, `governance`, and `knowledge` are not defined here. Each department has distinct workflows that require more detailed design. These will be addressed in a follow-up session with voice access.\n\nDepartments and roles are defined above — implementation can proceed with dev templates and the full department/role topology. Non-dev templates slot in when ready without any structural changes.\n\n---"
    },
    {
      "title": "Open Items",
      "level": 2,
      "body": "- [ ] Define `sales_and_marketing` templates: `bdr`, `sales`, `customer_success`, `content`, `design`, `podcast`\n- [ ] Define `governance` templates: `finance`, `legal`\n- [ ] Define `knowledge` templates: `research`, `library`\n- [ ] Design COO agent and its relationship to Claire\n- [ ] Define `exec` role topic and escalation pattern"
    }
  ],
  "html_path": "artifacts/2026-04-21-orchestration-design-86732c4244.html",
  "json_path": "artifacts/2026-04-21-orchestration-design-86732c4244.json"
}