Compatibility First Planning

Required Outputs

Your planning output must contain all of these, either as separate docs or as sections in one design doc:

1. Goal and non-goals
2. Current-system inventory
3. Compatibility contract
4. Terminology mapping
5. Core vs compatibility-shell boundary
6. Phase plan
7. Rough task breakdown
8. Verification and parity plan
9. Current-system evidence references

If any of these are missing, the plan is not implementation-ready.

The Flow

1. Clarify the target

Define what success means in user-facing terms.

Lock these early:

• what must be preserved
• what may change internally
• what is explicitly out of scope for v1

If "1:1" is requested, ask which surfaces count:

• workflow semantics
• API routes and payloads
• terminal dashboard
• web dashboard
• CLI behavior
• tracker/provider behavior

2. Inventory the current system

Before proposing architecture, identify:

• real runtime behavior
• user-facing surfaces
• provider-specific behavior
• implementation accidents that should not be preserved blindly

Back inventory claims with evidence when possible:

• point to concrete files, interfaces, routes, configs, or runtime behaviors
• prefer a small number of high-signal references over broad code dumps
• do not claim something is "core" or "compatibility-facing" without showing where that behavior exists today

Separate:

• true core behavior
• compatibility shell behavior
• future extension ideas

3. Freeze compatibility contracts

Write down the external contracts before abstraction work starts.

Examples:

• WORKFLOW.md parsing and reload behavior
• HTTP API routes, DTOs, and error semantics
• dashboard output expectations
• CLI flags and shutdown behavior
• provider-specific workflow behavior

Do not leave compatibility as "we'll compare later".

4. Write terminology mapping

Create an explicit old-term to new-term map.

Always do this when:

• the existing system uses provider-specific names
• the new system introduces a provider-neutral domain model
• internal and external language may intentionally differ

Example questions:

• What is the internal replacement for issue?
• Which external surfaces still say issue for compatibility?
• Which provider-specific names must stay out of the core?

5. Draw the architectural boundary

Define the smallest possible provider-neutral core.

For go-symphony, the default posture is:

• keep orchestration, runtime state, runner, workspace lifecycle, Codex protocol handling, and tracker reads in the core
• keep provider-specific workflow behavior, tracker writes, workpad semantics, and provider tools in the compatibility shell

Only abstract what the current system already proves is common.

6. Phase the work around closed loops

The earliest meaningful milestone must close a real loop.

Prefer this shape:

1. boot
2. load config
3. poll stub or memory source
4. run one worker
5. emit snapshot
6. stop cleanly

Do not make the first phase "all abstractions" or "all provider integrations".

7. Define checks before implementation

Every phase needs explicit verification.

At minimum, include:

• scope check
• boundary check
• compatibility check
• operational closed-loop check
• extension check
• maintenance check

If the plan says "we will test later", it is incomplete.

8. Hand off to execution planning

Once the design is approved:

• freeze the design doc
• identify the implementation order
• then use writing-plans for the task-by-task execution plan

Quick Reference

Default Checks

Run these checks against every major design:

• Scope: Is v1 solving one concrete end-to-end user path?
• Boundary: Is each abstraction required now, or only hypothetical?
• Compatibility: Is every user-facing surface explicitly covered?
• Operational: Can the system boot, run, observe, and stop cleanly?
• Extension: Would adding another provider later require rewriting the core?
• Maintenance: Is the design understandable to the people who will actually maintain it?

Red Flags

Stop and fix the plan if you notice any of these:

• "We'll figure out compatibility as we implement."
• "Let's make tracker writes generic now for future providers."
• "The default workflow should be provider-agnostic from day one."
• "Observability can keep its own runtime truth."
• "CLI or shutdown behavior is just edge polish."
• "Terminology mapping is obvious; we can skip it."
• "We'll add verification after the code exists."

Common Rationalizations

Common Mistakes

• Jumping from vague goal to package layout without freezing compatibility
• Mixing provider-specific writes and workpad semantics into the core
• Letting future provider support dictate v1 abstractions
• Treating Codex app-server as a thin transport instead of a protocol contract
• Creating phases that do not close a real operational loop
• Producing architecture notes without a verification plan

Output Standard

A good planning result for go-symphony should leave the reader knowing:

• what the v1 target is
• what is intentionally deferred
• how Symphony terms map into Go terms
• what the provider-neutral core is
• what remains compatibility-facing
• what order the work should happen in
• how parity will be proven

If any of those are unclear, the plan is not ready.

Next Step

After approval, use writing-plans to turn the approved design into an execution-ready implementation plan.