Agentic Workflow Operating System

awos[^1] 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.

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.

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: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 |

Step 3: Feature Development Cycle

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.

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

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

Command Reference

Each command has detailed documentation covering how it works, key behaviors, common misconceptions, and example usage.

Browse all command docs

Testing Strategies

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

Customizing awos

The awos framework is designed to be both powerful out-of-the-box and highly customizable.

The .awos Folder: Framework Core (Do Not Edit)

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.

The .claude Folder: Your Customization Layer

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

How to Customize

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.md

Updating awos

To update awos to the latest version, run the installer again:

npx @provectusinc/awos

What 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.

[^1]: 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."