Task API Lab Starter

This repository is a small practice project for learning the codex-multiagent-development workflow on a real but low-risk codebase.

The lab goal is to build a simple FastAPI service with:

• GET /health
• GET /tasks
• POST /tasks

Use this repository together with CODEX_MULTIAGENT_LAB.md. If you are running a team workshop, also use FACILITATOR_GUIDE.md.

Use Python 3.11 through 3.13 for this lab. Python 3.14 is not recommended for the current pinned FastAPI and Pydantic stack.

What Is Already Here

• The multi-agent workflow files from codex-multiagent-development
• A minimal Python project file
• A bootable FastAPI app with GET /health
• A passing smoke test for the health endpoint
• docs/tech.md for research notes

The application is intentionally incomplete. The team should use Codex to:

1. create a spec
2. plan the task groups
3. implement the remaining API behavior
4. review it
5. QA it
6. document it

The lab work still to be done is:

• GET /tasks
• POST /tasks
• task input validation
• tests for the task endpoints
• review, security review, QA, and documentation artifacts for the new work

This repository also includes a seeded lab spec at .codex/specs/2026-07-14-task-api-lab/ if you want to start from a prepared workshop plan instead of asking Codex to draft one from scratch.

Why This Starter Is Slightly Prebuilt

This repo starts from a known-good baseline so the workshop does not get derailed by setup issues. The team should learn the multi-agent workflow on top of a runnable app, not spend the first half debugging environment problems.

The included Makefile prefers python3.13, then python3.12, then python3.11, and only falls back to python3 if needed. For Windows, use the included setup.ps1 / run.ps1 or setup.bat / run.bat helpers instead of make.

Quick Start

macOS / Linux:

make setup
source .venv/bin/activate
make test
make run

Windows PowerShell:

.\setup.ps1
.\.venv\Scripts\Activate.ps1
.\.venv\Scripts\pytest.exe
.\run.ps1

Windows Command Prompt:

setup.bat
.\.venv\Scripts\activate.bat
.\.venv\Scripts\pytest.exe
run.bat

In another terminal:

macOS / Linux:

curl http://127.0.0.1:8000/health

Windows PowerShell:

curl.exe http://127.0.0.1:8000/health

Windows PowerShell alternative:

Invoke-RestMethod http://127.0.0.1:8000/health

Expected response:

{"status":"ok"}

Then start Codex:

codex

Then prompt Codex with:

Read AGENTS.md and inspect this repository. Then use prompts/scope.md to create a spec for adding GET /tasks and POST /tasks to this FastAPI service. Keep GET /health unchanged. Include tests, QA, and documentation.

Or, if you want to start from the seeded lab spec:

Read AGENTS.md and inspect this repository. Then review the seeded spec in .codex/specs/2026-07-14-task-api-lab/ and execute it to completion.

Expected Starting State

Before the lab begins:

• the starter test command should pass
• the starter run command should start the API successfully
• GET /health should return {"status": "ok"}

That gives the team a stable base before the real feature work begins.

Optional curl Examples For The Finished Lab

These will not work until the team completes the lab feature:

curl http://127.0.0.1:8000/tasks
curl -X POST http://127.0.0.1:8000/tasks \
  -H 'content-type: application/json' \
  -d '{"title":"Write workshop notes"}'
curl http://127.0.0.1:8000/tasks

One reasonable finished behavior would be:

[]

then:

{"id":1,"title":"Write workshop notes","completed":false}

then:

[{"id":1,"title":"Write workshop notes","completed":false}]

Starter Structure

task-api-lab-starter/
├── AGENTS.md
├── agents/
├── app/
│   ├── __init__.py
│   └── main.py
├── docs/
│   └── tech.md
├── Makefile
├── prompts/
├── run.bat
├── run.ps1
├── scripts/
├── setup.bat
├── setup.ps1
├── skills/
├── steering/
├── tests/
│   └── test_api.py
├── pyproject.toml
└── README.md