an interactive walkthrough of a prompt-driven workflow for AI-assisted hackathon development. eight phases, each with a prompt you can copy and an exit condition you can check. built for small teams who want the discipline of a big one without the overhead.
front-load every decision, then let the agent execute.
most teams start a hackathon by opening an editor and hoping for the best. this workflow does the opposite. every decision, constraint, and plan goes into structured documents before a single line of code is written. the coding agent then executes against those documents, phase by phase, and a human reviews every transition point.
the result: less debugging, fewer merge conflicts, no "wait, what are we building again" at 3am.
the whole thing runs like a loop: plan, code, test, review, repeat. each phase has a prompt to use and an exit condition to check. nothing depends on memory or improvisation. a phase is done when its checkboxes are ticked, not when it roughly feels done.
at the start of a project, copy these into your repo and fill them out. the originals stay untouched. after a project, update the originals based on what you learned. that return loop is what makes the system get smarter.
0
eight phases. copy the prompt, check the exit, move on.
the whole flow, from idea to post-mortem. each phase names its tool, its file, the prompt to hand your agent, and the exit condition that says you're done.
upload your hackathon or project documentation and a filled idea.md, and have claude generate eight candidate ideas before you commit to one.
prompt · claude
Here is the official hackathon document [attached file] and my project context:
[paste filled idea.md]
Generate 8 ideas. For each idea:
- One-line concept
- Core problem it solves
- Who the user is
- The single most impressive thing a judge would see in the demo
- Realistic scope for [X] hours with [Y] team
- Biggest technical risk
After the list, recommend the top 2 based on my judging criteria and team strengths.
pick one idea and sharpen it. one-sentence pitch, what the demo moment looks like, and what gets cut if time runs out. record these decisions in section 6 of idea.md as you make them.
exit condition every checkbox in the idea.md ready check is ticked. all must be yes before moving.
1
phase 1 · specification
the single source of truth
tool claude · file spec.md
turn the sharpened idea into a complete spec. this file is the contract every line of code traces back to, so be ruthless about scope.
prompt · claude
Here is the spec template.
Based on everything we've discussed about this project — the idea, the users, the constraints, and the tech choices — fill this out completely and in detail. Remove any [CONDITIONAL] sections that don't apply to this project type. Never leave a field blank; if something is genuinely not applicable, write "N/A" with a one-line reason.
For the architecture, data flow, and acceptance criteria sections, be especially thorough — these are what the coding agent relies on most. Be ruthless about scope: if we didn't discuss it, it goes in Out of Scope, not in Must-Have.
This file is the single source of truth. Everything the coding agent builds will trace back to it.
exit condition every must-have feature has a testable ears-format acceptance criterion: when [trigger] the system shall [behave].
2
phase 2 · planning
one plan per person
tool claude · file plan.md (one per member)
have claude divide the project across the team, then generate a full plan per member. every acceptance criterion must be testable without waiting on someone else's work.
prompt · claude
Here is spec.md: [attach]
Here is plan.md template: [attach]
Generate plan.md for [role].
Use the uploaded plan.md template structure as template. Pick only the phases for their scope.
Each phase must list tasks specific to their role. Acceptance criteria must be
independently testable, no other member's work required first.
exit condition every member has a plan, and every acceptance criterion maps to a feature in spec.md.
3
phase 3 · repository setup
branches, context, and a generated rules file
tool git + opencode
create the repo.
create a branch per member. nobody pushes to main directly; the one exception is shared foundation work.
create the context folder in the repo root:
context/
context/
├── spec.md
└── plan-[name].md ← one per member
run opencode's /init to auto-generate AGENTS.md by analyzing the directory. don't write it by hand. it then applies your summarized habits in every session.
build shared foundation work (data models, folder structure, environment setup) on main before people branch off.
exit condition repo, branches, context folder, and root AGENTS.md exist; the shared foundation runs.
4
phase 4 · coding
every session starts the same way
tool opencode · files context folder
open the session by forcing the agent to read the context and confirm the plan before it writes a line of code.
session start prompt
Read these files before doing anything:
- context/spec.md
- context/plan.md
Skills active this session: ponytail [+ hallmark or impeccable by phase — see table]
Do not write any code yet. Confirm you have read them by summarizing:
1. What this project does
2. What your role is responsible for
3. What phase we are currently on
4. What the acceptance criteria are for this phase
phase type
skills to load
backend, logic, api
ponytail
new ui from scratch
ponytail, hallmark
ui audit and iteration
ponytail, impeccable
then run the phase in plan mode (press tab in opencode to switch plan ↔ build). replace n with whatever phase you're working on based on your plan.md file.
phase start prompt
Implement Phase [N]: [Phase Name] from my plan.
Rules:
- Finish every task in this phase before touching a future phase
- After every file you create or modify:
1. Run the test or type check for that file
2. Run the full suite
3. Report both results before touching the next file
- Do not proceed if either check fails
- Do not advance to Phase [N+1] until all of Phase [N] passes
- If something falls outside the spec or plan, stop and ask. Don't invent a fix
and if the agent loops on the same error twice or more, stop it before it burns more time.
anti-loop prompt
Stop fixing this. Don't modify any files.
Explain in plain language:
1. What the error actually is
2. Why your earlier fixes failed
3. Three ways to fix it and the trade-off of each
Then wait for my decision before touching anything.
exit condition every task in the phase is done, every test and type check passes, and nothing was built that isn't in the plan.
for sessions past 2 hours: re-read spec.md and your plan, confirm which phase and task is next, and keep going.
5
phase 5 · frontend audit
two audits, one table, one fix pass
tool opencode (hallmark + impeccable)
after any phase that produces UI, run both audits together, merge the findings into one table, fix everything in a single pass.
merged audit prompt
Run a Hallmark audit on the project, then run an Impeccable audit too.
Present a single merged table with:
- Issue found
- Which skill flagged it (Hallmark / Impeccable / Both)
- Recommended fix
If two skills call out the same issue, list it once as "Both".
Single-skill flags get that skill's name.
fix the "both" rows first, then judge the single-skill findings and fix everything in one pass.
exit condition all "both" rows fixed, single-skill findings judged, fixes applied in one pass.
6
phase 6 · phase transition review
never skip the checkpoint
tool you (human) + the agent
before every phase change, even under pressure, have the agent self-review its own work before you sign off.
transition review prompt
Before we move to Phase [N+1], review everything built in Phase [N].
Don't modify any files.
Report:
1. Tasks from the plan that are incomplete or missing
2. Hardcoded values that should be env vars
3. Unhandled error states
4. Tests that could false-pass
5. Anything built that wasn't in the plan
6. Whether every acceptance criterion in the spec is verifiably met
Is this phase genuinely done, or does something need fixing first?
exit condition the agent reports a clean pass and your manual check passes. sign off in phase-review.md; update the change log in spec.md if it changed.
7
phase 7 · merging and red team
a fresh eye on everything committed
tool opencode (new session)
once a plan is done, get a fresh session to red-team the branch as a senior engineer before it merges.
red-team review prompt
Read the following files completely before doing anything:
- context/spec.md
- context/plan-[name].md
Then scan the entire codebase — every file this member was responsible for.
Cross-reference what exists in the codebase against every task and acceptance
criterion in plan-[name].md. Then review as a senior engineer.
Report in this exact order:
1. COVERAGE — For every phase and task in plan-[name].md, state whether it is
fully implemented, partially implemented, or missing entirely. Be specific
about what is missing.
2. SPEC DRIFT — Does what was built match what spec.md required? List every
deviation, no matter how small.
3. BUGS & ERRORS — Obvious bugs, unhandled error states, missing edge cases,
hardcoded values that should be environment variables.
4. SECURITY — Any credentials, keys, or sensitive data exposed. Any input that
is not validated. Any endpoint that is not protected when it should be.
5. SCOPE CREEP — Anything built that does not appear in plan-[name].md or
spec.md. List the file and the specific addition.
6. MERGE RISK — Any file, function, or data structure likely to conflict with
other members' branches based on PLAN-SHARED conventions and overlapping
scope.
7. VERDICT — Is this branch ready to merge to main, or does something need
fixing first? List every blocking issue explicitly.
Be blunt. Do not soften findings. Do not mention anything positive unless
it is directly relevant to a finding.
fix anything flagged, then merge to main. for publishing: ask your coding agent how to publish the codebase to github and how to deploy, but do the actual publish and deploy steps manually. once live, expect issues to surface even if the local code was flawless, so keep a cleanup routine: open the browser console, copy the errors, and hand them to the agent to chase every time. you can also check your deployment provider's log for errors.
exit condition every blocking issue from the red team is fixed, merged to main, and deployed.
it catches ai mistakes cheaply, before they compound.
the agent didn't know what to build
fixed by spec.md and its ears-format criteria.
the agent built the wrong thing and nobody noticed
fixed by the phase-review prompt at every transition.
everyone's work didn't fit together
fixed by the per-member plans.
most ai coding failures come from exactly these three causes. this workflow doesn't eliminate the mistakes; it catches them before they become hours of repair cost.
scored against the field.
evaluated against 12 industry standards and scored on 9 dimensions — 8.34 / 10★★★★★★★★★★ overall.
just you? drop the branches, keep everything else.
work in one branch and use everything else the same. one person asks claude for spec and plan, runs the agent phase by phase with testing, audits the ui, deploys, and debugs from console logs. you become the review that the whole team flow would use.