Skip to main content

Working with Agents

Green Goods is built with AI agents as a daily practice, not an experiment. The maintainers develop with Claude Code and Codex, agents review every pull request, and the repository is deliberately shaped so that an agent, or a person pairing with one, can work here safely. This page is the high-level map; the pages below it are the machinery.

The contract​

Everything starts with AGENTS.md: the repo-level contract that maps the monorepo, names the invariants, and defines how validation and publication work. Every package carries its own AGENTS.md with the rules that actually bite there. Agents read these before touching a package, and so should you; they encode what the team will assume you know.

Three design choices make agent-assisted work trustworthy here:

  • Generated truth. Deployment tables, the data model, the skills catalog, and other volatile facts are projected from code with digest gates, so neither humans nor agents can let them drift silently.
  • Selected validation. bun run check --plan -- --intent qa picks the smallest honest check set for a change, and the push gate runs it again before anything leaves the machine.
  • No shortcuts for anyone. Agent-made changes pass the same CI Gate, the same review bots, and the same repo rules as human-made ones.

Start your agent​

Copy the onboarding procedure embedded in First Contribution into your agent. It checks your setup against the team's, picks the right path, and ends with a short report naming which package owns your first task.

What's on this section​

  • Skills: the catalog of packaged workflows an agent can invoke by name, from repo audits to QA triage, generated from the skill folders themselves.
  • Task Routing: which workflow owns which kind of task, with each one's mutation boundary and handoff.
  • MCP Guide: the project-scoped MCP servers agents may use here, and the safety boundary around them.

Next steps​