Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs(spec): remove overview.md, rewrite architecture.md for plugin model

Browse Source 
## Why
overview.md described the chunk-based delivery model, which is superseded
by the marketplace/plugin pivot. architecture.md was equally stale: it
described .agents/skills/ as the canonical skills source (directory does not
exist), a provider-manifest.sh symlink mechanism (never built), and sync.sh /
init-project.sh as existing scripts (Chunk 6, not yet built).

## Implementation Notes
- overview.md deleted; all cross-references scrubbed from AGENTS.md, CONTEXT.md,
  and three notes/research files
- architecture.md fully rewritten: content deployment model reflects actual
  install.sh behaviour (DEPLOY_FILES / DEPLOY_EXECUTABLES / DEPLOY_DIRS);
  plugin model section added listing all 5 plugins; directory structure section
  removed (was describing a layout that no longer exists)
- "Chunk 6" phase label → "planned"; "chunk workflow" removed from AGENTS.md
  description
- Fixed broken path docs/HUMANS.md → docs/wiki/HUMANS.md in governance layer
  and core/instructions/governance.md

Refs: #15
This commit is contained in:
Defame1297
2026-06-28 19:53:19 +00:00
parent 7a00368683
commit 3b5b1b5199
8 changed files with 18 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
AGENTS.md
View File

@@ -14,7 +14,6 @@ Read CONTEXT.md at the start of every session in this repo.
Read these on demand:
- `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/adr/` — architectural decisions; read before answering design questions or proposing structural changes
- `docs/ai-constitution.md` — full governance evidence base; read when a governance decision needs justification

2
CONTEXT.md
View File

@@ -14,7 +14,7 @@ description: Domain language and decisions for the global AI development config
`core/instructions/<topic>.md` files are plain markdown — no frontmatter, no schema. The agent decides when to read each file based on task context and the content index label in `providers/claude-code/CLAUDE.md`. Frontmatter is deferred until there is evidence that agents are loading the wrong files in practice.
### Repo/gitea as source of truth
All project state, decisions, context, and working conventions live in this repo or Gitea. 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.
All project state, decisions, context, and working conventions live in this repo or Gitea. 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.
Before answering any design or architecture question, check for existing decisions: `docs/adr/` (hard architectural decisions).

2
core/instructions/governance.md
View File

@@ -70,7 +70,7 @@ When asked to perform a well-defined, repeatable task — file processing, deplo
## What This File Does Not Govern
Human process decisions are outside agent scope: oversight checkpoints, human approval gates, post-mortems, regulatory notifications, IP licence scanning, and sustainability measurement. These are defined in `docs/ai-constitution.md` and executed by humans following `docs/HUMANS.md`.
Human process decisions are outside agent scope: oversight checkpoints, human approval gates, post-mortems, regulatory notifications, IP licence scanning, and sustainability measurement. These are defined in `docs/ai-constitution.md` and executed by humans following `docs/wiki/HUMANS.md`.
The deterministic enforcement layer — pre-commit hooks, CI gates, scanner configuration, audit logging infrastructure, and AI agent permission scoping — is specified in `docs/research/governance_principles/CONTROLS.md` and implemented by humans. Agent instructions alone cannot enforce what deterministic tooling must enforce.

1
docs/notes/factory-integration-decisions.md
View File

@@ -92,7 +92,6 @@ Evals require a runner to be meaningful. Chunk 3 ships skills without evals; the
Both this repo and project repos get `docs/spec/`. The distinction from VISION.md:
- `docs/VISION.md` — goals, intent, long-term roadmap (stable)
- `docs/spec/overview.md` — current deployed state, what works today (updated with each chunk)
- `docs/spec/architecture.md` — current directory structure, install behavior, provider model as-deployed
VISION.md is refactored in issue 0014 to goals/intent only; architecture content moves to `docs/spec/`. The `implement-feature` skill constraint: update `docs/spec/` in the same PR as any behavior change.

2
docs/notes/factory-research-gaps-conflicts.md
View File

@@ -49,7 +49,7 @@ Factory treats `LESSONS.md` as a required committed file — the mechanism for l
### 3.2 `docs/spec/` living spec layer
Factory requires `docs/spec/overview.md` and `docs/spec/architecture.md` — a spec that is updated in the same PR as any behaviour change. The current docs structure has no equivalent layer; workflow artifacts go in `docs/prd/`, `docs/ard/`, etc. Adding `docs/spec/` is additive (not conflicting), but it changes the docs convention and needs to be decided before Chunk 4 (workflows) defines workflow artifacts.
Factory requires `docs/spec/architecture.md` — a spec that is updated in the same PR as any behaviour change. The current docs structure has no equivalent layer; workflow artifacts go in `docs/prd/`, `docs/ard/`, etc. Adding `docs/spec/` is additive (not conflicting), but it changes the docs convention and needs to be decided before Chunk 4 (workflows) defines workflow artifacts.
### 3.3 Session handoff skill (impacts Chunk 3)

2
docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md
View File

@@ -419,7 +419,7 @@ Goal: A working factory skeleton that a real task can be run through end-to-end.
1. Commit `AGENTS.md` — merge existing governance content; validate against principles doc
2. Generate `CONTEXT.md` — manually populate shared vocabulary (10–15 domain terms to start)
3. Create `docs/spec/overview.md` and `docs/spec/architecture.md` — initial living spec, even if sparse
3. Create `docs/spec/architecture.md` — initial living spec, even if sparse
4. Create `docs/adr/` with an `adr-template.md`
5. Implement Phase 1 skill set (7 files):
- `roles/architect`, `roles/developer`, `roles/reviewer`

64
docs/spec/architecture.md
View File

@@ -1,79 +1,45 @@
# 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)
└── scripts/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/
├── AGENTS.md # Provider-agnostic always-on rules for this repo; imported by repo CLAUDE.md
├── CONTEXT.md # Domain language, principles, glossary; auto-loaded at session start
├── 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/
│ └── evals/ # eval.yaml files for skills not yet in a plugin (cross-cutting/, implement/)
├── .claude-plugin/ # Marketplace manifest (both Claude Code and Copilot CLI read here)
│ └── marketplace.json # Declares all installable plugins in this repo
├── .github/plugin/
│ └── marketplace.json # Mirror of .claude-plugin/marketplace.json for Copilot CLI canonical path
├── plugins/ # Installable plugin units (each is a self-contained deployable)
│ └── kyberforge/ # Marketplace management toolkit (create-plugin, marketplace-architect, write-skill, write-eval)
├── core/ # Provider-agnostic source of truth
│ ├── AGENTS.md # Global always-on rules (Communication + Behavior); deployed to ~/.agents/AGENTS.md
│ ├── 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 (thin adapter), settings.json, provider-manifest.sh
│ └── copilot/ # copilot-instructions.md, hooks, agents adapter
└── 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:
`scripts/install.sh` is a **deployer**, not a composer. It sources `scripts/deploy-manifest.sh` and deploys three categories:
- `.agents/skills/` → `~/.agents/skills/` — canonical skills location; each skill dir is replaced individually (parent not wiped, user-added skills preserved)
- `core/AGENTS.md` → `~/.agents/AGENTS.md` — global always-on rules (Communication + Behavior); imported by `~/.claude/CLAUDE.md` via `@~/.agents/AGENTS.md`
- 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`
- `providers/claude-code/CLAUDE.md` → `~/.claude/CLAUDE.md` — thin adapter: imports `~/.agents/AGENTS.md` and `governance.md`; no original content
- **Files** (`DEPLOY_FILES`): `providers/claude-code/CLAUDE.md` → `~/.claude/CLAUDE.md`; `providers/claude-code/settings.json` → `~/.claude/settings.json`; `core/AGENTS.md` → `~/.agents/AGENTS.md`
- **Executables** (`DEPLOY_EXECUTABLES`): `providers/claude-code/statusline-command.sh` → `~/.claude/statusline-command.sh` (with `+x`)
- **Directories** (`DEPLOY_DIRS`): `core/` → `~/.claude/core/` (destination fully replaced on each deploy)
Skills are **not** deployed by `install.sh`. They are distributed as plugins and installed separately via `claude plugin install <name>@holocron`.
`~/.claude/CLAUDE.md` is a thin adapter, not a content source. It imports `~/.agents/AGENTS.md` (always-on rules) and `governance.md` (always-on governance), then lists the content index. All always-on content lives in `AGENTS.md` files so other providers can import the same source without duplication.
## Plugin model
Skills, agents, MCP servers, and hooks are distributed as self-contained plugin units under `plugins/`. Each plugin has a `plugin.json` manifest and is installed independently via `claude plugin install`.
## 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`.
- **Phase 1** (complete): instruction and documentation layer — `governance.md` loaded via `@import`; `docs/ai-constitution.md` and `docs/wiki/HUMANS.md` as human-facing reference; `CONTEXT.md` extended with governance domain language.
- **Phase 2** (planned): deterministic enforcement layer — pre-commit hooks, CI gates, secret scanning, licence scanning. Specified in `docs/research/governance_principles/CONTROLS.md`.
## AGENTS.md pattern
This repo uses two `AGENTS.md` files as the provider-agnostic source of always-on rules (ADR-0012):
- **Repo-level `AGENTS.md`** — instructions for agents working inside this repo (structure, key rules, chunk workflow). Imported by repo `CLAUDE.md` via `@AGENTS.md`.
- **Repo-level `AGENTS.md`** — instructions for agents working inside this repo (structure, key rules). Imported by repo `CLAUDE.md` via `@AGENTS.md`.
- **Global `core/AGENTS.md`** — Communication and Behavior rules that apply across all projects. Deployed to `~/.agents/AGENTS.md`; imported by `~/.claude/CLAUDE.md` via `@~/.agents/AGENTS.md`.
Both `CLAUDE.md` files are thin adapters: they import from their respective `AGENTS.md` and add only Claude Code-specific syntax (`@import`, content index paths). They carry no original always-on content.
@@ -84,8 +50,6 @@ This repo also has a `CLAUDE.md` at its root — the Claude Code entry point for
`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.

69
docs/spec/overview.md
View File

@@ -1,69 +0,0 @@
# 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-06-27 (kyberforge plugin — agent-author skill)*
## What is deployed
### Plugins
1 plugin registered in the marketplace (`holocron` marketplace, `.claude-plugin/marketplace.json`):
- **`kyberforge`** — marketplace management toolkit and skill/agent factory. Contains `skill-author` (create/improve SKILL.md files), `skill-audit` (validate skills against agentskills.io spec), and `agent-author` (create/improve Claude Code + Copilot CLI agent definition files at plugin, project, or user scope) skills. Install: `claude plugin install kyberforge@holocron`. Source: `plugins/kyberforge/`. Research doc: `plugins/kyberforge/docs/plugin-marketplace-architecture.md`.
### Skills
13 skills deployed directly to `~/.agents/skills/` via `install.sh`. Available as slash commands in Claude Code via `~/.claude/skills/ → ~/.agents/skills/` symlink. Factory and marketplace skills (`write-eval`, `write-skill`, `create-plugin`, `marketplace-architect`) have moved to the `kyberforge` plugin and are only available after plugin install.
**Factory bootstrap (now in kyberforge plugin):**
- `write-eval` — produces `eval.yaml` test files for skills. Hand-written (bootstrap). Eval at `plugins/kyberforge/tests/evals/write-eval/eval.yaml`.
- `write-skill` — authors new SKILL.md files and converts placeholders to canonical format. Hand-written (bootstrap). Eval at `plugins/kyberforge/tests/evals/write-skill/eval.yaml`. Invokes `write-eval` as part of its own process.
- `write-docs` — produces technical documentation derived from code and spec; never invents behaviour. **First factory-authored skill** (SKILL.md produced via `write-skill`, eval via `write-eval`). Eval at `.agents/evals/implement/write-docs/eval.yaml`. Sources: anthropics/skills `doc-coauthoring`, mattpocock/skills `write-a-skill`, bmad-code-org/BMAD-METHOD `bmad-advanced-elicitation`.
Current skills (direct): `caveman`, `diagnose`, `gitleaks`, `grill-me`, `grill-with-docs`, `improve-codebase-architecture`, `prototype`, `tdd`, `to-issues`, `to-prd`, `triage`, `write-docs`, `zoom-out`.
**Chunk 3 target:** 42 skills across 9 categories. PRD: `docs/prd/chunk-3-skills-library.md`. Canonical build reference: `docs/research/ai-coding-factory/ai-coding-factory-skills-index.md` (delete once all skills exist). Skills stored flat (`skill-name/SKILL.md`) per ADR-0009; category in `metadata.category` frontmatter. Categories: design, factory, implement, test, review, deploy, operate, cross-cutting, iac (2 skills only — docker-compose + iac-security-review). Role skills (6) deferred to Chunk 5. Gitea skills moved to `providers/gitea/` provider adapter.
**Skill implementation workflow:** each skill follows the per-skill process in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016). Sub-agents handle source discovery, source review, and conflict checking; synthesis grill and HITL test are human steps. Bootstrap: write-eval (hand-written) → write-skill (hand-written) → write-docs (first factory-authored) → all others via factory.
### Claude Code configuration
- `~/.claude/CLAUDE.md` — thin adapter; imports `~/.agents/AGENTS.md` (Communication + Behavior) and `governance.md`; content index pointers only
- `~/.agents/AGENTS.md` — global always-on rules (Communication + Behavior); provider-agnostic source of truth
- `~/.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)
- `init-project.sh` scaffolding (Chunk 6) — will seed `.pre-commit-config.yaml` for new projects
## Recent changes
- 2026-06-27 — `agent-author` skill added to kyberforge plugin. Creates and improves agent definition files for both Claude Code (`.md`) and GitHub Copilot CLI (`.agent.md`) from a single root directory input via `new-agent.sh`. Supports plugin, project, and user scope — scope auto-detected from root (`plugin.json` presence). File-by-file no-op scaffold; routing on file existence (neither → create, any exists → improve). `agents/sources.md` for provenance at plugin scope. No companion `agent-audit` skill (deferred, tracked in issue #11). ADR-0015 documents the dual-provider single-root scaffold decision.
- 2026-06-20 — kyberforge plugin created and registered in `holocron` marketplace. Consolidates `create-plugin`, `marketplace-architect`, `write-skill`, and `write-eval` skills (previously in `.agents/skills/`) plus their evals, bundled scripts, references, and the plugin-marketplace-architecture research doc into a single installable plugin at `plugins/kyberforge/`. Plugin template (`templates/plugin/`) bundled into `plugins/kyberforge/skills/create-plugin/assets/plugin-template/` and removed from repo root. Evals moved from `.agents/evals/marketplace/` and `.agents/evals/factory/write-eval/` into `plugins/kyberforge/tests/evals/`. These four skills are no longer available as standalone slash commands — install the plugin to use them.
- 2026-06-20 — Gitleaks secret scanning added via pre-commit framework. `.gitleaks.toml` in repo root is the base config extending gitleaks defaults and adds path allowlist for `docs/research/` (high-entropy terminal captures). `gitleaks` skill added (`cross-cutting`) covering full lifecycle: install, update, tune allowlist, scan modes, resolve real findings. Supports both modern repos (pre-commit-based) and legacy repos (shell hook-based setup). Key lesson: v8.24.2 uses `[allowlist]` (singular); v8.25.0+ uses `[[allowlists]]` — wrong syntax silently does nothing.
- 2026-05-18 — Issue 0018 phase 1 refactor complete: `write-skill` redesigned from scratch. New files added to skill directory: `SKILL-TEMPLATE.md` (authoritative 6-section template with XML blocks, human-usable), `META-TEMPLATE.md` (provenance schema with inline-commented YAML), `CATEGORIES.md` (self-contained category table), `META.md` (write-skill's own provenance). SKILL.md rewritten: 6 sections replacing 8 (Role and When/When not dropped — not in agentskills.io spec); frontmatter reduced to 3 fields (`name`, `description`, `metadata.category`); provenance fields (`version`, `updated`, `when`, `source`, `references`) moved to META.md (progressive disclosure — not loaded at startup). `docs/notes/skill-implementation-workflow.md` updated to reference SKILL-TEMPLATE.md as the authoritative template.
- 2026-05-17 — Issue 0018 phase 2 complete: `write-docs` skill written and deployed. First skill produced end-to-end by the factory (SKILL.md via `write-skill`, eval via `write-eval`). Category: implement. Key decisions: file-approval gate before reading (user names files or approves proposals); gap check before drafting (user fills what code doesn't explain); stage skipping allowed with logged reason; full revised section shown before confirmation gate; surgical edits only with per-round delta summary; Reader Testing via scoped sub-agent (doc + questions only, no source files); summary/overview sections written last. Sources: anthropics/skills doc-coauthoring (Reader Testing stage, surgical-edit constraint), mattpocock/skills write-a-skill (trigger pattern), bmad-code-org/BMAD-METHOD bmad-advanced-elicitation (confirmation gate). Open follow-up: documentation convention (file/folder/content structure, global vs repo-specific) — not yet defined.
- 2026-05-17 — Issue 0018 phase 1 complete: `write-skill` bootstrap skill written and deployed. Hand-written (factory bootstrap). Self-authored — no upstream content adopted; agentskills.io best-practices and optimizing-descriptions docs cited as references. Speckit excluded (AGPL-3.0). Key decisions: new-skill + placeholder-conversion scope only (upgrades → `upgrade-skill`); trigger description tested against 3 cases before body written; `write-eval` invoked as step 7 in process; HITL prompt as step 8. Eval at `.agents/evals/factory/write-skill/eval.yaml`.
- 2026-05-17 — Issue 0017 complete: `write-eval` bootstrap skill written and deployed. Two sections schema (`trigger_tests` + `output_tests`), provider-agnostic string assertions, show-plan-then-merge-on-rerun behaviour, conflict flagging (B model). Sources: agentskills/agentskills, darkrishabh/agent-skills-eval, bmad-code-org/BMAD-METHOD, mattpocock/skills. Hand-written eval at `.agents/evals/factory/write-eval/eval.yaml`.
- 2026-05-17 — Issue 0016 complete: skill implementation workflow grill completed. `docs/notes/skill-implementation-workflow.md` written. All issues 0017–0028 updated with specific acceptance criteria. Key conventions: sub-agents prescribed at each research/writing step; conflict check against constitution + factory principles before synthesis grill; `when:` and `references:` fields added to authoring standard; write-docs moved to issue 0018 phase 2 (first factory-authored skill).
- 2026-05-17 — Issue 0015 complete: AGENTS.md refactor implemented. Two AGENTS.md files created (`AGENTS.md` at repo root, `core/AGENTS.md` deployed to `~/.agents/AGENTS.md`). Both CLAUDE.md files slimmed to thin adapters. `deploy-manifest.sh` updated. `docs/spec/architecture.md` updated with new structure. ADR-0012 in effect.
- 2026-05-17 — Chunk 3 issues created (0015–0028): AGENTS.md refactor prerequisite, skill workflow grill, bootstrap skills (write-eval, write-skill), factory/design/implement/test/review/deploy/operate/IaC/cross-cutting skill groups, chunk closure; all HITL; acceptance criteria for 0017–0028 to be refined after issue 0016 grill session
- 2026-05-17 — behavioral tests fully resolved: `CONTEXT.md` now always-loaded via `@import` in repo `CLAUDE.md`; standing rule added to check `docs/adr/` before answering design questions; communication/behavior and secrets rules tightened; Chunk 2 and Governance Phase 1 ✅ complete
- 2026-05-17 — added `LESSONS.md` (issue 0013) and `docs/spec/` (issue 0014); refactored `docs/VISION.md` to goals/intent only