# Implementation Plan
This document is the planning index for OpenSymphony. It is designed to be directly convertible into Linear issues.
## 1. Planning principles
- preserve Symphony semantics first
- keep the OpenHands adapter isolated behind one crate boundary
- go WebSocket-first for runtime updates
- local supervised mode is the MVP
- hosted mode is a follow-on milestone, not an MVP blocker, so it will be built in the future
- every task should be independently implementable by a coding agent with only repository and task context
## 2. Milestones
| M1 Foundation and contracts | repo bootstrap, workflow/config, domain model | stable repo skeleton and core invariants |
| M2 OpenHands runtime adapter | local supervisor, REST client, WebSocket runtime, session runner | working agent runtime path |
| M3 Symphony orchestration core | workspace lifecycle, Linear adapter, scheduler, GraphQL-backed repo harness | issue-driven autonomous execution with a generic scheduler core over tracker, workspace, and worker backends |
| M4 Operator UX and repo harness | control plane, FrankenTUI, generated context artifacts | usable local operator experience |
| M5 Validation and local packaging | fake server, live tests, doctor, packaging | reliable local MVP |
## 3. Issue hierarchy
```text
OSYM-100 Foundation and Contracts
├─ OSYM-101 Bootstrap workspace and crate boundaries
├─ OSYM-102 Workflow loader and typed config
└─ OSYM-103 Domain model and orchestrator state machine
OSYM-200 OpenHands Runtime Adapter
├─ OSYM-201 Local agent-server supervisor
├─ OSYM-202 REST client and conversation contract
├─ OSYM-203 WebSocket event stream, reconciliation, and recovery
└─ OSYM-204 Issue session runner
OSYM-300 Tracker, Workspaces, and Orchestration
├─ OSYM-301 Workspace manager and lifecycle hooks
├─ OSYM-302 Linear read adapter
├─ OSYM-303 Linear GraphQL agent write path
├─ OSYM-304 Orchestrator scheduler, retries, and reconciliation
└─ OSYM-305 Repository harness and generated context artifacts
OSYM-400 Observability and FrankenTUI
├─ OSYM-401 Control-plane API and snapshot store
└─ OSYM-402 FrankenTUI operator client
OSYM-500 Validation and Local Ops
├─ OSYM-501 Fake OpenHands server and contract suite
├─ OSYM-502 Live local end-to-end suite
└─ OSYM-503 CLI packaging, doctor, and operations docs
```
## 4. Recommended execution order
1. OSYM-101
2. OSYM-102 and OSYM-103
3. OSYM-201 and OSYM-202
4. OSYM-203
5. OSYM-301 and OSYM-302
6. OSYM-204
7. OSYM-303 and OSYM-304
8. OSYM-401
9. OSYM-305 and OSYM-402
10. OSYM-501
11. OSYM-502 and OSYM-503
## 5. Dependency graph
```text
OSYM-101
├─ OSYM-102
├─ OSYM-103
├─ OSYM-201
├─ OSYM-202
├─ OSYM-301
└─ OSYM-302
OSYM-102 + OSYM-103
└─ OSYM-204
OSYM-201 + OSYM-202
└─ OSYM-203
OSYM-203 + OSYM-301 + OSYM-302 + OSYM-102 + OSYM-103
└─ OSYM-204
OSYM-302
└─ OSYM-303
OSYM-204 + OSYM-301 + OSYM-302
└─ OSYM-304
OSYM-304
└─ OSYM-401
OSYM-303 + OSYM-304
└─ OSYM-305
OSYM-401
└─ OSYM-402
OSYM-202 + OSYM-203 + OSYM-204 + OSYM-302 + OSYM-304
└─ OSYM-501
OSYM-201 + OSYM-204 + OSYM-303 + OSYM-304 + OSYM-305 + OSYM-501
└─ OSYM-502
OSYM-401 + OSYM-402 + OSYM-502
└─ OSYM-503
```
## 6. Linear conversion guidance
Each task file in `docs/tasks/` includes front matter intended for issue creation.
Recommended mapping:
- `id` -> issue identifier suffix or custom field
- `title` -> issue title
- `parent` -> parent issue relationship
- `milestone` -> Linear project milestone
- `priority` -> Linear priority
- `estimate` -> estimate field or label
- `depends_on` -> linked blocking issues
- `blocks` -> reverse dependency links
- `project_context` -> issue description reference block
- `repo_paths` -> code ownership hint inside issue body
- `definition_of_ready` -> checklist in issue body
## 7. Definition of Ready
A task is ready when:
- its dependencies are merged or available in the working branch
- the docs referenced in `project_context` exist and are current
- target repository paths are identified
- required test fixtures are available
- required secrets or local services for live tests are documented
## 8. Definition of Done for the local MVP
The local MVP is done when all of the following are true:
- the daemon can read active Linear issues
- issue workspaces are created deterministically and safely
- a local supervised OpenHands server can execute issue conversations with per-issue `working_dir`
- the runtime adapter is WebSocket-first with readiness, reconciliation, and reconnect recovery
- the orchestrator can claim, run, retry, reconcile, and release work according to Symphony semantics
- the local control plane publishes snapshots
- FrankenTUI can observe and render daemon state
- fake-server contract tests pass
- live local end-to-end tests pass on a controlled machine
- `opensymphony doctor` validates a machine well enough to run the MVP
## 9. Parent issue strategy
Create the parent issues first in Linear, attach the relevant milestone, then create the child issues and link them under the parent.
Recommended parent issue purpose:
- collect architectural context
- hold milestone progress
- aggregate child acceptance notes
- reduce duplication in child issue descriptions
## 10. Suggested first milestone review gate
At the end of M2, run a formal adapter review.
Required evidence:
- conversation create payload example
- successful WebSocket attach trace
- readiness event handling proof
- reconcile-after-ready proof
- disconnect and reconnect test output
- one end-to-end run in a temp repo
If M2 is solid, M3 onward is mostly orchestration work rather than protocol risk.
## 11. Follow-on rich client and knowledge milestones
The current Linear roadmap extends the local MVP with rich-client, hosted,
provider, and release-quality work in M6 through M15. The additional OKF memory,
LLM wiki graph, ACP debugging, Tree-sitter code-intelligence, and workflow
target-branch specifications fit best as additive fractional milestones instead
of broadening the existing hardening milestone:
| M10.3 Codex And Subscription Readiness | after M10 web client/external gateway work, before M10.5 OKF memory and M14 hosted alpha | local Codex app-server support and ChatGPT subscription credential foundations before full hosted mode |
| M10.4 Desktop Live Operations And Model Polish | after M10.3 Codex readiness, before M10.5 OKF memory | desktop live refresh, truthful run-detail metrics, and Codex subscription model-configuration cleanup from first operator use |
| M10.5 OKF Memory Bundle Foundation | after M10 web/client transport, before M14 hosted visibility depends on portable memory documents | OKF concept schema, writer/lint, catalog reindex, import/export, docs sync and MCP/admin parity |
| M10.6 Desktop Run Detail Operations And Interrupts | after M10.5 OKF memory, before M14 hosted alpha | harness interrupt contract, OpenHands/Codex cancel wiring, Human Review to Merging supersede, Run Detail action cleanup, TUI parity, lazy desktop launcher |
| M10.7 Project Grouping And Dependency Signals | after M10.6 desktop operations, before M14 hosted alpha | control-plane project/dependency metadata, TUI project headers and dependency gutter, desktop grouping and collapse |
| M11.5 LLM Wiki Graph View | after M14 hosted identity and visibility foundations, before provider/harness readiness | memory graph DTOs, graph extraction, shared frontend package, Three.js renderer, inspector/accessibility, live privacy gates |
| M12.6 Tree-sitter Code Intelligence | after memory foundations, before M12.9 code graph and M15 release hardening | trusted Tree-sitter provider, memory-context AST integration, query packs, persistence, read-only MCP/CLI AST tools, performance and docs |
| M12.7 Workflow Target Branch Configuration | after M12.6 code intelligence, before M15 release hardening | configurable target branch markers, init prompt and flag, marker-only update settings mode, template/docs hardening |
| M12.8 Desktop App Installer And Auto-Update | after M12.7 workflow target branch configuration, before M15 release hardening | lazy desktop installer/launcher, verified release bundles, source-build fallback, auto-update prompts, and installer docs |
| M12.85 Codex Thread Lifecycle | after M10.3 Codex production harness, before M15 release hardening | manifest-backed per-issue thread reuse, retained terminal workspaces, durable archive transitions, and debug/reopen recovery |
| M12.9 Code Graph View | after M12.8 desktop installer and after M12.6 code-intelligence foundations, before M15 release hardening | graph-hero shell, stable symbol identity, code graph DTOs, shared frontend surface, run-diff overlays, cross-graph chips, and hardening |
| M12.95 Multi-Repository Foundations | after M12.9 target snapshots/overlays and completed COE-448 memory-server foundations | central instance config, canonical task binding, verified per-repository checkouts/instructions, per-instance memory catalog, and scoped leaf memory |
| M12.96 Parent Integration Lifecycle | after M12.95 foundations, before multi-repository operator rollout | hierarchy generations, durable leases, retained-child worktree reuse, restart-safe parent integration, repair PRs, and bottom-up cleanup |
| M12.97 Multi-Repository Operations And Rollout | after M12.96 parent lifecycle, before M15 release hardening | cross-client operator truth, hermetic lifecycle/fault validation, migration rollback, and isolated non-production activation |
| M12.99 ACP Harness Runtime Adapter | on current native-harness and multi-repository foundations, before M13 qualification | executable ACP v1 stdio client, profiles, host-owned sessions, concrete worker routing, callbacks, operator response delivery, extensions and two-harness live qualification |
| M13 ACP Debugging And IDE Attach | builds on M12.99 routing and session ownership, before M15 release hardening | multi-harness attachment, scheduler/IDE control handoff, ACP bridge fidelity, static editor setup, desktop launch and qualification before default UX transition |
M10.3 pulls the shared harness adapter, model/credential settings, OpenHands
subscription credential adapter, model configuration UI metadata, Codex
app-server prototype, ChatGPT OAuth readiness, production Codex harness
enablement, and cross-harness approval/routing work forward before the broader
hosted-provider backlog. Hosted subscription credential brokering remains in
M14 so local Codex subscription support is not blocked by hosted secret storage.
M10.4 captures the immediate operator feedback from live Codex-backed desktop
and TUI use: live snapshot/run-detail refresh without app restart, truthful Run
Detail metrics, model configuration defaults/auth-status cleanup for Codex
subscription profiles, Codex token usage accounting, and more useful Codex
event summaries.
M10.6 follows the desktop operations spec with the smallest set of issue-ready
tasks for real cancellation, same-conversation Human Review to Merging
supersede handling, Run Detail button cleanup, TUI parity, and the lazy desktop
launcher command.
M10.7 follows the TUI dependency gutter spec with project/dependency snapshot
fields, compact FrankenTUI project headers and dependency signals, desktop
project grouping with collapse, and a thin cross-client verification pass.
M12.6 follows the Tree-sitter AST specification with the smallest useful
agent-facing code-intelligence wave: a trusted provider, memory-context
integration, query packs, optional persistence, read-only AST tools, and
resource/security hardening.
M12.7 follows the workflow target branch specification with the smallest useful
target-repo bootstrap wave: workflow branch markers, init prompt and flag,
marker-only update flags, and template/docs hardening.
M12.8 follows the desktop installer and auto-update specification with release
metadata, verified bundles, app install/launch flow, source-build fallback,
update prompts, and end-to-end installer documentation.
M12.85 follows the Codex thread lifecycle specification with its required two
deployment-ordered slices: canonical per-issue thread reuse and retained
workspaces first, then terminal archival and debug/reopen recovery.
M12.9 follows the Code Graph specification with the smallest useful split:
workspace shell geometry first, stable symbol identity and code read contracts,
shared frontend adapters, run-diff symbol navigation, cross-graph chips, and
scale/accessibility hardening.
M12.95 through M12.97 follow the multi-repository orchestration specification.
They first replace implicit repository scope with central config, canonical task
bindings, verified checkouts, and one per-instance memory service; then add
durable parent leases, child-storage reuse, integration, repair, and cleanup;
finally they expose truthful operator state and gate activation on deterministic
fault-injected validation. M12.97 uses the composed hermetic gate and isolated
rollout procedure in `docs/multi-repository-rollout.md`; production activation
remains a separate operator decision. The wave reuses completed COE-448
memory-server work and M12.9 code snapshots/overlays instead of creating
parallel implementations.
M12.99 follows `docs/specs/acp-harness-adapter.md`. It delivers a working generic
ACP runtime through the real `opensymphony run` path, including configured
profile selection, retained host-owned sessions, filesystem/terminal callbacks,
scoped MCP setup, operator replies and registered extension operations. Adding
capability metadata without executable routing and response delivery does not
satisfy this milestone. ACP v2 and network transports are follow-on work.
M13 follows `docs/specs/opensymphony-acp-debugging-spec.md`. All supported ACP
profiles are core IDE attachment targets. A separate editor bridge attaches to
the same host-owned session; the orchestrator holds scheduling while transferring
exclusive control. The bridge preserves ACP source events and supported extension
semantics. OpenHands and native Codex debug compatibility remain explicit. Two
live harnesses and actual editor attachment must pass qualification before the
default debug UX changes.
The default `docs/tasks/task-package.yaml` and `docs/tasks/linear-publish.yaml`
track `multi-repository-orchestration`. The ACP runtime and IDE wave uses
`docs/tasks/acp-runtime-ide-task-package.yaml` and its matching
`acp-runtime-ide-linear-publish.yaml`, retaining the existing M13 issue identities.
`docs/tasks/advanced-knowledge-debug-task-package.yaml` contains the OKF and wiki
graph work; its published mapping remains available for those original issues.
## Current model
- COE-252 contributed: PR #10: Implement foundation workflow and scheduler contracts
- COE-253 contributed: PR #19: COE-253: OpenHands Runtime Adapter (merge `911b0b4`)
- COE-254 contributed: PR #6: COE-254: bootstrap tracker, workspace, and orchestration core
- COE-255 contributed: PR #4: COE-255: add control plane and FrankenTUI slice
- COE-256 contributed: PR #1: COE-257: tighten hosted deployment guidance
- COE-258 contributed: PR #83: Add memory init and mapped docs sync
## Important invariants
- Preserve the behavior described in the recent captured changes unless current code and tests show it has changed.
- Use capsule source refs to inspect the original PR or Linear issue when context is ambiguous.
## Operational flow
- No generated diagram requested for this sync.
## Known gotchas
- No area-specific gotchas were inferred from the selected memory.
## Recent changes
- COE-252: Foundation and Contracts
- COE-253: OpenHands Runtime Adapter
- COE-254: Tracker, Workspaces, and Orchestration
- COE-255: Observability and FrankenTUI
- COE-256: Validation and Local Operations
- COE-258: Bootstrap workspace and crate boundaries
- COE-259: Workflow loader and typed config
- COE-260: Domain model and orchestrator state machine
- COE-261: Local agent-server supervisor
- COE-262: REST client and conversation contract
- COE-263: Workspace manager and lifecycle hooks
- COE-264: Linear read adapter and issue normalization
- COE-265: WebSocket event stream, reconciliation, and recovery
- COE-266: Issue session runner
- COE-267: Linear MCP write surface
- COE-268: Orchestrator scheduler, retries, and reconciliation
- COE-269: Control-plane API and snapshot store
- COE-270: Repository harness and generated context artifacts
- COE-271: FrankenTUI operator client
- COE-272: Fake OpenHands server and protocol contract suite
- COE-273: Live local end-to-end suite
- COE-274: CLI packaging, doctor, and local operations docs
- COE-275: Remote agent-server mode and auth hardening
- COE-277: Implement hierarchy-aware task selection
- COE-280: Support workflow-owned OpenHands auth, provider, and launcher overrides at runtime
- COE-281: Support path-bearing OpenHands base URLs and MCP config at runtime
- COE-282: Support workflow-owned OpenHands conversation reuse policy at runtime
- COE-284: Add orchestrator run command to CLI and make it installable
- COE-287: Add opensymphony debug command for conversational session debugging
- COE-294: Detect LLM config changes and rehydrate conversations with updated env vars
- COE-382: Add supply-chain and security audits to CI
- COE-383: Decompose oversized session and TUI modules into focused submodules
- COE-384: Expand error-path tests for Linear client and workspace hooks
- COE-385: Resolve runtime tracking TODO in OpenHands session runner
- COE-386: Wire cargo-llvm-cov coverage reporting and regression floor into CI
- COE-387: Audit tracing spans and diagnostics for secret leakage
- COE-389: Current Gateway Inventory And Vocabulary
- COE-390: Gateway Schemas And Stream Feasibility
- COE-391: Gateway Module, Capabilities, And Dashboard Snapshot
- COE-392: Task Graph, Run Detail, File, And Diff Read APIs
- COE-393: Event Journal And Stream Broker
- COE-394: Frontend Workspace And Shared Schemas
- COE-395: Planning Artifact Schema And Session Service
- COE-396: Action Receipts And Initial Run Actions
- COE-397: Gateway API Client, Transport Adapters, And Reducers
- COE-398: Tauri Shell And Security Capabilities
- COE-399: Linear Read Coverage And Task Graph Cache
- COE-400: OpenHands Event Normalization And Runtime Mirror
- COE-401: Web App Entry And Deployment Modes
- COE-402: App Shell, Dashboard, Task Graph, And Run Views
- COE-403: Terminal And Log Renderer Prototype
- COE-404: Desktop Connection Profiles And Daemon Management
- COE-405: Linear Milestone, Issue, And Sub-Issue Mutations
- COE-406: Repository, Linear, And Research Analysis
- COE-407: Browser Transport And Remote Stream Protocols
- COE-408: Harness Adapter And Capability Model
- COE-409: Desktop Settings, Keychain, And Native Actions
- COE-410: Desktop Local Stream Optimization
- COE-411: Task Graph Editor And Runtime Overlay UI
- COE-412: Runtime Timeline And Terminal/Log Association
- COE-413: Implementation Plan Generator Stage
- COE-414: Diff, Validation, Approval, And Run Action Views
- COE-415: Milestone, Issue, And Sub-Issue Compiler
- COE-416: Dependency Graph And Plan Checks
- COE-417: Planning Workspace UI
- COE-419: Hosted Auth Placeholders And Web Parity
- COE-423: Model And Credential Settings
- COE-425: OpenHands Subscription Credential Adapter
- COE-426: Codex App-Server Prototype And Benchmarks
- COE-428: Model Configuration UI And Routing Metadata
- COE-429: Codex Approvals And Cross-Harness Routing
- COE-434: Long-running harness liveness and scheduler/runtime ownership contract
- COE-435: Long-running run observability fixtures and client-facing diagnostics
- COE-448: Multi-repo memory server and deterministic context
- COE-449: Desktop alpha recovery: replace stubs with functional app
- COE-454: OKF Bundle Schema And Legacy Capsule Mapping
- COE-456: OKF Writer, Lint, And Migration Fixtures
- COE-458: Catalog Reindex And Query Compatibility From OKF
- COE-460: OKF Export, Import, And Visibility Boundaries
- COE-463: Docs Sync And MCP Admin Parity For OKF
- COE-473: Desktop task graph dependency and run detail parity
- COE-475: ChatGPT OAuth For Codex Harness
- COE-476: Codex Production Harness Enablement
- COE-478: Harden model profile storage and validation follow-ups
- COE-479: Codex Debug Session Resume
- COE-505: Add scheduler-side Codex stdio interrupt channel
## Source refs
- COE-252
- COE-253
- COE-254
- COE-255
- COE-256
- COE-258
- COE-259
- COE-260
- COE-261
- COE-262
- COE-263
- COE-264
- COE-265
- COE-266
- COE-267
- COE-268
- COE-269
- COE-270
- COE-271
- COE-272
- COE-273
- COE-274
- COE-275
- COE-277
- COE-280
- COE-281
- COE-282
- COE-284
- COE-287
- COE-294
- COE-382
- COE-383
- COE-384
- COE-385
- COE-386
- COE-387
- COE-389
- COE-390
- COE-391
- COE-392
- COE-393
- COE-394
- COE-395
- COE-396
- COE-397
- COE-398
- COE-399
- COE-400
- COE-401
- COE-402
- COE-403
- COE-404
- COE-405
- COE-406
- COE-407
- COE-408
- COE-409
- COE-410
- COE-411
- COE-412
- COE-413
- COE-414
- COE-415
- COE-416
- COE-417
- COE-419
- COE-423
- COE-425
- COE-426
- COE-428
- COE-429
- COE-434
- COE-435
- COE-448
- COE-449
- COE-454
- COE-456
- COE-458
- COE-460
- COE-463
- COE-473
- COE-475
- COE-476
- COE-478
- COE-479
- COE-505