Repository Manager Agent v2.0

Agent ID: repo-manager
Category: Meta
Type: Meta Agent
Version: 2.0.0
Status: Stable

Overview

The Repository Manager is a meta agent specifically designed for managing development work on the OpenAgents Control repository itself. It provides lazy context loading, smart delegation, and automatic documentation updates with intelligent subagent coordination.

What's New in v2.0

✅ Lazy Context Loading - Uses contextscout for dynamic context discovery
✅ Smart Delegation - Session files for complex tasks, inline context for simple
✅ Predictable Workflow - Same 6-stage process every time
✅ No Hardcoded Paths - Adapts to any repo structure
✅ Clear Decision Trees - Explicit logic for when to delegate vs execute

Purpose

While openagent is a universal agent for any project, repo-manager is specialized for OpenAgents Control repository development. It understands the repository's structure, conventions, and standards, ensuring all work follows established patterns.

Key Features

1. Lazy Context Loading

Uses contextscout subagent for dynamic discovery
Loads context just-in-time (after approval, before execution)
No hardcoded paths - adapts to repo changes
Only loads what's needed for the specific task

2. Smart Delegation Strategy

Complex tasks (4+ files, >60min) → Session file + task-manager
Simple specialists (tester, reviewer) → Inline context
Direct execution (1-3 files) → No delegation

3. Session-Based Coordination

Creates .tmp/sessions/{timestamp}-{task-slug}/ for complex tasks
Context file contains: user request, context files to load, requirements, exit criteria
Shared memory for subagent coordination
Automatic cleanup after completion

4. Approval-Gated Workflow

Never executes without explicit user approval
Presents clear implementation plans before proceeding
Stops on validation failures and requests approval for fixes

5. Automatic Documentation Updates

Identifies documentation affected by changes
Updates docs automatically or delegates to documentation subagent
Keeps README files, guides, and context files current

6. Validation Integration

Runs validation scripts automatically (registry, test suites)
Executes eval tests when applicable
Stops on failure and reports issues clearly

When to Use

Use repo-manager for:

✅ Creating new agents
✅ Creating/modifying eval tests
✅ Updating the registry
✅ Managing context files
✅ Updating documentation
✅ Any OpenAgents Control repository development

Don't use repo-manager for:

❌ Working on user projects (use openagent instead)
❌ General coding tasks outside this repo
❌ Questions about other projects

The 6-Stage Workflow

Every task follows the same predictable workflow:

┌─────────────────────────────────────────────────────────────┐
│ STAGE 1: ANALYZE                                            │
│ - Classify task type (agent, eval, registry, docs, etc.)   │
│ - Determine complexity (simple vs complex)                  │
│ - Decide execution path (question vs task)                  │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ STAGE 2: PLAN & APPROVE                                     │
│ - Create implementation plan                                │
│ - List files to create/modify                               │
│ - Identify context needed (don't load yet)                  │
│ - Request approval                                          │
│ - ✅ Wait for user approval                                 │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ STAGE 3: LOAD CONTEXT (Lazy Loading)                        │
│ - Load quick-start.md (always)                              │
│ - Delegate to contextscout for discovery               │
│ - Load discovered context files                             │
│ - Extract key requirements                                  │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ STAGE 4: EXECUTE                                            │
│ - Decision: Complex → Session file + delegate               │
│ - Decision: Simple specialist → Inline context              │
│ - Decision: Direct → Execute with loaded context            │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ STAGE 5: VALIDATE                                           │
│ - Run validation scripts                                    │
│ - Run tests if applicable                                   │
│ - On failure: STOP → REPORT → PROPOSE → APPROVE → FIX       │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ STAGE 6: COMPLETE                                           │
│ - Update affected documentation                             │
│ - Summarize all changes                                     │
│ - Confirm user satisfaction                                 │
│ - Cleanup session files (if created)                        │
└─────────────────────────────────────────────────────────────┘

Lazy Context Loading (Stage 3)

Instead of hardcoding context file paths, repo-manager uses contextscout for dynamic discovery:

How It Works

Load quick-start.md (always - orientation file)

Read: .opencode/context/openagents-repo/quick-start.md

Delegate to contextscout for discovery

task(
  subagent_type="ContextScout",
  description="Find context for {task-type}",
 prompt="Search for context files related to: {task-type}
             
         Return:
         - Exact file paths
         - Brief summaries
         - Priority order"
)

Load discovered files in priority order

FOR EACH file in discovered_files:
 Read: {file-path}

Extract requirements from loaded context
- Naming conventions
- File structure requirements
- Validation requirements
- Testing requirements

Benefits

✅ No hardcoded paths - adapts to repo changes
✅ Only loads what's needed - true lazy loading
✅ Discovers new context files automatically
✅ Works even if context structure changes

Smart Delegation (Stage 4)

Repo-manager uses three delegation strategies based on task complexity:

Strategy 1: Session File Delegation (Complex Tasks)

When: 4+ files, >60min, complex dependencies, task breakdown needed

Subagents: task-manager, documentation

Process:

Create session directory: .tmp/sessions/{timestamp}-{task-slug}/
Write context.md with:
- User request
- Context files to load
- Key requirements (extracted from Stage 3)
- Files to create/modify
- Exit criteria
Delegate with context path
Cleanup after completion

Example:

task(
  subagent_type="TaskManager",
  prompt="Load context from .tmp/sessions/20250114-143022-parallel-tests/context.md
          
          Break down this feature into atomic subtasks.
          Follow all requirements in context file."
)

Strategy 2: Inline Context Delegation (Simple Specialists)

When: Simple delegation to specialists (tester, reviewer, coder-agent)

Subagents: tester, reviewer, coder-agent, build-agent

Process:

No session file needed
Pass context directly in prompt
Include extracted requirements from Stage 3

Example:

task(
  subagent_type="TestEngineer",
  prompt="Context to load:
          - .opencode/context/core/standards/tests.md
          
          Task: Write tests for {feature}
          
          Requirements:
          - Positive and negative test cases
          - Arrange-Act-Assert pattern
          
          Files to test:
          - {file1}
          - {file2}"
)

Strategy 3: Direct Execution (No Delegation)

When: 1-3 files, straightforward, <30min

Process:

Execute directly using context loaded in Stage 3
Apply requirements extracted from context
Create/modify files as planned

Available Subagents

Core Subagents (Planning & Coordination)

Subagent	Purpose	Context Strategy
task-manager	Break down complex features into atomic subtasks	Session file
contextscout	Find and retrieve relevant context files	None (discovery)
documentation	Generate/update comprehensive documentation	Session file

Code Subagents (Implementation & Quality)

Subagent	Purpose	Context Strategy
coder-agent	Execute simple coding subtasks	Inline
tester	Write tests following TDD	Inline
reviewer	Code review, security, quality checks	Inline
build-agent	Type checking, build validation	Inline

Session File Structure

When creating session files for complex tasks:

.tmp/sessions/{timestamp}-{task-slug}/
├── context.md              # Shared context for all subagents
└── .manifest.json          # Track session metadata

context.md Template

# Task Context: {Task Name}

Session ID: {timestamp}-{task-slug}
Created: {ISO timestamp}
Status: in_progress

## Current Request
{Original user request}

## Context Files to Load
- .opencode/context/openagents-repo/quick-start.md
- {other context files discovered in Stage 3}

## Key Requirements (Extracted from Context)
- {requirement 1}
- {requirement 2}

## Files to Create/Modify
- {file 1} - {purpose}
- {file 2} - {purpose}

## Technical Constraints
{Any technical constraints}

## Exit Criteria
- [ ] {criteria 1}
- [ ] {criteria 2}

## Progress Tracking
- [ ] Context loaded and understood
- [ ] Implementation complete
- [ ] Tests passing
- [ ] Documentation updated

---
**Instructions for Subagent**:
{Specific instructions}

Examples

Example 1: Simple Agent Creation (Direct Execution)

User: "Create a new data analyst agent"

Workflow:

Analyze: Task type = agent-creation, Complexity = simple (4 files)
Plan: Present plan to create 4 files, request approval
LoadContext:
- Load quick-start.md
- Delegate to contextscout: "Find context for agent-creation"
- Load discovered files: agents.md, adding-agent.md, code.md
- Extract: frontmatter format, category structure, naming conventions
Execute: Direct execution (4 files, straightforward)
- Create agent file with proper frontmatter
- Create eval structure
- Update registry
Validate: Run registry validation, smoke test
Complete: Update docs, summarize, confirm

Context Flow: ✅ Lazy loaded, ✅ No session files, ✅ Direct execution

Example 2: Complex Feature (Delegation Chain)

User: "Build parallel test execution for eval framework"

Workflow:

Analyze: Task type = general-development, Complexity = complex (6+ files, >60min)
Plan: Present plan to delegate to task-manager, request approval
LoadContext:
- Load quick-start.md
- Delegate to contextscout: "Find context for eval framework development"
- Load discovered files: evals.md, code.md, tests.md, patterns.md
- Extract: modular patterns, test requirements, eval structure
Execute: Session delegation
- Create .tmp/sessions/20250114-143022-parallel-tests/context.md
- Delegate to task-manager with context path
- Task-manager creates subtasks
- Implement subtasks (delegate to coder-agent or execute directly)
Validate:
- Run tests
- Delegate to tester for validation
- Delegate to reviewer for quality check
Complete:
- Delegate to documentation for docs update
- Summarize changes
- Cleanup session files

Context Flow: ✅ Lazy loaded, ✅ Session file created, ✅ Shared memory, ✅ Clean coordination

Decision Matrix

Scenario	Context Loading	Session File?	Delegation
Simple agent creation	Lazy (contextscout)	❌ No	None (direct)
Complex feature (4+ files)	Lazy (contextscout)	✅ Yes	task-manager
Write tests	Lazy (contextscout)	❌ No	tester (inline)
Code review	Lazy (contextscout)	❌ No	reviewer (inline)
Simple implementation	Lazy (contextscout)	❌ No	coder-agent (inline)
Comprehensive docs	Lazy (contextscout)	✅ Yes	documentation
Find context files	None (discovery agent)	❌ No	contextscout

Quality Standards

Repository Conventions

Follow category-based organization (core, development, content, etc.)
Use proper frontmatter metadata in agent files
Follow naming conventions (kebab-case for files)
Include proper tags and dependencies
Validate against registry schema

Context Awareness

Load quick-start.md for every task
Use contextscout for dynamic discovery
Apply standards from core/standards/
Follow workflows from core/workflows/
Reference context files (don't duplicate content)

Documentation Maintenance

Update docs when making changes
Keep README files current
Update version/date stamps
Maintain consistency across docs
Follow docs standards

Validation Requirements

Run validation scripts before completion
Test agents with eval framework
Validate registry entries
Check file structure
Verify documentation links

Critical Rules

Approval Gate: Request approval before ANY execution (bash, write, edit, task)
Context First: Load repo context BEFORE executing (lazy, via contextscout)
Stop on Failure: STOP on test fail/errors - NEVER auto-fix
Report First: On fail: REPORT→PROPOSE FIX→REQUEST APPROVAL→FIX
Confirm Cleanup: Confirm before deleting session files

Testing

Eval Tests: evals/agents/meta/repo-manager/

Test Suites:

smoke-test.yaml - Basic functionality
context-loading-test.yaml - Lazy context loading
delegation-test.yaml - Delegation decisions and session files

Run Tests:

cd evals/framework
npm run eval:sdk -- --agent=meta/repo-manager

Run Specific Test:

cd evals/framework
npm run eval:sdk -- --agent=meta/repo-manager --pattern="smoke-test.yaml"

Comparison: v1.0 vs v2.0

Aspect	v1.0	v2.0
Context Loading	Upfront (hardcoded paths)	Lazy (contextscout)
Session Files	Always creates bundles	Only for complex tasks
Context Passing	Always via files	Smart (inline vs session)
Workflow Stages	8 stages	6 stages
Lines of Code	763 lines	~650 lines
Adaptability	Hardcoded paths	Dynamic discovery
Clarity	Over-specified	Clear decision trees

Principles

Lazy Loading: Fetch context when needed via contextscout, not before
Smart Delegation: Session files for complex, inline for simple
Safety First: Always request approval, stop on failure
Quality Focused: Validate against repo standards, never auto-fix
Adaptive: Direct execution for simple, delegation for complex
Discoverable: Use contextscout for dynamic context discovery
Predictable: Same workflow every time

Last Updated: 2025-01-14
Maintainer: opencode
Status: Stable
Version: 2.0.0

repo-manager.md 17 KB History Raw

Repository Manager Agent v2.0

Overview

What's New in v2.0

Purpose

Key Features

1. Lazy Context Loading

2. Smart Delegation Strategy

3. Session-Based Coordination

4. Approval-Gated Workflow

5. Automatic Documentation Updates

6. Validation Integration

When to Use

The 6-Stage Workflow

Lazy Context Loading (Stage 3)

How It Works

Benefits

Smart Delegation (Stage 4)

Strategy 1: Session File Delegation (Complex Tasks)

Strategy 2: Inline Context Delegation (Simple Specialists)

Strategy 3: Direct Execution (No Delegation)

Available Subagents

Core Subagents (Planning & Coordination)

Code Subagents (Implementation & Quality)

Session File Structure

context.md Template

Examples

Example 1: Simple Agent Creation (Direct Execution)

Example 2: Complex Feature (Delegation Chain)

Decision Matrix

Quality Standards

Repository Conventions

Context Awareness

Documentation Maintenance

Validation Requirements

Critical Rules

Testing

Comparison: v1.0 vs v2.0

Principles

repo-manager.md 17 KB

History Raw