Tool Discipline

How Soma uses tools safely and efficiently. Scripts are your extended memory — they don't forget, they don't hallucinate, and they return structured output you can act on immediately.

TL;DR

Scripts first, raw commands second. Read before edit. Build tools for yourself — when you do the same thing twice manually, make a script. Guard auto-blocks dangerous bash. The agent that builds its own tools gets faster every session.

Script-First Workflow

Your scripts live in .soma/amps/scripts/. They're surfaced at boot and tracked by usage.

Before writing a raw command, check:

1. Is there a script that does this? (ls .soma/amps/scripts/)
2. Does it have --help? (Run it to see what it does)
3. Can an existing script be extended instead of writing a new one?

When to build a new script:

• You've done the same manual command pattern 2+ times
• The task has multiple steps that should be atomic
• You want future sessions to have this capability

Script standards:

• Add --help with usage examples
• Add header comments explaining purpose
• Leave breadcrumbs in comments: "Related: <muscle-name>, <other-script>"
• Use .soma/ discovery (walk up from cwd) so scripts work in any project

What the Guard Handles (Automatic)

The soma-guard.ts extension intercepts bash commands and flags dangerous patterns:

• rm -rf on sensitive paths
• > redirect to root/system paths (but >> append is allowed)
• Force pushes, rebase on shared branches
• Credential/secret exposure

Guard levels (configurable):

{
  "guard": {
    "bashCommands": "warn",
    "coreFiles": "warn"
  }
}

Level	Behavior
allow	No prompts. Power user mode.
warn	Flags dangerous commands, asks for confirmation.
block	Requires explicit override for each dangerous command.

Craft Practices

• Read before edit — always check file contents before modifying
• Edit for surgical changes — edit replaces exact text, safer than write
• Write for new files only — write overwrites everything; use edit for existing files
• Batch independent calls — if two reads don't depend on each other, do them in one turn
• Verify claims against code — don't say "this is broken" without checking. Run it. Read the output.
• Blast radius with multiple tools — one tool isn't enough. Before changing a function or type:

1. soma:code.blast — the one call that answers "what breaks if I change this"
2. soma:code.refs — every reference site, ranked
3. soma:code.find scoped to tests/ — test coverage (if nothing, you need to add tests)
4. Check scripts and docs that might reference it

A single search misses things. Use 3-4 across different scopes to catch the full blast radius.

Shipped Tools

Install from the community hub to extend your toolkit:

Task	Script	Install
Navigate codebase (find, map, refs, structure)	soma-code	/hub install script soma-code
Doc discovery + SDK research	soma:refdocs.*	built in — refdocs.find / .fetch / .tree
Spelling + grammar checking	soma-spell	/hub install script soma-spell

Browse all available scripts: /hub list --remote script

Run any script with --help for full usage. Build your own — drop a .sh into .soma/amps/scripts/ and it's available next session. Drop it into .soma/amps/scripts/commands/ and it becomes a /soma <name> command.

Source

• Guard extension: extensions/soma-guard.ts
• Settings: core/settings.ts → GuardSettings
• Scripts directory: .soma/amps/scripts/

---

Tool Discipline

How Soma uses tools safely and efficiently. Scripts are your extended memory — they don't forget, they don't hallucinate, and they return structured output you can act on immediately.

TL;DR

Scripts first, raw commands second. Read before edit. Build tools for yourself — when you do the same thing twice manually, make a script. Guard auto-blocks dangerous bash. The agent that builds its own tools gets faster every session.

Script-First Workflow

Your scripts live in .soma/amps/scripts/. They're surfaced at boot and tracked by usage.

Before writing a raw command, check:

1. Is there a script that does this? (ls .soma/amps/scripts/)
2. Does it have --help? (Run it to see what it does)
3. Can an existing script be extended instead of writing a new one?

When to build a new script:

• You've done the same manual command pattern 2+ times
• The task has multiple steps that should be atomic
• You want future sessions to have this capability

Script standards:

• Add --help with usage examples
• Add header comments explaining purpose
• Leave breadcrumbs in comments: "Related: <muscle-name>, <other-script>"
• Use .soma/ discovery (walk up from cwd) so scripts work in any project

What the Guard Handles (Automatic)

The soma-guard.ts extension intercepts bash commands and flags dangerous patterns:

• rm -rf on sensitive paths
• > redirect to root/system paths (but >> append is allowed)
• Force pushes, rebase on shared branches
• Credential/secret exposure

Guard levels (configurable):

{
  "guard": {
    "bashCommands": "warn",
    "coreFiles": "warn"
  }
}

Level	Behavior
allow	No prompts. Power user mode.
warn	Flags dangerous commands, asks for confirmation.
block	Requires explicit override for each dangerous command.

Craft Practices

• Read before edit — always check file contents before modifying
• Edit for surgical changes — edit replaces exact text, safer than write
• Write for new files only — write overwrites everything; use edit for existing files
• Batch independent calls — if two reads don't depend on each other, do them in one turn
• Verify claims against code — don't say "this is broken" without checking. Run it. Read the output.
• Blast radius with multiple tools — one tool isn't enough. Before changing a function or type:

1. grep -rn "name" src/ — find code references
2. grep -rn "name" tests/ — find test coverage (if nothing, you need to add tests)
3. grep -rn "name" docs/ — find doc references to update
4. Check scripts that might reference it

A single grep misses things. Use 3-4 searches across different directories to catch the full blast radius.

Shipped Tools

Install from the community hub to extend your toolkit:

Task	Script	Install
Navigate codebase (find, map, refs, structure)	soma-code	/hub install script soma-code
Doc discovery + SDK research	soma:refdocs.*	built in — refdocs.find / .fetch / .tree
Spelling + grammar checking	soma-spell	/hub install script soma-spell

Browse all available scripts: /hub list --remote script

Run any script with --help for full usage. Build your own — drop a .sh into .soma/amps/scripts/ and it's available next session. Drop it into .soma/amps/scripts/commands/ and it becomes a /soma <name> command.

Source

• Guard extension: extensions/soma-guard.ts
• Settings: core/settings.ts → GuardSettings
• Scripts directory: .soma/amps/scripts/

---

Tool Discipline

How Soma uses tools safely. The guard extension enforces some of these mechanically — this protocol covers both the automated safety net and the craft practices.

TL;DR

Guard auto-blocks dangerous bash. Three levels: allow, warn, block. Read before edit, edit for surgical changes, write for new files only.

What the Guard Handles (Automatic)

The soma-guard.ts extension intercepts bash commands and flags dangerous patterns:

• rm -rf on sensitive paths
• > redirect to root/system paths (but >> append is allowed)
• Force pushes, rebase on shared branches
• Credential/secret exposure

Guard levels (configurable):

{
  "guard": {
    "bashCommands": "warn",
    "coreFiles": "warn"
  }
}

Level	Behavior
allow	No prompts. Power user mode.
warn	Flags dangerous commands, asks for confirmation.
block	Requires explicit override for each dangerous command.

Craft Practices (Not Automated)

These aren't enforced by code — they produce better results:

• Read before edit — always check file contents before modifying
• grep/find/ls for exploration — cheaper than reading whole files
• Edit for surgical changes — edit replaces exact text, safer than write
• Write for new files only — write overwrites everything
• Batch independent calls — if two reads don't depend on each other, do them in one turn

Source

• Guard extension: extensions/soma-guard.ts
• Settings: core/settings.ts → GuardSettings

---

Tool Discipline

How to use tools effectively. These rules adapt based on which tools are available — if a tool isn't loaded, its rules don't apply.

TL;DR

Read before edit (never cat/sed). Prefer dedicated tools over bash for exploration. Edit for surgical changes, write for new files only. Batch independent calls. Output plain text — don't use tools to display summaries.

When to Apply

Any session involving file operations — reading, writing, editing, searching. Adapts to available toolset.

File Reading

• Read before you edit. Always. Never modify a file you haven't read this session.
• Use the read tool, not cat or sed or head via bash. The read tool tracks what you've seen. Bash doesn't.
• Earn context. Don't read everything preemptively. Read on demand, when the task requires it.

File Exploration

• Prefer grep/find/ls tools over bash for file discovery and search. They're faster and respect .gitignore automatically.
• Use grep for content search, find for file location, ls for directory structure. Don't bash find or bash grep when dedicated tools exist.

Editing

• Use edit for surgical changes. The old text must match exactly — this is precision, not convenience.
• Use write only for new files or complete rewrites. If the file exists and you're changing part of it, use edit.
• Batch independent operations. If multiple reads or edits don't depend on each other, make them in the same call.

Output

• Output plain text directly when summarizing your work. Don't use cat, bash echo, or other tools to display what you did.
• Show file paths clearly. When referencing files, use the full path. Be specific about what changed and where.