Classroom walkthrough: build a small issue tracker

A classroom walkthrough from the AI-SDLC template to a small issue-tracker API, with prompts, artifacts and review checkpoints.

Start from the template, not from BAIssue. This exercise borrows the issue-tracker domain from BAIssue, but students build their own implementation. The outputs below are targets and illustrative snapshots, not evidence of a completed run.

Return to the AI-SDLC method.

GitHub-stack classroom variant

This walkthrough is the concrete GitHub-stack quick start for teaching: students use the template repository, GitHub Codespaces, VS Code, GitHub Copilot and the included GitHub Actions workflows. The AI-SDLC method itself is tool-neutral; use the generic Getting Started guidance when working with another repository, agent or development environment.

Learning goal and scope

Build a small API that creates and lists issues and exposes FastAPI's interactive Swagger UI. Explain how one requirement becomes a specification, a design, tests, code and delivery evidence. Use Python, FastAPI, SQLite, pytest and Docker for this exercise; these are exercise choices, not requirements for every template project.

In scope	Out of scope
Create an issue with a nonblank title	Authentication and real personal data
Assign a server-generated ID and status open	Assignments, comments, deletion and search
List stored issues	A custom UI or production-ready service
Interactive Swagger UI at /docs	Authentication and real personal data
Unit, integration and container E2E checks	Automatic production deployment

Work in pairs: one person drives Copilot, the other reviews the artifacts. Swap roles after DESIGN. The instructor chooses the deployment platform before the delivery exercise.

Prepare the repository

1. Create a repository using ai-sdlc-template.
2. Open it in GitHub Codespaces.
3. The devcontainer automatically runs bash scripts/setup-skills.sh 1 and bash scripts/setup-python.sh when the Codespace is created. This prepares .agents/skills, creates .venv and installs the Python profile dependencies.
4. Check whether the phase skills appear in Copilot. If the automatic setup did not run or discovery fails, run bash scripts/setup-skills.sh 1 and bash scripts/setup-python.sh at the repository root, or explicitly reference the canonical skills/.../SKILL.md path in the prompts below.
5. Start with PHASE: 0 and STATUS: ready in docs/TASKS.md.

The setup exposes skills/ through an agent-specific path and prepares the Python environment. It does not generate application code. The FastAPI launch configuration is a starting convention; after BOOTSTRAP, update its module path if the project uses a different entry point.

For non-interactive setup, pass the selection directly, for example bash scripts/setup-skills.sh 1. The claude selection creates a missing CLAUDE.md containing @AGENTS.md; an existing file is preserved. Shared instructions and skills are not modified.

Execute one phase at a time. Review its result before explicitly selecting the next phase. Never copy an example status of done without checking the actual output.

Walk through the six phases

The examples use short, human-written prompts. A configured agent should load the repository instructions and discover the applicable skill automatically. Explicit instruction or skill paths are only needed as a fallback when discovery is unavailable. Execute only the selected phase and review its output before selecting the next.

1

0. BOOTSTRAP — establish a working project context

Prompt

Execute phase 0 of AI-SDLC.

Set up a small teaching issue-tracker API with Python, FastAPI, SQLite, pytest and Docker.

Expected artifact: project-specific PROJECT.md, dependency manifest and minimal compatible structure. Record commands that match the files actually created; distinguish planned test commands from checks that can already run.

Review checkpoint: can a teammate install the dependencies, identify the application entry point and explain the intended boundaries? A skeleton is not a completed feature.

State: after verified completion, PHASE: 0, STATUS: done. Select phase 1 explicitly; its initial status is ready.

2

1. SPECIFY — make acceptance observable

Prompt

Execute phase 1 of AI-SDLC.

Specify creating and listing issues: POST /issues returns 201 with a generated ID and status open, blank titles return 422, GET /issues lists issues by ascending ID, data persists in SQLite, and Swagger UI is available at /docs.
No authentication or other features.

Expected artifact: docs/specs/UC-001-CREATE-LIST-ISSUES.md, linked as the active UC in TASKS.md.

Acceptance ID	Given / when	Observable result
AC-1	Submit title Broken projector	201; generated ID; title; status open
AC-2	Submit whitespace-only title	422; no issue stored
AC-3	Create two valid issues, then list	200; both appear in ascending ID order
AC-4	Restart the application with the same database file	Previously stored issues remain
AC-5	Open /docs	Swagger UI is returned with status 200

These IDs are a teaching aid inside the existing Acceptance section, not a new required artifact.

Review checkpoint: can a reviewer derive a test from every row without guessing? Confirm missing or wrong-type title behavior before implementation if it is relevant to the exercise.

3

2. DESIGN — assign responsibilities

Prompt

Execute phase 2 of AI-SDLC.

Expected artifact: a concise architecture description in PROJECT.md. A candidate design has this source dependency direction:

The adapter implements the port; runtime wiring connects them. Do not read the diagram as a required sequence of network calls.

Optional ADR exercise: compare direct persistence in routes with an application port. Record the decision as Proposed, ask the human to decide, then update the current architecture and only a relevant durable rule in AGENTS.md. If the boundary was already decided, reuse it rather than manufacturing another ADR.

Review checkpoint: can domain tests run without FastAPI or SQLite? Is the rationale recorded once?

4

3. DEVELOP — connect acceptance to tests and code

Prompt

Execute phase 3 of AI-SDLC.

Expected artifacts: tests and implementation for the active UC. Reference AC-1 to AC-4 in test names or descriptions where useful.

Boundary	Example check
Domain	Whitespace-only title is invalid
API + persistence	Invalid input returns 422 without inserting a row
Application + repository	Created issues can be listed in the required order
Persistent storage	Data survives a fresh connection/application instance

Review checkpoint: did the test fail for the intended missing behavior, rather than a broken test setup? Inspect assertions, not just the green result.

A snapshot during execution might be:

PHASE: 3
STATUS: in-progress

After verified completion, keep phase 3 and set done. A missing decision or unavailable dependency can instead require blocked with a reason.

5

4. VALIDATE — check the deliverable independently

Prompt

Execute phase 4 of AI-SDLC.

Expected evidence: actual commands/results, CI run link when available, container identity and an E2E create/list/restart check against an isolated test database. Choose and document the database volume for the restart test.

The template's green structure check is not a passing application test suite. Its release workflow is initially a source-release baseline, not a container build/test/publication pipeline. Complete the missing project checks; report unmet release-readiness requirements instead of declaring success.

Review checkpoint: can the other student reproduce the checks? Does the tested artifact correspond to the recorded source? If required validation cannot be completed, record blocked and the reason; do not invent evidence.

6

5. DEPLOY — distinguish preparation from delivery

Prompt

Execute phase 5 of AI-SDLC.

Expected artifact: the reviewed deployment workflow and its operational context. The template's enabled CD path expects deployment and smoke-test scripts; implement them for the agreed target before enabling it.

Review checkpoint: a verified workflow can complete the current DEPLOY skill, but does not demonstrate a live deployment. Record Delivery: prepared; not executed in the evidence note where that is the actual result. If the instructor authorizes a real run, also record target, artifact, workflow run and smoke-test outcome.

If no target has been selected, record the missing decision as a blocker. Never use an invented target or real credentials in the teaching material.

Fast Track: set the Swagger UI path

After the first API walkthrough, make a small configuration-only change to the developer-facing Swagger UI endpoint. The application API and architecture remain unchanged.

Use AI-SDLC Fast Track to move the FastAPI Swagger UI from /docs to /api/docs.
Keep the issue API, architecture and dependencies unchanged.

The acceptance criterion is: /api/docs returns the Swagger UI with status 200, while the issue API behavior remains unchanged. This is suitable as a configuration-only Fast Track example; a new custom browser UI would be a regular second use case.

Submission and reflection

Submit one repository/PR link, not a duplicate document pack:

• PROJECT.md with reproducible commands and current architecture;
• the UC with acceptance criteria and meaningful test references;
• TASKS.md with honest phase/status and a short evidence note;
• tests, implementation and relevant CI results;
• ADR only if a consequential decision was made;
• delivery evidence, or a clear statement of what remains unexecuted.

Discussion questions: Which agent proposal did you reject? Which acceptance criterion exposed a defect? Could a teammate continue from the recorded state? What changed between a green local test and a validated deliverable?

The exercise illustrates the method. It does not establish empirical productivity or quality gains.