diegosouzapw 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
| Metric | Current | Target | Timeframe |
|--------|---------|--------|-----------|
| [Metric 1] | [Current value] | [Target value] | [When] |
| [Metric 2] | [Current value] | [Target value] | [When] |
| [Metric 3] | [Current value] | [Target value] | [When] |
## 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
| Category | Technology | Version | Purpose |
|----------|-----------|---------|---------|
| Language | Python | 3.11+ | Primary development |
| Package Manager | UV | Latest | Fast dependency management |
| Testing | pytest | 7.4+ | Test framework |
| Visualization | Plotly | 5.15+ | Interactive charts |
| Data | Pandas | 2.0+ | Data processing |
## 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
| Tool | Purpose | Configuration |
|------|---------|---------------|
| ruff | Linting | pyproject.toml |
| black | Formatting | pyproject.toml |
| mypy | Type checking | pyproject.toml |
| pytest-cov | Coverage | pytest.ini |
## 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
| Type | Location | Format |
|------|----------|--------|
| Raw data | data/raw/ | CSV, JSON |
| Processed | data/processed/ | CSV, Parquet |
| Results | data/results/ | CSV, JSON |
| Reports | reports/ | HTML |
## External Dependencies
### APIs
- [API 1]: [Purpose]
- [API 2]: [Purpose]
### Services
- [Service 1]: [Purpose]
- [Service 2]: [Purpose]
## 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
- [x] Project structure setup
- [x] Basic configuration
- [x] Core module implementation
- [x] Initial test coverage (80%+)
- [x] 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
- [x] Feature A implementation
- [x] 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
| Milestone | Target Date | Status |
|-----------|------------|--------|
| MVP Complete | [Date] | ✅ |
| Beta Release | [Date] | 🚧 |
| Production Release | [Date] | 📋 |
| Feature Complete | [Date] | 📋 |
## Risks and Mitigations
| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| [Risk 1] | Medium | High | [Mitigation strategy] |
| [Risk 2] | Low | Medium | [Mitigation strategy] |
| [Risk 3] | High | Low | [Mitigation strategy] |
## 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
```markdown
### 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
Version History
- 1.0.0 (2026-01-14): Initial release - .agent-os framework with mission, tech-stack, roadmap, and decisions