# ADR: AI-Optimized Directory Structure ## Status Proposed. Revision: 2026-07-31. Renamed from `docs/specs/directory-structure.md`. If local host instructions still name the old path, this ADR is the canonical successor. This decision is listed as `ADR-0001` in the [ADR index](README.md). The ID is a stable navigation label and does not change this ADR's Proposed status. This ADR is the detailed directory-status reference under `docs/ARCHITECTURE.md`, the accepted repository-wide owner. Formal acceptance of this ADR still requires the validation gate below. ## Scope This ADR owns directory ownership and contribution routing. It does not define knowledge-base registry schemas, host package generation internals, or the cross-surface DX control plane; the latter belongs to the [Developer Experience System ADR](developer-experience-system.md). Rejected direction: top-level `packs/`. A pack is a lifecycle state, not a source directory. Legend: - `[active]`: exists or can be edited now. - `[generated]`: package output; may be absent from the source checkout because the generator is source of truth. - `[target]`: future owner; create only when the inline gate is satisfied. - `[candidate]`: may be created as docs-only evidence; does not affect runtime. ## Directory Structure ```text # host and agent surfaces .claude-plugin/ # [active] thin Claude Code shell plugin.json marketplace.json # native install/discovery metadata only .qoder-plugin/ # [active] hand-maintained Qoder shell plugin.json # thin discovery/install metadata only .cursor-plugin/ # [active] thin Cursor shell plugin.json marketplace.json # install/discovery metadata only .codex-plugin/ # [active] thin Codex shell plugin.json # thin discovery/install metadata only .github/plugin/ # [active] thin GitHub Copilot shell plugin.json marketplace.json # native install/discovery metadata only qwen-extension.json # [active] thin Qwen Code shell .agents/ skills// # [active] host-local only; shared logic -> root skills/ SKILL.md references/ scripts/ # host-only depth for this skill skills// # [active] canonical shared workflows SKILL.md references/ models/ # [active] maturity models and embedded detector contracts routing.md .md agent-roles/.md # [target] create only for role-only prompts # no workflow steps/tools/evidence contracts # reused by 2+ explicit consumers # repository governance and support policy SECURITY.md # [target] private disclosure and security policy SUPPORT.md # [target] supported versions and support routes # executable automation; split by business capability, never scripts/core/ scripts/ dx-contracts/ # [target] judgment-free declaration catalog, # activation ledger, validation, and projection diff host-support/ # [active] host identities, support slices, # profile predicates, and freshness policies evidence-contract/ # [target] shared receipt envelope, evidence # taxonomy, compatibility, and redaction invariants harness-doctor/ # [target] bounded read-only product diagnostics support-bundle/ # [target] plan/redact/persist/delete support evidence harness-analysis/ # [active] Harness evidence and report mechanics canvas-preview/ # [active] local Canvas preview subcapability cli.mjs # executable command owner index.mjs # public import surface inside/outside the capability report-source/ # [active] report-source and bounded review integrity index.mjs # public contract/review import surface apply-review.mjs # review application and compatibility CLI owner core-change-watch/ # [active] static structure/core-path/history evidence session-analysis.mjs # [active] thin shim; new exports -> scripts/session-analysis/ session-analysis/ # [active] session evidence collection/normalization platforms/.mjs # Qoder/Codex/Claude/Cursor/Qwen/Copilot/Pi/Kimi/WorkBuddy host adapters ides// # target editor-local evidence not covered by host adapters / # [target] new capability owner cli.mjs # use cli.mjs for new capabilities schema.json fixtures/ lib/ # helpers scoped to this capability knowledge-base-registry/ # [target] compiler; requires matching spec runtime-smoke// # [target] isolated native checks and receipt payloads npm-package/ # [active] current bundle and verify tooling packaging/ # [active] source-local generated host artifacts build-host-plugin.mjs # assemble an existing thin host shell plus runtime roots verify-host-plugin.mjs # reject host/package/state leakage and non-portable links schemas/ # [target] versioned public runtime contracts .v.schema.json # shared by 2+ repo surfaces or packaged hosts hooks/ hooks.json.template # [active] copyable hook wiring template git-scripts/.mjs # [active] existing wrapper; new wrappers need target gate git-scripts// # [active] existing owner; new owners need target gate # structured knowledge; docs-only until registry compile + binding tests exist knowledge-base/ # [candidate] not runtime-active NOTICE.md # must say assets do not execute by default official/{practices,languages,frameworks,contracts,scenarios}// knowledge.md schema.json fixtures/ community//{practices,languages,frameworks,contracts,scenarios}// knowledge.md schema.json fixtures/ references/ # [active] human guidance without fixtures README.md # redirects historical names and topic roots session-evidence/ # bounded session and usage evidence project-harness/ # static project and delivery evidence agent-customize/ # agent assets and Skill guidance loop-engineering/ # repeated-work owner selection tool-runtimes/ # runtime lookup support contracts recommend/ # [target] recommendation examples case-studies/ # [target] examples, not runtime policy projects/.md scenarios/.md private//operating-models/ # local-only; exclude from packaging templates/ # [active] runtime-selected contracts reporting/ # [active] report-generation template family routing.md # [active] report/style/output route selection report-structure.md # [active] Markdown report skeleton qoder-canvas.md # [active] Qoder Canvas output contract cursor-canvas.md # [active] Cursor Canvas output contract html-visual.md # [active] HTML visual contract style/ # visual grammar and style routing components/ # [target] reusable component profiles, 2+ consumers common/ # [target] shared fragments, 2+ consumers docs/ dx/ # [target] curated journeys, metric definitions, # and DX improvement governance privacy.md # [target] repository data-use and privacy policy accessibility.md # [target] cross-surface accessibility minimums adrs/ README.md # [active] ADR id, status, and route index directory-structure.md # [active] this directory ownership ADR developer-experience-system.md # [active] proposed DX target architecture specs/ knowledge-base-registry.md # [target] required before KB runtime activation adapters/ # [active] matrix first; split notes by trigger README.md # [active] host matrix and split triggers dev/ # [active] local preview/debug helpers, not hooks/CI test/ # [active] tests for scripts/hooks/skills/templates ``` ## Routing Rules Use the tree first. These rules resolve common collisions: | Artifact | Canonical owner | | --- | --- | | Shared workflow | `skills//SKILL.md` | | Host-local wrapper or mirror | `.agents/skills//` | | Maturity model and embedded detector contract | `models/.md` | | Executable detector or scoring signal | `scripts//` | | Skill-specific signal interpretation | `skills//references/` | | Role/persona prompt | `agent-roles/.md` | | Single-consumer role/persona text | `skills//references/` | | Single-file executable script | `scripts/.mjs` only until a second support file is needed | | Executable capability | `scripts//cli.mjs` | | DX declaration catalog, activation state, or projection drift | `scripts/dx-contracts/` | | Host identity, support slice, profile predicate, or freshness policy | `scripts/host-support/` | | Shared evidence envelope, class taxonomy, or redaction invariant | `scripts/evidence-contract/` | | Read-only Better Harness environment diagnostics | `scripts/harness-doctor/` | | Native Host smoke payload | `scripts/runtime-smoke//` | | Support bundle plan, redaction, persistence, deletion, or handoff | `scripts/support-bundle/` | | Harness Canvas preview runtime | `scripts/harness-analysis/canvas-preview/` | | Harness report-source and review integrity | `scripts/harness-analysis/report-source/` | | Capability-specific host adapter | `scripts//platforms/.mjs` | | Versioned public runtime schema | `schemas/.v.schema.json` | | Current package builder and verifier | `scripts/npm-package/` | | Source-local generated host artifact | `scripts/packaging/` | | Hook wiring | `hooks/hooks.json.template` | | Hook implementation | `hooks/git-scripts//` | | Host matrix entry | `docs/adapters/README.md` | | DX journey, contract, evidence, or governance decision | `docs/adrs/developer-experience-system.md` | | Split adapter note | `docs/adapters/.md` only after matrix split triggers | | Local debug helper | `dev/` | | Automated test | `test/` | | Human prose guidance | `references/` | | Better Harness DX journey or metric governance | `docs/dx/` after the ADR activation gate | | Repository privacy or accessibility policy | `docs/privacy.md` or `docs/accessibility.md` after the ADR activation gate | | Prose-only community guidance | `references//community/` | | Named examples or operating models | `case-studies/` | | Report skeleton | `templates/reporting/report-structure.md` | | Report output-mode contract | `templates/reporting/.md` | | Template component profile | `templates/components/.md` | | Shared template fragment | `templates/common/.md` | | Structured knowledge candidate | `knowledge-base/{official,community}/...` | - Prose guidance goes to `references/`. - Prose-only community guidance goes to `references/*/community/`. - Community content stays in `references//community/` unless the same change includes `knowledge.md`, an interim `schema.json`, and at least one fixture. Promotion from `references/` to `knowledge-base/` is a migration-gated move. - Named examples and operating models go to `case-studies/`. - Runtime behavior goes to `skills/`, `scripts/`, `hooks/`, or `templates/`. - Versioned public runtime contracts shared by multiple repo surfaces or packaged hosts go to `schemas/`. Capability-private schemas stay under the owning `scripts//` directory. - Role/persona text goes to `agent-roles/` only when it has no workflow steps, tool instructions, evidence rules, artifacts, or validation contract. A single-consumer role stays under `skills//references/` until the second explicit consumer lands in the same change as the promotion. - Structured knowledge with `knowledge.md`, `schema.json`, and fixtures goes to `knowledge-base/{official,community}/` as docs-only candidate content until `docs/specs/knowledge-base-registry.md`, compiler, and binding tests exist. Prose-only drafts stay in `references/*/community/` until they have schema and fixtures. Community namespaces are lowercase and unique under `knowledge-base/community/`; the registry spec owns final collision policy. Until then, namespace uniqueness is a Review Readiness Check item: list the existing immediate child directories under `knowledge-base/community/`, confirm the exact name is unused, and reject renames unless the same change adds a deprecation redirect. This manual check expires when `scripts/knowledge-base-registry/` provides an equivalent validation command. - Shared workflows go to root `skills/`; host-local wrappers or generated mirrors go to `.agents/skills/`. - Host plugin directories such as `.claude-plugin/`, `.qoder-plugin/`, `.cursor-plugin/`, `.codex-plugin/`, and `.github/plugin/` are install/discovery shells for one host. Existing active shells may be hand-maintained narrowly, but the Qoder public npm package ships all seven plugin metadata roots, while the Qoder runtime bundle ships only `.qoder-plugin/`. New host shells start from the `docs/adapters/README.md` matrix; split to `docs/adapters/.md` and add a source-local `scripts/packaging/` builder only for an accepted host-artifact contract. New host identities still require the matrix split triggers. `.agents/` is the generic host-local skill/wrapper/mirror surface and is not a product owner. - New executable capabilities use `scripts//cli.mjs`. The root `.mjs` facade pattern is reserved for compatibility shims, existing owners, or an accepted spec that needs a stable root API. Product logic, helpers, capability-private schemas, fixtures, and adapter depth live under `scripts//`; adding any second support file for a flat script triggers a directory owner or a documented facade migration. A grandfathered facade delegates to its directory owner. Existing compatibility wiring may stay in the facade; any new export, option, helper, schema, fixture, adapter, or output mode lands in the directory. - Reusable Canvas preview serving, transform, runtime discovery, fixture, and platform helpers live under `scripts/harness-analysis/canvas-preview/` and are imported through its `index.mjs`. This keeps the whole Harness analysis owner copyable for installed-like consumers. The repository preserves the historical `scripts/harness-analysis/canvas-preview-server.mjs` command as a compatibility facade while public CLI metadata still exposes that path. - Report-source creation/validation, review-packet binding, episode/delivery review normalization, and review application live under `scripts/harness-analysis/report-source/`. Non-facade consumers import the contract through `index.mjs`; the historical `report-source.mjs`, `report-review-packet.mjs`, `episode-evidence-review.mjs`, and `apply-source-review.mjs` paths remain compatibility facades. The apply-review facade delegates to the private command owner without widening the public Harness command registry. - Host shells are thin. Existing active shells may be assembled into generated artifacts through `scripts/packaging/`; new host identities still require a matrix entry and the split triggers before host-specific builders land. - `scripts//platforms/.mjs` collects or normalizes per-capability host evidence. `scripts/npm-package/` owns current repository package assembly and verification. `scripts/packaging/` owns source-local generated host artifacts and stays excluded from public package/runtime outputs. Do not collapse these concerns. - Report skeletons and output modes live under `templates/reporting/`. Keep `report-structure.md` and the runtime contracts at the family root; update consumers to canonical paths instead of adding compatibility files. - `templates/components/` owns named reusable component profiles with their own contract, such as a scorecard component profile. `templates/common/` owns shared fragments included by other templates, such as a repeated metadata block. Do not add language-specific report skeletons beside the base report by default; keep language choice in source data, prompts, and rendered content unless a separate skeleton has explicit active consumers and cannot be represented by the shared report template. - Countable consumers are explicit local references that load, invoke, select, package, or test an asset. Casual prose mentions do not count toward the 2+ consumer rule. Repo-local `.agents/skills//` directories use `SKILL.md` as their entrypoint. Host-only ownership, wrapper routing, and generated-file provenance belong in the skill instructions or beside the generator; this repository does not require a separate mirror sidecar schema. Knowledge-base activation stages: - Stage 0: no registry spec. Community prose stays in `references/`; structured candidates need the interim schema, fixtures, namespace check, and migration note. - Stage 1: `docs/specs/knowledge-base-registry.md` accepted. Candidate assets may accumulate against the accepted schema. - Stage 2: compiler exists and passes representative fixtures for the accepted schema. Candidate assets may become discoverable output. - Stage 3: binding tests pass for every active kind and explicit consumer mapping. Assets may become runtime-active. Minimum `knowledge-base/**/schema.json` shape until the registry spec exists: ```json { "schemaVersion": 0, "kind": "practice|language|framework|contract|scenario", "status": "candidate", "runtimeActive": false, "owner": "repo-or-community-namespace", "fixtures": ["fixtures/.json"] } ``` ## New Host Checklist Adding support for a new host must route every artifact to an owner: - `docs/adapters/README.md`: host matrix row with boundary, discovery paths, evidence sources, smoke command, default output, rules/prompts, and packaging status. Split to `docs/adapters/.md` only when the README matrix split triggers are met. - `.host-plugin/` or equivalent generated shell: install/discovery metadata only; default to no new shell unless an independent install or release lifecycle exists. - `.agents/skills//`: host-local skills, wrappers, or generated mirrors only; promote shared workflow judgment to root `skills/`. - `scripts//platforms/.mjs`: only when a capability needs host-specific evidence collection or normalization. - `scripts/npm-package/`: current package bundle and verification owner. - `scripts/packaging/`: source-local generated host artifact builder and verifier; generated output remains ignored and is never a canonical owner. ## Migration Gates - DX targets named by the [Developer Experience System ADR](developer-experience-system.md) begin inactive. ADR acceptance never activates them. The first DX implementation slice records the current baseline without creating target directories. `scripts/dx-contracts/` creates the report-only activation ledger only when that directory's own activation gate passes; each fact or policy slice then requires a dated spec, owner/parity evidence, reviewed cutover, and rollback before its target becomes authoritative. - Target directories need a first real asset plus the entry-specific gate below. If no entry-specific gate exists yet, the default minimum is validation evidence named in the change. For prose-only targets, validation evidence is a link/path check plus consumer-grep proof for any 2+ consumer claim. Runtime, parser, generator, and packaging surfaces also need tests or fixtures. - `knowledge-base/` needs `NOTICE.md`, `knowledge.md`, an interim `schema.json` matching the minimum shape above, fixtures, a namespace uniqueness check for community assets, and a migration note until the registry exists. - `docs/adapters/README.md` must keep the host matrix scan-friendly, name canonical roots, and include smoke commands or "not yet available" notes. A split `docs/adapters/.md` must link back to the matrix and explain which split trigger it satisfies. - `templates/reporting/`, `templates/style/`, `templates/components/`, and `templates/common/` require routing/parser tests and path-reference checks in the same migration. - Renaming established paths such as `references/agent-customize/` requires `rg` evidence for imports/references, redirect or deprecation notes where needed, and fixture or consumer updates in the same change. - Old owners may be deleted only after parity fixtures pass and `rg` shows no remaining imports/references outside a deprecation note. - Do not move files only for symmetry. ## Validation Gate Before accepting this ADR, run the host-local `.agents/skills/triangulate-spec-review/scripts/run-triad-review.mjs` in this repo or an equivalent manual review. Equivalent means the same prompt contract, the `complexity`, `convenience`, and `evolution` dimensions, JSON output from at least two available independent reviewers, and recorded timeout/error evidence for unavailable reviewers. Acceptance requires no `P1` or `P2` findings in the recorded review output. Store review JSON under `.harness/state/` or paste the structured summary in the change evidence. The runner is currently a host-local `.agents/skills/` workflow; promotion to root `skills/` requires a separate promotion change.