Coding OS
Sign in
Browse docs▾

Wrapper Derivation Policy

Purpose: Define how editor- and tool-specific wrapper files (.claude/, .codex/) stay thin, derived, and subordinate to canonical SSOT docs. Read when: Editing .claude/rules/* or adding future wrappers such as .github/instructions. Skip when: The task only changes canonical docs and does not touch wrappers. Read next: docs-system.md, agent-workflow.md, and mcp-tool-inventory.md

Nav: Docs Index | AGENTS

Rule

  • Canonical truth lives in docs/ and root SSOT files such as AGENTS.md.
  • Wrapper files are derived adapters for a specific tool runtime.
  • Wrappers must never become a second source of project truth.

Thin-Wrapper Contract

  • Each wrapper includes exactly one Source of truth: line.
  • Each wrapper includes 1-3 canonical refs.
  • Each wrapper keeps only routing, verification, or scope hints needed by that tool.
  • Each wrapper body stays short enough to avoid loading duplicate context.

What Wrappers May Contain

  • path/glob targeting
  • one-line source-of-truth pointer
  • a small set of canonical refs
  • one verification line

What Wrappers Must Not Contain

  • product or architecture decisions
  • API contract details
  • schema names or field lists
  • workflow rules that differ from SSOT
  • copied policy text that can drift

Verification

  • make docs-lint

Wrapper Surfaces

The coding-os adapter system creates wrappers automatically:

  • .claude/rules/* (Claude adapter — symlinks to src/core/rules/)
  • .codex/instructions.md (Codex adapter — merged from src/core/rules/ + src/core/skills/)

Wrappers are regenerated by coding-os init and coding-os add-adapter. Manual edits to wrappers are discouraged — change the canonical source instead.