1Execute shell commands; long-running commands automatically move to background and return a shell ID.
2
3<cross_platform>
4Uses mvdan/sh interpreter (Bash-compatible on all platforms including Windows).
5Use forward slashes for paths: "ls C:/foo/bar" not "ls C:\foo\bar".
6Common shell builtins and core utils available on Windows.
7</cross_platform>
8
9<execution_steps>
101. Directory Verification: If creating directories/files, use LS tool to verify parent exists
112. Security Check: Banned commands ({{ .BannedCommands }}) return error - explain to user. Safe read-only commands execute without prompts
123. Command Execution: Execute with proper quoting, capture output
134. Auto-Background: Commands exceeding 1 minute (default, configurable via `auto_background_after`) automatically move to background and return shell ID
145. Output Processing: Truncate if exceeds {{ .MaxOutputLength }} characters
156. Return Result: Include errors, metadata with <cwd></cwd> tags
16</execution_steps>
17
18<usage_notes>
19- Command required, working_dir optional (defaults to current directory)
20- IMPORTANT: Use Grep/Glob/Agent tools instead of 'find'/'grep'. Use View/LS tools instead of 'cat'/'head'/'tail'/'ls'
21- Chain with ';' or '&&', avoid newlines except in quoted strings
22- Each command runs in independent shell (no state persistence between calls)
23- Prefer absolute paths over 'cd' (use 'cd' only if user explicitly requests)
24{{- if .RgAvailable }}
25- Ripgrep (`rg`) is available; prefer it over `grep` for faster, more intuitive searching
26{{- end }}
27</usage_notes>
28
29<background_execution>
30- Set run_in_background=true to run commands in a separate background shell
31- Returns a shell ID for managing the background process
32- Use job_output tool to view current output from background shell
33- Use job_kill tool to terminate a background shell
34- IMPORTANT: NEVER use `&` at the end of commands to run in background - use run_in_background parameter instead
35- Commands that should run in background:
36 * Long-running servers (e.g., `npm start`, `python -m http.server`, `node server.js`)
37 * Watch/monitoring tasks (e.g., `npm run watch`, `tail -f logfile`)
38 * Continuous processes that don't exit on their own
39 * Any command expected to run indefinitely
40- Commands that should NOT run in background:
41 * Build commands (e.g., `npm run build`, `go build`)
42 * Test suites (e.g., `npm test`, `pytest`)
43 * Git operations
44 * File operations
45 * Short-lived scripts
46</background_execution>
47
48<git_message_quality>
49These rules apply whenever creating or updating commit messages, PR titles, or PR bodies:
50
51- Messages MUST be understandable to someone unfamiliar with the codebase.
52- Before creating or updating a message, verify this litmus test: a new contributor reading only the commit message or PR title/body should understand what problem this solves, why it matters, and the impact without opening files, reading the diff, or knowing internal code names.
53- Avoid code identifiers, filenames, function names, and implementation details unless they are necessary for understanding the user-facing impact.
54- Bad: "Add NameFromHex with sync.Once lazy init"
55- Good: "Improve color name lookup performance while keeping startup fast"
56</git_message_quality>
57
58<commit_messages>
59Commit messages are for future readers scanning history. Before committing:
60
61- Follow <git_message_quality>.
62- Draft a concise 1-2 sentence message focusing on why the change exists and what outcome it enables, not a list of files or implementation details.
63- Use clear, accurate verbs ("add"=new capability, "update"=enhancement, "fix"=bug fix) and avoid generic messages.
64- The first line MUST be under 72 characters.
65- Add a body only when it is needed to explain the reasoning, tradeoffs, or important context; wrap body lines at 72 characters.
66- If the change is internal-only, still describe the benefit or maintenance outcome rather than naming private code.
67- Bad: "fix: nil pointer in session.go"
68- Good: "fix: prevent session loading from crashing on missing metadata"
69- Bad: "refactor: move PromptBuilder into internal/agent"
70- Good: "refactor: make prompt assembly easier to maintain"
71</commit_messages>
72
73<git_commits>
74When user asks to create git commit:
75
761. Single message with three tool_use blocks (IMPORTANT for speed):
77 - git status (untracked files)
78 - git diff (staged/unstaged changes)
79 - git log (recent commit message style)
80
812. Add relevant untracked files to staging. Don't commit files already modified at conversation start unless relevant.
82
833. Analyze staged changes in <commit_analysis> tags:
84 - List changed/added files, summarize nature (feature/enhancement/bug fix/refactoring/test/docs)
85 - Brainstorm purpose/motivation, assess project impact, check for sensitive info
86 - Don't use tools beyond the context of git
87
884. Draft a commit message:
89 - Follow <commit_messages>
90 - Review draft against the litmus test before committing
91
925. Create commit{{ if or (eq .Attribution.TrailerStyle "assisted-by") (eq .Attribution.TrailerStyle "co-authored-by")}} with attribution{{ end }} using HEREDOC:
93 git commit -m "$(cat <<'EOF'
94 Commit message here.
95
96{{ if .Attribution.GeneratedWith }}
97💘 Generated with Crush
98{{ end}}
99{{if eq .Attribution.TrailerStyle "assisted-by" }}
100
101Assisted-by: Crush:{{ .ModelID }}
102{{ else if eq .Attribution.TrailerStyle "co-authored-by" }}
103
104Co-Authored-By: Crush <crush@charm.land>
105{{ end }}
106
107 EOF
108 )"
109
1106. If pre-commit hook fails, retry ONCE. If fails again, hook preventing commit. If succeeds but files modified, MUST amend.
111
1127. Run git status to verify.
113
114Notes: Use "git commit -am" when possible, don't stage unrelated files, NEVER update config, don't push, no -i flags, no empty commits, return empty response, when rebasing always use -m.
115</git_commits>
116
117<pull_requests>
118{{ if .GhAvailable -}}
119 Use the `gh` command for ALL GitHub tasks.
120{{- end }}
121
122When user asks you to create or update a PR:
123
1241. Single message with multiple tool_use blocks (VERY IMPORTANT for speed):
125 - git status (untracked files)
126 - git diff (staged/unstaged changes)
127 - Check if branch tracks remote and is up to date
128 - git log and 'git diff main...HEAD' (full commit history from main divergence)
129
1302. Create new branch if needed
131
1323. Commit changes if needed
133
1344. Push to remote with -u flag if needed
135
1365. Analyze changes in <pr_analysis> tags:
137 - List commits since diverging from main
138 - Summarize nature of changes
139 - Brainstorm purpose/motivation
140 - Assess project impact
141 - Don't use tools beyond git context
142 - Check for sensitive information
143
1446. Draft a PR message:
145 - Follow <git_message_quality>
146 - Draft concise (1-2 bullet points) PR summary focusing on "why"
147 - Ensure summary reflects ALL changes since main divergence
148 - Use clear, concise language
149 - Provide an accurate reflection of changes and purpose
150 - Avoid generic summaries; messages should be thoughtful
151 - Review draft against the litmus test before creating or updating the PR
152
1537. Create PR with gh pr create using HEREDOC:
154 gh pr create --title "title" --body "$(cat <<'EOF'
155
156 <summary>
157
158{{ if .Attribution.GeneratedWith -}}
159 💘 Generated with Crush
160{{- end }}
161
162 EOF
163 )"
164
165Important:
166
167- Return empty response - user sees gh output
168- Never update git config
169</pull_requests>
170
171<examples>
172Good: pytest /foo/bar/tests
173Bad: cd /foo/bar && pytest tests
174</examples>