Document placement rules and index. When adding a new document, place it according to the categories below. All internal documents are written in English.
| Location | Nature | Rules |
|---|---|---|
docs/ root |
Living documents — hold the truth of current behavior, updated continuously | No date prefix. When code changes, the document must change with it |
docs/adr/ |
Decision records — why it was done this way | YYYY-MM-DD_slug.md. Not edited after the decision; to reverse one, supersede it with a new ADR |
docs/designs/ |
Pre-implementation designs and plans — what to build and how (point-in-time) | YYYY-MM-DD-slug.md. The header must carry Status (Draft → Approved → Shipped/Abandoned) and Symphony Layers (list the layers involved). After shipping, update only the Status and keep the body as history |
docs/reports/ |
Point-in-time analysis — audits, feasibility studies, RCAs | YYYY-MM-DD-slug.md. A snapshot of when it was written. The body is not kept current; follow-ups link only from the header status line |
docs/examples/ |
Example files for users | Keep consistent with actual behavior |
Symphony Layers follows the six-layer classification defined by AGENTS.md
(Policy / Configuration / Coordination / Execution / Integration /
Observability). Designs usually span multiple layers, so they are tagged via
header metadata rather than directories.
- symphony-spec.md — upstream Symphony spec, synced verbatim from openai/symphony
SPEC.md@8001b52(2026-08-12). Read-only, never modify — resync only via a dedicated PR - architecture.md — maps spec components (§3.1) and layers (§3.2) to packages. Organized as per-layer slices; PRs that move code across layers/packages update the matching slice
- configuration.md — configuration and environment variable reference (env loading order, standalone projects, skill layering)
Architecture documentation scoped to a single package lives in that package's
README.md (for example packages/control-plane/README.md).
Provider-specific compact adapter profiles and host-side agent-tool contracts:
- GitHub Project — configuration, normalization, and
github_graphql - GitHub tool — standalone
github_graphqltool contract - Linear — configuration, normalization, and
linear_graphql - File — local/Docker E2E fixture adapter profile
| Document | Layers | Status |
|---|---|---|
| 2026-05-10-cli-restructure-design.md | Coordination, Configuration | Shipped |
| 2026-05-10-cli-restructure-issues.md | Coordination, Configuration | Completed (plan) |
| 2026-07-06-github-project-repo-dispatch-filter-design.md | Integration, Coordination, Observability | Shipped (PR #435) |
| 2026-08-11-standalone-project-model-design.md | Policy, Configuration, Coordination, Execution, Observability | Shipped |
| 2026-08-11-agent-bootstrap-plugin-pm-steward-design.md | Policy, Configuration, Coordination, Observability | Draft |
| 2026-08-11-standalone-project-model-issues.md | (plan) | Active |
| Document | Status |
|---|---|
| 2026-05-04-single-repo-orchestrator-feasibility.md | Concluded — promoted to an ADR |
| 2026-06-25-spec-gap-analysis.md | Retired — living-map upkeep stopped, final snapshot |
| 2026-07-06-risk-audit-report.md | Awaiting review (issues not filed) |
| 2026-07-19-github-api-rate-limit-audit.md | Partially implemented (R1.5 shipped) |
| 2026-08-28-upstream-spec-drift-research.md | Documentation follow-up: #675 |
See the adr/ directory for the ADR list. When a newer decision replaces
an older one, they are linked via the Supersedes header.