paw — Personal Agent Workforce

What paw is

A lightweight, composable toolkit that gives your AI coding agent standards enforcement, specialized reviewers, and domain knowledge. Every piece works standalone.

How to work in this repo

Composability is the design

Every directory runs independently. Agents work without skills. Hooks work without agents. Rules are plain markdown anyone can read. Don't add cross-directory dependencies.

Agents have scoped permissions

Most agents are read-only. Only 4 of 18 agents have full access (builder, merge-resolver, migration-architect, incident-commander). This is intentional — trust through bounded autonomy.

Rules are the source of truth

If a rule in rules/ contradicts how an agent behaves, fix the agent. Rules don't bend to implementation convenience.

Tests before code

The builder agent writes failing tests first, then implementation. The test-runner agent verifies. The auto_test_detect hook warns on missing tests.

Git rules

• Always git pull (merge, not rebase) before push
• Never git rebase against published history
• Never git push --force to any branch
• Never commit to main directly — use a feature branch
• Always verify git branch shows the intended branch before committing

These are enforced by hooks/git_safety.py and hooks/branch_guard.py.

Adding an agent

1. Pick the context it loads from contexts/.
2. Pick the rules it references from rules/.
3. Define minimum tools — least privilege.
4. Write the role, process, outputs, done-when.
5. Add to agents/README.md.

Load contexts/X in an agent file is a prompt directive, not a mechanical import. The AI tool reads the line and opens the file itself. This works in Claude Code, where agent files are loaded into context and the agent can read the repo. In other tools, you may need to paste or otherwise include the referenced context and rule files manually.

Adding a rule

1. Write the statement, why, hard rules, soft rules.
2. Identify which agents/hooks enforce it.
3. Update relevant agents to reference the new rule.
4. Add to rules/README.md.

Known limitations

Be honest about these when documenting or extending paw.

Prompt-directed, not mechanically dispatched. Context and skill loading (Load contexts/X, rules/Y.md) is a directive the AI tool follows by reading the file. Nothing dispatches or validates it. A typo'd path degrades silently rather than erroring.

Agent tool restrictions are not sandboxed. The tools: frontmatter field is an instruction, not a runtime boundary. See agents/README.md.

Quality gates need the agent files to be discoverable. paw check and the /quality-check prompt work by asking the AI tool to invoke agents by name. If the tool cannot see agents/, the gate silently does less than it claims. Verify with paw doctor.

.paw.json history logging is not implemented. paw init scaffolds a history block pointing at .paw/history.jsonl, and the README documents it, but nothing writes that file yet.

Protocol dependencies on Claude Code

paw's hooks and agents are portable in spirit but currently bind to Claude Code specifics:

• Hooks read a JSON payload on stdin and write a JSON response on stdout, following Claude Code's hook protocol. Another tool with a different hook contract needs an adapter, not just a path change.
• hooks/install_hooks.py assumes the ~/.claude/settings.json layout — specifically a top-level hooks object keyed by event name. It edits that file in place.
• Agent model: frontmatter uses Claude model aliases (opus, sonnet). These mean nothing to a non-Claude runner.