Download and copy to .soma/protocols/pattern-evolution.md — or view on GitHub ↗
Tags
Applies to
always
Details
Pattern Evolution Protocol
TL;DR
Maturation: Skills → Muscles → Protocols → Automations. Born from gaps and repeated friction. Not every pattern climbs the full ladder.
The Maturation Layers
observation (noticed gap, repeated action)
↓ write it down as reusable knowledge
skill (plug-and-play expertise — works across frameworks)
↓ applied repeatedly, patterns emerge
muscle (learned pattern — refines through use, tracked by heat)
↓ becomes mandatory, skipping causes failures
protocol (behavioral rule — universal, ships to all users)
↓ becomes executable, runs without thinking
automation (executable workflow — hooks, rituals, enforcement)
Layer
When
Nature
Skill
Domain knowledge — teaches, doesn't enforce. Works across any agent.
On-demand.
Muscle
Repeated pattern — refines through use, builds heat.
Learned.
Protocol
Pattern becomes a behavioral rule. Skipping it causes mistakes.
Mandatory.
Automation
Protocol becomes executable — enforces without thinking.
Automatic.
Automations are the final crystallization. The protocol explains why; the automation enforces how. An agent with the automation but without the protocol can't reason about edge cases.
Promotion is by ENFORCEABILITY, and it moves a PART — not the whole thing
A muscle cannot enforce itself. It is a reflex: it fires if you happen to recall it, and a
reflex you did not recall is indistinguishable from a reflex you do not have. So the trigger for
muscle → protocol is not "it feels important now." It is:
🔑 *Does this muscle contain a gotcha that keeps costing you precisely because* nothing can
catch it at the moment it's violated?** That part — and only that part — belongs in a protocol,
as a gates: entry.
What moves, what stays:
stays in the muscle
moves to the protocol
the reflex — when to reach for this at all
the rule that must fire at the violation
judgement, tradeoffs, worked reasoning
a mechanical trigger: paths: / command: / after:
the pointer to the full procedure
the one-line correction the violator needs right then
The muscle shrinks to a trigger; the protocol gains a gate. Neither duplicates the other,
and the procedure keeps one home (usually a skill). *That split is the crystallization — the muscle
becomes muscle memory precisely by giving up the part it could never enforce.*
Why this rung only recently became real
The table above calls Protocol "Mandatory" and puts enforcement at Automation. Until protocols
could declare gates:, that was accurate but hollow: a protocol was the same injected text as a
muscle wearing a stronger word, and text cannot stop you. Anything genuinely enforceable had to
become a full automation — an expensive jump most patterns never justified.
gates: moved enforcement down one rung. A protocol can now fire at the violation without
becoming an automation, which makes muscle → protocol a real promotion instead of a relabelling.
→ releases/cycles/protocol-gates/cycle.md
The gate on the gate — promotion is not free
Do not promote a gotcha that has no mechanical trigger. "Plausibly detectable" is not detectable;
if you cannot name the paths:/command:/after: expression, the honest outcome is **it stays
resident text**, and saying so beats forcing a bad matcher.
⚠ Three costs, all measured 2026-08-07:
A gate is a narrowing of the rule, and the boundary is where the next incident lives. A
command: gate on \b(timeout|...)\b matched the word, blocking grep 'timeout' and
curl --timeout — 5 false positives in 14 cases.
A gate's premise rots, and nobody re-reads a rule they agree with. Two gates enforced a cache
claim that had been false for months — contradicting the TL;DR of the very file they lived in.
Escalation on a gate that cannot observe compliance is unsound. A paths: gate counts
traffic, not violations; escalating on that count demanded a behaviour change from an agent that
was already complying.
⇒ A promoted gate inherits a falsifiability duty: state what would make it fire wrongly, and
re-verify its premise on a live path — not from the session that wrote it (getProtocolGates()
caches at boot).
Known blocker — the trigger kind that would unlock the next class
Today's triggers see location and literal text, never edit shape. So a whole class of
otherwise-ready gotchas cannot be promoted — e.g. *"don't change a role's default-model without
reading the calibration ledger"* (amps/muscles/model-role-calibration.md) is mechanical in spirit
but needs a content-diff trigger to fire on that field rather than on every edit under
body/children/. Same missing primitive blocks append-vs-correct detection
(protocol-gates/cycle.md #11). One trigger kind, two blocked classes — which is the argument
for building it.
Identity: The Override Layer
Identity sits outside the maturation ladder. It doesn't replace protocols — it sharpens them for a specific project.
protocol: "Verify after you build" ← universal rule
identity: "Verify using ./verify-paths.sh" ← project-specific application
Protocols should work without identity. A user who never writes an identity file should still get useful behavior from protocols alone. If a protocol requires project-specific knowledge to be useful, it's too narrow.
Identity overrides, never conflicts. Identity can make protocols more specific ("always use X tool for verification") but shouldn't contradict them. If identity says "skip verification" and a protocol says "always verify," that's a design problem in the protocol (too rigid) or the identity (too reckless).
The reverse check: During mid-session reflections, scan identity for lines that aren't project-specific. If a principle would help any Soma user, extract it into a protocol. Identity accumulates fast — protocols should accumulate the universal parts.
identity insight: "After structural changes, verify scripts still produce correct output"
↓ is this project-specific? No — it's universal.
↓ extract to protocol (quality-standards or tool-discipline)
↓ identity keeps the project-specific version: "run ./verify-paths.sh after path changes"
How Muscles Are Born
Muscles come from gaps — not from planning sessions.
Source
Example
Agent notices own friction
"I keep checking test counts manually"
Agent notices user friction
"User keeps asking me to open URLs"
Post-incident
"We deleted working automations with no cleanup protocol"
Cross-session repetition
"Third session in a row doing this sequence"
Failed assumption
"API works differently than I assumed"
Key insight: The user's repeated behaviors are the richest source. When you notice a pattern — how they like PRs structured, a testing sequence they always follow — that's a muscle waiting to be written.
Burst Heat (aspirational — not yet implemented)
Standard: +1 applied in action, +2 explicitly referenced.
Burst modifier: 3+ uses in one session → +3 bonus heat. Intense repetition in a short window builds muscle memory faster than occasional use over months.
Implementation status: Heat auto-detection exists but is limited to specific tool result patterns. Burst counting and the +2 "explicit reference" detection are not yet coded. See heat-tracking protocol for what's actually automated.
Evolution Triggers
From → To
Signal
Skill → Muscle
You keep applying this knowledge — it's becoming a pattern.
Muscle → Protocol
Skipping it causes failures. It's not optional. AND it's universal — not project-specific.
Protocol → Automation
The rule is clear enough to enforce without thinking.
Identity → Protocol
The insight isn't project-specific. Extract the universal part.
Muscle stays muscle
Useful pattern but doesn't rise to rule/workflow.
When to Check for Evolution
Mid-session reflections are the best time. You've been doing real work, you have context, and the patterns are fresh. During session log writing:
Check observations — do any of these recur from previous sessions? If so → muscle.
Check muscles — are you following any muscle so consistently that skipping it would be a mistake? If so → protocol candidate.
Check identity — did you add anything this session? Is any of it universal? If so → extract to protocol.
Check gaps — did you hit an issue that a tool should have caught? If so → update the tool AND the muscle/protocol that references it.
The session log's Observations section is the raw material. The reflection is where you ask: should this stay an observation, or has it earned promotion?
Parallel Maturation Gradients
Content isn't the only thing that matures. Three parallel gradients follow the same pattern:
Gradient
Stages
What Matures
Content
Skill → Muscle → Protocol → Automation
Knowledge
Product
Internal → Power-user → Feature → Core
Features
Trust
Cold → Warm → Hot
Confidence
All three follow the same principle: start small, prove useful, increase visibility, become default. Heat IS the maturation gradient — it just operates on content. Product maturation (should we ship this feature?) should follow the same pattern: build it internal, let usage decide, ship when hot.
Naming drives maturation. Calling something a "muscle" makes you treat it as something that strengthens with use. Calling it a "rule" makes you treat it as something to comply with. The name prescribes behavior. When naming AMPS content, choose names that imply the right relationship: develop (muscles), follow (protocols), trigger (automations), use (scripts).
What Doesn't Evolve
One-off solutions (specific bug fix, not a pattern)
Context-dependent decisions ("we chose React for this project")
Preferences that change weekly (not a pattern yet)
Low-heat muscles after 10 unused sessions (consider retiring, not deleting)
When to Apply
Always. This protocol governs how the agent's knowledge base grows.
When NOT to Apply
Don't force evolution. If a pattern hasn't naturally emerged, don't manufacture it. The hierarchy is descriptive (what happens) not prescriptive (what must happen on schedule).
Muscles are born from gaps — moments where you notice missing patterns, repeated friction, workflow holes
Burst heat: 3+ uses in one session → +3 bonus heat (intense repetition accelerates learning)
Not every pattern climbs the full ladder. Some stay muscles forever. That's fine.
The AMPS Layers
observation (noticed gap, repeated action)
↓ write it down as reusable knowledge
skill (plug-and-play expertise — works across frameworks)
↓ applied repeatedly, patterns emerge
muscle (learned pattern — refines through use, tracked by heat)
↓ becomes mandatory, skipping causes failures
protocol (behavioral rule — crystallized, enforced)
↓ becomes executable, runs without thinking
automation (executable workflow — hooks, rituals, enforcement)
Layer
When
Nature
Skill
Domain knowledge — teaches, doesn't enforce. Works across any agent.
On-demand.
Muscle
Repeated pattern — refines through use, builds heat.
Learned.
Protocol
Pattern becomes a behavioral rule. Skipping it causes mistakes.
Mandatory.
Automation
Protocol becomes executable — enforces without thinking.
Automatic.
Automations are the final crystallization. The protocol explains why; the automation enforces how. An agent with the automation but without the protocol can't reason about edge cases.
How Muscles Are Born
Muscles come from gaps — not from planning sessions.
Source
Example
Agent notices own friction
"I keep checking test counts manually"
Agent notices user friction
"User keeps asking me to open URLs"
Post-incident
"We deleted working automations with no cleanup protocol"
Cross-session repetition
"Third session in a row doing this sequence"
Failed assumption
"API works differently than I assumed"
Key insight: The user's repeated behaviors are the richest source. When you notice a pattern — how they like PRs structured, a testing sequence they always follow — that's a muscle waiting to be written.
Burst Heat (aspirational — not yet implemented)
Standard: +1 applied in action, +2 explicitly referenced.
Burst modifier: 3+ uses in one session → +3 bonus heat. Intense repetition in a short window builds muscle memory faster than occasional use over months.
Implementation status: Heat auto-detection exists but is limited to specific tool result patterns. Burst counting and the +2 "explicit reference" detection are not yet coded. See heat-tracking protocol for what's actually automated.
Evolution Triggers
From → To
Signal
Skill → Muscle
You keep applying this knowledge — it's becoming a pattern.
Muscle → Protocol
Skipping it causes failures. It's not optional.
Protocol → Automation
The rule is clear enough to enforce without thinking.
Muscle stays muscle
Useful pattern but doesn't rise to rule/workflow.
What Doesn't Evolve
One-off solutions (specific bug fix, not a pattern)
Context-dependent decisions ("we chose React for this project")
Preferences that change weekly (not a pattern yet)
Low-heat muscles after 10 unused sessions (consider retiring, not deleting)
When to Apply
Always. This protocol governs how the agent's knowledge base grows.
When NOT to Apply
Don't force evolution. If a pattern hasn't naturally emerged, don't manufacture it. The hierarchy is descriptive (what happens) not prescriptive (what must happen on schedule).
Muscles are born from gaps — moments where you notice missing patterns, repeated friction, workflow holes
Burst heat: 3+ uses in one session → +3 bonus heat (intense repetition accelerates learning)
Not every pattern climbs the full ladder. Some stay muscles forever. That's fine.
The AMPS Layers
observation (noticed gap, repeated action)
↓ write it down as reusable knowledge
skill (plug-and-play expertise — works across frameworks)
↓ applied repeatedly, patterns emerge
muscle (learned pattern — refines through use, tracked by heat)
↓ becomes mandatory, skipping causes failures
protocol (behavioral rule — crystallized, enforced)
↓ becomes executable, runs without thinking
automation (executable workflow — hooks, rituals, enforcement)
Layer
When
Nature
Skill
Domain knowledge — teaches, doesn't enforce. Works across any agent.
On-demand.
Muscle
Repeated pattern — refines through use, builds heat.
Learned.
Protocol
Pattern becomes a behavioral rule. Skipping it causes mistakes.
Mandatory.
Automation
Protocol becomes executable — enforces without thinking.
Automatic.
Automations are the final crystallization. The protocol explains why; the automation enforces how. An agent with the automation but without the protocol can't reason about edge cases.
How Muscles Are Born
Muscles come from gaps — not from planning sessions.
Source
Example
Agent notices own friction
"I keep checking test counts manually"
Agent notices user friction
"User keeps asking me to open URLs"
Post-incident
"We deleted working automations with no cleanup protocol"
Cross-session repetition
"Third session in a row doing this sequence"
Failed assumption
"API works differently than I assumed"
Key insight: The user's repeated behaviors are the richest source. When you notice a pattern — how they like PRs structured, a testing sequence they always follow — that's a muscle waiting to be written.
Burst Heat (aspirational — not yet implemented)
Standard: +1 applied in action, +2 explicitly referenced.
Burst modifier: 3+ uses in one session → +3 bonus heat. Intense repetition in a short window builds muscle memory faster than occasional use over months.
Implementation status: Heat auto-detection exists but is limited to specific tool result patterns. Burst counting and the +2 "explicit reference" detection are not yet coded. See heat-tracking protocol for what's actually automated.
Evolution Triggers
From → To
Signal
Skill → Muscle
You keep applying this knowledge — it's becoming a pattern.
Muscle → Protocol
Skipping it causes failures. It's not optional.
Protocol → Automation
The rule is clear enough to enforce without thinking.
Muscle stays muscle
Useful pattern but doesn't rise to rule/workflow.
What Doesn't Evolve
One-off solutions (specific bug fix, not a pattern)
Context-dependent decisions ("we chose React for this project")
Preferences that change weekly (not a pattern yet)
Low-heat muscles after 10 unused sessions (consider retiring, not deleting)
When to Apply
Always. This protocol governs how the agent's knowledge base grows.
When NOT to Apply
Don't force evolution. If a pattern hasn't naturally emerged, don't manufacture it. The hierarchy is descriptive (what happens) not prescriptive (what must happen on schedule).
Muscles are born from gaps — moments where you notice missing patterns, repeated friction, workflow holes
Burst heat: 3+ uses in one session → +3 bonus heat (intense repetition accelerates learning)
Not every pattern climbs the full ladder. Some stay muscles forever. That's fine.
The Hierarchy
observation (noticed gap, repeated action)
↓ seen 2+ times → write it down
muscle (learned pattern, markdown file)
↓ loaded repeatedly, applied automatically
muscle memory (subconscious — agent applies without thinking)
↓ crystallizes based on nature
protocol | skill | ritual | script
Destination
When
Nature
Protocol
Pattern becomes a behavioral rule. Skipping it causes mistakes.
Mandatory.
Skill
Pattern is domain knowledge. Teaches, doesn't enforce.
On-demand.
Ritual
Pattern is a multi-step workflow. Sequences actions.
Triggered.
Script
Pattern is automated — protocol becomes executable enforcement.
Automatic.
Scripts are the final crystallization. The protocol explains why; the script enforces how. An agent with the script but without the protocol can't reason about edge cases.
How Muscles Are Born
Muscles come from gaps — not from planning sessions.
Source
Example
Agent notices own friction
"I keep checking test counts manually"
Agent notices user friction
"User keeps asking me to open URLs"
Post-incident
"We deleted working scripts with no cleanup protocol"
Cross-session repetition
"Third session in a row doing this sequence"
Failed assumption
"API works differently than I assumed"
Key insight: The user's repeated behaviors are the richest source. When you notice a pattern — how they like PRs structured, a testing sequence they always follow — that's a muscle waiting to be written.
Burst Heat (aspirational — not yet implemented)
Standard: +1 applied in action, +2 explicitly referenced.
Burst modifier: 3+ uses in one session → +3 bonus heat. Intense repetition in a short window builds muscle memory faster than occasional use over months.
Implementation status: Heat auto-detection exists but is limited to specific tool result patterns. Burst counting and the +2 "explicit reference" detection are not yet coded. See heat-tracking protocol for what's actually automated.
Evolution Triggers
From → To
Signal
Muscle → Protocol
Skipping it causes failures. It's not optional.
Muscle → Skill
It's domain knowledge, loads on demand, not a rule.
Muscle → Ritual
It's a repeatable multi-step workflow triggered by command.
Muscle stays muscle
Useful pattern but doesn't rise to rule/expertise/workflow.
What Doesn't Evolve
One-off solutions (specific bug fix, not a pattern)
Context-dependent decisions ("we chose React for this project")
Preferences that change weekly (not a pattern yet)
Low-heat muscles after 10 unused sessions (consider retiring, not deleting)
When to Apply
Always. This protocol governs how the agent's knowledge base grows.
When NOT to Apply
Don't force evolution. If a pattern hasn't naturally emerged, don't manufacture it. The hierarchy is descriptive (what happens) not prescriptive (what must happen on schedule).
Scripts are the final crystallization — what was once a behavioral rule the agent followed manually becomes code that runs automatically. But the protocol doesn't disappear when a script exists. The protocol explains why. The script enforces how. An agent with the script but without the protocol can run the automation but can't reason about edge cases, adapt to new situations, or know when to break the rule.
Skills: The Universal Building Block
Skills are unique in the hierarchy — they're framework-agnostic knowledge sets. A skill from Claude Code, Cursor, or any agent framework works in Soma without modification. Skills are plug-and-play.
What makes Soma different: muscles and protocols refine skills. A logo design skill teaches the technique. A muscle learns your logo preferences. A protocol enforces your brand standards. The skill provides raw expertise; Soma's layers personalize and improve it through use — without the user ever asking.
This is the key differentiator: other systems have skills. Soma has skills that get better every time they're used, because muscles notice what worked and protocols enforce what matters.
The muscle doesn't choose its destination consciously. It becomes whatever it naturally is. A testing pattern that you must always follow → protocol. A logo design technique you sometimes need → skill. A publish workflow you repeat every release → ritual.
How Muscles Are Born
Muscles come from gaps — not from planning sessions. They emerge from work.
Gap Sources
Source
Example
Agent notices own friction
"I keep checking test counts manually — this should be a pattern"
Agent notices user friction
"The user keeps asking me to open URLs instead of just linking them"
Post-incident
"We deleted working scripts because we had no cleanup protocol"
Cross-session repetition
"Third session in a row I've done this exact sequence"
Failed assumption
"I assumed the API worked one way — writing down the actual behavior"
The key insight: the user's repeated behaviors are the richest source of muscles. When you notice the user has a pattern — a way they like PRs structured, a testing sequence they always follow, a communication style they prefer — that's a muscle waiting to be written.
Burst Heat
Standard heat events:
+1 when applied in action
+2 when explicitly referenced
Burst modifier: If a pattern is applied 3+ times within a single session, add +3 bonus heat. This reflects the biological reality — intense repetition in a short window builds muscle memory faster than occasional use over months.
This means a pattern discovered and used heavily in one session can be warm by session's end. That's correct behavior — if something matters enough to use 3+ times in one session, it matters.
The Muscle Memory Threshold
A muscle becomes "muscle memory" when:
Heat ≥ hot threshold (loaded automatically, every session)
The agent applies it without being asked
The digest alone is sufficient — the full body is reference material
The user stops needing to remind the agent about this pattern
At this point, the muscle is subconscious. The agent just does it. The written muscle is insurance — proof that the pattern exists, documentation for future sessions after heat decay, and a teaching tool for other agents.
Evolution Triggers
Muscle → Protocol
Signal: Skipping the pattern causes failures. It's not optional anymore.
Action: Write a protocol with ## TL;DR, ## When to Apply, ## When NOT to Apply.
Example: "test-hygiene" started as a muscle. After the scripts-we-deleted incident, it became mandatory. Protocol candidate.
Muscle → Skill
Signal: The pattern is domain knowledge that loads on demand, not a behavioral rule.
Action: Write a SKILL.md with instructions, examples, decision frameworks.
Example: "svg-logo-design" is knowledge about how to design logos. It's not a rule — it's expertise.
Muscle → Ritual
Signal: The pattern is a repeatable multi-step workflow triggered by a command.
Action: Write a ritual with steps, checkpoints, and error handling.
Example: "publish flow" — plan → draft → review → commit → push → deploy. Always the same sequence.
Muscle stays muscle
Signal: It's a useful pattern but doesn't rise to rule/expertise/workflow.
Example: "pr-release-workflow" — helpful patterns for PRs, but every PR is different enough that rigid rules would hurt.
User Adaptation
The most important muscles are the ones that emerge from observing the user's patterns:
Notice — the user does something repeatedly, or expresses a preference
Confirm — verify the pattern is intentional, not accidental
Encode — write a muscle capturing the pattern
Apply — use the muscle in future interactions
Evolve — refine as the user's pattern evolves
This isn't just "following orders." It's learning the user's workflow, filling their gaps, and adapting the agent's behavior to maximize collaboration quality.
Examples of User Adaptation Muscles
User always wants URLs opened, not linked → muscle: "open browser for URLs"
User prefers short confirmations over detailed explanations → muscle: "concise responses"
User always reviews blog posts for accuracy before publish → muscle: "pre-publish verification"
User structures PRs with specific sections → muscle: "PR template"
What Doesn't Evolve
One-off solutions — a fix for a specific bug isn't a pattern
Context-dependent decisions — "we chose React for this project" isn't a muscle
Preferences that change — if the user changes their mind weekly, it's not a pattern yet
Low-heat muscles — if it hasn't been used in 10 sessions, consider retiring (not deleting)
The Perfectionist's Check
Before modifying any muscle, protocol, or ritual:
Read the full file — not just the section you're changing
Trace references — grep -rn "muscle-name" to find everything that depends on it
Understand the ripple — changing heat thresholds affects which muscles load at boot
Test the change — if the muscle has associated tests, run them
Verify recency — is this file current? Check updated: field. Don't build on stale foundations.
The goal isn't caution. It's confidence. Change quickly, but change with full understanding of what you're touching.
When to Apply
Always. This protocol governs how the agent's knowledge base grows. It's the meta-protocol for self-improvement.
When NOT to Apply
Don't force evolution. If a pattern hasn't naturally emerged, don't manufacture it. The hierarchy is descriptive (what happens naturally) not prescriptive (what must happen on a schedule).