TODO Generator Prompt: Full Stack Type Projects (Spring + React)

gistfile1.txt

I will give you a PRD. Based on that PRD, generate a full-stack, OpenAPI-first development roadmap optimized for Cursor. Follow *all* rules below strictly.

## SHORT INTRO (for the AI)

* You may mark TODOs as done later on command (the user may ask you to toggle checkboxes). For now, every checkbox must be unchecked `[ ]`.
* The output must be extremely clean, Cursor-friendly, and immediately executable in Cursor (actual file creation/editing commands or runnable commands).
* All phrases and commands must be actionable, short, and imperative.

## TOP RULES (global)

1. **Always output a multi-phase roadmap**: PHASE 0, PHASE 1, PHASE 2, … (include as many phases as needed to implement the PRD; include mandatory phases listed later).
2. **Inside each phase, output a flat TODO list** using unchecked checkboxes `[ ]`.
3. **Every TODO item must include:**

   * One-line short description (imperative).
   * Acceptance criteria as bullet points (each `- ` on its own line). **Acceptance criteria must always include that relevant tests were created and executed and passed** (e.g., “Relevant unit/integration/E2E tests exist and all tests pass”).
4. **Every task must be Cursor-executable** (create/edit files, run commands). Avoid vague high-level tasks.
5. **All commits required by the roadmap must be real `git` commits** and executed via commands in tasks.

## INITIAL INTERACTION (MANDATORY at the very beginning of the roadmap)

* Before PHASE 0 tasks, include an initial small block of tasks that:

  * [ ] Initialize a local git repository (`git init`) and create a first commit.

    * Acceptance criteria:

      * `git init` executed and initial commit created.
      * `git status` is clean.
      * Relevant README or initial files exist.
      * Tests (if any yet) run and pass.
  * [ ] Prompt the user for an optional **git remote URL** and, if provided, set it (`git remote add origin <URL>`).

    * Acceptance criteria:

      * If user provided URL, `git remote -v` lists `origin` with that URL.
      * If user did not provide URL, repo remains local and `git remote -v` is empty.
  * [ ] Prompt the user for an optional **Docker registry URL** (this is optional; local registries often have no auth). **Do not perform `docker login`.**

    * Acceptance criteria:

      * If user provided a registry URL, the variable `REGISTRY_URL` is set in project config files and used in subsequent docker image tags.
      * If user did not provide a registry URL, images will be built locally and tagged accordingly.
  * Note: none of these initial prompts are mandatory from the user—make the tasks conditional in the roadmap (i.e., include tasks that branch: “if provided, do X; else, do Y”).

## BACKEND TECHNOLOGY REQUIREMENTS (MANDATORY)

* Stack:

  * **Kotlin + Spring Boot**
  * Build tool: **Gradle (Kotlin DSL)**
  * API layer: controllers must implement OpenAPI-generated interfaces
  * Data layer: **Spring Data JPA**
  * **Database migrations: Liquibase, located inside the backend project**
  * Migrations must run automatically at startup and in Testcontainers-based tests

## OPENAPI-FIRST REQUIREMENTS — PHASE 0 MUST BE: OpenAPI Specification Setup

PHASE 0 must include tasks to:

* [ ] Create `api/openapi.yaml` (shared single OpenAPI file).

  * Acceptance criteria:

    * `api/openapi.yaml` exists and defines all required endpoints from the PRD.
    * OpenAPI linter (e.g., `spectral`) run and reports zero critical errors.
    * Tests created to validate the OpenAPI file schema (if applicable) and they pass.
* [ ] Validate the OpenAPI file with an OpenAPI linter (e.g., Spectral).

  * Acceptance criteria:

    * Linter run command is included and exits 0.
    * Linter output contains no ERROR or FAIL items.
* [ ] Set up OpenAPI Generator scripts for:

  * Kotlin Spring **server stubs** (interfaces for controllers)
  * Kotlin **DTOs/models**
  * Frontend **TypeScript client**
  * Provide regeneration commands for backend and frontend (e.g., Gradle task, npm script).
  * Acceptance criteria:

    * Generator scripts present (e.g., `scripts/gen-backend.sh`, `scripts/gen-frontend.sh` or Gradle tasks).
    * Running the regeneration commands produces generated code without errors.
    * Backend controllers are wired to implement generated interfaces (task for wiring included).
    * Frontend app uses only the generated TypeScript client (task enforces usage).
    * Tests (unit) created to assert controllers and client types compile; tests run and pass.
* [ ] Add CI-free enforcement tasks (local checks) that validate generated vs checked-in specs (but no CI/CD jobs).

  * Acceptance criteria:

    * Local command exists to compare `api/openapi.yaml` and generated artifacts and returns non-zero on mismatch.
    * Tests for this check exist and pass.

## PHASE STRUCTURE (for every phase)

Every phase must have three labeled sections in this exact order:

### BACKEND

* Provide a flat list of Cursor-executable tasks (file creation, edits, commands).
* Each task must end with acceptance criteria bullets and include test creation & run verification.

### FRONTEND

* Flat list of Cursor-executable tasks (file creation, edits, commands).
* Use React + TypeScript for frontend.
* Frontend must call only the generated TypeScript client.
* Each task must include acceptance criteria bullets and test creation & run verification.

### TESTING TASKS FOR THIS PHASE

* Backend unit tests (JUnit 5) using Mockito or Mockk.
* Backend integration tests using Testcontainers:

  * Launch PostgreSQL Testcontainer.
  * Run Liquibase migrations automatically inside the Testcontainer environment.
  * Perform real HTTP calls via WebTestClient or RestAssured.
  * Validate DB state after HTTP operations.
* Frontend unit tests with Vitest or Jest + React Testing Library.
* All tests must be runnable with a single command for the phase and must pass.
* Acceptance criteria must explicitly state tests were created, executed, and passed.

### PHASE-END COMMIT

* At the end of *every* phase include:

  * [ ] Commit changes for this phase (`git add -A && git commit -m "phase <N>: <short summary>"`).

    * Acceptance criteria:

      * Commit exists and `git status` is clean.
      * All tests for the phase pass.

## BACKEND TESTING REQUIREMENTS (detailed)

* Unit tests:

  * JUnit 5
  * Mockito or Mockk
* Integration tests:

  * Use **Testcontainers PostgreSQL**
  * Use Spring Boot Test
  * Ensure Liquibase migrations execute when Testcontainers boots the DB
  * Use real HTTP calls (no controller mocking) and verify DB state after operations
* Each integration task must include exact commands to run Testcontainers-based tests.

## FRONTEND TESTING REQUIREMENTS (detailed)

* Use **Vitest** or **Jest**.
* Use **React Testing Library**.
* Include tasks to run tests and verify passing.

## E2E TESTING REQUIREMENTS

* Use **Playwright** or **Cypress**.
* Must run against a `docker-compose` environment (see Docker Compose phase below).
* Provide CLI commands to run E2E tests.
* Acceptance criteria: E2E tests created, run against docker-compose environment, all pass.

## DOCKER COMPOSE REQUIREMENTS (one full phase must create docker-compose.yml)

* Create `docker-compose.yml` with services:

  * backend (Kotlin + Spring Boot)
  * frontend
  * PostgreSQL
* Tasks must:

  * Build images (using `REGISTRY_URL` prefix if user provided registry; else local tags).
  * Start containers.
  * Run E2E tests against running services.
  * Tear down containers.
  * Verify environment consistency (e.g., `docker-compose ps`, healthchecks).
* Acceptance criteria:

  * `docker-compose up --build -d` starts all services.
  * Healthchecks show services healthy.
  * E2E test command runs and passes.
  * `docker-compose down` cleans up containers and networks.
  * Commit created after successful run (phase-end commit).

## MANDATORY ADDITIONAL PHASES (include each)

* **Refactoring + Performance Tuning**

  * Include tasks to profile backend endpoints, optimize queries, add indices, and re-run integration tests.
  * Acceptance criteria must include test coverage and performance metric improvement (benchmarks or simplified timing).
* **Documentation Phase**

  * API documentation (auto-generated from OpenAPI)
  * README (project setup, run, test, regenerate)
  * Architecture/UML diagram (e.g., PlantUML file)
  * Developer onboarding guide (local dev steps including git remote and registry instructions)
  * Acceptance criteria: generated API docs accessible locally, README covers steps, diagrams render, tests mentioned run and pass.
* **Static Analysis Phase**

  * **Only** include the rule: *(No CI/CD tasks.)*
  * Do **not** include the removed items: Linting, Formatting, Type-checking, Security scanning, Dependency audit — these are explicitly excluded for now.
  * Acceptance criteria: only the “No CI/CD tasks” requirement is present and acknowledged in the phase.

## FINAL RULES / FORMATTING

* All checkboxes must be `[ ]` (unchecked).
* The output must be extremely clean and Cursor-friendly.
* Use imperative, short task descriptions.
* Where commands are described, provide exact commands (e.g., `./gradlew build`, `pnpm test`, `docker-compose up --build -d`, `git commit -m "..."`).
* Every task’s acceptance criteria must explicitly state that:

  * relevant tests were added,
  * tests were executed,
  * tests passed.
* At the very start of the generated roadmap, prompt the user (via tasks) for optional `git remote URL` and optional `Docker registry URL`. **Do not perform `docker login`.**
* Ensure the OpenAPI-first rules are strictly enforced (backend controllers must implement generated interfaces; frontend must call only the generated TypeScript client).
* The roadmap must include PHASE 0 — OpenAPI Spec Setup — followed by implementation and the required phases above.
* Do **not** add CI/CD tasks.

---

When you (the AI) have finished producing the roadmap from the PRD, end the message with: **“Ready. Please provide the PRD.”**

**Ready. Please provide the PRD.**