hack-plan

hackathon-kit

English · Español

A Claude Code plugin that takes a hackathon challenge statement and gets your team ready to code: it analyses the challenge, proposes approaches for you to choose from, generates the repo, a per-person plan and a pitch outline, and checks all of it against the statement.

Who it's for: hackathon teams that use Claude Code and want to go from the challenge statement to the first commit without losing the first hour. Prompts and templates are in Spanish, and the kit has only been validated in Spanish.

Installation

Inside a Claude Code session:

/plugin marketplace add Mveradc/hackathon-kit
/plugin install hackathon-kit@hackathon-kit

Or from your shell:

claude plugin marketplace add Mveradc/hackathon-kit
claude plugin install hackathon-kit@hackathon-kit

To update: /plugin marketplace update hackathon-kit. To try it without installing, clone the repo and run claude --plugin-dir <path to the repo>.

Check that /hack lists the ten commands: the six of the chain, /hack-note and the three for agent coordination. Each one can be run as /hack-<name> or /hackathon-kit:hack-<name>.

Flow

Run it in the project's empty folder. Each command reads the previous step's file in .hackathon/, which you can edit by hand between steps.

/hack-analyze <challenge> → /hack-approaches → you choose → /hack-scaffold <stack>
   → fill in equipo.md → /hack-plan → /hack-pitch → /hack-check

Sample outputs from two real challenges are in skills/*/examples/.

Agent coordination (optional, experimental, since 0.2.0)

Experimental. Validated in a private sandbox repo with one person simulating the team (two accounts, two sessions), not yet with a real team.

When each team member works with their own Claude Code, questions between pieces usually travel agent → person → person → agent. With coordination on, the agents ask each other through GitHub Issues and only design, product and pitch decisions reach people.

• Turn it on in /hack-scaffold (it asks; off by default). It writes .hackathon/coordinacion.md with the repo and each person's GitHub user, and /hack-plan adds .hackathon/autoridad.md: what each agent decides alone, what needs its owner's confirmation and what is people-only.
• /hack-ask asks another agent without blocking (it works on a provisional assumption), /hack-inbox handles what arrives and /hack-decide closes an agreement into .hackathon/decisiones.md. A background monitor polls the repo every minute and stays silent when there is nothing new.
• A contract change only closes when its owner comments exactly hk confirmo from their own GitHub account. Long disagreements and loops are cut and escalated to people.
• Every /hack-note note is announced to the whole team: each person's agent summarises it and tells them to git pull.
• Requirements: gh signed in with each person's own account, Git Bash on Windows and an interactive session (not claude -p). It relies on plugin monitors, an experimental Claude Code feature.
• Since 0.3.0, a hook stops any agent from posting hk confirmo through gh. It is a safety net, not a guarantee: the agent uses its person's gh and could get around it.

Orchestrator (optional, experimental, since 0.3.0)

Experimental. Validated in a sandbox copy of a real challenge with one person simulating the team, not yet with a real team.

One orchestrator per person takes that person's tasks from .hackathon/plan.md and gets them done without writing code itself:

claude --agent hackathon-kit:orquestador

• It splits each block of the plan into small jobs and hands them to workers (Sonnet), at most two at a time, each in its own git worktree. A hook stops the orchestrator (Opus) from editing code.
• It merges each worker's branch outside your branch. An independent reviewer (Sonnet) checks that merge in its own worktree and reruns the check, without seeing the worker's report. Your branch only moves (fast-forward) to merges the reviewer approved. If the reviewer asks for changes twice, the task stays open and your branch is untouched.
• It pushes its approved merges (never forced), but never commits or pushes your own work.
• Progress lives in .hackathon/estado/<person>.md. Restart the orchestrator after each block: its context grows with every job, and a fresh session picks up from the state file without repeating merged work. It also recovers after a crash: it re-reviews a pending merge and asks you what to do with leftover worktrees, without deleting anything on its own.
• Cost: about USD 0.9–1.6 per block of one or two jobs, most of it the orchestrator.

Hackathon OS (optional, experimental, since 0.4.0)

Experimental. Validated without a model (400+ tests and the evals in evals/coordinacion/) and in a sandbox with one person simulating the team. Not yet rehearsed with a real team.

Keeps the whole team aware of who is doing what, what is already in main and where you are about to collide, without asking out loud. Turn it on with activa: sí in .hackathon/os.md; off, everything behaves as in 0.3.2.

• Team status. A daemon per person (no model) reports what happens in their clone, and a relay on the coordinator's laptop puts it together. Each session gets a short «Team» block at start and, on every turn, only what changed and affects it. An os MCP server answers estado, tarea and colisiones. Anything stale is shown as stale, with its time.
• Collision warnings, never blocks: two people in the same file, incompatible changes before merging (opt-in with publicar_wip: sí) and contracts touched by someone who doesn't own them.
• Work web (web_nueva: sí): each person's daemon serves it on 127.0.0.1. hk-os web opens it. Four views (cockpit, team graph, board, services), plus two actions: Anotar (adds a note to criterios.md in origin/main without touching your copy) and Reclamar (assigns the issue with your gh and opens one turn in your session). Nobody installs Node: the web ships built.
• .hackathon/servicios.md: port