Team Lead Perspective: OAC User Scenarios

Date: 2026-02-14
Role: Engineering Team Lead (5-10 developers)
Focus: Standardization, reproducibility, collaboration, governance

Executive Summary

As a team lead managing 5-10 developers, OAC needs to solve team coordination problems, not just individual developer productivity. This document outlines critical team workflows, pain points, and must-have features for successful team adoption.

Key Requirements:

🔒 Reproducibility: Same setup across all team members
📋 Standardization: Enforce coding standards and agent behavior
👥 Collaboration: Easy sharing of agents and configurations
🔍 Visibility: Track who has what installed
🚀 Onboarding: Get new hires productive in hours, not days
🛡️ Governance: Policy enforcement without micromanagement

1. Team Workflows

1.1 Onboarding New Team Members

Scenario: Sarah joins the team on Monday. She needs to be productive by Wednesday.

Current Reality (Without OAC):

# Day 1: Setup chaos
- Clone repo ✓
- Install dependencies (npm install) ✓
- Read README... wait, which version of Claude Code?
- Copy .cursorrules from teammate's Slack message
- Manually set up agents... which ones?
- Configure approval gates... how?
- Add custom team agents... where are they?
- Day 1 ends: 50% set up, confused about what's missing

# Day 2: Troubleshooting
- "My agent doesn't have the team's code quality standards"
- "Where do I get the React specialist agent?"
- "Why does my setup look different from John's?"
- Senior dev spends 2 hours helping

# Day 3: Finally productive (maybe)

With OAC (Team Standard Workflow):

# Day 1 Morning: 15 minutes to full setup
cd ~/Projects/company-frontend
oac install --frozen

# OAC reads oac.lock (committed to repo)
📦 Installing Team Configuration
  
  Reading lockfile: oac.lock
  Team: Frontend Team
  Last updated: 2026-02-10 by john@company.com
  
  Components (exact versions):
  ✓ agent:openagent@0.7.1
  ✓ agent:frontend-specialist@1.2.0
  ✓ agent:tester@2.0.1
  ✓ context:team-standards@1.0.0
  ✓ context:react-patterns@1.5.0
  ✓ skill:git-workflow@0.8.0
  
  Total: 6 components
  
? Install for which IDE?
  ✓ OpenCode
  > Cursor

? Install location?
  > Local (this project: ~/Projects/company-frontend/.opencode)
    Global (~/.config/oac)

⚡ Installing...
  ✓ All components installed
  ✓ Team standards applied
  ✓ Approval gates configured
  ✓ Git hooks installed

✅ Setup complete!

📊 Your setup matches team standard (100%)

🔍 Next steps:
  1. Review team standards: oac context show team-standards
  2. Test your setup: oac doctor
  3. Start coding!
  
💡 Questions? Ask in #engineering-setup

Result: Sarah is productive in 15 minutes. Zero configuration drift.

1.2 Standardizing Agent Configurations

Scenario: Team lead wants all developers using same agent behavior (approval gates, context loading, etc.)

Challenge: Different developers have different preferences, but team needs consistency

Team Standard Configuration (oac-team.json):

{
  "version": "1.0.0",
  "team": {
    "name": "Frontend Team",
    "owner": "john@company.com",
    "enforced": true
  },
  "components": {
    "agents": [
      {
        "name": "openagent",
        "version": "0.7.1",
        "required": true,
        "config": {
          "behavior": {
            "approvalGates": true,
            "contextLoading": "lazy",
            "delegationThreshold": 4
          },
          "permissions": {
            "bash": "approve",
            "write": "approve",
            "edit": "approve",
            "task": "approve"
          }
        }
      },
      {
        "name": "frontend-specialist",
        "version": "1.2.0",
        "required": true,
        "config": {
          "frameworks": ["react", "nextjs"],
          "typescript": true,
          "testingLibrary": "vitest"
        }
      },
      {
        "name": "tester",
        "version": "2.0.1",
        "required": false,
        "recommendedFor": ["senior-devs"]
      }
    ],
    "contexts": [
      {
        "name": "team-standards",
        "version": "1.0.0",
        "required": true,
        "description": "Company coding standards and best practices"
      },
      {
        "name": "react-patterns",
        "version": "1.5.0",
        "required": true,
        "description": "Approved React patterns for this project"
      }
    ],
    "skills": [
      {
        "name": "git-workflow",
        "version": "0.8.0",
        "required": true,
        "description": "Company git workflow (branch naming, commit style)"
      }
    ]
  },
  "policies": {
    "allowCustomization": true,
    "allowAdditionalAgents": true,
    "enforceVersions": true,
    "requireLockfile": true,
    "auditChanges": true
  },
  "validation": {
    "frequency": "on-install",
    "strictMode": false,
    "warnOnDrift": true
  }
}

Team Lead Workflow:

# 1. Create team configuration
oac team init
? Team name: Frontend Team
? Owner email: john@company.com
? Enforce configuration? (Y/n) y

✓ Created: oac-team.json

# 2. Add required components
oac team add agent:openagent@0.7.1 --required
oac team add agent:frontend-specialist@1.2.0 --required
oac team add context:team-standards@1.0.0 --required

# 3. Configure policies
oac team policy set enforceVersions true
oac team policy set allowCustomization true

# 4. Generate lockfile
oac lock
✓ Created: oac.lock (based on team config)

# 5. Commit to repo
git add oac-team.json oac.lock
git commit -m "Add team OAC configuration"
git push

# 6. Announce to team
echo "Team: Please run 'oac install --frozen' to sync with team standard"

Developer Experience:

# Developer pulls latest
git pull

# OAC detects team config
⚠ Team configuration detected
  
  Your setup differs from team standard:
  - agent:openagent: 0.6.5 (team: 0.7.1) ⚠
  - context:team-standards: missing ❌
  - skill:git-workflow: missing ❌
  
? Update to team standard? (Y/n) y

⚡ Updating to team standard...
  ✓ agent:openagent: 0.6.5 → 0.7.1
  ✓ context:team-standards: installed
  ✓ skill:git-workflow: installed

✅ Your setup now matches team standard (100%)

1.3 Sharing Custom Agents/Presets

Scenario: Senior dev creates amazing custom agent, wants to share with team

Without OAC:

Copy/paste agent file in Slack
Everyone manually copies to their .opencode folder
Updates? Manually notify everyone
Who has it installed? No idea
Version drift inevitable

With OAC:

# Senior dev creates custom agent
cd ~/Projects/company-frontend
oac create agent review-specialist

# ... edits agent prompt ...

# Package for team
oac team share agent:review-specialist
? Share with:
  > Current team (Frontend Team)
    Entire organization
    Specific team members

? Access level:
  > Recommended (team members can install)
    Required (auto-installed for everyone)
    Optional (discoverable in team registry)

✓ Shared: agent:review-specialist
✓ Added to team registry
✓ Slack notification sent to #frontend-team

📊 Analytics:
  - Available to: 8 team members
  - Auto-installed for: 0 (recommended only)
  
💡 Team members can install with:
    oac team install agent:review-specialist

Team Member Experience:

# Check team-shared components
oac team browse

┌─────────────────────────────────────────────────────┐
│  Team Components (Frontend Team)                    │
├─────────────────────────────────────────────────────┤
│  Agents:                                            │
│  ✓ review-specialist (recommended)                  │
│    By: john@company.com                             │
│    Downloads: 3/8 team members                      │
│    "Enhanced code review with team standards"       │
│                                                     │
│  Contexts:                                          │
│  ✓ team-standards (required)                        │
│    By: john@company.com                             │
│    Installed: 8/8 team members                      │
└─────────────────────────────────────────────────────┘

# Install recommended agent
oac team install agent:review-specialist
✓ Installed: agent:review-specialist@1.0.0
✓ Added to your local config

1.4 Enforcing Coding Standards

Scenario: Team lead wants to ensure all code follows team standards

Team Standards Context (.oac/team/contexts/team-standards.md):

# Frontend Team Coding Standards

## React Patterns

### Component Structure
- Use functional components with hooks
- No class components (legacy only)
- Props interface above component
- Export at bottom of file

### State Management
- Use Zustand for global state
- No Redux (legacy projects only)
- Local state with useState for UI state

### Testing
- Vitest for unit tests
- Playwright for e2e tests
- Minimum 80% coverage for new code
- Test files: *.test.tsx

### File Structure

components/ Button/

Button.tsx
Button.test.tsx
Button.stories.tsx
index.ts


## Git Workflow

### Branch Naming
- feature/JIRA-123-short-description
- fix/JIRA-123-short-description
- chore/JIRA-123-short-description

### Commit Messages
- feat: Add user authentication
- fix: Fix login button not working
- chore: Update dependencies

### PR Requirements
- Minimum 1 approval
- All checks must pass
- No merge conflicts
- Linked to Jira ticket

Enforcement Workflow:

# Team lead creates standards context
oac create context team-standards
# ... adds standards content ...

# Make it required
oac team add context:team-standards@1.0.0 --required

# Configure agent to enforce standards
oac team config set agents.openagent.context.required team-standards
oac team config set agents.openagent.strictMode true

# Commit to repo
git add .oac/team/
git commit -m "Add enforced team standards"
git push

Developer Experience:

# Agent automatically loads team standards
> create a new button component

Agent checks team-standards.md:
✓ Using functional component (required)
✓ Creating test file Button.test.tsx (required)
✓ Creating story file Button.stories.tsx (recommended)
✓ Props interface above component (required)

Creating:
  components/Button/
    Button.tsx
    Button.test.tsx
    Button.stories.tsx
    index.ts

✅ Follows team standards

1.5 Managing Updates Across Team

Scenario: New version of openagent released, team lead needs to coordinate update

Without OAC:

Manual announcement: "Everyone update to openagent 0.8.0"
Some update immediately, some forget
Version drift across team
Bugs appear on some machines, not others
Hard to debug: "Works on my machine"

With OAC:

# Team lead checks for updates
oac team update --check

📦 Updates Available for Frontend Team

agent:openagent
  Current: 0.7.1 (team standard)
  Latest:  0.8.0
  
  Changes:
  - Improved delegation logic
  - Fixed approval gate bug
  - New context loading patterns
  
  Impact: 8/8 team members affected
  Breaking: No

? How would you like to proceed?
  > Review changes
    Update team standard
    Skip this update
    
# Review changes
oac diff agent:openagent 0.7.1 0.8.0
[Shows detailed diff]

# Update team standard
oac team update agent:openagent@0.8.0

⚡ Updating team standard...
  ✓ Updated: agent:openagent 0.7.1 → 0.8.0
  ✓ Updated: oac.lock
  ✓ Updated: oac-team.json

? Notify team?
  > Yes, send Slack notification
    No, silent update
    
✓ Slack notification sent to #frontend-team

📊 Update Status:
  - Team standard: 0.8.0
  - Team members on 0.8.0: 0/8
  - Team members on 0.7.1: 8/8
  
💡 Track adoption: oac team status

Team Member Experience:

# Pull latest code (next day)
git pull

⚠ Team standard updated
  
  agent:openagent: 0.7.1 → 0.8.0 (required)
  
  Changes:
  - Improved delegation logic
  - Fixed approval gate bug
  
? Update now? (Y/n) y

⚡ Updating...
  ✓ agent:openagent: 0.7.1 → 0.8.0
  ✓ Backup saved: .oac/backups/openagent-0.7.1.md

✅ Up to date with team standard

# Team lead checks adoption
oac team status

📊 Team Configuration Status
  Team: Frontend Team
  Members: 8
  
  agent:openagent@0.8.0 (required):
    ✓ john@company.com (you)
    ✓ sarah@company.com
    ✓ mike@company.com
    ⏳ jane@company.com (pending)
    ⏳ bob@company.com (pending)
    ❌ alice@company.com (offline)
    ❌ tom@company.com (on vacation)
    ❌ lisa@company.com (needs update)
  
  Adoption: 3/8 (37.5%)
  
💡 Send reminder: oac team remind agent:openagent

2. Key Experiences

2.1 Setting Up Team Standards (First Time)

Persona: John, Senior Frontend Lead, managing 8 developers

Goal: Establish team standards for new React project

Workflow:

# Week 1: Project kickoff
cd ~/Projects/new-frontend
git init
npm init

# Initialize OAC for team
oac team init

Welcome to OAC Team Setup! 👥

? Team name: Frontend Team
? Owner (your email): john@company.com
? Team size: 
  > Small (2-10 developers)
    Medium (11-50 developers)
    Large (50+ developers)

? Primary tech stack:
  ✓ React
  ✓ TypeScript
  ✓ Node.js
  ☐ Python

? Strictness level:
  > Balanced (enforce core standards, allow customization)
    Strict (enforce all standards, minimal customization)
    Flexible (recommend standards, full customization)

✓ Created team configuration

📦 Recommended setup for React + TypeScript team:
  
  Core Agents (required):
  - openagent@0.7.1
  - frontend-specialist@1.2.0
  
  Specialists (recommended):
  - tester@2.0.1
  - reviewer@1.8.0
  
  Contexts (required):
  - core/standards/code-quality
  - development/react-patterns
  
  Skills (recommended):
  - git-workflow
  - testing-workflow

? Install recommended setup? (Y/n) y

⚡ Installing team setup...
  ✓ Installed 4 agents
  ✓ Installed 2 contexts
  ✓ Installed 2 skills
  ✓ Generated oac.lock
  ✓ Generated oac-team.json

✅ Team setup complete!

🔍 Next steps:
  1. Review team config: oac team config show
  2. Customize standards: oac context edit team-standards
  3. Commit to repo: git add .oac/ oac* && git commit
  4. Invite team: Share repo URL
  
💡 Team members run: oac install --frozen

Customization:

# Customize team standards
oac context edit team-standards
[Opens in editor]

# Configure policies
oac team policy set enforceVersions true
oac team policy set allowCustomization true
oac team policy set auditChanges true

# Set up approval gates
oac team config set agents.openagent.permissions.bash approve
oac team config set agents.openagent.permissions.write approve

# Commit team configuration
git add .oac/ oac-team.json oac.lock
git commit -m "Add team OAC configuration

- Team: Frontend Team
- Core agents: openagent, frontend-specialist
- Required contexts: team-standards, react-patterns
- Policies: enforce versions, allow customization
"
git push origin main

# Announce to team
echo "Team setup complete! Clone repo and run 'oac install --frozen'"

2.2 Ensuring Everyone Has Same Setup

Scenario: New sprint starts, team lead wants to verify everyone is in sync

Team Lead Workflow:

# Check team configuration status
oac team status --detailed

📊 Frontend Team Configuration Status
  Updated: 2026-02-10 10:30 AM
  Members: 8
  
┌─────────────────────┬──────────┬────────────┬──────────┐
│ Component           │ Required │ Version    │ Adoption │
├─────────────────────┼──────────┼────────────┼──────────┤
│ openagent           │ Yes      │ 0.7.1      │ 8/8 ✓    │
│ frontend-specialist │ Yes      │ 1.2.0      │ 7/8 ⚠    │
│ tester              │ No       │ 2.0.1      │ 5/8      │
│ team-standards      │ Yes      │ 1.0.0      │ 8/8 ✓    │
│ react-patterns      │ Yes      │ 1.5.0      │ 7/8 ⚠    │
└─────────────────────┴──────────┴────────────┴──────────┘

⚠ Issues:
  - bob@company.com: Missing frontend-specialist@1.2.0
  - bob@company.com: Missing react-patterns@1.5.0

? Actions:
  > Send reminder to bob@company.com
    Generate compliance report
    View detailed per-member status
    
# View per-member status
oac team members

┌────────────────────┬──────────┬────────────┬────────────┐
│ Member             │ Status   │ Compliance │ Last Sync  │
├────────────────────┼──────────┼────────────┼────────────┤
│ john@company.com   │ ✓ Active │ 100%       │ Today      │
│ sarah@company.com  │ ✓ Active │ 100%       │ Today      │
│ mike@company.com   │ ✓ Active │ 100%       │ Yesterday  │
│ jane@company.com   │ ✓ Active │ 100%       │ Today      │
│ bob@company.com    │ ⚠ Drift  │ 75%        │ 3 days ago │
│ alice@company.com  │ ✓ Active │ 100%       │ Today      │
│ tom@company.com    │ ⏳ Away  │ 100%       │ Last week  │
│ lisa@company.com   │ ✓ Active │ 100%       │ Today      │
└────────────────────┴──────────┴────────────┴────────────┘

# Send reminder to specific member
oac team remind bob@company.com

📧 Reminder sent to bob@company.com

Subject: Update your OAC setup (Frontend Team)
  
Missing components:
- frontend-specialist@1.2.0 (required)
- react-patterns@1.5.0 (required)

Please run: oac install --frozen

# Generate compliance report
oac team report --export team-compliance.md

✓ Generated: team-compliance.md

📄 Team Compliance Report
  Date: 2026-02-14
  Team: Frontend Team
  
  Overall Compliance: 93.75% (7.5/8 members)
  
  Required Components:
  - All members have: openagent, team-standards
  - Missing from 1 member: frontend-specialist, react-patterns
  
  Recommended Actions:
  1. Follow up with bob@company.com
  2. Consider reminder automation
  
  Compliance Trend:
  - Last week: 87.5%
  - This week: 93.75%
  - Change: +6.25% ✓

Developer Self-Check:

# Developer checks their own compliance
oac team validate

📊 Validating your setup against team standard...

Team: Frontend Team
Your compliance: 100% ✓

Required components:
✓ openagent@0.7.1
✓ frontend-specialist@1.2.0
✓ team-standards@1.0.0
✓ react-patterns@1.5.0

Recommended components:
✓ tester@2.0.1
✓ git-workflow@0.8.0

✅ Your setup matches team standard

# Developer has drift
oac team validate

📊 Validating your setup against team standard...

Team: Frontend Team
Your compliance: 75% ⚠

Required components:
✓ openagent@0.7.1
❌ frontend-specialist: missing (required)
✓ team-standards@1.0.0
❌ react-patterns: missing (required)

? Fix issues now? (Y/n) y

⚡ Installing missing components...
  ✓ frontend-specialist@1.2.0
  ✓ react-patterns@1.5.0

✅ Your setup now matches team standard (100%)

2.3 Reviewing Team's Agent Usage

Scenario: Team lead wants insights into how team uses agents

Analytics Dashboard:

oac team analytics

📊 Frontend Team Analytics
  Period: Last 30 days
  Members: 8
  
Agent Usage:
┌────────────────────┬───────────┬──────────┬────────────┐
│ Agent              │ Users     │ Sessions │ Avg/Day    │
├────────────────────┼───────────┼──────────┼────────────┤
│ openagent          │ 8/8 (100%)│ 2,340    │ 9.75       │
│ frontend-specialist│ 7/8 (87%) │ 1,890    │ 7.88       │
│ tester             │ 5/8 (62%) │ 450      │ 1.88       │
│ reviewer           │ 3/8 (37%) │ 210      │ 0.88       │
└────────────────────┴───────────┴──────────┴────────────┘

Most Used Features:
1. Code generation (frontend-specialist): 890 sessions
2. Test writing (tester): 340 sessions
3. Code review (reviewer): 210 sessions
4. Refactoring (openagent): 180 sessions

Context Access:
- team-standards: 1,200 loads
- react-patterns: 980 loads
- api-docs: 450 loads

Insights:
💡 reviewer is underused (37% adoption)
   → Consider team training or review workflow update
   
💡 tester usage spiking (+40% this week)
   → Positive trend, sprint deadline approaching
   
💡 frontend-specialist high usage (87%)
   → Good adoption, consider advanced features

? Actions:
  > Export detailed report
    Schedule weekly digest
    View per-member analytics

Per-Member Analytics:

oac team analytics --member sarah@company.com

📊 Analytics: sarah@company.com
  Period: Last 30 days
  
Activity Summary:
- Total sessions: 342
- Agents used: 4
- Most active: Weekdays 9am-5pm
- Avg sessions/day: 11.4

Agent Breakdown:
1. frontend-specialist: 180 sessions (52%)
2. openagent: 120 sessions (35%)
3. tester: 30 sessions (9%)
4. reviewer: 12 sessions (4%)

Top Actions:
- Component creation: 45 times
- Test writing: 30 times
- Code refactoring: 25 times
- Bug fixing: 20 times

Productivity Metrics:
- Code commits: 87
- PRs created: 23
- Tests added: 156
- Reviews given: 18

Comparison to team average:
- Sessions: +15% above average
- Test coverage: +10% above average
- PR activity: Average

2.4 Handling Version Conflicts

Scenario: Project uses openagent@0.7.1 but new dependency requires openagent@0.8.0

Conflict Detection:

# Developer tries to add new agent
oac add agent:new-specialist

⚠ Version Conflict Detected

Package: agent:new-specialist
Requires: agent:openagent@^0.8.0

Your setup:
  agent:openagent@0.7.1 (from team standard)

Team standard:
  agent:openagent@0.7.1 (locked)

? How would you like to resolve?
  > Request team update (contact team lead)
    Use compatible version (find alternative)
    Override locally (breaks team standard)
    Cancel installation

# Option 1: Request team update
? Request team update
  
📧 Request sent to team lead (john@company.com)

Subject: Version conflict resolution needed
  
Developer: sarah@company.com
Requested component: agent:new-specialist
Conflict: Requires openagent@0.8.0, team has 0.7.1

Details:
- new-specialist requires openagent@^0.8.0
- Team is on openagent@0.7.1
- Suggested action: Update team standard

# Team lead receives request
oac team requests

📬 Team Requests (1 pending)

1. Version Conflict: openagent@0.7.1 → @0.8.0
   Requested by: sarah@company.com
   Reason: Need agent:new-specialist
   Impact: All team members (8)
   Breaking: No
   
? Action:
  > Approve and update team standard
    Check for team impact first
    Request more info
    Reject (explain why)

# Approve update
oac team approve-request 1

⚡ Approving request...
  ✓ Updated team standard: openagent@0.8.0
  ✓ Updated oac.lock
  ✓ Sent notifications to team

📧 Notifications sent:
  - sarah@company.com: Approved, you can now install
  - Team members (7): Team standard updated, please sync

# Sarah gets notified
✓ Your request was approved!

agent:openagent@0.7.1 → 0.8.0 (team standard updated)

? Install now? (Y/n) y

⚡ Updating...
  ✓ openagent: 0.7.1 → 0.8.0
  ✓ new-specialist: installed

✅ Installation complete

2.5 Migrating to New Versions

Scenario: Team needs to migrate from v0.7.x to v1.0.0 (breaking changes)

Migration Workflow:

# Team lead checks migration path
oac team migrate --check

📦 Migration Available: v0.7.1 → v1.0.0

Breaking Changes:
⚠ Approval gates: Configuration format changed
⚠ Context resolution: New priority system
⚠ Preset system: New metadata format

Migration Steps:
1. Backup current setup
2. Update configuration files
3. Test with subset of team
4. Roll out to full team

Estimated time: 2-4 hours
Estimated effort: Medium

? View detailed migration guide? (Y/n) y

# View migration guide
📚 Migration Guide: v0.7.1 → v1.0.0

### Step 1: Backup
```bash
oac team backup
# Creates: .oac/backups/team-backup-2026-02-14.tar.gz

Step 2: Create Migration Branch

git checkout -b oac-v1-migration

Step 3: Run Migration Tool

oac team migrate --to v1.0.0

⚡ Running migration...
  ✓ Backed up current config
  ✓ Updated configuration format
  ✓ Migrated approval gates config
  ✓ Updated context resolution
  ✓ Migrated presets
  ✓ Generated new lockfile

⚠ Manual steps required:
  1. Review updated configs: .oac/team/
  2. Test locally: oac doctor
  3. Update README with new instructions

? Commit changes? (Y/n) y

✓ Changes committed

Step 4: Test with Pilot Group

# Team lead designates pilot group
oac team pilot add sarah@company.com mike@company.com

📢 Announcement: Pilot Group
  
  Testing v1.0.0 migration
  Pilot members:
  - sarah@company.com
  - mike@company.com
  
  Please:
  1. git checkout oac-v1-migration
  2. oac install --frozen
  3. Test for 1 day
  4. Report issues: #oac-migration
  
? Send notifications? (Y/n) y

# Pilot members test
cd ~/Projects/company-frontend
git checkout oac-v1-migration
oac install --frozen

⚠ Migration Detected: v0.7.1 → v1.0.0

Breaking changes:
- Approval gates config updated
- Context resolution changed
- Presets migrated

? Install v1.0.0? (Y/n) y

⚡ Installing...
  ✓ All components migrated
  ✓ Configuration updated

⚠ Action required:
  - Test approval gates behavior
  - Verify context loading
  - Check presets

💡 Report issues: #oac-migration

# After 1 day of testing
oac team pilot report

📊 Pilot Test Results
  Duration: 1 day
  Participants: 2/2
  
  Feedback:
  ✓ sarah@company.com: No issues, works great
  ✓ mike@company.com: No issues, approval gates clearer
  
  Issues: 0
  Recommendation: Ready for full rollout

? Proceed with full team migration? (Y/n) y

Step 5: Full Team Rollout

# Merge migration branch
git checkout main
git merge oac-v1-migration
git push origin main

# Announce to team
oac team announce

📢 Team Update: OAC v1.0.0 Migration

What: Upgrading to OAC v1.0.0
When: Now
Impact: All team members

Breaking changes:
- Approval gates config (automatically migrated)
- Context resolution (automatically migrated)
- Presets (automatically migrated)

Action required:
1. git pull
2. oac install --frozen
3. Test your workflow
4. Report issues: #oac-migration

Tested by: sarah@company.com, mike@company.com
Estimated time: 5 minutes

? Send to team? (Y/n) y

✓ Sent to #frontend-team
✓ Email sent to all members

# Track migration progress
oac team status

📊 Migration Status: v0.7.1 → v1.0.0
  
  Completed: 2/8 (25%)
  In Progress: 3/8 (37.5%)
  Pending: 3/8 (37.5%)
  
  Timeline:
  - Hour 1: 2 completed (sarah, mike)
  - Hour 2: 3 in progress (jane, bob, alice)
  - Pending: tom, lisa, you
  
  Issues: 0
  
💡 Migration going smoothly

3. Pain Points & Solutions

3.1 Developers Using Different Versions

Pain Point:

"Half the team is on openagent 0.7.1, half on 0.8.0. Behavior is inconsistent. Hard to debug issues."

Root Causes:

No enforcement mechanism
Developers update independently
No visibility into team versions
Updates happen out of sync

Solution 1: Version Locking

# Team lead enables strict version enforcement
oac team policy set enforceVersions strict

# oac-team.json
{
  "policies": {
    "enforceVersions": "strict",  // "strict" | "warn" | "off"
    "allowOverrides": false
  }
}

# Developer tries to install different version
oac add agent:openagent@0.8.0

❌ Version Enforcement Error

Team standard requires: agent:openagent@0.7.1
You requested: agent:openagent@0.8.0

Policy: Strict (no overrides allowed)

? Actions:
  > Use team version (0.7.1)
    Request version update from team lead
    Cancel

Solution 2: Automatic Drift Detection

# Enable drift detection
oac team policy set driftDetection enabled

# Developer's setup drifts
# (git pull doesn't update oac)

# On next oac command:
⚠ Configuration Drift Detected

Your setup differs from team standard:
- agent:openagent: 0.6.5 (team: 0.7.1) ⚠

This may cause inconsistent behavior.

? Sync with team standard? (Y/n) y

Solution 3: Pre-commit Hooks

# Team lead enables git hooks
oac team hooks install

✓ Installed git hooks:
  - pre-commit: Check OAC compliance
  - pre-push: Validate team standard

# Developer commits code with drift
git commit -m "Add feature"

⚠ OAC Compliance Check

Your setup differs from team standard:
- agent:openagent: 0.6.5 (team: 0.7.1) ⚠

? How would you like to proceed?
  > Fix now (sync with team)
    Commit anyway (not recommended)
    Cancel commit

3.2 Customizations Breaking Team Standards

Pain Point:

"Bob customized his agent and now he's getting different code suggestions. His PRs don't match team style."

Root Causes:

No visibility into customizations
Developer doesn't realize impact
No enforcement of required contexts

Solution 1: Customization Visibility

# Team lead can see customizations
oac team members --show-customizations

┌────────────────────┬─────────────┬──────────────────────┐
│ Member             │ Compliance  │ Customizations       │
├────────────────────┼─────────────┼──────────────────────┤
│ john@company.com   │ 100%        │ None                 │
│ sarah@company.com  │ 100%        │ None                 │
│ bob@company.com    │ 90% ⚠       │ 2 presets, 1 override│
│ mike@company.com   │ 100%        │ 1 preset (approved)  │
└────────────────────┴─────────────┴──────────────────────┘

# View Bob's customizations
oac team member bob@company.com --customizations

📊 Customizations: bob@company.com

Presets:
- custom-openagent (overrides team agent)
- custom-tester (adds extra behavior)

Context Overrides:
- team-standards (local override)
  ⚠ Warning: Overrides required context

Impact:
- May generate code not matching team standards
- Test patterns may differ
- PR reviews may flag inconsistencies

? Actions:
  > Discuss with bob@company.com
    Request alignment with team standards
    Approve customizations (if beneficial)

Solution 2: Required vs Optional Contexts

# Team lead marks contexts as required (cannot be overridden)
oac team add context:team-standards@1.0.0 --required --locked

# Bob tries to override
cp team-standards.md .oac/context/override/team-standards.md

# Agent tries to load context
⚠ Required Context Override Blocked

Context: team-standards
Status: Required and locked by team lead

You cannot override this context.
Reason: Team consistency (enforced)

Using team version: .oac/team/context/team-standards.md

💡 To suggest changes:
    oac team context propose-change team-standards

Solution 3: Preset Approval Workflow

# Enable preset approval requirement
oac team policy set requirePresetApproval true

# Bob creates preset
oac customize agent:openagent --name my-openagent

✓ Created preset: my-openagent

⚠ Team Policy: Preset approval required

Your preset has been created locally but requires team lead approval to use.

? Submit for approval? (Y/n) y

📧 Approval request sent to john@company.com

# Team lead reviews
oac team approvals

📬 Pending Approvals (1)

1. Preset: my-openagent
   By: bob@company.com
   Base: agent:openagent
   Changes:
   - Modified approval gates (auto-approve reads)
   - Changed delegation threshold (4 → 6)
   
   Impact: Individual only (preset is personal)
   Risk: Low

? Action:
  > Approve for bob@company.com only
    Approve and recommend to team
    Request changes
    Reject

# Approved
✓ Approved preset: my-openagent (bob@company.com only)

📧 bob@company.com notified

3.3 Hard to Track What's Installed Where

Pain Point:

"I have no idea what each team member has installed. Debugging is a nightmare."

Solution: Team Dashboard

# Team lead views comprehensive dashboard
oac team dashboard

╔════════════════════════════════════════════════════╗
║  Frontend Team Dashboard                           ║
║  Updated: 2026-02-14 3:45 PM                      ║
╚════════════════════════════════════════════════════╝

Team Health: 95% ✓

┌─────────────────────────────────────────────────────┐
│ Component Adoption                                  │
├─────────────────────────────────────────────────────┤
│ Required:                                           │
│ ████████████████████ 100%  openagent@0.7.1          │
│ ███████████████████░  95%  frontend-specialist      │
│ ████████████████████ 100%  team-standards           │
│                                                     │
│ Recommended:                                        │
│ ████████████░░░░░░░░  62%  tester                   │
│ ██████░░░░░░░░░░░░░░  37%  reviewer                 │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│ Member Status (8 total)                             │
├─────────────────────────────────────────────────────┤
│ ✓ Compliant (100%):     6 members                   │
│ ⚠ Minor drift (90-99%): 1 member (bob)              │
│ ❌ Major drift (<90%):  1 member (alice, offline)   │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│ Recent Activity (24 hours)                          │
├─────────────────────────────────────────────────────┤
│ • sarah synced with team standard                   │
│ • mike installed reviewer@1.8.0                     │
│ • bob created custom preset (pending approval)      │
│ • jane updated to latest team config                │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│ Alerts (2)                                          │
├─────────────────────────────────────────────────────┤
│ ⚠ bob@company.com has configuration drift          │
│ ⚠ alice@company.com offline 3+ days                │
└─────────────────────────────────────────────────────┘

? Actions:
  > View detailed member status
    Send reminders
    Generate report
    Schedule weekly digest

Solution: Installation Registry

# Automatic installation tracking
# Every install is logged to team registry

oac team registry

📊 Installation Registry (Last 30 days)

2026-02-14 10:30 AM
  sarah@company.com installed frontend-specialist@1.2.0
  Location: ~/Projects/company-frontend/.opencode
  
2026-02-14 09:15 AM
  mike@company.com updated openagent@0.7.0 → 0.7.1
  Location: ~/Projects/company-frontend/.opencode
  
2026-02-13 4:20 PM
  bob@company.com created preset:my-openagent
  Status: Pending approval
  
2026-02-13 2:10 PM
  jane@company.com installed team standard
  Components: 6 (all required)

# Filter by member
oac team registry --member bob@company.com

# Filter by component
oac team registry --component openagent

# Export audit log
oac team registry --export audit-log.csv

3.4 Updates Breaking Team Workflows

Pain Point:

"We updated openagent and everyone's workflow broke. Spent 2 days debugging."

Solution 1: Staged Rollouts

# Team lead enables staged rollouts
oac team policy set rolloutStrategy staged

# Update available
oac team update agent:openagent@0.8.0

? Rollout strategy:
  > Staged (pilot → gradual → full)
    Immediate (all members now)
    Scheduled (pick date/time)

# Staged rollout
⚡ Starting staged rollout: openagent@0.8.0

Stage 1: Pilot (2 members)
  Pilot members:
  - sarah@company.com
  - mike@company.com
  
  Duration: 24 hours
  Start: Now
  
? Proceed? (Y/n) y

✓ Pilot stage started
📧 Notifications sent to pilot members

# 24 hours later: Check pilot results
oac team rollout status

📊 Rollout Status: openagent@0.8.0

Stage 1: Pilot (Complete) ✓
  Duration: 24 hours
  Success: 2/2 members
  Issues: 0
  Feedback: Positive
  
? Proceed to Stage 2 (Gradual)?
  > Yes, continue (50% of team)
    No, pause (investigate)
    Rollback (revert pilot)

# Stage 2: Gradual
Stage 2: Gradual (50% of team)
  Members: 4 more (sarah, mike already on 0.8.0)
  Duration: 48 hours
  
✓ Stage 2 started

# 48 hours later: Final stage
Stage 3: Full (remaining 2 members)
  Final members: bob, alice
  
✓ Rollout complete (100%)

Solution 2: Automatic Rollback

# Team lead enables automatic rollback
oac team policy set autoRollback true
oac team policy set rollbackThreshold 30  # 30% failure rate

# Update deployed
oac team update agent:openagent@0.8.0 --rollout staged

# Problems detected
⚠ Rollback Triggered

Component: agent:openagent@0.8.0
Reason: 40% failure rate (threshold: 30%)

Issues reported:
- sarah@company.com: Approval gates not working
- mike@company.com: Context loading errors
- jane@company.com: Delegation failed

⚡ Rolling back to openagent@0.7.1...

✓ Rollback complete (all members)
📧 Notifications sent
🔍 Issue report created: .oac/issues/rollback-2026-02-14.md

💡 Review issues before next update attempt

Solution 3: Dry Run / Preview

# Before updating team standard
oac team update --dry-run agent:openagent@0.8.0

🔍 Dry Run: Update Preview

Component: agent:openagent
Current: 0.7.1 (team standard)
Target: 0.8.0

Changes:
  ✓ Improved delegation logic
  ✓ Fixed approval gate bug
  ⚠ Breaking: Context loading API changed

Impact Analysis:
  Affected members: 8/8
  Estimated impact: Medium
  Breaking changes: Yes
  Migration required: Yes

Compatibility:
  ✓ Compatible with: frontend-specialist@1.2.0
  ✓ Compatible with: tester@2.0.1
  ⚠ May conflict with: custom-presets (1 member)

Risk Assessment: Medium
  - Breaking changes require testing
  - Bob's custom preset may need updates
  - Migration script available

Recommendations:
  1. Test in pilot first
  2. Review Bob's custom preset
  3. Schedule update during low-activity period
  4. Have rollback plan ready

? Proceed with actual update?
  > No, just previewing
    Yes, start pilot rollout

3.5 Onboarding Takes Too Long

Pain Point:

"New developers spend half a day just setting up their environment. Then they still ask questions."

Solution: One-Command Onboarding

# New developer (Sarah) - Day 1, Hour 1
cd ~/Projects
git clone git@github.com:company/frontend-app.git
cd frontend-app

# Run single onboarding command
oac onboard

╔════════════════════════════════════════════════════╗
║  Welcome to Frontend Team! 👋                      ║
║  Let's get you set up in 5 minutes.               ║
╚════════════════════════════════════════════════════╝

🔍 Detecting configuration...
  ✓ Found team config: oac-team.json
  ✓ Found lockfile: oac.lock
  ✓ Team: Frontend Team
  ✓ Owner: john@company.com

📦 Team Configuration:
  - 4 agents (2 required, 2 recommended)
  - 2 contexts (required)
  - 2 skills (recommended)
  - Approval gates: Enabled
  - IDE: OpenCode (detected .opencode/)

? Confirm installation? (Y/n) y

⚡ Installing team configuration...
  ✓ agent:openagent@0.7.1
  ✓ agent:frontend-specialist@1.2.0
  ✓ agent:tester@2.0.1 (recommended)
  ✓ agent:reviewer@1.8.0 (recommended)
  ✓ context:team-standards@1.0.0
  ✓ context:react-patterns@1.5.0
  ✓ skill:git-workflow@0.8.0
  ✓ skill:testing-workflow@0.5.0
  
✅ Installation complete! (4 minutes 32 seconds)

📊 Setup verification...
  ✓ All required components installed
  ✓ Team standards loaded
  ✓ Approval gates configured
  ✓ Git hooks installed
  ✓ IDE configured

╔════════════════════════════════════════════════════╗
║  You're all set! 🎉                                ║
╚════════════════════════════════════════════════════╝

📚 Next Steps:
  1. Review team standards: oac context show team-standards
  2. Read React patterns: oac context show react-patterns
  3. Test your setup: oac doctor
  4. Start coding: Try creating a component!

💡 Resources:
  - Team wiki: https://wiki.company.com/frontend
  - Ask questions: #frontend-team
  - Team lead: john@company.com

🎯 Your First Task:
  Review this PR for practice:
  https://github.com/company/frontend-app/pull/123

# Setup is complete - Sarah is ready to code!
# Total time: 5 minutes (vs 4 hours previously)

Solution: Interactive Tutorial

# After onboarding, optional tutorial
oac tutorial

╔════════════════════════════════════════════════════╗
║  OAC Team Tutorial (5 minutes)                     ║
╚════════════════════════════════════════════════════╝

Let's learn the basics of working with OAC in a team.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Lesson 1: Your Team Configuration

Your team has a shared configuration (oac-team.json).
This ensures everyone has the same agents and standards.

Try this:
  $ oac team validate

[User runs command]

✓ Great! You're 100% compliant with team standards.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Lesson 2: Team Standards

Your team has coding standards in: team-standards

Try viewing them:
  $ oac context show team-standards

[Shows team standards]

💡 Agents automatically follow these standards when generating code.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Lesson 3: Staying In Sync

Before each sprint, sync with team standard:
  $ oac team sync

Try it now:
  $ oac team sync

✓ Already in sync! You're good to go.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Lesson 4: Getting Help

If you need help:
  - Team commands: oac team --help
  - Ask teammates: #frontend-team
  - Team lead: john@company.com

╔════════════════════════════════════════════════════╗
║  Tutorial Complete! 🎓                             ║
║  You're ready to work with the team.               ║
╚════════════════════════════════════════════════════╝

4. Edge Cases

4.1 Team Member Goes Rogue (Custom Setup)

Scenario: Bob decides to completely customize his setup, ignoring team standards

Detection:

# Bob's setup
oac list

Installed Components:
  ✓ custom-agent (personal, not from team)
  ✓ openagent@0.5.0 (old version, team: 0.7.1)
  ⚠ frontend-specialist: missing (required by team)
  ✓ react-patterns (overridden with custom version)

# Team lead notices in dashboard
oac team status

⚠ Compliance Alert: bob@company.com

Compliance: 40% ❌ (critical)

Issues:
- Using old version: openagent@0.5.0 (team: 0.7.1)
- Missing required: frontend-specialist
- Unauthorized override: react-patterns
- Unapproved custom agent: custom-agent

Impact:
- Code may not follow team standards
- PRs may fail review
- Potential bugs

? Actions:
  > Send compliance alert to bob@company.com
    Schedule 1-on-1 discussion
    Enforce team standard (reset bob's setup)

Resolution Workflow:

# Team lead sends alert
oac team alert bob@company.com

📧 Compliance Alert Sent

To: bob@company.com
Subject: OAC Setup Non-Compliant

Your OAC setup does not match team standards.

Issues:
- Old version: openagent@0.5.0 (team: 0.7.1)
- Missing: frontend-specialist (required)
- Unauthorized override: react-patterns

Impact: Your code may not match team standards

Please run: oac team sync

Questions? Contact john@company.com

# Bob receives alert and syncs
oac team sync

⚠ Configuration Compliance Issue

Your setup differs significantly from team standard.

Compliance: 40% ❌

Required actions:
  ✓ Update openagent: 0.5.0 → 0.7.1
  ✓ Install frontend-specialist@1.2.0
  ✓ Revert react-patterns override

Optional actions:
  ⚠ Remove custom-agent (not approved)

? Sync with team standard? (Y/n) y

⚡ Syncing...
  ✓ Backed up your custom setup
  ✓ Updated to team standard
  ✓ Removed unapproved customizations

✅ You're now compliant (100%)

💬 Your custom setup was backed up to:
    .oac/backups/custom-setup-2026-02-14/

💡 To use custom agents, request approval:
    oac team request-approval custom-agent

Enforcement Options:

# Team lead can enforce different levels
oac team policy set enforcementLevel flexible  # warn only
oac team policy set enforcementLevel balanced   # warn + block critical
oac team policy set enforcementLevel strict     # enforce all

# Strict mode example
# Bob tries to install old version
oac add agent:openagent@0.5.0

❌ Enforcement Policy Violation

Policy: Strict enforcement
Team requires: agent:openagent@0.7.1
You requested: agent:openagent@0.5.0

This action is blocked.

? Actions:
  > Use team version (0.7.1)
    Request exception from team lead
    Learn more about team policy

4.2 Monorepo with Multiple Projects

Scenario: Monorepo with 5 projects, each needs different agent setups

Structure:

company-monorepo/
├── apps/
│   ├── frontend/          # React frontend
│   ├── admin/             # React admin panel
│   ├── mobile/            # React Native
│   └── docs/              # Documentation site
├── packages/
│   ├── ui-components/     # Shared components
│   ├── api-client/        # API client
│   └── utils/             # Utilities
├── oac-workspace.json     # Workspace config
└── package.json

Workspace Configuration (oac-workspace.json):

{
  "version": "1.0.0",
  "workspace": {
    "name": "Company Monorepo",
    "owner": "platform-team@company.com",
    "root": "."
  },
  "projects": {
    "apps/frontend": {
      "profile": "frontend-react",
      "team": "Frontend Team",
      "agents": ["openagent", "frontend-specialist", "tester"],
      "contexts": ["team-standards", "react-patterns"]
    },
    "apps/admin": {
      "profile": "frontend-react",
      "team": "Frontend Team",
      "agents": ["openagent", "frontend-specialist"],
      "contexts": ["team-standards", "react-patterns", "admin-patterns"]
    },
    "apps/mobile": {
      "profile": "react-native",
      "team": "Mobile Team",
      "agents": ["openagent", "mobile-specialist", "tester"],
      "contexts": ["team-standards", "mobile-patterns"]
    },
    "apps/docs": {
      "profile": "documentation",
      "team": "Platform Team",
      "agents": ["openagent", "technical-writer"],
      "contexts": ["team-standards", "docs-style"]
    },
    "packages/*": {
      "profile": "library",
      "team": "Platform Team",
      "agents": ["openagent", "library-specialist"],
      "contexts": ["team-standards", "library-patterns"]
    }
  },
  "shared": {
    "contexts": [".oac/shared/contexts"],
    "config": ".oac/shared/config.json"
  },
  "policies": {
    "inheritShared": true,
    "allowProjectOverrides": true,
    "enforceVersions": true
  }
}

Developer Workflow:

# Working on frontend app
cd apps/frontend
oac install

🏢 Workspace Detected: Company Monorepo

Project: apps/frontend
Profile: frontend-react
Team: Frontend Team

Shared configuration:
  ✓ Workspace config: ../../oac-workspace.json
  ✓ Shared contexts: ../../.oac/shared/contexts

Project configuration:
  ✓ Agents: openagent, frontend-specialist, tester
  ✓ Contexts: team-standards, react-patterns

? Install project configuration? (Y/n) y

⚡ Installing...
  ✓ Shared contexts (workspace)
  ✓ Project agents (apps/frontend)
  ✓ Project contexts (apps/frontend)

✅ Frontend project setup complete

# Move to mobile app
cd ../mobile
oac install

🏢 Workspace Detected: Company Monorepo

⚠ Different project detected

Current setup: apps/frontend (frontend-react)
New project: apps/mobile (react-native)

? Switch to mobile project configuration?
  > Yes, switch (keeps both configs)
    Yes, switch (remove frontend config)
    No, keep current

# Switch (keeps both)
⚡ Installing mobile configuration...
  ✓ Shared contexts (workspace) [already installed]
  ✓ Mobile agents (mobile-specialist)
  ✓ Mobile contexts (mobile-patterns)

✅ Multi-project setup active:
  - apps/frontend (frontend-react)
  - apps/mobile (react-native)

💡 OAC will auto-detect which config to use based on:
    - Current directory
    - File type
    - Context

Workspace Management:

# Team lead manages workspace
oac workspace status

🏢 Company Monorepo - Workspace Status

Projects: 5 active
Teams: 3 (Frontend, Mobile, Platform)
Members: 24

┌─────────────────┬──────────┬────────────┬────────────┐
│ Project         │ Team     │ Members    │ Compliance │
├─────────────────┼──────────┼────────────┼────────────┤
│ apps/frontend   │ Frontend │ 8          │ 95% ✓      │
│ apps/admin      │ Frontend │ 5          │ 100% ✓     │
│ apps/mobile     │ Mobile   │ 6          │ 90% ⚠      │
│ apps/docs       │ Platform │ 2          │ 100% ✓     │
│ packages/*      │ Platform │ 3          │ 100% ✓     │
└─────────────────┴──────────┴────────────┴────────────┘

Shared Components:
  ✓ team-standards: 24/24 (100%)
  ✓ workspace config: 24/24 (100%)

? Actions:
  > View project details
    Update shared configuration
    Sync all projects

4.3 Different Teams Need Different Setups

Scenario: Frontend team needs React specialists, Backend team needs API specialists

Solution: Multi-Team Configuration

// oac-teams.json (workspace root)
{
  "version": "1.0.0",
  "teams": {
    "frontend": {
      "name": "Frontend Team",
      "owner": "john@company.com",
      "members": ["sarah@", "mike@", "jane@", "bob@"],
      "config": {
        "agents": ["openagent", "frontend-specialist", "tester"],
        "contexts": ["team-standards", "react-patterns"],
        "skills": ["git-workflow"]
      },
      "policies": {
        "enforceVersions": true,
        "allowCustomization": true
      }
    },
    "backend": {
      "name": "Backend Team",
      "owner": "alice@company.com",
      "members": ["tom@", "lisa@", "charlie@"],
      "config": {
        "agents": ["openagent", "api-specialist", "database-specialist"],
        "contexts": ["team-standards", "api-patterns", "database-patterns"],
        "skills": ["git-workflow", "api-testing"]
      },
      "policies": {
        "enforceVersions": true,
        "allowCustomization": false
      }
    },
    "mobile": {
      "name": "Mobile Team",
      "owner": "emma@company.com",
      "members": ["frank@", "grace@"],
      "config": {
        "agents": ["openagent", "mobile-specialist"],
        "contexts": ["team-standards", "mobile-patterns"],
        "skills": ["git-workflow", "mobile-testing"]
      }
    }
  },
  "shared": {
    "contexts": ["team-standards"],
    "skills": ["git-workflow"]
  }
}

Cross-Team Developer:

# Sarah works on both frontend and backend
cd ~/Projects/company-monorepo

# Auto-detect team based on project
cd apps/frontend
oac install

🏢 Team Detected: Frontend Team
✓ Installing frontend configuration...

cd ../../backend/api
oac install

🏢 Team Detected: Backend Team

⚠ You're switching teams:
  Current: Frontend Team
  New: Backend Team

Different configurations:
  - Frontend: react-focused agents
  - Backend: API-focused agents

? Install backend configuration?
  > Yes, add backend config (multi-team mode)
    Yes, replace frontend config
    No, keep frontend only

# Multi-team mode
✓ Multi-team mode enabled

Active configurations:
  ✓ Frontend Team (apps/frontend)
  ✓ Backend Team (backend/api)

💡 OAC auto-detects correct config based on directory

4.4 Legacy Projects with Old Agents

Scenario: Maintaining old project with agents from 2 years ago

Challenge:

Old agents (v0.3.x) incompatible with new OAC (v1.0)
Can't update (legacy dependencies)
Need to support both old and new

Solution: Version Pinning & Compatibility Mode

# Legacy project setup
cd ~/Projects/legacy-app

oac install --legacy

⚠ Legacy Project Detected

Project uses old OAC configuration:
  - Agent format: v0.3.x (2 years old)
  - OAC version: 0.3.2 (current: 1.0.0)

? How would you like to proceed?
  > Compatibility mode (use old agents with new OAC)
    Migrate to v1.0 (may require changes)
    Keep old OAC version (not recommended)

# Compatibility mode
✓ Compatibility mode enabled

⚡ Installing with compatibility layer...
  ✓ Loaded legacy agents (v0.3.x format)
  ✓ Applied compatibility transforms
  ✓ Pinned to legacy versions

✅ Legacy project setup complete

⚠ Limitations in compatibility mode:
  - No new features (skills, plugins)
  - Limited context resolution
  - No team features

💡 Consider migration when possible:
    oac migrate --check

Version Coexistence:

# Developer works on both legacy and modern projects
cd ~/Projects/legacy-app
oac install --legacy
# Uses OAC v0.3.x compatibility mode

cd ~/Projects/modern-app
oac install
# Uses OAC v1.0.0 with all features

# OAC maintains separate configs
oac config list

Configurations:
  ✓ ~/Projects/modern-app: OAC v1.0.0 (standard)
  ✓ ~/Projects/legacy-app: OAC v0.3.x (legacy compat)

💡 Each project uses correct version automatically

4.5 Remote Team Across Timezones

Scenario: Team spread across US (PST), Europe (CET), and Asia (IST)

Challenge:

Updates roll out during work hours for some, sleep hours for others
Hard to coordinate synchronous changes
Need async-friendly workflows

Solution: Scheduled Rollouts & Async Notifications

# Team lead schedules update
oac team update agent:openagent@0.8.0 --schedule

? Rollout strategy:
  > Timezone-aware (roll out during work hours)
    Scheduled (specific date/time)
    Immediate (all members now)

# Timezone-aware rollout
📅 Timezone-Aware Rollout

Team members by timezone:
  - PST (US West): 3 members
  - CET (Europe): 3 members
  - IST (Asia): 2 members

? Rollout window:
  > During work hours (9am-5pm local time)
    Weekdays only
    Custom schedule

# During work hours
✓ Scheduled rollout:
  
  PST (9am-5pm): Tue Feb 14, 9am PST
    - sarah@company.com
    - mike@company.com
    - bob@company.com
  
  CET (9am-5pm): Tue Feb 14, 9am CET (12am PST)
    - alice@company.com
    - tom@company.com
    - lisa@company.com
  
  IST (9am-5pm): Tue Feb 14, 9am IST (Sat 7:30pm PST)
    - frank@company.com
    - grace@company.com

📧 Notifications:
  - Email: Sent to all members (async)
  - Slack: Posted to #frontend-team (async)
  - Calendar: Added to team calendar

? Confirm schedule? (Y/n) y

✓ Rollout scheduled

Async Update Process:

# Sarah (PST) starts work Tuesday 9am
cd ~/Projects/company-frontend

⚠ Team Update Available

Component: agent:openagent@0.8.0
Scheduled: Today 9am PST (now)

? Install update now? (Y/n) y

# Alice (CET) starts work Tuesday 9am (CET time)
cd ~/Projects/company-frontend

⚠ Team Update Available

Component: agent:openagent@0.8.0
Scheduled: Today 9am CET (now)

? Install update now? (Y/n) y

# Both update during their local work hours
# Team lead sees progress across timezones

oac team rollout status

📊 Rollout Progress: openagent@0.8.0

┌──────────┬─────────┬──────────┬────────────┐
│ Timezone │ Members │ Updated  │ Status     │
├──────────┼─────────┼──────────┼────────────┤
│ PST      │ 3       │ 3/3 ✓    │ Complete   │
│ CET      │ 3       │ 2/3 ⏳   │ In progress│
│ IST      │ 2       │ 0/2      │ Scheduled  │
└──────────┴─────────┴──────────┴────────────┘

Overall: 5/8 (62.5%)
Expected completion: Wed Feb 15, 5pm IST

💡 All timezone windows respected

5. Must-Have Features

5.1 Lockfile for Reproducibility

Feature: oac.lock ensures exact same setup across all team members

Format:

{
  "version": "1.0.0",
  "lockfileVersion": 1,
  "team": {
    "name": "Frontend Team",
    "owner": "john@company.com",
    "generated": "2026-02-14T10:30:00Z"
  },
  "components": {
    "agent:openagent": {
      "version": "0.7.1",
      "resolved": "https://registry.openagents.dev/agents/openagent-0.7.1.tar.gz",
      "integrity": "sha256-abc123...",
      "dependencies": {
        "context:core-standards": "^1.0.0"
      }
    },
    "agent:frontend-specialist": {
      "version": "1.2.0",
      "resolved": "https://registry.openagents.dev/agents/frontend-specialist-1.2.0.tar.gz",
      "integrity": "sha256-def456...",
      "dependencies": {
        "context:react-patterns": "^1.5.0"
      }
    }
  },
  "metadata": {
    "platform": "darwin",
    "oacVersion": "1.0.0",
    "node": "18.16.0"
  }
}

Usage:

# Generate lockfile
oac lock
✓ Generated: oac.lock

# Install from lockfile (exact versions)
oac install --frozen
✓ Installing exact versions from oac.lock

# Verify lockfile integrity
oac lock verify
✓ All components match lockfile

# Update lockfile after changes
oac lock update
✓ Updated: oac.lock

Benefits:

✅ Reproducible installs across team
✅ No version drift
✅ CI/CD friendly
✅ Audit trail

5.2 Shared Team Configurations

Feature: Team config repository for centralized management

Setup:

# Team lead creates shared config repo
git init oac-team-configs
cd oac-team-configs

# Initialize team configs
oac team init --repo

✓ Created team config repository

Structure:
  teams/
    frontend/
      config.json
      agents/
      contexts/
      skills/
    backend/
      config.json
      agents/
      contexts/

# Publish to GitHub
git remote add origin git@github.com:company/oac-team-configs.git
git push -u origin main

# Team members link to shared configs
cd ~/Projects/company-frontend
oac team link git@github.com:company/oac-team-configs.git

✓ Linked to shared team config
✓ Auto-sync enabled

💡 Changes to team config will auto-update on pull

Auto-Sync:

# Team lead updates shared config
cd oac-team-configs/teams/frontend
oac team add agent:new-specialist@1.0.0
git commit -m "Add new-specialist to team config"
git push

# Team members auto-sync
cd ~/Projects/company-frontend
git pull  # Pulls project code

⚠ Team Configuration Updated

Shared config has new changes:
  + agent:new-specialist@1.0.0

? Sync with team config? (Y/n) y

✓ Synced with team configuration

5.3 Audit Trail (Who Installed What)

Feature: Complete audit log of all team installations and changes

Audit Log (.oac/team/audit.log):

{
  "version": "1.0.0",
  "team": "Frontend Team",
  "entries": [
    {
      "timestamp": "2026-02-14T10:30:00Z",
      "member": "sarah@company.com",
      "action": "install",
      "component": "agent:frontend-specialist",
      "version": "1.2.0",
      "location": "~/Projects/company-frontend/.opencode",
      "source": "team-standard",
      "success": true
    },
    {
      "timestamp": "2026-02-14T09:15:00Z",
      "member": "mike@company.com",
      "action": "update",
      "component": "agent:openagent",
      "versionFrom": "0.7.0",
      "versionTo": "0.7.1",
      "source": "team-update",
      "success": true
    },
    {
      "timestamp": "2026-02-13T16:20:00Z",
      "member": "bob@company.com",
      "action": "create-preset",
      "component": "preset:my-openagent",
      "base": "agent:openagent",
      "approved": false,
      "success": true
    }
  ]
}

Query Audit Log:

# View recent activity
oac team audit

📊 Team Audit Log (Last 7 days)

2026-02-14 10:30 AM - sarah@company.com
  Installed: agent:frontend-specialist@1.2.0
  Source: team-standard
  
2026-02-14 09:15 AM - mike@company.com
  Updated: agent:openagent 0.7.0 → 0.7.1
  Source: team-update
  
2026-02-13 4:20 PM - bob@company.com
  Created: preset:my-openagent
  Status: Pending approval

# Filter by member
oac team audit --member bob@company.com

# Filter by action
oac team audit --action install

# Filter by component
oac team audit --component openagent

# Export audit report
oac team audit --export audit-report-2026-02.csv

5.4 Policy Enforcement

Feature: Configurable policies for team governance

Policy Configuration:

{
  "policies": {
    "versioning": {
      "enforceVersions": true,        // Require exact versions
      "allowBeta": false,             // Block beta versions
      "requireLockfile": true,        // Must use oac.lock
      "autoUpdate": false             // No auto-updates
    },
    "customization": {
      "allowPresets": true,           // Allow personal presets
      "requireApproval": true,        // Presets need approval
      "allowOverrides": false,        // No context overrides
      "allowCustomAgents": false      // No unauthorized agents
    },
    "compliance": {
      "enforceStandards": true,       // Enforce team standards
      "minimumCompliance": 90,        // 90% compliance required
      "blockOnDrift": true,           // Block commits if non-compliant
      "auditAll": true                // Audit all actions
    },
    "security": {
      "requireVerified": true,        // Only verified components
      "blockExternalSources": false,  // Allow GitHub sources
      "scanComponents": true,         // Scan for malware/secrets
      "requireSignatures": false      // GPG signatures required
    }
  }
}

Enforcement:

# Developer tries to install beta version
oac add agent:openagent@0.8.0-beta

❌ Policy Violation: Beta versions not allowed

Team policy: allowBeta = false
You requested: openagent@0.8.0-beta (beta)

? Actions:
  > Use stable version (0.7.1)
    Request policy exception
    Learn more about team policies

# Developer tries to commit with low compliance
git commit -m "Add feature"

❌ Pre-commit Check Failed

OAC Compliance: 85% (minimum: 90%)

Issues:
- Missing: frontend-specialist (required)
- Old version: openagent@0.6.5 (team: 0.7.1)

Policy: blockOnDrift = true

? Actions:
  > Fix compliance now (sync with team)
    Request exception
    Skip pre-commit check (not recommended)

5.5 Easy Onboarding for New Hires

Feature: One-command onboarding with guided setup

Onboarding Command:

oac onboard

╔════════════════════════════════════════════════════╗
║  Welcome to Frontend Team! 👋                      ║
║  Let's get you set up in 5 minutes.               ║
╚════════════════════════════════════════════════════╝

Step 1/5: Team Detection
  ✓ Detected team: Frontend Team
  ✓ Team lead: john@company.com
  ✓ Team size: 8 members

Step 2/5: Configuration
  ✓ Found lockfile: oac.lock
  ✓ Components: 6 (4 agents, 2 contexts)
  ✓ IDE: OpenCode

Step 3/5: Installation
  ⚡ Installing team configuration...
  ✓ agent:openagent@0.7.1
  ✓ agent:frontend-specialist@1.2.0
  ✓ context:team-standards@1.0.0
  ✓ context:react-patterns@1.5.0

Step 4/5: Verification
  ✓ All components installed
  ✓ Team standards loaded
  ✓ Compliance: 100%

Step 5/5: Resources
  📚 Team Wiki: https://wiki.company.com/frontend
  💬 Slack: #frontend-team
  👤 Team Lead: john@company.com

✅ Onboarding complete! (4m 32s)

? Start interactive tutorial? (Y/n)

6. Example Scenarios (Detailed)

Scenario 1: Team Setup from Scratch

Persona: John, Engineering Manager
Goal: Set up standardized development environment for new team
Team Size: 8 developers
Tech Stack: React, TypeScript, Node.js

Timeline: Week 1 - Project Kickoff

Monday: Initial Setup

# Create new project
mkdir company-frontend && cd company-frontend
git init
npm init -y

# Initialize OAC for team
oac team init

Welcome to OAC Team Setup! 👥

? Team name: Frontend Team
? Owner (your email): john@company.com
? Team size: Small (2-10 developers)
? Primary tech stack: React, TypeScript, Node.js
? Strictness level: Balanced

📦 Recommended setup for React + TypeScript:
  
  Core Agents:
  - openagent@0.7.1 (AI pair programmer)
  - frontend-specialist@1.2.0 (React/TS expert)
  
  Specialists:
  - tester@2.0.1 (Test generation)
  - reviewer@1.8.0 (Code review)
  
  Contexts:
  - team-standards (coding guidelines)
  - react-patterns (React best practices)

? Install recommended setup? (Y/n) y

⚡ Installing team setup...
  ✓ 4 agents installed
  ✓ 2 contexts installed
  ✓ Generated oac.lock
  ✓ Generated oac-team.json

✅ Team setup complete!

# Customize team standards
oac context edit team-standards

[Editor opens with template]
# Frontend Team Coding Standards

## React
- Functional components only
- TypeScript strict mode
- Props interfaces above components

## Testing
- Vitest for unit tests
- 80% coverage minimum
- Test files: *.test.tsx

## Git
- Branch naming: feature/JIRA-XXX-description
- Commit messages: Conventional Commits
- PR: Minimum 1 approval

[Save and close]

✓ Updated: team-standards

# Configure policies
oac team policy set enforceVersions true
oac team policy set allowCustomization true
oac team policy set minimumCompliance 90

# Commit team configuration
git add .
git commit -m "Initial team OAC setup

- Team: Frontend Team (8 developers)
- Agents: openagent, frontend-specialist, tester, reviewer
- Contexts: team-standards, react-patterns
- Policies: Enforce versions, allow customization, 90% compliance
"
git remote add origin git@github.com:company/frontend.git
git push -u origin main

# Announce to team
echo "Team setup complete! 📦

Clone the repo and run 'oac onboard' to get started.

Repo: git@github.com:company/frontend.git
" | slack-send #frontend-team

✓ Setup time: 30 minutes

Tuesday: First Team Member Onboards (Sarah)

# Sarah joins team
git clone git@github.com:company/frontend.git
cd frontend

# Run onboarding
oac onboard

╔════════════════════════════════════════════════════╗
║  Welcome to Frontend Team! 👋                      ║
╚════════════════════════════════════════════════════╝

🔍 Detecting configuration...
  ✓ Team: Frontend Team
  ✓ Lockfile: oac.lock
  ✓ Components: 6

⚡ Installing...
  [Progress bar: 100%]

✅ Setup complete! (3m 45s)

? Start tutorial? (Y/n) y

# Interactive tutorial
# ... (5 minutes) ...

# Sarah starts coding
> create a Button component

Agent (using team-standards):
  ✓ Functional component
  ✓ TypeScript
  ✓ Props interface above
  ✓ Test file included

Created:
  components/Button/
    Button.tsx
    Button.test.tsx
    index.ts

✅ Follows team standards

✓ Sarah productive in 15 minutes (vs 4 hours previously)

Results:

Setup time: 30 minutes (one-time)
Onboarding time: 15 minutes (per developer)
Team compliance: 100% from day 1
Zero configuration drift

Scenario 2: New Developer Onboarding (First Day)

Persona: Sarah, Junior Developer (first dev job)
Goal: Get productive on first day
Context: Joining established team with existing OAC setup

Hour 1: HR & Setup (9am - 10am)

Get laptop
Create accounts
Clone repos

Hour 2: Development Environment (10am - 11am)

# 10:00 AM - Clone project
cd ~/Projects
git clone git@github.com:company/frontend-app.git
cd frontend-app

# 10:05 AM - Install dependencies
npm install  # Takes 3 minutes

# 10:08 AM - Run OAC onboarding
oac onboard

╔════════════════════════════════════════════════════╗
║  Welcome to Frontend Team! 👋                      ║
║  Hi Sarah! Let's get you set up.                   ║
╚════════════════════════════════════════════════════╝

🔍 Detecting your setup...
  ✓ Git: Configured (sarah@company.com)
  ✓ Node: v18.16.0
  ✓ IDE: OpenCode detected
  ✓ Team: Frontend Team (8 members)
  ✓ Team lead: john@company.com

📦 Installing team configuration...
  
  Components (from oac.lock):
  ⠋ agent:openagent@0.7.1        [████████████░░] 80%
  ✓ agent:frontend-specialist@1.2.0
  ✓ agent:tester@2.0.1
  ✓ context:team-standards@1.0.0
  ✓ context:react-patterns@1.5.0
  ✓ skill:git-workflow@0.8.0

⚡ Configuring...
  ✓ Team standards applied
  ✓ Approval gates configured
  ✓ Git hooks installed

✅ Installation complete! (4m 12s)

📊 Verification...
  ✓ All components installed
  ✓ Team compliance: 100%
  ✓ IDE configured

╔════════════════════════════════════════════════════╗
║  You're all set! 🎉                                ║
╚════════════════════════════════════════════════════╝

📚 Resources for you:
  - Team wiki: https://wiki.company.com/frontend
  - Code standards: oac context show team-standards
  - React patterns: oac context show react-patterns
  - Slack: #frontend-team
  - Your buddy: mike@company.com

🎯 Your first task:
  Review this PR to learn our code style:
  https://github.com/company/frontend-app/pull/456

? Start 5-minute interactive tutorial? (Y/n) y

# 10:12 AM - Interactive tutorial
╔════════════════════════════════════════════════════╗
║  Quick Tutorial (5 minutes)                        ║
╚════════════════════════════════════════════════════╝

Lesson 1/4: Team Standards
  Your team has coding standards in: team-standards
  
  Let's view them:
  $ oac context show team-standards
  
  [Shows standards]
  
  ✓ These are automatically enforced by your agents

Lesson 2/4: Creating Components
  Let's create a simple Button component:
  
  > create a Button component with TypeScript
  
  Agent response:
  ✓ Created components/Button/Button.tsx (functional, TS)
  ✓ Created components/Button/Button.test.tsx (Vitest)
  ✓ Follows team standards
  
  💡 Try it yourself!

Lesson 3/4: Running Tests
  $ npm test
  ✓ All tests pass
  
  💡 Write tests for all new components

Lesson 4/4: Getting Help
  - Ask in #frontend-team
  - Your buddy: mike@company.com  
  - Team lead: john@company.com
  - OAC help: oac team --help

╔════════════════════════════════════════════════════╗
║  Tutorial Complete! 🎓                             ║
║  You're ready to code!                             ║
╚════════════════════════════════════════════════════╝

# 10:17 AM - Tutorial complete
✓ Onboarding time: 17 minutes total

Hour 3: First Tasks (11am - 12pm)

# 11:00 AM - Review PR (learning task)
# Sarah reviews PR #456, learns code style

# 11:30 AM - First commit
> create a simple Avatar component

Agent (using team-standards):
  Creating component following team standards...
  
  ✓ components/Avatar/Avatar.tsx
  ✓ components/Avatar/Avatar.test.tsx
  ✓ components/Avatar/Avatar.stories.tsx
  
  All files follow team standards ✓

# Commit
git add components/Avatar
git commit -m "feat: Add Avatar component"

# Pre-commit hook runs
✓ OAC compliance check: 100%
✓ Tests pass
✓ Linting pass

# Push
git push origin feature/JIRA-789-avatar

# Create PR
gh pr create --title "feat: Add Avatar component"

✓ PR created: #457
✓ CI checks running...
✓ All checks pass

# 11:45 AM - First PR merged!
✓ PR approved by mike@company.com
✓ Merged to main

# Sarah is fully productive by hour 3 of day 1!

Results:

Time to setup: 17 minutes
Time to first commit: 3 hours
Time to first merged PR: 4 hours
Team compliance: 100% from start
Zero confusion about standards
Zero questions about setup

Comparison:

Metric	Before OAC	With OAC
Setup time	4-8 hours	17 minutes
First commit	1-2 days	3 hours
First PR merged	2-3 days	4 hours
Setup questions	10-20	0-2
Compliance issues	5-10	0
Onboarding buddy time	4-6 hours	30 minutes

Scenario 3: Handling Version Conflicts (Mid-Sprint)

Persona: Mike, Senior Developer
Goal: Add new testing library that requires newer agent
Context: Team on openagent@0.7.1, new library needs @0.8.0

Wednesday Morning: Discovery

# Mike wants to add Playwright specialist
oac add agent:playwright-specialist

⚠ Dependency Conflict

Component: agent:playwright-specialist@1.0.0
Requires: agent:openagent@^0.8.0

Your current setup:
  agent:openagent@0.7.1 (from team standard)

Team standard:
  agent:openagent@0.7.1 (locked in oac.lock)

Conflict: Cannot install without updating openagent

? How would you like to resolve?
  > Request team update (contact team lead)
    Find compatible version (alternative)
    Override locally (breaks team standard - not recommended)
    Cancel installation

# Mike requests team update
? Request team update

📝 Creating update request...

? Reason for update:
Need Playwright specialist for e2e testing.
Playwright specialist requires openagent@0.8.0.

? Priority:
  > Medium (this sprint)
    High (blocking)
    Low (nice to have)

? Impact:
  Will require all team members to update openagent.
  No breaking changes expected (checked changelog).

✓ Request sent to team lead (john@company.com)

📧 Request created:
  - ID: REQ-001
  - Component: agent:openagent 0.7.1 → 0.8.0
  - Requested by: mike@company.com
  - Status: Pending review
  
💡 Track status: oac team requests
💡 Team lead notified via Slack and email

Wednesday Afternoon: Team Lead Review

# John reviews request
oac team requests

📬 Pending Update Requests (1)

REQ-001: openagent@0.7.1 → 0.8.0
  Requested by: mike@company.com
  Reason: Need Playwright specialist for e2e testing
  Priority: Medium (this sprint)
  
  Impact Analysis:
    - Affects: 8/8 team members
    - Breaking changes: None
    - Dependencies: Compatible with all current agents
    - Team adoption: Will require sync
    
  Changelog (0.7.1 → 0.8.0):
    ✓ Improved delegation logic
    ✓ Fixed approval gate bug
    ✓ New context loading patterns
    ❌ No breaking changes

? Action:
  > Approve and schedule update
    Approve immediately
    Request more information
    Reject with reason
    Test in pilot first

# John approves with schedule
? Approve and schedule update

? Rollout strategy:
  > Staged (pilot → gradual → full)
    Immediate (all members now)
    Scheduled (specific date/time)

# Staged rollout
? Pilot members:
  ✓ mike@company.com (requester)
  ✓ sarah@company.com

? Pilot duration: 24 hours

? Full rollout: If pilot successful, roll out to full team

✓ Update approved!

📅 Rollout Schedule:
  
  Stage 1: Pilot (2 members)
    - mike@company.com
    - sarah@company.com
    Start: Now
    Duration: 24 hours
    
  Stage 2: Gradual (4 members)
    - jane@company.com
    - bob@company.com
    - alice@company.com
    - tom@company.com
    Start: If pilot successful
    Duration: 24 hours
    
  Stage 3: Full (remaining 2)
    - lisa@company.com
    - charlie@company.com
    Start: If gradual successful
    
📧 Notifications sent:
  - Pilot members: Update available now
  - Other members: Update scheduled
  - Slack: Posted to #frontend-team

? Proceed with pilot? (Y/n) y

✓ Pilot rollout started

Wednesday Evening: Pilot Stage

# Mike gets notification
⚠ Team Update Available (Pilot)

Component: agent:openagent@0.8.0
Your role: Pilot tester
Status: Approved by john@company.com

Changes:
  - Improved delegation logic
  - Fixed approval gate bug
  - New context loading patterns

? Install pilot update now? (Y/n) y

⚡ Installing openagent@0.8.0 (pilot)...
  ✓ Backed up current version (0.7.1)
  ✓ Installed openagent@0.8.0
  ✓ Updated dependencies

✅ Pilot update installed

⚠ You're now in pilot mode

Please test the update and report:
  - Any issues: oac team pilot report-issue
  - Works well: oac team pilot approve
  - Critical problems: oac team pilot reject

Testing period: 24 hours

# Mike tests for a few hours
# Everything works great

# Mike approves pilot
oac team pilot approve

✓ Pilot approved by mike@company.com

Feedback:
  ? Works as expected? ✓ Yes
  ? Any issues? ✗ None
  ? Comments: Delegation seems faster, no issues

✓ Feedback submitted

# Sarah also approves
# (similar process)

# Team lead sees pilot results
oac team rollout status

📊 Pilot Results: openagent@0.8.0

Status: ✓ Successful
Duration: 24 hours
Participants: 2/2

Feedback:
  ✓ mike@company.com: Approved, no issues
  ✓ sarah@company.com: Approved, works great

Issues: 0

? Proceed to Stage 2 (Gradual rollout)? (Y/n) y

Thursday: Gradual Rollout

# 4 team members get notification
⚠ Team Update Available

Component: agent:openagent@0.8.0
Status: Pilot successful, rolling out

Pilot results:
  ✓ 2/2 approved
  ✓ 0 issues reported
  ✓ Feedback: Positive

? Install update now? (Y/n) y

# All 4 members install successfully
# Team lead monitors

oac team rollout status

📊 Gradual Rollout Progress

Stage 2: Gradual (4 members)
  ✓ jane@company.com: Installed
  ✓ bob@company.com: Installed  
  ✓ alice@company.com: Installed
  ⏳ tom@company.com: Pending (on vacation)

Status: 3/4 completed (75%)

? Action:
  > Wait for tom@company.com
    Skip tom (complete stage 2)
    Pause rollout

# Skip tom (he's on vacation)
✓ Stage 2 complete (skipping tom)

? Proceed to Stage 3? (Y/n) y

Friday: Full Rollout Complete

# Final 2 members update
# Rollout complete

oac team status

📊 Team Update Complete: openagent@0.8.0

✅ Rollout successful!

Timeline:
  Wed 2pm: Pilot started (2 members)
  Thu 2pm: Gradual rollout (4 members)
  Fri 10am: Full team (8 members)
  
Adoption: 7/8 (87.5%)
  ✓ 7 members on 0.8.0
  ⏳ 1 member pending (tom - on vacation)

Issues: 0

Next:
  - Tom will auto-update on return
  - Mike can now install playwright-specialist

# Mike installs Playwright specialist
oac add agent:playwright-specialist

✓ Dependency check: openagent@0.8.0 (satisfied)
✓ Installing agent:playwright-specialist@1.0.0

✅ Installation complete!

# Team successfully updated, zero disruption

Results:

Total time: 3 days (staged rollout)
Issues: 0
Team disruption: Minimal (staged approach)
Pilot caught potential issues: N/A (clean update)
Rollback needed: No

Scenario 4: Enforcing Standards (Code Review Crisis)

Persona: John, Team Lead
Problem: PRs have inconsistent code style, reviews taking too long
Goal: Enforce team standards automatically

Monday: Problem Recognition

# John reviews recent PRs
# Notices issues:
# - Inconsistent component structure
# - Mixed class/functional components
# - No test files
# - Inconsistent file naming

# Current state: Standards documented but not enforced
# Solution: Create enforced team standards context

Tuesday: Create Enforceable Standards

# Create team standards context
oac create context team-standards --required

# Edit with enforceable rules
oac context edit team-standards

# Content:
---
version: 1.0.0
enforcement: strict
rules:
  - id: functional-components
    level: error
    description: Use functional components only
  - id: typescript
    level: error
    description: All components must use TypeScript
  - id: test-files
    level: error
    description: All components must have test files
  - id: file-naming
    level: error
    description: PascalCase for components, camelCase for utils
---

# Frontend Team Coding Standards

## React Components

### Structure (REQUIRED)
```typescript
// components/Button/Button.tsx

import React from 'react';

interface ButtonProps {
  label: string;
  onClick: () => void;
}

export const Button: React.FC<ButtonProps> = ({ label, onClick }) => {
  return <button onClick={onClick}>{label}</button>;
};

Testing (REQUIRED)

// components/Button/Button.test.tsx

import { render, fireEvent } from '@testing-library/react';
import { Button } from './Button';

describe('Button', () => {
  it('calls onClick when clicked', () => {
    const handleClick = jest.fn();
    const { getByText } = render(<Button label="Click me" onClick={handleClick} />);
    fireEvent.click(getByText('Click me'));
    expect(handleClick).toHaveBeenCalled();
  });
});

File Structure (REQUIRED)

components/
  Button/
    Button.tsx        # Component (required)
    Button.test.tsx   # Tests (required)
    Button.stories.tsx # Storybook (recommended)
    index.ts          # Barrel export (required)

Enforcement

Agents will: ✓ Generate components following this structure ✓ Create test files automatically ✓ Use TypeScript with strict mode ✓ Follow file naming conventions ❌ Reject class components ❌ Reject components without tests ❌ Reject non-TypeScript files

[Save]

Make context required and locked

oac team add context:team-standards@1.0.0 --required --locked

✓ Added as required (cannot be overridden) ✓ All team members must use this context

Configure agents to enforce strictly

oac team config set agents.frontend-specialist.strictMode true oac team config set agents.frontend-specialist.requireTests true

Update lockfile and push

oac lock update git add .oac/ oac.lock oac-team.json git commit -m "feat: Add enforced team standards

Created team-standards context (required, locked)
Configured strict enforcement
All components must:
- Use functional components (TS)
- Include test files
- Follow file structure " git push origin main

Announce to team

slack-send #frontend-team "📋 New Team Standards Enforced

We've added enforced coding standards to improve PR quality.

Changes:

All components must be functional (TypeScript)
Test files required for all components
Strict file structure

Action: Pull latest and run 'oac team sync'

Agents will automatically follow these standards. Old code is grandfathered in. "

✓ Standards deployed


**Wednesday: Team Syncs**

```bash
# Team members pull and sync
git pull
oac team sync

⚠ Team Configuration Updated

New required component:
  + context:team-standards@1.0.0 (required, locked)

Agent configuration updated:
  - frontend-specialist: Strict mode enabled
  - frontend-specialist: Tests required

? Sync with team standard? (Y/n) y

⚡ Syncing...
  ✓ Installed: context:team-standards@1.0.0
  ✓ Updated: agent configuration

✅ Synced with team standard

💡 Try creating a component to see standards in action:
    > create a Card component

Wednesday Afternoon: Standards in Action

# Sarah creates a component
> create a Card component with title and description props

Agent (using team-standards):
  Creating component following team standards...
  
  ✓ Enforcing: Functional component (TypeScript)
  ✓ Enforcing: Test file required
  ✓ Enforcing: File structure

Created:
  components/Card/
    Card.tsx          # Functional component, TypeScript
    Card.test.tsx     # Vitest tests
    Card.stories.tsx  # Storybook stories
    index.ts          # Barrel export

All files follow team standards ✓

# Bob tries to create class component (bad habit)
> create a Modal component using class

Agent (using team-standards):
  ❌ Enforcement: Class components not allowed
  
  Team standard requires functional components.
  Creating functional component instead...

Created:
  components/Modal/
    Modal.tsx         # Functional (not class)
    Modal.test.tsx
    index.ts

✓ Converted to functional component (team standard)

# Mike forgets to add tests
> create a Dropdown component

Agent (using team-standards):
  Creating component...
  
  ✓ components/Dropdown/Dropdown.tsx
  ✓ components/Dropdown/Dropdown.test.tsx (auto-generated)
  ✓ components/Dropdown/index.ts

✓ Test file automatically created (required by team)

Thursday: PR Quality Improves

# John reviews PRs
# All PRs now:
# ✓ Functional components (TypeScript)
# ✓ Include test files
# ✓ Follow file structure
# ✓ Consistent style

# PR review time drops from 30min to 10min
# Style comments: Eliminated
# Focus shifts to logic and business requirements

# Team velocity increases

Results:

PR review time: 30min → 10min (67% reduction)
Style issues in PRs: ~15/PR → 0/PR (100% reduction)
Test coverage: 60% → 95% (automatically enforced)
Team consistency: 100% (enforced by agents)
Developer happiness: Higher (less nitpicking in reviews)

Scenario 5: Migration to New Version (Breaking Changes)

Persona: John, Team Lead
Challenge: Migrate team from OAC v0.7.x to v1.0.0 (breaking changes)
Team Size: 8 developers
Risk: High (breaking changes)

Week 1: Planning & Testing

Monday: Assessment

# Check migration requirements
oac team migrate --check

📦 Migration Available: v0.7.1 → v1.0.0

⚠ Breaking Changes Detected:

1. Approval Gates Configuration
   - Old format: approval.gates = ["bash", "write"]
   - New format: permissions.bash = "approve"
   - Impact: All team members (auto-migrated)

2. Context Resolution
   - Old: Single context path
   - New: Layered resolution (project → global)
   - Impact: Custom context paths need update

3. Preset System
   - Old: No presets
   - New: Preset metadata required
   - Impact: Custom agents need migration

Migration Complexity: Medium
Estimated Time: 2-4 hours (full team)
Auto-Migration: 80% (manual review needed)

? View detailed migration guide? (Y/n) y

Migration Guide:

📚 Migration Guide: v0.7.1 → v1.0.0

## Step 1: Backup (5 minutes)
```bash
oac team backup
# Creates: .oac/backups/team-backup-2026-02-14.tar.gz

Step 2: Create Migration Branch (2 minutes)

git checkout -b oac-v1-migration

Step 3: Run Migration Tool (10-15 minutes)

oac team migrate --to v1.0.0
# Auto-migrates: configs, presets, contexts
# Outputs: migration-report.md

Step 4: Manual Review (30-60 minutes)

Review updated configs
Test approval gates
Verify context resolution

Step 5: Pilot Test (1-2 days)

Test with 2-3 developers
Collect feedback
Fix issues

Step 6: Full Rollout (1-2 days)

Roll out to full team
Monitor for issues
Provide support

Total Time: 3-5 days (cautious approach)

? Start migration planning? (Y/n) y


**Tuesday: Migration Execution**

```bash
# Create backup
oac team backup

✓ Backup created: .oac/backups/team-backup-2026-02-14.tar.gz
✓ Includes: all configs, agents, contexts, lockfile

# Create migration branch
git checkout -b oac-v1-migration

# Run migration tool
oac team migrate --to v1.0.0

⚡ Running Migration: v0.7.1 → v1.0.0

Phase 1: Analysis
  ✓ Scanning configurations...
  ✓ Detecting breaking changes...
  ✓ Planning migrations...

Phase 2: Backup
  ✓ Backed up all configs

Phase 3: Auto-Migration
  ⚡ Migrating approval gates config...
    ✓ Converted 8 configurations
    
  ⚡ Migrating context resolution...
    ✓ Updated context paths
    ⚠ 2 custom contexts need manual review
    
  ⚡ Migrating presets...
    ✓ Added metadata to 3 custom agents
    
  ⚡ Updating lockfile...
    ✓ Generated new oac.lock (v1.0.0 format)

Phase 4: Validation
  ✓ Validating configurations...
  ⚠ 2 warnings (see migration-report.md)
  ✓ No errors

✅ Migration Complete (80% automated)

📊 Migration Summary:
  - Configurations migrated: 8/8
  - Auto-migrated: 80%
  - Manual review needed: 2 items
  - Breaking changes handled: 3/3
  
⚠ Action Required:
  1. Review: migration-report.md
  2. Fix: 2 manual migration items
  3. Test: oac doctor
  4. Commit: git commit -m "Migrate to OAC v1.0.0"

? Open migration report? (Y/n) y

Migration Report (migration-report.md):

# OAC Migration Report: v0.7.1 → v1.0.0

**Date**: 2026-02-14  
**Team**: Frontend Team  
**Status**: ⚠ Needs Manual Review

## Summary

✅ Auto-migrated: 80%  
⚠ Manual review: 2 items  
❌ Errors: 0

## Auto-Migrations Completed

### 1. Approval Gates Configuration
✅ Migrated all 8 team member configurations

Old format:
```json
"approval": {
  "gates": ["bash", "write", "edit"]
}

New format:

"permissions": {
  "bash": "approve",
  "write": "approve",
  "edit": "approve"
}

2. Context Resolution

✅ Updated context paths for layered resolution

Changes:

Updated project context paths
Added context priority configuration
Migrated global context references

3. Preset System

✅ Added metadata to 3 custom agents

Custom agents migrated:

bob-custom-tester → preset:bob-custom-tester
sarah-reviewer → preset:sarah-reviewer
mike-debugger → preset:mike-debugger

Manual Review Required

1. Custom Context Paths (bob@company.com)

⚠ Manual review needed

Issue: Bob has custom context override that conflicts with new layered resolution

Location: /Users/bob/.opencode/context/custom-patterns.md

Action Required:

Review custom context
Move to: .oac/context/override/ (new override location)
OR: Integrate into team-standards

Priority: Medium (affects 1 member)

2. Legacy Agent Format (alice@company.com)

⚠ Manual review needed

Issue: Alice has very old custom agent (v0.3.x format)

Location: /Users/alice/.opencode/agent/legacy-agent.md

Action Required:

Update to v1.0.0 format
OR: Remove if no longer needed
Test after update

Priority: Low (custom agent, optional)

Testing Checklist

Before pilot rollout:

Test approval gates (new format)
Test context resolution (layered)
Test presets (new metadata)
Verify all agents load correctly
Run: oac doctor

Rollback Plan

If issues occur:

oac team rollback --to backup-2026-02-14

This will restore all configurations to pre-migration state.

Next Steps

Fix manual review items (Bob, Alice)
Run oac doctor to validate
Start pilot with 2 members
Full rollout after successful pilot ```

Wednesday: Fix Manual Items

# Contact Bob
slack-send @bob "Hey Bob, migration to OAC v1.0 needs your help.

You have a custom context that needs updating:
  /Users/bob/.opencode/context/custom-patterns.md

Options:
1. Move to new override location (5 min)
2. Integrate into team-standards (15 min)

Can you handle this today? Let me know if you need help.
"

# Bob fixes
# (moves custom context to new location)

# Contact Alice
slack-send @alice "Hey Alice, found an old custom agent during migration:
  /Users/alice/.opencode/agent/legacy-agent.md

Is this still needed? If not, we can remove it.
If yes, needs update to v1.0.0 format (I can help).
"

# Alice confirms not needed
# Removed

# Validate migration
oac doctor

✓ All configurations valid
✓ All agents load correctly
✓ Context resolution working
✓ Presets migrated successfully

✅ Migration ready for testing

Thursday: Pilot Test

# Designate pilot members
oac team pilot add sarah@company.com mike@company.com

? Pilot duration: 1 day

✓ Pilot group created (2 members)

📧 Sent to pilot members:
  "You've been selected for OAC v1.0 pilot test.
  
  Please:
  1. git checkout oac-v1-migration
  2. oac install --frozen
  3. Test for 1 day
  4. Report: oac team pilot feedback
  
  Questions? #oac-migration"

# Pilot members test
# Sarah tests, no issues
# Mike tests, no issues

# Collect feedback
oac team pilot report

📊 Pilot Test Results (1 day)

Participants: 2/2
Completion: 100%

Feedback:
✓ sarah@company.com:
  - No issues
  - Approval gates clearer
  - Likes new preset system
  
✓ mike@company.com:
  - No issues
  - Context resolution faster
  - No problems

Issues Reported: 0
Critical Bugs: 0

Recommendation: ✅ Ready for full rollout

? Proceed with full team rollout? (Y/n) y

Friday: Full Rollout

# Merge migration branch
git checkout main
git merge oac-v1-migration
git push origin main

# Announce rollout
oac team announce

📢 OAC v1.0 Migration - Ready to Roll Out

What: Upgrade to OAC v1.0.0
When: Now (pull latest from main)
Duration: 5 minutes per person

Breaking Changes (auto-migrated):
✓ Approval gates (new format)
✓ Context resolution (layered)
✓ Presets (new metadata)

Tested By:
✓ sarah@company.com (no issues)
✓ mike@company.com (no issues)

Action Required:
1. git pull
2. oac install --frozen
3. Test your workflow
4. Report issues: #oac-migration

Estimated time: 5 minutes

Rollback available if needed.

? Send to team? (Y/n) y

✓ Sent to #frontend-team
✓ Emails sent to all members

# Track rollout
oac team status

📊 Migration Progress: v1.0.0

Completed: 6/8 (75%)
In Progress: 2/8 (25%)
Issues: 0

Timeline:
- 10am: sarah ✓
- 10:15am: mike ✓
- 11am: jane ✓
- 11:30am: bob ✓
- 1pm: alice ✓
- 2pm: tom ✓
- Pending: lisa, charlie

✅ Migration going smoothly

# End of day: 8/8 complete
✓ Full team migrated
✓ Zero issues
✓ Total time: 3 days (cautious approach)

Results:

Planning: 1 day
Migration execution: 1 day
Pilot test: 1 day
Full rollout: 1 day (completed in hours)
Total: 3 days (actual) vs 4 days (estimated)
Issues: 0
Rollbacks: 0
Team disruption: Minimal

Summary

Key Insights for Team Leads

What OAC Solves:

✅ Onboarding: 4 hours → 15 minutes
✅ Consistency: 100% team alignment
✅ Standards: Automatically enforced
✅ Updates: Coordinated across team
✅ Visibility: Full audit trail

What OAC Needs:

🚨 Lockfile: For reproducibility
🚨 Team Dashboard: Real-time compliance
🚨 Audit Trail: Who installed what, when
🚨 Policy Enforcement: Configurable governance
🚨 Rollout Management: Staged updates with rollback

Must-Have Commands:

oac team init           # Set up team standards
oac team status         # Check team compliance
oac team sync           # Sync with team standard
oac team update         # Coordinate updates
oac team dashboard      # Team health overview
oac team audit          # Installation audit trail
oac team policy         # Configure policies
oac onboard             # One-command onboarding
oac team migrate        # Version migration
oac team rollout        # Staged rollout management

Success Metrics:

Onboarding time: <30 minutes
Team compliance: >95%
PR review time: -50%
Setup questions: -90%
Version drift: 0%

Next Steps: Use these scenarios to validate OAC design and implementation priorities.

05-team-lead-scenarios.md 99 KB History Raw

Team Lead Perspective: OAC User Scenarios

Executive Summary

1. Team Workflows

1.1 Onboarding New Team Members

1.2 Standardizing Agent Configurations

1.3 Sharing Custom Agents/Presets

1.4 Enforcing Coding Standards

1.5 Managing Updates Across Team

2. Key Experiences

2.1 Setting Up Team Standards (First Time)

2.2 Ensuring Everyone Has Same Setup

2.3 Reviewing Team's Agent Usage

2.4 Handling Version Conflicts

2.5 Migrating to New Versions

Step 2: Create Migration Branch

Step 3: Run Migration Tool

Step 4: Test with Pilot Group

Step 5: Full Team Rollout

3. Pain Points & Solutions

3.1 Developers Using Different Versions

3.2 Customizations Breaking Team Standards

3.3 Hard to Track What's Installed Where

3.4 Updates Breaking Team Workflows

3.5 Onboarding Takes Too Long

4. Edge Cases

4.1 Team Member Goes Rogue (Custom Setup)

4.2 Monorepo with Multiple Projects

4.3 Different Teams Need Different Setups

4.4 Legacy Projects with Old Agents

4.5 Remote Team Across Timezones

5. Must-Have Features

5.1 Lockfile for Reproducibility

5.2 Shared Team Configurations

5.3 Audit Trail (Who Installed What)

5.4 Policy Enforcement

5.5 Easy Onboarding for New Hires

6. Example Scenarios (Detailed)

Scenario 1: Team Setup from Scratch

Scenario 2: New Developer Onboarding (First Day)

Scenario 3: Handling Version Conflicts (Mid-Sprint)

Scenario 4: Enforcing Standards (Code Review Crisis)

Testing (REQUIRED)

File Structure (REQUIRED)

Enforcement

Make context required and locked

Configure agents to enforce strictly

Update lockfile and push

Announce to team

Scenario 5: Migration to New Version (Breaking Changes)

Step 2: Create Migration Branch (2 minutes)

Step 3: Run Migration Tool (10-15 minutes)

Step 4: Manual Review (30-60 minutes)

Step 5: Pilot Test (1-2 days)

Step 6: Full Rollout (1-2 days)

2. Context Resolution

3. Preset System

Manual Review Required

1. Custom Context Paths (bob@company.com)

2. Legacy Agent Format (alice@company.com)

Testing Checklist

Rollback Plan

Next Steps

Summary

Key Insights for Team Leads

05-team-lead-scenarios.md 99 KB

History Raw