Build · AI-native SDLC

AI-native SDLC — spec-driven development

On AirawatOS you don't hand an AI a blank repository and hope. You author one governed artifact — a Service Specification — and agents generate, certify and reconcile a running service against it. Because the AI generates into a narrow, governed space (a shared vocabulary of nouns and verbs, certified components, one interaction spine, and a constitution), what it produces is far more likely to be correct — and every claim is checkable.

Why this is reliable

Most AI code generation fails because the target is unbounded — any name, any shape, no contract, no way to tell right from merely plausible. AirawatOS inverts that. Generation is boxed in by four rails:

The Service Specification is the source of truth

A human authors one artifact — a governed platform.service_spec — that declares the service, not the code:

• Domain model — the governed nouns it manages (grievance.complaint, finance.payment, …).
• Operations — each a governed verb acting on a noun via a transition (e.g. lifecycle.request · grievance.complaint · file).
• Workflows, business rules, roles, apps, and acceptance criteria (executable GIVEN/WHEN/THEN).

Every element carries a status (built / roadmap) and an impl: pointer to the governed id that realizes it — or null when nothing does yet. The spec is both the plan and the live map of what's been built.

Stratified: spec-first and code-first

Two layers, meeting at a seam:

• Service layer → spec-first. Schemas, interfaces, workflows, rules and roles are declared in the spec and governed centrally.
• Component internals → code-first. You write ordinary Python against ctx; aos check derives the component's contract (reads / writes / egress / scopes) from the code.

They meet at conformance (next) rather than one dictating the other.

Conformance is the reconciliation seam

The declared contract (the spec) is checked against an independently derived / tested view at certify time. Implementation and its check can't share a misunderstanding, so a plausible-but-wrong component is caught. Acceptance criteria become executable conformance tests; authoring-time checks (e.g. every operation must bind to a governed verb) catch drift even earlier.

The loop, and who drives it

You stay in control at every gate — the AI writes, the human enacts.

1. Author a spec — describe (or upload) a brief; the assistant refines it; Compile turns it into a governed spec; you review and Govern it. (Studio → Contracts → ✍️ Author a spec.)
2. Generate — pick a spec + a target; the Solution Architect scaffolds the component, grounded in the spec's reads/writes, the acceptance criteria, and the constitution. (A component's ✨ Generate with AI.)
3. Certify — conformance + the clean-room checks.
4. Compose & install into your sandbox.
5. Run & observe.
6. Reconcile — spec elements flip roadmap → built with the id of what realized them; a change-request loops back to the author step.

Two front doors onto the same pipeline: Studio (in the browser) and the aos CLI (code-first).

A tiny example

Say a resident wants to report a broken streetlight. You don't invent anything — you describe the service in plain words, and it compiles to governed pieces:

Brief (what you type): "A resident files a grievance about a civic issue; an officer resolves or rejects it; the resident can track it or withdraw it."

Compiles to (service spec, abridged):

noun    grievance.complaint                              the record
roles   civic.resident · civic.grievance-officer

operations
  lifecycle.request   · grievance.complaint · file       resident files it
  lifecycle.decide    · grievance.complaint · resolve     officer resolves / rejects
  lifecycle.status    · grievance.complaint · track        anyone tracks it
  lifecycle.withdraw  · grievance.complaint · withdraw     resident withdraws it

Notice there is no file-grievance verb. "Filing" is the governed lifecycle.request verb acting on the grievance.complaint noun — the domain lives in the noun, not in a bespoke verb. From this spec, Generate scaffolds the component that implements each operation, and conformance checks it against the acceptance criteria. Change the brief ("add a priority", "route by ward") and you re-compile — the spec stays the single source of truth.

What's live today

Honest note: the LLM's draft — of a spec or of code — is always a starting point you review, never blind-accepted. The reliability comes from the governed space it generates into and the conformance that checks it, not from trusting the model.