felhom.eu/documentation/architecture/12-agent-tooling.md

12 — The agent-tooling layer: who owns which artifact, and where an instruction lives

What this is: the map of how the project's two AI roles split the work, and where each kind of instruction is kept. Written 2026-10-06 night (R-392) from the files as they are. It records what exists; it does not restate the writing rules — those are in the felhom-doc-authoring skill (skills/felhom-doc-authoring/SKILL.md), and this page only points at them.

Marks as in 00-capability-map.md: [FACT] = read in a named file; [DESIGN] = a decision.

1. The two roles

Role	Where it runs	Owns
Project Claude (the planning and architecture assistant, claude.ai)	the operator's chat	the specs (TASK-*.md), the procedures (RUNBOOK-*.md), the night briefs (drills/*.md), and validation: checking a push against a spec's criteria
Claude Code (CC)	DooPlex, as kisfenyo, inside tmux	implementing a spec, executing a runbook's steps on live hosts it can reach, the repos' main, CHANGELOG.md / REPORT.md, and the register rows it files

[FACT] The taxonomy and its reason („a file open in the editor is NOT an instruction") are in the workspace-root CLAUDE.md § „Artifact taxonomy". [FACT] The spec shape is documentation/PROMPT-TEMPLATE.md (who writes it, who executes it, the mandatory sections per task class). Validation is project Claude's unless CC is asked (CLAUDE.md, same section).

A session with no spec (a /goal, a night brief, „work the register") inherits the discipline a spec used to carry from .claude/rules/unprompted-work.md — [FACT] five byte-identical copies: the workspace root and each of the four repos (the file's own header says „change all five or none").

2. Where an instruction lives

Kind of material	Home	Loaded
Cross-repo facts and standing rules (production host, gates, secrets, CHANGELOG/REPORT)	workspace-root CLAUDE.md	every session in the workspace
One repo's stable orientation	<repo>/CLAUDE.md	when a file in that repo is touched
Path-scoped rules (a subsystem's traps)	<repo>/.claude/rules/*.md	when a matching path is touched
A procedure with steps (build, test, diagnose, write for the operator)	a skill, felhom.eu/skills/<name>/SKILL.md	when its trigger matches, or by name
Current state, decisions, open work	CONTEXT.md, STATUS.md, documentation/backlog/OPEN-ITEMS.md	read on demand — never copied into an instruction file
Durable cross-session facts about the operator and the machines	the memory folder (.claude-memory/, index MEMORY.md)	the index each session; files on recall

Which rung a piece of material belongs on is the doc-authoring skill's §3 („Where a piece of material sits") and §6 („One rule, one home"). This page does not repeat them.

[FACT] Skills are written in felhom.eu/skills/, installed by python3 felhom.eu/scripts/install_skills.py as symlinks into ~/.claude/skills/ (so a repo edit is live at once), and checked by python3 felhom.eu/scripts/check_skills.py (shape, the 150-line limit and its one grandfathered entry, R-394). The list is the folder; skills/SOURCES.md names where each skill's material came from.

3. Who may change an instruction file

[DESIGN, operator ruling 2026-10-06, 09 §3 decision 150] A session keeps instruction files true: it may correct a stale fact, add a fact it proved, and remove a reference to something gone, naming each edit in its report. It may NOT loosen a safety rule, a fence, a „never", a protected machine, a secret rule or a review step, or remove a rule — that is the operator's. The full text is §5 of .claude/rules/unprompted-work.md.

4. Why the boundaries sit where they do

• The spec author does not execute, and the executor does not validate its own spec — the reviewer of a push is a different context from the one that wrote it (CLAUDE.md „Artifact taxonomy").
• State is never kept in an instruction file — versions change several times a day and the fleet is not uniform (CLAUDE.md § Access: „Component versions are not recorded in any inventory doc"). An instruction that carries state goes stale silently; a pointer to where state is read does not.
• A procedure is a skill, not a paragraph in CLAUDE.md — a CLAUDE.md is paid for on every session; a skill only when its trigger matches (doc-authoring skill §2, „The two costs").