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:

A stable, production-ready gh aw runtime with consistent behaviour across repositories
Credentials provisioned at the workflow level (GitHub token scopes, LLM API keys)
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.

Available Templates

File	Trigger	Society Member	What it does
triage-issues.agent.md	New issue opened	The Doorman	Classifies, labels, and asks clarifying questions
review-pr.agent.md	PR opened or ready for review	The Reviewer	Five-axis review with structured findings
diagnose-ci-failure.agent.md	CI run fails	The Debugger	Root cause diagnosis posted as a PR comment
sync-docs.agent.md	Merge to main	The Librarian	Checks for stale docs and opens a follow-up PR

How to Use a Template

Open your AI coding assistant (Claude Code, OpenAI Codex CLI, etc.)
Load the relevant Society member skill — e.g., for PR review, load skills/the-reviewer/SKILL.md
Paste the template's Steps section as your prompt
Add context: the issue body, PR diff, CI log, or merge commit as applicable
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:

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:

# .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.