Naming Conventions

REFERENCE — consult while working. No rationale here; see understanding-explanation/ for design decisions.

Files

Context	Convention	Example
General files	kebab-case, lowercase	reference_audio-pipeline.md
Federation context	{rank}_{pillar}_{agent}_context.md	colonel_goku-fire_killua-friendship_context.md
Federation agent def	{rank}_{pillar}_{agent}_agent.md	colonel_goku-fire_killua-friendship_agent.md
Federation sub-topic	{rank}_{pillar}_{agent}_{topic}_context.md	colonel_levi-ackerman-forge_squidward-music_piano_context.md
Captain context	captain_{captain-name}_context.md	captain_canary-organiser_context.md
Captain lieutenant	captain_{captain}_{lieutenant}_context.md	captain_canary-organiser_nami-routing_context.md
Handover files	memory/memory_{cli-name}.md	memory_claude-code.md
Transcript files	{cli-name}-transcript.md	claude-code-transcript.md
Date-stamped files	YYYY-MM-DD-{topic}.md	2026-06-07-vps-migration.md
Audit files	{dd-mm-yy}_{audit-type}.md — flat in the-government/audits/	14-06-26_agent.md, 11-06-26_task.md
One-shot scripts	oneshot-YYYY-MM-DD-{purpose}.py or .sh — deleted in the same session they run	oneshot-2026-06-11-id-migration.py

Audit files (2026-06-14)

All audit outputs live flat in the-government/audits/ under {dd-mm-yy}_{audit-type}.md. The folder name carries "audit"; the file name carries date + type only. audit-type is the kind of audit (agent, task, website, credential, transcript, orchestration, diataxis-migration, documentation-gaps, etc.) — never includes the word "audit" itself. Date is the leading 2-digit dd-mm-yy. Lowercase kebab-case applies to the audit-type slug. Multiple audits of the same type on the same day take a -b, -c suffix on the slug (e.g. 09-06-26_task-b.md). Index lives at audits/index.md. Ruling: Michael, 2026-06-14 ("flat folder in audits/ {dd-mm-yy}_{audit-type}"). Supersedes the prior [scope]-audit-YYYY-MM-DD.md and audit_[scope]-YYYY-MM-DD.md shapes.

One-shot scripts & script registry (2026-06-11)

Permanent top-level .py/.sh scripts in Sandpit/hinata-sandpit/scripts/ and Sandpit/hinata/scripts/ must hold a row in scripts/script-manifest.json (one-line purpose). scan-orphan-scripts.py (session-end Batch 2) flags unregistered scripts, oneshot-* files older than 24h, and stale manifest rows. One-shots are never registered — run, then delete in the same session. Ruling: 2026-06-11, after four orphaned one-shot patch scripts accumulated unreferenced (task 800136).

Retired scripts are deleted outright (git rm for tracked files; manifest row removed in the same commit) — git history is the recovery surface. The former scripts/_archive/ holding pen is purged and retired; never recreate it, and never park a script under a -deprecated-* suffix. Ruling: Michael, 2026-06-11 ("delete deprecated scripts").

No historical versions are retained on any surface (Mac, sandpit, vault, Z2 host, containers): the moment a successor goes live, the superseded script and its runtime artefacts (systemd/launchd units, logs, token copies) are deleted in the same session — only the most efficient, effective current version survives. Ruling: Michael, 2026-06-11 ("all dead scripts should be deleted — don't need historical scripts, just the most efficient effective version today retained").

Folders

Context	Convention	Example
Top-level directories	kebab-case, lowercase	supreme-court/, the-government/
Subdirectories	kebab-case, lowercase	information-reference/, how-to-guides/
No empty placeholder names	name describes content, not aspiration	format-design/ not format-design-TODO/
No version suffixes	content replaces, never versions	hinata-infrastructure/ not hinata-infrastructure-v2/
No date prefixes on folders	dates go on files, not folders	z2-sandpit-sync/ not 2026-05-z2-sandpit-sync/

Agents

Context	Convention	Example
Commander name	kebab-case character name	killua-friendship, bulma-finances
Colonel name	{character}-{pillar-theme}	levi-ackerman-forge, saitama-foundation
Captain name	kebab-case with role suffix	canary-organiser, jimmy-neutron-brain-ops
Lieutenant name	kebab-case role descriptor	nami-routing, robin-intent
Compound agent	{captain}-{lieutenant}	meruem-toph
Demoted/archived agent	move to federation/demoted/	demoted/splinter-reading.md

Subagent Dispatch

Every dispatch carries five dimensions. Three map to Agent tool parameters; two are encoded in the prompt.

Five dispatch dimensions

Dimension	Agent tool field	Value	Example
subagent_name	description (prefix)	Federation member name	"Jimmy Neutron"
subagent_type	subagent_type	Commander/Captain name (registered in .claude/agents/)	"Jimmy Neutron"
action_type	Prompt prefix [Plan] / [Explore] / omit for execute	Operation mode	[Plan]
description	description (body after name)	Task description	"CT106 Itachi bind mount"
model	model	Always "sonnet" for subagents (see model-policy)	"sonnet"

Working-directory rule (2026-06-11)

Dispatches never instruct an agent to cd away from the vault — Sandpit/Z2 work uses absolute paths. The harness writes agent memory relative to the project dir the agent runs from; running from another repo sprouts a parallel .claude/agent-memory/ there (observed: Jimmy-Neutron in hinata-sandpit, 2026-06-10). The vault copy is sole canon; other repos gitignore .claude/. See ../runtime/memory-architecture.

Description field format

{Name}: {task} — the name is the primary key for per-commander token attribution.

Context	Convention	Example
Commander dispatch	{Name}: {task}	"Trunks: studio dashboard fix"
Captain dispatch	{Name}: {task}	"Jimmy Neutron: Z2 mount config"
Colonel dispatch	Colonel {Name}: {task}	"Colonel Levi Ackerman: forge synthesis"
Lieutenant dispatch	{Name}: {task}	"Toph: grounding check"

Canonical dispatch example

Agent(
  subagent_type="Jimmy Neutron",
  description="Jimmy Neutron: CT106 Itachi bind mount",
  model="sonnet",
  prompt="Load captain_jimmy-neutron-brain-ops_context.md from /Users/nnamdi/hinata-v2/federation/. Task: ..."
)

Prompt structure

Every subagent prompt MUST:

1. Load the agent's context file: Load federation/{context_file}. Then: ...
2. Reference relevant supreme-court strategy if the task touches doctrine
3. Constrain file access to approved paths only — subagents do not inherit access rules from the main thread

Dispatch output contract (research / audit / multi-step execute)

Law since 2026-06-10 (finding H14, full-stack diagnostic — four of seven first-wave audit arms died on working notes; every contract-carrying rescue succeeded, including a 7-item infra bundle closed in 24 calls). Every research, audit, or multi-step execute dispatch MUST carry all six elements:

Element	Form
Objective	One sentence — what done looks like
Seed evidence	The files/paths/facts already known, so the agent doesn't re-derive them
Tool budget	≤N tool calls, sized to the task
Stop-at-80% rule	At ~80% of budget, STOP gathering and WRITE the report regardless of completeness
Final-message schema	The exact headings/fields the last message must contain
Failure clause	No report = failed run — working notes do not count as output

A dispatch missing any element is malformed — the dispatcher owns the failure, not the agent.

Access control propagation

Subagents have no knowledge of the blacklist or whitelist unless told. Any prompt involving file search or reads MUST include:

Permitted search paths: /Users/nnamdi/hinata-v2/, /Users/nnamdi/Sandpit/hinata/, /Users/nnamdi/Sandpit/hinata-sandpit/, ~/Library/CloudStorage/OneDrive-Personal/hinata/hinata-inbox/
Do NOT search or read outside these paths.

Never use find /Users/nnamdi/ (home root scan) — always scope to a specific permitted path.

Forbidden

• subagent_type: "general-purpose" — never use
• subagent_type with an unregistered name — register in .claude/agents/ first
• Omitting subagent_type — defaults to general-purpose, equally forbidden
• Omitting the agent name from description — breaks token attribution
• Omitting model — always required, always "sonnet" for subagents

Attribution chain

description field → JSONL session log → check-delegation-ratio.py parses commander tag → classifies into band → per-commander token attribution → Orochimaru token-burn report → Meruem evolution assessment (token efficiency dimension).

Git Branches

Context	Convention	Example
Cloud task branches	cloud/{task-id}	cloud/t212c1
Feature branches	{scope}/{kebab-description}	infra/z2-collector-deploy
Never push to	main (from cloud)	—

Identifiers

Context	Convention	Example
Task IDs	#{category-prefix}{sequence}	#840045
Category prefixes	2=michael, 3=learning, 4=coding, 5=music, 6=health, 7=portfolio, 8=infra, 9=strategy	#800028 = infra
Short task IDs	6-char alphanumeric, ≥4 numerals	t212c1, 49b001
Task ID validity	6 characters, at least 4 numerals (Michael ruling 2026-06-11) — applies to both forms	800128 ✓ · task-028 ✗
Session IDs	CLI-assigned	—

Task ID binding (2026-06-11)

the-government/tasks/tasks.json id fields store the category-prefixed numeric form, bare — no # sigil (800128, not #800128); the # is prose/display only. Sequential task-NNN IDs are forbidden. Drift incident: the v2 task file was seeded 2026-06-09 with task-001-style IDs and every subsequent session pattern-matched the file instead of consulting this law — 36 rows accreted before the 2026-06-11 migration (full old→new map in 11-06-26_task). When writing a task row, take the format from this table, never from existing rows. New rows continue the category's sequence ({prefix}{5-digit sequence}).

Terminology Ownership (2026-06-11)

Three surfaces, three jobs — no overlap (resolves full-stack-diagnostic L2):

Surface	Owns	Does not own
This file (naming-conventions)	Naming rules — formats, conventions, validity	Definitions, inventories
glossary	Term definitions vault-wide	Naming rules
naming-register	Infrastructure name inventory (hosts, CTs, accounts) under this file's rules	Rules or terminology

Phase Numbering

Phases in skills, audits, and multi-step plans use integers only (1–200). No sub-letters (1a, 1b, 2c). If a step needs substeps, promote each substep to its own numbered phase.

Correct	Forbidden
Phase 1, Phase 2, Phase 3	Phase 1a, Phase 1b, Phase 2a
Phase 4 (was "3a")	Phase 3a

Prohibited Patterns

• No version labels: v1, v2, upgraded-from-v1 — content replaces or is new
• No Co-Authored-By trailers in commits
• No vendor model names in author-controlled content — use Tier-O / Tier-S / Tier-H
• No underscores in folder names except the-government diataxis subfolders (see folder-naming-preference)
• No spaces in any file or folder name
• All files and folders lowercase — exceptions: CLAUDE.md, CLOUD.md, CODEX.md, GEMINI.md, ANTIGRAVITY.md (harness contracts), SKILL.md (Claude Code convention), Dockerfile (Docker convention)