Curate AGENTS.md by mbarlow12 · Pull Request #166 · RMI/stitch

mbarlow12 · 2026-07-09T02:52:47Z

Replace the generic AGENTS.md with curated, repo-specific guidance. The CLAUDE.md → @AGENTS.md bridge is already on this branch, so the diff is AGENTS.md only.

This was almost entirely generated by Claude with some minor edits after the fact.

I first ran the /init slash command to have CC review the repo in detail and create a CLAUDE.md. Then, I went through an interactive merge process/conversation to combine the contents of the 2 files while still keeping under the 200 line recommended limit. I use the official claude-md-management plugin that has a claude-md-improvement skill which has been useful for me across a number of project.

There's a shift toward orienting agents to the repo with common commands, structure/layout, notable gotchas, etc...

Important

With the added specifics, it'll be more important to keep AGENTS.md & supporting docs updated with relevant content (e.g. the source key list).

The hope is that this should offer decent guidance/guardrails on working in stitch without overly dictating specific workflows or patterns. And it should pair well with user-level ~/.claude/CLAUDE.md or local overrides (CLAUDE.local.md).

# Conflicts: # AGENTS.md

github-actions · 2026-07-09T02:56:49Z

CD summary `5df28d2`

Frontend: https://witty-mushroom-017a3dc1e-166.westus2.1.azurestaticapps.net

Deployments (4)

service	url	fqdn
api	open	`pr-166-api.purplegrass-c07d0a94.westus2.azurecontainerapps.io`
entity-linkage	open	`pr-166-entity-linkage.purplegrass-c07d0a94.westus2.azurecontainerapps.io`
frontend	https://witty-mushroom-017a3dc1e-166.westus2.1.azurestaticapps.net
stitch-llm	open	`pr-166-stitch-llm.purplegrass-c07d0a94.westus2.azurecontainerapps.io`

Database (1)

db_name	postgres_host	postgres_port	postgres_db
pr_166	`stitch-dev.postgres.database.azure.com`	`5432`	`pr_166`

Jobs (2)

job	image	postgres_db	api_url	auth_mode
db-migrations	`ghcr.io/rmi/stitch-api:pr-166@sha256:1f09592bcbaee12a44661b651fa084553d94403281dee1538ce6f7f7636d2cc3`	`pr_166`
seed	`ghcr.io/rmi/stitch-seed:pr-166@sha256:19e0661602ed6f501b3bffd275e8300147146593c905a98602acb344f5028587`		`https://pr-166-api.purplegrass-c07d0a94.westus2.azurecontainerapps.io/api/v1`	`stitch-client-bearer-token`

Images (4)

build_time	commit_time	git_sha	image	image_digest
2026-07-09T02:53:02Z	2026-07-09T02:52:47Z	`d84492c`	`ghcr.io/rmi/stitch-api:pr-166`	`ghcr.io/rmi/stitch-api:pr-166@sha256:1f09592bcbaee12a44661b651fa084553d94403281dee1538ce6f7f7636d2cc3`
2026-07-09T02:53:01Z	2026-07-09T02:52:47Z	`d84492c`	`ghcr.io/rmi/stitch-entity-linkage:pr-166`	`ghcr.io/rmi/stitch-entity-linkage:pr-166@sha256:a34dd3b9f7de6efeda140aa75665fa5930f7f014e9cb6fc52b60ad6062658b4a`
2026-07-09T02:53:05Z	2026-07-09T02:52:47Z	`d84492c`	`ghcr.io/rmi/stitch-seed:pr-166`	`ghcr.io/rmi/stitch-seed:pr-166@sha256:19e0661602ed6f501b3bffd275e8300147146593c905a98602acb344f5028587`
2026-07-09T02:53:02Z	2026-07-09T02:52:47Z	`d84492c`	`ghcr.io/rmi/stitch-stitch-llm:pr-166`	`ghcr.io/rmi/stitch-stitch-llm:pr-166@sha256:4095a4444706355d5a0a6d665b24f8ed99e93e2825984f6d34452545dea4df75`

github-actions · 2026-07-09T03:14:10Z

CD summary `d1b3daa`

Frontend: https://witty-mushroom-017a3dc1e-166.westus2.1.azurestaticapps.net

Deployments (4)

service	url	fqdn
api	open	`pr-166-api.purplegrass-c07d0a94.westus2.azurecontainerapps.io`
entity-linkage	open	`pr-166-entity-linkage.purplegrass-c07d0a94.westus2.azurecontainerapps.io`
frontend	https://witty-mushroom-017a3dc1e-166.westus2.1.azurestaticapps.net
stitch-llm	open	`pr-166-stitch-llm.purplegrass-c07d0a94.westus2.azurecontainerapps.io`

Database (1)

db_name	postgres_host	postgres_port	postgres_db
pr_166	`stitch-dev.postgres.database.azure.com`	`5432`	`pr_166`

Jobs (1)

job	image	postgres_db
db-migrations	`ghcr.io/rmi/stitch-api:pr-166@sha256:fb1f01c12999784d4919bbf0bf255363ad3d8b08e0988b0e2fad22a45992d97a`	`pr_166`

Images (4)

build_time	commit_time	git_sha	image	image_digest
2026-07-09T03:10:18Z	2026-07-09T03:10:03Z	`87abd68`	`ghcr.io/rmi/stitch-api:pr-166`	`ghcr.io/rmi/stitch-api:pr-166@sha256:fb1f01c12999784d4919bbf0bf255363ad3d8b08e0988b0e2fad22a45992d97a`
2026-07-09T03:10:16Z	2026-07-09T03:10:03Z	`87abd68`	`ghcr.io/rmi/stitch-entity-linkage:pr-166`	`ghcr.io/rmi/stitch-entity-linkage:pr-166@sha256:3c6a2d97b2dc04b3ce61fce96d7795818c79ceb5252683aa096e0a15a1ee6dde`
2026-07-09T03:10:17Z	2026-07-09T03:10:03Z	`87abd68`	`ghcr.io/rmi/stitch-seed:pr-166`	`ghcr.io/rmi/stitch-seed:pr-166@sha256:12a7bbd52427287da1b668564c5f52168d401747adef1e0b3acb0a4daf30dbbb`
2026-07-09T03:10:19Z	2026-07-09T03:10:03Z	`87abd68`	`ghcr.io/rmi/stitch-stitch-llm:pr-166`	`ghcr.io/rmi/stitch-stitch-llm:pr-166@sha256:af3b6feb2e2c7e4f96568f8284d049117a8cda912d81b2ff8a7b30abf40d293a`

github-actions · 2026-07-09T03:39:41Z

CD summary `646f404`

Frontend: https://witty-mushroom-017a3dc1e-166.westus2.1.azurestaticapps.net

Deployments (4)

service	url	fqdn
api	open	`pr-166-api.purplegrass-c07d0a94.westus2.azurecontainerapps.io`
entity-linkage	open	`pr-166-entity-linkage.purplegrass-c07d0a94.westus2.azurecontainerapps.io`
frontend	https://witty-mushroom-017a3dc1e-166.westus2.1.azurestaticapps.net
stitch-llm	open	`pr-166-stitch-llm.purplegrass-c07d0a94.westus2.azurecontainerapps.io`

Database (1)

db_name	postgres_host	postgres_port	postgres_db
pr_166	`stitch-dev.postgres.database.azure.com`	`5432`	`pr_166`

Jobs (1)

job	image	postgres_db
db-migrations	`ghcr.io/rmi/stitch-api:pr-166@sha256:b641b3dee8f3f7784da18e9fe02108fe438e59885714d089731f6605371d3188`	`pr_166`

Images (4)

build_time	commit_time	git_sha	image	image_digest
2026-07-09T03:35:53Z	2026-07-09T03:35:34Z	`5d6f37a`	`ghcr.io/rmi/stitch-api:pr-166`	`ghcr.io/rmi/stitch-api:pr-166@sha256:b641b3dee8f3f7784da18e9fe02108fe438e59885714d089731f6605371d3188`
2026-07-09T03:35:51Z	2026-07-09T03:35:34Z	`5d6f37a`	`ghcr.io/rmi/stitch-entity-linkage:pr-166`	`ghcr.io/rmi/stitch-entity-linkage:pr-166@sha256:f93b43bdfc2d0bc9843ac2b9419c19b570cd8d0565d8666892c28eece0b95c6d`
2026-07-09T03:35:49Z	2026-07-09T03:35:34Z	`5d6f37a`	`ghcr.io/rmi/stitch-seed:pr-166`	`ghcr.io/rmi/stitch-seed:pr-166@sha256:81069f5264a46102ad56420b1ed291c078c48ae8a2d4e0e0b40bc390628b5cdf`
2026-07-09T03:35:52Z	2026-07-09T03:35:34Z	`5d6f37a`	`ghcr.io/rmi/stitch-stitch-llm:pr-166`	`ghcr.io/rmi/stitch-stitch-llm:pr-166@sha256:7abf7d24a9b6465c21bf959ac3ca24c1ecb8e0c0d91f0ce48a535801f0e3174b`

AlexAxthelm

Big fan of this! Could not have written better myself. Some small notes from my experiences with the robots. Thanks.

AlexAxthelm · 2026-07-09T11:16:06Z

+
+- `make api-test`, `make entity-linkage-test`, `make stitch-llm-test`, `make seed-test`, `make frontend-test`, `make pkg-test-<name>` — per-target suites.
+- One file or test: `uv run --package <pkg> pytest <path>[::test_name] -x`, e.g.
+  `uv run --package stitch-api pytest deployments/api/tests/db/test_query.py -x`.


Suggested change

`uv run --package stitch-api pytest deployments/api/tests/db/test_query.py -x`.

`uv run --package stitch-api pytest deployments/api/tests/db/test_query.py -x`.

While the per-target suites and `uv` invoked tests are good for iterating quickly, note that `make check` and the higher-level targets should pass cleanly before work is considered complete.

AlexAxthelm · 2026-07-09T11:19:51Z

+
+## CI gates that will fail a PR
+
+- A **forbidden-patterns** scan (`.github/workflows/admin-forbidden-patterns.yml`) blocks


Open question for the group, do we want to add forbidden-patterns to make check or something similar?

Co-authored-by: Alex Axthelm <alex@alexaxthelm.com>

github-actions · 2026-07-09T19:06:28Z

CD summary `0d47e8d`

Database (1)

db_name	postgres_host	postgres_port	postgres_db
pr_166	`stitch-dev.postgres.database.azure.com`	`5432`	`pr_166`

Jobs (1)

job	image	postgres_db
db-migrations	`ghcr.io/rmi/stitch-api:pr-166@sha256:ef8afd16c5b149ccd31492dfb2547b60df66bf49a133af3bfc2a80e2778ba97c`	`pr_166`

Images (4)

build_time	commit_time	git_sha	image	image_digest
2026-07-09T19:04:34Z	2026-07-09T19:04:16Z	`5dc4423`	`ghcr.io/rmi/stitch-api:pr-166`	`ghcr.io/rmi/stitch-api:pr-166@sha256:ef8afd16c5b149ccd31492dfb2547b60df66bf49a133af3bfc2a80e2778ba97c`
2026-07-09T19:04:34Z	2026-07-09T19:04:16Z	`5dc4423`	`ghcr.io/rmi/stitch-entity-linkage:pr-166`	`ghcr.io/rmi/stitch-entity-linkage:pr-166@sha256:345211139e918df60e51d47f2fcf86977d40289113136a0f9102391649e31fc5`
2026-07-09T19:04:35Z	2026-07-09T19:04:16Z	`5dc4423`	`ghcr.io/rmi/stitch-seed:pr-166`	`ghcr.io/rmi/stitch-seed:pr-166@sha256:629d228fb4f4020aa223f4f5ff664f5014c71b4503312386b1b6c7fe9b794160`
2026-07-09T19:04:36Z	2026-07-09T19:04:16Z	`5dc4423`	`ghcr.io/rmi/stitch-stitch-llm:pr-166`	`ghcr.io/rmi/stitch-stitch-llm:pr-166@sha256:e9fbd62360482626893d68d8002c438dfa2b69dd312e88e39c96a25eef0c2a3a`

github-actions · 2026-07-09T19:07:56Z

CD summary `0b514e7`

Deployments (2)

service	url	fqdn
api	open	`pr-166-api.purplegrass-c07d0a94.westus2.azurecontainerapps.io`
stitch-llm	open	`pr-166-stitch-llm.purplegrass-c07d0a94.westus2.azurecontainerapps.io`

Database (1)

db_name	postgres_host	postgres_port	postgres_db
pr_166	`stitch-dev.postgres.database.azure.com`	`5432`	`pr_166`

Jobs (1)

job	image	postgres_db
db-migrations	`ghcr.io/rmi/stitch-api:pr-166@sha256:5e0c3046b5684a1f61c97c2f1a752c4965aea002cd7d8368882897cf4e881831`	`pr_166`

Images (4)

build_time	commit_time	git_sha	image	image_digest
2026-07-09T19:04:50Z	2026-07-09T19:04:31Z	`9cdce18`	`ghcr.io/rmi/stitch-api:pr-166`	`ghcr.io/rmi/stitch-api:pr-166@sha256:5e0c3046b5684a1f61c97c2f1a752c4965aea002cd7d8368882897cf4e881831`
2026-07-09T19:04:49Z	2026-07-09T19:04:31Z	`9cdce18`	`ghcr.io/rmi/stitch-entity-linkage:pr-166`	`ghcr.io/rmi/stitch-entity-linkage:pr-166@sha256:e2b020a28975e12cdc53387cdbd02567e17b6864dd0b3c0c17f25fada9b9b237`
2026-07-09T19:04:50Z	2026-07-09T19:04:31Z	`9cdce18`	`ghcr.io/rmi/stitch-seed:pr-166`	`ghcr.io/rmi/stitch-seed:pr-166@sha256:b3bc3a3ef585b17c427695ad7fd67cf07339b92cc829a5686e102a3f151d923d`
2026-07-09T19:04:49Z	2026-07-09T19:04:31Z	`9cdce18`	`ghcr.io/rmi/stitch-stitch-llm:pr-166`	`ghcr.io/rmi/stitch-stitch-llm:pr-166@sha256:c3a63aba7cb4c2bdb3bad7ddc19c181a93c1fd80f812328a5388c16917f90603`

github-actions · 2026-07-09T19:08:16Z

CD summary `f297a70`

Frontend: https://witty-mushroom-017a3dc1e-166.westus2.1.azurestaticapps.net

Deployments (4)

service	url	fqdn
api	open	`pr-166-api.purplegrass-c07d0a94.westus2.azurecontainerapps.io`
entity-linkage	open	`pr-166-entity-linkage.purplegrass-c07d0a94.westus2.azurecontainerapps.io`
frontend	https://witty-mushroom-017a3dc1e-166.westus2.1.azurestaticapps.net
stitch-llm	open	`pr-166-stitch-llm.purplegrass-c07d0a94.westus2.azurecontainerapps.io`

Database (1)

db_name	postgres_host	postgres_port	postgres_db
pr_166	`stitch-dev.postgres.database.azure.com`	`5432`	`pr_166`

Jobs (1)

job	image	postgres_db
db-migrations	`ghcr.io/rmi/stitch-api:pr-166@sha256:d7ed95c1660788f49aa353f0c9b4cf0effc987d503930f24f5af5ec34b8adbfa`	`pr_166`

Images (4)

build_time	commit_time	git_sha	image	image_digest
2026-07-09T19:04:20Z	2026-07-09T19:04:04Z	`ea73e22`	`ghcr.io/rmi/stitch-api:pr-166`	`ghcr.io/rmi/stitch-api:pr-166@sha256:d7ed95c1660788f49aa353f0c9b4cf0effc987d503930f24f5af5ec34b8adbfa`
2026-07-09T19:04:21Z	2026-07-09T19:04:04Z	`ea73e22`	`ghcr.io/rmi/stitch-entity-linkage:pr-166`	`ghcr.io/rmi/stitch-entity-linkage:pr-166@sha256:74eda00d718b1d3b46e314026f533982233893455729e1eb6622340b8997eaf5`
2026-07-09T19:04:20Z	2026-07-09T19:04:04Z	`ea73e22`	`ghcr.io/rmi/stitch-seed:pr-166`	`ghcr.io/rmi/stitch-seed:pr-166@sha256:5e9771eec2ec9dcc2989591c43d605227f60541305d835499d58138a82de7d12`
2026-07-09T19:04:22Z	2026-07-09T19:04:04Z	`ea73e22`	`ghcr.io/rmi/stitch-stitch-llm:pr-166`	`ghcr.io/rmi/stitch-stitch-llm:pr-166@sha256:122ed7680a0a2253dea7aa8df123ed3a854ba5342314a89f949af3dea9361631`

mbarlow12 added 2 commits July 8, 2026 20:51

docs: unify agent guidance into curated AGENTS.md with CLAUDE.md bridge

34b8d98

Merge origin/add-claude-md into feat/adjust-agents-md

5df28d2

# Conflicts: # AGENTS.md

mbarlow12 temporarily deployed to development July 9, 2026 02:52 — with GitHub Actions Inactive

mbarlow12 temporarily deployed to development July 9, 2026 02:53 — with GitHub Actions Inactive

mbarlow12 temporarily deployed to development July 9, 2026 02:54 — with GitHub Actions Inactive

mbarlow12 temporarily deployed to development July 9, 2026 02:55 — with GitHub Actions Inactive

remove overly specific content

d1b3daa

mbarlow12 temporarily deployed to development July 9, 2026 03:10 — with GitHub Actions Inactive

mbarlow12 temporarily deployed to development July 9, 2026 03:11 — with GitHub Actions Inactive

mbarlow12 temporarily deployed to development July 9, 2026 03:12 — with GitHub Actions Inactive

mbarlow12 temporarily deployed to development July 9, 2026 03:13 — with GitHub Actions Inactive

docs: correct .agents/docs ignore mechanism in AGENTS.md

646f404

mbarlow12 temporarily deployed to development July 9, 2026 03:35 — with GitHub Actions Inactive

mbarlow12 temporarily deployed to development July 9, 2026 03:36 — with GitHub Actions Inactive

mbarlow12 temporarily deployed to development July 9, 2026 03:37 — with GitHub Actions Inactive

mbarlow12 temporarily deployed to development July 9, 2026 03:38 — with GitHub Actions Inactive

jdhoffa requested a review from john July 9, 2026 09:53

AlexAxthelm reviewed Jul 9, 2026

View reviewed changes

Base automatically changed from add-claude-md to main July 9, 2026 18:48

Update AGENTS.md

f297a70

Co-authored-by: Alex Axthelm <alex@alexaxthelm.com>

mbarlow12 temporarily deployed to development July 9, 2026 19:04 — with GitHub Actions Inactive

Update AGENTS.md

0d47e8d

Co-authored-by: Alex Axthelm <alex@alexaxthelm.com>

mbarlow12 temporarily deployed to development July 9, 2026 19:04 — with GitHub Actions Inactive

Merge branch 'main' into feat/adjust-agents-md

0b514e7

mbarlow12 temporarily deployed to development July 9, 2026 19:04 — with GitHub Actions Inactive

mbarlow12 temporarily deployed to development July 9, 2026 19:05 — with GitHub Actions Inactive

mbarlow12 had a problem deploying to development July 9, 2026 19:06 — with GitHub Actions Failure

mbarlow12 temporarily deployed to development July 9, 2026 19:06 — with GitHub Actions Inactive

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Curate AGENTS.md#166

Curate AGENTS.md#166
mbarlow12 wants to merge 7 commits into
mainfrom
feat/adjust-agents-md

mbarlow12 commented Jul 9, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 9, 2026

Uh oh!

github-actions Bot commented Jul 9, 2026

Uh oh!

github-actions Bot commented Jul 9, 2026

Uh oh!

AlexAxthelm left a comment

Uh oh!

Uh oh!

AlexAxthelm Jul 9, 2026

Uh oh!

Uh oh!

AlexAxthelm Jul 9, 2026

Uh oh!

github-actions Bot commented Jul 9, 2026

Uh oh!

github-actions Bot commented Jul 9, 2026

Uh oh!

github-actions Bot commented Jul 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		## CI gates that will fail a PR

		- A forbidden-patterns scan (`.github/workflows/admin-forbidden-patterns.yml`) blocks

Uh oh!

Conversation

mbarlow12 commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 9, 2026

CD summary 5df28d2

Uh oh!

github-actions Bot commented Jul 9, 2026

CD summary d1b3daa

Uh oh!

github-actions Bot commented Jul 9, 2026

CD summary 646f404

Uh oh!

AlexAxthelm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AlexAxthelm Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AlexAxthelm Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 9, 2026

CD summary 0d47e8d

Uh oh!

github-actions Bot commented Jul 9, 2026

CD summary 0b514e7

Uh oh!

github-actions Bot commented Jul 9, 2026

CD summary f297a70

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mbarlow12 commented Jul 9, 2026 •

edited

Loading

CD summary `5df28d2`

CD summary `d1b3daa`

CD summary `646f404`

CD summary `0d47e8d`

CD summary `0b514e7`

CD summary `f297a70`