Skill v1.0.0
currentLLM-judged scan98/100version: "1.0.0" name: build-spec description: Translate the PRD into a practical technical implementation plan.
Guided Build: Spec
Read references/build-guide.md, then follow this command.
This is the Codex version of the learning curriculum's spec command.
Goal
Turn the PRD into a technical spec detailed enough that Codex can build from it without guessing.
Interview first, propose second. Adapt depth to the participant's experience level.
Preconditions
Read .devpost-hackathon-state.json.
If the state file does not exist, direct the user to $start-hackathon.
Read everything in docs/hackathon-build/. If scope.md or prd.md is missing, direct the user to the missing prior command.
Flow
Interview in small batches of related questions (per the build guide). You are a technical collaborator: interview first, propose second. The participant should walk away understanding their app intimately enough to explain it to someone else.
Mandatory beats:
- Tech preferences, calibrated to the learner profile — newer builders: "What sounds
interesting to you?" plus simple recommendations; experienced builders: "Preferred stack? Any strong opinions?" Favor boring, reliable choices over novel plumbing — winners spend their time on the product, not the infrastructure.
- Deployment: local only, or a deployed URL? (Running locally with screenshots is a
perfectly good answer.)
- Research the stack: rely on what you already know for well-known frameworks, libraries, and APIs; consult current official docs only for version-specific or fast-moving details you are unsure of, batching those lookups. Do not search for well-known docs you can already summarize.
- Propose architecture section by section, explicitly mapping PRD epics to components —
propose briefly, explain why, then ask for their reaction: "Here's how I'm picturing the data flow — does this match what you're thinking?"
- Build the file structure and data flow together: every file and folder annotated with
its purpose, then walk the lifecycle of the app's most important piece of data from input to storage to display.
After mandatory beats, offer a deepening round per the build guide. Good spec deepening topics: state ("for every piece of data — where does it live, how does it get updated, what happens when they navigate away and come back?"), exact API contracts (endpoint, payload, response shape — this prevents build stalls), error strategy ("the 2-3 places this will actually break during a demo"), demo flow ("if the coolest feature is hard to demo, that's a spec problem worth solving"), and an architecture self-review: audit your own draft and surface 2-3 findings as genuine questions for the participant — including complexity that doesn't match the time budget ("this data model has six tables for an evening's build").
Output
Use references/templates/spec-template.md.
Create or update:
docs/hackathon-build/spec.mddocs/hackathon-build/build-notes.md
Critical requirements:
- every architectural component has headings
- PRD epics are cross-referenced
- major dependencies and APIs have documentation links
- file structure and data flow are explicit
- if
$build-checklistneeds to point to it, it has its own heading
State Update
Set:
learning.current_steptospec- add
prdtolearning.completed_stepsif missing next_commandtobuild-checklist
Presentation Output
Compose the response in-context per references/plugin-runtime.md ("Composing the Response"): read references/content/learning/spec.md, strip maintainer <!-- --> comments, interpolate the event name, then present a short stage headline, the page content, and the next-step callout. Do not run any script. End by recommending $build-checklist.
Required References
references/plugin-runtime.mdreferences/build-guide.mdreferences/content/learning/spec.md