Muscles

Learned patterns in .soma/amps/muscles/ as markdown with frontmatter (type, status, topic, keywords, heat, loads). Loaded by heat within token budget (default: 2000). Hot (≥5) = full body, warm (≥1) = TL;DR only, cold = name listed. Add a ## TL;DR section — it’s what loads 90% of the time. /pin to keep hot, /kill to drop cold.

Muscles are learned patterns — reusable knowledge that Soma builds from experience. Unlike protocols (which are behavioral rules you write), muscles emerge organically from work. They’re Soma’s playbook.

How Muscles Form

Muscles start as observations. When Soma notices a pattern across sessions — a deployment process, a code style, an API workflow — it writes it down as a muscle file in .soma/amps/muscles/.

A muscle is a markdown file with frontmatter:

---
type: muscle
status: active
topic: [deployment, vercel, astro]
keywords: [deploy, build, preview, production]
created: 2026-03-09
updated: 2026-03-09
heat: 3
loads: 0
---

# Deployment — Muscle

> Learned patterns for deploying Astro sites to Vercel.

## TL;DR

Build with `pnpm build`, deploy with `npx vercel --prod`.
Always verify with curl after deploy. Check build output for page count changes.

## Full Process

1. Run `pnpm build` and check for errors
2. Verify page count matches expectations
3. Deploy with `npx vercel --prod`
4. Confirm alias URL responds with 200
5. Commit and push

Frontmatter Fields

Field	Type	Description
`type`	`"muscle"`	Always `muscle`
`status`	`active \| dormant \| retired`	Controls discovery. Only `active` muscles load.
`tags`	`string[]`	Searchable tags (used by focus matching)
`topic`	`string[]`	What this muscle covers (broad categories)
`keywords`	`string[]`	Finer search terms for lookup and focus matching
`triggers`	`string[] \| object[]`	Focus triggers — keywords that auto-activate this muscle (see Focus)
`tools`	`string[]`	Scripts this muscle relates to
`heat`	`number`	Current heat level — determines loading tier
`loads`	`number`	How many times loaded at boot (tracked automatically)
`created`	`date`	When the muscle first formed
`updated`	`date`	Last modification

The Digest System

Muscles can be large — a full logo design muscle might be 200+ lines. Loading all of that into the system prompt wastes context. The TL;DR system solves this with a two-tier approach.

Every muscle should have a ## TL;DR section:

## TL;DR

Concise summary of the key patterns — what the agent needs at a glance.
When to apply. What to watch for. 2-6 lines max.

When a muscle loads as warm (digest tier), only the ## TL;DR content enters the prompt. When it loads as hot, the full body loads.

No TL;DR? The muscle can only load as hot (full) or cold (not at all). Write TL;DRs — they’re what loads 90% of the time.

Note: The ## TL;DR format is shared across all AMPS (protocols, muscles, automations). Older muscles may use  markers — both formats work, but ## TL;DR is preferred. soma doctor auto-converts on boot.

Heat & Loading Tiers

Like protocols, muscles use the heat system to decide what loads:

Tier	Heat	What Loads	When
🔥 Hot	≥ `fullThreshold` (default: 5)	Full body	Heavily used, recent
🟡 Warm	≥ `digestThreshold` (default: 1)	TL;DR section only	Occasionally used
❄️ Cold	0	Name listed, nothing loaded	Unused, decayed

Loading respects a token budget (default: 2000 estimated tokens). Hot muscles load first (up to maxFull, default: 2), then warm muscles fill remaining budget (up to maxDigest, default: 8). Cold muscles are listed by name so the agent knows they exist.

All thresholds are configurable in settings.json.

Writing a Muscle

With `soma new` (recommended)

Scaffolds the file from a template with frontmatter pre-filled:

soma new muscle my-workflow
soma new muscle my-workflow -d "Run tests before every commit."
soma new muscle my-workflow -t testing,ci,commit-hook
soma new muscle my-workflow --global         # write to ~/.soma/ instead of project
soma new muscle my-workflow --no-edit        # skip opening $EDITOR

Idempotent — re-running on an existing name opens it in $EDITOR rather than clobbering. Use --force to overwrite.

The template at templates/default/_muscle-template.md is the single source of truth for frontmatter shape. If you want to change conventions for new muscles project-wide, edit that template rather than each muscle file.

Writing manually (lower friction, more ceremony)

You can still write the file by hand if you prefer:

touch .soma/amps/muscles/my-workflow.md

---
type: muscle
status: active
topic: [testing, ci]
keywords: [jest, vitest, test-runner]
heat: 3
loads: 0
---

# Testing Workflow — Muscle

## TL;DR

Run `pnpm test` before every commit. Use vitest for unit tests.
Coverage threshold is 80%. CI runs the same suite.

## Full Process

...your detailed patterns here...

Set heat: 3 or higher so it loads on next boot. Heat will decay naturally if the muscle isn’t used.

Where Muscles Live

.soma/amps/muscles/
├── svg-logo-design.md      ← learned from logo sessions
├── deployment.md           ← learned from deploy workflows
├── github-app-auth.md      ← learned from auth patterns
└── social-preview-gen.md   ← learned from OG image work

By default, muscles inherit from parent .soma/ directories when inherit.muscles is true (the default). Parent muscles are discovered alongside project muscles and compete for the same token budget based on heat. To disable, set inherit.muscles: false in settings.json.

Heat Commands

Command	Effect
`/pin my-muscle`	Bumps heat by `pinBump` (default: +5). Keeps it loaded.
`/kill my-muscle`	Drops heat to 0. Won’t load until used again.

Tips

Keep muscles focused. One muscle per domain. Don’t mix deployment and testing.
Write TL;DRs first. The TL;DR is what loads 90% of the time. Make it good.
Let heat do the work. Don’t manually set heat to 15 on everything. Let usage patterns decide what matters.
Retire, don’t delete. Set status: retired instead of removing. The knowledge stays searchable.
Update, don’t duplicate. When patterns evolve, update the existing muscle. Don’t create deployment-v2.md.