Skip to content

Curate AGENTS.md - #166

Open
mbarlow12 wants to merge 8 commits into
mainfrom
feat/adjust-agents-md
Open

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

Conversation

@mbarlow12

@mbarlow12 mbarlow12 commented Jul 9, 2026

Copy link
Copy Markdown
Contributor

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).

@github-actions

github-actions Bot commented Jul 9, 2026

Copy link
Copy Markdown

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

github-actions Bot commented Jul 9, 2026

Copy link
Copy Markdown

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

github-actions Bot commented Jul 9, 2026

Copy link
Copy Markdown

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

github-actions Bot commented Jul 9, 2026

Copy link
Copy Markdown

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

github-actions Bot commented Jul 9, 2026

Copy link
Copy Markdown

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

@github-actions

Copy link
Copy Markdown

CD summary 0b514e7

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: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

Comment thread AGENTS.md
# Stitch — Agent Guidance

Stitch integrates diverse oil & gas asset datasets, applies AI-driven enrichment with human
review, and delivers curated, trustworthy data. This file captures the things that aren't

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

This is taken straight from the README, so it will be in context already. Should we reserve AGENTS.md for instructions and information it won't otherwise get?

Comment thread AGENTS.md
Pointers: [`HACKING.md`](./HACKING.md) (setup & day-to-day workflow) ·
[`ARCHITECTURE.md`](./ARCHITECTURE.md) · [`CONTRIBUTING.md`](./CONTRIBUTING.md) ·
[`deployments/CI_DEPLOYMENTS.md`](./deployments/CI_DEPLOYMENTS.md) (deploy pipeline) ·
[`deployments/PERFORMANCE.md`](./deployments/PERFORMANCE.md) (query-layer performance).

@john john Jul 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Same comment as above--these are linked from the README, so why are they necessary here? If we're concerned README material will fall out of context, we might be able to be more economical in AGENTS if there's just a line saying "Read the README"

Skimmed the rest and that will be my general comment--most of what's been added already exists in top-level *.md files. I think we should do some research about how agents treat existing docs vs AGENTS, so we can take advantage of this new file while reducing duplication as much as possible. It's not just that adding that material bumps other material, given suggested length limits for AGENTS, it also means there's no longer one source of truth, we'll have to keep two files updated if anything changes.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Addressed in #195

@jdhoffa

jdhoffa commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

Recommend that we close this in favour of #195
fyi @john @mbarlow12

@jdhoffa

jdhoffa commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

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).

Just for what it's worth, I think the spirit of #154 was precisely to orient us around more similar workflows and development patterns.

In light of the fact that we don't really have a mechanism to enforce a common generic AGENTS.md across all SPD, doing so in a repo-specific way is the next best way to orient more common practices across the team.

That said, repo-specific guidance is definitely still valuable, however it is already well-documented (for humans) in the appropriate root-level .md files.

#195 handles this in a much simpler and less destructive diff
Screenshot 2026-07-24 at 14 37 00
vs.
Screenshot 2026-07-24 at 14 37 12

@github-actions

Copy link
Copy Markdown

CD summary b3c7e60

Deployments (3)
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
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:77ab71e6bdd76219b672a25cc6ba4ab76ad967676803cee7e148aa88f7ad77f3 pr_166
Images (4)
build_time commit_time git_sha image image_digest
2026-07-30T08:04:39Z 2026-07-30T08:02:33Z 7f94438 ghcr.io/rmi/stitch-api:pr-166 ghcr.io/rmi/stitch-api:pr-166@sha256:77ab71e6bdd76219b672a25cc6ba4ab76ad967676803cee7e148aa88f7ad77f3
2026-07-30T08:04:39Z 2026-07-30T08:02:33Z 7f94438 ghcr.io/rmi/stitch-entity-linkage:pr-166 ghcr.io/rmi/stitch-entity-linkage:pr-166@sha256:23c05d2a52a2593e1727c3899f16fc0e25b642694cfd6a847ebaceacb44ae0ac
2026-07-30T08:04:40Z 2026-07-30T08:02:33Z 7f94438 ghcr.io/rmi/stitch-seed:pr-166 ghcr.io/rmi/stitch-seed:pr-166@sha256:3150ae5775fde42819a33683e15838f7a7c62c1a62613f34eac023f726ea441b
2026-07-30T08:04:43Z 2026-07-30T08:02:33Z 7f94438 ghcr.io/rmi/stitch-stitch-llm:pr-166 ghcr.io/rmi/stitch-stitch-llm:pr-166@sha256:bcbe5dc9be9f4bed7ed357785305075df26b61f662e961a11f7dc770e49a9d37

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants