Plans
Implementation Plan

Make write-guide output dynamic

todo
2026-06-19 agentics feature
Objective

Make the write-guide skill produce genuinely topic-shaped guides. The section library is the primary unit: the author assembles each guide from it to fit the topic — adding, dropping, reordering, or blending sections freely. The five archetypes (system-explainer, rule-deep-dive, how-to/tutorial, concept-explainer, change/recap) are non-binding starting points, not molds. What every guide is held to is the evidentiary spine — the six discipline rules, verbatim quoting, a quoted-source/worked-example depth bar, and the provenance → body → Quick reference → Cross-references frame — never a fixed section sequence.

Implement Read and implement all steps in the plan at docs/plans/make-write-guide-output-dynamic.html — Make write-guide output dynamic via a section library and archetypes. Start from the embedded digest: awk '!f && /<script[^>]*id="plan-digest"/{f=1;next} f && /<\/script>/{exit} f' docs/plans/make-write-guide-output-dynamic.html
File make-write-guide-output-dynamic.html
Path docs/plans/make-write-guide-output-dynamic.html
Acceptance criteria 0 / 9 done

Context

The write-guide skill (kit/plugins/social-media-tools/skills/write-guide/) advertises broad scope — "systems, rules, concepts, tools, resources, plans, changes, or saved memories" (SKILL.md:10-11) — but builds every guide to a single "fixed 12-section skeleton" (SKILL.md:12) reverse-engineered from only two exemplars, both rule/system deep-dives. The skeleton's rhetorical devices (incident with numbers §3, italic diagnostic question §6, do/do-NOT script §7, numbered carve-outs §8, verification protocol §12) fit guardrail and subsystem topics but misfit tutorials, concept explainers, and change recaps. Flex valves exist (titles may flex, sections may be omitted) but the framing — "copy verbatim", "Every guide follows it", and a self-check that counts all 12 sections (SKILL.md:136) — pushes authors to fill the template rather than fit the topic. Empirically, write-guide has produced two guides: publish-docs-to-github-pages.md used all 12 sections (it is a system), while using-design-md-and-component-md.md abandoned the numbered skeleton for six renamed sections — proving the flex works but is treated as a deviation. This plan implements recommendations A (reframe the template as a section library) and B (add archetypes) while leaving the evidentiary spine untouched. The write-guide ↔ documenting-plans scope overlap is deliberately deferred to Next Steps.

Files to Modify

agentics/
  • CLAUDE.md modified reframe write-guide plugin-table line (drop "fixed 12-section")
  • .claude-plugin/marketplace.json modified bump social-media-tools 2.12.1 → 2.13.0
  • kit/plugins/social-media-tools/
    • README.md modified reframe write-guide row (drop "12-section skeleton")
    • CHANGELOG.md modified add v2.13.0 entry (house heading format)
    • skills/write-guide/
      • SKILL.md modified library-primary framing (5 refs) + §3 + shaping step + spine/depth contract + boundary note
      • references/
        • skeleton.md modified section library (incl. lines 7-10 reframe)
        • exemplars.md modified five archetypes as starting points + picker + most-specific-wins heuristic

Diagram

How a guide gets its shape (new flow)
Source
Gather facts
conversation, files, git, code, canonical docs
Select
Pick one archetype
rule-deep-dive · system-explainer · how-to · concept · change-recap
Assemble
Draw sections from the library
only the sections the archetype needs — no filler, no forced 12
Write
Apply the invariant spine
6 discipline rules · provenance frame · Quick reference · Cross-references

Steps

1
todo Reframe SKILL.md from "fixed 12-section skeleton" to section-library language across ALL five references: the overview (lines ~10-14), "What this skill produces" (line 25), the "Before you write" reference list (line 60), Workflow §3 Structure (line 81), and the self-check bullet (line 136) — so the skeleton reads as a library of section types to draw from.
The rigidity is in the framing — "fixed", "Every guide follows it", and a 12-count self-check push authors to fill the template instead of fitting the topic. Three of the five references sit outside the originally-scoped lines.
Verify
grep -nE '12-section|12 skeleton|Every guide follows' SKILL.md returns nothing; the self-check bullet reads as a filler/coverage quality test, not a count of 12.
2
todo Reframe references/skeleton.md as a section library — retitle "The template (copy verbatim)" (lines 1, 12), rewrite the line-3 "Every guide ... follows the structure below", AND reword lines 7-10 ("the two exemplars map onto this skeleton exactly… all twelve… §1–§6") to be archetype-count-agnostic, so the 12 sections read as a catalog of intents and devices, not a default sequence.
skeleton.md is the authoritative structure spec; if its title or the lines 7-10 narration still assert "copy verbatim" / "all twelve" / "two exemplars", the section-library framing added to SKILL.md is contradicted at the source.
Verify
Re-read skeleton.md: all 12 section intents/devices remain documented but framed as a menu; nothing still asserts "two exemplars", "all twelve", or "copy verbatim" as the default shape.
3
todo Expand references/exemplars.md to five archetypes — keep system-explainer and rule-deep-dive; add how-to/tutorial, concept-explainer, and change/recap (kebab ids how-to, concept-explainer, change-recap). Frame each as a non-binding starting point: a suggested section set drawn from the library plus a short "what to steal" note (lighter than A/B, which have backing exemplar files), with explicit permission to add, drop, reorder, or blend sections to fit the topic. Rewrite the contradictory framing: line 3 ("two archetypes every topic falls into"), the binary picker question (line 75, "one rule, or a whole system?"), and lines 82-84 ("default to the 12-section skeleton… fits both archetypes"). Give the picker one row per archetype and a most-specific-wins starting-point heuristic (not a constraint — blend when a topic genuinely spans two).
Both existing exemplars are rule/system docs, so tutorials, concepts, and change recaps had no first-class shape; framing the archetypes as starting points (not molds) is what makes output topic-shaped rather than one-of-five-shaped.
Verify
exemplars.md lists five archetypes with kebab ids; each is labelled a starting point with explicit add/drop/reorder/blend permission; the picker has one row each, a tell each, and a most-specific-wins heuristic; grep 'default to the 12-section' exemplars.md returns nothing.
4
todo Add a "Select a starting archetype" step to the SKILL.md Workflow, after Structure and before Write — pick the closest archetype as a starting point, then assemble the body from the section library to fit the topic, adding/dropping/reordering/blending sections as needed. State explicitly that the archetype is a starting shape, not a contract. As part of this, change Workflow §3 Structure (line 81) from "map onto the 12-section skeleton" to "map onto the section library". Renumber the subsequent workflow steps.
A shaping step makes the section library the active unit and the archetype a hint; without the "not a contract" wording the step would re-impose a fixed shape — the very rigidity being removed.
Verify
SKILL.md Workflow has a numbered "Select a starting archetype" step between Structure and Write that names the archetype as a starting point and the library as the assembly source, with explicit add/drop/reorder/blend permission; §3 Structure now says "section library"; downstream numbering stays consistent.
5
todo Add an "Invariant spine (every guide)" note to SKILL.md — every guide keeps the six discipline rules, the concreteness rules, and the frame (title + subtitle + provenance callout → body → Quick reference → Cross-references), regardless of shape. Strengthen the self-check with a quality-floor bar: every guide must include at least one verbatim-quoted primary source and one concrete/worked example. State explicitly that the spine + depth bar — not any fixed section sequence — is what every guide is held to. Add one boundary sentence distinguishing write-guide's change/recap (ad-hoc topic recap) from the documenting-plans skill (recap of a completed plan from git history). Leave the discipline rules (lines 111-128) and tone-rules.md unchanged in intent.
With the section shape now free, the spine + depth bar is the only enforced quality contract, so it must be explicit and shape-independent; the boundary sentence keeps change/recap from silently competing with documenting-plans.
Verify
SKILL.md names the spine + depth bar as the enforced contract (the section shape is explicitly not); the self-check requires ≥1 verbatim source and ≥1 worked example per guide; a change/recap-vs-documenting-plans boundary sentence is present; the discipline rules (111-128) and tone-rules.md are byte-unchanged.
6
todo Reframe the external discovery surfaces — root CLAUDE.md (line 79 plugin table) and kit/plugins/social-media-tools/README.md (line 33), both of which describe write-guide as following "a fixed 12-section skeleton". Reword each to section-library/archetype language. Leave the marketplace.json plugin description unchanged (it does not mention 12-section).
These are the session-loaded capability index and the plugin's public README; if left stale they keep advertising the old rigid contract after the skill changed — and the plan's own grep-based criteria would otherwise pass while the docs contradict the skill.
Verify
grep -rnE 'fixed 12-section|12-section skeleton' CLAUDE.md kit/plugins/social-media-tools/README.md returns nothing.
7
todo Bump social-media-tools 2.12.1 → 2.13.0 in .claude-plugin/marketplace.json (MINOR). Add a CHANGELOG entry in the house format — "## v2.13.0 — 2026-06-19 — <summary>" with ### Changed / ### Added sub-headings. Do not add a version field to plugin.json, and leave the SKILL.md frontmatter description and the marketplace.json plugin description unchanged (neither contains "12-section"; preserve the three-part ≤200-char format).
Adding archetypes and a selection step is a new capability (MINOR per semver); marketplace.json is the single version source for relative-path plugins, and the CHANGELOG must match the existing entry format.
Verify
marketplace.json shows social-media-tools 2.13.0; CHANGELOG.md has a "## v2.13.0 — 2026-06-19" section with ### sub-headings; plugin.json has no version field; both description fields are unchanged; the .claude/settings.json post-write JSON validation on marketplace.json passes.

Tests

Tier 2 — Non-code plan
Objective write-guide shapes each guide to its topic — spine + depth enforced, never a forced mold

File: manual smoke check — invoke write-guide on two pinned topics; the skill is prose, so there is no automated runner.

Topics (pinned): (1) rule/system regression — re-derive a guide for the GitHub Pages publishing pipeline (the topic behind docs/guides/publish-docs-to-github-pages.md); (2) tutorial — a how-to such as "how to add a new archetype to write-guide".

Type: smoke test

Asserts (pass bar — topic-fit + spine + depth, NOT conformance to a fixed list): the tutorial run passes if it is shaped to the topic (the sections a how-to needs — goal, prerequisites, steps, pitfalls — present; sections that do not fit, such as an incident or numbered carve-outs, absent rather than padded in), carries the full invariant spine (provenance frame, Quick reference, Cross-references, six discipline rules), and meets the depth bar (≥1 verbatim-quoted source + ≥1 worked example). The rule/system run passes if it still naturally uses the deep-dive devices because they fit, and carries the same spine + depth. The test never requires conformance to a fixed archetype section list.

Re-run stability: invoke the same topic twice and confirm both runs carry the full spine, meet the depth bar, and stay shaped to the topic; structural wording may vary run-to-run (expected in a dynamic system) — the spine and depth must hold every time.

Run: invoke the skill per topic; check (a) the spine is present, (b) the depth bar is met, (c) no section that does not fit the topic was padded in, and (d) no section the topic needs is missing.

Acceptance Criteria

Verification

Re-read the write-guide files: SKILL.md frames the section library as the primary unit and adds a shaping step where the archetype is a starting point and the body is assembled freely; skeleton.md presents its sections as a catalog (incl. lines 7-10); exemplars.md defines five archetypes as non-binding starting points with a most-specific-wins heuristic. Confirm the six discipline rules and tone-rules.md are unchanged and that the spine + depth bar — not a fixed shape — is named as the enforced contract. Reframe and re-check the external surfaces (CLAUDE.md, README.md). Run the objective smoke test on the two pinned topics: each must be shaped to its topic, carry the full spine, and meet the depth bar — without conforming to a fixed archetype section list. Confirm marketplace.json shows social-media-tools 2.13.0, CHANGELOG.md has the v2.13.0 entry in house format, plugin.json has no version field, and the settings.json post-write JSON validation passes. As a coverage gate, run grep -rniE 'fixed 12-section|12-section skeleton|two exemplars|both archetypes|all twelve|default to the 12-section' kit/plugins/social-media-tools/skills/write-guide CLAUDE.md kit/plugins/social-media-tools/README.md and confirm it returns nothing (the historical CHANGELOG entry is excluded from scope).

Completion Checklist

Required

Completion Report

No items to report — all requirements met.

Next Steps

Resolve the write-guide ↔ documenting-plans scope overlap

Paste this prompt into Claude to execute this follow-up:

In the agentics repo, decide and implement the boundary between the write-guide skill (kit/plugins/social-media-tools/skills/write-guide/) and the documenting-plans skill (kit/plugins/plan-interview/, which writes docs/<slug>.md). Today write-guide's description claims "plans/changes" scope and now also ships a change/recap archetype — but documenting-plans already owns plan recaps: 59 of ~61 files in docs/guides/ carry documenting-plans' <!-- generated:start --> markers and **Plan:** backlinks, and only 2 are write-guide output. Choose one: (a) narrow write-guide's description to drop "plans/changes" and route change-recap requests to documenting-plans, or (b) keep write-guide's change/recap archetype as the deliberate bridge and document when to use which skill. Update the skill descriptions, the root CLAUDE.md plugin table, and bump the affected plugin version(s) in marketplace.json. Report the decision and the files changed.
Wish List
Archetype-aware guides gallery Wish List

Speculative / blue-sky idea — not on the critical path. Paste into Claude when ready to explore:

Add an `archetype:` field to the metadata write-guide emits on every generated guide (one of: system-explainer, rule-deep-dive, how-to, concept-explainer, change-recap). Then build or extend a docs/guides gallery — mirroring the plans-library / media-library pattern in this repo — so guides can be filtered by archetype, with the archetype shown as a visible badge on each guide card.
Generated by plan-agent · 2026-06-19 · agentics
Team Review (2026-06-19)

Reviewers: 5 core (architecture, completeness, testability, risk, conventions). UI reviewers skipped — no UI signals (Markdown/JSON skill-authoring change).

Executive summary. Sound, approve with revisions — no reviewer recommended rejection. The section-library + archetype + invariant-spine design was called "architecturally sound" and "a clean information-architecture pattern." Findings clustered on scope completeness (the "12-section" reframe missed several references and two external surfaces) and verification tightening, not on the approach.

Architecture. Design is sound and extensible. Flagged orphaned cross-file references the steps did not enumerate (SKILL.md:25, :81; skeleton.md:7-10) and archetype overlap without an arbitration rule. Recommended a most-specific-wins picker rule and broadening the sweep.

Completeness. Steps are specific, but file coverage was under-scoped: SKILL.md has five "12-section" references (Step 1 named three), and root CLAUDE.md:79 + README.md:33 were missing from the Files list. Recommended adding both external surfaces, a coverage criterion, and a pinned smoke-test topic.

Testability. The Tier-2 smoke-test approach is correct (no false demand for unit tests on prose). The objective test lacked an explicit pass bar and a concrete regression assertion. Recommended a strict pass bar, pinned topics, and a "no-diff" tone-rules criterion.

Risk. Medium. Highest: stale discovery surfaces (CLAUDE.md/README.md) shipping the old contract; incomplete SKILL.md sweep; change/recap overlapping documenting-plans (boundary deferred). Recommended a quality-floor bar in the spine and an interim boundary sentence. Versioning (MINOR 2.13.0) confirmed correct; the merge driver keeps the higher semver.

Conventions. Close fit. Version handling, the reference-file pattern, and the 141-line SKILL.md (≤500 budget) all align. Recommended pinning the CHANGELOG heading format and stating the description fields are deliberately unchanged.

Agreements & conflicts. Three reviewers independently confirmed the under-scoped reframe (amplified to highest priority). One soft conflict: Risk offered "hold change/recap" as an option, which conflicts with the "all three now" decision — resolved by keeping the archetype and adding a boundary sentence instead.

Highest-risk issues (priority order):

  • Incomplete "12-section" sweep — SKILL.md:25/81, skeleton.md:7-10, exemplars.md:3/75/82-84 (Architecture + Completeness + Risk).
  • Stale external surfaces not in scope — CLAUDE.md:79, README.md:33 (Completeness + Risk).
  • Archetype-selection ambiguity for overlapping topics — needs an arbitration rule (Architecture + Risk).
  • Quality-floor regression from loosening the fixed skeleton (Risk).
  • Loose smoke-test pass bar (Testability).

Triage outcome — walkthrough mode; all 8 findings Accepted and applied:

  • Accepted — Step 1 broadened to all five SKILL.md "12-section" references + grep verify.
  • Accepted — Step 2 extended to skeleton.md lines 7-10.
  • Accepted — Step 3 expanded: rewrite exemplars.md framing (3/75/82-84), most-specific-wins arbitration, kebab ids, synopsis depth.
  • Accepted — new Step 6 reframes CLAUDE.md:79 + README.md:33; both added to the Files tree.
  • Accepted — Step 4 names the Workflow §3 Structure wording change.
  • Accepted — Step 5 adds the quality-floor depth bar + a change/recap↔documenting-plans boundary sentence (archetype kept, per "all three now").
  • Accepted — Step 7 (was 6) pins the CHANGELOG house format + descriptions-unchanged note.
  • Accepted — Tests pass bar + pinned topics + determinism; acceptance criteria ac8 (external-surface coverage) and ac9 (determinism) added; ac5 tightened to "no diff"; verification coverage grep added.

Modified / Rejected: none.

Result: Steps grew 6 → 7; acceptance criteria 7 → 9; Files +2; digest refreshed. Plan remains status: todo.