Capabilities · Agentic Workflow Operating System · Open source · MIT
AWOS is a framework for spec-driven development that transforms Claude Code from a chat interface into an autonomous engineering department. It builds a structured chain of intent, from product vision to task list, so agents can execute large-scale features independently, with production-ready results.
The context
Fact 01 · The level playing field
84% of developers use or plan to use AI tools, all buying the same frontier intelligence. The only layer that's yours is what the AI knows about your product.
Stack Overflow · 2025 Developer Survey
Fact 02 · The paradox
Higher AI adoption raises individual effectiveness, and is associated with increasing delivery instability, two years running.
DORA · 2024 & 2025 findings
Fact 03 · The cause
Missing context beats hallucinations as the top reason developers distrust AI output. With persistent, stored context, misses fall from 54% to 16%.
Qodo · State of AI Code Quality, 2025
Context that lives in a person scales like a person. Context that lives in the repo scales like code.
The anatomy
Each layer answers a question the model would otherwise answer with an assumption — written down, versioned, kept current.
The goal, so nothing is built in a silo
What the product is, why it exists, and for whom, plus the roadmap and architecture. Every feature request lands inside this frame, so the model stops filling gaps with assumptions.
“This is a billing platform for SaaS finance teams. This quarter is usage-based pricing. We’re a modular monolith on Postgres — new services need a reason.”
How this team does things
Your conventions and review standards, installed as skills and specialist agents, so output follows your practices instead of a generic model's taste.
“API errors follow RFC 7807. Migrations are always backwards-compatible. Schema changes go through the database agent.”
Where the truth lives, wired in via MCP
Connections to the systems around the code: tickets, documentation, logs, incident history. Agents look things up instead of guessing.
“The customer complaint is in ticket PAY-341. The billing runbook is in Confluence. Last night’s failure is in the logs.”
L4 · Feature specs · the current unit of work
Functional
What the feature must do, as testable acceptance criteria and a definition of done.
“Done means: a team over its seat limit can’t add members — and the admin sees why.”
Technical
How to build it in this codebase: the approach, the touched modules, the constraints.
“Extend the quota middleware in billing-svc. Don’t touch the legacy enforcement path.”
What must never break, as executable tests
E2E and regression tests encode every hard-won lesson, so no change by human or agent can quietly undo one.
“Regression #212: proration always rounds toward the customer. E2E: an invoice is never sent twice.”
The blueprint
Everything below is one worked example — setup first, then the seat-limits feature, end to end.
Foundation · run once · living documents, revisited as the product evolves
Reads your codebase, drafts what it thinks the product is, and interviews you on the gaps. You correct it; the definition is written down — once.
Features, in order, each tied to the goal. “Why this, why now” stops being tribal knowledge.
Stack, data, constraints: decisions recorded with their reasons, so they can be obeyed and challenged.
Finds and installs the specialists this repo needs: agents, skills, MCP connections to tickets, docs, and logs. Committed to the repo, so every session hires the same team.
Feature cycle · once per feature · per-seat limits, from roadmap item to verified merge
Asks the questions a good PM would: hard stop at the limit, or a grace period? Who can override? The answers become testable acceptance criteria.
Proposes the approach from your architecture. Your lead corrects one call: quota checks belong in billing-svc. The correction is permanent.
Decomposes the tech spec into PR-sized tasks, each routed to a specialist.
The orchestrator delegates and writes no code itself. Tasks run in parallel; PRs arrive the size your reviewers actually read.
Walks the acceptance criteria against the implementation. One fails. It goes back, gets fixed, passes — then the spec is marked Completed.
The keystone
The five layers aren't a wiki. Product definition, roadmap, architecture, specs, agent instructions — all plain Markdown, versioned beside the code they describe.
Every change to the documentation is a diff with an author, approved in a PR, including every instruction your agents follow.
The nine commands read and write these files as part of shipping. Docs stay current as a side effect of the work itself.
A new engineer, or a fresh agent session on any machine, reads the same files and starts with full context. No wiki archaeology.
Your team will change. Your product's context won't.
Under the hood
The details an engineering leader checks before trusting a framework — each with a receipt from the repo.
01 · Context-window economy
The orchestrator loads spec context once and hands each task a scoped package. Completed specs are deleted, so stale context never leaks into the next session.
02 · Claude Code native
Prompts follow Anthropic's guidance and are updated as the platform moves: model-behavior shifts, tool renames, new built-in agents.
03 · Tested prompts
A static linter enforces 20+ prompt contracts, fixture projects run real installs, and a QA harness replays live Claude Code sessions asserting on the actual tool-call trace.
04 · Safe updates
Your wrapper layer is preserved on every update by policy; silent overwrite is treated as a bug. Migrations must prove idempotency before they ship.
05 · Zero dependencies
The installer has no runtime dependencies at all: standard built-ins, on Node or Bun. Due diligence takes one look at the manifest.
06 · Nothing hidden
Every prompt, template, and script is plain text in the open. Read every line of what your agents are told before you trust them with your codebase.
The questions
Do we have to change our git flow?
Keep yours.
Branch, trunk, or merge queue: AWOS never sees it. Specs are files; how they reach main is your business.
Does it replace our tickets?
Keep yours.
Jira stays Jira. Wire it in as an information source if you want agents reading tickets; your flow doesn't move.
What about security and compliance?
Keep yours.
AWOS adds Markdown to a repo — no runtime, no service, no new surface. Every agent instruction passes the same review gates your code already does.
Do we adopt a new testing methodology?
Keep yours.
TDD, BDD, integration-first: the framework is explicitly non-prescriptive. /awos:verify gates on whatever you run.
And the fifth question, "our setup is unusual", is built in: every command can be extended with your own instructions. Open its wrapper in .claude/, add a line like "always run the integration suite after each task" — and that's policy now, versioned, visible to the whole team, preserved through every update.
The program
AWOS lands across an organization through Agentic SDLC: stackable tracks, hands-on in your repos, from first baseline to board-ready evidence.
The program opens with an audit of your real codebase: where agents lose context today, and your starting point on the AI Maturity Index.
Hands-on tracks in your repos — the context stack built, the nine commands in your engineers' hands, team by team, project by project.
The Index is re-measured against the baseline as tracks stack, so your board reads progress as a number.
One command installs the framework. The program installs the practice.