docs(symphony): add package README and fork value-add banner#1510
Closed
Ddell12 wants to merge 12 commits intocoleam00:devfrom
Closed
docs(symphony): add package README and fork value-add banner#1510Ddell12 wants to merge 12 commits intocoleam00:devfrom
Ddell12 wants to merge 12 commits intocoleam00:devfrom
Conversation
Phase 1 of the archon-symphony consolidation
(see Ddell12/symphoney-codex docs/superpowers/plans/2026-04-30-archon-symphony-consolidation.md).
Adds an empty-but-buildable @archon/symphony workspace package and the
DB schema needed for Phase 2's orchestrator port. No runtime behavior
yet — Phase 2 will land the tracker + orchestrator + dispatch loop.
What's in this commit:
* packages/symphony/{package.json,tsconfig.json,src/index.ts} — new
workspace package mirroring packages/git's shape. Deps: @archon/core,
@archon/paths.
* migrations/022_symphony_dispatches.sql — PostgreSQL migration adding
symphony_dispatches table. UUID FKs to remote_agent_codebases and
remote_agent_workflow_runs. Indexes on (tracker, issue_id), identifier,
workflow_run_id, codebase_id. dispatch_key UNIQUE so the same raw issue
id from two trackers (e.g. Linear + GitHub) cannot collide.
* migrations/000_combined.sql — append symphony_dispatches table to the
fresh-postgres bootstrap snapshot.
* packages/core/src/db/adapters/sqlite.ts — add SQLite-equivalent
symphony_dispatches table + indexes inside createSchema(). Uses TEXT
IDs / datetime('now') per existing SQLite convention.
* packages/symphony/src/db/dispatches.ts — typed CRUD: insertDispatch,
getDispatchByDispatchKey, getDispatchById, updateStatus,
attachWorkflowRun. Functions accept IDatabase explicitly so tests pass
a fresh SqliteAdapter against a temp file (Phase 2 will switch to the
pool singleton at call sites).
* packages/symphony/src/db/dispatches.test.ts — 8 round-trip tests
against real SQLite: insert/get, dispatch_key UNIQUE, multi-tracker
non-collision, updateStatus mutation, attachWorkflowRun idempotency,
conflict rejection, and missing-id error path.
Verification:
bun install && bun run validate
(= check:bundled && type-check && lint --max-warnings 0 && format:check && test)
All 11 packages green. New @archon/symphony package contributes 8
passing tests. No regressions in @archon/core's SQLite adapter tests.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Phase 1: scaffold packages/symphony
Captures `Ddell12/symphoney-codex` as of 2026-04-30 before that repo is
archived (Phase 5 of the consolidation plan). Phase 2-4 port code from
this snapshot into packages/symphony/; once Phase 5 lands and
symphoney-codex is deleted, this directory becomes the only remaining
record of the pre-fork standalone Symphony daemon.
Contents (69 files / 664K):
* Master plan: docs/symphoney-legacy/plans/2026-04-30-archon-symphony-consolidation.md
* Incident report: docs/symphoney-legacy/incidents/2026-04-30-app-273-data-loss.md
(Phase 0 reconcile-terminal data-loss bug fixed in symphoney-codex
commit fa70be2, dogfood-verified APP-291)
* Spec + config: SPEC.md (canonical OpenAI Symphony spec), WORKFLOW.md
(production daemon config — source for ~/.archon/symphony.yaml in
Phase 2), WORKFLOW.example.md, PARITY_REPORT.md, ROADMAP.md,
WEB_GAPS.md, PRD.md
* Architecture reference: CLAUDE.md, symphoney-readme.md
* Source snapshot: src/ (34 .ts files — orchestrator, tracker, config,
publisher, agent, server, workspace)
* Test snapshot: test/ (21 .ts files — unit + integration patterns to
port to bun:test in Phase 2)
* Smoke scripts: scripts/{smoke-claude,smoke-linear-graphql}.ts
NOT copied: node_modules/, dist/, web/ (retired in Phase 5),
package.json/tsconfig.json/vitest.config.ts (pnpm/Vitest mechanics —
archon uses Bun), bin/ (symphoney CLI binary), .env (credentials).
eslint.config.mjs: added 'docs/**' to global ignores so the legacy code
is not linted (it uses different conventions: ESM `.js` import suffixes,
verbatimModuleSyntax off, vitest, etc.). Prettier already ignored docs/
via .prettierignore so format:check is unaffected.
Verification: bun run validate green across all 11 packages. The new
docs/symphoney-legacy/ directory adds no runtime code, no tests, and
no lint surface.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
docs: snapshot symphoney-codex under docs/symphoney-legacy/
Lands the Phase 2 deliverable from
docs/symphoney-legacy/plans/2026-04-30-archon-symphony-consolidation.md.
- Linear + GitHub trackers behind a shared Tracker interface
- Orchestrator with tick loop, slot accounting, per-state caps,
retry backoff. Re-keyed all in-memory state on dispatch_key
('<tracker>:<identifier>') so cross-tracker raw-id collisions
are impossible.
- Config snapshot rewrite: trackers as a list, no agent/codex/claude
blocks (those move to per-workflow YAML in Archon proper).
~/.archon/symphony.yaml.example committed under packages/symphony/.
- dispatchIssue stub: writes a symphony_dispatches row with
workflow_run_id = null and logs symphony.dispatch_skipped. Phase 3
replaces the stub with executeWorkflow.
- Unit + integration tests, including a multi-tracker fixture
(same raw id on Linear and GitHub -> distinct dispatch_keys, both
dispatch, no UNIQUE violation). 41 symphony tests, 0 fail.
- New CLI dev entrypoint: bun packages/symphony/src/cli/dev.ts.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…secrets
The Phase 2 manual smoke surfaced this: symphony.yaml.example uses
$LINEAR_PROJECT_SLUG, $GH_OWNER, $GH_REPO, but only $api_key and $token
were resolved through env-indirection. Non-secret fields were passed
literally to the underlying SDKs ('$LINEAR_PROJECT_SLUG' as a slug → 0
candidates with no error).
Threads `resolveEnvIndirection` (renamed locally to `resolveString`) through
every string field in `buildTracker` and `buildCodebases`: project_slug,
endpoint, repository (Linear), owner, repo (GitHub), and codebase_id /
repository (codebases). Behavior for hardcoded literals is unchanged —
`resolveEnvIndirection` returns the trimmed input when the value is not a
$VAR pattern.
Two new tests in snapshot.test.ts cover the $VAR-everywhere case and the
"env var unset → fall back to default/null" case.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
feat(symphony): port tracker + orchestrator (dispatch stubbed)
Phase 3 of the archon-symphony consolidation. Replaces the Phase 2 stub
dispatchIssue (which only logged and wrote workflow_run_id=NULL rows)
with a full launch path through Archon's existing workflow executor,
isolation resolver, and provider stack.
Sequence per Symphony dispatch:
- Hard-fail when no codebase is mapped (writes a status='failed' row,
no retry — config error per CLAUDE.md fail-fast).
- Resolve workflow definition via discoverWorkflowsWithConfig against
the codebase's default_cwd (home-scoped + project-scoped + bundled).
- Create a hidden web worker conversation, resolve a real worktree via
validateAndResolveIsolation.
- Pre-create the workflow_run row through createWorkflowDeps().store,
attach its id to symphony_dispatches before launch.
- Fire executeWorkflow(...) (fire-and-forget); terminal status comes
back through getWorkflowEventEmitter() — orchestrator subscribes once
in start() and translates workflow_completed / failed / cancelled
into DB updateStatus + state mutations + retry on failure.
Server bootstrap auto-boots the Symphony service when ~/.archon/
symphony.yaml exists (silent no-op otherwise). Adds
/api/symphony/{state, dispatches, dispatches/:id, dispatch, cancel,
refresh} via OpenAPIHono with Zod-validated request/response schemas.
Service is awaited in graceful shutdown before pool close.
reconcileOnStart() reads upstream workflow_run_status for in-flight
symphony_dispatches rows so a process crash mid-dispatch doesn't
lose terminal-state writes — never marks non-terminal upstream runs
failed by timer (CLAUDE.md "No Autonomous Lifecycle Mutation"
compliance).
Verified end-to-end via the Symphony Smoke Linear project: APP-293
created in Todo, polled within ~2s, dispatched to e2e-deterministic
(bash + bun + uv/Python script DAG with conditions and trigger_rule
joins), workflow ran in a real worktree under
~/.archon/workspaces/Ddell12/Cowork/worktrees/archon/, terminal event
landed on the orchestrator, both symphony_dispatches.status='completed'
and remote_agent_workflow_runs.status='completed' written.
Test coverage: 18 new tests across dispatcher.test.ts (5),
terminal-events.test.ts (5), reconcile.test.ts (4), plus 4 new
dispatches DB helper tests. Existing dispatch-loop and multi-tracker
tests rewritten to assert the real Phase 3 lifecycle. 61 symphony
tests pass (was 41 in Phase 2). Full repo `bun run validate` clean.
Phase 3 of docs/symphoney-legacy/plans/2026-04-30-archon-symphony-consolidation.md
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
feat(symphony): bridge dispatch to Archon workflow runs (Phase 3)
Adds /symphony route to @archon/web that renders the Symphony orchestrator's running, retrying, and historical dispatches as a kanban board on top of Phase 3's /api/symphony/* surface. Cards group by lifecycle (default), tracker state, or repository, poll every 5s via TanStack Query, and deep-link each workflow_run_id into Archon's existing /workflows/runs/:runId page. Includes typed client + transform utilities (cards keyed by dispatch_key, with live-state-wins dedup against stale terminal dispatch rows), bun-test coverage for transform/group/client, and Inbox icon nav entry between Workflows and Settings. Types are sourced from packages/web/src/lib/api.generated.d.ts after regenerating against a server with ~/.archon/symphony.yaml present. Phase 4 of the archon-symphony consolidation (docs/symphoney-legacy/plans/2026-04-30-archon-symphony-consolidation.md). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
feat(web): symphony kanban page with workflow-run drill-through
Phase 5 of the archon-symphony consolidation (docs/symphoney-legacy/plans/2026-04-30-archon-symphony-consolidation.md). - packages/symphony/README.md: setup, codebase mapping, startup, /symphony kanban location, /api/symphony/* endpoint table, parity- with-spec note, and migration notes for users coming from the standalone symphoney-codex repo. - root README.md: short banner after the badges identifying this as Ddell12/archon-symphony and pointing at the package README; upstream Archon content preserved verbatim below. No code or schema changes. Documentation only. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Author
|
Mistargeted — meant for the fork Ddell12/archon-symphony, not upstream. Closing. (Phase 5 of internal archon-symphony consolidation; not relevant to coleam00/Archon.) |
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (126)
📝 WalkthroughWalkthroughA comprehensive Symphony orchestrator is integrated into Archon, enabling poll-based issue dispatch to workflows across Linear and GitHub trackers. The addition includes orchestrator, tracker adapters, database persistence, workflow bridge integration, web UI, and extensive legacy documentation from the prior standalone daemon. Changes
Sequence Diagram(s)sequenceDiagram
participant OrchestratorLoop as Orchestrator Tick
participant Tracker
participant DB as Dispatch DB
participant Bridge as Workflow Bridge
participant WorkflowStore as Workflow Store
OrchestratorLoop->>Tracker: fetchCandidateIssues()
Tracker-->>OrchestratorLoop: Issue[]
OrchestratorLoop->>OrchestratorLoop: Filter by eligibility<br/>(state, capacity, blockers)
loop For each eligible issue
OrchestratorLoop->>DB: insertDispatch(pending)
DB-->>OrchestratorLoop: DispatchRow
OrchestratorLoop->>Bridge: dispatchToWorkflow()
Bridge->>WorkflowStore: resolveWorkflow()
WorkflowStore-->>Bridge: WorkflowDefinition
Bridge->>WorkflowStore: createWorkerConversation()
WorkflowStore-->>Bridge: ConversationId
Bridge->>WorkflowStore: createWorkflowRun()
WorkflowStore-->>Bridge: WorkflowRunId
Bridge->>DB: attachWorkflowRun(dispatch, runId)
DB-->>Bridge: success
Bridge->>WorkflowStore: executeWorkflow()
WorkflowStore-->>Bridge: Promise<WorkflowExecutionResult>
end
OrchestratorLoop->>OrchestratorLoop: Schedule next tick
Estimated code review effort🎯 5 (Critical) | ⏱️ ~120 minutes Rationale: This is a substantial, multi-package architectural addition introducing a new orchestrator subsystem with orchestration logic, multiple tracker implementations, database persistence, workflow bridge integration, server routing, and web UI—totaling ~7,700 lines of production code and ~4,000 lines of tests across heterogeneous components (config parsing, orchestration state machines, tracker GraphQL/REST clients, bridge orchestration, database operations, React components). The changes span the entire stack (backend service, database, HTTP API, web UI) with complex interdependencies and non-trivial control flow (dispatch eligibility, retry backoff, terminal event reconciliation). Although the legacy documentation is large, the production code density and architectural scope demand careful review of orchestrator correctness, state management, tracker implementation details, bridge integration contracts, and data consistency across multiple subsystems. Possibly related PRs
Suggested reviewers
✨ Finishing Touches🧪 Generate unit tests (beta)
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
packages/symphony/runtime config.symphoney-codex/web/. Without these READMEs, anyone arriving at the fork sees only the upstream Archon README and an undocumentedpackages/symphony/directory.packages/symphony/README.md(setup, codebase mapping, startup,/api/symphony/*table, parity-with-spec note, migration notes) and inserts a short fork-distinction banner in the root README./release minorafter Phase 5 lands). The legacysymphoney-codexretirement is in a separate PR against that repo.UX Journey
Before
After
Architecture Diagram
Before
No code-level architecture in this PR. Documentation only.
After
Same diagram. Marked:
[+] README.md (root banner block),[+] packages/symphony/README.md.Connection inventory: None — this is a docs-only change. Cross-references inside the new README point at existing files (
packages/symphony/symphony.yaml.example,packages/symphony/src/index.ts,packages/server/src/routes/api.symphony.ts,packages/web/src/routes/SymphonyPage.tsx,docs/symphoney-legacy/PARITY_REPORT.md).Label Snapshot
risk: lowsize: Sdocsdocs:symphonyChange Metadata
docsmulti(root README + packages/symphony)Linked Issue
docs/symphoney-legacy/plans/2026-04-30-archon-symphony-consolidation.md)devValidation Evidence (required)
bun run validateis non-zero ondevitself due to 3 pre-existing@archon/workflowsDAG loader failures (cycle-detection / inline prompt / unknown-top-level-fields). Documented in~/.claude/projects/-Users-desha-archon-symphony/memory/dag-loader-test-failures.md. This PR does not touch the workflows package.Security Impact (required)
NoNoNoNoCompatibility / Migration
YesNoNoHuman Verification (required)
packages/symphony/README.mdsetup section matches the field names actually present inpackages/symphony/symphony.yaml.example./api/symphony/*endpoint table cross-checked against route registrations inpackages/server/src/routes/api.symphony.ts.packages/web/src/routes/SymphonyPage.tsxandpackages/web/src/components/symphony/.check:bundled; Prettier formats markdown identically before/after the lint-staged auto-format on commit.bun run devwalkthrough of the README setup steps (deferred to the manual smoke step in the consolidation plan's Phase 5 verification block, after Part B retirement also lands).Side Effects / Blast Radius (required)
coleam00/Archonmay conflict on README.md; the banner is a self-contained block above the original content to keep that conflict trivial.Rollback Plan (required)
git revert <merge sha>ondev.Risks and Mitigations
/api/symphony/*schema if new routes are added without updating the table.packages/server/src/routes/api.symphony.tsas the source of truth, so future changes have a single anchor point.symphony.yaml.example(always the live source); Part B of Phase 5 (separate PR inDdell12/symphoney-codex) appends the deprecation pointer there too.🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
@archon/symphony): Automatically polls Linear and GitHub trackers, dispatches eligible issues into Archon workflows, and manages retries with configurable concurrency limits./symphony): Visual dispatch board with column grouping, status tracking, and quick-action buttons for manual dispatch/cancel per issue./api/symphony/*): Snapshot state, dispatch listing/details, immediate dispatch, cancel, and refresh endpoints.~/.archon/symphony.yaml) supporting multi-tracker routing, state-to-workflow mapping, and per-tracker codebase association.