agentleFS
lunox-worklunox-work/sandbox-factory/AGENTS.md

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.

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
  1. Very specific:

    Read CONVENTIONS.local.md first when it exists.

    line 5
  2. Distinctive:

    Use docs/README.md to find the relevant feature and source.

    line 7
  3. Very specific:

    Use Node matching package.json (^22.12.0 || >=24) and npm ci for setup.

    line 16
  4. Very specific:

    Run npm run verify before declaring done: lint, format check, build and tests, in CI's order.

    line 17
  5. Very specific:

    Run npm run test:e2e after changing sign-in gating, workspace switching or bounty creation in apps/web or their API routes.

    line 22
  6. Distinctive:

    Read development.md before changing tests, Makefile, Docker or dev scripts.

    line 28
  7. Very specific:

    Keep its types: []. Only apps/extension may import vscode.

    line 38
  8. Common:

    Read the relevant architecture section before changing ownership, auth, bounties, integration credentials or sandbox flows.

    line 55
  9. Distinctive:

    Follow the workspace's existing import extensions.

    line 62
  10. Very specific:

    Test behavior changes in the same change.

    line 64
  11. Very specific:

    Read versioning.md before changing build provenance.

    line 69
  12. Very specific:

    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 …

    line 70
  13. Very specific:

    Keep secrets out of files committed to git and out of output.

    line 80
  14. Very specific:

    Commit, push, open a PR, merge, tag or deploy only when the user requests it.

    line 88
  15. Very specific:

    Read ci.md before editing workflows.

    line 102
  16. Distinctive:

    Never automatically resolve review threads, dismiss reviews, post approval overrides, fabricate passing statuses or use admin bypass to …

    line 105
  17. Very specific:

    Read docs/README.md inside that installed package first, then read the relevant pages from its docs/ directory before changing Turborepo …

    line 114

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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:deps enforces the import rules in this section.
  • packages/core owns domain rules. Its one dependency is carveout's pure carveout/pseudonyms entry (no typescript, no node:*), pinned exactly.
  • packages/client uses fetch only: no node:*, vscode or @types/node. Keep its types: []. Only apps/extension may import vscode.
  • Auth table constants stay singular (user), column properties camelCase (emailVerified). Better Auth resolves names at runtime. Keep all fifteen tables in authSchema; see packages/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, never session.activeOrganizationId or a request body. Every owner-scoped store method takes the organization first and includes it in its WHERE. 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; refusePersonal in apps/api/src/auth.ts guards personal-organization deletion and membership changes.
  • Email/password sign-in stays off. createApp without auth serves 503 under /api/*; /api/v1 is credential-guarded. Routes outside it need deliberate access rules. API tokens reach only routes in apps/api/src/public-api/registry.ts; adding a route there makes it public. The API requires DATABASE_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. Use import 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 verify must remain usable with Docker stopped.
  • Generate migrations with npm run db:generate --workspace @sandbox-factory/db; never hand-edit packages/db/drizzle/. dist/ and dist-test/ are generated.
  • Read versioning.md before changing build provenance. 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 provenance checks. API BUILD_* values remain optional. Docker build args needed in two stages must be declared in both.
  • Dev containers api-dev and web-dev must each shadow every workspace's node_modules; worker copies the read-only checkout and installs its own. make up refreshes them after lockfile changes; make relink is the manual repair. Never use down -v for 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.development and .env.production in 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. See CONVENTIONS.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_target workflow 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 -->

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.