> For the complete documentation index, see [llms.txt](https://docs.aisl.science/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aisl.science/learning-and-resources/ai-sdlc/classroom-walkthrough.md).

# 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.

{% hint style="info" %}
**Start from the template, not from BAIssue.** This exercise borrows the issue-tracker domain from [BAIssue](https://github.com/AIaSDev/BAIssue), but students build their own implementation. The outputs below are targets and illustrative snapshots, not evidence of a completed run.
{% endhint %}

[Return to the AI-SDLC method](https://docs.aisl.science/learning-and-resources/ai-sdlc).

## 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](https://docs.aisl.science/learning-and-resources/ai-sdlc#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](https://github.com/AIaSDev/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.

{% hint style="warning" %}
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.
{% endhint %}

## 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.

{% stepper %}
{% step %}

### 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`.
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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:

```mermaid
flowchart BT
    API["FastAPI routes"] --> APP["Application operations"]
    DB["SQLite adapter"] --> PORT["Repository port"]
    APP --> PORT
    APP --> DOMAIN["Issue and title validation"]
```

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?
{% endstep %}

{% step %}

### 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.
{% endstep %}

{% step %}

### 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.

{% hint style="warning" %}
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.
{% endhint %}

**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.
{% endstep %}

{% step %}

### 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.
{% endstep %}
{% endstepper %}

## 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.aisl.science/learning-and-resources/ai-sdlc/classroom-walkthrough.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.