Home Explore Help
Sign In
logic855
/
OpenAgentsControl
mirror of https://github.com/darrenhinde/OpenAgentsControl.git
1
0
Fork 0
Files Issues 0 Wiki
Tree: 5f4991633f
Branches Tags
OpenAgentsCo...
/
plugins
/
claude-code
/
commands
/
oac-add-context.md

oac-add-context.md 15 KB
History Raw

name: oac:add-context description: Add context files from GitHub, worktrees, local files, or URLs to your project

argument-hint: [source] [options]

Add Context

Add context files to your project from various sources: $ARGUMENTS

What This Command Does

The /oac:add-context command helps you add context files from:

  1. GitHub repositories - Team or company standards
  2. Git worktrees - Local development branches
  3. Local files - Project-specific patterns
  4. URLs - Remote documentation

This command invokes the context-manager subagent to:

  • Discover your context root location
  • Fetch/copy files from the source
  • Validate file format and structure
  • Update navigation for discoverability
  • Verify files are accessible via /context-discovery

Supported Sources

1. GitHub Repository

Format: github:owner/repo[/path][#ref]

Examples:

# Add from GitHub repo (main branch)
/oac:add-context github:acme-corp/standards

# Add specific path
/oac:add-context github:acme-corp/standards/security

# Add specific branch/tag
/oac:add-context github:acme-corp/standards#v1.0.0

# Add with category
/oac:add-context github:acme-corp/standards --category=team

What it does:

  • Clones repository (shallow, single branch)
  • Copies specified path to context root
  • Validates markdown files
  • Updates navigation
  • Cleans up temporary clone

2. Git Worktree

Format: worktree:/path/to/worktree[/subdir]

Examples:

# Add from worktree
/oac:add-context worktree:../team-context

# Add specific subdirectory
/oac:add-context worktree:../team-context/standards

# Add with category
/oac:add-context worktree:../team-context/security --category=team

What it does:

  • Validates worktree exists (.git directory)
  • Copies files from worktree
  • Validates markdown files
  • Updates navigation
  • Preserves worktree (no cleanup)

Use case: Perfect for team members working on shared context in a separate worktree

3. Local File or Directory

Format: file:./path/to/file-or-dir

Examples:

# Add single file
/oac:add-context file:./docs/patterns/auth-flow.md

# Add directory
/oac:add-context file:./docs/patterns/

# Add with category and priority
/oac:add-context file:./docs/security.md --category=custom --priority=critical

What it does:

  • Validates file/directory exists
  • Copies to context root
  • Validates markdown format
  • Updates navigation
  • Preserves original files

Use case: Add project-specific patterns or documentation to context

4. URL

Format: url:https://example.com/path/to/file.md

Examples:

# Add from URL
/oac:add-context url:https://example.com/standards/security.md

# Add with category
/oac:add-context url:https://raw.githubusercontent.com/owner/repo/main/doc.md --category=external

What it does:

  • Downloads file via HTTP/HTTPS
  • Validates markdown format
  • Saves to context root
  • Updates navigation

Use case: Add public documentation or standards from the web

Options

--category=<name>

Purpose: Specify target category for context files

Default: custom

Examples:

# Add to team category
/oac:add-context github:acme-corp/standards --category=team

# Add to custom category
/oac:add-context file:./docs/patterns.md --category=custom

# Add to core category (override defaults)
/oac:add-context file:./security.md --category=core

Categories:

  • core - Essential standards and workflows
  • team - Team/company-specific context
  • custom - Project-specific overrides
  • external - External library documentation
  • personal - Personal templates and patterns

--priority=<level>

Purpose: Set priority level for context files

Default: medium

Levels:

  • critical - Must-read files for all tasks
  • high - Strongly recommended files
  • medium - Optional but helpful files

Examples:

# Mark as critical
/oac:add-context file:./security-policy.md --priority=critical

# Mark as high priority
/oac:add-context github:acme-corp/standards --priority=high

Impact: Priority affects ranking in /context-discovery results

--overwrite

Purpose: Overwrite existing files with same name

Default: false (skip existing files)

Examples:

# Overwrite existing files
/oac:add-context github:acme-corp/standards --overwrite

# Skip existing files (default)
/oac:add-context github:acme-corp/standards

Warning: Use with caution - overwrites local modifications

--dry-run

Purpose: Preview what would be added without making changes

Examples:

# Preview GitHub addition
/oac:add-context github:acme-corp/standards --dry-run

# Preview worktree addition
/oac:add-context worktree:../team-context --dry-run

Output:

Dry Run: No changes will be made

Would add:
- security-patterns.md → .opencode/context/team/security-patterns.md
- auth-guidelines.md → .opencode/context/team/auth-guidelines.md
- deployment-process.md → .opencode/context/team/deployment-process.md

Would update:
- .opencode/context/team/navigation.md
- .opencode/context/navigation.md

Run without --dry-run to apply changes.

Usage Examples

Example 1: Add Team Standards from GitHub

Command:

/oac:add-context github:acme-corp/engineering-standards/security --category=team --priority=critical

Process:

  1. Discover context root → .opencode/context
  2. Clone acme-corp/engineering-standards (shallow)
  3. Copy security/ directory
  4. Validate markdown files
  5. Copy to .opencode/context/team/security/
  6. Update navigation files
  7. Verify discoverability

Output:

✅ Context root discovered: .opencode/context

✅ Cloned from GitHub: acme-corp/engineering-standards
   Branch: main
   Path: security/

✅ Validation passed:
   - security-policies.md ✅
   - auth-patterns.md ✅
   - data-protection.md ✅

✅ Copied to: .opencode/context/team/security/

✅ Navigation updated:
   - .opencode/context/team/navigation.md
   - .opencode/context/navigation.md

✅ Verification: All files discoverable via /context-discovery

Summary:
- Added 3 context files to team/security/
- Source: github:acme-corp/engineering-standards/security
- Category: team
- Priority: critical
- Discoverable: ✅

Example 2: Add from Git Worktree

Command:

/oac:add-context worktree:../team-context/standards --category=team

Process:

  1. Discover context root → .claude/context (from .oac config)
  2. Validate worktree exists
  3. Copy files from ../team-context/standards/
  4. Validate markdown files
  5. Copy to .claude/context/team/standards/
  6. Update navigation
  7. Verify discoverability

Output:

✅ Context root discovered: .claude/context (from .oac config)

✅ Worktree validated: ../team-context/.git exists

✅ Copied from worktree: ../team-context/standards
   Files: 5 markdown files

✅ Validation passed:
   - code-quality.md ✅
   - naming-conventions.md ✅
   - testing-standards.md ✅
   - deployment-process.md ✅
   - review-checklist.md ✅

✅ Copied to: .claude/context/team/standards/

✅ Navigation updated:
   - .claude/context/team/navigation.md
   - .claude/context/navigation.md

✅ Verification: All files discoverable via /context-discovery

Summary:
- Added 5 context files to team/standards/
- Source: worktree:../team-context/standards
- Category: team
- Priority: medium (default)
- Discoverable: ✅

Example 3: Add Local Pattern File

Command:

/oac:add-context file:./docs/patterns/auth-flow.md --category=custom --priority=high

Process:

  1. Discover context root → context (found in project root)
  2. Validate file exists
  3. Validate markdown format
  4. Copy to context/custom/patterns/
  5. Update navigation
  6. Verify discoverability

Output:

✅ Context root discovered: context

✅ File validated: ./docs/patterns/auth-flow.md
   Format: markdown ✅
   Structure: valid ✅
   Size: 2.3 KB

✅ Copied to: context/custom/patterns/auth-flow.md

✅ Navigation updated:
   - context/custom/navigation.md
   - context/navigation.md

✅ Verification: File discoverable via /context-discovery

Summary:
- Added 1 context file to custom/patterns/
- Source: file:./docs/patterns/auth-flow.md
- Category: custom
- Priority: high
- Discoverable: ✅

Example 4: Add from URL

Command:

/oac:add-context url:https://raw.githubusercontent.com/openagents/standards/main/security.md --category=external --priority=critical

Process:

  1. Discover context root → .opencode/context
  2. Download file from URL
  3. Validate markdown format
  4. Save to .opencode/context/external/
  5. Update navigation
  6. Verify discoverability

Output:

✅ Context root discovered: .opencode/context

✅ Downloaded from URL: https://raw.githubusercontent.com/openagents/standards/main/security.md
   Size: 5.2 KB
   Content-Type: text/plain

✅ Validation passed:
   - security.md ✅

✅ Saved to: .opencode/context/external/security.md

✅ Navigation updated:
   - .opencode/context/external/navigation.md
   - .opencode/context/navigation.md

✅ Verification: File discoverable via /context-discovery

Summary:
- Added 1 context file to external/
- Source: url:https://raw.githubusercontent.com/...
- Category: external
- Priority: critical
- Discoverable: ✅

Integration with OAC Workflow

Stage 1: Analyze & Discover

Before adding context:

# Discover what context you need
/context-discovery authentication security patterns

# If context is missing, add it
/oac:add-context github:acme-corp/security-standards --category=team

Stage 3: LoadContext

After adding context:

# Context is now discoverable
/context-discovery authentication security patterns

# Returns newly added files:
# - .opencode/context/team/security-patterns.md ✅

Stage 6: Complete

After implementing a feature:

# Add learned patterns to context
/oac:add-context file:./docs/new-pattern.md --category=custom

# Now available for future tasks

Advanced Usage

Batch Addition

# Add multiple sources
/oac:add-context github:acme-corp/standards --category=team
/oac:add-context worktree:../team-context --category=team
/oac:add-context file:./docs/patterns/ --category=custom

Preview Before Adding

# Dry run to see what would be added
/oac:add-context github:acme-corp/standards --dry-run

# Review output, then add for real
/oac:add-context github:acme-corp/standards --category=team

Update Existing Context

# Overwrite existing files with latest from GitHub
/oac:add-context github:acme-corp/standards --category=team --overwrite

Add with Specific Branch/Tag

# Add from specific version
/oac:add-context github:acme-corp/standards#v2.0.0 --category=team

# Add from development branch
/oac:add-context github:acme-corp/standards#develop --category=team

Context Root Discovery

The command automatically discovers where to add context:

Discovery Order:

  1. Check .oac config - Read context.root setting
  2. Check .claude/context - Claude Code default
  3. Check context - Simple root-level directory
  4. Check .opencode/context - OpenCode/OAC default
  5. Create .opencode/context - Fallback if none found

Example .oac config:

{
  "context": {
    "root": ".claude/context"
  }
}

Validation

All added context files are validated:

Format Validation

  • ✅ Valid markdown file
  • ✅ UTF-8 encoding
  • ✅ No binary content

Structure Validation

  • ✅ Has title (# heading)
  • ✅ Has content sections
  • ⚠️ Metadata header (optional but recommended)

Navigation Validation

  • ✅ File added to navigation.md
  • ✅ Category exists in root navigation
  • ✅ Priority set correctly

Validation Output:

✅ Markdown format valid
✅ Structure valid (title, content)
⚠️  Metadata header missing (recommended but optional)
✅ Navigation entry added

Status: Valid (with warnings)

Troubleshooting

"Source not found"

Cause: GitHub repo, worktree, or file doesn't exist

Solution:

# Verify GitHub repo exists
gh repo view acme-corp/standards

# Verify worktree exists
ls -la ../team-context/.git

# Verify local file exists
ls -la ./docs/patterns/auth-flow.md

"Validation failed"

Cause: File is not valid markdown or has structural issues

Solution:

Error: Validation failed for security-pattern.md

Issues:
❌ Not a markdown file (detected: text/html)
❌ Missing title (no # heading)
⚠️  No metadata header (recommended)

Fix these issues before adding to context.

Fix: Convert to markdown, add title, then retry

"Context root not found"

Cause: No context directory exists and .oac config missing

Solution:

# Option 1: Let command create default
/oac:add-context github:acme-corp/standards
# Creates .opencode/context automatically

# Option 2: Create .oac config
cat > .oac <<EOF
{
  "context": {
    "root": ".claude/context"
  }
}
EOF

# Option 3: Create directory manually
mkdir -p .opencode/context

"Permission denied"

Cause: No write access to context directory

Solution:

# Check permissions
ls -la .opencode/

# Fix permissions
chmod -R u+w .opencode/context/

"Navigation update failed"

Cause: Navigation file is malformed or locked

Solution:

# Backup current navigation
cp .opencode/context/navigation.md .opencode/context/navigation.md.backup

# Let command regenerate navigation
/oac:add-context github:acme-corp/standards --category=team

Tips

✅ Do

  • Use --dry-run first - Preview changes before applying
  • Organize by category - Use appropriate categories (team, custom, external)
  • Set priority correctly - Critical for must-read files
  • Verify discoverability - Test with /context-discovery after adding
  • Keep worktrees updated - Pull latest changes before adding
  • Use version tags - Pin to specific versions for stability

❌ Don't

  • Don't add binary files - Only markdown files are supported
  • Don't skip validation - Fix validation errors before adding
  • Don't overwrite without backup - Use --overwrite carefully
  • Don't add sensitive data - Keep API keys and secrets out of context
  • Don't add too much - Only add relevant, high-signal context

Related Commands

  • /oac:setup - Download OAC context from GitHub
  • /oac:status - Check context installation status
  • /oac:help - View all available commands
  • /context-discovery - Discover added context files

Related Skills

  • /context-manager - Manage context configuration
  • /using-oac - Main workflow (uses added context)

Success Criteria

After running /oac:add-context, you should have:

  • ✅ Context files copied to context root
  • ✅ All files validated (format, structure)
  • ✅ Navigation updated for discoverability
  • ✅ Files accessible via /context-discovery
  • ✅ Category and priority set correctly

Test discoverability:

/context-discovery [topic related to added context]
# Should return newly added files

Version: 1.0.0
Command: oac:add-context
Last Updated: 2026-02-16