Thought UmweltThought Umwelt

thought umwelt

Agent OS

5 min read

Obsidian Metadata

sourcehttps://buildermethods.com/agent-os/workflow

References

Quick Reference: Command Cheat Sheet:

CommandPhaseWhen to use
/plan-productPlanningAt the start of a project or when shifting strategy.
/shape-specRequirementsYou have an idea but need to flesh out the details.
/write-specDocumentationYou have requirements and need a formal blueprint.
/create-tasksPlanningYou have a spec and need a step-by-step to-do list.
/implement-tasksCodingYou are ready to build the feature (Standard mode).
/orchestrate-tasksCodingYou are building a massive feature requiring multiple specialized agents.

1. What is Agent OS?

Agent OS is a framework designed to transform AI coding assistants (like Claude Code, Cursor, or Windsurf) from “confused interns” into productive, autonomous developers.

Instead of prompting an AI with vague instructions (“Make a login page”), Agent OS forces a Spec-Driven Development lifecycle. It provides structured workflows that ensure every line of code is written against a clear specification, adhering to your team’s specific tech stack and coding standards.

Key Concepts

  • Project-Specific Context: Agent OS installs directly into your repo (.agent-os/), meaning the “brain” of the agent travels with the code.

  • Six Distinct Phases: Development is broken down into specific stages: Plan, Shape, Write, Task, Implement, and Orchestrate.

  • Standards Enforcement: It proactively feeds your coding style, architectural patterns, and testing rules to the AI before it writes a single line of code.

2. Setup & Installation

Before starting work on a feature, ensure the environment is ready.

A. Base Installation (One-time setup per machine)

This installs the core Agent OS files to your local machine, serving as a template for all projects.

  1. Run the base install script: Bash
    curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/setup/base.sh | bash -s -- --claude-code --cursor

_(Flags depend on your tooling: `--claude-code` or `--cursor`)_ 1

2. Customize Defaults: Navigate to ~/agent-os/standards and edit the default files (e.g., code-style.md, tech-stack.md) to match your team’s general preferences. 2222

B. Project Installation (Per repository)

This injects Agent OS into a specific codebase.

  1. Navigate to your project root.

  2. Run the project install script:

    Bash

    ~/.agent-os/setup/project.sh

    This copies the standards and workflows into your project’s .agent-os/ folder. 3

  3. Project-Specific Tuning: Edit the files in your project’s .agent-os/standards/ folder to match the specific needs of that repo (e.g., specific testing frameworks or naming conventions). 4

3. The Development Workflow (The Happy Path)

Follow these steps sequentially for every new feature to guarantee high-quality output.

Phase 1: Product Planning

Goal: Establish the high-level vision before getting into the weeds.

  • Command: /plan-product

  • Action: The agent interviews you to create or update three core documents in agent-os/product/:

    • mission.md: The product vision and target user.

    • roadmap.md: A prioritized list of features.

    • tech-stack.md: The definitive guide to libraries and frameworks used. 5

Phase 2: Shape the Spec

Goal: Move from a vague idea to concrete requirements without writing formal documentation yet.

  • Command: /shape-spec

  • Action:

    1. The agent asks clarifying questions about the feature (e.g., “Should this modal be dismissible?”).

    2. It checks for existing code reusability to avoid duplication. 6

    3. It asks for visual assets (screenshots/mockups).

    4. Outcome: A requirements.md file is generated in a new spec folder (e.g., agent-os/specs/2025-10-21-user-login/planning/). 7

Phase 3: Write the Spec

Goal: Create the “blueprint” that the coding agent must follow strictly.

  • Command: /write-spec

  • Action: The agent reads the requirements and writes a spec.md.

  • Critical Detail: This file contains no code. It outlines User Stories, Specific Requirements, Visual Design notes, and Out-of-Scope items. 8

Phase 4: Create Tasks

Goal: Break the spec into a strategic execution plan.

  • Command: /create-tasks

  • Action: The agent generates tasks.md.

  • The Strategy: It groups tasks logically (e.g., Database Layer → API Layer → Frontend). It ensures tests are focused (2-8 tests per group) rather than exhaustive, to keep the agent fast and focused. 9

Phase 5: Implementation

Choose one of the two paths below based on complexity.

  • Command: /implement-tasks

  • Action:

    1. The agent reads the tasks.md and implements them group-by-group.

    2. It references your standards/ to ensure code style matches.

    3. It updates the task list as it finishes items.

    4. It runs a final verification step to ensure all tests pass. 10

Path B: Orchestration (For complex, multi-file features)

  • Command: /orchestrate-tasks

  • Action:

    1. Creates an orchestration.yml map.

    2. Assigns specific sub-agents (e.g., backend-specialist, frontend-specialist) to specific task groups.

    3. Allows for fine-grained control where you can assign specific standards to specific tasks (e.g., applying only CSS standards to the Frontend task group). 11

4. Best Practices for “Best Outcomes”

To get the most out of Agent OS, the team should adhere to these principles found in the system’s standards:

  1. Visuals are Mandatory (Sort of): The shape-spec phase explicitly checks for visual assets. If you have mockups, drop them into the planning/visuals folder. The agent is trained to read these and extract UI details, which significantly reduces frontend churn. 12

  2. Lean Testing Strategy: Agent OS is configured to discourage “test bloat.”

    • Rule: Write 2-8 focused tests per task group.

    • Why: Prevents the agent from getting stuck in endless test-fixing loops for edge cases that don’t matter yet. 13

  3. Code Reusability First: During the shaping phase, the agent is instructed to look for existing components. Explicitly point the agent to similar existing features (e.g., “Make the settings page look like the profile page”) to enforce consistency. 14

  4. Keep Standards Updated: If the agent consistently makes the same mistake (e.g., using the wrong date format), update agent-os/standards/global/coding-style.md. This fixes the behavior permanently for all future tasks. 15

Graph View