# Agentic Workflows

> *Templates for multi-step Society operations. Not automated — intentional.*

---

## What These Files Are

Each `.agent.md` file in this directory is a **manual-prompt template** — a
structured set of instructions you paste into your AI coding assistant to
perform a specific Society operation.

They are **not** deployed as automated GitHub Actions or `gh aw` workflows.
The frontmatter (`on:`, `permissions:`, `safe-outputs:`) describes the
*intended trigger and safety contract* for documentation purposes, not
a live automation configuration.

---

## Why Templates, Not Automation

Deploying these as automated workflows (via GitHub's `gh aw` extension or
similar) would require:

1. A stable, production-ready `gh aw` runtime with consistent behaviour
   across repositories
2. Credentials provisioned at the workflow level (GitHub token scopes,
   LLM API keys)
3. Per-project configuration for labels, milestones, and routing rules

These dependencies are not yet stable enough to prescribe for all adopters.
The template approach gives you the same structured process — with full
control over when and how it runs.

This decision is documented in [ADR-001](../adr/ADR-001-markdown-skills-over-code-agents.md).

---

## Available Templates

| File | Trigger | Society Member | What it does |
|------|---------|----------------|-------------|
| [triage-issues.agent.md](triage-issues.agent.md) | New issue opened | The Doorman | Classifies, labels, and asks clarifying questions |
| [review-pr.agent.md](review-pr.agent.md) | PR opened or ready for review | The Reviewer | Five-axis review with structured findings |
| [diagnose-ci-failure.agent.md](diagnose-ci-failure.agent.md) | CI run fails | The Debugger | Root cause diagnosis posted as a PR comment |
| [sync-docs.agent.md](sync-docs.agent.md) | Merge to main | The Librarian | Checks for stale docs and opens a follow-up PR |
| [sentry-opencode-debugging.agent.md](sentry-opencode-debugging.agent.md) | Production error in Sentry | The Debugger | Verify → search → details → fix → Seer? → regression test |

---

## How to Use a Template

1. Open your AI coding assistant (Claude Code, OpenAI Codex CLI, etc.)
2. Load the relevant Society member skill — e.g., for PR review, load
   `skills/the-reviewer/SKILL.md`
3. Paste the template's **Steps** section as your prompt
4. Add context: the issue body, PR diff, CI log, or merge commit as applicable
5. The member will follow the steps and produce the appropriate output

**Example — triaging a new issue in Claude Code:**

```
/load .claude/skills/the-doorman/the-doorman.md

A new issue was just opened: [paste issue URL or body]

Please follow the triage steps from the triage-issues.agent.md template.
```

---

## Executing Workflows via the Runtime

With the TypeScript runtime, the `review-pr` workflow can be executed
autonomously rather than pasted into an AI assistant manually:

```bash
npx agenthood workflow review-pr
```

Only `review-pr` is registered as a runtime workflow
(`src/workflows/definitions/review-pr.ts`). The other `.agent.md` templates
(`triage-issues`, `diagnose-ci`, `sync-docs`) run manually via an AI assistant
until the orchestrator ships.

The runtime reads the `on:`, `members:`, and `safe-outputs:` frontmatter
from each `.agent.md` file to configure the execution graph and
set `interrupt_on` gates appropriately. In CI environments, pass `--mode ci`
to disable interactive approval gates for actions marked `safe-outputs`.

The orchestrator (`src/orchestrator/`) is not yet implemented. The manual-prompt approach above remains the workflow.

---

## When Fully Automated (CI)

When the orchestrator ships, the `review-pr` workflow will run automatically on every
PR via a GitHub Actions workflow template:

```yaml
# .github/workflows/agenthood-review-pr.yml (generated when orchestrator ships)
on:
  pull_request:
    types: [opened, ready_for_review]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g agenthood
      - run: npx agenthood workflow review-pr
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

The `on:` and `safe-outputs:` frontmatter fields in each `.agent.md` are
already in the correct format for this transition.