docs(adr): triage, rewrite, and renumber ADRs for clean slate

Complete ADR refactoring for issue #15:

## Changes

1. **Triage archival** — deleted chunk-era ADRs (0001–0003, 0006–0011, 0013); kept active decisions (0004, 0005, 0012, 0014+)
2. **ADR-0004 rewrite** — now reflects plugin-based skill distribution (`plugins/<name>/skills/` + `claude plugin install`) instead of monolithic `.agents/skills/` deployment
3. **Renumber to 0001–0009** — sequential clean slate after archival; all cross-references updated
4. **Content audit** — verified all 9 remaining ADRs for alignment with plugin model, removed stale chunk/deployment language

Kept ADRs: 0001–0009
- 0001: Skills distributed via plugins
- 0002: Two-tier CLAUDE.md (always-on + on-demand)
- 0003: AGENTS.md as provider-agnostic entry point
- 0004: INFO finding level in skill-audit
- 0005: agent-author dual provider scaffold
- 0006: Plugin version parity (version in both manifests)
- 0007: Gitea as exclusive issue tracker
- 0008: agent-audit single-file invocation
- 0009: agent-audit field inventory reference

All decisions are active and aligned with current repository state (marketplace/plugin model).

Closes #15 (ADR section of acceptance criteria)
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

docs/adr/0001-pull-distribution-model.md

@@ -1,3 +0,0 @@
-# Pull distribution model
-
-Projects pull config updates from this repo consciously rather than receiving automatic pushes. We chose pull because it keeps projects in control of when they take updates — a silent push could break a project mid-sprint with no warning. Pull also scales cleanly from solo homelab to open source: anyone can fork this repo and projects remain decoupled from the origin. The trade-off is that stale projects are invisible until they pull; push would make fleet drift detectable earlier, which is why fleet sync tooling (Phase 2) revisits this at the network layer, not at the file distribution layer.

docs/adr/0001-skills-in-agents-dir.md

@@ -0,0 +1,15 @@
+# Skills are distributed via plugins, not monolithic repo deployment
+
+Skills (slash commands) are authored and distributed as part of **plugins** — each plugin contains its own `skills/` directory alongside agents and other artifacts. Plugins are installed via `claude plugin install <name>@holocron` rather than deployed from the repo's local tree. This decision decouples skill authoring cadence from core provider deployments and allows independent versioning per plugin.
+
+## Context
+
+Initially, skills were stored in a single `.agents/skills/` directory and deployed universally via `install.sh`. This created a coupling problem: shipping a new skill required shipping an entire repo release, and skill updates were pinned to provider version releases. As the skill library grew, independent skill shipping became essential.
+
+## Consequences
+
+- Skills are now co-located with their associated agents and infrastructure in `plugins/<name>/`. Logically related skills ship together; independent skills can ship on independent cadences.
+- `claude plugin install` handles installation, versioning, and updates — no need for shell deployment logic in `install.sh`.
+- Repositories that use skills from this project declare plugin dependencies in their `claude.plugin.json` manifest or install via the CLI.
+- Providers that do not natively understand `claude plugin install` (hypothetically) would need a custom adapter to fetch from the Holocron marketplace — deferred concern, not yet needed.
+- A skill in one plugin does not block a breaking change in another plugin.

docs/adr/0002-copy-not-symlink.md

@@ -1,3 +0,0 @@
-# Copy files, not symlinks or submodules
-
-Content is deployed by copying files, not symlinking or using git submodules. Symlinks break if this repo moves or is renamed; submodules require git tooling everywhere a project runs — including on machines where this repo may not be cloned at all. Copying means a deployed project works in complete isolation from this repo's location or existence. The cost is that updates are opt-in (consistent with ADR-0001) and no automatic change detection exists. This is intentional: silent changes are a worse failure mode than stale configs.

docs/adr/0003-agents-md-provider-agnostic-entry-point.md

@@ -4,8 +4,8 @@
 
 Claude Code reads `CLAUDE.md` natively, not `AGENTS.md`. The Anthropic documentation explicitly recommends the import pattern for repos that use `AGENTS.md` for other tools: `CLAUDE.md` contains `@AGENTS.md` and appends Claude Code-specific content below. This means `CLAUDE.md` continues to exist as the Claude Code entry point but carries no original content — it is purely an adapter.
 
-`AGENTS.md` must be self-contained: no `@import` syntax (which is Claude Code-specific and would make the file provider-specific). On-demand instruction loading via `@import` stays in the Claude Code adapter (`CLAUDE.md`), pointing to `core/instructions/` as today. The `core/` deployment path (`~/.claude/core/`) is unchanged in this chunk; migration to `~/.agents/` is deferred to Chunk 7 when a second provider (Copilot) provides evidence of what that provider needs.
+`AGENTS.md` must be self-contained: no `@import` syntax (which is Claude Code-specific and would make the file provider-specific). On-demand instruction loading via `@import` stays in the Claude Code adapter (`CLAUDE.md`), pointing to `core/instructions/` as today. The `core/` deployment path (`~/.claude/core/`) reflects the current provider deployment model.
 
-This partially supersedes ADR-0005 (two-tier CLAUDE.md model). ADR-0005 established the always-on / on-demand split and remains correct as a structural pattern. What changes is where the always-on content lives: previously in `providers/claude-code/CLAUDE.md`, now in `AGENTS.md`. The adapter layer ADR-0005 described still exists; `CLAUDE.md` is now the adapter rather than the source.
+This partially supersedes ADR-0002 (two-tier CLAUDE.md model). ADR-0002 established the always-on / on-demand split and remains correct as a structural pattern. What changes is where the always-on content lives: previously in `providers/claude-code/CLAUDE.md`, now in `AGENTS.md`. The adapter layer ADR-0002 described still exists; `CLAUDE.md` is now the adapter rather than the source.
 
-The alternative — keeping always-on content in `providers/claude-code/CLAUDE.md` — was rejected because it violates ADR-0003 (provider-agnostic core). Content that applies to all agents regardless of provider has no business living in a provider-specific file. When Copilot arrives in Chunk 7, duplicating that content into a Copilot adapter or maintaining two sources of the same rules is exactly the drift ADR-0003 was written to prevent.
+The alternative — keeping always-on content in `providers/claude-code/CLAUDE.md` — was rejected because it violates the provider-agnostic principle: content that applies to all agents regardless of provider has no business living in a provider-specific file. When multiple providers exist, duplicating that content into a separate adapter or maintaining two sources of the same rules creates drift and inconsistency.

docs/adr/0003-provider-agnostic-core.md

@@ -1,3 +0,0 @@
-# Provider-agnostic core with thin adapters
-
-`core/` uses plain imperative markdown — no tool names, provider APIs, or format assumptions. Provider-specific translations live in `providers/<name>/`. The alternative was provider-specific content everywhere, which means adding a second provider (Copilot, Cursor) requires rewriting all content from scratch rather than writing a thin adapter. The cost is a translation layer: content must be kept abstract enough to survive adaptation, which sometimes means less tool-specific precision in the core. Where precision matters more than portability, it belongs in `providers/`, not `core/`.

docs/adr/0004-skills-in-agents-dir.md

@@ -1,5 +0,0 @@
-# Skills live in .agents/skills/, not .claude/skills/
-
-Skills (slash commands) are stored in `.agents/skills/` following the [Agent Skills open standard](https://agentskills.io), not in `.claude/skills/` which is a Claude Code-specific location. Putting skills in `.claude/skills/` would make them Claude Code-only and contradict ADR-0003 (provider-agnostic where possible). Skills are the strongest shared primitive across providers — they should live at the most portable location available.
-
-`install.sh` deploys skills to `~/.agents/skills/` as the single canonical location. Providers that do not read `~/.agents/skills/` natively declare a symlink adapter in `providers/<name>/provider-manifest.sh`; `install.sh` discovers and creates these automatically. Claude Code is one such provider — it reads `~/.claude/skills/` natively, so it gets a `~/.claude/skills/ → ~/.agents/skills/` symlink. See ADR-0007 for the rationale behind using symlinks for provider adapters.

docs/adr/0006-install-always-overwrites.md

@@ -1,5 +0,0 @@
-# install.sh always overwrites deployed files
-
-`install.sh` overwrites `~/.claude/` and `~/.claude/core/` unconditionally on every run. It does not merge, diff, or ask. The rationale: the source of truth is this repo. Editing deployed files directly is a usage error — `sync.sh` would overwrite those edits on the next pull anyway. Offering a merge path would imply that editing `~/.claude/CLAUDE.md` directly is a supported workflow, which it is not. If a local customisation is needed it belongs in a project-level override file, not in the deployed global config.
-
-**Exception — skills**: `~/.agents/skills/` uses a merge-per-skill strategy. Each skill directory from `.agents/skills/` is replaced individually; the parent directory is never wiped. This preserves user-installed skills from other sources alongside the skills managed by this repo. The overwrite-always principle still holds for each individual managed skill — the per-skill replace is unconditional.

docs/adr/0007-gitea-canonical-issue-tracker.md

@@ -1,5 +1,7 @@
 # Gitea is the exclusive issue tracker — file-based fallback removed
 
+**Supersedes:** ADR-0011 (provider-agnostic issue tracker with file-based default — archived during refactoring)
+
 ADR-0011 established a provider-agnostic model with `docs/issues/NNNN-<slug>.md` as the file-based default, switching to Gitea MCP at runtime when available. The interim model was justified because Gitea would not be configured until after Chunk 3, and the repo needed to work before then.
 
 Gitea is now configured and in active use. The condition in ADR-0011 has been met. This ADR supersedes it.

docs/adr/0007-provider-adapters-as-symlinks.md

@@ -1,9 +0,0 @@
-# Provider skill adapters are symlinks, not copies
-
-Provider skill adapters — the mechanism that makes `~/.agents/skills/` visible to a provider that reads a different path — are implemented as symlinks, not file copies. This is a deliberate exception to ADR-0002 (copy-not-symlink), which applies to content files. Adapters are infrastructure, not content.
-
-**Why symlinks here:** a provider adapter has no content of its own — it is purely a pointer to the canonical location. Copying would create a second source of truth and require install.sh to keep two directories in sync; any drift between them would be a silent bug. A symlink makes the relationship explicit and eliminates the sync problem entirely.
-
-**Why ADR-0002 still holds for content:** ADR-0002's concern is that symlinks break if this repo moves. Provider adapters point to `~/.agents/skills/`, not into this repo — they survive repo relocation without modification.
-
-Each provider that cannot read `~/.agents/skills/` natively declares its adapter path in `providers/<name>/provider-manifest.sh`. `install.sh` discovers all provider manifests and creates the symlinks. A provider that reads `~/.agents/skills/` natively needs no entry. If the adapter target already exists as a real directory, install.sh emits a warning and leaves it intact rather than destroying user data.

docs/adr/0008-factory-boundary.md

@@ -1,7 +0,0 @@
-# This repo is a provider of factory tooling, not a factory instance
-
-This repo ships skills, governance, and conventions to project repos — it does not itself adopt the full factory structure (LESSONS.md, docs/spec/, eval infrastructure, references/) as if it were a software project using the factory. Conflating the two layers would mix config-delivery concerns with application concerns, make the repo harder to upgrade (changes to the factory shape would break all consumers simultaneously), and obscure what is a global primitive vs. what is project-specific.
-
-Exception: artefacts also needed while building *this repo itself* are added here in addition to being scaffolded for project repos. LESSONS.md and docs/spec/ qualify — this repo undergoes active development and benefits from the same feedback and spec hygiene it ships to others. This exception is bounded: it applies only when the artefact genuinely serves the repo's own development, not to import the full factory shape by default.
-
-Orchestration agents (cross-project automation) are a natural future extension at Chunk 5, not a reason to change the provider boundary now.

docs/adr/0009-flat-skill-taxonomy.md

@@ -1,7 +0,0 @@
-# Flat skill directories with category metadata, not nested paths
-
-Skills are stored as flat directories directly under `.agents/skills/` (`grill-me/SKILL.md`, not `design/grill-me/SKILL.md`). Category organisation is expressed via `metadata: category:` in each SKILL.md frontmatter rather than directory nesting.
-
-Nested paths were evaluated and rejected for three reasons. First, Claude Code discovers skills exactly one level deep under `~/.claude/skills/` — a skill at `~/.claude/skills/design/grill-me/SKILL.md` is invisible to the tool. Second, the agentskills.io open standard specifies that the `name` field must match the parent directory name, implying a flat structure at the skills root; no nested discovery is defined in the spec. Third, `install.sh` iterates `for skill_dir in .agents/skills/*/` — one level only; nested paths would require a traversal rewrite before a single nested skill could be deployed.
-
-Category metadata achieves the same organisational goals: the Management App can group skills by category, a generated README can cluster them, and the category is machine-readable for tooling — all without path changes, pipeline changes, or deviation from the open standard. If Claude Code adds nested discovery in a future release, paths can be restructured then with evidence rather than speculatively now.

docs/adr/0010-role-skills-vs-subagents.md

@@ -1,7 +0,0 @@
-# Role skills in .agents/skills/, core/agents/ reserved for subagent definitions
-
-Role skills (Architect, Developer, Reviewer, Security, QA, Ops) live in `.agents/skills/` with `category: roles`. They are ordinary skills that activate a cognitive mode in the current conversation — loaded on trigger, follow the standard SKILL.md authoring format, and use the same deployment pipeline as every other skill. Placing them in a separate `core/agents/` directory would require a distinct deployment path, a distinct provider adapter, and a distinct discovery mechanism for no functional gain.
-
-`core/agents/` is reserved for a distinct content type: provider-agnostic subagent definitions that run in isolated execution contexts (`context: fork` in Claude Code terms). These are skills or agents that need a fresh context window, a dedicated system prompt, and no access to the parent conversation history. The Claude Code adapter translates `core/agents/` definitions to `.claude/agents/`. This is structurally different from a role skill that loads inline — the isolation boundary is the defining characteristic, not the cognitive mode.
-
-The factory research conflates these two into a single `roles/` skill category. The distinction matters here because Claude Code's subagent execution model is meaningfully different from skill activation, and the provider adapter pattern requires them to be in separate source locations to translate correctly.

docs/adr/0011-provider-agnostic-issue-tracker.md

@@ -1,11 +0,0 @@
-# Provider-agnostic issue tracker with file-based default and provider adapters
-
-Skills and workflows reference a "linked issue" generically rather than coupling to a specific issue tracker. In the file-based phase, an issue is a `docs/issues/NNNN-<slug>.md` file. When a provider MCP (e.g. Gitea MCP) is configured, skills detect it at runtime and use it instead. The active backend is determined by MCP availability — no config flag required. "Issue" is the canonical cross-provider term; GitHub, GitLab, and Gitea all use it natively.
-
-Gitea-specific skills (`setup-gitea-mcp`, `post-pr-review`, `create-issue`) are a provider adapter at `providers/gitea/` — structurally identical to how `providers/claude-code/` adapts core content for Claude Code. They are not part of the core skill library.
-
-Two alternatives were rejected. Gitea-specific skills in the core library would block use before Gitea is configured and embed a provider assumption into skills that are otherwise provider-neutral. Per-provider skill variants (e.g. `implement-feature` + `implement-feature-gitea`) create maintenance overhead with no functional gain — the only difference is the issue lookup mechanism, not the skill logic.
-
-The file-based default was chosen because this repo must work before Gitea is set up. File-based issues are already the working convention (`docs/issues/`), established in Chunk 1. Gitea is the first concrete provider and will be configured after Chunk 3; existing file-based issues will be migrated at that point.
-
-This decision makes the skills library usable on any machine without external service dependencies, while keeping Gitea integration as a first-class path once available. The provider adapter pattern (`providers/gitea/`) is consistent with ADR-0007 (provider adapters as symlinks) and ADR-0008 (factory boundary).

docs/adr/0013-skill-author-merge.md

@@ -1,16 +0,0 @@
-# Merge skill-write and skill-improve into skill-author
-
-The kyberforge plugin shipped a factory trio: `skill-write` (create), `skill-improve` (apply signals), `skill-audit` (review). Write and improve both embed authoring quality guidance inline. As standards evolve — agentskills.io spec updates, shared scripts, future governance rules — each change requires updating both skills. Plugin cache isolation makes shared reference files unworkable: `../` paths break when a plugin is copied to its install cache, and the spec explicitly prohibits cross-skill file sharing. We therefore merge `skill-write` and `skill-improve` into a single `skill-author` skill.
-
-## Considered options
-
-**Mirror shared files (rejected)** — duplicate `references/body-discipline.md` and any shared scripts into both skill directories with a mirror comment, relying on convention to keep them in sync. Rejected because it compounds as standards grow: every new governance rule, every spec change, requires updating two files with no enforcement mechanism. The maintenance surface is small today but was judged unacceptable as a permanent pattern.
-
-**Status quo (rejected)** — accept that the two skills embed divergent authoring guidance. Rejected because the divergence is already observable: audit/improve loops oscillate (improve applies criteria slightly different from audit's, producing new findings on re-audit). Adding governance rules to both skills independently would worsen this.
-
-## Consequences
-
-- `skill-write` and `skill-improve` are deleted; invocations of `/skill-write` and `/skill-improve` break — users must switch to `/skill-author`.
-- `skill-audit`'s report footer references `/skill-improve`; that reference is now stale. Update deferred to a follow-on issue.
-- `skill-author` uses auto-detect routing: no existing directory → create flow; existing directory + improvement signals → improve flow; existing directory but no signals → ask.
-- Shared scripts (`scripts/new-skill.sh`), reference files, templates, and tests live in one directory. Future governance rules and spec updates have a single target.