holocron/docs/prd/chunk-1.md

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.