Guide

During the hackathon you work in a small team (1–3 people, formed freely on Day 1) on one simulation method. You work with two things: an AI coding agent — a chat assistant that runs in your terminal and can read files, write code, and run programs — and the harness, the shared GitHub repository QuantumBFS/quantum.harness, where an expert for each method has collected the key papers, worked examples, and step-by-step instructions that teach the agent to run that method correctly.

Your goal for the week: reproduce a published result for your method, then go beyond it with a challenge of your own, and submit everything as a pull request — GitHub’s mechanism for proposing your changes back to a shared repository, and the form in which advisors review your work.

This page walks through the week in order. Each ▶ Prompt box is text to paste into your agent (Claude Code, Codex CLI, Kimi Code CLI, or OpenCode — see Setup); hover over a box for a copy button.

// Deadlines

// Methods

Each card names the method, the expert who curated that track, and the command that loads the method’s instructions in your agent.

Track folder names in the repository (also used in your submission path and PR title): ed, mps, peps, qmc, qcs, polyopt, agent-kb.

// Setup — Day 1

Install and log in to one AI coding agent before starting the Day 1 workflow. You also need a free GitHub account.

To verify it works, start the tool in any folder and ask it to read a file.

Next, install two helpers. superpowers is a collection of skills — reusable instruction files that teach the agent careful working habits, such as planning before coding and testing before claiming success. gh is GitHub’s command-line tool; the agent uses it to copy the repository and open your pull request.

Install https://github.com/obra/superpowers and gh (GitHub CLI) if not already installed.
Authenticate me to GitHub via gh auth login if I'm not logged in.

// Get the harness (Day 1)

Start from the shared repository and install its skills. The /take-challenge workflow later creates the draft pull request that registers your team and challenge.

Clone https://github.com/QuantumBFS/quantum.harness to ~/code/quantum.harness.
Run make skills to install the harness skills.
Then run /beginner-training to start the guided training.

// Onboard — reproduce a published result

Each track names a reference paper and the specific figures or tables to reproduce. Matching the published numbers proves that your whole setup — agent, code, environment — works end to end, and earns you the right to move on. Start with:

/beginner-training

Run /beginner-training. It offers five guided tracks — setup check, reproduce a paper, literature survey, develop code like an expert, and go beyond — and walks each one step at a time, explaining before it runs anything. No prior git, GitHub, or Julia experience is assumed; that is the training’s job. For the reproduction, take Track 2: it lists every method track’s reference paper, lets you pick one, and then guides the reproduction step by step. When it finishes, note what matched the paper, what didn’t, and which hardware and software you ran on — you will need all of this for your report.

// Take on a challenge

A challenge is a well-posed question that goes beyond the reference paper: a larger system, a different observable, a sharper bound, a better algorithm. Team up in a group of 1–3, pick an accepted idea from the Challenges page or bring your own, then run /take-challenge before 15:00 on Day 1. The skill opens your team’s draft registration pull request; once that PR exists, your challenge is registered. You may consult mentors at the help desk, but you do not need permission to register.

To think through a listed challenge with your agent:

Read challenge issue #<N> from https://github.com/QuantumBFS/quantum.harness/issues/<N>.
Brainstorm with me: surface 3–5 distinct angles, name the riskiest assumption in each, and recommend one to start with.

If you need HPC resources, take the registration PR to the on-site help desk so the team can allocate an SCNet account.

// Work in the draft PR — submit by Thursday 20:00

Your committed work lives under tracks/<track>/solutions/ in the same draft pull request you opened on Monday. Push every commit there as your result develops. Generated data and figures land in tracks/<track>/results/, which stays out of git.

When the work is ready, run /challenge-report, then mark the draft pull request ready for review. That transition—not opening another PR—is your submission.

/challenge-report

After the report finishes, run gh pr ready. Finish this by Thursday 20:00. At that point the PR must be ready for review and updates stop because advisor review begins.

// Review & showcase

Use Day 4 afternoon to make your pull request easy to review: rerun your demo from a clean start and reread your README with fresh eyes. Your last chance to update the pull request is Thursday 20:00.

That evening, 20:00–22:00, the advisors review the pull requests online, track by track, and select 8 groups. Those groups present on the main stage on Friday morning, 15 minutes each. After the talks, the advisor panel jointly decides 4 Mac mini awards; a 5th goes to the best sharing session of the week.

// Getting help

• Zulip — harnessing-quantum.zulipchat.com: announcements, help-desk Q&A, and per-track threads. Your invite arrives with the acceptance email.
• Help desk (on site) — consultation, schedule guidance, and ad-hoc support, staffed by teachers and TAs.
• Expert office hours — scheduled during the week; see the Program.

// Learn more

Learning:

• The Complete Guide to Building Skills for Claude (PDF)
• Agentic Coding — MIT Open Course (Video)

Optional tools & skills: the Resources page lists MCP servers, command-line tools, and skill collections worth knowing.