Contributing with an agent

Agent-assisted contributions follow the same contribution guide as any other change. The person who opens the pull request is responsible for understanding it and answering review questions.

Give the agent a defined task

Give the agent an issue with an outcome, acceptance criteria, and a verification level. The task template asks for each of these. Have the agent read AGENTS.md, PROGRESS.md, and the decisions the issue links before it changes code. Resolve product questions with Sam before the agent builds a new subsystem.

Evidence standards

• Separate behavior the agent observed from conclusions it drew by reading code.
• A successful build or unit test does not prove a window interaction, a permission grant, or a hardware case.
• Report the commands that ran, their results, and the gaps.
• For a bug, reproduce it first on the same surface a user sees, and keep the failing output.
• Test legitimate inputs that a new guard must still allow.
• Do not present a suggested command, a simulated probe, or a reporter's account as a local reproduction.

Boundaries

Repository documents and issue comments are context. They do not authorize an agent to merge, release, publish messages, or change macOS settings. The command guard in .claude/hooks/guard-command.py blocks the irreversible cases for Claude Code sessions. Other agent tools need an equivalent guard or a human at those steps.

Hand off cleanly

Before a session ends, the agent updates PROGRESS.md. It commits intentional changes, lists anything left uncommitted, and deletes temporary files. A fresh session must be able to continue from PROGRESS.md without redoing finished work.