Roadmap

Each stage closes a verifiable loop. Prove the architecture with one real Agent before parallel migration.

R0: Documentation contract

• [x] Freeze the six-concept model and three-command user surface.
• [x] Separate Canonical data from target-private configuration.
• [x] Keep Adapter conversion pure and Core execution authoritative.

The gate rejects parallel semantic layers, target-private Canonical fields, standalone Extension manifests, and Adapter-expanded side effects.

R1: headless Claude Code Reference Extension

Complete ProjectConfig, CanonicalDocument, ArtifactChange, managed state, and a minimal npm Extension Host. Verify the current official Claude native surface and headless confirmation path. Implement Claude read/write/confirm, then run the real dry-run → Core apply → confirm → check loop in an isolated project with idempotency, conflict, denied approval, and rollback evidence.

No other Agent work starts until headless Claude proves the generated capability through a target-native path in a clean reproducible environment.

R2: agent-extension Scale Gate

Create the repository agent-extension Skill to standardize official capability discovery, aggregate Artifact research, minimal exhaustive fixtures, conversion, and native confirmation. Extract and freeze the reusable Extension directory, shared types, contract tests, fixture conventions, and migration checklist from Claude. A neutral second Adapter proves that no Core or Canonical change is needed.

Only after Claude regression still passes does parallel migration open.

R3: Parallel Agent migration

Codex, OpenClaw, and Hermes reuse the same Extension skeleton and contract tests. Each parallel task implements only target-native read/write/confirm. Public gaps return to a serial Architecture/RFC decision. All four Agents share one portable Canonical fixture.

The gate forbids changes to Core, Canonical DSL, ArtifactChange, or generic approval semantics and requires native confirmation with zero silent loss.

R4: Cross-Agent and multi-target acceptance

Freeze the shared portable Canonical fixture and target projections. Verify every Agent A → Canonical → Agent B projection, apply --all followed by per-target reverse reads, target-private isolation, and multi-target failure isolation. Real Presets do not define Canonical.

R5: ai-assets final consumer loop

Create a redacted inventory of every ai-assets leaf capability, composition, scope, and runtime dependency. Migrate it to the new CapabilityRef and Preset contracts without copying private bodies into public fixtures. Generate native project and aggregate Artifacts for Claude Code, Codex, OpenClaw, and Hermes from the same Preset, then run official installation/discovery, representative real invocation, complete inventory checks, reverse reads, apply --all, and a zero-diff second apply.

The gate requires semantic usability of every ai-assets capability on all four targets, zero degraded, unsupported, or blocked entries, and no sensitive scan findings. ai-assets is the final product acceptance corpus, but does not change Canonical DSL.