Add DECISIONS.md guidance to starter AGENTS.md - #404
Merged
Merged
Conversation
Fusion's project-shape questionnaire already writes DECISIONS.md before the first build and injects a one-time read instruction into that first prompt (ai-services render-shape-decisions.ts). Make the same rule durable across every later session, and add the missing half: update DECISIONS.md when the user changes one of those decisions in chat. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
AGENTS.md is injected into the runtime chat agent's system prompt on every request and hard-truncated at COMPACT_PROMPT_RESOURCE_MAX_CHARS (6,000 chars); the starter's AGENTS.md was already past that (~6,900 chars) before this branch's own addition pushed it further. Most of the excess was dev-only guidance (choosing an auth landing route, SQL scaffolding pointers, verification cadence, config-vs-env-vars) that only matters to whoever is actively writing source for the app, not to every runtime turn. DEVELOPING.md already exists as the framework's development-mode-only guide and is not injected into the runtime prompt, so move that detail there and leave a short pointer in AGENTS.md. Net result: AGENTS.md drops to ~4,400 chars, comfortably under the cap with room to grow. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
CI checks the two hardcoded assertions in verify-starter-patch.yml independently of apply.mjs's own assertPatched(); these still expected the auth-landing-route guidance in AGENTS.md after the previous commit moved it to DEVELOPING.md, so the workflow failed even though the overlay itself applied correctly. Update the workflow's assertions to match, and add a check for the new short pointer left in AGENTS.md. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
lucia-builder
approved these changes
Sep 22, 2026
…PING.md AGENTS.md is injected into the runtime chat agent's system prompt on every request; DEVELOPING.md is not (see COMPACT_PROMPT_RESOURCE_MAX_CHARS in agent-native's prompt-resources.ts, and the loader that reads `instructions.runtime` but never `instructions.development`). Everything this overlay had been patching into AGENTS.md beyond the previous commit's move was actually about editing this app's source code, not about operating the deployed app for end users: the blank-canvas build-additively guidance, the DECISIONS.md check-and-update rule, and the i18n/changelog opt-in note. Move all of it into DEVELOPING.md and collapse AGENTS.md's own patches down to a single pointer sentence in the intro: "See DEVELOPING.md before making any source code change." The agent already reaches for DEVELOPING.md exactly when it's about to edit source, so the pointer does the real work; the content itself no longer needs to survive the 6,000-char runtime prompt cutoff at all. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The AGENTS.md pointer wraps across two lines at its natural markdown width, so the exact-phrase assertion never matched; check the unwrapped prefix instead. The migrated-tree duplicate-content guard for the i18n/changelog note still pointed at AGENTS.md after the previous commit moved that text to DEVELOPING.md. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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
2 participants
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.
We can merge this after the work in devtools and elsewhere is merged to write the DECISIONS.md file. I think we likely will want to play around with this. We might want it to have some awareness of whether or not the decisions have already been accounted for. I can imagine it unnecessarily reading the DECISIONS.md file on subsequent prompts as well with the current implementation
Summary
DECISIONS.mdbefore the first build and injects a one-time instruction to read it into the first prompt (ai-servicesrender-shape-decisions.ts). This adds the same rule to the starter'sAGENTS.mdso it's durable across every later session, not just the first prompt, plus the missing half: if the user changes one of those decisions later in chat, updateDECISIONS.mdto match.AGENTS.mdwas already pastCOMPACT_PROMPT_RESOURCE_MAX_CHARS(6,000 chars, the hard truncation limit for what gets injected into the runtime chat agent's system prompt) before this branch's own addition pushed it further. Most of the excess was dev-workflow guidance (choosing an auth landing route, SQL scaffolding pointers, verification cadence, config-vs-env-vars) that only matters to whoever is actively writing source for the app — not something every runtime chat turn needs, and not something a coding agent needs repeated in the same file the production agent reads.DEVELOPING.mdalready exists as the framework's development-mode-only guide (it is not injected into the runtime prompt), so that detail moved there andAGENTS.mdkeeps a short pointer instead. Net:AGENTS.mddrops from ~6,900/~7,100 chars to ~4,400, comfortably under the cap with room to grow.Test plan
node .github/starter-patch/apply.mjs --root <preview>applies cleanly andassertPatchedpassesAGENTS.mdandDEVELOPING.mdrender correctly andAGENTS.mdis under the 6,000-char runtime cap🤖 Generated with Claude Code