chore: bootstrap repo with chunks 1 and 2

Establishes the global AI development config repo from scratch:

- Chunk 1: repo skeleton, install.sh, statusline, deploy manifest
- Chunk 2: core instructions (coding/git/testing), CLAUDE.md rewrite
  (always-on + content index two-tier model), docs restructure,
  6 ADRs, ROADMAP.md, .gitkeep placeholders
- Bootstrap skills in .claude/skills/ (to be catalogued and migrated
  to .agents/skills/ in Chunk 3)

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

docs/ROADMAP.md

@@ -0,0 +1,75 @@
+# Roadmap
+
+## Chunk conventions
+
+Content chunks (2–5) run in two phases, treated as separate sessions:
+
+1. **Architecture + thin drafts** — define the format, schema, and loading model; populate every category with a minimal first draft. Mark speculative entries with `<!-- draft -->` so future sessions know what to trust. Architecture decisions must be stable before phase 2.
+2. **Focused refinement** — work through each category properly, one at a time. Treated as ongoing rather than a hard deadline; refinement is triggered by real friction, not a schedule.
+
+Phase 1 is the planned chunk. Phase 2 is ongoing.
+
+Chunk 6 (tooling) is exempt — it is implementation-driven, not content-driven.
+
+## Chunk table
+
+| Chunk | Scope | Why this order |
+|---|---|---|
+| ✅ 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 |
+| 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 |
+
+## Development workflow
+
+Every workstream follows this shape. Pick a kick-off type, grill it, then run the implementation loop per issue.
+
+```
+Kick-off (pick type)
+  ├── Feature          → /grill-with-docs → PRD              → /to-issues
+  ├── Bug              → /grill-with-docs → Bug Brief         → /to-issues → /diagnose
+  ├── Architecture     → /grill-with-docs → ARD (+ ADR later) → /to-issues
+  ├── Improvement      → /grill-with-docs → PRD or ARD        → /to-issues
+  ├── Feedback         → /triage          → PRD or Bug Brief  → /to-issues
+  └── Ideation         → /grill-me        → Exploration Note  → /to-issues (optional)
+
+Per issue
+  └── /tdd → implement → automated QA → commit (conventional)
+
+Manual QA — only for nuanced UI/UX or agent interaction behavior
+/improve-codebase-architecture — ad hoc or at chunk/PR boundaries, not per issue
+
+Ongoing (ad hoc, within any workstream)
+  ├── /diagnose        (unexpected breakage)
+  ├── /prototype       (design uncertainty)
+  └── /zoom-out        (orientation)
+
+Finalize (per workstream)
+  └── update docs → commit
+```
+
+This workflow is defined at convention level in Chunk 2. Chunk 4 formalizes it as a composable skill/workflow.
+
+## Open questions / deferred decisions
+
+Items consciously not resolved — to be addressed in the relevant chunk PRD or grill.
+
+| Question | Deferred to |
+|---|---|
+| How project-level overrides are structured and what they can override | Chunk 6 PRD |
+| ~~Deployment manifest seam — `install.sh` embeds source→target mappings implicitly; `sync.sh` will need the same mapping.~~ | ✅ Resolved in Chunk 2 architecture review — extracted to `scripts/deploy-manifest.sh`; `sync.sh` sources the same file in Chunk 6 |
+| Feedback intake workflow — where does feedback arrive (GitHub issues, Slack, email)? | Grill before Chunk 4 (workflows) |
+| QA agent design — what does automated agent testing look like in practice? | Grill before Chunk 5 (agents) |
+| Automated deployment pipeline — CI/CD beyond gitops convention | Chunk 6 grill |
+| Formal CI gate for `/improve-codebase-architecture` | Chunk 6 grill |
+| Changelog tooling — which generator (git-cliff, conventional-changelog, etc.) and where it runs | Chunk 3 grill |
+| Content index frontmatter — replace inline `when:` hints in CLAUDE.md content index with a `when:` field in each instruction/skill file so the agent discovers load conditions from the file itself. Cover before implementing Chunk 3 skills. | Chunk 3 grill |
+| Agent behavior confirmation model — writes/edits/git currently require stating intent + approval before acting. Loosen to autonomy-first once skills and workflows are proven and automated agents replace direct interaction. | Phase 2 refinement (post Chunk 4) |
+| CLAUDE.md always-on refinement — security floor (no credentials/auth URLs), scope discipline (no over-engineering), tool preference (Read/Edit over Bash). Needs its own grill session → PRD before implementation. | Future workstream, post Chunk 2 |
+
+## 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.

docs/VISION.md

@@ -0,0 +1,130 @@
+# Vision
+
+## Purpose
+
+A global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects. Provides a consistent, provider-agnostic foundation that individual projects can inherit and extend.
+
+Designed to start as a personal homelab tool and grow into something shareable with a team and potentially the open source community.
+
+## Goals
+
+- **Single source of truth** — one place to define and evolve AI development configs across all projects
+- **Provider-agnostic core** — content works across AI coding tools (Claude Code, GitHub Copilot, etc.) through thin provider adapters
+- **Layered override model** — global defaults defined here, project-level overrides live in each project
+- **Pull-based distribution** — projects opt into updates consciously; no automatic or silent changes
+- **Scales gracefully** — works solo today, designed to onboard a team and open source later
+
+## Non-Goals (for now)
+
+- Automatic push-based sync to projects
+- Runtime dependency from projects back to this repo
+- Bootstrapping new projects (`init-project.sh` comes in chunk 6)
+- GitHub Copilot support (chunk 7)
+
+## Architecture
+
+### Layered model
+
+```
+this repo (global defaults)
+    ├── install.sh → ~/.agents/skills/  (cross-client skills, all providers)
+    └── 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/)
+├── .agents/                     # Agent Skills standard location (provider-agnostic)
+│   └── skills/                  # SKILL.md files — read natively by Claude Code, Copilot, Cursor, etc.
+├── 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
+│   └── 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.
+    ├── 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/` — user-level cross-client skills (read by Claude Code, Copilot, Cursor, etc.)
+- `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.
+
+### 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 — both Claude Code and GitHub Copilot use the `SKILL.md` format and follow the [Agent Skills open standard](https://agentskills.io).
+
+### 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.
+
+## V1 Definition
+
+V1 is "ready to develop" — not a finished product. It means this repo is structured, Claude Code is wired up to it, and there is enough initial content to start building incrementally.
+
+**V1 = Chunk 1 complete — ✅ done.**
+
+Everything from chunk 2 onward is content and tooling built on top of that foundation.
+
+## Long-term: Management Application
+
+A product for making it easy to manage and update AI development configs. Lives in a separate repo. The UX speaks in domain concepts — skills, workflows, agents, providers. Git is the persistence layer, invisible to the user. Saving a skill commits under the hood; the user just clicks Save.
+
+The app is **repo-agnostic** — it works with any git repo that follows these conventions. This repo is the canonical default content: the official starter pack referenced in the app's setup flow.
+
+### Phase 1 — Config Management
+
+Browse, edit, and configure AI development config through a proper product UI.
+
+**Core features:** browse the skill/workflow/agent/prompt library; create and edit config content; manage provider settings.
+
+**Design principle:** This is a product, not a file browser. Users never see git operations, file paths, or commit messages. The UI presents domain concepts (skills, workflows, agents, providers) and handles persistence silently. Any feature that exposes git internals to the user is out of scope.
+
+**Architecture:**
+- Stack: React + TypeScript + Vite (frontend), Node.js + Fastify + TypeScript (backend), PostgreSQL (introduced only when a specific feature requires state with no natural home in git)
+- Stack rationale: single language across the full stack keeps the codebase navigable for junior developers and AI coding agents; TypeScript's explicit types make intent clear without comments; React → React Native is the cleanest path to mobile in Phase 3; `simple-git` covers all required git operations without needing a Python backend
+- Git operations via `simple-git`; git repo stays the source of truth
+- Deployment: Docker (Nginx + Node containers), k8s-ready
+- Hosting: self-hosted first, cloud-hosted option later
+- Users: solo-first, multi-user-ready data model from day one
+
+**Start trigger:** after Chunk 6 of this repo (`sync.sh` + `init-project.sh`). Full content model and sync tooling must be stable before building a UI over them.
+
+**Mobile/desktop (Phase 3):** React → React Native for mobile; Tauri to wrap the web app for desktop.
+
+### Phase 2 — Agent & Fleet Management
+
+Runtime orchestration: push config updates to machines, see running agents, manage task queues and outputs across a fleet of machines and projects.
+
+**Start trigger:** feature-driven — Phase 2 begins when a concrete Phase 1 limitation forces it (e.g. wanting to push a config update to all machines without SSH-ing in, or needing visibility into what agents are running remotely).
+
+### Phase 3 — Native Apps
+
+Mobile (React Native) and desktop (Tauri) wrappers over the Phase 1/2 web app. Deferred until the web app is mature.

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

@@ -0,0 +1,3 @@
+# 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/0002-copy-not-symlink.md

@@ -0,0 +1,3 @@
+# 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-provider-agnostic-core.md

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

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

docs/adr/0005-two-tier-claude-md.md

@@ -0,0 +1,3 @@
+# Two-tier CLAUDE.md: always-on rules + on-demand content index
+
+The deployed `~/.claude/CLAUDE.md` has two sections: (1) a short always-on section with universal rules loaded every session, and (2) a content index of pointers to on-demand files the agent reads when the task warrants it. The alternative — a single large file with all rules, workflows, and conventions — would load coding standards, git rules, and testing conventions into every session, including sessions that never touch code or run tests. Context is a scarce resource. Keeping the always-on section under 30 lines ensures it costs almost nothing; the agent pulls deeper content only when it's relevant.

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

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

docs/ard/.gitkeep

@@ -0,0 +1 @@
+# Remove this file when the first ARD is added.

docs/bug/.gitkeep

@@ -0,0 +1 @@
+# Remove this file when the first Bug Brief is added.

docs/issues/0001-repo-skeleton-content-files.md

@@ -0,0 +1,23 @@
+# 0001 — Repo skeleton: content files ✅
+
+## What to build
+
+Create the three content files that `install.sh` will deploy. This establishes the repo skeleton and makes the global Claude Code config a real, version-controlled artifact.
+
+- `providers/claude-code/CLAUDE.md` — fill in the two-tier structure: one always-on rule ("when you need workflows, agents, or prompts, read them from `~/.claude/core/`") plus a content index section with pointers to `~/.claude/core/` (initially sparse, populated as chunks complete)
+- `providers/claude-code/settings.json` — `{"theme": "dark"}`
+- `core/instructions/global.md` — placeholder stub confirming the pipeline works; real content comes in Chunk 2
+
+The root `CLAUDE.md` and `providers/claude-code/CLAUDE.md` already exist as shells with warnings — this issue fills in the real content of `providers/claude-code/CLAUDE.md`.
+
+## Acceptance criteria
+
+- [ ] `providers/claude-code/CLAUDE.md` has a short always-on section with the content index rule and a pointers section referencing `~/.claude/core/`
+- [ ] `providers/claude-code/settings.json` contains `{"theme": "dark"}`
+- [ ] `core/instructions/global.md` exists as a clearly-labelled placeholder stub
+- [ ] No empty directories committed (`core/agents/`, `core/workflows/`, `core/prompts/` do not exist yet)
+- [ ] `providers/claude-code/CLAUDE.md` warning banner distinguishes it from the root `CLAUDE.md`
+
+## Blocked by
+
+None — can start immediately.

docs/issues/0002-install-sh.md

@@ -0,0 +1,28 @@
+# 0002 — install.sh — deploy script ✅
+
+## What to build
+
+Write `scripts/install.sh` — an idempotent script that deploys this repo's content to `~/.claude/` and creates `~/.agents/skills/` as an empty directory. Running it once wires Claude Code to use this repo as its global config source. Running it again after pulling updates is safe.
+
+Deployment targets:
+- `providers/claude-code/CLAUDE.md` → `~/.claude/CLAUDE.md`
+- `providers/claude-code/settings.json` → `~/.claude/settings.json`
+- `core/` → `~/.claude/core/` (full directory copy)
+- Create `~/.agents/skills/` as an empty directory
+
+Always overwrites deployed files — editing deployed files directly is a usage error, not a conflict. Creates directories if they don't exist.
+
+After writing the script, run it once and perform the manual smoke test.
+
+## Acceptance criteria
+
+- [ ] `scripts/install.sh` exists and is executable
+- [ ] Running it deploys `~/.claude/CLAUDE.md`, `~/.claude/settings.json`, and `~/.claude/core/instructions/global.md`
+- [ ] Running it creates `~/.agents/skills/` on disk
+- [ ] Running it a second time completes without errors (idempotency check)
+- [ ] A new Claude Code session confirms the always-on rule is in effect (ask Claude where it looks for workflows — it references `~/.claude/core/`)
+- [ ] Bootstrap skills at `.claude/skills/` are untouched
+
+## Blocked by
+
+- 0001 — Repo skeleton: content files

docs/issues/0003-statusline.md

@@ -0,0 +1,42 @@
+# 0003 — Claude Code status line ✅
+
+## What to build
+
+Add a custom status line to the Claude Code provider that shows session context at a glance. The status line is a bash script that reads JSON from stdin on every Claude Code render event and prints a formatted, colored line.
+
+Segments (left to right — identity → config → health):
+- **Directory** — basename of working dir (bold blue)
+- **Git branch** — green on feature branches, red on `main`/`master`
+- **Model** — colored by cost tier: Haiku green, Sonnet amber, Opus red
+- **Context %** — model-aware thresholds: Opus 55/75%, Sonnet 65/85%, Haiku 75/90%; green → amber → red
+- **Cost** — session cost in USD; shown as ¢ below $1, $X.XX above; green → amber at $1.50 → red at $3.00
+- **Tokens** — cumulative session total, formatted as Xk when ≥ 1000; blue (informational only)
+- **Vim mode** — magenta, only shown when active
+
+Segments joined with ` · `. Missing or zero-value segments are omitted entirely.
+
+Files:
+- `providers/claude-code/statusline-command.sh` — the script
+- `providers/claude-code/settings.json` — updated with `statusLine` config
+- `scripts/install.sh` — updated to deploy the script and set executable bit
+
+## Acceptance criteria
+
+- [x] `providers/claude-code/statusline-command.sh` exists and is executable
+- [x] `settings.json` references the script via `statusLine.command`
+- [x] `install.sh` deploys the script to `~/.claude/statusline-command.sh` with `chmod +x`
+- [x] All segments render correctly with ANSI colors (no literal `\033[0m` in output)
+- [x] Segments separated by ` · `, not `|`
+- [x] Cost shown as ¢ below $1, $X.XX above
+- [x] Tokens shown as Xk when ≥ 1000, raw number below
+- [x] Missing fields produce no empty segment
+- [x] `tests/test-statusline.sh` passes (11 tests)
+- [x] `tests/test-install.sh` passes (now covers statusline deployment)
+
+## Cost threshold rationale
+
+On a $20/month subscription, `total_cost_usd` measures session weight rather than real spend. Thresholds ($1.50 amber / $3.00 red) are calibrated to signal a heavy session, not budget overrun. Adjust upward if amber rarely appears.
+
+## Blocked by
+
+- 0002 — install.sh

docs/issues/0004-rewrite-claude-md.md

@@ -0,0 +1,26 @@
+# 0004 — Rewrite providers/claude-code/CLAUDE.md and retire global.md ✅
+
+## What to build
+
+Replace the sparse content in `providers/claude-code/CLAUDE.md` with a complete always-on section covering communication style and behavior rules, plus a content index that tells the agent when to load each topic instruction file. Delete `core/instructions/global.md`, which is a placeholder stub with no content — the content index update makes it obsolete.
+
+The always-on communication rules define how the agent responds: answer directly first, challenge bad ideas explicitly rather than validating them, explain the why behind decisions, and never soften disagreement into a suggestion.
+
+The always-on behavior rules define when the agent asks permission: reads and exploration proceed freely; writes, edits, and git operations state intent before acting; irreversible or shared-state operations (push, drop, publish) require explicit confirmation every time.
+
+The content index provides inline load triggers so the agent knows when to read each on-demand instruction file without requiring frontmatter in those files.
+
+## Acceptance criteria
+
+- [ ] `providers/claude-code/CLAUDE.md` contains an always-on communication section with all seven rules from the PRD
+- [ ] `providers/claude-code/CLAUDE.md` contains an always-on behavior section covering reads, writes, and irreversible operations
+- [ ] Content index includes load triggers for: coding conventions, git conventions, testing conventions, and workflows/agents/prompts
+- [ ] `core/instructions/global.md` is deleted
+- [ ] In a new session, ask an exploratory design question — agent responds with one recommendation and one tradeoff in 2–3 sentences
+- [ ] In a new session, propose a clearly overengineered approach — agent names the problem rather than implementing it
+- [ ] In a new session, ask the agent to edit a file — agent states what it is about to do before proceeding
+- [ ] In a new session, ask the agent to push a commit — agent requires explicit confirmation
+
+## Blocked by
+
+None — can start immediately

docs/issues/0005-coding-instructions.md

@@ -0,0 +1,18 @@
+# 0005 — Write core/instructions/coding.md ✅
+
+## What to build
+
+Create the coding conventions instruction file at `core/instructions/coding.md`. Plain markdown, no frontmatter. The agent reads this file on demand when writing, editing, or reviewing code, as directed by the content index in `providers/claude-code/CLAUDE.md`.
+
+The file establishes five key rules: automate anything repeatable; no comments unless the why is genuinely non-obvious; no defensive code at internal boundaries; prefer explicit over implicit; no abstractions, features, or cleanup beyond what the task requires.
+
+## Acceptance criteria
+
+- [ ] File exists at `core/instructions/coding.md`
+- [ ] Contains all five rules from the PRD Module 2 section
+- [ ] Plain markdown with no frontmatter or schema
+- [ ] In a new session, ask the agent to implement something with unnecessary complexity — agent pushes back and names the rule being violated
+
+## Blocked by
+
+- 0004 — rewrite providers/claude-code/CLAUDE.md and retire global.md

docs/issues/0006-git-instructions.md

@@ -0,0 +1,19 @@
+# 0006 — Write core/instructions/git.md ✅
+
+## What to build
+
+Create the git conventions instruction file at `core/instructions/git.md`. Plain markdown, no frontmatter. The agent reads this file on demand when doing git operations, as directed by the content index in `providers/claude-code/CLAUDE.md`.
+
+The file establishes five key rules: never skip hooks (`--no-verify`); never force-push main or master; commit messages explain why, not what; never commit secrets or credentials; and the conventional commits vocabulary (`feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`).
+
+## Acceptance criteria
+
+- [ ] File exists at `core/instructions/git.md`
+- [ ] Contains all five rules from the PRD Module 3 section, including the conventional commits vocabulary
+- [ ] Plain markdown with no frontmatter or schema
+- [ ] In a new session, ask the agent to commit a change — agent uses conventional commits format unprompted
+- [ ] In a new session, ask the agent to skip a pre-commit hook — agent refuses
+
+## Blocked by
+
+- 0004 — rewrite providers/claude-code/CLAUDE.md and retire global.md

docs/issues/0007-testing-instructions.md

@@ -0,0 +1,18 @@
+# 0007 — Write core/instructions/testing.md ✅
+
+## What to build
+
+Create the testing conventions instruction file at `core/instructions/testing.md`. Plain markdown, no frontmatter. The agent reads this file on demand when writing or running tests, as directed by the content index in `providers/claude-code/CLAUDE.md`.
+
+The file establishes four key rules: prefer integration tests over mocks; automate everything automatable; test observable end-state, not implementation internals; no test is better than a wrong test.
+
+## Acceptance criteria
+
+- [ ] File exists at `core/instructions/testing.md`
+- [ ] Contains all four rules from the PRD Module 4 section
+- [ ] Plain markdown with no frontmatter or schema
+- [ ] In a new session, ask the agent to write a test requiring a mocked database — agent pushes back and proposes an integration test instead
+
+## Blocked by
+
+- 0004 — rewrite providers/claude-code/CLAUDE.md and retire global.md

docs/issues/0008-docs-restructure.md

@@ -0,0 +1,21 @@
+# 0008 — Restructure docs/ subdirectories and migrate existing PRD ✅
+
+## What to build
+
+Create the subdirectory-by-type structure under `docs/` as defined in CONTEXT.md. Migrate the one existing PRD from its flat location to the correct subdirectory. No other files move.
+
+New directories to create: `docs/prd/`, `docs/ard/`, `docs/bug/`, `docs/notes/`, `docs/adr/`. (`docs/issues/` already exists and is correctly placed.) `docs/VISION.md` stays at `docs/VISION.md`.
+
+Migration: `docs/prd-chunk-1.md` → `docs/prd/chunk-1.md`.
+
+## Acceptance criteria
+
+- [ ] `docs/prd/`, `docs/ard/`, `docs/bug/`, `docs/notes/`, `docs/adr/` directories exist
+- [ ] `docs/prd/chunk-1.md` exists (migrated from `docs/prd-chunk-1.md`)
+- [ ] `docs/prd-chunk-1.md` no longer exists
+- [ ] `docs/VISION.md` is unchanged at `docs/VISION.md`
+- [ ] `docs/issues/` is unchanged
+
+## Blocked by
+
+None — can start immediately

docs/notes/.gitkeep

@@ -0,0 +1 @@
+# Remove this file when the first Exploration Note is added.

docs/prd/chunk-1.md

@@ -0,0 +1,80 @@
+# PRD: Chunk 1 — Repo Skeleton + install.sh
+
+## Problem Statement
+
+Claude Code is not currently using this repo as its global config source. There is no directory structure, no install mechanism, and no deployed configuration — Claude Code runs with default behavior across all projects. The global AI development config repo exists in name only.
+
+## Solution
+
+Build the repo skeleton and an idempotent `install.sh` that deploys this repo's content to `~/.claude/` and `~/.agents/skills/`. After running it once, Claude Code will load universal rules every session and know where to find on-demand content (workflows, agents, prompts). The repo becomes the authoritative global config source.
+
+## User Stories
+
+1. As a developer, I want to run `install.sh` once and have Claude Code configured globally, so that I don't need to configure it per-project.
+2. As a developer, I want `install.sh` to be idempotent, so that I can re-run it after pulling updates without fear of breaking my setup.
+3. As a developer, I want Claude Code to load universal rules every session, so that my global conventions are always applied without manual setup.
+4. As a developer, I want Claude Code to know where to find workflows, agents, and prompts, so that it can load them on demand using its Read tool.
+5. As a developer, I want a clear separation between this repo's meta-config and the deployed global config, so that editing the wrong file doesn't silently corrupt my setup.
+6. As a developer, I want placeholder content in `core/` to validate the pipeline end-to-end, so that I can confirm the structure works before building real content in Chunk 2.
+7. As a developer, I want `~/.agents/skills/` created on my machine during install, so that Chunk 3 can populate it without needing to create the directory itself.
+8. As a developer, I want the global `settings.json` committed to this repo, so that my Claude Code preferences are version-controlled and reproducible.
+9. As a developer, I want the two `CLAUDE.md` files to have prominent warnings at the top, so that I never accidentally edit the deployed global config thinking it's the repo meta-config.
+
+## Implementation Decisions
+
+### Modules
+
+**`scripts/install.sh`**
+Idempotent shell script. Always overwrites deployed files (never skips on conflict — editing deployed files directly is a usage error, not a sync problem). Creates directories if they don't exist. Deploys:
+- `providers/claude-code/CLAUDE.md` → `~/.claude/CLAUDE.md`
+- `providers/claude-code/settings.json` → `~/.claude/settings.json`
+- `core/` → `~/.claude/core/` (full directory copy)
+- Creates `~/.agents/skills/` as an empty directory (Chunk 3 populates it)
+
+**`providers/claude-code/CLAUDE.md`**
+Verbatim source file — `install.sh` copies it as-is, no templating. Two-tier structure:
+- Always-on section: one rule — when workflows, agents, or prompts are needed, read them from `~/.claude/core/`
+- Content index section: pointers to on-demand content in `~/.claude/core/` (populated as chunks are completed)
+
+**`providers/claude-code/settings.json`**
+Minimal global settings baseline for Chunk 1: `{"theme": "dark"}`. Permissions, hooks, and model defaults are Chunk 2+ territory.
+
+**`core/instructions/global.md`**
+Single placeholder stub file. Exists to validate that `install.sh` correctly deploys `core/` to `~/.claude/core/` and that the always-on rule in `CLAUDE.md` can successfully point to it. Content is a stub; real instructions are written in Chunk 2.
+
+### Key decisions
+
+- `providers/claude-code/CLAUDE.md` is a **verbatim copy** — no variable substitution. Paths like `~/.claude/core/` are stable and don't vary per machine. Templating is deferred until there's a concrete need.
+- Empty directories (`core/agents/`, `core/workflows/`, `core/prompts/`) are **not committed**. They are created when Chunk 2+ populates them.
+- The bootstrap skills at `.claude/skills/` are **not touched** by Chunk 1. They stay in place until Chunk 3 migrates them to `.agents/skills/`.
+- Two `CLAUDE.md` files exist in this repo and must never be conflated: the root `CLAUDE.md` (how to work in this repo) and `providers/claude-code/CLAUDE.md` (deployed global config). Both have prominent warnings.
+
+## Testing Decisions
+
+A good test for this chunk verifies observable end-state, not script internals: after running `install.sh`, the right files exist at the right paths with the right content.
+
+**Manual smoke test (sufficient for Chunk 1):**
+1. Run `scripts/install.sh`
+2. Verify `~/.claude/CLAUDE.md`, `~/.claude/settings.json`, `~/.claude/core/instructions/global.md`, and `~/.agents/skills/` all exist
+3. Open a new Claude Code session and confirm the always-on rule is in effect — ask Claude where it looks for workflows; it should reference `~/.claude/core/`
+4. Run `install.sh` a second time and verify it completes without errors (idempotency check)
+
+No automated tests for Chunk 1. The install script is simple enough that a one-time manual check is sufficient. Automated install testing becomes worthwhile when `sync.sh` and `init-project.sh` are added in Chunk 6.
+
+## Out of Scope
+
+- Real instructions, coding conventions, AI behavior rules (Chunk 2)
+- Skills content and migration of bootstrap `.claude/skills/` to `.agents/skills/` (Chunk 3)
+- Workflows, agents, prompts content (Chunks 4–5)
+- `sync.sh` and `init-project.sh` (Chunk 6)
+- GitHub Copilot provider adapter (Chunk 7)
+- `skills-lock.json` design and long-term role (Chunk 3)
+- `providers/claude-code/settings.json` permissions, hooks, model defaults (Chunk 2+)
+- Templating in `install.sh` (deferred until concretely needed)
+- Project-level override structure (Chunk 6)
+
+## Further Notes
+
+The root `CLAUDE.md` and `providers/claude-code/CLAUDE.md` were created during the grilling session and already exist in the repo — Chunk 1 implementation should fill in the content of `providers/claude-code/CLAUDE.md` and ensure the root `CLAUDE.md` accurately reflects the final structure.
+
+V1 is complete when Chunk 1 is done: the repo is structured, `install.sh` has been run once, and Claude Code uses this repo as its global config source.

docs/prd/chunk-2-instructions.md

@@ -0,0 +1,151 @@
+# PRD: Chunk 2 — Core Instructions
+
+## Problem Statement
+
+Claude Code runs without any domain conventions or coding standards — every session starts from scratch. The placeholder `core/instructions/global.md` exists but contains no content. `providers/claude-code/CLAUDE.md` has only one rule and no communication or behavior guidelines. There are no rules about how code should be written, how commits should be structured, or how tests should be approached. The agent has no basis for challenging bad ideas, explaining decisions, or behaving consistently across sessions.
+
+Separately, `docs/` has no consistent naming convention. As workflow artifacts accumulate (PRDs, ARDs, Bug Briefs), there is no predictable place to find them.
+
+## Solution
+
+Write three topic-specific instruction files (`coding.md`, `git.md`, `testing.md`) that the agent reads on demand. Update `providers/claude-code/CLAUDE.md` with a proper always-on section covering communication style and behavior rules. Retire the placeholder `global.md`. Establish the subdirectory-by-type naming convention for `docs/` and migrate the existing PRD into it.
+
+This gives the agent real conventions to follow from every session forward, and gives humans a clean, navigable document structure as the repo grows.
+
+## User Stories
+
+1. As a developer, I want the agent to follow consistent coding conventions, so that code quality is predictable across sessions without repeating instructions.
+2. As a developer, I want coding conventions loaded on demand rather than always, so that every session does not pay a context cost for rules that may not be relevant.
+3. As a developer, I want the agent to follow conventional commits format, so that git history is machine-readable and changelog automation is possible in Chunk 3.
+4. As a developer, I want git safety rules available whenever I do git operations, so that I never accidentally bypass hooks or force-push main.
+5. As a developer, I want the agent to require my approval before writing or editing files, so that I stay in control and understand what is changing.
+6. As a developer, I want the agent to proceed freely with reads and exploration, so that information-gathering does not require constant approval.
+7. As a developer, I want the agent to always require explicit confirmation for irreversible or shared-state operations, so that I never accidentally push, drop, or publish something unintended.
+8. As a developer, I want the agent to challenge my ideas with industry standards rather than validate them, so that I make better decisions rather than hearing what I want to hear.
+9. As a developer, I want the agent to explain the why behind pushback and decisions, so that I build domain knowledge and can generalise to future situations.
+10. As a developer, I want the agent to answer directly first and give context only when it changes the answer, so that responses are efficient and signal-dense.
+11. As a developer, I want the agent never to soften disagreement into a suggestion, so that I can trust the agent is giving me its actual assessment.
+12. As a developer, I want the agent to prefer integration tests over mocks, so that tests catch real divergences between code and production systems.
+13. As a developer, I want manual testing reserved for nuanced UI/UX or agent interaction behaviour, so that automation handles everything that can be automated.
+14. As a developer, I want the agent to test observable end-state rather than implementation internals, so that tests survive refactoring without needing to be rewritten.
+15. As a developer, I want a consistent subdirectory-by-type naming convention for `docs/`, so that I can navigate artifacts without guessing where they live.
+16. As a developer, I want existing docs migrated to the new convention, so that the repo is consistent from the start rather than accumulating two naming patterns.
+17. As a developer, I want `global.md` retired, so that there is no ambiguity about where instruction content lives.
+18. As a developer, I want the content index in `CLAUDE.md` to include a load trigger for each file, so that the agent knows when to read each instruction file without requiring frontmatter.
+19. As a developer, I want acceptance criteria on each issue that I can verify in a new Claude session, so that I can confirm conventions are actually being applied and not just written.
+20. As a developer, I want instruction files to use plain markdown with no schema or frontmatter, so that they are readable by both humans and agents without tooling.
+
+## Implementation Decisions
+
+### Module 1 — `providers/claude-code/CLAUDE.md` (rewrite)
+
+The source file deployed to `~/.claude/CLAUDE.md` via `install.sh`. Rewritten with two top-level sections replacing the current sparse content.
+
+**Always-on / Communication:**
+- Answer directly first; context only if it changes the answer
+- Challenge bad ideas explicitly — name the problem, cite the industry standard or first principle, then implement if the user proceeds
+- Never validate an approach because the user seems confident about it
+- When disagreeing, say so clearly — do not soften into a suggestion
+- For exploratory questions: one recommendation, one tradeoff, 2–3 sentences
+- Never say "it depends" without immediately stating what it depends on
+- Explain the why behind decisions — assume the user is learning, not just executing
+
+**Always-on / Behavior:**
+- Reads, searches, exploration: proceed without asking
+- Writes, edits, deletes, git operations: state what you are about to do and why in one sentence; wait for approval before proceeding
+- Irreversible or shared-state operations (push, force-push, drop, publish): require explicit confirmation every time, regardless of prior context
+
+**On-demand content index** (inline load triggers to guide agent judgment):
+- Coding conventions — when writing, editing, or reviewing code
+- Git conventions — when doing git operations
+- Testing conventions — when writing or running tests
+- Workflows / agents / prompts — read from `~/.claude/core/` when invoked
+
+### Module 2 — `core/instructions/coding.md` (new, thin draft)
+
+Plain markdown. On-demand. Read when writing, editing, or reviewing code.
+
+Key rules for the thin draft:
+- Automate anything repeatable — if done manually twice, it belongs in a script, hook, or pipeline step
+- No comments unless the why is genuinely non-obvious — names carry meaning, git history carries context
+- No defensive code at internal boundaries — validate only at system edges (user input, external APIs, git hooks)
+- Prefer explicit over implicit — agents reading code must not need to infer intent from convention
+- No abstractions, features, or cleanup beyond what the task requires
+
+### Module 3 — `core/instructions/git.md` (new, thin draft)
+
+Plain markdown. On-demand. Read when doing git operations. Includes conventional commits convention.
+
+Key rules for the thin draft:
+- Never skip hooks (`--no-verify`) — hooks are the automated QA gate; bypassing them breaks the pipeline
+- Never force-push main or master
+- Commit messages explain why, not what — written for both humans and changelog generators
+- Never commit secrets, credentials, or environment-specific config
+- Conventional commits categories: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`
+
+### Module 4 — `core/instructions/testing.md` (new, thin draft)
+
+Plain markdown. On-demand. Read when writing or running tests.
+
+Key rules for the thin draft:
+- Prefer integration tests over mocks — mocks mask production divergence; real systems catch real failures
+- Automate everything automatable — manual testing only for nuanced UI/UX or agent interaction behaviour requiring human judgment
+- Test observable end-state, not implementation internals — tests must survive refactoring
+- No test is better than a wrong test — a passing mock that masks a real failure is actively harmful
+
+### Module 5 — `core/instructions/global.md` (retire)
+
+Delete this file. It is a placeholder stub with no content. The content index in `providers/claude-code/CLAUDE.md` will be updated to point to the three topic files instead. `install.sh` copies `core/` wholesale, so deletion automatically removes the deployed file on next install.
+
+### Module 6 — `docs/` restructure
+
+Create subdirectories by artifact type. Migrate the one existing PRD.
+
+New structure:
+```
+docs/
+├── prd/          ← PRDs (this PRD is the first)
+├── ard/          ← Architecture Requirements Documents
+├── bug/          ← Bug Briefs
+├── notes/        ← Exploration Notes
+├── adr/          ← Architecture Decision Records (NNNN-slug)
+├── issues/       ← Issues (NNNN-slug, already correct)
+└── VISION.md     ← stays at root of docs/
+```
+
+Migration: `docs/prd-chunk-1.md` → `docs/prd/chunk-1.md`. No other files need moving.
+
+### install.sh
+
+No changes required. It copies `core/` wholesale and deploys `providers/claude-code/CLAUDE.md` verbatim. Adding new files to `core/instructions/` and deleting `global.md` takes effect automatically on next install run.
+
+## Testing Decisions
+
+Instruction files and CLAUDE.md content cannot be unit tested. A well-formed file is not the same as an effective file — the test is whether the agent actually follows the rule in a real session.
+
+**Approach:** Each issue carries a short acceptance criteria checklist. After committing the issue, the developer opens a new Claude session and exercises the relevant behaviour. The issue is closed only when the behaviour is confirmed.
+
+**What a good test looks like:**
+- Trigger the scenario the rule covers (e.g. ask Claude to implement something with unnecessary complexity; expect pushback citing the rule)
+- Confirm the agent's response matches the intended behaviour
+- Do not test that the file was written correctly — test that the behaviour changed
+
+**Prior art:** Chunk 1 used the same approach — manual smoke test in a new session to verify the always-on rule was in effect. Chunk 2 formalises this as per-issue acceptance criteria.
+
+No automated tests for this chunk. Automated QA applies to tooling (scripts, hooks); behavioural QA for content is always human-executed.
+
+## Out of Scope
+
+- Changelog tooling (Chunk 3 follow-on to the conventional commits convention)
+- Frontmatter or load-trigger hints in instruction files themselves — deferred until there is evidence agents are loading the wrong files in practice (Chunk 2 Phase 2 refinement)
+- Security floor, scope discipline, tool preference in the always-on CLAUDE.md section — separate future workstream with its own grill and PRD
+- Loosening the agent behavior confirmation model for automation — deferred to post Chunk 4 once skills and workflows are proven
+- Additional instruction categories beyond coding, git, and testing — Phase 2 refinement, triggered by real friction
+- The `docs/VISION.md` file path does not change — it stays at `docs/VISION.md`, not moved into a subdirectory
+
+## Further Notes
+
+- `install.sh` copies `core/` wholesale — adding or removing files in `core/instructions/` automatically affects what is deployed on the next install run. No install script changes are needed for this chunk.
+- This PRD is itself the first artifact written under the new `docs/prd/` convention. The migration of `docs/prd-chunk-1.md` is a Chunk 2 deliverable, not a precondition for writing this PRD.
+- The behavior confirmation model (writes require stating intent and approval) is intentionally conservative. It reflects the current context: a junior developer interacting directly with the agent. It will loosen post Chunk 4 when automated agents replace direct interaction for routine tasks.
+- The inline load triggers in the content index ("when writing, editing, or reviewing code") are a lightweight substitute for frontmatter. They are noted as a known interim approach and will be revisited if agents load wrong files in practice.