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>
This commit is contained in:
80
docs/prd/chunk-1.md
Normal file
80
docs/prd/chunk-1.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user