Defame1297
3b5b1b5199
## 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
56 lines
3.8 KiB
Markdown
56 lines
3.8 KiB
Markdown
# Architecture
|
|
|
|
## Layered model
|
|
|
|
```
|
|
this repo (global defaults)
|
|
└── scripts/install.sh → ~/.claude/ (Claude Code config + content)
|
|
|
|
project repo (local overrides)
|
|
└── .claude/settings.json, CLAUDE.md (overrides global)
|
|
```
|
|
|
|
|
|
## Content deployment model
|
|
|
|
`scripts/install.sh` is a **deployer**, not a composer. It sources `scripts/deploy-manifest.sh` and deploys three categories:
|
|
|
|
- **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/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). 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.
|
|
|
|
This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for working in this repo. It imports `AGENTS.md` and `CONTEXT.md`, nothing more. This is distinct from `providers/claude-code/CLAUDE.md`, which is the global config deployed to `~/.claude/`.
|
|
|
|
## Provider model
|
|
|
|
`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.
|
|
|
|
## 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.
|