Part of #74. Most ambitious follow-up — defer until Phase 1+2+other follow-ups land and we have measurements showing re-edit cost is a real pain.
Goal
In SDD's plan phase, plan.md gets re-edited multiple times: 1-3 advisor guidance rounds, 1-2 crit review rounds, 1-2 post-review fix rounds. Today each round uses the Edit tool with output proportional to the section being changed. For large plans, output tokens compound across rounds.
GAP (Generative Artifact Protocol) proposes that sub-agents emit small JSON "edit envelopes" with target IDs or JSON Pointers, and a runtime applies the envelope to the artifact. The LLM produces only the delta plus envelope overhead — typically 10-30 tokens per change vs hundreds for an Edit operation, and unchanged content is never regenerated.
Inspired by
Scope (research draft, not implementation)
This is architectural — touches how the orchestrator and sub-agents interact with artifacts. Concrete impl is TBD; current goals are:
- Validate the savings on real SDD sessions (instrumentation issue first?)
- Decide envelope format (JSON with target IDs? JSON Pointer? Markdown anchor?)
- Decide on a runtime: does the orchestrator apply envelopes, or does a separate handler?
- How does this interact with crit / plannotator review of plan.md? (Reviewers comment on the rendered artifact, not the envelope stream.)
- Backwards compatibility with existing plan.md format
Out of scope (for the issue, will be revisited)
- Whether to migrate exploration.md / review.md too
- Building a generic GAP runtime — likely we just need the SDD-specific subset
Open questions
- Is the Edit tool's diff already efficient enough that GAP envelopes don't move the needle?
- Do all our target agents (Claude, OpenCode, Copilot, Factory, Codex) reliably produce well-formed JSON envelopes?
- Risk: malformed envelopes / hallucinated target IDs (acknowledged failure mode in GAP spec)
Pre-requisite
Add token-cost instrumentation to current SDD flow first. Without measurements showing re-edit cost is a real pain, this stays speculative.
Estimate
~2-3 weeks when picked up. Strong defer.
Part of #74. Most ambitious follow-up — defer until Phase 1+2+other follow-ups land and we have measurements showing re-edit cost is a real pain.
Goal
In SDD's plan phase, plan.md gets re-edited multiple times: 1-3 advisor guidance rounds, 1-2 crit review rounds, 1-2 post-review fix rounds. Today each round uses the Edit tool with output proportional to the section being changed. For large plans, output tokens compound across rounds.
GAP (Generative Artifact Protocol) proposes that sub-agents emit small JSON "edit envelopes" with target IDs or JSON Pointers, and a runtime applies the envelope to the artifact. The LLM produces only the delta plus envelope overhead — typically 10-30 tokens per change vs hundreds for an Edit operation, and unchanged content is never regenerated.
Inspired by
Scope (research draft, not implementation)
This is architectural — touches how the orchestrator and sub-agents interact with artifacts. Concrete impl is TBD; current goals are:
Out of scope (for the issue, will be revisited)
Open questions
Pre-requisite
Add token-cost instrumentation to current SDD flow first. Without measurements showing re-edit cost is a real pain, this stays speculative.
Estimate
~2-3 weeks when picked up. Strong defer.