OpenWriterControle/plugins/claude-code/commands/oac-add-context.md

---

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