Skip to content

docs(agents): fix accuracy bugs and flip AGENTS.md to canonical#208

Merged
btravers merged 3 commits intomainfrom
docs/agent-rules-fixes
May 4, 2026
Merged

docs(agents): fix accuracy bugs and flip AGENTS.md to canonical#208
btravers merged 3 commits intomainfrom
docs/agent-rules-fixes

Conversation

@btravers
Copy link
Copy Markdown
Owner

@btravers btravers commented May 4, 2026

Summary

Audit pass on AGENTS.md / CLAUDE.md and the seven .agents/rules/*.md files. Two outright bugs were misleading agents; several stale claims and coverage gaps cleaned up.

Outright bugs fixed

  • commands.md — pnpm version and pnpm release are documented but bare pnpm version collides with pnpm's built-in (silently prints process.versions instead of running the changeset script — the release workflow already worked around this in release.yml). Switched to pnpm run version / pnpm run release and added a release-flow walkthrough that documents OIDC Trusted Publishing + the RELEASE_PAT setup.
  • handlers.md — import { declareWorkflow } from "@temporal-contract/worker" doesn't work. The worker package's exports map only declares ./activity, ./worker, and ./workflow subpaths; there's no root entry. Fixed to from "@temporal-contract/worker/workflow".

Stale claims now matching reality

  • code-style.md — Documented the legitimate interface exception for declaration merging (packages/testing/src/global-setup.ts augments vitest's ProvidedContext), softened the type-imports rule from "use" to "prefer" (it isn't lint-enforced), and clarified that pino is for examples/ only — published packages/*/src/ are silent.
  • dependencies.md — Dropped the unused-pino claim, added ts-pattern (used by examples), added a Peer Dependencies table documenting the neverthrow ^8 peer dep policy that just landed in feat!: replace @swan-io/boxed with neverthrow #206, and a section on pnpm.overrides (security pins for lodash / vite / etc. that agents bumping deps will trip over).

Coverage gaps filled

  • contract-patterns.md — Added updates blocks, searchAttributes (KEYWORD / INT / DATETIME / etc.), and the standalone define* helpers (defineActivity, defineSignal, defineQuery, defineUpdate, defineSearchAttribute, defineWorkflow).
  • AGENTS.md — Was pure delegation (just a 7-row table of links). Now inlines the 5 highest-leverage rules at the top so an agent reading only the entry doc already knows the load-bearing constraints (ResultAsync, no any, .js imports, ESM, catalog versions). Rule table preserved for deep dives.

Structural change: symlink direction flipped

Was: AGENTS.md → CLAUDE.md (Anthropic-named file as source).
Now: CLAUDE.md → AGENTS.md (cross-tool standard as source — Cursor / Aider / Continue / Codex etc. all look for AGENTS.md).

Git captures this as a type-change on both files (T in git status).

Test plan

  • All .agents/rules/*.md links from AGENTS.md resolve (verified locally — see grep loop in commit).
  • pnpm run version and pnpm run release referenced in commands.md match the scripts defined in root package.json.
  • import { declareWorkflow } from "@temporal-contract/worker/workflow" matches the exports field in packages/worker/package.json.

🤖 Generated with Claude Code

@claude
docs(agents): fix accuracy bugs in agent rules and flip AGENTS.md to …
f5c32bc 
…canonical

Two outright bugs that would mislead any agent following the docs:
- commands.md said \`pnpm version\` / \`pnpm release\` — bare \`pnpm version\`
  collides with pnpm's built-in (silently prints \`process.versions\` instead
  of running the changeset script). Switched to \`pnpm run version\` /
  \`pnpm run release\` and added a release-flow walkthrough that documents
  the OIDC + RELEASE_PAT setup.
- handlers.md imported \`declareWorkflow\` from \`@temporal-contract/worker\`,
  but the worker package's exports map only declares \`./activity\`,
  \`./worker\`, and \`./workflow\` subpaths — no root entry. Fixed to
  \`@temporal-contract/worker/workflow\`.

Stale claims now matching reality:
- code-style.md: documented the legitimate \`interface\` exception for
  declaration merging (testing/src/global-setup.ts), softened the
  type-imports rule (not actually lint-enforced), and clarified that
  published packages don't log — pino is for examples only.
- dependencies.md: dropped the unused-pino claim, added ts-pattern, and
  documented peer-dependency policy + the \`pnpm.overrides\` security pins.

Coverage gaps filled:
- contract-patterns.md: added \`updates\`, \`searchAttributes\`, and the
  standalone \`define*\` helpers (defineActivity / defineSignal / defineQuery
  / defineUpdate / defineSearchAttribute / defineWorkflow).
- AGENTS.md: inlined the 5 highest-leverage rules at the top so an agent
  reading only the entry doc already knows the load-bearing constraints
  (ResultAsync, no \`any\`, \`.js\` imports, ESM, catalog versions).

Structural change: AGENTS.md is now the canonical file (matches the
cross-tool standard) and CLAUDE.md is a symlink to it. Reverses the
previous direction.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings May 4, 2026 15:25
Copilot AI reviewed May 4, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Updates the agent-facing documentation (AGENTS.md rule set) to correct inaccurate guidance and expand coverage around releases, dependency management, and contract authoring patterns.

Changes:

  • Fixes incorrect usage examples (e.g., declareWorkflow import path; pnpm version/release invocation).
  • Expands dependency guidance (catalog usage, peer dependency policy, pnpm.overrides) and contract patterns (updates + search attributes + define* helpers).
  • Refines code-style guidance (interface exception for module augmentation; clarify logging expectations).

Reviewed changes

Copilot reviewed 7 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file
File Description
.agents/rules/handlers.md Fixes declareWorkflow import to use the exported subpath.
.agents/rules/dependencies.md Reworks dependency documentation: catalog, peer deps, overrides, and monorepo conventions.
.agents/rules/contract-patterns.md Expands contract examples with define* helpers, updates, and search attributes.
.agents/rules/commands.md Updates version/release commands and documents the release workflow mechanics.
.agents/rules/code-style.md Clarifies TS rules (interface exception, type-import preference) and logging guidance.

Comment thread .agents/rules/contract-patterns.md Outdated
Comment thread .agents/rules/dependencies.md Outdated
Comment thread .agents/rules/dependencies.md Outdated
Comment thread .agents/rules/commands.md Outdated
Comment thread .agents/rules/code-style.md Outdated
@claude
docs(agents): cover determinism, cancellation, ApplicationFailure, pa…
c261ec9 
…ckage scaffolding

The previous accuracy pass fixed bugs but left real footguns undocumented.
Adds the high-impact missing tribal knowledge identified in the audit.

New rule files:
- workflow-determinism.md — banned APIs (Date.now, Math.random, setTimeout,
  crypto, native I/O) and Temporal-provided replacements. Promoted to the
  #1 entry in AGENTS.md's top-rules list since determinism is the leading
  cause of broken Temporal workflows.
- adding-a-package.md — step-by-step runbook covering tsconfig extension,
  vitest config, knip + changeset registration, peer-dep mirroring, and
  the multi-entry exports gotcha.

Expanded existing files:
- handlers.md: added Cancellation section (cancellableScope /
  nonCancellableScope / WorkflowCancelledError) and ApplicationFailure
  semantics (type / nonRetryable / cause / details), each with
  file:line breadcrumbs to the canonical source.
- code-style.md: documented the three non-default tsconfig flags
  (noUncheckedIndexedAccess, exactOptionalPropertyTypes,
  noPropertyAccessFromIndexSignature) with the spread idiom for optional
  cause. Stated that oxlint enforces only two rules.
- commands.md: listed all 11 commitlint-allowed types (config-conventional)
  with one-line guidance per type.
- testing.md: added file:line breadcrumb to vitest.config.ts:11-27,
  noted contract package's unit-only template, documented turbo's
  cache: false on test tasks and the vitest --coverage flag passthrough.
- project-overview.md: added repo-layout table (packages / examples /
  tools / docs), canonical entry-point breadcrumbs per package, and
  cross-links to determinism + handlers rules.

Cleanup:
- AGENTS.md: top-rules list grew from 5 to 6 with determinism at #1;
  rule-reference table now includes the two new files.
- CONTRIBUTING.md: trimmed to a contributor on-ramp that delegates to
  .agents/rules/ as canonical, eliminating the prior duplication
  (commit types, code-style, test conventions). Adds a where-to-look
  table covering all nine rule files.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@btravers btravers requested a review from Copilot May 4, 2026 15:40
@claude
docs(agents): address copilot review + fix oxfmt CI
58c1fc7 
CI was red on the Format job because AGENTS.md and CONTRIBUTING.md
were checked in without going through oxfmt. Fixed.

Five review comments from the Copilot reviewer, all accurate:

1. contract-patterns.md said \`defineContract\` enforces activity-name
   collisions "at the type level" — wrong, it's a Zod runtime validation
   pass that throws (\`packages/contract/src/builder.ts:441\`). Reworded to
   match reality and added the file:line breadcrumb.
2. dependencies.md "Key Dependencies" labeled \`zod / valibot / arktype\`
   as purely user-side, but \`zod\` is a direct runtime dep of the
   \`contract\` package (used by the validation pass above). Split the row
   so \`zod\` is documented as both internal and a user-facing schema lib.
3. dependencies.md "Peer Dependencies" said \`testing\` had no peer deps,
   but \`@temporal-contract/testing\` declares \`vitest ^4\` as a peer
   (the \`globalSetup\` hook integrates with vitest's runner). Documented.
4. commands.md release-flow step 3 said \`pnpm run release\` runs
   \`pnpm publish ...\`, omitting the \`pnpm build &&\` prefix from the
   actual root script. Step now mirrors the package.json command.
5. code-style.md anti-pattern claimed \`packages/*/src/\` is silent re:
   logging — not true, \`packages/testing/src/global-setup.ts\` uses
   \`console.log\`/\`console.error\` to surface testcontainers progress.
   Narrowed the rule to library packages (\`contract\`/\`client\`/\`worker\`)
   and explicitly carved out \`testing\` as the documented exception.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@btravers btravers merged commit d386794 into main May 4, 2026
12 checks passed
@btravers btravers deleted the docs/agent-rules-fixes branch May 4, 2026 16:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Awaiting requested review from Copilot

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@btravers