From 97a589e9b0b939381ad52cf2d47c917c10d48ee6 Mon Sep 17 00:00:00 2001 From: NagyVikt Date: Thu, 14 May 2026 12:23:24 +0200 Subject: [PATCH] Import Symphony reference context --- docs/external/README.md | 12 +++++++++ openspec/specs/colony-symphony/context.md | 30 +++++++++++++++++++++++ 2 files changed, 42 insertions(+) diff --git a/docs/external/README.md b/docs/external/README.md index 215ead5..f0a1c47 100644 --- a/docs/external/README.md +++ b/docs/external/README.md @@ -8,3 +8,15 @@ only. Do not vendor Symphony reference implementation code into this repository. Keep external source code read-only and cite the canonical spec path instead. + +Imported context lives in `openspec/specs/colony-symphony/context.md`. That +context paraphrases the source SPEC anchors needed by Colony agents and records +which future OpenSpec lanes own normative requirements. + +Use these source boundaries when adding or reviewing Symphony adoption work: + +- Treat `examples/symphony/SPEC.md` as normative for source intent. +- Treat `examples/symphony/README.md` as non-normative orientation. +- Do not copy upstream Elixir implementation files into Colony paths. +- Map tracker behavior onto Colony task and plan state unless a later + extension explicitly claims another tracker adapter. diff --git a/openspec/specs/colony-symphony/context.md b/openspec/specs/colony-symphony/context.md index 64910ba..d255b7c 100644 --- a/openspec/specs/colony-symphony/context.md +++ b/openspec/specs/colony-symphony/context.md @@ -30,6 +30,36 @@ Normative requirements, behavior deltas, and change proposals are intentionally out of scope here. Agent 202 owns the change proposal that will decide which Symphony patterns become Colony requirements. +## Reference Import Summary + +Symphony's source spec defines a long-running scheduler/runner service that +polls an issue tracker, prepares isolated per-issue workspaces, and starts a +coding-agent session for each eligible issue. The service is intentionally not a +tracker writer: issue comments, PR links, and state transitions remain workflow +or agent-tool responsibilities unless a later Colony change explicitly adds a +write contract. + +The first three source sections import into Colony as orientation, not as +requirements: + +- Section 1 frames the operational problems: repeatable daemon execution, + per-issue workspace isolation, repo-owned workflow policy in `WORKFLOW.md`, + and enough observability to debug concurrent agent runs. +- Section 2 defines the high-level goals: bounded-concurrency polling, a single + authoritative orchestrator state, deterministic workspaces, state-change stop + behavior, retry recovery, workflow loading, structured visibility, and restart + recovery from tracker/filesystem state. +- Section 2 also keeps rich UI, a general workflow engine, built-in ticket edit + policy, and a universal sandbox posture out of core scope. +- Section 3 decomposes the system into workflow loading, typed config, issue + intake, orchestration, workspace management, agent running, optional status + display, and structured logging. + +The supporting README positions Symphony as an engineering preview for trusted +environments and points implementers to the SPEC as the source of truth. Colony +adoption should therefore cite the SPEC for behavior and keep the README as +non-normative product orientation. + ## Mapping Anchors | Adoption phase | Symphony SPEC anchor |