Skip to content

ADR-0002: Context Representation Format

Status

Proposed

Date

2026-04-05

Context

workspace-mcp retains durable project context in repository documents and structured artifacts. The repo already needs both human-readable narrative context and machine-readable metadata, but the preferred representation format has not been stated as a separate architectural decision.

The representation choice must remain:

  • durable and version-controlled
  • readable in normal repo workflows
  • consumable by tools and agents
  • compatible with schema validation where needed

Decision

Adopt a dual-format representation model:

  1. Use Markdown as the default format for human-governed durable context.
  2. Use JSON or YAML for machine-readable metadata, registries, indexes, and similar structured artifacts.
  3. Prefer schema validation when structured artifacts are operationally important.

Markdown is the default for:

  • architecture notes
  • ADRs
  • contracts
  • workflows
  • design notes

Structured formats are appropriate for:

  • manifests and metadata
  • registries and indexes
  • mappings and identifiers
  • configuration that benefits from deterministic parsing

Consequences

Positive:

  • repo documentation stays readable and diff-friendly
  • structured artifacts remain suitable for tooling and validation
  • agents can distinguish narrative sources from machine-readable support data

Tradeoffs:

  • maintainers must choose formats consistently
  • some context may need both narrative and structured representations
  • schemas add maintenance overhead when introduced

Scope Notes

This ADR does not prescribe a new top-level folder structure. Repository layout decisions remain governed by the retention policy, repo contracts, and existing workspace-mcp document organization.