ADR-142/143/144: agent-ways 1.0 — XDG application distribution#202
Merged
Conversation
Draft spine ADR-142 (XDG application distribution: state taxonomy, manifest-driven projection, flip-the-default superseding ADR-140 defaults, one-engine/four-from-states, autonomy gradient, auto-update, deprecation lifecycle) plus two children: ADR-143 (three-root core/user/project runtime) and ADR-144 (install/repair/migrate as one manifest reconciler). Claude-Session: https://claude.ai/code/session_01TFyiQNDZ8RTMHX4Tnmp1wY
Add "Bootstrap via a thin marketplace plugin" to ADR-144's Alternatives Considered — a viable alternative (not the decision; the self-sufficient copied/stable-path entrypoint stands). Captures the documented auto-firing plugin SessionStart hook, that it relocates rather than eliminates the bootstrap exemption, the corrected risk-ranking (plugin-subsystem coupling, not the exemption, is the headline risk), three hard constraints, and the discoverability payoff. Cross-references ADR-133. Stays Status: Draft. Claude-Session: https://claude.ai/code/session_01TFyiQNDZ8RTMHX4Tnmp1wY
…en question) Per review decision: all four XDG tiers share the agent-ways name. The cache, which exists today as claude-ways/, is renamed by the reconciler (regenerable, so a missed rename costs only a rebuild). Retires the naming Open Question.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Draft for review — three Draft-status ADRs proposing the most significant architectural change since the project's origin: agent-ways stops living in
~/.claudeand becomes an XDG application that projects into it. Authored bysystem-architect, grounded against the real repo (not just a brief). No code — decision records only.The set
ADR-142 — agent-ways 1.0: XDG application distribution (spine)
Identity shift:
~/.claudebecomes a thin, regenerable, Claude-Code-owned projection surface. Core decision is the state taxonomy — DATA (app, replaced wholesale) / CONFIG (user, never touched) / STATE (session substrate, survives wipe) / CACHE (derived) /~/.claude(projection). Durability + ownership become structural, so "can we auto-update?" becomes a lookup, not a judgment call. Also: manifest-driven projection (symlink default / copy fallback / git-derived), flips the default and supersedes ADR-140's defaults only, one-reconciler/four-from-states, the autonomy gradient, and the population-independent deprecation lifecycle (1.1.0 as a per-user update-gate; "remove the migrator" safe by construction).ADR-143 — Three-root way runtime: core, user, project
Splits today's single "global" root into core (DATA) + user (CONFIG); precedence
project > user > core, dedup-by-name, shadow-a-shipped-way-without-forking. Inserts a user tier into the existing two-tier precedence (not new machinery).ADR-144 — Install/repair/migrate as one manifest reconciler
One idempotent reconciler; git-derived manifest (an elevation of the existing
.claude-source-manifest); the self-sufficient bootstrap exemption (the healer can't be a link into the tree it heals); gated, crash-safe migrator; git-as-migration-ground-truth.Open decisions to resolve in review
related: [[ADR-141]]dangles until that lands. Numbering reserved 141 for it. → merge ADR-141: Knowledge graph as evidential memory backend #198 first?~/.cache/claude-ways/; proposed data/config/state areagent-ways. Parked as an Open Question rather than silently harmonized. → harmonize toagent-ways?The two honest leaks (in each ADR's Consequences/Negative — managed, not solved)
settings.jsonmerge — the one shared-write seam; two writers on a file agent-ways doesn't own. The single place separation genuinely breaks.Grounding findings (where the real repo refined the design)
Manifest already exists (copy-only, filesystem-enumerated → elevate to git-derived); precedence already project>global (insert user tier);
way-embedalready the copy-not-symlink binary (validates the bootstrap exemption); XDG cache leg already correct. Net: this completes a separation the codebase already started, not a from-scratch reorg.Related: ADR-140 (supersedes defaults), ADR-141 (#198), ADR-112, ADR-128.