Workflows: Modular Building Blocks

Workflows are modular instruction blocks that Agent OS uses to assemble consistent instructions across all modes and agents. They're the building blocks that power the spec-driven development workflow.

Most users never need to customize workflows. Agent OS includes a comprehensive set of pre-built workflows that handle the entire development process. But if you want fine-grain control over how instructions are assembled and how standards get injected into your agents, understanding workflows helps.

This page covers:

• What workflows are
• How workflows are organized
• How the injection system works
• When to customize workflows

What workflows are

Workflows are reusable markdown files containing instructions for specific parts of the development process. They get injected into:

• Command files - Single-agent mode prompts that you run sequentially
• Agent files - Multi-agent mode subagent instructions
• Role definitions - Specialized implementer and verifier agents

This modular approach ensures consistency: the same process instructions appear everywhere they're needed, regardless of which mode you're using.

How workflows are organized

Workflows live inside your profiles and follow the same inheritance system as standards and roles.

The default profile organizes workflows by development phase:

~/agent-os/profiles/default/workflows/
├── planning/
│   ├── research-feature.md
│   └── plan-roadmap.md
├── specification/
│   ├── write-spec.md
│   └── analyze-requirements.md
└── implementation/
    ├── implement-tasks.md
    └── verification/
        └── verify-implementation.md

When you install Agent OS into a project, these workflows are compiled into your project's commands and agents based on your active profile.

How the injection system works

Agent OS uses a simple injection syntax to embed workflows (and standards) wherever instructions are needed.

Workflow injection syntax

Workflows are injected using this syntax in any command, agent, or workflow file:

{{workflows/specification/write-spec}}

During project installation, Agent OS finds this placeholder and replaces it with the contents of write-spec.md.

Standards injection syntax

Similarly, standards get injected using this syntax:

{{standards/global/*}}
{{standards/backend/database}}

The * wildcard includes all files in that folder. Without it, you're referencing a specific file (without the .md extension).

Note: An important difference between injecting standards vs. workflows: standards are injected as a list of @ references to the files in your project's agent-os/standards folder, while workflows are injected as the file contents themselves.

How compilation happens

When you run project installation, Agent OS:

1. Scans all command and agent files for injection placeholders
2. Locates the referenced workflow or standard files in your active profile
3. Replaces each placeholder with the file contents
4. Validates that all referenced files exist

The result is fully compiled commands and agents with all instructions assembled and ready to use.

When and how to customize workflows

Most users work with the default workflows indefinitely without needing customization.

If you do choose to customize, start small. Make minor tweaks to existing workflows before attempting major rewrites. Only work up to larger customizations once you have a firm understanding of how the Agent OS system works.

Most common customization: changing injection points

The most common reason to customize workflows is adjusting where individual workflows or standards are injected. For example:

• Adding specific standards to certain agents but not others
• Changing which verification workflows run for different implementers
• Removing standards that don't apply to your tech stack

Other reasons to customize

• Add project-specific processes - Your team has unique deployment or testing workflows
• Modify instruction phrasing - You want agents to follow different communication patterns
• Create specialized workflows - You have unique development phases or processes

Customizing

Overriding workflows in custom profiles

To customize a workflow, use profile inheritance:

1. Create or use a custom profile that inherits from default (or another existing profile)
2. Copy the workflow file you want to modify from profiles/default/workflows/
3. Place it in the same path within your custom profile
4. Modify as needed—your version will be used instead of the default

Example: To override how specs are written, create:

~/agent-os/profiles/my-profile/workflows/specification/write-spec.md

When you install this profile into a project, your custom version will be used everywhere {{workflows/specification/write-spec}} appears.

Creating

Adding new workflows

To create entirely new workflows:

1. Add a new markdown file in your profile's workflows/ folder
2. Write self-contained, reusable instructions
3. Inject it using {{workflows/[path]/[name]}} in commands or agents

Example workflow in ~/agent-os/profiles/my-profile/workflows/deployment/deploy-staging.md:

# Deploy to Staging

After implementation is verified:

1. Run the staging deployment script:
   ```bash
   npm run deploy:staging
   ```

2. Verify the deployment at https://staging.example.com

3. Run smoke tests to ensure core functionality works

Then inject it into a verification workflow or agent:

## Final Steps
{{workflows/deployment/deploy-staging}}

Or reference it in your role definitions as documented here.

Finding injection points

To see where a specific workflow is used, search your profile:

grep -r "{{workflows/implementation/verify" ~/agent-os/profiles/default/

This shows all commands, agents, and workflows that inject this specific workflow, helping you understand the impact of any changes.

Next steps

Learn about profiles

Learn about standards

See the Agent OS workflow