webnet/AGENTS.md

Agent instructions

Guidelines for AI agents (Claude Code, etc.) working in this repository.

CLAUDE.md is a symlink to AGENTS.md: they are the same file, so edit either one and never both — and don't be surprised if only one of them shows up in a listing or diff.

Project structure

• This is an npm workspace repository. The root package.json is the workspace manifest, packages/* contains the workspace packages, and package-lock.json is the lockfile.
• Use npm commands (npm ci, npm install, and npm run ... --workspace=packages/<name>). There is no pnpm-workspace.yaml; do not treat this as a pnpm repository.
• Turbo is used as the task runner behind several root scripts (build, test, typecheck, and related commands). Its presence does not change the package manager or workspace layout.
• tailscale/ is a git submodule containing the forked Tailscale source used by packages/tsconnect; it is not another npm workspace.

Model attribution

Before creating commits, PRs, reviews, or applying Agent/* labels, use the exact model currently running — not merely its generic model family.

Prefer model information supplied directly by the harness or system prompt. If the exact model is not exposed there and the session is running under Codex CLI, use $CODEX_THREAD_ID to locate the corresponding rollout file under ~/.codex/sessions/ and read model from its latest turn_context record.

Use the model's established display name for commit attribution. For PRs, apply the corresponding established org-level Agent/* label; label granularity may differ by model lineup. Do not guess the model or reuse model information remembered from another session.

Pull requests

• Open PRs with the tea CLI (tea pr create).
• Always prefix PR titles with WIP: when opening them.
• Always base PRs against origin/main: fetch and pull origin/main before branching unless a different base is specified.
• Keep the PR description up to date: update it after each push to reflect the current state of the branch, not just the initial intent.
• Before committing, run linting, formatting, and typechecking scoped to the affected packages or files where practical.
• Apply the org-level Agentic label and the appropriate established org-level Agent/* label (e.g. Agent/Opus, Agent/Sonnet, Agent/Haiku for the Claude lineup) to every PR or issue you open. These labels already exist at the organisation level — do not create repo-level duplicates. The Agent/* labels are exclusive (only one may be set at a time). The org-level Human label identifies work opened by a human; do not apply it to work opened by an agent. Use tea api (the tea label flags are unreliable): look up the label IDs with tea api orgs/webnet/labels, then apply them with tea api repos/{owner}/{repo}/issues/<number>/labels -d '{"labels":[<id1>,<id2>]}'.
• After pushing to the PR branch or opening the PR, watch the CI results (e.g. via the tea CLI or available harness tools) and address any errors before proceeding.
• When the PR work appears complete (typically after push and CI passes): if the harness provides a tool for spawning a new thread or agent, spawn an autonomous code review using a medium-size model (e.g. Sonnet for the Claude lineup). Watch the review output and address findings as appropriate.
• When everything has settled, or if you need the user to unblock you: if the harness or other instructions provide a push notification tool, send the user a push notification with a short summary; include the full details in the main conversation thread.
• When asked to finalise a PR: run all relevant tests and scoped checks as appropriate; rely on CI for global linting, formatting, and typechecking; ensure the AI disclosure in AI_CHANGES.md and the PR description are up to date; then remove the WIP: prefix from the PR title to mark it ready for merging.
• Reading tea mergeability output:
  • tea reports mergeable: false not only for git-level conflicts but also whenever the WIP: prefix is present, since that blocks merging in the web UI. Only treat mergeable as meaningful during finalisation, after the prefix has been removed.
  • tea output includes a section header listing conflicting files; the header itself is always printed. Its mere presence does not mean there are conflicts — actual conflicting files are listed under it, if any.
• Auto-finalise the PR (without waiting to be asked) if you are confident the user will not request changes — for example, if the work is trivial, mechanical, or was fully specified upfront with no ambiguity. In that case, run the finalise steps above immediately after CI passes and the review is clean.

Reviewing pull requests

• Always use the tea CLI to read PR details and post comments — use tea pr subcommands, not gh.
• If the user asked for an interactive review: pause after gathering initial findings and validate key assumptions or ambiguous judgements with the user before writing up conclusions.
• If the user asked for an autonomous review: post the review feedback directly on the PR (e.g. tea pr review) without stopping to ask — do not just report findings back in the conversation.

Commits

• Always include a Co-Authored-By trailer in every commit message for work assisted or authored by an AI agent, using the actual model that did the work:

  Co-Authored-By: <Model Name> <noreply@provider.example>
  

  For example: Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> or Co-Authored-By: GPT-5.5 <noreply@openai.com>. Do not hardcode a model name — use whichever model is actually running.

Worktrees

• When working inside a git worktree, always work on a feature branch — never commit directly to webnet or main unless explicitly directed.
• The repository has a tailscale submodule. If you need to read or edit it while in a worktree, initialize and use the copy inside the worktree (git submodule update --init from the worktree root), not the one in the main repo checkout. Work on the main repo's submodule may be ongoing and must not be disturbed.

Coding style

Follow the existing style of the codebase. Use packages/http as the primary reference: no comments unless the reason is non-obvious, no unnecessary abstractions, no speculative error handling, no trailing summaries in commit messages or PR descriptions.

Dependencies

Do not add new dependencies without first asking the user, unless the intent to do so is unambiguously implied by the task (e.g. initialising a React app, adding a Postgres client when the task is explicitly about connecting to Postgres). When in doubt, ask.

AI disclosure

AI_CHANGES.md contains the full AI disclosure log and must be kept up to date. README.md links to it but does not contain the disclosure itself. At the end of every branch, review the commits (e.g. git log main..HEAD --oneline) and append entries to AI_CHANGES.md for any new work that was assisted or authored by an AI agent.