docs(ai-briefing): profiled rich-config convention + engine/profile split design

[kyle-sexton]

Codifies the design(ai-briefing) gate — the generic engine plugin + extracted-profile design and the general profiled rich-config convention that ai-briefing is the reference adopter of.

What lands

• Playbook seam-2 amendment (docs/MIGRATION-PLAYBOOK.md) — the profiled-folder convention: files at .claude/<plugin>/ are the default profile; .claude/<plugin>/<name>/ subfolders are additive named overlays. Root-is-default means single-config consumers never nest and growing a profile later is additive, never a reorg. One-increment PRECEDENT-EXTENSION of the tracked-rich-config folder form; composes with the concern-named folder.
• docs/ai-briefing-design.md — the engine/profile/personal split, branding scrub, overridable ranking-policy defaults, interim medley-cutover home, and the deferred dedicated-SETWorks-repo record with a revisit trigger.
• README — design note wired into the docs list.

Decisions (owner, interview mode, 2026-07-12)

• Publish the generic engine as a plugin; extract SETWorks specifics into a named profile.
• Profile home: interim = medley (tracked .claude/ai-briefing/setworks/, plugin enabled) via a cutover; dedicated SETWorks repo deferred (clean tracked→tracked move later, no republish).
• Ranking-policy defaults (pragmatic-use lens + apolitical filter) ship as documented overridable engine defaults; only the setworks_impact stack lens is profile-only.
• Branding: neutral engine default + provider logos; SETWorks logos/tokens/spec → profile.

Emitted issues (self-contained; do not depend on this note)

• publish(ai-briefing) — author the engine plugin.
• cutover(ai-briefing) (medley) — shed the skill, move the profile, enable the plugin, reconcile CI/typos/html-artifacts surfaces; blocked on publish, appended to sweep.

Refs melodic-software/medley#1392

---

Note

Low Risk
Documentation-only changes to playbook, a new design record, and README; no runtime or plugin code.

Overview
Adds documentation for the ai-briefing migration gate and a reusable profiled-folder tracked-config pattern.

docs/MIGRATION-PLAYBOOK.md extends seam 2 with profiled folders: .claude/<plugin>/ is the default profile; .claude/<plugin>/<profile-name>/ overlays it per key. Profile selection uses one present folder, else active_profile or --profile, else root. This is distinct from concern-named folders (multi-plugin) and composes with them. ai-briefing is named as the reference adopter.

docs/ai-briefing-design.md records splitting the in-repo skill into a generic engine plugin, a SETWorks named profile (interim home medley at .claude/ai-briefing/setworks/), and personal state in ${CLAUDE_PLUGIN_DATA}. It documents overridable engine ranking defaults, branding scrub, deferred dedicated SETWorks repo triggers, and follow-on issues publish(ai-briefing) and cutover(ai-briefing).

README.md lists the new design doc in the docs index.

^{Reviewed by Cursor Bugbot for commit 7aa3794. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_3a865c7c-3fa0-4f68-bbf2-657d12f74bbe)

[claude]

Claude finished @kyle-sexton's task in 1m 59s —— View job

---

PR Review

• Gather context and read changed files
• Review MIGRATION-PLAYBOOK.md changes
• Review ai-briefing-design.md (new file)
• Review README.md change
• Post final review

---

Summary

Pure documentation PR — no executable code, no plugin manifests, no schema changes. Changes are internally consistent and well-grounded in the existing playbook conventions. Ready to merge with one minor wording note.

---

docs/MIGRATION-PLAYBOOK.md — Profiled folder sub-bullet (lines 140–155)

Looks good overall. The addition correctly sits as a third sub-bullet under seam 2, tagged in prose as "a one-increment PRECEDENT-EXTENSION of the folder form" — consistent with how the existing "Concern-named folder" sub-bullet signals its own classification.

One minor wording ambiguity: The selection rule reads:

exactly one profile folder present → use it

Within .claude/<plugin>/, both the root itself and its named subfolders are "folders," so "exactly one profile folder present" could be read as "the .claude/<plugin>/ folder exists" — which is always true once any file is there. The intended meaning is clearly one named profile subfolder, but tightening to "subfolder" or "named profile subdirectory" would remove any ambiguity for a reader skimming the resolution ladder.

Compose clause is intentionally thin: The statement "the two compose (.claude/<concern>/<profile-name>/)" names the composed path without specifying the overlay semantics for that form. That's appropriate here — it's a design record noting the shapes are composable, not a spec for every downstream case. A plugin author hitting that case would need to spell out semantics in their own convention doc (per the concern-named folder pattern), which the existing "docs/conventions//" template already handles.

Relative link: [ai-briefing](ai-briefing-design.md) at line 155 — both files live in docs/, so this resolves correctly on GitHub.

---

docs/ai-briefing-design.md (full file)

Design decisions are internally consistent and well-reasoned:

• Three-tier split (engine / employer profile / personal state) maps cleanly to the three plugin persistence mechanisms (CLAUDE_PLUGIN_ROOT, ${CLAUDE_PROJECT_DIR}/.claude/ai-briefing/, ${CLAUDE_PLUGIN_DATA}).
• Ranking-policy defaults are correctly scoped: documented + overridable at the engine level, setworks_impact lens profile-only. The distinction between "documented overridable defaults" vs "silent behavior" aligns with the playbook's "configurable-by-default, safe documented defaults" standard.
• Branding scrub logic is correct: provider logos (used nominatively) stay in the engine; SETWorks-specific assets move to the profile.
• The interim medley home rationale is solid: tracked-and-backed-up beats machine-local, the move is git mv (reproducible, not a manual copy), and the content already lives in a private repo — reorg not new exposure.
• The deferred dedicated-repo path includes a clear revisit trigger with a concrete action ("file a repo(setworks-briefing) issue"). Well-formed deferral record.

Setup action requirement: The doc correctly states "The plugin ships a re-runnable setup action … (the contract requires it for any tracked-config seam)" — this matches the playbook's mandate.

Personal state scoping: ${CLAUDE_PLUGIN_DATA} for personal state (seen-items registry, generated decks) is correctly using seam 4's machine-state path, not leaking personal data into seam 2's tracked config.

Missing hyperlink (non-blocking): The profile mechanism section references "see the migration playbook, 'Extensibility contract v2.1 — the four seams', seam 2" in prose but doesn't link to the playbook. A relative link like [migration playbook](MIGRATION-PLAYBOOK.md) would help navigability, but this is cosmetic.

Decay warning is well-placed: The opening note ("Empirical claims decay — re-verify the medley-side surfaces named here before executing the cutover") is a good defensive header given the CLAUDE.md fresh-docs mandate. The emitted issue bodies are the executable artifacts; this file is the rationale layer.

---

README.md (line 73)

The new line correctly describes the file's role ("reference adopter of the profiled-folder convention") and is inserted in the right position in the docs list. No issues.

---

Verdict

The profiled-folder seam extension is well-motivated, keeps the "one-increment" constraint relative to existing precedent, and ai-briefing-design.md is a complete decision record. The only actionable item is the "folder" vs "subfolder" wording in the selection ladder — small enough to fix here or in the publish(ai-briefing) PR. No blocking issues.

[cursor]

Risk: low. Did not approve because Cursor Bugbot did not complete successfully (check skipped; usage limit reached). Human review is needed for this docs-only PR; no reviewers were assigned.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}