Check the clock, the setup, the push and the pitch line

Run this at the start of every working session in the team's clone, before any other work: the clock comes first, because a team that loses track of it loses its submission. The

hackathon

CLI does the checks; this skill runs it, reads the

--json

answers and walks the participant through the fixes. Run from the team's clone. If the participant never joined (no

hackathon

command, or

hackathon connect

says to sign in), use the

hackathon-setup

skill instead.

1. The clock, first

bash

hackathon event status --json

Read, from the answer:

phase

(

scheduled

building

grace

closed

serverTime

event.buildEndsAt

event.freezeAt

(always the build end plus 15 minutes),

event.timezone

event.lastReschedule

(the organizers moved the build end, with their reason),

me.project

(the team:

id

name

) and, in the team's line of

projects[]

submission.repository.designatedBranch

and

submission.lastReceipt

(

sha

receivedAt

late

Compute every time left from

serverTime

, never from this machine's clock. Then tell the participant, in two or three lines, in the event's time zone:

the phase, and the time left to the build end and to the freeze (for example: "Building. 3 h 12 min to the build end (17:00), 3 h 27 min to the freeze (17:15).");
the rule, once per session: what counts is the last push to
```
<designatedBranch>
```
that the platform received before the freeze. There is nothing to click and nothing to submit; a commit on this machine is not a submission;
a reschedule, if
```
event.lastReschedule
```
is set, with its reason.

If you are not sure the participant knows a deadline (a new session, a reschedule, a teammate who joined late), ASK: "Do you know the build ends at 17:00 and the freeze is at 17:15?" Wait for the answer before going on.

scheduled

: say when the build starts; the setup can be checked now.

closed

: say the submission is frozen (

submission.frozen.sha

), that nothing pushed now counts, and skip the pacing.

2. The doctor

bash

hackathon doctor --directory . --json      # from the clone; without --directory it checks the default folder

It changes nothing. The answer is

{ ok, platform, checks: [{ name, ok, detail, fix?, cls? }] }

: Git and its identity, Node.js 22, Docker, the daemon, Compose, the disk, the instance, the credential, the roster, the repository, the GitHub access, the clone, a dry-run push, the installer, the app and

hackathon.json

. For every check with

ok

false, show its

fix

and offer to walk the participant through it on their system (

platform

darwin

is macOS,

linux

win32

is Windows). Run the doctor again after each fix, until it exits 0.

git identity

: ask the name and email they want on their commits, then

git config --global user.name "<name>"

and

git config --global user.email "<email>"

```
push
```
refused: GitHub saw another account than the one on the roster. The participant accepts the invitation with the roster's account, or signs in to GitHub with it (
```
gh auth login
```
, which they run themselves).
```
credential
```
or
```
roster
```
(class
```
access
```
): use the
```
hackathon-setup
```
skill; it handles the sign-in.

Never run

sudo

gh auth login

for them: show the command and let them run it.

3. The app

If the

app

check failed because nothing answers on the port:

bash

hackathon setup --directory . --json

It keeps the clone and its local changes, builds the image, starts the app and waits for its readiness probe. Exit 4 "not ready in time": run the

docker compose … logs

command it printed and read the error with the participant (a missing key in

.env

is the usual one; they paste keys there themselves, never in the chat).

4. Did the platform receive the last push

bash

hackathon submissions list --json
git rev-parse HEAD
git status --short --branch

A participant's answer has one line in

projects[]

: their team's. Compare its

submission.lastReceipt.sha

with the local

HEAD

the same: say it plainly ("The platform has your last commit, received at 14:32.");
different, or
```
lastReceipt
```
null: the platform does not have this machine's work. If the local commits are meant to count, push to the designated branch now (the pacing below), then check again;
```
late
```
true: that push arrived at or after the freeze, is recorded, and never counts.

GitHub delivers a push to the platform in a few seconds, sometimes more. If the revision is not there after a minute,

hackathon submissions show <me.project.id> --json

lists the receipts, refused ones included; if it still does not arrive, open a request for an organizer (

hackathon requests open

5. The team's project description

Each team is a project of the event, and its description is the one line the organizers, the coaches and the jury read about the team. Read it:

bash

hackathon projects get <me.project.id> --json

Read

description

and

myRole

. The description needs work when it is empty, or stale: it no longer matches what the repository and this session show the team is building (the README, the recent commits, what the participant says now), or the participant says the idea changed.

ASK, in one question: "In one or two sentences, what are you building: the problem, for whom, and your approach?" Skip the question when they have just told you.
Propose a crisp description from their answer: one or two sentences, under 300 characters, the problem, who it is for and how, in their words, no marketing. For example, invented: "Cooks waste leftovers because recipes start from a shopping list. Fridgeful starts from a photo of the fridge and proposes three dinners that use what is already there."
Set it only on their OK.

Who sets it.

hackathon projects update

needs the manager role on the project, and a participant is placed on their team's project as an editor, so the command is normally refused for them. So:

myRole

manager

: run

hackathon projects update <me.project.id> --description "<the agreed text>" --json

, then

hackathon projects get <me.project.id> --json

to read it back. A refusal with

insufficient_project_role

means the role changed: go to the next case.

otherwise (the usual case): an organizer sets it. First
```
hackathon requests list --status open --json
```
: if the team already has an open request titled
```
Project description
```
, post the new text in its thread instead of opening another one (
```
hackathon requests show <id> --json
```
names the thread's channel;
```
hackathon chats post <channelId> --file <file>
```
). Else open one:
bash
```
hackathon requests open --title "Project description" \
  --body "Please set our team's description to: <the agreed text>"
```
Tell the participant an organizer sets it, and read it again at the next check.

Keep it current: whenever the participant says the idea, the audience or the approach changed, run this section again.

6. The pacing for the rest of the session

This section holds for the whole session, not only while this skill runs.

Push small and often to
```
<designatedBranch>
```
: after every piece that works, and at least every 30 to 45 minutes. Ask once per session: "May I commit and push to
```
<designatedBranch>
```
after each working step?" and push only with that OK; otherwise remind the participant to push at the same pace. Never force-push, never rewrite history.
Confirm the receipt after each push:
```
hackathon submissions list --json
```
,
```
lastReceipt.sha
```
against
```
git rev-parse HEAD
```
(section 4). A push the platform did not receive is not a submission.
Read the clock again (
```
hackathon event status --json
```
) before starting any task that takes more than a few minutes, and after each push. Warn the participant once as each mark passes:
- 60 minutes before the build end: say the time left; scope down to what can work by then; remind that the demo deck is due: the
```
hackathon-deck-demo
```
  skill;
- 30 minutes: no new feature; make what exists work, push, confirm the receipt; the demo deck should be under way;
- 15 minutes: final push of the working state, confirm the receipt, finish the demo deck.
The grace (
```
phase
```
```
grace
```
, between the build end and the freeze): only fixes, no new work. Push each fix at once and confirm its receipt. Do not push in the last minute: a push GitHub accepts just before the freeze but that reaches the platform after it does not count.
Before the end, if the demo deck is not linked yet (
```
hackathon decks show --json
```
), run the
```
hackathon-deck-demo
```
skill.
If the organizers moved the build end (
```
event.lastReschedule
```
), say the new deadlines and their reason.

Exit codes

0 done; 1 an API refusal outside the journey, such as

insufficient_project_role

projects update

(read the

error.code

); 2 a flag is wrong; 3 access (a sign-in to do, not on the roster, no repository yet, GitHub refused): the state has to change before a retry, say who to ask; 4 the machine: install, start or free what the message names; 5 the folder is not the assigned clone.

Never

Never pass a credential to any command, never edit the remote URL, never

git reset --hard

or delete files to make a check pass, never run a real

git push

to test access (the doctor's dry run does that), never push without the participant's OK, never force-push.

hackathon-doctor

NPX Install

Tags

SKILL.md Content

Check the clock, the setup, the push and the pitch line

1. The clock, first

2. The doctor

3. The app

4. Did the platform receive the last push

5. The team's project description

6. The pacing for the rest of the session

Exit codes

Never