metal — architecture

← back to metal · reference · history · telemetry · v0 · r713 · 2026-04-22 · 1,216 pts

Two repos

Repo Cloned to Purpose
joeycastilloUS/joeycastillo.us web Cloudflare Pages Website. Serves install scripts, Li, Na, product page, architecture, history at joeycastillo.us/metal/
joeycastilloUS/metal metal C:\metal or ~/metal Everything: launcher, tilde commands, settings, Fe, artifacts
Private repo. metal is private. The user must authenticate with gh auth login before cloning.

File structure

Website repo web — joeycastillo.us/metal/

install.bat Windows first-time setup. git → gh → auth → clone → Fe → go. install.sh Mac/Linux first-time setup. Same flow. Go.Li.bat Lithium (Li) — Windows OS diet. Standalone add-on, 12 steps, zero deps. Go.Li.sh Lithium (Li) — Mac/Linux OS diet. Standalone add-on. Go.Na.bat Sodium (Na) — Windows reset. Removes metal repo, leaves tools + OS. Go.Na.sh Sodium (Na) — Mac/Linux reset. Same cleanup. index.html Product page — tilde commands as hero, install, Fe, Na, Li add-on. history.html Version changelog. architecture.html This document. favicon-m.svg Favicon

Metal repo metal — C:\metal or ~/metal

go.bat Daily launcher (103 lines). Dirty-tree handler + Claude Code launch. go.sh Mac/Linux daily launcher (98 lines). exec < /dev/tty for stdin fix. CLAUDE.md THE PRODUCT — tilde-command kernel (~14k chars). Routes to be/docs/. settings.json Tool whitelist — Bash(*), all built-ins, mcp__*. effortLevel: max. Zero prompts. .mcp.json MCP server defaults — project-scope Slack + GitHub. Auto-discovered. Go.Fe.bat Iron (Fe) — Windows dev tools + identity + MCP + auth. Go.Fe.sh Iron (Fe) — Mac/Linux dev tools + identity + MCP + auth. brew/apt/dnf/pacman. .gitconfig Git identity — name, email, GPG signing key, aliases. claude/ Claude Code settings — settings.json, settings.local.json. be/ Be artifacts — plans, builds, tests, ships, retros, transfers. be/docs/ Lazy-loaded specs — commands.md (21 commands), conventions.md (deploy/auth). be/debug/ Debug logs — one per session (YYYY-MM-DD-HH-MM.log). Read by ~R retro. auth/ Pure C auth library — crypt, totp, qr, auth, gate. Zero deps beyond libc. logs/ Tool install logs — one file per install, created at runtime. .tools-done Version marker — skip Fe tools phase if version matches. README.md Project readme.

Dev tools installed by Fe

Iron (Go.Fe) installs these tools. Idempotent — skips what's already there.

CategoryToolsInstaller
Core Git, GCC (MinGW-w64), Make winget / brew / apt / dnf / pacman
Languages Python 3.12, Node.js LTS, Rust (rustup) winget / brew / apt / dnf / pacman
Cloud + CLI GitHub CLI (gh), Google Cloud CLI (gcloud) winget / brew / apt / dnf / pacman
npm Claude Code, Wrangler (Cloudflare), Snowflake CLI npm / pip
Browsers Chrome, Firefox, Brave, Opera winget / brew cask (Mac only)

Approved Claude tools (settings.json)

Every tool Claude Code can use, whitelisted. Zero approval prompts.

CategoryTools
Shell Bash(*) — all shell commands
File ops Read, Write, Edit, Glob, Grep
Web WebFetch, WebSearch
Agents Agent, Skill
Tasks TaskCreate, TaskUpdate, TaskGet, TaskList, TaskStop, TaskOutput
Workspace EnterWorktree, ExitWorktree, EnterPlanMode, ExitPlanMode, NotebookEdit
Scheduling CronCreate, CronDelete, CronList, RemoteTrigger
Interactive AskUserQuestion
MCP mcp__* — all MCP server tools (Slack, etc.)
effortLevel: max. skipDangerousModePermissionPrompt: true. Full autonomy.

Tilde commands (Be)

The tilde-command system. Defined in CLAUDE.md (kernel, ~14k chars) with full specs lazy-loaded from be/docs/commands.md and be/docs/conventions.md.

CommandNameWhat it does
~NNewCreate a new project — repo, be/ scaffold, CLAUDE.md
~LIListList all projects — local, remote, open transfers
~LLoadLoad a repo — clone, sync, switch context
~ULUnloadClose out a project — housekeep, report, switch back
~IInspectRead a repo, URL, or codebase — report what's there
~PPlanPlan it, render it, save it
~PUUser StoryPlan as a user story with acceptance criteria
~PTPlan TestPlan the test strategy
~EEstimateBreak a plan into sized kanban boards
~AAddAdd something new — review, report, commit, demo
~UUpdateUpdate existing code or feature
~DDeleteRemove code, feature, or files
~FFixFix a bug — diagnose, fix, write a test, ship proof
~BBuildBuild it — or pull next from the board
~BTBuild TestBuild the tests for a feature
~TTestTest it, fix what's broken
~SShipCommit, push, version bump, deploy
~MonitorMonitorWatch the deploy — verify it's live and healthy
~DemoDemoDemo, review, or refactor code
~RRetroRetrospect recent work — what went well, what didn't
~MMCPManage MCP servers — add, remove, diagnose, setup
~CRRecoverCrash recovery — read the dirt, resume the chain
~TransferTransferProject handoff — scan, clean, manifest for recipient
~HHelpThree-column workflow guide with use cases
~JCJoey's Take40 years of architecture advice, on demand
Every tilde command (except ~H) produces an HTML report. Chain reaction: do the work → review → render report → update index → commit → push → launch demo.

~chain-reaction

Named workflow macros with loop segments. Define a chain once, run it forever.

~P ~E /~B ~T/ ~S ~R Commands outside / run once, left to right. Commands inside / / loop until: board exhausted + tests pass. Built-in chains: ~GO ~P ~E /~B ~T/ ~S ~R Full lifecycle: plan to retro ~HOTFIX ~I ~P /~T ~F/ ~S ~R Inspect, plan fix, test/fix loop, ship, retro

Definition of Done (DoD)

Every tilde command that produces an artifact must pass all 7 items before the command is considered complete. If any item fails, the command is not Done. Fix in-place and re-verify.

The 7 Items 1. Code committed — All changes in a git commit with descriptive message. No uncommitted work. 2. Commit hash in telemetry — be/telemetry.json entry has a non-null commit field. 3. Board updated — If a board item was worked, it moved to Done with commit hash. 4. HTML report saved — Report exists in be/ with correct datetime filename. 5. Index updated — be/index.html has an entry linking to the new report. 6. Pushed to remote — git push succeeded. Work exists on origin. 7. No prior work damaged — Done items untouched unless a new item targets them. Chain-final commands (~s, ~r) also require: 8. Chain complete — Every preceding step has a telemetry entry with non-null commit hash. DoD-exempt commands: ~h, ~li, ~l, ~cr, ~jc, ~m (utility, no artifacts)

Definition of Ready (DoR)

Before the first edit of a session, verify:

1. Board state — Read be/board.md. Know what's Done, In Progress, Ready. 2. Last telemetry entry — Was the previous chain completed? Flag if not. 3. Source of truth — Respect canonical files declared in CLAUDE.md.
DoD is defined in CLAUDE.md (source of truth), with an execution copy in be/docs/commands.md and a pre-deploy gate in be/docs/conventions.md.

CLAUDE.md kernel split

CLAUDE.md was 45k characters — too large. Split into a lean kernel (~14k) with full specs lazy-loaded from be/docs/.

CLAUDE.md Kernel — tilde table, rules, conventions, routing be/docs/commands.md Full specs for all 21 tilde commands be/docs/conventions.md Deploy, auth, manifest conventions Routing rule: When a tilde command is invoked, read the relevant doc file FIRST, find that command's section, then execute. The kernel routes — the doc executes.

Every script, what it does

Website — install + add-ons web

FileWhat it does
install.bat Windows first-time setup. Downloaded to %TEMP% and run.
Shows 6 steps → [Y] yes / [S] skip
[1/6] Install Git (winget)
[2/6] Install GitHub CLI (winget)
[3/6] gh auth login (browser OAuth)
[4/6] gh repo clone metal → C:\metal
[5/6] call "C:\metal\Go.Fe.bat" — Iron (dev tools + auth)
[5b/6] call "C:\metal\Go.Sign.bat" — per-laptop GPG + signing setup
[5c/6] git ls-remote origin in C:\metal — push-auth smoke
[6/6] call "C:\metal\go.bat" — launches Claude Code (Be)
install.sh Mac/Linux first-time setup. Piped to bash.
Same 6 + 2 steps as install.bat but uses xcode-select/brew/apt/dnf/pacman.
gh auth login < /dev/tty for stdin.
[5b/6] bash $METAL_DIR/Go.Sign.sh — per-laptop GPG + signing
[5c/6] git ls-remote origin in $METAL_DIR — push-auth smoke
Ends with bash ~/metal/go.sh
Go.Li.bat Lithium (Li) — Windows diet. Self-contained, zero deps.
Shows 12 steps → [A] all / [P] pick / [S] skip.
Registry tweaks, PowerShell bloatware removal.
Standalone add-on — not part of the main install flow.
Go.Li.sh Lithium (Li) — Mac/Linux diet.
Mac: 9 steps (dark mode, dock, finder, keyboard, remap, trackpad, screenshots, privacy, power).
Linux: 4 steps (dark mode, keyboard, file manager, power).
Same [A] / [P] / [S] menu.
Standalone add-on — not part of the main install flow.
Go.Na.bat Windows reset. Confirms [y/N], then rmdir /s /q C:\metal.
Go.Na.sh Mac/Linux reset. Confirms [y/N], then rm -rf ~/metal.

Daily launcher — go.bat / go.sh metal

Type go from C:\metal or ~/metal. Checks for dirty working tree (offers Stash/Discard/Ignore/Delete/Keep), pulls latest if clean, counts revision and points via be/pts.py, prints the Be banner with v0 · rN · date · pts, then launches Claude Code.

FileWhat it does
go.bat
103 lines		 1. git status --porcelain → dirty-tree handler (5 options with file preview)
2. Clean path: git pull --ff-only --no-rebase
3. git rev-list --count HEAD → revision
4. py be/pts.py → total points
5. Print Be banner
6. claude --permission-mode bypassPermissions
   --settings settings.json
   --append-system-prompt-file CLAUDE.md
   --max-budget-usd 50
   --model opus "~h"
go.sh
98 lines		 Same flow. exec < /dev/tty (fix stdin for curl|bash). python3 be/pts.py with fallback to python.

settings.json metal

File-based tool whitelist. Zero approval prompts. Loaded by go.bat/go.sh via --settings.

KeyValue
permissions.allow Bash(*), Edit, Write, Read, Glob, Grep, WebFetch, WebSearch, Agent, Task*, Skill, NotebookEdit, Worktree, PlanMode, AskUserQuestion, Cron*, RemoteTrigger, mcp__*
effortLevel max
skipDangerousModePermissionPrompt true

Iron (Fe) — Go.Fe.bat / Go.Fe.sh metal

Dev tools + identity + auth. Does its job and returns.

StepDetailWhat happens
Fe 1/3
Dev tools		 Version gate Reads .tools-done. If version matches VERSION, skips entire step.
Otherwise asks [Y/n] to install.
Winget phase Creates logs/tools_YYYYMMDD_HHMM.log.
Each tool: where X → skip if found, else :run_install.
:run_install writes a temp .cmd, wraps it in PowerShell with 300s timeout.
Installs: Git, GCC (MinGW-w64), GitHub CLI, Python 3.12, Node.js LTS, Google Cloud CLI, Rust, Make
npm + pip phase Extends PATH with %APPDATA%\npm and Python dirs.
Upgrades pip. Installs: Claude Code, Wrangler, Snowflake CLI
Then browsers: Chrome, Firefox, Brave, Opera (checks .exe paths, not winget list).
Refreshes PATH from registry via :refresh_path.
Writes version to .tools-done.
Fe 2/3
Identity		 Inline call "C:\metal\Go.Sign.ps1" — per-machine GPG + git config global
copy claude\settings.json → %USERPROFILE%\.claude\settings.json
copy claude\settings.local.json → %USERPROFILE%\.claude\settings.local.json
Note: .gitconfig ships [filter "lfs"] only; identity is per-laptop.
Fe 3/3
Auth		 Inline gh auth status → skip or gh auth login
gcloud auth print-access-token → skip or gcloud auth login

Subroutines in Go.Fe.bat

LabelWhat it does
:refresh_path Reads PATH from HKLM\...\Environment and HKCU\Environment registry keys.
Rebuilds the PATH variable from scratch. Warning: can drop System32.
:log Appends timestamped line to LOGFILE. No-op if LOGFILE not set.
:skip Logs skip, prints "already installed", increments SKIP_COUNT.
:run_install Writes command to %TEMP%\metal_run.cmd.
Wraps in PowerShell Start-Process with WaitForExit(300000).
Captures stdout/stderr to temp files, appends to log.
Exit 258 = timeout. Nonzero = fail. Zero = OK.

Iron (Fe) — Go.Fe.sh details metal

Mac/Linux version. Same three steps as .bat, different package managers.

StepDetailWhat happens
Fe 1/3
Dev tools		 Version gate Reads .tools-done, strips whitespace. If matches VERSION, skips.
Otherwise asks [Y/n].
Core tools Mac: xcode-select → Homebrew → brew install.
Linux: apt/dnf/pacman auto-detected for each tool.
install_pkg() helper checks command -v before install.
Installs: git, gh, python3, node, make, Rust (rustup), gcloud
Each wrapped in run_install() with timeout via timeout/gtimeout.
npm + pip + browsers Claude Code, Wrangler, Snowflake CLI via npm/pip.
Mac browsers: Chrome, Firefox, Brave, Opera via brew --cask.
Linux: Firefox only (others vary by distro).
Writes version to .tools-done.
Fe 2/3
Identity		 Inline bash Go.Sign.sh — per-machine GPG + git config global
Copies Claude settings to ~/.claude/
Note: .gitconfig ships [filter "lfs"] only; identity is per-laptop.
Fe 3/3
Auth		 Inline gh auth status → skip or gh auth login < /dev/tty
gcloud auth print-access-token → skip or gcloud auth login < /dev/tty

Helper functions in Go.Fe.sh

FunctionWhat it does
log() Appends timestamped line to $LOGFILE.
run_install() Runs command with timeout/gtimeout wrapper (300s default).
Exit 124 = timeout. Nonzero = fail. Zero = OK. Logs everything.
install_pkg() Checks command -v first. Then auto-selects: brew (Mac), apt/dnf/pacman (Linux).

Lithium (Li) — standalone add-on web

OS diet scripts. Standalone add-on, run separately.

FileWhat it does
Go.Li.bat Self-contained Windows OS diet. 12 steps: bloatware, Cortana, taskbar, dark mode, explorer, power, privacy, notifications, keyboard, start, clock, OneDrive.
[A] all / [P] pick / [S] skip. Zero deps.
Go.Li.sh Self-contained Mac/Linux OS diet.
Mac: 9 steps. Linux: 4 steps.
[A] all / [P] pick / [S] skip.

Windows flow — full schematic

User runs in CMD: curl -fsSL joeycastillo.us/metal/install.bat -o %TEMP%\install.bat && %TEMP%\install.bat ┌──────────────────────────────────────────────────────────────┐ │ install.bat web runs from %TEMP% │ │ │ │ Shows 6 steps → [Y] yes / [S] skip │ │ [1/6] Install Git (winget) │ │ [2/6] Install GitHub CLI (winget) │ │ [3/6] gh auth login (browser OAuth) │ │ [4/6] gh repo clone metal → C:\metal │ │ [5/6] call "C:\metal\Go.Fe.bat" │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────┐ │ │ │ Go.Fe.bat metal Iron — dev tools + identity │ │ │ │ │ │ │ │ [Fe 1/3] Dev tools │ │ │ │ check .tools-done → skip if version matches │ │ │ │ winget: Git, GCC, gh, Python, Node, │ │ │ │ gcloud, Rust, Make │ │ │ │ npm: Claude Code, Wrangler; pip: Snowflake │ │ │ │ browsers: Chrome, Firefox, Brave, Opera │ │ │ │ write .tools-done │ │ │ │ [Fe 2/3] Identity — Go.Sign.ps1 + claude settings │ │ │ │ [Fe 3/3] Auth — gh + gcloud │ │ │ └────────────────────────────────────────────────────┘ │ │ │ │ [5b/6] call "C:\metal\Go.Sign.bat" │ │ per-laptop GPG key + git config global │ │ signed-commit smoke in scratch repo │ │ [5c/6] git ls-remote origin in C:\metal │ │ HTTPS push-auth verification │ │ │ │ [6/6] call "C:\metal\go.bat" │ │ │ │ └─────────┼────────────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ go.bat metal 103 lines — daily launcher │ │ │ │ Dirty-tree check → [S]tash/[D]iscard/[I]gnore/[X]del/[K]eep │ │ Clean → git pull --ff-only --no-rebase │ │ rev-list --count HEAD → revision │ │ py be/pts.py → total points │ │ Print Be banner: v0 · rN · date · pts │ │ claude --permission-mode bypassPermissions │ │ --settings settings.json │ │ --append-system-prompt-file CLAUDE.md │ │ --max-budget-usd 50 │ │ --model opus "~h" │ │ │ │ ~GO plan-to-retro ~HOTFIX inspect+fix+ship │ └──────────────────────────────────────────────────────────────┘

Mac/Linux flow — full schematic

User runs in Terminal: curl -fsSL joeycastillo.us/metal/install.sh | bash ┌──────────────────────────────────────────────────────────────┐ │ install.sh web piped to bash │ │ │ │ Shows 6 steps → [Y] yes / [S] skip │ │ [1/6] Install Git (xcode-select / apt / dnf / pacman) │ │ [2/6] Install GitHub CLI (brew / apt / dnf / pacman) │ │ [3/6] gh auth login < /dev/tty (browser OAuth) │ │ [4/6] gh repo clone metal → ~/metal │ │ [5/6] bash ~/metal/Go.Fe.sh │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────┐ │ │ │ Go.Fe.sh metal Iron — dev tools + identity │ │ │ │ │ │ │ │ [Fe 1/3] Dev tools │ │ │ │ Mac: xcode-select → Homebrew → brew │ │ │ │ Linux: apt / dnf / pacman (auto-detected) │ │ │ │ git, gh, python3, node, make, Rust, gcloud │ │ │ │ npm: Claude Code, Wrangler; pip: Snowflake │ │ │ │ Mac browsers: brew cask / Linux: Firefox │ │ │ │ write .tools-done │ │ │ │ [Fe 2/3] Identity — Go.Sign.sh + claude settings │ │ │ │ [Fe 3/3] Auth — gh + gcloud < /dev/tty │ │ │ └────────────────────────────────────────────────────┘ │ │ │ │ [5b/6] bash $METAL_DIR/Go.Sign.sh │ │ per-laptop GPG key + git config global │ │ signed-commit smoke in scratch repo │ │ [5c/6] git ls-remote origin in $METAL_DIR │ │ HTTPS push-auth verification │ │ │ │ [6/6] bash ~/metal/go.sh │ │ │ │ └─────────┼────────────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ go.sh metal 98 lines — daily launcher │ │ │ │ exec < /dev/tty (fix stdin for curl|bash) │ │ Dirty-tree check → [S]tash/[D]iscard/[I]gnore/[X]del/[K]eep │ │ Clean → git pull --ff-only --no-rebase │ │ python3 be/pts.py → total points │ │ Print Be banner: v0 · rN · date · pts │ │ claude --permission-mode bypassPermissions │ │ --settings settings.json │ │ --append-system-prompt-file CLAUDE.md │ │ --max-budget-usd 50 │ │ --model opus "~h" │ │ │ │ ~GO plan-to-retro ~HOTFIX inspect+fix+ship │ └──────────────────────────────────────────────────────────────┘

Daily use flow

User types from C:\metal or ~/metal: go ┌──────────────────────────────────────────────────────────────┐ │ go.bat / go.sh metal │ │ │ │ Dirty-tree check → [S]tash/[D]iscard/[I]gnore/[X]del/[K]eep │ │ Clean → git pull --ff-only --no-rebase │ │ Count revision + points (be/pts.py) │ │ Print Be banner: v0 · rN · date · pts │ │ │ │ claude --permission-mode bypassPermissions │ │ --settings settings.json │ │ --append-system-prompt-file CLAUDE.md │ │ --max-budget-usd 50 │ │ --model opus "~h" │ │ │ │ CLAUDE.md = tilde command kernel (~14k chars) │ │ be/docs/ = command specs + conventions (lazy-loaded) │ │ settings.json = tool whitelist (zero approval prompts) │ │ "~h" = initial prompt, prints tilde command reference │ │ │ │ Then: ~GO, ~HOTFIX, or any tilde command. │ └──────────────────────────────────────────────────────────────┘

Reset flow (Na)

curl ... Go.Na.bat or curl ... Go.Na.sh | bash Confirms [y/N] → removes C:\metal (or ~/metal) Tools and OS changes stay. Run install.bat/sh to start fresh.

Version markers

One marker file in the metal repo prevents re-running completed steps:

Bumping VERSION in Go.Fe forces tools to re-run on next launch.

Versioning

Version is 0. Always. No semantic versions. Every change is a revision — the git commit count: git rev-list --count HEAD.

Display format: v0 · r388 · 2026-04-09 · 626 pts (version zero + revision + date + total board points).

Total points come from be/board.md — summed by be/pts.py. The launcher computes revision and points at launch time.

Version/revision appears in:

RepoFileWhere
metalgo.bat / go.shcomputed at launch: git rev-list --count HEAD + be/pts.py
metalREADME.mdv0 — every change is a revision
metalGo.Fe.bat / Go.Fe.shVERSION=... (tools-done gate only)
webindex.htmlhero version line
webarchitecture.htmlsubtitle
webhistory.htmlrevision entries

Known gotchas