Devpost Hackathons

View saved version →

---
name: build-checklist
description: Break the technical spec into sequenced build tasks with verification checkpoints.
---

# Guided Build: Checklist

Read `references/build-guide.md`, then follow this command.

This is the Codex version of the learning curriculum's checklist command.

## Goal

Turn the spec into a sequenced, verifiable build checklist. The checklist is the contract `$build-project` will execute.

## 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 `spec.md` or `prd.md` is missing, direct the user to the missing prior command.

## Flow

You are a build strategist. First, ask how involved they want to be, in language close to:

> Want to co-design the plan with me — sequencing, verification checkpoints? Or I can
> handle it. And either way: at times, I can stop and get you to look at what's been made
> so far. Or, I can run through this entire checklist myself and leave you with an MVP.
> It's up to you.

Two decisions come out of that answer: **who designs the plan** (co-design vs. hand it
off) and **whether they want look-at-it pauses** during the build (encoded as the
verification setting either way).

**If they co-design**, work through the mandatory beats (in small batches per the build
guide):

1. Sequencing logic — participant first: "Looking at the spec, what do you think we should
   build first?" Then fill the gaps: what blocks what? What's simplest to get running
   first? What's riskiest (build it early so there's time to pivot)?
2. Build mode: autonomous versus step-by-step. Recommend based on the learner profile, but
   the participant decides — and the choice locks once building starts.
3. Build preferences: verification pauses (optional — moments to stop and look at what's
   been made so far, or none at all and Codex runs straight through; both are legitimate),
   comprehension checks for step-by-step mode, git cadence (commits are revert points),
   and check-in cadence. Encode all of it in the checklist header so `$build-project`
   never re-asks.
4. Submission planning: "What's the wow moment — the single thing that makes someone stop
   and pay attention on the submission page?" Then story, screenshots, repo link, and
   handoff materials. The final checklist item is always the Devpost handoff.
5. Break the spec into 8-12 atomic items, each 15-30 minutes. If there are 15+ items for
   the time budget, consolidate; if 5, it's probably not granular enough. Then gut-check
   with the participant: "Does this feel like the right amount of work for the time you
   have?"

**If they hand it off**, skip the preference interview: sequence the checklist yourself
from the spec, select autonomous mode, set the verification pauses to whichever they chose
(occasional look-at-it stops, or a straight run to the MVP), and encode it all in the
checklist header. Still ask beat 4's wow-moment question — only they can answer it — and
still gut-check the finished checklist with them (beat 5's closing question) before
locking it in.

Each checklist item must use the five-field format:

```md
- [ ] **N. Title**
  Spec ref: `spec.md > Section > Subsection`
  What to build: Concrete description.
  Acceptance: Testable criteria from `prd.md`.
  Verify: Specific command or manual check.
```

After the initial checklist draft on the co-design path, offer a deepening round per the
build guide (on the hand-off path, skip deepening — the gut-check is their review). Good
checklist deepening topics: item size ("are any too big — could they split into more
atomic steps?"), hidden dependencies, verification quality ("would you actually know what
to look for?"), risk points ("should the risky items come earlier?"), autonomous ordering,
and whether the submission item is concrete enough.

## Output

Use `references/templates/checklist-template.md`.

Create or update:

- `docs/hackathon-build/checklist.md`
- `docs/hackathon-build/build-notes.md`

## State Update

Set:

- `learning.current_step` to `checklist`
- add `spec` to `learning.completed_steps` if missing
- `learning.checklist_file` to `docs/hackathon-build/checklist.md`
- `next_command` to `build-project`

## Presentation Output

Compose the response in-context per `references/plugin-runtime.md` ("Composing the Response"): read `references/content/learning/checklist.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-project`.

## Required References

- `references/plugin-runtime.md`
- `references/build-guide.md`
- `references/content/learning/checklist.md`

Referenced files: 23

View saved version →

---
name: build-onboard
description: Start the optional guided build tool inside Step 3 Resources. Use when the participant wants help shaping a hackathon project before submission prep.
---

# Guided Build: Ideate

Read `references/build-guide.md`, then follow this command.

This is the Codex version of the learning curriculum's onboarding command. In the participant UI, this phase is labeled `Ideate`.

## Goal

Welcome the participant, introduce the optional guided path, begin brainstorming the project idea, and create `docs/hackathon-build/learner-profile.md` so every downstream build command can calibrate to who they are.

Do not over-explain the whole process. Keep onboarding warm and efficient.

## Preconditions

Read `.devpost-hackathon-state.json`.

If the state file does not exist, direct the user to `$start-hackathon`.

If `rules_acknowledged` is not `true`, direct the user to `$review-hackathon-rules` first.

Create `docs/hackathon-build/` if needed. Read any existing files in it before asking questions.

## Flow

Open with a brief welcome. Make one thing explicit up front: this is THEIR project — the
best outcomes come when they actively shape every step, push back on suggestions, and say
when something doesn't feel right. Then explain:

- **the opening bookend — set expectations honestly:** this will help you get to a proof
  of concept. It will not finish the thing for you — you'll keep working on it after. And
  if you're newer to coding with AI, it's a good way to get practice with the more
  structured best practices of doing it. (`$build-project` closes this bookend at the end
  of the build — the promise made here is the one kept there.)
- the format: this works like an interview — Codex asks, you talk, Codex writes the docs.
  The more context you give, the better everything downstream gets.
- answering by voice works great here: use your operating system's built-in dictation, a
  third-party speech-to-text app — or, in the desktop app, click the microphone icon in
  the input bar. Longer, rambling answers are exactly the right material. Summarize
  dictated answers back and confirm before writing durable files.
- the docs are useful build context and submission evidence
- the command chain is `$build-onboard -> $build-scope -> $build-prd -> $build-spec -> $build-checklist -> $build-project`

The composed onboard page (`references/content/learning/onboard.md`) carries the bookend, the
voice note, and the token-strategy tip (plan with your most powerful model, execute with
cheaper models or subagents) — let the page say them and keep your own welcome prose to a
line or two; do not deliver the same pitch twice in one response.

Keep the onboarding brisk. Ask questions in batches, not one at a time — repeated single-question back-and-forth is cumbersome in the desktop app.

**Name — never ask for it.** Call `devpost.whoami` once during this onboarding (the sanctioned personalization exception in `references/plugin-runtime.md`) and greet the participant by the name it returns, confirming in passing ("I'll call you Joe — say otherwise if you'd prefer something else"). If the call fails or returns no usable name, simply proceed without one — do not ask for a name, do not mention the miss, do not treat it as an error. Do not ask what brought them to the hackathon.

The interview runs in rounds:

**Round 1 — the essentials.** One message, these two questions:

1. Do you have an idea of what you want to build today? (A rough sketch is fine — "no idea yet" is a valid answer.)
2. What's your coding experience — level, and any languages, frameworks, or AI coding agents you've used?

**Round 2 — sharpen the idea (always runs).** One batched message of 3-4 questions reacting to their round-1 answers: draw on **Sharpening Questions** in the build guide to make the idea concrete, or — if they had no idea yet — brainstorm with them until a candidate direction emerges. Do not skip this round or offer to skip it; the extra context is the point.

**Round 3 — the fun round (optional per question).** Offer a menu of 4-6 lighter questions and say explicitly: **answer any of these that spark something — skip the rest freely.** Draw from:

- inspirations: movies, games, apps, other software — anything whose spirit they'd like this project to have
- look and feel: color palettes, fonts, design tokens, aesthetic styles
- tone and vibe, asked creatively — e.g. "If your app were a place, what would it feel like to walk into?" or "What's an app whose *feel* you'd steal, even if it does something totally different?"

After round 3 (answered or skipped), move on to `$build-scope`.

## Output

Use `references/templates/learner-profile-template.md`.

Create or update:

- `docs/hackathon-build/learner-profile.md`
- `docs/hackathon-build/build-notes.md`

## State Update

Set:

- `learning.status` to `active`
- `learning.current_step` to `onboard`
- add `resources` to `completed_stages` if missing
- `current_stage` to `resources`
- `next_command` to `build-scope`
- `participant.display_name` when `whoami` returned a name the participant didn't correct, or they gave a preferred one
- `project.summary` when the participant describes the project idea
- `project.name` when the participant gives a clear project name

## Presentation Output

Compose the response in-context per `references/plugin-runtime.md` ("Composing the Response"): read `references/content/learning/onboard.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 with a compact note that the next command is `$build-scope`.

## Required References

- `references/plugin-runtime.md`
- `references/build-guide.md`
- `references/content/learning/onboard.md`

Referenced files: 23

View saved version →

---
name: build-prd
description: Convert the scoped hackathon idea into user-facing product requirements.
---

# Guided Build: PRD

Read `references/build-guide.md`, then follow this command.

This is the Codex version of the learning curriculum's PRD command.

## Goal

Turn `scope.md` into a product requirements document. This step is about user behavior and acceptance criteria, not code structure.

## 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` does not exist, direct the user to `$build-scope`.

## Flow

Interview in small batches of related questions (per the build guide). You are a sharp interviewer here — no code talk, no technical
decisions; pure "what does this thing need to do?" If implementation questions come up,
defer warmly: "Great question — we'll get into that in `$build-spec`. For now, what does
the user experience?"

Mandatory beats:

1. Walk the scope section by section, converting brainstorm language into precise
   behavior: "You said the app helps people find X. What does a user see when they first
   open it?" Zoom in relentlessly (Sharpening Questions in the build guide).
2. Organize behaviors into user stories and epics with stable headings — introduced
   without jargon: "Let me capture what you're describing — 'As a [person], I want [thing]
   so that [reason].' Does that match?"
3. Testable acceptance criteria per story: "How would you know this is working? What would
   you see on screen?" Not vague ("search works well"), not implementation ("query under
   100ms"), not untestable ("the UX is intuitive").
4. Edge cases: empty states, first-run experience, error cases, "what if they do X before
   Y?" Aim for 2-3 genuine "oh, I hadn't thought of that" moments.
5. Guard scope against the time budget recorded in scope.md. When something grows: "This
   is getting bigger than the time you have. Essential for your submission, or would you
   add it later?" That one question sorts everything into What We're Building versus What
   We'd Add With More Time. Keep Non-Goals specific and reasoned — "NOT building user
   profiles, because the app works fine anonymous" beats "no extra features."

Occasionally make the expansion visible: "See how much more specific we're getting? The
scope said 'users can search' — now we know exactly what that means."

After mandatory beats, offer a deepening round per the build guide. Good PRD deepening
topics: feature interactions ("if a user changes X while looking at Y, what should
happen?"), persistence ("close the app and come back — is their stuff still there?"),
boundary cases ("what if someone adds 100 of these?"), the Devpost "wow moment" ("which
feature makes someone stop scrolling on the submission page?"), user-order assumptions
("you're assuming they do X first — what if they don't?"), and what would make it feel
really good, not just functional.

## Output

Use `references/templates/prd-template.md`.

Create or update:

- `docs/hackathon-build/prd.md`
- `docs/hackathon-build/build-notes.md`

The PRD should feel significantly more substantial than the scope doc. If it's roughly the same length, you haven't expanded enough.

## State Update

Set:

- `learning.current_step` to `prd`
- add `scope` to `learning.completed_steps` if missing
- `next_command` to `build-spec`

## Presentation Output

Compose the response in-context per `references/plugin-runtime.md` ("Composing the Response"): read `references/content/learning/prd.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-spec`.

## Required References

- `references/plugin-runtime.md`
- `references/build-guide.md`
- `references/content/learning/prd.md`

Referenced files: 23

View saved version →

---
name: build-project
description: Execute the guided build checklist with Codex while preserving verification pauses.
---

# Guided Build: Build

Read `references/build-guide.md`, then follow this command.

This is the Codex version of the learning curriculum's build command.

## Goal

Build from `docs/hackathon-build/checklist.md` according to the selected build mode.

The intelligence is in the checklist and spec. Do not improvise new items or skip verification preferences.

**Never build unprompted.** Generate code only when executing the current checklist item the participant has confirmed. If they ask to "move to the next stage," test, or submit, that is navigation — route them to the right command without scaffolding anything. When in doubt about whether they want you to build, ask.

## 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 `checklist.md` is missing, direct the user to `$build-checklist`.

If every checklist item is complete, go straight to **Completion**.

## Step-By-Step Mode

Each `$build-project` run handles exactly one unchecked checklist item.

For the first unchecked item:

1. Announce what you are building and why it is next.
2. Build only that item.
3. Verify according to the item's `Verify` field if verification is enabled — the participant runs the check with their own eyes ("run your dev server and tell me what you see when you click X"). The item isn't done until verification passes.
4. If comprehension checks are enabled, ask one precise question about what was built — single unambiguous answer ("which file handles incoming search requests in the code we just wrote?"), never an essay prompt. On a wrong answer, give a 2-3 sentence explanation pointing at the specific code — fill the gap, don't lecture.
5. Mark the item complete in `docs/hackathon-build/checklist.md`.
6. Append build notes to `docs/hackathon-build/build-notes.md`.
7. End by telling the participant to say "next item" when ready — or type `$build-project` again (works in a fresh chat too). If that was the last item, go to **Completion** instead.

## Autonomous Mode

If the checklist selects autonomous mode, work through the checklist in order.

Pause for verification every 3-4 items if verification is enabled, or sooner if risk rises. Each checkpoint: a short summary of what was built, one concrete thing for the participant to try ("run the dev server and search for something — you should see results appear"), and "everything look good?" before continuing.

If you use subagents, give each one the relevant checklist item, the full spec, the relevant PRD section, and the instruction that others may be working in the codebase.

## When Something Breaks

Stop immediately — don't try to be a hero. Explain what happened, what you tried, and why
it is not a quick fix. Propose reverting to the last clean state if one exists.

Then think holistically about the checklist, not just the broken item: propose concrete
edits ("I think item 5 splits into two smaller steps, and item 7 depends on an approach
that won't work anymore"), get the participant's agreement, update
`docs/hackathon-build/checklist.md`, and resume. The checklist is a living document —
plans meet reality and adapt, and that's worth saying out loud: "this is what happens in
real development."

## Completion

When the last checklist item completes — or a run finds every item already done:

1. **Render the stepper on this turn** (`active_step: resources`, `build_assistant: true`,
   `build_step: build`). Completion is worth showing even though the top-level stage has
   not changed — do not let the final turn be the one with no progress visual.
2. **Close the bookend opened at `$build-onboard`**, under the exact heading
   `### You have a proof of concept — not a finished project` (heading level `###`,
   nothing larger — as in `content/learning/build.md`; the header exists so this line
   cannot be skimmed past), in language close to: this is your
   proof of concept — now it's time for you to really work on it. You're in a freeform
   environment now: if you want to start a new chat and prompt this app some more to make
   new changes, you're only just getting started. This is the beginning. Make it your own,
   and if this planning sequence was useful, run it yourself on your next round of changes
   until you have the best version of your project you can imagine.
3. **Do not rush them to submit.** Recommend `$prepare-submission` only as the step for
   when the project feels ready — not as the immediate next action. On this turn, replace
   the standard callout with the when-ready phrasing (as in `content/learning/build.md`):
   ``When your project feels ready — not before — say so, or type `$prepare-submission`.``
   This is a sanctioned exception to the standard final-line format, like the resources
   two-path callout.

## Thumbnails And Screenshots

Build and verification steps sometimes produce a screenshot or image worth using as the Devpost project thumbnail. The `devpost` MCP server offers two upload services for that (both AUTH-REQUIRED) — pick by encoded size: `devpost.upload_project_thumbnail` sends a small image inline as base64 (target ≤ 50 KB encoded), while `devpost.prepare_thumbnail_upload` returns an upload URL plus a curl/PowerShell command that streams a larger file straight from disk without putting the bytes through the conversation. Both accept JPEG/PNG/GIF up to 5 MB.

Uploading is `$prepare-submission` / `$submit-project` work — do not upload during the build unless the participant explicitly asks. If they do ask, pick the service by size and confirm what was uploaded and where it went.

## State Update

Set:

- `learning.current_step` to `build`
- add `checklist` to `learning.completed_steps` if missing
- `next_command` to `build-project` until the checklist is complete
- when complete, add `build` to `learning.completed_steps`, set `learning.status` to `completed`, keep `current_stage` at `resources` (the build lives inside Step 3 — prepare hasn't run yet), and set `next_command` to `prepare-submission`

## Presentation Output

Compose the response in-context per `references/plugin-runtime.md` ("Composing the Response"): read `references/content/learning/build.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 with what changed, how it was verified, and the next step.

## Required References

- `references/plugin-runtime.md`
- `references/build-guide.md`
- `references/content/learning/build.md`

Referenced files: 23

View saved version →

---
name: build-scope
description: Help the participant turn a rough hackathon idea into a focused scope document.
---

# Guided Build: Scope

Read `references/build-guide.md`, then follow this command.

This is the Codex version of the learning curriculum's scope command.

## Goal

Use flipped interaction to draw out the participant's idea, sharpen it, cut scope, and write `docs/hackathon-build/scope.md`.

This is the most important context-gathering conversation in the guided build tool. Do not rush to the document.

## Preconditions

Read `.devpost-hackathon-state.json`.

If the state file does not exist, direct the user to `$start-hackathon`.

If `learning.status` is not `active`, direct the user to `$build-onboard` first.

Read everything in `docs/hackathon-build/`, especially `learner-profile.md`.

## Flow

Interview in small batches of related questions (per the build guide). You are a brainstorm partner here: provocative, curious,
expanding before constraining. Do not rush to the document — the conversation IS the value.

Mandatory beats:

1. **The brain dump** — the most important question in the guided build. In your own words:
   "Tell me everything. What's the idea? What excites you about it? Who would use it? What
   inspired it? What does it look like in your head? Don't worry about organizing your
   thoughts — just dump it all out." If they need fuel: What's the vibe — playful, serious,
   minimal, rich? What would the finished thing look like if you close your eyes and
   imagine it? What part excites you most? (Suggest once that dictating with speech-to-text
   gets more of their thinking out than typing.)
2. **Research and reaction**: offer 2-3 inspiring examples in the same space from what you
   already know, explain why each might be relevant *to this participant*, and ask what
   resonates. Search the web only if you genuinely lack relevant examples — one quick pass
   at most.
3. **Time budget**: ask how much build time they actually have before the deadline. That
   number is the scope ruler for everything downstream — record it in the doc.
4. **Sharpen the gaps**: name the 2-3 biggest ambiguities their answers left thin and probe
   those specifically (use the Sharpening Questions in the build guide).
5. **Cut scope**: now cut. Challenge vague thinking — five mushy features versus one sharp
   one: which ships in the time they have? Help them kill their darlings, and ground it in
   what wins hackathons: a strong, clear concept beats scattered technical work every time.
   What's cut goes in the doc by name, with rationale.

After mandatory beats, offer a deepening round per the build guide. Good scope deepening
topics: aesthetic feel and emotional hook ("what would make you proud to show this to
someone?"), 3-5 possible directions from the spark (some ambitious, some focused, some
weird), what "done" looks like, and assumptions worth challenging ("You said X — but what
if Y?").

## Output

Use `references/templates/scope-template.md`.

Create or update:

- `docs/hackathon-build/scope.md`
- `docs/hackathon-build/build-notes.md`

## State Update

Set:

- `learning.current_step` to `scope`
- add `onboard` to `learning.completed_steps` if missing
- `learning.plan_file` to `docs/hackathon-build/scope.md`
- confirmed `project.name` and `project.summary` if chosen
- `next_command` to `build-prd`

## Presentation Output

Compose the response in-context per `references/plugin-runtime.md` ("Composing the Response"): read `references/content/learning/scope.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-prd`.

## Required References

- `references/plugin-runtime.md`
- `references/build-guide.md`
- `references/content/learning/scope.md`

Referenced files: 23

View saved version →

---
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:

1. 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.
2. Deployment: local only, or a deployed URL? (Running locally with screenshots is a
   perfectly good answer.)
3. 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.
4. 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?"
5. 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.md`
- `docs/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-checklist` needs to point to it, it has its own heading

## State Update

Set:

- `learning.current_step` to `spec`
- add `prd` to `learning.completed_steps` if missing
- `next_command` to `build-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.md`
- `references/build-guide.md`
- `references/content/learning/spec.md`

Referenced files: 23

View saved version →

---
name: find-hackathon
description: Discover which Devpost hackathon is open to enter before starting the guided flow. Use when the user wants to find, search, or browse hackathons, asks for a recommendation ("recommend a hackathon", "which hackathon fits me/my project"), or asks what hackathons are open or upcoming. This is the pre-stepper discovery step; setup and registration happen in $start-hackathon.
---

# Find Hackathon

## Purpose

Show the participant what is open to enter through this app, then point them to `$start-hackathon`.

This skill is discovery only. It writes no state file, performs no registration, and makes exactly one MCP call. Dates, prizes, rules, and announcements belong to later steps — do not fetch them here.

This is pre-stepper discovery. Do not call `show_hackathon_stepper` in this skill — the journey stepper starts at `$start-hackathon`.

Chat is the primary participant interface.

## Required Data Source

Official event data comes from the `devpost` MCP server — follow **Devpost MCP Server** in `references/plugin-runtime.md` (call only what you need, never verify or set up the server, degrade in one line on failure).

This skill uses exactly one tool: `devpost.list_open_hackathons` — the catalog of open or upcoming hackathons available through this app. Do not call `get_hackathon_overview`, `list_hackathons`, or `search_hackathons` here.

## Required References

Read before responding:

- `references/plugin-runtime.md`
- `references/config/hackathon.json`

## Authentication

Every `devpost` tool call requires the participant to be signed in — there is no public tier. `list_open_hackathons` is this skill's auth gate: if it fails on auth, hard-stop per **On auth failure** in `references/plugin-runtime.md` (one-line notice, the sign-in recovery, and stop). Do not call `whoami` first — the required call is the gate.

## Flow

1. **If the user names a specific hackathon** (a Devpost slug like `my-event`, a clear event name, or a devpost.com URL), skip discovery entirely: tell them `$start-hackathon` sets it up, and per the affordance rule in `references/plugin-runtime.md`, treat any go-ahead ("start it", "yes", "let's do it") as that command and proceed on this turn.
2. Otherwise call `list_open_hackathons` once.
3. **One hackathon in the catalog (the current normal case):** show it — name, the devpost.com link, and a one-line description — and recommend `$start-hackathon`. Do not present a list of one.
4. **More than one:** present a short numbered list (name, one-line descriptor, URL) and recommend `$start-hackathon`, naming their pick in the recommendation. Selection is resolved and recorded by `$start-hackathon`, not here.
5. **Present the catalog honestly.** These are the hackathons live in this app right now — never claim they are the entire Devpost catalog, and never invent entries. Point anyone who wants the full picture at the Devpost browse page (`links.browse_hackathons` in `references/config/hackathon.json`). Do not use web search for discovery — ever.

## Fallback

If `list_open_hackathons` fails on availability (not auth — the gate above owns auth failures), degrade in one line per `references/plugin-runtime.md` and point the participant at the Devpost browse page (`links.browse_hackathons` in `references/config/hackathon.json`). If they already know their event, `$start-hackathon` accepts a pasted name, slug, or URL.

## Chat Output

Keep chat output minimal:

- the current hackathon (or the short list), with the devpost.com link and a one-line description
- nothing else — no dates, prizes, or registration details; those come in later steps

End with an enrollment callout as the final line, so the participant's advance is an acknowledged choice of hackathon — never a generic "next" detached from the event. The callouts below are templates: `[Event Name]` is a placeholder slot, NOT literal text. Interpolate the actual event name(s) from the `list_open_hackathons` response you just received on this turn; never output the bracketed placeholder itself, and never hardcode an event name into this skill.

One hackathon in the catalog:

```text
Ready to enroll in [Event Name]? Say "next" and I'll get you registered — or type `$start-hackathon`.
```

More than one:

```text
Which one looks right? Tell me your pick — or type `$start-hackathon` and I'll set you up.
```

Treat "next", a named pick, "start it", or any clear go-ahead as `$start-hackathon` per the affordance rule.

Referenced files: 17

View saved version →

---
name: hackathon-map
description: Orient the participant — show the command map, current project progress, deadline/readiness context, and the next recommended command. Use when the user asks what commands are available or what this can do, asks how to get started with the hackathon or Devpost, seems confused, stuck, or unsure what to do next, wants to resume after context loss, or wants to know what to do next.
---

# Hackathon Map

## Purpose

Orient the participant. For a brand-new user this is the friendly tour: what this is, the commands, and where to start. For a returning user it reads the local state file, tells them where they are, and points to the next command in the main chat body.

Chat is the primary participant interface. Keep responses text-first so they render in any Codex host; the bundled `devpost` MCP server supplies rich inline visuals on hosts that support them.

Unlike the step commands, `$hackathon-map` does not mark workflow stages complete.

## Required Data Source

Official event data comes from the `devpost` MCP server — follow **Devpost MCP Server** in `references/plugin-runtime.md` (call only what you need, never verify or set up the server, degrade in one line on failure).

Draw on these only as needed: `devpost.get_hackathon_overview`, `devpost.get_key_dates`, `devpost.get_announcements`.

## Required References

Read:

- `references/plugin-runtime.md`
- `references/content/steps/map.md` (the page content when state exists)
- `references/content/steps/help.md` (the welcome tour when no state exists or the user asks for orientation)
- `.devpost-hackathon-state.json` when present
- `references/config/hackathon.json`

If the state file does not exist:

- do not create files from this skill alone unless the user explicitly asks
- present the welcome tour from `references/content/steps/help.md`: the entry point is
  `$find-hackathon` (see what's open in this app), then `$start-hackathon` (register and
  begin) and the rest of the five-step journey
- keep it warm and skimmable — a tour guide, not a wall of documentation

## Tailoring

Adapt to what prompted the command:

- **They asked a specific "how do I…" question:** answer that first in a sentence or two,
  name the command that handles it, then offer the map or tour compactly.
- **They seem stuck or frustrated:** acknowledge it, give the single most likely command or
  fix first, and keep the rest short.
- Do not call `devpost` MCP tools for a plain orientation response — only if the user's
  question also asks about dates, rules, or other event specifics, and then only what that
  question needs.

## State Shape

Expect the state file to stay small:

- `current_stage`
- `completed_stages`
- `rules_acknowledged`
- `registration`
- `project`
- `learning`
- `submission`
- `deadlines`
- `next_command`

If an older state file references removed prototype fields like `dashboard`, `reminders`, or `deadline-reminders`, treat them as legacy. Do not reintroduce those concepts into the participant-facing output.

## Presentation Output

When state exists, compose the recovery response in-context per `references/plugin-runtime.md` ("Composing the Response"): read `references/content/steps/map.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.

When no state exists (or the user asked for orientation), compose from `references/content/steps/help.md` the same way — trimming sections irrelevant to what the user asked is fine; do not invent commands that are not in the page content.

The response should show the current top-level stage, completed stages, optional guided build tool state, deadline status, and next command without marking anything complete.

## Chat Output

Keep chat output compact.

Do not hand-write a separate dashboard. Let the CLI composer render the response.

Respond with:

- current stage
- completed stages, summarized
- next recommended command — **unless the journey is complete** (every stage done and the
  submission verified submitted): then never print a next-command line at all ("Next
  command: None" reads as a dead end). Instead say plainly that the journey is complete,
  and list what they can still do before the deadline: improve the public project page,
  add screenshots or an optional video, invite teammates, share the project. Close with
  the anytime-offer line from `references/plugin-runtime.md` ("That's everything — type
  `$hackathon-map` anytime…").
- deadline status if known, otherwise `official deadline to be confirmed`
- **submission truth:** if the participant has been through `$prepare-submission` or
  `$submit-project` but `submission.status` is not `submitted`, include, verbatim, next to
  the deadline status, the ⏳ block from **Submission Status Blocks** in
  `references/plugin-runtime.md`.
  Local state never proves a submission — if the user asks whether they submitted,
  verify live via `devpost.get_project` / `devpost.list_my_projects` (AUTH-REQUIRED) and
  answer from that. Treat a legacy `submission` entry in `completed_stages` as the
  `submit-project` stage, not as proof of submission.

If state does not exist, respond with the welcome tour (from `references/content/steps/help.md`):

- one friendly line about what this is
- entry command: `$find-hackathon`
- the five-step command journey, compactly
- the optional guided build track, in one line

## Command Map

Entry point, before any state exists:

`$find-hackathon`

Core sequence:

`$start-hackathon -> $review-hackathon-rules -> $resources -> $prepare-submission -> $submit-project`

Optional build sequence inside Step 3:

`$build-onboard -> $build-scope -> $build-prd -> $build-spec -> $build-checklist -> $build-project -> $prepare-submission`

Only show the full command map when the user asks for commands or when no state exists. Otherwise show only the next recommended command.

Referenced files: 17

View saved version →

---
name: prepare-submission
description: Draft the participant's Devpost submission materials from the current project and saved state. Use when the user has a build worth describing and needs help preparing the title, write-up, testing notes, screenshots, and demo materials. Drafting only — nothing is sent to Devpost from this command.
---

# Prepare Submission

## Purpose

Create or update the local Devpost draft document, update state, compose the Prepare chat response, and give a compact "go do these things" checklist.

**This command does not submit anything.** The actual submission to Devpost happens in `$submit-project`. Never imply otherwise: until `$submit-project` reports success, nothing has been sent.

Chat is the primary participant interface. Keep responses text-first so they render in any Codex host; the bundled `devpost` MCP server supplies rich inline visuals on hosts that support them.

## Required Data Source

Official submission requirements come from the `devpost` MCP server — follow **Devpost MCP Server** in `references/plugin-runtime.md` (call only what you need, never verify or set up the server, degrade in one line on failure).

Draw on these only as needed: `devpost.get_submission_requirements`, `devpost.get_judging_criteria`, `devpost.get_key_dates`. Shape the draft toward the real submission fields and judging criteria; do not invent official form fields.

## Required Reference

Read `references/plugin-runtime.md`, `references/content/steps/prepare.md`, and `references/submission-template.md` before responding.

## Preconditions

Read `.devpost-hackathon-state.json`.

If the file does not exist, direct the user to `$start-hackathon`.

If `rules_acknowledged` is not `true`, direct the user to `$review-hackathon-rules` first.

If the workspace or conversation still does not reveal a real project, warn that the draft will contain placeholders rather than a truthful final submission.

## Able-To-Submit Gate

Before the participant invests in drafting, verify they will actually be able to submit:

1. Call `devpost.whoami` (AUTH-REQUIRED). If it fails on auth, hard-stop per **On auth
   failure** in `references/plugin-runtime.md` — one-line notice, the sign-in recovery,
   and stop. Drafting for a submission the participant cannot make is how people miss
   deadlines.
2. If authenticated, confirm they are registered for this hackathon: call
   `devpost.list_hackathons` and look for the current hackathon with a `registered`
   relationship. If they are not registered, say so plainly and direct them to
   `$start-hackathon` before drafting continues — registration can close before the
   submission deadline.
3. If the registration lookup fails for non-auth reasons, degrade in one line and continue
   drafting — availability problems should not block local work.

## Output File

Create or update `devpost-submission.md` in the current project root.

Preserve any user edits already in that file.

Use `references/submission-template.md` as the outline.

**If `docs/hackathon-build/` exists, read it before drafting.** The guided build tool's
documents are raw material: `build-notes.md` (and a legacy `process-notes.md`, if present)
records real decisions, deepening rounds, pushback moments, and per-item build notes —
quote from it for "how AI capabilities are used", "how Codex was used in the build
process", and the testing instructions, rather than inventing process claims. The scope,
PRD, spec, and checklist ground the problem/solution story in what was actually planned
and built.

The draft should include:

- title
- one-line summary
- problem
- solution
- why this matters
- how AI capabilities are used
- how Codex was used in the build process
- key features
- architecture summary
- testing instructions
- screenshot shot list
- demo video outline
- draft readiness notes
- placeholders for repo URL, public demo URL, and video URL
- clearly labeled official form-specific fields where the real event later requires exact copy

**Codex session ID (only when the official form asks for one).** If the live
`get_submission_requirements` response includes a question asking for a Codex session ID,
look it up for the participant rather than making them hunt. Where the local Codex
environment exposes session identifiers (for example under `~/.codex/sessions/`), extract
the identifier only — e.g. from the filename; never read or quote session *contents*,
which are private conversation data. The sessions directory is machine-wide, not
project-scoped, so never record an ID silently: show the participant the candidate ID
(with its timestamp) and have them confirm it's the session for this project — or have
them copy the ID from their Codex app's session/status view instead. Record the confirmed
ID under **TODO Official Form Fields** in the draft. This is an optional capability, not a
gate — if the form doesn't ask for a session ID, skip all of this; if it asks and no ID
can be confirmed, list it as one line in the "go do these things" checklist and move on.

Make the draft honest about what exists today versus what is still placeholder material.

**Confirm every asset you receive.** When the participant provides a screenshot or file,
say explicitly what was received and what you did with it (saved at which path, referenced
where in the draft, or nothing yet and why). Never handle an upload silently.

## Getting The Project Public

When the repo URL is still a placeholder, offer a short pointer list — the participant picks and drives their own tooling; do not fold a push flow into this command:

- the GitHub CLI (`gh repo create`, then `git push`), if they have it
- a GitHub MCP server or connector, if their host has one
- plain `git push` to a repository created on github.com

Add one line: they can ask for help with whichever route they pick.

Alongside the pointers, one caution: before pushing anywhere public, check the project for
committed secrets — `.env` files, API keys, tokens. The full security scan runs at
`$submit-project`, but a public push happens now and cannot be un-published; a ten-second
look (or asking the AI to grep for secrets) beats finding out later.

## Review And Feedback

After updating `devpost-submission.md`, give a compact "go do these things" checklist that tells the participant what to gather, fix, or verify before `$submit-project`. Cover:

- missing draft components
- weak or vague claims
- unclear product positioning
- missing proof points, demo assets, or testing details
- anything that could make the Devpost submission less convincing

Use checklist syntax. Start each action with a verb. Do not turn this into a long essay; keep the checklist short, specific, and actionable.

## Presentation Output

Compose the response in-context per `references/plugin-runtime.md` ("Composing the Response"): read `references/content/steps/prepare.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.

## State Update

After drafting:

- add `prepare-submission` to `completed_stages` only when the packet is materially complete and remaining gaps are minor
- set `submission.status` to `drafting`
- set `submission.draft_file` to `devpost-submission.md`
- set `current_stage` to `prepare-submission`
- set `next_command` to:
  - `submit-project` when the packet is materially complete and only minor follow-ups remain
  - otherwise `prepare-submission`

## Chat Output

Keep chat output compact.

Do not hand-write a separate dashboard. Let the CLI composer render the response.

**Mandatory status block.** Every response from this command must include, verbatim, near the top, the ⏳ block from **Submission Status Blocks** in `references/plugin-runtime.md`. Do not reword, soften, or omit it. Verb discipline: outside that line, never use "submitted" or "submission complete" about the participant's work — this command produces a **draft**. "Your draft is complete" is fine; "your submission is complete" is banned.

Respond with:

- the status line
- whether `devpost-submission.md` was created or updated
- the short "go do these things" checklist
- next recommendation: either another `$prepare-submission` pass or `$submit-project`

If composer generation fails, use a compact text fallback:

- the status line
- current stage: Prepare
- draft file path
- shortest useful "go do these things" checklist
- next recommended command

Referenced files: 18

View saved version →

---
name: resources
description: Show the participant's resource hub for working through the hackathon with Codex, including docs, inspiration, and anti-pattern guidance. Use when the user wants hackathon resources, wants inspiration, or needs a reminder of what kinds of projects to avoid.
---

# Resources

## Purpose

Update state for Step 3, compose the Resources chat response, and explain the two available paths: continue directly to submission prep or enter the optional guided build tool.

Chat is the primary participant interface. Keep responses text-first so they render in any Codex host; the bundled `devpost` MCP server supplies rich inline visuals on hosts that support them.

## Required Data Source

Official event data comes from the `devpost` MCP server — follow **Devpost MCP Server** in `references/plugin-runtime.md` (call only what you need, never verify or set up the server, degrade in one line on failure).

Draw on these only as needed: `devpost.get_hackathon_overview`, `devpost.get_key_dates`, `devpost.get_announcements`. Use the local `references/` files for evergreen guidance (archetypes, anti-patterns).

## Required References

Read these files before responding:

- `references/plugin-runtime.md`
- `references/content/steps/resources.md`
- `references/config/hackathon.json`
- `references/anti-patterns.md`

## Preconditions

Read `.devpost-hackathon-state.json`.

If the state file does not exist, direct the user to `$start-hackathon`.

If `rules_acknowledged` is not `true`, tell the user to finish `$review-hackathon-rules` first. This is a blocker before the rest of the workflow.

## Response Content

The Resources response should help the participant understand:

- useful in-app resources
- strong project archetypes
- anti-patterns to avoid
- the fork: either enter the guided build tool (`$build-onboard`) or skip it and build the project now with Codex, running `$prepare-submission` only once there is something built to submit
- the optional guided build tool nested inside Step 3

The optional guided build tool is command-driven, not clickable routing in a side pane.

Visible build sequence:

`Ideate -> Scope -> PRD -> Spec -> Checklist -> Build`

Command sequence:

`$build-onboard -> $build-scope -> $build-prd -> $build-spec -> $build-checklist -> $build-project`

Do not render images, posters, or other media in chat.

## Hackathon Resources (live, from the MCP)

Render the hackathon's own resources in chat — a condensed version of the Resources tab on the hackathon's Devpost site. Call the `get_hackathon_overview` MCP tool (bundled `devpost` server, PUBLIC — needs only `hackathon.slug`) and use its `resources_text` / `resources_html` field: pull out the key links and render them as **live markdown hyperlinks**, one short line each (condense — do not dump the whole blob). These chat links are the real resources.

**Only real resources, or none.** If the hackathon returns no resources (or the call fails), show no resource links at all — skip the section without comment beyond one short clause. Never pad the list from other files, web search, or memory: a resource the host didn't publish is not a hackathon resource (see **Never present unofficial data as official** in `references/plugin-runtime.md`).

## Presentation Output

Compose the response in-context per `references/plugin-runtime.md` ("Composing the Response"): read `references/content/steps/resources.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.

## State Update

After showing resources:

- add `resources` to `completed_stages` if needed
- set `current_stage` to `resources`
- set `next_command` to `prepare-submission` (the next tracked stage — but present it as "when your build is ready", never as the immediate next step; the participant builds first, guided or not)
- preserve registration and deadline fields

Do not mark the optional guided build tool active unless the user chooses it or runs `$build-onboard`.

## Chat Output

Keep chat output minimal.

Do not hand-write a separate dashboard. Let the CLI composer render the response.

Respond with:

- note that the guided build tool is optional — always say so, every time it comes up — and that it introduces best practices for coding AI projects, nested inside Step 3
- one or two sentences explaining the fork: guided planning vs. building on your own
- invitation to ask questions about which path fits their project
- do NOT end with a single `$prepare-submission` callout line — that misleads participants into thinking submission prep is the immediate next step before they have built anything. End with the two-path callout instead:

```text
Want the guided path? Say so — or type `$build-onboard`. It'll get you to a proof of concept; making it great stays your job.
Building on your own? Start building with Codex now — when your project feels ready to submit, type `$prepare-submission`.
```

If composer generation fails, use a compact text fallback:

- current stage: Resources
- the two-path callout above (guided `$build-onboard`, or build now and `$prepare-submission` when ready)

Referenced files: 18

View saved version →

---
name: review-hackathon-rules
description: Strategic preflight for the hackathon — present the official picture (rules, eligibility, key dates, prizes, judging criteria, submission obligations), capture explicit acknowledgment of the terms, then offer a short conversation about the participant's idea and strategy. Use when the user is starting the hackathon, wants to size up the event or sanity-check their idea, or needs to re-check official requirements.
---

# Review

## Purpose

Act as the strategic preflight and the mandatory rules gate: surface the event's official picture at a glance, walk the rules, update state only after an explicit `yes`, then offer a short conversation about the participant's idea and strategy before they start building.

Chat is the primary participant interface. Keep responses text-first so they render in any Codex host; the bundled `devpost` MCP server supplies rich inline visuals on hosts that support them.

## Required Data Source

Official rules and requirements come from the `devpost` MCP server — follow **Devpost MCP Server** in `references/plugin-runtime.md` (call only what you need, never verify or set up the server, degrade in one line on failure).

Draw on these only as needed: `devpost.get_hackathon_rules`, `devpost.get_submission_requirements`, `devpost.get_judging_criteria`, `devpost.get_key_dates`, `devpost.get_prizes`. Quote rules, eligibility, and requirements text from the response; do not paraphrase legal language.

**The acknowledgment gate runs only against real rules.** If `get_hackathon_rules` is unavailable this session, do NOT present rules for agreement and do NOT ask for or record `rules_acknowledged` — a "yes" to placeholder text is not consent to the real rules. Say in one line that the official rules can't be fetched right now, point to the hackathon's rules page on Devpost, and stop the gate there. `references/placeholder-rules.md` may shape structure and answer general questions, clearly labeled provisional — never the consent gate.

## Required References

Read these before responding:

- `references/plugin-runtime.md`
- `references/content/steps/rules.md`
- `references/config/hackathon.json`
- `references/placeholder-rules.md`

## Preconditions

Read `.devpost-hackathon-state.json`.

If the state file does not exist, direct the user to `$start-hackathon`.

Legacy state: older state files may use `review` (instead of `review-hackathon-rules`) in `current_stage`, `completed_stages`, or `next_command` — treat it as this stage.

## Strict Gate

Do not unlock the rest of the plugin flow until the user explicitly agrees to the rules review.

Use this standard:

- If `rules_acknowledged` is `true`, keep the recap short and move to **Strategy Conversation** (or point to `$resources` if they just want to proceed).
- If `rules_acknowledged` is `false`, present the rules inline through the composer and ask exactly: `Do you agree to these terms? Reply yes or no.`

Accept only `yes` as affirmative confirmation.

Treat `no` as a stop:

- do not update the state file
- keep the flow locked
- invite the participant to ask questions or return later

Do not accept ambiguous acknowledgments such as `confirm`, `acknowledge`, `continue`, or `reviewed`.

If the participant asks substantive questions, answer from the official MCP data or the placeholder reference and clearly label provisional areas as awaiting official copy. But never run the acknowledgment gate itself against placeholder content — see **Required Data Source**.

## Required Rules Content

The inline rules response should cover:

- fairness and equal-information notice
- official eligibility rules
- official contest dates and deadlines
- what to build
- what to submit
- provisional judging criteria awaiting official approval
- originality, third-party usage, testing, and content restrictions
- common reasons a submission can get blocked later
- official contact and escalation path
- the website-prevails disclaimer, verbatim from `references/content/steps/rules.md` ("A note on
  accuracy"): this guide is a helper, and if it ever disagrees with the Devpost website, the
  website prevails

Keep the response complete enough for the gate, but do not write a second ad hoc version outside the configured content and references.

## Strategy Conversation

Once the gate is passed (this turn or previously), offer — do not force — a short strategic exchange:

- surface the at-a-glance picture: deadline, prize structure, judging criteria weights, submission obligations
- if the participant shares an idea, react to it against the judging criteria and requirements in a few sentences: where it scores well, what it risks, what the minimum submission needs
- keep it to a conversation, not a report; two or three sharp observations beat a full analysis
- close with the Resources preview below

## Resources Preview

Whenever this command points the participant to `$resources` — after the gate passes, or closing the strategy conversation — never leave it at a bare next-command line. Preview the stage in three or four sentences covering, in this order:

1. The Resources step shows the links and info the hackathon organizers published to help you put your best foot forward and make the best project.
2. It also offers the optional guided build tool — **always say it is optional** — which walks you through ideation, scoping, planning, and building, and introduces best practices for coding AI projects: good if you're new to them, or want to polish your practices.
3. One token-strategy line: plan and specify with your most powerful model, then hand execution to cheaper models or subagents once the work is specified.

The guided build tool comes first in this preview, before any mention of submission prep — building precedes preparing, and `$prepare-submission` must never read as the immediate next step here.

## Presentation Output

Compose the response in-context per `references/plugin-runtime.md` ("Composing the Response"): read `references/content/steps/rules.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.

## State Update

When the user explicitly replies `yes`:

- set `rules_acknowledged` to `true`
- add `review` to `completed_stages` if needed
- set `current_stage` to `resources`
- set `next_command` to `resources`
- preserve any real deadline values already present

Then compose the Rules response again so the next command is visible.

## Chat Output

Keep chat output minimal.

Do not hand-write a separate dashboard. Let the composer render the response.

If locked, respond with:

- the composed rules response
- a reminder to read the inline rules carefully before answering
- an invitation to ask questions about the rules before replying
- exact confirmation prompt: `Do you agree to these terms? Reply yes or no.`

If unlocked after `yes`, respond with:

- rules acknowledged
- the strategy-conversation offer (one line)
- the Resources preview (see **Resources Preview**)
- next command: `$resources`

If composer generation fails, use a compact text fallback:

- current stage: Review
- locked/unlocked status
- exact yes/no requirement when locked
- next command only when unlocked

Referenced files: 18

View saved version →

---
name: start-hackathon
description: Start the Devpost Hackathon workflow in the current project folder and register for the event. Use when the user wants to begin the guided experience, initialize the local state file, register on Devpost, or understand the end-to-end flow before working through the event in Codex.
---

# Start Hackathon

## Purpose

Own the first real setup: initialize or resume the local hackathon state, register the participant for the event, compose the Start chat response, and point them to the next command.

Chat is the primary participant interface. Keep responses text-first so they render in any Codex host; the bundled `devpost` MCP server supplies rich inline visuals on hosts that support them.

## Required Data Source

Official event data comes from the `devpost` MCP server — follow **Devpost MCP Server** in `references/plugin-runtime.md` (call only what you need, never verify or set up the server, degrade in one line on failure). Every `devpost` tool call requires sign-in; the auth gate is this skill's first required `devpost` call. On a fresh start that is a selection call — `list_open_hackathons` or `get_hackathon_overview` (see **Preconditions**); when a hackathon is already selected, it is `get_registration_form` (see **Registration**). Do not add a separate `whoami` call.

For the Start page, draw on these only as needed: `devpost.get_hackathon_overview`, `devpost.get_key_dates`, `devpost.get_announcements`. For inline selection when no hackathon is chosen (see **Preconditions**): `devpost.list_open_hackathons`.

For registration (see **Registration**): `devpost.get_registration_form` and `devpost.register_for_hackathon`.

## Required References

Read before responding:

- `references/plugin-runtime.md`
- `references/config/hackathon.json`
- `references/content/steps/start.md` (the page content you will present)

## Workspace Assumption

Treat the current directory as the participant's real hackathon project folder.

If the folder already contains project files, continue. This plugin is meant to operate inside the real project, not in a separate notes workspace.

## Preconditions

Read `.devpost-hackathon-state.json` if it exists. `$find-hackathon` is discovery only and
writes nothing, so selection normally happens here. If no hackathon has been chosen yet
(`hackathon.selected` is absent or false), do not stop and do not bounce the participant to
another command — resolve the selection inline, then continue with this command's flow in
the same turn:

1. If the participant named a hackathon in their message (a Devpost slug, a clear event
   name, or a devpost.com URL), confirm it via `get_hackathon_overview` and select it
   (`source: "known"`).
2. Otherwise call `devpost.list_open_hackathons` once:
   - **Exactly one hackathon in the catalog:** select it automatically — do not present a
     list of one or ask them to choose. Say so in one line: "This app currently features
     [name], so I've set you up for it — the full catalog is always on Devpost" (link
     `links.browse_hackathons` from `references/config/hackathon.json`). Then move on
     (`source: "featured"`).
   - **More than one:** present the short numbered list (top 3-5); when they pick, confirm
     via `get_hackathon_overview`, then continue (`source: "search"`).
   - **Fetch fails or returns nothing:** ask them to paste a hackathon name, slug, or URL.
     Never invent or assume an event no tool returned.
3. **Slug:** the catalog entries carry no slug. Derive it from the event's standard
   `https://<subdomain>.devpost.com/` URL — the subdomain is the slug. This is a
   deliberate shortcut for the current one-event period; revisit the identity/listing
   design when multiple events are supported. Later steps (for example `$resources`) read
   `hackathon.slug`, so always record it.
4. Record the selection in the `hackathon` block of the state file initialized below —
   `slug`, `name`, `url`, `selected: true`, and the `source` noted above.

The single-entry auto-select is deliberately not a config flag — the server-curated catalog
is the switch. While the catalog lists only one event (Build Week at launch),
`$start-hackathon` alone gets participants into it with zero friction; when the catalog
opens up after the event, this same rule automatically starts presenting choices. Nothing
to un-ship. Every later step targets the selected event.

## State Initialization

This command initializes the full local state, once. If `.devpost-hackathon-state.json`
does not exist in the project root, create it by writing this initial payload (the
canonical state shape), with the `hackathon` block filled in from **Preconditions**:

```json
{
  "plugin": "devpost-hackathon",
  "version": 2,
  "hackathon": { "slug": "", "name": "", "url": "", "selected": true, "source": "" },
  "participant": { "name": "", "display_name": "" },
  "project": { "name": "", "summary": "", "ai_usage": "", "codex_usage": "" },
  "current_stage": "start-hackathon",
  "completed_stages": [],
  "rules_acknowledged": false,
  "learning": { "status": "not-started", "current_step": "", "completed_steps": [], "plan_file": "", "checklist_file": "" },
  "submission": { "draft_file": "devpost-submission.md", "status": "not-started" },
  "next_command": "start-hackathon"
}
```

The initial payload deliberately does not add `start-hackathon` to `completed_stages` —
this stage is marked complete only after the registration gate resolves (see **Marking
Start Complete**). Never mark a stage complete before its auth gate has passed.

If a state file already exists but is partial — for example a legacy file containing only a
`hackathon` block, written by an older version of `$find-hackathon` — merge the initial
payload into it: add every missing field, preserve every field that is present (including
`hackathon`), and never reset progress.

If the state file already exists and is complete, do not reinitialize and do not reset
progress — load it, preserve it, and continue.

Do not create sample project content, draft submission files, or example hackathon notes
during this step. Only initialize or reuse the state file.

## Registration

Step 1 is the registration surface. After state is initialized:

1. Call `devpost.get_registration_form` immediately — do not first ask whether the participant is already registered, and do not call `whoami`. This call requires sign-in (when a hackathon was already selected before this run, it is the skill's first required call and therefore the auth gate) and it reports both the participant's registration status and the form requirements.
   - **Auth failure:** hard-stop per **On auth failure** in `references/plugin-runtime.md` — one-line notice, the sign-in recovery, and stop. Do not walk the participant through registration questions they will be unable to submit.
   - **Already registered:** say so in one line and skip the rest of this section — continue to the Start response.
   - **Availability failure (not auth):** degrade in one line per `references/plugin-runtime.md` and offer the browser fallback (the official event landing page from live data or the hackathon URL already in local state).
2. Walk the participant through the required fields conversationally:
   - Open the walk-through plainly: "Reply to these registration questions and agree to the rules and terms." Tell them they can answer in ordinary language — free text is fine — and that questions marked with an asterisk (*) are required.
   - Present each custom question's text VERBATIM, IN ALL CAPS, exactly as the form returns it — never paraphrase, summarize, or truncate a question (a participant must see precisely what they are answering). Mark required questions with an asterisk (*). Before submitting, confirm every required question has an answer — stop and ask rather than submitting with gaps or invented answers.
3. Show a short plain summary of exactly what will be submitted on the registration form and require an explicit confirmation before proceeding. Alongside the rules/terms agreement, include the website-prevails disclaimer: this guide is a helper — if anything here ever disagrees with the Devpost website, the website prevails.
4. On confirmation, call `devpost.register_for_hackathon` with the collected answers, then report the result. If it fails on availability, degrade in one line and offer the browser fallback above.

Do not persist registration status in the state file — it is Devpost-owned and read live. Registration is a real write to Devpost: never call `register_for_hackathon` without the participant's explicit go-ahead on this turn.

## Marking Start Complete

Once the registration section resolves without an auth stop — already registered,
registration submitted, or the availability-failure browser fallback (offered or
declined) — update `.devpost-hackathon-state.json` before composing the Start response:
add `start-hackathon` to `completed_stages`, and set `current_stage` and `next_command`
to `review-hackathon-rules` (per **Next-command discipline** in `references/plugin-runtime.md`).

On an auth failure, make no completion update: leave `current_stage` and `next_command`
as `start-hackathon` so `$hackathon-map` routes the participant back here, keep the
recorded `hackathon` selection so a rerun resumes cleanly after sign-in, and hard-stop
per `references/plugin-runtime.md`.

## Personalization

Do not ask personalization questions here — no name question, no project-idea question.
The guided build tool's onboarding (`$build-onboard`) picks up the participant's name via
`devpost.whoami` and the project idea through its interview; submission prep gathers the
rest. If the participant volunteers a name or project idea unprompted, record it in
`.devpost-hackathon-state.json` (`participant.display_name`, `project.summary`, and
`project.name` only for a clear project name), preserving the rest of the file — but never
solicit it.

## Presentation Output

After creating or loading state, compose the response in-context per `references/plugin-runtime.md`
("Composing the Response"): read `references/content/steps/start.md`, strip maintainer `<!-- -->`
comments, interpolate the event name, and present it as the participant-facing response.
Render the journey stepper widget first (see PLUGIN_RUNTIME). Keep the response text-only;
the stepper widget is the progress visual.

## Chat Output

Keep chat output minimal. Do not hand-write a separate progress dashboard or landing
experience — the stepper widget shows progress.

In normal operation, respond with:

- a warm welcome that names the event and explains that Codex will guide the participant through the hackathon from this project folder
- one sentence explaining that Codex will keep the process in chat with text progress
- whether state was created or loaded
- the next command: `$review-hackathon-rules`
- an invitation to ask questions about how the flow works before continuing

## Handoff

End by telling the participant:

1. Their registration status (registered here via MCP, already registered, or the browser fallback if declined/unavailable).
2. Run `$review-hackathon-rules` next.

The stepper note is on the Start page itself (`content/steps/start.md`): a simple stepper visualization always shows what stage they're in, and `$hackathon-map` is there whenever it isn't enough information. Don't repeat that note in your own prose — the page carries it.

Referenced files: 17

View saved version →

---
name: submit-project
description: Submit the project to Devpost — run the final readiness check against the hackathon requirements and the prepared draft, then, after explicit user confirmation, actually submit via the Devpost MCP and verify it landed. Use when the user is ready to submit, wants the final checklist, or asks whether they have submitted.
---

# Submit Project

## Purpose

Actually submit the participant's project to Devpost. The command runs the final readiness review and the local security scan on the way, but its job is the submission itself: confirm, call `devpost.submit_project`, verify live that it landed, and report the truth.

Chat is the primary participant interface. Keep responses text-first so they render in any Codex host; the bundled `devpost` MCP server supplies rich inline visuals on hosts that support them.

## Required Data Source

Official requirements and rules come from the `devpost` MCP server — follow **Devpost MCP Server** in `references/plugin-runtime.md` (call only what you need, never verify or set up the server, degrade in one line on failure).

Draw on these only as needed: `devpost.get_submission_requirements`, `devpost.get_hackathon_rules`, `devpost.get_judging_criteria`, `devpost.get_key_dates`. Check readiness against the real requirements; if they are unavailable, run the check against `references/preflight-checklist.md` alone, say it is provisional, and cap the result at `close` — a provisional review can never yield `ready`, because `ready` authorizes a real submit and must rest on the event's live requirements (per **Never present unofficial data as official** in `references/plugin-runtime.md`).

For submission status and the submit itself (all AUTH-REQUIRED): `devpost.list_my_projects` / `devpost.get_project` (find the project and read its real submission status), `devpost.create_project` / `devpost.update_project` (sync the prepared draft when needed), and `devpost.submit_project` (the actual submission).

For thumbnails, two upload services exist (both AUTH-REQUIRED) — pick by encoded size: `devpost.upload_project_thumbnail` sends the image inline as base64 through the conversation and is for small images only (target ≤ 50 KB encoded, e.g. a 300×300 JPEG at quality 60; pre-shrink in one step, do not iterate); `devpost.prepare_thumbnail_upload` returns an upload URL (10-minute TTL) plus the OS-specific curl/PowerShell command that streams the file from disk without putting the bytes through the conversation — use it for anything larger. Both accept JPEG/PNG/GIF up to 5 MB.

## Required References

Read before responding:

- `references/plugin-runtime.md`
- `references/preflight-checklist.md`
- `references/config/hackathon.json`
- `references/content/steps/check.md` (the page content you will present)

## Preconditions

Read `.devpost-hackathon-state.json`.

If the file does not exist, direct the user to `$start-hackathon`.

If `rules_acknowledged` is not `true`, direct the user to `$review-hackathon-rules` first.

If `devpost-submission.md` does not exist, direct the user to `$prepare-submission`.

Legacy state: older state files may use `submission` (instead of `submit-project`) in `completed_stages` or `next_command`, and may contain a `browser_handoff_ready` field. Treat `submission` as this stage and ignore `browser_handoff_ready` — but never treat a legacy `completed_stages` entry as proof of an actual submission; only the live check below proves that.

## Live Status Check (first, when reachable)

This whole command acts on Devpost, so gate it: call `devpost.whoami` (AUTH-REQUIRED) first. If it fails on auth, hard-stop per **On auth failure** in `references/plugin-runtime.md` — one-line notice, the sign-in recovery, plus the official Devpost submission page URL so the participant can still finish on the website before the deadline. Do not run the readiness review as if it could end in a submit.

Whether the project is submitted is Devpost-owned data — local state is never proof. After the gate passes, check live: call `devpost.list_my_projects` / `devpost.get_project` (AUTH-REQUIRED) and read whether this project has been submitted to this hackathon (`submitted_at` on the hackathon entry).

- **Already submitted:** lead with the ✅ status block (below) and the public project URL, skip the readiness review and confirmation, and offer the offboarding follow-up ideas instead (see **Offboarding**).
- **Not submitted:** proceed with the readiness review below, under the ⏳ status line.
- **Status tools unavailable (availability, not auth):** proceed with the review, say the live status could not be verified, and keep the ⏳ line. A signed-out participant never reaches this branch — auth failure already hard-stopped at the gate above.

## Security Scan

Before assigning the final readiness result, scan the project for exposed secrets with a
grep (no script needed). Run from the participant's project root:

```bash
grep -rInE 'sk-[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9]{20,}|gh[posru]_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]+|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----|(api[_-]?key|secret|password|token)\s*[:=]\s*["'"'"'][^"'"'"']{8,}' . \
  --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=build --exclude-dir=.next --exclude-dir=venv --exclude-dir=__pycache__ 2>/dev/null
find . \( -name '.env' -o -name '*.pem' -o -name 'id_rsa' -o -name 'id_dsa' \) -not -path '*/node_modules/*' -not -path '*/.git/*' 2>/dev/null
```

Interpret the results:

- **block**: the grep matched a high-confidence secret (OpenAI/GitHub/Slack token, AWS key,
  or a private-key block). The submission cannot be marked `ready` — and you must NOT call
  `submit_project` — until it is removed.
- **review**: only risky credential-looking files (`.env`, `*.pem`, `id_rsa`) or generic
  `key=…`/`password=…` assignments turned up. The submission can be `close`, not `ready`,
  unless the participant explicitly verifies they are benign.
- **pass**: no matches.

Never paste raw secret values in chat or generated files — refer to the file and line only,
with the value redacted.

## Readiness Review

Review:

- rules acknowledgment recorded
- project brief present
- honest build description
- AI usage explained clearly
- Codex usage explained clearly
- testing instructions included
- repo link present or clearly marked TODO
- public demo link present or clearly marked TODO
- demo video plan or URL present or clearly marked TODO
- screenshot plan present
- every event requirement satisfied (cross-check against `get_submission_requirements`)
- unresolved legal or sponsor placeholders clearly labeled
- no obvious contradiction between the build and the submission copy
- no high-confidence exposed secrets from the local security scan
- no risky credential-looking files that need user review

Assign one top-line result: `ready`, `close`, or `not ready`. Missing inputs (repo URL,
demo URL, video decision) are asked for conversationally — one short question each — not
dumped as a chore list pointing at internal files.

## Submit To Devpost (MCP, auth, high-stakes)

The final submit is high-stakes, so it REQUIRES explicit user confirmation before you call the tool.

1. Only proceed when the readiness result is `ready` — which requires the live requirements check; a provisional, fallback-checklist review caps at `close` and never ends in a submit. Never submit on a `block` scan result.
2. Present a short, plain summary of exactly what will be submitted: the project title, the hackathon name, and any category or custom-question answers. State clearly that this submits the project to Devpost for real.
3. Require the user to explicitly confirm they want to submit now (an unambiguous "yes, submit"). If they do not confirm, stop and leave the project unsubmitted — do not call the tool — and keep the ⏳ status line in the response.
4. On confirmation, call the `devpost.submit_project` MCP tool (AUTH-REQUIRED) for the prepared project and hackathon. If the project does not exist on Devpost yet, create or sync it first via `create_project` / `update_project`, confirming with the user before each write.
4a. **Offer to capture a screenshot when one is missing.** If the project has no thumbnail or screenshots and it runs locally, offer — don't just note the gap: "Want me to capture a screenshot from the running app and upload it as your project thumbnail?" On yes, capture, upload via the size-appropriate thumbnail service (AUTH-REQUIRED; see **Required Data Source** — `upload_project_thumbnail` inline at ≤ 50 KB encoded, `prepare_thumbnail_upload` streaming from disk above that), and confirm per 4b. Never capture or upload without their yes.
4b. **Confirm every asset you handle.** If a screenshot or thumbnail is provided or uploaded on this turn (`prepare_thumbnail_upload` / `upload_project_thumbnail`), state explicitly what was received and where it went — uploaded as the project thumbnail, saved locally at a path, or still pending. Never handle an upload silently. On a successful thumbnail upload, add one line telling the participant what it's for: this image now represents the project — it's the picture shown on their project listing in the hackathon's submissions on Devpost.
5. **Verify, then report.** After `submit_project` returns success, confirm live via `devpost.get_project` (or `list_my_projects`) that the submission is recorded, and report the ✅ status line with the public project URL. If the readback can't run, report the tool's returned confirmation and say verification is pending.

Fallback: if `submit_project` fails on auth or availability, do NOT silently succeed — keep the ⏳ status line, report that the submit could not be completed, note that submitting requires being signed in to the Devpost MCP, and give the official Devpost submission page URL so the participant can finish on the website before the deadline. If they submit on the website, tell them to come back and run `$submit-project` again — the live status check will verify it. Leave `submission.status` as `ready` so the MCP submit can be retried.

## State Update

Edit `.devpost-hackathon-state.json` directly, only when state changes on this turn,
preserving the fields you are not touching.

`completed_stages` may gain `submit-project` in exactly one case: `submit_project`
succeeded (or the live check confirmed an existing submission). A readiness result of
`ready` is not completion — the participant has not submitted yet.

- **Submitted (verified):** add `submit-project` to `completed_stages`, set `current_stage`
  to `submit-project`, `submission.status` to `submitted`, and `next_command` to
  `hackathon-map`. A returned confirmation id/url may be recorded under `submission`.
- **Ready but not yet confirmed/submitted:** set `current_stage` to `submit-project`,
  `submission.status` to `ready`, and `next_command` to `submit-project`. Do NOT touch
  `completed_stages`.
- **Not ready:** set `current_stage` to `submit-project`, `submission.status` to
  `needs-work`, and `next_command` to the specific command that fixes the top issue (e.g.
  `prepare-submission`).

## Presentation Output

After the readiness review and the state edit, compose the response in-context per
`references/plugin-runtime.md` ("Composing the Response"): read `references/content/steps/check.md`,
strip maintainer `<!-- -->` comments, interpolate the event name, and present it. Render
the journey stepper widget first (see PLUGIN_RUNTIME). Summarize the scan + readiness
result in your own words alongside the page content.

## Chat Output

Keep chat output compact. Do not hand-write a separate progress dashboard — the stepper
widget shows progress.

**Mandatory status block.** Every response from this command must include, verbatim, near
the top, exactly one of the two blocks (⏳ or ✅) from **Submission Status Blocks** in
`references/plugin-runtime.md`. On the turn a fresh submit succeeds, the **Offboarding** response
below replaces the ✅ heading with its celebratory form — that is the one sanctioned
variant. The ✅ form may be used only after `submit_project` success or a live check
confirming the submission — never on `ready`, never from local state alone. Verb
discipline: outside the ✅ block, never say "submitted" or "submission complete" about the
participant's work.

## Offboarding (after a verified submission)

On the turn a submit succeeds (and, trimmed to the follow-up ideas, when a later run finds
the project already submitted), close the journey properly. First call
`devpost.get_key_dates` for the real submission deadline; if it is unavailable, write "the
submission deadline" and point to the hackathon page — never invent a date. Then compose
in this shape, interpolating the URL and deadline:

```markdown
### 🎉 Submitted — congratulations!

✅ **Submitted to Devpost** — verified live. Your public project page: <URL>

You did the hard part: you shipped. Now here's the part most people miss — **your
submission isn't frozen.** You can keep improving your project page until the deadline
(**<deadline>**), and judges see the final version, not the one from the moment you hit
submit. You can keep editing and polishing your submission form on the Devpost website
too — **a good idea to double-check the AI's work and make sure it looks exactly how you
want it.**

Worth an hour before the deadline:

- **Read your project page like a judge.** Open it on Devpost and ask: would a stranger
  understand what this does in 10 seconds? For example, if your gallery opens with a
  screenshot of your terminal, swap in the one where the app is actually doing the
  impressive thing.
- **Add more screenshots or a short demo video** — projects with visuals get remembered.
- **Invite your teammates** on Devpost so everyone gets credit on the project page.
- **Share your public link** — momentum and feedback beat polishing in private.

That's everything — type `$hackathon-map` anytime to see where things stand.
```

The journey is complete, so never end this response with the "Say next" callout — the
anytime-offer line above is the closer (per `references/plugin-runtime.md`).

Respond with:

- the status line
- readiness result: `ready`, `close`, or `not ready` (when a review ran)
- security scan status
- missing inputs asked conversationally, one short question each, if needed
- when ready but not yet submitted: the explicit confirmation prompt described above (what will be submitted + "yes, submit?")
- when submitted: the **Offboarding** response (see that section) — celebratory heading, live deadline, the polish ideas, and the anytime-offer closer; never the "Say next" callout
- when a submit attempt failed: the specific failure, the sign-in note, and the official website URL to finish before the deadline

If you cannot read the content file, fall back to a compact text response:

- the status line
- readiness result and security scan status
- the confirmation prompt, missing-input questions, or the submission result as appropriate
- next recommended command

Referenced files: 18