vending-machine-api

Imported from mabuzax/vending-machine (vending-machine-api/AGENTS.md). Install upstream with npx skills add mabuzax/vending-machine --skill vending-machine-api. Copyright stays with the author.

AGENTS.md — vending-machine-api

Guidance for any agent working in vending-machine-api, the API folder of the vending-machine repository — Kiro discovers this file at the root of the workspace folder and always includes it.

This project is built with Kiro's spec-driven workflow. The rules an agent must obey live in .kiro/steering/, exactly where Kiro would put them. This file is the loader: read the steering files it links before doing anything in this folder. They are not background reading — they are the constraints.

What this folder is

The Spring Boot back end of a vending machine simulation, built as a technical assessment (docs/business/technical-assignment-1.md). The Angular front end is the ../vending-machine-ui folder of the same repository. The only coupling between them is the REST contract: /v3/api-docs on the running API, with a copy committed at docs/api/openapi.yaml.

The one rule that overrides everything

.kiro/steering/scope.md is the only authority on what gets built.

Before proposing, designing or writing anything — a requirement, a design element, a task, a class, a method, a field — name the REQ-n.m it satisfies and the scope id (C-, E-, D-, B-) behind it. If you cannot name one, you do not build it: say OUT OF SCOPE — not in scope.md, note the idea in one line for the README's Not built list, and stop. Do not ask permission to add it; the default is no.

This covers methods and fields, not only features. The realistic creep here is a findByCategory, a page/size parameter, a description on Product, a ChangeStrategyFactory "for future strategies", a @Cacheable, a GET /api/v1/state because the state model is interesting. Each is one line and each is defensible alone; together they are how a POC becomes unreviewable.

Scope changes only by a commit to scope.md, never by a chat message.

Simplicity comes first

The brief scores "simplicity and understandability of the implementation". Write every plan, every class and every comment so that a junior developer can read it without help. If you are choosing between clever and plain, choose plain.

In code

• Use plain for loops and if statements. Do not use streams, method references (::), Optional chains, UnaryOperator, Function or other functional interfaces to save lines.
• Repeating a few simple lines is better than one clever helper that hides what happens.
• Give variables full names: denomination, not d.
• Do not write code that nothing calls. A method needs a caller now, or a named task that will call it.
• Do not add a class, interface, factory or layer "for later". Add it when a requirement needs it.
• Do not add something the framework or compiler already does. Use Spring Boot configuration before writing a class.
• Use the simplest Spring feature that works: Spring Data repositories, @ConfigurationProperties, @RestControllerAdvice. No custom frameworks.

In comments

• The comments rule is .kiro/steering/coding-standards.md §10: a comment states a reason, constraint or workaround the code cannot show; nothing else.

In designs

• Start with the simplest design that meets the requirement. Only add more if a requirement forces it, and say which one.
• Record what you chose not to build, one line each, under Deliberately not designed in design.md.

In commit messages

• Say what changed and why, in plain sentences. A few lines is usually enough.

Before you finish any task, ask: could a junior read this without asking me a question? If not, simplify it.

Steering files

Read in this order. The first four are the ones that change what you write; the rest are checked at review time. Rules tagged [DEFAULT] were proposed by the team rather than set by the brief; to override one, edit the file, remove the tag and commit with chore(steering): ....

fileMatch files apply only when you are working on a matching path; always files apply to every request.

Specs

Spec-driven work lives in .kiro/specs/<spec-name>/ as requirements.md → design.md → tasks.md, each approved before the next is written. No phase is approved while bash scripts/scope-guard.sh exits non-zero.

delivery-pipeline is a Quick Spec because Dockerfiles and a CI workflow have no contentious design.

Guards — the anti-creep system

Five layers, each catching what the one before missed: the scope rule, review against the allow-lists, the compiler and Checkstyle, the two guard scripts, and CI. The scripts are the mechanical ones; they run as Kiro hooks (.kiro/hooks/), before a merge, and in CI. A guard is not trusted until a planted violation has been watched to fail.

Both take --check <file>... and --stdin (hook mode). With no arguments scope-guard.sh checks every spec file under .kiro/specs, while no-secrets.sh checks only the staged files; no-secrets.sh --all scans every tracked file.

The hooks use Kiro's hook schema ({"version":"v1","hooks":[{name, trigger, matcher, action, timeout, enabled}]}); a command action receives session context as JSON on STDIN, which is what --stdin reads. .kiro/settings/mcp.json configures the AWS documentation MCP server for the Kiro session; it is a development-environment setting, not part of the product.

To run the same checks by hand, run the two scripts directly (see Commands below). scripts/dev/local-check.sh is a local helper, not in the repository: scripts/dev/ is gitignored, so a clone does not have it. A green guard you have not tried to break is not evidence.

These are the only two guard scripts: the compiler refuses javax.*, Lombok, WebSecurityConfigurerAdapter and JUnit 4 on Boot 4.1 / Java 21, Checkstyle fails verify on System.out, printStackTrace and double money, and the endpoint and dependency lists are kept by review against api-conventions.md and tech.md.

Key documents

Commands

./mvnw -B verify                 # unit (surefire) + feature (failsafe *IT) + checkstyle + jacoco report
                                 # always verify, never test: test skips every *IT class
./mvnw spring-boot:run           # start on :8080
./mvnw javadoc:javadoc           # fails on error; CI runs it
curl localhost:8080/actuator/health
# Swagger UI: http://localhost:8080/swagger-ui.html
bash scripts/scope-guard.sh        # all specs; --check <file> for one
bash scripts/no-secrets.sh --all

./run.sh --api (or .\run.ps1 --api) starts this API on its own; --docker uses the compose file. The whole system (this service plus the UI) is started by run.sh in ../vending-machine-ui.

Working agreements

• One task in tasks.md = one branch = one --no-ff merge; commits cite [task N] [REQ-x.y] (.kiro/steering/git-workflow.md).
• A task is not done until ./mvnw -B verify is green, including the *IT feature tests. feature-test-after-task.json runs it on PostTaskExecution — which reports, it does not block, because only PromptSubmit, PreToolUse and PreTaskExecution can. The Definition of Done is the gate; the hook is what makes the evidence appear without being asked for.
• Do not touch files outside a task's Files: list.
• A change that touches more than one area, or a file other features use, runs the regression set in its task's _Affects: line and the full suite before it is merged (.kiro/steering/testing.md).
• Do not check a Definition of Done box you have not verified.
• Run every guard in scripts/ before proposing a merge; CI is the backstop, not the gate.
• Never trust a green guard you have not tried to break.