À la carte mode

Supplying an entire application in one /akka:specify prompt is possible but not recommended — if your application is that simple, a single-file spec is less overhead. To specify a new feature:

The short description becomes a branch name like 00#-feature-short-description (kebab case). The prompt should define exclusively the what and why of the feature, not technical implementation detail.

This creates a specification in specs/001-core-users on the 001-core-users branch. Resist manually editing the spec — clarification is the next step. Keep features scoped small enough that you have a clear idea of the acceptance criteria and the generated code is easy to review.

Clarification is a critical step. Start it with a single command, no parameters:

Your assistant analyzes your constitution, feature specification, and conversation history and identifies gaps — places where it would have to make a decision without enough information. Running /akka:clarify on the chess core users feature will likely raise several questions: how users are uniquely identified, what happens to deleted users, whether multiple concurrent sessions are allowed. This level of clarity is a hallmark of spec-driven development.

The plan is your technical architecture — the how. Like specify, its input is a prompt, not the final plan; your agent produces the plan as output. If code generation later does not give you what you wanted, iterate on the plan; amendments are tracked alongside constitution and feature updates.

The plan output is categorized by priority and functional requirements, making it easy to verify. Make sure you agree with the functional requirements before continuing.

This converts your clarified specification and plan into a formal, dependency-ordered set of work items, identifying which can run in parallel. You can refine the list by discussing it with your agent.

Your assistant writes the application code. Before running it, make sure you are satisfied with the effort or "thought" level — results vary between medium and high. It is normal for the agent to hit compilation and test failures and iterate toward the answer; the default Akka constitution mandates both unit and integration tests.

/akka:build does more than mvn compile exec:java: it shuts down pre-existing services and anything on the target port, recompiles, runs the tests, launches the service, and exercises it through its real endpoints. The service is left running and is recompiled and restarted automatically when project files change.

Once the service is running — locally after /akka:build or deployed via /akka:deploy — /akka:inspect verifies it against your specification at runtime: it exercises API endpoints, verifies entity state via backoffice tools, and validates the UI in the browser, then summarizes findings. If inspect finds issues, iterate with /akka:implement and /akka:build.

To deploy through Akka Automated Operations, /akka:deploy prompts for the organization and project, builds and pushes a container image, and deploys — doing a rolling update if the service is already running. After deployment it verifies component health and inspects the deployed service.

Beyond the core loop, several commands help you shape and maintain the work:

Every command, with its options and examples, is in the Specify commands reference.