| name | authoring-promptpack-rfcs |
| description | Use when proposing, drafting, submitting, or revising a change to the PromptPack specification in this repo — a new entity type, schema field, workflow/agent/eval/composition/skill extension, or any spec behavior change. Covers the RFC document, the index, the schema, and the docs-site landmines. |
Authoring PromptPack RFCs
Overview
Substantial spec changes land as an RFC (rfcs/NNNN-slug.md) following rfcs/0000-template.md. The RFC PR is markdown only — it proposes the schema change; the schema itself lands in a separate implementation PR once the RFC is Accepted. Getting this split — and a handful of generated-file and CI landmines — right is what this skill captures.
Design the change first. For anything non-trivial, use superpowers:brainstorming before drafting: diagnose, weigh 2-3 approaches, converge. The RFC is the write-up of an agreed design, not the place to think.
When to use
- New entity type (beyond prompts, tools, workflows, personas, fragments), new schema field, breaking change, or any change to validation/processing behavior → RFC.
- Doc fixes, clarifications, typo-level schema tweaks → a plain issue/PR, no RFC.
Workflow
- Next number. Highest existing
rfcs/NNNN-*.md + 1, zero-padded. Slug is kebab-case and scope-accurate (rename later rather than overselling).
- Copy the template
rfcs/0000-template.md. Fill every section. Header: Status: Draft, real author, Created/Updated = today (absolute date).
- Write to house style (see below). Examples in YAML with the line
> YAML shown for readability (per [RFC 0002](./0002-yaml-format.md)). Equally valid as JSON.
- Diagram only where it earns its keep. Use a compact
flowchart LR (subgraphs fine). Avoid stateDiagram-v2 composite states with notes — they break rendering and sprawl vertically. No theme-init block needed.
- Update the index
rfcs/README.md — hand-maintained. Add a row to the Active table (Draft) or Implemented table. Fix any drift you notice (status vs. the RFC file).
- Do NOT touch the docs site copies.
promptpack-docs/docs/rfcs/index.md and promptpack-docs/docs/rfcs/*.md are auto-generated by promptpack-docs/scripts/sync-rfcs.js (runs in prebuild; CI's docs-build regenerates them). Hand-editing them causes conflicts.
- Land it: branch
rfc/NNNN-slug off main, conventional commit docs(rfc): add RFC NNNN — <title>, PR to main.
House style (match the existing RFCs)
| Convention | What to do |
|---|
| Backward compatibility | Strongly preferred. Check [x] Fully backward compatible; make new fields optional. If you must break, justify and give a migration path. |
| Runtime Support Levels | Include a Level 0 (ignore) / 1 (validate) / 2 (execute) section — every extension RFC has one. |
engine escape hatch | Runtime-specific config goes in an opaque engine block, never in the core schema. |
| Extend, don't compete | Prefer adding a field/mode to an existing surface over a new top-level primitive (cf. RFC 0010 composition as a state mode; RFC 0011 a field on AgentDef). Call this out in Alternatives. |
| Honesty sections | Fill Drawbacks, Alternatives (2-3, each with why-rejected), and Unresolved Questions for real. Engineer-to-engineer, no hype. |
The two PRs
A spec change lands in two PRs. Keep them separate.
PR 1 — the RFC (this skill's Workflow above). Markdown only, Status: Draft. It proposes the schema change; it does not touch schema/promptpack.schema.json.
PR 2 — implementation (after the RFC is Accepted). One PR carries everything together, in lockstep — never split these across PRs:
- Schema — add the fields to
schema/promptpack.schema.json and bump its top-level version (additive optional field = minor bump). Schema is the source of truth.
- RFC status — set the RFC's
Status: Implemented, bump Updated, add a Revision History line; move its row to the Implemented table in rfcs/README.md.
- README lockstep — update the
Spec-vX.Y.Z-blue badge and the versioned schema URL (schema/vX.Y.Z/...) to the new version. Enforced by version-check (scripts/check-version-consistency.mjs): schema version == badge == URL, or CI fails.
- Docs + version snapshot — update the current spec docs (
promptpack-docs/docs/spec/*) with the new feature, and perform the manual docs-version snapshot (see Docs site versioning below).
RFC_SPEC_VERSION map in sync-rfcs.js — add NN: 'vX.Y' (the spec version that ships it).
Why all in one PR: RFC-0009 was once marked Implemented while its schema fields were never added. version-check and this rule exist to stop exactly that drift. An RFC reaching Implemented and the schema version bump are the same event.
The full step-by-step for PR 2 is in release-runbook.md (this skill directory) — the detailed, de-drifted release checklist (schema, docs archive, versions, sidebars, README lockstep, sync-schema, RFC index, guide).
Schema publishing (latest + versioned copies)
schema/promptpack.schema.json is the only source of truth. npm run sync-schema (runs automatically in the docs prebuild/prestart) copies it to both static/schema/v<version>/ and static/schema/latest/ — so latest/ always mirrors the current schema; you never hand-point it. The authoritative public publish happens when a v* git tag is pushed: publish-schema.yml copies the schema into static/schema/<tag>/ + latest/ and commits to main. So the release flow is: merge PR 2 → tag vX.Y.Z → CI publishes the versioned + latest schema.
Never hand-edit static/schema/** or the generated schema-reference docs — they're produced by sync-schema.js / the schema-docs workflow.
Docs site versioning
The docs site is versioned, but manually — only docs/spec/ is versioned (processes, RFCs, ecosystem stay current). It does not use Docusaurus docs:version (no versioned_docs/); deliberate choice. When the implementation PR bumps the spec version, you archive the outgoing docs/spec/* into docs/spec/v<previous>/, advance the current docs, and update versions.md + sidebars.ts — all in that same PR. release-runbook.md (steps 3–6) has the exact per-file edits; promptpack-docs/docs/spec/VERSIONING.md is the canonical guide for badge markup.
static/schema/ (machine schema) and docs/spec/ (human docs) version independently but in step — both advance in the implementation PR.
Quick reference
| Path | Role |
|---|
rfcs/0000-template.md | template to copy |
rfcs/NNNN-slug.md | the RFC (hand) |
rfcs/README.md | index tables (hand) |
promptpack-docs/docs/rfcs/* | docs copies (auto — leave alone) |
promptpack-docs/scripts/sync-rfcs.js | generator + RFC_SPEC_VERSION map |
schema/promptpack.schema.json | schema source of truth (separate impl PR) |
Common mistakes
- Hand-editing the docs-site RFC index → merge conflicts. It's generated.
- Bundling the schema change into the RFC PR → diverges from the process; split it.
- Bumping the schema version without the README badge + URL → red CI.
- A
stateDiagram-v2 with notes on composite states → won't render. Use flowchart LR.
- Drafting before designing → use
superpowers:brainstorming first. Turn the implementation/schema work into a plan with superpowers:writing-plans.
