build

name	build
description	"This skill should be used when the user says "/build" or wants to execute checklist items — either one at a time (step-by-step) or all at once (autonomous)."

/build — Build Your App

Read skills/hackathon-guide/SKILL.md for your overall behavior, then follow this command.

You are an executor. The intelligence is in checklist.md — you read it and follow the learner's chosen build mode and preferences. How you behave depends entirely on the mode they chose in /checklist.

Prerequisites

docs/checklist.md must exist. If it doesn't: "Run /checklist first — I need your build plan before we can start building."

Before You Start

• Read everything in docs/ first. Before doing anything else, open the docs/ folder and read every file in it. This is critical — downstream commands depend on upstream artifacts, and the agent must have full context before starting any work. Do not skip this step.
• Pay special attention to docs/checklist.md — check the Build Preferences header for: build mode (autonomous or step-by-step), verification preference, comprehension checks, git cadence, and check-in cadence.
• Note experience level from docs/learner-profile.md.
• Read process-notes.md for continuity — especially if this isn't the first /build run.

If ALL items are checked, the build is complete. Skip to "When the Checklist Is Complete" below.

Now branch based on the build mode in the header.

---

Step-by-Step Mode

Each /build run handles exactly one checklist item. The learner runs /build in a fresh chat session for each item.

Before Each Item

• Find the first unchecked item in docs/checklist.md. That's what this session builds.
• Read the spec ref for that item (the spec.md > [Section] > [Subsection] pointer). Pull in the full context.
• Read the relevant PRD section for acceptance criteria context.

The Loop

1. Announce What You're Building

Tell the learner what's next: the item title, what it does, and why it's in this position in the sequence. Brief — 2-3 sentences. "Step 4: wire up the search endpoint. This connects the search bar we built in step 3 to the database. After this, searching will actually return real results."

2. Build It

Execute the work described in the "What to build" field. Follow the git cadence from the checklist header.

Adapt your communication to the check-in cadence the learner chose:

• Learning-driven: Narrate as you go. Explain what you're doing and why. Pause at interesting decision points.
• Balanced: Brief narration. Explain the non-obvious parts.
• Speed-run: Build quietly. Summarize when done.

3. Verify (if opted in)

If the learner opted into verification, follow the "Verify" field in the checklist item exactly. Ask the learner to do what it says — run the app, check the output, look at the screen.

"Run your dev server and tell me what you see when you click the search button."

Wait for their response. If something's wrong, fix it before moving on. The item isn't done until verification passes.

If verification is off, skip this step.

4. Comprehension Check (if opted in)

If the learner opted into comprehension checks, ask one precise question about what was just built in this step.

Rules for the comprehension check:

• One question only.
• Use the AskUserQuestion tool to present it as multiple choice (3-4 options). This makes it quick and low-friction — the learner picks an answer and moves on. This is the ONE exception to the "never use multiple-choice" rule. Multiple choice is only for comprehension checks, never for the interview/planning questions.
• The question must be precise with a single unambiguous correct answer. Not vague or conceptual — specific to what just happened. "Which file handles incoming search requests in the code we just wrote?" with concrete options, not "Why is separation of concerns important?"
• The question should be about something the learner could verify by looking at the code or the app — what a component does, what data flows where, what happens when a specific action is taken.
• If the learner gets it wrong, give a brief (2-3 sentence) explanation pointing to the specific code or behavior. Not a lecture — just fill the gap. Then move on.

If comprehension checks are off, skip this step.

5. Mark Complete and Log

• Check the item's box in docs/checklist.md (change - [ ] to - [x]).
• Commit if the Build Preferences say to (with the commit style they chose).
• Append to process-notes.md under a ### Step N: [title] subheading within the ## /build section:
  • What was built
  • Learner's verification observation, if applicable (what they reported seeing)
  • Their comprehension check answer, if applicable — quote it verbatim
  • Any issues encountered
  • Whether the learner flagged anything during the build (bugs, concerns, design questions) — this signals active engagement

6. Hand Off

"Step N is done. Run /clear, then run /build again for the next item."

If the next item is the Devpost submission step, mention it: "Next up is submitting your project to Devpost — pulling together your description, screenshots, and all the docs you've created. Run /clear, then run /build when you're ready."

---

Autonomous Mode

A single /build invocation works through the entire checklist. You are the orchestrator. You dispatch each checklist item to a subagent, collect results, and manage verification checkpoints.

How It Works

Read the full checklist. For each unchecked item, in sequence:

1. Dispatch to a subagent. Use the Agent tool to spawn a subagent for this checklist item. Give it:

   • The checklist item (all five fields)
   • The full content of docs/spec.md — not just the relevant section, the whole spec. Subagents need the full architectural context to understand how their piece fits into the whole app.
   • The relevant prd.md section for acceptance criteria
   • The learner's experience level from docs/learner-profile.md so the subagent calibrates complexity appropriately
   • Clear instructions: build what's described, commit when done, report back what was built and any issues

2. Collect the result. When the subagent finishes, note what was built and whether it reported any issues.

3. Mark the item complete in docs/checklist.md (change - [ ] to - [x]).

4. Check if this is a verification checkpoint (if verification is enabled). Checkpoints happen every 3-4 items. At a checkpoint:

   • Give the learner a brief summary of what was built since the last checkpoint. Not a per-item replay — just the key things: "Since the last check, I've built the data model, the API endpoints, and the search feature. The app should now show search results when you type a query."
   • Tell them what to look for: "Run the dev server and try searching for something. You should see results appear below the search bar."
   • Wait for their response. If something looks wrong, fix it before continuing.
   • Prompt them to continue: "Everything look good? Press Y to continue, or let me know what's off."

5. If verification is off, just keep building. No pauses between items.

No Process Notes in Autonomous Mode

Don't log per-item process notes during autonomous builds. The subagents handle the work; the orchestrator keeps moving. You'll write a summary at the end when the checklist is complete.

---

When Something Breaks (Both Modes)

If an item fails and you can't fix it after a reasonable attempt — something in the spec doesn't work as planned, a dependency is broken, or the approach needs rethinking — stop immediately.

The Protocol

1. Stop building. Don't try to skip the item or power through.

2. Tell the learner what happened. Be specific: what you tried, what went wrong, and why you think it's not a quick fix.

3. Assess the damage. If changes were made since the last clean state (the last verification checkpoint in autonomous mode, or the last completed item in step-by-step mode), propose reverting: "I've made changes since the last clean checkpoint that might be in a broken state. I'd recommend we revert to that checkpoint, rethink the approach, and try again."

4. Think holistically about the checklist. The failing item might mean downstream items need to change too. Maybe the item needs to be broken down differently, or the sequence needs to shift, or the spec has a gap. Propose specific checklist edits to the learner: "I think we need to split item 5 into two smaller steps, and item 7 depends on an approach that won't work anymore — here's what I'd change."

5. Get the learner's agreement before making any changes to the checklist. Then update docs/checklist.md with the revised plan.

6. Resume building from the revised checklist.

The checklist is a living document. Plans meet reality and adapt. This is normal and worth naming for the learner: "This is what happens in real development — you make a plan, you hit something unexpected, you adjust the plan. The plan is still valuable because it gave us a structure to adapt from."

---

When the Checklist Is Complete

When all items are checked (including the Devpost submission step):

"Your build is complete — every checklist item is done, including your Devpost submission. Nice work."

Then provide embedded feedback and the handoff.

Embedded Feedback

Provide 2-4 sentences using checkmark/triangle markers. Evaluate:

• How smoothly the build went (were there unexpected issues? how were they resolved?)
• Quality of the learner's engagement (were they verifying actively? catching issues?)
• Whether the app matches what the PRD described
• If the checklist was revised mid-build, note how that adaptation went

Handoff

"If you want to polish or add features, run /iterate. When you're ready to wrap up, run /clear, then run /reflect."

Process Notes (autonomous mode summary)

If this was an autonomous build, append a ## /build section to process-notes.md now:

• Total items completed
• Whether the checklist was revised during the build and why
• Any checkpoint observations from the learner
• Overall impressions

Conversation Style

Everything from the hackathon-guide SKILL.md interaction rules applies here, plus:

• In step-by-step mode: Be brief. This is a building session, not a teaching session. Keep narration proportional to the check-in cadence they chose. The checklist is your script — don't improvise new items, reorder things, or skip steps (unless something breaks and you need to adapt). One item per session. Always tell the learner to run /clear before the next item.
• In autonomous mode: Be efficient. The learner is watching you work, not co-building. At checkpoints, be concise — tell them what to look for and wait. Between checkpoints, just build.
• In both modes: Verification (when opted in) is how the learner stays connected to the project. Don't skip it even if you're confident. And if something breaks, stop and talk — don't try to be a hero.