[ctawiah]

Context

Every source format needs the same contract. The shared core owns path resolution, projection building, and edit planning, so an adapter cannot get them wrong.

What changes

• Add the adapter contract. An adapter turns bytes into a tree of logical nodes with byte spans and encoders. The core resolves select and map paths, builds the typed projection, and plans exact edits.
• Add the select and map path grammar, the registry, and the node constructors.
• Add the YAML tree with exact scalar spans, which the YAML adapter and Markdown front matter share.
• Add the Markdown adapter. One format exposes the front matter, the body, the heading sections, and the LaunchDarkly marker regions. It serves prompt files, AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instructions.
• Add the Agent Skill adapter.

Design notes

• Adapters receive bytes only. They never read files, run code, or use the network.
• Each format is its own package. A format cannot import another format.
• Parse is mode-agnostic. The planner converts the prompt to the mode of the config.

Review focus

• Can a new format be added with one package and one registration?
• Do edits keep every byte outside the accepted spans?

Verification

• make build
• go test ./...
• golangci-lint run ./...

Related changes

1. refactor(sync): remove Phase 1 source references #1005: Phase 1 reference removal
2. feat(sync): add projection and problem core #987: projection and problem core
3. This PR: adapter core and Markdown
4. feat(sync): add the structured document adapters #989: structured adapters
5. feat(sync): add the Python adapter #991: Python adapter
6. feat(sync): add the TypeScript and JavaScript adapters #992: TypeScript and JavaScript adapters
7. feat(sync): add source descriptor storage #993: descriptor storage
8. feat(sync): compile and publish repository sources #994: compile and publish
9. feat(sync): detach descriptor-backed sources #1003: descriptor detach
10. feat(sync): prepare repository source links #997: link preparation
11. feat(sync): integrate repository sources with planning and link #995: planning and link
12. feat(sync): add the link commands #998: link commands

🤖 Generated with Claude Code

---

Note

Overview
Introduces internal/sync/adapter, the shared layer between the sync engine and per-format parsers: registered Adapter implementations turn a SourceBundle into a logical Node tree with byte spans and encoders, while the core owns select/map path parsing and resolution, descriptor normalization, typed projections (variation, tool, skill), indexed-selection fingerprints, and UpdateSource planning of **TextEdit**s with read-only fallbacks when structure or capabilities block writes.

Adds yamltree for YAML→nodes with exact scalar spans (shared by front matter and future YAML support), marking structural YAML, aliases, merge keys, and non-exact scalars read-only where appropriate.

Adds markdown and agent-skill formats: documents expose frontmatter, body, sections, and LaunchDarkly marker regions, with fenced/indented-code-aware parsing; markdown defaults variation prompts to body, agent-skill validates SKILL.md front matter and maps description + body for skills. Includes testdata/golden fixtures for common agent instruction file shapes.

^{Reviewed by Cursor Bugbot for commit 7abc71a. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[nkester-ld]

This doesn't seem to be used in this PR. we could move it to it's first reference #992 - or keep it. It seems reasonable to have this in place for later testing.

[ctawiah]

Good call. The package now lands in #992 with the conformance tests, which are its only user. I updated both descriptions.

[nkester-ld]

IMO, a nit that claude helped me find, but does crash the yaml reader given valid yaml:

yamlValueNode sends every !!int and !!float through strconv.ParseFloat (yamltree.go:252). That function rejects some valid YAML numbers, such as 0x10, 0o17, .inf, -.inf and .nan. All my test numbers cause it to crash file read with:
strconv.ParseFloat: parsing "0x10": invalid syntax (and the same error for the others).`

This is the test I ran to confirm the issue. It needs "github.com/launchdarkly/ldcli/internal/sync/adapter" in the imports):

func buildDocument(t *testing.T, source string) (*adapter.Node, error) {
        t.Helper()
        var document yaml.Node
        require.NoError(t, yaml.Unmarshal([]byte(source), &document))
        return Build([]byte(source), document.Content[0], 0, false)
}

func TestValidYAMLNumbersDoNotFailTheDocument(t *testing.T) {
        for _, value := range []string{"0x10", "0o17", ".inf", "-.inf", ".nan"} {
                t.Run(value, func(t *testing.T) {
                        root, err := buildDocument(t, "limit: "+value+"\nname: kept\n")
                        require.NoError(t, err)
                        assert.Equal(t, "kept", root.Fields["name"].Value)
                })
        }
}

[ctawiah]

Thanks for the test. Hex and octal now decode through the YAML library, so they are plain numbers. Infinity and NaN decode too, but they have no JSON form, so the builder keeps them as read-only text instead of a number that would fail later in a fingerprint. Your test is in yamltree_test.go as TestValidYAMLNumbersDoNotFailTheDocument, with the read-only check added.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d501e74. Configure here.}