{"id":6309,"plugin_id":"plugin_asdk_app_6a330a7730c081919892632d5baaec58","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T22:48:05.543Z","digest":"4a133612b078070bd87bba58f97426e8ca1c1debf40c168ed28d37295cfd902c","against":null,"payload":{"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.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":199},{"relative_path":"references/SETUP.md","size_in_bytes":1231},{"relative_path":"references/config/hackathon.json","size_in_bytes":1897},{"relative_path":"references/content/learning/build.md","size_in_bytes":939},{"relative_path":"references/content/learning/checklist.md","size_in_bytes":618},{"relative_path":"references/content/learning/onboard.md","size_in_bytes":1333},{"relative_path":"references/content/learning/prd.md","size_in_bytes":972},{"relative_path":"references/content/learning/scope.md","size_in_bytes":403},{"relative_path":"references/content/learning/spec.md","size_in_bytes":356},{"relative_path":"references/content/steps/check.md","size_in_bytes":1150},{"relative_path":"references/content/steps/help.md","size_in_bytes":2595},{"relative_path":"references/content/steps/map.md","size_in_bytes":948},{"relative_path":"references/content/steps/prepare.md","size_in_bytes":1599},{"relative_path":"references/content/steps/resources.md","size_in_bytes":1601},{"relative_path":"references/content/steps/rules.md","size_in_bytes":840},{"relative_path":"references/content/steps/start.md","size_in_bytes":1868},{"relative_path":"references/plugin-runtime.md","size_in_bytes":11707}],"skill_md_contents":"---\nname: start-hackathon\ndescription: 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.\n---\n\n# Start Hackathon\n\n## Purpose\n\nOwn 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.\n\nChat 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.\n\n## Required Data Source\n\nOfficial 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.\n\nFor 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`.\n\nFor registration (see **Registration**): `devpost.get_registration_form` and `devpost.register_for_hackathon`.\n\n## Required References\n\nRead before responding:\n\n- `references/plugin-runtime.md`\n- `references/config/hackathon.json`\n- `references/content/steps/start.md` (the page content you will present)\n\n## Workspace Assumption\n\nTreat the current directory as the participant's real hackathon project folder.\n\nIf the folder already contains project files, continue. This plugin is meant to operate inside the real project, not in a separate notes workspace.\n\n## Preconditions\n\nRead `.devpost-hackathon-state.json` if it exists. `$find-hackathon` is discovery only and\nwrites nothing, so selection normally happens here. If no hackathon has been chosen yet\n(`hackathon.selected` is absent or false), do not stop and do not bounce the participant to\nanother command — resolve the selection inline, then continue with this command's flow in\nthe same turn:\n\n1. If the participant named a hackathon in their message (a Devpost slug, a clear event\n   name, or a devpost.com URL), confirm it via `get_hackathon_overview` and select it\n   (`source: \"known\"`).\n2. Otherwise call `devpost.list_open_hackathons` once:\n   - **Exactly one hackathon in the catalog:** select it automatically — do not present a\n     list of one or ask them to choose. Say so in one line: \"This app currently features\n     [name], so I've set you up for it — the full catalog is always on Devpost\" (link\n     `links.browse_hackathons` from `references/config/hackathon.json`). Then move on\n     (`source: \"featured\"`).\n   - **More than one:** present the short numbered list (top 3-5); when they pick, confirm\n     via `get_hackathon_overview`, then continue (`source: \"search\"`).\n   - **Fetch fails or returns nothing:** ask them to paste a hackathon name, slug, or URL.\n     Never invent or assume an event no tool returned.\n3. **Slug:** the catalog entries carry no slug. Derive it from the event's standard\n   `https://<subdomain>.devpost.com/` URL — the subdomain is the slug. This is a\n   deliberate shortcut for the current one-event period; revisit the identity/listing\n   design when multiple events are supported. Later steps (for example `$resources`) read\n   `hackathon.slug`, so always record it.\n4. Record the selection in the `hackathon` block of the state file initialized below —\n   `slug`, `name`, `url`, `selected: true`, and the `source` noted above.\n\nThe single-entry auto-select is deliberately not a config flag — the server-curated catalog\nis the switch. While the catalog lists only one event (Build Week at launch),\n`$start-hackathon` alone gets participants into it with zero friction; when the catalog\nopens up after the event, this same rule automatically starts presenting choices. Nothing\nto un-ship. Every later step targets the selected event.\n\n## State Initialization\n\nThis command initializes the full local state, once. If `.devpost-hackathon-state.json`\ndoes not exist in the project root, create it by writing this initial payload (the\ncanonical state shape), with the `hackathon` block filled in from **Preconditions**:\n\n```json\n{\n  \"plugin\": \"devpost-hackathon\",\n  \"version\": 2,\n  \"hackathon\": { \"slug\": \"\", \"name\": \"\", \"url\": \"\", \"selected\": true, \"source\": \"\" },\n  \"participant\": { \"name\": \"\", \"display_name\": \"\" },\n  \"project\": { \"name\": \"\", \"summary\": \"\", \"ai_usage\": \"\", \"codex_usage\": \"\" },\n  \"current_stage\": \"start-hackathon\",\n  \"completed_stages\": [],\n  \"rules_acknowledged\": false,\n  \"learning\": { \"status\": \"not-started\", \"current_step\": \"\", \"completed_steps\": [], \"plan_file\": \"\", \"checklist_file\": \"\" },\n  \"submission\": { \"draft_file\": \"devpost-submission.md\", \"status\": \"not-started\" },\n  \"next_command\": \"start-hackathon\"\n}\n```\n\nThe initial payload deliberately does not add `start-hackathon` to `completed_stages` —\nthis stage is marked complete only after the registration gate resolves (see **Marking\nStart Complete**). Never mark a stage complete before its auth gate has passed.\n\nIf a state file already exists but is partial — for example a legacy file containing only a\n`hackathon` block, written by an older version of `$find-hackathon` — merge the initial\npayload into it: add every missing field, preserve every field that is present (including\n`hackathon`), and never reset progress.\n\nIf the state file already exists and is complete, do not reinitialize and do not reset\nprogress — load it, preserve it, and continue.\n\nDo not create sample project content, draft submission files, or example hackathon notes\nduring this step. Only initialize or reuse the state file.\n\n## Registration\n\nStep 1 is the registration surface. After state is initialized:\n\n1. 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.\n   - **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.\n   - **Already registered:** say so in one line and skip the rest of this section — continue to the Start response.\n   - **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).\n2. Walk the participant through the required fields conversationally:\n   - 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.\n   - 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.\n3. 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.\n4. 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.\n\nDo 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.\n\n## Marking Start Complete\n\nOnce the registration section resolves without an auth stop — already registered,\nregistration submitted, or the availability-failure browser fallback (offered or\ndeclined) — update `.devpost-hackathon-state.json` before composing the Start response:\nadd `start-hackathon` to `completed_stages`, and set `current_stage` and `next_command`\nto `review-hackathon-rules` (per **Next-command discipline** in `references/plugin-runtime.md`).\n\nOn an auth failure, make no completion update: leave `current_stage` and `next_command`\nas `start-hackathon` so `$hackathon-map` routes the participant back here, keep the\nrecorded `hackathon` selection so a rerun resumes cleanly after sign-in, and hard-stop\nper `references/plugin-runtime.md`.\n\n## Personalization\n\nDo not ask personalization questions here — no name question, no project-idea question.\nThe guided build tool's onboarding (`$build-onboard`) picks up the participant's name via\n`devpost.whoami` and the project idea through its interview; submission prep gathers the\nrest. If the participant volunteers a name or project idea unprompted, record it in\n`.devpost-hackathon-state.json` (`participant.display_name`, `project.summary`, and\n`project.name` only for a clear project name), preserving the rest of the file — but never\nsolicit it.\n\n## Presentation Output\n\nAfter creating or loading state, compose the response in-context per `references/plugin-runtime.md`\n(\"Composing the Response\"): read `references/content/steps/start.md`, strip maintainer `<!-- -->`\ncomments, interpolate the event name, and present it as the participant-facing response.\nRender the journey stepper widget first (see PLUGIN_RUNTIME). Keep the response text-only;\nthe stepper widget is the progress visual.\n\n## Chat Output\n\nKeep chat output minimal. Do not hand-write a separate progress dashboard or landing\nexperience — the stepper widget shows progress.\n\nIn normal operation, respond with:\n\n- a warm welcome that names the event and explains that Codex will guide the participant through the hackathon from this project folder\n- one sentence explaining that Codex will keep the process in chat with text progress\n- whether state was created or loaded\n- the next command: `$review-hackathon-rules`\n- an invitation to ask questions about how the flow works before continuing\n\n## Handoff\n\nEnd by telling the participant:\n\n1. Their registration status (registered here via MCP, already registered, or the browser fallback if declined/unavailable).\n2. Run `$review-hackathon-rules` next.\n\nThe 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.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}