erg.

Action reference

Actions are used in task states via the action: key. Each action accepts typed params and may produce output data that downstream choice states can inspect.

AI actions

ai.code async

Starts an autonomous Claude Code session that reads the issue, writes code, runs tests, and commits changes locally. The daemon waits for the session to complete before advancing.

Params
Name Type Default Description
max_turns int 50 Maximum number of Claude turns per session.
max_duration duration 30m Hard time limit for the session, e.g. 20m, 2h.
containerized bool true Run Claude inside a Docker container sandbox.
system_prompt string built-in Inline prompt or file:.erg/prompt.md to load from the repo. Overrides the default coding prompt.
format_command string none Shell command to run as a formatter after coding completes (e.g. go fmt ./...). Claude is also instructed to run it before each commit. Omit to skip auto-formatting.
format_message string Apply auto-formatting Commit message used when the daemon commits the post-coding format pass. Only used when format_command is set.
simplify bool false When true, Claude runs the built-in /simplify skill after completing the primary coding task to review and clean up the implementation.
Output data

None. Session completion is signalled internally; the daemon advances the state machine when the worker exits.

Notes
  • If the branch already has an open PR, coding is skipped and the workflow advances to github.create_pr, which detects the existing PR.
  • If the branch was already merged, the issue is closed and the workflow jumps to done.
ai.fix_ci async

Resumes the existing Claude session to fix failing CI. Fetches failure logs from the most recent GitHub Actions run and passes them to Claude as context.

Params
Name Type Default Description
max_ci_fix_rounds int 3 Maximum number of CI fix attempts before returning an error.
system_prompt string built-in Custom system prompt for the fix session.
format_command string inherited Shell command to run as a formatter after each CI fix round (e.g. go fmt ./...). Overrides the value inherited from the ai.code step. Omit to keep the inherited formatter or skip formatting.
format_message string Apply auto-formatting Commit message used when the daemon commits the post-fix-round format pass. Only used when format_command is set (directly or inherited).
simplify bool false When true, Claude runs the built-in /simplify skill after fixing CI to review and clean up the implementation.
Output data
Key Type Description
ci_fix_rounds int Incremented on each attempt. Inspect in choice states to check round count.
ai.address_review async

Fetches PR review comments and resumes the coding session to address them. Daemon-managed transcript comments are filtered out so Claude only sees human feedback. Increments review_rounds on each invocation; returns an error when the max is reached.

Params
Name Type Default Description
max_review_rounds int 3 Maximum number of review-address attempts before returning an error.
system_prompt string built-in Custom system prompt for the review-address session.
simplify bool false When true, Claude runs the built-in /simplify skill after addressing review feedback to review and clean up the implementation.
Output data
Key Type Description
review_rounds int Incremented on each attempt. Inspect in choice states to check round count.
ai.write_pr_description sync

Generates a rich PR description from the branch diff using Claude and updates the open PR body. Useful after coding to produce a concise, human-readable summary before requesting review.

Params

None.

Output data

None.

ai.resolve_conflicts async

Merges the base branch into the feature branch (leaving conflict markers in place), then starts a Claude session to resolve the conflicts. Claude reads each conflicted file, resolves the markers, stages the files, and commits the merge.

Params
Name Type Default Description
max_conflict_rounds int 3 Maximum number of conflict resolution attempts before returning an error.
system_prompt string built-in Custom system prompt for the resolution session.
simplify bool false When true, Claude runs the built-in /simplify skill after resolving conflicts to review and clean up the implementation.
Output data
Key Type Description
conflict_rounds int Incremented on each attempt. Inspect in choice states to check round count.
ai.plan async

Starts a read-only planning session where Claude analyzes the issue and codebase, then posts a structured implementation plan as an issue comment. No new branch or worktree is created — Claude reads from the main repo directory. Useful as a first step before ai.code to get human sign-off on the approach.

Params
Name Type Default Description
system_prompt string built-in Inline prompt or file:.erg/plan_prompt.md to load from the repo. Overrides the default planning prompt.
max_turns int unlimited Maximum number of Claude turns for the planning session.
max_duration duration none Hard time limit for the session, e.g. 20m, 2h.
containerized bool true Run Claude inside a Docker container sandbox.
Output data

None. The plan is posted as an issue comment by Claude during the session. The daemon advances the state machine when the worker exits.

ai.review async

Runs a Claude session to self-review the branch diff before pushing, acting as a quality gate. Claude examines the diff, checks for correctness, test coverage, security issues, and code quality, then reports via the submit_review MCP tool. If the review fails (passed=false), the step returns an error and the workflow follows the error edge.

Params
Name Type Default Description
max_ai_review_rounds int 1 Maximum number of review attempts before returning an error.
system_prompt string built-in Custom system prompt for the review session.
Output data
Key Type Description
review_passed bool true if the review passed, false if it was blocked. Inspect in choice states to branch on review outcome.
ai_review_summary string One-sentence summary of the review findings.
ai_review_rounds int Incremented on each attempt. Inspect in choice states to check round count.

GitHub actions

github.create_pr sync

Opens a pull request from the working branch to the base branch. Detects and reuses an existing PR if one was already opened in a previous attempt.

Params
Name Type Default Description
draft bool false Create the pull request as a draft. Use when you want the PR visible for early feedback but not yet ready for formal review.
link_issue bool true Add a closing reference to the source issue in the PR body (e.g. Closes #42).
Output data
Key Type Description
pr_url string URL of the created (or existing) pull request.
Notes
  • If the coding session made no commits, the issue is closed automatically and the workflow skips to done.
github.push sync

Pushes committed changes to the remote branch. Typically used after Claude addresses review feedback.

Params

None.

Output data

None.

github.merge sync

Merges the pull request into the base branch using the configured strategy.

Params
Name Type Default Description
method string rebase Merge strategy: rebase, squash, or merge.
cleanup bool false Delete the worktree and branch after a successful merge.
Output data

None.

github.comment_issue sync

Posts a comment on the original issue associated with the work item.

Params
Name Type Default Description
body string required Comment text. Prefix with file: to load content from a repo path, e.g. file:.erg/comments/msg.md.
Output data

None.

github.comment_pr sync

Posts a comment on the pull request for the work item.

Params
Name Type Default Description
body string required Comment text. Prefix with file: to load content from a repo path, e.g. file:.erg/comments/msg.md.
Output data

None.

github.add_label sync

Adds a label to the source issue.

Params
Name Type Default Description
label string required Label name to add.
Output data

None.

github.remove_label sync

Removes a label from the source issue.

Params
Name Type Default Description
label string required Label name to remove.
Output data

None.

github.close_issue sync

Closes the source issue.

Params

None.

Output data

None.

github.request_review sync

Requests a review from a specific GitHub user on the pull request.

Params
Name Type Default Description
reviewer string required GitHub username to request a review from.
Output data

None.

github.assign_pr sync

Assigns the pull request to a specific GitHub user. Useful for routing work to the right person after coding completes.

Params
Name Type Default Description
assignee string required GitHub username to assign the PR to.
Output data

None.

github.create_release sync

Creates a GitHub release for the repository. Typically used in post-merge workflows to publish a tagged release after a PR lands.

Params
Name Type Default Description
tag string required Git tag for the release, e.g. v1.2.0.
title string same as tag Release title displayed on GitHub.
notes string empty Release body / change notes.
draft bool false Create the release as a draft (not publicly visible).
prerelease bool false Mark the release as a pre-release.
target string default branch Target branch or commit SHA for the release tag.
Output data
Key Type Description
release_url string URL of the created GitHub release.

Asana actions

asana.comment sync

Posts a comment on the Asana task associated with the work item. Requires the ASANA_PAT environment variable to be set and an Asana provider registered for the repository.

Params
Name Type Default Description
body string required Comment text. Prefix with file: to load content from a repo path, e.g. file:.erg/comments/msg.md.
Output data

None.

asana.move_to_section sync

Moves the Asana task to a named section within its configured project board. Use this to reflect workflow progress on the board (e.g., move a card to “In Review” after opening a PR). Requires the ASANA_PAT environment variable to be set and an Asana provider registered for the repository.

Params
Name Type Default Description
section string required Name of the board section to move the task into. Matched case-insensitively against the project's sections.
Output data

None.

Linear actions

linear.comment sync

Posts a comment on the Linear issue associated with the work item. Requires the LINEAR_API_KEY environment variable to be set and a Linear provider registered for the repository.

Params
Name Type Default Description
body string required Comment text. Prefix with file: to load content from a repo path, e.g. file:.erg/comments/msg.md.
Output data

None.

linear.move_to_state sync

Moves the Linear issue to a named workflow state (e.g., “In Progress”, “Done”). Use this to reflect workflow progress in Linear as work advances through the pipeline. Requires the LINEAR_API_KEY environment variable to be set and a Linear provider registered for the repository.

Params
Name Type Default Description
state string required Name of the workflow state to move the issue into. Matched case-insensitively against the team's configured states.
Output data

None.

Git actions

git.format sync

Runs a formatter command in the session worktree, stages all changes with git add -A, and commits them. Silently succeeds if the formatter produces no changes.

Params
Name Type Default Description
command string required Shell command to run, e.g. gofmt -w . or prettier --write ..
message string Apply auto-formatting Commit message used when the formatter produces changes.
Output data

None.

git.rebase sync

Rebases the feature branch onto the latest base branch and force-pushes. This is a mechanical rebase — if real file-level conflicts exist, the rebase is aborted and an error is returned.

Params
Name Type Default Description
max_rebase_rounds int 3 Maximum number of rebase attempts before returning an error.
Output data
Key Type Description
rebase_rounds int Incremented on each attempt.
git.squash sync

Squashes all commits on the feature branch since it diverged from the base branch into a single commit. Useful before opening a PR when you want a clean, single-commit history.

Params
Name Type Default Description
message string auto-generated Commit message for the squashed commit. Defaults to a summary generated from the original commit messages.
Output data

None.

git.validate_diff sync

Runs static validation checks on the branch diff before pushing or opening a PR. All params are optional; with no params the check always passes. Returns an error listing all violations found.

Params
Name Type Default Description
max_diff_lines int 0 (disabled) Fail if total added + deleted lines exceed this value.
forbidden_patterns []string none Fail if any changed file matches one of these glob patterns, e.g. [".env", "*.pem"].
require_tests bool false Fail if source files were modified but no test files appear in the diff.
source_patterns []string common extensions Glob patterns identifying source files for the require_tests check. Defaults to *.go, *.py, *.js, etc.
test_patterns []string common patterns Glob patterns identifying test files. Defaults to *_test.go, test_*.py, *.test.js, etc.
max_lock_file_lines int 0 (disabled) Fail if any single lock file has more than this many lines changed.
lock_file_patterns []string common lock files Glob patterns for lock files. Defaults to go.sum, package-lock.json, yarn.lock, etc.
Output data
Key Type Description
violations []string List of violation messages when checks fail.
git.cherry_pick sync

Cherry-picks one or more commits onto a target branch. Designed for backport workflows where merged changes need to be applied to a release or maintenance branch.

Params
Name Type Default Description
commits []string | string required List of commit SHAs to cherry-pick. Accepts a YAML sequence or a space-separated string.
target_branch string required Branch to cherry-pick the commits onto.
Output data

None.

Slack actions

slack.notify sync

Posts a notification to a Slack channel via an incoming webhook. The message supports Go text/template syntax with work item variables. The webhook URL supports $ENV_VAR expansion so secrets stay out of config files.

Params
Name Type Default Description
webhook_url string required Slack incoming webhook URL. Supports $ENV_VAR substitution, e.g. $SLACK_WEBHOOK_URL.
message string required Message text. Go text/template variables: {{.Title}}, {{.IssueID}}, {{.IssueURL}}, {{.PRURL}}, {{.Branch}}, {{.Status}}.
username string erg Display name shown in Slack.
icon_emoji string :robot_face: Emoji icon for the Slack message.
channel string webhook default Override the channel configured in the webhook, e.g. #alerts.
Output data

None.

Setup

Slack uses Incoming Webhooks for authentication — there is no separate API token. To get a webhook URL:

  1. Go to api.slack.com/apps and create a new app (or open an existing one).
  2. Under Features, click Incoming Webhooks and toggle it on.
  3. Click Add New Webhook to Workspace, choose a channel, and authorise.
  4. Copy the generated URL (e.g. https://hooks.slack.com/services/T.../B.../...).
  5. Set it as an environment variable on the host running erg:
    export SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
  6. Reference it in your workflow config as webhook_url: $SLACK_WEBHOOK_URL.
Example
workflow.yaml (excerpt)
  notify_merged:
    type: task
    action: slack.notify
    params:
      webhook_url: $SLACK_WEBHOOK_URL           # set in the host environment
      message: "Merged: {{.Title}} (#{{.IssueID}})\n{{.PRURL}}"
      username: erg
      icon_emoji: ":white_check_mark:"
      channel: "#eng-deployments"              # optional — overrides webhook default
    next: done

Given an issue titled "Fix login redirect loop" with ID 42 and a merged PR, the message posted to Slack would be:

Slack message (rendered)
Merged: Fix login redirect loop (#42)
https://github.com/your-org/your-repo/pull/99

Webhook actions

webhook.post sync

POSTs a JSON body to a configurable URL. The body is a Go text/template string interpolated with work item data. Use for integrating with external systems — CI triggers, deployment pipelines, or custom notification endpoints.

Params
Name Type Default Description
url string required Destination URL for the POST request.
body string required JSON body template. Go text/template variables: {{.IssueID}}, {{.IssueTitle}}, {{.IssueURL}}, {{.IssueSource}}, {{.PRURL}}, {{.Branch}}, {{.State}}, {{.WorkItemID}}.
headers map[string]string none Additional HTTP request headers, e.g. Authorization: Bearer $TOKEN.
timeout duration 30s Request timeout, e.g. 10s, 1m.
expected_status int 200 HTTP status code considered a success. Non-matching codes return an error.
Output data
Key Type Description
response_status int HTTP status code returned by the server.

Workflow actions

workflow.retry sync

Meta-action that wraps another registered action with synchronous retry logic. On failure it sleeps for the configured interval (scaled by backoff_rate on each subsequent attempt) and re-executes the inner action. Async inner actions are passed through unchanged on the first attempt since they cannot be retried synchronously.

Params
Name Type Default Description
action string required Name of the inner action to execute, e.g. github.push.
max_attempts int 3 Total number of attempts (1 = no retry).
interval duration 0 Base delay between retries, e.g. 10s, 1m.
backoff_rate float 1.0 Multiplier applied to interval after each failed attempt. 1.0 = fixed delay; 2.0 = double each time.
params map none Parameters forwarded to the inner action.
Output data

Returns the output data from the inner action on success.

workflow.wait sync

Pauses workflow execution for a configurable duration. Cancels cleanly on daemon shutdown. Useful as a delay between polling cycles or before time-sensitive operations.

Params
Name Type Default Description
duration duration required How long to pause, e.g. 30s, 5m, 1h.
Output data

None.

made by zack · mit license