feat: deploy skills pipeline with provider adapter pattern

docs/ROADMAP.md

@@ -33,11 +33,11 @@ A parallel workstream (not a numbered chunk) that runs alongside the chunk seque
 |---|---|---|
 | ✅ 1 | Repo skeleton + `install.sh` — structure in place, Claude Code wired up | Nothing else can be built without the structure and install working |
 | ⏳ 2 | Core instructions — `coding.md`, `git.md` (incl. conventional commits), `testing.md`; communication rules in `providers/claude-code/CLAUDE.md` always-on section; retire `global.md`; migrate `docs/` to subdirectory-by-type naming | Instructions are the foundation everything else references; commit convention and doc naming must be in place before history accumulates |
-| 3 | First skills — initial slash commands for day-to-day use; changelog tooling (follow-on to Chunk 2 conventional commits); catalogue existing skills incl. `zoom-out` which is installed but undocumented | Skills are the most immediately useful output; validates the full pipeline |
+| ⏳ 3 | First skills — initial slash commands for day-to-day use; changelog tooling (follow-on to Chunk 2 conventional commits); catalogue existing skills incl. `zoom-out` which is installed but undocumented. **Infrastructure complete**: 12 skills deployed to `~/.agents/skills/` via `install.sh`; provider adapter pattern in place; remaining scope is content (changelog tooling, zoom-out docs, content index frontmatter) | Skills are the most immediately useful output; validates the full pipeline |
 | 4 | Workflows — formalize the workstream workflow (kick-off types → grill → artifact → issues → implement → QA → commit); feature, bug, architecture, improvement, feedback patterns | Higher-level patterns built on top of a working skills foundation; grill feedback intake design before starting |
 | 5 | Agents — role definitions (reviewer, architect, developer) | More abstract definitions; benefits from workflow patterns being established first |
 | 6 | Sync + project init tooling — `sync.sh` and `init-project.sh` | Tooling only makes sense once there is content worth syncing and scaffolding |
-| 7 | Copilot provider — adapter for GitHub Copilot | Second provider comes after the first is fully proven |
+| 7 | Copilot provider — adapter for GitHub Copilot. **Provider adapter pattern established**: `install.sh` auto-discovers `providers/*/provider-manifest.sh`; Copilot adapter is a new `providers/copilot/provider-manifest.sh` declaring a symlink if needed | Second provider comes after the first is fully proven |
 
 ## Development workflow
 
@@ -89,6 +89,7 @@ Items consciously not resolved — to be addressed in the relevant chunk PRD or
 ## Housekeeping reminders
 
 - **`.gitkeep` files** — placeholder files exist in `core/agents/`, `core/workflows/`, `core/prompts/`, `docs/ard/`, `docs/bug/`, `docs/notes/`. Remove each when the first real file is added to that directory. Each `.gitkeep` names the chunk that will populate it.
+- **Skills pipeline verified** — `install.sh` deploys 12 skills to `~/.agents/skills/` and creates `~/.claude/skills/ → ~/.agents/skills/` symlink adapter. Tested idempotent. `skills-lock.json` removed (was a manual artifact). If `~/.claude/skills/` exists as a real directory on a machine being migrated, remove it manually and re-run install.
 - **Chunk 2 behavioral tests** — 8 manual scenarios in `tests/test-instructions-and-docs.sh` (MANUAL TEST PLAN section) are pending verification. Must run in a fresh Claude session before Chunk 2 is fully verified. See instruction quality finding in `CONTEXT.md` for why these cannot be skipped.
 - **Governance Phase 1 behavioral tests** — manual test plan in `tests/test-governance-layer.sh` (MANUAL TEST PLAN section) is pending verification. Must run in a fresh Claude session before marking governance Phase 1 fully verified.
 - **AI ethics/security workstream** — `docs/notes/ai-ethics-security-principles.md` exploration note is superseded. Governance Phase 1 (`core/instructions/governance.md`) covers all planned scope: credentials, data classification, HITL, scope discipline, agent autonomy, transparency, and security code review. Tier-placement architectural question resolved by the `@import` always-on model. No separate workstream needed.

docs/VISION.md

@@ -28,7 +28,8 @@ Designed to start as a personal homelab tool and grow into something shareable w
 
 ```
 this repo (global defaults)
-    ├── install.sh → ~/.agents/skills/  (cross-client skills, all providers)
+    ├── install.sh → ~/.agents/skills/  (canonical skills location)
+    ├── install.sh → ~/.claude/skills/  (symlink → ~/.agents/skills/, Claude Code adapter)
     └── install.sh → ~/.claude/         (Claude Code config + content)
 
 project repo (local overrides)
@@ -43,17 +44,16 @@ Projects consume from this repo by pulling updates via `sync.sh` (chunk 6). Unti
 ai-development/
 ├── docs/                        # Workflow artifacts and issues (prd/, ard/, bug/, notes/, adr/, issues/) + research/ (raw research audit trail)
 ├── .agents/                     # Agent Skills standard location (provider-agnostic)
-│   └── skills/                  # SKILL.md files — read natively by Claude Code, Copilot, Cursor, etc.
+│   └── skills/                  # SKILL.md files — canonical source, deployed to ~/.agents/skills/
 ├── core/                        # Provider-agnostic source of truth
 │   ├── 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, settings.json
+│   ├── claude-code/             # CLAUDE.md, settings.json, provider-manifest.sh
 │   └── copilot/                 # copilot-instructions.md, hooks, agents adapter
 ├── templates/                   # Project scaffolding templates
-├── skills-lock.json             # Tracks installed skills and their sources/hashes
 └── scripts/
     ├── deploy-manifest.sh       # Source→target mappings; sourced by install.sh and sync.sh
     ├── install.sh               # Deploys to ~/.agents/skills/, ~/.claude/, etc.
@@ -65,7 +65,8 @@ ai-development/
 
 `install.sh` is a **deployer**, not a composer. It does not concatenate content into a single file. Instead:
 
-- `.agents/skills/` → `~/.agents/skills/` — user-level cross-client skills (read by Claude Code, Copilot, Cursor, etc.)
+- `.agents/skills/` → `~/.agents/skills/` — canonical skills location; each skill dir is replaced individually (parent not wiped, user-added skills preserved)
+- 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`
 - Writes a lean `~/.claude/CLAUDE.md` — universal rules only, plus pointers to where detailed content lives
@@ -88,7 +89,7 @@ This repo has a `CLAUDE.md` at its root — a meta file that tells Claude how to
 
 `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 — both Claude Code and GitHub Copilot use the `SKILL.md` format and follow the [Agent Skills open standard](https://agentskills.io).
+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
 

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

@@ -1,3 +1,5 @@
 # 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. Claude Code, GitHub Copilot, Cursor, and other tools read `.agents/skills/` natively without an adapter. 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.
+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,3 +1,5 @@
 # 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-provider-adapters-as-symlinks.md

@@ -0,0 +1,9 @@
+# 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.