Creating Custom Routines

Routines are periodic maintenance tasks with a frequency. You can create custom routines alongside catalog-provided ones.

How It Works

Create a file in agent/Routines/ (e.g., agent/Routines/branch-cleanup.md)
Add YAML frontmatter with description and frequency
Run bonsai update — it detects untracked files and offers to track them
Once tracked, custom routines appear in CLAUDE.md, .bonsai.yaml, and the routine dashboard

Frontmatter Format

Routines need a frequency field:

---
description: Review and clean up stale feature branches
display_name: Branch Cleanup
frequency: 14 days
---

# Branch Cleanup

**Frequency:** Every 14 days

1. **List stale branches:**
   - Run `git branch --merged` to find branches already merged
   ...

Field	Required	Notes
`description`	Yes	Shown in CLAUDE.md nav tables
`display_name`	No	Human-readable name
`frequency`	Yes	How often to run (e.g., `5 days`, `7 days`, `14 days`)

File Naming

Use kebab-case for filenames: branch-cleanup.md, not BranchCleanup.md
The filename (minus extension) becomes the item’s machine name
Use .md extension

The Routine Dashboard

Custom routines are automatically added to the routine dashboard at agent/Core/routines.md. The dashboard tracks:

When the routine last ran
When it’s next due
Whether it’s overdue

The routine-check sensor reads this dashboard at session start and flags overdue routines.

What `bonsai update` Does for Routines

When you run bonsai update with custom routines:

Detects untracked .md files in agent/Routines/
Validates frontmatter — warns if frequency is missing
Tracks in .bonsai.yaml and .bonsai-lock.yaml
Updates the routine dashboard at agent/Core/routines.md
Refreshes CLAUDE.md nav tables