Triggers and Activation

How abilities activate in a Bonsai workspace — the complete reference for sensors, path rules, slash commands, navigation tables, and prompt-based activation.

How Triggers Work

Bonsai abilities (skills, workflows, protocols, sensors) don’t just sit in files waiting to be read manually. They activate through a layered system that ranges from fully automatic enforcement to prompt-based invocation. The goal: the right ability loads at the right time, without the user needing to remember file paths or instruction sets.

Each layer operates independently. A single ability can be activated through multiple layers simultaneously — a skill might auto-load when you open a matching file (Layer 2), appear in a navigation table with scenario descriptions (Layer 4), and contain embedded trigger hints in its own file (Layer 5).

The 5-Layer Activation Stack

  Layer 1 │ Sensors (hooks)              │ Always active — auto-enforced
  Layer 2 │ Path-scoped rules            │ Auto-load when reading matching files
  Layer 3 │ Claude Code skills           │ /slash-command and description-based
  Layer 4 │ CLAUDE.md navigation tables  │ Scenario-based "Activate when..." guidance
  Layer 5 │ Trigger sections in files    │ Embedded scenarios, paths, and examples

Layer 1: Sensors (Hooks)

Sensors are the most deterministic layer. They run automatically via Claude Code’s hook system — no user action required.

Bonsai generates hook entries in .claude/settings.json during bonsai init and bonsai add. Each sensor script runs at a specific event (session start, before/after tool use, on stop) and can inject context, block actions, or flag issues.

Event	When it fires
SessionStart	Once at session startup
UserPromptSubmit	Before each user prompt is processed
PreToolUse	Before the agent uses a tool (can block)
PostToolUse	After a tool completes
SubagentStop	When a dispatched sub-agent finishes
Stop	After every agent response

Sensors are always active. You cannot trigger them manually — they enforce automatically.

Layer 2: Path-Scoped Rules

Path-scoped rules auto-load skills when the agent reads files matching specific glob patterns. They live in .claude/rules/skill-{name}.md and are generated by Bonsai.

Each rule file contains a YAML frontmatter with paths: globs. When Claude reads a file matching any of those globs, the rule fires and instructs the agent to load the corresponding skill.

Layer 3: Claude Code Skills

Claude Code skills (.claude/skills/{name}/SKILL.md) enable two activation methods:

1. Slash commands — type /{name} to explicitly invoke a workflow
2. Description-based auto-invocation — Claude reads skill descriptions and may automatically load the workflow when the user’s request matches

Only the 7 curated workflows get Claude Code skill files. Other workflows and all skills are activated through other layers.

Layer 4: CLAUDE.md Navigation Tables

The generated CLAUDE.md in each workspace contains scenario-based navigation tables. Instead of listing abilities by name, tables use “Activate when…” descriptions derived from trigger metadata.

Layer 5: Trigger Sections in Ability Files

Each skill and workflow file begins with a ## Triggers section containing activation metadata — slash command, auto-load patterns, scenario descriptions, and example prompts.

Slash Commands

Seven curated workflows are available as /slash-commands in Claude Code:

Command	What it does
/planning	End-to-end planning process — from request to dispatch-ready plan
/code-review	Review agent output against the plan — correctness, standards, security
/pr-review	Review a pull request — context, scope, correctness, security, performance, standards
/security-audit	Security audit — secrets scan, dependency audit, SAST, config review, access control
/issue-to-implementation	End-to-end autonomous workflow — issue intake through to shipped code
/test-plan	Design a structured test plan for a feature — scope, prioritize, allocate test types
/plan-execution	Execute an assigned plan step by step — implement, test, report

Slash commands are the most explicit activation method. Use them when you know exactly which workflow you want.

Path-Based Auto-Loading

Skills with path triggers auto-load when the agent reads files matching their glob patterns:

Skill	Glob Patterns
API Design Standards	**/routes/**, **/handlers/**, **/controllers/**, **/api/**
Auth Patterns	**/auth/**, **/middleware/auth*, **/login*, **/session*
CLI Conventions	cmd/**, **/cli/**, **/*command*
Coding Standards	*.go, *.py, *.js, *.ts, *.java, *.rs
Container Standards	**/Dockerfile*, **/docker-compose*, **/k8s/**
Database Conventions	*.sql, migrations/**, **/schema.*, **/models/**
Design Guide	**/components/**, **/*.css, **/*.scss, **/styles/**
IaC Conventions	**/*.tf, **/*.tfvars, **/cloudformation/**
Mobile Patterns	**/ios/**, **/android/**, **/*.swift, **/*.kt
Test Strategy	**/*_test.go, **/*.test.*, **/*.spec.*
Testing	**/*_test.go, **/*.test.*, **/*.spec.*, **/test/**

Note

Test Strategy and Testing share some glob patterns. Both will auto-load when the agent reads test files. Test Strategy covers the architectural decisions (which tests to write and why), while Testing covers the implementation conventions (frameworks, patterns, coverage requirements).

Customization

Adding Custom Rules

You can create your own .claude/rules/ files alongside the ones Bonsai generates. Custom rule files will not be tracked by the Bonsai lock file and will not be overwritten by bonsai update.

Adding Custom Skills

You can create your own .claude/skills/ files to add custom slash commands.

What Bonsai Manages vs. What You Own

File pattern	Managed by Bonsai	Safe to customize
.claude/rules/skill-*.md	Yes — generated, tracked in lock file	No — will be overwritten on bonsai update
.claude/rules/custom-*.md	No	Yes — Bonsai will never touch these
.claude/rules/{any-other-name}.md	No	Yes — Bonsai only generates skill- prefixed files
.claude/skills/{workflow}/SKILL.md	Yes — generated for curated workflows	No — will be overwritten on bonsai update
.claude/skills/{custom}/SKILL.md	No	Yes — Bonsai will never touch these

Tip

Generated .claude/rules/ and .claude/skills/ files should be committed to version control. They are project-specific configuration, not user-local state.

Troubleshooting

Ability didn’t activate

1. Is the ability installed? Run bonsai list to check.
2. Is the agent type compatible? Check agents: in meta.yaml.
3. Did the agent read a matching file? Path-based rules only fire on file reads.
4. Is the session started properly? The session-context sensor loads CLAUDE.md at session start.
5. Try explicit invocation. Use a slash command to bypass auto-detection.

Wrong ability loaded

1. Overlapping path patterns. Some skills share glob patterns — be more specific in your request.
2. Ambiguous prompt. Use a slash command for explicit invocation.
3. Custom rules conflicting. Check if custom .claude/rules/ files overlap with generated rules.