sandbox-factory
AGENTS.md4 starsChanged 43 days agoMITView on GitHub
Read CONVENTIONS.local.md first when it exists. Open it by name: it is gitignored and takes precedence where it overlaps these instructions. Use docs/README.md to find the relevant feature and source; read only the sections needed for the task. Product proposals are not evidence that a feature is implemented. The repository is lunox-work/sandbox-factory; feversoul is the maintainer's personal account. Repository URLs take the organization. Use Node matching package.json (^22.12.0 || >=24) and npm ci for setup. Run npm run verify before…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repositoryOne other file it gives its agents.
- graphifySkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
17 rules. About 1 is common, 4 are distinctive, and 12 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
12
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 5
Read CONVENTIONS.local.md first when it exists.
- Distinctive: line 7
Use docs/README.md to find the relevant feature and source.
- Very specific: line 16
Use Node matching package.json (^22.12.0 || >=24) and npm ci for setup.
- Very specific: line 17
Run npm run verify before declaring done: lint, format check, build and tests, in CI's order.
- Very specific: line 22
Run npm run test:e2e after changing sign-in gating, workspace switching or bounty creation in apps/web or their API routes.
- Distinctive: line 28
Read development.md before changing tests, Makefile, Docker or dev scripts.
- Very specific: line 38
Keep its types: []. Only apps/extension may import vscode.
- Common: line 55
Read the relevant architecture section before changing ownership, auth, bounties, integration credentials or sandbox flows.
- Distinctive: line 62
Follow the workspace's existing import extensions.
- Very specific: line 64
Test behavior changes in the same change.
- Very specific: line 69
Read versioning.md before changing build provenance.
- Very specific: line 70
Keep scripts/build-info.mjs as the sole resolver, its .d.mts types, web's virtual:build-info, Turbo's declared build env and both CI …
- Very specific: line 80
Keep secrets out of files committed to git and out of output.
- Very specific: line 88
Commit, push, open a PR, merge, tag or deploy only when the user requests it.
- Very specific: line 102
Read ci.md before editing workflows.
- Distinctive: line 105
Never automatically resolve review threads, dismiss reviews, post approval overrides, fabricate passing statuses or use admin bypass to …
- Very specific: line 114
Read docs/README.md inside that installed package first, then read the relevant pages from its docs/ directory before changing Turborepo …
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
Start here
Read CONVENTIONS.local.md first when it exists. Open it by name: it is
gitignored and takes precedence where it overlaps these instructions.
Use docs/README.md to find the relevant feature and source;
read only the sections needed for the task. Product proposals are not evidence
that a feature is implemented.
The repository is lunox-work/sandbox-factory; feversoul is the maintainer's
personal account. Repository URLs take the organization.
Setup and verification
Use Node matching package.json (^22.12.0 || >=24) and npm ci for setup.
Run npm run verify before declaring done: lint, format check, build and tests,
in CI's order. Never bypass a failing pre-push hook with --no-verify.
During iteration, use npx turbo run lint test --filter=<workspace-name>.
Workspace names and entry points are in the index.
Run npm run test:e2e after changing sign-in gating, workspace switching or
bounty creation in apps/web or their API routes; CI requires it. The
graphify, archify and diagram-design skills are optional navigation and
diagram aids, installed per clone with scripts/install-agent-tools.sh; see
development.md.
Read development.md before changing tests, Makefile, Docker or dev scripts. It preserves the setup and testing constraints.
Architecture and access
- Apps never import each other; shared logic belongs in packages.
npm run lint:depsenforces the import rules in this section. packages/coreowns domain rules. Its one dependency is carveout's purecarveout/pseudonymsentry (notypescript, nonode:*), pinned exactly.packages/clientusesfetchonly: nonode:*,vscodeor@types/node. Keep itstypes: []. Onlyapps/extensionmay importvscode.- Auth table constants stay singular (
user), column properties camelCase (emailVerified). Better Auth resolves names at runtime. Keep all fifteen tables inauthSchema; seepackages/db/test/auth-schema.test.ts. - Handle validation lives in
packages/core/src/handle.ts; do not duplicate its length or character rules in schemas, stores or forms. - Organization routes take the owner from the path after
requireMembership, neversession.activeOrganizationIdor a request body. Every owner-scoped store method takes the organization first and includes it in itsWHERE. Another owner's resource and non-membership return 404, not 403. - Store methods do not branch on
organization.kind. Personal and team organizations share the path;refusePersonalinapps/api/src/auth.tsguards personal-organization deletion and membership changes. - Email/password sign-in stays off.
createAppwithout auth serves 503 under/api/*;/api/v1is credential-guarded. Routes outside it need deliberate access rules. API tokens reach only routes inapps/api/src/public-api/registry.ts; adding a route there makes it public. The API requiresDATABASE_URL; in-memory stores are test doubles. - Read the relevant architecture section before changing ownership, auth, bounties, integration credentials or sandbox flows.
Implementation
- Extend
tooling/tsconfig; do not copy compiler options. Useimport type, preserve strictness and narrow possibly undefined values rather than using!. Follow the workspace's existing import extensions; see TypeScript configuration. - Test behavior changes in the same change. Keep the existing runners and
coverage thresholds; see testing.
npm run verifymust remain usable with Docker stopped. - Generate migrations with
npm run db:generate --workspace @sandbox-factory/db; never hand-editpackages/db/drizzle/.dist/anddist-test/are generated. - Read versioning.md before changing build provenance.
Keep
scripts/build-info.mjsas the sole resolver, its.d.mtstypes, web'svirtual:build-info, Turbo's declared build env and both CI provenance checks. APIBUILD_*values remain optional. Docker build args needed in two stages must be declared in both. - Dev containers
api-devandweb-devmust each shadow every workspace'snode_modules;workercopies the read-only checkout and installs its own.make uprefreshes them after lockfile changes;make relinkis the manual repair. Never usedown -vfor dependency repair: it deletes database and object-storage volumes. - Dependabot handles routine dependency bumps. Explain any added dependency and its workspace in the PR; keep core free of any other dependency.
- Keep secrets out of files committed to git and out of output. When editing
.env.example, align.env.developmentand.env.productionin the same task: matching line counts, key positions, comments, headers and blank lines. New keys get empty values and retain the example's commented/active state; preserve existing values and activation states. SeeCONVENTIONS.local.md.
Shipping
Commit, push, open a PR, merge, tag or deploy only when the user requests it.
For authorized shipping, read scripts/README.md and use
./scripts/ship.sh --title "fix: ..." --yes. It waits for the merge, then
leaves main at the merge and deletes the branch; exit 0 means merged, not
deployed. On exit 3, fix the blocker on the branch and re-run with --branch
until it merges, then report the PR URL. Keep one logical change per fix/...
or feat/... branch and fill in the PR template.
- Ready same-repository PRs auto-merge on required checks, except Dependabot majors. CodeRabbit and unresolved review threads are advisory. Use a draft to hold a PR for inspection; policy changes follow the same pipeline.
- The Conventional Commit PR title becomes the squash commit and controls the
release. Tags are the version of record; never hand-edit
CHANGELOG.md. See CI and releases for version rules and required check names. - Read ci.md before editing workflows. Never execute PR code in
a privileged
pull_request_targetworkflow or weaken permissions. Change required check names and branch protection together. - Never automatically resolve review threads, dismiss reviews, post approval overrides, fabricate passing statuses or use admin bypass to ship.
<!-- BEGIN:turborepo-agent-rules -->This is NOT the Turborepo you know
Turborepo configuration, task behavior, and CLI commands can vary between installed versions and may differ from your training data. Resolve the turbo package from this file's directory or relevant workspace; in monorepos, it may not be visible from the repository root. For example, run node -p "require.resolve('turbo/package.json')" from a workspace that depends on turbo.
Read docs/README.md inside that installed package first, then read the relevant pages from its docs/ directory before changing Turborepo configuration or commands. Heed deprecation notices. These bundled docs match the installed package version and are available without network access.
This block is written and re-added by turbo before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in crates/turborepo-cli/src/cli/agent_guidance.rs. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set "agentGuidance": false in the root turbo.json or turbo.jsonc to opt out; this does not remove an existing block. Keep the block committed with your work to avoid an uncommitted change on the next agent invocation.
<!-- END:turborepo-agent-rules -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

