ASTRA OS

SPEC-DRIVEN DEVELOPMENT / 001

Make the agent earn its way to code.

ASTRA OS turns coding-agent work into a visible, gated software factory. Intent first. Design before code. Every handoff leaves an artifact someone can inspect.

Install Astra Trace the gates
01—05
front-loaded gates
ON DISK
artifacts, not promises
HUMAN
approval stays in the loop
ASTRA / REVIEW CONSOLE RUN 0001
$ astra start "make billing observable"
GATE RAIL / HANDSHAKE READY
  1. 01PRODUCT INTENTUI LAYOUT / READY
  2. 02ARCHITECTURESERVICE FIT / QUEUED
  3. 03PROGRAM DESIGNCONTRACTS / QUEUED
  4. 04GRAPH ENGINEERINGDAG / QUEUED
  5. 05TESTING TROPHYEXECUTION / QUEUED
ARTIFACTS ARE THE WITNESS

THE FRONT-LOADED LINE OF DEFENSE

Five gates. One coherent run.

Each stage creates the thing the next stage is allowed to trust. If the artifact is missing or invalid, the transition stops.

  1. 01

    PRODUCT ARCHITECT / GATE ONE

    Product intent & visual spec

    Translate a human change request into the product intent and UI layout that everyone can validate before architecture exists.

    DOCdocs/01-product.mdjson/ui-layout.json
  2. 02

    SYSTEM DESIGNER + GRUNT / GATE TWO

    Architecture & adversarial audit

    Design service fit, interfaces, data flow, and failure paths. Then put the design in front of a skeptic before anyone reads it as settled.

    JSONjson/system-architecture.jsonjson/audit.json
  3. 03

    PROGRAM DESIGNER / GATE THREE

    Program design & contract hardening

    Turn intent into exact paths, signatures, error contracts, and test assertions. The contract becomes the write boundary for execution.

    JSONjson/call-stack-types.jsonwrite boundaries
  4. 04

    GRAPH ENGINEER / GATE FOUR

    Graph engineering & role allocation

    Decompose the work into a dependency-aware DAG. Every node carries a scoped role, write boundary, inputs, and outputs.

    PLANPLAN.mdjson/plan.json
  5. 05

    SLICE WORKERS / GATE FIVE

    Testing Trophy execution

    Run static, unit, integration, and end-to-end evidence through the graph. State streams to the console on every transition.

    LIVEjson/dag-execution.json00-status.md

THE SESSION MODEL

Reasoning stays in the room.

ASTRA is the orchestration layer around the coding agent you already use. It keeps the handoff legible without asking your team to trust a black box.

ASTRA OS session architecture flow
INPUTHuman intentplain-language change
CONTROL PLANEASTRA OSgates / ledger / policy
WORKERAgent CLIPi · Claude · Codex · more
WITNESSArtifactsdocs / json / status
A

One agent. The whole pipeline.

The agent that wrote the product intent keeps its reasoning context through architecture, program design, graph planning, and execution.

B

Every transition is inspectable.

The ledger and artifacts are the source of truth. An announced-but-unrun gate cannot masquerade as complete.

C

Human approval is a feature.

ASTRA never enables unrestricted auto-run flags. Risky commands pause for an explicit response.

SUBAGENTS / CONTEXT / BOUNDARIES

Specialists can move fast because the frame is fixed.

At the graph stage, each slice gets a role on top of a shared contract. The prompt stays small. The write boundary stays explicit. The output stays reviewable.

See the operator loop
ROLEintegration verifier≤ 80-word scoped prompt
BOUNDARYlib/runtime/local.mjsdeclared write surface
CONTRACTcall stack + assertionsinputs / outputs / failure path

BUDGET VISIBILITY / NO BROKER FEED

Make the pause visible.

ASTRA does not manufacture a spend number or pretend to have live broker telemetry. It surfaces the decision point so an operator can make one.

POLICY / REQUEST QUEUELOCAL
ALLOWread repository treepolicy / safe
WAITrun external agentoperator response
DENYwrite outside contractwrite boundary
$ astra respond <request-id>

WHAT THE CONSOLE KNOWS

  • Which gate is open
  • Which artifact is missing or invalid
  • Which request needs a human response
  • Which write boundary a node owns

No vendor lock-in to a broker dashboard. Keep the evidence you can inspect, version, and discuss.

GATE FIVE / TESTING TROPHY

Evidence has a shape.

Execution is not one green check. It is a trace across the layers that matter, rendered with the same rigor as the plan.

01STATIC

Shape check

Lint, type, and AST checks catch a broken contract before runtime.

02UNIT

Domain check

Isolated calculations prove the smallest meaningful behavior.

03INTEGRATION

Wiring check

Real cross-component connections test the system where it joins.

04E2E

Trace check

One path per slice confirms the user-visible behavior is still there.

The artifact is the witness. State streams to the retro visualizer on every node transition.

Inspect the source

DEVELOPER WORKFLOW / CLI-FIRST

A clean loop for the next change.

Use the command line for the work. Use the review console for the shared picture. The surface is retro; the handoff is practical.

Get the package Read the repo
OPERATOR / ASTRA CLINODE ≥ 18
$astra doctor# check available CLIs
$astra start "add usage-based billing"
→gate 01 / product intent + UI mockups
$astra run# generate current artifact
→human approval required
$astra approve product && astra advance
$astra viz# open review console

FREQUENT SIGNALS

Questions before the first run.

The short version: ASTRA is a process and evidence layer for the agent you already have.

Is ASTRA OS another coding agent?

No. It is a portable harness around the coding agent you already use. ASTRA adds the gated process, artifact validation, bounded roles, and review surface.

Which agent CLIs can ASTRA drive?

The bundled adapters cover Pi, Claude, Droid, OpenCode, Hermes, and Codex. Pi runs through its SDK; the other adapters spawn their installed CLIs.

What happens when a gate is not ready?

ASTRA names the missing or invalid artifact, stops the transition, and leaves the run available for a bounded rework loop or a human decision.

Can a non-technical stakeholder review the work?

Yes. Gate 1 is written for product intent and visual validation, while the review console renders saved artifacts and document viewers for human inspection.

Does ASTRA require LangGraph?

No. The bundled local runtime is the default. LangGraph is an optional peer runtime with parity tests.

NEXT RUN / YOUR CODEBASE

Give the change a paper trail.

Start with intent, earn the implementation, keep the evidence.

Install Astra View on GitHub