Agentic Beacon CLI

CLI tool for distributing agentic engineering contexts, knowledge, and skills from a warehouse repository to project .opencode directories.

Overview

This tool enables the DRY (Don't Repeat Yourself) principle for agentic knowledge management:

• Centralized warehouse: Store all contexts, knowledge, and skills in one place
• Fork workflow: Fork the warehouse template to create your organization's warehouse
• Local distribution: Use the CLI to distribute content to gitignored .opencode folders in projects
• Easy updates: Sync latest changes from the warehouse with one command

Installation

Recommended: Install with uv (if you have uv installed)

The best way to install abc is using uv tool install, which installs it in an isolated environment:

# Install once, use anywhere
uv tool install agentic-beacon

# Verify installation
abc --help

# Update to latest version
uv tool upgrade agentic-beacon

# Uninstall
uv tool uninstall agentic-beacon

Alternative Installation Methods

# Using pipx (similar to uv tool, isolated environment)
pipx install agentic-beacon

# Using pip (global Python environment)
pip install agentic-beacon

# One-off execution without installation
uvx --from agentic-beacon abc init my-warehouse

Usage

All examples below use the abc command directly (after installation).

1. List Available Content

# List all available contexts, knowledge, and skills
abc list

# From a specific warehouse location
abc list --warehouse /path/to/warehouse

2. Setup (First Time)

# Interactive mode (recommended for first time)
abc setup --interactive

# Install specific content
abc setup \
  --context global \
  --context python \
  --knowledge global \
  --knowledge languages/python \
  --skill example-skill

# Install everything
abc setup --all

# Specify warehouse and project locations
abc setup --all \
  --warehouse /path/to/warehouse \
  --project /path/to/project

What it does:

• Creates .opencode/ directory in your project (gitignored)
• Copies selected contexts to .opencode/contexts/
• Copies selected knowledge to .opencode/knowledge/
• Copies selected skills to .opencode/skills/
• Saves configuration for future updates

3. Update Existing Installation

# Update all installed content from warehouse
agentic update

# From a specific warehouse location
agentic update --warehouse /path/to/warehouse

What it does:

• Reads existing .opencode/.warehouse-config.yml
• Re-copies all previously selected content
• Overwrites with latest versions from warehouse

4. Check Installation Status

# Show what's currently installed
agentic status

# For a specific project
agentic status --project /path/to/project

5. Clean Installation

# Remove .opencode directory
agentic clean

# Will prompt for confirmation

Workflow

For Organization Admins

1. Create warehouse: Fork the template repository

   # Use GitHub's "Use this template" button
   # Name it: your-org-agentic-warehouse
   

2. Customize content: Add your organization's contexts, knowledge, and skills

   your-org-agentic-warehouse/
   ├── contexts/
   │   ├── AGENTS.global.md
   │   ├── AGENTS.python.md
   │   └── AGENTS.your-domain.md
   ├── knowledge/
   │   ├── global/
   │   ├── languages/python/
   │   └── domains/your-domain/
   └── skills/
       └── your-skill/
   

3. Distribute to teams: Team members clone and install

For Team Members

1. Clone warehouse (one time):

   git clone https://github.com/your-org/agentic-warehouse.git ~/agentic-warehouse
   cd ~/agentic-warehouse
   pip install -e libs/agentic_warehouse_cli
   

2. Setup in project (per project):

   cd ~/your-project
   agentic setup --warehouse ~/agentic-warehouse --interactive
   

3. Update when needed:

   cd ~/your-project
   agentic update --warehouse ~/agentic-warehouse
   

4. Add to .gitignore:

   # Add to your project's .gitignore
   .opencode/
   

Directory Structure

Warehouse Structure

your-org-agentic-warehouse/
├── contexts/
│   ├── AGENTS.global.md
│   ├── AGENTS.python.md
│   └── AGENTS.data-platform.md
├── knowledge/
│   ├── global/
│   │   ├── decisions/
│   │   ├── lessons/
│   │   └── facts/
│   ├── languages/
│   │   └── python/
│   └── domains/
│       └── data-platform/
├── skills/
│   └── example-skill/
│       └── SKILL.md
└── libs/
    └── agentic_warehouse_cli/  # This CLI tool

Project Structure (After Setup)

your-project/
├── .opencode/                    # gitignored
│   ├── .warehouse-config.yml    # Tracks what's installed
│   ├── contexts/
│   │   ├── AGENTS.global.md
│   │   └── AGENTS.python.md
│   ├── knowledge/
│   │   ├── global/
│   │   └── languages/
│   │       └── python/
│   └── skills/
│       └── example-skill/
├── .gitignore                    # Contains .opencode/
└── ...

Configuration

The CLI auto-saves configuration to .opencode/.warehouse-config.yml:

contexts:
  - global
  - python
knowledge_scopes:
  - global
  - languages/python
skills:
  - example-skill

This configuration is used by the update command to know what to refresh.

Auto-Detection

The CLI automatically detects:

• Warehouse root: Looks for directories containing contexts/, knowledge/, and skills/
• Project root: Looks for .git directory or uses current directory

You can override with --warehouse and --project options.

Examples

Example 1: Setup Python Project

cd ~/my-python-project

# Interactive setup
agentic setup --interactive

# Select:
#   Contexts: global, python
#   Knowledge: global, languages/python
#   Skills: none

# Result: .opencode/ created with selected content

Example 2: Setup Data Platform Project

cd ~/data-platform-project

# Non-interactive setup
agentic setup \
  --context global \
  --context python \
  --context data-platform \
  --knowledge global \
  --knowledge languages/python \
  --knowledge domains/data-platform \
  --skill deploy-airflow

# Result: Full data platform context installed

Example 3: Update After Warehouse Changes

cd ~/my-project

# Warehouse maintainers updated content
# Pull latest warehouse changes
cd ~/agentic-warehouse
git pull origin main

# Update project installation
cd ~/my-project
agentic update

# Result: Latest content synced to .opencode/

Example 4: Check What's Installed

cd ~/my-project
agentic status

# Output:
# Installation: /Users/you/my-project/.opencode
#
# Installed Contexts
# ┌─────────┐
# │ Context │
# ├─────────┤
# │ global  │
# │ python  │
# └─────────┘

Development

Running Tests

cd libs/agentic_warehouse_cli
pytest

Building Package

pip install build
python -m build

Troubleshooting

CLI not found after installation

# Make sure you're in the right environment
which agentic

# Reinstall
pip install -e libs/agentic_warehouse_cli --force-reinstall

Warehouse not auto-detected

# Explicitly specify warehouse path
agentic setup --warehouse /path/to/warehouse

.opencode not in .gitignore

# Add to .gitignore
echo ".opencode/" >> .gitignore

Bundled Skills

Three skills are shipped inside the abc package and available immediately after connecting a warehouse:

Invoke any bundled skill from an OpenCode or Claude Code session:

/record-knowledge
/record-skill
/contribute-warehouse

Warehouse Commands

abc warehouse lint

Validates a warehouse directory against every Beacon artifact contract: structure, skill frontmatter, skill context references, agent manifest, agent frontmatter (name + description), and knowledge link integrity. Designed as the single entry-point for warehouse-side CI.

# Lint the current directory (inside a warehouse clone)
abc warehouse lint

# Lint a specific path
abc warehouse lint ~/my-org-warehouse

Exit 0 when clean; exit 1 on any finding.

License

MIT