Project Day
Building a Website from Markdown Specs
Codex AI conversation lab
Using gstack skills
Website Project Built Through Conversation with Codex
Instead of asking Codex straight away to "make a website,"
this lab has you complete the proper 6-step project process: from idea conversation to Markdown specs, code generation, testing and history tracking.
How student projects work
- Finish one phase at a time. Each step's output becomes the input for the next.
- Don't accept Codex's results as-is. Separate facts, assumptions, decisions and open questions, and record the team's reasons.
- Check each card's detailed guide. It gives the phase goal, steps, required outputs, real-world considerations and a done checklist.
- A checkable process matters more than a finished product. You must be able to explain why you designed it that way with docs and test evidence.
🧰 Running each phase with gstack
gstack is an open-source collection of AI coding skills released by Garry Tan. You can call roles like idea review, design review, code review, QA and retros with slash commands, and it works in Codex CLI too. The purple box on each phase card below lists the gstack skills to use at that step.
Think → Plan → Build → Review → Test → Ship → Reflect
# Install inside the project folder (for Codex)
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git .agents/skills/gstack
cd .agents/skills/gstack && ./setup --host codex
- Install needs Git and Bun (v1.0 or later). Windows also needs Node.js.
- Treat gstack skill results the same as Codex results. Don't accept them as-is; record the team's reasons in the Markdown docs and CONVERSATION.md.
- Record the gstack commands you used and a summary of results in CONVERSATION.md every time.
🚀 Project Day: 6 Key Phases (Tasks)
Phase 1
Idea Definition
State the site's purpose, user roles (student/teacher) and key actions clearly in 3 sentences or fewer.
Key outputA project definition showing the problem, users and key actions
Key criterionCan every team member picture the same product?
🧰 Using gstack · Think
- /office-hours Check the idea's assumptions with 6 key questions, restate whose problem you solve, and make a design doc.
💡 Don't use the resulting design doc as-is; compress it into a 3-sentence "problem·user·key action" definition. This becomes the input for Phase 2.
See detailed lab guide
Phase 2
Markdown Specs
Write the doc pack: SITE_SPEC, USER_FLOWS, DATA_MODEL, IMPLEMENTATION_PLAN, CONVERSATION.
Key output5 Markdown planning docs that connect with no contradictions
Key criterionCan a developer start the first build without extra questions?
🧰 Using gstack · Plan
- /plan-ceo-review Check the scope. Since it must be done in a day, use Hold Scope or Reduction mode to keep only essential features.
- /plan-eng-review Settle data flow, exceptions and the test plan, and reflect them in DATA_MODEL·IMPLEMENTATION_PLAN.
- /autoplan (optional) Run CEO·design·engineering reviews at once and get only the items a person must decide.
💡 Record in CONVERSATION.md which of the 5 docs each review decision and held item went into.
Spec summary guide
Phase 3
Building the Website with Codex
Have Codex read the docs first, then ask it to generate responsive website code under the website/ folder.
Key outputA runnable website and build/check records
Key criterionAre the docs' done criteria really reflected in the code?
🧰 Using gstack · Build · Review
- /freeze Limit edits to the
website/ folder so planning docs don't change by mistake.
- /design-consultation (optional) Set simple design rules like colors and typography first.
- /review After building, review the code to find bugs that could blow up in real use.
💡 Keep the build request order as before: "read docs first → generate code". Use gstack before and after it to limit scope and review.
Example build request prompt
Phase 4
Feature and Scenario Testing
Test student QR generation/scan check-in, the teacher dashboard's live status, and exception handling.
Key outputNormal/exception scenario test results and a defect list
Key criterionDoes it handle failures safely, not just success screens?
🧰 Using gstack · Test
- /qa-only Test the QR check-in and dashboard scenarios in a real browser and get only a defect list, without changing code.
- /investigate For defects with an unclear cause, investigate the root cause before fixing.
- /qa After checking the defect list, hand over fixing, rechecking and creating regression tests.
💡 QA continues the test plan made with /plan-eng-review in Phase 2. Organize normal and exception results in a table.
See test scenarios
Phase 5
Improving Site and Docs Together
Apply change requests to the planning docs first (Spec-First), then improve the site through Codex.
Key outputChange spec, impact analysis, fixed code and regression tests
Key criterionDid you prove the change didn't break existing features?
🧰 Using gstack · Plan · Review · Test
- /plan-eng-review Review the planning docs again with the change applied and analyze the impact (Spec-First).
- /review Review the changed code and check its effect on existing features.
- /qa Run regression tests again to prove existing features didn't break.
💡 Keep the order: fix docs → review → fix code → regression test. Fixing code first isn't Spec-First.
See improvement guide
Phase 6
Work History and Retro Presentation
Record prompts and decision history in CONVERSATION.md and give a 5-minute final presentation.
Key outputA reproducible work record and a 5-minute project talk
Key criterionDo you explain why you made decisions, more than what you built?
🧰 Using gstack · Reflect
- /document-release Update the planning docs and README to match the final code so docs and site agree.
- /retro From the work history, sum up what went well, what fell short and what to improve next, and use it for your slides.
💡 In the talk, explain which gstack skills you used in each phase, which results you accepted or rejected, and why.
Retro and presentation guide