Skip to content

How It Works

Agentic Beacon is built around two components — the warehouse and the beacon — plus a small set of commands that move artifacts between them.

Mental Model

Agentic Beacon has two halves: a warehouse (a shared git repo of artifacts) and a beacon (per-project config that declares which artifacts this project needs). abc sync reads the project's declaration, follows the dependency graph through the warehouse, and creates per-file symlinks under .agentic-beacon/artifacts/ pointing into the warehouse clone.

Warehouse and beacon architecture A warehouse holding contexts, skills, knowledge, and agents directories on the left, with abc sync arrows pointing right into two project boxes. Each project contains a .agentic-beacon/ subdirectory holding beacon.yaml, config.toml, pending.yaml, .last-adopt, and an artifacts/ subdirectory of symlinks back into the warehouse. Warehouse shared git repo contexts/ skills/ knowledge/ agents/ Project A .agentic-beacon/ ├─ beacon.yaml ├─ config.toml ├─ pending.yaml ├─ .last-adopt └─ artifacts/ ↳ symlinks into warehouse Project B .agentic-beacon/ ├─ beacon.yaml ├─ config.toml ├─ pending.yaml ├─ .last-adopt └─ artifacts/ ↳ symlinks into warehouse abc sync abc sync
Concept What it is
Warehouse Shared git repo of contexts, skills, knowledge, and agents
beacon.yaml Per-project file declaring the artifacts this project needs
.agentic-beacon/artifacts/ Per-project symlink tree into the warehouse — gitignored, regenerated by abc sync
abc sync Resolves the declared artifacts, follows their dependencies, creates the symlinks

The warehouse is the single source of truth on a machine. Symlinks (not copies) mean every consuming project sees the same content with no drift.

The Warehouse

A warehouse is a plain git repository. It stores your team's shared agent artifacts in four directories:

my-org-warehouse/
├── contexts/       # boot instruction files
├── knowledge/      # decisions, lessons, facts
├── skills/         # reusable agent workflows
├── agents/         # global sub-agent definitions
└── docs/           # warehouse documentation

The four top-level directories are part of Beacon's schema — abc warehouse init creates them and abc warehouse lint enforces a minimal shape inside each:

  • contexts/ — fully free-form. Use any subdirectory layout you like.
  • skills/ — each skill lives at skills/<name>/SKILL.md with required YAML frontmatter (name, description).
  • knowledge/ — leaf directories must be one of three taxonomies: decisions/, lessons/, facts/. The path shape is knowledge/[<topic>/]<type>/<name>.md; the optional topic prefix (e.g. python-standards/, infrastructure/) is yours to design.
  • agents/ — entries registered in agents/agents.yaml; each agent .md has required frontmatter.

Within those rules you have full freedom over topic grouping, subdirectory depth, and naming. The warehouse lives on any git host (GitHub, GitLab, Bitbucket); team members clone it locally.

The Beacon

Each project that consumes warehouse artifacts has a .agentic-beacon/ directory:

my-project/
└── .agentic-beacon/
    ├── beacon.yaml       ← committed: declares which artifacts this project needs
    ├── config.toml       ← gitignored: local warehouse path
    ├── pending.yaml      ← gitignored: artifacts authored but not yet wired
    ├── .last-adopt       ← gitignored: timestamp of last abc adopt commit
    └── artifacts/        ← gitignored: symlink tree into warehouse

beacon.yaml declares three artifact types — contexts, skills, agents:

artifacts:
  contexts:
    - contexts/global.md
  skills:
    - skills/code-review/
  agents:
    - agents/spec-planner.md

Knowledge files are not declared — abc sync auto-derives them by scanning your adopted contexts and skills for markdown links into knowledge/.

pending.yaml and .last-adopt are working-state files managed by abc adopt — see Pending & Adoption for the full lifecycle.

The Sync Flow

abc sync does four things in one pass:

  1. Resolve — reads beacon.yaml, follows skill requires: frontmatter and agent declarations, then walks markdown links from contexts and skills into knowledge/ to auto-derive every transitive dependency.
  2. Symlink — creates per-file symlinks under .agentic-beacon/artifacts/ pointing into the warehouse clone.
  3. Wire — installs skills and agents into your detected AI tools (Claude Code, OpenCode), and appends adopted contexts to your tool's config file (CLAUDE.md, opencode.json). Beacon is idempotent and non-destructive: re-running never duplicates entries, and only its own references are added or removed.
  4. Prune — removes symlinks and config references for artifacts no longer declared.

For the full pipeline, flags, and edge cases, see the Adopting Artifacts guide. For per-type details (what wiring each artifact gets), see Artifact Types.

abc sync creates symlinks, not copies. .agentic-beacon/artifacts/ is a tree of symlinks pointing into the warehouse clone. This means:

  • One physical file per machine. No duplicate copies to drift out of sync.
  • Edits go directly to the warehouse. Editing a symlinked file edits the warehouse working tree — no separate "push my changes back" step before contributing.
  • Cross-project visibility. If two projects share the same artifact, editing it in Project A makes the change visible in Project B immediately.

This is what makes the contribution loop tight: there is no copy step, so the agent's edit is the warehouse edit.

The Contribution Loop

The workflow is bidirectional, and most edits happen inside an agent session. The agent either edits symlinked warehouse files directly, or uses one of the bundled authoring skills (record-knowledge, record-skill) — these write to the warehouse and append a wiring entry to pending.yaml. abc adopt then promotes pending entries into beacon.yaml, and abc sync refreshes symlinks so the new artifact is immediately usable. To push the warehouse changes upstream, invoke the /contribute-warehouse bundled skill — it lints, scans for duplicates, splits the changes into cohesive commits, and atomically pushes once.

Contribution loop Four-node cycle: agent edits and authors via symlinks and bundled skills; abc adopt and abc sync wire and refresh the project; the contribute-warehouse skill pushes upstream; teammates abc sync and abc adopt pull and wire on their side, restarting the cycle. agent edits & authors direct symlink edits or /record-knowledge, /record-skill abc adopt → abc sync wire pending entries, refresh symlinks /contribute-warehouse lint → cohesive commits → atomic push teammates abc sync (pull warehouse) + abc adopt (their pendings)

abc adopt and abc sync both run on each side of the loop — abc adopt to wire your own pending entries (from authoring skills you ran), abc sync to refresh symlinks against the current warehouse HEAD.

Next: Artifact Types

Each artifact type has distinct behavior around installation, scope, and contribution. → Artifact Types