CLAUDE.md — General Project Guidelines

This file is the always-on guardrails. Topic-specific detail lives in claude/ (symlinked from ~/dev/claude/claude/). Read those files when the situation calls for them — see the pointer table at the bottom.

Tone and Interaction

No hedge words. Less is more.

No intro paragraph. The user doesn't need a repeat of what they said, or validation of their idea.

No validation. Give direct and honest feedback. Do not validate an idea just because it exists.

Question the question. Before answering, check: is this the right question? Common failure modes:

XY problem: the question asks how to do X, but X is a means to an unstated goal Y with a better path. Name the Y and address that.
False premise: the question assumes something that may be wrong. State the assumption and challenge it before answering.
Scope creep in disguise: the question has a well-defined answer that solves only a symptom. Note the larger problem if it's obvious.

When any of these apply, lead with the reframe: "The better question here is probably: ..." — then answer that.

One clarifying question, not many. If critical context is missing and would substantially change the answer, ask the single most important question. Don't fire off a list.

Plain Language (ISO 24495-1:2023)

All prose you write for people follows the ISO 24495-1:2023 Plain Language standard. This covers chat responses, and documentation such as README, CLAUDE.md, CONTEXT.md, MEMORY.md, FUTURE.md, specs, plans, runbooks, session logs, commit messages, and PR descriptions. It does not cover code, config, or machine-read formats, where the surrounding conventions win.

Before writing, name the reader and what they need to do with the text. Then check the draft against the standard's four principles:

Relevant: include what this reader needs to act or decide, and leave out the rest. Put the conclusion or required action first.
Findable: use descriptive headings, a logical order, and lists or tables where they help scanning. A reader should locate their answer without reading everything.
Understandable: short sentences, one idea each. Common words over jargon. Define a term or acronym on first use unless the reader already knows it. Use the same word for the same thing throughout. Prefer active voice and concrete subjects.
Usable: write so the reader can do the task with the text alone. Give steps in order, with exact commands, paths, and expected results. Say what to do, not only what to avoid.

Where this conflicts with brevity, keep the plain version. Where it conflicts with exact technical terms, keep the term and define it once.

Session Start

Before showing any picker, check for auto-selection signals:

From cwd: if $PWD is ~/dev/claude/<name> or starts with ~/dev/claude/<name>/ (where <name> is a known project directory, not secrets/), that project is auto-selected.
From active-mode.env: if $CLAUDE_CONFIG_DIR is set and $CLAUDE_CONFIG_DIR/active-mode.env exists, read it. If CLAUDE_PROJECT is non-empty, that project is auto-selected. Also read CLAUDE_MODE and CLAUDE_MODE_TAG for the announcement below.
Cwd takes precedence if both signals are present and disagree.

If a project was auto-selected, skip the picker and open your first response with:

Auto-selected project <name>. [Engagement mode: <mode-tag>] — starting load now.

Then proceed directly to step 2. Otherwise:

Immediately (without waiting for user input) use the project CLAUDE.md paths listed in the CLAUDE.md FILES section provided by context-load to identify projects under ~/dev/claude/ (excluding secrets/). Present a numbered menu like:
What are we working on today?
1. cluster-bootstrap — Kubernetes homelab cluster
2. custom-claude-skills — Reusable Claude Code skills ... N-1. No project right now — just chat N. New project! — start something new
Include a brief description from each project's ABOUT.md/CLAUDE.md/README.md. The project list is generated fresh each session, so new projects are always visible.
Based on the selected project (auto or chosen):
- Existing project: cd into the directory. Pull the latest from the remote (git pull --ff-only) before reading any files — work may have been pushed from another machine or agent. If the pull fails (diverged history, uncommitted changes), warn the user and ask how to proceed. Then read all .md files at the project root, and read ~/dev/claude/secrets/ (read-only — review every file to refresh context). Then read BESTPRACTICES.md (loaded automatically by context-load) and load topic files relevant to the project's stack. Ask clarifying questions if anything is unclear.
- No project right now: do nothing further — just respond normally.
- New project! Follow claude/new-projects.md. Also read ~/dev/claude/secrets/ and the relevant best-practices/ topic files for the stack.
Set the status line topic once the user has selected a project or described their task. See claude/status-line.md.

Secrets (`~/dev/claude/secrets/`)

CRITICAL — treat this folder with extreme paranoia:

Files in ~/dev/claude/secrets/ are read-only. Never edit them.
Never copy, echo, write, or reproduce secret values into any other file — not MEMORY.md, not CLAUDE.md, not commit messages, not scripts, not tool output, nowhere.
Never include secret values in git commits, diffs, or changelogs of any project.
Never pass secret values as command-line arguments (visible in ps). Use @file references, env vars sourced at runtime, or stdin.
When a task requires a secret, read it at execution time from the secrets folder and use it ephemerally. Do not cache or persist the value.
Referencing the existence of a secret file is fine (e.g., "credentials are in ~/dev/claude/secrets/gitea/ai_enablement") — referencing the contents is not.

Gitea CI visibility

When working with Gitea (watching Actions runs, checking whether a release/container built, diagnosing failing CI), use gitea-agent-companion — alias gac, installed in ~/sbin, source at projects/gitea-agent-companion. Run gitea-agent-companion --help first: the help text is the full reference (verbs, flags, token discovery, exit codes). Canonical post-push pattern: gac tail <owner/repo> --until run-complete --timeout 600; on failure, gac inspect <owner/repo> --run <N> --logs — or /ci-triage-minimax owner/repo <N> to triage a long failure log in MiniMax instead of in-session. Note: gac does NOT auto-discover the secrets-path token (as of v0.0.2.10) — set GITEA_TOKEN_FILE=~/dev/claude/secrets/gitea/ai_admin/token (the token file, not the directory); ci-triage-minimax-run defaults this itself.

Subagent coding tasks — use `mm-worktree-task`

For any coding task delegated to a subagent in a project that has a planner (a cp-cli planner reference in its CLAUDE.md), strongly prefer mm-worktree-task <item-uuid> over hand-written subagent briefs or /ask-minimax. It fetches the work item, its documents, parent and siblings from the planner, prepends the standard implementation preamble, runs MiniMax M3.1-Flash-Preview (1M context, effort max; --m3 for M3) detached in its own git worktree and branch, and can attach the report back to the item (--collect --upload). Source and spec: projects/small-scripts (scripts/mm-worktree-task, specs/mm-worktree-task.spec.md); pattern and gotchas: projects/agent-runtimes/memory/gotchas-minimax.md. The supervising session still owns review: run the full suite on the merged tree, and check any wire-shape change against the live server model before merging. Fall back to a Claude subagent only when the task has no work item or needs tools MiniMax cannot use.

Process Principles

Hard-won lessons that apply across every project:

Read the gotcha before you diagnose. When an issue surfaces (HTTP 4xx/5xx, hung connection, perpetual OutOfSync, "permission denied", silent drop, etc.), the FIRST step is to grep ~/dev/claude/projects/best-practices/<topic>.md and the project's memory/gotchas-*.md for keywords matching the symptom AND the technologies involved. Search both the symptom (e.g., permission denied, 30s timeout, not matching) and the infrastructure (e.g., cilium, ipBlock, ESO, apiserver). Do this BEFORE forming your first hypothesis. Turns a multi-hour investigation into a 5-minute lookup. If the gotcha isn't there, capture the new one when you solve it.
Validate locally, deploy once. Don't use the live environment as a test bed. Catch errors with local validation tools before pushing (helm template, kustomize build, lint/typecheck, docker inspect, etc.). Batch fixes locally, push once.
Check before you act. Before writing firewall/network rules, check actual routing (ip route get). Before running config management with variables, ensure values are real, not placeholders. Before assuming a container has a shell, docker inspect it. For state-changing infrastructure actions (network links, DNS records, branch protection, cluster/auth settings, settings files): investigate read-only, present the plan, and get explicit approval before changing anything.
Test the full chain immediately. After wiring up a new service or endpoint, test end-to-end from the user's perspective right away. Don't assume intermediate steps working means the whole chain works.
Verify scripts should be environment-resilient. Avoid needing sudo or special access. Test from the accessible side of a connection. Use curl --resolve to bypass DNS/proxy layers when testing direct connectivity.
Automate repeated sequences. If you run the same 3+ commands in sequence more than once, it should become a script.
Reflect after milestones. Don't just finish — review what happened, what went wrong, what can be improved. Write it down.
Pre-flight before push. Before any git push: derive the SSH alias from git remote get-url origin, then run ssh-add -l and inspect the full output — keys are often pre-loaded, so always check before asking the user to load one. Use grep -i (case-insensitive) when scanning for the relevant key name. Only ask if the key is genuinely absent. Passphrase-protected keys must be ssh-added by the user — hand off, don't retry. If a push fails: commit locally, say so explicitly, note the recovery step in CONTEXT.md. Details: claude/source-control.md.
Everyday shell/edit footguns. grep exits 1 on no match (breaks set -e chains); Edit replace_all matches substrings — make the old string unique. Full list: claude/scripting-conventions.md.

Session End

Run /end-session (session log + CONTEXT.md refresh + doc updates), then commit and push — applying the SSH pre-flight above. A session is not finished while completed work sits unpushed. If the push fails, say so explicitly and record the recovery step in CONTEXT.md before stopping.

Version & Secrets Management (compact rules)

Use the latest stable version of dependencies unless pinned for a reason. Verify versions from live sources (helm search repo, upstream docs) — don't rely on memory. Document the reason in a comment if pinned below latest. Check compatibility matrices before upgrading.
SOPS + age is the standard encryption tool across all projects. .sops.yaml at the repo root defines path-based encryption rules. Filenames containing secret trigger SOPS encryption via pre-commit hooks. Non-secret files must NOT contain secret in their name. Keep unencrypted secrets in local_secrets/ (gitignored).

Detail files — when to read

Pull one of these in only when the situation calls for it. Listed in roughly descending frequency.

File	Read when
`claude/source-control.md`	Touching git, creating repos, setting up remotes
`claude/agent-runtimes-cp.md`	Dispatching work to agent containers / hosted CP
`claude/agent-dispatch-preflight.md`	Before starting any dispatch loop, /orchestrate autoloop, or agent batch
`claude/status-line.md`	Setting or updating the status line topic
`claude/plan-mode.md`	In plan mode — before calling `ExitPlanMode`
`claude/spec-driven-development.md`	Starting a milestone / writing or editing specs
`claude/milestones.md`	Completing a milestone (verification, reflection)
`claude/documentation-standards.md`	Creating or restructuring project doc files (ABOUT/CLAUDE/MEMORY/CONTEXT/FUTURE/README)
`claude/new-projects.md`	Creating a new project from scratch
`claude/scripting-conventions.md`	Writing a new script, or non-trivial shell one-liners (bash safety)
`claude/script-skill-documentation.md`	Authoring or editing a script in claude-foundations or a skill in custom-claude-skills
`claude/knowledge-distillation.md`	Running `/log`, `/reflect-logs`, or `/distill-best-practices`
`claude/ask-minimax-usage.md`	Considering delegating a file-heavy task to MiniMax
`claude/impeccable.md`	Skill maintenance/install for Impeccable (design skill): updating the version, re-applying the no-auto-invoke flag, hint-shim sync, detector usage

14 KiB Raw Blame History