Action Recipes

Copy any of the snippets below into your Spruce project's actions/ folder as <name>.md to add the action to the project. Each recipe is a complete action definition: frontmatter (with command: and optionally display: / forward:) plus the markdown body, which becomes the agent's system prompt or, for non-agent commands, is unused.

The display name comes from the filename: save Run Tests as run-tests.md, Dev Server as dev-server.md.

The agent launchers below mirror the multi-mode base actions Spruce ships for Claude Code, Codex, OpenCode, Kiro, and Gemini. These recipes are for hand-authoring or layering in tweaks on top of the base bundle. See Where actions come from.

Agent launchers

Most useful actions launch an agent. The general shape is an argv mode such as claude --system-prompt '{{action_content}}' --allowedTools "..." -- "<user-turn>", with equivalent modes for Codex, OpenCode, Kiro, or Gemini and the prompt living in the markdown body.

Generic Claude Code launcher

---
display:
  icon: terminal-2
command: claude --system-prompt '{{action_content}}' --allowedTools "Read,Glob,Grep,Edit,Write,Bash,mcp__spruce__artifact_get,mcp__spruce__artifact_update,mcp__spruce__artifact_body_edit,mcp__spruce__artifact_search,mcp__spruce__artifact_comment_list,mcp__spruce__artifact_comment_claim,mcp__spruce__artifact_comment_add,mcp__spruce__artifact_comment_reply,mcp__spruce__artifact_comment_resolve,mcp__spruce__template_get"
---
You are a software developer working on a Spruce project.

The current date and time is: {{current_time}}
Your session ID is {{session_id}}.

## Current Context

You are viewing artifact: {{artifact_id}}

Get it using `mcp__spruce__artifact_get` to understand what you're working with.

{{context:artifact-system}}
{{context:comment-system}}

The user will tell you what they need help with.

Save as claude-code.md or adapt the mode for another supported agent. This is the do-anything launcher the user picks for ad-hoc work.

Plan / Implement / Review

The base bundle ships these as separate actions, each with a tighter prompt and a curated tool list. See the Plan example on Actions for a full real-world version. Recommended pattern:

• Plan: read-only / search tools, prompts the agent to refine the artifact's scope and write an implementation plan back into the body.
• Implement: read + write tools (Edit, Write, Bash) plus git, prompts the agent to execute the plan in the worktree.
• Review: read-only + git, prompts the agent to self-review the diff and post comments.

Respond to comments

---
display:
  icon: messages
command: claude --system-prompt '{{action_content}}' --allowedTools "Read,Glob,Grep,Edit,Write,Bash,mcp__spruce__artifact_get,mcp__spruce__artifact_update,mcp__spruce__artifact_body_edit,mcp__spruce__artifact_status,mcp__spruce__artifact_commit,mcp__spruce__artifact_sync,mcp__spruce__artifact_comment_list,mcp__spruce__artifact_comment_claim,mcp__spruce__artifact_comment_add,mcp__spruce__artifact_comment_reply,mcp__spruce__template_get,mcp__spruce__git_status,mcp__spruce__git_diff" -- "Your session ID is {{session_id}}. Get artifact {{artifact_id}} and respond to its unresolved comments."
forward:
  - comment-added
---
You are responding to comments on a Spruce artifact. Read each unresolved comment, address it (either by replying with the answer, or by editing the artifact / code as requested), and resolve it when done.

{{context:artifact-system}}
{{context:comment-system}}

The forward: [comment-added] line is the bit that lets the same session absorb new user comments mid-loop without re-launching.

Dev / build / test (non-agent)

Non-agent actions skip the prompt and just put a command in the frontmatter. The body is unused.

Dev server

---
display:
  icon: server
command: npm run dev
---

Production build

---
display:
  icon: package
command: npm run build
---

Unit tests, full suite

---
display:
  icon: test-pipe
command: npm test
---

Unit tests, watch mode

---
display:
  icon: refresh
command: npm test -- --watch
---

Lint

---
display:
  icon: bug
command: npm run lint
---

Run tests by artifact ID

Combines a template variable so the action filters tests by the current artifact's ID:

---
display:
  icon: target
command: npm test -- --grep "{{artifact_id}}"
---

Rust workspace check

---
display:
  icon: package-import
command: cargo check --workspace
---

Git helpers

Quick-commit and push the code branch

---
display:
  icon: git-commit
command: git add -A && git commit -m "wip" && git push
---

Use wip commits sparingly. For real work, prefer reviewed commits. This action operates on the code repo's branch, not the Spruce project. For the Spruce project, use the sync menu in the sidebar header.

Related

• Actions — anatomy, MCP server, base bundle.
• Action Template Variables — {{artifact_id}}, {{session_id}}, {{action_content}}, etc.
• MCP Tools — the tool surface area agent commands hand to the agent via --allowedTools.