mbrucedogs/ai-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: require new chat repo summary

Browse Source
This commit is contained in:
Matt Bruce 2026-02-10 16:07:34 -06:00
parent 7e3a770455
commit 12da6e4f95
3 changed files with 9 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
Agents.md
View File

@ -7,11 +7,12 @@ It is internal guidance for the assistant, not reader-facing documentation.
## Audience And Tone Rules ## Audience And Tone Rules
Assume the reader is new to AI and needs detailed, step-by-step guidance. Assume the reader is new to AI and needs detailed, step-by-step guidance.
- Read the PRD.md and README.md to understand this project.
- On the first response in a new chat, read this file and summarize the repo purpose in 1-2 sentences before proceeding.
- Be specific and explicit. Avoid shorthand. - Be specific and explicit. Avoid shorthand.
- Explain terms in plain language. - Explain terms in plain language.
- Provide an example whenever possible. - Provide an example whenever possible.
- Format chat or code examples consistently: use "Example prompt:" with a fenced ```text``` block for chat prompts, and "Example code:" with the right language for code. - Format chat or code examples consistently: use "Example prompt:" with a fenced ```text``` block for chat prompts, and "Example code:" with the right language for code.
- For required instructions, label them as "Required instruction" and use a fenced ```text``` block.
- Prefer checklists, short steps, and concrete outcomes. - Prefer checklists, short steps, and concrete outcomes.
- Assume the reader is an expert engineer but a beginner at AI. - Assume the reader is an expert engineer but a beginner at AI.
@ -46,6 +47,8 @@ When using AI to add or change docs in this repo:
## When A New Chat Starts ## When A New Chat Starts
If you had to restart a chat and re-explain the goal, add a short reminder so the assistant places content in the reader-facing docs instead of workflow files. If you had to restart a chat and re-explain the goal, add a short reminder so the assistant places content in the reader-facing docs instead of workflow files.
Also, the first response in a new chat must confirm it read Agents.md and briefly state what this repo is about at a high level.
### What To Say (Plain English) ### What To Say (Plain English)
- "Treat this repo like a book for developers. Put reader-facing guidance in docs/ai, not in Agents.md." - "Treat this repo like a book for developers. Put reader-facing guidance in docs/ai, not in Agents.md."
- "If placement is unclear, ask where the content should live before editing." - "If placement is unclear, ask where the content should live before editing."

2
PRD.md
View File

@ -64,6 +64,8 @@ Teams need a clear, zero-knowledge onboarding path for AI tools, setup, and usag
## Documentation Sync ## Documentation Sync
When scope, workflows, or structure change, update PRD, README, and Agents together. When scope, workflows, or structure change, update PRD, README, and Agents together.
New chat starts should read Agents.md and state the repo purpose at a high level before proceeding.
## Risks and Mitigations ## Risks and Mitigations
- Outdated instructions: set a review cadence. - Outdated instructions: set a review cadence.
- Unclear ownership: assign section owners. - Unclear ownership: assign section owners.

4
README.md
View File

@ -17,9 +17,11 @@ These docs assume the reader is new to AI. Be explicit, explain terms, and inclu
3. Follow the iOS or Android setup guide. 3. Follow the iOS or Android setup guide.
4. Review skills and token usage guidance. 4. Review skills and token usage guidance.
When a new chat starts, the assistant should read Agents.md and state the repo purpose at a high level before proceeding.
## Local Workflow ## Local Workflow
- Edit files in docs/ai. - Edit files in docs/ai.
- Keep sections short and scannable. - Keep sections short but very detailed and scannable.
- Avoid vendor-specific step details that change frequently. - Avoid vendor-specific step details that change frequently.
- Keep Agents, PRD, and README in sync when scope or structure changes. - Keep Agents, PRD, and README in sync when scope or structure changes.