Add /generate-feature-docs skill for spec-to-docs generation

.claude/commands/generate-feature-docs.md

@@ -0,0 +1,7 @@
+Generate publisher-facing documentation from an implemented engineering spec.
+
+Spec path: $ARGUMENTS
+
+Use the `generate-feature-docs` skill at `.claude/skills/generate-feature-docs/SKILL.md` to perform this task. The skill runs in two interactive stages (extraction pass for outline review, generation pass for prose and reference-doc updates) and commits the result on user approval.
+
+If `$ARGUMENTS` is empty, ask the user which spec to document, defaulting to the most recently modified file under `docs/superpowers/specs/implemented/`.

.gitignore

@@ -24,6 +24,7 @@ src/*.html
 !.claude/settings.json
 !.claude/commands/
 !.claude/agents/
+!.claude/skills/
 
 # SSL certificates
 *.pem

CLAUDE.md

@@ -375,6 +375,32 @@ both runtime behavior and build/tooling changes.
 
 ---
 
+## Engineering Spec Conventions
+
+Implementation specs live under `docs/superpowers/specs/`, split by lifecycle:
+
+- `docs/superpowers/specs/drafts/`: brainstorm output. The Superpowers brainstorming skill writes new specs here. Specs are not yet ready for documentation. Frontmatter: `status: draft`.
+- `docs/superpowers/specs/implemented/`: post-implementation truth. Specs are promoted here once code has shipped and the spec body has been updated to reflect what shipped. Frontmatter: `status: implemented`.
+
+**Required frontmatter** (every spec):
+
+```yaml
+---
+status: draft | in-progress | implemented
+implemented_in: PR#123              # optional, set on promotion
+last_reviewed: 2026-04-15           # optional, YYYY-MM-DD
+verified_against_commit: a1b2c3d4   # optional, audit trail (skill records, does not validate)
+---
+```
+
+**For agents writing new specs:** when invoked from this project, the brainstorming skill must write to `docs/superpowers/specs/drafts/`, not the parent directory. Add `status: draft` frontmatter at write time.
+
+**For agents generating user-facing docs:** the `generate-feature-docs` skill operates only on specs under `implemented/` with `status: implemented`. See `.claude/skills/generate-feature-docs/SKILL.md`.
+
+Promoting a spec from draft to implemented is a `git mv` plus a frontmatter edit, ideally landed in the same PR that updates the spec body to match shipped code.
+
+---
+
 ## What NOT to Do
 
 - Do not add unnecessary dependencies without justification.

docs/.vitepress/config.mts

@@ -38,6 +38,7 @@ export default withMermaid(
     description:
       'Privacy-preserving edge computing for ad serving and edge cookie (EC) generation',
     base: '/trusted-server',
+    srcExclude: ['superpowers/**', '**/node_modules/**'],
 
     // Replace version placeholders like {{NODEJS_VERSION}} with values from .tool-versions
     markdown: {