OAC Package Refactor - Critical Feedback & Recommendations

Date: 2026-02-14
Source: Parallel review by CodeReviewer + User Research Agent
Status: Action Required Before Phase 1

Executive Summary

Overall Assessment: The OAC refactor plan is 80% solid but needs critical additions before implementation.

Key Findings:

✅ Core architecture is sound (approval system, context resolution, multi-IDE)
⚠️ Missing critical features (discovery, lockfile, security)
❌ Some approaches need rethinking (context merging, local/global UX)
💡 Repository structure needs optimization for extensibility

🚨 CRITICAL Issues to Address Before Phase 1

1. Security & Verification (BLOCKER)

Problem: Community components have no security layer

Required Additions:

interface ComponentSecurity {
  signature: string;           // GPG signature
  checksum: string;            // SHA-256 hash
  scanResults: {
    malware: boolean;
    secrets: boolean;
    externalCalls: string[];
  };
  permissions: {
    fileSystem: 'read' | 'write' | 'none';
    network: 'allowed' | 'denied';
    shell: 'allowed' | 'denied';
  };
}

Add to Phase 1:

Component signing mechanism
Checksum verification
Basic malware scanning (ClamAV)
Secret detection (gitleaks)

CLI Commands:

oac verify <component>        # Verify signature
oac audit                     # Security scan
oac trust @author             # Trust publisher

2. Discovery & Browse Experience (CRITICAL GAP)

Problem: Users can't discover what's available

Current Plan: Only oac add (assumes you know what exists)

Required Additions:

oac browse                    # Interactive TUI browser
oac search "rust" --verified  # Search registry
oac trending                  # Popular components
oac info agent:rust-specialist # Detailed info
oac preview agent:rust        # Show what it does

Implementation:

Interactive TUI using ink or blessed
Web registry at https://registry.openagents.dev
Component ratings and reviews
Download counts and trending

Add to Phase 1: Basic oac browse and oac search

3. Lockfile for Reproducibility (CRITICAL GAP)

Problem: No way to guarantee reproducible installs (teams need this)

Required Addition:

// oac.lock
{
  "version": "1.0.0",
  "lockfileVersion": 1,
  "components": {
    "agent:openagent": {
      "version": "0.7.1",
      "resolved": "https://github.com/.../openagent.md",
      "integrity": "sha256-abc123...",
      "dependencies": {
        "context:code-quality": "^1.0.0"
      }
    }
  }
}

CLI Commands:

oac lock                      # Generate lock file
oac install --frozen          # Use exact locked versions
oac lock verify               # Verify integrity

Add to Phase 2: Lockfile generation and frozen installs

4. Version Conflict Management (CRITICAL GAP)

Problem: No strategy for handling version conflicts

Required Additions:

{
  "dependencies": {
    "agents": {
      "tester": "^1.0.0",     // Semver range
      "reviewer": "~2.1.0"    // Patch updates only
    }
  },
  "peerDependencies": {
    "openagent": "^0.5.0"     // Required version
  }
}

CLI Commands:

oac outdated                  # Show outdated components
oac update --check-breaking   # Warn about breaking changes
oac pin <component> <version> # Pin to specific version
oac deps tree                 # Show dependency tree
oac deps conflicts            # Show conflicts

Add to Phase 2: Semver support and conflict detection

5. Interactive Onboarding (HIGH PRIORITY)

Problem: First-time users need guidance

Required Addition:

oac init

┌─────────────────────────────────────────────────┐
│  Welcome to OpenAgents Control! 👋              │
│  Let's set up your AI agent environment.        │
└─────────────────────────────────────────────────┘

? What's your primary use case?
  > Software Development
    Content Creation
    Data Analysis

? Which IDE do you use?
  ✓ OpenCode
  ✓ Cursor

? Install location preference?
  > Ask each time (recommended)
    Always local
    Always global

✓ Configuration saved!
📦 Installing recommended agents...
✓ Done! Try: oac browse

Add to Phase 1: Interactive wizard for oac init

6. Visual Feedback & Progress (HIGH PRIORITY)

Problem: Long operations feel unresponsive

Required Addition:

📦 Installing OpenCode Developer Profile
⠋ Downloading components... [████████████░░░░░░░░] 60% (12/20)
✓ openagent.md (15KB)
✓ opencoder.md (18KB)
⠋ Installing contexts...

Implementation:

Use ora for spinners
Use cli-progress for progress bars
Color-coded output with chalk
Clear success/error states

Add to Phase 1: Progress indicators for all long operations

⚠️ Approaches That Need Rethinking

1. Context Merging is Dangerous

Current Plan: Merge context files from multiple sources

Problem:

Conflicts between sections
Unclear merge strategy
Hard to debug

Better Approach: Use composition instead

interface ContextComposition {
  base: string;                // Base context
  overrides: string[];         // Override files (applied in order)
  strategy: 'override' | 'append' | 'prepend';
}

Action: Replace merging with composition in Phase 5

2. Local vs Global UX is Confusing

Current Plan: Ask "local or global?" on every command

Problem:

Decision fatigue
Most users want one or the other
No clear guidance

Better Approach: Auto-detection with smart defaults

# Set default once
oac configure set preferences.installLocation auto

# Auto-detect based on context:
# - In git repo? → local
# - Has .opencode/? → local
# - In home dir? → global

# Override when needed
oac install --global
oac install --local

Action: Implement auto-detection in Phase 1

3. Cursor Agent Merging is Problematic

Current Plan: Merge all agents into single .cursorrules

Problem:

Loss of modularity
Hard to debug
100KB limit is restrictive
Merge conflicts on updates

Better Approach: Router agent pattern

# Cursor Router Agent
When user asks about testing → delegate to tester patterns
When user asks about frontend → delegate to frontend patterns
Default → delegate to openagent patterns

[Embedded agent patterns as sections, not full agents]

Action: Implement router pattern in Phase 3

💡 Recommended Additions

1. Plugin Architecture for Extensibility

Why: Keep core lean, allow community extensions

interface OACPlugin {
  name: string;
  version: string;
  hooks: {
    beforeInstall?: (context: InstallContext) => void;
    afterInstall?: (context: InstallContext) => void;
  };
  commands?: Command[];
  adapters?: IDEAdapter[];
}

Add to Phase 6: Plugin system

2. Workspace Support for Monorepos

Why: Teams use monorepos, need first-class support

// oac-workspace.json
{
  "version": "1.0.0",
  "packages": ["packages/*", "apps/*"],
  "shared": {
    "context": ".oac/shared/context",
    "config": ".oac/shared/config.json"
  }
}

Add to v1.1: Workspace support

3. Component Marketplace with Ratings

Why: Discovery and trust

interface ComponentMarketplace {
  downloads: number;
  rating: number;           // 1-5 stars
  reviews: Review[];
  verified: boolean;
  maintainer: string;
  lastUpdated: Date;
}

Add to v1.1: Marketplace features

🏗️ Repository Structure Recommendation

Use Monorepo (pnpm workspaces)

@nextsystems/oac/
├── packages/
│   ├── core/                  # Core CLI package
│   │   ├── src/
│   │   │   ├── cli/
│   │   │   ├── config/
│   │   │   ├── approval/
│   │   │   └── context/
│   │   ├── tests/
│   │   └── package.json
│   ├── adapters/              # IDE adapters package
│   │   ├── src/
│   │   │   ├── opencode/
│   │   │   ├── cursor/
│   │   │   ├── claude/
│   │   │   └── windsurf/
│   │   └── package.json
│   ├── registry/              # Registry package
│   │   ├── src/
│   │   └── package.json
│   ├── security/              # Security scanning
│   │   ├── src/
│   │   └── package.json
│   └── cli/                   # CLI entry point
│       ├── bin/
│       └── package.json
├── .opencode/                 # Official components
├── registry.json              # Official registry
├── community-registry.json    # Community registry
├── pnpm-workspace.yaml        # Monorepo config
└── package.json               # Root package

Why Monorepo:

✅ Shared dependencies
✅ Atomic commits across packages
✅ Easier to maintain consistency
✅ Easier to test integrations
✅ Single version for all packages

Tools: pnpm workspaces + Turborepo

🤝 Community Contribution Workflow

Recommended Process

# 1. Create component locally
oac create agent my-specialist

# 2. Test locally
oac test agent:my-specialist

# 3. Package for submission
oac package agent:my-specialist
# Creates: my-specialist.oac.tar.gz

# 4. Submit to registry
oac submit my-specialist.oac.tar.gz
# Uploads to GitHub, creates PR

# 5. Automated checks run
# - Security scan (ClamAV)
# - Secret scan (gitleaks)
# - Dependency check
# - Test execution
# - Size check

# 6. Manual review (for verification badge)
# - Code quality review
# - Documentation review
# - Test coverage review

# 7. Approval and publish
# - Merged to community-registry.json
# - Available via `oac add`

Security Scanning Pipeline

# .github/workflows/component-scan.yml
name: Component Security Scan

on:
  pull_request:
    paths:
      - 'community-registry.json'

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - name: Malware scan
        run: clamav scan component/
      
      - name: Secret scan
        run: gitleaks detect --source component/
      
      - name: Dependency audit
        run: npm audit
      
      - name: Test execution
        run: oac test component/

📋 Updated Feature Prioritization

MVP (v1.0.0 - Must Ship)

Feature	Priority	Status	Action
Core CLI	P0	✅ Planned	Keep
Multi-IDE support	P0	✅ Planned	Keep
Approval gates	P0	✅ Planned	Keep
Configuration system	P0	✅ Planned	Keep
Context resolution	P0	✅ Planned	Fix merging
Discovery (`browse`, `search`)	P0	🚨 ADD	Phase 1
Lockfile (`oac.lock`)	P0	🚨 ADD	Phase 2
Security (verify, audit)	P0	🚨 ADD	Phase 1
Onboarding (interactive init)	P0	🚨 ADD	Phase 1
Progress UI (spinners, bars)	P0	🚨 ADD	Phase 1
Auto-detection (local/global)	P0	🚨 ADD	Phase 1

Post-MVP (v1.1.0)

Feature	Priority	Impact
Preview/try mode	P1	High
Dependency management	P1	High
Plugin system	P1	Medium
Workspace support	P1	Medium
Marketplace features	P1	High

📚 Documentation Requirements

Critical Docs (Before Launch)

Quick Start (5-Minute Guide)
- Install → Init → Add Agent → Start Coding
CLI Reference (Auto-Generated)
- Every command documented
- Examples for each flag
- Common use cases
Recipes / Cookbook
- Set up React project
- Share config with team
- Create custom agent
- Troubleshooting
Component Creation Guide
- Step-by-step agent creation
- Testing guide
- Publishing checklist
Migration Guide
- From current OAC to v1.0
- Breaking changes
- Upgrade path

✅ Action Items (Before Phase 1)

Immediate (This Week)

✅ Update context file with critical additions
✅ Update Phase 1 tasks to include:
- Discovery (browse, search)
- Security (verify, checksum)
- Onboarding (interactive init)
- Progress UI (spinners, bars)
- Auto-detection (local/global)
✅ Update Phase 2 tasks to include:
- Lockfile generation
- Version conflict detection
- Semver support

Before Implementation

⬜ Set up monorepo structure (pnpm workspaces)
⬜ Create security scanning workflow
⬜ Design TUI for browse command
⬜ Write Quick Start docs

🎯 Key Takeaways

What's Good (Keep)

✅ User approval system with YOLO mode
✅ Layered context resolution (fix merging)
✅ Multi-IDE support via adapters
✅ Community registry concept
✅ Backward compatibility

What's Missing (Add)

🚨 Discovery (browse, search, trending)
🚨 Lockfile (reproducibility)
🚨 Security (verification, scanning)
🚨 Onboarding (interactive wizard)
🚨 Progress UI (spinners, bars)
🚨 Auto-detection (local/global)

What Needs Fixing (Rethink)

⚠️ Context merging → Use composition
⚠️ Always asking local/global → Auto-detect
⚠️ Cursor agent merging → Router pattern
⚠️ No version management → Add semver + lockfile

📊 Success Metrics (Post-Launch)

Metric	Target (6 months)
GitHub stars	1,000+
npm downloads/month	10,000+
Community components	50+
Active contributors	20+
Docs page views	5,000+/month

🚀 Next Steps

Update OAC refactor plan with critical additions
Update Phase 1 tasks to include new features
Set up monorepo structure
Start Phase 1 implementation

Status: Ready to proceed with updated plan
Confidence: High (80% → 95% with additions)
Risk: Low (critical gaps identified and addressed)

03-critical-feedback.md 14 KB History Raw

OAC Package Refactor - Critical Feedback & Recommendations

Executive Summary

🚨 CRITICAL Issues to Address Before Phase 1

1. Security & Verification (BLOCKER)

2. Discovery & Browse Experience (CRITICAL GAP)

3. Lockfile for Reproducibility (CRITICAL GAP)

4. Version Conflict Management (CRITICAL GAP)

5. Interactive Onboarding (HIGH PRIORITY)

6. Visual Feedback & Progress (HIGH PRIORITY)

⚠️ Approaches That Need Rethinking

1. Context Merging is Dangerous

2. Local vs Global UX is Confusing

3. Cursor Agent Merging is Problematic

💡 Recommended Additions

1. Plugin Architecture for Extensibility

2. Workspace Support for Monorepos

3. Component Marketplace with Ratings

🏗️ Repository Structure Recommendation

Use Monorepo (pnpm workspaces)

🤝 Community Contribution Workflow

Recommended Process

Security Scanning Pipeline

📋 Updated Feature Prioritization

MVP (v1.0.0 - Must Ship)

Post-MVP (v1.1.0)

📚 Documentation Requirements

Critical Docs (Before Launch)

✅ Action Items (Before Phase 1)

Immediate (This Week)

Before Implementation

🎯 Key Takeaways

What's Good (Keep)

What's Missing (Add)

What Needs Fixing (Rethink)

📊 Success Metrics (Post-Launch)

🚀 Next Steps

03-critical-feedback.md 14 KB

History Raw