docs(#265): AgDR-0047 for framework packaging & distribution#343
Conversation
- Compares 6 packaging options: fork-as-install (status quo), release-tarball delivery, layered install, npm package, Homebrew formula, one-line install script - Pros / Cons / Migration cost columns per option, plus combination plays (2+3 staged, 3+4 layered, 3 + brand mitigation, 6 + any) - Recommendation leans option 3 (layered install) with brand-mitigation pattern; status quo explicitly NOT recommended - Decision section is PROPOSED; operator picks via PR comment - Body-H1 only, no YAML frontmatter (matches AgDR-0044/0045/0046 live convention; documents the drift from templates/agdr.md inline) Refs #265 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… count) in AgDR-0047 CI flagged 3 markdownlint errors on the initial push: - MD028 line 4: blockquote with bare blank-line separator (need `>` continuation) - MD056 lines 39-40: options 4 (npm) + 5 (Homebrew) missing the 5th "Migration cost" column cell — table header declares 5 columns, those two rows had only 4. Replaced the blank blockquote line with `>` continuation, filled the missing Migration cost cells with the medium-disruption rationale (npm: smooth for JS adopters, awkward for non-JS shops; Homebrew: brew tap + per-release formula bump, no Windows path). Refs #265
atlas-apex
left a comment
There was a problem hiding this comment.
Code Review: PR #343
Commit: d2d2a5ad825ad11a2657c0430d914098cb764243
Summary
Pure-docs PR adding docs/agdr/AgDR-0047-framework-packaging-and-distribution.md (114 lines, single file, zero deletions). Compares six packaging-strategy options for the framework — fork-as-install / release-tarball / layered install / npm / Homebrew / one-line install script — plus four combination plays. Recommends option 3 (layered install) with the "3 + brand mitigation" pattern but defers the actual call (status PROPOSED, operator picks via PR comment).
Checklist Results
- ✅ Architecture & Design: N/A (docs-only)
- ✅ Code Quality: Pass
- ✅ Testing: N/A (docs-only; markdown lint covered by CI)
- ✅ Security: Pass (no secrets, no executable changes)
- ✅ Performance: N/A
- ✅ PR Description & Glossary: Pass (8-row glossary, narrative bullets)
- ✅ Technical Decisions (AgDR):Pass (this PR is an AgDR — meta-Pass)
- ✅ Adopter Handbooks: N/A (architecture/general handbooks load but find no violations; no language diff)
Issues Found
None.
Spot-checks against the items called out in the review request
1. AgDR shape — body-H1 only, no YAML frontmatter, canonical one-liner present.
Verified. Line 1 is # AgDR-0047 — Framework packaging & distribution (body H1). No --- frontmatter delimiter at file start. Markdownlint MD025 cannot fire. The Metadata line (line 7) carries the body-H1-convention rationale inline, which is helpful for the next AgDR author who might be tempted to re-add frontmatter.
The canonical "In the context of … I am proposing … accepting …" one-liner is at line 3, present and complete. It correctly uses proposing (not decided) given the PROPOSED status — small but load-bearing tense choice that keeps the AgDR honest.
2. Six options + 5-column table — all cells populated.
Verified row-by-row: every option has Pros, Cons, and Migration cost filled. No empty cells. Specifically on the two cells called out in the fix-up commit (npm + Homebrew Migration cost):
- Option 4 (npm) Migration cost: "JS/TS adopters adopt smoothly via
package.json; non-JS shops bear awkwardness or skip; framework ships an npm-publish CI step on release tag." Accurate — the adopter-side cost is heterogeneous (JS shops vs others), and naming the framework-side cost (npm-publish CI step) is the right level of detail for a PROPOSED options table. - Option 5 (Homebrew) Migration cost: "
brew tapsetup + per-release formula bump; Windows adopters unsupported (no migration path); needs an additional distribution channel." Accurate and surfaces the Windows gap that's already a known framework constraint (perlink-custom-skills.sh). Not misleading.
Both cells are consistent with their respective Pros/Cons cells — no contradictions.
3. PROPOSED status with explicit operator-pick-via-PR-comment guidance.
Verified. The Decision section opens with "PROPOSED — awaiting operator pick via PR comment." and enumerates five concrete inputs the operator should weigh in on (option pick, brand-visibility mitigation shape, staged vs single-step, migration story, install-script timing). The status appears coherently in three places: the one-liner blockquote tense, the Metadata line, and the Decision header — no drift between them.
4. Consequences section captures the v1 risks.
Verified. Lines 90–95 explicitly call out:
- Migration path articulation must precede implementation (with the
/split-portfolioprecedent named — the right reference shape) - Compounding implementation cost ("every new skill, hook, or rule from the date this AgDR lands implicitly assumes the chosen packaging model")
- Reversibility-but-rising-cost-over-time
These match exactly the three risks the ticket scope called out. The per-option sketches that follow are appropriately tagged as "placeholders to be expanded in the chosen-option follow-up AgDR" — they don't pre-decide.
5. PR body Glossary + narrative bullets.
Verified. Four bullets in the Summary, each answering both what changed AND why it matters per .claude/rules/pr-quality.md. No label-only bullets. Glossary has 8 rows covering every framework-specific or load-bearing term (AgDR PROPOSED status, fork-as-install, layered install, XDG, breaking change, migration path, version pin, brand visibility) — comfortably above the "every technical term explained" bar.
Suggestions
Two small nice-to-haves, neither blocking, neither expected to be addressed in this PR:
-
Combination 3 + 4 ("layered + npm as delivery channel") is a strong combination play but currently lives only in the prose subsection. If the operator's eventual pick is "option 3 + option 4 as delivery channel", the Decision section's bullet list might need one more input slot. Not a current-PR fix — flagging for the follow-up AgDR that records the pick.
-
The "PR: (will be filled in once opened)" placeholder in the Artifacts section is fine for a PROPOSED AgDR but worth remembering to populate when this lands (or when the ACCEPTED-rewrite PR opens). The framework convention from sibling AgDRs (0044/0045/0046) is to link the merging PR. Operator's call — could be addressed in the ACCEPTED follow-up rewrite.
On PR #267 (the superseded draft)
Per the review request — flagging that PR #267 (currently draft state) carries the same scope but with the wrong AgDR number (0029, which is already taken). Operator's call to close it as superseded post-merge here. No action needed in this PR.
Verdict
APPROVED (recorded as a --comment because GitHub blocks self-approve on author-owned PRs)
The AgDR is structurally clean, honest about the trade-offs, deferential on the actual decision, and explicit about the cost of not deciding. The two cells the author flagged for verification (npm + Homebrew Migration cost) are accurate and non-misleading. CI is 3/3 green.
Ready to merge from the code-review side. Per pr-workflow.md, the merge itself still requires an explicit per-PR CEO approval via /approve-merge 343 — plan-level "go" does not authorise the merge.
🤖 Reviewed by Rex (Code Reviewer Agent)
📌 Reviewed commit: d2d2a5ad825ad11a2657c0430d914098cb764243
* docs(#265): AgDR-0047 framework packaging & distribution (proposed) - Compares 6 packaging options: fork-as-install (status quo), release-tarball delivery, layered install, npm package, Homebrew formula, one-line install script - Pros / Cons / Migration cost columns per option, plus combination plays (2+3 staged, 3+4 layered, 3 + brand mitigation, 6 + any) - Recommendation leans option 3 (layered install) with brand-mitigation pattern; status quo explicitly NOT recommended - Decision section is PROPOSED; operator picks via PR comment - Body-H1 only, no YAML frontmatter (matches AgDR-0044/0045/0046 live convention; documents the drift from templates/agdr.md inline) Refs #265 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: fix markdownlint MD028 (blockquote blank) + MD056 (table column count) in AgDR-0047 CI flagged 3 markdownlint errors on the initial push: - MD028 line 4: blockquote with bare blank-line separator (need `>` continuation) - MD056 lines 39-40: options 4 (npm) + 5 (Homebrew) missing the 5th "Migration cost" column cell — table header declares 5 columns, those two rows had only 4. Replaced the blank blockquote line with `>` continuation, filled the missing Migration cost cells with the medium-disruption rationale (npm: smooth for JS adopters, awkward for non-JS shops; Homebrew: brew tap + per-release formula bump, no Windows path). Refs #265 --------- Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Summary
docs/agdr/AgDR-0047-framework-packaging-and-distribution.md— proposes a packaging-strategy decision with six options compared (fork-as-install / release-tarball / layered install / npm / Homebrew / one-line install script) plus combination plays. The Options table is the load-bearing artefact — Pros / Cons / Migration cost columns per option so the operator can pick without diff archaeology.README.md+ registry-at-fork-root so the brand-visibility concern that motivated the original fork-as-install model stays mitigated. The recommendation is honest about the breaking-change migration cost for existing adopters — every adopter would need a/migrate-to-layeredskill (shaped like/split-portfoliofrom [Feature] /split-portfolio migration helper skill (follow-up to #143) #146) before their next framework update.title:+ body H1 together — the drift fromtemplates/agdr.mdis documented inline in the AgDR's metadata section).Testing
docs/agdr/AgDR-0047-*.mdis unique ondev(verified againstupstream/devat branch-create time).markdownlint.jsondisables MD013 / MD024 / MD025 surfaces this AgDR could trip)AgDR-0007,AgDR-0021,AgDR-0023)Closes #265
Glossary
docs/agdr/AgDR-NNNN-<slug>.md. The framework's per-decision durable artefact.me2resh/apexyardon GitHub, clones the fork locally, and syncs updates viagit pull upstream+ the/updateskill. Framework files live in the adopter's git tree alongside their customisations.~/.local/share/<app>/), config (~/.config/<app>/), and cache (~/.cache/<app>/). One candidate layout for layered install's base + overlay split..claude/,roles/,workflows/,templates/under a new install dir./split-portfolio(#146) — explicit destructive-recovery flow with operator-confirmation gates, idempotent re-runs, default-nodry-runmode.git logon the fork. Layered install would make this explicit via a manifest file (framework_version: 1.3.0) so skills declaringrequires framework ≥ Ncan be checked mechanically at runtime..apexyard/dotfile dir invisible tolsand GitHub views; v1 moved to fork-as-install partly to fix this. Any new packaging model must preserve discoverability — typically via a visible install-dir name + fork-rootREADME.mdnaming the framework + registry-at-fork-root.