admin
ba40c0a25b
gates / gates (push) Successful in 6m44s
Build skill (hub token, ISO publish), fb_probe (token from `sec run` env, tests red-proved), secrets.md (Resend: pipe inside sec run), bench README, read_credential docstring, 12-agent-tooling §5, workspace CLAUDE secrets line. Evidence: audits/cc-creds-build-2026-10-17/ (tests, red-proofs, 36-row child-session proof both launch modes, install, fresh-session proof, import names+lengths, history sweep names). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012qRErfCoiTkvDK9N5XHbzb
73 lines
5.1 KiB
Markdown
73 lines
5.1 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").
|
|
|
|
## 5. Secrets — how CC obtains one
|
|
|
|
**Pointer, not a copy:** the private repo `admin/cc-secrets` (cloned at `/mnt/5_hdd/felhom.eu/git/cc-secrets`), its
|
|
`ARCHITECTURE.md`. In one line: an encrypted store (SOPS + age, operator ruling 2026-10-17 11:28), a broker `sec`
|
|
that uses a value by NAME and never prints it, and Claude Code hooks in `~/.claude/settings.json` — so every CC
|
|
session on DooPlex — that refuse the known leak shapes, mask stored values in tool output, and a nightly sweep of old
|
|
session records that mails NAMES only. Built 2026-10-17 (R-1118); evidence `audits/cc-creds-build-2026-10-17/`.
|
|
`runbooks/secrets.md` stays the home of the CLUSTER Secrets.
|