diff --git a/CLAUDE.md b/CLAUDE.md index d941cc4..e188993 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,7 +21,9 @@ This repo is the global AI development configuration repository — the authorit Read these at the start of every session in this repo: - `CONTEXT.md` — domain language and principles; challenge any term that conflicts with it -- `docs/VISION.md` — purpose, goals, roadmap, and long-term Management Application vision +- `docs/VISION.md` — purpose, goals, and long-term Management Application vision +- `docs/spec/overview.md` — current deployed state; what works today +- `docs/spec/architecture.md` — current directory structure, install pipeline, provider model - `docs/ROADMAP.md` — chunk status table and open questions; read this to orient on where work stands - `docs/ai-constitution.md` — full governance evidence base; read when a governance decision needs justification - `docs/HUMANS.md` — human practitioner checklist; applies when working with AI tools in this repo diff --git a/CONTEXT.md b/CONTEXT.md index 13e7263..1d63bbb 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -26,9 +26,13 @@ Workflow artifacts are committed to `docs/` in subdirectories by type. All are t - `docs/notes/.md` — Exploration Notes - `docs/adr/NNNN-.md` — Architecture Decision Records - `docs/issues/NNNN-.md` — Issues +- `docs/spec/.md` — Living spec files (current deployed state); updated in the same PR as any behavior change **NNNN** — zero-padded 4-digit sequential number (e.g. `0001`, `0042`). Used only for artifact types referenced by number (issues, ADRs). PRDs, ARDs, Bug Briefs, and Notes are referenced by topic and use a descriptive slug only. +**Other repo-level artifacts:** +- `LESSONS.md` — long-loop feedback log; patterns observed during development. Three or more entries on the same pattern graduate to the relevant standing file. Updated by the session-handoff skill or by the human directly. + **Slug** — kebab-case, lowercase, max 4–5 words, derived from the document title. No dates (git history carries dates). Examples: `chunk-2-instructions`, `user-auth-flow`, `database-migration`. **When each is written:** PRDs, ARDs, Bug Briefs, and Notes are pre-work — produced by a grill session before issues are created. ADRs are post-decision — written during or after implementation of an ARD when a hard-to-reverse choice is made. An improvement kick-off produces either a PRD (user-facing scope) or ARD (architectural scope). @@ -48,7 +52,7 @@ Projects override on-demand content (workflows, agent roles, prompts) by placing Projects must never edit synced files directly — customizations live in separate override files. A sync conflict is a signal that a synced file was edited directly. ### Repo as source of truth -All project state, decisions, context, and working conventions live in this repo. External memory systems should not be used for this project — they create a split-brain risk where cached state diverges from the repo. At the start of every session, read `CLAUDE.md`, `CONTEXT.md`, and `docs/VISION.md`. Everything needed to orient is here. +All project state, decisions, context, and working conventions live in this repo. External memory systems should not be used for this project — they create a split-brain risk where cached state diverges from the repo. At the start of every session, read `CLAUDE.md`, `CONTEXT.md`, `docs/VISION.md`, and `docs/spec/overview.md`. Everything needed to orient is here. ### Working context This repo is built by a junior developer as a homelab tool intended to scale to professional environments. The agent should challenge ideas and reference industry standards rather than validate assumptions. Explain the why behind decisions — assume the user is learning, not just executing. Flag significant actions before taking them. diff --git a/LESSONS.md b/LESSONS.md new file mode 100644 index 0000000..7bbdafb --- /dev/null +++ b/LESSONS.md @@ -0,0 +1,9 @@ +# Lessons + +Patterns observed during development of this repo. Three or more entries on the same pattern → promote to CONTEXT.md (or the relevant instruction file) as a standing rule. + +**Graduation rule:** When three or more entries cover the same pattern, the human reviews and promotes it to the appropriate standing location: `CONTEXT.md` for domain-level principles, `core/instructions/coding.md` for coding conventions, `core/instructions/git.md` for git conventions, or `core/instructions/testing.md` for testing conventions. The graduated entries are marked `[graduated → target file]` rather than deleted (audit trail). + +**Who writes here:** The session-handoff skill (Chunk 3) prompts LESSONS.md extraction before closing a session. The human may also write directly. + +**What belongs here:** Non-obvious observations — a rule that was misapplied, a pattern that caused friction, a decision that turned out wrong in practice. Not summaries of what was built (that's git history) or planned changes (that's issues). diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index d074acd..34f63c3 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -91,7 +91,7 @@ Items consciously not resolved — to be addressed in the relevant chunk PRD or ## Housekeeping reminders -- **AI coding factory integration** — grill complete. Decision record: `docs/notes/factory-integration-decisions.md`. ADRs: 0008 (factory boundary), 0009 (flat taxonomy), 0010 (role skills vs subagents). Follow-on issues: 0013 (LESSONS.md), 0014 (docs/spec/ + VISION.md refactor). Chunk 3 scope substantially expanded — skills rebuild, new skills, IaC/Gitea skills. See updated chunk table above. +- **AI coding factory integration** — grill complete. Decision record: `docs/notes/factory-integration-decisions.md`. ADRs: 0008 (factory boundary), 0009 (flat taxonomy), 0010 (role skills vs subagents). Follow-on issues: ~~0013 (LESSONS.md)~~ ✅, ~~0014 (docs/spec/ + VISION.md refactor)~~ ✅. Chunk 3 scope substantially expanded — skills rebuild, new skills, IaC/Gitea skills. See updated chunk table above. - **`.gitkeep` files** — placeholder files exist in `core/agents/`, `core/workflows/`, `core/prompts/`, `docs/ard/`, `docs/bug/`. Remove each when the first real file is added to that directory. Each `.gitkeep` names the chunk that will populate it. (`docs/notes/.gitkeep` already removed — directory has real content.) - **Skills pipeline verified** — `install.sh` deploys 12 skills to `~/.agents/skills/` and creates `~/.claude/skills/ → ~/.agents/skills/` symlink adapter. Tested idempotent. `skills-lock.json` removed (was a manual artifact). If `~/.claude/skills/` exists as a real directory on a machine being migrated, remove it manually and re-run install. diff --git a/docs/VISION.md b/docs/VISION.md index c1de44e..400ec2d 100644 --- a/docs/VISION.md +++ b/docs/VISION.md @@ -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//` 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//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 diff --git a/docs/issues/0013-lessons-md.md b/docs/issues/0013-lessons-md.md index 65bcf17..dcebb62 100644 --- a/docs/issues/0013-lessons-md.md +++ b/docs/issues/0013-lessons-md.md @@ -1,4 +1,4 @@ -# 0013 — LESSONS.md for this repo +# 0013 — LESSONS.md for this repo ✅ ## What to build diff --git a/docs/issues/0014-docs-spec.md b/docs/issues/0014-docs-spec.md index ecdedd2..71a1b61 100644 --- a/docs/issues/0014-docs-spec.md +++ b/docs/issues/0014-docs-spec.md @@ -1,4 +1,4 @@ -# 0014 — docs/spec/ and VISION.md refactor +# 0014 — docs/spec/ and VISION.md refactor ✅ ## What to build diff --git a/docs/notes/factory-integration-decisions.md b/docs/notes/factory-integration-decisions.md index 4602c68..7908fd3 100644 --- a/docs/notes/factory-integration-decisions.md +++ b/docs/notes/factory-integration-decisions.md @@ -1,7 +1,7 @@ # Exploration Note: AI Coding Factory Integration — Decision Record **Date:** 2026-05-17 -**Status:** Decisions locked. Follow-on issues: 0013, 0014. ADRs: 0008, 0009, 0010. +**Status:** Complete. Follow-on issues: ~~0013~~, ~~0014~~ — both done (2026-05-17). ADRs: 0008, 0009, 0010. **Input:** `docs/notes/factory-research-gaps-conflicts.md`, `docs/research/ai-coding-factory/` --- diff --git a/docs/spec/architecture.md b/docs/spec/architecture.md new file mode 100644 index 0000000..15e1a28 --- /dev/null +++ b/docs/spec/architecture.md @@ -0,0 +1,74 @@ +# Architecture + +Current deployed architecture. Updated in the same PR as any structural change. + +## 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/, spec/) + 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//` 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//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. diff --git a/docs/spec/overview.md b/docs/spec/overview.md new file mode 100644 index 0000000..6449e27 --- /dev/null +++ b/docs/spec/overview.md @@ -0,0 +1,40 @@ +# Overview + +Current deployed state of this repo — what you get if you run `install.sh` today. Updated at the close of each chunk and in the same PR as any behavior change. + +*Last updated: 2026-05-17* + +## What is deployed + +### Skills +12 skills deployed to `~/.agents/skills/` via `install.sh`. Available as slash commands in Claude Code via `~/.claude/skills/ → ~/.agents/skills/` symlink. All 12 are first-draft placeholders pending rebuild in Chunk 3. + +Current skills: `caveman`, `claude-api`, `diagnose`, `grill-me`, `grill-with-docs`, `improve-codebase-architecture`, `init`, `prototype`, `review`, `security-review`, `tdd`, `to-issues`, `to-prd`, `triage`, `update-config`, `write-a-skill`. + +### Claude Code configuration +- `~/.claude/CLAUDE.md` — global config index; always-on rules + content index pointers +- `~/.claude/core/instructions/` — coding, git, testing, governance instruction files +- `~/.claude/settings.json` — Claude Code settings + +### Governance layer +`core/instructions/governance.md` loads into every Claude Code session via `@import` in `~/.claude/CLAUDE.md`. Covers: hard prohibitions on secrets and data, data classification tiers, HITL requirements, sycophancy resistance, deterministic execution preference. + +## What works end-to-end + +- `install.sh` runs idempotently — safe to re-run after changes +- Provider adapter pattern: `providers/*/provider-manifest.sh` auto-discovered by `install.sh` +- Governance rules take effect at session start without any manual loading step +- Skills available as slash commands immediately after install + +## What is not yet deployed + +- `sync.sh` — pulls updates into existing projects (Chunk 6) +- `init-project.sh` — bootstraps a new project (Chunk 6) +- Copilot provider adapter (Chunk 7) +- Formal CI/pre-commit enforcement of governance rules (Chunk 6) + +For chunk planning and open questions, see `docs/ROADMAP.md`. + +## Recent changes + +- 2026-05-17 — added `LESSONS.md` (issue 0013) and `docs/spec/` (issue 0014); refactored `docs/VISION.md` to goals/intent only