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:
@@ -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
|
||||
|
||||
@@ -26,9 +26,13 @@ Workflow artifacts are committed to `docs/` in subdirectories by type. All are t
|
||||
- `docs/notes/<slug>.md` — Exploration Notes
|
||||
- `docs/adr/NNNN-<slug>.md` — Architecture Decision Records
|
||||
- `docs/issues/NNNN-<slug>.md` — Issues
|
||||
- `docs/spec/<slug>.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.
|
||||
|
||||
9
LESSONS.md
Normal file
9
LESSONS.md
Normal file
@@ -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).
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# 0013 — LESSONS.md for this repo
|
||||
# 0013 — LESSONS.md for this repo ✅
|
||||
|
||||
## What to build
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# 0014 — docs/spec/ and VISION.md refactor
|
||||
# 0014 — docs/spec/ and VISION.md refactor ✅
|
||||
|
||||
## What to build
|
||||
|
||||
|
||||
@@ -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/`
|
||||
|
||||
---
|
||||
|
||||
74
docs/spec/architecture.md
Normal file
74
docs/spec/architecture.md
Normal file
@@ -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/<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.
|
||||
40
docs/spec/overview.md
Normal file
40
docs/spec/overview.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user