Merge pull request #51 from andyjessop/aj/readme-improvements

chore: better readme

Author: andyjessop

scripts/readme-generator/readme-generator.ts

@@ -44,6 +44,7 @@ You are a REAME.md generator. Your goal is to generate a README.md file for a pr
 - Use markdown syntax to format the README.md file content
 - Use Mermaid syntax to generate diagrams
 - Use jsonc for all json code snippets. This allows you to add comments to the json code.
+- Leave a blank line between sections and code blocks, and after headings in the markdown file.
 
 ## Sections
 The following sections must be included in the README.md file:
@@ -66,6 +67,7 @@ The following sections must be included in the README.md file:
 ## Architecture Instructions
 - Only if the project is an 'app', create a system diagram using the Mermaid syntax. The diagram should show the main components of the system and how they interact.
 - Only if the project uses LLMs or AI in some way, highlight any of the patterns described below in the Agentic Patterns Cheatsheet. Each distinct pattern should be described in a separate section with a title and a brief description of how it is used in the project, and a Mermaid diagram too.
+- All mermaid diagrams should relate to specific code patterns, not just generic explanations of the pattern itself. Always relate it to the code or specific functionality. 
 
 ### Mermaid Diagrams
 - mermaid diagrams MUST NOT contain parentheses in the descriptions. The reason for this is that the Mermaid renderer that we use does not allow it.
@@ -87,7 +89,7 @@ graph TD;
 
 ### Markdown formatting
 
-There is often a problem when using lists where the next line is indented with the list. This often happens with code blocks, e.g.:
+There is often a problem when using lists where the next line is indented with the list. You should also leave a line between the list line and the start of the code block, e.g.:
 
 - **dev**: Starts the development server.
   \`\`\`
@@ -97,6 +99,7 @@ npx nx dev agent-task-manager
 Notice how the first set of backticks is indented with the list item. This causes the list item to be treated as a code block, and really can mess things up. To fix this, you should ensure that the next line is not indented, e.g.:
 
 - **dev**: Starts the development server.
+
 \`\`\`
 npx nx dev agent-task-manager
 \`\`\`