Spec Creator
Create implementation-grade SPEC.md files through structured brainstorming, then drafting, then
self-review. The output is a single monolithic Markdown specification that an AI coding agent can
implement without asking clarifying questions.
Quality Bar
The target quality level is a portable implementation contract — the kind of document a
principal engineer writes so any competent engineer (or AI agent) in any language can build a
conforming implementation. Read quality-bar.md for the full quality rubric before
starting any spec.
Key quality markers (internalize these, don't just check them off):
- Every entity field has a type, default value (if applicable), and validation rule
- Every error has a named category and explicit recovery behavior
- Every state transition has explicit triggers and outcomes
- Every boundary says what is in scope AND what is out of scope
- Reference algorithms are provided in language-agnostic pseudocode for complex logic
- Configuration has a cheat-sheet section for quick agent consumption
- The test/validation matrix maps back to spec sections
- Forward compatibility is addressed (e.g., "unknown keys should be ignored")
- The spec is self-contained: an agent reading only this file can implement the system
Workflow
The spec creation process has 4 phases. Follow them in order.
Phase 1: Intake and Calibration
When the user provides their input (anything from a one-liner to a detailed brain-dump):
Parse what's already been said. Extract every concrete decision, constraint, technology
choice, boundary, entity, and opinion from the user's input.
Classify input depth:
- Sparse (1-3 sentences, just an idea): The user needs heavy discovery. Start with
foundational questions about problem, users, scope.
- Medium (a paragraph or two with some decisions made): The user has direction. Focus on
filling architectural and domain-model gaps.
- Rich (detailed brain-dump with technology choices, entity sketches, constraints): The user
has thought deeply. Focus on edge cases, failure modes, and contract boundaries.
Acknowledge what you understood. Before asking questions, write a short summary (3-5
sentences) of what you extracted from their input. This lets the user correct misunderstandings
early. Frame it as: "Here's what I'm taking as given from what you've described: [summary]. Now
let me ask about the gaps."
Phase 2: Brainstorming Rounds
Ask questions one round at a time. Each round should have 3-6 questions, grouped by a coherent
theme. Do NOT dump all questions at once. Wait for the user's answers before proceeding.
Continue rounds until all 10 knowledge domains are sufficiently covered for the task's complexity.
Not every domain applies to every task — use judgment. But never skip a domain without consciously
deciding it's irrelevant.
Read brainstorm-domains.md for the full questioning framework. Here is the summary:
The 10 Knowledge Domains:
- Problem & Scope — What problem? Who benefits? What's the boundary?
- Architecture & Components — What are the pieces? How do they connect?
- Domain Model — What are the core entities, their fields, relationships?
- Configuration & Inputs — What's configurable? Defaults? Validation?
- State & Lifecycle — What states exist? What triggers transitions?
- Integration Contracts — External systems, protocols, API shapes?
- Failure & Recovery — What breaks? How does the system recover?
- Security & Safety — Trust boundaries? Invariants? Secrets?
- Observability — Logs, metrics, debugging? What does an operator need?
- Testing & Validation — How do you prove correctness?
Questioning strategy by input depth:
- Sparse input: Start with Domain 1 (Problem & Scope) and Domain 2 (Architecture). These
unlock everything else. Expect 5-8 rounds total.
- Medium input: Start with whichever domain has the biggest gaps. Expect 3-5 rounds.
- Rich input: Jump straight to edge cases — Domains 7 (Failure), 8 (Security), and 10
(Testing) are usually the least-specified even in detailed brain-dumps. Expect 2-4 rounds.
Rules for good brainstorming questions:
- Ask about decisions, not preferences. "What happens when the webhook delivery fails after 3
retries?" not "How do you feel about retry strategies?"
- Offer concrete options when the decision space is bounded. "Should failed jobs be retried with
exponential backoff (recommended), fixed delay, or not retried?" — this accelerates the user.
- Flag when you're making an assumption. "I'm assuming WebSocket for real-time updates — push back
if you prefer SSE or polling."
- Ask about what should NOT happen. Non-goals and anti-patterns are as valuable as goals.
- Ask about the consumer agent's needs. "Will the implementing agent need to handle graceful
shutdown, or is hard-kill acceptable?"
When to stop brainstorming:
Stop when you can mentally draft every section header AND fill in the first paragraph of each
section without guessing. If you find yourself thinking "I'd have to make something up for the
failure recovery section," you need another round.
Phase 3: Drafting the SPEC.md
Read section-templates.md for the canonical section structure and what belongs in each
section. Then draft the full spec.
Section Structure (adapt to the task — not every section applies to every system):
1. Problem Statement
2. Goals and Non-Goals
3. System Overview (components, layers, external deps)
4. Core Domain Model (entities, fields, types, normalization)
5. [Domain-Specific Contract] (e.g., Workflow Spec, API Spec, Protocol Spec)
6. Configuration Specification (schema, defaults, resolution, dynamic reload)
7. State Machine / Lifecycle (states, transitions, triggers)
8. Core Algorithms (scheduling, routing, processing — pseudocode)
9. [Integration Contracts] (per external system)
10. [Subsystem Contracts] (per major internal subsystem)
11. Prompt/Context Assembly (if AI-related)
12. Logging, Status, and Observability
13. Failure Model and Recovery Strategy
14. Security and Operational Safety
15. Reference Algorithms (language-agnostic pseudocode)
16. Test and Validation Matrix
17. Implementation Checklist (Definition of Done)
Drafting rules — these are critical for agent-consumable specs:
Every field needs a type. Not "the timeout setting" but
"turn_timeout_ms (integer) — Default: 3600000 (1 hour)".
Every default needs a value. If something is optional, say what happens when it's absent.
Never "defaults to a reasonable value" — always "defaults to 30000".
Every error needs a name and a recovery. Not "handle errors gracefully" but
"workspace_creation_failed — Fail the current run attempt. Orchestrator will retry with
exponential backoff."
Every boundary needs both sides. "Symphony IS a scheduler/runner. Symphony is NOT a ticket
writer." Agents take unstated scope as license to expand.
Use pseudocode for complex logic. Any algorithm with branching, loops, or sequencing gets a
pseudocode block. Use function name(params): style, not any specific language.
Include a config cheat sheet. A flat list of every config key, its type, and its default.
Agents parse this faster than hunting through nested sections.
Include "Important boundary" and "Important nuance" callouts. These prevent the most common
misimplementation. Place them inline where the misunderstanding would occur.
State validation profiles in the test matrix. "Core Conformance" (must-pass), "Extension
Conformance" (if-you-ship-it-test-it), "Integration Profile" (needs real credentials).
End with a Definition of Done checklist. This is the literal implementation punch-list.
Group by conformance profile.
Write for the agent, not for a human skimming. Be explicit, repetitive where it aids
clarity, and never ambiguous. Agents don't infer intent — they follow contracts. Intentional
redundancy (like a config cheat sheet that restates what's in the config section) is a feature,
not a bug.
Output format:
- Default: single monolithic
SPEC.md file
- If the draft exceeds ~2000 lines, offer to split into logical files:
SPEC.md (core spec)
DOMAIN_MODEL.md (entities, fields, normalization)
TEST_MATRIX.md (validation matrix + implementation checklist)
- Create the file(s) in
/home/claude/ during drafting, then copy to /mnt/user-data/outputs/
when presenting.
Phase 4: Self-Review
Before presenting the spec to the user, run a self-review against the quality bar. Read
self-review-checklist.md for the full checklist.
Self-review process:
Walk through every section and ask: "Could an AI coding agent implement this section without
asking me a single clarifying question?" If no, fix it.
Check for these common spec failures:
- Vague defaults: Any "reasonable", "appropriate", "as needed" → replace with concrete value
- Missing error handling: Any operation without a failure path → add one
- Implicit state transitions: Any state change without an explicit trigger → add the trigger
- Unbounded behavior: Any loop, retry, or timeout without a cap → add the cap
- Unclear boundaries: Any component without explicit in-scope/out-of-scope → add them
- Missing types: Any field without a type annotation → add the type
- Hand-wavy sections: Any section that says "implementation-defined" without documenting what
the implementation must decide → enumerate the decisions
Produce a Review Summary (shown to user alongside the spec):
- Number of sections
- Total line count
- Gaps found and fixed during self-review
- Any remaining
[TBD] markers with explanation of what's needed
- Confidence assessment: "Ready for implementation" / "Needs user input on N items"
If the spec exceeds ~2000 lines, proactively offer to split it.
Iteration
After presenting the spec, the user may request changes. When iterating:
- Apply changes surgically — don't regenerate the entire spec for a localized fix
- If the user's feedback reveals a gap in your understanding, you may need another brainstorming
round before editing
- Re-run the self-review checklist on modified sections
- Track iteration count and present a changelog summary
Anti-Patterns to Avoid
- The PRD trap: Don't write user stories, acceptance criteria, or business justification. This
is an implementation contract, not a product requirements doc.
- The HLD trap: Don't stop at boxes-and-arrows. Every component needs its internal contract.
- The design doc trap: Don't include alternatives-considered or decision rationale (unless the
user explicitly wants ADRs). The spec is the decision.
- The tutorial trap: Don't explain concepts. Assume the reader (an AI agent) knows programming,
distributed systems, and common patterns. Explain domain-specific decisions.
- The over-prescription trap: Don't specify implementation language, framework, or library
unless the user explicitly chose them. Keep the spec portable.
- The under-specification trap: Don't say "handle errors appropriately" or "use standard
practices." Every behavior must be explicit enough to implement without judgment calls.
1---2name: spec-creator3description: >4 Create production-grade SPEC.md files — portable implementation contracts that any AI coding agent5 can build from without follow-up questions. Use this skill whenever the user wants to write a spec,6 specification, technical spec, implementation contract, SPEC.md, or service specification for any7 software task. Also trigger when the user says "spec out", "write a spec for", "create a spec",8 "define the contract for", or describes a system they want built and needs a thorough specification9 before implementation. This skill works for backend services, full-stack apps, CLI tools, SDKs,10 developer tools, and any domain. It produces specs at the level of a principal-engineer-authored11 portable implementation contract — not a PRD, not an HLD, but the artifact that sits between12 architecture and code.13triggers:14 - "write a spec"15 - "create SPEC.md"16 - "implementation contract"17 - "spec out this feature"18metadata:19 source: https://skillmd.com/skills/praxstack/spec-creator20---2122# Spec Creator2324Create implementation-grade SPEC.md files through structured brainstorming, then drafting, then25self-review. The output is a single monolithic Markdown specification that an AI coding agent can26implement without asking clarifying questions.2728## Quality Bar2930The target quality level is a **portable implementation contract** — the kind of document a31principal engineer writes so any competent engineer (or AI agent) in any language can build a32conforming implementation. Read [quality-bar.md](./quality-bar.md) for the full quality rubric before33starting any spec.3435Key quality markers (internalize these, don't just check them off):3637- Every entity field has a type, default value (if applicable), and validation rule38- Every error has a named category and explicit recovery behavior39- Every state transition has explicit triggers and outcomes40- Every boundary says what is in scope AND what is out of scope41- Reference algorithms are provided in language-agnostic pseudocode for complex logic42- Configuration has a cheat-sheet section for quick agent consumption43- The test/validation matrix maps back to spec sections44- Forward compatibility is addressed (e.g., "unknown keys should be ignored")45- The spec is self-contained: an agent reading only this file can implement the system4647## Workflow4849The spec creation process has 4 phases. Follow them in order.5051### Phase 1: Intake and Calibration5253When the user provides their input (anything from a one-liner to a detailed brain-dump):54551. **Parse what's already been said.** Extract every concrete decision, constraint, technology56 choice, boundary, entity, and opinion from the user's input.57582. **Classify input depth:**59 - **Sparse** (1-3 sentences, just an idea): The user needs heavy discovery. Start with60 foundational questions about problem, users, scope.61 - **Medium** (a paragraph or two with some decisions made): The user has direction. Focus on62 filling architectural and domain-model gaps.63 - **Rich** (detailed brain-dump with technology choices, entity sketches, constraints): The user64 has thought deeply. Focus on edge cases, failure modes, and contract boundaries.65663. **Acknowledge what you understood.** Before asking questions, write a short summary (3-567 sentences) of what you extracted from their input. This lets the user correct misunderstandings68 early. Frame it as: "Here's what I'm taking as given from what you've described: [summary]. Now69 let me ask about the gaps."7071### Phase 2: Brainstorming Rounds7273Ask questions **one round at a time**. Each round should have 3-6 questions, grouped by a coherent74theme. Do NOT dump all questions at once. Wait for the user's answers before proceeding.7576Continue rounds until all 10 knowledge domains are sufficiently covered for the task's complexity.77Not every domain applies to every task — use judgment. But never skip a domain without consciously78deciding it's irrelevant.7980Read [brainstorm-domains.md](./brainstorm-domains.md) for the full questioning framework. Here is the summary:8182**The 10 Knowledge Domains:**83841. **Problem & Scope** — What problem? Who benefits? What's the boundary?852. **Architecture & Components** — What are the pieces? How do they connect?863. **Domain Model** — What are the core entities, their fields, relationships?874. **Configuration & Inputs** — What's configurable? Defaults? Validation?885. **State & Lifecycle** — What states exist? What triggers transitions?896. **Integration Contracts** — External systems, protocols, API shapes?907. **Failure & Recovery** — What breaks? How does the system recover?918. **Security & Safety** — Trust boundaries? Invariants? Secrets?929. **Observability** — Logs, metrics, debugging? What does an operator need?9310. **Testing & Validation** — How do you prove correctness?9495**Questioning strategy by input depth:**9697- **Sparse input:** Start with Domain 1 (Problem & Scope) and Domain 2 (Architecture). These98 unlock everything else. Expect 5-8 rounds total.99- **Medium input:** Start with whichever domain has the biggest gaps. Expect 3-5 rounds.100- **Rich input:** Jump straight to edge cases — Domains 7 (Failure), 8 (Security), and 10101 (Testing) are usually the least-specified even in detailed brain-dumps. Expect 2-4 rounds.102103**Rules for good brainstorming questions:**104105- Ask about decisions, not preferences. "What happens when the webhook delivery fails after 3106 retries?" not "How do you feel about retry strategies?"107- Offer concrete options when the decision space is bounded. "Should failed jobs be retried with108 exponential backoff (recommended), fixed delay, or not retried?" — this accelerates the user.109- Flag when you're making an assumption. "I'm assuming WebSocket for real-time updates — push back110 if you prefer SSE or polling."111- Ask about what should NOT happen. Non-goals and anti-patterns are as valuable as goals.112- Ask about the consumer agent's needs. "Will the implementing agent need to handle graceful113 shutdown, or is hard-kill acceptable?"114115**When to stop brainstorming:**116117Stop when you can mentally draft every section header AND fill in the first paragraph of each118section without guessing. If you find yourself thinking "I'd have to make something up for the119failure recovery section," you need another round.120121### Phase 3: Drafting the SPEC.md122123Read [section-templates.md](./section-templates.md) for the canonical section structure and what belongs in each124section. Then draft the full spec.125126**Section Structure (adapt to the task — not every section applies to every system):**127128```1291. Problem Statement1302. Goals and Non-Goals1313. System Overview (components, layers, external deps)1324. Core Domain Model (entities, fields, types, normalization)1335. [Domain-Specific Contract] (e.g., Workflow Spec, API Spec, Protocol Spec)1346. Configuration Specification (schema, defaults, resolution, dynamic reload)1357. State Machine / Lifecycle (states, transitions, triggers)1368. Core Algorithms (scheduling, routing, processing — pseudocode)1379. [Integration Contracts] (per external system)13810. [Subsystem Contracts] (per major internal subsystem)13911. Prompt/Context Assembly (if AI-related)14012. Logging, Status, and Observability14113. Failure Model and Recovery Strategy14214. Security and Operational Safety14315. Reference Algorithms (language-agnostic pseudocode)14416. Test and Validation Matrix14517. Implementation Checklist (Definition of Done)146```147148**Drafting rules — these are critical for agent-consumable specs:**1491501. **Every field needs a type.** Not "the timeout setting" but151 "`turn_timeout_ms` (integer) — Default: `3600000` (1 hour)".1521532. **Every default needs a value.** If something is optional, say what happens when it's absent.154 Never "defaults to a reasonable value" — always "defaults to `30000`".1551563. **Every error needs a name and a recovery.** Not "handle errors gracefully" but157 "`workspace_creation_failed` — Fail the current run attempt. Orchestrator will retry with158 exponential backoff."1591604. **Every boundary needs both sides.** "Symphony IS a scheduler/runner. Symphony is NOT a ticket161 writer." Agents take unstated scope as license to expand.1621635. **Use pseudocode for complex logic.** Any algorithm with branching, loops, or sequencing gets a164 pseudocode block. Use `function name(params):` style, not any specific language.1651666. **Include a config cheat sheet.** A flat list of every config key, its type, and its default.167 Agents parse this faster than hunting through nested sections.1681697. **Include "Important boundary" and "Important nuance" callouts.** These prevent the most common170 misimplementation. Place them inline where the misunderstanding would occur.1711728. **State validation profiles in the test matrix.** "Core Conformance" (must-pass), "Extension173 Conformance" (if-you-ship-it-test-it), "Integration Profile" (needs real credentials).1741759. **End with a Definition of Done checklist.** This is the literal implementation punch-list.176 Group by conformance profile.17717810. **Write for the agent, not for a human skimming.** Be explicit, repetitive where it aids179 clarity, and never ambiguous. Agents don't infer intent — they follow contracts. Intentional180 redundancy (like a config cheat sheet that restates what's in the config section) is a feature,181 not a bug.182183**Output format:**184185- Default: single monolithic `SPEC.md` file186- If the draft exceeds ~2000 lines, offer to split into logical files:187 - `SPEC.md` (core spec)188 - `DOMAIN_MODEL.md` (entities, fields, normalization)189 - `TEST_MATRIX.md` (validation matrix + implementation checklist)190- Create the file(s) in `/home/claude/` during drafting, then copy to `/mnt/user-data/outputs/`191 when presenting.192193### Phase 4: Self-Review194195Before presenting the spec to the user, run a self-review against the quality bar. Read196[self-review-checklist.md](./self-review-checklist.md) for the full checklist.197198**Self-review process:**1992001. Walk through every section and ask: "Could an AI coding agent implement this section without201 asking me a single clarifying question?" If no, fix it.2022032. Check for these common spec failures:204 - **Vague defaults:** Any "reasonable", "appropriate", "as needed" → replace with concrete value205 - **Missing error handling:** Any operation without a failure path → add one206 - **Implicit state transitions:** Any state change without an explicit trigger → add the trigger207 - **Unbounded behavior:** Any loop, retry, or timeout without a cap → add the cap208 - **Unclear boundaries:** Any component without explicit in-scope/out-of-scope → add them209 - **Missing types:** Any field without a type annotation → add the type210 - **Hand-wavy sections:** Any section that says "implementation-defined" without documenting what211 the implementation must decide → enumerate the decisions2122133. Produce a **Review Summary** (shown to user alongside the spec):214 - Number of sections215 - Total line count216 - Gaps found and fixed during self-review217 - Any remaining `[TBD]` markers with explanation of what's needed218 - Confidence assessment: "Ready for implementation" / "Needs user input on N items"2192204. If the spec exceeds ~2000 lines, proactively offer to split it.221222## Iteration223224After presenting the spec, the user may request changes. When iterating:225226- Apply changes surgically — don't regenerate the entire spec for a localized fix227- If the user's feedback reveals a gap in your understanding, you may need another brainstorming228 round before editing229- Re-run the self-review checklist on modified sections230- Track iteration count and present a changelog summary231232## Anti-Patterns to Avoid233234- **The PRD trap:** Don't write user stories, acceptance criteria, or business justification. This235 is an implementation contract, not a product requirements doc.236- **The HLD trap:** Don't stop at boxes-and-arrows. Every component needs its internal contract.237- **The design doc trap:** Don't include alternatives-considered or decision rationale (unless the238 user explicitly wants ADRs). The spec is the decision.239- **The tutorial trap:** Don't explain concepts. Assume the reader (an AI agent) knows programming,240 distributed systems, and common patterns. Explain domain-specific decisions.241- **The over-prescription trap:** Don't specify implementation language, framework, or library242 unless the user explicitly chose them. Keep the spec portable.243- **The under-specification trap:** Don't say "handle errors appropriately" or "use standard244 practices." Every behavior must be explicit enough to implement without judgment calls.