docs: Add additional non-determinism rules to workflow guide for agents

[c-warren]

What changed?

Updated the structure for our agent-guiding prompts to be agent agnostic, added additional rules to prevent non-determinism in workflow code.

Why?

There were additional ways to cause non-determinism that we have found while working on rules for agents writing workflow code. These have been added to our existing documentation, which lives in this repository.

Longer term we would like to move the rules somewhere that can be consumed by people/agents that are writing client code, where it will be most useful.

Additionally I've updated some of our agent memory/guidance to be tool agnostic, and updated the tool specific guidance to point to the generic guidance.

How did you test it?

I queried agents at runtime to find out what and how they loaded their context to validate that AGENTS.md was used.

# cursor
When I start up in this repo, I have the following from the system (no tools run yet):
...
Rules (already applied)
.cursor/rules/agents.mdc – Agent config: use AGENTS.md and .agents/ as main source of truth; precedence is user instructions → AGENTS.md / .agents/ → .cursor/rules/ → default.
CLAUDE.md – Dev guidelines: no co-authored-by in commits, testing (table tests, uber-go/mock), no IDL in service logic, map to common/types or common/persistence, architecture (common/persistence, common/types, services, tools/cli, idls), workflow commands (make test, make lint, make pr, etc.), pointers to .agents/ and workflow docs.
AGENTS.md – Same content as the dev guidelines in CLAUDE.md (core rules, architecture, workflow).
So at startup I know: path, git state, and the above rules. I do not have file contents, search results, or terminal state until I read files or run tools.

# claude
I read the following from CLAUDE.md on startup:

  Core Development Rules

  - Never mention co-authored-by or tool attribution in commits
  - Testing: Prefer table-tests, avoid suite-tests (legacy), use uber-go/mock not testify for new mocks
  - Types: Never use IDL code directly in service logic - map to common/types or common/persistence

  System Architecture

  - common/persistence - persistence layer packages with PersistenceManager/PersistenceStore structure
  - common/types - RPC layer internal type representation (top of dependency tree)
  - services - Major services (history, matching, frontend, worker)
  - tools/cli - Cadence CLI
  - idls - Submodule for Thrift codegen

  Development Workflow Commands

  - make test / go test for testing
  - make lint for linting
  - make pr to prepare for PRs (re-runs IDL codegen, linting, formatting)
  - Test files should be <filename>_test.go
  - Run go test /path/to/changes during dev, only make test at end (slow)

  References

  - .agents/ directory for go-style.md and shell-style.md
  - docs/non-deterministic-error.md for workflow debugging
  - .cursor/rules/CADENCE-WORKFLOWS.mdc for workflow patterns

Potential risks

These are just documentation changes, mostly for agents when writing code within our repository.

Release notes

N/A

Documentation Changes

These changes do not require documentation changes in our public docs repo.

[gitar-bot]

🔍 CI failure analysis for 0981f38: 1 flaky Cassandra integration test failure due to schema event buffer overflow during rapid schema operations—unrelated to documentation changes in this PR.

Overview

Analyzed 2 CI logs from 1 unique failure pattern. The single failure is a Cassandra persistence integration test that encountered a schema event buffer overflow, a known infrastructure issue unrelated to the PR's documentation-only changes.

Failures

Cassandra SchemaEvents Buffer Overflow (confidence: high)

• Type: flaky_test, infrastructure
• Affected jobs: 66528831235 (go-cassandra-integration-coverage)
• Related to PR: no
• Root cause: The Cassandra gocql driver's SchemaEvents buffer filled up and began dropping schema change event frames during rapid consecutive schema creation operations in the test. Starting at 20:41:27, repeated "SchemaEvents: buffer full, dropping event frame" messages indicate the driver could not keep pace with schema notifications, causing test state inconsistencies.
• Suggested fix: (1) Increase SchemaEvents buffer size in Cassandra driver configuration; (2) Reduce schema operation parallelism or add inter-operation delays; (3) Upgrade gocql/Cassandra driver to a version with improved buffer management; (4) Add retry logic to the test given this is a known flaky infrastructure pattern.

Summary

• PR-related failures: 0 — This PR contains only documentation and configuration updates (workflow guides, agent rules, markdown files)
• Infrastructure/flaky failures: 1 — Cassandra schema event buffer overflow, a driver-level infrastructure issue
• Recommended action: This failure is unrelated to the PR content. Investigate Cassandra test infrastructure configuration or upgrade the driver version to resolve the buffer management issue. No code changes are needed for this PR.

Code Review ✅ Approved 2 resolved / 2 findings

Documentation update to the workflow guide adds non-determinism rules for agents, addressing home directory path portability and formatting issues. No remaining issues found.

✅ 2 resolved

✅ Bug: Go style guide references non-portable home directory path

📄 .agents/go-style.md:5
.agents/go-style.md references ~/.rules/uber_go_style_guide.md, a user-specific home directory path. This file will not exist for other contributors, CI environments, or most AI agent runtimes, making the rule effectively broken for anyone except the original author. The reference should either point to a file committed in the repository (e.g., .agents/uber_go_style_guide.md) or to a public URL like https://github.com/uber-go/guide/blob/master/style.md.

✅ Quality: CLAUDE.md missing trailing newline

📄 CLAUDE.md:1
The new CLAUDE.md file is missing a trailing newline (\ No newline at end of file). POSIX text files should end with a newline, and many tools (including git diff) will flag this.

Rules ❌ No requirements met

Repository Rules

❌ PR Description Quality Standards: Expand 'Why?' to explain the specific non-determinism issues addressed (GetVersion for in-flight workflow safety, workflow.Channel/Selector for determinism); provide concrete, reproducible testing steps in 'How did you test it?' rather than referencing informal agent queries; update 'Documentation Changes' from N/A to describe the actual documentation changes (AGENTS.md as single source of truth, new CADENCE-WORKFLOWS.mdc rules).

_{2 rules not applicable. Show all rules by commenting gitar display:verbose.}

Tip

Comment Gitar fix CI or enable auto-apply: gitar auto-apply:on

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}

[themavik]

Sections on GetVersion plus workflow.Channel/workflow.Selector in CADENCE-WORKFLOWS.mdc spell out real nondeterminism foot-guns. nit: new root AGENTS.md and always-on .cursor/rules/agents.mdc is a wider policy change than the workflow doc—splitting that out keeps the workflow guidance easy to merge on its own.