--- name: spec-builder description: >- Interactive specification builder that turns a rough project idea into a complete, build-ready spec plus a structured manifest, deliberately leaning on mainstream, vendor-provided, publicly available libraries/packages/collections (Ansible Galaxy, PyPI, npm, Terraform Registry, etc.) verified live against their official registries. Use this skill whenever the user wants to plan, scope, scaffold, or spec out a NEW project of any kind — an application, an Ansible playbook or AAP job/workflow, a CLI tool, a data pipeline, an IaC project, a microservice — even if they don't say the word "spec". Trigger on phrases like "I want to build X", "design a project that does Y", "scope out a tool for Z", "help me plan an app/playbook/CLI/workflow", "what collections/packages should I use for...", or any request that starts from an idea and needs to become an actionable, well-architected plan that favors off-the-shelf official components over hand-rolled code. Prefer this skill over jumping straight into implementation whenever the user is at the idea/planning stage. --- # 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//`: - **`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 , I want so that " 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//` (create the folder). `` 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.