agenthood

Agenthood

A full AI engineering team as plain Markdown files.

Specialized AI agents — architect, reviewer, security expert, DevOps engineer, strategist, operator, and more — each a single Markdown skill file any agent runtime can load into any project. No lock-in. No configuration. Just drop them in.

They have opinions about your PR descriptions. They will not merge your branch if your commit says fix stuff. They are not polite about it.

---

The Oath

I commit with intention. I branch with purpose. I review with honesty. I ship with confidence. I never push to main.

---

How it works

Each agent is a single .md file that describes a role, its responsibilities, standards, and how it communicates. Load one or all of them into Claude Code, Copilot, or any runtime that supports skill files. Or run them autonomously via the TypeScript CLI.

1. Install the Society — npm install --save-dev agenthood && npx agenthood init (or npx skills add fworks-tech/agenthood via skills.sh)
2. Load into your runtime — point Claude Code, Copilot, or your agent framework at the skills directory
3. Invoke any agent — ask the Reviewer to check your PR, ask the Auditor to scan your auth flow. They know their role. They have standards.

---

Meet the team

Every role a real software team needs — available as a skill file with impeccable standards.

	Agent	Role
	The Scribe	Commits, PRs, changelogs
	The Architect	System design, ADRs, tech decisions
	The Reviewer	Code review, standards enforcement
	The Tester	TDD, coverage, edge cases
	The Debugger	Error triage, root cause analysis
	The Auditor	Security, vulnerability scanning, dependency audit
	The Herald	Releases, versioning, changelogs
	The Librarian	Documentation, API references
	The Doorman	Validation, branch protection, health checks
	The Oracle	Institutional knowledge, authoring templates
	The Envoy	Cross-provider translation, convention validation
	The Sentinel	Integrity, cross-member contradiction detection
	The Warden	Code health, complexity enforcement
	The Steward	Context economy, provider cache strategies
	The Strategist	Goal refinement, requirement discovery
	The Operator	Runtime health, deployments, rollback

---

Getting started

Option A — Drop into any AI runtime

npm install --save-dev agenthood
npx agenthood init       # interactive setup (~5 minutes)
npx agenthood check      # verify everything is in place

Members are loaded as context by your existing AI assistant. Works with Claude Code and Copilot.

Option B — Run agents autonomously

Execute members as real LLM agents that reason, act, and remember across sessions.

# From the repo clone (when installed via npm, the runtime is pre-built)
npm run build                              # build the runtime (once)
npx agenthood list                          # see available agents
npx agenthood run the-scribe "write a commit message for the current diff"
npx agenthood run the-reviewer "review the changes in the last commit"
npx agenthood run the-architect "plan the implementation for issue #42"
npx agenthood verify                    # validate member SKILL.md integrity
npx agenthood status --watch            # live project health monitoring
npx agenthood rollback the-scribe       # restore SKILL.md from lockfile
npx agenthood workflow review-pr        # execute the review-pr workflow

Set one of these in a .env file in your project root (loaded automatically by the runtime):

Variable	Provider	Free tier
GROQ_API_KEY	Groq (default)	console.groq.com
ANTHROPIC_API_KEY	Anthropic	—
OPENAI_API_KEY	OpenAI	—
OPENCODE_API_KEY	OpenCode / OpenCodeGo	opencode.ai

Or use Ollama for fully offline execution (no key required).

For a full walkthrough — install, commands, CI pipeline, and next steps — see the Academy Getting Started guide.

---

What's shipped

Runtime (TypeScript CLI)

See the CHANGELOG.md for the full version history.

Playground (agenthood-site)

Agenthood Studio — a browser-based chat interface for all 16 Society members. Features configurable provider backend (Anthropic, OpenAI, Groq, Ollama, OpenCode), SSE streaming, turnstile CAPTCHA, session-scoped config persistence, Upstash Redis rate limiting, and structured logging with field-level redaction. Source

---

Compatibility

Agenthood is agent-agnostic. The skill files work with:

• Claude Code — via .claude/skills/
• GitHub Copilot — via .github/copilot-instructions.md

The TypeScript runtime (agenthood run) supports Groq (default, free tier at console.groq.com), Anthropic, OpenAI, OpenCode, and Ollama for fully offline execution.

The Agenthood Studio playground exercises the same runtime through a browser UI — every chat request runs through agenthood/dist/llm with provider routing, failover, and streaming.

---

Architecture

The framework runs on five core principles adapted from production AI agent systems. See the architecture docs for details on how agents coordinate, prioritize, fail over, and stay safe.

Principle	Document
Multi-agent orchestration & agent roles	agent-system.md
Priority queues & concurrency slots	concurrency-and-queues.md
Agent mode vs Ask mode	operating-modes.md
Multi-LLM support & automatic failover	provider-failover.md
Tool registry, scoping & safety caps	built-in-tools.md
Agent memory tiers	memory — ResidualMemory, ShortTermMemory, LongTermMemory, EpisodicMemory, ProjectMemory, DecisionLog, MetricsCollector, InMemoryStore, PersonalisationStore, LanceDBStore
Workflow engine & quality gates	workflows — WorkflowEngine, QualityGates, DiffImpactAnalyzer, WorkflowCheckpoint, GoalChain
Service-agnostic RAG (graph, vector, agentic)	rag — KnowledgeGraphStore, FixedSizeChunkStrategy + MarkdownHierarchicalChunkStrategy, Indexer, Retriever, AgenticRAG, TreeSitterParser, ProjectIngestion

---

For this repo

npm install && npm run build
make setup          # activates git hooks and commit template
npm test            # run all tests
npm run typecheck   # strict TypeScript check
npm run lint        # ESLint

---

Repository structure

See STRUCTURE.md for the full directory tree.

---

Academy

Structured learning path from "what is a prompt?" to "ship agents to production."

• Getting Started — install, first commit, CI, configuration
• Skills Reference — all members, their tools, and invocation
• Level 1: GenAI & RAG Basics — LLMs, prompt engineering, RAG
• Level 2: AI Agent Essentials — memory, planning, multi-agent systems
• Level 3: Advanced Agent Skills — integration, performance, deployment

---

References

• Conventional Commits
• addyosmani/agent-skills
• groq-sdk — default free LLM provider
• semantic-release
• commitlint

---

Open source. No sign-up. Works with any agent runtime. Membership is free. Standards are not.