ARCHITECTURE.md v2 Revision
Track: arch-md-v2-20260428
Type: chore (docs)
Overview
Rewrite the load-bearing sections of ARCHITECTURE.md to reflect the athens-v2 architectural pivot: replace the static-install pipeline (detect → resolve → fetch → convert → write Markdown to .claude/skills/spring-*/) with a dynamic-loading skill that delegates to @pleaseai/ask at runtime to fetch Spring reference content from GitHub on demand.
This is a docs-only track. No source files are added, modified, or removed. The track exists so that the v2 direction is documented in the same planning PR that introduces it (sibling tracks: plugin-scaffold-20260428, build-file-detect-20260428), preventing a window where the implementation lags the architecture document or vice versa.
ARCHITECTURE.md is currently the team's single bird's-eye view of the system. After this revision, a reader should be able to open ARCHITECTURE.md and reach a complete and correct understanding of the v2 install model without cross-referencing track specs or PR descriptions.
Scope
Sections to rewrite
- § System Overview — replace the static-pipeline narrative with the dynamic-loading model. Explain that install produces a thin per-component skill that, at the moment Claude Code invokes it, calls
@pleaseai/ask to fetch the relevant Spring reference content from upstream GitHub at the resolved version ref.
- § Entry Points — remove "the install pipeline" framing as a sequence ending in conversion; replace with two distinct entry points: (1)
/spring:install writes thin skills, (2) skill invocation at runtime delegates to @pleaseai/ask. Each entry point's "first file to read" pointer needs updating.
- § Module Reference — remove rows for
prebuilt/ and any Antora-conversion library scaffolding that was justified solely by the static pipeline. Add a row for the runtime @pleaseai/ask boundary (likely a thin wrapper module under scripts/lib/ask-bridge.ts or similar — exact file naming is the implementing track's call). Update existing rows to reflect that scripts/fetch.ts no longer exists; the corresponding domain function in v2 is a skill-manifest writer, not a doc fetcher/converter.
- § Architecture Invariants — remove invariants that pertained only to the static pipeline (Antora conversion, prebuilt archive sha256, nightly-build idempotency, etc.). Add invariants that protect the v2 model: (a) install-time output is metadata only (no Markdown bodies); (b) the
@pleaseai/ask call is the single network boundary at runtime; (c) the resolved Boot version pins the GitHub ref used by ask (no drift between detected version and fetched content).
Sections to add
- § Install Model (v2) — new section explaining the install-time vs. runtime split, the data flow from detection through
@pleaseai/ask, and the contract between the spring plugin and @pleaseai/ask (what shape the spring plugin's skill manifest takes, what ask is asked to do).
Sections to leave untouched
- § Cross-Cutting Concerns — most content (error handling, logging, security boundaries) carries over; only the "doc conversion" subsection (if present) is replaced with the runtime-fetch equivalent.
- § Quality Notes — review for stale references but do not rewrite as a whole.
- Headings outside the listed sections must be preserved verbatim so cross-PR references still resolve.
Coordination with sibling tracks
plugin-scaffold-20260428 spec already promised that ARCHITECTURE.md would be revised in a separate track and that scaffold should not touch it. This track delivers on that promise. The order in which the three tracks merge does not matter for correctness, since this track is docs-only and the scaffold track touches no overlapping files.build-file-detect-20260428 spec is architecture-agnostic (the DetectResult contract is the same in both pipelines), so this revision does not change anything that detect-track depends on.
Success Criteria
Constraints
- Docs-only: zero changes outside
ARCHITECTURE.md and (optionally) cross-references in README.md if they describe install behavior in incompatible terms. Code, configs, manifests, and tests are untouched.
- Preserve existing heading anchors unless a heading is being explicitly removed. Renaming a kept heading would break external references with no commensurate gain.
Track: arch-md-v2-20260428
Type: chore (docs)
Phase: planning (PR for team review)
Sibling tracks: plugin-scaffold-20260428 (#3), build-file-detect-20260428 (#4)
Merge order: independent — no overlap with sibling tracks
See full spec: .please/docs/tracks/active/arch-md-v2-20260428/spec.md
See plan: .please/docs/tracks/active/arch-md-v2-20260428/plan.md
ARCHITECTURE.md v2 Revision
Overview
Rewrite the load-bearing sections of
ARCHITECTURE.mdto reflect the athens-v2 architectural pivot: replace the static-install pipeline (detect → resolve → fetch → convert → write Markdown to.claude/skills/spring-*/) with a dynamic-loading skill that delegates to@pleaseai/askat runtime to fetch Spring reference content from GitHub on demand.This is a docs-only track. No source files are added, modified, or removed. The track exists so that the v2 direction is documented in the same planning PR that introduces it (sibling tracks:
plugin-scaffold-20260428,build-file-detect-20260428), preventing a window where the implementation lags the architecture document or vice versa.ARCHITECTURE.mdis currently the team's single bird's-eye view of the system. After this revision, a reader should be able to openARCHITECTURE.mdand reach a complete and correct understanding of the v2 install model without cross-referencing track specs or PR descriptions.Scope
Sections to rewrite
@pleaseai/askto fetch the relevant Spring reference content from upstream GitHub at the resolved version ref./spring:installwrites thin skills, (2) skill invocation at runtime delegates to@pleaseai/ask. Each entry point's "first file to read" pointer needs updating.prebuilt/and any Antora-conversion library scaffolding that was justified solely by the static pipeline. Add a row for the runtime@pleaseai/askboundary (likely a thin wrapper module underscripts/lib/ask-bridge.tsor similar — exact file naming is the implementing track's call). Update existing rows to reflect thatscripts/fetch.tsno longer exists; the corresponding domain function in v2 is a skill-manifest writer, not a doc fetcher/converter.@pleaseai/askcall is the single network boundary at runtime; (c) the resolved Boot version pins the GitHub ref used byask(no drift between detected version and fetched content).Sections to add
@pleaseai/ask, and the contract between the spring plugin and@pleaseai/ask(what shape the spring plugin's skill manifest takes, whataskis asked to do).Sections to leave untouched
Coordination with sibling tracks
plugin-scaffold-20260428spec already promised that ARCHITECTURE.md would be revised in a separate track and that scaffold should not touch it. This track delivers on that promise. The order in which the three tracks merge does not matter for correctness, since this track is docs-only and the scaffold track touches no overlapping files.build-file-detect-20260428spec is architecture-agnostic (theDetectResultcontract is the same in both pipelines), so this revision does not change anything that detect-track depends on.Success Criteria
ARCHITECTURE.mdcold can describe the v2 install model in one paragraph without referring to any other file.ARCHITECTURE.mdagrees with every other section. There are no places where one section describes the static pipeline and another describes the dynamic one. (Reviewer-verified; no automation.)ARCHITECTURE.md. Every[text](#section)resolves to an existing heading; every relative link to a sibling file (README.md,.please/docs/knowledge/*.md) points at a file that still exists. (Verified bybun run lint:mdif a markdown linter is wired by the time this lands; otherwise manual.)prebuilt/,antora-rules.ts, "HTML → Markdown conversion", "nightly archive build", andscripts/fetch.ts(in the static-pipeline meaning) are removed from the document. Searching the post-revision file for any of these strings returns zero matches in the body — they may appear only inside an explicit "removed in v2" sidebar or migration note, if such a note is included.@pleaseai/ask.asklets the plugin focus on detection/resolution and reuse a generic doc-fetching primitive). This is for reviewer context, not for inclusion inARCHITECTURE.mditself.Constraints
ARCHITECTURE.mdand (optionally) cross-references inREADME.mdif they describe install behavior in incompatible terms. Code, configs, manifests, and tests are untouched.