Agent OS Framework

Generate standardized .agent-os structure for AI-native repository workflows.

Quick Start

Generate full .agent-os structure

/agent-os-framework

Generate for existing project

/agent-os-framework --update

Generate specific component

/agent-os-framework --component mission

When to Use

USE when:

• Setting up new repository

• Adding AI workflow support

• Documenting product vision

• Creating decision records

DON'T USE when:

• Project has complete .agent-os

• Non-product repositories (e.g., dotfiles)

Prerequisites

• Repository initialized with git

• Basic project understanding

• Stakeholder input for mission

Overview

Creates complete .agent-os structure:

• product/ - Core product documentation

• specs/ - Feature specifications

• standards/ - Code style guidelines

• instructions/ - Workflow instructions

Directory Structure

.agent-os/ ├── product/ │ ├── mission.md # Product pitch, users, pain points │ ├── tech-stack.md # Technology choices │ ├── roadmap.md # Development phases │ └── decisions.md # Decision log ├── specs/ │ └── README.md # Spec index ├── standards/ │ ├── code-style.md # Coding guidelines │ └── testing.md # Testing guidelines └── instructions/ ├── create-spec.md # How to create specs └── execute-tasks.md # How to execute tasks

Core Templates

1. mission.md

Mission: [Project Name]

[One-line pitch describing the project's core purpose]

Product Pitch

[2-3 paragraph description of what the product does, why it exists, and what problem it solves]

Target Users

Primary Users

• [User Type 1]: [Description and needs]
• [User Type 2]: [Description and needs]

Secondary Users

• [User Type 3]: [Description and needs]

Pain Points Addressed

Before This Product

1. [Pain Point 1]: [Description of the problem]
2. [Pain Point 2]: [Description of the problem]
3. [Pain Point 3]: [Description of the problem]

After This Product

1. [Solution 1]: [How this product solves the problem]
2. [Solution 2]: [How this product solves the problem]
3. [Solution 3]: [How this product solves the problem]

Success Metrics

Differentiators

What Makes This Unique

1. [Differentiator 1]: [Description]
2. [Differentiator 2]: [Description]
3. [Differentiator 3]: [Description]

Competitive Landscape

• [Competitor 1]: [How we differ]
• [Competitor 2]: [How we differ]

Non-Goals

Things explicitly out of scope:

• [Non-goal 1]
• [Non-goal 2]
• [Non-goal 3]

Last Updated: [Date] Version: 1.0.0

2. tech-stack.md

Tech Stack: [Project Name]

Technical architecture and technology choices

Overview

Core Technologies

Python 3.11+

Why: Modern async support, performance improvements, type hints Usage: All source code in src/

UV Package Manager

Why: 10-100x faster than pip, reliable lockfiles Usage: uv venv, uv pip install

pytest

Why: Industry standard, excellent fixtures, plugins Usage: All tests in tests/

Plotly

Why: Interactive plots, HTML export, professional appearance Usage: All visualizations must be interactive (no static matplotlib)

Pandas

Why: Data manipulation, time series, CSV handling Usage: Data loading and transformation

Development Tools

Infrastructure

Version Control

• Git: Source control
• GitHub: Remote repository
• Branch Strategy: main → feature branches → PR

CI/CD

• GitHub Actions: Automated testing
• Coverage: Minimum 80%

Data Storage

External Dependencies

APIs

Services

Decision Rationale

Why Python?

• Strong ecosystem for data analysis
• Excellent library support (Pandas, NumPy, Plotly)
• Team expertise
• Integration with existing tools

Why UV over pip?

• Significantly faster installation
• Reliable dependency resolution
• Lockfile support
• workspace-hub standard

Why Plotly over Matplotlib?

• Interactive by default
• Better HTML export
• Modern API
• workspace-hub HTML reporting standard

Last Updated: [Date] Version: 1.0.0

3. roadmap.md

Roadmap: [Project Name]

Development phases and milestones

Vision

[Long-term vision for the product - where it will be in 1-2 years]

Current Phase

Phase [N]: [Phase Name]

• Status: [In Progress / Planning / Complete]
• Target: [Date]
• Progress: [X]%

Phase Overview

Phase 1: Foundation [████████████████████] 100% Phase 2: Core Features [████████████░░░░░░░░] 60% Phase 3: Enhancement [░░░░░░░░░░░░░░░░░░░░] 0% Phase 4: Scale [░░░░░░░░░░░░░░░░░░░░] 0% Phase 5: Optimization [░░░░░░░░░░░░░░░░░░░░] 0%

Detailed Phases

Phase 1: Foundation ✅

Goal: Establish project structure and basic functionality Duration: 2 weeks

Deliverables

• Project structure setup
• Basic configuration
• Core module implementation
• Initial test coverage (80%+)
• Documentation framework

Key Outcomes

• Working development environment
• Basic functionality operational
• CI/CD pipeline configured

Phase 2: Core Features 🚧

Goal: Implement primary feature set Duration: 4 weeks

Deliverables

• Feature A implementation
• Feature B implementation
• Feature C implementation
• Integration testing
• Documentation complete

Key Outcomes

• Primary use cases supported
• User-facing functionality complete
• Quality standards met

Phase 3: Enhancement 📋

Goal: Add secondary features and improvements Duration: 3 weeks

Deliverables

• Advanced Feature D
• Performance optimizations
• Additional integrations
• Extended test coverage
• User documentation

Key Outcomes

• Feature-complete product
• Performance targets met
• Full documentation

Phase 4: Scale 📋

Goal: Prepare for production scale Duration: 2 weeks

Deliverables

• Performance testing
• Load testing
• Security review
• Deployment automation
• Monitoring setup

Key Outcomes

• Production-ready
• Monitoring operational
• Runbook complete

Phase 5: Optimization 📋

Goal: Continuous improvement Duration: Ongoing

Deliverables

• User feedback integration
• Performance tuning
• Technical debt reduction
• Feature iteration

Key Outcomes

• Improved user satisfaction
• Better performance
• Reduced maintenance burden

Milestones

Risks and Mitigations

Dependencies

External

• [Dependency 1]: Required for [Feature]
• [Dependency 2]: Required for [Feature]

Internal

• [Team/Resource 1]: [What's needed]
• [Team/Resource 2]: [What's needed]

Last Updated: [Date] Version: 1.0.0

4. decisions.md

Decision Log: [Project Name]

Record of architectural and design decisions

How to Use This Document

Document significant technical decisions using the format below. Include context, options considered, and rationale.

Decision Template

### DEC-XXX: [Decision Title]
**Date**: YYYY-MM-DD
**Status**: [Proposed | Accepted | Deprecated | Superseded]
**Deciders**: [Names or roles]

#### Context
[What is the issue or opportunity?]

#### Options Considered
1. **Option A**: [Description]
   - Pros: [Benefits]
   - Cons: [Drawbacks]

2. **Option B**: [Description]
   - Pros: [Benefits]
   - Cons: [Drawbacks]

#### Decision
[Which option was chosen and why]

#### Consequences
- Positive: [Good outcomes]
- Negative: [Trade-offs accepted]

#### Related
- [Links to related decisions, issues, docs]

Decisions

DEC-001: Package Manager Selection

Date: 2026-01-01
Status: Accepted
Deciders: Engineering Team

Context

Need to select a Python package manager for dependency management across the project.

Options Considered

- 
pip + requirements.txt

- Pros: Universal, simple

- Cons: Slow, no lockfile

- 
poetry

- Pros: Modern, lockfile support

- Cons: Slower than UV

- 
UV

- Pros: Very fast, lockfiles, drop-in pip replacement

- Cons: Newer tool

Decision

Use UV as the primary package manager.

Consequences

- Positive: 10-100x faster installations, reliable builds

- Negative: Team needs to learn UV commands

DEC-002: Visualization Library

Date: 2026-01-01
Status: Accepted
Deciders: Engineering Team

Context

Need to select visualization library for data analysis reports.

Options Considered

- 
Matplotlib

- Pros: Widely used, flexible

- Cons: Static images, complex API

- 
Plotly

- Pros: Interactive, HTML export, modern

- Cons: Larger bundle size

- 
Altair

- Pros: Declarative, clean syntax

- Cons: Less flexible than Plotly

Decision

Use Plotly for all visualizations.

Consequences

- Positive: Interactive reports, better user experience

- Negative: No static image export (design decision)

- Note: Aligns with workspace-hub HTML reporting standards

DEC-003: Testing Framework

Date: 2026-01-01
Status: Accepted
Deciders: Engineering Team

Context

Need to select testing framework for the project.

Options Considered

- 
unittest

- Pros: Built-in, no dependencies

- Cons: Verbose, limited features

- 
pytest

- Pros: Fixtures, plugins, markers, excellent output

- Cons: External dependency

Decision

Use pytest with pytest-cov for coverage.

Consequences

- Positive: Better developer experience, powerful fixtures

- Negative: Additional dependency (acceptable trade-off)

Pending Decisions

DEC-004: [Pending Decision Title]

Date: Pending
Status: Proposed

[Description of pending decision]

Last Updated: [Date]
Total Decisions: 3 Accepted, 1 Pending

## Usage Examples

### Example 1: New Project Setup

```bash
# Generate complete .agent-os
/agent-os-framework

# Creates:
# - .agent-os/product/mission.md
# - .agent-os/product/tech-stack.md
# - .agent-os/product/roadmap.md
# - .agent-os/product/decisions.md
# - .agent-os/specs/README.md
# - .agent-os/standards/code-style.md
# - .agent-os/instructions/create-spec.md

Example 2: Update Existing

# Add missing components
/agent-os-framework --update

# Only creates files that don't exist

Execution Checklist

Initial Setup:

-  Create .agent-os directory

-  Generate product/ documents

-  Generate specs/ structure

-  Generate standards/

-  Generate instructions/

Content Review:

-  Update mission with actual project details

-  Fill in tech-stack choices

-  Define roadmap phases

-  Document initial decisions

Best Practices

- Keep mission current - Review quarterly

- Document decisions promptly - When made, not later

- Update roadmap status - Weekly or bi-weekly

- Reference in CLAUDE.md - Link from root config

Related Skills

- repo-readiness - Validates .agent-os

- python-project-template - Creates initial structure

References

- Agent OS Framework

- workspace-hub Standards

Version History

- 1.0.0 (2026-01-14): Initial release - .agent-os framework with mission, tech-stack, roadmap, and decisions