From 8515012cacb0a96a77463a64ca474cf71e90f46e Mon Sep 17 00:00:00 2001 From: Henry Chu Date: Tue, 1 Sep 2026 09:23:11 -0400 Subject: [PATCH 1/3] docs: add md-structure alignment prompt for other repos --- MD_STRUCTURE_PROMPT.md | 45 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) create mode 100644 MD_STRUCTURE_PROMPT.md diff --git a/MD_STRUCTURE_PROMPT.md b/MD_STRUCTURE_PROMPT.md new file mode 100644 index 000000000000..18882b29b15c --- /dev/null +++ b/MD_STRUCTURE_PROMPT.md @@ -0,0 +1,45 @@ +# Prompt: align a repo's markdown files to this structure + +Copy everything below this line into another session. + +--- + +Restructure this repo's markdown files to follow this layout and these principles. Do not invent +new policy — extract rules that already exist (in conversation history, code comments, scattered +docs) and consolidate them. + +## Target layout +- `AGENTS.md` (root): the single canonical agent-rules file. No nested AGENTS.md/CLAUDE.md files + anywhere else. If `CLAUDE.md` exists, make it the single line `@AGENTS.md`. +- `docs/README.md`: index hub with two sections — user-facing guides, then maintainer/contributor + docs. Every md file must be reachable from an index. +- `docs/user/*.md`: task-oriented user guides, one topic per file. +- `docs/internals/*.md`: deep architecture/boundary docs. +- `README.md` (root): what the product is, requirements, quick start, a table linking each user + guide, how this project differs from its upstream/origin (if a fork), and the verification + commands. +- `CONTRIBUTING.md`: short — pointers to AGENTS.md and the internals doc, verification expectations, + commit/hygiene rules. +- `SECURITY.md` (if applicable): supported boundary, reporting process, dependency review. + +## AGENTS.md required sections, in order +1. One-paragraph identity: what this project is and isn't. +2. A "read `` before changing ``" pointer. +3. Non-negotiable boundary: hard rules written as explicit prohibitions. Allowed exceptions are + enumerated individually, each scoped to its own mechanism with exact limits (sizes, counts, + paths), and state what the exception does NOT authorize. +4. Supported platforms/environments. +5. Code layout: one line per package/directory describing its responsibility. +6. Verification: exact commands to run, plus which checks NOT to run (e.g. "use the smallest + relevant checks, not repository-wide legacy suites"). +7. Working practices: preferred tooling, source-of-truth conventions, git hygiene (preserve + unrelated changes, no destructive commands, never commit secrets/scratch notes/generated output), + and anything that must never be done proactively (commits, PRs). + +## Writing principles +- Single source of truth per topic; cross-link instead of duplicating content between files. +- Declare the source of truth explicitly wherever two docs could drift (e.g. "upstream X is the + source of truth for shared behavior; adapt, don't re-derive"). +- Prefer concrete, testable rules over vague guidance — exact versions, limits, and paths. +- Keep each file short; move depth into docs/ and leave pointers in root files. +- After restructuring, verify every link resolves and report a summary of what moved where. From d254f64a47968683c3de63c5c96308ea0afa9819 Mon Sep 17 00:00:00 2001 From: Henry Chu Date: Tue, 1 Sep 2026 09:30:35 -0400 Subject: [PATCH 2/3] docs: preserve scoped rules, single doc index, cleanup note --- MD_STRUCTURE_PROMPT.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/MD_STRUCTURE_PROMPT.md b/MD_STRUCTURE_PROMPT.md index 18882b29b15c..3c2b0db3f776 100644 --- a/MD_STRUCTURE_PROMPT.md +++ b/MD_STRUCTURE_PROMPT.md @@ -1,6 +1,7 @@ # Prompt: align a repo's markdown files to this structure -Copy everything below this line into another session. +Scratch file for copy-paste only — delete it after copying. Copy everything below the line into +another session. --- @@ -9,15 +10,19 @@ new policy — extract rules that already exist (in conversation history, code c docs) and consolidate them. ## Target layout -- `AGENTS.md` (root): the single canonical agent-rules file. No nested AGENTS.md/CLAUDE.md files - anywhere else. If `CLAUDE.md` exists, make it the single line `@AGENTS.md`. -- `docs/README.md`: index hub with two sections — user-facing guides, then maintainer/contributor - docs. Every md file must be reachable from an index. +- `AGENTS.md` (root): the single canonical agent-rules file. If `CLAUDE.md` exists, make it the + single line `@AGENTS.md`. Before removing any nested `AGENTS.md`/`CLAUDE.md` files, inventory + them, record which rules are scoped to their directory, and merge still-valid scoped rules into + the root file — never silently delete existing guidance. Keep a nested file only when its rules + are genuinely directory-scoped and conflict with nothing at the root. +- `docs/README.md`: the canonical index hub, with two sections — user-facing guides, then + maintainer/contributor docs. Every md file must be reachable from this index. Where two indexes + could exist, this one wins; other files link to it rather than re-listing the guides. - `docs/user/*.md`: task-oriented user guides, one topic per file. - `docs/internals/*.md`: deep architecture/boundary docs. -- `README.md` (root): what the product is, requirements, quick start, a table linking each user - guide, how this project differs from its upstream/origin (if a fork), and the verification - commands. +- `README.md` (root): what the product is, requirements, quick start, a link to the canonical docs + index (`docs/README.md`) instead of its own guide list, how this project differs from its + upstream/origin (if a fork), and the verification commands. - `CONTRIBUTING.md`: short — pointers to AGENTS.md and the internals doc, verification expectations, commit/hygiene rules. - `SECURITY.md` (if applicable): supported boundary, reporting process, dependency review. From 7aa3a3041ea16a269afe15f2ac6fb2756fd490ae Mon Sep 17 00:00:00 2001 From: Henry Chu Date: Tue, 6 Oct 2026 08:38:16 -0400 Subject: [PATCH 3/3] docs: align md-structure prompt with upstream t3code docs layout Add an approval-gated process, keep directory-scoped nested agent files, add docs/operations, and adopt upstream's documentation rules. Co-Authored-By: Claude Opus 5.5 --- MD_STRUCTURE_PROMPT.md | 106 ++++++++++++++++++++++++----------------- 1 file changed, 62 insertions(+), 44 deletions(-) diff --git a/MD_STRUCTURE_PROMPT.md b/MD_STRUCTURE_PROMPT.md index 3c2b0db3f776..5dcfec7440ba 100644 --- a/MD_STRUCTURE_PROMPT.md +++ b/MD_STRUCTURE_PROMPT.md @@ -1,50 +1,68 @@ # Prompt: align a repo's markdown files to this structure -Scratch file for copy-paste only — delete it after copying. Copy everything below the line into +Scratch file for copy-paste only — never merge this PR. Copy everything below the line into another session. --- -Restructure this repo's markdown files to follow this layout and these principles. Do not invent -new policy — extract rules that already exist (in conversation history, code comments, scattered -docs) and consolidate them. - -## Target layout -- `AGENTS.md` (root): the single canonical agent-rules file. If `CLAUDE.md` exists, make it the - single line `@AGENTS.md`. Before removing any nested `AGENTS.md`/`CLAUDE.md` files, inventory - them, record which rules are scoped to their directory, and merge still-valid scoped rules into - the root file — never silently delete existing guidance. Keep a nested file only when its rules - are genuinely directory-scoped and conflict with nothing at the root. -- `docs/README.md`: the canonical index hub, with two sections — user-facing guides, then - maintainer/contributor docs. Every md file must be reachable from this index. Where two indexes - could exist, this one wins; other files link to it rather than re-listing the guides. -- `docs/user/*.md`: task-oriented user guides, one topic per file. -- `docs/internals/*.md`: deep architecture/boundary docs. -- `README.md` (root): what the product is, requirements, quick start, a link to the canonical docs - index (`docs/README.md`) instead of its own guide list, how this project differs from its - upstream/origin (if a fork), and the verification commands. -- `CONTRIBUTING.md`: short — pointers to AGENTS.md and the internals doc, verification expectations, - commit/hygiene rules. -- `SECURITY.md` (if applicable): supported boundary, reporting process, dependency review. - -## AGENTS.md required sections, in order -1. One-paragraph identity: what this project is and isn't. -2. A "read `` before changing ``" pointer. -3. Non-negotiable boundary: hard rules written as explicit prohibitions. Allowed exceptions are - enumerated individually, each scoped to its own mechanism with exact limits (sizes, counts, - paths), and state what the exception does NOT authorize. -4. Supported platforms/environments. -5. Code layout: one line per package/directory describing its responsibility. -6. Verification: exact commands to run, plus which checks NOT to run (e.g. "use the smallest - relevant checks, not repository-wide legacy suites"). -7. Working practices: preferred tooling, source-of-truth conventions, git hygiene (preserve - unrelated changes, no destructive commands, never commit secrets/scratch notes/generated output), - and anything that must never be done proactively (commits, PRs). - -## Writing principles -- Single source of truth per topic; cross-link instead of duplicating content between files. -- Declare the source of truth explicitly wherever two docs could drift (e.g. "upstream X is the - source of truth for shared behavior; adapt, don't re-derive"). -- Prefer concrete, testable rules over vague guidance — exact versions, limits, and paths. -- Keep each file short; move depth into docs/ and leave pointers in root files. -- After restructuring, verify every link resolves and report a summary of what moved where. +Restructure this repo's Markdown docs to follow the layout and rules below. Adapt them to this +repo: skip any section that doesn't apply, and don't create files the repo has no content for. + +Do not invent policy. Only consolidate rules that already exist in this repo's docs. If you +would infer a rule from code, config, or CI, list it as a proposal for me to confirm instead +of writing it in. + +## Process +1. List every human-facing Markdown file. Ignore vendored, generated, changelog, and + `.github/` template files. +2. Propose a move/merge plan (old path → new path, what gets merged or dropped and why). + Wait for my approval before changing anything. +3. Use `git mv` for moves. Don't commit, push, or open a PR. Leave unrelated changes alone. +4. After restructuring, search the whole repo (code, CI, package manifests, templates), + not just Markdown, for old paths and fix them. Then check that every relative link + resolves. Report what moved where, what was merged, and anything left unresolved. + +## Layout +- `AGENTS.md` (root): canonical agent rules. Make `CLAUDE.md` the single line `@AGENTS.md` + only after merging any Claude-specific content from it into `AGENTS.md`. +- Nested `AGENTS.md`/`CLAUDE.md`: keep them when their rules apply only to that directory. + Move only duplicated or repo-wide rules up to the root. Never silently delete guidance. +- `docs/README.md`: canonical index. "Using " (user guides), then + "Working on " (internals, then runbooks). Other files link here instead of + keeping their own full guide list. Package READMEs may stay unindexed. +- `docs/user/`: task-oriented guides, one feature per file. +- `docs/internals/`: architectural decisions, constraints that span components, and traps. +- `docs/operations/`: maintainer runbooks (development setup, release, debugging). +- `README.md`: what the product is, requirements, install/quick start, a short list of key + guides plus a link to `docs/README.md`, and (if a fork) how it differs from upstream. + Dev setup and verification live in AGENTS.md and the development runbook, not here. +- `CONTRIBUTING.md`: contribution policy, with a link to the development runbook for setup. +- `SECURITY.md` (root or `.github/`, if applicable): how to report vulnerabilities and the + supported scope. + +## AGENTS.md should cover, where applicable +- Identity: what the project is and isn't. +- Hard boundaries: explicit prohibitions. Enumerate each exception with exact limits and + state what it does NOT authorize. Point to the internals doc to read before changing one. +- Common ways to cause damage (killing processes by pattern, writing to live data, etc.). +- Dev servers and test data, if relevant. +- Verification: exact commands (confirm each one exists in scripts/Makefile) and which + repo-wide checks not to run. +- PR and commit conventions, including "never commit or open PRs unless asked." +- Documentation rules (below). +- Where code lives: one line per package/directory. +- Taste/conventions that reviewers actually enforce. + +## Documentation rules (put these in AGENTS.md under `## Documentation`) +- Most code changes need no doc change; agents can read the code. +- Internals hold decisions and hard-to-discover constraints. Before adding text, ask what a + maintainer would get wrong without it. Don't list fields, narrate control flow, keep file + catalogs, or append PR summaries. Put local explanations in code comments, and link to + source rather than copying it. +- When a documented decision changes, rewrite or remove the old text. Don't append a second + account. A new page needs a lasting reason to exist. +- User guides help users finish tasks, in the product's voice: what the feature does, how to + start, and anything unintuitive. Don't describe obvious controls or every UI state. +- One source of truth per topic; link across files instead of duplicating. Where a fork or + mirror could drift, name the source of truth explicitly. +- Never commit plans, research notes, or scratch files.