ACE AI SW Startup Training · Project Day
PROJECT DAY · SIX PHASE GUIDE

Project Day Detailed Lab Guide

A guide to running the Markdown-spec website build like a real project. For each phase, check "what you do," "why it's needed" and "what output to leave," and move to the next step after meeting the done criteria.

🧰 Check the gstack tips at the bottom of each phase for the gstack skills to use and their order.

Original Task specs

The original Task requirements are unchanged. Do the Tasks below as the base assignment, and use the 6-phase detailed guide that follows to improve the quality of your outputs and project process.

Task 01. Idea Definition and 3-Sentence Statement (Phase 1)

Write the project purpose and user roles to give Codex in the 3-sentence format below.

1. Site purpose: a system where students pick their card and check in with a QR code, and the teacher sees it in real time.
2. Student role: search name ➔ click ID card ➔ scan QR on mobile ➔ click check-in button
3. Teacher role: attendance monitoring dashboard ➔ check live updates ➔ filter present/absent

Task 02. Write the 5 Markdown Spec Docs (Phase 2)

Ask Codex to create these 5 files and review the done criteria.

  • SITE_SPEC.md: screens, features, design, done/acceptance criteria
  • USER_FLOWS.md: step-by-step paths for each user
  • DATA_MODEL.md: student and attendance data model
  • IMPLEMENTATION_PLAN.md: build order
  • CONVERSATION.md: conversation record

Task 03. Codex Code Generation and Testing (Phase 3 & 4)

Have Codex read the specs, then ask it to create the website/ folder.

Prompt: "Read the spec docs first, then finish the student QR check-in page and teacher monitoring page under the website/ folder."

Task 04. Requirement Change and Presentation Prep (Phase 5 & 6)

Change the planning docs first, then revise the code, organize the conversation history in CONVERSATION.md and present.

🧰 Getting ready to use gstack

What is gstack?

gstack is an open-source collection of AI coding skills released by Garry Tan. With one command you can call roles like product review (office hours), planning/design review, code review, browser QA, doc cleanup and retros, and it works in Codex CLI too. In this class we use gstack not as a replacement for talking with Codex, but as a reviewer that checks each phase's output.

# Install inside the project folder (for Codex · needs Git, Bun v1.0+ / Windows also needs Node.js)
git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git .agents/skills/gstack
cd .agents/skills/gstack && ./setup --host codex
Phasegstack stageMain skillsLinked outputs
1. IdeaThink/office-hoursPROJECT_BRIEF.md
2. SpecsPlan/plan-ceo-review /plan-eng-review /autoplan5 spec docs, test plan
3. BuildBuild · Review/freeze /design-consultation /reviewwebsite/, README.md, build log
4. TestingTest/qa-only /investigate /qaTEST_PLAN.md, BUG_LOG.md
5. ChangePlan · Review · Test/plan-eng-review /review /qaCHANGE_REQUEST.md, regression results
6. Retro talkReflect/document-release /retroREADME.md, RETROSPECTIVE.md

✅ Shared rule: don't accept gstack results as-is either. Record the command you ran, key findings, and the team's accept/change/reject and reasons in CONVERSATION.md every time.

Detailed 6-Phase Project Guide

PHASE 1 · DISCOVER

Idea Definition: defining the problem before building

In this phase the team agrees, before picturing screens and features, on whose pain you'll solve and how much you'll build this time.

What you do in this phase

Imagine user interviews to narrow down the problem, users, situation of use, key actions and success conditions.

Required outputs

PROJECT_BRIEF.md3-sentence definitionScope tableSuccess metrics

Most important criterion

Teammates and Codex must picture the same user and be able to explain even "what we won't build."

Student steps

  1. Observe the problem. Write 3 pain points each that students and teachers have with checking attendance.
  2. Pick the key users. Don't try to satisfy everyone; set each of the student's and teacher's most important goals in one sentence.
  3. Connect the key actions. Write a start-action-result flow from entering class to confirming check-in.
  4. Split the scope. Sort features into Must, Should (if possible) and Out (not this time).
  5. Put numbers on success. E.g. students check in within 30 seconds and the teacher finds absent students within 10 seconds.

Real-project considerations

  • Decide how to handle proxy check-in (sharing the QR with a friend) and duplicate check-ins.
  • Collect only essential personal data like name, student number, location or IP, and set the purpose and how long it's kept.
  • Write down situations outside the ideal flow in advance, like unstable internet, camera permission denied and students with the same name.
  • Cut scope based on time and team skills so it can be built in one day.

Done Checklist

  • User, problem and key action are each clear in one sentence.
  • Must features and excluded features are separated.
  • There are at least 2 measures to check success.
  • Every team member agreed on the same 3-sentence definition.

Codex tips

Critically review our team's attendance service idea. Don't add features right away; give me, as questions, ① vague wording ② unchecked assumptions ③ the riskiest exceptions ④ scope to exclude from a one-day project. After I answer, organize only what we agreed on into a PROJECT_BRIEF.md structure.

🧰 gstack tips

OrderskillWhen · whatWhere results go
1/office-hoursRun right after drafting the 3-sentence definition. Answer 6 key questions to check whether the problem is real, the key users and the narrowest starting scope.Problem·user·scope in PROJECT_BRIEF.md
2/plan-ceo-review (optional)Check scope in Reduction mode so only Must features buildable in a day remain.Scope table (Must / Should / Out)
/office-hours
We want to build, in one day, an attendance service where students check in with QR and the teacher sees it in real time.
Ask us questions based on the 3-sentence definition below, and point out risky assumptions like proxy and duplicate check-ins.
[paste 3-sentence definition]

⚠️ The design doc from /office-hours can be long and broad. Compress only what the team agreed on into PROJECT_BRIEF.md and the 3-sentence definition, and keep dropped suggestions under Out with reasons.

PHASE 2 · DEFINE

Writing specs: turning ideas into buildable promises

Split the idea into screens, user flows, data, build order and done criteria to make one shared standard for the team and Codex.

What you do in this phase

Detail requirement IDs, flows, data fields and test criteria so the 5 Markdown docs connect to each other.

Required outputs

SITE_SPEC.mdUSER_FLOWS.mdDATA_MODEL.mdIMPLEMENTATION_PLAN.mdCONVERSATION.md

Most important criterion

Instead of words like "nice," "fast" or "real-time," use done criteria anyone can check.

Student steps

  1. Write SITE_SPEC. List screens, functional requirement IDs, design principles, responsive conditions and done criteria.
  2. Write USER_FLOWS. Separate the normal flows of students and teachers from exception flows like QR expired, duplicate check-in and no search results.
  3. Write DATA_MODEL. Define fields, types, required-ness, relationships and status values for Student, ClassSession and Attendance.
  4. Write IMPLEMENTATION_PLAN. Split small tasks in the order base screens → data → core features → exception handling → tests.
  5. Check for contradictions between docs. Use a requirement trace table to confirm each screen feature exists in both the flows and data.

Real-project considerations

  • "Checked in" shown in the UI must match the Attendance status actually saved.
  • Don't use the student name as a unique key; use a separate studentId.
  • State the date/time zone, the late cutoff, QR expiry time and the teacher's permission to edit manually.
  • Make a glossary so docs don't use different names for the same idea.

Done Checklist

  • Every core feature has a requirement ID and acceptance criteria.
  • There is a normal flow and 3+ exception flows.
  • Data field types, required-ness and relationships are defined.
  • The build order and each task's done condition are clear.
See the original 5-doc spec summary guide →

Codex tips

Write the 5 planning docs based on PROJECT_BRIEF.md. Ask the questions you need first, and mark anything unanswered as [Undecided]. Give each feature an ID in FR-001 format with Given-When-Then acceptance criteria, and at the end review contradictions and gaps between the five docs in a separate table.

🧰 gstack tips

OrderskillWhen · whatWhere results go
1/plan-ceo-reviewAfter drafting SITE_SPEC, run in Hold Scope mode to check the scope didn't grow and no core value is missing.SITE_SPEC.md feature list·done criteria
2/plan-eng-reviewRun after all 5 docs are written. Settle data flow, exceptions, hidden assumptions and the test plan.DATA_MODEL.md, USER_FLOWS.md exception flows, IMPLEMENTATION_PLAN.md test items
3/plan-design-review (optional)Score the screen design item by item and turn vague design wording into concrete criteria.SITE_SPEC.md design principles
4/autoplan (optional)Run the reviews above at once and get only the items a person must decide. Recommended for teams short on time.List of [Undecided] items
/plan-eng-review
Review SITE_SPEC, USER_FLOWS, DATA_MODEL and IMPLEMENTATION_PLAN.
Especially check studentId uniqueness, QR expiry time, duplicate check-ins and save failure handling,
and make a test plan for each requirement ID (FR-xxx). List contradictions between docs in a separate table.

⚠️ The test plan from /plan-eng-review carries over to /qa in Phase 4. Link it to requirement IDs and save it in IMPLEMENTATION_PLAN.md or TEST_PLAN.md.

PHASE 3 · BUILD

Building with Codex: turning docs into a working product

Don't let Codex make product decisions on its own; review the work plan and change scope against the planning docs and build in small units.

What you do in this phase

Set up the project structure and build the student check-in screen and teacher dashboard by priority.

Required outputs

website/README.mdrunning screensbuild log

Most important criterion

More important than lots of code: the spec's acceptance criteria actually work and others can run it.

Student steps

  1. Have Codex read the docs first. Have it summarize the requirements it understood, undecided items and build order, and get team approval.
  2. Fix the runtime environment. Write the tech stack, folder structure, run commands, supported browsers and data storage method in the README.
  3. Build the core flow first. Finish the vertical flow first: choose student → check QR → save check-in → update teacher status.
  4. Run after every small change. Check the browser and console each time you build a feature before moving on.
  5. Compare docs and build. Mark in IMPLEMENTATION_PLAN where each requirement ID is built and how to check it.

Real-project considerations

  • Don't put API keys or passwords directly in code or push them to the repository.
  • Before adding a new library, check it's really needed and teammates can install it in the same environment.
  • When AI tries to change existing files a lot, review the diff and impact first.
  • Clearly separate temporary demo data from real saved data.
  • For the mobile QR screen, consider touch areas, loading and camera permission denial.

Done Checklist

  • Another teammate can run it with just the README commands.
  • The student and teacher core flows are connected and working.
  • There are no unresolved errors in the browser console.
  • No features were added that aren't in the spec.

Codex tips

Read the 5 planning docs first and summarize requirement IDs, undecided items and build order. Don't write code yet; suggest which files to create or change and why. After I check the plan, build under website/ starting from the smallest runnable unit, and tell me how to run it and which acceptance criteria to check at each step.

🧰 gstack tips

OrderskillWhen · whatWhere results go
1/freezeBefore starting the build, limit edits to the website/ folder so planning docs don't change by mistake. (/guard also adds warnings for risky commands)Record the allowed edit scope in the build log
2/design-consultation (optional)If there are no design rules like colors, typography and spacing, set a simple design system first.SITE_SPEC.md design principles, README.md
3Codex buildUse the original "Codex tips" prompt: read docs → approve plan → build in small units.website/, IMPLEMENTATION_PLAN.md
4/reviewRun after the core flow works. Finds bugs that run but could blow up in real use, and builds that differ from the spec.Build log, fix commits
/review
Review the code in website/ against the requirement IDs and acceptance criteria in SITE_SPEC.md.
Look first for features not in the spec, and unhandled check-in save failures and double clicks.
Tell me separately what you auto-fixed and what needs a decision.

⚠️ Check the diff of anything /review auto-fixed too. If a fix adds a feature not in the spec, revert it and record why.

PHASE 4 · VERIFY

Feature and scenario testing: turning "it seems to work" into evidence

Check that the product behaves predictably not only in normal use but also with mistakes, duplicates, expiry, permission denial and different screen sizes.

What you do in this phase

Run test scenarios for each requirement and record actual results, evidence, defects and recheck results.

Required outputs

TEST_PLAN.mdtest results tableerror screenshotsBUG_LOG.md

Most important criterion

More important than the number of passing tests: failures were reproduced and rechecked after fixing.

Student steps

  1. Turn acceptance criteria into tests. Make items for precondition, action, expected result, actual result and evidence.
  2. Check the normal scenario. Run the whole flow of student check-in and teacher status update from start to finish.
  3. Run exception scenarios. Try empty search, same names, double clicks, expired QR, network failure and permission denial.
  4. Check different environments. Check mobile, tablet and desktop, keyboard use, long names and lots of student data.
  5. Fix defects and regression test. Record the cause and fix, and rerun related existing features too.

Minimum test scenarios

  • After a normal check-in, the dashboard count and student status match right away.
  • Even if the same student submits twice, only one counts.
  • Expired QR codes and QR codes for the wrong class are rejected with a reason.
  • With no search results or same names, the wrong student isn't selected.
  • On save failure, no success message is shown and how to retry is explained.
  • Core features work on a 375px mobile screen with no horizontal scrolling.

Done Checklist

  • Test results are linked to each requirement ID.
  • Normal, exception, responsive and accessibility tests were done.
  • Failed items have reproduction steps and evidence.
  • Fixed defects were tested again and confirmed passing.

Codex tips

Make a test table based on the acceptance criteria in the planning docs. Don't write only the normal path; include duplicate check-in, expired QR, same names, network errors, mobile layout and keyboard access scenarios. For each test, write the precondition, steps, expected result and how to collect evidence, and don't mark anything not yet run as PASS.

🧰 gstack tips

OrderskillWhen · whatWhere results go
1/qa-onlyFirst run in report mode without fixing code. Run the student check-in and teacher dashboard scenarios in a real browser and get a defect list and screen evidence.Test results table, BUG_LOG.md, error screenshots
2/investigateFor defects with an unclear cause, investigate the root cause before fixing. If it isn't solved after 3 tries, stop and let the team decide.BUG_LOG.md cause analysis
3/qaRun after the team settles what to fix. Fixes defects, rechecks and creates regression tests.BUG_LOG.md fix/recheck results
4/benchmark (optional)Measure the loading speed of the mobile QR screen and use it to check success measures like "check in within 30 seconds."Success measure results
/qa-only
Run website/ and test the TEST_PLAN.md scenarios in the browser.
Be sure to include normal check-in, duplicate submit, expired QR, same names, save failure and a 375px mobile screen,
don't change code, and leave reproduction steps and a screenshot for each defect.

⚠️ In /qa-only and /qa results, don't record anything not actually run as PASS. Link each defect to a requirement ID.

PHASE 5 · ITERATE

Improving site and docs together: applying changes safely

Don't put new requirements straight into code; first check the impact on specs, user flows, data and tests, then build.

What you do in this phase

Analyze the change request, update the planning docs first, and improve with minimal code changes and regression tests.

Required outputs

CHANGE_REQUEST.mdImpact analysis tableDoc diffCode diffRegression results

Most important criterion

Even after adding a new feature, the docs and code must describe the same product, and existing core flows must keep working.

Student steps

  1. Rewrite the change request in one sentence. Confirm the requester, reason, expected result and done criteria.
  2. Analyze the impact. Make a table of the impact on screens, flows, data model, permissions, tests and schedule.
  3. Change the docs first. Update related requirement IDs and versions, and have the team approve the before/after differences.
  4. Build with minimal scope. Ask Codex to show the files to change and the expected diff first, then change the code.
  5. Regression test. Recheck the new acceptance criteria and all affected existing scenarios.

Real-project considerations

  • Agree on whether adding "real-time status" means refresh, polling or WebSocket.
  • When data fields change, think about migration so existing data and screens don't break.
  • Prefer a small diff over rebuilding all the code for one request.
  • If a change request goes beyond the project's time and goals, send it to the next version's backlog instead of building it.
  • If the requester's words conflict with real user value, ask and record the reason for the decision.

Done Checklist

  • The reason for the change and done criteria are documented.
  • You can explain which docs and code files are affected.
  • The doc change was approved before the code change.
  • New tests and related regression tests are all recorded.

Codex tips

Don't build the change request right away; analyze its impact on SITE_SPEC, USER_FLOWS, DATA_MODEL, IMPLEMENTATION_PLAN and existing tests. Show in a table the doc items and code files that need changing, the risk of breaking existing features, and regression tests to add. After I approve, change the docs first and build with a minimal diff.

🧰 gstack tips

OrderskillWhen · whatWhere results go
1/plan-eng-reviewReview CHANGE_REQUEST.md together with the changed planning docs to check the impact on data, flows and tests. Run before touching code (Spec-First).Impact analysis table, doc diff
2/plan-ceo-review (optional)Check in Hold Scope mode whether the change request goes beyond the project goal. If it does, send it to the next version's backlog.CHANGE_REQUEST.md decision reasons
3/reviewRun after building with a minimal diff to find effects on existing features and missing handling.Code diff, build log
4/qaTest the new acceptance criteria and all affected existing scenarios again.Regression test results
/plan-eng-review
Analyze the impact of the "teacher dashboard real-time status" change in CHANGE_REQUEST.md
on SITE_SPEC, USER_FLOWS, DATA_MODEL, IMPLEMENTATION_PLAN and existing tests.
Suggest whether polling or WebSocket fits a one-day project, with reasons, and list the regression tests to add in a table.

⚠️ Keep the order: fix docs → /plan-eng-review → team approval → fix code → /review → /qa. If you fixed code first, it's not Spec-First.

PHASE 6 · SHARE

Work history·retro·presentation: turning project decisions into shareable knowledge

Don't just demo the finished screens; organize the problem, decisions, failures, improvements and evidence so they can be understood in 5 minutes.

What you do in this phase

Organize the Codex conversations and team decisions, and present how to reproduce it, the demo, limits and next steps.

Required outputs

CONVERSATION.mdREADME.md5-min slidesDEMO_SCRIPT.mdRETROSPECTIVE.md

Most important criterion

More than flashy screens, show the reasons behind the team's choices and how you reviewed AI's suggestions.

Student steps

  1. Edit the conversation history. Don't copy every chat; keep questions, key suggestions, and the team's accept/change/reject and reasons.
  2. Finish how to reproduce it. Check install, run, test, demo accounts and known limits in the README.
  3. Build a 5-minute talk flow. Problem 40 sec, user and solution 50 sec, demo 2 min, decisions and checks 1 min, retro and next steps 30 sec.
  4. Prepare a demo ready for failure. Set reset data, demo order, backup screenshots and presenter roles.
  5. Write a team retro. Write specifically what went well, what was hard, AI errors, what you'd change and the next experiment.

Must show in the talk

  • The real user problem you're solving and the project scope
  • A core demo from student check-in to teacher confirmation
  • The hardest decision and the reason for your choice
  • A case where you changed or rejected a Codex suggestion instead of using it as-is
  • Test evidence and limits not yet solved
  • The one thing to improve first in the next version

Done Checklist

  • We really rehearsed a talk under 5 minutes.
  • We have backup material we can explain even without a network.
  • Every team member can explain their contribution and decisions.
  • How to run it, test results and limits are saved in the repository.

Codex tips

Make a 5-minute talk draft based on CONVERSATION.md and the project docs. Structure it as problem-user-key decisions-demo-evidence-limits-next steps, not a feature list. Separate cases where the team accepted, changed or rejected AI suggestions, and don't add results without evidence.

🧰 gstack tips

OrderskillWhen · whatWhere results go
1/document-releaseUpdate README.md and the planning docs to match the final code so docs and site describe the same product.README.md, final 5 planning docs
2/retroFrom the work history, sum up what went well, what was hard and what to improve next.RETROSPECTIVE.md, retro slide for the talk
3Tidy CONVERSATION.mdSum up the gstack skills used in each phase, key findings and the team's accept/change/reject cases, and use them in the talk's "decisions·checks" part.CONVERSATION.md, 5-min slides
/retro
Write a retro based on this Project Day's work history and CONVERSATION.md.
Separate what went well, what was hard, cases where we rejected or changed AI (Codex·gstack) suggestions, and the one thing to improve first in the next version.
Don't add results without evidence.

⚠️ In the talk, show at least one case of "which gstack skill pointed out what, and why the team accepted or rejected it."