Hackathon

Plan, build, and demo one project inside a judged event's fixed build window.

A hackathon asks three questions that the normal pipeline does not, and this skill exists to answer them:

1. Which project wins? The most useful project and the winning project are different choices. Judges see many tables in a row, rate noisily, and remember the best moment and the last one more than the average. Projects that win are familiar surprises: a frame the judge already knows, with one twist they did not expect, understood in seconds (Thompson's MAYA, "most advanced yet acceptable").
2. How much fits? Do not estimate in hours. An agent-assisted build does not move at human rates, and a model estimating its own throughput borrows human ones. Fix the time, vary the scope (Shape Up): plan more rungs than seem possible, measure how long rungs actually take on the day, and re-plan at fixed clock checkpoints from that measured pace. Your own measured rung time is the only reference class that counts.
3. What does "done" mean when judges inspect it? Many events judge the process as well as the product: tests, security, observability, and whether you can explain your decisions. The build keeps its tests and gates, and the process that produced the code (the factory) is something you show.

The time box is fixed. Scope, never the deadline, absorbs every surprise.

Invocation Position

Side-route, user-invoked only. It fires when a human types /hackathon <brief-url-or-nothing>; disable-model-invocation: true keeps its description out of every other session's context. Send it as its own message, never as the first message of a fresh workspace: a host that prepends text to a first message displaces the slash command, and because this skill is hidden from the model it cannot be looked up afterward (the same failure /lfg § Invocation Position records).

It runs in two sittings: prep before the event (Phases 0–2) and the build day (Phases 3–4). A second /hackathon with no argument resumes from the newest dossier (see State).

Boundary with /lfg. /lfg takes an ask to an unattended proof-of-concept PR and ends in /pre-merge --loop. Use it for a spike nobody judges. Use /hackathon when a panel will judge the result inside a fixed window: it adds project selection, clock checkpoints, and the demo, and it keeps a human in the loop all day.

Reconnects to the main workflow: nowhere by default; the event is the end of the line. If the project continues after the event, start it at /shape with the dossier and DECISIONS.md as input. If the day exposed friction in the pack itself, recommend /improve-pipeline.

Mode. HITL by default, one question per turn. A rung runs AFK only after its row in the ladder names its done-condition and its tracer test.

What this skill never does. It never invents a judging rubric, weight, or prize the brief does not state. It never pushes to the event repo before the event's start time. It never moves the freeze or the submission deadline: when time runs short it cuts rungs. It never writes the review-currency stamp, never merges, and never runs /closeout.

Locked vocabulary

Every phase reads these values. Change one here and nowhere else.

State

Two homes, split on purpose.

• Prep lives off-tree, in the project's sidecar (the pack's private, local git repo outside the working tree), as one dossier: <sidecar>/research/hackathon-<YYYY-MM-DD>.md. Events often require the repo to be empty until the start, so nothing from prep may be committed there. The dossier's shape is references/dossier-template.md.
• From the start time on, two files live in the event repo: PLAN.md (the ladder) and DECISIONS.md (the decision log). This is a scoped exception to the pack's rule that durable state never lives in the project tree. Here the repo is the judged deliverable, and judges read the decision log. The exception covers those two files in an event repo and nothing else.

Set up the sidecar in the directory that will become the event repo. Create it with git init and no commits and nothing pushed, so the empty-until-start rule holds. Ask the user for the event repo's remote URL (the empty repo they create on the forge) and record it with git remote add, which pushes nothing, before init: init reads the remotes once to set forge.kind and the write permissions, so a sidecar created with no remote records none and routes PRDs, slices, and the review stamp to the sidecar instead of GitHub. The resolver has no command that re-derives forge.kind later (config set mode re-derives only the write permissions), so if the URL is not known yet, do not leave the remote off. Ask which forge host the event repo will use, put a placeholder on that host in the <event repo remote URL> slot below (for example https://github.com/placeholder/event-repo.git), and when the real URL arrives run git remote set-url origin <real URL>; the sidecar still resolves and forge.kind stays as recorded. The resolver is the bundled references/sidecar.sh, at its absolute installed path:

SC="<this skill's directory>/references/sidecar.sh"
git rev-parse --git-dir >/dev/null 2>&1 || git init -q
# The URL the user gave for the event repo. Adds the remote only; pushes nothing.
git remote get-url origin >/dev/null 2>&1 || git remote add origin "<event repo remote URL>"
if git rev-parse --verify -q HEAD >/dev/null; then
  echo "note: this repo already has commits; if the event requires an empty repo until the start, stop and use a fresh directory" >&2
fi
SC_ERR="$(mktemp)"
if bash "$SC" resolve 2>"$SC_ERR"; then
  echo "sidecar: resolved (a hit; do not run init)"
elif grep -q '^SIDECAR MISS' "$SC_ERR"; then
  cat "$SC_ERR" >&2
  echo "sidecar: miss; ask the mode question below, then run init" >&2
else
  cat "$SC_ERR" >&2
  echo "sidecar: resolve failed without a SIDECAR MISS line; stop and relay it as printed" >&2
  rm -f "$SC_ERR"
  exit 1
fi
rm -f "$SC_ERR"

Creating a sidecar is a human decision, so run init only on the SIDECAR MISS line above. On any other failure, stop and relay what the block printed, with no questions and no init. On a miss, ask one question: is the event repo owned (the user's own, so the pack may write issues and PRs on its forge) or guest (the organizer's or someone else's, so the pack writes nothing to its forge)? Recommend guest when the repo sits in an organizer's or sponsor's org. Then run init with the miss line's suggested --name and the answer:

SC="<this skill's directory>/references/sidecar.sh"
bash "$SC" init --name <suggested name from the miss line> --mode <owned|guest> --write sidecar --in-tree-path none --no-migrate-archive

Relay an init refusal as printed. Then, on a hit or after init:

SC="<this skill's directory>/references/sidecar.sh"
research_dir="$(bash "$SC" path research)" || exit 1
echo "dossier: $research_dir/hackathon-$(date +%F).md"

Commit the dossier to the sidecar at the end of each phase. Set the dossier's phase: first, to the phase that comes next (choose after Phase 0, shape after Phase 1, build after Phase 2, demo at the freeze, done after Phase 4), so a resume starts where the work stopped:

SC="<this skill's directory>/references/sidecar.sh"
bash "$SC" commit -- "<dossier path>" -m "hackathon: <phase name>"

Resume. With no argument, find the newest dossier, read it, and continue from the phase: its frontmatter records (demo resumes at Phase 4). A build resume skips the kickoff block when PLAN.md is already committed in the event repo:

SC="<this skill's directory>/references/sidecar.sh"
research_dir="$(bash "$SC" path research)" || exit 1
newest="$(find "$research_dir" -maxdepth 1 -name 'hackathon-*.md' | sort | tail -n 1)"
if [ -z "$newest" ]; then
  echo "no dossier in $research_dir; start at Phase 0" >&2
  exit 1
fi
echo "$newest"
sed -n '2,/^---$/p' "$newest"

Process

Phase 0. Event profile

Take the brief as a URL (fetch it, and any rules, FAQ, or judging page it links) or as pasted text. Fill the dossier's Event profile table. Mark every field stated (with a short verbatim quote) or not stated:

• start time, build window, submission deadline, and submission platform
• judging format (stage pitch, floor or table visits, video) and length
• judging criteria and any weights
• tracks and prize categories, including sponsor prizes
• team size; rules on pre-built code, templates, and installed tooling
• allowed tools and models; required artifacts (repo, video, write-up)

Never fill a not stated field with a typical value. A rubric you invented steers every later score toward a judge who does not exist. Instead, list each gap as a question for the organizers in the dossier's Open questions. Whether your own installed tooling counts as pre-built code is always on that list unless the rules state it.

Recheck before the build. When a rules guide or judging guide arrives later, redo this phase against it before Phase 3.

Team. Then ask, one question at a time, who is on the team and what each person will do on the day: who writes code, and who does not. Record each person in the dossier's Team table with the accounts they need logged in. A team is rarely all builders. A common shape is one developer driving agents plus a product, design, or domain person who writes no code, and that person is not a spare pair of hands. They are the one independent reader the build has, and Phases 1–4 give them work only a non-builder can do well (see Lanes in Phase 2).

Phase 1. Choose the project

1. Reference class. Look at what this event, or the same series, picked before: a past-winners gallery (Devpost and similar list them), a recap post, or sponsor-track winners. Note in one line each what the winners had in common. If there is no history, record none found and move on.
2. Generate candidates. Ask the user, one question at a time, what problems they care about and what the tracks invite. Then propose candidates up to the Locked count. Include at least one that is familiar and one that is ambitious, so the scoring has range.

3. Score each dimension across all candidates before totaling anything. Score dimension by dimension, column by column, never candidate by candidate. A strong first impression of one candidate then cannot raise its other scores (Noise's decomposition move: independent assessments first, one holistic judgment last). Anchors, 1 → 5:

   Dimension	1	5
   Fit	fits no stated track or criterion	squarely in a stated track and hits every stated criterion
   Familiar surprise	either a clone of a known thing, or nothing a judge can map to anything	sayable as "a known X, for / with an unexpected Y"
   Peak moment	nothing visibly happens in a demo	one moment where a judge watches something surprising happen live
   60-second legibility	needs a setup talk before it makes sense	a judge gets it from the first screen and one sentence
   Factory showcase	the process behind it would be invisible	building it exercises tests, gates, and agents you can tour
   Slow-dependency risk (higher is safer)	needs approvals, hardware, scarce data, or a paid tier	runs on accounts you already have, with public or synthetic data
   Why you	no reason you, specifically, built this	a reason you can say in one sentence that a judge will believe

   Weights follow the brief's stated weights. When none are stated, weight the dimensions equally and say so; do not invent a weighting.

4. Blind second scorer. Spawn one fresh sub-agent. Give it only the event profile, the candidate one-liners, and the anchor table, never this conversation. Have it score the same grid. Discuss only the cells where the two grids differ by the Locked disagreement threshold. That spread is the noise in your own judgment. When the team includes a non-builder, have them score the grid too, on their own and before seeing either grid. A person who thinks like a user is the closest stand-in for a judge you have, and their column is worth more than a third model.
5. Compare, then commit. The Locked candidate count, scored on seven dimensions, meets the comparison threshold in references/next-step-menu.md § Show the comparison before you take the choice. Show the grid as a table first, then ask the user to pick with an AskUserQuestion menu. The menu's option cap (see the same reference) is smaller than the candidate count, so offer only the top scorers that fit, top scorer first and marked recommended; the free-text "Other" hatch takes a pick from the rest of the table.
6. Write the two lines everything else hangs on into the dossier:
   • the high-concept line ("a known X, with Y"), and
   • the peak moment: the one thing the judge watches happen.

Phase 2. Shape

Use /shape's discipline compressed to one sitting; point at it rather than re-deriving it. Fill the dossier:

• Scope ladder. List at least the Locked minimum of rungs, in build order. Plan more than seems possible on purpose: cutting a planned rung at a checkpoint is cheap, and an empty ladder at mid-afternoon wastes the day.
  • Rung 1 is a tracer bullet (Hunt & Thomas): the thinnest path that runs end to end through every real layer, demoable on its own, built with production structure rather than as a throwaway prototype. If only rung 1 ships, you still have a demo.
  • Each later rung adds one thing a judge would notice, and it must be able to land on its own.
  • Mark nice-to-haves ~ (Shape Up's scope hammer). They are the first cut.
  • Give each rung a done-condition and the tracer test that proves it. A rung without both is not ready to run AFK.
  • Put the peak moment as early on the ladder as it can go.
• Rabbit holes and no-gos. Name what you will not build, and the parts most likely to swallow an hour, along with what you will do instead.
• Slow-dependency work goes first. Move to the kickoff block and rung 1 everything an agent cannot speed up: API keys and quotas, OAuth and auth, the deploy target (its final hostname), the riskiest third-party integration, and data access. These fail slowly, and they fail late if left late.
• Factory plan. Decide which process artifacts to stand up at kickoff and show at the table: the pipeline hooks from /init-pipeline, CI running the tests on every push, a dependency or secret scan, structured logging or a health endpoint, and the decision log. Pick what the event's criteria reward. If the brief names none, default to tests, CI, and logs.
• Lanes. Split the day by lane, not by person, then give each lane an owner from the Team table. Record the owners in the dossier.
  • Build lane (whoever writes code, with agents): the rungs, the factory, and the deploy. With several builders, give each a rung from the same ladder, choosing rungs that touch different files where possible.
  • Demo lane (a non-builder when there is one): owns the clock and calls each checkpoint; accepts each rung by using it on the deployed URL against its done-condition, not by reading code; seeds the demo data and rehearses the peak moment; keeps DECISIONS.md current by asking "why that one?" as decisions happen; drafts the submission write-up and table script during the build instead of after the freeze; asks mentors and organizers the Open questions on the floor.
  • Solo: you hold both lanes. Put the demo-lane work into the checkpoint, so it happens at fixed times instead of never.
• Seed the decision log. Copy each decision made so far (project, stack, cuts), with the alternatives you rejected and why. Judges ask "why X over Y?", and the answer should already be written down.
• Pre-flight checklist for the night before (dossier template § Pre-flight): accounts logged in on the build machine, keys tested, the deploy target reachable, chargers and adapters packed, and the rules guide read with Phase 0 rechecked against it.

End prep: set phase: build, commit the dossier, and print the clock plan from the next section so the user sees the day.

Phase 3. Build day

Clock plan. Compute from the event profile, using the Locked vocabulary:

• the kickoff block's end (start time + kickoff block)
• each checkpoint (every checkpoint interval after that, while before the freeze)
• the freeze (deadline − freeze)
• the submit-by time (deadline − submission buffer)

Write the four kinds of times into PLAN.md and the dossier. Then hold them: nothing in this phase moves the freeze or the submit-by time.

Kickoff block (after the start time and never before):

1. If the build actually starts at a time other than the event profile's start time, recompute the kickoff block's end and the checkpoints from the actual start, in PLAN.md and the dossier alike. The freeze and the submit-by time come from the deadline, so they stay. Add PLAN.md (the ladder plus the clock plan) and DECISIONS.md (copied from the dossier's seeded log), make the first commit, then push it to the remote added in prep with git push -u origin HEAD.
2. Run /init-pipeline to scaffold the hooks and pre-commit gates. Add CI that runs the tests.
3. Deploy a hello-world to the deploy target, so the slowest unknown is resolved first.

Rung loop. For each rung, in ladder order:

1. Record its start time in the dossier.

2. Write the rung's tracer test first, then the code. Delegate to /tdd for behavior-heavy logic; invoking it creates .claude/.tdd-active. Once /init-pipeline has installed its hook, an implementation write is blocked unless a classification marker exists, so a rung that is visual, layout, styling, or copy only, and so does not go through /tdd, first creates the skip marker at the project root, where the hook looks, not in the current directory:

   ROOT="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel)}"
   mkdir -p "$ROOT/.claude" && touch "$ROOT/.claude/.tdd-skipped"

3. Run the tests, commit with CI green. Do not tick the rung yet (step 6 does). Then remove the rung's classification marker, as /execute Step 6 does, so the next rung classifies afresh and the gate stays closed between rungs:

   ROOT="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel)}"
   rm -f "$ROOT/.claude/.tdd-active" "$ROOT/.claude/.tdd-skipped" "$ROOT/.claude/.lfg-active"

4. Deploy the green commit to the deploy target, or confirm CI's deploy shipped it, then give the demo-lane owner the URL. Acceptance below happens on that URL, so a rung that is not deployed cannot be accepted.
5. Append to DECISIONS.md any decision the rung forced, with the rejected alternative.
6. The demo-lane owner (you, when solo) accepts the rung: they use it where a judge would, and either tick it in PLAN.md or name the gap. A rung is done only when accepted, so a builder's green commit does not make it done.
7. Record its end time when it is ticked.

The lanes from Phase 2 run in parallel. The checkpoint re-plan below still runs on the whole ladder, and the demo-lane owner calls it.

Checkpoint (at each checkpoint time; stop what you are doing):

1. Measure. From the dossier, compute the median time per accepted (ticked) rung. Leave rung 1 out once two later rungs exist, because it carries setup time.
2. Re-plan from measured pace, never from a fresh estimate. Rungs that fit ≈ (freeze − now) ÷ median rung time. Keep that many of the remaining rungs in ladder order. Cut ~ rungs first. If the time left exceeds the remaining ladder, add rungs: the ladder ran short, not the day.
3. Circuit breaker. If rung 1 is not green at the first checkpoint, make it thinner: stub the dependency that blocks it behind the same interface, and say so in DECISIONS.md. Pivot projects only if the idea itself is broken. A thinner tracer is almost always cheaper than a new idea.
4. Record the re-plan (kept, cut, added) in the dossier and PLAN.md. A changed ladder is a real fork, so confirm it with the user before going on.

Freeze. At the freeze, stop adding rungs. Whatever is unfinished either works behind a flag or gets reverted. Set phase: demo and commit the dossier. From here on, the only work is demo readiness.

Phase 4. Freeze → demo

1. Pre-demo checklist (dossier template § Pre-demo). Run it DO-CONFIRM style: do the work, then read the list aloud and confirm each item (Gawande). Things fail at the worst moment, so the checklist assumes the live demo will break; the template holds the one list.
2. Submission. Fill the platform's write-up from the dossier and PLAN.md: the problem, the high-concept line, what shipped (the ticked rungs), how it was built (the factory), and what was cut. Submit by the submit-by time.
3. Table script (Locked length): open on the high-concept line, show rung 1's path, and end on the peak moment. Judges remember the peak and the ending. Rehearse it until it fits the time, then rehearse the 15-second version for a judge who is already walking away.
4. Judge Q&A. From DECISIONS.md, draft the five most likely "why X over Y?" questions with a one-sentence answer each, plus a two-minute factory tour: the hooks, CI, the tests, and the decision log. Drill both with the user, one question at a time.
5. Who says what at the table. With a non-builder on the team, they open: the problem, the high-concept line, and the demo through the peak moment. The builder takes the factory tour and the "how did you build it" questions. Each "why X over Y?" goes to whoever made that decision in DECISIONS.md.

Before phase: done, tick the template's § Pre-handoff confirmations, then commit the dossier.

Common Rationalizations

Red Flags

• A score or weight in the dossier with no stated quote behind it.
• A ladder with fewer rungs than the Locked minimum, or no ~ rungs.
• A checkpoint that re-estimated remaining rungs instead of using the measured median.
• A commit in the event repo dated before the start time.
• No recorded fallback video at the freeze.
• DECISIONS.md unchanged since kickoff.

Handoff

• Expected input: the event brief (a URL or pasted text) and the user, present for both sittings, plus who else is on the team and whether each writes code; a local directory that will become the event repo.
• Produces: the sidecar dossier (event profile, scored candidates, ladder, rung timings, checkpoint re-plans); in the event repo, PLAN.md, DECISIONS.md, the pipeline hooks, and CI; a submitted entry; a rehearsed table script and judge Q&A.
• May invoke: /init-pipeline (kickoff block), /tdd (rung loop), one blind-scorer sub-agent (Phase 1).
• Returns control to: the user at the judging table.
• Comes next by default: nothing. To continue the project after the event, start at /shape with the dossier and DECISIONS.md. For pack friction, use /improve-pipeline.

Print, substituting the real values:

**Next session:** /shape (only if the project continues)
**Input:** dossier <path> and DECISIONS.md in <repo> — a hackathon build; read its cut rungs before reshaping