docs: implement issues 0013 and 0014 — LESSONS.md and docs/spec/

Add LESSONS.md as the long-loop feedback log at repo root. Patterns
observed during development graduate to standing rules when three or
more entries appear.

Introduce docs/spec/ as the living spec layer: overview.md (deployed
state) and architecture.md (directory structure, install pipeline,
provider model, governance layer). Refactor docs/VISION.md to goals
and intent only — architecture content moved to docs/spec/architecture.md.

Update CLAUDE.md and CONTEXT.md to reference the new spec files.
Close issues 0013 and 0014. Update ROADMAP and factory integration
note to reflect completion.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/spec/architecture.md

@@ -0,0 +1,74 @@
+# 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)
+
+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/
+├── 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/
+├── 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, provider-manifest.sh
+│   └── copilot/                 # copilot-instructions.md, hooks, agents adapter
+├── templates/                   # Project scaffolding templates
+└── 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:
+
+- `.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
+
+`~/.claude/CLAUDE.md` is an index, not a content dump. It tells the agent where things are; the agent pulls what it needs using its Read tool. This keeps context size minimal — only what is needed for every session is loaded upfront.
+
+## 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`.
+
+## This repo's own CLAUDE.md
+
+This repo has a `CLAUDE.md` at its root — a meta file that tells Claude how to work *in this repo itself* (structure, conventions, how to add skills/workflows/providers). This is distinct from `providers/claude-code/CLAUDE.md`, which is the global config deployed to `~/.claude/` for use across all projects. Do not conflate the two.
+
+## 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.
+
+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.

docs/spec/overview.md

@@ -0,0 +1,40 @@
+# Overview
+
+Current deployed state of this repo — what you get if you run `install.sh` today. Updated at the close of each chunk and in the same PR as any behavior change.
+
+*Last updated: 2026-05-17*
+
+## What is deployed
+
+### Skills
+12 skills deployed to `~/.agents/skills/` via `install.sh`. Available as slash commands in Claude Code via `~/.claude/skills/ → ~/.agents/skills/` symlink. All 12 are first-draft placeholders pending rebuild in Chunk 3.
+
+Current skills: `caveman`, `claude-api`, `diagnose`, `grill-me`, `grill-with-docs`, `improve-codebase-architecture`, `init`, `prototype`, `review`, `security-review`, `tdd`, `to-issues`, `to-prd`, `triage`, `update-config`, `write-a-skill`.
+
+### Claude Code configuration
+- `~/.claude/CLAUDE.md` — global config index; always-on rules + content index pointers
+- `~/.claude/core/instructions/` — coding, git, testing, governance instruction files
+- `~/.claude/settings.json` — Claude Code settings
+
+### Governance layer
+`core/instructions/governance.md` loads into every Claude Code session via `@import` in `~/.claude/CLAUDE.md`. Covers: hard prohibitions on secrets and data, data classification tiers, HITL requirements, sycophancy resistance, deterministic execution preference.
+
+## What works end-to-end
+
+- `install.sh` runs idempotently — safe to re-run after changes
+- Provider adapter pattern: `providers/*/provider-manifest.sh` auto-discovered by `install.sh`
+- Governance rules take effect at session start without any manual loading step
+- Skills available as slash commands immediately after install
+
+## What is not yet deployed
+
+- `sync.sh` — pulls updates into existing projects (Chunk 6)
+- `init-project.sh` — bootstraps a new project (Chunk 6)
+- Copilot provider adapter (Chunk 7)
+- Formal CI/pre-commit enforcement of governance rules (Chunk 6)
+
+For chunk planning and open questions, see `docs/ROADMAP.md`.
+
+## Recent changes
+
+- 2026-05-17 — added `LESSONS.md` (issue 0013) and `docs/spec/` (issue 0014); refactored `docs/VISION.md` to goals/intent only