Plans

Make write-guide output dynamic

High completed
2026-06-19 agentics feature High effort
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.md — Make write-guide output dynamic. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/make-write-guide-output-dynamic.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
More ways to run this plan — goal & workflow prompts, file path
Pursue as goal — optimize for the outcome, in parallel
Achieve this goal: Make write-guide output dynamic. The plan at docs/plans/make-write-guide-output-dynamic.md describes one approach — use it as reference, but optimize for the outcome. Fan out across parallel subagents where that serves the outcome. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/make-write-guide-output-dynamic.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
Run as workflow — launch parallel subagents
Run a workflow to implement the plan at docs/plans/make-write-guide-output-dynamic.md — Make write-guide output dynamic. Brief subagents with the plan file at docs/plans/make-write-guide-output-dynamic.md. Reserve a final verification phase for the lead agent, not a subagent. Verify against the plan's Tests, Verification, and Acceptance Criteria before reporting done. If everything passed, mark completion in docs/plans/make-write-guide-output-dynamic.md — tick each step's [x] marker and each criterion's - [x], set status: completed — and re-render the HTML from the spec. If any check failed, leave status: in-progress and say which.
File make-write-guide-output-dynamic.html
Path docs/plans/make-write-guide-output-dynamic.html
Spec docs/plans/make-write-guide-output-dynamic.md
Definition of done 9 / 9 done

Context

The story behind this plan — what prompted the work and why it matters now.

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 that change

Every file this plan touches, and what happens to each one.

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

Steps

The step-by-step work, in order — each step says what to do, why it matters, and how to check it worked.

1
done 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.
Why
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
done 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.
Why
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
done 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).
Why
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
done 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.
Why
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
done 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.
Why
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
done 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).
Why
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
done 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).
Why
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

The tests that prove the change does what it promises.

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.

Definition of done

The plan counts as done when every statement below is true — check each one off as you verify it.

Final check

One last pass to confirm the whole change works end to end.

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).

Wrapping up

Three gates that must all pass before this plan is marked completed.

Required

Completion Report

No items to report — all requirements met.

Next steps

Follow-up ideas that came up along the way — none of them are required to finish this plan.

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.
Archetype-aware guides gallery Wish List

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

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

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.