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.

FileKindSize
README.mdmarkdown4.4 KB
SKILL.mdskill md3.7 KB
---
name: design-docs-template
description: >-
  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.

| Command | What it does | Child |
| --- | --- | --- |
| **bootstrap** | Starts 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](bootstrap/SKILL.md) |
| **new-rfc** | Adds 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-rfc/SKILL.md) |
| **new-adr** | Adds 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](new-adr/SKILL.md) |
| **rfc-hygiene** | Consistency 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](rfc-hygiene/SKILL.md) |
| **close-loop** | Closes 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](close-loop/SKILL.md) |
| **preview** | Syncs `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](preview/SKILL.md) |
| **update-skills** | Pulls 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](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

| Flavour | GitHub template |
| --- | --- |
| **OpenMove (default here)** | `openmove/engineering-design-playbook` |
| Generic upstream | `alessandroros/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: 322kUpdated 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: 198kUpdated 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: 198kUpdated 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: 198kUpdated Claude CodeCodexVerifiedInstall