From affafe762c1d698062a1ff9649998afeba80914d Mon Sep 17 00:00:00 2001 From: Song Yikun Date: Mon, 18 May 2026 18:01:44 +0800 Subject: [PATCH 1/7] =?UTF-8?q?docs:=20phase=20A=20=E2=80=94=20delete=20ti?= =?UTF-8?q?er=201=20duplicates,=20migrate=20tier=202=20small=20pages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Part of PER-190 docs consolidation. Removes pure duplicates already covered by the mkdocs site and migrates two small conceptual pages. - delete docs/README.md (superseded by mkdocs nav) - delete docs/cli-reference.md (stub; site-docs/reference/cli.md canonical) - delete docs/artifact-type-matrix.md (covered by concepts/artifact-types.md) - migrate docs/no-project-overrides.md → concepts/design-decisions.md - migrate docs/understanding-agent-skills.md → concepts/what-is-a-skill.md - nav: add What Is a Skill + Design Decisions under Concepts Refs PER-190 --- docs/README.md | 86 --------------- docs/artifact-type-matrix.md | 101 ------------------ docs/cli-reference.md | 28 ----- mkdocs.yml | 2 + .../concepts/design-decisions.md | 17 +-- .../concepts/what-is-a-skill.md | 28 +++-- 6 files changed, 26 insertions(+), 236 deletions(-) delete mode 100644 docs/README.md delete mode 100644 docs/artifact-type-matrix.md delete mode 100644 docs/cli-reference.md rename docs/no-project-overrides.md => site-docs/concepts/design-decisions.md (85%) rename docs/understanding-agent-skills.md => site-docs/concepts/what-is-a-skill.md (79%) diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index f5c6f36..0000000 --- a/docs/README.md +++ /dev/null @@ -1,86 +0,0 @@ -# Documentation Overview - -This directory contains **conceptual design documentation** that drives the agentic coding practices setup. For **practical how-to guides**, see the [guides/](../guides/) directory. - ---- - -## Conceptual Design Documents - -### Core Architecture - -**[Agentic Warehouse Design](./agentic-warehouse-design.md)** -- High-level design philosophy and motivation -- Central repository model (contexts, knowledge, skills) -- Two-tier structure (context + knowledge) -- Component organization and discovery patterns -- Workflow: Setup → Use → Update → Contribute - -### Boot Context Design - -**[Boot Context Design](./boot-context-design/)** -- Comprehensive documentation on AGENTS.md architecture -- Three-tier context model (Warehouse → User → Project) - -Files: -- **[agents-md-architecture.md](./boot-context-design/agents-md-architecture.md)** - Three-tier architecture overview, decision framework, anti-patterns -- **[project-level-agents-design.md](./boot-context-design/project-level-agents-design.md)** - Deep-dive into project-level AGENTS.md with detailed patterns - -### Development Methodology - -**[Spec-Driven Development](./spec-driven-development.md)** -- Structured approach to feature planning -- Two-phase process: Specification → Implementation -- Reduces ambiguity and improves AI collaboration - -**[Specs vs. Artifacts](./specs-vs-artifacts.md)** -- Clarifies the distinction between project specs and warehouse artifacts -- When specs should (and should not) live in the warehouse -- Blueprint vs. building code analogy - -### Concepts - -**[Understanding Agent Skills](./understanding-agent-skills.md)** -- What an agent skill is — defined by outcome, not implementation -- The spectrum: cognitive, action, and workflow skills -- Why "everything is a prompt" and what that means for skill design - ---- - -## Practical Guides - -For step-by-step instructions and how-to guides, see: - -- **[guides/getting-started.md](../guides/getting-started.md)** - Onboarding and first sync -- **[guides/warehouse-contribution-guide.md](../guides/warehouse-contribution-guide.md)** - Contributing improvements - ---- - -## Document Purpose - -| Document | Purpose | Audience | -|----------|---------|----------| -| `agentic-warehouse-design.md` | Understand the overall architecture | Architects, team leads setting up warehouse | -| `boot-context-design/agents-md-architecture.md` | Understand three-tier AGENTS.md model | Everyone writing AGENTS.md files | -| `boot-context-design/project-level-agents-design.md` | Learn how to write effective project AGENTS.md | Project maintainers | -| `spec-driven-development.md` | Learn structured feature planning | Developers planning features | -| `specs-vs-artifacts.md` | Understand distinction between specs and artifacts | Everyone | -| `understanding-agent-skills.md` | Understand what agent skills are conceptually | Anyone designing or evaluating skills | - ---- - -## Reading Order - -**For new users:** -1. Start with [Agentic Warehouse Design](./agentic-warehouse-design.md) - understand the big picture -2. Read [agents-md-architecture.md](./boot-context-design/agents-md-architecture.md) - understand the three tiers -3. When creating project AGENTS.md, use [project-level-agents-design.md](./boot-context-design/project-level-agents-design.md) as reference -4. For practical usage, move to [guides/](../guides/) - -**For contributors:** -1. Start with design docs to understand philosophy -2. Check [guides/warehouse-contribution-guide.md](../guides/warehouse-contribution-guide.md) for process - -**For developers:** -1. Read [Spec-Driven Development](./spec-driven-development.md) first -2. Then [project-level-agents-design.md](./boot-context-design/project-level-agents-design.md) for context management -3. Use [guides/](../guides/) for day-to-day tasks diff --git a/docs/artifact-type-matrix.md b/docs/artifact-type-matrix.md deleted file mode 100644 index d783830..0000000 --- a/docs/artifact-type-matrix.md +++ /dev/null @@ -1,101 +0,0 @@ -# Artifact Type Matrix - -How the four warehouse artifact types differ by scope and tool-specificity — and how those differences drive the design of every `abc` command. - -**Last Updated:** 2026-04-12 - ---- - -## The Two Axes - -Every artifact in a warehouse can be described by two independent questions: - -**1. Project scope** — Does this artifact belong to one project, or is it useful across all projects on a machine? - -**2. Tool specificity** — Is this artifact consumed in a way that is identical regardless of which AI tool reads it, or does it need to be installed in a tool-specific location to function? - -Those two questions produce four cells: - -| | Tool-agnostic | Tool-specific | -|---|---|---| -| **Project-scoped** | 📄 Contexts · 🧠 Knowledge | ⚡ Skills · 🤖 Agents | -| **Global** | — | — | - -The bottom-left cell (global + tool-agnostic) is intentionally empty: a globally shared, tool-agnostic artifact would be a system-wide context file with no natural home, which is not a pattern Agentic Beacon supports. - ---- - -## Why Each Artifact Falls Where It Does - -### Contexts — project-scoped, tool-agnostic - -Contexts are boot instructions: coding standards, architectural constraints, team conventions. They are consumed by being *referenced* in a config file that the agent reads at session start (`opencode.json`, `AGENTS.md`, etc.). - -- **Project-scoped** because the standards relevant to a data pipeline project differ from those in a mobile app. Each project controls which contexts it loads. -- **Tool-agnostic** because the content is plain markdown. The reference mechanism (an entry in `opencode.json` vs. an `@include` in `AGENTS.md`) adapts to the tool, but the file itself does not change. - -### Knowledge — project-scoped, tool-agnostic - -Knowledge files (decisions, lessons, facts) are atomic reference documents. They exist to be pointed at from a context file or fetched on demand. - -- **Project-scoped** because a project curates which knowledge is relevant to its domain. -- **Tool-agnostic** for the same reason as contexts: plain markdown files, referenced by path. - -### Skills — project-scoped, tool-specific - -Skills are reusable procedures available as slash commands during a session. To function they must be physically present in a tool's live skill directory — the agent discovers them there at runtime. - -- **Project-scoped** because a skill only makes sense when its project dependencies are present (e.g. a `run-migrations` skill assumes the project has a migrations setup). -- **Tool-specific** because each tool has its own installation path: - - OpenCode: `.opencode/skills//` and `.opencode/command/.md` - - Claude Code: `.claude/skills//` and `.claude/commands/.md` - - The skill directory must be present in each tool's location for the tool to discover it. Under the symlink-based sync model, this is achieved by symlinking individual skill files into the project's `.agentic-beacon/artifacts/skills/` tree and wiring each tool's live skill directory via per-tool installation. - -### Agents — project-scoped, tool-specific - -Agent definitions are sub-agent profiles (e.g. a "code reviewer" agent that can be invoked from the current project). They have no dependency on any one project's codebase. - -- **Project-scoped** because agents are declared per-project in `beacon.yaml.artifacts.agents`. -- **Tool-specific** because each tool has its own project-local agent directory: - - Claude Code: `.claude/agents/` - - OpenCode: `.opencode/agents/` - ---- - -## How the Matrix Shapes Command Design - -### `abc sync` - -`abc sync` handles all four types but applies different logic to each cell: - -| Artifact | What sync does | -|---|---| -| Contexts | Creates symlinks at `.agentic-beacon/artifacts/contexts/` pointing into the warehouse clone; adds path references to `opencode.json` / `AGENTS.md` | -| Knowledge | Creates symlinks at `.agentic-beacon/artifacts/knowledge/`; no automatic wiring (referenced from contexts) | -| Skills | Creates symlinks at `.agentic-beacon/artifacts/skills/`; then wires each detected tool's live skill and command directories | -| Agents | Reads `agents/` from the warehouse; creates artifact symlinks at `.agentic-beacon/artifacts/agents/.md` pointing into the warehouse, then per-tool symlinks at project-local `.claude/agents/.md` and `.opencode/agents/.md` pointing at those artifact files | - -The asymmetry between knowledge and skills is intentional: knowledge does not need to be in a tool-specific location because agents read it via a path reference in the context. Skills need to be wired into tool-specific directories because agents discover them by scanning those directories. - -Agents follow a **two-hop symlink** model: the per-tool symlinks at `.claude/agents/.md` and `.opencode/agents/.md` point at the artifact-layer symlink under `.agentic-beacon/artifacts/agents/.md`, which in turn points at the warehouse file. This indirection keeps `abc list / status / contribute` consistent across artifact types — all four cells route through `.agentic-beacon/artifacts/`. - -### `abc warehouse status` - -`abc warehouse status` reports uncommitted and unpushed state of the warehouse clone, scoped by the current project's `beacon.yaml`. Because symlinks collapse project-vs-warehouse duplication into a single physical file, there is no project-vs-warehouse delta to compute — the question "what did I change in this project?" becomes "what's unstaged/uncommitted in the warehouse?". - -- **Contexts / Knowledge / Skills**: runs `git status` / `git diff` in the warehouse working tree, filtered to paths matched by `beacon.yaml`. -- **Agents**: surfaced by `abc warehouse status` filtering when declared in `beacon.yaml`; editing via a project symlink writes to the warehouse working tree. - -### `abc warehouse contribute` - -`abc warehouse contribute` commits modifications inside the warehouse clone. The matrix determines what is committed: - -- **Contexts / Knowledge / Skills**: any warehouse working-tree modifications to paths matched by the project's `beacon.yaml`. The source is the warehouse file itself — editing via a project symlink is writing to the warehouse. -- **Agents**: auto-contributed when declared in `beacon.yaml`; editing via a project symlink is writing to the warehouse. - ---- - -## Summary - -The two-axis model keeps the framework internally consistent: knowing an artifact's scope and tool-specificity tells you exactly where it lives, how it is installed, where `abc warehouse status` looks for it, and what `abc warehouse contribute` commits. Adding a new artifact type only requires deciding where it sits in the matrix — the rest of the command behavior follows. diff --git a/docs/cli-reference.md b/docs/cli-reference.md deleted file mode 100644 index 934ec78..0000000 --- a/docs/cli-reference.md +++ /dev/null @@ -1,28 +0,0 @@ -# CLI Reference - -**Platform support:** macOS and Linux only. - -## Warehouse Commands - -| Command | Description | -|---------|-------------| -| `abc warehouse init ` | Initialize a new warehouse repository | -| `abc warehouse connect --path ` | Connect a project to a local warehouse clone | -| `abc warehouse status [] [--all]` | Show uncommitted warehouse edits (scoped by `beacon.yaml` unless `--all`) | -| `abc warehouse contribute -m "…" [--push]` | Commit warehouse edits, optionally push | -| `abc warehouse list` | List artifacts available in the connected warehouse | -| `abc warehouse template-upgrade` | Upgrade template-generated files in an existing warehouse | - -## Project Commands - -| Command | Description | -|---------|-------------| -| `abc adopt` | Interactively browse and select warehouse artifacts via TUI; writes to `beacon.yaml` | -| `abc sync` | Create/repair symlinks for all artifacts declared in `beacon.yaml`; wires agent config | -| `abc sync --dry-run` | Preview the symlink operations without touching the filesystem | -| `abc sync --contribute-local` / `--discard-local` | Non-interactive migration from a copy-based tree | -| `abc doctor` | Validate project health: warehouse connection, `beacon.yaml` validity, broken symlinks | -| `abc reset` | Force-rebuild all symlinks from the warehouse | -| `abc list` | List synced artifacts; `abc list agents` shows agents wired into the current project (`.claude/agents/`, `.opencode/agents/`) | -| `abc status` | Show current warehouse connection and project sync status | -| `abc clean` | Remove synced artifacts from the project | diff --git a/mkdocs.yml b/mkdocs.yml index 9555b99..504f03f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -79,9 +79,11 @@ nav: - Quick Start: quickstart.md - Concepts: - How It Works: concepts/how-it-works.md + - What Is a Skill: concepts/what-is-a-skill.md - Bundled Skills: concepts/bundled-skills.md - Pending & Adoption: concepts/pending-and-adoption.md - Artifact Types: concepts/artifact-types.md + - Design Decisions: concepts/design-decisions.md - Guides: - Creating a Warehouse: guides/warehouse-creation.md - Connecting a Project: guides/connecting-projects.md diff --git a/docs/no-project-overrides.md b/site-docs/concepts/design-decisions.md similarity index 85% rename from docs/no-project-overrides.md rename to site-docs/concepts/design-decisions.md index 4dbfcb7..7774c45 100644 --- a/docs/no-project-overrides.md +++ b/site-docs/concepts/design-decisions.md @@ -1,13 +1,18 @@ -# Decision: No Project-Local Artifact Overrides +# Design Decisions + +This page records architectural decisions that shape how Agentic Beacon behaves. Each entry captures a decision, the reasoning behind it, and any historical context worth preserving. New decisions are appended over time. + +--- + +## No Project-Local Artifact Overrides -**Date:** 2026-03-14 **Status:** Accepted (updated 2026-05-03 to reflect the symlink-based sync model) -## Decision +### Decision Agentic Beacon does not support project-local overrides of warehouse artifacts. There is no `overrides/` directory, no `abc override` command, and no mechanism to maintain a diverged version of a warehouse artifact within a project. -## Why +### Why Project-local overrides promote divergence. If an artifact needs to be different for a project, that difference is almost always worth sharing with the whole team — which means it belongs in the warehouse, not hidden in a project directory. @@ -21,10 +26,10 @@ The right workflow when a local change is discovered: This keeps the warehouse as the single source of truth and ensures improvements discovered in one project benefit all projects. -## Genuine per-project variation +### Genuine per-project variation When a team genuinely needs different harness behavior for different projects, the correct response is to **author distinct artifacts** (e.g. `skills/code-review-python/` vs `skills/code-review-ts/`) and select between them via each project's `beacon.yaml`. The artifact system supports arbitrary naming; there is no need to duplicate the same-named file with different content. -## Historical note +### Historical note Earlier versions of this document described the sync-time `--preserve` flag as "a narrow escape hatch for avoiding accidental overwrites during an active editing session." Under the symlink-based sync model, `abc sync` does not overwrite files (it creates or repairs symlinks pointing at the warehouse), and the preserve flag was removed from `abc sync`. diff --git a/docs/understanding-agent-skills.md b/site-docs/concepts/what-is-a-skill.md similarity index 79% rename from docs/understanding-agent-skills.md rename to site-docs/concepts/what-is-a-skill.md index 38635e1..419de3b 100644 --- a/docs/understanding-agent-skills.md +++ b/site-docs/concepts/what-is-a-skill.md @@ -1,22 +1,20 @@ -# Understanding Agent Skills +# What Is a Skill? -A conceptual framework for thinking about what agent skills are and how to categorize them. - -**Last Updated:** 2026-03-10 +A conceptual primer on agent skills — what they are, how to think about them, and where they sit in Agentic Beacon. --- -## What Is an Agent Skill? +## A Skill Is an Abstraction of a Capability -The best way to view an agent skill is as an **abstraction of a capability** — a modular unit of work the agent knows how to perform. Define a skill by the **outcome it enables**, not by how it is implemented under the hood. +The best way to view an agent skill is as **an abstraction of a capability** — a modular unit of work the agent knows how to perform. Define a skill by the **outcome it enables**, not by how it is implemented under the hood. --- -## The Spectrum of Agent Skills +## The Spectrum of Skills -Agent skills exist on a spectrum from purely cognitive to purely mechanical. +Skills exist on a spectrum from purely cognitive to purely mechanical. -### Cognitive Skills +### Cognitive skills A set of instructions, a reasoning framework, or a persona injected into the agent's context. The agent doesn't execute code — it changes *how it thinks*. @@ -24,7 +22,7 @@ A set of instructions, a reasoning framework, or a persona injected into the age The skill gives the agent a repeatable, reliable way to perform a specific intellectual task. -### Action Skills +### Action skills A deterministic tool the agent can invoke to interact with the outside world — a function call, an API integration, a CLI command. @@ -32,7 +30,7 @@ A deterministic tool the agent can invoke to interact with the outside world — The skill extends the agent's reach beyond its training data into external systems. -### Workflow Skills +### Workflow skills A multi-step, orchestrated process combining cognitive and action skills — involving loops, conditional logic, multiple prompts, and multiple tools. @@ -40,7 +38,7 @@ A multi-step, orchestrated process combining cognitive and action skills — inv --- -## The "Everything Is a Prompt" Insight +## Everything Is a Prompt Under the hood, even function calls are just prompts. When you give an LLM access to a `search_web` tool, you're not giving it code — you're injecting a prompt that says: *"You have access to a tool called search_web. To use it, output JSON formatted like this..."* @@ -51,7 +49,7 @@ The LLM's only interface with the world is text in and text out. The line betwee --- -## Practical Implications +## Where Skills Fit in Agentic Beacon Think of a skill as a **black-box interface**: it takes an input, does some agentic work, and returns an output. When designing your skill library, don't limit yourself to just one type: @@ -67,5 +65,5 @@ In Agentic Beacon, `SKILL.md`-based skills are primarily **cognitive and workflo ## Further Reading -- [Creating Skills](../guides/creating-skills.md) — How to write and distribute skills in Agentic Beacon -- [Agentic Warehouse Design](./agentic-warehouse-design.md) — Where skills fit in the overall architecture +- [Bundled Skills](bundled-skills.md) — the three skills shipped inside `abc` itself +- [Creating Skills](../guides/creating-skills.md) — how to write and distribute warehouse skills From 8bccffaaaabbcef1c73c9067fdd0fe144364b604 Mon Sep 17 00:00:00 2001 From: Song Yikun Date: Mon, 18 May 2026 18:04:14 +0800 Subject: [PATCH 2/7] =?UTF-8?q?docs:=20phase=20B=20=E2=80=94=20migrate=20t?= =?UTF-8?q?ier=202=20conceptual=20pages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Part of PER-190. Migrates the larger conceptual docs into the mkdocs site as new pages, extracting still-valid framing from the legacy agentic-warehouse-design.md without re-adding operational detail that how-it-works.md intentionally drops. - new concepts/philosophy.md — three-questions framing + two-tier model - migrate docs/specs-vs-artifacts.md → concepts/specs-vs-artifacts.md - migrate docs/spec-driven-development.md → guides/spec-driven-development.md - delete docs/agentic-warehouse-design.md (framing extracted into philosophy.md; bulk already covered in how-it-works.md and artifact-types.md) - nav: add Philosophy + Specs vs. Artifacts under Concepts; add Spec-Driven Development under Guides Refs PER-190 --- docs/agentic-warehouse-design.md | 667 ------------------ docs/spec-driven-development.md | 199 ------ mkdocs.yml | 3 + site-docs/concepts/philosophy.md | 78 ++ .../concepts}/specs-vs-artifacts.md | 121 ++-- site-docs/guides/spec-driven-development.md | 199 ++++++ 6 files changed, 342 insertions(+), 925 deletions(-) delete mode 100644 docs/agentic-warehouse-design.md delete mode 100644 docs/spec-driven-development.md create mode 100644 site-docs/concepts/philosophy.md rename {docs => site-docs/concepts}/specs-vs-artifacts.md (54%) create mode 100644 site-docs/guides/spec-driven-development.md diff --git a/docs/agentic-warehouse-design.md b/docs/agentic-warehouse-design.md deleted file mode 100644 index d47a5dc..0000000 --- a/docs/agentic-warehouse-design.md +++ /dev/null @@ -1,667 +0,0 @@ -# Agentic Warehouse Design - -A high-level design guide for centralized context, knowledge, and skills management in agentic engineering. - -**Last Updated:** 2026-03-10 - -> **Built for OpenCode:** This design was developed with [OpenCode](https://opencode.ai) usage in mind. While we keep patterns as generic as possible, the experience with other AI coding agents may differ. The core concepts (centralized context, progressive disclosure, DRY) remain applicable across tools. - ---- - -## Table of Contents - -1. [Why This Exists: Three Questions](#why-this-exists-three-questions) -2. [Central Repository Model](#central-repository-model) - - [Understanding the Two-Tier Structure: Context + Knowledge](#understanding-the-two-tier-structure-context--knowledge) -3. [Component 1: Contexts (Boot Context Organization)](#component-1-contexts-boot-context-organization) - - [What Are Contexts?](#what-are-contexts) - - [Multi-Tier Context Model](#multi-tier-context-model) - - [Progressive Disclosure Pattern](#progressive-disclosure-pattern) - - [What Goes Where?](#what-goes-where) - - [Collaboration Benefits](#collaboration-benefits) -4. [Component 2: Stateless Knowledge](#component-2-stateless-knowledge) - - [What is Stateless Knowledge?](#what-is-stateless-knowledge) - - [Organization Structure](#organization-structure) - - [Discovery: Proactive vs Reactive Pointers](#discovery-proactive-vs-reactive-pointers) - - [Example: Lesson File Structure](#example-lesson-file-structure) - - [Storage Strategy](#storage-strategy) -5. [Component 3: Skills Organization](#component-3-skills-organization) - - [What Are Skills?](#what-are-skills) - - [Skills vs Knowledge](#skills-vs-knowledge) - - [Organization Structure](#organization-structure-1) - - [Discovery](#discovery) - - [Skill Invocation](#skill-invocation) - - [Testing and Contribution](#testing-and-contribution) -6. [Workflow: Setup → Use → Update → Contribute](#workflow-setup--use--update--contribute) - - [1. Setup (One-time per project)](#1-setup-one-time-per-project) - - [2. Use (Daily development)](#2-use-daily-development) - - [3. Update (Periodic sync)](#3-update-periodic-sync) - - [4. Contribute (Give back improvements)](#4-contribute-give-back-improvements) - - [Technical Notes](#technical-notes) - ---- - -## Why This Exists: Three Questions - -### Q: Why do we need this at all? - -As teams adopt AI coding agents, inconsistent practices emerge quickly: each project develops its own conventions, agents receive different instructions, and valuable patterns discovered in one project never reach others. The result is fragmented quality, slow onboarding, and duplicated effort. - -The answer is applying **DRY (Don't Repeat Yourself) to agentic knowledge**. - -Instead of each project maintaining its own copy of coding standards, agent instructions, and learned patterns, centralize them in a warehouse where: -- **One update propagates everywhere** — fix a pattern once, all projects benefit -- **Teams learn collectively** — a lesson discovered in one project is shared with all -- **Onboarding is instant** — new developers and agents inherit organizational knowledge automatically -- **Nothing gets lost** — valuable conventions that emerge organically get captured and preserved - ---- - -### Q: Why markdown files instead of a local RAG system? - -The short answer: **the problem doesn't need that solution.** - -RAG (Retrieval-Augmented Generation) is designed for large-scale, unstructured, frequently-changing content where users don't know what they're looking for. A warehouse of organizational standards is none of those things. - -| | File-Based (our approach) | RAG-Based | -|---|---|---| -| **Setup** | Copy markdown files | Vector DB + embedding pipeline + maintenance | -| **Dependencies** | Git, filesystem | Chroma/Pinecone/Weaviate, embedding models | -| **Adoption barrier** | Very low (everyone knows Git) | High (requires ML/infrastructure expertise) | -| **Maintenance** | Standard Git workflow | DB maintenance, reindexing, embedding updates | -| **Versioning** | Native Git history | Custom versioning layer | -| **Human readability** | Direct markdown editing | Requires retrieval interface | -| **Contribution** | Standard PR workflow | More complex (embeddings must be regenerated) | - -The warehouse stores curated, structured standards — typically hundreds of KB, not gigabytes. Agents don't need to *search* for relevant knowledge; context files tell them explicitly what to read and when. This two-tier pointer model (boot context → on-demand knowledge files) achieves the same goal as RAG without the infrastructure overhead. - -RAG would make sense if the warehouse held thousands of unstructured documents, or if content changed hourly, or if users were doing exploratory search. None of those apply here. - ---- - -### Q: Why keep this lightweight? Won't we need more features eventually? - -**The agentic engineering landscape is shifting rapidly.** What's best practice today may be superseded in six months — by new agent capabilities, new tool conventions, new paradigms entirely. A heavy framework with strong opinions on structure bakes in assumptions that may not age well. - -Keeping Agentic Beacon lightweight is a deliberate bet: - -- **Low adoption cost** — teams can try it without committing to infrastructure -- **Easy to abandon or replace** — if something better comes along, the cost of migrating away is minimal (it's just markdown files and a small CLI) -- **Structure follows the team, not the tool** — the inner organization of your warehouse is entirely up to you; the framework only prescribes the three top-level directories -- **Works with any agent today** — no custom integrations, no proprietary formats; markdown files work with every coding agent that exists - -The goal is to solve the DRY problem for agentic knowledge without creating a new dependency problem. A warehouse is just a Git repo. Artifacts are just markdown files. The CLI is just a sync tool. If the paradigm shifts again, your knowledge doesn't disappear — it's still plain text in a git repository. - ---- - -## Central Repository Model - -All reusable context, knowledge, and skills live in a **central repository** with this structure: - -``` -agentic-engineering-central/ -├── contexts/ # AGENTS.md files (global, language, domain) -├── knowledge/ # Decisions, lessons, facts (referenced by contexts) -└── skills/ # Reusable workflows and procedures -``` - -**Key principles:** -- **Single source of truth:** Updates propagate to all projects -- **Versioned:** Changes go through PR review -- **Discoverable:** CLI provides interactive selection -- **Testable:** Skills include test harnesses for validation - -The repository acts as a "warehouse" where projects select what they need, install locally, and stay synchronized with organizational standards. - -### Understanding the Two-Tier Structure: Context + Knowledge - -This design uses a **two-tier approach** to manage agent information efficiently: - -**Tier 1: Contexts** (Boot context - loaded immediately) -- Lightweight context files that agents see on session start -- Contains **summaries and pointers**, not full details -- Think: "What does the agent need to know exists?" -- Kept minimal to reduce token consumption - -**Naming conventions:** -- **Warehouse level:** Simple filenames (e.g., `global.md`, `python.md`, `data-platform.md`) -- **Project level:** Single `AGENTS.md` file at the project root -- **User level:** Single `AGENTS.md` file (at `~/.config/opencode/AGENTS.md`) - -The warehouse uses flexible naming because files are loaded via `opencode.json` configuration. Project and user levels use `AGENTS.md` as a convention for easy identification. - -**Tier 2: Knowledge** (Deep context - loaded on demand) -- Detailed explanations, rationale, examples -- Referenced by contexts via pointer system -- Think: "What are the full details when needed?" -- Agents pull this when they need deeper understanding - -**Why both?** - -Without this separation, AGENTS.md files become bloated with details agents rarely need, wasting tokens and making it hard to scan. The two-tier approach enables: -- **Fast scanning:** Agents quickly find relevant topics in contexts -- **Progressive disclosure:** Agents dive deep only when needed -- **Token efficiency:** Don't load detailed rationale for every rule on every session -- **Maintainability:** Update detailed docs without cluttering boot context - -**Examples:** - -**Example 1: Proactive Pointer (Agent must read immediately)** - -```markdown -# In python.md (Tier 1: Context) -## Type Annotations - -**Rule:** Only quote type annotations for forward references. - -**Read:** [Common mistakes](.agentic-beacon/artifacts/knowledge/languages/python/lessons/quoted-type-annotations.md) -``` - -```markdown -# In knowledge/languages/python/lessons/quoted-type-annotations.md (Tier 2: Knowledge) -## Lesson: Agents Often Over-Quote Type Annotations - -**Agent Failure Mode:** Agents quote all type annotations unnecessarily: - -# Incorrect - unnecessary quotes -def process(data: "list[Document]") -> "ProcessedResult": - return result - -**Correct Pattern:** Only quote for forward references or circular imports: - -# Correct - no quotes for available types -def process(data: list[Document]) -> ProcessedResult: - return result - -**Guardrail:** Before quoting a type annotation, ask: -1. Is this a forward reference (type defined later in file)? -2. Is this avoiding a circular import? -3. If neither, remove the quotes. -``` - -**Example 2: Reactive Pointer (Agent reads when needed)** - -```markdown -# In data-platform.md (Tier 1: Context) -## Troubleshooting - -If DAG parsing fails, consult the debugging checklist. - -**See:** [Airflow debugging checklist](.agentic-beacon/artifacts/knowledge/domains/data-platform/lessons/airflow-debugging-checklist.md) -``` - -```markdown -# In knowledge/domains/data-platform/lessons/airflow-debugging-checklist.md (Tier 2: Knowledge) -## Lesson: Pre-Flight Checklist for Airflow Debugging - -Run this checklist BEFORE debugging anything. 60% of issues are caught here. - -**Step 1: Environment Variables** -```bash -echo $DOT_PROJECT_PATH # Should be set -echo $AIRFLOW_HOME # Should be set -``` - -**Step 2: Services Running** -```bash -docker ps | grep airflow # Should show containers -``` - -**Step 3: Config Loaded** -```bash -psql $DATABASE_URL -c \ - "SELECT COUNT(*) FROM pipeline_configs WHERE workspace='your_workspace';" -# Should return > 0 -``` - -[... detailed troubleshooting steps continue ...] - -**Key difference:** -- **Proactive (`Read:`)**: Agent must load immediately—affects every file they touch -- **Reactive (`See:`)**: Agent loads only when encountering the specific problem - ---- - -## Component 1: Contexts (Boot Context Organization) - -### What Are Contexts? - -Context files serve as **boot context** - the knowledge agents see immediately on session start. They provide instructions, standards, and pointers to deeper knowledge. - -**Naming conventions:** -- **Warehouse:** Simple filenames like `global.md`, `python.md`, `data-platform.md` -- **Project:** Single `AGENTS.md` at the project root -- **User:** Single `AGENTS.md` at `~/.config/opencode/AGENTS.md` - -### Multi-Tier Context Model - -Context is organized into three tiers: - -**Required Context: Global** -- Universal practices applicable to all projects -- **Examples:** Spec-driven development, session handoff patterns, commit conventions -- **When to use:** Always included in every project setup - -**Optional Contexts: Modular** -- **Language-specific:** Python, TypeScript, Java, Go, etc. - - Standards for a specific programming language - - Examples: Python type annotation rules, TypeScript interface patterns -- **Domain-specific:** Data Platform, Web App, ML/AI, DevOps, etc. - - Patterns for teams working in similar problem domains - - Examples: Data Platform (PostgreSQL, Airflow, DBT), Web App (Auth, API design) -- **Mix and match:** Choose multiple contexts based on project needs -- **When to use:** Select what applies to your project's technology stack and problem domain - -**Project Context: Unique** -- Project-specific architecture, troubleshooting guides, module references -- **Examples:** "Our microservices communicate via gRPC", "See docs/architecture.md for service map" -- **When to use:** Information that only applies to this specific codebase - -### Progressive Disclosure Pattern - -Context files should be a **pointer system**, not an encyclopedia. - -**In context files:** -- 1-2 sentence summary of the pattern or rule -- Reference to detailed knowledge elsewhere - -**Example:** -```markdown -## Database Standards - -**Rule:** Always use PostgreSQL for development, never SQLite. - -**Rationale:** [See decision doc](.agentic-beacon/artifacts/knowledge/decisions/postgres-over-sqlite.md) - -**Troubleshooting:** [Connection pool guide](.agentic-beacon/artifacts/knowledge/lessons/postgres-troubleshooting.md) -``` - -**Benefits:** -- Keeps context files scannable (agents can quickly find what they need) -- Detailed knowledge lives in searchable, versioned files -- Agents pull deeper context only when needed - -### What Goes Where? - -**Decision framework:** - -| Question | Yes → | No → | -|----------|-------|------| -| Does this apply to all projects org-wide? | **Global context** (`global.md`) | ↓ | -| Does this apply to all projects using this language? | **Language context** (e.g., `python.md`) | ↓ | -| Does this apply to multiple teams in the same domain? | **Domain context** (e.g., `data-platform.md`) | ↓ | -| Is this unique to this project? | **Project AGENTS.md** | ↓ | -| Is this a detailed explanation? | **Knowledge file** (reference from context) | | - -**Anti-patterns to avoid:** -- ❌ Copying the same pattern into multiple project `AGENTS.md` files → Promote to warehouse context -- ❌ Putting implementation details in context files → Extract to knowledge file -- ❌ Creating language-specific patterns used by only one team → Consider if it's truly language-wide or just domain-specific - -### Collaboration Benefits - -**For teams:** -- **Consistency:** All projects using the same language/stack see the same standards -- **Evolution:** Improvements in one project benefit all others -- **Onboarding:** New developers get full context automatically -- **Discoverability:** CLI shows what's available, teams don't need to guess - -**For individuals:** -- **Minimal setup:** Install once, works everywhere -- **Stay current:** Update command pulls latest standards -- **Contribute easily:** Proven patterns flow back to central repo - ---- - -## Component 2: Stateless Knowledge - -### What is Stateless Knowledge? - -Stateless knowledge represents **timeless, atomic, reusable insights** - decisions made, lessons learned, and established facts that remain valid across projects and sessions. Unlike session-specific context or runtime state, this knowledge is **stable, shareable, and reference-able**. - -**Three types of stateless knowledge:** - -**Decisions** -- Technical choices made and their rationale -- Examples: "Why Pydantic over dataclasses", "Why PostgreSQL over SQLite" -- Format: Problem → Options → Decision → Rationale - -**Lessons** -- Patterns where agents commonly fail or get distracted -- Anti-patterns and guardrails to prevent repeated mistakes -- Examples: "Agents over-quote type annotations", "Agents create premature abstractions" -- Format: Agent failure mode → Correct pattern → Guardrail - -**Facts** -- Established technical information and configurations -- Examples: "Database port mappings", "API endpoint patterns", "Naming conventions" -- Format: Statement → Context → Usage notes - -### Organization Structure - -Knowledge is organized to **mirror context structure**, enabling selective import based on which contexts a project uses. - -``` -knowledge/ -├── global/ # Universal knowledge (all projects) -│ ├── decisions/ -│ │ └── conventional-commits.md -│ ├── lessons/ -│ │ └── session-handoff-patterns.md -│ └── facts/ -│ └── git-workflow.md -├── languages/ # Language-specific knowledge -│ ├── python/ -│ │ ├── decisions/ -│ │ │ └── why-pydantic-over-dataclass.md -│ │ └── lessons/ -│ │ └── quoted-type-annotations.md -│ ├── typescript/ -│ │ ├── decisions/ -│ │ └── lessons/ -│ └── java/ -│ └── decisions/ -└── domains/ # Domain-specific knowledge - ├── data-platform/ - │ ├── decisions/ - │ │ └── two-workflow-approach.md - │ ├── lessons/ - │ │ └── airflow-debugging-checklist.md - │ └── facts/ - │ └── infrastructure-ports.md - ├── web-app/ - │ ├── decisions/ - │ │ └── auth-pattern.md - │ └── facts/ - │ └── api-endpoints.md - └── ml-ai/ - ├── decisions/ - └── lessons/ -``` - -**Knowledge organization by scope:** - -**Global knowledge** (`knowledge/global/`) -- Referenced by `global.md` (required for all projects) -- Universal practices: commit conventions, session handoffs, spec-driven development - -**Language knowledge** (`knowledge/languages/*/`) -- Referenced by language-specific contexts (e.g., `python.md`, `typescript.md`) -- Language-specific patterns and anti-patterns - -**Domain knowledge** (`knowledge/domains/*/`) -- Referenced by domain-specific contexts (e.g., `data-platform.md`, `web-app.md`) -- Domain-specific infrastructure, tools, and practices - -**Selective installation:** When teams configure `beacon.yaml` and run `abc sync`, the CLI creates symlinks for the declared artifacts under `.agentic-beacon/artifacts/`. A project using Python + Data Platform knowledge gets `global/`, `languages/python/`, and `domains/data-platform/` knowledge, but not `web-app/` or `typescript/` knowledge. - -### Discovery: Proactive vs Reactive Pointers - -Agents discover knowledge through **pointer systems** in context files with two modes: - -**Proactive Pointers (Agent must read immediately)** - -Example in `global.md`: -```markdown -## Commit Conventions - -**Rule:** Use conventional commits format for all commits. - -**Read:** [Conventional commits guide](.agentic-beacon/artifacts/knowledge/global/decisions/conventional-commits.md) -``` - -Example in `data-platform.md`: -```markdown -## Development Workflow - -**Rule:** Use two-workflow approach (venv for parsing, Docker for execution). - -**Read:** [Two-workflow decision](.agentic-beacon/artifacts/knowledge/domains/data-platform/decisions/two-workflow-approach.md) -``` - -Use proactive pointers for: -- Critical patterns agents must internalize before coding -- Common failure modes agents encounter frequently -- Standards that affect every file they touch - -**Reactive Pointers (Agent reads when needed)** - -Example in `data-platform.md`: -```markdown -## Troubleshooting - -If DAG parsing fails, consult the debugging checklist. - -**See:** [Airflow debugging checklist](.agentic-beacon/artifacts/knowledge/domains/data-platform/lessons/airflow-debugging-checklist.md) - -Use reactive pointers for: -- Troubleshooting guides consulted during errors -- Detailed explanations of complex topics -- Reference material for edge cases - -### Example: Lesson File Structure - -**File:** `knowledge/languages/python/lessons/quoted-type-annotations.md` - -**Content:** -``` -## Lesson: Agents Often Over-Quote Type Annotations - -**Agent Failure Mode:** Agents quote all type annotations unnecessarily: - -# Incorrect - unnecessary quotes -def process(data: "list[Document]") -> "ProcessedResult": - return result - -**Correct Pattern:** Only quote for forward references or circular imports: - -# Correct - no quotes for available types -def process(data: list[Document]) -> ProcessedResult: - return result - -# Correct - quotes only for forward reference -def create_node(self) -> "TreeNode": - return TreeNode() - -**Guardrail:** Before quoting a type annotation, ask: -1. Is this a forward reference (type defined later in file)? -2. Is this avoiding a circular import? -3. If neither, remove the quotes. - -**When this matters:** Python 3.10+ with `from __future__ import annotations` makes quotes unnecessary in most cases. -``` - -### Storage Strategy - -**Minimize AGENTS.md, maximize knowledge files:** - -**In context file (minimal):** -```markdown -## Type Annotations - -Use primitive types when available (`list` not `List`). - -**Read:** [Common annotation mistakes](.agentic-beacon/artifacts/knowledge/languages/python/lessons/quoted-type-annotations.md) -``` - -**In knowledge file (detailed):** -- Full context and examples -- Agent failure modes -- Correct patterns with code samples -- Guardrails and decision criteria - -**Benefits:** -- Context files stay scannable -- Knowledge is searchable and versioned -- Multiple contexts can reference the same knowledge -- Teams can update knowledge without touching all contexts - ---- - -## Component 3: Skills Organization - -### What Are Skills? - -Skills are **reusable workflows, procedures, and specialized contexts** that agents can load on-demand. Unlike knowledge (which is atomic and informational), skills are **procedural and actionable**. - -**Skills encompass everything that is not knowledge:** - -**Procedural Workflows** -- Multi-step processes agents follow -- Examples: "Create a new spec", "Review pull request", "Debug Airflow DAGs" - -**Context Injections** -- Specialized instructions loaded for specific tasks -- Examples: "Load DBT development patterns", "Activate security review mode" - -**Templates and Patterns** -- Structured documents or code patterns -- Examples: "API endpoint template", "Test file structure" - -**Executable Procedures** -- Scripts, tools, or automation bundled with instructions -- Examples: "Setup script + usage guide", "Diagnostic tool + interpretation guide" - -### Skills vs Knowledge - -| Aspect | Knowledge | Skills | -|--------|-----------|--------| -| **Nature** | Informational, atomic | Procedural, multi-step | -| **Scope** | Reusable facts/decisions/lessons | Complete workflows | -| **Level** | Global or optional contexts only | Can be project-specific | -| **Format** | Short markdown files | Instructions + optional templates/scripts | -| **Usage** | Referenced via pointers | Invoked via skill commands | - -**Example distinction:** -- **Knowledge:** "Lesson: Agents over-quote type annotations" (what mistake to avoid) -- **Skill:** "Python type checking workflow" (how to systematically check types in a codebase) - -### Organization Structure - -Skills use a **flat structure** in the central repository: - -``` -skills/ -├── README.md # Catalog (agent-maintained) -├── openspec-propose/ -│ ├── SKILL.md # Primary instructions -│ └── templates/ # Optional templates -│ └── task_brief.md.template -├── openspec-apply-change/ -│ └── SKILL.md -├── pr-review/ -│ ├── SKILL.md -│ └── checklists/ # Optional supporting files -│ └── security-checklist.md -└── airflow-debug/ - ├── SKILL.md - └── scripts/ # Optional diagnostic scripts - └── check-config.sh -``` - -**Naming convention:** Use kebab-case for skill directories (e.g., `openspec-propose`, not `openspec_propose`) - -**Optional components within a skill:** -- `templates/` - Structured documents agents fill out -- `scripts/` - Helper scripts or diagnostic tools -- `checklists/` - Reference checklists for complex workflows -- `examples/` - Sample outputs or usage examples - -### Discovery - -**Primary method: CLI** -```bash -# List all available content (including skills) in the connected warehouse -abc list - -# Example output (skills section): -# skills/ -# openspec-propose/ - Create new OpenSpec change with design and tasks -# openspec-apply-change/ - Implement tasks from an OpenSpec change -# pr-review/ - Comprehensive code review for pull requests -``` - -**Secondary method: Browse repository** -- Navigate to `skills/README.md` in the warehouse repository -- Catalog is maintained by agents when skills are added or updated -- Includes skill name, description, and usage notes - -### Skill Invocation - -Once installed in a project, agents invoke skills using skill commands: - -```bash -# Example invocations -/openspec-propose "Add user authentication" -/pr-review -/airflow-debug --check-parsing -``` - -The skill's `SKILL.md` contains detailed instructions agents follow when invoked. - -### Testing and Contribution - -**Testing:** Validation strategies for skills are project-specific. Common approaches include: -- Manual validation in test projects -- Automated test harnesses (if skill includes scripts) -- Peer review before merging to central repo - -**Contribution:** Workflows for contributing improved skills back to the central repository are covered in separate operational documentation. - -**Note:** Both testing and contribution processes depend on organizational practices and tooling. Teams should establish their own conventions based on their CI/CD infrastructure and review processes. - ---- - -## Workflow: Setup → Use → Update → Contribute - -### 1. Setup (One-time per project) - -Connect the project to a warehouse and declare which artifacts to use: - -```bash -abc warehouse connect --path ~/org-warehouse -abc setup -abc adopt # choose contexts, skills, and agents (knowledge is auto-derived) -abc sync -``` - -**Result:** -- Artifacts symlinked to `.agentic-beacon/artifacts/` (contexts, skills, agents) -- Knowledge files auto-derived from markdown links inside adopted contexts and skills -- Project's `opencode.json` can reference the synced contexts -- Project's `AGENTS.md` created for project-specific content - -### 2. Use (Daily development) - -Agents automatically load all configured contexts on session start. Developers don't think about it - it just works. - -### 3. Update (Periodic sync) - -Pull the latest warehouse changes: - -```bash -cd ~/org-warehouse && git pull -# No `abc sync` needed per-project unless beacon.yaml changed — projects read -# warehouse files through symlinks, so the new warehouse content is visible -# immediately after the pull. -cd ~/my-project && abc sync # run only if beacon.yaml was modified or symlinks drifted -``` - -Uncommitted warehouse edits (files you've modified via project symlinks) are surfaced by `abc warehouse status` before you pull. - -### 4. Contribute (Give back improvements) - -When you improve a context, knowledge file, or skill: -- Test locally in your project (edits via `.agentic-beacon/artifacts/` land directly in the warehouse working tree) -- Review uncommitted changes with `abc warehouse status` -- Commit with `abc warehouse contribute -m "…"` (optionally `--push`), or open a PR in the warehouse repository -- Once pushed and pulled by teammates, the updated content is immediately visible across their projects - -### Technical Notes - -- **Artifact location:** Synced artifacts live in `.agentic-beacon/artifacts/` within each project -- **OpenCode native support:** The `instructions` field in `opencode.json` loads context files automatically -- **Glob patterns supported:** `beacon.yaml` supports `contexts/**/*.md` and `skills/*/` style patterns -- **Load order matters:** Project `AGENTS.md` loads last, so it can override global patterns - ---- diff --git a/docs/spec-driven-development.md b/docs/spec-driven-development.md deleted file mode 100644 index 4fc1868..0000000 --- a/docs/spec-driven-development.md +++ /dev/null @@ -1,199 +0,0 @@ -# Spec-Driven Development Guide - -A guide for using spec-driven development approaches in agentic engineering. - -**Last Updated:** 2026-03-06 -**Status:** Draft / To Be Expanded - ---- - -## Overview - -Spec-driven development is a methodology for transforming vague ideas into implementation-ready specifications through structured planning phases. - -**When to use spec-driven development:** -- Complex, multi-component features -- Features requiring cross-team coordination -- Features with unclear or evolving requirements -- When you need to validate approach before significant implementation - -**When NOT to use spec-driven development:** -- Simple, well-understood tasks (1-2 file changes) -- Bug fixes with clear root cause -- Routine maintenance tasks -- Prototyping or exploratory coding - ---- - -## Two-Phase Approach - -### Phase 1: Technical Planning - -**Goal:** Transform free-form ideas into formal, implementation-ready technical plan - -**Process:** -1. **Listen and Parse** - Extract core problem, goals, scope, technical ideas -2. **Generate First Draft** - Create structured technical planning document -3. **Audit and Gap Analysis** - Identify missing information, ask targeted questions -4. **Baseline** - Complete when all open questions answered and user approves - -**Output:** Technical planning document with: -- Clear problem statement and goals -- Testable acceptance criteria -- Explicit in-scope and out-of-scope boundaries -- High-level technical approach -- Identified risks and dependencies -- Impacted modules/systems - -### Phase 2: Task Breakdown - -**Goal:** Decompose technical plan into granular, sequential implementation tasks - -**Process:** -1. **Source Audit** - Access planning document, scan codebase for impacted modules -2. **Decomposition** - Break work into "sprints of one" atomic tasks -3. **Resolution** - Address ambiguities before starting implementation -4. **Handoff** - Deliver actionable task checklist ready for execution - -**Output:** Task breakdown document with: -- User story extracted from plan -- Step-by-step implementation checklist -- Verification steps for each task -- Dependencies and execution order -- Manual intervention steps (if any) - ---- - -## Integration with Agentic Warehouse - -Spec-driven development workflows can be packaged as **skills** in your warehouse: - -``` -skills/ -├── spec-propose/ # Phase 1: Create technical plan -├── spec-breakdown/ # Phase 2: Create task breakdown -└── spec-implement/ # Execute tasks from breakdown -``` - -**Example usage:** -```bash -# Phase 1: Create spec -/spec-propose "Add user authentication with OAuth" - -# Phase 2: Break down into tasks -/spec-breakdown - -# Execute implementation -/spec-implement -``` - ---- - -## Best Practices - -### During Planning -- **Be thorough**: Better to over-specify than under-specify -- **Ask questions**: Don't assume—clarify ambiguities -- **Think about failure**: What happens when things go wrong? -- **Identify manual steps early**: Know what requires human intervention -- **Use diagrams**: Mermaid.js for complex flows - -### During Task Breakdown -- **Small tasks**: Each completable in one focused session -- **Verification steps**: Every task needs confirmation method -- **Logical order**: Dependencies should flow naturally -- **Mark manual steps**: Use `[MANUAL]` prefix to set expectations -- **Don't invent**: Stick to what's in the technical plan - -### General -- **Iterate**: Specs improve with feedback -- **Version control**: Commit after each phase -- **Link to knowledge**: Store decisions in warehouse -- **Keep readable**: Write for humans first, AI second - ---- - -## Document Templates - -### Technical Planning Template - -```markdown -# [Feature Name] - -## 1. Background and Problem Statement -[Clear synthesis of problem and why it needs solving] - -## 2. Goals & Acceptance Criteria -- [ ] AC 1: [Testable criterion] -- [ ] AC 2: [Testable criterion] - -## 3. Scope -### In Scope -[What will be implemented] - -### Out of Scope -[What won't be implemented] - -## 4. Proposed Technical Solution -### High-Level Architecture -[End-to-end flow and data lifecycle] - -### Impacted Modules -- [Module/Path]: [Required modifications] - -### Manual Intervention Requirements -- [Manual Step]: [Description and rationale] - -## 5. Risks and Dependencies -- **Risk:** [Problem] - - **Mitigation:** [Solution] - -## 6. Open Questions -- [ ] [Question to resolve] -``` - -### Task Breakdown Template - -```markdown -# Implementation Plan: [Feature Name] - -## 1. User Story -[Extracted from technical plan] - -## 2. Technical Summary -[Concise summary of solution] - -## 3. Acceptance Criteria -- [ ] AC 1: [From technical plan] -- [ ] AC 2: [From technical plan] - -## 4. Technical Task Checklist - -### Phase 1: Preparation -- [ ] **Step 1:** [Action] - - *Verification:* [How to check] - -### Phase 2: Implementation -- [ ] **Step 2:** [Action] - - *Verification:* [How to check] -- [ ] **[MANUAL] Step 3:** [User action required] - - *User Action:* [What user needs to do] - - *Verification:* [How to confirm] - -## 5. Dependencies -[Internal/external dependencies] - -## 6. Questions & Ambiguities -[Items needing resolution] -``` - ---- - -## Related Resources - -- **[Agentic Warehouse Design](./agentic-warehouse-design.md)** - How to organize specs in your warehouse -- **Implementation Guide** - Building spec-driven skills _(coming soon)_ - ---- - -**Note:** This is a high-level overview. Detailed spec-driven development workflows will be added as skills to the warehouse as they evolve. diff --git a/mkdocs.yml b/mkdocs.yml index 504f03f..0914c39 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -79,10 +79,12 @@ nav: - Quick Start: quickstart.md - Concepts: - How It Works: concepts/how-it-works.md + - Philosophy: concepts/philosophy.md - What Is a Skill: concepts/what-is-a-skill.md - Bundled Skills: concepts/bundled-skills.md - Pending & Adoption: concepts/pending-and-adoption.md - Artifact Types: concepts/artifact-types.md + - Specs vs. Artifacts: concepts/specs-vs-artifacts.md - Design Decisions: concepts/design-decisions.md - Guides: - Creating a Warehouse: guides/warehouse-creation.md @@ -90,6 +92,7 @@ nav: - Interactive Adoption: guides/interactive-adoption.md - Syncing Artifacts: guides/syncing.md - Day-to-Day Workflow: guides/day-to-day-workflow.md + - Spec-Driven Development: guides/spec-driven-development.md - Contributing Back: guides/contributing-back.md - Contribute Warehouse Skill: guides/contribute-warehouse.md - Creating Skills: guides/creating-skills.md diff --git a/site-docs/concepts/philosophy.md b/site-docs/concepts/philosophy.md new file mode 100644 index 0000000..e1b8b6e --- /dev/null +++ b/site-docs/concepts/philosophy.md @@ -0,0 +1,78 @@ +# Philosophy + +Three questions explain the choices behind Agentic Beacon — why the problem is worth solving at all, why the solution is plain markdown files instead of a retrieval system, and why the framework is intentionally lightweight. + +--- + +## Why Do We Need This At All? + +As teams adopt AI coding agents, inconsistent practices emerge quickly: each project develops its own conventions, agents receive different instructions, and valuable patterns discovered in one project never reach others. The result is fragmented quality, slow onboarding, and duplicated effort. + +The answer is applying **DRY (Don't Repeat Yourself) to agentic knowledge**. + +Instead of each project maintaining its own copy of coding standards, agent instructions, and learned patterns, centralize them in a warehouse where: + +- **One update propagates everywhere** — fix a pattern once, all projects benefit +- **Teams learn collectively** — a lesson discovered in one project is shared with all +- **Onboarding is instant** — new developers and agents inherit organizational knowledge automatically +- **Nothing gets lost** — valuable conventions that emerge organically get captured and preserved + +--- + +## Why Markdown Files Instead of a Local RAG System? + +The short answer: **the problem doesn't need that solution.** + +RAG (Retrieval-Augmented Generation) is designed for large-scale, unstructured, frequently-changing content where users don't know what they're looking for. A warehouse of organizational standards is none of those things. + +| | File-based (Beacon's approach) | RAG-based | +|---|---|---| +| **Setup** | Clone a git repo | Vector DB + embedding pipeline + maintenance | +| **Dependencies** | Git, filesystem | Chroma/Pinecone/Weaviate, embedding models | +| **Adoption barrier** | Very low (everyone knows Git) | High (requires ML/infra expertise) | +| **Maintenance** | Standard Git workflow | DB maintenance, reindexing, embedding updates | +| **Versioning** | Native Git history | Custom versioning layer | +| **Human readability** | Direct markdown editing | Requires retrieval interface | +| **Contribution** | Standard PR workflow | More complex (embeddings must be regenerated) | + +A warehouse stores curated, structured standards — typically hundreds of KB, not gigabytes. Agents don't need to *search* for relevant knowledge; context files tell them explicitly what to read and when. The two-tier pointer model (context → on-demand knowledge files) achieves the same goal as RAG without the infrastructure overhead. + +RAG would make sense if the warehouse held thousands of unstructured documents, or if content changed hourly, or if users were doing exploratory search. None of those apply here. + +--- + +## Why Keep This Lightweight? + +**The agentic engineering landscape is shifting rapidly.** What's best practice today may be superseded in six months — by new agent capabilities, new tool conventions, new paradigms entirely. A heavy framework with strong opinions on structure bakes in assumptions that may not age well. + +Keeping Agentic Beacon lightweight is a deliberate bet: + +- **Low adoption cost** — teams can try it without committing to infrastructure +- **Easy to abandon or replace** — if something better comes along, migrating away is minimal (it's just markdown files and a small CLI) +- **Structure follows the team, not the tool** — the inner organization of your warehouse is yours to design; the framework only prescribes the four top-level directories and a minimum shape inside each +- **Works with any agent today** — no custom integrations, no proprietary formats; markdown files work with every coding agent that exists + +The goal is to solve the DRY problem for agentic knowledge without creating a new dependency problem. A warehouse is just a Git repo. Artifacts are just markdown files. The CLI is just a sync tool. If the paradigm shifts again, your knowledge doesn't disappear — it's still plain text in a git repository. + +--- + +## Two-Tier Information Model + +A direct consequence of staying file-based is that agents need a way to scan boot context fast and pull deeper detail only when relevant. Beacon's structure formalises this as two tiers: + +- **Tier 1 — Contexts** (boot context, loaded on session start): lightweight, scannable, contains summaries and pointers — *what does the agent need to know exists?* +- **Tier 2 — Knowledge** (deep context, loaded on demand): detailed explanations, rationale, examples — *what are the full details when needed?* + +Pointers between the two come in two flavours: + +- **Proactive pointers** (written as `**Read:**`) — agent must internalise immediately because the rule affects every file they touch. +- **Reactive pointers** (written as `**See:**`) — agent loads only when encountering the specific problem (troubleshooting, edge cases). + +This separation is what keeps boot context cheap to load while preserving access to organisational depth. The taxonomy inside `knowledge/` — `decisions/`, `lessons/`, `facts/` — is enforced by `abc warehouse lint`; see [Artifact Types](artifact-types.md) for the operational rules. + +--- + +## Next + +- [How It Works](how-it-works.md) — the mechanics that follow from these choices +- [Artifact Types](artifact-types.md) — the four types and how each is wired diff --git a/docs/specs-vs-artifacts.md b/site-docs/concepts/specs-vs-artifacts.md similarity index 54% rename from docs/specs-vs-artifacts.md rename to site-docs/concepts/specs-vs-artifacts.md index 10ad363..94eb64a 100644 --- a/docs/specs-vs-artifacts.md +++ b/site-docs/concepts/specs-vs-artifacts.md @@ -1,14 +1,17 @@ -# Specs vs. Artifacts: Understanding the Distinction +# Specs vs. Artifacts -## The Blueprint vs. Building Code Analogy +Understanding the difference between **specs** and **artifacts** is crucial for effectively using Agentic Beacon. They look similar — both are markdown files an agent reads — but they answer different questions and live in different places. + +--- -Understanding the difference between **specs** and **artifacts** is crucial for effectively using Agentic Beacon. +## The Blueprint vs. Building Code Analogy -### Specs = The Blueprint ("What" to build) +### Specs = the blueprint ("what" to build) Specs define the **exact, deterministic requirements** of a specific project or feature. **Examples:** + - OpenSpec files (`openspec.md`) - OpenAPI definitions (`swagger.yaml`) - Protobuf definitions (`.proto` files) @@ -16,51 +19,55 @@ Specs define the **exact, deterministic requirements** of a specific project or - Product Requirement Documents (PRDs) **Nature:** + - Project-specific - Exact and deterministic - Contract-driven - Defines the goal **Agent's internal monologue:** -> "I need to build a POST /users endpoint that accepts a JSON payload with email and age, and returns a 201 status." +> "I need to build a `POST /users` endpoint that accepts a JSON payload with email and age, and returns a 201 status." -### Artifacts = The Building Codes & Tools ("How" to build it) +### Artifacts = the building codes & tools ("how" to build it) -Artifacts (managed by Agentic Beacon warehouse) are the **reusable heuristics, rules, and capabilities** that govern how the agent writes code to fulfill the spec. +Artifacts (managed by the warehouse) are the **reusable heuristics, rules, and capabilities** that govern how the agent writes code to fulfill a spec. **Examples:** + - Knowledge files (`fastapi-rules.md`, `react-state-management-lessons.md`) - Skills (`generate-unit-tests`, `code-review`) -- Contexts (`backend-microservice`, `python`) +- Contexts (`backend-microservice.md`, `python.md`) **Nature:** + - Organization-wide - Cross-project and reusable - Heuristic-driven - Defines the approach **Agent's internal monologue:** -> "When I build that POST /users endpoint, I must remember to use Pydantic V2 for validation, and I must use the generate-unit-tests skill to write a pytest file for it." +> "When I build that `POST /users` endpoint, I must remember to use Pydantic V2 for validation, and I must use the `generate-unit-tests` skill to write a pytest file for it." --- ## How to Handle Them in Your Workflow -Because their purposes are fundamentally different, specs and artifacts live in different places and are handled differently by the CLI. +Because their purposes are fundamentally different, specs and artifacts live in different places and are handled differently. + +### Scenario A: the spec belongs to the local project (most common) -### Scenario A: The Spec Belongs to the Local Project (Most Common) +**Rule:** Most of the time, specs should **not** live in your warehouse. -**Rule:** Most of the time, specs should **NOT** live in your central Agentic Beacon warehouse. +**Example — building a new microservice:** -**Example:** Building a new microservice - The OpenSpec for that microservice lives directly inside the local project repository - Location: `~/my-project/openspec/spec.md` - The agent reads the spec directly from the local workspace -- Agentic Beacon doesn't sync specs—it only syncs the **knowledge of how to implement** that spec properly +- Beacon doesn't sync specs — it only syncs the **knowledge of how to implement** that spec properly **Workflow:** -```bash -# Project structure + +``` my-project/ ├── openspec/ │ └── spec.md # Local spec (project-specific) @@ -73,33 +80,34 @@ my-project/ ``` **Agent's workflow:** + 1. Read `openspec/spec.md` to understand **what** to build 2. Read `.agentic-beacon/artifacts/knowledge/` to understand **how** to build it -3. Execute `.agentic-beacon/artifacts/skills/` to automate and verify work +3. Execute `.agentic-beacon/artifacts/skills/` to automate and verify the work -### Scenario B: Shared Organizational Specs (The Exception) +### Scenario B: shared organizational specs (the exception) **Rule:** Sometimes a spec **is** an organizational artifact and belongs in the warehouse. -**Example:** Company-wide authentication API +**Example — company-wide authentication API:** + - Your company has a core Authentication API - Every frontend project needs the `auth-openapi.yaml` spec to know how to log users in - This spec is organizational infrastructure, not project-specific -**In this case, store shared specs in the warehouse and reference them in beacon.yaml:** +In this case, store shared specs in the warehouse and reference them in `beacon.yaml`: ```yaml -# .agentic-beacon/beacon.yaml artifacts: contexts: - - backend/api-design-rules.md # The "How" - rules for APIs - - specs/core-auth-api.yaml # The shared "What" - auth API spec - + - backend/api-design-rules.md # The "How" — rules for APIs + - specs/core-auth-api.yaml # The shared "What" — auth API spec skills: - - generate-api-client # The "Tool" - generate client code + - generate-api-client # The "Tool" — generate client code ``` **When to treat specs as artifacts:** + - API contracts shared across multiple teams/projects - Core platform interfaces that many services integrate with - Organizational data models or schemas @@ -107,53 +115,48 @@ artifacts: --- -## The Ultimate Synergy +## The Triangulation -When an agent works in a local project equipped with Agentic Beacon, it gets the **perfect triangulation of data**: +When an agent works in a local project equipped with Beacon, it gets a clean triangulation of data: -### 1. The Goal (Local Spec) -**Location:** `./openspec/spec.md` -**Purpose:** Tells the agent **what** to code today -**Example:** "Build a user registration endpoint with email validation" - -### 2. The Rules (Synced Knowledge) -**Location:** `./.agentic-beacon/artifacts/knowledge/` -**Purpose:** Tells the agent **how** to follow company standards -**Example:** "Always use Pydantic V2 for validation, never store passwords in plain text" - -### 3. The Engine (Synced Skills) -**Location:** `./.agentic-beacon/artifacts/skills/` -**Purpose:** Automates and verifies the agent's work -**Example:** "Execute test-runner skill to generate and run pytest files" +| Source | Location | Tells the agent… | +|---|---|---| +| **Local spec** | `./openspec/spec.md` | **What** to code today | +| **Synced knowledge** | `./.agentic-beacon/artifacts/knowledge/` | **How** to follow company standards | +| **Synced skills** | `./.agentic-beacon/artifacts/skills/` | **Procedures** to automate and verify work | --- ## Best Practices -### ✅ DO Store in Warehouse (Artifacts) +### ✅ Do store in the warehouse (artifacts) + - Coding standards and best practices - Architectural patterns and guidelines - Reusable skills and workflows - Shared organizational contexts - Common API contracts used across teams -### ❌ DON'T Store in Warehouse (Specs) +### ❌ Don't store in the warehouse (specs) + - Feature-specific requirements - Project-specific API endpoints - Individual user stories - One-off implementation details - Project roadmaps and milestones -### 🤔 Gray Area (Case-by-Case) -- **Core platform APIs**: If 10+ projects depend on it → Warehouse -- **Data schemas**: If organization-wide standard → Warehouse -- **Communication protocols**: If company standard → Warehouse +### 🤔 Gray area (case-by-case) + +- **Core platform APIs** — if 10+ projects depend on it → warehouse +- **Data schemas** — if organization-wide standard → warehouse +- **Communication protocols** — if company standard → warehouse --- ## Example: Building a Payment Service -### Local Project (Specs) +**Local project (specs):** + ``` payment-service/ ├── openspec/ @@ -162,26 +165,26 @@ payment-service/ └── src/ ``` -### Warehouse (Artifacts) +**Warehouse (artifacts) referenced by the project's `beacon.yaml`:** + ```yaml -# .agentic-beacon/beacon.yaml artifacts: contexts: - backend/api-security-rules.md # How: Handle sensitive data - backend/error-handling-patterns.md # How: Return error responses - payments/pci-compliance-rules.md # How: PCI-DSS requirements - specs/stripe-api-contract.yaml # Shared: Stripe integration spec - skills: - generate-api-tests # Tool: Generate test suites - security-audit # Tool: Check for vulnerabilities ``` -**Agent's Process:** +**Agent's process:** + 1. Reads `openspec/spec.md`: "I need to build a payment processing API" 2. Reads `knowledge/api-security-rules.md`: "I must encrypt sensitive data and use HTTPS" 3. Reads `knowledge/pci-compliance-rules.md`: "I must never log credit card numbers" -4. References `specs/stripe-api-contract.yaml`: "Here's how to integrate with Stripe API" +4. References `specs/stripe-api-contract.yaml`: "Here's how to integrate with the Stripe API" 5. Executes `skills/generate-api-tests`: "Now I'll generate comprehensive test coverage" 6. Executes `skills/security-audit`: "Finally, I'll verify no security vulnerabilities" @@ -189,14 +192,14 @@ artifacts: ## Key Takeaway -**Keep Agentic Beacon focused on reusable artifacts** (Knowledge, Skills, Contexts) and **leave feature-specific specs in local project repositories**. +**Keep Agentic Beacon focused on reusable artifacts** (knowledge, skills, contexts) and **leave feature-specific specs in local project repositories**. -This ensures your warehouse remains a **lean, highly reusable library of "Agentic Intelligence"** rather than a dumping ground for every project's random feature requirements. +This keeps the warehouse a lean, highly reusable library of agentic intelligence rather than a dumping ground for every project's feature requirements. --- -**See Also:** -- [Warehouse Structure](../README.md) - Understanding warehouse organization -- [beacon.yaml Reference](../guides/beacon-yaml-reference.md) - How to declare artifact dependencies +## See Also -**Last Updated:** 2026-03-08 +- [How It Works](how-it-works.md) — the warehouse / beacon mental model +- [Artifact Types](artifact-types.md) — the four artifact types and how each is wired +- [beacon.yaml Reference](../reference/beacon-yaml.md) — how to declare artifact dependencies diff --git a/site-docs/guides/spec-driven-development.md b/site-docs/guides/spec-driven-development.md new file mode 100644 index 0000000..268f12c --- /dev/null +++ b/site-docs/guides/spec-driven-development.md @@ -0,0 +1,199 @@ +# Spec-Driven Development + +A guide for using spec-driven development approaches in agentic engineering. The methodology is **orthogonal to Beacon proper** — Beacon distributes the artifacts that govern *how* an agent works, but a spec describes *what* it should build. Spec-driven workflows are a common way to author specs your agents can act on. + +--- + +## Overview + +Spec-driven development is a methodology for transforming vague ideas into implementation-ready specifications through structured planning phases. + +**When to use spec-driven development:** + +- Complex, multi-component features +- Features requiring cross-team coordination +- Features with unclear or evolving requirements +- When you need to validate approach before significant implementation + +**When NOT to use spec-driven development:** + +- Simple, well-understood tasks (1-2 file changes) +- Bug fixes with clear root cause +- Routine maintenance tasks +- Prototyping or exploratory coding + +--- + +## Two-Phase Approach + +### Phase 1: Technical planning + +**Goal:** Transform free-form ideas into a formal, implementation-ready technical plan. + +**Process:** + +1. **Listen and parse** — Extract core problem, goals, scope, technical ideas +2. **Generate first draft** — Create a structured technical planning document +3. **Audit and gap analysis** — Identify missing information, ask targeted questions +4. **Baseline** — Complete when all open questions are answered and the user approves + +**Output — a technical planning document with:** + +- Clear problem statement and goals +- Testable acceptance criteria +- Explicit in-scope and out-of-scope boundaries +- High-level technical approach +- Identified risks and dependencies +- Impacted modules/systems + +### Phase 2: Task breakdown + +**Goal:** Decompose the technical plan into granular, sequential implementation tasks. + +**Process:** + +1. **Source audit** — Access the planning document, scan the codebase for impacted modules +2. **Decomposition** — Break work into "sprints of one" atomic tasks +3. **Resolution** — Address ambiguities before starting implementation +4. **Handoff** — Deliver an actionable task checklist ready for execution + +**Output — a task breakdown document with:** + +- User story extracted from the plan +- Step-by-step implementation checklist +- Verification steps for each task +- Dependencies and execution order +- Manual intervention steps (if any) + +--- + +## Packaging as Warehouse Skills + +Spec-driven development workflows can be packaged as **skills** in your warehouse: + +``` +skills/ +├── spec-propose/ # Phase 1: Create the technical plan +├── spec-breakdown/ # Phase 2: Create the task breakdown +└── spec-implement/ # Execute tasks from the breakdown +``` + +**Example usage:** + +```bash +/spec-propose "Add user authentication with OAuth" +/spec-breakdown +/spec-implement +``` + +See [Creating Skills](creating-skills.md) for how to author and distribute the underlying `SKILL.md` files. + +--- + +## Best Practices + +### During planning + +- **Be thorough** — better to over-specify than under-specify +- **Ask questions** — don't assume, clarify ambiguities +- **Think about failure** — what happens when things go wrong? +- **Identify manual steps early** — know what requires human intervention +- **Use diagrams** — Mermaid for complex flows + +### During task breakdown + +- **Small tasks** — each completable in one focused session +- **Verification steps** — every task needs a confirmation method +- **Logical order** — dependencies should flow naturally +- **Mark manual steps** — use `[MANUAL]` prefix to set expectations +- **Don't invent** — stick to what's in the technical plan + +### General + +- **Iterate** — specs improve with feedback +- **Version control** — commit after each phase +- **Link to knowledge** — store rationale and decisions in your warehouse +- **Keep readable** — write for humans first, AI second + +--- + +## Document Templates + +### Technical planning template + +```markdown +# [Feature Name] + +## 1. Background and Problem Statement +[Clear synthesis of problem and why it needs solving] + +## 2. Goals & Acceptance Criteria +- [ ] AC 1: [Testable criterion] +- [ ] AC 2: [Testable criterion] + +## 3. Scope +### In Scope +[What will be implemented] + +### Out of Scope +[What won't be implemented] + +## 4. Proposed Technical Solution +### High-Level Architecture +[End-to-end flow and data lifecycle] + +### Impacted Modules +- [Module/Path]: [Required modifications] + +### Manual Intervention Requirements +- [Manual Step]: [Description and rationale] + +## 5. Risks and Dependencies +- **Risk:** [Problem] + - **Mitigation:** [Solution] + +## 6. Open Questions +- [ ] [Question to resolve] +``` + +### Task breakdown template + +```markdown +# Implementation Plan: [Feature Name] + +## 1. User Story +[Extracted from technical plan] + +## 2. Technical Summary +[Concise summary of solution] + +## 3. Acceptance Criteria +- [ ] AC 1: [From technical plan] +- [ ] AC 2: [From technical plan] + +## 4. Technical Task Checklist + +### Phase 1: Preparation +- [ ] **Step 1:** [Action] + - *Verification:* [How to check] + +### Phase 2: Implementation +- [ ] **Step 2:** [Action] + - *Verification:* [How to check] +- [ ] **[MANUAL] Step 3:** [User action required] + - *User Action:* [What user needs to do] + - *Verification:* [How to confirm] + +## 5. Dependencies +[Internal/external dependencies] + +## 6. Questions & Ambiguities +[Items needing resolution] +``` + +--- + +## See Also + +- [Specs vs. Artifacts](../concepts/specs-vs-artifacts.md) — why specs and warehouse artifacts live in different places +- [Creating Skills](creating-skills.md) — package spec workflows as distributable skills From a9b1edf1d6dba293f681aa95f73fb338e80bc8e4 Mon Sep 17 00:00:00 2001 From: Song Yikun Date: Mon, 18 May 2026 18:05:49 +0800 Subject: [PATCH 3/7] =?UTF-8?q?docs:=20phase=20C=20=E2=80=94=20archive=20t?= =?UTF-8?q?ier=203=20design=20+=20migration=20records?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Part of PER-190. Moves the legacy boot-context-design notes and historical migration records into docs/archive/. These predate the current artifact model (contexts + skills + knowledge + agents) and are opencode-centric. Still-valid framing (two-tier information model, three-tier context concept) was already extracted into the new concepts/philosophy.md during Phase B. The archive directory is kept in-repo so external references in older commits and write-ups continue to resolve. A new docs/archive/README.md explicitly redirects readers to the live mkdocs site. - move docs/boot-context-design/ → docs/archive/boot-context-design/ - move docs/migrations/ → docs/archive/migrations/ - add docs/archive/README.md with status table + mkdocs pointers Refs PER-190 --- docs/archive/README.md | 29 +++++++++++++++++++ .../agents-md-architecture.md | 0 .../boot-context-design/naming-convention.md | 0 .../project-level-agents-design.md | 0 .../user-level-agents-design.md | 0 .../artifact-dependencies-frontmatter.md | 0 ...ending-artifacts-flow-and-record-revamp.md | 0 7 files changed, 29 insertions(+) create mode 100644 docs/archive/README.md rename docs/{ => archive}/boot-context-design/agents-md-architecture.md (100%) rename docs/{ => archive}/boot-context-design/naming-convention.md (100%) rename docs/{ => archive}/boot-context-design/project-level-agents-design.md (100%) rename docs/{ => archive}/boot-context-design/user-level-agents-design.md (100%) rename docs/{ => archive}/migrations/artifact-dependencies-frontmatter.md (100%) rename docs/{ => archive}/migrations/pending-artifacts-flow-and-record-revamp.md (100%) diff --git a/docs/archive/README.md b/docs/archive/README.md new file mode 100644 index 0000000..3501c3c --- /dev/null +++ b/docs/archive/README.md @@ -0,0 +1,29 @@ +# Archive + +Historical design and migration notes preserved for reference. These documents predate the current warehouse model and **should not be used as authoritative guidance** — the live documentation at is the source of truth. + +The archive is kept in-repo (rather than relying purely on git history) so that links and references in older commits, blog posts, and external write-ups continue to resolve. + +--- + +## `boot-context-design/` + +Original design notes for the three-tier `AGENTS.md` architecture (warehouse / user / project). The framing is partially reflected in today's [Philosophy](https://shadowsong27.github.io/agentic-beacon/concepts/philosophy/), [How It Works](https://shadowsong27.github.io/agentic-beacon/concepts/how-it-works/), and [Artifact Types](https://shadowsong27.github.io/agentic-beacon/concepts/artifact-types/) pages, but the operational detail is **opencode-centric and superseded** by the current artifact model (contexts + skills + knowledge + agents, each with its own wiring). + +| File | Status | +|---|---| +| `agents-md-architecture.md` | Three-tier framing — partial concept retained in [Philosophy](https://shadowsong27.github.io/agentic-beacon/concepts/philosophy/) | +| `project-level-agents-design.md` | Predates current warehouse model. Treat as historical only. | +| `user-level-agents-design.md` | Minimal-by-design principle is still sound but Beacon does not actively manage user-level AGENTS.md today. | +| `naming-convention.md` | Superseded by `abc warehouse lint` rules and [Artifact Types](https://shadowsong27.github.io/agentic-beacon/concepts/artifact-types/). | + +## `migrations/` + +One-off migration records preserved verbatim. Each describes a since-completed structural change; the live behaviour is documented in the mkdocs site. + +| File | Describes | +|---|---| +| `artifact-dependencies-frontmatter.md` | The introduction of `requires:` frontmatter on skills | +| `pending-artifacts-flow-and-record-revamp.md` | The introduction of `pending.yaml` and `.last-adopt`, and the revamped `record-knowledge` / `record-skill` flow | + +For the current behaviour see [Pending & Adoption](https://shadowsong27.github.io/agentic-beacon/concepts/pending-and-adoption/) and [Artifact Types](https://shadowsong27.github.io/agentic-beacon/concepts/artifact-types/). diff --git a/docs/boot-context-design/agents-md-architecture.md b/docs/archive/boot-context-design/agents-md-architecture.md similarity index 100% rename from docs/boot-context-design/agents-md-architecture.md rename to docs/archive/boot-context-design/agents-md-architecture.md diff --git a/docs/boot-context-design/naming-convention.md b/docs/archive/boot-context-design/naming-convention.md similarity index 100% rename from docs/boot-context-design/naming-convention.md rename to docs/archive/boot-context-design/naming-convention.md diff --git a/docs/boot-context-design/project-level-agents-design.md b/docs/archive/boot-context-design/project-level-agents-design.md similarity index 100% rename from docs/boot-context-design/project-level-agents-design.md rename to docs/archive/boot-context-design/project-level-agents-design.md diff --git a/docs/boot-context-design/user-level-agents-design.md b/docs/archive/boot-context-design/user-level-agents-design.md similarity index 100% rename from docs/boot-context-design/user-level-agents-design.md rename to docs/archive/boot-context-design/user-level-agents-design.md diff --git a/docs/migrations/artifact-dependencies-frontmatter.md b/docs/archive/migrations/artifact-dependencies-frontmatter.md similarity index 100% rename from docs/migrations/artifact-dependencies-frontmatter.md rename to docs/archive/migrations/artifact-dependencies-frontmatter.md diff --git a/docs/migrations/pending-artifacts-flow-and-record-revamp.md b/docs/archive/migrations/pending-artifacts-flow-and-record-revamp.md similarity index 100% rename from docs/migrations/pending-artifacts-flow-and-record-revamp.md rename to docs/archive/migrations/pending-artifacts-flow-and-record-revamp.md From 0de0d27deb70a86190d47f5108409e1cdb26c8a8 Mon Sep 17 00:00:00 2001 From: Song Yikun Date: Mon, 18 May 2026 18:08:41 +0800 Subject: [PATCH 4/7] =?UTF-8?q?docs:=20phase=20D=20=E2=80=94=20reshuffle?= =?UTF-8?q?=20contributing=20docs=20into=20mkdocs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Part of PER-190. Moves the 12-file contributor guide into a Contributing section of the mkdocs site so it gets search and proper navigation, and rewrites the root CONTRIBUTING.md as a thin entry point covering only environment setup (the part GitHub renders natively for PR authors). - move docs/contributing/*.md → site-docs/contributing/*.md - new site-docs/contributing/index.md as section overview - strip `← Back to CONTRIBUTING.md` headers (don't make sense in mkdocs) - fix internal references: contribution-workflow, documentation - nav: add Contributing section under Reference + Troubleshooting - rewrite CONTRIBUTING.md as thin entry point linking to mkdocs site Refs PER-190 --- CONTRIBUTING.md | 64 ++++++++------- docs/contributing/documentation.md | 79 ------------------- mkdocs.yml | 14 ++++ .../contributing/architecture.md | 2 - .../contributing/code-style.md | 0 {docs => site-docs}/contributing/commands.md | 2 - .../contributing/configuration.md | 2 - .../contributing/contribution-workflow.md | 4 +- .../contributing/design-patterns.md | 0 site-docs/contributing/documentation.md | 75 ++++++++++++++++++ {docs => site-docs}/contributing/gotchas.md | 0 site-docs/contributing/index.md | 22 ++++++ .../contributing/local-development.md | 2 - .../contributing/open-questions.md | 0 .../contributing/project-layout.md | 2 - {docs => site-docs}/contributing/testing.md | 0 16 files changed, 147 insertions(+), 121 deletions(-) delete mode 100644 docs/contributing/documentation.md rename {docs => site-docs}/contributing/architecture.md (99%) rename {docs => site-docs}/contributing/code-style.md (100%) rename {docs => site-docs}/contributing/commands.md (98%) rename {docs => site-docs}/contributing/configuration.md (98%) rename {docs => site-docs}/contributing/contribution-workflow.md (94%) rename {docs => site-docs}/contributing/design-patterns.md (100%) create mode 100644 site-docs/contributing/documentation.md rename {docs => site-docs}/contributing/gotchas.md (100%) create mode 100644 site-docs/contributing/index.md rename {docs => site-docs}/contributing/local-development.md (98%) rename {docs => site-docs}/contributing/open-questions.md (100%) rename {docs => site-docs}/contributing/project-layout.md (99%) rename {docs => site-docs}/contributing/testing.md (100%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0ec6ac4..1011c8a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,10 @@ # Contributing to Agentic Beacon -Welcome to Agentic Beacon — the package manager for AI coding agents. This guide covers everything you need to go from zero to a merged pull request: environment setup, the project's architecture and conventions, how to run tests, and the contribution workflow. +Welcome — this file is the entry point for new contributors. It covers everything you need to go from a fresh clone to running tests locally. The deeper guides (architecture, code style, testing strategy, design patterns, gotchas, etc.) live on the documentation site: + +📚 **** + +--- ## Project Overview @@ -8,18 +12,16 @@ Welcome to Agentic Beacon — the package manager for AI coding agents. This gui The primary consumers of this project are software engineering teams that use AI coding assistants (Claude Code, OpenCode, or compatible tools) across multiple repositories. The CLI is the sole public interface; there is no HTTP API, no library API surface, and no frontend. -The project is pure Python (requires Python 3.12+) and is distributed as a standard PyPI wheel. It uses [uv](https://github.com/astral-sh/uv) as its package and workspace manager. The package is structured as a [uv workspace](https://docs.astral.sh/uv/concepts/workspaces/) with the single workspace member at `libs/beacon/`. The entrypoint registered in `pyproject.toml` is `abc = "beacon.cli.main:main"`. +The project is pure Python (requires Python 3.12+) and is distributed as a standard PyPI wheel. It uses [uv](https://github.com/astral-sh/uv) as its package and workspace manager — the package is structured as a [uv workspace](https://docs.astral.sh/uv/concepts/workspaces/) with a single workspace member at `libs/beacon/`. The entrypoint registered in `pyproject.toml` is `abc = "beacon.cli.main:main"`. -Key runtime dependencies are [Click](https://click.palletsprojects.com/) (CLI framework), [Rich](https://rich.readthedocs.io/) (terminal formatting), [Textual](https://textual.textualize.io/) (TUI for `abc adopt`), [Pydantic](https://docs.pydantic.dev/) and [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) (data models and settings), [PyYAML](https://pyyaml.org/) (YAML I/O), and [Loguru](https://loguru.readthedocs.io/) (structured logging). +**Platform support:** macOS and Linux only. Windows is explicitly rejected at startup because symlink-based artifact sync is not reliably supported there. -**Platform support:** macOS and Linux only. Windows is explicitly rejected at startup via `utils/platform.py`. The rejection reason is symlink-based artifact sync, which is not reliably supported on Windows. +--- ## Environment Setup ### 1. Install Python 3.12+ -The project requires Python 3.12 or newer. If you do not have it, install via [pyenv](https://github.com/pyenv/pyenv) (recommended) or your system package manager: - ```bash # macOS with Homebrew brew install python@3.12 @@ -31,8 +33,6 @@ pyenv global 3.12 ### 2. Install uv -[uv](https://docs.astral.sh/uv/) is the package manager for this project. It manages the virtual environment, resolves dependencies, and runs tools. - ```bash # macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh @@ -54,7 +54,7 @@ uv sync --group dev The `--group dev` flag installs test and linting dependencies (`pytest`, `pytest-cov`, `pytest-asyncio`, `pre-commit`, `ruff`). Run this once, and again any time `pyproject.toml` changes. -**Important:** Never run `uv sync` inside `libs/beacon/` and never create a separate virtualenv there. The workspace is managed from the repo root; the single `.venv` at the root is shared across all workspace members. +> **Important:** never run `uv sync` inside `libs/beacon/`, and never create a separate virtualenv there. The workspace is managed from the repo root; the single `.venv` at the root is shared across all workspace members. ### 4. Install pre-commit hooks @@ -66,7 +66,7 @@ This wires the pre-commit hooks (ruff lint, ruff format, YAML/TOML/JSON syntax c ### 5. Configure git identity -Some tests run real `git` subprocess commands and require a configured git identity. If you do not have a global git config, set one: +Some tests run real `git` subprocess commands and require a configured git identity: ```bash git config --global user.email "you@example.com" @@ -76,14 +76,11 @@ git config --global user.name "Your Name" ### 6. Verify the setup ```bash -# Should print the installed version (e.g. 3.2.0) .venv/bin/abc --version - -# Run the unit test suite — all should pass uv run pytest -m "not integration" -q ``` -### Environment Variables +### Environment variables The CLI reads a small set of optional environment variables via `pydantic-settings`. All are optional with sensible defaults: @@ -92,20 +89,27 @@ The CLI reads a small set of optional environment variables via `pydantic-settin | `ABC_GLOBAL_AGENTS_DIR` | `Path` | `~/.abc/agents` | Override the global agents directory used for agent symlink installation | | `ABC_MAX_COMMITS_LOOKBACK` | `int` | `100` | Maximum number of git commits to scan when annotating warehouse artifacts with recency | | `ABC_DEBUG` | `bool` | `false` | Enable debug-level logging output | +| `BEACON_OFFLINE` | `bool` | `false` | Skip integration tests that require the package index (planes, flaky networks) | + +These are rarely needed in normal development. + +--- + +## Where to Go Next + +The rest of the contributor reference is on the documentation site. Bookmark the [Contributing section](https://shadowsong27.github.io/agentic-beacon/contributing/) and dip in by topic: + +- [Commands](https://shadowsong27.github.io/agentic-beacon/contributing/commands/) — build, run, test, and lint commands +- [Project Layout](https://shadowsong27.github.io/agentic-beacon/contributing/project-layout/) — annotated directory tree +- [Architecture](https://shadowsong27.github.io/agentic-beacon/contributing/architecture/) — four-layer design, five domains, data flows +- [Configuration](https://shadowsong27.github.io/agentic-beacon/contributing/configuration/) — settings, workspace config, manifest models +- [Local Development](https://shadowsong27.github.io/agentic-beacon/contributing/local-development/) — dev loop, debugging, running subsets +- [Code Style](https://shadowsong27.github.io/agentic-beacon/contributing/code-style/) — naming, imports, formatting rules +- [Design Patterns](https://shadowsong27.github.io/agentic-beacon/contributing/design-patterns/) — recurring patterns and when to use them +- [Testing](https://shadowsong27.github.io/agentic-beacon/contributing/testing/) — test layout, unit vs integration, fixtures +- [Contribution Workflow](https://shadowsong27.github.io/agentic-beacon/contributing/contribution-workflow/) — branches, PRs, CI gates, release process +- [Documentation](https://shadowsong27.github.io/agentic-beacon/contributing/documentation/) — how docs are built and published +- [Gotchas](https://shadowsong27.github.io/agentic-beacon/contributing/gotchas/) — known traps and sharp corners +- [Open Questions](https://shadowsong27.github.io/agentic-beacon/contributing/open-questions/) — unresolved items -These are rarely needed in normal development. The most common override is `ABC_MAX_COMMITS_LOOKBACK` if you have a very deep git history in a test warehouse. - -## Documentation - -- [Commands](docs/contributing/commands.md) — build, run, test, and lint commands -- [Project Layout](docs/contributing/project-layout.md) — annotated directory tree and organization -- [Architecture](docs/contributing/architecture.md) — four-layer design, subsystem boundaries, data flows -- [Configuration System](docs/contributing/configuration.md) — settings, workspace config, manifest models -- [Local Development](docs/contributing/local-development.md) — dev loop, debugging, running subsets -- [Code Style & Conventions](docs/contributing/code-style.md) — naming, imports, formatting rules -- [Design Patterns & Techniques](docs/contributing/design-patterns.md) — recurring patterns and when to use them -- [Testing Strategy](docs/contributing/testing.md) — test layout, runners, unit vs integration, fixtures -- [Contribution Workflow](docs/contributing/contribution-workflow.md) — branches, PRs, CI gates, release process -- [Documentation Maintenance](docs/contributing/documentation.md) — how docs are built and published -- [Gotchas & Sharp Edges](docs/contributing/gotchas.md) — known traps, architecture debt, sharp corners -- [Open Questions](docs/contributing/open-questions.md) — unresolved items for future documentation updates +If the live site is ever unreachable, the same content is in `site-docs/contributing/` in this repo. diff --git a/docs/contributing/documentation.md b/docs/contributing/documentation.md deleted file mode 100644 index bb56f61..0000000 --- a/docs/contributing/documentation.md +++ /dev/null @@ -1,79 +0,0 @@ -# Documentation - -How project documentation is organized and maintained. - ---- - -## Documentation Sources - -| Location | Purpose | -|---|---| -| `CONTRIBUTING.md` | Contributor onboarding (this doc's entry point) | -| `docs/` | Conceptual design documents and contributor reference | -| `docs/contributing/` | Detailed contributor guides (this directory) | -| `site-docs/` | MkDocs source — user-facing documentation published to GitHub Pages | -| `AGENTS.md` | Project context for AI coding agents (authoritative project reference) | -| `CLAUDE.md` | AI agent bootstrap file — imports `AGENTS.md` and context files | - ---- - -## User Docs (MkDocs) - -The published documentation site is built from `site-docs/` using -[MkDocs Material](https://squidfunk.github.io/mkdocs-material/). - -```bash -# Serve locally with hot reload -uv run mkdocs serve --config-file site-docs/mkdocs.yml - -# Build static site -uv run mkdocs build --config-file site-docs/mkdocs.yml -``` - -The site is deployed automatically to GitHub Pages on every push to `main` via -`.github/workflows/docs.yml`. - -### Adding a page - -1. Create a `.md` file under `site-docs/docs/`. -2. Add the page to the `nav:` section in `site-docs/mkdocs.yml`. -3. Verify it renders correctly with `mkdocs serve`. - ---- - -## Conceptual Design Docs (`docs/`) - -`docs/` contains in-depth design documents written for contributors and advanced users. These -are not part of the published MkDocs site. - -When writing a design doc: -- Use plain GitHub-flavored Markdown. -- Link from `AGENTS.md` (or `docs/contributing/architecture.md`) if the doc is referenced in - contributor workflows. - ---- - -## Keeping Docs Current - -Documentation updates are part of every code change. The pre-PR checklist includes: - -- Update `docs/contributing/` if you change architecture, CLI patterns, or configuration - semantics. -- Update `site-docs/docs/` if you change user-facing commands, output format, or config files. -- Update `AGENTS.md` if the project overview, five domains, Python standards, or common patterns - change. - ---- - -## AGENTS.md Conventions - -`AGENTS.md` is the authoritative reference for AI coding agents working on this project. Keep it -accurate and concise: - -- Five domains table must match the actual `domains/` directory. -- Python standards section must reflect what `test_architecture.py` enforces. -- Common patterns section must reflect current CLI handler and domain conventions. -- Update the **Last Updated** date at the bottom when making changes. - -`CLAUDE.md` must not duplicate `AGENTS.md`. It imports `AGENTS.md` via `@AGENTS.md` and adds -any additional context file references. diff --git a/mkdocs.yml b/mkdocs.yml index 0914c39..2b5c1df 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -107,3 +107,17 @@ nav: - beacon.yaml: reference/beacon-yaml.md - CLI Reference: reference/cli.md - Troubleshooting: troubleshooting.md + - Contributing: + - Overview: contributing/index.md + - Commands: contributing/commands.md + - Project Layout: contributing/project-layout.md + - Architecture: contributing/architecture.md + - Configuration: contributing/configuration.md + - Local Development: contributing/local-development.md + - Code Style: contributing/code-style.md + - Design Patterns: contributing/design-patterns.md + - Testing: contributing/testing.md + - Contribution Workflow: contributing/contribution-workflow.md + - Documentation: contributing/documentation.md + - Gotchas: contributing/gotchas.md + - Open Questions: contributing/open-questions.md diff --git a/docs/contributing/architecture.md b/site-docs/contributing/architecture.md similarity index 99% rename from docs/contributing/architecture.md rename to site-docs/contributing/architecture.md index 40bd7d5..654d82a 100644 --- a/docs/contributing/architecture.md +++ b/site-docs/contributing/architecture.md @@ -2,8 +2,6 @@ This file describes the overall design of Agentic Beacon: the four-layer architecture, the five domain modules, key data flows, and the major design decisions that shape the codebase. -← [Back to CONTRIBUTING.md](../../CONTRIBUTING.md) - --- ## Overview diff --git a/docs/contributing/code-style.md b/site-docs/contributing/code-style.md similarity index 100% rename from docs/contributing/code-style.md rename to site-docs/contributing/code-style.md diff --git a/docs/contributing/commands.md b/site-docs/contributing/commands.md similarity index 98% rename from docs/contributing/commands.md rename to site-docs/contributing/commands.md index 3a8808d..20db0d7 100644 --- a/docs/contributing/commands.md +++ b/site-docs/contributing/commands.md @@ -2,8 +2,6 @@ This file is the reference for all commands you will need while developing Agentic Beacon — from running tests to building the package to verifying the CLI. -← [Back to CONTRIBUTING.md](../../CONTRIBUTING.md) - --- ## Development Commands diff --git a/docs/contributing/configuration.md b/site-docs/contributing/configuration.md similarity index 98% rename from docs/contributing/configuration.md rename to site-docs/contributing/configuration.md index e08cc75..d88eedd 100644 --- a/docs/contributing/configuration.md +++ b/site-docs/contributing/configuration.md @@ -2,8 +2,6 @@ This file documents how Agentic Beacon is configured at runtime — environment variables, workspace config files, and the manifest models that drive behavior. -← [Back to CONTRIBUTING.md](../../CONTRIBUTING.md) - --- ## Configuration Sources diff --git a/docs/contributing/contribution-workflow.md b/site-docs/contributing/contribution-workflow.md similarity index 94% rename from docs/contributing/contribution-workflow.md rename to site-docs/contributing/contribution-workflow.md index 113461a..d1839f0 100644 --- a/docs/contributing/contribution-workflow.md +++ b/site-docs/contributing/contribution-workflow.md @@ -8,7 +8,7 @@ How to contribute a change — from branch to merged PR. 1. Check [open issues](https://github.com/Shadowsong27/agentic-beacon/issues) for context. 2. For non-trivial changes, open or comment on an issue first to align on approach. -3. Make sure your environment is set up: see [CONTRIBUTING.md](../../CONTRIBUTING.md). +3. Make sure your environment is set up: see [CONTRIBUTING.md](https://github.com/Shadowsong27/agentic-beacon/blob/main/CONTRIBUTING.md) in the repo root. --- @@ -78,7 +78,7 @@ Before opening a PR, verify: - [ ] `pre-commit run --all-files` passes - [ ] Architecture tests pass: `pytest tests/unit/test_architecture.py` - [ ] If adding a new CLI command: handler follows the thin-handler pattern (see - [Architecture](architecture.md#cli-layer-rules)) + [Architecture](architecture.md#four-layer-architecture)) - [ ] If adding a new domain module: placed in the correct domain; not in `core/` unless multiple domains share it - [ ] If adding dependencies: update `libs/beacon/pyproject.toml`; run `uv sync --group dev` diff --git a/docs/contributing/design-patterns.md b/site-docs/contributing/design-patterns.md similarity index 100% rename from docs/contributing/design-patterns.md rename to site-docs/contributing/design-patterns.md diff --git a/site-docs/contributing/documentation.md b/site-docs/contributing/documentation.md new file mode 100644 index 0000000..d2155fe --- /dev/null +++ b/site-docs/contributing/documentation.md @@ -0,0 +1,75 @@ +# Documentation + +How project documentation is organized and maintained. + +--- + +## Documentation Sources + +| Location | Purpose | +|---|---| +| `CONTRIBUTING.md` | Thin entry point at the repo root — environment setup + pointer to this site | +| `site-docs/` | MkDocs source — user-facing docs and contributor guides, published to GitHub Pages | +| `site-docs/contributing/` | Contributor guides (this directory) | +| `docs/archive/` | Frozen historical design and migration notes (not published) | +| `AGENTS.md` | Project context for AI coding agents (authoritative project reference) | +| `CLAUDE.md` | AI agent bootstrap file — imports `AGENTS.md` and context files | + +--- + +## Site Build (MkDocs) + +The published documentation site is built from `site-docs/` using +[MkDocs Material](https://squidfunk.github.io/mkdocs-material/). + +```bash +# Serve locally with hot reload +uv run mkdocs serve --livereload + +# Build static site +uv run mkdocs build --strict +``` + +> **Click 8.3.x regression:** `mkdocs serve` silently disables livereload unless `--livereload` is passed explicitly. Always include the flag. + +The site is deployed automatically to GitHub Pages on every push to `main` via +`.github/workflows/docs.yml`. + +### Adding a page + +1. Create a `.md` file under `site-docs/` (use the existing folder structure: `concepts/`, `guides/`, `tutorials/`, `reference/`, `contributing/`). +2. Add the page to the `nav:` section in `mkdocs.yml`. +3. Verify it renders cleanly with `mkdocs build --strict`. + +--- + +## Archive (`docs/archive/`) + +Historical design notes and migration records live under `docs/archive/`. They are not part of the published site. See `docs/archive/README.md` for the index and current-equivalent links. + +Do not add new design docs there — write conceptual content in `site-docs/concepts/` instead. + +--- + +## Keeping Docs Current + +Documentation updates are part of every code change. The pre-PR checklist includes: + +- Update `site-docs/contributing/` if you change architecture, CLI patterns, or configuration semantics. +- Update `site-docs/` (concepts/guides/reference) if you change user-facing commands, output format, or config files. +- Update `AGENTS.md` if the project overview, five domains, Python standards, or common patterns change. + +--- + +## AGENTS.md Conventions + +`AGENTS.md` is the authoritative reference for AI coding agents working on this project. Keep it +accurate and concise: + +- Five domains table must match the actual `domains/` directory. +- Python standards section must reflect what `test_architecture.py` enforces. +- Common patterns section must reflect current CLI handler and domain conventions. +- Update the **Last Updated** date at the bottom when making changes. + +`CLAUDE.md` must not duplicate `AGENTS.md`. It imports `AGENTS.md` via `@AGENTS.md` and adds +any additional context file references. diff --git a/docs/contributing/gotchas.md b/site-docs/contributing/gotchas.md similarity index 100% rename from docs/contributing/gotchas.md rename to site-docs/contributing/gotchas.md diff --git a/site-docs/contributing/index.md b/site-docs/contributing/index.md new file mode 100644 index 0000000..6f20636 --- /dev/null +++ b/site-docs/contributing/index.md @@ -0,0 +1,22 @@ +# Contributing + +Welcome — this section is the deep contributor reference for Agentic Beacon. For one-shot environment setup, the [CONTRIBUTING.md](https://github.com/Shadowsong27/agentic-beacon/blob/main/CONTRIBUTING.md) at the repo root is the canonical entry point. Once you're set up, the guides here cover the architecture, conventions, and workflows you'll need. + +--- + +## Map + +| Topic | What it covers | +|---|---| +| [Commands](commands.md) | Build, run, test, lint commands | +| [Project Layout](project-layout.md) | Annotated directory tree | +| [Architecture](architecture.md) | Four-layer design, subsystem boundaries, data flows | +| [Configuration](configuration.md) | Settings, workspace config, manifest models | +| [Local Development](local-development.md) | Dev loop, debugging, running subsets | +| [Code Style](code-style.md) | Naming, imports, formatting rules | +| [Design Patterns](design-patterns.md) | Recurring patterns and when to use them | +| [Testing](testing.md) | Test layout, unit vs integration, fixtures | +| [Contribution Workflow](contribution-workflow.md) | Branches, PRs, CI gates, release process | +| [Documentation](documentation.md) | How docs are built and published | +| [Gotchas](gotchas.md) | Known traps, architecture debt, sharp corners | +| [Open Questions](open-questions.md) | Unresolved items for future doc updates | diff --git a/docs/contributing/local-development.md b/site-docs/contributing/local-development.md similarity index 98% rename from docs/contributing/local-development.md rename to site-docs/contributing/local-development.md index eb2d311..8dd1935 100644 --- a/docs/contributing/local-development.md +++ b/site-docs/contributing/local-development.md @@ -2,8 +2,6 @@ This file covers the day-to-day development loop for Agentic Beacon — how to iterate on changes, debug issues, and test specific parts of the system. -← [Back to CONTRIBUTING.md](../../CONTRIBUTING.md) - --- ## Inner Dev Loop diff --git a/docs/contributing/open-questions.md b/site-docs/contributing/open-questions.md similarity index 100% rename from docs/contributing/open-questions.md rename to site-docs/contributing/open-questions.md diff --git a/docs/contributing/project-layout.md b/site-docs/contributing/project-layout.md similarity index 99% rename from docs/contributing/project-layout.md rename to site-docs/contributing/project-layout.md index 44c6ede..3293ff9 100644 --- a/docs/contributing/project-layout.md +++ b/site-docs/contributing/project-layout.md @@ -2,8 +2,6 @@ This file describes the directory structure of the Agentic Beacon repository and explains the organizing principles that govern where code lives. -← [Back to CONTRIBUTING.md](../../CONTRIBUTING.md) - --- ## Top-level Structure diff --git a/docs/contributing/testing.md b/site-docs/contributing/testing.md similarity index 100% rename from docs/contributing/testing.md rename to site-docs/contributing/testing.md From a88226afdb5d9aace596aa35ad0f2a2b5834aa24 Mon Sep 17 00:00:00 2001 From: Song Yikun Date: Mon, 18 May 2026 18:11:29 +0800 Subject: [PATCH 5/7] docs: update cross-references to relocated and archived docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Part of PER-190. Updates every live reference to a docs/ path that moved or was archived during the consolidation. Working documents under openspec/changes/ are left untouched — they describe historical fix-ups and reference paths that were correct at the time. - README.md: replace 7 broken docs/ links with mkdocs-site equivalents; restructure Documentation section into Concepts / Guides / Reference - CHANGELOG.md: repoint migration guide link to docs/archive/migrations/ - guides/creating-skills.md: point at the new What Is a Skill mkdocs page - guides/{getting-started,beacon-yaml-reference}.md: repoint migration links - libs/beacon/src/beacon/{core/dependencies/{resolver,manifest,frontmatter}, domains/distribution/orchestrator}.py: MIGRATION_DOC_URL constants now point at docs/archive/migrations/artifact-dependencies-frontmatter.md - libs/beacon/tests/{unit,integration}: update test assertions to match - openspec/specs/{agent-requires-manifest,artifact-dependency-resolution}/ spec.md: update spec text to reference the archive path Verified: pytest unit suite (1047 passed) and `mkdocs build --strict` both green. Refs PER-190 --- CHANGELOG.md | 4 +- README.md | 37 ++++++++++--------- guides/beacon-yaml-reference.md | 2 +- guides/creating-skills.md | 2 +- guides/getting-started.md | 2 +- .../beacon/core/dependencies/frontmatter.py | 2 +- .../src/beacon/core/dependencies/manifest.py | 2 +- .../src/beacon/core/dependencies/resolver.py | 2 +- .../domains/distribution/orchestrator.py | 2 +- .../integration/test_auto_pull_deps_e2e.py | 2 +- .../core/dependencies/test_frontmatter.py | 2 +- .../specs/agent-requires-manifest/spec.md | 2 +- .../artifact-dependency-resolution/spec.md | 4 +- 13 files changed, 34 insertions(+), 31 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 686581d..c9965e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,7 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Pending artifact alert on every `abc` subcommand.** When `.agentic-beacon/pending.yaml` is non-empty, every `abc` invocation prints a one-line stderr notice: `⚠ N pending artifacts. Run 'abc adopt' to wire them.` Exit code is unaffected. - **Removed `artifacts.knowledge` from `beacon.yaml`.** Knowledge is now auto-derived from markdown links inside adopted contexts and skills. On first sync after upgrade, any existing `artifacts.knowledge` list is silently dropped and a single INFO log is emitted. To keep a knowledge file available, ensure it is referenced by a markdown link from an adopted context or skill. -- **Agent dependencies moved from frontmatter to `agents/agents.yaml`.** `requires:` blocks in agent frontmatter are no longer supported. Agent skill dependencies must be declared in `agents/agents.yaml` instead. `abc sync` and `abc warehouse status` will hard-error if agent files contain `requires:` frontmatter or if `agents/agents.yaml` is missing/malformed. See [Migration Guide: Artifact Dependencies via Frontmatter](./docs/migrations/artifact-dependencies-frontmatter.md) for upgrade instructions. +- **Agent dependencies moved from frontmatter to `agents/agents.yaml`.** `requires:` blocks in agent frontmatter are no longer supported. Agent skill dependencies must be declared in `agents/agents.yaml` instead. `abc sync` and `abc warehouse status` will hard-error if agent files contain `requires:` frontmatter or if `agents/agents.yaml` is missing/malformed. See [Migration Guide: Artifact Dependencies via Frontmatter](./docs/archive/migrations/artifact-dependencies-frontmatter.md) for upgrade instructions. ### Added @@ -31,7 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Migration -- See [Migration Guide: Artifact Dependencies via Frontmatter](./docs/migrations/artifact-dependencies-frontmatter.md) for step-by-step instructions on adding `requires:` frontmatter to existing warehouses. +- See [Migration Guide: Artifact Dependencies via Frontmatter](./docs/archive/migrations/artifact-dependencies-frontmatter.md) for step-by-step instructions on adding `requires:` frontmatter to existing warehouses. ### Breaking Changes (PER-113 — unify-agent-distribution) diff --git a/README.md b/README.md index 0af9edf..e28b1ed 100644 --- a/README.md +++ b/README.md @@ -126,7 +126,7 @@ Everything is a per-file **symlink** into the warehouse clone — one physical f **Frontmatter dependencies.** Skills declare `requires:` in YAML frontmatter; agents declare dependencies in `agents/agents.yaml`. `abc sync` validates all declared dependencies are adopted and errors early if any are missing. -> **Read:** [Decision — Single Warehouse Write Entrypoint](docs/no-project-overrides.md) for the full design rationale. +> **Read:** [Decision — No Project-Local Artifact Overrides](https://shadowsong27.github.io/agentic-beacon/concepts/design-decisions/) for the full design rationale. > **Platform support:** macOS and Linux only. @@ -142,7 +142,7 @@ Everything is a per-file **symlink** into the warehouse clone — one physical f - **Skills** — reusable workflows wired as slash commands into each tool's live directories. - **Agents** — sub-agent definitions declared per-project in `beacon.yaml` and symlinked into project-local `.claude/agents/` and `.opencode/agents/`; edits flow back to the warehouse through the symlink. -> See **[Artifact Type Matrix](./docs/artifact-type-matrix.md)** for the full design rationale. +> See **[Artifact Types](https://shadowsong27.github.io/agentic-beacon/concepts/artifact-types/)** for the full design rationale. ## When to Use Agentic Beacon @@ -158,21 +158,24 @@ Everything is a per-file **symlink** into the warehouse clone — one physical f 📚 **Full documentation site:** [shadowsong27.github.io/agentic-beacon](https://shadowsong27.github.io/agentic-beacon/) -### Conceptual Design (docs/) -- **[Artifact Type Matrix](./docs/artifact-type-matrix.md)** — Scope and tool-specificity axes; how they drive command design -- **[Agentic Warehouse Design](./docs/agentic-warehouse-design.md)** — High-level design and architecture -- **[Boot Context Design](./docs/boot-context-design/)** — AGENTS.md architecture and patterns -- **[Spec-Driven Development](./docs/spec-driven-development.md)** — Structured approach to feature planning -- **[Migration: Artifact Dependencies via Frontmatter](./docs/migrations/artifact-dependencies-frontmatter.md)** — Migrate warehouses to auto-derived knowledge and `requires:` frontmatter - -### Practical Guides (guides/) -- **[Getting Started](./guides/getting-started.md)** — Full onboarding walkthrough -- **[Warehouse Creation](./guides/warehouse-creation.md)** — Creating and structuring a warehouse -- **[Contributing Back](./guides/warehouse-contribution-guide.md)** — Commit agent improvements back to the warehouse -- **[beacon.yaml Reference](./guides/beacon-yaml-reference.md)** — Full configuration schema -- **[Team Collaboration](./guides/team-collaboration.md)** — Multi-team workflows -- **[Advanced Patterns](./guides/advanced-patterns.md)** — Glob patterns, dry-run, warehouse commands, migration -- **[CLI Reference](./docs/cli-reference.md)** — Full command reference +### Concepts +- **[How It Works](https://shadowsong27.github.io/agentic-beacon/concepts/how-it-works/)** — Warehouse + beacon mental model and sync flow +- **[Philosophy](https://shadowsong27.github.io/agentic-beacon/concepts/philosophy/)** — Why this exists, why markdown not RAG, why lightweight +- **[Artifact Types](https://shadowsong27.github.io/agentic-beacon/concepts/artifact-types/)** — Scope and tool-specificity axes; how they drive command design +- **[Specs vs. Artifacts](https://shadowsong27.github.io/agentic-beacon/concepts/specs-vs-artifacts/)** — What belongs in a warehouse vs. a project +- **[Design Decisions](https://shadowsong27.github.io/agentic-beacon/concepts/design-decisions/)** — Architectural choices and their rationale + +### Guides +- **[Quick Start](https://shadowsong27.github.io/agentic-beacon/quickstart/)** — Onboarding walkthrough +- **[Warehouse Creation](https://shadowsong27.github.io/agentic-beacon/guides/warehouse-creation/)** — Creating and structuring a warehouse +- **[Contributing Back](https://shadowsong27.github.io/agentic-beacon/guides/contributing-back/)** — Commit agent improvements back to the warehouse +- **[Spec-Driven Development](https://shadowsong27.github.io/agentic-beacon/guides/spec-driven-development/)** — Structured approach to feature planning +- **[Team Collaboration](https://shadowsong27.github.io/agentic-beacon/guides/team-collaboration/)** — Multi-team workflows +- **[Advanced Patterns](https://shadowsong27.github.io/agentic-beacon/guides/advanced-patterns/)** — Glob patterns, dry-run, warehouse commands, migration + +### Reference +- **[beacon.yaml](https://shadowsong27.github.io/agentic-beacon/reference/beacon-yaml/)** — Full configuration schema +- **[CLI Reference](https://shadowsong27.github.io/agentic-beacon/reference/cli/)** — Full command reference ### Examples (examples/) - **[Beacon Configs](./examples/beacon-configs/)** — Example `beacon.yaml` configurations for common project setups diff --git a/guides/beacon-yaml-reference.md b/guides/beacon-yaml-reference.md index f950dd1..bc7381c 100644 --- a/guides/beacon-yaml-reference.md +++ b/guides/beacon-yaml-reference.md @@ -28,7 +28,7 @@ ignore: - "openspec-*" # fnmatch glob patterns ``` -> **Note:** `artifacts.knowledge` was removed in a recent version. Knowledge is now auto-derived from markdown links inside adopted contexts and skills. See [Migration: Artifact Dependencies via Frontmatter](../docs/migrations/artifact-dependencies-frontmatter.md) for details. +> **Note:** `artifacts.knowledge` was removed in a recent version. Knowledge is now auto-derived from markdown links inside adopted contexts and skills. See [Migration: Artifact Dependencies via Frontmatter](../docs/archive/migrations/artifact-dependencies-frontmatter.md) for details. > **Note:** Agents are machine-level global artifacts installed into `~/.config/opencode/agents/` and `~/.claude/agents/` via `abc install agents/.md` or `abc adopt`. They are not tracked in `beacon.yaml` (which contains only contexts and skills). `abc sync` does not install all warehouse agents and does not consume agent `requires`. PER-109 adds persistent selected-global-agent state so `abc sync` can install the user's selected set of global agents. diff --git a/guides/creating-skills.md b/guides/creating-skills.md index cb02d68..7613330 100644 --- a/guides/creating-skills.md +++ b/guides/creating-skills.md @@ -8,7 +8,7 @@ A skill is a packaged capability — a modular unit of work defined by the **out In Agentic Beacon, skills are distributed as a directory containing a `SKILL.md` entry point plus optional supporting files. The agent reads `SKILL.md` and follows its instructions when invoked. -> For a deeper conceptual breakdown — cognitive vs. action vs. workflow skills, and why "everything is a prompt" — see [Understanding Agent Skills](../docs/understanding-agent-skills.md). +> For a deeper conceptual breakdown — cognitive vs. action vs. workflow skills, and why "everything is a prompt" — see [What Is a Skill?](https://shadowsong27.github.io/agentic-beacon/concepts/what-is-a-skill/). ## Directory Structure diff --git a/guides/getting-started.md b/guides/getting-started.md index c0ab7aa..f7d2fc1 100644 --- a/guides/getting-started.md +++ b/guides/getting-started.md @@ -181,7 +181,7 @@ artifacts: - contexts/global.md ``` -> **Note:** Knowledge files are no longer declared in `beacon.yaml`. They are auto-derived from markdown links inside your adopted contexts and skills. See [Migration: Artifact Dependencies via Frontmatter](../docs/migrations/artifact-dependencies-frontmatter.md) for details. +> **Note:** Knowledge files are no longer declared in `beacon.yaml`. They are auto-derived from markdown links inside your adopted contexts and skills. See [Migration: Artifact Dependencies via Frontmatter](../docs/archive/migrations/artifact-dependencies-frontmatter.md) for details. Paths are relative to the warehouse root. Glob patterns are supported. See [beacon.yaml Reference](./beacon-yaml-reference.md) for the full schema. diff --git a/libs/beacon/src/beacon/core/dependencies/frontmatter.py b/libs/beacon/src/beacon/core/dependencies/frontmatter.py index acfe14c..a15d409 100644 --- a/libs/beacon/src/beacon/core/dependencies/frontmatter.py +++ b/libs/beacon/src/beacon/core/dependencies/frontmatter.py @@ -27,7 +27,7 @@ def reject_skills_key(cls, data: dict) -> dict: msg = ( "Skill-to-skill dependencies are not supported. " "Remove 'skills' from the requires block. See " - "docs/migrations/artifact-dependencies-frontmatter.md" + "docs/archive/migrations/artifact-dependencies-frontmatter.md" ) raise ValueError(msg) return data diff --git a/libs/beacon/src/beacon/core/dependencies/manifest.py b/libs/beacon/src/beacon/core/dependencies/manifest.py index c4b01fa..e0a95d2 100644 --- a/libs/beacon/src/beacon/core/dependencies/manifest.py +++ b/libs/beacon/src/beacon/core/dependencies/manifest.py @@ -11,7 +11,7 @@ from beacon.core.dependencies.frontmatter import parse_frontmatter from beacon.core.exceptions import AgentManifestError -MIGRATION_DOC_URL = "docs/migrations/artifact-dependencies-frontmatter.md" +MIGRATION_DOC_URL = "docs/archive/migrations/artifact-dependencies-frontmatter.md" class AgentEntry(BaseModel): diff --git a/libs/beacon/src/beacon/core/dependencies/resolver.py b/libs/beacon/src/beacon/core/dependencies/resolver.py index 696f94d..bc671e6 100644 --- a/libs/beacon/src/beacon/core/dependencies/resolver.py +++ b/libs/beacon/src/beacon/core/dependencies/resolver.py @@ -20,7 +20,7 @@ from beacon.core.manifest.beacon import BeaconManifest from beacon.core.scanner.scanner import scan_file_for_knowledge -MIGRATION_DOC_URL = "docs/migrations/artifact-dependencies-frontmatter.md" +MIGRATION_DOC_URL = "docs/archive/migrations/artifact-dependencies-frontmatter.md" @dataclass(frozen=True) diff --git a/libs/beacon/src/beacon/domains/distribution/orchestrator.py b/libs/beacon/src/beacon/domains/distribution/orchestrator.py index 72961fd..95a9874 100644 --- a/libs/beacon/src/beacon/domains/distribution/orchestrator.py +++ b/libs/beacon/src/beacon/domains/distribution/orchestrator.py @@ -66,7 +66,7 @@ from beacon.domains.warehouse.preconditions import ensure_sync_ready from beacon.utils.git import find_project_root -MIGRATION_DOC_URL = "docs/migrations/artifact-dependencies-frontmatter.md" +MIGRATION_DOC_URL = "docs/archive/migrations/artifact-dependencies-frontmatter.md" # Per-tool entries written into agent-folder .gitignore files during sync. # Covers Beacon-owned subdirs (skills/, command/) plus tool-runtime byproducts diff --git a/libs/beacon/tests/integration/test_auto_pull_deps_e2e.py b/libs/beacon/tests/integration/test_auto_pull_deps_e2e.py index 49d9807..6367f85 100644 --- a/libs/beacon/tests/integration/test_auto_pull_deps_e2e.py +++ b/libs/beacon/tests/integration/test_auto_pull_deps_e2e.py @@ -416,7 +416,7 @@ def test_e2e_missing_skill_context_shows_migration_url( assert "missing-context" in output.lower(), ( f"Expected missing context name in output: {output}" ) - assert "docs/migrations/artifact-dependencies-frontmatter.md" in output, ( + assert "docs/archive/migrations/artifact-dependencies-frontmatter.md" in output, ( f"Expected migration doc URL in output: {output}" ) diff --git a/libs/beacon/tests/unit/core/dependencies/test_frontmatter.py b/libs/beacon/tests/unit/core/dependencies/test_frontmatter.py index de830e4..7f3f307 100644 --- a/libs/beacon/tests/unit/core/dependencies/test_frontmatter.py +++ b/libs/beacon/tests/unit/core/dependencies/test_frontmatter.py @@ -100,7 +100,7 @@ def test_tc6_skill_with_skills_key(self): ) assert "skill" in str(exc_info.value).lower() assert ( - "docs/migrations/artifact-dependencies-frontmatter.md" + "docs/archive/migrations/artifact-dependencies-frontmatter.md" in str(exc_info.value).lower() ) diff --git a/openspec/specs/agent-requires-manifest/spec.md b/openspec/specs/agent-requires-manifest/spec.md index 92c3dab..cef5fc0 100644 --- a/openspec/specs/agent-requires-manifest/spec.md +++ b/openspec/specs/agent-requires-manifest/spec.md @@ -12,7 +12,7 @@ The system SHALL require every warehouse that contains at least one `agents/*.md #### Scenario: Warehouse with agents missing agents.yaml - **WHEN** a warehouse contains `agents/spec-planner.md` but no `agents/agents.yaml` -- **THEN** `abc warehouse status` and `abc sync` both fail with an error identifying the missing file and linking to `docs/migrations/artifact-dependencies-frontmatter.md` +- **THEN** `abc warehouse status` and `abc sync` both fail with an error identifying the missing file and linking to `docs/archive/migrations/artifact-dependencies-frontmatter.md` #### Scenario: Empty agents directory - **WHEN** a warehouse contains an `agents/` directory with only `README.md` (or is empty) diff --git a/openspec/specs/artifact-dependency-resolution/spec.md b/openspec/specs/artifact-dependency-resolution/spec.md index 651e098..32e58db 100644 --- a/openspec/specs/artifact-dependency-resolution/spec.md +++ b/openspec/specs/artifact-dependency-resolution/spec.md @@ -60,11 +60,11 @@ If a required skill declared by an agent in `agents.yaml` does NOT exist in the - **THEN** `abc sync` exits non-zero with an error naming `spec-planner`, the missing skill `ghost-skill`, and linking to the migration document — regardless of TTY mode ### Requirement: Migration document exists and is referenced -The system SHALL ship a migration document at `docs/migrations/artifact-dependencies-frontmatter.md` in the agentic-beacon repository. Every error message raised by the sync flow due to missing or malformed `requires:` frontmatter on skills SHALL include a URL pointing to this document. +The system SHALL ship a migration document at `docs/archive/migrations/artifact-dependencies-frontmatter.md` in the agentic-beacon repository. Every error message raised by the sync flow due to missing or malformed `requires:` frontmatter on skills SHALL include a URL pointing to this document. #### Scenario: Error message links to migration doc - **WHEN** `abc sync` fails due to a missing `requires:` block on a skill -- **THEN** the error message includes the string "docs/migrations/artifact-dependencies-frontmatter.md" +- **THEN** the error message includes the string "docs/archive/migrations/artifact-dependencies-frontmatter.md" ### Requirement: Contexts have no frontmatter dependencies The system SHALL NOT inspect context files for a `requires:` block. Context files have no sibling-tier dependencies: they reach knowledge via markdown links in the body and do not depend on other contexts or skills. From aa6272c5d4624c9ec2317d1bef7bc7c542f3f0fd Mon Sep 17 00:00:00 2001 From: Song Yikun Date: Mon, 18 May 2026 22:26:41 +0800 Subject: [PATCH 6/7] docs: restructure guides, split out Design section, merge adoption pages (PER-190) Iterative restructuring pass on top of phases A-D: - New top-level Design section: philosophy and skills (moved from concepts/) - design/skills.md: merged what-is-a-skill + bundled-skills framing, reframed as 'thin skills, fat tools' / intermediate state perspective - guides/adopting-artifacts.md: merged interactive-adoption + syncing into a single page presenting interactive vs declarative adoption paths - New Contributing Back parent guide with three sub-pages: creating-skills, creating-knowledge-and-contexts, creating-agents - guides/contribute-warehouse.md moved to reference/ (it is reference, not a flow guide) - Deleted: team-collaboration.md (covered by symlink/sync/adoption pages), spec-driven-development.md (out of scope; openspec mentioned where relevant) - contributing/ docs reshuffled: site-docs/contributing/* moved to docs/contributing/ (agent-facing); top-level user-facing site-docs/contributing.md added as the public entry point - Knowledge / context two-tier framing rewritten: context is a curated collection of knowledge; progressive disclosure is an optimisation, not the definition Note: mkdocs.yml is left at the post-audit state (commit 2). This commit alone will not build a coherent nav; the branch endpoint does. --- CONTRIBUTING.md | 36 ++- .../contributing/architecture.md | 0 .../contributing/code-style.md | 0 {site-docs => docs}/contributing/commands.md | 0 .../contributing/configuration.md | 0 .../contributing/contribution-workflow.md | 2 +- .../contributing/design-patterns.md | 0 .../contributing/documentation.md | 27 +- {site-docs => docs}/contributing/gotchas.md | 0 .../contributing/local-development.md | 0 .../contributing/open-questions.md | 0 .../contributing/project-layout.md | 0 {site-docs => docs}/contributing/testing.md | 0 site-docs/concepts/how-it-works.md | 4 +- site-docs/concepts/pending-and-adoption.md | 2 +- site-docs/concepts/what-is-a-skill.md | 69 ----- site-docs/contributing/index.md | 22 -- site-docs/{concepts => design}/philosophy.md | 20 +- site-docs/design/skills.md | 123 ++++++++ site-docs/guides/adopting-artifacts.md | 143 +++++++++ site-docs/guides/contributing-back.md | 112 ++++--- site-docs/guides/creating-agents.md | 147 ++++++++++ .../guides/creating-knowledge-and-contexts.md | 147 ++++++++++ site-docs/guides/creating-skills.md | 251 ++++------------ site-docs/guides/interactive-adoption.md | 106 ------- site-docs/guides/spec-driven-development.md | 199 ------------- site-docs/guides/syncing.md | 150 ---------- site-docs/guides/team-collaboration.md | 273 ------------------ site-docs/guides/warehouse-creation.md | 4 +- site-docs/index.md | 20 -- site-docs/installation.md | 10 - site-docs/quickstart.md | 22 +- site-docs/reference/beacon-yaml.md | 19 +- .../contribute-warehouse.md | 6 +- 34 files changed, 727 insertions(+), 1187 deletions(-) rename {site-docs => docs}/contributing/architecture.md (100%) rename {site-docs => docs}/contributing/code-style.md (100%) rename {site-docs => docs}/contributing/commands.md (100%) rename {site-docs => docs}/contributing/configuration.md (100%) rename {site-docs => docs}/contributing/contribution-workflow.md (95%) rename {site-docs => docs}/contributing/design-patterns.md (100%) rename {site-docs => docs}/contributing/documentation.md (64%) rename {site-docs => docs}/contributing/gotchas.md (100%) rename {site-docs => docs}/contributing/local-development.md (100%) rename {site-docs => docs}/contributing/open-questions.md (100%) rename {site-docs => docs}/contributing/project-layout.md (100%) rename {site-docs => docs}/contributing/testing.md (100%) delete mode 100644 site-docs/concepts/what-is-a-skill.md delete mode 100644 site-docs/contributing/index.md rename site-docs/{concepts => design}/philosophy.md (64%) create mode 100644 site-docs/design/skills.md create mode 100644 site-docs/guides/adopting-artifacts.md create mode 100644 site-docs/guides/creating-agents.md create mode 100644 site-docs/guides/creating-knowledge-and-contexts.md delete mode 100644 site-docs/guides/interactive-adoption.md delete mode 100644 site-docs/guides/spec-driven-development.md delete mode 100644 site-docs/guides/syncing.md delete mode 100644 site-docs/guides/team-collaboration.md rename site-docs/{guides => reference}/contribute-warehouse.md (97%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1011c8a..0a3363f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,6 @@ # Contributing to Agentic Beacon -Welcome — this file is the entry point for new contributors. It covers everything you need to go from a fresh clone to running tests locally. The deeper guides (architecture, code style, testing strategy, design patterns, gotchas, etc.) live on the documentation site: - -📚 **** +Welcome — this file is the entry point for new contributors. It covers everything you need to go from a fresh clone to running tests locally. The deeper reference material (architecture, code style, testing strategy, design patterns, gotchas, etc.) is in `docs/contributing/` and is primarily there so AI coding agents working in the repo have something to grep. Human contributors generally won't need to read them end-to-end. --- @@ -97,19 +95,19 @@ These are rarely needed in normal development. ## Where to Go Next -The rest of the contributor reference is on the documentation site. Bookmark the [Contributing section](https://shadowsong27.github.io/agentic-beacon/contributing/) and dip in by topic: - -- [Commands](https://shadowsong27.github.io/agentic-beacon/contributing/commands/) — build, run, test, and lint commands -- [Project Layout](https://shadowsong27.github.io/agentic-beacon/contributing/project-layout/) — annotated directory tree -- [Architecture](https://shadowsong27.github.io/agentic-beacon/contributing/architecture/) — four-layer design, five domains, data flows -- [Configuration](https://shadowsong27.github.io/agentic-beacon/contributing/configuration/) — settings, workspace config, manifest models -- [Local Development](https://shadowsong27.github.io/agentic-beacon/contributing/local-development/) — dev loop, debugging, running subsets -- [Code Style](https://shadowsong27.github.io/agentic-beacon/contributing/code-style/) — naming, imports, formatting rules -- [Design Patterns](https://shadowsong27.github.io/agentic-beacon/contributing/design-patterns/) — recurring patterns and when to use them -- [Testing](https://shadowsong27.github.io/agentic-beacon/contributing/testing/) — test layout, unit vs integration, fixtures -- [Contribution Workflow](https://shadowsong27.github.io/agentic-beacon/contributing/contribution-workflow/) — branches, PRs, CI gates, release process -- [Documentation](https://shadowsong27.github.io/agentic-beacon/contributing/documentation/) — how docs are built and published -- [Gotchas](https://shadowsong27.github.io/agentic-beacon/contributing/gotchas/) — known traps and sharp corners -- [Open Questions](https://shadowsong27.github.io/agentic-beacon/contributing/open-questions/) — unresolved items - -If the live site is ever unreachable, the same content is in `site-docs/contributing/` in this repo. +The deep reference lives in `docs/contributing/`. These files are primarily written for AI coding agents working in the repo — the most efficient way to use them is to point your agent at the directory ("read `docs/contributing/`") and let it pick what's relevant. + +| File | Covers | +|---|---| +| [`commands.md`](docs/contributing/commands.md) | Build, run, test, and lint commands | +| [`project-layout.md`](docs/contributing/project-layout.md) | Annotated directory tree | +| [`architecture.md`](docs/contributing/architecture.md) | Four-layer design, five domains, data flows | +| [`configuration.md`](docs/contributing/configuration.md) | Settings, workspace config, manifest models | +| [`local-development.md`](docs/contributing/local-development.md) | Dev loop, debugging, running subsets | +| [`code-style.md`](docs/contributing/code-style.md) | Naming, imports, formatting rules | +| [`design-patterns.md`](docs/contributing/design-patterns.md) | Recurring patterns and when to use them | +| [`testing.md`](docs/contributing/testing.md) | Test layout, unit vs integration, fixtures | +| [`contribution-workflow.md`](docs/contributing/contribution-workflow.md) | Branches, PRs, CI gates, release process | +| [`documentation.md`](docs/contributing/documentation.md) | How docs are built and published | +| [`gotchas.md`](docs/contributing/gotchas.md) | Known traps and sharp corners | +| [`open-questions.md`](docs/contributing/open-questions.md) | Unresolved items | diff --git a/site-docs/contributing/architecture.md b/docs/contributing/architecture.md similarity index 100% rename from site-docs/contributing/architecture.md rename to docs/contributing/architecture.md diff --git a/site-docs/contributing/code-style.md b/docs/contributing/code-style.md similarity index 100% rename from site-docs/contributing/code-style.md rename to docs/contributing/code-style.md diff --git a/site-docs/contributing/commands.md b/docs/contributing/commands.md similarity index 100% rename from site-docs/contributing/commands.md rename to docs/contributing/commands.md diff --git a/site-docs/contributing/configuration.md b/docs/contributing/configuration.md similarity index 100% rename from site-docs/contributing/configuration.md rename to docs/contributing/configuration.md diff --git a/site-docs/contributing/contribution-workflow.md b/docs/contributing/contribution-workflow.md similarity index 95% rename from site-docs/contributing/contribution-workflow.md rename to docs/contributing/contribution-workflow.md index d1839f0..00e169e 100644 --- a/site-docs/contributing/contribution-workflow.md +++ b/docs/contributing/contribution-workflow.md @@ -8,7 +8,7 @@ How to contribute a change — from branch to merged PR. 1. Check [open issues](https://github.com/Shadowsong27/agentic-beacon/issues) for context. 2. For non-trivial changes, open or comment on an issue first to align on approach. -3. Make sure your environment is set up: see [CONTRIBUTING.md](https://github.com/Shadowsong27/agentic-beacon/blob/main/CONTRIBUTING.md) in the repo root. +3. Make sure your environment is set up: see [CONTRIBUTING.md](../../CONTRIBUTING.md). --- diff --git a/site-docs/contributing/design-patterns.md b/docs/contributing/design-patterns.md similarity index 100% rename from site-docs/contributing/design-patterns.md rename to docs/contributing/design-patterns.md diff --git a/site-docs/contributing/documentation.md b/docs/contributing/documentation.md similarity index 64% rename from site-docs/contributing/documentation.md rename to docs/contributing/documentation.md index d2155fe..66220f7 100644 --- a/site-docs/contributing/documentation.md +++ b/docs/contributing/documentation.md @@ -6,14 +6,19 @@ How project documentation is organized and maintained. ## Documentation Sources -| Location | Purpose | -|---|---| -| `CONTRIBUTING.md` | Thin entry point at the repo root — environment setup + pointer to this site | -| `site-docs/` | MkDocs source — user-facing docs and contributor guides, published to GitHub Pages | -| `site-docs/contributing/` | Contributor guides (this directory) | -| `docs/archive/` | Frozen historical design and migration notes (not published) | -| `AGENTS.md` | Project context for AI coding agents (authoritative project reference) | -| `CLAUDE.md` | AI agent bootstrap file — imports `AGENTS.md` and context files | +| Location | Purpose | Audience | +|---|---|---| +| `CONTRIBUTING.md` | Environment setup; GitHub-rendered entry point | Humans | +| `site-docs/` | MkDocs source — user-facing docs published to GitHub Pages | Humans (Beacon users) | +| `docs/contributing/` | Deep reference for the `abc` codebase (this directory) | Mostly agents | +| `docs/archive/` | Frozen historical design and migration notes (not published) | Humans on a hunt | +| `AGENTS.md` | High-level project context, auto-loaded on session start | Agents | +| `CLAUDE.md` | Bootstrap file that imports `AGENTS.md` and context files | Agents (Claude Code) | + +The split exists because the value of each document is very different: + +- `site-docs/` is for **users** of Agentic Beacon — installing `abc`, creating a warehouse, adopting artifacts. It needs to be polished and to have a small, navigable nav. +- `docs/contributing/` is reference material an **agent** reads when modifying the `abc` codebase — architecture, code style, design patterns, gotchas. Surfacing it on the public site would clutter the nav for users who never need it. --- @@ -37,7 +42,7 @@ The site is deployed automatically to GitHub Pages on every push to `main` via ### Adding a page -1. Create a `.md` file under `site-docs/` (use the existing folder structure: `concepts/`, `guides/`, `tutorials/`, `reference/`, `contributing/`). +1. Create a `.md` file under `site-docs/` (use the existing folder structure: `concepts/`, `guides/`, `tutorials/`, `reference/`, `design/`). 2. Add the page to the `nav:` section in `mkdocs.yml`. 3. Verify it renders cleanly with `mkdocs build --strict`. @@ -47,7 +52,7 @@ The site is deployed automatically to GitHub Pages on every push to `main` via Historical design notes and migration records live under `docs/archive/`. They are not part of the published site. See `docs/archive/README.md` for the index and current-equivalent links. -Do not add new design docs there — write conceptual content in `site-docs/concepts/` instead. +Do not add new design docs there — write conceptual content in `site-docs/concepts/` or `site-docs/design/` instead. --- @@ -55,7 +60,7 @@ Do not add new design docs there — write conceptual content in `site-docs/conc Documentation updates are part of every code change. The pre-PR checklist includes: -- Update `site-docs/contributing/` if you change architecture, CLI patterns, or configuration semantics. +- Update `docs/contributing/` if you change architecture, CLI patterns, or configuration semantics. - Update `site-docs/` (concepts/guides/reference) if you change user-facing commands, output format, or config files. - Update `AGENTS.md` if the project overview, five domains, Python standards, or common patterns change. diff --git a/site-docs/contributing/gotchas.md b/docs/contributing/gotchas.md similarity index 100% rename from site-docs/contributing/gotchas.md rename to docs/contributing/gotchas.md diff --git a/site-docs/contributing/local-development.md b/docs/contributing/local-development.md similarity index 100% rename from site-docs/contributing/local-development.md rename to docs/contributing/local-development.md diff --git a/site-docs/contributing/open-questions.md b/docs/contributing/open-questions.md similarity index 100% rename from site-docs/contributing/open-questions.md rename to docs/contributing/open-questions.md diff --git a/site-docs/contributing/project-layout.md b/docs/contributing/project-layout.md similarity index 100% rename from site-docs/contributing/project-layout.md rename to docs/contributing/project-layout.md diff --git a/site-docs/contributing/testing.md b/docs/contributing/testing.md similarity index 100% rename from site-docs/contributing/testing.md rename to docs/contributing/testing.md diff --git a/site-docs/concepts/how-it-works.md b/site-docs/concepts/how-it-works.md index 7e2f926..5765511 100644 --- a/site-docs/concepts/how-it-works.md +++ b/site-docs/concepts/how-it-works.md @@ -145,7 +145,7 @@ Knowledge files are **not** declared — `abc sync` auto-derives them by scannin 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 [Syncing guide](../guides/syncing.md). For per-type details (what wiring each artifact gets), see [Artifact Types](artifact-types.md). +For the full pipeline, flags, and edge cases, see the [Adopting Artifacts guide](../guides/adopting-artifacts.md). For per-type details (what wiring each artifact gets), see [Artifact Types](artifact-types.md). --- @@ -163,7 +163,7 @@ This is what makes the contribution loop tight: there is no copy step, so the ag ## 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](bundled-skills.md) (`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`](../guides/contribute-warehouse.md) bundled skill — it lints, scans for duplicates, splits the changes into cohesive commits, and atomically pushes once. +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](bundled-skills.md) (`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`](../reference/contribute-warehouse.md) bundled skill — it lints, scans for duplicates, splits the changes into cohesive commits, and atomically pushes once.
diff --git a/site-docs/concepts/pending-and-adoption.md b/site-docs/concepts/pending-and-adoption.md index c996fc5..5258f7f 100644 --- a/site-docs/concepts/pending-and-adoption.md +++ b/site-docs/concepts/pending-and-adoption.md @@ -173,5 +173,5 @@ For details on how bundled skills are wired into your project after `abc adopt`, ## Next Steps - **[Bundled Skills](bundled-skills.md)** — the `record-*` skills that write to `pending.yaml` -- **[Interactive Adoption](../guides/interactive-adoption.md)** — full `abc adopt` TUI reference +- **[Adopting Artifacts](../guides/adopting-artifacts.md)** — full `abc adopt` TUI reference - **[beacon.yaml Reference](../reference/beacon-yaml.md)** — structure of the committed artifact config diff --git a/site-docs/concepts/what-is-a-skill.md b/site-docs/concepts/what-is-a-skill.md deleted file mode 100644 index 419de3b..0000000 --- a/site-docs/concepts/what-is-a-skill.md +++ /dev/null @@ -1,69 +0,0 @@ -# What Is a Skill? - -A conceptual primer on agent skills — what they are, how to think about them, and where they sit in Agentic Beacon. - ---- - -## A Skill Is an Abstraction of a Capability - -The best way to view an agent skill is as **an abstraction of a capability** — a modular unit of work the agent knows how to perform. Define a skill by the **outcome it enables**, not by how it is implemented under the hood. - ---- - -## The Spectrum of Skills - -Skills exist on a spectrum from purely cognitive to purely mechanical. - -### Cognitive skills - -A set of instructions, a reasoning framework, or a persona injected into the agent's context. The agent doesn't execute code — it changes *how it thinks*. - -**Example:** A "Copywriting Skill" that says: *"Always use the AIDA framework. Here are three examples of good copy..."* - -The skill gives the agent a repeatable, reliable way to perform a specific intellectual task. - -### Action skills - -A deterministic tool the agent can invoke to interact with the outside world — a function call, an API integration, a CLI command. - -**Example:** A "Fetch Jira Ticket Skill" that gives the agent an OpenAPI spec to query a Jira instance. - -The skill extends the agent's reach beyond its training data into external systems. - -### Workflow skills - -A multi-step, orchestrated process combining cognitive and action skills — involving loops, conditional logic, multiple prompts, and multiple tools. - -**Example:** A "Triage Bug Report Skill" that (1) queries the database for related issues, (2) evaluates severity using a structured prompt, and (3) creates a ticket via API. - ---- - -## Everything Is a Prompt - -Under the hood, even function calls are just prompts. When you give an LLM access to a `search_web` tool, you're not giving it code — you're injecting a prompt that says: *"You have access to a tool called search_web. To use it, output JSON formatted like this..."* - -The LLM's only interface with the world is text in and text out. The line between a "prompt skill" and a "function skill" is an implementation detail: - -- A **cognitive skill** tells the LLM to output natural language formatted in a certain way -- An **action skill** tells the LLM to output JSON formatted in a certain way, which downstream code intercepts and executes - ---- - -## Where Skills Fit in Agentic Beacon - -Think of a skill as a **black-box interface**: it takes an input, does some agentic work, and returns an output. When designing your skill library, don't limit yourself to just one type: - -| Skill Type | Example | Implementation | -|---|---|---| -| Cognitive | Code review checklist | `SKILL.md` with structured instructions | -| Action | Fetch GitHub PR diff | `SKILL.md` + tool/API spec | -| Workflow | Full PR review pipeline | `SKILL.md` orchestrating multiple steps and tools | - -In Agentic Beacon, `SKILL.md`-based skills are primarily **cognitive and workflow skills** — they package repeatable reasoning processes and multi-step procedures as distributable artifacts. Action skills (tool integrations) are typically handled at the agent tool level rather than in a warehouse. - ---- - -## Further Reading - -- [Bundled Skills](bundled-skills.md) — the three skills shipped inside `abc` itself -- [Creating Skills](../guides/creating-skills.md) — how to write and distribute warehouse skills diff --git a/site-docs/contributing/index.md b/site-docs/contributing/index.md deleted file mode 100644 index 6f20636..0000000 --- a/site-docs/contributing/index.md +++ /dev/null @@ -1,22 +0,0 @@ -# Contributing - -Welcome — this section is the deep contributor reference for Agentic Beacon. For one-shot environment setup, the [CONTRIBUTING.md](https://github.com/Shadowsong27/agentic-beacon/blob/main/CONTRIBUTING.md) at the repo root is the canonical entry point. Once you're set up, the guides here cover the architecture, conventions, and workflows you'll need. - ---- - -## Map - -| Topic | What it covers | -|---|---| -| [Commands](commands.md) | Build, run, test, lint commands | -| [Project Layout](project-layout.md) | Annotated directory tree | -| [Architecture](architecture.md) | Four-layer design, subsystem boundaries, data flows | -| [Configuration](configuration.md) | Settings, workspace config, manifest models | -| [Local Development](local-development.md) | Dev loop, debugging, running subsets | -| [Code Style](code-style.md) | Naming, imports, formatting rules | -| [Design Patterns](design-patterns.md) | Recurring patterns and when to use them | -| [Testing](testing.md) | Test layout, unit vs integration, fixtures | -| [Contribution Workflow](contribution-workflow.md) | Branches, PRs, CI gates, release process | -| [Documentation](documentation.md) | How docs are built and published | -| [Gotchas](gotchas.md) | Known traps, architecture debt, sharp corners | -| [Open Questions](open-questions.md) | Unresolved items for future doc updates | diff --git a/site-docs/concepts/philosophy.md b/site-docs/design/philosophy.md similarity index 64% rename from site-docs/concepts/philosophy.md rename to site-docs/design/philosophy.md index e1b8b6e..654e777 100644 --- a/site-docs/concepts/philosophy.md +++ b/site-docs/design/philosophy.md @@ -58,21 +58,23 @@ The goal is to solve the DRY problem for agentic knowledge without creating a ne ## Two-Tier Information Model -A direct consequence of staying file-based is that agents need a way to scan boot context fast and pull deeper detail only when relevant. Beacon's structure formalises this as two tiers: +A direct consequence of staying file-based is that the warehouse needs to be cheap to load at session start without sacrificing organisational depth. Beacon's structure addresses this with two related artifact types, and an optimisation pattern that connects them: -- **Tier 1 — Contexts** (boot context, loaded on session start): lightweight, scannable, contains summaries and pointers — *what does the agent need to know exists?* -- **Tier 2 — Knowledge** (deep context, loaded on demand): detailed explanations, rationale, examples — *what are the full details when needed?* +- **Contexts** are the boot-time payload — the agent loads them on session start. A context is, in effect, a curated collection of knowledge: it can hold short rules and patterns inline AND point at deeper material elsewhere. +- **Knowledge files** are atomic units — one decision, one lesson, one fact, in its own file. They can be referenced from one or more contexts (or from other knowledge files), and they exist as standalone files so the same knowledge can be composed into multiple contexts and so it can be left out of the boot-time payload when it's not needed every session. -Pointers between the two come in two flavours: +Within a context, two link styles signal how the linked content should be treated: -- **Proactive pointers** (written as `**Read:**`) — agent must internalise immediately because the rule affects every file they touch. -- **Reactive pointers** (written as `**See:**`) — agent loads only when encountering the specific problem (troubleshooting, edge cases). +- **Proactive pointers** (`**Read:**`) — the linked content matters often enough that the agent should load it immediately when starting work in this area. +- **Reactive pointers** (`**See:**`) — the linked content is troubleshooting, edge-case detail, or reference material; the agent only loads it when the specific situation arises. -This separation is what keeps boot context cheap to load while preserving access to organisational depth. The taxonomy inside `knowledge/` — `decisions/`, `lessons/`, `facts/` — is enforced by `abc warehouse lint`; see [Artifact Types](artifact-types.md) for the operational rules. +The progressive-disclosure pattern that emerges from these pointer styles is an **optimisation**, not the definition of either artifact. Not all knowledge is hidden at session start; some of it lives inline in a context because the rule applies every session and is short enough that hiding it would just force an extra link-follow. The extraction decision — *should this be inline content in the context, or its own knowledge file?* — is a judgement call, covered in the [Creating Knowledge and Contexts](../guides/creating-knowledge-and-contexts.md) guide. + +The taxonomy inside `knowledge/` — `decisions/`, `lessons/`, `facts/` — is enforced by `abc warehouse lint`; see [Artifact Types](../concepts/artifact-types.md) for the operational rules. --- ## Next -- [How It Works](how-it-works.md) — the mechanics that follow from these choices -- [Artifact Types](artifact-types.md) — the four types and how each is wired +- [How It Works](../concepts/how-it-works.md) — the mechanics that follow from these choices +- [Artifact Types](../concepts/artifact-types.md) — the four types and how each is wired diff --git a/site-docs/design/skills.md b/site-docs/design/skills.md new file mode 100644 index 0000000..2bab6ca --- /dev/null +++ b/site-docs/design/skills.md @@ -0,0 +1,123 @@ +# Skills + +A conceptual take on what agent skills are, why I think the current form is an intermediate one, and how the *workflow* end of the spectrum increasingly belongs to agents rather than skills. + +This page is opinion and design rationale, not usage. For the practical reference on the skills that ship inside `abc` (`/record-knowledge`, `/record-skill`, `/contribute-warehouse`), see [Bundled Skills](../concepts/bundled-skills.md). + +--- + +## A Skill Is an Abstraction of a Capability + +The best way to view an agent skill is as **an abstraction of a capability** — a modular unit of work the agent knows how to perform. Define a skill by the **outcome it enables**, not by how it is implemented under the hood. + +--- + +## The Spectrum of Skills + +Skills exist on a spectrum from purely cognitive to purely mechanical. + +### Cognitive skills + +A set of instructions, a reasoning framework, or a persona injected into the agent's context. The agent doesn't execute code — it changes *how it thinks*. + +**Example:** A "Copywriting Skill" that says: *"Always use the AIDA framework. Here are three examples of good copy..."* + +The skill gives the agent a repeatable, reliable way to perform a specific intellectual task. + +### Action skills + +A deterministic tool the agent can invoke to interact with the outside world — a function call, an API integration, a CLI command. + +**Example:** A "Fetch Jira Ticket Skill" that gives the agent an OpenAPI spec to query a Jira instance. + +The skill extends the agent's reach beyond its training data into external systems. + +### Workflow skills + +A multi-step, orchestrated process combining cognitive and action skills — involving loops, conditional logic, multiple prompts, and multiple tools. + +**Example:** A "Triage Bug Report Skill" that (1) queries the database for related issues, (2) evaluates severity using a structured prompt, and (3) creates a ticket via API. + +--- + +## Thin Skill, Fat Tools + +It's tempting to say *"everything is a prompt"* — that under the hood, even function calls reduce to text instructions the LLM emits and downstream code interprets. That framing is misleading. It collapses an important distinction the current generation of skills actively exploits: **the split between what should be non-deterministic and what should be deterministic.** + +A well-designed skill is **thin** — a prompt that orchestrates reasoning, handles the parts that genuinely need a language model (intent classification, decision points, free-form summarisation, what-to-do-next judgement). The prompt is the entry point into a wider set of capabilities. + +The capabilities themselves are **fat tools** — CLIs, scripts, library calls — that handle everything deterministic. File I/O. YAML manipulation. Git operations. String formatting that has to come out exactly right every time. You don't want an LLM doing those: it's slow, expensive, and gets details wrong in unpredictable ways. You want a script. + +The bundled `contribute-warehouse` skill is the cleanest example in this repo: + +| Layer | Concern | Implementation | +|---|---|---| +| **Prompt** | "Are these changes cohesive? Should they be one commit or several? What's a good commit message?" | The agent reasons over the diff in natural language | +| **Tools** | "Stage these specific files. Run the lint gate. Write the commit. Push atomically." | `summarize_changes.py`, `draft_commit_message.py`, `push_warehouse.py`, `abc warehouse contribute` | + +The prompt never *writes* a commit. It decides what should be in it; the script executes that decision. + +This is what cognitive vs. action skill means in practice: + +- A **cognitive skill** is almost entirely prompt — the work *is* the reasoning, and the only "tool" is the LLM's own output. Code review checklists, naming-convention guidance, structured-output templates fit here. +- An **action skill** is a thin prompt that decides *when* and *how* to invoke fat external tools. The skill's value is in the orchestration, not the execution. + +Skill authors who don't internalise this end up writing prompts that ask the LLM to do work that should be a script. That produces slow, brittle, expensive skills. The right discipline is the opposite: **push as much as possible into deterministic tools, and let the prompt do only what genuinely requires judgement.** + +--- + +## Why I Think Skills Are an Intermediate Form + +Skills, as we package them today — a `SKILL.md` file with frontmatter, optionally bundled with scripts — are a useful response to a current constraint: LLMs need explicit, discoverable instructions to behave consistently across sessions, and we don't yet have a better substrate for distributing those instructions than markdown in a git repo. + +I don't think this is the end form of how agents interact with the world. It's an **intermediate state**. A few reasons: + +- The packaging is human-curated. Today you author a `SKILL.md`, decide when to invoke it, and maintain it as the model behind it improves. As models get better at long-running planning and at retrieving relevant procedures on demand, the value of *pre-packaging* a repeatable workflow shrinks — the agent can increasingly assemble the procedure itself from looser context. +- Invocation is still largely manual. A user types `/record-skill`. Some coding agents today do attempt auto-invocation — picking up "this looks like a record-skill moment" from context and firing the skill without an explicit slash command — and the results are mixed (sometimes spot-on, often wrong skill / wrong moment). That those attempts exist at all suggests the long-run direction: the slash-command entry point is a holdover from CLI ergonomics, and the discovery layer will eventually move inside the agent itself. +- The artifact / tool / agent boundary is blurry. Right now we say "skills are markdown procedures", "tools are function calls", and "agents are personas that own a workflow". These three categories already overlap. Treating them as three distinct distributable kinds is a packaging decision, not a fundamental one. + +Skills as they exist in Agentic Beacon are deliberately the **simplest thing that captures and distributes a repeatable procedure**. That's worth doing today. But I'd expect the shape of "skill" to dissolve as the substrate matures. + +--- + +## Workflow Skills Probably Belong to Agents + +Within the spectrum above, the workflow end is where this intermediate-form pressure shows up most clearly. + +A pure cognitive skill is just instructions — there's nothing for an agent to own; you load the instructions into context and the LLM follows them. A pure action skill is just a tool — you wrap an API and let the LLM call it. + +A workflow skill is different. It implies *state*, *decision points*, *long-running execution across multiple turns*. That looks much more like what an **agent** does than like what a skill does: + +- An agent has a name, a persona, a scoped responsibility, and the ability to spawn sub-agents. +- An agent is a more natural home for "this multi-step procedure" than a `SKILL.md` that the parent agent has to remember to follow. +- When the workflow is non-trivial, packaging it as an agent (with its own tools, its own context) gives you isolation and composability that a skill loaded into the parent context doesn't. + +In Agentic Beacon, both skills and agents are distributable warehouse artifacts. My current rule of thumb: + +| Shape | Better as | +|---|---| +| "Always think this way when reviewing code" | **Skill** (cognitive) | +| "Call this API; here's the contract" | **Skill** (action) | +| "Investigate the failure, decide the fix, write the test, open the PR" | **Agent** | + +Where the line falls is a design call, not a mechanical rule. But if you find yourself writing a `SKILL.md` with multiple phases, sub-loops, and "if X then Y else Z" branches, it's a signal you're really describing an agent. + +--- + +## What Skills Are Good At, Today + +Setting aside the future, here is the present case for distributing procedures as skills in a warehouse: + +- **Cognitive skills** — code review checklists, naming conventions, structured-output templates. These genuinely are "instructions to be followed", they read well as markdown, and they distribute cleanly. +- **Lightly action-flavoured skills** — wrappers around a small, well-defined external tool with a few decision points (the bundled `record-knowledge` skill is roughly this shape — prompt for inputs, write a file at a deterministic path). +- **Low-state procedures** — the steps are linear, the agent doesn't need to remember much between them, and the right behaviour can be expressed in prose. + +For everything heavier, prefer an agent. For everything lighter than this, you may not need a skill at all — a paragraph in a context file may do. + +--- + +## See Also + +- [Bundled Skills](../concepts/bundled-skills.md) — operational reference for the `record-*` and `contribute-warehouse` skills shipped with `abc` +- [Creating Skills](../guides/creating-skills.md) — how to author and distribute a warehouse skill today +- [Artifact Types](../concepts/artifact-types.md) — skills vs. agents vs. contexts vs. knowledge in the wider artifact matrix diff --git a/site-docs/guides/adopting-artifacts.md b/site-docs/guides/adopting-artifacts.md new file mode 100644 index 0000000..17efb9f --- /dev/null +++ b/site-docs/guides/adopting-artifacts.md @@ -0,0 +1,143 @@ +# Adopting Artifacts + +There are two ways to get warehouse artifacts wired into your project: an **interactive** path through the TUI, and a **declarative** path through `beacon.yaml`. Both end in the same result — symlinks under `.agentic-beacon/artifacts/` and wiring into your AI tool's config — but they're optimised for different moments. + +| Path | Command | When to reach for it | +|---|---|---| +| **Interactive** | `abc adopt` | First-time setup, discovering new artifacts a teammate added, when you'd rather pick from a list than write YAML | +| **Declarative** | `abc sync` | After editing `beacon.yaml` directly, in CI, scripts, or any non-interactive workflow | + +The two paths overlap deliberately: `abc adopt` runs `abc sync` automatically after a successful commit, and `abc sync` notifies you when new pending artifacts are available so you can switch back to the TUI. + +--- + +## Interactive: `abc adopt` + +The TUI browses the warehouse, shows artifacts not yet in your `beacon.yaml`, and lets you select what to wire in. + +```bash +abc adopt +``` + +![abc adopt TUI](../assets/adopt-tui.png) + +### Keyboard shortcuts + +| Key | Action | +|---|---| +| `↑` / `↓` | Navigate the list | +| `Space` | Toggle selection (select / deselect) | +| `Enter` | Confirm selections and write to `beacon.yaml` | +| `a` | Select all visible artifacts | +| `n` | Deselect all visible artifacts | +| `t` | Toggle show-all (include already-adopted artifacts) | +| `Esc` / `q` | Cancel without making changes | + +### What happens on confirm + +When you press `Enter`, `abc adopt` runs a single session-atomic commit: + +1. Selected artifacts (contexts, skills, agents) are appended to `.agentic-beacon/beacon.yaml`. +2. Matching entries are removed from `.agentic-beacon/pending.yaml`. +3. A full sync runs — symlinks are created under `.agentic-beacon/artifacts/`. +4. Contexts are wired into your agent config (`CLAUDE.md` / `opencode.json`). +5. Skills are installed into each detected tool's directories. +6. Agents are wired into project-local `.claude/agents/` and `.opencode/agents/`. + +If any step fails, the manifests are rolled back to their pre-commit state. See [Pending & Adoption](../concepts/pending-and-adoption.md) for the storage model behind this. + +### Flags + +```bash +# Preview what's available without opening the TUI +abc adopt --dry-run +``` + +To view your currently-adopted artifacts (or remove some), press `t` inside the TUI to toggle the show-all view. There is no `--all` CLI flag — the toggle is in-TUI only. + +> Editing `beacon.yaml` by hand? The auto-sync described above only fires from the TUI confirm path. Run `abc sync` yourself afterward. + +--- + +## Declarative: `abc sync` + +`abc sync` reads `.agentic-beacon/beacon.yaml`, resolves dependencies, and installs everything. This is the path you take after editing `beacon.yaml` directly, or in any non-interactive context (CI, scripts). + +```bash +abc sync +``` + +Output example: + +``` +✓ Sync complete + Created: 5 symlinks + Up to date: 10 symlinks + ✓ Wired 2 context(s) into CLAUDE.md + ✓ Installed 1 skill(s) (code-review) +``` + +### What sync does + +`abc sync` runs a multi-phase pipeline: + +1. **Read `beacon.yaml`** — load declared contexts, skills, and agents. +2. **Resolve dependencies** — read `requires:` frontmatter from each skill's `SKILL.md` and agent dependencies from `agents/agents.yaml` to compute transitive dependencies. +3. **Auto-derive knowledge** — scan all adopted contexts and skills for markdown links to `knowledge/` paths. +4. **Create symlinks** — create per-file symlinks under `.agentic-beacon/artifacts/` pointing into the warehouse. +5. **Wire artifacts** — add context references to `CLAUDE.md`/`opencode.json`, install skills into tool directories, wire agents into project-local `.claude/agents/` and `.opencode/agents/`. +6. **Prune orphans** — remove symlinks for artifacts no longer referenced. + +| Artifact | Destination | Wiring | +|---|---|---| +| **Contexts** | `.agentic-beacon/artifacts/contexts/` (symlinks) | Added to `CLAUDE.md` or `opencode.json` | +| **Skills** | `.agentic-beacon/artifacts/skills/` (symlinks) + tool dirs | Installed as slash commands | +| **Knowledge** | `.agentic-beacon/artifacts/knowledge/` (symlinks) | Auto-derived from markdown links; no wiring needed | +| **Agents** | `.agentic-beacon/artifacts/agents/` (symlinks) + `.claude/agents/` + `.opencode/agents/` | Wired per-project; declared in `beacon.yaml` | + +### Sync flags + +| Flag | Effect | +|---|---| +| `--dry-run` | Show what would be synced without making changes | +| `--force` | Force-overwrite all conflicting files, ignoring local modifications | +| `--verbose` | Print per-file output for each artifact processed | +| `--skip-git-check` | Bypass warehouse git state checks (uncommitted changes, behind remote, non-main branch) — useful in CI | +| `--contribute-local` | Non-interactive: contribute all locally modified files back to the warehouse during sync | +| `--discard-local` | Non-interactive: discard all locally modified files and replace them with fresh symlinks | + +Flags compose: `abc sync --force --dry-run` previews a full reset. + +--- + +## The Discovery Loop + +When a teammate pushes new artifacts to the warehouse, `abc sync` picks up on it: + +``` +✓ Sync complete + Created: 0 symlinks + Up to date: 10 symlinks + +1 new artifact(s) available — run abc adopt to review +``` + +The two paths chain naturally: `abc sync` after a `git pull` notices the new pendings; `abc adopt` is how you actually pull them in. + +--- + +## Resetting and Cleaning Up + +```bash +abc reset # force-overwrite all synced artifacts from the warehouse, discarding local mods +abc clean # remove .agentic-beacon/artifacts/ entirely (re-create with abc sync) +``` + +--- + +## See Also + +- [Pending & Adoption](../concepts/pending-and-adoption.md) — the `pending.yaml` storage model and atomic-commit guarantees +- [beacon.yaml Reference](../reference/beacon-yaml.md) — direct editing reference +- [Day-to-Day Workflow](day-to-day-workflow.md) — how adopt + sync fit into the recurring loop +- [CLI Reference](../reference/cli.md) — full flag documentation diff --git a/site-docs/guides/contributing-back.md b/site-docs/guides/contributing-back.md index 0af32b8..82cb9c3 100644 --- a/site-docs/guides/contributing-back.md +++ b/site-docs/guides/contributing-back.md @@ -1,110 +1,100 @@ # Contributing Back to the Warehouse -Agentic Beacon uses a **symlink model**: `abc sync` creates symlinks from `.agentic-beacon/artifacts/` into your warehouse clone. When an agent session improves an artifact, those changes are already in the warehouse working tree — use `abc warehouse contribute` to commit and share them. +Contributing back has two phases: ---- +1. **Author the artifact** — create or improve a skill, knowledge file, context, or agent in the warehouse working tree. +2. **Commit and push** — share it with teammates via the bundled `/contribute-warehouse` skill (or the lower-level CLI). -## The Workflow +This page covers the commit-and-push half. The sub-pages cover authoring each artifact type: -### 1. Review what changed +- [Creating Skills](creating-skills.md) — via `/record-skill` or by asking an agent to write one +- [Creating Knowledge and Contexts](creating-knowledge-and-contexts.md) — via `/record-knowledge` or direct edit +- [Creating an Agent](creating-agents.md) — direct edit (no bundled skill) -```bash -abc warehouse status -``` +> Agentic Beacon uses a **symlink model**: `abc sync` creates symlinks from `.agentic-beacon/artifacts/` into your warehouse clone. When you author or improve an artifact through any of the paths above, the change is already in the warehouse working tree — you just need to commit and push it. -Shows modifications to warehouse files tracked by `beacon.yaml`: +--- -``` -Modified files: - modified knowledge/python/type-hints.md - modified skills/code-review/SKILL.md -``` +## The Recommended Path: `/contribute-warehouse` -Inspect a specific file: +From an OpenCode or Claude Code session inside a connected project: -```bash -abc warehouse status knowledge/python/type-hints.md ``` - -Shows a line-by-line diff. - -### 2. Commit changes - -Commit all modified files with a message: - -```bash -abc warehouse contribute -m "Improve type hints guide with Python 3.12+ patterns" +/contribute-warehouse ``` -Push the commit immediately: +The skill walks you through the contribution interactively: -```bash -abc warehouse contribute -m "Fix typo in error handling guide" --push -``` - -### 3. What happens automatically +1. **Resolves the warehouse** from `.agentic-beacon/config.toml`. +2. **Runs `abc warehouse lint`** as a hard gate — aborts if the warehouse has any integrity errors. +3. **Summarises dirty paths** and asks you which to include and which to leave for later. +4. **Scans `knowledge/` files for semantic duplicates** so you don't ship the same lesson twice under different names. +5. **Splits the included files into cohesive commits** with drafted Conventional Commits messages. +6. **Pushes all commits atomically** at the end — one push, all-or-nothing. -`abc warehouse contribute`: +This is the path you should reach for almost every time. It catches problems the raw CLI doesn't, and it produces a tidy commit history without you having to think about it. -1. Stages all files tracked by `beacon.yaml` that have uncommitted changes -2. Creates a commit with your message -3. If `--push` is used, pushes the commit to the remote +> For the full design and flag reference, see [`contribute-warehouse` Skill Reference](../reference/contribute-warehouse.md). -If there are no changes to commit, it prints a message and exits cleanly. +--- -### 4. Teammates pick it up +## The Lower-Level Primitive: `abc warehouse contribute` -Once your changes are in the warehouse: +The raw `abc warehouse contribute` CLI is what the skill wraps. You can use it directly for one-off commits that don't need the full guided flow: ```bash -cd ~/team-warehouse && git pull -cd my-project && abc sync +abc warehouse status # review dirty files +abc warehouse contribute -m "" --paths # commit specific files +abc warehouse contribute -m "" --push # commit + push in one step ``` +The `--paths` option is repeatable — pass it once per file. Omitting it stages every dirty tracked file in the warehouse, which is rarely what you want when you've been editing across several artifacts. + +> **Heads up:** raw `abc warehouse contribute` is currently less reliable than the bundled skill in some environments. If it misbehaves, reach for `/contribute-warehouse` instead. + --- -## Manual Git Workflow +## Manual Git, If You Prefer -Since artifacts are symlinks into the warehouse clone, you can also use plain git commands: +Because artifacts are symlinks into the warehouse clone, the warehouse working tree is always up to date. You can also just use plain git: ```bash -# In the warehouse clone cd ~/team-warehouse git add knowledge/python/type-hints.md git commit -m "docs: improve type hints guide" git push ``` -The warehouse working tree is always up to date because symlinks write directly to it. +This bypasses the lint gate and the cohesion split — fine for trivial edits, but for anything substantive, prefer the bundled skill. --- -## How the Symlink Model Changes Things +## Teammates Pick It Up + +Once the commit is on the remote, teammates pull and resync: -| Old copy-based model (removed) | Current symlink model | -|---|---| -| Artifacts copied to `.agentic-beacon/artifacts/` | Artifacts are symlinks into the warehouse | -| `abc delta` compared copies against warehouse | `abc warehouse status` shows warehouse working tree changes | -| `abc contribute` copied files back to warehouse | `abc warehouse contribute` commits changes already in the warehouse | -| Local edits were isolated per project | Local edits go directly to the warehouse clone | +```bash +cd ~/team-warehouse && git pull +cd my-project && abc sync +``` -Editing a symlinked artifact file IS editing the warehouse working tree. The edit is visible to all projects that use the same artifact on the same machine. +Their existing symlinks pick up the new content immediately; `abc sync` only needs to run if `beacon.yaml` references new paths or if symlinks have drifted. --- ## Contribution Checklist -Before committing to the warehouse: +Whichever path you use, before you push: -- [ ] Tested the artifact in a real project — agent actually used it correctly -- [ ] Content is generic — no project-specific paths, credentials, or names -- [ ] No broken references or links -- [ ] Commit message describes **why** the change helps, not just what changed +- [ ] Tested the artifact in a real session — the agent actually used it correctly. +- [ ] Content is generic — no project-specific paths, credentials, or names. +- [ ] No broken references or links. +- [ ] Commit message describes **why** the change helps, not just what changed. --- -## Next Steps +## See Also -- **[Day-to-Day Workflow](day-to-day-workflow.md)** — how contributing fits into the loop -- **[Creating Skills](creating-skills.md)** — writing effective skill definitions before contributing -- **[Command Reference](../reference/cli.md)** — full `abc warehouse contribute` options +- [`contribute-warehouse` Skill Reference](../reference/contribute-warehouse.md) — full flow, flags, and design notes +- [Day-to-Day Workflow](day-to-day-workflow.md) — how contributing fits into the broader loop +- [CLI Reference](../reference/cli.md) — every `abc warehouse contribute` option diff --git a/site-docs/guides/creating-agents.md b/site-docs/guides/creating-agents.md new file mode 100644 index 0000000..30cc697 --- /dev/null +++ b/site-docs/guides/creating-agents.md @@ -0,0 +1,147 @@ +# Creating an Agent + +An **agent** is a distinct AI persona with its own scoped responsibility, instructions, and (optionally) a set of skills it can invoke. In Agentic Beacon, agents live as individual markdown files under `/agents/` and are registered in `/agents/agents.yaml`. + +There is **no bundled skill** for authoring an agent — you write the markdown directly. Either by hand or by asking your current agent to author one for you. Both are fine. + +> Why an agent instead of a skill? Skills are best for cognitive or low-state procedures (a code review checklist, a templated transformation). Agents are better when the work has multiple phases, decision points, or wants its own context and tool surface. See [Skills design — Workflow Skills Probably Belong to Agents](../design/skills.md#workflow-skills-probably-belong-to-agents) for the line of reasoning. + +--- + +## File Layout + +``` +agents/ +├── README.md +├── agents.yaml # Required: agent dependency manifest +├── code-reviewer.md # An agent +└── spec-planner.md # Another agent +``` + +Each `.md` must have a matching top-level key in `agents.yaml`. Both directions are enforced by `abc warehouse lint`. + +--- + +## Authoring the Agent File + +### Frontmatter + +```markdown +--- +name: code-reviewer +description: Reviews PRs against team standards. Use for end-to-end PR review before merge. +--- +``` + +| Field | Required | Notes | +|---|---|---| +| `name` | yes | Becomes the agent's invocation name | +| `description` | yes | One sentence; tool surfaces use this to pick the right agent for a task | + +> **Important:** do not put `requires:` in agent frontmatter. Skill dependencies belong in `agents.yaml` (see below). `abc warehouse lint` hard-errors if `requires:` appears here. + +### Body + +After the frontmatter, write the agent's instructions. Treat it the way you'd write a system prompt: scope, persona, tools, expected behaviour. Be explicit about decision points and what the agent should escalate. + +```markdown +--- +name: code-reviewer +description: Reviews PRs against team standards. Use for end-to-end PR review before merge. +--- + +# Code Reviewer + +You review pull requests for correctness, style, test coverage, and security. + +## Scope +- One PR at a time, end-to-end. +- You produce a structured review with three sections: Blockers, Suggestions, Notes. +- You do not merge or close PRs — leave that to the human. + +## Process +1. Read all changed files in full before commenting. +2. ... + +## Tools You'll Use +- `/code-review` skill for the per-file checklist +- The shared `python-standards.md` context for language conventions +``` + +--- + +## Registering the Agent in `agents.yaml` + +Every agent file needs an entry in `agents/agents.yaml` — even if it has no skill dependencies. + +```yaml +# agents/agents.yaml + +code-reviewer: + skills: + - code-review + - generate-tests + +spec-planner: + skills: + - opsx-propose + - opsx-enhance + +pipeline-developer: + skills: [] # an agent with no skill dependencies still needs an entry +``` + +Rules: + +- Top-level key must equal the stem of an `agents/.md` file. +- `skills:` is a list of skill directory names (no `skills/` prefix, no trailing `/`). +- Every listed skill must exist in the warehouse and must be adopted by any project that uses this agent — `abc sync` errors otherwise. +- `contexts:` is **not** allowed at the agent entry level. + +--- + +## Declaring the Agent in a Project's `beacon.yaml` + +Agents are **project-scoped**. Each project that wants an agent declares it explicitly: + +```yaml +artifacts: + agents: + - agents/code-reviewer.md +``` + +After `abc sync` (or `abc adopt`), the agent is wired into the project's tool directories: + +- Claude Code: `.claude/agents/code-reviewer.md` (symlink) +- OpenCode: `.opencode/agents/code-reviewer.md` (symlink) + +Both directories are gitignored — they're per-machine state. The shared source of truth is `beacon.yaml.artifacts.agents`. + +> See [Artifact Types — Agents](../concepts/artifact-types.md) for the rationale behind per-project agent wiring. + +--- + +## Two Authoring Paths + +Just like skills, you can take either path: + +**Direct edit / by hand:** the simplest path for a small agent. Write the markdown, register in `agents.yaml`, add to `beacon.yaml`, sync. + +**Ask your agent to write one:** describe the responsibility and tool surface in conversation. Your agent inspects existing agents in `/agents/` for shape, writes the new `.md`, updates `agents.yaml`, and (if you ask) appends a pending entry so `abc adopt` can wire it for you. + +The second path is what you reach for when designing the agent's behaviour is the harder part of the work, and you want to iterate on the prose in conversation. + +--- + +## When You're Done + +Commit the new agent through [`/contribute-warehouse`](contributing-back.md) like any other warehouse change. The skill's lint gate runs `abc warehouse lint`, which checks both that the agent file has the required frontmatter and that the bidirectional `agents.yaml` correspondence holds. + +--- + +## See Also + +- [Creating Skills](creating-skills.md) — the procedural artifact most often paired with an agent +- [Creating Knowledge and Contexts](creating-knowledge-and-contexts.md) — what an agent reads on session start +- [Skills design — Workflow Skills Probably Belong to Agents](../design/skills.md#workflow-skills-probably-belong-to-agents) — when to reach for an agent over a skill +- [Artifact Types](../concepts/artifact-types.md) — how agents fit in the wider artifact matrix diff --git a/site-docs/guides/creating-knowledge-and-contexts.md b/site-docs/guides/creating-knowledge-and-contexts.md new file mode 100644 index 0000000..f59c34e --- /dev/null +++ b/site-docs/guides/creating-knowledge-and-contexts.md @@ -0,0 +1,147 @@ +# Creating Knowledge and Contexts + +Knowledge and contexts are the two tool-agnostic artifact types — plain markdown that any agent can read. They're related: **a context is, in effect, a curated collection of knowledge**. The distinction is about how the content is packaged and loaded, not about what kind of content it is. + +- **Contexts** are the boot-time payload — what the agent loads on session start. A context can hold short rules and patterns inline, AND point at deeper material via links. The inline content is loaded immediately; the linked content is loaded only when the agent follows the link. +- **Knowledge files** are atomic units — one decision, one lesson, one fact — that can be referenced from one or more contexts (or from other knowledge files). They exist as standalone files so the same piece of knowledge can be composed into multiple contexts and so it can be left out of the boot-time payload when it's not needed every session. + +Progressive disclosure — pulling deep detail in only when the agent needs it — is an **optimisation pattern**, not the definition of either artifact. Not all knowledge is hidden at session start; some of it lives inline in a context, on purpose. + +This guide covers authoring each. + +--- + +## Knowledge + +The `/record-knowledge` [bundled skill](../concepts/bundled-skills.md) is the structured path. It prompts you for a topic, type (decision / lesson / fact), and content, then writes the file at the correct warehouse path. + +From an OpenCode or Claude Code session: + +``` +/record-knowledge +``` + +Or, if you'd rather drive it yourself: just tell the agent *"record this as a lesson under `python-standards`"* and let it write the file directly. + +### Where Knowledge Files Live + +The warehouse-lint rule is: `knowledge/[/]/.md` where `` is one of `decisions/`, `lessons/`, or `facts/`. + +``` +knowledge/ +├── python-standards/ +│ ├── decisions/ +│ │ └── pydantic-vs-dataclass.md +│ ├── lessons/ +│ │ └── python-type-annotations-use-primitive-types.md +│ └── facts/ +└── cicd/ + └── lessons/ + └── github-runner-setup-procedure.md +``` + +The `/` prefix is optional and free-form — you design the topic taxonomy that suits your warehouse. The three leaf taxonomies (`decisions`, `lessons`, `facts`) are enforced. + +### What Each Type Is For + +| Type | Captures | Typical shape | +|---|---|---| +| **decisions** | A choice that was made and why | Problem → options → decision → rationale | +| **lessons** | A pattern where agents commonly fail or get distracted | Agent failure mode → correct pattern → guardrail | +| **facts** | An established piece of technical information | Statement → context → usage notes | + +### Knowledge Is Not Declared in `beacon.yaml` + +You don't add knowledge to `beacon.yaml`. `abc sync` scans every adopted context and skill for markdown links into `knowledge/`, resolves them against the warehouse, and creates symlinks transitively. To make a new knowledge file appear in a project: add a link to it from a context or skill that the project already adopts. + +If no context links to your new knowledge file yet, the file is fine in the warehouse — it just won't appear in any project's `.agentic-beacon/artifacts/knowledge/` until something points at it. + +--- + +## Contexts + +Contexts have **no bundled skill**. You author them directly — either by hand or by asking an agent to write one in the warehouse. + +``` +contexts/ +├── python-standards.md +├── cicd-flow.md +└── teams/ + └── backend.md +``` + +Naming and subdirectory layout are entirely free — `abc warehouse lint` doesn't enforce a shape inside `contexts/`. Use whatever organisation suits your warehouse. + +### What Goes in a Context + +A context is a **scannable** boot-time document. Each entry typically: + +1. States the rule or pattern in one or two sentences. +2. Links to deeper knowledge for the rationale or details. + +Don't put long explanations in a context — push that into a knowledge file and link to it. + +### Proactive vs. Reactive Pointers + +Two link styles are used by convention, and they signal different agent behaviour: + +| Style | Meaning | Use for | +|---|---|---| +| `**Read:** [link](path)` | Agent should read this immediately | Rules that affect every file the agent touches | +| `**See:** [link](path)` | Agent should read only when relevant | Troubleshooting, edge-case detail, reference material | + +Example from `python-standards.md`: + +```markdown +## Type Annotations + +**Rule:** Use unquoted primitive types. Never import from `typing` for built-in generics. + +**Read:** [Primitive types](../knowledge/python-standards/lessons/python-type-annotations-use-primitive-types.md) +``` + +The distinction is conventional — the agent treats both as readable links, but a context-savvy agent uses the verb to prioritise. + +### Declaring a Context + +Once the file exists in the warehouse, add it to `beacon.yaml`: + +```yaml +artifacts: + contexts: + - contexts/python-standards.md + - contexts/cicd-flow.md +``` + +Then `abc sync` symlinks it into `.agentic-beacon/artifacts/contexts/` and wires it into your tool's config (`CLAUDE.md`, `opencode.json`). + +You can also let `abc adopt` handle the wiring — write the context, append a pending entry, accept it in the TUI. + +--- + +## When to Extract a Knowledge File vs. Keep It Inline in a Context + +The decision isn't *"is this for every session or only sometimes?"* — a context can already hold both inline rules and pointers. The useful question is whether a piece of content should be its **own file**. + +Extract it as a knowledge file when: + +- **It's referenced from more than one context.** A single source of truth that multiple contexts can link to. +- **It's atomic and complete on its own** — one decision, one lesson, one fact, with its own rationale. The kind of thing you'd link to from a PR description. +- **It's heavy enough that loading it inline at boot is wasteful** — long examples, lots of code, troubleshooting trees. Push it into a knowledge file and link via `**See:**` so the agent only pulls it when relevant. + +Keep it inline in the context when: + +- **It's short and the agent needs it on every session** — a one-line naming rule, a quick "always do X" reminder. Extracting it forces an extra link-follow for no gain. +- **It's tightly bound to the surrounding rules** in the context and doesn't make sense outside that grouping. +- **You don't yet know if it'll be reused.** Start inline; extract later if a second context wants it. + +The progressive-disclosure pattern (`**Read:**` for must-load, `**See:**` for load-when-needed) only kicks in *once you've extracted*. Before that, content lives in the context and is loaded with it. See the [Philosophy](../design/philosophy.md#two-tier-information-model) page for the design rationale behind the split. + +--- + +## See Also + +- [Creating Skills](creating-skills.md) — packaged workflows, the procedural counterpart to contexts and knowledge +- [Creating an Agent](creating-agents.md) — when you need a distinct agent persona rather than just instructions +- [Bundled Skills](../concepts/bundled-skills.md) — operational reference for `/record-knowledge` +- [Philosophy](../design/philosophy.md) — why the two-tier (context + knowledge) model exists diff --git a/site-docs/guides/creating-skills.md b/site-docs/guides/creating-skills.md index 7c3ce46..1794d05 100644 --- a/site-docs/guides/creating-skills.md +++ b/site-docs/guides/creating-skills.md @@ -1,18 +1,48 @@ # Creating Skills -> This guide covers user-authored **warehouse skills**. For the `record-*` skills shipped with `abc`, see [Bundled Skills](../concepts/bundled-skills.md). +A skill is a packaged, reusable workflow that an agent can invoke as a slash command. In Agentic Beacon, a skill is a directory under `/skills//` containing a `SKILL.md` entry point (with required frontmatter) plus optional supporting files. -Skills are reusable agent workflows stored in your warehouse. When a project syncs a skill, the agent can invoke it as a slash command to follow a consistent, repeatable process. +There are two equally valid ways to author one. Pick the path that fits the situation. -## What Is a Skill? +--- + +## Path 1 — Use `/record-skill` + +The `/record-skill` [bundled skill](../concepts/bundled-skills.md) is the structured path. It prompts you for the skill name, description, and initial process steps, then writes a correctly-shaped `SKILL.md` into the warehouse and appends a `pending.yaml` entry so the new skill is picked up by `abc adopt`. + +From an OpenCode or Claude Code session in a connected project: + +``` +/record-skill +``` + +Use this when: -A skill is a packaged capability — a modular unit of work defined by the outcome it enables. Skills range from pure reasoning instructions (cognitive) to multi-step workflows combining prompts and tool calls. +- You already know roughly what the skill should do — the conversation is about capturing it, not designing it. +- You want the frontmatter and directory layout to come out correct without thinking about it. +- You want the wiring half (`pending.yaml` → `abc adopt`) handled for you. -In Agentic Beacon, a skill is a directory containing a `SKILL.md` entry point plus optional supporting files. The agent reads `SKILL.md` when the skill is invoked. +After the skill is written, run `abc adopt` to wire it into the project, then commit via [`/contribute-warehouse`](contributing-back.md) when you're ready to share it. --- -## Directory Structure +## Path 2 — Ask Your Agent to Author One + +You can also just tell your agent: *"Write a `code-review` skill that does X, Y, Z. Put it in the warehouse."* The agent reads the existing skills in `/skills/` for shape, writes a new `SKILL.md` with frontmatter, and saves it. + +Use this when: + +- The skill needs design work — the conversation is about figuring out what the skill should do, not just transcribing it. +- You want to iterate on the SKILL.md text directly as you go. +- You want supporting files (`templates/`, `examples/`, `scripts/`) authored alongside the SKILL.md in one go. + +This path skips `pending.yaml` — you'll need to add the skill to `beacon.yaml` yourself (or via `abc adopt` after manually appending a pending entry). It trades a small amount of bookkeeping for full creative control. + +--- + +## Either Way, the Output Looks the Same + +A skill on disk: ``` skills/ @@ -23,7 +53,7 @@ skills/ └── example-pr.md # Optional — examples for the agent ``` -The skill name is the directory name (`code-review`). In `beacon.yaml`: +The skill name is the directory name. In `beacon.yaml`: ```yaml artifacts: @@ -33,9 +63,9 @@ artifacts: --- -## Writing SKILL.md +## SKILL.md Anatomy -`SKILL.md` is the entry point the agent reads. Write it for an AI agent to follow, not for casual human reading — be explicit about steps, inputs, and expected output. +`SKILL.md` is the entry point the agent reads when the skill is invoked. Write it for an AI agent to follow, not for casual human reading — be explicit about steps, inputs, and expected output. ### Minimal Template @@ -64,118 +94,18 @@ Describe the trigger — when should a developer invoke this skill? What should the agent produce or report back? ``` -### Full Template - -```markdown ---- -name: code-review -description: Perform a structured code review of a PR or diff, following team standards. -requires: - contexts: [python-standards] ---- - -# Skill: Code Review - -## Purpose -Perform a structured code review of a PR or diff, following team standards. - -## When to Use -Invoke when: -- Reviewing a PR before merging -- Reviewing a specific file or function -- Auditing a new contributor's code - -## Inputs -- The code to review (file paths, diff, or PR description) -- Language context from synced knowledge artifacts - -## Process -1. Read all changed files in full before commenting -2. Check correctness — does it do what it claims? -3. Check style — does it follow team conventions? -4. Check tests — are all paths covered? -5. Check for security issues (auth, input validation, secrets) -6. Summarize with three sections: - - Must fix (blockers) - - Should fix (improvements) - - Nice to have (suggestions) - -## Output -A structured review with: -- **Blockers** — must be resolved before merge -- **Suggestions** — recommended improvements -- **Notes** — observations, questions, praise -``` - ---- - -## Examples: Common Skill Types - -### Generate Unit Tests - -````markdown ---- -name: generate-tests -description: Generate comprehensive unit tests for a given Python function or class. -requires: - contexts: [python-standards] ---- - -# Skill: Generate Unit Tests - -## Purpose -Generate comprehensive unit tests for a given Python function or class. - -## Process -1. Read the function/class signature and docstring -2. Identify the happy path (expected inputs and outputs) -3. Identify edge cases (empty, null, boundary values) -4. Identify error conditions (invalid input, exceptions) -5. Write one test per case using pytest -6. Name tests descriptively: `test__` - -## Output -A complete test file ready to run with `pytest`. -```` - -### Write PR Description - -````markdown ---- -name: write-pr-description -description: Generate a clear, structured PR description from a diff or set of commits. -requires: - contexts: [] ---- - -# Skill: Write PR Description - -## Purpose -Generate a clear, structured PR description from a diff or set of commits. - -## Process -1. Read the diff or list of commits -2. Summarize what changed (not how — that's in the code) -3. Explain why the change was made -4. List any breaking changes or side effects -5. Note testing performed - -## Output Format -``` -## Summary -<1-3 sentences describing the change> - -## Changes -- +### Frontmatter Fields -## Testing -- -``` -```` +| Field | Required | Notes | +|---|---|---| +| `name` | yes | Slash-command name agents will use to invoke | +| `description` | yes | One-sentence summary, used in skill catalogs | +| `requires.contexts` | no | List of context names (no `contexts/` prefix, no `.md`) the skill depends on; `abc sync` errors if they're not also adopted | +| `requires.skills` | no | List of other skill directory names this skill calls into | --- -## Adding Supporting Files +## Supporting Files For complex skills, include reference files the agent reads during execution: @@ -190,7 +120,7 @@ skills/ └── bad-api.md # Common mistakes ``` -Reference them explicitly in `SKILL.md`: +Reference them explicitly inside `SKILL.md`: ```markdown ## References @@ -199,87 +129,22 @@ Reference them explicitly in `SKILL.md`: - See `examples/` for before/after examples ``` ---- - -## Adding a Skill to Your Warehouse - -```bash -# 1. Create the skill directory -cd ~/team-warehouse -mkdir -p skills/generate-tests - -# 2. Write SKILL.md -cat > skills/generate-tests/SKILL.md << 'EOF' ---- -name: generate-tests -description: Generate pytest unit tests for a given function or class. -requires: - contexts: [python-standards] ---- - -# Skill: Generate Unit Tests - -## Purpose -Generate pytest unit tests for a given function or class. - -## Process -1. Identify function signature and return type -2. Determine test cases: happy path, edge cases, errors -3. Write tests using pytest, one test per case -4. Name each test: test__ - -## Output -A complete pytest test file ready to run. -EOF - -# 3. Commit to warehouse -git add skills/generate-tests/ -git commit -m "feat: add generate-tests skill" -git push - -# 4. Declare in your project -# Edit .agentic-beacon/beacon.yaml: -# artifacts: -# skills: -# - skills/generate-tests/ - -# 5. Sync -abc sync -``` - ---- - -## Invoking a Skill - -After syncing, the skill is available as a slash command: - -``` -/generate-tests src/services/user_service.py -/code-review src/api/routes.py -``` +For skills that need **deterministic execution** (file I/O, YAML manipulation, git operations), add `scripts/` containing standalone Python scripts. See the [Skills design page](../design/skills.md) for the thin-skill / fat-tools rationale, and the bundled `contribute-warehouse` skill for an in-repo example. --- ## Best Practices -**Keep skills focused.** One skill, one job. A skill that does code review *and* generates tests is harder to invoke and maintain. - -**Write for the agent, not the human.** Be explicit about steps, inputs, and expected output format. The agent follows your instructions literally. - -**Test with real projects.** Before distributing to the team, sync the skill to a project and invoke it on real code. Refine based on output quality. - -**Include examples.** Examples in `examples/` improve agent output quality. A "good example" shows what the agent should produce; a "bad example" with annotations shows what to avoid. - -**Version in the warehouse.** When a skill changes significantly: - -```bash -git commit -m "feat(skills): add security checks to code-review skill" -``` +- **Keep skills focused.** One skill, one job. A skill that does code review *and* generates tests is harder to invoke and maintain. +- **Write for the agent, not the human.** Be explicit about steps, inputs, and expected output format. The agent follows your instructions literally. +- **Test with real projects.** Before distributing, sync the skill and invoke it on real code. Refine based on output quality. +- **If it's heavily multi-phase with state, consider an agent instead.** Workflow-heavy skills often work better as [agents](creating-agents.md). See [Skills design](../design/skills.md#workflow-skills-probably-belong-to-agents). --- -## Next Steps +## See Also -- **[Syncing Artifacts](syncing.md)** — install skills into your project -- **[Warehouse Creation](warehouse-creation.md)** — organizing skills in the warehouse -- **[Contributing Back](contributing-back.md)** — share skill improvements with the team +- [Bundled Skills](../concepts/bundled-skills.md) — operational reference for the `record-*` and `contribute-warehouse` skills +- [Skills design](../design/skills.md) — opinion on what a skill is and what it isn't +- [Creating Knowledge and Contexts](creating-knowledge-and-contexts.md) — the other tool-agnostic artifacts +- [Creating an Agent](creating-agents.md) — when a workflow is too heavy for a skill diff --git a/site-docs/guides/interactive-adoption.md b/site-docs/guides/interactive-adoption.md deleted file mode 100644 index 0fd7e73..0000000 --- a/site-docs/guides/interactive-adoption.md +++ /dev/null @@ -1,106 +0,0 @@ -# Interactive Adoption - -`abc adopt` opens a terminal UI to browse your warehouse and select which artifacts to pull into your project. It's the fastest way to populate `beacon.yaml` without manually writing YAML paths. - -## When to Use It - -- **First setup** — when connecting a project to a warehouse for the first time -- **Discovering new artifacts** — after a teammate adds artifacts to the warehouse -- **Reviewing options** — to see what's available before committing to a sync - ---- - -## Starting the TUI - -```bash -abc adopt -``` - -The TUI opens in your terminal, showing all warehouse artifacts grouped by type that are not yet in your `beacon.yaml`. - -![abc adopt TUI](../assets/adopt-tui.png) - ---- - -## Keyboard Shortcuts - -| Key | Action | -|-----|--------| -| `↑` / `↓` | Navigate the list | -| `Space` | Toggle selection (select / deselect) | -| `Enter` | Confirm selections and write to `beacon.yaml` | -| `a` | Select all visible artifacts | -| `n` | Deselect all visible artifacts | -| `t` | Toggle show-all (include already-adopted artifacts) | -| `Esc` / `q` | Cancel without making changes | - ---- - -## What Happens After You Confirm - -When you press `Enter`, `abc adopt` runs a single session-atomic commit: - -1. Selected artifacts (contexts, skills, and agents) are appended to `.agentic-beacon/beacon.yaml` -2. Matching entries are removed from `.agentic-beacon/pending.yaml` -3. The newly-adopted artifacts are immediately synced — symlinks are created under `.agentic-beacon/artifacts/` -4. Contexts are wired into your agent config (`CLAUDE.md` / `opencode.json`) -5. Skills are installed into each detected tool's directories -6. Agents are wired into project-local `.claude/agents/` and `.opencode/agents/` directories - -The entire workflow — select → write config → sync → wire — happens in one step. If anything fails mid-commit, the manifests are restored to their pre-commit state. - -For the underlying storage model (`pending.yaml`, `.last-adopt`, atomic rollback), see [Pending & Adoption](../concepts/pending-and-adoption.md). - -> Editing `beacon.yaml` manually instead of going through the TUI? Run `abc sync` yourself afterward — the auto-sync described above only fires from the TUI confirm path. - ---- - -## Flags - -```bash -# Preview what's available without making any changes -abc adopt --dry-run -``` - -### `--dry-run` - -Lists available artifacts in the terminal without opening the TUI. Useful for scripting or quick inspection. - -### Show already-adopted artifacts - -By default the TUI hides artifacts you've already added to `beacon.yaml`. To review your current selection (or unadopt entries), press `t` inside the TUI to toggle the show-all view. There is no `--all` CLI flag — the toggle is in-TUI only. - ---- - -## Discovering New Artifacts - -After a teammate adds artifacts to the warehouse, `abc sync` will notify you: - -``` -✓ Sync complete - Copied: 0 files - Unchanged: 3 files - -1 new artifact(s) available — run abc adopt to review -``` - -Run `abc adopt` to open the TUI showing the new artifacts. Select the ones you want and press `Enter`. - ---- - -## Relationship to beacon.yaml - -`abc adopt` is a graphical front-end for editing `beacon.yaml`. It: -- Reads the warehouse to find available artifacts -- Reads your current `beacon.yaml` to know what's already adopted -- Writes new entries to `beacon.yaml` when you confirm - -You can always edit `beacon.yaml` directly if you prefer — `abc adopt` just makes it easier. - ---- - -## Next Steps - -- **[Syncing Artifacts](syncing.md)** — `abc sync` flags and behavior -- **[beacon.yaml Reference](../reference/beacon-yaml.md)** — direct editing reference -- **[Day-to-Day Workflow](day-to-day-workflow.md)** — the full recurring loop diff --git a/site-docs/guides/spec-driven-development.md b/site-docs/guides/spec-driven-development.md deleted file mode 100644 index 268f12c..0000000 --- a/site-docs/guides/spec-driven-development.md +++ /dev/null @@ -1,199 +0,0 @@ -# Spec-Driven Development - -A guide for using spec-driven development approaches in agentic engineering. The methodology is **orthogonal to Beacon proper** — Beacon distributes the artifacts that govern *how* an agent works, but a spec describes *what* it should build. Spec-driven workflows are a common way to author specs your agents can act on. - ---- - -## Overview - -Spec-driven development is a methodology for transforming vague ideas into implementation-ready specifications through structured planning phases. - -**When to use spec-driven development:** - -- Complex, multi-component features -- Features requiring cross-team coordination -- Features with unclear or evolving requirements -- When you need to validate approach before significant implementation - -**When NOT to use spec-driven development:** - -- Simple, well-understood tasks (1-2 file changes) -- Bug fixes with clear root cause -- Routine maintenance tasks -- Prototyping or exploratory coding - ---- - -## Two-Phase Approach - -### Phase 1: Technical planning - -**Goal:** Transform free-form ideas into a formal, implementation-ready technical plan. - -**Process:** - -1. **Listen and parse** — Extract core problem, goals, scope, technical ideas -2. **Generate first draft** — Create a structured technical planning document -3. **Audit and gap analysis** — Identify missing information, ask targeted questions -4. **Baseline** — Complete when all open questions are answered and the user approves - -**Output — a technical planning document with:** - -- Clear problem statement and goals -- Testable acceptance criteria -- Explicit in-scope and out-of-scope boundaries -- High-level technical approach -- Identified risks and dependencies -- Impacted modules/systems - -### Phase 2: Task breakdown - -**Goal:** Decompose the technical plan into granular, sequential implementation tasks. - -**Process:** - -1. **Source audit** — Access the planning document, scan the codebase for impacted modules -2. **Decomposition** — Break work into "sprints of one" atomic tasks -3. **Resolution** — Address ambiguities before starting implementation -4. **Handoff** — Deliver an actionable task checklist ready for execution - -**Output — a task breakdown document with:** - -- User story extracted from the plan -- Step-by-step implementation checklist -- Verification steps for each task -- Dependencies and execution order -- Manual intervention steps (if any) - ---- - -## Packaging as Warehouse Skills - -Spec-driven development workflows can be packaged as **skills** in your warehouse: - -``` -skills/ -├── spec-propose/ # Phase 1: Create the technical plan -├── spec-breakdown/ # Phase 2: Create the task breakdown -└── spec-implement/ # Execute tasks from the breakdown -``` - -**Example usage:** - -```bash -/spec-propose "Add user authentication with OAuth" -/spec-breakdown -/spec-implement -``` - -See [Creating Skills](creating-skills.md) for how to author and distribute the underlying `SKILL.md` files. - ---- - -## Best Practices - -### During planning - -- **Be thorough** — better to over-specify than under-specify -- **Ask questions** — don't assume, clarify ambiguities -- **Think about failure** — what happens when things go wrong? -- **Identify manual steps early** — know what requires human intervention -- **Use diagrams** — Mermaid for complex flows - -### During task breakdown - -- **Small tasks** — each completable in one focused session -- **Verification steps** — every task needs a confirmation method -- **Logical order** — dependencies should flow naturally -- **Mark manual steps** — use `[MANUAL]` prefix to set expectations -- **Don't invent** — stick to what's in the technical plan - -### General - -- **Iterate** — specs improve with feedback -- **Version control** — commit after each phase -- **Link to knowledge** — store rationale and decisions in your warehouse -- **Keep readable** — write for humans first, AI second - ---- - -## Document Templates - -### Technical planning template - -```markdown -# [Feature Name] - -## 1. Background and Problem Statement -[Clear synthesis of problem and why it needs solving] - -## 2. Goals & Acceptance Criteria -- [ ] AC 1: [Testable criterion] -- [ ] AC 2: [Testable criterion] - -## 3. Scope -### In Scope -[What will be implemented] - -### Out of Scope -[What won't be implemented] - -## 4. Proposed Technical Solution -### High-Level Architecture -[End-to-end flow and data lifecycle] - -### Impacted Modules -- [Module/Path]: [Required modifications] - -### Manual Intervention Requirements -- [Manual Step]: [Description and rationale] - -## 5. Risks and Dependencies -- **Risk:** [Problem] - - **Mitigation:** [Solution] - -## 6. Open Questions -- [ ] [Question to resolve] -``` - -### Task breakdown template - -```markdown -# Implementation Plan: [Feature Name] - -## 1. User Story -[Extracted from technical plan] - -## 2. Technical Summary -[Concise summary of solution] - -## 3. Acceptance Criteria -- [ ] AC 1: [From technical plan] -- [ ] AC 2: [From technical plan] - -## 4. Technical Task Checklist - -### Phase 1: Preparation -- [ ] **Step 1:** [Action] - - *Verification:* [How to check] - -### Phase 2: Implementation -- [ ] **Step 2:** [Action] - - *Verification:* [How to check] -- [ ] **[MANUAL] Step 3:** [User action required] - - *User Action:* [What user needs to do] - - *Verification:* [How to confirm] - -## 5. Dependencies -[Internal/external dependencies] - -## 6. Questions & Ambiguities -[Items needing resolution] -``` - ---- - -## See Also - -- [Specs vs. Artifacts](../concepts/specs-vs-artifacts.md) — why specs and warehouse artifacts live in different places -- [Creating Skills](creating-skills.md) — package spec workflows as distributable skills diff --git a/site-docs/guides/syncing.md b/site-docs/guides/syncing.md deleted file mode 100644 index 0bb9b5c..0000000 --- a/site-docs/guides/syncing.md +++ /dev/null @@ -1,150 +0,0 @@ -# Syncing Artifacts - -`abc sync` is the core command — it reads `beacon.yaml`, resolves dependencies via frontmatter, auto-derives knowledge from markdown links, and installs everything in the right places for your AI tools. - -## Basic Usage - -```bash -abc sync -``` - -Reads `.agentic-beacon/beacon.yaml` and performs the full sync. Output example: - -``` -✓ Sync complete - Created: 5 symlinks - Up to date: 10 symlinks - ✓ Wired 2 context(s) into CLAUDE.md - ✓ Installed 1 skill(s) (code-review) -``` - ---- - -## What Sync Does - -`abc sync` runs a multi-phase pipeline: - -1. **Read `beacon.yaml`** — loads declared contexts, skills, and agents -2. **Resolve dependencies** — reads `requires:` frontmatter from each skill's `SKILL.md` and agent dependencies from `agents/agents.yaml` to compute transitive dependencies -3. **Auto-derive knowledge** — scans all adopted contexts and skills for markdown links to `knowledge/` paths -4. **Create symlinks** — creates per-file symlinks under `.agentic-beacon/artifacts/` pointing into the warehouse -5. **Wire artifacts** — adds context references to `CLAUDE.md`/`opencode.json`, installs skills into tool directories, wires agents into project-local `.claude/agents/` and `.opencode/agents/` -6. **Prune orphans** — removes symlinks for artifacts no longer referenced - -| Artifact | Destination | Wiring | -|---|---|---| -| **Contexts** | `.agentic-beacon/artifacts/contexts/` (symlinks) | Added to `CLAUDE.md` or `opencode.json` | -| **Skills** | `.agentic-beacon/artifacts/skills/` (symlinks) + tool dirs | Installed as slash commands | -| **Knowledge** | `.agentic-beacon/artifacts/knowledge/` (symlinks) | Auto-derived from markdown links; no wiring needed | -| **Agents** | `.agentic-beacon/artifacts/agents/` (symlinks) + `.claude/agents/` + `.opencode/agents/` | Wired per-project; declared in `beacon.yaml` | - ---- - -## Sync Flags - -### `--force` — Overwrite Everything - -```bash -abc sync --force -``` - -Force-overwrites all conflicting files, ignoring any local modifications. Use when you want to fully reset to the current warehouse state. - -### `--dry-run` — Preview Without Applying - -```bash -abc sync --dry-run -``` - -Shows what would be synced without making changes: - -``` -Would create: 5 symlinks -Up to date: 10 symlinks -``` - -### `--verbose` — Per-file Output - -```bash -abc sync --verbose -``` - -Shows detailed output for each file processed. - -### `--skip-git-check` — Skip Warehouse Validation - -```bash -abc sync --skip-git-check -``` - -Bypasses the warehouse git state checks (uncommitted changes, behind remote, non-main branch). Useful in CI environments. - -### `--contribute-local` — Auto-contribute Modified Files - -```bash -abc sync --contribute-local -``` - -Non-interactive: automatically contributes all locally modified files back to the warehouse during sync. - -### `--discard-local` — Auto-discard Local Changes - -```bash -abc sync --discard-local -``` - -Non-interactive: discards all locally modified files and replaces them with fresh symlinks from the warehouse. - ---- - -## Combining Flags - -```bash -# Preview a full reset -abc sync --force --dry-run -``` - ---- - -## Syncing Agents - -Agents declared in `beacon.yaml` are wired into project-local tool directories during `abc sync`: - -```bash -abc sync -``` - -`abc sync` creates: -- `.agentic-beacon/artifacts/agents/.md` — artifact symlink into the warehouse -- `.claude/agents/.md` — project-local symlink (when `.claude/` exists) -- `.opencode/agents/.md` — project-local symlink (when `.opencode/` exists) - -Agents are project-scoped. Use `abc adopt` to select which agents to declare in `beacon.yaml`. - ---- - -## Resetting All Artifacts - -```bash -abc reset -``` - -Force-overwrites all synced artifacts from the warehouse, discarding any local modifications. - ---- - -## Cleaning Up - -```bash -abc clean -``` - -Removes `.agentic-beacon/artifacts/` entirely. Run `abc sync` to re-sync. - ---- - -## Next Steps - -- **[Advanced Patterns](advanced-patterns.md)** — glob patterns and artifact lifecycle -- **[Day-to-Day Workflow](day-to-day-workflow.md)** — how sync fits into the recurring loop -- **[CLI Reference](../reference/cli.md)** — full flag documentation diff --git a/site-docs/guides/team-collaboration.md b/site-docs/guides/team-collaboration.md deleted file mode 100644 index 48ea110..0000000 --- a/site-docs/guides/team-collaboration.md +++ /dev/null @@ -1,273 +0,0 @@ -# Team Collaboration - -This guide covers how teams share a warehouse, stay in sync, and manage the contribution workflow at scale. - -## The Collaboration Model - -| Role | Artifact | -|------|---------| -| **Warehouse** | Your team's shared registry — one git repo | -| **`beacon.yaml`** | Each project's context and skill dependencies | -| **Artifacts** | Synced to each developer's local machine | - -The warehouse is the single source of truth. Projects pull from it; improvements flow back to it. - ---- - -## Setting Up Team Collaboration - -### 1. Create and push a warehouse - -```bash -abc warehouse init team-warehouse -cd team-warehouse - -# Add initial content -mkdir -p knowledge/languages/python -mkdir -p contexts/teams/backend -mkdir -p skills/code-review - -git init -git add . -git commit -m "Initial team warehouse" -git remote add origin git@github.com:yourorg/team-warehouse.git -git push -u origin main -``` - -### 2. Team members connect - -Each team member clones the warehouse and connects their projects: - -```bash -# Clone warehouse -git clone git@github.com:yourorg/team-warehouse.git ~/team-warehouse - -# In each project -cd my-project -abc warehouse connect --path ~/team-warehouse -abc adopt # select artifacts interactively -abc sync # sync and wire -``` - -**Tip:** Add to your team onboarding checklist: - -```markdown -## Developer Setup -- [ ] Clone warehouse: `git clone git@github.com:yourorg/team-warehouse.git ~/team-warehouse` -- [ ] In each project: `abc warehouse connect --path ~/team-warehouse` -- [ ] Select artifacts: `abc adopt` -- [ ] Sync artifacts: `abc sync` -``` - ---- - -## Workflow Patterns - -### Pattern 1: Standardized Project Templates - -Create example `beacon.yaml` files in the warehouse for common project types: - -```yaml -# team-warehouse/examples/beacon-python-api.yaml -artifacts: - skills: - - skills/code-review/ - - skills/generate-tests/ - - contexts: - - contexts/teams/backend/AGENTS.md -``` - -New projects copy the template: - -```bash -cd new-api-project -abc warehouse connect --path ~/team-warehouse -abc setup -cp ~/team-warehouse/examples/beacon-python-api.yaml .agentic-beacon/beacon.yaml -abc sync -``` - -Knowledge files referenced by those contexts and skills are auto-derived — no manual knowledge configuration needed. - -### Pattern 2: Progressive Artifact Adoption - -Start minimal, grow as the warehouse grows: - -**Sprint 1 — Start minimal:** -```yaml -artifacts: - skills: [] - contexts: - - contexts/teams/backend/AGENTS.md -``` - -**After warehouse grows:** -```bash -cd ~/team-warehouse && git pull -cd my-project && abc sync -# → "2 new artifact(s) available — run abc adopt to review" -abc adopt -# → TUI: select code-review skill, generate-tests skill → Enter -``` - -### Pattern 3: Team-Specific Contexts - -Organize contexts by team structure: - -``` -contexts/ -├── teams/ -│ ├── backend/AGENTS.md # backend team standards -│ ├── frontend/AGENTS.md # frontend team standards -│ └── platform/AGENTS.md # platform team standards -└── projects/ - ├── customer-portal/AGENTS.md - └── internal-tools/AGENTS.md -``` - -Backend project `beacon.yaml`: -```yaml -artifacts: - skills: [] - contexts: - - contexts/teams/backend/AGENTS.md - - contexts/projects/customer-portal/AGENTS.md -``` - -Frontend project `beacon.yaml`: -```yaml -artifacts: - skills: [] - contexts: - - contexts/teams/frontend/AGENTS.md - - contexts/projects/customer-portal/AGENTS.md -``` - ---- - -## Maintaining the Warehouse - -### Adding new knowledge - -Knowledge is auto-derived from markdown links. When you add a knowledge file to the warehouse, link to it from a context or skill and it will be synced automatically: - -```bash -cd ~/team-warehouse -cat > knowledge/best-practices/error-handling.md << 'EOF' -# Error Handling Best Practices -... -EOF - -# Add a reference in the backend context -echo "See [Error Handling](knowledge/best-practices/error-handling.md) for guidelines." >> contexts/teams/backend/AGENTS.md - -git add . -git commit -m "docs: add error handling best practices" -git push -``` - -Team members get the new knowledge on their next sync: - -```bash -cd ~/team-warehouse && git pull -cd my-project && abc sync -``` - -The resolver finds the `knowledge/best-practices/error-handling.md` link in the adopted context and syncs it automatically. - -### Updating existing artifacts - -```bash -cd ~/team-warehouse -vim knowledge/languages/python/type-hints.md - -git add knowledge/languages/python/type-hints.md -git commit -m "docs: update type hints guide with Python 3.12 features" -git push -``` - -Team members get the update on their next sync: - -```bash -cd ~/team-warehouse && git pull -cd my-project && abc sync -``` - ---- - -## Team Coordination - -### Weekly warehouse reviews - -1. Review PRs from team members -2. Discuss patterns that are working well -3. Prune outdated or deprecated artifacts -4. Update example `beacon.yaml` files - -### Regular maintenance schedule - -- **Monthly:** Review and prune outdated artifacts; remove dead markdown links -- **Quarterly:** Major version tags with changelogs -- **Ad-hoc:** Quick additions for new patterns - ---- - -## Handling Conflicts - -### Team standard changes - -When a shared artifact is updated, sync picks up the latest: - -```bash -# Before sync, review warehouse changes -abc warehouse status - -# Sync -abc sync -``` - -### Multiple warehouse versions - -For legacy projects that need an older warehouse state, use git tags: - -```bash -cd ~/team-warehouse -git checkout v1-stable -``` - ---- - -## Multi-Repository Organizations - -For large organizations, a hub-and-spoke model works well: - -``` -org-wide-warehouse/ # Org-wide standards -├── knowledge/security/ -└── contexts/organization/ - -backend-team-warehouse/ # Team-specific standards -├── knowledge/languages/python/ -└── contexts/teams/backend/ -``` - -!!! note - Agentic Beacon currently supports one warehouse per project. For multi-warehouse setups, merge warehouse content or use git submodules. - ---- - -## Best Practices - -1. **Clear ownership** — assign maintainers to warehouse sections (e.g., Python guild owns `knowledge/languages/python/`) -2. **Use frontmatter** — every skill's `SKILL.md` must declare `requires: { contexts: [...] }` -3. **Link to knowledge** — knowledge files only sync when referenced by a markdown link from an adopted context or skill -4. **Use semantic versioning** — tag stable warehouse releases: `v1.0.0` - ---- - -## Next Steps - -- **[Creating a Warehouse](warehouse-creation.md)** — detailed warehouse setup -- **[Contributing Back](contributing-back.md)** — getting improvements back to the warehouse -- **[Advanced Patterns](advanced-patterns.md)** — complex configurations diff --git a/site-docs/guides/warehouse-creation.md b/site-docs/guides/warehouse-creation.md index bd4cbb8..246d7a1 100644 --- a/site-docs/guides/warehouse-creation.md +++ b/site-docs/guides/warehouse-creation.md @@ -208,6 +208,6 @@ git push --tags ## Next Steps -- **[Team Collaboration](team-collaboration.md)** — share your warehouse across the team +- **[Quick Start](../quickstart.md)** — connect a project to this warehouse and adopt your first artifacts - **[Creating Skills](creating-skills.md)** — write effective skill definitions -- **[Connecting a Project](connecting-projects.md)** — connect a project to this warehouse +- **[Contributing Back](contributing-back.md)** — push warehouse changes upstream once your team is using it diff --git a/site-docs/index.md b/site-docs/index.md index 248329e..296aa62 100644 --- a/site-docs/index.md +++ b/site-docs/index.md @@ -82,23 +82,3 @@ abc sync ``` → **[Quick Start](quickstart.md)** for a full walkthrough. - ---- - -## Compared to Similar Tools - -| Tool | What it does | -|------|-------------| -| **Repomix** | Bundles your codebase into a single LLM-readable file | -| **faf-mcp** | Syncs context files locally via MCP | -| **cursorrules.com** | Static directory of community `.cursorrules` files | -| **Shared wiki / prompt library** | A team-maintained document store agents are told to read | -| **Langfuse / LLM Ops** | Production observability and prompt management | - -**Use Agentic Beacon when** you want a version-controlled, team-wide source of truth for agent instructions across multiple projects or repos. - -### Why not a shared wiki or prompt library? - -A shared wiki is **read-only by design** — someone curates it, everyone else consumes it. There is no path from a coding session back to the wiki. Improvements stay on the developer's machine. - -Agentic Beacon is **bidirectional**. When an agent session produces a better approach, `abc warehouse contribute -m "message"` commits it back to the warehouse. Once merged, every project gets the improvement on the next `abc sync`. The warehouse gets smarter over time because the whole team is contributing to it, not just reading from it. That compounding loop is what the tool was built around. diff --git a/site-docs/installation.md b/site-docs/installation.md index a37142c..6233f58 100644 --- a/site-docs/installation.md +++ b/site-docs/installation.md @@ -48,16 +48,6 @@ You should see a version number printed (e.g. `3.x.y`). uv tool upgrade agentic-beacon ``` -## What Gets Installed - -Installing `agentic-beacon` puts a single command on your PATH: - -| Command | Description | -|---------|-------------| -| `abc` | The Agentic Beacon CLI — the only command you need | - -All subcommands (`abc sync`, `abc warehouse init`, etc.) are available under `abc`. - ## Next Steps → **[Quick Start](quickstart.md)** — set up a warehouse and connect your first project in minutes. diff --git a/site-docs/quickstart.md b/site-docs/quickstart.md index 1c95290..d89029c 100644 --- a/site-docs/quickstart.md +++ b/site-docs/quickstart.md @@ -94,21 +94,6 @@ Done. Your agent now has the team's contexts, knowledge, and skills loaded. --- -## Day-to-Day Workflow - -Once set up, the recurring loop is: - -``` -1. git pull (in warehouse) — fetch teammates' updates - abc sync — re-sync symlinks after manual beacon.yaml edits or global artifact installs -2. code with agent — agent uses synced contexts, knowledge, and skills -3. abc warehouse status — see what has changed in the warehouse working tree -4. abc warehouse contribute — commit improvements back to the warehouse -5. repeat -``` - ---- - ## What Gets Committed to Git ``` @@ -123,7 +108,6 @@ Teammates run `abc warehouse connect` + `abc sync` to get the same artifacts on ## Next Steps -- **[Concepts: How It Works](concepts/how-it-works.md)** — understand the warehouse model -- **[Creating a Warehouse](guides/warehouse-creation.md)** — full warehouse setup walkthrough -- **[beacon.yaml Reference](reference/beacon-yaml.md)** — configure exactly which artifacts you need -- **[Interactive Adoption](guides/interactive-adoption.md)** — the `abc adopt` TUI in depth +- **[How It Works](concepts/how-it-works.md)** — the warehouse + symlink model in depth +- **[Day-to-Day Workflow](guides/day-to-day-workflow.md)** — the recurring sync / status / contribute loop +- **[Adopting Artifacts](guides/adopting-artifacts.md)** — the `abc adopt` TUI and declarative `beacon.yaml` flow diff --git a/site-docs/reference/beacon-yaml.md b/site-docs/reference/beacon-yaml.md index f992ad2..42ef7c1 100644 --- a/site-docs/reference/beacon-yaml.md +++ b/site-docs/reference/beacon-yaml.md @@ -226,21 +226,6 @@ The `.gitignore` entries are added automatically when you run `abc warehouse con --- -## Related Commands +## See Also -```bash -# Create beacon.yaml -abc setup - -# Populate it interactively -abc adopt - -# Apply the configuration -abc sync - -# Preview warehouse working tree changes -abc warehouse status - -# Check what's configured and synced -abc status -``` +- **[CLI Reference](cli.md)** — every command that reads or writes `beacon.yaml` diff --git a/site-docs/guides/contribute-warehouse.md b/site-docs/reference/contribute-warehouse.md similarity index 97% rename from site-docs/guides/contribute-warehouse.md rename to site-docs/reference/contribute-warehouse.md index 1604696..aad497d 100644 --- a/site-docs/guides/contribute-warehouse.md +++ b/site-docs/reference/contribute-warehouse.md @@ -96,7 +96,7 @@ knowledge/python/lessons/type-hints.md may duplicate: ``` The dedup scan in v1 is LLM-driven, scoped to the local directory. Cross-warehouse -vectorized search is planned for PER-179. +vectorized search is on the roadmap. --- @@ -267,6 +267,6 @@ The skill ships four PEP 723 helper scripts in its `scripts/` directory: ## Related -- [Contributing Back](contributing-back.md) — manual `abc warehouse contribute` workflow +- [Contributing Back](../guides/contributing-back.md) — manual `abc warehouse contribute` workflow - [Bundled Skills](../concepts/bundled-skills.md) — how bundled skills work -- [Creating Skills](creating-skills.md) — authoring warehouse skills manually +- [Creating Skills](../guides/creating-skills.md) — authoring warehouse skills manually From 6d13c316989fdaa41d975d3a872fc47af6115778 Mon Sep 17 00:00:00 2001 From: Song Yikun Date: Mon, 18 May 2026 22:27:27 +0800 Subject: [PATCH 7/7] =?UTF-8?q?docs:=20audit=20pass=20=E2=80=94=20trim=20d?= =?UTF-8?q?uplication,=20fix=20stale=20paths,=20scrub=20ticket=20refs=20(P?= =?UTF-8?q?ER-190)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Critical-read audit of the post-restructure site, then trimming. Page deletions (5 pages, -625 lines): - concepts/specs-vs-artifacts.md: 205-line essay; kernel idea fits in one bullet elsewhere - concepts/design-decisions.md: one-decision stub with unkept promise of more - guides/connecting-projects.md: covered by Quickstart Scenario B - guides/advanced-patterns.md: duplicated cli.md and beacon-yaml.md - tutorials/first-contribution.md: 80% duplicated day-to-day-workflow; unique 'stray edit' beat folded into the discard section Bug fixes: - artifacts/contexts/knowledge/error-handling.md → artifacts/knowledge/... in day-to-day-workflow.md (wrong path; would error on copy-paste) - warehouse-lint/github-actions.md: removed broken Python-standards link pointing to how-it-works.md; removed internal AGENTS.md reference Internal-ticket leak scrub (no PER-XXX in public docs): - bundled-skills.md (PER-150, PER-151) - contributing-back.md (PER-159) - reference/contribute-warehouse.md (PER-179) CLI reference gaps: - abc sync --yes flag added (auto-accept agent-required skills) - abc warehouse contribute --paths flag added (per-file commits) Section-level cuts: - bundled-skills.md: 'Bundled Skills in the Warehouse Template' (~25 lines) and duplicated record-skill walkthrough (~40 lines, already in pending-and-adoption.md) - artifact-types.md: 'How the Matrix Shapes Command Behavior' table + 'Summary' filler — content lives in cli.md and adopting-artifacts.md - index.md: removed 'Compared to Similar Tools' table per direction; collapsed wiki-vs-beacon paragraph into the multiplayer admonition - installation.md: 'What Gets Installed' single-row filler - quickstart.md: 'Day-to-Day Workflow' mini-block; capped Next Steps to 3 - day-to-day-workflow.md: 'Quick Reference' command table (duplicates cli.md and prose above it) - creating-skills.md: 'Full Template' YAML (Minimal Template above is enough) - beacon-yaml.md: 'Related Commands' duplicate of cli.md Nav reorder (mkdocs.yml): - Guides moved before Design (Guides is the entry point; Design is rationale for advanced readers) - Removed dead nav entries: specs-vs-artifacts, design-decisions, connecting-projects, advanced-patterns, tutorials section, top-level contributing.md page README cleanup: removed dead specs-vs-artifacts and design-decisions links from the Concepts section. Net result: 27 → 22 pages, ~4534 → ~3668 lines (-19%). All 19 live pages return 200; all deleted pages return 404. Build green. --- README.md | 9 +- mkdocs.yml | 39 +--- site-docs/concepts/artifact-types.md | 46 +--- site-docs/concepts/bundled-skills.md | 85 +------- site-docs/concepts/design-decisions.md | 35 --- site-docs/concepts/specs-vs-artifacts.md | 205 ------------------ site-docs/guides/advanced-patterns.md | 202 ----------------- site-docs/guides/connecting-projects.md | 160 -------------- site-docs/guides/day-to-day-workflow.md | 31 +-- .../guides/warehouse-lint/github-actions.md | 2 +- site-docs/reference/cli.md | 4 + site-docs/tutorials/first-contribution.md | 193 ----------------- 12 files changed, 31 insertions(+), 980 deletions(-) delete mode 100644 site-docs/concepts/design-decisions.md delete mode 100644 site-docs/concepts/specs-vs-artifacts.md delete mode 100644 site-docs/guides/advanced-patterns.md delete mode 100644 site-docs/guides/connecting-projects.md delete mode 100644 site-docs/tutorials/first-contribution.md diff --git a/README.md b/README.md index e28b1ed..2aa2e07 100644 --- a/README.md +++ b/README.md @@ -126,8 +126,6 @@ Everything is a per-file **symlink** into the warehouse clone — one physical f **Frontmatter dependencies.** Skills declare `requires:` in YAML frontmatter; agents declare dependencies in `agents/agents.yaml`. `abc sync` validates all declared dependencies are adopted and errors early if any are missing. -> **Read:** [Decision — No Project-Local Artifact Overrides](https://shadowsong27.github.io/agentic-beacon/concepts/design-decisions/) for the full design rationale. - > **Platform support:** macOS and Linux only. ## Artifact Types @@ -160,18 +158,13 @@ Everything is a per-file **symlink** into the warehouse clone — one physical f ### Concepts - **[How It Works](https://shadowsong27.github.io/agentic-beacon/concepts/how-it-works/)** — Warehouse + beacon mental model and sync flow -- **[Philosophy](https://shadowsong27.github.io/agentic-beacon/concepts/philosophy/)** — Why this exists, why markdown not RAG, why lightweight +- **[Philosophy](https://shadowsong27.github.io/agentic-beacon/design/philosophy/)** — Why this exists, why markdown not RAG, why lightweight (Design) - **[Artifact Types](https://shadowsong27.github.io/agentic-beacon/concepts/artifact-types/)** — Scope and tool-specificity axes; how they drive command design -- **[Specs vs. Artifacts](https://shadowsong27.github.io/agentic-beacon/concepts/specs-vs-artifacts/)** — What belongs in a warehouse vs. a project -- **[Design Decisions](https://shadowsong27.github.io/agentic-beacon/concepts/design-decisions/)** — Architectural choices and their rationale ### Guides - **[Quick Start](https://shadowsong27.github.io/agentic-beacon/quickstart/)** — Onboarding walkthrough - **[Warehouse Creation](https://shadowsong27.github.io/agentic-beacon/guides/warehouse-creation/)** — Creating and structuring a warehouse - **[Contributing Back](https://shadowsong27.github.io/agentic-beacon/guides/contributing-back/)** — Commit agent improvements back to the warehouse -- **[Spec-Driven Development](https://shadowsong27.github.io/agentic-beacon/guides/spec-driven-development/)** — Structured approach to feature planning -- **[Team Collaboration](https://shadowsong27.github.io/agentic-beacon/guides/team-collaboration/)** — Multi-team workflows -- **[Advanced Patterns](https://shadowsong27.github.io/agentic-beacon/guides/advanced-patterns/)** — Glob patterns, dry-run, warehouse commands, migration ### Reference - **[beacon.yaml](https://shadowsong27.github.io/agentic-beacon/reference/beacon-yaml/)** — Full configuration schema diff --git a/mkdocs.yml b/mkdocs.yml index 2b5c1df..3c294b4 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -79,45 +79,26 @@ nav: - Quick Start: quickstart.md - Concepts: - How It Works: concepts/how-it-works.md - - Philosophy: concepts/philosophy.md - - What Is a Skill: concepts/what-is-a-skill.md - Bundled Skills: concepts/bundled-skills.md - Pending & Adoption: concepts/pending-and-adoption.md - Artifact Types: concepts/artifact-types.md - - Specs vs. Artifacts: concepts/specs-vs-artifacts.md - - Design Decisions: concepts/design-decisions.md - Guides: - Creating a Warehouse: guides/warehouse-creation.md - - Connecting a Project: guides/connecting-projects.md - - Interactive Adoption: guides/interactive-adoption.md - - Syncing Artifacts: guides/syncing.md + - Adopting Artifacts: guides/adopting-artifacts.md - Day-to-Day Workflow: guides/day-to-day-workflow.md - - Spec-Driven Development: guides/spec-driven-development.md - - Contributing Back: guides/contributing-back.md - - Contribute Warehouse Skill: guides/contribute-warehouse.md - - Creating Skills: guides/creating-skills.md + - Contributing Back: + - Overview: guides/contributing-back.md + - Creating Skills: guides/creating-skills.md + - Creating Knowledge and Contexts: guides/creating-knowledge-and-contexts.md + - Creating an Agent: guides/creating-agents.md - Warehouse Lint: - GitHub Actions CI: guides/warehouse-lint/github-actions.md - Pre-commit Hook: guides/warehouse-lint/pre-commit.md - - Team Collaboration: guides/team-collaboration.md - - Advanced Patterns: guides/advanced-patterns.md - - Tutorials: - - Your First Contribution: tutorials/first-contribution.md + - Design: + - Philosophy: design/philosophy.md + - Skills: design/skills.md - Reference: - beacon.yaml: reference/beacon-yaml.md - CLI Reference: reference/cli.md + - contribute-warehouse Skill: reference/contribute-warehouse.md - Troubleshooting: troubleshooting.md - - Contributing: - - Overview: contributing/index.md - - Commands: contributing/commands.md - - Project Layout: contributing/project-layout.md - - Architecture: contributing/architecture.md - - Configuration: contributing/configuration.md - - Local Development: contributing/local-development.md - - Code Style: contributing/code-style.md - - Design Patterns: contributing/design-patterns.md - - Testing: contributing/testing.md - - Contribution Workflow: contributing/contribution-workflow.md - - Documentation: contributing/documentation.md - - Gotchas: contributing/gotchas.md - - Open Questions: contributing/open-questions.md diff --git a/site-docs/concepts/artifact-types.md b/site-docs/concepts/artifact-types.md index 05995f7..76bfeab 100644 --- a/site-docs/concepts/artifact-types.md +++ b/site-docs/concepts/artifact-types.md @@ -17,7 +17,7 @@ The bottom-left cell (global + tool-agnostic) is intentionally empty: a globally Beacon also touches one set of files that are **not artifacts**: the agent config files (`opencode.json`, `CLAUDE.md`). These hold no shared content and are not synced from the warehouse — they are per-project files that the AI tool reads at session start. -Beacon manages them via **agent config wiring**: it bootstraps them on first setup and keeps the synced context references inside them current on every sync — idempotently and without touching user-authored entries. This is the "wire" step of [the sync flow](how-it-works.md#the-sync-flow); see the [Syncing guide](../guides/syncing.md) for per-tool detail. +Beacon manages them via **agent config wiring**: it bootstraps them on first setup and keeps the synced context references inside them current on every sync — idempotently and without touching user-authored entries. This is the "wire" step of [the sync flow](how-it-works.md#the-sync-flow); see the [Adopting Artifacts guide](../guides/adopting-artifacts.md) for per-tool detail. Agent config files are listed here for completeness, not because they fit the matrix — they sit underneath it as the runtime surface that artifacts get wired into. @@ -132,45 +132,7 @@ agents: --- -## How the Matrix Shapes Command Behavior +## See Also -### `abc sync` - -Applies different logic per type: - -| Artifact | Sync behavior | -|---|---| -| Contexts | Symlink to `.agentic-beacon/artifacts/contexts/`; wire into agent config | -| Skills | Symlink to artifacts; install into each detected tool's live directories | -| Knowledge | Auto-derived from markdown links; symlink to `.agentic-beacon/artifacts/knowledge/` | -| Agents | Symlink to `.agentic-beacon/artifacts/agents/`; wire into project-local `.claude/agents/` and `.opencode/agents/` | - -### `abc warehouse status` - -Shows modifications to warehouse files tracked by resolved artifacts. With symlinks, editing an artifact directly modifies the warehouse working tree: - -```bash -abc warehouse status # summary of modified files -abc warehouse status knowledge/python/type-hints.md # diff for a single file -``` - -### `abc warehouse contribute` - -Commits changes in the warehouse working tree. Since symlinks write directly to the warehouse, you edit an artifact, then commit: - -```bash -abc warehouse contribute -m "Update type hints guide with Python 3.12+ patterns" -``` - ---- - -## Summary - -Knowing an artifact's type tells you exactly: - -- Where it lives after sync -- How it's declared (or auto-derived) -- How it's wired or installed -- Which commands manage it - -The two-axis model keeps the framework internally consistent: the behavior follows directly from position in the matrix. +- **[Adopting Artifacts](../guides/adopting-artifacts.md)** — how each artifact type flows through the sync pipeline +- **[CLI Reference](../reference/cli.md)** — per-type behaviour for `abc sync`, `abc warehouse status`, `abc warehouse contribute` diff --git a/site-docs/concepts/bundled-skills.md b/site-docs/concepts/bundled-skills.md index 13d1b47..8b7e766 100644 --- a/site-docs/concepts/bundled-skills.md +++ b/site-docs/concepts/bundled-skills.md @@ -57,7 +57,7 @@ lint gate, intent triage, semantic dedup scan, cohesion split, and atomic push. safe, intent-aware flow — especially when multiple files are dirty or you want the lint gate enforced. -For full documentation, see [Contribute Warehouse Skill](../guides/contribute-warehouse.md). +For full documentation, see [`contribute-warehouse` Skill Reference](../reference/contribute-warehouse.md). --- @@ -89,7 +89,7 @@ Claude Code discovers skills directly from `.claude/skills/` — there's no equi Two commands wire bundled skills: - **`abc sync`** — wires bundled skills as part of its normal artifact-sync flow. -- **`abc adopt`** — also wires bundled skills after its commit step (added in PER-151). This means the standard first-run sequence `connect → setup → adopt` leaves bundled skills fully available without a separate `abc sync`. Note: `abc adopt` only triggers bundled wiring when at least one entry is accepted in the TUI (reject-only or defer-only commits do not fire post-sync wiring). If you open `abc adopt` and exit without accepting anything, run `abc sync` to wire bundled skills. +- **`abc adopt`** — also wires bundled skills after its commit step. This means the standard first-run sequence `connect → setup → adopt` leaves bundled skills fully available without a separate `abc sync`. Note: `abc adopt` only triggers bundled wiring when at least one entry is accepted in the TUI (reject-only or defer-only commits do not fire post-sync wiring). If you open `abc adopt` and exit without accepting anything, run `abc sync` to wire bundled skills. ```bash abc warehouse connect --path ~/my-org-warehouse @@ -112,39 +112,11 @@ abc adopt # select warehouse artifacts; bundled skills wired here too Warehouse skills are distributed to teammates via `abc sync`. Bundled skills follow the developer — wherever `abc` is installed, those two skills are available. -> **Note:** `abc warehouse init` copies each bundled skill into the new warehouse's `skills/` directory as a starting-point template. This means a freshly initialised warehouse will contain `skills/record-knowledge/` and `skills/record-skill/` entries that look like ordinary warehouse skills — but the canonical version used for project wiring is always the one inside the `abc` package. See [Bundled Skills in the Warehouse Template](#bundled-skills-in-the-warehouse-template) below. +> **Note:** `abc warehouse init` copies each bundled skill into the new warehouse's `skills/` directory as a starting-point template — but the canonical version used for project wiring is always the one inside the `abc` package. Customising the warehouse copy will not shadow the bundled version. To distribute a custom variant, treat it as a new warehouse skill with a different name. --- -## Bundled Skills in the Warehouse Template - -When you run `abc warehouse init`, the initializer copies each bundled skill from the `abc` package into the new warehouse's `skills/` directory (via `_install_bundled_skills`). This produces real files — not symlinks — at paths like: - -``` -my-warehouse/ -└── skills/ - ├── record-knowledge/ - │ └── SKILL.md - ├── record-skill/ - │ └── SKILL.md - └── contribute-warehouse/ - ├── SKILL.md - └── scripts/ - ├── resolve_warehouse.py - ├── summarize_changes.py - ├── draft_commit_message.py - └── push_warehouse.py -``` - -These copies exist so teams have a visible, editable starting point. You can modify `/skills/record-knowledge/SKILL.md` to adjust the workflow for your organisation and commit that change into the warehouse. - -However, **the copies are not automatically used for project wiring**. When `abc sync` or `abc adopt` wires bundled skills into a project, it always reads from the `abc` package source — the warehouse copy is informational unless you explicitly adopt it as a regular warehouse skill via `beacon.yaml`. There is currently no automatic override mechanism that promotes a customised warehouse copy back into the wiring pipeline. - -In practice this means: a fresh warehouse visually contains bundled skills alongside other warehouse content, but teams that want to distribute a customised variant should treat it as a new warehouse skill (with a different name) rather than expecting the warehouse copy to shadow the bundled version. - ---- - -## Self-Contained Scripts (PER-150) +## Self-Contained Scripts The `scripts/append_pending.py` script inside each bundled skill has **no dependency on the `beacon` package**. It declares `pyyaml>=6.0` in a PEP 723 inline header and inlines all the YAML read-merge-write logic it needs. @@ -152,53 +124,8 @@ This means the `record-* → pending.yaml → abc adopt` loop works for any `abc --- -## Full Walkthrough: `record-skill` - -This walkthrough assumes you have already run `abc warehouse connect`, `abc setup`, and `abc adopt` at least once. - -```bash -# 1. In your project, invoke the bundled skill -# (inside a Claude Code or OpenCode session) -/record-skill - -# Agent prompts you: -# Skill name? → python-type-hints -# Description? → Enforce Python type annotation standards in new code. -# Initial steps? → (you describe the workflow) - -# Agent writes the warehouse file: -# /skills/python-type-hints/SKILL.md - -# Agent appends to project: -# .agentic-beacon/pending.yaml - -# 2. Back in your shell — notice the pending alert: -abc warehouse status -# → "⚠ 1 pending artifacts. Run 'abc adopt' to wire them." - -# 3. Review and accept the pending entry -abc adopt -# TUI opens, shows "python-type-hints" as a pending skill entry -# Press Space to select, Enter to confirm -# → Confirm screen shows: "+ skills/python-type-hints/ → beacon.yaml" -# → Press Enter to commit - -# 4. The skill is now wired: -# .agentic-beacon/beacon.yaml updated -# .claude/skills/python-type-hints/SKILL.md (symlink) -# .opencode/skills/python-type-hints/SKILL.md (symlink) -# .agentic-beacon/pending.yaml cleared - -# 5. Invoke the new skill immediately: -/python-type-hints -``` - -For the storage model behind step 2 and 3 (`pending.yaml` lifecycle, confirm screen, atomic rollback), see [Pending & Adoption](pending-and-adoption.md). - ---- - ## Next Steps -- **[Pending & Adoption](pending-and-adoption.md)** — the full `pending.yaml` lifecycle +- **[Pending & Adoption](pending-and-adoption.md)** — the full `pending.yaml` lifecycle, with a `record-skill` walkthrough - **[Creating Skills](../guides/creating-skills.md)** — authoring warehouse skills manually -- **[Interactive Adoption](../guides/interactive-adoption.md)** — the `abc adopt` TUI in depth +- **[Adopting Artifacts](../guides/adopting-artifacts.md)** — the `abc adopt` TUI in depth diff --git a/site-docs/concepts/design-decisions.md b/site-docs/concepts/design-decisions.md deleted file mode 100644 index 7774c45..0000000 --- a/site-docs/concepts/design-decisions.md +++ /dev/null @@ -1,35 +0,0 @@ -# Design Decisions - -This page records architectural decisions that shape how Agentic Beacon behaves. Each entry captures a decision, the reasoning behind it, and any historical context worth preserving. New decisions are appended over time. - ---- - -## No Project-Local Artifact Overrides - -**Status:** Accepted (updated 2026-05-03 to reflect the symlink-based sync model) - -### Decision - -Agentic Beacon does not support project-local overrides of warehouse artifacts. There is no `overrides/` directory, no `abc override` command, and no mechanism to maintain a diverged version of a warehouse artifact within a project. - -### Why - -Project-local overrides promote divergence. If an artifact needs to be different for a project, that difference is almost always worth sharing with the whole team — which means it belongs in the warehouse, not hidden in a project directory. - -Under the current symlink-based sync model, the warehouse clone **is** the single source of truth on any given machine — a project's `.agentic-beacon/artifacts/` tree is symlinks into the warehouse. "Overriding" a warehouse artifact per-project is therefore not just discouraged, it is mechanically prevented. - -The right workflow when a local change is discovered: - -1. `abc warehouse status` — review what changed in the warehouse working tree (scoped by `beacon.yaml`) -2. `abc warehouse contribute -m "…"` — commit the improvement in the warehouse clone -3. Push the warehouse — teammates pull and `abc sync` if new paths were added - -This keeps the warehouse as the single source of truth and ensures improvements discovered in one project benefit all projects. - -### Genuine per-project variation - -When a team genuinely needs different harness behavior for different projects, the correct response is to **author distinct artifacts** (e.g. `skills/code-review-python/` vs `skills/code-review-ts/`) and select between them via each project's `beacon.yaml`. The artifact system supports arbitrary naming; there is no need to duplicate the same-named file with different content. - -### Historical note - -Earlier versions of this document described the sync-time `--preserve` flag as "a narrow escape hatch for avoiding accidental overwrites during an active editing session." Under the symlink-based sync model, `abc sync` does not overwrite files (it creates or repairs symlinks pointing at the warehouse), and the preserve flag was removed from `abc sync`. diff --git a/site-docs/concepts/specs-vs-artifacts.md b/site-docs/concepts/specs-vs-artifacts.md deleted file mode 100644 index 94eb64a..0000000 --- a/site-docs/concepts/specs-vs-artifacts.md +++ /dev/null @@ -1,205 +0,0 @@ -# Specs vs. Artifacts - -Understanding the difference between **specs** and **artifacts** is crucial for effectively using Agentic Beacon. They look similar — both are markdown files an agent reads — but they answer different questions and live in different places. - ---- - -## The Blueprint vs. Building Code Analogy - -### Specs = the blueprint ("what" to build) - -Specs define the **exact, deterministic requirements** of a specific project or feature. - -**Examples:** - -- OpenSpec files (`openspec.md`) -- OpenAPI definitions (`swagger.yaml`) -- Protobuf definitions (`.proto` files) -- GraphQL schemas -- Product Requirement Documents (PRDs) - -**Nature:** - -- Project-specific -- Exact and deterministic -- Contract-driven -- Defines the goal - -**Agent's internal monologue:** -> "I need to build a `POST /users` endpoint that accepts a JSON payload with email and age, and returns a 201 status." - -### Artifacts = the building codes & tools ("how" to build it) - -Artifacts (managed by the warehouse) are the **reusable heuristics, rules, and capabilities** that govern how the agent writes code to fulfill a spec. - -**Examples:** - -- Knowledge files (`fastapi-rules.md`, `react-state-management-lessons.md`) -- Skills (`generate-unit-tests`, `code-review`) -- Contexts (`backend-microservice.md`, `python.md`) - -**Nature:** - -- Organization-wide -- Cross-project and reusable -- Heuristic-driven -- Defines the approach - -**Agent's internal monologue:** -> "When I build that `POST /users` endpoint, I must remember to use Pydantic V2 for validation, and I must use the `generate-unit-tests` skill to write a pytest file for it." - ---- - -## How to Handle Them in Your Workflow - -Because their purposes are fundamentally different, specs and artifacts live in different places and are handled differently. - -### Scenario A: the spec belongs to the local project (most common) - -**Rule:** Most of the time, specs should **not** live in your warehouse. - -**Example — building a new microservice:** - -- The OpenSpec for that microservice lives directly inside the local project repository -- Location: `~/my-project/openspec/spec.md` -- The agent reads the spec directly from the local workspace -- Beacon doesn't sync specs — it only syncs the **knowledge of how to implement** that spec properly - -**Workflow:** - -``` -my-project/ -├── openspec/ -│ └── spec.md # Local spec (project-specific) -├── .agentic-beacon/ -│ ├── beacon.yaml # Artifact dependencies (how to build) -│ └── artifacts/ -│ ├── knowledge/ # Synced from warehouse -│ └── skills/ # Synced from warehouse -└── src/ -``` - -**Agent's workflow:** - -1. Read `openspec/spec.md` to understand **what** to build -2. Read `.agentic-beacon/artifacts/knowledge/` to understand **how** to build it -3. Execute `.agentic-beacon/artifacts/skills/` to automate and verify the work - -### Scenario B: shared organizational specs (the exception) - -**Rule:** Sometimes a spec **is** an organizational artifact and belongs in the warehouse. - -**Example — company-wide authentication API:** - -- Your company has a core Authentication API -- Every frontend project needs the `auth-openapi.yaml` spec to know how to log users in -- This spec is organizational infrastructure, not project-specific - -In this case, store shared specs in the warehouse and reference them in `beacon.yaml`: - -```yaml -artifacts: - contexts: - - backend/api-design-rules.md # The "How" — rules for APIs - - specs/core-auth-api.yaml # The shared "What" — auth API spec - skills: - - generate-api-client # The "Tool" — generate client code -``` - -**When to treat specs as artifacts:** - -- API contracts shared across multiple teams/projects -- Core platform interfaces that many services integrate with -- Organizational data models or schemas -- Standard communication protocols - ---- - -## The Triangulation - -When an agent works in a local project equipped with Beacon, it gets a clean triangulation of data: - -| Source | Location | Tells the agent… | -|---|---|---| -| **Local spec** | `./openspec/spec.md` | **What** to code today | -| **Synced knowledge** | `./.agentic-beacon/artifacts/knowledge/` | **How** to follow company standards | -| **Synced skills** | `./.agentic-beacon/artifacts/skills/` | **Procedures** to automate and verify work | - ---- - -## Best Practices - -### ✅ Do store in the warehouse (artifacts) - -- Coding standards and best practices -- Architectural patterns and guidelines -- Reusable skills and workflows -- Shared organizational contexts -- Common API contracts used across teams - -### ❌ Don't store in the warehouse (specs) - -- Feature-specific requirements -- Project-specific API endpoints -- Individual user stories -- One-off implementation details -- Project roadmaps and milestones - -### 🤔 Gray area (case-by-case) - -- **Core platform APIs** — if 10+ projects depend on it → warehouse -- **Data schemas** — if organization-wide standard → warehouse -- **Communication protocols** — if company standard → warehouse - ---- - -## Example: Building a Payment Service - -**Local project (specs):** - -``` -payment-service/ -├── openspec/ -│ ├── spec.md # What: Build payment processing API -│ └── tasks.md # What: Stripe integration, refund flow -└── src/ -``` - -**Warehouse (artifacts) referenced by the project's `beacon.yaml`:** - -```yaml -artifacts: - contexts: - - backend/api-security-rules.md # How: Handle sensitive data - - backend/error-handling-patterns.md # How: Return error responses - - payments/pci-compliance-rules.md # How: PCI-DSS requirements - - specs/stripe-api-contract.yaml # Shared: Stripe integration spec - skills: - - generate-api-tests # Tool: Generate test suites - - security-audit # Tool: Check for vulnerabilities -``` - -**Agent's process:** - -1. Reads `openspec/spec.md`: "I need to build a payment processing API" -2. Reads `knowledge/api-security-rules.md`: "I must encrypt sensitive data and use HTTPS" -3. Reads `knowledge/pci-compliance-rules.md`: "I must never log credit card numbers" -4. References `specs/stripe-api-contract.yaml`: "Here's how to integrate with the Stripe API" -5. Executes `skills/generate-api-tests`: "Now I'll generate comprehensive test coverage" -6. Executes `skills/security-audit`: "Finally, I'll verify no security vulnerabilities" - ---- - -## Key Takeaway - -**Keep Agentic Beacon focused on reusable artifacts** (knowledge, skills, contexts) and **leave feature-specific specs in local project repositories**. - -This keeps the warehouse a lean, highly reusable library of agentic intelligence rather than a dumping ground for every project's feature requirements. - ---- - -## See Also - -- [How It Works](how-it-works.md) — the warehouse / beacon mental model -- [Artifact Types](artifact-types.md) — the four artifact types and how each is wired -- [beacon.yaml Reference](../reference/beacon-yaml.md) — how to declare artifact dependencies diff --git a/site-docs/guides/advanced-patterns.md b/site-docs/guides/advanced-patterns.md deleted file mode 100644 index 8387bef..0000000 --- a/site-docs/guides/advanced-patterns.md +++ /dev/null @@ -1,202 +0,0 @@ -# Advanced Patterns - -Glob syntax, sync flags, the warehouse status workflow, and artifact lifecycle management. - -## Glob Pattern Syntax - -Patterns in `beacon.yaml` are matched against the warehouse root. Only files (not directories, except skills) are matched. - -### Supported Syntax - -| Pattern | Matches | -|---------|---------| -| `contexts/teams/backend/AGENTS.md` | Exact file | -| `contexts/teams/*/AGENTS.md` | One `AGENTS.md` per team subdirectory | - -### Practical Examples - -```yaml -artifacts: - skills: - # Skills are declared at directory level - - skills/code-review/ - - skills/generate-tests/ - - contexts: - - contexts/global.md - - contexts/teams/*/AGENTS.md -``` - -**Knowledge is auto-derived** — not declared in `beacon.yaml`. Markdown links in contexts and skills (e.g. `[guide](knowledge/python/type-hints.md)`) are automatically resolved and synced. - -### Debugging Unmatched Patterns - -If a pattern matches nothing, `abc sync` warns but does not fail: - -``` -Warning: No files matched pattern: contexts/nonexistent.md -``` - -Debug by listing the warehouse directory: - -```bash -ls /path/to/warehouse/contexts/ -``` - ---- - -## The Warehouse Status Workflow - -`abc warehouse status` shows modifications to warehouse files tracked by resolved artifacts. Since artifacts are symlinks into the warehouse clone, editing an artifact directly modifies the warehouse working tree. - -### Summary View - -```bash -abc warehouse status -``` - -``` -Modified files: - modified knowledge/python/type-hints.md - modified knowledge/python/async-patterns.md - added knowledge/python/new-lesson.md - untracked skills/new-skill/SKILL.md -``` - -**Status meanings:** - -| Status | Meaning | -|--------|---------| -| `modified` | File exists in warehouse and has been changed | -| `added` | New file staged for commit | -| `deleted` | File staged for removal | -| `untracked` | New file not yet tracked by git | - -### Detailed Diff - -```bash -abc warehouse status knowledge/python/type-hints.md -``` - -Shows a line-by-line unified diff. - -### Full Status - -For unfiltered status including files not tracked by `beacon.yaml`: - -```bash -abc warehouse status --all -``` - ---- - -## Sync Flags in Practice - -### Starting fresh - -```bash -abc reset -# or -abc sync --force -``` - -Force-overwrites all artifacts from the warehouse. Use `abc warehouse status` first if you want to review any local changes. - -### Non-interactive resolve - -If there are conflicts between local and warehouse files: - -```bash -abc sync --contribute-local # auto-contribute local modifications -abc sync --discard-local # auto-discard local changes -``` - -### Removing stale artifacts - -After removing entries from `beacon.yaml`, the old symlinks are automatically removed as orphans: - -```bash -# Edit beacon.yaml to remove a skill -vim .agentic-beacon/beacon.yaml -abc sync -# → Removed: 1 orphan symlink(s) no longer in beacon.yaml -``` - -Or clean everything and re-sync: - -```bash -abc clean # remove entire artifacts directory -abc sync # re-sync only what's currently declared + derived -``` - ---- - -## Keeping Artifacts Up to Date - -The recommended update workflow: - -```bash -# 1. Pull warehouse updates -cd ~/team-warehouse -git pull - -# 2. Check what changed in warehouse working tree -cd my-project -abc warehouse status - -# 3. Contribute any local changes -abc warehouse contribute -m "Update python standards for 3.12+" - -# 4. Re-sync -abc sync -``` - ---- - -## Syncing Agents - -Agents are wired into project-local tool directories as part of `abc sync`: - -```bash -abc sync -``` - -Declare agents in `beacon.yaml` first (via `abc adopt` or manually), then `abc sync` wires them into `.claude/agents/` and `.opencode/agents/` inside the project root. - -### Listing installed artifacts - -```bash -abc list # all synced artifacts (contexts, skills) -abc list agents # project-scoped agents from .agentic-beacon/artifacts/agents/ -abc list skills # synced skills -abc list contexts # synced contexts -``` - ---- - -## Validate Your Setup - -```bash -abc doctor -``` - -Checks: -- Warehouse connection is valid -- `beacon.yaml` is well-formed -- All declared artifacts exist in the warehouse -- No stale paths from old schema versions -- Skill frontmatter dependencies are satisfied - -Use `--fix` to automatically migrate stale paths: - -```bash -abc doctor --fix -``` - ---- - -## Next Steps - -- **[beacon.yaml Reference](../reference/beacon-yaml.md)** — full schema documentation -- **[CLI Reference](../reference/cli.md)** — all commands and flags -- **[Contributing Back](contributing-back.md)** — the contribution workflow diff --git a/site-docs/guides/connecting-projects.md b/site-docs/guides/connecting-projects.md deleted file mode 100644 index 0450fc4..0000000 --- a/site-docs/guides/connecting-projects.md +++ /dev/null @@ -1,160 +0,0 @@ -# Connecting a Project - -Once a warehouse exists, connect your project to it and declare which artifacts you need. - -## Prerequisites - -- A warehouse repository (local path) -- `abc` installed (`uv tool install agentic-beacon`) -- An existing project directory - ---- - -## Step 1: Clone the Warehouse Locally - -```bash -git clone git@github.com:your-org/warehouse.git ~/my-org-warehouse -``` - -The warehouse must be present locally — `abc sync` reads directly from the filesystem. - ---- - -## Step 2: Connect Your Project - -```bash -cd my-project -abc warehouse connect --path ~/my-org-warehouse -``` - -This creates `.agentic-beacon/config.toml` (gitignored) pointing to the warehouse: - -```toml -[warehouse] -local_path = "/Users/you/my-org-warehouse" -``` - -Expected output: -``` -✓ Warehouse structure validated -✓ Connected to warehouse - Location: /Users/you/my-org-warehouse - -Next Steps: - 1. Run 'abc setup' to configure artifacts - 2. Run 'abc sync' to sync artifacts -``` - ---- - -## Step 3: Select Artifacts - -### Option A: Interactive TUI (Recommended) - -```bash -abc adopt -``` - -Opens a TUI where you browse artifacts grouped by type. Press `Space` to select, `Enter` to confirm. Writes selections to `beacon.yaml` automatically. - -→ **[Interactive Adoption](interactive-adoption.md)** for full details. - -### Option B: Manual configuration - -```bash -abc setup -``` - -Creates a `beacon.yaml` template at `.agentic-beacon/beacon.yaml`. Edit it manually to declare which contexts, skills, and agents you need: - -```yaml -artifacts: - skills: - - skills/code-review/ - - contexts: - - contexts/global.md - - agents: - - agents/code-reviewer.md -``` - -**Knowledge is auto-derived** — knowledge files referenced by markdown links in your contexts and skills are synced automatically. No manual knowledge configuration needed. - ---- - -## Step 4: Sync - -```bash -abc sync -``` - -Reads `beacon.yaml`, resolves skill→context dependencies via frontmatter, auto-derives knowledge from markdown links, and performs the full sync: - -- **Contexts** → symlinked into `.agentic-beacon/artifacts/contexts/` and wired into `CLAUDE.md` or `opencode.json` -- **Skills** → symlinked into `.agentic-beacon/artifacts/skills/` and installed into each detected tool's directories -- **Knowledge** → auto-derived from markdown links and symlinked into `.agentic-beacon/artifacts/knowledge/` -- **Agents** → declared per-project in `beacon.yaml` and wired into project-local `.claude/agents/` and `.opencode/agents/` symlinks - ---- - -## Step 5: Commit beacon.yaml - -```bash -git add .agentic-beacon/beacon.yaml -git commit -m "chore: add beacon.yaml artifact dependencies" -``` - -Teammates clone the repo, run `abc warehouse connect`, and `abc sync` to get the same artifacts. - ---- - -## What Gets Committed to Git - -``` -✅ .agentic-beacon/beacon.yaml — commit this -❌ .agentic-beacon/config.toml — gitignored (local path) -❌ .agentic-beacon/artifacts/ — gitignored (symlink tree) -``` - -The `.gitignore` entries are added automatically by `abc warehouse connect` and `abc sync`. - ---- - -## Keeping Artifacts Updated - -When the warehouse changes: - -```bash -# Pull warehouse updates -cd ~/my-org-warehouse && git pull - -# Re-sync your project -cd my-project && abc sync -``` - -Sync is idempotent — only changed files are updated. - ---- - -## Verifying Your Setup - -```bash -abc status -``` - -Shows the connected warehouse, configured contexts and skills (with ✓/✗ for synced status), and total synced file count. - -```bash -abc doctor -``` - -Validates the full setup — connection, `beacon.yaml` validity, missing artifacts. Use `--fix` to auto-migrate stale paths. - ---- - -## Next Steps - -- **[beacon.yaml Reference](../reference/beacon-yaml.md)** — full configuration schema -- **[Syncing Artifacts](syncing.md)** — sync flags and behavior -- **[Interactive Adoption](interactive-adoption.md)** — the `abc adopt` TUI diff --git a/site-docs/guides/day-to-day-workflow.md b/site-docs/guides/day-to-day-workflow.md index 4c8cf0f..401cb54 100644 --- a/site-docs/guides/day-to-day-workflow.md +++ b/site-docs/guides/day-to-day-workflow.md @@ -54,7 +54,7 @@ No extra setup needed — everything is in place after `abc sync`. ### Example: agent improves a knowledge file mid-session You ask the agent to document a new error handling pattern. It writes the explanation -directly into `artifacts/contexts/knowledge/error-handling.md`. Because that file +directly into `artifacts/knowledge/python/error-handling.md`. Because that file is a symlink into your warehouse clone, the warehouse working tree is updated immediately. No copy step needed — the improvement is already in the warehouse. @@ -134,17 +134,14 @@ Leave `skills/code-review/SKILL.md` unstaged if you're not ready to share that c ### Discard a change you don't want to keep +A common case: you ran `abc warehouse status` and find two modified files, but only one is the change you intended. The other is a stray edit from earlier in the session — perhaps the agent retitled a skill in passing. Discard it from the warehouse clone: + ```bash cd ~/team-warehouse git checkout -- skills/code-review/SKILL.md ``` -The symlink reflects the restored file immediately in your project. - ---- - -!!! tip "Want a full walkthrough?" - **[Tutorial: Your First Contribution](../tutorials/first-contribution.md)** — step-by-step from morning sync to pushing an improvement back to the warehouse. +The symlink reflects the restored file immediately in your project — no further sync needed. --- @@ -157,25 +154,7 @@ abc doctor # full validation; --fix to auto-resolve stale paths --- -## Quick Reference - -| Situation | Command | -|-----------|---------| -| Pull warehouse updates | `cd ~/warehouse && git pull && cd project && abc sync` | -| Discover new artifacts | `abc adopt` | -| Review warehouse changes | `abc warehouse status` | -| Review a specific file diff | `abc warehouse status ` | -| Contribute all changes | `abc warehouse contribute -m "message"` | -| Contribute and push | `abc warehouse contribute -m "message" --push` | -| Contribute selectively | `cd ~/warehouse && git add && git commit` | -| Discard a change | `cd ~/warehouse && git checkout -- ` | -| Check project health | `abc status` | -| Diagnose issues | `abc doctor` | - ---- - ## Next Steps - **[Contributing Back](contributing-back.md)** — contribution workflow in depth -- **[Advanced Patterns](advanced-patterns.md)** — glob patterns and advanced configuration -- **[Team Collaboration](team-collaboration.md)** — coordinating across a team +- **[CLI Reference](../reference/cli.md)** — every flag for `sync`, `warehouse status`, `warehouse contribute` diff --git a/site-docs/guides/warehouse-lint/github-actions.md b/site-docs/guides/warehouse-lint/github-actions.md index 14fd9ff..17d6892 100644 --- a/site-docs/guides/warehouse-lint/github-actions.md +++ b/site-docs/guides/warehouse-lint/github-actions.md @@ -77,7 +77,7 @@ That's it. The workflow: ### Why `uv tool install agentic-beacon` instead of `pip install` -Per the project's [Python standards](../../concepts/how-it-works.md) and AGENTS.md, `uv` is the canonical Python toolchain. `uv tool install` creates an isolated environment for the CLI and exposes `abc` on `PATH` — same shape as `pipx install`, but inside the `uv` ecosystem the runner is already set up for. +`uv tool install` creates an isolated environment for the CLI and exposes `abc` on `PATH` — same shape as `pipx install`, but `uv` is the toolchain Beacon itself uses for development and CI. ### Why no version pin in `uv tool install agentic-beacon` diff --git a/site-docs/reference/cli.md b/site-docs/reference/cli.md index d771c2d..4ec8e49 100644 --- a/site-docs/reference/cli.md +++ b/site-docs/reference/cli.md @@ -89,6 +89,7 @@ abc warehouse contribute -m MESSAGE [OPTIONS] |--------|-------------| | `-m, --message TEXT` | Commit message (required) | | `--push` | Push the commit to the remote after committing | +| `--paths TEXT` | Warehouse-relative path to commit (repeatable). When omitted, commits all `beacon.yaml`-tracked dirty paths. | Stages and commits files tracked by `beacon.yaml` that have uncommitted changes in the warehouse clone. @@ -96,6 +97,8 @@ Stages and commits files tracked by `beacon.yaml` that have uncommitted changes ```bash abc warehouse contribute -m "Update python standards" abc warehouse contribute -m "Fix typo" --push +abc warehouse contribute -m "Update skill" --paths skills/foo/SKILL.md +abc warehouse contribute -m "Split commit" --paths a.md --paths b.md ``` --- @@ -246,6 +249,7 @@ abc sync [OPTIONS] | `--skip-git-check` | Skip warehouse git state validation | | `--contribute-local` | Non-interactive: contribute all modified local files to warehouse | | `--discard-local` | Non-interactive: discard all modified local files and replace with symlinks | +| `--yes` | Auto-accept adding missing agent-required skills to `beacon.yaml` | **What sync does per artifact type:** diff --git a/site-docs/tutorials/first-contribution.md b/site-docs/tutorials/first-contribution.md deleted file mode 100644 index 602e724..0000000 --- a/site-docs/tutorials/first-contribution.md +++ /dev/null @@ -1,193 +0,0 @@ -# Tutorial: Your First Contribution - -This tutorial walks through a realistic day using Agentic Beacon — from pulling the morning's warehouse updates to contributing an improvement back to your team. - -**What you'll do:** - -1. Pull warehouse updates and sync your project -2. Run a coding session where the agent improves an artifact -3. Review what changed -4. Contribute the improvement back -5. Verify your teammates can pick it up - -**Prerequisites:** You've already [connected your project](../guides/connecting-projects.md) and run `abc sync` at least once. - ---- - -## Setup - -In this tutorial you're working on `payments-service`. Your team warehouse lives at `~/team-warehouse`. - -``` -~/team-warehouse/ ← shared warehouse (git repo) -~/projects/payments-service/ ← your project (connected via beacon.yaml) -``` - ---- - -## Step 1: Pull the Morning's Updates - -A teammate added a new SQL review skill overnight. Pull it into the warehouse and sync: - -```bash -cd ~/team-warehouse && git pull -``` - -``` -remote: Enumerating objects: 6, done. -Updating abc1234..def5678 - skills/sql-review/SKILL.md | 47 ++++++++++++++++++++++++++++++++++++ - 1 file changed, 47 insertions(+) -``` - -```bash -cd ~/projects/payments-service && abc sync -``` - -``` -✓ Sync complete - Updated: 1 symlink (skills/sql-review/SKILL.md) - Up to date: 11 symlinks -``` - -The SQL review skill is now available to your agent as `/sql-review`. - ---- - -## Step 2: Code with Your Agent - -You open your editor, start a Claude Code session, and ask it to review a new migration file. - -The agent runs `/sql-review` and flags a decimal precision issue. You fix the migration together, then ask the agent to document the pattern for the team: - -> *"Add a note to our error-handling knowledge file about using `NUMERIC(19,4)` for financial amounts."* - -The agent opens `.agentic-beacon/artifacts/contexts/knowledge/error-handling.md` and adds the section. Because that file is a **symlink into the warehouse**, the warehouse working tree is updated immediately — no copy step. - ---- - -## Step 3: Review What Changed - -After the session, check the warehouse: - -```bash -abc warehouse status -``` - -``` -Modified files in warehouse: - modified knowledge/python/error-handling.md - modified skills/sql-review/SKILL.md -``` - -Two files changed. You only authored the `error-handling.md` addition — the `sql-review` change must be a stray edit from earlier in the session. - -Inspect each one: - -```bash -abc warehouse status knowledge/python/error-handling.md -``` - -```diff ---- a/knowledge/python/error-handling.md -+++ b/knowledge/python/error-handling.md -@@ -38,3 +38,12 @@ - ## Connection timeouts - - Always set an explicit timeout on httpx clients. Default is `None` (blocks forever). -+ -+## Financial amounts -+ -+Always use `NUMERIC(19,4)` (or Python `Decimal`) for monetary values. -+Never use `FLOAT` or `DOUBLE` — binary floating point cannot represent -+decimal fractions exactly, which causes rounding errors in summations. -+ -+```python -+from decimal import Decimal -+total = Decimal("0.00") -+``` -``` - -Looks good. Now check the SQL review skill: - -```bash -abc warehouse status skills/sql-review/SKILL.md -``` - -```diff ---- a/skills/sql-review/SKILL.md -+++ b/skills/sql-review/SKILL.md -@@ -1,4 +1,4 @@ --# SQL Review -+# SQL Review Skill -``` - -Just a title casing change — not worth a commit on its own. Discard it: - -```bash -cd ~/team-warehouse -git checkout -- skills/sql-review/SKILL.md -``` - ---- - -## Step 4: Contribute the Improvement - -Commit just the `error-handling.md` change: - -```bash -cd ~/team-warehouse -git add knowledge/python/error-handling.md -git commit -m "docs: document NUMERIC(19,4) rule for financial amounts" -git push -``` - -``` -[main 9f3c21a] docs: document NUMERIC(19,4) rule for financial amounts - 1 file changed, 11 insertions(+) -``` - -Alternatively, use `abc warehouse contribute` to stage-and-commit everything tracked by `beacon.yaml` in one step: - -```bash -abc warehouse contribute -m "docs: document NUMERIC(19,4) rule for financial amounts" --push -``` - -Both produce the same result. Use whichever fits your flow — plain git gives you more granular control; `abc warehouse contribute` is faster when you want to ship everything at once. - ---- - -## Step 5: Verify Your Teammates Can Pick It Up - -Anyone on the team can now get your change: - -```bash -cd ~/team-warehouse && git pull -cd my-project && abc sync -``` - -``` -✓ Sync complete - Updated: 1 symlink (knowledge/python/error-handling.md) - Up to date: 11 symlinks -``` - -Their agent picks up the new financial amounts rule on the next session — no manual steps. - ---- - -## What You Learned - -- `abc sync` updates symlinks when the warehouse changes — re-run it after every `git pull` -- Editing a synced artifact **is** editing the warehouse; no copy step needed -- `abc warehouse status` scopes to files tracked by `beacon.yaml`, not the entire warehouse -- Use plain git inside the warehouse for selective commits; use `abc warehouse contribute` for convenience -- Discarding an unwanted change is just `git checkout -- ` in the warehouse - ---- - -## Next Steps - -- **[Contributing Back](../guides/contributing-back.md)** — reference guide for the full contribute workflow -- **[Day-to-Day Workflow](../guides/day-to-day-workflow.md)** — the loop in summary form -- **[Creating Skills](../guides/creating-skills.md)** — write a new skill and contribute it to the warehouse