jared
/
cc-os
1
0
Fork 0
Code Issues 17 Pull Requests Packages Projects Releases Wiki Activity
cc-os/docs/adr-system/01-current-state-survey.md

11 KiB
Raw Permalink Blame History

Current-State Survey: ADR Practices Across ~/dev/ Projects

Last updated: 2026-07-03

Survey of every project directory under ~/dev/ for existing Architecture Decision Record practices. Read-only audit; no files were changed. Source: agent survey, 2026-07-03.

Projects with formal ADRs

cc-os

  • Organization: monolithic — docs/memory-system/03-architecture-decisions.md, 601 lines, 19 ADRs (this repo, before this research phase).
  • Naming: ADR-NNN heading per entry within the single file.
  • Template fields: Context · Decision · Rationale · Alternatives rejected · Status. Supersession noted inline ("Superseded by ADR-010", "Refined by ADR-011").
  • Tooling: none; plain markdown. _Last updated:_ date at top of file.

viking-warrior-training-log

  • Organization: one file per decision — docs/adr/, 6 files + README.md index.
  • Naming: NNNN-kebab-case-title.md (e.g. 0001-pocketbase-backend.md).
  • Template fields: Status · Date · Context · Decision · Consequences · Alternatives considered. Files are 30–41 lines.
  • Tooling: README.md index — a table of all ADRs with title + status. Explicitly notes ADRs 0001–0003 were backfilled after the fact; 0004–0006 record refinements after critique.
  • This is the only project with both per-file organization AND a maintained index.

delta-refinery

  • Organization: one file per topic (not numbered) — docs/decisions/, 12 files, 25–48 lines each.
  • Naming: topic-driven kebab-case (bin-lint-fix.md, map-driven-design-system.md).
  • Template fields: Status · Decided (date) · Decision · Why · What Was Built (artifact table) · Open Questions · "Delete this document when" (a sunset/supersession condition instead of an explicit supersedes/superseded-by field).
  • Tooling: none.

design-mode

  • Organization: one file, dated — docs/decisions/2024-12-jsx-conversion-pivot.md (only 1 decision recorded), 78 lines.
  • Naming: YYYY-MM-topic-kebab.md.
  • Template fields: Date · Status · Context · Problem · Decision · Implementation (Keep/Remove/Update subsections) · Open Questions · Lessons Learned (a retrospective field not seen elsewhere in this survey).
  • Tooling: none.

llf-schema

  • Organization: mixed — docs/decisions/, 6 files (18–134 lines), but several files embed multiple numbered decisions rather than one-per-file.
  • Naming: YYYY-MM-DD-topic-kebab.md at the file level; D-NNN numbering for individual decisions embedded within a file (at least D-038 through D-043+ found).
  • Template fields: Status · Context · Decision · Consequences; some have an "Open sub-decision" pattern with explicit options + rationale.
  • Tooling: cross-links into the project's openspec/changes/... spec-driven change system — the only project doing this. One file (2026-06-04-plugin-decision-index.md) acts as a superseded historical index pointing to newer sub-documents.

cc-plugins

  • Organization: decisions embedded in prose within larger design docs, not a dedicated ADR directory. progressive-disclosure/docs/gaps-and-decisions.md (297 lines) numbers decisions inline ("Decision 26: Single entry point").
  • Template fields: narrative Decision / Why / mechanics — no structured Status/Context fields as distinct headings.
  • Notable: the whole document is marked (LOCKED) — a document-level freeze convention instead of a per-decision status field.

Projects without formal ADRs

Project Notes
playground No docs/; minimal project.
remetrics Has a README; no decision docs.
ruby-gems Umbrella dir, 10 sub-repos checked; none have ADRs.
thinkfast CLAUDE.md references "architectural decisions" as a task category but no ADR files exist.
verona-vocab Has CLAUDE.md; no decision docs.
websites Umbrella dir (hyperthrive, hyperthrive-strategy checked); none have ADRs.
wordpress-dc No docs/.
hyperthrive_dev Uses ad hoc .scratch/active/progress.md subagent handoff logs instead of ADRs.
llf-schema-build-tmp Throwaway build directory, not a persistent project — excluded from future onboarding.

Addendum: ~/clients/ and ~/projects/

The first pass covered ~/dev/ only. A second pass surveyed ~/clients/ (inovis-lighting-audit-manager, philly-search-engine-marketing, summit-new-hire-automation, virtuosocontent) and ~/projects/ (niche-automation-prospecting, taxes-swanson). This surfaced a distinct organizational pattern from ~/dev/ — worth treating as its own category, not merging into the table above.

Client projects (~/clients/)

  • inovis-lighting-audit-manager: no ADRs, nothing adjacent.
  • philly-search-engine-marketing: monolithic root-level DECISIONS.md (236 lines, 14 decisions), plus two secondary dated docs for specific incidents. Per-decision fields: date + title heading, Status: (Confirmed/Deferred), Category: ([Tech]/[Business]), Source: (attribution), then narrative Goal/Decision/Reasoning/Residual-or-Deferred-notes. Explicitly referenced from CLAUDE.md's quick-reference table as "Past decisions" — i.e. treated as a canonical, actively-pointed-to file.
  • summit-new-hire-automation: not really an ADR — one post-hoc "decision framework" document (n8n vs Rails) that's a retrospective/lessons-learned analysis of a platform choice already made, including a decision matrix and red-flag checklist for future similar choices. ADR-adjacent, not an ADR.
  • virtuosocontent: monolithic root-level DECISIONS.md, but minimal — 10 lines, 2 decisions, just a date+title heading and a one/two-line factual statement (no Status, Category, or reasoning fields at all).

Personal/internal projects (~/projects/)

  • niche-automation-prospecting: no dedicated decisions file; decisions are scattered inside timestamped working documents — logs/increments/2026-05-26-*-decisions.md and a PHASE4-DECISION-MEMO.md — organized by project phase/event (executive summary, tier score-snapshot tables, "clear kills," next steps) rather than as discrete Status-tagged entries. ~20 decisions total across the two files, but as narrative sections, not an ADR list.
  • taxes-swanson: no ADRs, nothing adjacent.

What's different here vs. ~/dev/

  1. Client projects favor one monolithic root-level DECISIONS.md, not a docs/decisions/ or docs/adr/ directory — the opposite of the ~/dev/ majority pattern (one-file-per-decision in a subdirectory). Likely driver: a client-facing single readable log is easier to hand off or reference during a client conversation than a directory of numbered files, and these projects are shorter-lived/smaller in decision count (2–14) than cc-os's 19.
  2. Client DECISIONS.md files use a Status: field (Confirmed/Deferred) that tracks whether a decision is still locked-in — a business/client-relationship framing distinct from the Accepted/Superseded lifecycle framing used in ~/dev/ (ADR-013/ADR-018-style projects).
  3. Internal (~/projects/) decision-adjacent docs skip Status entirely and are organized as phase/incident narratives (a "worklog," not an architectural record) — closer to hyperthrive_dev's .scratch/active/progress.md pattern from the ~/dev/ survey than to any ADR convention.
  4. The no-ADR baseline holds: 3 of 6 (inovis-lighting-audit-manager, taxes-swanson, and arguably summit-new-hire-automation) have nothing ADR-like, roughly matching the ~60% no-ADR rate found across ~/dev/.

Implication for plugin design: a future os-adr plugin likely needs two supported shapes, not one-size-fits-all — a lightweight monolithic DECISIONS.md mode (small decision counts, client-facing/handoff-friendly, business Confirmed/Deferred status framing) alongside the per-file docs/adr/+index mode recommended for larger personal/tooling projects. Forcing the ~/dev/-style per-file convention onto a 2–14-decision client project would likely be over-engineering relative to what those projects need.

Cross-project comparison

Organization pattern, by frequency:

  1. One file per decision in a dedicated directory — viking-warrior-training-log, llf-schema (partially), design-mode (only 1 file so far, same shape). Most common approach once a project has more than a couple of decisions.
  2. Monolithic single file — cc-os only, and only this repo has reached a high ADR count (19) while staying in one file; still, that file is now 601 lines and prompted this research.
  3. Embedded in prose within other docs — cc-plugins. Lowest discoverability; no per-decision status field.

Naming, by frequency:

  • Sequential numeric (0001-, ADR-NNN, D-NNN): cc-os, viking-warrior-training-log, llf-schema — 3 of 6.
  • Topic-only kebab-case, no number: delta-refinery.
  • Date-prefixed: design-mode, llf-schema (at the file level).
  • Inline prose numbering: cc-plugins.

Template fields, by prevalence (of the 6 projects with any ADR-like content):

Field Count Projects
Decision 6/6 all
Status 5/6 all but cc-plugins
Context 5/6 all but cc-plugins
Consequences 4/6 viking-warrior-training-log, design-mode, llf-schema, cc-plugins ("Why")
Alternatives (rejected/considered) 3/6 cc-os, viking-warrior-training-log, design-mode
Rationale 2/6 cc-os, delta-refinery
Date 4/6 viking-warrior-training-log, delta-refinery, design-mode, llf-schema

Key observations:

  • No two projects use an identical template — field names and ordering vary even where the underlying concept (e.g. "why we rejected X") is the same.
  • Supersession handling is ad hoc everywhere: cc-os uses inline prose notes, delta-refinery uses a sunset condition ("delete this document when…"), viking-warrior- training-log uses a status column in its index, llf-schema uses an explicit open/settled status field. No project has a formal supersedes: / superseded-by: field.
  • Indexing is rare: only viking-warrior-training-log (README table) and cc-plugins (a locked index-like document) have anything resembling a discoverability index. Every other project relies on ls/grep of the directory.
  • None of the 6 projects use ADR tooling (adr-tools, log4brains, etc.) — all are hand-authored markdown.
  • 9 of 15 ~/dev/ projects have no ADRs at all — future onboarding candidates once a plugin exists (per this repo's own ADR-013 precedent: build-first, then migrate/onboard one project at a time rather than batch-migrating everyone). Across the ~/clients/+~/projects/ addendum, 3 of 6 also have none — a consistent ~55-60% no-ADR baseline across every category surveyed.
  • Client-facing and personal/internal projects (see addendum above) use a visibly different shape than ~/dev/ tooling projects: a single monolithic root DECISIONS.md rather than a per-file directory, smaller decision counts (2–14 vs. cc-os's 19), and — for client projects — a business-framed Status: Confirmed/Deferred field rather than an Accepted/Superseded lifecycle field. A future plugin needs to support this as a distinct, legitimate mode, not treat it as an under-developed version of the ~/dev/ pattern.