Feat/added AGENTS.md by john · Pull Request #154 · RMI/stitch

john · 2026-06-30T20:03:11Z

What changed

Adds a project-scoped AGENTS.md to top level of repo.

Verification

Pull, ask the AI if this file is visible. Maybe ask it to do something crazy in direct defiance of what's in the file, see if it pushes back and references its instructions (do this in plan mode!)

Human review

This has worked well for me generally but could probably be specifically tuned for Stitch. My inclination is that once reviewed, if there are no issues, merge to main as is and iterate.

Copilot

Pull request overview

Adds a new top-level AGENTS.md intended to guide AI agents working in this repository.

Changes:

Introduces AGENTS.md with operating principles, guardrails, and workflow guidance for AI-assisted changes.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

github-actions · 2026-06-30T20:07:16Z

CD summary `be2ea62`

Deployments (3)

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

Database (1)

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

Jobs (2)

job	image	postgres_db	api_url	auth_mode
db-migrations	`ghcr.io/rmi/stitch-api:pr-154@sha256:1982f01b3355dd025343c29659320ac057fc97cd2c4969bf9b4f4cf2c8ead336`	`pr_154`
seed	`ghcr.io/rmi/stitch-seed:pr-154@sha256:922284d2be983eacde4a9bb9db2b3febfc67c99709c879a31ed90693131f72e2`		`https://pr-154-api.purplegrass-c07d0a94.westus2.azurecontainerapps.io/api/v1`	`stitch-client-bearer-token`

Images (4)

build_time	commit_time	git_sha	image	image_digest
2026-06-30T20:03:30Z	2026-06-30T20:03:11Z	`7a036b1`	`ghcr.io/rmi/stitch-api:pr-154`	`ghcr.io/rmi/stitch-api:pr-154@sha256:1982f01b3355dd025343c29659320ac057fc97cd2c4969bf9b4f4cf2c8ead336`
2026-06-30T20:03:27Z	2026-06-30T20:03:11Z	`7a036b1`	`ghcr.io/rmi/stitch-entity-linkage:pr-154`	`ghcr.io/rmi/stitch-entity-linkage:pr-154@sha256:42d4c385f9c8c537fc379512273d96ce456104cb1abd59fd1856770099aeb7ff`
2026-06-30T20:03:26Z	2026-06-30T20:03:11Z	`7a036b1`	`ghcr.io/rmi/stitch-seed:pr-154`	`ghcr.io/rmi/stitch-seed:pr-154@sha256:922284d2be983eacde4a9bb9db2b3febfc67c99709c879a31ed90693131f72e2`
2026-06-30T20:03:26Z	2026-06-30T20:03:11Z	`7a036b1`	`ghcr.io/rmi/stitch-stitch-llm:pr-154`	`ghcr.io/rmi/stitch-stitch-llm:pr-154@sha256:661c63b0be4cad2fad433486fa7d4e01d8de2048304d5500119d2dab3735d703`

jdhoffa · 2026-07-01T11:27:13Z

+## Testing
+
+* Test changes proportionally to their risk.
+* Prefer existing test patterns and frameworks.
+* Add tests when introducing new behavior or fixing bugs where practical.
+* Do not claim something works without verification.


I have found success using this as a CLAUDE.md (with very few changes): https://github.com/multica-ai/andrej-karpathy-skills

The only substantive difference between the karpathy skills and the ones proposed in this PR is around "Goal-driven execution" which essentially asks the robot to conduct test driven development (https://github.com/multica-ai/andrej-karpathy-skills#4-goal-driven-execution)

@john thoughts about adopting that approach?

I think it depends how we ask it to do this and whether or not we want to put ourselves inside that loop. If it's ""Write tests for invalid inputs, then make them pass," and it does that itself, that's great (and what I've seen it do on its own). If it's "Agent writes tests for invalid inputs, human checks them out, then agent make them pass" I'm not keen on it, honestly I think we apply more scrutiny than we should. As Karpathy says, "These guidelines bias toward caution over speed," which if you're Andrej Karpathy and responsible for pre-training Claude, yes of course. Stakes are low for us and I'd rather prioritize speed.

But to that point if you'd prefer to add that and it gets this merged I'm totally fine with it, I defer to your experience. I presume it would merit its own section, perhaps above or below "Working Style"?

A great deal of the work we've set up around non-local (shared PR previews and CI) dev work has an implict philosophy of "caution over speed". The robot is fast enough on its own. Keeping the option of tighter human review (the invalid test workflow you mentioned, or anything where progress is incremental over one-shot) should be considered valid, and perhaps encouraged.

Don't get me wrong, I didn't mean to imply speed uber alles. More like, increasing relative to historical baseline, rather than reckless.

The PR previews and CI I'm super excited about, they feel like win-wins--good tooling and guardrails make it safer to go fast.

jdhoffa

Q: @john I suspect that you've used this AGENTS.md personally on other projects? How have you found that it handles small / trivial changes? Does it recognize that the change is tiny and skip to implementation, or does it arduously go through all instructions here?

I've proposed a few changes that could better align this with https://github.com/multica-ai/andrej-karpathy-skills/blob/main/CLAUDE.md

Better H1 Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

More specific bullet, avoids redundancy Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

mbarlow12

Generally, I think we can go ahead and merge then iterate on the details. We get the benefit of trying it out, checking agent results/behavior, and make targeted changes as we go.

One minor fix (covered in #158): Per Anthropic docs, Claude Code only reads CLAUDE.md, so a single @AGENTS.md line in CLAUDE.md gets all agents working harmoniously 👼 off the same context file.

Regarding the content itself, (NB) it's probably a bit too generic, so swapping in more stitch-specific guidance will be more useful in the long run.

Name real commands: make check before pushing, tight loops like make api-test/make stitch-llm-test/make frontend-test/make pkg-test-<name>.
Link HACKING.md, ARCHITECTURE.md, CONTRIBUTING.md (via @) and remove overlapping/redundant content
Trim the duplicated lines (the UX ones Copilot/Alex flagged).
Later, consider per-area CLAUDE.md files (deployments/api, deployments/stitch-frontend, packages/) — Claude lazy-loads the nearest one, so a11y goes with the frontend, migrations with the api, etc.

As we refine, it's worth thinking about the aspects of our development practices that an agent could not learn from reading files in the repo.

specific steps the agent should take before doing X. E.g.
- "Run make check before committing changes."
- "Search latest dependency documentation when responding in Plan mode."
doc/sharepoint references or Jira guidance
- "Relevant jira issues have been written to md files under docs/jira/"
- "Use acli jira ... to surface relevant project task information"
tree output or quick repo structure index (probably better suited for ARCHITECTURE.md)
commands to check build CI/CD outputs/logs/status
PR review steps/guidelines (though there are a lot of skills that handle this)
proactive skill/tool use ("Use the context7 MCP to ground your responses in up-to-date documentation")

mbarlow12 · 2026-07-02T20:58:14Z

+* Prefer parameterized queries and framework-native escaping.
+* Call out security-sensitive changes explicitly.
+
+## User Experience


Is the "user" here the Claude Code/Codex user or the stitch end-user? If it's the latter, I think a tightly-scope CLAUDE/AGENTS.md located in deployments/stitch-frontend would get us more mileage when providing direction.

AlexAxthelm · 2026-07-03T09:33:24Z

One more comment on the overall structure here, this only works for folks using Claude Code or ChatGPT Codex. So if I am having Claude (chat) interrogate the codebase and iterating on a plan that I'll later hand over to a code session, then this file doesn't have any special powers (Claude Chat acknowleges its existence, but otherwise entirely ignores it).

add CLAUDE.md that imports AGENTS.md

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

github-actions · 2026-07-07T09:31:13Z

CD summary `7e0cab2`

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

Deployments (4)

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

Database (1)

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

Jobs (1)

job	image	postgres_db
db-migrations	`ghcr.io/rmi/stitch-api:pr-154@sha256:c0ab3eff92fea485f9ee0955ff5d0531b8dde14db0c110a31bea5d21215b52a8`	`pr_154`

Images (4)

build_time	commit_time	git_sha	image	image_digest
2026-07-07T09:27:15Z	2026-07-07T09:27:01Z	`2a018f7`	`ghcr.io/rmi/stitch-api:pr-154`	`ghcr.io/rmi/stitch-api:pr-154@sha256:c0ab3eff92fea485f9ee0955ff5d0531b8dde14db0c110a31bea5d21215b52a8`
2026-07-07T09:27:19Z	2026-07-07T09:27:01Z	`2a018f7`	`ghcr.io/rmi/stitch-entity-linkage:pr-154`	`ghcr.io/rmi/stitch-entity-linkage:pr-154@sha256:f8bb8fa795c8cc528b14a2cd00f44d2294a43d46bfe000cf351e245c329f2468`
2026-07-07T09:27:19Z	2026-07-07T09:27:01Z	`2a018f7`	`ghcr.io/rmi/stitch-seed:pr-154`	`ghcr.io/rmi/stitch-seed:pr-154@sha256:4bc09b91c604c1ab25c84a6ccf6c224622424f05f3da8288c440715d1539471a`
2026-07-07T09:27:15Z	2026-07-07T09:27:01Z	`2a018f7`	`ghcr.io/rmi/stitch-stitch-llm:pr-154`	`ghcr.io/rmi/stitch-stitch-llm:pr-154@sha256:4f5c423c0bdc8ba2ba8390b9bc17d17230a3961d77f24d82ba1403b786dd1ddb`

github-actions · 2026-07-07T09:31:49Z

CD summary `b6c4731`

Database (1)

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

Jobs (1)

job	image	postgres_db
db-migrations	`ghcr.io/rmi/stitch-api:pr-154@sha256:4a5689b96d66ede77db280aae23ddc7fc56573e967defca98612531454ab98a1`	`pr_154`

Images (4)

build_time	commit_time	git_sha	image	image_digest
2026-07-07T09:29:36Z	2026-07-07T09:29:19Z	`fa89709`	`ghcr.io/rmi/stitch-api:pr-154`	`ghcr.io/rmi/stitch-api:pr-154@sha256:4a5689b96d66ede77db280aae23ddc7fc56573e967defca98612531454ab98a1`
2026-07-07T09:29:35Z	2026-07-07T09:29:19Z	`fa89709`	`ghcr.io/rmi/stitch-entity-linkage:pr-154`	`ghcr.io/rmi/stitch-entity-linkage:pr-154@sha256:225cfd1c4d7b2a2e0990d251c3ded40885e9071fe70e67539d5e00fc1c5e7378`
2026-07-07T09:29:38Z	2026-07-07T09:29:19Z	`fa89709`	`ghcr.io/rmi/stitch-seed:pr-154`	`ghcr.io/rmi/stitch-seed:pr-154@sha256:f2da69fbc2c509efd6b2eabda65df5e666cc218a41256d6c1658507586e9e57b`
2026-07-07T09:29:36Z	2026-07-07T09:29:19Z	`fa89709`	`ghcr.io/rmi/stitch-stitch-llm:pr-154`	`ghcr.io/rmi/stitch-stitch-llm:pr-154@sha256:f4aeb56eb82ed3d2b870da6993b181b7496e28a3ab6c434aa058890ca257bffa`

github-actions · 2026-07-07T09:34:01Z

CD summary `e54061d`

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

Deployments (4)

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

Database (1)

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

Jobs (1)

job	image	postgres_db
db-migrations	`ghcr.io/rmi/stitch-api:pr-154@sha256:abd6f22ad4cb326eee3259880814ff1ca0f6aebe689487940b6595cf8e0518e9`	`pr_154`

Images (4)

build_time	commit_time	git_sha	image	image_digest
2026-07-07T09:30:05Z	2026-07-07T09:29:48Z	`5ed0019`	`ghcr.io/rmi/stitch-api:pr-154`	`ghcr.io/rmi/stitch-api:pr-154@sha256:abd6f22ad4cb326eee3259880814ff1ca0f6aebe689487940b6595cf8e0518e9`
2026-07-07T09:30:05Z	2026-07-07T09:29:48Z	`5ed0019`	`ghcr.io/rmi/stitch-entity-linkage:pr-154`	`ghcr.io/rmi/stitch-entity-linkage:pr-154@sha256:2614d13ef2508526d3f70d23aac95c04556b46aac36b22d3ce08f80a61f1848e`
2026-07-07T09:30:07Z	2026-07-07T09:29:48Z	`5ed0019`	`ghcr.io/rmi/stitch-seed:pr-154`	`ghcr.io/rmi/stitch-seed:pr-154@sha256:2c48e42d8117a0adc439a66be09ee73f212f929c95945ba4a97ce9410f80606c`
2026-07-07T09:30:06Z	2026-07-07T09:29:48Z	`5ed0019`	`ghcr.io/rmi/stitch-stitch-llm:pr-154`	`ghcr.io/rmi/stitch-stitch-llm:pr-154@sha256:4def6c337ad3d6a9dfe660736f2202fda5c10dc71f5cb877b0558b2087b57834`

github-actions · 2026-07-07T09:34:48Z

CD summary `3a2d1e8`

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

Deployments (4)

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

Database (1)

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

Jobs (1)

job	image	postgres_db
db-migrations	`ghcr.io/rmi/stitch-api:pr-154@sha256:1d2bcabdde15cf91b85e0700130eec510996776402f04d99fb8fc3b9d497e323`	`pr_154`

Images (4)

build_time	commit_time	git_sha	image	image_digest
2026-07-07T09:30:35Z	2026-07-07T09:30:14Z	`53fad45`	`ghcr.io/rmi/stitch-api:pr-154`	`ghcr.io/rmi/stitch-api:pr-154@sha256:1d2bcabdde15cf91b85e0700130eec510996776402f04d99fb8fc3b9d497e323`
2026-07-07T09:30:37Z	2026-07-07T09:30:14Z	`53fad45`	`ghcr.io/rmi/stitch-entity-linkage:pr-154`	`ghcr.io/rmi/stitch-entity-linkage:pr-154@sha256:cdd7ca382340e2dbf0c5e2a80c32564d2d03503735714720110833a44a395a9b`
2026-07-07T09:30:33Z	2026-07-07T09:30:14Z	`53fad45`	`ghcr.io/rmi/stitch-seed:pr-154`	`ghcr.io/rmi/stitch-seed:pr-154@sha256:309b904f693720eb5a210b01360e505eaa4c6bb56b1fe23a511215a9d3b0d258`
2026-07-07T09:30:32Z	2026-07-07T09:30:14Z	`53fad45`	`ghcr.io/rmi/stitch-stitch-llm:pr-154`	`ghcr.io/rmi/stitch-stitch-llm:pr-154@sha256:89f7260b4efb1e02a9136e0db8e78705630b8f8076dadc5d992e2ada6d43a984`

added AGENTS.md

be2ea62

john requested a review from Copilot June 30, 2026 20:03

john assigned jdhoffa Jun 30, 2026

john temporarily deployed to development June 30, 2026 20:03 — with GitHub Actions Inactive

Copilot started reviewing on behalf of john June 30, 2026 20:03 View session

john temporarily deployed to development June 30, 2026 20:04 — with GitHub Actions Inactive

Copilot AI reviewed Jun 30, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

Comment thread AGENTS.md Outdated

Comment thread AGENTS.md Outdated

john temporarily deployed to development June 30, 2026 20:04 — with GitHub Actions Inactive

john temporarily deployed to development June 30, 2026 20:05 — with GitHub Actions Inactive

john had a problem deploying to development June 30, 2026 20:06 — with GitHub Actions Failure

jdhoffa requested review from AlexAxthelm and mbarlow12 July 1, 2026 11:01

jdhoffa reviewed Jul 1, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

jdhoffa reviewed Jul 1, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

jdhoffa reviewed Jul 1, 2026

View reviewed changes

Comment thread AGENTS.md Outdated

jdhoffa reviewed Jul 1, 2026

View reviewed changes

Potential fix for pull request finding

4a2014a

Better H1 Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

john temporarily deployed to development July 1, 2026 18:57 — with GitHub Actions Inactive

Potential fix for pull request finding

3d6285c

More specific bullet, avoids redundancy Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

john temporarily deployed to development July 1, 2026 18:57 — with GitHub Actions Inactive

Potential fix for pull request finding

076d1fb

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

john temporarily deployed to development July 1, 2026 18:58 — with GitHub Actions Inactive

mbarlow12 approved these changes Jul 2, 2026

View reviewed changes

AlexAxthelm mentioned this pull request Jul 3, 2026

add CLAUDE.md that imports AGENTS.md #158

Merged

Merge pull request #158 from RMI/feat/claude-md-import

7e0cab2

add CLAUDE.md that imports AGENTS.md

jdhoffa temporarily deployed to development July 7, 2026 09:27 — with GitHub Actions Inactive

jdhoffa temporarily deployed to development July 7, 2026 09:28 — with GitHub Actions Inactive

jdhoffa temporarily deployed to development July 7, 2026 09:29 — with GitHub Actions Inactive

Update AGENTS.md

b6c4731

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

jdhoffa temporarily deployed to development July 7, 2026 09:29 — with GitHub Actions Inactive

Update AGENTS.md

e54061d

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

jdhoffa temporarily deployed to development July 7, 2026 09:30 — with GitHub Actions Inactive

Update AGENTS.md

3a2d1e8

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

jdhoffa temporarily deployed to development July 7, 2026 09:30 — with GitHub Actions Inactive

jdhoffa temporarily deployed to development July 7, 2026 09:31 — with GitHub Actions Inactive

jdhoffa temporarily deployed to development July 7, 2026 09:32 — with GitHub Actions Inactive

jdhoffa temporarily deployed to development July 7, 2026 09:33 — with GitHub Actions Inactive

Uh oh!

Conversation

john commented Jun 30, 2026

What changed

Verification

Human review

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Jun 30, 2026

CD summary be2ea62

Uh oh!

jdhoffa Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

john Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

AlexAxthelm Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

john Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jdhoffa left a comment

Choose a reason for hiding this comment

Uh oh!

mbarlow12 left a comment

Choose a reason for hiding this comment

Uh oh!

mbarlow12 Jul 2, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AlexAxthelm commented Jul 3, 2026

Uh oh!

github-actions Bot commented Jul 7, 2026

CD summary 7e0cab2

Uh oh!

github-actions Bot commented Jul 7, 2026

CD summary b6c4731

Uh oh!

github-actions Bot commented Jul 7, 2026

CD summary e54061d

Uh oh!

github-actions Bot commented Jul 7, 2026

CD summary 3a2d1e8

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

CD summary `be2ea62`

CD summary `7e0cab2`

CD summary `b6c4731`

CD summary `e54061d`

CD summary `3a2d1e8`