Agent OS Documentation

Agent OS is a lightweight system designed to help developers shape better specifications and keep AI agents aligned with existing codebase patterns. It is designed to work alongside AI tools like Claude Code, Cursor, and Antigravity, supporting any language or framework.

Core capabilities include:

• Discover Standards: Extract patterns and conventions from your codebase into documented standards.
• Deploy Standards: Intelligently inject relevant standards based on the current build context.
• Shape Spec: Create high-quality plans to improve build outcomes.
• Index Standards: Organize and make standards discoverable.

The standards index (agent-os/standards/index.yml) is used by the /inject-standards command to quickly match relevant standards to tasks without reading every file. The index maps standards to brief, one-sentence descriptions.

When to run the indexing process:

• After manually creating or deleting standards files.
• If /inject-standards suggestions appear out of sync.
• To clean up an outdated or messy index.

Note: The /discover-standards command runs this indexing process automatically as its final step, so manual execution is often unnecessary after discovery.

The shape-spec command is used to gather context and structure planning for significant work.

CRITICAL REQUIREMENT: This command must be run while the agent is in plan mode. If you attempt to run it outside of plan mode, the process will stop with the following error:

Shape-spec must be run in plan mode. Please enter plan mode first, then run /shape-spec again.

The shape-spec process follows a structured sequence to ensure implementation is well-informed:

1. Clarify Scope: Define exactly what is being built.
2. Gather Visuals: Collect mockups, wireframes, or screenshots.
3. Identify References: Locate similar code in the existing codebase to study patterns.
4. Check Product Context: Align the work with files in agent-os/product/ (e.g., mission.md, roadmap.md).
5. Surface Standards: Identify relevant patterns from agent-os/standards/index.yml (e.g., api/response-format).
6. Generate Spec Folder: Create a timestamped directory.
7. Structure the Plan: Organize tasks, ensuring Task 1 is always saving the spec documentation.
8. Complete & Execute: Finalize implementation tasks and await approval.

Because standards are intended to be injected into AI context windows, they must be optimized for token efficiency and scannability. Follow these rules:

• Lead with the rule: State what to do first, explain why second.
• Use code examples: Show the pattern rather than just describing it.
• Skip the obvious: Do not document what the code already makes clear.
• One standard per concept: Avoid combining unrelated patterns.
• Bullet points over paragraphs: Prioritize scannability over prose.

Example of a good standard:

# Error Responses

Use error codes: `AUTH_001`, `DB_001`, `VAL_001`

```json
{ "success": false, "error": { "code": "AUTH_001", "message": "..." } }

• Always include both code and message
• Log full error server-side, return safe message to client

If you encounter issues with the /inject-standards command, check the following:

• No standards index found: If you see No standards index found. Run /discover-standards first to create standards, or /index-standards if you have standards files without an index., you need to generate or rebuild your standards index.
• Standard not found: If you provide an incorrect path in Explicit Mode, the agent will report Standard not found: [path] and list available options in that directory to help you correct the path.
• Incorrect suggestions: If the Auto-Suggest mode provides irrelevant standards, run /index-standards to rebuild the index and ensure descriptions are accurate.

When the shape-spec process generates a new specification folder, it uses the following format:

YYYY-MM-DD-HHMM-{feature-slug}/

• YYYY-MM-DD-HHMM: Current timestamp.
• feature-slug: A lowercase, hyphenated description of the feature (maximum 40 characters).

Example: 2026-01-15-1430-user-comment-system/

The plan-product process generates the following files in agent-os/product/:

mission.md

Contains the core product vision:

• ## Problem: The core problem or pain point addressed.
• ## Target Users: The intended audience.
• ## Solution: The key differentiator or unique approach.

roadmap.md

Contains the development timeline:

• ## Phase 1: MVP: Must-have features for launch.
• ## Phase 2: Post-Launch: Planned future features.

tech-stack.md

Contains the technical architecture:

• ## Frontend: Frontend technologies.
• ## Backend: Backend technologies.
• ## Database: Database choice.
• ## Other: Hosting, APIs, and other tools.