Agentic Workflow Operating System
awos[^1] is a framework for spec-driven development that transforms Claude Code from a chat interface into an autonomous engineering department. By creating a structured chain of intent, you enable agents to execute large-scale features independently — ensuring results that are production-ready.
Quick Start
Before You Begin
- Node.js and npm: Required only for the installer. The agents themselves do not require Node.js.
- Claude Code: This framework is designed for Claude Code. All examples assume you are using it.
Note on Token Usage: awos feeds large amounts of project context to the AI. Plan your Claude subscription or AWS Bedrock usage accordingly.
Step 1: Install awos
npx @provectusinc/awos
This sets up the .awos/ directory (commands, templates, scripts), the .claude/commands/awos/ wrappers, and the context/ directory where your project documents will live. It also registers the AWOS plugin marketplace in your project settings.
Running on an existing codebase? Start with an AI readiness audit to understand how AI-friendly your project is. Install the plugin with /plugin install awos@awos-marketplace, then run /awos:ai-readiness-audit to get a scored assessment with actionable recommendations for improvement. Learn more
Step 2: Foundation Setup
These commands establish your project's foundation. Run them once at the start, and re-run them as your project evolves — requirements change, architecture decisions get refined, and that's normal.
| Command | What it does | Docs |
|---|
/awos:product | Defines the Product — what, why, and for who. | Details |
/awos:roadmap | Builds the Product Roadmap — features and their order. | Details |
/awos:architecture | Defines the System Architecture — stack, DBs, infra. | Details |
/awos:hire | Hires specialist agents — finds, installs skills and MCPs, generates agent files. | Details |
Step 3: Feature Development Cycle
Once your foundation is set, iterate through this cycle for each feature on your roadmap. These commands are designed to be run repeatedly — once per feature.
Tip: Don't hesitate to delete specs after implementation. Completed specs can become outdated and confuse the AI. Your code documentation is the source of truth.
| Command | What it does | Docs |
|---|
/awos:spec | Creates the Functional Spec — what the feature does for the user. | Details |
/awos:tech | Creates the Technical Spec — how the feature will be built. | Details |
/awos:tasks | Breaks the Tech Spec into a task list for engineers. | Details |
/awos:implement | Runs tasks — delegates coding to sub-agents, tracks progress. | Details |
/awos:verify | Verifies spec completion — checks acceptance criteria, marks Status as Completed. | Details |
When to skip the cycle: Not every change needs a spec. Hotfixes, simple bugfixes, and small edits don't require the full spec workflow — Claude Code's built-in plan mode handles those just fine.
Step 4: You're Awesome
That's it! By following these steps, you can systematically turn your vision into a well-defined and fully implemented product.
The awos Philosophy
The awos framework is built on a simple but powerful idea: AI agents, like human developers, need clear context to do great work. Without a structured plan, even the most advanced LLM can act like a confused intern. awos provides a step-by-step workflow that transforms your vision into a detailed blueprint that AI agents can understand and execute flawlessly.
Read more about the philosophy behind awos
Command Reference
Each command has detailed documentation covering how it works, key behaviors, common misconceptions, and example usage.
Browse all command docs
Testing Strategies
