Improve agent orientation: project.md convention, jvm-project.md, Copilot instructions#666
Merged
Conversation
…nstructions - Introduce `.agents/project.md` as the repo-specific context file (Overview + Architecture), preserved by `migrate` across updates - Add `.agents/jvm-project.md` as the shared JVM requirements doc (build stack, coding style, tests, versioning) that project.md files link to - Add `.github/copilot-instructions.md` (project-neutral; universal safety rules + pointer to project.md); distributed to all repos by `migrate` - Strengthen `AGENTS.md` to peer with CLAUDE.md: full commit-safety rule, project.md orientation, other safety rules - Trim `quick-reference-card.md` to the one universal item: commit safety rule - Update `CLAUDE.md` to reference project.md and jvm-project.md conventions Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…, link style - Renumber _TOC.md items 3-22 (duplicate 3 after insertion) - Fix task frontmatter: branch master to improve-caching; add related-memories - Add template comment to project.md so agents do not read it as live context - Use footnote-style reference link for Kotest URL in jvm-project.md - Normalise .agents/ link paths in AGENTS.md (drop leading ./) - Align org name to Spine SDK organisation in copilot-instructions.md - Broaden cache-hygiene memory to include .agents/, .claude/, buildSrc/ Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 9fceaba816
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Contributor
There was a problem hiding this comment.
Pull request overview
This PR standardizes agent “orientation” across the Spine SDK org by introducing a repo-specific .agents/project.md convention (plus a shared .agents/jvm-project.md), distributing GitHub Copilot instructions via migrate, and adding prompt-caching hygiene guidance to team memory.
Changes:
- Add
.agents/project.md(repo context convention) and.agents/jvm-project.md(shared JVM requirements + review checklist), and update.agents/_TOC.mdaccordingly. - Strengthen agent guidance in
AGENTS.md/CLAUDE.md, and simplify the quick reference card to the commit/history safety rule. - Add Copilot instructions and prompt-caching task/memory docs; update
migrateto preserve an existing sibling repo’s.agents/project.mdand to copy Copilot instructions into target repos.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
migrate |
Preserves target repo .agents/project.md during .agents refresh; copies Copilot instructions into target .github/. |
CLAUDE.md |
Adds guidance to read .agents/project.md / shared requirement docs. |
AGENTS.md |
Adds orientation + explicit commit/history safety policy; reorganizes sections. |
.github/copilot-instructions.md |
Introduces universal Copilot rules and points to .agents/project.md and .agents/_TOC.md. |
.agents/tasks/prompt-caching-org.md |
Adds an org-level task plan for improving prompt caching hit rates. |
.agents/quick-reference-card.md |
Trims down to the single universal commit/history safety rule. |
.agents/project.md |
Adds a project.md template intended for sibling repos. |
.agents/memory/MEMORY.md |
Indexes new memory entries. |
.agents/memory/feedback/cache-hygiene.md |
Adds cache hygiene guidance for shared-config edits. |
.agents/memory/reference/cache-warm-window.md |
Documents practical cache TTL/windows and org/workspace implications. |
.agents/memory/reference/anthropic-api-caching.md |
Documents a cache_control pattern for future direct Anthropic API callers. |
.agents/jvm-project.md |
Adds shared JVM requirements + code review checklist. |
.agents/_TOC.md |
Adds the JVM requirements doc to the documentation index. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…SKILL.md cache verdict - Rename .agents/project.md to project.template.md so agents do not load the placeholder as live repo context; migrate seeds project.md from the template only when the target repo has none (simpler than preserve-and-restore) - Update CLAUDE.md to reference project.template.md as the starting point - Add mkdir -p ../.github before copying copilot-instructions.md in Hugo path to avoid cp failure on repos without an existing .github directory - Fix pre-pr SKILL.md: record cached check-links result as plain APPROVE with prose note, matching the PASS criteria and check-links SKILL.md convention Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…pre-pr SKILL.md - Notes section: add that the skill may auto-fix a missing version bump via /bump-version; all other fixes require explicit user confirmation - Sentinel section: restore the mention that pre-pr-gate.sh reads head= and status=, making clear the sentinel format is a hook contract not just a log Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Move universal rules (orientation, memory, quality, principles, task planning) from CLAUDE.md into AGENTS.md so Codex, Copilot, and Claude Code all read from a single source. CLAUDE.md becomes a thin @AGENTS.md wrapper plus Claude Code-specific notes.
Contributor
Author
alexander-yevsyukov
left a comment
alexander-yevsyukov
left a comment
There was a problem hiding this comment.
@copilot, please change the text as instructed. Commit the changes when done.
Contributor
Done in commit Updated the requested text in:
|
…ching # Conflicts: # .agents/skills/pre-pr/SKILL.md # .agents/tasks/setup-cross-tool-agent-instructions.md
alexander-yevsyukov
changed the title
project.md convention, jvm-project.md, Copilot instructions
Bare mktemp without a template fails on macOS's default mktemp. Use mktemp -t <name>.XXXXXX for all three temp-file calls. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…covery note to JVM repos In Hugo repos, migrate removes running-builds.md, so pre-pr Step 3 must treat a missing file as 'no documented command' rather than failing. Also qualifies the api-discovery bullet in CLAUDE.md as JVM-only, since migrate removes that skill from Hugo repos.
Step 2: only auto-invoke /bump-version when .agents/skills/bump-version/ exists; otherwise record a Must-fix for manual bump. Step 4: check skill directory exists before dispatching; skip with 'not applicable for this repo' note when absent (covers Hugo repos where migrate removes kotlin-review, dependency-audit, bump-version).
armiol
approved these changes
May 25, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
New conventions and orientation
.agents/project.mdconvention: repo-specific context (Overview + Architecture) read by all agents at session start;migrateseeds it from.agents/project.template.mdonly when the target repo has none.agents/jvm-project.mdas the shared JVM requirements doc (build stack, Kotlin/Java style, tests, versioning) thatproject.mdfiles link to.github/copilot-instructions.md— project-neutral universal safety rules + pointer toproject.md; distributed to all repos bymigrateAgent instruction consolidation
AGENTS.md: move universal rules (orientation, memory, verification & quality, core principles, task planning) fromCLAUDE.mdso Codex, Copilot, and Claude Code all read from a single source;CLAUDE.mdbecomes a thin@AGENTS.mdwrapper plus Claude Code-specific notescherry-pickto the git history safety prohibition inAGENTS.mdapi-discoverybullet inCLAUDE.mdto JVM repos (Hugo repos don't have that skill after migration)quick-reference-card.mdto its one universal item: the commit safety rulepre-prskill improvementsN/A→not-applicablethroughoutbuild=<command>andbuild_status=PASS|FAIL|skippedfieldsversion.gradle.ktsto the diff)build_status=skippedwhen no command is documented for the change type.agents/running-builds.md: treat as "no documented command" →build_status=skipped(Hugo repos don't have this file after migration)/bump-versionauto-fix and reviewer dispatch against missing skills (Hugo repos pruned bymigrate)check-linksresult to record plainAPPROVE; document auto-fix behaviour and sentinel contractmigraterobustnessmkdir -p ../.agentsguard beforeproject.mdrestore in both Hugo and JVM pathsmktempportability: usemktemp -t name.XXXXXXfor all three temp-file calls (baremktempfails on macOS)Settings
git pushfrom thedenylist in.claude/settings.json(it was silently overriding the existingallowrule)Team memory
feedback/copilot-review-request.md: GraphQLbotIdsis the only reliable path to request or re-request a Copilot PR review; the REST endpoint silently no-ops on re-requests🤖 Generated with Claude Code