Enforced mode
Enforced mode is the default. It guides you to define "done" up front as machine-checkable conditions, then will not let a feature ship until those conditions are met. You get a cleaner, auditable result — at the cost of more up-front definition and a longer, more thorough build. For the lighter, run-the-commands-yourself flow, see À la carte mode; switch between the two with /akka:mode.
Exit conditions and Definition of Done
Enforced mode treats "done" as something the system checks, not a judgment call. It separates "done" into three layers, each with a distinct owner:
| Layer | What it is | Who authors it |
|---|---|---|
Definition of Done |
The business statement of done, in the customer’s own terms ("greetings are personalized", "the service survives a node loss"). |
The project owner and the organization. |
Exit condition (EC) |
The technical translation of a Definition of Done item into a precise, binary |
Derived by the tooling; refined by the developer. |
Auditor |
The check that evaluates an exit condition and returns a verdict. It is one of three kinds — introspective (runs in the tree), provisioned (verifies a harness asset), or delegated (resolved by an attestation). |
Akka ships the built-in introspective set; projects and the organization author the rest. |
The layers roll up in the other direction: an auditor produces a verdict, verdicts set each exit condition’s status, and those aggregate into a Definition-of-Done type status. A developer sees progress in business language ("Reliability: covered", "Functional: 2 of 3 met") while the machine works in precise conditions underneath.
Every exit condition resolves to a single boolean pass — there is no "mostly done". A requirement that cannot be expressed as a binary predicate over an observable surface is not yet an exit condition; it is a Definition of Done item still waiting to be made precise.
Every condition also carries a provenance that determines whether a developer can change it: akka-intrinsic (platform guarantees, always on and asserted), recommended-default (from the default library, strikable), corporate (the organization policy, locked), and developer (added for this feature). Done is layered and additive — the organization defines mandatory controls and developers add to them, tightening but never loosening. See the exit condition schema for the full field set.
Definition-of-Done types
Every exit condition is tagged with a fixed, versioned Definition-of-Done type. Types are the scaffold the tooling walks to infer which conditions a feature needs, and the buckets progress rolls up into. Each is pinned to a distinct Akka observable surface. They are organized into three tiers — the "three P’s".
Product — does the software work? (developer- and customer-led)
Type |
Covers |
Functional |
Endpoint, event, view, and workflow behavior. |
Data Integrity |
Entity state and its invariants. |
Reliability |
Cluster behavior and fault injection — recovery, supervision, surviving node loss. |
Performance |
Timing and throughput. |
Security & Compliance |
Authorization, audit, and PII handling at runtime. |
Operability |
Deployment, health, telemetry, and runtime cost. |
Experience |
Browser-facing behavior — accessibility, responsiveness, page performance. On by default; struck as a group for a headless or API-only service. |
Project — is the codebase healthy and standards-compliant? (heavily organization-authored)
Type |
Covers |
Documentation & Training |
Documentation completeness, content standards, training material, changelog history. |
Repository Hygiene |
Clean git history — rebased, no lingering commits, no orphaned dead code. |
Pipeline & Scanning |
Prior commits CI-green; code scanning (SAST, SCA, secrets, license) complete. |
Code & Test Health |
Coverage thresholds, test-pyramid balance, and maintainability budgets. |
Environment & Dependencies |
Every dependency identified, available, and verified, and the local environment current with the resolved governance. A drift check, not a run-once flag. |
Process — did the AI build stay honest and efficient? (organization policy)
Type |
Covers |
Process Integrity |
Meta-guardrails on the build, including source-grounding — API usage cited to official docs, no invented APIs. |
Build Efficiency |
Token-to-cost budgets and model routing. |
The core types are closed and versioned. Organizations extend "done" by adding conditions within a type, not by inventing new types.
Akka ships a browsable exit condition catalog of candidate conditions for every type. Browse it for inspiration, or point your AI coding assistant at it to help identify the conditions that make sense for your project.
The guided flow
Enforced mode is two human touchpoints book-ending a silent machine phase — not a gate at every step.
-
Define (you). Frame the feature and define done in business terms. The engine infers a full draft of the definition of done from your intent and Akka’s fixed surfaces, then asks only about the residue it cannot safely infer — a threshold, a genuine fork, a type toggle — each anchored to a proposed default. Inferred conditions are marked and do not become the contract until you confirm them. The organization’s mandatory conditions are merged in, locked. Enforced mode will not build while a required decision is open.
-
Build (the machine). The engine derives exit conditions, wires auditors, plans, and implements, looping until every locally runnable auditor is green. It stops only for a short, closed list of reasons: a condition it cannot reach after repeated tries, an ambiguity Define did not resolve, or a conflict between your definition and the organization’s.
-
Review (you). Validate the definition, not the code. A review miss becomes a new condition and loops back to Build. Close any conditions that need your sign-off, then ship.
-
Ship.
/akka:shipruns the in-scope auditors and fires the organization-authored terminal action.
The /akka:specify engine
You drive the whole flow through one re-entrant command. You always run /akka:specify <input> — a spec, a clarification answer, review feedback, or a decision — and it always ends with a definitive status line and the exact next command. Every call resolves to exactly one of three states:
State |
Meaning and next step |
NEEDS_INPUT |
Your turn — a clarification, threshold, decision, or review feedback is required. Next: |
WORKING |
The machine’s turn — building autonomously. Next: wait, or |
READY_TO_SHIP |
The completion policy is satisfied. Next: |
Because every call ends in exactly one of these three states with one explicit next command, the workflow is predictable enough to follow by eye and to parse in CI.
READY_TO_SHIP does not mean every condition is green. It means the completion policy — itself part of the definition of done, authored by the project owner — is satisfied: human review after a confidence pass, a percentage-of-conditions threshold, or all-must-pass.
Auditors
An auditor is the check bound to an exit condition. The engine resolves each condition’s auditor into one of three kinds, set by where the check can run:
| Kind | What it is |
|---|---|
Introspective |
A check that inspects the working tree directly and returns green or red. This covers both the built-in set Akka ships ( |
Provisioned |
A condition whose check is |
Delegated |
A condition with |
The built-in introspective set is small, and there is no large closed catalogue of checks you pick from by id. Beyond the built-ins, auditors are authored per ecosystem (inline commands), provisioned as harness assets, or delegated via attestation. Each auditor declares what it needs to run (a git tree, Maven, a live service); the tooling checks availability and resolves the condition accordingly rather than blindly failing. See Auditor kinds for the full model.
Every condition carries a status:
| Status | Meaning |
|---|---|
GREEN |
The auditor ran and the invariant holds. |
RED |
The auditor ran and the invariant is violated — or a prohibition condition has no auditor, which reds rather than passing silently. |
OPEN |
Active but not yet resolved: not yet evaluated, awaiting a human sign-off, or a check whose command you have not yet approved. |
DEFERRED |
Not verifiable locally — a delegated (attested) check before its attestation, or a requirement unavailable here (for example, a live-service check before deployment). Carried downstream and recorded in the conformance receipt. |
WAIVED |
Unmet, but covered by a time-bound waiver. |
ASSERTED |
Guaranteed by the platform (an |
OFF |
Not applied. |
A deferred condition is not a gap — it is a check that will run elsewhere. An open condition is unfinished work.
The two locked gates
Two Process-integrity conditions are always on and cannot be struck — they make the verification apparatus police itself:
-
Coverage (
PROC-AUDITOR-COVERAGE) — every material build surface (apom.xml,package.json,go.mod,Dockerfile, and so on) must have a covering auditor. Add a React app and the gate goes red until a web check is authored; a folder that genuinely needs no check can be waived. -
Adequacy review (
PROC-ADEQUACY-REVIEWED) — before the build advances, each check is reviewed adversarially: could it pass while its invariant is false? A fresh review, keyed to the current checks, must cover every auditor. Feedback that changes a check stales the review and forces it to re-run — so an auditor can never quietly drift out of adequacy.
New or changed checks are surfaced to you for approval at the exit-condition level — "here are the checks and how I’ll check them" — never as a low-level "approve running a command". See Auditors for the full model.
Shipping and receipts
/akka:ship runs the in-scope auditors and, if they pass, fires the terminal action the organization defined. Akka provides the mechanism; the organization writes what "ship" does — deploy and activate, push to a repository, open a pull request, publish an artifact, or a sequence of these. There is no fixed menu of ship profiles.
One rule holds regardless: ship fires only when every in-scope condition is green. What ship targets determines what "done" proves. A deploy-and-activate ship verifies the full definition of done, including live-service conditions. A push-to-repository ship cannot run live-service auditors, so those defer downstream and Akka guarantees only the pre-handoff conditions.
When ship completes, Akka writes a conformance receipt — which conditions were green, which auditors ran, which deferred and to whom, and any waivers in effect. The receipt is what makes an AI-built handoff auditable: the downstream owner sees exactly what was verified and what remains. In Enforced mode, a successful ship also offers to shut down the local services the build started, closing the lifecycle that /akka:setup opened.
Enterprise governance
In Enforced mode an organization defines a mandatory baseline of exit conditions and definitions of done — security, compliance, repository hygiene, its "way of working" — that Akka enforces and developers can tighten but never loosen. Each condition is assigned a governance level (always-apply, never-apply, on-but-dev-configurable, off-but-dev-configurable).
Author the governance policy
The policy is a single policy.yaml, versioned somewhere your organization owns and controls. Set it up once:
-
Store
policy.yamlunder version control. Keep it in a dedicated git repository — name it whatever you like (github.com/<org>/akka-specify-governanceis a common example) — governed by your own access controls: private repository, SSO, RBAC, and branch protection. Akka does not host it, and the CLI does not require any particular provider or name; it fetches the file from the URL you configure. -
Define the policy in
policy.yaml— the single source of truth. It declares the allowed mode, the ship definition, the toolchain version, the exit conditions and their governance levels, and the completion, waiver, and rollout policies. See Policies for the full schema and an annotated example. -
Add a CI workflow that runs the Akka conformance check against the policy. The organization’s own CI is the enforcement backstop: local tooling is advisory and guided; CI is the gate a change must pass to merge or ship.
For the policy to reach developers, IT points each machine’s Akka CLI at this repository one time, through a managed setting named governance-policy-url — a configuration file the developer cannot edit. From then on, whenever a developer runs /akka:setup, the CLI downloads policy.yaml, applies it on top of the developer’s own choices (which may only make the rules stricter, never looser), and enforces it automatically in status, conform, and ship — with no flag required and no way to opt out. When the organization changes the policy, developers pick up the new version by running /akka:setup again. See Applying the policy in every project for how IT sets this up.
Beyond the organization policy, the default library provides a rich, curated set of best-practice conditions on by default; you strike what does not apply, and strikes are recorded. For inspiration on what else to require, browse the exit condition catalog, organized by type and project flavor.
Working in Enforced mode
Every Specify command remains available — Enforced mode changes the ship gate, not the command set (see /akka:mode). In practice you drive an Enforced build through /akka:specify as the re-entrant engine, and use the governance commands to inspect progress and release:
Command |
Role |
The re-entrant engine that drives the whole flow. |
|
Read-only rollup of the definition of done by business category. |
|
Fire the organization-authored terminal action, gated on the in-scope conditions. |
|
Switch mode within the organization-allowed set. |
|
Install and repair the local environment and source the governance policy. |