agent-os-framework

What this skill does

# Agent OS Framework

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

## Quick Start

```bash
# 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:

1. **product/** - Core product documentation
2. **specs/** - Feature specifications
3. **standards/** - Code style guidelines
4. **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

```markdown
# 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

```markdown
# 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

```markdown
# 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 Compl