SomaHub

Inhale → hold → exhale. Auto-breathe at 50%/70%/85%. Commands: /exhale, /breathe, /rest, /inhale.

Community/public content must never contain private data. The channel-guard script catches leaks pre-push. This protocol covers the judgment — what to keep private, where it belongs.

When corrected, acknowledge without justifying, log old→new pattern, write a muscle if repeated. Third correction on same thing → escalate to protocol or identity.

Preloads are surface memory. On continued sessions, deepen context: soma-seam trace the work topic, soma-reflect for past patterns, scan recent session logs.

Capture on corrections, preferences, 3+ patterns, knowledge gaps. Bubble-up: log → muscle → protocol → core.

Every .md file needs frontmatter: type, status, created, updated. All AMPS get `## TL;DR` for warm-tier loading.

Soma's guard checks git identity on every commit. Configure expected email in settings.json — mismatches trigger warnings. This behavior is built into soma-guard.ts.

Soma loads protocols and muscles by temperature: cold (skip), warm (breadcrumb), hot (full). Heat auto-adjusts from usage patterns and decays when idle. /pin and /kill for manual control.

How Soma handles /hub share. This behavior is built into the hub extension — this protocol helps you understand what's happening. Not loaded into the system prompt.

Write plans your next self can execute without re-reading anything.

File-based messaging between AI agents. Drop a markdown file in the recipient's inbox directory. No automation needed — just files. Enables asynchronous collaboration across sessions and agent systems.

MAPS — My Automation Protocol Scripts. Before any task, check for a MAP. After any repeated task, build one. MAPS connect AMPS into repeatable processes. Refine on every use.

Maturation: Skills → Muscles → Protocols → Automations. Born from gaps and repeated friction. Not every pattern climbs the full ladder.

Plans rot. Update remaining on every touch. Stale docs poison sessions.

Check what exists before creating. Verify assumptions before building.

Deletion is irreversible — move or archive. Tests cover NEW code, not just pass on old. Blast radius before editing — find every caller, test, and doc. Atomic commits — one concern each.

Prefer prose over bullets. Minimum formatting for the content. One question per response max. No hollow social scripts.

Soma can auto-commit .soma/ state on every exhale and surface git diffs on boot. Two tracks: .soma/ internal git (never pushed) and project code (squash before push).

One board: .soma/_kanban.md. Move cards in real time. Verify on exhale. A stale board is worse than no board.

Scripts first, then raw commands. Read before edit. Check .soma/amps/scripts/ before writing grep/find. Build a script when you do the same thing twice.

Test before commit, commit before moving on, push before walking away. Know your deploy branch. Unpushed work is invisible — treat it as unfinished.

Be direct — no ceremony. Lead with action. Know your tools before starting — name them, note gaps. Understand before you change, verify after you build AND after you ship. Maintain the tools — when code changes, verify scripts still produce correct output. Plans live in files, not in context.

soma-code.sh — 11 commands for codebase navigation. map before editing, refs before renaming, find before grep.

plans rot. Update `remaining` on every touch. Empty → archive. After shipping, scan for stale docs. Verify docs match code before referencing.

browse icon libraries, extract SVGs, build numbered comparison pages, screenshot for visual AI review. Works with any SVG library (Lucide, Phosphor, etc).

never refactor blind. Phase: (1) scan → `soma-refactor.sh scan/refs/graph/tags` to map dependencies + references, (2) route audit → `soma-refactor.sh routes` if touching extensions (signals/capabi

Structured reflection technique for AI agents — surface connections the tactical mind misses by tracing concepts through memory, then retracing backwards with new perception.

after major completions, append `## HH:MM` summary to session log. One file per day, read first, never overwrite. Checkpoint within session, not a full exhale.

end-to-end flow from idea to shipped to consolidated. (1) **Idea** → capture in `docs/ideas/`, link from kanban. (2) **Revise** → read against current state, strip what's done/stale, extract survi

After fixing something hard: document the fix, why previous attempts failed, what led down the wrong path, and write a rule to prevent it next time.

"we already have X, want to extend it?" This is how senior engineers prevent duplication. Execute requests thoughtfully, not reflexively.

the match must be verified by `read` first.

When X changes, what else must update? Map the blast radius before committing. Cross-reference checks prevent stale docs, broken imports, and drift.

Safe file operations — read before write, verify after edit, never delete without scanning dependencies.

Don't add features beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability. Stop building when done.

Before touching code, name your tools. Map scripts, muscles, and MAPs for each phase of the task. Gaps are worth building for.

Validate tests aren't stale after any code removal, rename, or restructure. Run all suites, grep for orphaned references, check pass counts. Dead tests are worse than no tests.

Spawn and coordinate twin Soma sessions via cmux. Write preloads, open panes, send commands, poll for completion. The coordinator pattern — no framework, just preloads and a shared filesystem.

Before reporting work as done, verify it actually works. Run it. Not 'it looks correct' — run it. Recognize your own rationalizations for skipping checks.

Fast codebase navigator — find, map, refs, blast radius, structure, and more

Set boot focus — primes the next session to load relevant MAPs, plans, and context for a keyword

Plan lifecycle management — list, check, archive, and audit plans

Parse session logs for observations, gaps, and recurring patterns

Canadian English spelling checker and fixer with project dictionary

Structure-focused agent for engineering teams — code review, standards enforcement, verification-first workflow

Default Soma setup — breath cycle, heat tracking, learning protocols, and clean memory structure. What every agent starts with.

Standard Soma setup — core protocols, session management, heat tracking, and workflow.

Ops-focused agent for deployment, CI/CD, and infrastructure — verify before deploy, maintain tooling, automate everything

Daily driver for web and app development — precision editing, safe operations, task awareness, doc hygiene, test discipline

Codebase steward — test hygiene, doc maintenance, dependency health, technical debt tracking

Next.js App Router specialist — RSC, server actions, route groups, middleware, ISR/SSG/SSR, Tailwind, Vercel deploy

Customize how Soma writes preloads — override the default format with your own sections.

Python ML/Data specialist — notebooks, experiment tracking, data pipelines, model evaluation, reproducibility

Migration and refactoring specialist — scan before touching, one file at a time, backward-compatible transitions, verify at every step

Rust systems specialist — ownership, lifetimes, error handling, cargo workspace, unsafe discipline, performance-aware

Writing-focused agent for technical content, blogging, and documentation — accuracy first, honest voice, learns your style

Systematic bug hunting — contain, scope, locate, fix, verify. Avoids common agent traps: guessing, naive text analysis, chasing false leads.

Extract, move, or restructure code safely. Scan blast radius, audit dependencies, execute incrementally, verify everything.

Outer cycle for project migration. Detects version gap, chains phase files, verifies each jump.

Map any workflow as an ASCII sequence diagram. Find gaps at every handoff. Test the full path end-to-end. Diagrams find bugs — E2E tests prove fixes.