Spec-first hello agent

This guide builds a "hello world" greeting agent with spec-driven development. The agent greets each user in a new language every turn and tracks the languages it has already used in the session.

Spec-driven development runs in two modes, and you can build this agent either way. Choose your style below.

Choose your style

  • À la carte mode (the default) — you run each specification command yourself, one at a time. Faster and lighter; you own the rigor. Follow Build À la carte.

  • Enforced mode — you define "done" as machine-checkable exit conditions and the assistant drives the build until they are met. A cleaner, auditable result. Follow Build in Enforced mode.

New installs start in À la carte mode. To use Enforced, switch first:

/akka:mode enforced

Prerequisites

  • Complete Set up your AI harness — install the Akka Specify Plugin and run /akka:setup.

  • An OpenAI API key. The application code calls OpenAI, independently of your AI coding assistant. Set OPENAI_API_KEY in your environment before starting your assistant; on Mac/Linux use export so child processes inherit it.

Build in Enforced mode

Enforced mode is opt-in; switch to it first (new installs default to À la carte):

/akka:mode enforced

In Enforced mode you drive the whole build through one re-entrant command, /akka:specify, instead of running clarify, plan, tasks, and implement individually — /akka:specify sequences those phases for you.

Specify the feature

Prompt 1. Feature specification

/akka:specify greeter agent - greet each user in a new language every turn, remembering which languages were used per session

The engine infers a definition of done from your intent and Akka’s own surfaces, and shows it grouped by tier — Product, Project, and Process. Some conditions are guaranteed by the platform, some are the machine’s to build, some need a receipt from an external system, and a few need a decision from you. Prohibitions — the conditions that must never become true — print in a separate NEVER section:

DEFINITION OF DONE — 17 conditions (17 applicable)    mode: enforced · policy: none (library defaults)
🔒 locked   ✓ green   ✗ red   ○ open   — not applicable   [akka] platform-guaranteed
──────────────────────────────────────────────────────────────────────────────
PRODUCT
  operability             ✓  AKKA-OBS-TRACES            [akka]  green — platform-guaranteed
  reliability             ✓  AKKA-RES-RECOVERY          [akka]  green — platform-guaranteed
  reliability             ✓  AKKA-SCALE-SHARDING        [akka]  green — platform-guaranteed
  operability             ○  OPS-COMPILES                       needs your action — machine will build
  functional              ○  FUNC-TESTS-PASS                    needs your action — machine will build
  data-integrity          ○  DATA-ENTITY-INVARIANTS             blocked outside this project — needs a running service
  security-compliance     ○  SEC-AUTHZ-ENFORCED                 blocked outside this project — needs a running service
PROJECT
  pipeline-scanning       ○  PROJ-SCAN-SAST-CLEAN               needs your action — external SAST run receipt required
  code-test-health        ○  PROJ-TEST-COVERAGE                 needs your action — decide the coverage threshold
  environment-dependencies ○ ENV-DEPS-RESOLVE                   needs your action — machine will build
PROCESS
  process-integrity       ○  PROC-SOURCE-GROUNDING              needs your action — APIs cited, none invented
  process-integrity       🔒○ PROC-AUDITOR-COVERAGE              needs your action — every surface needs a check
  process-integrity       🔒○ PROC-ADEQUACY-REVIEWED             needs your action — checks need an adequacy review
  build-efficiency        ○  BUILD-WITHIN-BUDGET                needs your action — sign-off required

NEVER
PROJECT
  pipeline-scanning       ✓  SEC-SECRETS-NOT-COMMITTED          green — no secret committed
  repository-hygiene      ✓  NEVER-COMMIT-BUILD-OUTPUT          green — no build output tracked
  environment-dependencies ✓ NEVER-UNPINNED-DEP                 green — lockfile present
──────────────────────────────────────────────────────────────────────────────
rollup — product: 3✓ 4○ 0✗   project: 3✓ 3○ 0✗   process: 0✓ 4○ 0✗

Every condition is in one of three states: open, green, or red. An open condition carries a reason: needs-user-action (a person on this project can move it forward) or blocked-outside-project (a required tool is missing, or a receipt from an external system is required). The two locked (🔒) process-integrity conditions — PROC-AUDITOR-COVERAGE and PROC-ADEQUACY-REVIEWED — are always on and cannot be struck; they make the verification apparatus check itself. See Definition-of-Done types for what each tier covers.

Answer the open conditions

Enforced mode reports NOT_READY while any condition is open. The engine ends every turn with a definitive verdict and the exact next command, and calls out the conditions that need action from you:

NOT_READY — an action to close before I can build:
  • Code & Test Health — coverage threshold?     I suggest 80%
NEXT → /akka:specify <your answer>

Answer in your own words — accept the suggestion or set your own:

Prompt 2. Decisions

/akka:specify keep the suggested 80% coverage threshold

The engine records your decisions, locks the definition of done, and starts building.

Let the build run

The machine derives the exit conditions, wires auditors, plans, implements, and loops until every locally runnable condition is green. It reports NOT_READY and interrupts only if it cannot reach a condition, hits an unresolved ambiguity, or finds a conflict with the organization’s policy.

NOT_READY — 17 applicable conditions
  plan → tasks → implement → verify
  ✓ OPS-COMPILES   ✓ FUNC-TESTS-PASS 6/6   ✓ ENV-DEPS-RESOLVE
NEXT → wait, or /akka:status

Check progress at any time without interrupting the build with /akka:status.

Add a check with feedback

/akka:specify is re-entrant: send it plain-language feedback at any time and it materializes the change as a new exit condition with a covering auditor. Ask for a compile-clean guarantee on every build:

Prompt 3. Feedback

/akka:specify every build must compile with no errors before it ships

The engine adds one exit condition and wires an introspective auditor — an inline command that inspects the working tree directly, delegating to the project’s own toolchain. Here that is mvn -q compile, whose non-zero exit is the red verdict:

+ Code & Test Health — build compiles clean ........ auditor: mvn -q compile

Adding an auditor recomputes the two locked process-integrity gates. Check them with /akka:status:

NOT_READY — 18 applicable conditions
  ✓ PROC-AUDITOR-COVERAGE   every build surface has a covering auditor
  ○ PROC-ADEQUACY-REVIEWED  adversarial review re-running for the new check
NEXT → wait, or /akka:status

PROC-ADEQUACY-REVIEWED re-runs because the set of checks changed; once the review clears, the gate turns green.

Ship

When every applicable condition is green and not stale, the engine reports READY_TO_SHIP:

READY_TO_SHIP — every applicable condition is green
  18 conditions · 15 auditor-verified · 3 platform-guaranteed
  ✓ PROC-AUDITOR-COVERAGE   ✓ PROC-ADEQUACY-REVIEWED
NEXT → /akka:ship

Run /akka:ship release. It runs the auditors for every applicable exit condition at any tier one last time, then runs the ship steps your organization declared for a release ship, and writes a conformance receipt recording what was verified.

Build À la carte

In À la carte mode you run each command yourself. It is the default, so no switch is needed unless you previously moved to Enforced.

Specify the feature

Run /akka:specify with the feature description:

Prompt 4. Feature specification

/akka:specify greeter agent - The greeter agent generates greetings in different languages using an LLM. The consumer of the agent supplies a name and some greeting text in their native language. The agent will then respond with a friendly greeting in English. Each subsequent message sent by a given user will result in a greeting in a randomly chosen language that hasn’t yet been used in that agent session.

Approve the MCP tool calls when prompted. The assistant creates a new git branch (001-greeter-agent), writes the specification file, and summarizes what the spec covers:

  • User Story 1 (P1): first greeting always in English, personalized with the user’s name

  • User Story 2 (P1): subsequent greetings in randomly chosen, non-repeating languages per session

  • User Story 3 (P2): session isolation — independent language tracking across sessions

  • 7 functional requirements, 4 success criteria, 4 edge cases

If the summary does not match your intent, re-run /akka:specify with a revised prompt. For a single-feature application like this, skip /akka:clarify.

Create a plan

Run /akka:plan with the technical implementation prompt. The plan defines how to implement the specification — architecture, components, and constraints:

Prompt 5. Implementation plan

/akka:plan The greeter application is a single RESTful endpoint that exposes a /greet route. This accepts a JSON payload with the user and text fields, which are then incorporated into the user message sent to the OpenAI model. This service has no authentication or other guardrails. Session history for agent conversations is to be implemented using the default and provided agent session support in the SDK. The system prompt for the greeter agent should include the following points without modification:

* You are a cheerful AI assistant with a passion for teaching greetings in new languages

* Start the response with a greeting in a specific language

* Always append the language you’re using in parenthesis in English. E.g. "Hola (Spanish)"

* The first greeting should be in English

* In subsequent interactions the greeting should be in a different language than the ones used before

* After the greeting phrase, add one or a few sentences in English

* Try to relate the response to previous interactions to make it a meaningful conversation

* Always respond with enthusiasm and warmth

* Add a touch of humor or wordplay when appropriate

* At the end, append a list of previous greetings

This implementation should result in a single agent, the HelloWorldAgent, and a single endpoint, the HelloWorldEndpoint. There are no domain objects nor are there any entity components. The application should obtain its model target configuration from the standard Akka SDK model provider configuration. If insufficient configuration is provided, then the endpoint request should fail with a 500 error code.

Results vary between runs. The assistant works on branch 001-greeter-agent and generates these artifacts:

Prompt 6. Generated artifacts
File Purpose

specs/001-greeter-agent/plan.md

Implementation plan and component design

specs/001-greeter-agent/research.md

Decisions on memory, model config, and errors

specs/001-greeter-agent/data-model.md

API record types only (no entities)

specs/001-greeter-agent/contracts/http-api.md

HTTP API contract for POST /greet

specs/001-greeter-agent/quickstart.md

Build, run, and test instructions

The architecture summary describes:

  • HelloWorldAgent — a single Akka Agent with the verbatim system prompt, SDK session memory, and a config-driven model provider

  • HelloWorldEndpoint — POST /greet taking {"user","text"}, using user as the session ID, returning 500 on model-config failure

  • No domain objects, entities, or views — a pure agent plus endpoint

  • Tests — an agent unit test (TestModelProvider) and an endpoint integration test (httpClient)

All four constitution principles pass: Akka SDK First, Design Principles, Test Coverage, and Simplicity. No code has been written yet.

Generate tasks

Run /akka:tasks to convert the plan into an ordered task list. The assistant marks which tasks can run in parallel:

Prompt 7. Task summary
Metric Value

Total tasks

8

Phase 1 (Setup)

1 task — application.conf

Phase 2 (Foundational)

1 task — HelloWorldAgent

Phase 3 (US1 & US2 — MVP)

3 tasks — endpoint + 2 tests

Phase 4 (US3)

1 task — session isolation test

Phase 5 (Polish)

2 tasks — README + quickstart validation

T004 and T005 can run in parallel after T003; T007 and T008 can run in parallel. The MVP (User Stories 1 and 2) is functional after the first five tasks.

Implement the agent

Run /akka:implement and approve the operations it requests. Expect the assistant to hit compilation or test failures and correct them on its own; step in only if it stops converging after repeated attempts. To change the result, re-run /akka:implement with a different model or effort level.

Prompt 8. Implementation summary
Task Status File

T001

Done

src/main/resources/application.conf

T002

Done

src/main/java/com/example/application/HelloWorldAgent.java

T003

Done

src/main/java/com/example/api/HelloWorldEndpoint.java

T004

Done

src/test/java/com/example/application/HelloWorldAgentTest.java

T005

Done

src/test/java/com/example/api/HelloWorldEndpointIntegrationTest.java

T006

Done

session isolation test (in T005’s file)

T007

Done

README.md

T008

Done

build verified via mvn verify

All four tests pass (1 agent unit, 3 endpoint integration) and mvn verify succeeds.

Exercise the application before reviewing the code. If it does not meet the requirements, re-run /akka:plan or /akka:specify and regenerate. Do not merge the feature branch to main until you have exercised the result.

Exercise the agent API

Run /akka:build. This compiles the project, runs the tests, starts the service, and issues a sample request to the endpoint. The AI picks a default port for the service, usually port 9000.

Prompt 9. Local build results
Step Status

Compilation

PASS

Tests

4 passed, 0 failed

Local service

Running on localhost:9000

The endpoint is available at POST http://localhost:9000/greet. Test it with:

curl -X POST http://localhost:9000/greet \
  -H "Content-Type: application/json" \
  -d '{"user": "Maria", "text": "Buenos dias, soy Maria"}'
Set OPENAI_API_KEY for live LLM responses. Without it, the request returns a 500 as designed.

Next steps