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>
This commit is contained in:
@@ -22,78 +22,9 @@ Designed to start as a personal homelab tool and grow into something shareable w
|
||||
- Bootstrapping new projects (`init-project.sh` comes in chunk 6)
|
||||
- GitHub Copilot support (chunk 7)
|
||||
|
||||
## Architecture
|
||||
## Current architecture
|
||||
|
||||
### 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/) + 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.
|
||||
See `docs/spec/architecture.md` for the deployed directory structure, content deployment model, governance layer, provider model, and architectural decisions.
|
||||
|
||||
## V1 Definition
|
||||
|
||||
|
||||
Reference in New Issue
Block a user