From 9765e3c7e21d95a2e22acc18c3e87569b9780471 Mon Sep 17 00:00:00 2001
From: Phil Austin <paustin01@users.noreply.github.com>
Date: Sun, 19 Jul 2026 15:38:23 +0000
Subject: [PATCH] docs: add AGENTS.md and thin CLAUDE.md shim

Promote evaluated repo guidance into AGENTS.md, point at the
versioner-workspace docs/agent spine, and drop stale cross-repo paths.
---
 AGENTS.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md | 40 +++++-----------------------------------
 2 files changed, 51 insertions(+), 35 deletions(-)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..b59ff39
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,46 @@
+# AGENTS.md — versioner-github-action
+
+TypeScript GitHub Action that sends build/deployment events to the Versioner API. Node 20, `@actions/core`, Axios.
+
+## Cross-repo context
+
+This repo is one of the Versioner app repos.
+
+1. Resolve `versioner-workspace` (nested parent **or** sibling — see that repo's `docs/agent/ECOSYSTEM.md` layout discovery).
+2. Read:
+   - `docs/agent/ECOSYSTEM.md` (routing / which repo)
+   - `docs/agent/CONVENTIONS.md` (branches, PRs, commits)
+3. Then follow **this file** for repo-local setup, test, and architecture.
+
+Do **not** use `versioner-dev-docs`, kanban-markdown feature trees, or machine-specific paths like `/Users/phil...`.
+
+
+## Build & test
+
+```bash
+just setup_local_dev    # npm install
+just build              # ncc → dist/index.js (committed bundle)
+just run_tests          # Jest (80% coverage threshold)
+just test_coverage
+just lint               # ESLint strict
+just format             # Prettier
+just ci                 # format → lint → build → test
+```
+
+**`dist/` is committed** (required for GitHub Actions consumption). Rebuild and commit dist when source changes.
+
+## Architecture
+
+- `src/index.ts` — entry; routes build vs deployment by `event_type`
+- `src/inputs.ts` — input validation (action inputs / env)
+- `src/api-client.ts` — Versioner HTTP client; preflight rejections 409/423/428
+- `src/github-context.ts` — repo/SHA/branch/actor/workflow; `vi_gh_` env capture
+- `src/types.ts` — payloads/responses
+- `action.yml` — inputs/outputs
+
+## Local conventions
+
+- Follow existing patterns
+- Blank lines must be completely empty
+- Add tests for new behavior; pass before PR
+- Prefer editing existing files over creating new ones
diff --git a/CLAUDE.md b/CLAUDE.md
index 8895a42..a80a9cd 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,40 +1,10 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Follow **[AGENTS.md](./AGENTS.md)** in this repository (authoritative for Claude Code and other agents).
 
-## What This Is
+Global Versioner rules live in the `versioner-workspace` spine:
 
-Versioner GitHub Action - a TypeScript GitHub Action that sends build and deployment events to the Versioner API. Node.js 20, @actions/core, Axios.
+- `docs/agent/ECOSYSTEM.md` — routing
+- `docs/agent/CONVENTIONS.md` — universal process
 
-
-## Build & Test Commands
-
-All commands use `just` (run `just` to list all):
-
-```bash
-just setup_local_dev    # npm install
-just build              # ncc build to dist/index.js (self-contained bundle)
-just run_tests          # Jest (80% coverage threshold)
-just test_coverage      # Jest with coverage report
-just lint               # ESLint (strict: explicit return types, no any)
-just format             # Prettier
-just ci                 # format -> lint -> build -> test
-```
-
-The `dist/` directory is committed (GitHub Actions requires it).
-
-## Architecture
-
-- `src/index.ts` - Entry point; routes to build or deployment event handling based on `event_type` input
-- `src/inputs.ts` - Input validation and parsing (from GitHub Actions inputs or env vars)
-- `src/api-client.ts` - HTTP client for Versioner API with error handling for preflight rejections (409, 423, 428)
-- `src/github-context.ts` - Extracts GitHub metadata (repo, SHA, branch, actor, workflow URL) and auto-captures env vars with `vi_gh_` prefix
-- `src/types.ts` - TypeScript interfaces for payloads and responses
-- `action.yml` - Action definition with inputs/outputs
-
-## Conventions
-
-- Follow existing code patterns and style
-- Blank lines must be completely empty (no whitespace-only lines)
-- Add tests for new features; ensure tests pass before committing
-- Prefer editing existing files over creating new ones
+Resolve the workspace as a **parent** directory (nested Mac layout) or **sibling** directory (Hermes layout).