Skip to main content

​
When to Use

When implementing a package or tool from multiple specification documents that cover different concerns (reference, architecture, scoping). This extends the single-spec a2a pattern to cross-document synthesis.

​
The Pattern

Read [doc A] section N (command reference — exit codes, flags)
Read [doc B] layer M (architecture — detailed specifications per command)
Read [doc C] section P phase Q (scoping — MVP subset of commands)

Implement @stratt/{package} as a Bun TypeScript CLI:
  (1) src/commands/{name}.ts — {specification from doc B}, exit codes {from doc A}
  (2) src/commands/{name}.ts — ...
  ...

Wire all commands through src/index.ts with global {flags from doc A}.
Include bin field in package.json for bunx invocation.

​
Why Three Documents

DocumentRoleWithout It
Reference (Handbook)Canonical exit codes, flag names, command tableAgent invents exit codes
Architecture (TAD)Detailed per-command behaviour, saga patterns, integration pointsShallow implementations
Scoping (Synthesis)MVP subset, phasing constraintsAgent implements everything
The scoping document is the most important. Without explicit scoping, the agent plans from the most complete specification and builds all 13 commands instead of the 7 MVP commands.

​
Cross-Document Resolution

The agent’s plan mode reconciles all three documents before writing code:
  • Exit codes come from the reference (authoritative)
  • Behaviour comes from the architecture (detailed)
  • Scope comes from the synthesis (constrained)
Contradictions surface during planning, not during coding. This is why the plan phase matters — it absorbs specification reconciliation.

​
Example Application

This pattern produced the STRATT CLI (7 commands, 25 files, 39 tests) in one session from:
  • Handbook Section 9 (13 commands with exit codes)
  • TAD Layer 5 (full command specifications)
  • Synthesis Strategy Section 4 Phase 1 (MVP: new, validate, fingerprint, publish, run, deprecate, verify)

​
When NOT to Use

For single-spec packages (like @stratt/fingerprint which had one canonical serialisation spec), the simpler a2a spec-to-package pattern is sufficient. Multi-doc synthesis adds overhead that is only justified when the specification genuinely spans multiple documents.