action-runner

# Action Runner Skill

The library is great at *recommending* work. This skill executes it — the action layer of the
[Professional Brain](../professional-brain/SKILL.md) (Phase 2). A skill says "open a ticket per
checklist item"; this turns that into real GitHub/Linear/Slack actions, **safely**: previewed,
risk-rated, approved, then recorded. The cardinal rule: **nothing acts silently.**

## What This Skill Produces

1. A **dry-run actions plan** — every proposed action with its target, operation, and **risk**.
2. After approval, the **executed actions** (via the connected action MCP) — outbound/destructive
   ones gated individually.
3. A **record back to the brain** of what was actually done, with provenance.

## Required Inputs

Ask for (if not already provided):
- **The recommendations to act on** (a launch checklist, PRD requirements, postmortem follow-ups…).
- **The connected action MCP** and **targets** — which GitHub repo / Linear project / Slack channel. Scope is limited to what the user names; never act outside it.
- **Approval posture** — what may run with a single OK vs. what needs per-action confirmation.

## How it works

```
recommend → build an actions plan (JSON) → preview + risk-gate → approve → execute → record
```

1. **Build the plan** — express each action as JSON: `{"target","op","args","why","risk?"}`.
2. **Preview + gate** — run the helper; it prints a dry-run, classifies risk (🟢 low / 🟡 medium /
   🔴 high), and **refuses to proceed while any 🔴 outbound/destructive action is unapproved**:
   ```bash
   echo '<plan json>' | python3 scripts/action_preview.py -
   # after the user approves the risky ones:
   echo '<plan json>' | python3 scripts/action_preview.py - --allow-high
   ```
3. **Approve** — low/medium can run on a single confirmation; every 🔴 (post, send, delete, deploy,
   merge, charge…) needs explicit per-action approval. Default is **do nothing** until told.
4. **Execute** — only approved actions, only via the connected action MCP (e.g. Composio/GitHub
   `create_issue`). One target at a time; stop and report on the first failure.
5. **Record** — append what was actually done to the brain so the loop closes:
   ```bash
   python3 ../professional-brain/scripts/brain_write.py ./brain decisions "Filed launch tickets" \
     --tag external --body "Opened 7 issues in acme/app from the launch checklist" --commit
   ```

## Supported action targets

Any action MCP can be wired in; these are the common targets, with example operations and the
**default risk** the gate applies. Reads are 🟢; anything outbound, destructive, or that spends is 🔴.

| Target | Example operations | Default risk |
|---|---|---|
| **GitHub** | `create_issue`, `comment`, `open_pr` · (`merge_pr`, `close` 🔴) | 🟡 (🔴 for merge/close) |
| **Linear / Jira** | `create_issue`, `update_status`, `comment` | 🟡 |
| **Slack** | `post_message`, `reply_in_thread` (outbound → always confirm) | 🔴 |
| **Notion** | `append_block`, `create_page`, `update_property` | 🟡 (🔴 if it overwrites) |
| **Email / Gmail** | `send_email` (outbound) | 🔴 |
| **Calendar** | `create_event`, `invite` (outbound) | 🟡 (🔴 if it emails invitees) |

Pick the narrowest target and op that does the job, scope to exactly what the user named, and let the
risk gate decide what needs explicit approval. Outbound messages (Slack/email) are 🔴 by default —
the model never posts on someone's behalf without a per-action yes.

## Safety rules (non-negotiable)

- **Dry-run by default.** The plan is shown before anything runs.
- **Approval-gated.** No execution without a yes; 🔴 actions are confirmed one by one.
- **Scope-limited.** Only the repos/channels/projects the user named.
- **Logged.** Every executed action is recorded to the brain with an `[external]` tag and a link.
- **No silent retries, no bulk outbound.** If a step fails, stop and surface it.

## The contract for other skills

An action-aware skill adds a short **"Proposes Actions"** section: after producing its artifact,
it lists the actions it *could* take (target · op · why), then hands off to `action-runner` —
which previews, gates, executes, and records. The skill never executes directly.

## Output Format

1. **Proposed actions** — a table: # · target · operation · why · risk.
2. **Gate result** — the preview output; the 🔴 actions needing approval called out explicitly.
3. **Executed** (after approval) — what ran, with links/IDs returned by the MCP.
4. **Recorded to the brain** — the line(s) appended, with provenance.

## Quality Checks

- [ ] A dry-run plan is shown before anything executes
- [ ] Every action has a risk level; 🔴 actions are individually approved
- [ ] Execution stays within the named scope and uses only the connected MCP
- [ ] Each executed action is recorded back to the brain with an `[external]` tag
- [ ] On failure, it stops and reports rather than retrying blindly

## Anti-Patterns

- Executing anything without showing the dry-run plan first
- Treating an outbound/destructive action (post, email, delete, deploy) as low-risk
- Acting outside the scope the user named, or fanning out to many targets
- "Helpfully" doing more than was approved
- Forgetting to record what was done — the brain must reflect reality