decision-log

🏁 Hackathon Run

Ship the demo, not the dream.

A decision-making and execution system for hackathon teams operating under time pressure. Fifteen skills, one workflow: clarify, prize-target, scope, time-box, build, verify, demo, judge, ship, recover, pivot, retro, decide-log.

---

The problem

A hackathon is not a coding problem. It is a time-pressure, decision-making, execution problem.

• 23 hours in, you have 8 unfinished features.
• The demo crashes on stage and you have 60 seconds to recover.
• A judge asks "what's novel here?" and you have no answer.
• Your README references API keys that you cannot ship.
• Your teammate has been debugging the wrong thing for 4 hours.

Hackathon Run does not help you write code faster. It helps you make the right cut, at the right time, every time.

---

How it works

Fifteen skills, mapped to the hackathon lifecycle:

idea-clarify (pre) pivot (mid-build redirect) │ │ ▼ ▼ scope-knife ─► time-box ─► fast-verify ─► demo-coach ─► judge-sim ─► ship-pack │ │ │ │ │ │ └──────────────┴────────────┴──────────────┴─────────────┴────────────┘ │ │ │ │ │ │ stack-picker (cold-start) retro (post-event) │ │ │ │ team-roster (build start) recovery-runbook (anytime) │ │ demo-rehearsal (final 2h)

Each skill is independently invokable. You can run any of them at any time without running the others.

---

Agent workflow

Hackathon Run works best when an agent treats it as a harness, not as a menu of one-shot prompts. Four roles keep long-running work moving without letting the same agent both build and approve its own output: an initializer sets up the first session, a planner writes the default-FAIL contract, a generator builds one feature per sprint, and an evaluator verifies it from a fresh context.

The runtime follows the production agent-loop pattern used by ChatGPT and the OpenAI Agents SDK: context is assembled from sessions, every input and output passes a guardrail, tools return observable results, the loop is bounded by budget, and every meaningful step is traced. It also follows Anthropic's long-running harness pattern: the first session initializes the environment, every later session reads PROGRESS.md + git log, and the operator can stop or steer the loop from the outside.

Production agent loop

flowchart LR
  User(["User / trigger"]) --> InGuard{"Input guardrail\npolicy + budget + schema"}
  InGuard -->|"reject"| Block(["Blocked\nrefuse + explain"])
  InGuard -->|"accept"| Context["Context assembly\nsession + plan + skill"]
  Context --> Loop{"Agent loop\nmax_turns + budget"}
  Loop -->|"next turn"| Reason["Reason\nchoose action"]
  Reason --> Tools["Tool invocation\nskills / scripts / MCP / shell"]
  Tools --> Observe["Observe\nstdout / files / tests / evidence"]
  Observe -->|"loop"| Loop
  Loop -->|"final"| OutGuard{"Output guardrail\nJSON Schema + evidence"}
  OutGuard -->|"reject"| Loop
  OutGuard -->|"accept"| Output(["Final output\nstate + evidence"])
  Context -. "read / write" .-> Session[("Session\nhandoff + memory")]
  Loop -. "trace" .-> Trace[("Trace\nevents / spans")]

Harness runtime architecture

The production agent loop is organized into six layers: interface, context, agent loop, hands, durable state, and operator control. Every layer writes to or reads from the durable state store so a fresh context window can resume without the previous conversation.

flowchart TB
  classDef state fill:#fff7ed,stroke:#ea580c,color:#7c2d12;
  classDef gate fill:#eff6ff,stroke:#2563eb,color:#1e3a8a;
  classDef trace fill:#f0fdf4,stroke:#16a34a,color:#14532d;

  subgraph Interface["Interface Layer"]
    User(["User / trigger"]) --> InGuard{"Input guardrail\npolicy / budget / schema"}
    InGuard -->|"reject"| Reject(["Blocked\nrefuse + explain"])
    InGuard -->|"accept"| ContextAssembly["Context Assembly\nplan + session + skill + progress"]
  end

  subgraph Context["Context Layer"]
    Session[("session.json\nhandoff")]
    Progress[("PROGRESS.md\nagent log")]
    Git[("git log\ncommit history")]
    ContextAssembly -. "reads" .-> Session
    ContextAssembly -. "reads" .-> Progress
    ContextAssembly -