Spec builder

Spec Builder

Turn a rough idea into a build-ready specification by interviewing the user through four phases, then emit two artifacts to ./output/specs/<project-slug>/:

• spec.md — the human-readable specification.
• manifest.yaml — a structured, machine-readable summary a downstream autonomous builder can consume.

Why this skill exists

People describe what they want loosely ("a playbook that configures all my ESXi hosts"). A good spec is the difference between an autonomous build that nails it and one that flails. The two things that make this skill valuable:

1. A real interview. Don't guess the user's intent — draw it out. The cost of one clarifying round is tiny compared to building the wrong thing.
2. Standing on giants. The single biggest quality lever in infra/automation projects is reusing official, maintained, vendor-provided components instead of reinventing them. Hand-rolled shell-outs and bespoke modules rot; vmware.vmware, kubernetes.core, boto3, the Terraform AWS provider do not. So this skill verifies recommended components live against their registries — confirming the name is exact, the collection/package actually exists, it's maintained, and capturing the current version. A spec that names a hallucinated collection is worse than useless.

The four phases

Run these interactively. After Phase 1 and Phase 3 especially, stop and let the user respond — this is a conversation, not a form you fill in silently. Summarize what you heard before moving on.

Phase 1 — Discovery

Open with a short, plain-language set of questions. Adapt them to what the user already told you; don't re-ask what they've answered. Cover:

• Goal in one sentence — what does success look like?
• Target users / platform — who runs this, and where (AAP, a laptop, CI, a cluster)?
• 3–5 core features — the things it must do.
• Technology preferences — any languages, tools, or collections they already want.
• Constraints — auth model, network boundaries, idempotency needs, data sources, compliance, existing systems it must integrate with.

If the user gave a rich prompt already (like the ESXi example), extract the answers from it and present them back as "here's what I understood — correct me," rather than interrogating from scratch.

Phase 2 — Elaboration

For each core feature, expand it so the spec is concrete enough to build from. For each one capture:

• Sub-features — the discrete steps/capabilities inside it.
• User stories — "as a <role>, I want <X> so that <Y>" for the non-obvious ones.
• Edge cases & failure modes — what happens when a host is unreachable, a credential is wrong, input is empty, the run is re-run (idempotency).
• Integrations — the external systems, APIs, providers, modules, or collections each feature touches. This list feeds Phase 3.

Keep this tight — elaborate enough to remove ambiguity, not so much that you're designing line by line.

Phase 3 — Technology recommendation (with live verification)

Recommend a stack. Favor the user's stated preferences first, then these defaults where they fit (this is a bias, not a cage — pick the right tool):

Domain	Favored default
Infrastructure-as-Code	Terraform
Configuration-as-Code	Ansible / Ansible Automation Platform
CLI tooling	Go
Data science & scripting	Python
Event streaming	Kafka
Source control / CI	GitLab
Containerization	Docker / Podman

Then the core move: for every collection, package, provider, or module you intend to name in the spec, verify it live. See references/registries.md for exactly how to query each registry. The goal: exact name, confirmed existence, maintenance signal, and current version. If a component you expected doesn't exist or is abandoned, find the maintained alternative and say so.

Present the recommended stack and the verified component list back to the user for sign-off before writing the spec. This is the second natural pause point.

Phase 4 — Specification output

Once the user signs off, write both artifacts to ./output/specs/<project-slug>/ (create the folder). <project-slug> is a short kebab-case name derived from the goal.

• spec.md follows the template in references/manifest-schema.md. It must include a proposed project/folder structure that follows that ecosystem's conventions (an Ansible role layout looks nothing like a Go CLI layout — match the idiom), and a testing plan that aims for high coverage with mocking of external systems (no live vCenter in a unit test).
• manifest.yaml follows the schema in references/manifest-schema.md — the structured digest of features, the verified component list (with versions), and test targets.

Read references/manifest-schema.md before writing these so both artifacts match the expected shape.

After writing, tell the user the paths and give a 3–5 line summary of what was produced.

Delivering the files

Write the actual files with the normal file-writing tools. Don't dump the full spec into the chat — the user wants the artifacts on disk; a short summary in chat is enough.

A note on scope

If the user only wants to brainstorm and isn't ready for a spec, don't force all four phases — help them think, and offer the full spec when they're ready. If they hand you a fully-formed prompt and say "just build the spec," you can compress Phases 1–2 into a single "here's what I understood" confirmation and move quickly to verification and output. Match their pace.