Narrow plugin scope — extract engineering-workflow skills from cairn-notes

[SnowboardTechie]

Problem / Motivation

v0.6.0 reframed cairn-notes around capture and storage (commits c5a0b7c, 6f16491, 02d11f3). The plugin's "north star" — per AGENTS.md Capture Triggers and the new /capture + /recall surfaces — is low-friction note capture and retrieval, not generalized engineering automation.

Several skills in plugins/cairn-notes/skills/ are inherited from earlier framings and don't pass the capture-first test ("does this skill produce or retrieve a vault artifact?"). They're useful skills, but they overstretch what the plugin is for, dilute the README/plugin description, and force every install of cairn-notes to ship engineering tooling a notes-only user doesn't need.

Notable self-tell: issue-work/SKILL.md frontmatter already says "Standalone — does not require any specific note system... writes state under ~/.claude/issue-work/ (not the notes vault)." The skill itself signals it doesn't belong.

Proposed behavior

Extract the engineering-workflow skills out of plugins/cairn-notes/skills/ and into plain skills (either standalone ~/.claude/skills/ skills or a sibling plugin under plugins/). The cairn-notes plugin retains only skills that produce or retrieve a vault artifact (capture/storage focus).

After extraction, the cairn-notes plugin skill list reads cleanly as a capture system:

capture, recall, cairn-notes (note types), obsidian, agent-workspace,
meeting-sync, session-review, workday-planning, weekly-planning

Spokes (scribe, archivist, pyre, forge, kindle, sage) stay — all support the capture/planning skills above.

Scope

In scope — extract

Skill	Why	Notes
dependency-review	Pure dependency-PR review; no vault artifact	Standalone candidate
dependency-triage	Pure dependency-PR triage; no vault artifact	Standalone candidate
pr-self-review	Three-lens parallel PR review; no vault artifact	impl-reviewer spoke leaves with it (partly — see issue-work)
ship	Push branch + open PR; git/PR workflow	Standalone candidate
issue-work	Ticket → implementation; frontmatter self-declares standalone	ticket-analyst spoke leaves with it; takes the remainder of impl-reviewer
update-pr-description	Edits a PR body; no vault artifact	Standalone candidate

Borderline — discuss before deciding

• issue-create — produces a GitHub issue, not a vault note. But AGENTS.md L156 explicitly routes session-review's plugin-misbehavior signal through /issue-create. Extracting it forces session-review to call across the plugin boundary, which complicates the dependency graph. Options: (a) keep issue-create as a "capture-adjacent" skill on the grounds that it captures plugin-improvement signal; (b) extract it and have session-review shell out to the new home; (c) extract it and drop the plugin-misbehavior route from session-review entirely.
• find-skills — meta/discovery skill for browsing skills.sh. Not capture, not storage; arguably belongs in a plugin-management plugin or as a standalone.

Out of scope — keep in cairn-notes

capture, recall, cairn-notes (note types), obsidian, agent-workspace, meeting-sync, session-review, workday-planning, weekly-planning. All produce or retrieve a vault artifact, or are required infrastructure for those that do.

Implementation hints

• Per-skill extraction PRs. Each extraction is a versionable change under AGENTS.md Git & Commits rules and needs a CHANGELOG.md entry under ## [Unreleased]. Doing them as separate PRs keeps blast radius small and lets reverts target one skill at a time.
• Spoke migrations follow their primary caller.
  • ticket-analyst is only invoked by issue-work — leaves with it.
  • impl-reviewer is invoked by both pr-self-review and issue-work — moves with whichever extracts first; the second extraction depends on the first.
• Coupling audit (do this first). Grep for cross-skill references inside the candidates and the keepers:

  grep -rln 'dependency-review\|dependency-triage\|pr-self-review\|ship\|issue-work\|update-pr-description' plugins/cairn-notes/
  

  Known coupling: pr-self-review is invoked from issue-work Phase 4 (frontmatter), and issue-create references issue-work as "natural next step." Any reference that crosses the new boundary becomes a cross-plugin call — confirm those still resolve.
• Identity / config touchpoints. Candidates that read ~/.claude/cairn/identity.md or write to ~/.claude/cairn/ need to be checked — extracting them shouldn't strand them dependent on cairn-notes' identity bootstrap. Spot-check: issue-work writes under ~/.claude/issue-work/ (clean), but verify the others.
• Plugin description rewrite. After extraction, the cairn-notes plugin's description field in .claude-plugin/plugin.json and the README opening should be rewritten to match the narrower scope. This is the user-visible payoff of the change.
• Release shape. Treat the full extraction as one minor bump (e.g., 0.7.0) once all extractions land, not a major. The plugin's public surface narrows but doesn't break: removed skills will still exist, just at a different namespace.

Acceptance criteria

• Coupling audit completed (single PR or comment on this issue listing every cross-skill reference and where it lands post-extraction).
• Decision recorded on each borderline (issue-create, find-skills) — extract or keep, with rationale.
• Per-skill extraction PRs merged for each in-scope skill (six PRs, or fewer if grouping makes sense — e.g., the two dependency-* skills together).
• impl-reviewer and ticket-analyst spokes moved with their callers; no orphaned spoke files in plugins/cairn-notes/agents/.
• AGENTS.md updated — Capture Triggers table, spoke roster, and any cross-skill references no longer pointing at extracted skills.
• plugins/cairn-notes/.claude-plugin/plugin.json description rewritten to reflect the capture-first scope.
• README opening paragraph rewritten to match.
• CHANGELOG entries land per PR; final release PR bumps plugin.json to 0.7.0 (or appropriate version).

Open questions

• Where do the extracted skills live? Three plausible homes: (1) personal ~/.claude/skills/ standalone skills, (2) a new sibling plugin in plugins/ (e.g., plugins/eng-workflow/), (3) entirely separate repos. Each has different discoverability and dependency-management trade-offs.
• Should issue-create extract with the engineering-workflow group, stay as capture-adjacent, or get its own borderline-resolution decision? (See Scope → Borderline.)
• Does find-skills extract with this batch, or get filed as its own separate scope-narrowing issue?
• Is there appetite to also split workday-planning / weekly-planning into a "planning" plugin? They do write notes to the vault, so they pass the capture test — but if the broader narrowing is "notes only, no orchestration," planning is the next ring out. Probably out of scope here, but worth naming so it doesn't surprise anyone later.

[SnowboardTechie]

Coupling audit complete + scope decisions

Ran the coupling-audit grep from the implementation hints. Posting findings and three decisions that resolve open questions on this issue.

---

Scope decisions (resolving open questions)

1. Planning skills also leave. workday-planning and weekly-planning are out of scope for cairn-notes post-trim, moving to dotfiles alongside the engineering-workflow skills. They write notes to the vault, so they pass the original capture-first test, but under a stricter test ("is the vault write primary, or incidental to a larger orchestration?") they're orchestration, not capture. Resolves the question at the bottom of the original scope table.

2. /issue-create handoff from session-review becomes a natural-language instruction. Resolves the borderline question with a fourth option (call it d):

   • Not (a) "keep issue-create as capture-adjacent" — it isn't capture.
   • Not (b) "extract and have session-review shell out via hard Skill() call" — couples across plugin boundary.
   • Not (c) "drop the plugin-misbehavior route entirely" — loses the feedback loop.
   • Option (d): Replace Skill(skill="cairn-notes:issue-create", ...) with a natural-language instruction in session-review's skill body: "On approval, post the draft body as a new GitHub/Forgejo issue against the repo named in the 'Filing this against …' lead-in. Use whatever issue-creation tool is available (e.g., /issue-create if installed; otherwise gh issue create directly). Before posting, show the rendered body and confirm with the user."

   Lets Claude (the runtime) pick routing. Preserves the loop. The "confirm before posting" clause is load-bearing — without it, the second of the two gates (/issue-create Stage 3.4) silently disappears when /issue-create isn't installed.

3. sage spoke leaves with the engineering skills. Audit found zero in-plugin Task(subagent_type="sage", ...) calls. Sage exists for external research, which none of the staying skills do. The cache-directory awareness in archivist, pyre, and agent-workspace stays (it's a layout convention, not an invocation).

---

Final post-trim scope

Layer	Stays in cairn-notes	Leaves for dotfiles
Skills	capture, recall, cairn-notes (note types), obsidian, agent-workspace, meeting-sync, session-review	issue-work, issue-create, ship, pr-self-review, dependency-review, dependency-triage, update-pr-description, find-skills, workday-planning, weekly-planning
Commands	cairn-setup	plan-workday
Spokes	scribe, archivist, pyre	forge, kindle, scout, ticket-analyst, impl-reviewer, sage

---

Cross-boundary coupling — STAYING → LEAVING (break after extraction)

Location	What it references	Severity	Fix
skills/session-review/SKILL.md (18 line-refs)	Hard Skill(skill="cairn-notes:issue-create", …) invocation + draft-body shape mirroring	High	Rewrite per decision (2) above — natural-language instruction.
agents/pyre.md lines 74, 275, 290, 305	.notes/.agents/issue-work/ used as example dirs	Cosmetic	Swap for meeting-sync or session-review examples.
skills/agent-workspace/SKILL.md line 204	Lists issue-create, weekly-planning, session-review as {domain} examples	Cosmetic	Drop leaving names.
skills/agent-workspace/SKILL.md line 280	"issue-work, planning skills own their .agents/{skill}/ subdir"	Cosmetic	Rephrase generically.
skills/agent-workspace/SKILL.md line 405	mkdir -p .notes/.agents/{sage,archivist,forge,kindle,drafts,_archive}	Cosmetic	Trim to {archivist,drafts,_archive}.
commands/cairn-setup.md line 89	"Used by: forge, kindle, and other skills/spokes that address the user by name"	Cosmetic	Generalize wording.

---

Cross-boundary coupling — LEAVING → STAYING (become cross-plugin calls)

Leaving skill	Pulls from STAYING	Severity	Fix
issue-work, issue-create, pr-self-review	Doc-link to agent-workspace/SKILL.md's resolve_trunk_root pattern	Medium	Inline the function in each leaving skill, or extract to a dotfile-shared snippet.
pr-self-review	Active Task(subagent_type="archivist", …) for related-notes phase	Medium	Already degrades gracefully when .notes/ missing. Keep as soft cross-plugin dep, or rewrite per the soft-coupling principle (natural-language instruction).
workday-planning	Active Task(subagent_type="archivist", …) × 3 call sites	Medium	Same as above.
workday-planning, weekly-planning	Heavy reliance on obsidian skill's vault-path conventions	Medium	Inline the conventions, or declare cairn-notes as a soft dep for vault-aware operation.
pr-self-review, workday-planning, weekly-planning	Doc references to /cairn-setup	Cosmetic	Generalize wording.
agents/forge.md lines 167, 219, 292	Mentions /capture, pyre, scribe — but doesn't call them, just flags moments	Cosmetic	Rephrase: forge flags; caller routes.
agents/scout.md line 14	"doesn't capture notes" — describing what it doesn't do	Cosmetic	Generalize wording.

---

Design principle that emerged from this audit

The session-review → /issue-create decision instantiates a broader pattern: hard-couple within a plugin, soft-couple across plugins via natural-language handoffs. Same pattern applies to pr-self-review → archivist and workday-planning → archivist (both flagged Medium in the table above). May become an ADR / contribution to plugin authoring docs once it's been applied a few more times.

---

Updated acceptance criteria

• Coupling audit completed (this comment)
• Decision on issue-create borderline (option d above)
• Decision on find-skills borderline (extracts with engineering batch)
• Decision on planning skills (extract — out of scope per stricter capture test)
• Decision on sage spoke (extracts with engineering — no in-plugin callers)
• Per-skill extraction PRs (six skills + four spokes; planning is two more PRs on top)
• impl-reviewer and ticket-analyst spokes move with their callers; forge, kindle, scout, sage move with the planning + engineering batches
• session-review rewritten per decision (2) — Skill() → natural-language instruction, "confirm before posting" gate preserved
• AGENTS.md updated — Capture Triggers, spoke roster trimmed to scribe/archivist/pyre, cross-skill references no longer pointing at extracted skills
• plugin.json description rewritten to capture-first scope
• README opening paragraph rewritten to match
• CHANGELOG entries per PR; final release PR bumps plugin.json to 0.7.0

---

Suggested PR order

Recommend starting with the lowest-coupling extraction as a warm-up:

1. dependency-review + dependency-triage together — no shared spokes, no cross-skill calls in either direction, smallest blast radius.
2. update-pr-description — standalone, no dependencies.
3. find-skills — standalone meta-skill.
4. ship — standalone PR workflow.
5. pr-self-review + impl-reviewer spoke — first extraction with a spoke that has a sibling caller (issue-work still in plugin at this point). Decide: keep archivist as soft cross-plugin dep, or rewrite the call per the soft-coupling principle.
6. issue-work + ticket-analyst spoke + remainder of impl-reviewer ownership — biggest skill, deepest internal coupling.
7. issue-create — last in the engineering batch, blocked on session-review rewrite landing first.
8. workday-planning + forge + scout spokes + plan-workday command + kindle spoke — biggest single extraction.
9. weekly-planning — depends on planning conventions extracted in (8).
10. session-review rewrite — Skill() → natural-language; lands before (7) or as part of it.
11. Final cleanup PR — AGENTS.md, plugin.json, README, CHANGELOG, version bump to 0.7.0.

[SnowboardTechie]

Carry-over note from #81 (just closed):

Whenever `/issue-create` extracts to its new home, carry over the goal-level-implementation-hints default. The proposed rule: at draft stage, `Implementation hints` stays at goal/file-location level by default — concrete library/syntax pointers only on explicit user direction, or when there are 1–4 distinct options worth surfacing as a choice. Cap the narrowing prompt at 4 options; past that, just write goal-level hints.

Encoded in the user's memory already, so the principle isn't lost — but worth including in the extraction PR so the skill doesn't drift back to over-prescriptive drafting in its new home.