Skip to content

AGENTS.md

Latest commit

 

History

History
83 lines (64 loc) · 3.84 KB

AGENTS.md

File metadata and controls

83 lines (64 loc) · 3.84 KB
Raw

AGENTS.md

Principles: the contracts that stay true while implementations churn. For how to run, boot, share, or navigate things today, see RUNNING.md; for e2e scenarios, e2e/AGENTS.md. Run bun run bootstrap first in any fresh checkout or worktree.

Task Completion

  • Tests use Effect Vitest. Run scoped tests with vitest run .... bun run test is fine (it delegates to Vitest); NEVER run bun test.
  • Run the narrowest useful verification for a change. For broad or merge-ready work the full gates are bun run format:check, lint, typecheck, test.
  • Run bun run format before opening a PR, staging only files your branch touched (leave unrelated files format rewrites out of the PR).

Handing Back Work: Evidence, Not Assertions

"Done" is something the user can open, not a claim. When work changes what a user sees, hand back: an e2e run that proves it (link the specific run with one line on what to look at, not a wall of green), the dev server left running so they can poke at it, and the paths worth trying by hand including ones no scenario covers yet. If no scenario covers the change, write one, and embed its recording in the PR. The machinery runs in reverse too: seed an environment into a state (reproduce a bug live, stage data) and hand across the link.

Service Emulators

For any test or demo needing an upstream API, OAuth/OIDC provider, or webhook source, use the @executor-js/emulate emulators instead of writing a stub: wire-level and stateful, real SDKs run unmodified, each serves a full OpenAPI spec, mints real-shaped credentials, and records every call in a request ledger to assert against. Hosted at https://<service>.emulators.dev. See the emulate skill (.claude/skills/emulate/SKILL.md). They are a standalone project (github.com/UsefulSoftwareCo/emulate) consumed here as the published package: full autonomy to change, publish, and deploy them on their main; don't re-vendor.

Attribution

No AI/Claude/Anthropic/Co-Authored-By attribution in commits, messages, PRs, or generated files. PR titles and descriptions go to a public repo: no internal info or specific names unless explicitly stated.

Collaboration Notes

  • The user uses speech-to-text; infer likely intent from odd wording, ask only when needed.
  • Code is cheap to write: no time estimates, implementation time isn't a blocker.
  • Never use em-dashes anywhere. Use commas, colons, parentheses, or separate sentences.

Reference Repos

Repos in .reference (Effect, effect-atom, …) are available for patterns. Clone a given Git URL into .reference and pull latest before using it.

Engineering Priorities

  • Prefer correctness and predictable behavior over short-term convenience.
  • Preserve runtime behavior when changing lint, typing, or test structure.
  • Keep package boundaries clear; use public package exports, not cross-package relative imports.
  • Extract shared logic only when the shared behavior is real; avoid broad generic abstractions for one-off duplication.

Package Roles

  • packages/core/sdk: core contracts, plugin wiring, scopes, sources, secrets, policies, fixtures. @executor-js/sdk/http-auth carries the shared auth-method vocabulary the HTTP protocol plugins compose (core never imports it, keeping it carrier-agnostic).
  • packages/core/storage-*: storage adapters and test support.
  • packages/plugins/*: protocol and provider plugins; their runtime, React, API, and testing helpers live with the owning plugin.
  • packages/react: shared React UI and atom/client integration.
  • packages/hosts/mcp: MCP host surface.
  • packages/kernel/*: execution runtimes and code execution substrate.
  • apps/{local,cloud,cli,desktop}: product entry points composing the packages.

Other

Note mistakes in MISTAKES.md, missing context or tools in DESIRES.md, and env learnings in LEARNINGS.md.