Skip to content

AGENTS.md

Latest commit

 

History

History
116 lines (89 loc) · 5.67 KB

AGENTS.md

File metadata and controls

116 lines (89 loc) · 5.67 KB
Raw

Working agreement — js.software

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.

JavaScript/TypeScript application / site (JS Software UI), built with bun.

Invariants (don't break these)

  • Read docs/frontend-conventions.md before opening implementation files. It is the frontend working agreement: SolidJS/@pathscale/ui conventions, and a context-efficient workflow. Reading it first keeps context small and avoids re-deriving patterns that already exist.
  • bun run typecheck must pass. It is the type gate for this repo; a build succeeding is not the same as types being sound.
  • bun is the package manager — its lockfile is authoritative. Don't introduce a second one by running npm/yarn/pnpm here.
  • Docs describe what is true now. If you change behaviour, update the README and any affected doc in the same change.

Build & run

bun install
bun run dev
bun run build
bun run typecheck
bun run lint

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.

PR discipline

Always paste the full PR URL (https://github.com/pathscale/js.software/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.
  • Never create merge commits — this is a hard ban. Not locally, not to refresh a branch, not to land a pull request. If your branch has fallen behind, rebase it onto the moved base (git rebase origin/master, then --force-with-lease). git merge master into a feature branch is not an acceptable shortcut: it adds a commit whose only content is the fact that you were behind, and it turns a readable line of work into a diamond. Merge commits are disabled server-side on these repositories — that is a backstop, not a licence to rely on it.
  • Rebase is the default everywhere — refreshing a branch, and landing a pull request. Individual commits carry information: what was tried, in what order, and why. A rebase merge keeps that granularity on the base branch, so write commits worth keeping and land them intact.
  • Squash is acceptable where it genuinely makes things easier or is the more appropriate shape for the branch — one logical change scattered across fixup commits, or a long branch whose intermediate states aren't worth preserving. It is a judgement call, not a violation. Merging is the only thing that is never allowed.

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.