docs: share AGENTS.md guidance with Claude and Codex (ENG-748)

AGENTS.md

@@ -0,0 +1,12 @@
+# Shared instructions
+
+Before doing any work, read `docs/agents/organization.md` and
+`docs/agents/org-rules/tool-usage.md` in full. These checked-in snapshots make
+organization guidance available in standalone clones and worktrees. Before
+changing Linear work, also read `docs/agents/org-rules/linear.md`.
+Repository-specific instructions below take precedence for this repository.
+All paths in this entrypoint and its repository reference are repo-root relative.
+
+# simulation-github-action
+
+Read `README.md` and the relevant build/configuration files before changing this repository.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

docs/agents/org-rules/linear-surfaces.md

@@ -0,0 +1,129 @@
+# Linear surfaces — the derived copies
+
+Maintained in `linro-io/linro-io` at `docs/agents/org-rules/linear-surfaces.md`.
+In other repositories this is a generated snapshot: update the metarepo source
+and refresh with its `bin/sync-agent-guidance`; do not edit the copy independently.
+
+`docs/agents/org-rules/linear.md` is canonical. This file holds the **exact text** of
+the copies that live inside Linear, so a change to the convention is one diff
+covering the rule and its copies instead of a rule change plus a promise to
+update Linear later.
+
+Linear's API is **read-only** for agent skills and templates (`list_` and
+`get_` exist; there is no `save_`), so each of these is pasted once by a human.
+When this file changes, re-paste the block that changed.
+
+---
+
+## 1. Linear Agent Skill — "Issue handling"
+
+**Where:** Linear → Settings → Agents → Skills → New skill. Name it
+`Issue handling`.
+
+**Why it exists:** it reaches agents on any machine, including ones that never
+open the meta repo. Keep it short — it is a pointer with enough substance to be
+useful when the repo is not to hand.
+
+```markdown
+How work is tracked in this workspace. The full convention lives in
+`docs/agents/org-rules/linear.md` in the linro-io/linro-io meta repo; this is the
+short version for when that is not to hand.
+
+**There is no "epic".** The hierarchy is Initiative → Project → Project
+Milestone → Issue → sub-issue. Do not file a parent issue titled `Epic: …`:
+it is never meaningfully done, and it duplicates what a project already holds.
+
+**A workstream is a Project.** Its phases are **Project Milestones**, and every
+milestone description states its **gate** — the observable condition that must
+hold before the next phase starts. A phase with no gate is a label.
+
+**Sequencing is blocking relations** (`blocks` / `blockedBy`). Parent/sub-issue
+means containment, never order — a tree cannot say "this gates everything
+downstream". Sub-issues are for decomposing one issue into parts.
+
+**Every issue carries** the problem with evidence (`file:line`, an error
+string, a measured number — not a restatement of the title), acceptance
+criteria, and a *not in scope* line wherever the boundary is load-bearing.
+
+**Titles say what the change is.** No phase prefixes (`M0 — …`): the phase
+lives in the milestone, and a prefix duplicates it and then drifts from it.
+
+**Before filing, look for an existing ticket.** Link or comment on it rather
+than filing a near-duplicate. If an old ticket's design is superseded, say so
+in a comment on it.
+
+**Cancel, never delete.** Deleting breaks every reference from other issues,
+comments and PR bodies. Cancel with a pointer to whatever superseded it.
+
+Branch names come from Linear's `gitBranchName`, so PRs link themselves.
+Move to In Review when the PR opens; Done when merged — and, where reaching an
+environment is what makes it true, when deployed.
+```
+
+---
+
+## 2. Issue template — Engineering
+
+**Where:** Linear → Settings → Teams → Engineering → Templates → New issue
+template. Name it `Issue`, and set it as the team default so it appears
+without being chosen.
+
+```markdown
+## The problem
+
+<!-- Evidence, not a restatement of the title: file:line, the error string,
+     the measured number. What is broken or missing, and how you know. -->
+
+## Acceptance
+
+<!-- What is observably true when this is done. -->
+
+## Not in scope
+
+<!-- Delete this heading if the boundary is obvious. Keep it wherever the
+     ticket could quietly grow — it is what stops a guard becoming a rewrite. -->
+```
+
+---
+
+## 3. Project template — Engineering
+
+**Where:** Linear → Settings → Teams → Engineering → Templates → New project
+template. Name it `Workstream`.
+
+Linear project templates carry a description and can pre-create milestones.
+Create the description below, plus milestone placeholders `M0 · …` through
+`M2 · …` (add or delete phases per workstream — the point is that each one
+prompts for its gate).
+
+```markdown
+## The problem
+
+<!-- What is wrong today, with evidence. If a measurement settled something,
+     put the number here and link the ticket that measured it. -->
+
+## The shape of the fix
+
+<!-- The reframe, if there is one. What changes structurally. -->
+
+## Decisions taken
+
+<!-- Each with who took it, so nobody relitigates it in a month. -->
+
+## Alternatives rejected
+
+<!-- Each with the reason. A rejected option with no reason gets re-proposed. -->
+
+## Milestones
+
+<!-- Each milestone's description carries its GATE: the observable condition
+     that must hold before the next phase starts. -->
+```
+
+---
+
+## Keeping these in sync
+
+The rule file and this file change in the same PR. After merging, re-paste any
+block that changed — there is no API to do it for you, and a copy that has
+drifted is worse than no copy, because it is quoted with confidence.

docs/agents/org-rules/linear.md

@@ -0,0 +1,85 @@
+# Linear
+
+Maintained in `linro-io/linro-io` at `docs/agents/org-rules/linear.md`.
+In other repositories this is a generated snapshot: update the metarepo source
+and refresh with its `bin/sync-agent-guidance`; do not edit the copy independently.
+
+How work is tracked. **This file is canonical.** Three derived copies exist so
+the convention reaches surfaces the repo cannot:
+
+| Copy | Reaches | Source |
+|---|---|---|
+| Linear Agent Skill "Issue handling" | agents on any machine, including ones that never open this repo | `linear-surfaces.md` |
+| Engineering issue + project templates | humans and anything creating work in the Linear UI | `linear-surfaces.md` |
+| `.claude/skills/file-workstream/` | the multi-ticket procedure, where the traps are | that skill |
+
+**Change this file first, and update the copies in the same PR.** Three
+independent copies of a convention drift — that is exactly how this workspace
+ended up with three competing definitions of "epic".
+
+The two Linear-side copies are pasted by hand: Linear's API is read-only for
+agent skills and templates (`list_` / `get_`, no `save_`). Their exact text
+lives in `linear-surfaces.md` in this directory, so the copy travels in the
+same diff as the rule and re-pasting is mechanical.
+
+## There is no "epic"
+
+Linear has no epic object. The hierarchy is **Initiative → Project → Project
+Milestone → Issue → sub-issue**. "Epic" is Jira vocabulary; filing one as a
+parent issue titled `Epic: …` produces a permanent Backlog issue that is never
+meaningfully done, a breadcrumb on every child pointing at a stub, and a second
+container duplicating what a project already holds.
+
+## Shape of a workstream
+
+- **Project** — the workstream. Holds the write-up, the artifacts and links, a
+  lead, a start and target date. Note that this workspace's projects mix
+  long-lived *areas* (API, Frontend, Plugins, Infrastructure, Core Data
+  Platform) with real *efforts* (PII Data Scrubbing, Marketplace v1, Estate
+  Enrollment). A new workstream is an effort; do not file one under an area.
+- **Project Milestones** — the phases. **Every milestone description carries
+  its gate**: the observable condition that must hold before the next phase
+  starts. A phase with no gate is a label, not a milestone.
+- **Blocking relations** (`blocks` / `blockedBy`) — sequencing. This is the
+  only thing that expresses order.
+- **Sub-issues** — genuine decomposition of one issue into parts. Never an epic
+  stand-in.
+
+**Parent/sub-issue means containment, never order.** A tree cannot say "M1
+gates everything downstream"; a blocking relation can, and it shows on both
+issues.
+
+## Anatomy of an issue
+
+Every issue carries:
+
+- **The problem**, with evidence — `file:line`, an error string, a measured
+  number. Not a restatement of the title.
+- **Acceptance criteria** — what is observably true when it is done.
+- **Not in scope**, wherever the boundary is load-bearing. This is what stops a
+  guard ticket quietly becoming a rewrite.
+
+Titles say what the change is. **No phase prefixes** (`M0 — …`): the phase lives
+in the milestone, and a title prefix duplicates it and then drifts from it.
+
+## Lifecycle
+
+- **Before filing, look for an existing ticket.** Link or comment on it rather
+  than filing a near-duplicate; if an old ticket's design is superseded, say so
+  in a comment on that ticket.
+- Branch names come from Linear's `gitBranchName` (`istvandocsa/eng-627-…`), so
+  the PR links itself to the issue. Do not invent your own.
+- **In Review** when the PR opens. **Done** when it is merged — and, for
+  anything that has to reach an environment to be true, when it is deployed.
+- **Cancel, never delete.** A deleted issue breaks every reference to it from
+  other issues, comments and PR bodies. Cancel it with a pointer to whatever
+  superseded it.
+
+## Traps, learned the hard way
+
+- A parent issue looks like an epic and encodes nothing. If you catch yourself
+  explaining the sequencing in prose, you wanted blocking relations.
+- Structure encoded in a title (a phase prefix, a numbered option) becomes a
+  second source of truth the moment the real field exists.
+- A convention nobody can see at the point of creation decays. That is what the
+  issue template is for; keep it in sync with this file.

docs/agents/org-rules/tool-usage.md

@@ -0,0 +1,26 @@
+# Tool Usage
+
+Maintained in `linro-io/linro-io` at `docs/agents/org-rules/tool-usage.md`.
+In other repositories this is a generated snapshot: update the metarepo source
+and refresh with its `bin/sync-agent-guidance`; do not edit the copy independently.
+
+Use safe, purpose-built CLI tools for searching and file discovery. Never fall back to legacy commands.
+
+## Search
+
+- Always use `rg` (ripgrep) instead of `grep` for all text searching
+- Use `rg --type` to scope searches by language (e.g., `rg --type go`)
+- Use `rg --json` when structured output is needed
+
+## File Discovery
+
+- Always use `fd` instead of `find` for all file discovery. Add `--hidden`
+  when hidden paths are in scope and `--no-ignore` when ignored paths must
+  intentionally be checked.
+- Use `fd --extension` to filter by file type (e.g., `fd --extension tf`)
+
+## Security
+
+- Never use `find -exec`, `find -delete`, or `find -ok`
+- Never use `xargs` or shell pipes that execute commands
+- Never use `grep` directly — `rg` is always available and preferred