agenthood

# AGENTS.md — The Member Registry

This file is the agent-agnostic convention source for the Agenthood.
All AI coding agents (Claude Code, Copilot, Codex) should read this file
to understand the Society's standards before taking any action in a repository.

---

## Commit Standards

- Follow [Conventional Commits](https://www.conventionalcommits.org/) strictly
- Format: `type(scope)!: subject` — `!` marks breaking changes
- Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `revert`
- Subject: imperative, lowercase, ≤150 chars, no trailing period
- One logical change per commit — if in doubt, split it
- Never write: `fix stuff`, `wip`, `update`, `changes`, `misc`, `asdf`
- Never add `Co-Authored-By` footers — commits carry the author's identity only

## Branch Standards

- **Always start a new branch from the latest default branch**: `git fetch origin && git checkout main && git pull origin main && git checkout -b type/issue-NUMBER-description`
- One branch per issue: `type/issue-NUMBER-short-description`
- Never commit directly to `main`
- Branch names are lowercase, hyphenated, no spaces

## Pull Request Standards

- Every PR links to an issue via `Closes #N` or `Fixes #N`
- PR title follows the same Conventional Commits format as commits
- PR description answers: what changed, why, how to test
- **HARD GATE: Never merge unless ALL of the following are green:**
  - **All CI checks** (GitHub Actions workflows — every job, every check)
  - **Tests** (`npm test` or equivalent — zero failures)
  - **Build** (`npm run build` or equivalent — zero errors)
  - **Lint** (`npm run lint` or equivalent — zero warnings/errors)
- A red CI run is a blocking failure. No exceptions. Rebase, fix, re-run. Do not merge on a previous green run if the latest run is red.
- If CI fails after merge conflicts are resolved, you must re-run CI and wait for green before merging.

## Agent Behavior Rules

- Always create a branch before making changes
- Always run tests before considering a task complete
- Always prefer editing existing files over creating new ones
- Never add comments that explain *what* — only *why* when non-obvious
- Never introduce abstractions beyond what the task requires
- Never push to remote without explicit user confirmation
- Never merge without explicit user confirmation
- **Never merge a PR with failing CI** — verify `gh pr checks` shows ALL green before merging

## The Members

Load skills from `skills/` to activate specialized agents:

- `the-scribe` — commit messages, PR descriptions, changelogs
- `the-architect` — spec-driven development, planning, ADRs
- `the-builder` — coding, implementation, refactoring, test updates, local validation
- `the-reviewer` — code review, quality gates
- `the-tester` — TDD, test generation, coverage
- `the-debugger` — error triage, root cause analysis
- `the-auditor` — security review, dependency audit
- `the-herald` — semantic versioning, release notes
- `the-librarian` — documentation, knowledge management
- `the-doorman` — validation, health checks, enforcement
- `the-oracle` — institutional knowledge, member authoring templates, naming guidance
- `the-envoy` — cross-provider translation, bootstrap generation, convention validation
- `the-sentinel` — Society document integrity, cross-member contradiction detection, structural drift
- `the-warden` — code smell detection, complexity enforcement, architectural boundary violations
- `the-steward` — context economy, member routing, provider cache strategy, session triage
- `the-mediator` — first-in-line intent routing, handoff sequencing
- `the-operator` — runtime health, deployment, incidents, rollback, monitoring
- `the-strategist` — goal refinement, requirement discovery, ambiguity resolution
- `the-mailman` — message delivery, content scheduling, notification dispatch, cross-posting
- `the-inspector` — visual-reasoning benchmarking, pixel-level analysis, multi-panel correspondence

## Confidence-Gated Routing

All routing decisions follow a confidence cascade — obvious requests route instantly,
ambiguous requests surface to refinement. No request pays the same routing cost.

**The Mediator** scores every intent classification (0-100%):
- >= 90%: route directly to the specialist
- 70-89%: route with stated confidence — the receiving member can reclassify
- 50-69%: run Parallel Evaluation (Strategist + Doorman) before routing
- < 50%: escalate to The Strategist for refinement

**The Steward** scores every task's complexity (0-100%) before model tier routing:
- 0-39%: budget tier (Haiku, Flash, mini)
- 40-69%: standard tier (Sonnet, GPT-4o, Gemini Pro)
- 70-100%: frontier tier (Opus, o1, Gemini 2.0)
- If complexity confidence < 80%: run parallel evaluation before committing to a tier

Every routing decision produces a type-safe record in `.agenthood/routing/`.
`intent` is one of `ambiguous`, `capacity-sensitive`, `entry-violation`,
`clear-specialist`; `confidence` is an integer 0-100; `target` is a registered
member; `reasoning` is the only free-text field. `agenthood verify` enforces
all of it and reports every violation at once. The full record shape is in
[skills/the-mediator/SKILL.md](skills/the-mediator/SKILL.md) — do not duplicate
it here, or the two drift.

Binary classification without confidence is a guess. Calibrated confidence with
a cascade is a decision.

## Autonomous Runtime (agenthood run)

Members can also be executed as real LLM agents via the TypeScript runtime.
This is optional and additive — the prompt-driven workflow above continues to work unchanged.

```bash
# Build the runtime (once, after install)
npm run build

# Set the LLM provider key in your environment (do NOT commit it)
# Set GROQ_API_KEY in your shell profile or CI secrets (free at console.groq.com)
# or use Ollama for fully offline execution — no key required

# List available members
npx agenthood list

# Invoke any member against a task
npx agenthood run the-scribe "write a commit message for the current diff"
npx agenthood run the-reviewer "review the open PR"
npx agenthood run the-architect "plan the implementation for issue #42"
```

The runtime reads `.agenthood/config.json` (written by `npx agenthood init`) and respects
the same `members` configuration. The default LLM provider follows the `providers` list
in the config (currently opencode, with Groq among the fallbacks). See
[ADR-008](docs/adr/ADR-008-typescript-runtime-over-python.md)
and [ADR-009](docs/adr/ADR-009-groq-as-default-llm-provider.md) for design decisions.

Every `agenthood run` records one decision and one provenance entry (success or
failure) — the audit trail in `.agenthood/decisions/` and
`.agenthood/provenance/`, with tamper-evident hash-chain integrity and causal
links between decisions. See
[ADR-015](docs/adr/ADR-015-decision-intelligence-and-provenance.md) and
[decision-intelligence.md](docs/architecture/decision-intelligence.md).

> **ADR-008** supersedes the earlier Python/DeepAgents runtime approach.
> The TypeScript CLI in this repo is the single supported runtime for `agenthood run`.

More agent context in fworks-tech/agenthood

60 other files this repository gives its agents.