Tutorial

Build a web app with the AI Unified Process

Book Library: from a blank canvas to a tested app.
Walk through the AI Unified Process end-to-end by chaining the skills from aiup-core and the layer plugins for Flyway, jOOQ, Spring Boot, and Vaadin in Claude Code. Each step produces a concrete artifact (a markdown spec, a diagram, an architecture document, a SQL script, Java code, or a test class) that the next step builds on.
Why a process?

Structure beats improvisation #

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.

The chain #

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:

vision.md → /requirements → /entity-model
  → /stack → /use-case-diagram
/architecture-decision  # whenever the team makes a technology or structure decision

Use case chain, for every use case:

/next → /use-case-spec UC-001 → /spec-review UC-001
  → /use-case-implement UC-001 → /use-case-test UC-001
  → /use-case-coverage UC-001 → /acceptance-protocol
/open-questions  # whenever a gap needs a person's answer

At the end of a release, /release-notes writes the business release notes from the use cases that reached Done.

/release-notes

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.

Prerequisites #

What you need before running the chain:

  • Java 25 – the project ships an mvnw wrapper
  • Docker – or Testcontainers Cloud for the PostgreSQL container
  • Claude Code – with aiup-core and the layer plugins for the Book Library stack installed (see below). The same skills run in Codex CLI, Cursor, GitHub Copilot, Gemini CLI, and OpenCode; see other AI coding tools
  • The starter project – cloned fresh from the book-library repository

The Book Library combines Flyway, jOOQ, Spring Boot, and Vaadin Flow, so it needs one plugin per layer next to aiup-core:

/plugin marketplace add ai-unified-process/marketplace
/plugin install aiup-core
/plugin install aiup-flyway
/plugin install aiup-jooq
/plugin install aiup-spring-boot
/plugin install aiup-vaadin

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.

Step by step

The nine steps to a working app #

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.

  1. Review the Vision #

    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.

    Tip. Be explicit about non-goals. Calling out what is out of scope (no payments, no reservations, no self service sign-up) tells the AI not to scaffold features you do not need yet.
    Pre-seeded security. The starter ships Spring Security, an app_user table (identity only), a login view, and two seeded accounts (librarian / librarian, alice / alice). The tutorial therefore does not cover authentication; your generated views just need @RolesAllowed("MEMBER") for the member-only views (borrowing, returning, my loans: a librarian has no member row and does not borrow, as docs/architecture.md records), @RolesAllowed("LIBRARIAN") for the librarian-only ones, and @RolesAllowed({"MEMBER", "LIBRARIAN"}) for the catalog search both use.
  2. Generate the Requirements Catalog #

    /requirements

    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:

    • Functional requirements as user stories (As a member, I want to search the catalog so that I can find a book without asking the librarian).
    • Non-functional requirements (performance, usability, maintainability).
    • Constraints (the tech stack from the README, the non-goals from the vision, ...).

    Review the catalog before continuing; this is your last chance to course-correct cheaply. Every later step compounds on this list.

  3. Build the Entity Model #

    /entity-model

    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:

    • Book (id, title, author, isbn, copies)
    • Member (id, user_id, name, email) – a library member, linked 1:1 to an existing app_user row.
    • Loan (id, book_id, member_id, borrowed_at, returned_at)

    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.

  4. Record the Architecture #

    /stack

    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 Layers table migration with /flyway-schema, persistence with /jooq-persistence, service with /spring-service, UI with /vaadin-flow-ui, the test skill of each layer that has one, and the E2E layer with /vaadin-e2e-test
    • The Integration layer table where a use case is tested, per entry layer: one offered through the UI in the UI, whose Browserless tests run in process against the real database, and one offered through the service alone, such as a scheduled job, in the service
    • The E2E scope Use cases and test cases: every use case offered through the UI also gets a browser test; with Test cases only, browser tests are written for the journeys alone
    • The module layout and commands where the code of each layer lives, and how to build and test it

    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 one question. The skill detects the layers but not how many browser tests you want, so it asks for the E2E scope. Answer Use cases and test cases: step 8 then writes the browser test that step 9 runs. With Test cases only, /use-case-test writes no UC001SearchCatalogIT, and you ask for it with /use-case-test UC-001 e2e.
    Entry layers. Every Book Library use case is offered through the UI, so the specifications you write in step 6 need no Layers line. In an app that also has a REST API, a use case offered through only one of them says so with a line such as Layers: UI.
  5. Draw the Use Case Diagram #

    /use-case-diagram

    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 catalog
    UC-002Borrow book
    UC-003Return book
    UC-004View active loans (Librarian)
    UC-005Manage catalog (Librarian)
    UC-006Manage members (Librarian)
    UC-007View my loans

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

  6. Write the First Use Case Specification #

    /use-case-spec UC-001

    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.

    Be concrete. A step like "the system shows the books" is not enough; "the system shows the books with the columns Title, Author, ISBN, and Available Copies, sorted by title ascending" is. Name what the actor sees, not the widget: /spec-review flags a Grid or a button colour as the wrong level.
    Review before you implement. Run /spec-review UC-001 once the spec reads well; name the use case, because without an id the review covers the whole project and reports every use case of the diagram that has no specification yet as an error. It checks that every reference resolves and that the use case agrees with the requirements, the entity model, and the other use cases, and it flags steps that can fail without an alternative flow. It only reports; fix the findings with /use-case-spec and review again. Once the review is clean, set the Status line to Approved; on a Draft or Reviewed use case /use-case-implement asks before it builds.
  7. Implement the Use Case #

    /use-case-implement UC-001

    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:

    • /flyway-schema writes a versioned Flyway script under src/main/resources/db/migration/. The starter already contains V001__create_app_user.sql, so it adds a new version (e.g. V002__create_member_book_loan.sql) with the tables, primary and foreign keys (including member.user_id → app_user.id), and the NOT NULL, UNIQUE, and CHECK constraints from the entity model.
    • /jooq-persistence writes a jOOQ-based repository (BookRepository) against the classes jOOQ generates from the migration, with the results projected into Java records.
    • /spring-service writes the service with the transaction boundaries and the business rules of the use case.
    • /vaadin-flow-ui writes the Vaadin view (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.

  8. Write the Use Case Tests #

    /use-case-test UC-001

    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.

  9. Run the End-to-End Test #

    ./mvnw verify

    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.

Wrap up

What you have at the end #

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.

Add the next use case #

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.

Change an existing use case #

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.

Where to go next #

  • Run /use-case-coverage UC-001 to audit what you just built against its specification: it lists which scenario steps, alternative flows, and business rules have code and tests behind them, and which are still open. Every NFR and constraint on the Requirements line of the use case is a unit too: a limit a test can observe, such as a response time, stays open until a test asserts it, and only then does the audit suggest Tested. Link only the NFRs the use case has to prove; one that holds for the whole system, such as sign-in, needs no link. The audit only suggests the next status: Implemented once every unit has code, Tested once every unit has a test and the suite passes. You set the Status line yourself, as you did with Approved; no skill changes it, and /requirements then moves the statuses of the requirements the use case links.
  • Run the chain again for UC-002 Borrow book; it will reuse Book and Member and add rows to Loan. The seeded account alice has no member row yet, so its test data links a member of its own; to borrow as alice in the running app, give her one in the test data or with UC-006 Manage members.
  • Continue with UC-003 Return book to close the lifecycle.
  • Add the librarian-facing UC-004 View active loans for the operational view.
  • Before UC-005 Manage catalog, decide what removing a book means once it has been borrowed: its loans keep pointing at it, and the loan history has to stay. Either only a book that was never borrowed can be removed, or a book is withdrawn from the catalog instead of deleted; record the choice with /requirements and /entity-model before you run /use-case-spec UC-005.
  • Once a few use cases exist, run /test-case UC-001 UC-002 UC-003 to write a TC-001 journey that chains them into one end-to-end scenario, then automate it with /test-case-implement TC-001, which runs /vaadin-e2e-test with the journey, and audit it with /test-case-coverage TC-001.
  • Read Layer plugins to see how the layers combine, for example to add a REST API next to the UI.
Talk to us

Want a hands-on walkthrough? #

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.