mguinada · October 16, 2025 22:01 · Jul 23, 2025 · Jul 23, 2025 · Jul 23, 2025 · Jul 22, 2025
diff --git a/prompt-for-agents.md-generation.md b/prompt-for-agents.md-generation.md
@@ -1,3 +1,4 @@
+```markdown
 ### ABOUT
 Modern AI coding tools converge on a simple idea: give the agent a **single, well-structured Markdown file that explains how your repo “works,”** and prepend that file to every LLM call so the agent never has to guess about architecture, commands, or conventions. Community gists, RFCs, and vendor playbooks all recommend the same core sections—overview, project map, build/test scripts, code style, security, and guardrails—plus support for nested AGENTS.md files that override one another hierarchically.
 
@@ -35,3 +36,4 @@ Produce Markdown exactly in this order:
 ### OUTPUT
 
 Return only the completed AGENTS.md content; do not wrap it in JSON or additional commentary.
+```
diff --git a/prompt-for-agents.md-generation.md b/prompt-for-agents.md-generation.md
@@ -1,4 +1,3 @@
-````text
 ### ABOUT
 Modern AI coding tools converge on a simple idea: give the agent a **single, well-structured Markdown file that explains how your repo “works,”** and prepend that file to every LLM call so the agent never has to guess about architecture, commands, or conventions. Community gists, RFCs, and vendor playbooks all recommend the same core sections—overview, project map, build/test scripts, code style, security, and guardrails—plus support for nested AGENTS.md files that override one another hierarchically.
 

diff --git a/prompt-for-agents.md-generation.md b/prompt-for-agents.md-generation.md
@@ -1,10 +1,7 @@
-Modern AI coding tools converge on a simple idea: give the agent a **single, well-structured Markdown file that explains how your repo “works,”** and prepend that file to every LLM call so the agent never has to guess about architecture, commands, or conventions. Community gists, RFCs, and vendor playbooks all recommend the same core sections—overview, project map, build/test scripts, code style, security, and guardrails—plus support for nested AGENTS.md files that override one another hierarchically.  The prompt below wraps those best-practices into a **single, reusable instruction** you can hand to any LLM (ChatGPT, Claude, Gemini, etc.) to generate an AGENTS.md that’s both human-readable and machine-parsable.
-
----
-
-## Copy-and-paste Prompt Template
-
 ````text
+### ABOUT
+Modern AI coding tools converge on a simple idea: give the agent a **single, well-structured Markdown file that explains how your repo “works,”** and prepend that file to every LLM call so the agent never has to guess about architecture, commands, or conventions. Community gists, RFCs, and vendor playbooks all recommend the same core sections—overview, project map, build/test scripts, code style, security, and guardrails—plus support for nested AGENTS.md files that override one another hierarchically.
+
 ### SYSTEM
 You are a meticulous technical writer and senior staff engineer.  
 Your task is to create **AGENTS.md** for the repository whose contents are provided below.
@@ -39,21 +36,3 @@ Produce Markdown exactly in this order:
 ### OUTPUT
 
 Return only the completed AGENTS.md content; do not wrap it in JSON or additional commentary.
-
-```
-
----
-
-## Why these pieces matter
-
-| Section | Rationale | Key Sources |
-|---------|-----------|-------------|
-| **Repository Structure** | Agents work best when they have a “sitemap” of the codebase rather than prose wanderings.:contentReference[oaicite:1]{index=1} | Reddit best-practice thread |
-| **Build/Test Commands** | Tools like Claude Code or Cursor run these commands verbatim; documenting them prevents false guesses.:contentReference[oaicite:2]{index=2} | Medium case study |
-| **Code Style** | Agents generating patches must match project linting to avoid noisy diffs.:contentReference[oaicite:3]{index=3} | Codex AGENTS.md gist |
-| **Architecture Diagram** | A lightweight visual gives the LLM a mental model and improves tool-planning accuracy.:contentReference[oaicite:4]{index=4} | LangGraph agent-architecture guide |
-| **Security & Guardrails** | OpenAI’s agent guide stresses explicit guardrails to avoid unsafe actions.:contentReference[oaicite:5]{index=5} | OpenAI practical guide |
-| **Hierarchical Overrides** | Root + sub-directory AGENTS.md files let large monorepos fine-tune agent behaviour.:contentReference[oaicite:6]{index=6} | Sourcegraph RFC |
-| **Extensibility Hooks** | Encourages modular, multi-agent orchestration patterns described by Anthropic.:contentReference[oaicite:7]{index=7} | Anthropic engineering blog |
-
----
diff --git a/prompt-for-agents.md-generation.md b/prompt-for-agents.md-generation.md
@@ -0,0 +1,59 @@
+Modern AI coding tools converge on a simple idea: give the agent a **single, well-structured Markdown file that explains how your repo “works,”** and prepend that file to every LLM call so the agent never has to guess about architecture, commands, or conventions. Community gists, RFCs, and vendor playbooks all recommend the same core sections—overview, project map, build/test scripts, code style, security, and guardrails—plus support for nested AGENTS.md files that override one another hierarchically.  The prompt below wraps those best-practices into a **single, reusable instruction** you can hand to any LLM (ChatGPT, Claude, Gemini, etc.) to generate an AGENTS.md that’s both human-readable and machine-parsable.
+
+---
+
+## Copy-and-paste Prompt Template
+
+````text
+### SYSTEM
+You are a meticulous technical writer and senior staff engineer.  
+Your task is to create **AGENTS.md** for the repository whose contents are provided below.
+
+### CONTEXT (replace the JSON blocks)
+See the attached files.
+
+### REQUIRED SECTIONS
+
+Produce Markdown exactly in this order:
+
+1. `# Project Overview` – one-paragraph description and elevator pitch.
+2. `## Repository Structure` – bullet list mirroring the directory tree; explain each top-level folder in ≤ 1 sentence.
+3. `## Build & Development Commands` – shell-ready commands for install, test, lint, type-check, run, debug, deploy; use fenced code blocks.
+4. `## Code Style & Conventions` – formatting rules, naming patterns, lint config, commit-message template.
+5. `## Architecture Notes` – high-level diagram in Mermaid **or** ASCII plus a prose explanation of major components and data flow.
+6. `## Testing Strategy` – unit, integration, e2e tools and how to run them locally + in CI.
+7. `## Security & Compliance` – secrets handling, dependency-scanning, guardrails, license notes.
+8. `## Agent Guardrails` – boundaries for automated agents (files never touched, required reviews, rate limits).
+9. `## Extensibility Hooks` – plugin points, env vars, feature flags.
+10. `## Further Reading` – relative links to deeper docs (docs/ARCH.md, ADRs, etc.).
+
+### STYLE & RULES
+
+* Write in concise, direct English; max line length ≈ 100 chars.
+* Use **Markdown** only—no HTML.
+* Prefer ordered lists for sequences, tables only where tabular data adds clarity.
+* Do **NOT** invent details; if information is missing, insert a `> TODO:` marker.
+* Keep total tokens ≤ 12 k. If input tree is huge, summarise less-critical sub-dirs.
+* Preserve any existing build commands verbatim.
+
+### OUTPUT
+
+Return only the completed AGENTS.md content; do not wrap it in JSON or additional commentary.
+
+```
+
+---
+
+## Why these pieces matter
+
+| Section | Rationale | Key Sources |
+|---------|-----------|-------------|
+| **Repository Structure** | Agents work best when they have a “sitemap” of the codebase rather than prose wanderings.:contentReference[oaicite:1]{index=1} | Reddit best-practice thread |
+| **Build/Test Commands** | Tools like Claude Code or Cursor run these commands verbatim; documenting them prevents false guesses.:contentReference[oaicite:2]{index=2} | Medium case study |
+| **Code Style** | Agents generating patches must match project linting to avoid noisy diffs.:contentReference[oaicite:3]{index=3} | Codex AGENTS.md gist |
+| **Architecture Diagram** | A lightweight visual gives the LLM a mental model and improves tool-planning accuracy.:contentReference[oaicite:4]{index=4} | LangGraph agent-architecture guide |
+| **Security & Guardrails** | OpenAI’s agent guide stresses explicit guardrails to avoid unsafe actions.:contentReference[oaicite:5]{index=5} | OpenAI practical guide |
+| **Hierarchical Overrides** | Root + sub-directory AGENTS.md files let large monorepos fine-tune agent behaviour.:contentReference[oaicite:6]{index=6} | Sourcegraph RFC |
+| **Extensibility Hooks** | Encourages modular, multi-agent orchestration patterns described by Anthropic.:contentReference[oaicite:7]{index=7} | Anthropic engineering blog |
+
+---