Evyasys Docs

---
name: evyasys-docs
description: Use this skill to build and maintain a project's documentation layer in one command. Scans the code and writes core quality-gate documents, one-concern rule files (frontmatter, applies_to globs, ✅/❌ examples from real code), per-stage digests (distilled working memory) with machine-checked claims, architecture and project boundaries (owns / never / dependency law, measured blast radius), and module knowledge with the invariants that must not break — all under .evyasys/. The hook validates every path and document, generates the indexes, module registry and per-project version documents from the manifests, wires everything into Claude Code (managed CLAUDE.md block, path-scoped .claude/rules, .claude/skills) and runs a health check (structure, reach, links, measured claims, wiring). Modes: learn, update, retrain, modules, check. Triggered by `/evyasys:Docs`. Replaces `/evyasys:TrainDocs` and `/evyasys:CreateFunctionalDocs`.
trigger: /evyasys:Docs
---

# Skill: evyasys-docs

One command for every document a project needs so code stays consistent and stable. Source of truth: `.evyasys/`. What Claude Code loads: generated wiring in `CLAUDE.md` and `.claude/`.

## Layers

| Layer | Location | Written by | Used by |
|---|---|---|---|
| Core quality-gate documents | `.evyasys/docs/NAME.md` (+ `fe/`, `be/`) | agent | Plan, Build, Qa at Phase 0 |
| Rules — one concern per file | `.evyasys/docs/rules/<domain>/<concern>.md` | agent | `.claude/rules/evyasys-rule-*` stubs load by path; the full rule on demand |
| Digests — stage working memory | `.evyasys/docs/digests/<stage>.md` + `CLAIMS.tsv` | agent | `.claude/rules/evyasys-digest-*` stubs load by path; HARD RULES copied into `CLAUDE.md` |
| Architecture | `.evyasys/docs/architecture/` | agent | skill `evyasys-project-map`; read before editing a file you did not create |
| Folder guides | `.evyasys/docs/directories/<folder>.md` | agent | that folder's own `CLAUDE.md` (a managed block) — loaded when Claude works there |
| Module knowledge | `.evyasys/knowledge/modules/<m>/<m>.md` | agent | skill `evyasys-modules`; Plan / Build / Qa for the modules they touch |
| Module registry | `.evyasys/memory/modules-registry.md` | **generated** from the manifest | skill, Plan (unique module codes) |
| Versions per project | `.evyasys/docs/versions/*.md` | **generated** from `package.json`, `*.csproj`, `pom.xml`, `go.mod`, … | architecture, upgrades |
| Indexes | `docs/INDEX.md`, `docs/rules/README.md`, `docs/digests/README.md`, `knowledge/modules/README.md` | **generated** | navigation |
| Wiring | `CLAUDE.md` block, folder `CLAUDE.md` blocks, `.claude/rules/evyasys-*`, `.claude/skills/evyasys-*`, `.claude/agents/evyasys-*`, `.claude/hooks/evyasys-docs-guard.js` + `settings.json` entry | **generated**, marked; only marked content is touched, settings are merged | Claude Code itself |

## Why nothing is skipped

- **Generated, not written:** everything derivable (indexes, registry, versions, wiring) is produced by `scripts/lib/docs-*.js`, so it cannot be wrong or forgotten.
- **Wired:** every digest and every rule gets a path-scoped stub in `.claude/rules/`; `CLAUDE.md` carries a managed block that imports `CONTEXT.md` and lists the HARD RULES of each digest;
  skills expose the project map and module knowledge. Your own `CLAUDE.md` content and unmarked `.claude/` files are never touched.
- **Checked:** `node scripts/lib/docs-check.js` (or `/evyasys:Docs --check`) verifies structure, that every `applies_to` still matches files, that links resolve, that measured claims still hold
  (`CLAIMS.tsv`: `exact` drift is an error, `approx` is information — no shell commands, files are read directly), that module docs and the registry agree, and that every document is wired.
- **Specialist agents and a reviewer:** one `.claude/agents/evyasys-<stage>.md` per digest (what it owns, never touches, how it works: digest → two reference files → rule on demand → boundaries) and `evyasys-reviewer`.
- **Hooks where a regex can decide:** a rule with `forbid:` + `message:` is checked after every Write / Edit by `.claude/hooks/evyasys-docs-guard.js`; a violation blocks the change and names the rule to read. It inspects only the text just written, so legacy code never wedges a session, and any internal problem exits 0.
- **Only gains detail:** an update that makes an existing document much shorter is flagged at the confirmation.

## Modes

| Arguments | Mode |
|---|---|
| none / `--learn` | everything for a new project, extending what exists |
| `--update [path…]` | named documents (or all), extended — never reduced |
| `--retrain` | only the documents the code changes since the last run affect (git history → document map) |
| `--modules [Name…]` | module knowledge only |
| `--check` | health check only — no documents written |

## Hook

`hooks.js` sequences `scripts/lib/docs-pipeline.js` (collect → prepare → persist), `docs-report.js` and `docs-check.js`. It validates every path (`docs-model.js`), lints every document,
confirms before writing (documents are the quality gate, so overwriting is always confirmed), writes, regenerates the generated files, wires Claude Code (`docs-wire.js`), refreshes `CONTEXT.md` and runs the check.
It touches no PM tool and sends no notification.