🏁 Hackathon Run

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")]

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 -. "reads" .-> Git
  end

  subgraph Loop["Agent Loop Layer"]
    ContextAssembly --> LoopGate{"Loop\nbudget / max_iterations"}
    LoopGate -->|"turn"| Reason["Reason\nchoose action"]
    Reason --> ToolGate["Tool invocation"]
    ToolGate --> Observe["Observe\nstdout / files / tests / evidence"]
    Observe -->|"iterate"| LoopGate
    LoopGate -->|"final"| OutGuard{"Output guardrail\nJSON Schema / evidence"}
    OutGuard -->|"reject"| LoopGate
  end

  subgraph Hands["Hands Layer"]
    Skills["skills / scripts"]
    MCP["MCP tools"]
    Browser["browser automation"]
    Shell["shell / sandbox"]
    ToolGate --> Skills
    ToolGate --> MCP
    ToolGate --> Browser
    ToolGate --> Shell
  end

  subgraph State["Durable State Layer"]
    Plan[("plan.json\nP0/P1/P2 + default-FAIL")]
    Sprint[("sprint.json\ncriteria + budget + rubric")]
    Eval[("eval.json\nscores + strategy")]
    Trace[("events.jsonl\nappend-only")]
    OutGuard -->|"accept"| Plan
    LoopGate -. "write" .-> Sprint
    LoopGate -. "write" .-> Eval
    LoopGate -. "trace" .-> Trace
  end

  subgraph Operator["Operator Layer"]
    Stop[("AGENT_STOP\nkill switch")]
    Steer[("STEER.md\none-shot redirect")]
    Stop -. "halts" .-> LoopGate
    Steer -. "surfaced once" .-> ContextAssembly
  end

  class Session,Progress,Git,Plan,Sprint,Eval,Trace state;
  class InGuard,OutGuard,LoopGate,Stop gate;

flowchart TB
  classDef contract fill:#fff7ed,stroke:#ea580c,color:#1f2937;
  classDef gate fill:#eff6ff,stroke:#2563eb,color:#1f2937;
  classDef trace fill:#f0fdf4,stroke:#16a34a,color:#1f2937;
  classDef failure fill:#fef2f2,stroke:#dc2626,color:#1f2937;

  subgraph First["0. Initializer / First Session"]
    direction TB
    Brief(["User brief"]) --> InitCmd["hackathon init"]
    InitCmd --> ScopeCmd["hackathon run scope-knife --apply"]
    ScopeCmd --> Plan[("plan.json\nP0/P1/P2 + default-FAIL")]
    ScopeCmd --> Session[("session.json\nhandoff")]
    InitCmd --> Progress[("PROGRESS.md\nagent-maintained")]
    Progress --> Smoke["start app + smoke test\nverify demo path"]
    Smoke --> FirstCommit["git commit\ninitial setup"]
  end

  subgraph Orchestration["1. Orchestration / Handoff"]
    direction TB
    FirstCommit --> Resume["hackathon resume\npwd -> git log -> PROGRESS.md -> smoke"]
    Resume --> Route{"Next unpassed\nP0/P1/P2 KEEP feature?"}
    Route -->|"yes"| Contract["hackathon sprint new --feature X"]
    Contract --> Approve["hackathon sprint approve"]
    Approve --> Sprint[("sprint.json\ncriteria + budget + rubric")]
    Sprint --> Build
    Route -->|"no"| Pipeline["Delivery pipeline\nfast-verify -> demo-coach -> judge-sim -> ship-pack"]
  end

  subgraph Generator["2. Generator (generator.md)"]
    direction TB
    Build["Read contract + session\nbuild one feature"] --> Self["Self-verify\nlint / tests / smoke"]
    Self --> Commit["git commit + update session"]
    Commit --> Checkpoint["hackathon checkpoint\nappend PROGRESS.md"]
  end

  subgraph Evaluator["3. Evaluator (evaluator.md)"]
    direction TB
    Checkpoint --> Review["hackathon sprint review"]
    Review --> Eval[("eval.json\ncriteria default false")]
    Eval --> Run["Run app / tests / browser / commands"]
    Run --> Evidence["Collect machine-checkable evidence"]
    Evidence --> Rubric{"Score rubric 0-5\nweight + hard threshold"}
    Rubric --> Verdict{"Every criterion\nmeets threshold?"}
    Verdict -->|"no"| Feedback["Write feedback + strategy\nto session.json"]
    Feedback --> Resume
    Verdict -->|"yes"| Accept["hackathon sprint accept"]
    Accept --> Plan
  end

  subgraph Safety["4. Guardrails, Operator Controls & Observability"]
    direction TB
    Budget{"Budget gate\nminutes / max-iterations"} -->|"exhausted"| Blocked["sprint blocked\nverdict = blocked"]
    Schema{"JSON Schema\n+ default-FAIL"} -->|"invalid"| Blocked
    Stop{"AGENT_STOP?"} -->|"exists"| Blocked
    Steer[("STEER.md")] -->|"surfaced once"| Resume
    Blocked --> Session
    Trace[("events.jsonl\nappend-only")] --> Observe["hackathon trace / replay / report"]
    Checkpoint -. "trace" .-> Trace
    Review -. "trace" .-> Trace
    Accept -. "trace" .-> Trace
    Pipeline -. "trace" .-> Trace
  end

  Pipeline --> Ship["Ready to submit"]
  class Plan,Session,Sprint,Progress,Eval contract;
  class Budget,Schema,Stop gate;
  class Trace trace;
  class Blocked,Feedback failure;

flowchart LR
  classDef fail fill:#fef2f2,stroke:#dc2626,color:#1f2937;
  classDef gate fill:#eff6ff,stroke:#2563eb,color:#1f2937;

  FM1["Failure: agent tries to one-shot\nthe whole app"] --> G1{"Gate:\none feature per sprint\n+ default-FAIL"}
  FM2["Failure: agent declares victory\nbefore the demo works"] --> G2{"Gate:\nfresh-context evaluator\n+ machine-checkable evidence"}
  FM3["Failure: next session guesses\nwhat the previous one did"] --> G3{"Gate:\nPROGRESS.md + git log\n+ smoke before building"}
  FM4["Failure: unit tests pass but\nuser-visible flow is broken"] --> G4{"Gate:\nbrowser / command evidence\n+ sprint accept"}
  G1 --> Loop(["Next unpassed KEEP feature"])
  G2 --> Loop
  G3 --> Loop
  G4 --> Loop
  class FM1,FM2,FM3,FM4 fail;
  class G1,G2,G3,G4 gate;

sequenceDiagram
  autonumber
  participant I as Initializer
  participant O as Orchestrator (CLI)
  participant G as Generator
  participant E as Evaluator
  participant S as State Store
  participant T as Trace
  participant Op as Operator

  I->>O: hackathon init
  O->>S: seed session.json + PROGRESS.md
  I->>O: hackathon run scope-knife --apply
  O->>S: write plan.json (P0/P1/P2, default-FAIL)
  I->>I: start app + smoke test
  I->>O: git commit initial setup
  O->>G: hackathon resume
  G->>S: read PROGRESS.md + session.json + git log
  G->>O: hackathon sprint new + approve
  O->>S: write sprint.json (criteria + budget)
  G->>S: commit code + update session.json
  G->>O: hackathon checkpoint --summary "..."
  O->>S: append PROGRESS.md
  G->>E: hackathon sprint review
  E->>S: write eval.json (criteria default false)
  E->>E: run app / tests / browser / commands
  E->>E: score rubric 0-5 + set strategy

  alt all criteria pass
    E->>O: hackathon sprint accept
    O->>S: flip plan.json passes=true + evidence
  else criteria fail
    E->>S: write feedback + strategy to session.json
    E-->>G: feedback for the next iteration
    G->>G: rebuild against the same contract
  end

  Op->>O: hackathon guard steer / guard stop
  O->>S: write STEER.md / AGENT_STOP
  G->>O: hackathon resume
  O-->>G: surface steer once / refuse when stopped

  G-->>T: append event to events.jsonl
  E-->>T: append verdict to events.jsonl
  O-->>T: append state transition to events.jsonl

# One complete agent loop
hackathon init
hackathon run scope-knife --demo-goal "sign up + save note" --time-remaining 240 --apply
hackathon resume
hackathon sprint new --feature Auth
hackathon sprint approve

# Generator builds Auth against the contract, then:
hackathon sprint review

# Evaluator fills .hackathon/state/eval.json with evidence and feedback, then:
hackathon sprint accept
hackathon trace
hackathon flow --execute --demo-goal "sign up + save note" --time-remaining 240

hackathon checkpoint --summary "what changed" --compress

hackathon trace --verify

hackathon sprint budget --minutes 45 --max-iterations 3

npm run ab:harness -- \
  --solo-command "hackathon run scope-knife" \
  --harness-command "hackathon flow --execute"

# Option A -- one-shot via npx (no install needed)

npx @hackathon-run/hackathon-run init

# Option B -- install globally, then use hackathon as the CLI command

npm install -g @hackathon-run/hackathon-run
hackathon init

# Option C -- from source

git clone https://github.com/MAGA2010/hackathon-run
cd hackathon-run
npm install
npm run build
npm link

# Inside any hackathon project

cd my-hackathon-project
hackathon init # creates .hackathon/ in your repo
hackathon run scope-knife # forces a KEEP/CUT/DEFER decision
hackathon run fast-verify # verifies the demo path
hackathon run demo-coach # drafts the pitch
hackathon run judge-sim # self-reviews before submitting
hackathon run ship-pack # packages and checks for leaks
hackathon status --watch --interval 30 # live time and rehearsal-risk pulse
hackathon resume # handoff brief for a fresh agent or new session
hackathon sprint new --feature Auth # create a default-FAIL contract
hackathon sprint approve # lock the contract before building
hackathon sprint review # emit the evaluator handoff
# Evaluator fills eval.json, then:
hackathon sprint accept # apply the verdict back to plan/session
hackathon trace # inspect the runtime event log

# Chained run: follows Format v2 dependencies automatically
hackathon run demo-rehearsal --chain # scope-knife -> fast-verify -> demo-coach -> demo-rehearsal

hackathon skills audit --json
hackathon skills audit --risk-summary --json
hackathon skills audit --strict --policy .hackathon/skills-policy.json
hackathon skills audit --sarif > skills-audit.sarif
npm run test:routing

hackathon judge-calibrate \
  --backend https://judge.example.test \
  --golden tests/fixtures/judge-golden.json \
  --max-mae 1

npm run test:skill-eval

node skill-eval-lab/harness.mjs \
  --runner command \
  --runner-preset codex \
  --runs 3 \
  --ab \
  --control-command "your-baseline-agent --prompt-file {prompt_file}" \
  --min-grade A \
  --fail-on-p1