AI agents are great at producing code, but without structure they tend to improvise. The AI Unified Process (AIUP) gives the AI a predefined chain of artifacts to produce, each one narrowing the design space for the next.
By the time you reach /use-case-implement, the AI already has a vision, a use case spec, an entity model, and a stack file that names the skill for every layer to anchor its output, so the code it writes is grounded in your domain, not in a generic template.
Start chain, once per project:
Use case chain, for every use case:
At the end of a release, /release-notes writes the business release notes from the use cases that reached Done.
Start a new Claude Code session for every skill run: each skill reads what it needs from the files in docs/, and a long session that compacts its context several times loses detail and gets slow.
What you need before running the chain:
The Book Library combines Flyway, jOOQ, Spring Boot, and Vaadin Flow, so it needs one plugin per layer next to aiup-core:
Still on the combined aiup-vaadin-jooq plugin? It is deprecated and will be removed with aiup-core 4.0.0. Layer plugins explains the switch and maps the old commands to the new ones.
Apart from the vision you review first and the test run at the end, each step is one slash command you run inside Claude Code. Run them in order; every step builds on the artifacts of the previous one.
The vision is the only artifact you write by hand. Everything else is generated from it.
For this tutorial the vision is already prepared at docs/vision.md; open it and read it before continuing. It is the source of truth for every step that follows. Keep it short; one page is plenty: the problem, the solution, the target users, the goals, and the non-goals.
This skill reads docs/vision.md, asks up to five clarifying questions where the vision leaves a decision open, and produces a structured requirements catalog in docs/requirements.md and the domain terms in docs/glossary.md. The catalog includes:
Review the catalog before continuing; this is your last chance to course-correct cheaply. Every later step compounds on this list.
From the requirements the skill identifies the domain entities and writes docs/entity_model.md: a Mermaid ER diagram of the entities, their relationships, and cardinalities, plus one attribute table per entity with data types, lengths or precision, and validation rules (required fields, lengths, uniqueness).
For the Book Library you should expect roughly:
The AppUser entity (id, username, password_hash, role, created_at) is part of the starter and does not need to appear in the entity model; treat it as an external boundary.
Before the first line of code, the skill records which layer skill builds and tests each technical layer. It detects Flyway, jOOQ, Spring Boot, and Vaadin from the pom.xml and the source tree of the starter and writes the stack file to docs/architecture/stack.md. The stack file holds:
The starter already ships a docs/architecture.md with its package conventions; the skill reads it as input and leaves it where it is, so the stack file sits next to the team's own architecture document. You run this step once per project, and again only when a layer changes. Review the file like any other artifact: the implement and test steps read it.
The skill renders a PlantUML use case diagram from the requirements at docs/use_cases.puml. It shows the two actors (Member, Librarian) and the use cases they participate in:
UC-001Search catalogUC-002Borrow bookUC-003Return bookUC-004View active loans (Librarian)UC-005Manage catalog (Librarian)UC-006Manage members (Librarian)UC-007View my loansUse the diagram to confirm coverage: every requirement should land on at least one use case, and every use case should trace back to a requirement.
Pick the use case that unblocks the others to go first. For the Book Library that is UC-001 Search catalog; it has no preconditions, gives the member something to do the moment they land on the page, and produces the data structures that UC-002 needs.
The skill writes docs/use_cases/UC-001-search-catalog.md with the primary and secondary actors, the trigger, the requirements it links, preconditions, the main success scenario as numbered steps, alternative flows, success and failure postconditions, and business rules (BR-001, …). It starts with Status: Draft.
This is where the chain pays off. The skill reads the use case spec, the requirements it links, the entity model, and the stack file, asks about any gaps in the specification in one round, then runs the layer skills bottom-up. Each layer hands the types and methods it created over to the next:
BookRepository) against the classes jOOQ generates from the migration, with the results projected into Java records.SearchCatalogView), wired to MainLayout and calling the service directly.The skill runs the build in between, so the jOOQ classes are current before the repository is written. It writes no tests. Run the app via TestApplication from your IDE, or with ./mvnw spring-boot:test-run on the command line, sign in as alice / alice, and open the catalog. It is still empty: no use case adds books yet, and the production migrations hold no demo data, so you see the empty-state message the spec names. The books arrive with the test data of the next step.
The skill tests the use case once, in the integration layer. With Vaadin Flow that is the UI, so /vaadin-flow-ui-test writes UC001SearchCatalogTest under src/test/java, extending the starter's AbstractBrowserlessTest, a SpringBrowserlessTest with the Testcontainers database. It drives the view without a browser, but against the real service and database: navigate to the view, look up the search field and the grid, type a query, assert the grid shows the expected rows, and cover every alternative flow and business rule from the spec. Each test method carries @UseCase(id = "UC-001"), and the test data goes into a repeatable migration, src/test/resources/db/migration/R__uc001_search_catalog.sql, which Flyway picks up next to the production migrations without any profile or @TestPropertySource. Once that test data fills the catalog, the empty-catalog flow cannot be arranged with it, so its test method is annotated @Transactional, deletes the books inside the test transaction, and checks the empty-catalog message; the rollback restores the test data.
With the E2E scope Use cases and test cases, the same run then ends with the E2E layer and writes the end-to-end test of the next step as well.
Because these tests run through every layer below, the repository and the service get no tests of their own. Run them with ./mvnw test. They are fast, under a second per test, so they form the inner feedback loop while you iterate on the view.
Now start TestApplication again (or ./mvnw spring-boot:test-run): it runs on the test classpath and so loads the same test data from src/test/resources/db/migration, so you can type a query, see the grid filter, and see the results sorted as the spec requires.
With the E2E scope Use cases and test cases, the /use-case-test run of step 8 has already written the browser test: /vaadin-e2e-test produced a Playwright + Drama Finder test, UC001SearchCatalogIT, extending AbstractBasePlaywrightIT. It boots the full Spring Boot app on a random port and drives a real browser through the use case: start the app with a fresh database, sign in through the login view, open the catalog page, type a search query, and assert the visible rows match what the spec requires. The empty-catalog flow has no browser test: the running app has one data set, and the Browserless test already covers it.
./mvnw verify runs the Browserless tests and then the integration tests. This is your outer feedback loop: slower than the browserless tests, but it proves that the JavaScript, CSS, routing, and database layers all line up. To write or reconcile only the browser test, for example after a change to the view, run /use-case-test UC-001 e2e; with the E2E scope Test cases only, that is how you ask for a use case browser test at all.
After running the full chain for UC-001 you have a documented vision and requirements catalog, an entity model and use case diagram covering the whole app, plus a stack file of the layers, and for the first use case a spec, a migration, an implementation across four layers, Browserless tests in the integration layer, and an end-to-end test.
To add a new use case, you only need steps 6, 7, 8, 9; the requirements, entity model, diagram, and stack file cover the whole app, so they do not need to be redone. When a use case needs new tables or columns, /use-case-implement adds a new V003__... migration as its first layer.
A new feature, a change request, or a bug all end up in the same place: edit the specification, then re-run steps 7, 8, and 9. /use-case-implement finds the existing view, service, and repository and changes only what the spec now requires, and /use-case-test updates the existing test classes rather than adding second ones. A change that needs a new column gets a new migration; never edit one that has already been applied.
Workshops and tailored rollouts of the AI Unified Process for your team and stack. Book a call to talk through how the AI Unified Process fits your project.