Imported from sabarinathSubramani/order-sdd-demo (AGENTS.md). Install upstream with npx skills add sabarinathSubramani/order-sdd-demo. Copyright stays with the author.

AGENTS.md

Instructions for AI coding agents working in this repository.

What this repo is

A demo of spec-driven development (SDD): every non-trivial change is specified before it's built. Start here:

• SETUP.md — pre-session setup guide for workshop participants (tools to install, repo access, verifying the build).
• product.md — what the product is, who it's for, what's in/out of scope.
• architecture.md — how the system is built, tech stack, conventions.
• specs/README.md — how new features get specified (requirements → design → plan) before implementation.

Read product.md and architecture.md before making non-trivial changes. They're short — read them in full, don't skim.

The workflow

New feature work follows these steps, each backed by a skill:

1. create-requirements → specs/<feature-slug>/requirements.md — what & why, in functional/non-functional requirement form.
2. create-design → specs/<feature-slug>/design.md — data model, API contract, code impact. Requires requirements.md to exist first.
3. create-plan → specs/<feature-slug>/plan.md — ordered, checkable implementation tasks. Requires requirements.md and design.md to exist first. 3b. create-test-plan → specs/<feature-slug>/test-plan.md — scope, black-box functional/non-functional test cases, and regression impact. Also only requires requirements.md and design.md, so it can run before/after/alongside create-plan.
4. implement → works plan.md's task list, checking off each task as it's completed and verified. Requires plan.md to exist first.

Only after plan.md exists should code be written, and it should follow that plan — run implement rather than writing code ad hoc. If asked to "implement feature X" and no spec exists yet for it, propose running create-requirements first rather than jumping straight to code — small/obvious fixes (typos, bugs with an unambiguous correct behavior) don't need this ceremony, feature work does.

If you materially change the system's structure or the product's scope while implementing, update architecture.md / product.md in the same piece of work — don't let them drift.

Project layout

AGENTS.md          this file
product.md          product vision & scope
architecture.md      system architecture & conventions
specs/               per-feature requirements/design/plan (spec-driven workflow)
order-service/        the Spring Boot service (see order-service/README.md)
  docs/               original pre-SDD baseline docs (historical, not the active workflow)
e2e-tests/            black-box HTTP test automation against a running order-service
  README.md           how to run the suite
  CONVENTIONS.md       how new black-box test cases get written (naming, structure, patterns)

Building and testing order-service

Always use the Maven wrapper, never a system-installed mvn:

cd order-service
./mvnw clean package -DskipTests   # build
./mvnw test                        # unit tests only
./mvnw failsafe:integration-test failsafe:verify   # integration tests only
./mvnw verify                      # full suite (unit + integration) — run before considering work done
./mvnw spring-boot:run             # run locally on :8080

Swagger UI at http://localhost:8080/swagger-ui.html once running.

Conventions

Full conventions are in architecture.md. The short version: RFC 9457 ProblemDetail for errors, state transitions enforced in the service layer via the domain enum, append-only audit history, DTOs never expose entities directly.