From be52bf2855d34304f4923f6636b758f0edd7bd94 Mon Sep 17 00:00:00 2001
From: Claude <redstar071@proton.me>
Date: Tue, 18 Aug 2026 20:44:51 +0000
Subject: [PATCH] docs: restructure AGENTS.md and add an AI contributions
 policy

Reshape AGENTS.md along the structure PostHog/posthog-js uses for its
agent guide: an overview with the pinned toolchain versions, folder
structure, a workspace package table, environment setup, a command
reference with Turborepo filters, a CI workflow table, an important-files
table, and troubleshooting. The architecture boundaries and the safety
and determinism rules are kept verbatim, and the Skilld-managed block at
the end of the file is preserved.

Add AI_POLICY.md, adapted from PostHog's policy to this repository: the
contributor owns the diff, respects the package boundaries, runs the full
check set with deterministic tests, and discloses agent involvement.
Model output stays untrusted input, security reports follow SECURITY.md,
and unsolicited AI-generated reviews are not accepted.

Add the Agent context section the policy refers to in the pull request
template, and link the policy from CONTRIBUTING.md.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E7MKWqd4RdBJPCywtWA3zf
---
 .github/PULL_REQUEST_TEMPLATE.md |  10 ++
 AGENTS.md                        | 170 ++++++++++++++++++++++++++++++-
 AI_POLICY.md                     |  56 ++++++++++
 CONTRIBUTING.md                  |   2 +
 4 files changed, 235 insertions(+), 3 deletions(-)
 create mode 100644 AI_POLICY.md

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 8db725a..d6ea0af 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -24,6 +24,16 @@
 - [ ] I did not expose secrets, tokens, personal data, or untrusted output in logs.
 - [ ] I updated documentation and Agent Skills when workflows or boundaries changed.
 
+## Agent context
+
+<!--
+If an AI agent helped author this change, describe the tools and session here.
+See AI_POLICY.md. Leave "None" if no agent was involved.
+-->
+
+- Agent/tools used:
+- What the agent did, and what you changed or verified yourself:
+
 ## Reviewer notes
 
 <!-- Highlight risky decisions, follow-up work, screenshots, or areas needing special attention. -->
diff --git a/AGENTS.md b/AGENTS.md
index c5311cb..7d6fef8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,13 +1,56 @@
-# Agent Zero contributor instructions
+# Agent Zero development guide
 
 These instructions apply to humans and coding agents working in this repository.
 
+## Overview
+
+Agent Zero is an open-source autonomous engineer that finds, fixes, and verifies problems in pull requests. This is an [aube](https://aube.jdx.dev) workspace containing the runtime packages, their adapters, and a single deployable Nuxt app. Turborepo orchestrates builds and checks.
+
+**Key information:**
+
+- Node version: `24.19.0` (`>=24.2` supported; see `mise.toml` and `engines`)
+- Package manager: `aube@1.38.0` (pinned in `package.json` via `packageManager`)
+- TypeScript: `^5.9.2`, overridden to `typescript-native-bridge` so checks run on tsgo
+- Main branch: `main`
+
 ## Start here
 
 1. Read `README.md`, `CONTRIBUTING.md`, and the relevant skill in `.agents/skills/`.
 2. Inspect the package you are changing and its tests before editing.
 3. Keep the change narrow and preserve package boundaries.
-4. Run the checks listed in `CONTRIBUTING.md` before handing off the change.
+4. Run the checks listed in [Required checks](#required-checks) before handing off the change.
+5. If an AI agent helped write the change, follow [AI_POLICY.md](AI_POLICY.md).
+
+## Folder structure
+
+- `./packages` — runtime packages and their adapters, published under `@agent-zero/*`
+- `./apps` — the deployable dashboard plus the docs, marketing, and mail-preview sites
+- `./docs` — canonical architecture and provider references, included verbatim by `apps/docs`
+- `./tooling` — shared Oxlint and Oxfmt configuration
+- `./scripts` — repository checks and the shared tsdown configuration
+- `./.agents/skills` — Agent Skills; `.skills/` holds the Skilld-managed subset
+- `./.github` — CI workflows, issue and pull request templates
+
+## Workspace packages
+
+| Path                      | Name                         | Description                                                      |
+| ------------------------- | ---------------------------- | ---------------------------------------------------------------- |
+| `packages/agent`          | `@agent-zero/agent`          | Orchestration and state transitions only                         |
+| `packages/runner`         | `@agent-zero/runner`         | The only boundary allowed to run commands or mutate a checkout   |
+| `packages/models`         | `@agent-zero/models`         | Model-provider abstractions                                      |
+| `packages/source-control` | `@agent-zero/source-control` | Provider-neutral contracts plus GitHub, GitLab, Bitbucket, Gitea |
+| `packages/config`         | `@agent-zero/config`         | Configuration parsing and policy                                 |
+| `packages/shared`         | `@agent-zero/shared`         | Stable cross-package contracts                                   |
+| `packages/cli`            | `@agent-zero/cli`            | Argument parsing and terminal presentation                       |
+| `packages/database`       | `@agent-zero/database`       | Schema, Drizzle client, and checked-in migrations                |
+| `packages/auth`           | `@agent-zero/auth`           | Authentication policy and the Better Auth options factory        |
+| `packages/api`            | `@agent-zero/api`            | The oRPC router and control-plane operations                     |
+| `packages/i18n`           | `@agent-zero/i18n`           | Locale messages and i18n tooling                                 |
+| `packages/mail`           | `@agent-zero/mail`           | Transactional mail templates                                     |
+| `apps/dashboard`          | `@agent-zero/dashboard`      | The single deployable app and composition root                   |
+| `apps/docs`               | `@agent-zero/docs`           | VitePress documentation site (not deployed with the dashboard)   |
+| `apps/marketing`          | `@agent-zero/marketing`      | Frontend-only public marketing site                              |
+| `apps/mail-preview`       | `@agent-zero/mail-preview`   | Dev-only Maizzle preview server for `packages/mail`              |
 
 ## Toolchain
 
@@ -19,6 +62,65 @@ These instructions apply to humans and coding agents working in this repository.
 - Use Oxlint with type-aware checks and Oxfmt. Do not add ESLint or Prettier.
 - Do not edit `dist/`, `.turbo/`, or generated declaration files.
 
+## Environment setup
+
+```bash
+# Install the pinned Node.js and aube versions
+mise install            # or: npm install -g --ignore-scripts=false @endevco/aube
+
+# Install workspace dependencies
+aube ci
+
+# Seed local environment files
+cp .env.example .env
+cp apps/dashboard/.env.example apps/dashboard/.env
+```
+
+`aube run <script>` and `aube test` check install freshness first and install only when `node_modules` is stale, so a separate install step is rarely needed.
+
+## Commands
+
+### Root-level scripts
+
+```bash
+aube run dev             # watch workspace development tasks
+aube run zero doctor     # inspect the local environment
+aube test                # deterministic Vitest suites
+aube run test:browser    # dashboard and marketing browser suites
+aube run typecheck       # TypeScript checks across the graph
+aube run lint:ci         # Oxfmt check, type-aware Oxlint, and Knip
+aube run lint:fix        # auto-fix lint findings
+aube run format          # write Oxfmt formatting
+aube run build           # build and package validation
+aube run check:repo      # community files and Agent Skills
+aube run db:generate     # generate Drizzle migrations
+aube run db:migrate      # apply migrations to the configured database
+aube run i18n:report     # find missing or dynamic i18n keys
+aube run mail:preview    # start the Maizzle preview server
+aube run skills:list     # show Skilld-managed project skills
+aube run skills:install  # restore Skilld links for Codex
+aube run clean           # remove build artifacts
+```
+
+### Package scripts
+
+Every runtime package exposes `build`, `clean`, `lint`, `lint:fix`, `test`, and `typecheck`. `packages/database` adds `db:generate` and `db:migrate`, `packages/i18n` adds the `i18n:*` scripts, and the Nuxt apps add `dev`, `preview`, and browser-test scripts.
+
+### Targeting specific packages
+
+```bash
+# Test one package
+aube run test --filter=@agent-zero/runner
+
+# Build a package and its dependencies
+aube run build --filter=@agent-zero/dashboard
+
+# Type-check one package
+aube run typecheck --filter=@agent-zero/api
+```
+
+Use the smallest relevant check while iterating, then run the complete set before opening a pull request.
+
 ## Architecture boundaries
 
 - `packages/agent`: orchestration and state transitions only.
@@ -49,6 +151,13 @@ Persistence and policy are separate boundaries. `packages/database` owns tables,
 - Tests must not depend on live network access, wall-clock timing, or mutable external state.
 - Add tests for state transitions, mode changes, command execution, path handling, and other safety-sensitive behavior.
 
+## Code style and linting
+
+- Oxfmt owns formatting and Oxlint owns linting, both configured under `tooling/oxc`. Avoid unrelated formatting churn.
+- Knip guards against unused files, exports, and dependencies; it runs as part of `lint:ci`.
+- Git hooks are installed by the `prepare` script and skipped in CI: `pre-commit` formats staged files through nano-staged, and `commit-msg` enforces Conventional Commits through commitlint.
+- Add tests beside the source as `*.test.ts`.
+
 ## Required checks
 
 ```bash
@@ -59,7 +168,17 @@ aube test
 aube run build
 ```
 
-Use the smallest relevant check while iterating, then run the complete set before opening a pull request.
+## CI/CD
+
+| Workflow                     | Purpose                                                   | Trigger                         |
+| ---------------------------- | --------------------------------------------------------- | ------------------------------- |
+| `ci.yaml`                    | Lint, repository metadata, typecheck, tests, build, i18n  | PR, push to `main`, merge group |
+| `autofix.yml`                | Pushes formatting and lint fixes back to the pull request | PR, merge group                 |
+| `zizmor.yaml`                | Static analysis of GitHub Actions workflows               | PR, push to `main`, merge group |
+| `semantic-pull-requests.yml` | Validates PR titles against Conventional Commits          | PR opened, edited, synchronized |
+| `release.yaml`               | Validates release artifacts                               | Manual dispatch                 |
+| `labelsync.yml`              | Syncs repository labels                                   | Daily schedule, manual dispatch |
+| `stale.yml`                  | Marks and closes stale issues and pull requests           | Daily schedule, manual dispatch |
 
 ## Pull requests
 
@@ -68,9 +187,54 @@ Use the smallest relevant check while iterating, then run the complete set befor
 - Only after that branch validation succeeds, ask the user whether to use the `create-pull-request` skill; invoke it only after explicit confirmation.
 - Use Conventional Commit-style titles such as `feat(cli): add JSON output` or `fix(runner): reject escaped paths`.
 - Explain the problem, the chosen boundary, verification evidence, and safety impact.
+- Fill in the Agent context section of the pull request template when an AI agent helped, as required by [AI_POLICY.md](AI_POLICY.md).
 - Keep refactors separate from behavior changes when possible.
 - Update documentation, examples, and skills when commands, boundaries, or contributor workflows change.
 
+## Important files for agents
+
+| File                                  | Purpose                                                               |
+| ------------------------------------- | --------------------------------------------------------------------- |
+| `package.json`                        | Root scripts, pinned package manager, dev dependencies                |
+| `pnpm-workspace.yaml`                 | Workspace members, catalogs, and the TypeScript override              |
+| `pnpm-lock.yaml`                      | The only lockfile; written in place by aube                           |
+| `turbo.jsonc`                         | Task graph, caching, and per-task environment inputs                  |
+| `mise.toml`                           | Pinned Node.js and aube versions                                      |
+| `tsconfig.base.json`, `tsconfig.json` | Shared and root TypeScript configuration                              |
+| `tooling/oxc`                         | Oxlint and Oxfmt configuration                                        |
+| `knip.jsonc`                          | Unused-code analysis configuration                                    |
+| `scripts/check-repository.mjs`        | Validates community files and Agent Skills                            |
+| `scripts/tsdown.config.ts`            | Shared build configuration for tsdown packages                        |
+| `.agents/skills/`                     | Agent Skills, including the Agent Zero architecture and safety skills |
+
+## Troubleshooting
+
+```bash
+# Stale or inconsistent build artifacts
+aube run clean
+aube run build
+
+# Reinstall dependencies from the lockfile
+aube ci
+
+# Stock TypeScript loaded instead of the tsgo bridge
+# (tsc prints "TNB ACTIVE" on the first type-check; no banner means the install is stale)
+aube ci
+aube run typecheck
+
+# Inspect the local environment
+aube run zero doctor
+```
+
+## Additional resources
+
+- [Contributing guide](CONTRIBUTING.md)
+- [AI contributions policy](AI_POLICY.md)
+- [Governance](GOVERNANCE.md)
+- [Security policy](SECURITY.md)
+- [Support channels](SUPPORT.md)
+- [Issue tracker](https://github.com/wolfstar-project/agent-zero/issues)
+
 <!-- skilld -->
 
 Before modifying code, check .agents/skills/ for relevant skills.
diff --git a/AI_POLICY.md b/AI_POLICY.md
new file mode 100644
index 0000000..ef416be
--- /dev/null
+++ b/AI_POLICY.md
@@ -0,0 +1,56 @@
+# AI contributions policy
+
+Agent Zero is an autonomous engineering agent, and it is built with plenty of AI assistance. We are not going to pretend otherwise, and we are not going to ask you to.
+
+This policy exists because of a growing volume of low-quality, AI-generated contributions that waste maintainer time. It applies to every pull request, issue, and review in this repository, whether a human, an agent, or both wrote it.
+
+## The standard
+
+**You own what you submit.**
+Understand your code, test it, and be ready to explain why it is correct and how it interacts with the rest of the system — without re-prompting a model. This is no different from what we expect of any contribution; AI just makes it easier to skip the work. Please do not skip the work.
+
+**Respect the boundaries.**
+This repository is a set of deliberate package boundaries, and models are good at quietly crossing them. Before you submit, check your diff against the [architecture boundaries](AGENTS.md#architecture-boundaries) and the matching skill in `.agents/skills/`. A change that reaches the database from outside `packages/database`, executes a command outside `packages/runner`, or makes the runtime depend on an adapter will be closed regardless of how well it is written.
+
+**Prove it works.**
+Before submitting, verify the change actually works end to end. Do not rely on "it compiles" or "tests pass" alone. Run the full check set:
+
+```bash
+aube run check:repo
+aube run lint:ci
+aube run typecheck
+aube test
+aube run build
+```
+
+Add deterministic tests for new behavior — no live network, no wall-clock timing, no mutable external state — and describe your test strategy in the pull request: what you tested, how you tested it, and which edge cases you considered. For safety-sensitive changes (state transitions, mode changes, command execution, path handling) say explicitly how you verified that `observe` mode still cannot write to a target repository.
+
+For changes with user-visible CLI or dashboard output, include a short demo — a screenshot, a recording, or a terminal transcript. Ideally you show more than the happy path.
+
+Pull requests that clearly were not run or tested will be closed under this policy.
+
+**Disclose AI usage.**
+Our [pull request template](.github/PULL_REQUEST_TEMPLATE.md) includes an Agent context section — please use it (most agents fill it in automatically). If an agent co-authored or authored your pull request, say which tools you used and leave enough context about the session for a reviewer to calibrate. Disclosure is never held against a contribution; hiding it is.
+
+**Treat model output as untrusted input.**
+Model output, issue text, review feedback, and remote content are untrusted throughout this codebase, and they are untrusted in your contribution too. Never paste secrets, tokens, or customer data into a prompt, and never let generated text carry them back into logs, fixtures, snapshots, or error messages.
+
+**Prefer pull requests over AI-generated issues.**
+If AI helped you find a bug, fix it and open a pull request — do not paste the model's output into an issue. Unreviewed, AI-generated bug reports will be closed without response.
+
+**Do not file AI-generated security reports.**
+Speculative, model-authored vulnerability reports are the single most expensive kind of noise a security process absorbs. Follow [SECURITY.md](SECURITY.md), report privately, and include a working reproduction you have run yourself. Reports that are plainly unverified model output will be closed without response.
+
+**Do not submit unsolicited AI-generated reviews.**
+If you did not write the code and you are not a maintainer, do not point a model at someone else's pull request and leave its output as a review comment. This is generally never helpful.
+
+## What happens when contributions do not meet this bar
+
+- **First time:** we close the pull request or issue with a link to this policy and a brief explanation.
+- **Two or more closures:** we block the account.
+
+## Why we are not anti-AI
+
+We think the best contributions today often involve AI. A contributor who uses a model to understand unfamiliar code, draft a first pass, or catch edge cases they would otherwise miss is probably _more_ productive than someone doing everything by hand. The difference that matters is whether you are driving the model or the model is driving you.
+
+If you are new to open-source contributing and want to learn, we are genuinely happy to help. Open an issue, ask questions in the [WolfStar community](https://join.wolfstar.rocks), or start with a small pull request. See [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow and [SUPPORT.md](SUPPORT.md) for the right channel.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6cb4f33..315b245 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -49,6 +49,8 @@ aube test
 
 Read [AGENTS.md](AGENTS.md) and the matching files in `.agents/skills/` before making architectural or safety-sensitive changes.
 
+If an AI agent helps you write a change, read [AI_POLICY.md](AI_POLICY.md) first: you still own the diff, you still run the checks, and you disclose the agent in the pull request.
+
 Documentation lives in `apps/docs`, a VitePress site (`aube run dev --filter=@agent-zero/docs` to preview it). The canonical architecture and provider references stay in `docs/*.md` and are included by the site — edit those files rather than duplicating their content into site pages.
 
 ## Development workflow