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

bash git checkout -b oac-v1-migration


### Step 3: Run Migration Tool

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

Review updated configs: .oac/team/
Test locally: oac doctor
Update README with new instructions

? Commit changes? (Y/n) y

✓ Changes committed


### Step 4: Test with Pilot Group

bash

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:

git checkout oac-v1-migration
oac install --frozen
Test for 1 day
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

bash

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:

git pull
oac install --frozen
Test your workflow
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**

bash

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**
bash

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**

bash

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**

bash

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**
bash

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**

bash

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)

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**

bash

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**
bash

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**

bash

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**

bash

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**

bash

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:

Test in pilot first
Review Bob's custom preset
Schedule update during low-activity period
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**
bash

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:

Review team standards: oac context show team-standards
Read React patterns: oac context show react-patterns
Test your setup: oac doctor
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**

bash

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**:

bash

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**:
bash

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**:

bash

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`):
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**:
bash

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**:

bash

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**

json // 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**:

bash

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**

bash

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**:

bash

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**

bash

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**:

bash

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**:

json { "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**:

bash

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**:

bash

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**:

bash

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`):

json { "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**:

bash

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**:

json { "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**:

bash

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**:

bash oac onboard

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**

bash

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)**

bash

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)**

bash

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

📚 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)**

bash

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**

bash

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**

bash

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**

bash

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**

bash

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**

bash

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

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**

bash

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**

bash

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)

// 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**

bash

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**

bash

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**

bash

Check migration requirements

oac team migrate --check

📦 Migration Available: v0.7.1 → v1.0.0

⚠ Breaking Changes Detected:

Approval Gates Configuration
- Old format: approval.gates = ["bash", "write"]
- New format: permissions.bash = "approve"
- Impact: All team members (auto-migrated)
Context Resolution
- Old: Single context path
- New: Layered resolution (project → global)
- Impact: Custom context paths need update
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**:

bash 📚 Migration Guide: v0.7.1 → v1.0.0

Step 1: Backup (5 minutes)

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:

Review: migration-report.md
Fix: 2 manual migration items
Test: oac doctor
Commit: git commit -m "Migrate to OAC v1.0.0"

? Open migration report? (Y/n) y


**Migration Report** (`migration-report.md`):

markdown

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:

"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**
```
bash

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:

Move to new override location (5 min)
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**

bash

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:

git checkout oac-v1-migration
oac install --frozen
Test for 1 day
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**

bash

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:

git pull
oac install --frozen
Test your workflow
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**:
1. ✅ **Onboarding**: 4 hours → 15 minutes
2. ✅ **Consistency**: 100% team alignment
3. ✅ **Standards**: Automatically enforced
4. ✅ **Updates**: Coordinated across team
5. ✅ **Visibility**: Full audit trail

**What OAC Needs**:
1. 🚨 **Lockfile**: For reproducibility
2. 🚨 **Team Dashboard**: Real-time compliance
3. 🚨 **Audit Trail**: Who installed what, when
4. 🚨 **Policy Enforcement**: Configurable governance
5. 🚨 **Rollout Management**: Staged updates with rollback

**Must-Have Commands**:

bash 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 Permalink 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

Creates: .oac/backups/team-backup-2026-02-14.tar.gz

Team lead designates pilot group

Pilot members test

After 1 day of testing

Merge migration branch

Announce to team

Track migration progress

Team lead enables strict version enforcement

oac-team.json

Developer tries to install different version

Enable drift detection

Developer's setup drifts

(git pull doesn't update oac)

On next oac command:

Team lead enables git hooks

Developer commits code with drift

Team lead can see customizations

View Bob's customizations

Team lead marks contexts as required (cannot be overridden)

Bob tries to override

Agent tries to load context

Enable preset approval requirement

Bob creates preset

Team lead reviews

Approved

Team lead views comprehensive dashboard

Automatic installation tracking

Every install is logged to team registry

Filter by member

Filter by component

Export audit log

Team lead enables staged rollouts

Update available

Staged rollout

24 hours later: Check pilot results

Stage 2: Gradual

48 hours later: Final stage

Team lead enables automatic rollback

Update deployed

Problems detected

Before updating team standard

New developer (Sarah) - Day 1, Hour 1

Run single onboarding command

Setup is complete - Sarah is ready to code!

Total time: 5 minutes (vs 4 hours previously)

After onboarding, optional tutorial

Bob's setup

Team lead notices in dashboard

Team lead sends alert

Bob receives alert and syncs

Team lead can enforce different levels

Strict mode example

Bob tries to install old version

Working on frontend app

Move to mobile app

Switch (keeps both)

Team lead manages workspace

Sarah works on both frontend and backend

Auto-detect team based on project

Multi-team mode

Legacy project setup

Compatibility mode

Developer works on both legacy and modern projects

Uses OAC v0.3.x compatibility mode

Uses OAC v1.0.0 with all features

05-team-lead-scenarios.md 99 KB

Permalink History Raw