| name | Spec Page Brief Format |
| description | Use this skill when the discovery agent needs to produce a structured brief, or when the build agent needs to read one. Defines what a complete brief contains, all eight required sections, the artifact naming convention, and the completeness checklist discovery must pass before handing off to @blueprint. |
| version | 0.1.0 |
Spec Page Brief Format
What a complete brief is
A brief is the single artifact that connects discovery to build. It is not a summary of a conversation — it is a structured decision document that lets the build agent execute without asking any questions. If the build agent would need to ask a question, the brief is incomplete.
Think of it like a construction permit: the contractor (build agent) must be able to build from the permit alone. If the permit is vague, the building will be wrong.
Required sections
Every brief must contain all eight sections. No section may be empty or contain "TBD."
1. Concept name
The canonical name for this product, tool, or concept. This becomes the page title, the filename slug, and the artifact prefix.
Format: plain text, no brackets.
Example: Spec Page Agentic Team
2. One-sentence description
What this is, in one sentence. Not a tagline — a definition. Should answer: what does it do, and who is it for?
Example: A Claude Code plugin that takes any idea, brief, or URL as input and produces a complete, deployed HTML spec page, built on The Point CSS framework and optimized for both traditional SEO and AI discoverability.
3. Target audience
Who is this for? Name the person, their context, and what they already know. Be specific.
Example: Software engineers and CTOs who build on Claude Code and want to publish ideas as structured, findable spec pages — not designers, and not non-technical founders.
4. Core insight
What makes this interesting or different? The one thing that, if the page communicates it clearly, makes the reader lean in. This is not a feature list — it is the argument the page is making.
Example: AI systems don't rank pages — they extract answers from them. A page built for AI discoverability is a page full of clear, specific, attributable answers to real questions. That's a different discipline than traditional SEO, and this system applies both.
5. Page sections (ordered)
An ordered list of what the page covers. Each item is a section name plus a one-sentence description of what that section does.
Example:
1. Hero — names the system and its core output (one command → live page)
2. The Pipeline — visual diagram of all seven agents with one-line descriptions
3. The Agents — detailed section per agent: role, inputs, outputs, constraints
4. Skills — the three skill files and what they carry
5. SEO & AI SEO — what the optimization agents do and why it matters
6. Open Source Strategy — how the plugin ships and what gets published
7. Build It — CTA to the GitHub repo or to start a new spec page
6. Tone and positioning
How this page should sound. One or two words (e.g., "precise and direct"), followed by two sentences: what the page is, and what it is not.
Example: Precise and direct. This is a technical spec page for a technical audience — not a marketing landing page. No hype, no vague claims, no "powerful" or "seamless." Every claim is specific and checkable.
7. Visual references or preferences
What The Point mood to use (or "none — let @blueprint decide"), any specific visual direction, any constraints.
Example: Slate mood — professional, restrained, trustworthy. Dark background preferred. No warm tones — this is a systems tool, not a creative service.
8. URL (if applicable)
The URL being documented, if any. This is the source material for discovery in URL mode.
Example: https://github.com/revans/spec-page — or none if building from a brief.
Optional sections
These two sections come from the discovery agent's research pass. They are optional — but if the research pass found relevant information, they must be included. "Optional" means the research may come back empty, not that the agent can skip looking.
9. Competitive landscape (optional)
What already exists that's closest to this concept. Name specific alternatives, what each does, and where this concept's white space is. If the research found nothing comparable, write that explicitly: "No direct alternatives found — [reason]."
This section feeds the AI SEO agent's differentiation question ("How is [concept name] different from [closest alternative]?"). If it's empty, that question will have a thin answer.
Example:
Closest alternatives:
- Mintlify: generates documentation pages from code comments. Focused on API docs, not
product concept pages. No design system, no SEO optimization, no AI discoverability.
- Notion AI: can generate page content but produces a Notion page, not a deployed HTML
spec page. No brand identity layer.
White space: nothing generates a deployed, branded, SEO-optimized spec page from a
brief in one command. The concept-to-live-page pipeline doesn't exist as a single tool.
10. Speculative elements (optional)
Claims in the brief or concept that go beyond what's currently demonstrated or proven. Flag each one explicitly. Speculative is not the same as wrong — it means the claim is forward-looking and should not be stated as established fact on the page.
If nothing is speculative, write: none — all claims are based on demonstrated behavior or established technology.
This section prevents the build agent from writing headlines that sound like facts but are actually predictions, and gives the AI SEO agent's citation audit a head start on vague or unverifiable claims.
Example:
- "AI systems will cite pages with AP reading layer annotations more frequently" —
plausible inference, not yet measured. Frame as hypothesis on the page, not fact.
- "Seven agents in sequence is the right number" — design decision, not proven.
The page should present it as an architectural choice, not an industry standard.
Artifact location
Brief files are written to:
docs/briefs/NNN-[concept-name]/NNN.01-dis-[concept-name].md
Where NNN is the next available sequence number (zero-padded to 3 digits), and [concept-name] is a lowercase-hyphenated slug derived from the concept name.
Example: docs/briefs/001-spec-page-agentic-team/001.01-dis-spec-page-agentic-team.md
Completeness check
Before handing off, discovery must verify:
If any check fails, the brief is not complete. Discovery must resolve it before handing off.
