win-hackathon

A Claude Code plugin that runs the entire hackathon lifecycle as one guided, gated workflow: reading the Devpost rules, generating and scoring ideas against the real rubric, choosing a stack and architecture, writing specs, building test-driven, deploying, reviewing, and submitting — as slash commands, subagents, skills, and hooks.

Overview

A Devpost URL goes in. Eleven gated phases later, a reviewed, deployed, judge-ready submission comes out: a judge-facing README, demo runbook, Devpost form draft, video script, and screenshot shot-list — gated on a clean architecture-and-code review (zero blocking findings) plus every hard submission requirement done or skipped.

Every judgment phase emits a schema-validated JSON payload before it writes anything, and every rendered surface — markdown, diagrams, the Kiro spec triad, Terraform/CI config, the five submission surfaces — is generated from that one payload, so nothing downstream can drift from the source of truth.

The full design lives in docs/design/win-hackathon-plugin.md; see CHANGELOG.md for release history.

The workflow

Eleven gated phases. Nothing advances without explicit approval.

:recon → :brainstorm → :describe → :stack → :architect → :requirements → :spec → :build → :ship → :review → :submit

You never need to remember that order — :next resolves it from on-disk state.

Install

From a local clone:

git clone https://github.com/rogerjeasy/win-hackathon.git
/plugin marketplace add /path/to/win-hackathon
/plugin install win-hackathon

Directly from GitHub, without cloning first:

/plugin marketplace add rogerjeasy/win-hackathon
/plugin install win-hackathon

The git root is the plugin root deliberately: /plugin marketplace add expects .claude-plugin/ at the top level. Pin an exact release instead of tracking main by appending a ref: /plugin marketplace add rogerjeasy/win-hackathon#v1.0.0.

Commands

Command	What it does
/win-hackathon:init [--dry-run]	Sets up (or adopts) the workflow in this project. Never overwrites a file without a per-file yes; no --force flag exists.
/win-hackathon:next	Resolves which phase comes next from on-disk state and starts it. Reports drift when state and the filesystem disagree.
/win-hackathon:status	Phase board, time remaining, outstanding deliverables, unclaimed bonus points, missing tools. Changes nothing.
/win-hackathon:recon <devpost-url>	Reads the hackathon end to end — rules, rubric, deadlines, panel, bonus points — and writes the brief.
/win-hackathon:brainstorm [--fresh] [--angle <name>]	Generates ten ideas from four angles, gates them on Stage One, and scores the survivors against the real rubric.
/win-hackathon:describe [--idea <id>] [--track <id>]	Turns the chosen idea into the product case and the win strategy.
/win-hackathon:stack	Resolves the technology stack under sponsor-wins precedence — required tech first, personal defaults filling the gaps, every slot with a reason.
/win-hackathon:architect	Designs the system — architecture, data model, three diagram formats, and the AGENTS.md invariants — all rendered from one validated payload.
/win-hackathon:requirements	Turns the architecture into FR ids with acceptance criteria, a test matrix, and executable Gherkin scenarios.
/win-hackathon:spec	Turns requirements into per-feature specs — the Kiro triad, plus OpenSpec change proposals when the CLI is reachable.
/win-hackathon:build [--feature <FR-id>]	Implements the must-have features one at a time, TDD all the way via superpowers:subagent-driven-development, running :check after each one.
/win-hackathon:check	Audits required/forbidden sponsor technology with file:line evidence — never a manifest guess. Safe to run any time; does not gate.
/win-hackathon:ship	Picks a deploy target, writes Dockerfiles/Terraform/CI, actually deploys, and curl-verifies every URL before the gate.
/win-hackathon:pivot	Deadline triage — proposes a demoable core, ranked safest-to-cut-first, protecting any feature that solely claims a judging criterion. Requires explicit approval.
/win-hackathon:review	Runs /code-review and dispatches quality-reviewer, merges both into a validated review.json. Refuses to reach the gate while any finding is blocking; should-fix/post-hackathon findings never block.
/win-hackathon:submit	Re-runs :check, then dispatches submission-writer for a validated submission.json feeding all five judge-facing surfaces. Refuses the gate unless the review is clean and every hard submission requirement is done or skipped.
/win-hackathon:log <text>	Appends a timestamped entry to challenges.md — the manual path; agents write this file automatically too.

Each command ends at an approval gate and stops — :check, :pivot, and :log are the exceptions: :check is a repeatable audit with no gate of its own, :pivot's only gate is the approval it asks for directly in Step 2, and :log is a running log with no judgment to gate.

What each phase produces

Working documents land in .hackathon/; judge-facing ones land in docs/ and the repo root later in the workflow.

Phase	Artifacts
:recon	recon.json, brief.md, rules.md, criteria.md
:brainstorm	ideas.json, ideas.md — plus ideas-round-N.* when you re-run with --fresh
:describe	project.md (the product), strategy.md (how it wins)
:stack	stack.json, stack.md — every slot with a source (required/default/bonus) and a reason
:architect	architecture.json, docs/architecture.md, docs/data-model.md, plus AGENTS.md/CLAUDE.md at the repo root
:requirements	requirements.json, requirements.md, requirements.feature (executable Gherkin)
:spec	specs/NNNN-<slug>/{requirements,design,tasks}.md per must-have feature (the Kiro triad), plus openspec/changes/<slug>/proposal.md when the @fission-ai/openspec CLI is reachable
:build	Application source code, one must-have feature at a time — progress is read back from [x] checkboxes in that feature's own tasks.md, not tracked a second way in state.json
:ship	deploy.json — per-service target, Dockerfile, verified URL and verification method, plus the infra//.github/workflows/ files deploy-engineer writes alongside it
:review	review.json, review.md — merged /code-review + quality-reviewer findings, classified blocking/should-fix/post-hackathon
:submit	submission.json feeding five surfaces: README.md, docs/DEMO_RUNBOOK.md, .hackathon/submission.md, .hackathon/video-script.md, .hackathon/screenshots.md

Every judgment phase validates before it writes. Each of :recon, :brainstorm, :stack, :architect, :requirements, :ship, :review, and :submit emits a JSON payload that must pass a schema first; every rendered surface — markdown, diagrams, the Kiro triad, deploy.json, the five submission surfaces — comes from that payload, so nothing downstream can drift from the source. Rules the schemas enforce because they lose hackathons outright:

• Every date carries an explicit UTC offset. A floating 2026-06-29T17:00:00 is rejected.
• A disqualified idea is never scored — a number invites falling in love with an idea that cannot win.
• A rubric criterion no feature claims fails :requirements validation outright — it would otherwise score zero silently.
• A service marked verified: true in deploy.json must carry a real verified_at and verification_method — :ship does not gate on a deploy until every service it could verify has actually been curl-ed, not just configured.
• :review cannot reach awaiting_approval while any finding is blocking — mechanically enforced, not left as a reading of review.md.
• :submit cannot reach awaiting_approval unless project.review.clean is true and every hard submission_requirements item is done or skipped. (/win-hackathon:submit additionally asks, as a process convention rather than a schema check, that a skipped item get its own decisions.md entry — the same trail :pivot leaves for a cut feature.)

Dependencies

These are requirements of the workflow, not of the plugin's own code:

• superpowers — :build invokes its SDD and TDD skills
• @fission-ai/openspec — optional for :spec. When the CLI is reachable it also gets one change proposal per must-have feature; when it isn't, :spec defers that step and still finishes with the Kiro triad it writes either way. Install the scoped name; the bare openspec package on npm is an unrelated stub.
• No Playwright/MCP dependency. :recon uses WebFetch; when a page is JS-gated or comes back thin it records the gap in unresolved and asks you to paste the page, rather than failing silently. See the design note in docs/design/m2-front-half.md.

Releases

Not every push to main is a release — cutting one is a deliberate, separate act:

1. Add a ## [x.y.z] - YYYY-MM-DD section to the top of CHANGELOG.md describing what changed.
2. Bump version in .claude-plugin/plugin.json and package.json to match.
3. Commit, then tag and push: git tag -a vX.Y.Z -m "vX.Y.Z" and git push origin vX.Y.Z

Pushing the tag (not the commit itself) is what triggers .github/workflows/release.yml: it re-runs the test suite, pulls that version's section out of CHANGELOG.md via .github/scripts/release-notes.mjs, and publishes the GitHub Release from it. The workflow only listens for v* tag pushes, so ordinary commits to main never trigger it, and it fails closed if the matching CHANGELOG.md section is missing or empty rather than publishing a release with no notes.

License

MIT