# 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.