admin
caa79e95c6
gates / gates (push) Successful in 2m38s
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0159rPz1ZhFKsS53msqPYxtS
64 lines
4.5 KiB
Markdown
64 lines
4.5 KiB
Markdown
# 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").
|