draft-openspec-docs

fission-ai/openspec

Collaborative page-drafting mode for OpenSpec docs with scratch-plan workflow and user-in-the-loop iteration.

What is draft-openspec-docs?

A structured drafting skill for OpenSpec documentation that builds a scratch plan (purpose, structure, steps) inside the target page, iterates with the user, then drafts one section at a time. Use when rewriting a page from scratch or shaping a new page collaboratively.

Builds a scratch plan section with purpose, structure, and numbered draft steps
Iterates on the plan with the user before any drafting begins
Drafts one approved section at a time into the page
Consolidates cross-page updates (README, message map, sync config)
Cleans up scratch sections and validates retrievability before publishing

How to install draft-openspec-docs

npx skills add https://github.com/fission-ai/openspec --skill draft-openspec-docs

Prerequisites

Access to the OpenSpec repository
The write-openspec-docs skill (loaded before drafting)
The no-ai-slop skill (loaded before drafting)
Familiarity with OpenSpec docs structure (docs-lab/README.md, message-map.md)

Claude Code

Cursor

Windsurf

Cline

How to use draft-openspec-docs

1.Run the skill with the target page path as the argument
2.Review the generated scratch plan (purpose, structure, notes)
3.Edit and iterate on the plan with the user until approved
4.Call a draft step ID (e.g., D1, D2) to draft that section
5.Repeat step 3 until all sections are drafted
6.Run consolidation to update cross-references and sync config
7.Delete the scratch block and validate the final page

Use cases

Good for

Rewriting an existing OpenSpec docs page from scratch with team input
Creating a new documentation page while gathering user feedback on structure
Planning and drafting a complex multi-section page incrementally
Ensuring consistency across OpenSpec docs during major content updates
Collaboratively refining page purpose and scope before committing to prose

Who it's for

OpenSpec documentation maintainers
Technical writers collaborating with product teams
Teams doing docs-first design or planning
Contributors reshaping existing documentation pages

draft-openspec-docs FAQ

When should I use this instead of writing directly?

Use this when the page needs significant reshaping, is new and unscoped, or involves multiple stakeholders. Plan iterations are cheap; page rewrites are expensive.

Can the user edit the plan directly between turns?

Yes. User edits to the plan file are treated as decisions, not drift. Record them in the plan itself, not only in chat.

What does consolidation do?

It updates the README goal line, message map, sync config, and any cross-links pointing to the page, then validates with node website/scripts/sync-docs.mjs.

Do I need to verify facts while drafting?

Yes. Verify each fact against source before writing; use grep to check the repository rather than relying on memory.

What happens to the scratch section?

Delete it during cleanup, after running retrievability and glance tests at desktop and narrow widths.

Full instructions (SKILL.md)

Source of truth, from fission-ai/openspec.

name: draft-openspec-docs description: Collaborative page-drafting mode for the OpenSpec docs. Builds a scratch plan inside the target page (purpose, structure, numbered draft steps), iterates on it with the user, then drafts one section per approved step and cleans up after itself. Use when a page needs a from-scratch rewrite or a new page is being shaped with the user in the loop. argument-hint: target page

Draft OpenSpec docs (scratch-plan workflow)

You are shaping a docs page with the user in the loop. The page is planned and reviewed inside the page itself, then drafted one section at a time. Load write-openspec-docs (the style authority) and no-ai-slop before drafting anything.

1. Set up the scratch section

Strip the page to its title and > goal line, then add a working section below them:

## Scratch: page plan (delete before publish)

### Purpose

### Structure

Purpose: 3-5 dot points. Who the reader is and what they come to look up, what the page covers, what it links out to. Check docs-lab/README.md (the page's goal line) and docs-lab/message-map.md (the questions routed here) before writing it.
Structure: a numbered list of the page's sections, one line each naming the section and the shape of its content (table, fence, tree, bullets).
Say what the page will do, never what it won't. Plain words and short bullets; the user reads this in their editor.

2. Iterate until the plan is approved

Plan edits are cheap; page edits aren't. Reshape the plan as many times as the user asks before drafting.
Record every decision in the plan itself, not only in chat. Add a ### Notes list for follow-ups that belong to other pages and product observations found along the way.
The user may edit the file directly between turns; their edits are decisions, not drift to revert.
Surface one open call at a time, with a recommendation.

3. Add the draft plan, then draft step by step

Once the structure holds, add a ### Draft plan below the notes: one step per page section, each with an ID and a readable title (**D1. Goal line and intro**), ending with a consolidation step (cross-page updates) and a cleanup step. Then:

Wait for the user to call a step ID. Draft exactly that step, into the page above the scratch block.
Verify each fact against source before writing it; a cheap grep beats trust. Reference content shows the raw contract (templates, instructions, config) verbatim in fences, linked to the file on GitHub, rather than paraphrasing it.
Keep sibling sections on a repeatable sub-structure so the page scans as one system.
Mark the step (done) in the plan, report what landed, and name the next step.

4. Consolidation and cleanup

Consolidation: update everything that points at the page. The README goal line (verbatim match with the page's > line), the message map, the sync config (website/docs.sync.config.mjs), and any cross-links found by grepping the tree. Run node website/scripts/sync-docs.mjs to validate.
Cleanup: delete the scratch block, run the retrievability and glance tests from write-openspec-docs at desktop and narrow widths, and flip the page's message-map row to Answered if its prose landed.