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 docs/members/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, workflows can be executed autonomously
rather than pasted into an AI assistant manually.

# Requires orchestrator (planned — `src/orchestrator/` does not exist yet)
npx agenthood run workflow review-pr --pr 42
npx agenthood run workflow triage-issues
npx agenthood run workflow diagnose-ci --run-id <id>
npx agenthood run workflow sync-docs

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 below 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 run workflow review-pr --pr ${{ github.event.pull_request.number }} --mode ci
        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.