awos1 is a framework for spec-driven development built on Claude Code. By creating a structured chain of intent, you enable agents to execute large-scale features independently — ensuring results that are production-ready.
- 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.
npx @provectus/awosThis 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.
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:architecture |
Defines the System Architecture — stack, DBs, infra. Adopts your existing stack automatically when the repo already has code. | Details |
/awos:hire |
Hires specialist agents — finds, installs skills and MCPs, generates agent files. | Details |
Once your foundation is set, iterate through this cycle for each feature you build. These commands are designed to be run repeatedly — once per feature.
| 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.
That's it! By following these steps, you can systematically turn your vision into a well-defined and fully implemented product.
awos is a method for turning intent into working software with agents, where the human decides and the agent builds. Its product is not documents but agreement — a confirmed, shared understanding between you and the agent about what is being built and why, reached before any code is written.
Why awos works · The philosophy · Where it is heading
Each command has detailed documentation covering how it works, key behaviors, common misconceptions, and example usage.
The awos framework is flexible and non-prescriptive when it comes to testing. Teams can adopt the testing approach that best fits their project — whether that's TDD, BDD, integration testing, or a combination of strategies.
Explore testing strategies and customization options
The awos framework is designed to be both powerful out-of-the-box and highly customizable.
All framework service data lives in the .awos/ directory:
.awos/commands- Full command prompt instructions.awos/templates- Document templates.awos/scripts- Utility scripts
Warning: Do NOT manually edit files in the .awos/ folder. These files are always overwritten during updates.
This is where you customize awos to fit your needs:
.claude/commands/awos/{command}.md- Lightweight wrapper files that link to.awos/commands/{command}.md
Example: Customize a Command
Open .claude/commands/awos/implement.md and add your instructions:
---
description: Runs tasks — delegates coding to sub-agents, tracks progress.
---
Refer to the instructions located in this file: .awos/commands/implement.md
+ - Always run tests after implementing each task
+ - Follow the code style guide in docs/style-guide.mdTo update awos to the latest version, run the installer again:
npx @provectusinc/awosWhat gets updated:
- Commands in
.awos/commands - Templates in
.awos/templates - Scripts in
.awos/scripts - Commands in
.claude/commands/awos
Your customizations are preserved. Files under .awos/ are framework internals and are always updated. Files in .claude/commands/awos are your customization layer: when existing wrappers would be overwritten, the installer asks first — and in non-interactive runs it preserves them by default (pass --overwrite for a deliberate fresh sync).
Upgrading an existing project? See the upgrade guide for what left the framework and what happens to the local copies you already have — nothing of yours is deleted.
Footnotes
-
The Russian word «авось» (a-VOHS') doesn't have a direct equivalent in English — it's a very culturally loaded concept. It's a mix of hope, chance, and fatalism, often with a sense of "let's do it and maybe it will work out." ↩