Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs(spec): remove overview.md, rewrite architecture.md for plugin model

Browse Source 
## Why
overview.md described the chunk-based delivery model, which is superseded
by the marketplace/plugin pivot. architecture.md was equally stale: it
described .agents/skills/ as the canonical skills source (directory does not
exist), a provider-manifest.sh symlink mechanism (never built), and sync.sh /
init-project.sh as existing scripts (Chunk 6, not yet built).

## Implementation Notes
- overview.md deleted; all cross-references scrubbed from AGENTS.md, CONTEXT.md,
  and three notes/research files
- architecture.md fully rewritten: content deployment model reflects actual
  install.sh behaviour (DEPLOY_FILES / DEPLOY_EXECUTABLES / DEPLOY_DIRS);
  plugin model section added listing all 5 plugins; directory structure section
  removed (was describing a layout that no longer exists)
- "Chunk 6" phase label → "planned"; "chunk workflow" removed from AGENTS.md
  description
- Fixed broken path docs/HUMANS.md → docs/wiki/HUMANS.md in governance layer
  and core/instructions/governance.md

Refs: #15
This commit is contained in:
Defame1297
2026-06-28 19:53:19 +00:00
parent 7a00368683
commit 3b5b1b5199
8 changed files with 18 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
docs/spec/architecture.md
View File

@@ -1,79 +1,45 @@
# Architecture
Current deployed architecture. Updated in the same PR as any structural change.
## Layered model
```
this repo (global defaults)
├── install.sh → ~/.agents/skills/ (canonical skills location)
├── install.sh → ~/.claude/skills/ (symlink → ~/.agents/skills/, Claude Code adapter)
└── install.sh → ~/.claude/ (Claude Code config + content)
└── scripts/install.sh → ~/.claude/ (Claude Code config + content)
project repo (local overrides)
└── .claude/settings.json, CLAUDE.md (overrides global)
```
Projects consume from this repo by pulling updates via `sync.sh` (Chunk 6). Until then, install is a one-time manual step.
## Directory structure
```
ai-development/
├── AGENTS.md # Provider-agnostic always-on rules for this repo; imported by repo CLAUDE.md
├── CONTEXT.md # Domain language, principles, glossary; auto-loaded at session start
├── docs/ # Workflow artifacts and issues (prd/, ard/, bug/, notes/, adr/, issues/, spec/) + research/ (raw research audit trail)
├── .agents/ # Agent Skills standard location (provider-agnostic)
│ ├── skills/ # SKILL.md files — canonical source, deployed to ~/.agents/skills/
│ └── evals/ # eval.yaml files for skills not yet in a plugin (cross-cutting/, implement/)
├── .claude-plugin/ # Marketplace manifest (both Claude Code and Copilot CLI read here)
│ └── marketplace.json # Declares all installable plugins in this repo
├── .github/plugin/
│ └── marketplace.json # Mirror of .claude-plugin/marketplace.json for Copilot CLI canonical path
├── plugins/ # Installable plugin units (each is a self-contained deployable)
│ └── kyberforge/ # Marketplace management toolkit (create-plugin, marketplace-architect, write-skill, write-eval)
├── core/ # Provider-agnostic source of truth
│ ├── AGENTS.md # Global always-on rules (Communication + Behavior); deployed to ~/.agents/AGENTS.md
│ ├── instructions/ # AI behavior definitions (plain markdown)
│ ├── agents/ # Agent role definitions
│ ├── workflows/ # Workflow definitions
│ └── prompts/ # Reusable prompt templates
├── providers/ # Provider-specific adapters
│ ├── claude-code/ # CLAUDE.md (thin adapter), settings.json, provider-manifest.sh
│ └── copilot/ # copilot-instructions.md, hooks, agents adapter
└── scripts/
├── deploy-manifest.sh # Source→target mappings; sourced by install.sh and sync.sh
├── install.sh # Deploys to ~/.agents/skills/, ~/.claude/, etc.
├── sync.sh # Pulls updates into an existing project
└── init-project.sh # Bootstraps a new or existing project
```
## Content deployment model
`install.sh` is a **deployer**, not a composer. It does not concatenate content into a single file. Instead:
`scripts/install.sh` is a **deployer**, not a composer. It sources `scripts/deploy-manifest.sh` and deploys three categories:
- `.agents/skills/` → `~/.agents/skills/` — canonical skills location; each skill dir is replaced individually (parent not wiped, user-added skills preserved)
- `core/AGENTS.md` → `~/.agents/AGENTS.md` — global always-on rules (Communication + Behavior); imported by `~/.claude/CLAUDE.md` via `@~/.agents/AGENTS.md`
- Provider adapters declared in `providers/*/provider-manifest.sh` — symlinks from the provider's skill path to `~/.agents/skills/`; e.g. Claude Code gets `~/.claude/skills/ → ~/.agents/skills/` because it reads `~/.claude/skills/` natively. Providers that read `~/.agents/skills/` directly need no adapter.
- `core/` → `~/.claude/core/` — workflows, prompts, agent definitions; agent reads on demand
- `providers/claude-code/settings.json` → `~/.claude/settings.json`
- `providers/claude-code/CLAUDE.md` → `~/.claude/CLAUDE.md` — thin adapter: imports `~/.agents/AGENTS.md` and `governance.md`; no original content
- **Files** (`DEPLOY_FILES`): `providers/claude-code/CLAUDE.md` → `~/.claude/CLAUDE.md`; `providers/claude-code/settings.json` → `~/.claude/settings.json`; `core/AGENTS.md` → `~/.agents/AGENTS.md`
- **Executables** (`DEPLOY_EXECUTABLES`): `providers/claude-code/statusline-command.sh` → `~/.claude/statusline-command.sh` (with `+x`)
- **Directories** (`DEPLOY_DIRS`): `core/` → `~/.claude/core/` (destination fully replaced on each deploy)
Skills are **not** deployed by `install.sh`. They are distributed as plugins and installed separately via `claude plugin install <name>@holocron`.
`~/.claude/CLAUDE.md` is a thin adapter, not a content source. It imports `~/.agents/AGENTS.md` (always-on rules) and `governance.md` (always-on governance), then lists the content index. All always-on content lives in `AGENTS.md` files so other providers can import the same source without duplication.
## Plugin model
Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`. Each plugin has a `plugin.json` manifest and is installed independently via `claude plugin install`.
## Governance layer
`core/instructions/governance.md` is the always-on governance instruction file. Unlike the on-demand instruction files in the content index, governance.md is loaded into every Claude session via `@import` in `providers/claude-code/CLAUDE.md`. This is a technical guarantee, not a behavioural instruction — `@import` causes Claude Code to expand and load the file at launch, before any interaction begins.
The governance layer has two phases:
- **Phase 1** (complete): instruction and documentation layer — `governance.md` loaded via `@import`; `docs/ai-constitution.md` and `docs/HUMANS.md` as human-facing reference; `CONTEXT.md` extended with governance domain language.
- **Phase 2** (Chunk 6): deterministic enforcement layer — pre-commit hooks, CI gates, secret scanning, licence scanning. Specified in `docs/research/governance_principles/CONTROLS.md`.
- **Phase 1** (complete): instruction and documentation layer — `governance.md` loaded via `@import`; `docs/ai-constitution.md` and `docs/wiki/HUMANS.md` as human-facing reference; `CONTEXT.md` extended with governance domain language.
- **Phase 2** (planned): deterministic enforcement layer — pre-commit hooks, CI gates, secret scanning, licence scanning. Specified in `docs/research/governance_principles/CONTROLS.md`.
## AGENTS.md pattern
This repo uses two `AGENTS.md` files as the provider-agnostic source of always-on rules (ADR-0012):
- **Repo-level `AGENTS.md`** — instructions for agents working inside this repo (structure, key rules, chunk workflow). Imported by repo `CLAUDE.md` via `@AGENTS.md`.
- **Repo-level `AGENTS.md`** — instructions for agents working inside this repo (structure, key rules). Imported by repo `CLAUDE.md` via `@AGENTS.md`.
- **Global `core/AGENTS.md`** — Communication and Behavior rules that apply across all projects. Deployed to `~/.agents/AGENTS.md`; imported by `~/.claude/CLAUDE.md` via `@~/.agents/AGENTS.md`.
Both `CLAUDE.md` files are thin adapters: they import from their respective `AGENTS.md` and add only Claude Code-specific syntax (`@import`, content index paths). They carry no original always-on content.
@@ -84,8 +50,6 @@ This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for
`core/` is never tool-specific. `providers/` is never shared. When adding a new provider, write an adapter in `providers/<name>/` that translates core content into the tool's expected format and location. The core content itself does not change.
Skills are the strongest shared primitive — the `SKILL.md` format and [Agent Skills open standard](https://agentskills.io) are cross-provider. Providers that don't read `~/.agents/skills/` natively declare a symlink adapter in `providers/<name>/provider-manifest.sh`; `install.sh` discovers and wires these up automatically.
## Architectural decisions
Key hard-to-reverse decisions are recorded as ADRs in `docs/adr/`. See the index there for rationale on choices like the pull distribution model, copy-not-symlink coupling, and the two-tier CLAUDE.md structure.