Skip to content

openmove/engineering-design-playbook / .agents/skills/design-docs-template

design-docs-template

Verified

Router for the design-docs stack (RFC → ADR → arc42 + Starlight). Commands: bootstrap, new-rfc, new-adr, rfc-hygiene, close-loop, preview, update-skills. Use when the user says design-docs-template, docs-template, design-docs bootstrap, new RFC/ADR, RFC hygiene, close an RFC into ADRs and arc42, preview docs on localhost, update/refresh the docs skills, or nested docs-template commands.

Design docs template

Seven commands under one roof. Read the matching child SKILL.md and follow it; do not invent an eighth path.

CommandWhat it doesChild
bootstrapStarts a new docs repo from design-docs-template: arc42, ADR, RFC folders and a Starlight site ready to publish. Use on day zero so you never rebuild the scaffolding by hand.bootstrap/SKILL.md
new-rfcAdds the next numbered RFC from the project template, wires the index, and leaves a draft ready to fill. Use when a change has real trade-offs and a ticket is not enough.new-rfc/SKILL.md
new-adrAdds the next numbered ADR from the MADR template (minimal by default), status proposed, and updates the ADR index. Use when a choice is settled and must not be rewritten later.new-adr/SKILL.md
rfc-hygieneConsistency pass on a draft RFC: one canon for names, diagrams, prose, and examples; strips stale noise after many iterations. Use when the RFC still “works” but readers trip on old terms or dead options.rfc-hygiene/SKILL.md
close-loopCloses an approved RFC into the permanent record: draft ADR(s) for the decisions it produced, freeze/point the RFC, and a concrete arc42 + C4 update checklist in the same change. Use when review is done and implementation (or the map) must catch up.close-loop/SKILL.md
previewSyncs docs/ into Starlight and starts the local Astro/Starlight server; reports the Local URL with the configured base path. Use when you want to read the docs in the browser on localhost.preview/SKILL.md
update-skillsPulls the latest skill tree from the GitHub template into .cursor / .claude / .agents (optional personal dirs). Use when the template gained new commands and local copies are stale.update-skills/SKILL.md

Dispatch

  1. If the user named a command (or a clear synonym: hygiene, clean RFC, from template, accept RFC, scaffold RFC, localhost, alza i docs, aggiorna le skill, self-update…), open that child and run it.
  2. Otherwise ask once which command. Defaults: bootstrap on empty/new docs root; preview if they only want the site up; update-skills if they only want to refresh skills; rfc-hygiene if an RFC path is in chat; close-loop if they say the RFC was approved; new-rfc / new-adr if they ask to “add” one.
  3. After the child finishes, stop. Chain another command only if they ask (typical chain: rfc-hygiene → close-loop, or edit → preview).

Method (shared)

| Still deciding | RFC | Changes until accepted, then history | | Already decided | ADR | Never edit accepted; supersede with a new one | | What exists today | arc42 + C4 | Keep current; update in the same change that closes an RFC |

Template sources

FlavourGitHub template
OpenMove (default here)openmove/engineering-design-playbook
Generic upstreamalessandroros/design-docs-template

bootstrap / update-skills default to openmove/engineering-design-playbook in this playbook; only use the generic template if the user asks.

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 318kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall