Skip to content

AGENTS.md

Latest commit

 

History

History
103 lines (75 loc) · 5.33 KB

AGENTS.md

File metadata and controls

103 lines (75 loc) · 5.33 KB
Raw

Working agreement — WorkTable

The operating contract for any coding agent working in this repository. This file is the single source of truth for the rules: Codex, Cursor and Gemini CLI read AGENTS.md natively, and Claude Code loads it through the @AGENTS.md import in CLAUDE.md. Never fork these rules into a per-vendor file.

Rust crate (worktable).

Invariants (don't break these)

  • Keep cargo fmt and cargo clippy --workspace --all-targets -- -D warnings clean. Lint failures are part of the build here, not advisory. Note --workspace: without it worktable_codegen is never linted, and note -D warnings, because CI denies what your terminal merely prints.
  • Shell scripts are POSIX sh. #!/bin/sh, and none of [[ ]], arrays, echo -e, process substitution or pipefail. Check with sh -n before committing. Bash is not guaranteed to be the system shell, and a script that only runs on one machine is not a check.
  • Publishing to crates.io is irreversible. A version number can never be reused, and yanking does not delete. Run cargo publish --dry-run first, publish from the merged default branch, and tag the release.
  • Use caret dependency requirements, including our prerelease packages. Name the prerelease explicitly, for example ^1.0.0-beta.19; ^1.0 alone does not opt into prereleases. Do not introduce exact pins. Record resolved versions in release and benchmark evidence.
  • Docs describe what is true now. If you change behaviour, update the README and any affected doc in the same change.

Build & test

cargo build
cargo test
cargo fmt && cargo clippy --workspace --all-targets -- -D warnings

./scripts/ci-local.sh    # everything CI runs, same args, before you push

Verification

Run what you build before reporting it done. Type-checks and tests verify code correctness, not feature correctness — if you can't run it, say so explicitly rather than implying success.

  • Compare against the base branch rather than asserting: a pre-existing failing test or lint error is not something you introduced, and saying so requires checking.
  • A build that finishes suspiciously fast was cached, not rebuilt. Force a real rebuild when the rebuild is the thing you're verifying.
  • ci-local.sh runs your default toolchain; CI runs the newest stable. A clippy lint added between the two is invisible here and fails there, on code nobody touched. The script prints both so a local pass is not mistaken for a CI pass. If they differ and the lint matters, get the toolchain updated rather than pushing to find out.

PR discipline

Always paste the full PR URL (https://github.com/pathscale/WorkTable/pull/<n>), not just the number, so it's clickable.

Keeping docs honest

Hit a factual error here — a stale path, a wrong command, a moved status? Fix it in the same change. Don't open cosmetic rewording PRs.

Learned something durable — a gotcha, a decision, a constraint? It belongs in this repo's docs, not in your agent's private memory. Repo docs are versioned, reviewable, and visible to every agent and human; private memory dies with your machine.

Git workflow

  • Always specify the branch when pushing: git push origin branch-name
  • Branch naming: fix/issue-description or feat/issue-description
  • Force-push your own branch freely. Rebasing a feature branch onto a moved base, or amending before review, is normal and correct — use --force-with-lease so you don't clobber someone else's push.
  • Never force-push the default branch (main/master). That is the history everyone else builds on, and it is protected server-side for a reason.

Guardrails

.claude/settings.json and .claude/hooks/ make Claude Code prompt a human before prod-affecting or destructive commands — pushes, publishing to a registry, gh pr merge, cloud CLIs, recursive deletes, deploy scripts.

Other agents don't get that net automatically. Apply the same rule yourself: ask before running any command family listed in .claude/hooks/ask-before-risky-commands.sh. It is one layer of defence, not a guarantee — a pattern match over a command string is best-effort.

No AI attribution

Never add AI attribution to anything in this repo or leaving it: no "Generated with Claude Code" / robot-emoji footers, no Co-Authored-By: Claude (or any AI) trailers, and no AI credit in commit messages, PR or issue titles/bodies, changelogs, release notes, or code comments. Applies to every agent and every vendor. Work product should be indistinguishable from a human teammate's.