Skip to content

AGENTS.md

Latest commit

 

History

History
66 lines (47 loc) · 6.25 KB

AGENTS.md

File metadata and controls

66 lines (47 loc) · 6.25 KB
Raw

AGENTS.md

Commands

  • Use pnpm only; the repo pins pnpm@11.7.0 and requires Node >=22.
  • Install with pnpm install --frozen-lockfile when matching CI.
  • Full local gate and pre-push hook: pnpm verify (format:check -> lint -> code-mode:check-api -> schema:check -> docs:check -> typecheck -> test -> benchmark:check -> build).
  • Fast focused checks: pnpm format:check, pnpm lint, pnpm typecheck, pnpm test, pnpm build.
  • Run one package: pnpm --filter @caplets/core test, pnpm --filter @caplets/sdk test, pnpm --filter caplets build, or replace the filter with @caplets/opencode, @caplets/pi, or @caplets/benchmarks.
  • Run one Vitest file by passing it after the package script, e.g. pnpm --filter @caplets/core test -- test/config.test.ts.
  • Dev server: pnpm dev builds/watches @caplets/core and restarts packages/cli/dist/index.js; run pnpm build first if CLI dist output is missing.

Package Map

  • packages/core is the runtime/library source: config parsing, schema generation, MCP/OpenAPI/GraphQL/HTTP/CLI backends, native service exports.
  • packages/sdk owns the independent public Caplets SDK. Its root is the browser/Node Fetch client generated from the canonical public HTTP contract plus curated Caplet Bundle helpers; @caplets/sdk/project-binding owns the browser-safe fixed-v1 coordinator, and @caplets/sdk/project-binding/node owns marker-aware filesystem fingerprints. Keep caller authentication optional and caller-owned, require isolated clients and explicit service/WebSocket roots, and exclude MCP and dashboard-private routes.
  • packages/cli publishes the caplets binary and delegates almost all behavior to @caplets/core; caplets serve starts the MCP server, while no args print help.
  • packages/opencode and packages/pi are native agent integrations that wrap @caplets/core/native; keep integration-specific schema/adapter code there.
  • packages/benchmarks owns deterministic and opt-in live coding-agent benchmarks; deterministic benchmark docs are generated from pnpm benchmark.

Agent skills

Issue tracker

Issues and PRDs live in GitHub Issues for spiritledsoftware/caplets; use gh with --repo spiritledsoftware/caplets. See docs/agents/issue-tracker.md.

Triage labels

Use the five canonical triage labels without overrides. See docs/agents/triage-labels.md.

Domain docs

This is a single-context repo: start with root CONTEXT.md and relevant ADRs in docs/adr/. See docs/agents/domain.md.

Test Quality Bar

  • Keep tests that protect behavior, user-visible contracts, generated artifacts, integrations, regressions, or data-safety boundaries. Remove or avoid tests that mostly restate implementation literals.
  • Do not add tests that only assert package metadata, prompt/help copy substrings, Markdown wrapper scaffolding, export importability, or duplicated flag passthrough when stronger behavior coverage already exists.
  • Do not add tests for marketing/blog/editorial prose, exact headlines, body copy, or subjective positioning. Copy is reviewed by humans, not locked by tests; only test durable content-system behavior such as schema validation, routing, metadata generation, or safety boundaries.
  • Prefer Code Mode coverage through structured envelopes, session/recovery metadata, generated API checks, schema checks, and real tool execution. Avoid long prompt-description snapshots.
  • Prefer benchmark tests that validate metric shape and failure thresholds. Do not pin static scenario IDs or improvement-name fixtures unless the exact list is the behavior under test.
  • When deleting or skipping a narrow unit test, make sure a stronger integration test, generated-file check, or full gate still protects the meaningful behavior.

Docs And Generated Files

  • Source code is authoritative. Keep durable product docs in docs/product/, architecture docs in docs/, ADRs in docs/adr/, specs/plans in docs/specs/ or docs/plans/, and solution patterns in docs/solutions/.
  • Avoid committing short-lived plans unless explicitly requested. Do not use docs/superpowers/ in this repo.
  • Config schema source: packages/core/src/config.ts. Generate with pnpm schema:generate; check with pnpm schema:check.
  • Code Mode API sources: packages/core/src/code-mode/runtime-api.d.ts and packages/core/src/code-mode/platform-entry.ts. Generate with pnpm code-mode:generate-api; check with pnpm code-mode:check-api.
  • Canonical HTTP API sources are the route-local Zod/OpenAPI definitions in packages/core; pnpm openapi:generate writes schemas/caplets-http.openapi.json and packages/sdk/src/generated/. pnpm openapi:check checks both artifacts and the SDK contract. Do not hand-edit the generated SDK.
  • Benchmark report: pnpm benchmark updates docs/benchmarks/coding-agent.md; pnpm benchmark:check checks staleness.
  • Live benchmarks are opt-in and local/model-dependent: build first, then run CAPLETS_BENCH_LIVE=1 pnpm benchmark:live:opencode, CAPLETS_BENCH_LIVE=1 pnpm benchmark:live:pi, or CAPLETS_BENCH_LIVE=1 pnpm benchmark:live:pi-eval.

Config And Runtime Gotchas

  • Default user config path is resolved by core; tests commonly override with CAPLETS_CONFIG.
  • Project config lives at .caplets/config.json; project Markdown Caplet files load by default, while executable backend maps in project config are intentionally rejected.
  • Runtime config reload keeps the last known-good config on parse/validation errors; do not change this behavior without updating reload tests.
  • Caplet tool names come from configured server IDs and expose progressive discovery operations (get_caplet, list_tools/search_tools, get_tool, call_tool) rather than flattening downstream tools.

PR And Release Checks

  • CI runs pnpm verify plus pnpm changeset status --since=origin/main on PRs unless the PR has the no changeset label.
  • User-facing package changes usually need a changeset; current versioning is handled by Changesets and pnpm version-packages/pnpm release.
  • Pre-commit only runs pnpm lint-staged (oxfmt --check and oxlint on staged JS/TS/config/docs files); pre-push runs the full pnpm verify.
  • Alchemy deploy workflows are in .github/workflows/deploy.yml and .github/workflows/pr-preview-deploy.yml; check alchemy.run.ts and infra/ before changing deploy behavior.