Add /generate-feature-docs skill for spec-to-docs generation#675
Open
Add /generate-feature-docs skill for spec-to-docs generation#675
Conversation
Two-stage skill that converts implemented engineering specs into publisher-facing docs at docs/guide/, with handle verification against code, augment-in-place behavior for existing pages, and mechanical updates to configuration.md, api-reference.md, and error-reference.md. Establishes a spec-readiness convention (status frontmatter) and a directory split between drafts and implemented specs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sixteen tasks across three phases: prerequisites (VitePress exclusion, directory layout, spec migration, CLAUDE.md update), skill implementation (slash command + SKILL.md built up incrementally), and validation (greenfield, idempotency, augmentation, non-feature, and drift cases). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… SKILL Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds Section 16 documenting three amendments motivated by the JS Asset Auditor greenfield validation: verification-rate threshold (Section 16.1), branch-state heuristic (Section 16.2), and verified_against_commit audit field (Section 16.3). Section 6 updated to list the third optional field and to use chat-native prompt phrasing consistent with SKILL.md. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…SKILL - Edit 1: add optional frontmatter fields block (implemented_in, last_reviewed, verified_against_commit) to the spec readiness check section; specify that verified_against_commit is surfaced in the Stage 1 outline header - Edit 2: add Step 1.7a with verification-rate computation and a hard prompt when fewer than 50% of handles verify against the codebase - Edit 3: add Step 1.7b with a branch-state heuristic using git log from merge-base; surfaced as an informational note in the Stage 1 outline header - Step 1.9 outline template updated to include Verified against commit metadata and the conditional branch-state note Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Mirrors the optional field added in design Section 16.3 and SKILL.md, so the documented schema stays in sync with what the skill recognizes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Auto-formatted by prettier --write to satisfy the docs/format CI check. Mechanical changes only: trailing whitespace, table column padding, blank lines around fenced code blocks, italic style normalized to underscores. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a Claude Code skill that converts implemented engineering specs into publisher-facing documentation pages on the Trusted Server VitePress site. Closes a recurring gap where specs get written and code ships, but the docs at iabtechlab.github.io/trusted-server do not get updated.
The skill is invoked as
/generate-feature-docs <spec-path>and runs in two interactive stages: an extraction pass that produces a structured outline for user review, and a generation pass that writes prose, applies mechanical updates to reference docs, and commits on user approval. Built entirely on Claude Code's existing skill and slash-command primitives. No new runtime infrastructure.What's in this PR
.claude/skills/generate-feature-docs/SKILL.mdand slash command at.claude/commands/generate-feature-docs.md.docs/superpowers/specs/drafts/for brainstorm output,docs/superpowers/specs/implemented/for post-implementation truth, withstatus:frontmatter (draft,in-progress,implemented).drafts/withstatus: draft.srcExcludeforsuperpowers/**so internal specs no longer render on the public docs site.CLAUDE.md.docs/superpowers/specs/drafts/2026-04-28-generate-feature-docs-skill-design.mdand implementation plan atdocs/superpowers/plans/2026-04-28-generate-feature-docs-skill.md.What is NOT in this PR
srcExcludeconfig; the only runtime impact is on the public docs site (which removes internal spec pages, the desired outcome).Risk profile
Low. The skill is markdown-only, no compilation, no execution path through the runtime. The most material change is to the public docs site (internal specs no longer indexed). External links to those spec URLs will break, but they were never intended to be public.
Test plan
/generate-feature-docs docs/superpowers/specs/drafts/2026-04-28-generate-feature-docs-skill-design.mdto confirm the slash command is auto-discovered. Replyabortat the readiness prompt; expect a clean exit with no files written./superpowers/.cargo fmt,cargo clippy,vitest,npm run formatindocs/,npm run buildindocs/. Thecargo test --workspaceViceroy failure is pre-existing and unrelated to this branch.Follow-up issues
How to use the skill
After this lands, any team member who pulls
maincan invoke/generate-feature-docs <spec-path>against any spec underdocs/superpowers/specs/implemented/(withstatus: implementedfrontmatter) to generate or augment its publisher-facing guide page. The skill verifies handles (config keys, endpoints, headers, error variants) againstcrates/, surfaces drift before writing prose, and commits the result on user approval. See the design spec for the full behavior contract.