Use `design-prd` to get Product Requirements when planning any feature or to understand project business requirements, user roles, and success criteria.

2026-06-232

README.md Format

README.md must be written for humans in professional, user-manual style natural language

Use full sentences except diagrams and listing items like features

Use British English by default (unless specified otherwise)

Assume user has limited technical knowledge, but understand technical terminology (no need to explain basic technical terms like "docker", "compile", "proxy", etc.)

Code examples must specify the correct language attribute for syntax highlighting

Do not invent exact command output. If exact output is not known, describe the expected result in prose.

Use only links that are present in the repository, existing README, package metadata, build files, or supplied documentation.

Do not create links to internal files unless the file path is known.

Prefer relative links for repository files.

Mermaid diagrams must be high-level, readable, and syntactically valid.

Prefer flowchart TD for integration and component diagrams.

Use short node labels.

Do not include secrets, environment-specific hostnames, or internal credentials in diagrams.

Use one H1 heading only.

Use sequential heading levels without skipping levels.

Surround headings and fenced code blocks with blank lines.

Specify a language for every fenced code block, for example bash, json, yaml, sql, text, or mermaid.

Do not use trailing spaces.

Use hyphens for unordered lists.

README.md Layout

***[HERO]*** <p align="center">[LOGO]</p> <h1 align="center">[Project Name]</h1> --- [PURPOSE] --- ## Features [FEATURES] [INTEGRATION] ## Installation [PREREQUISITES] [LOCAL SETUP STEPS] [STARTUP STEPS] ## Usage [COMMON USAGE] [TUTORIAL] ## Configuration [CONFIGURATION] ## Development [ARCHITECTURE] [DEVELOPER NOTES] ### Testing [TESTING] ### Deployment [PACKAGING STEPS] [DEPLOYMENT STEPS] ## Terminology [ACRONYMS] [DEFINITIONS]

Replace placeholders in README.md as follows:

[LOGO]: Determine the logo as follow:

Use autocode_logo_find tool to find a logo.
If autocode_logo_find returns a logo path, replace [LOGO] with <img src="{path to logo}" alt="Project Logo" height="128">.
If no logo was found, use an appropriate emoji to replace [LOGO] with <span style="font-size: 96px; text-shadow: -3px -3px 0 #000, 3px -3px 0 #000, -3px 3px 0 #000, 3px 3px 0 #000, 0 -3px 0 #000, 0 3px 0 #000, -3px 0 0 #000, 3px 0 0 #000;">{emoji}</span>.

[Project Name]: Project name in a natural title format. If unknown: derive title from repo name

[HERO]: Catching advertising title as follows:

Summarize what project does in positive way like marketing advert
Max 20 words
No definitions in this section
Use only common words, not project specific terminology (except for naming components)

[PURPOSE]: Motivate why this project should exist as follows:

Briefly describe problem it solves and solution/benefit of using this project
Use marking style: Wording should encourage stakeholders to invest time to setup and use system
Do not list any technical features, instead mention problems it solve (use cases)
Max 80 words
No definitions in this section
Use only common words, not project specific terminology (except for naming components)

[FEATURES]: Advertise core features in markdown bullets as follows:

1 feature per bullet
Unique emoji per feature
Max 40 words per feature
No definitions in this section
Use only common words, not project specific terminology (except for naming components)

[INTEGRATION]: Explain how project integration with external systems (like miroservices):

Title summarize how it integrations (max 7 words), like "REST Integration" or "Microservice Architecture"
Include high-level Mermaid diagram of how it integrates
Only include [INTEGRATION] section if this project does integrate with external systems

[PREREQUISITES]: System requirements and dependencies needed before installation as follows:

List prerequisites as bullet points: 1 per dependency
Provide markdown links in text to online sources that provide guidance where to download or how to install dependency
Only include [PREREQUISITES] if project does depend on other systems

[LOCAL SETUP STEPS]: Commands and steps to set up the project locally as follows:

Provide sequential steps
Each step must include an example command/config/user action
Each step must include an example response/output (if known)
Provide minimal configuration/commands just to get a demo/basic version going
Format examples with proper markdown block formatting where appropriate
Only include [LOCAL SETUP STEPS] if project does require a setup

[STARTUP STEPS]: Commands to start the project

Provide sequential steps
Each step must include an example command/config/user action
Each step must include an example response/output (if known)
Format examples with proper markdown block formatting where appropriate
Explain different modes project support (for example development vs production mode)
If startup modes are vastly different organize it in different sub-sections
Only include [STARTUP STEPS] if project does require a server/service to start

[COMMON USAGE]: Explain how to use system as follows:

Provide primary commands (if applicable)
Provide primary URLs (if applicable)
Explain how user can navigate through application to reach primary features (if applicable)
Include example input/output in markdown blocks/tables (if possible)
ONLY include usage of feature that is currently available
NEVER include deprecated/uninplemented/planned/future features

[TUTORIAL]: Step-by-step guide for common user flows as per author-tutorial skill.

[CONFIGURATION]: Explain every project specific configuration setting as follow:

Provide tables of every custom config key/property/env var that project accepts with descriptions and default values and valid ranges or alternative enums
NEVER include standard framework properties like Spring Boot/Angular/Nuxt configs or any standard OS env vars
ONLY include known (proven) configuration (no guessing)
Only include this section if project has custom configuration

[ARCHITECTURE]: Explain how project fulfill its purpose describe in [PURPOSE] as follow:

If project is full stack: Include high-level Mermaid diagram of how different components of project interact with each other
If project contains complex event system: Include high-level Mermaid diagram of how events/data flow
If project contains multiple pages of static web content: Include high-level Mermaid diagram of primary pages link to each other (sitemap)
If project is library or monolithic application: Include high-level Mermaid diagram of primary internal components and how they relate to each other
If project is CLI tool: Include high-level Mermaid diagram of how data typically flow through this tool: inputs -> processes -> outputs
Project may solve more than 1 problem (multi-purpose project): In such case identify each primary goal, then for each goal:
- Write 1 paragraph per goal (max 200 words) how it solves that specific goal
- Include markdown links in text to core source files responsible for solution or where additional documentation could be found
Omit this section is project architecture is unclear, empty or new (no guessing)

[DEVELOPER NOTES]: Any special notes that developers of the project should be aware of like: Special commands to build project, common pitfalls, unusual file locations/config/commands required, quality standards, etc.

May contain sub-sections (max 200 words per section)
Must be human readable and may contain examples to explain intend
Keep this section as lean as possible and AVOID REPEATING any info mentioned in other sections of this document
Only include this optional section if you have important info to make developers aware of

[TESTING]: Steps how to test local development quality as follow:

Provide sequential steps
Each step must include an example command/config/user action
Each step must include an example response/output (if known)
Format examples with proper markdown block formatting where appropriate
Only include this section if project does contain tests

[PACKAGING STEPS]: Steps to build/package for production as follows:

Provide sequential steps
Each step must include an example command/config/user action
Each step must include an example response/output (if known)
Format examples with proper markdown block formatting where appropriate
Only contain this section if project needs packing for production deployment

[DEPLOYMENT STEPS]: Steps to deploy to production as follows:

Provide sequential steps
Each step must include an example command/config/user action
Each step must include an example response/output (if known)
Format examples with proper markdown block formatting where appropriate
If different deployment environments are supported (e.g. local vs docker): Organize in sub-sections
Only include this section if production deployment is different from [LOCAL SETUP STEPS]

Rules for Updates

If current README.md already follows this layout, only update outdated or missing sections

If current README.md already exist, but in different format:

Identify critical info to keep
Reorganize original README.md according to this specification
Verify that critical info is still included and in correct section

Remove empty sections or sections with no factual content (no guessing or "coming soon" placeholders)

Ensure all markdown links to internal project files or external sites are valid

Updated/Remove outdated info (if detected)

Avoid duplicated content (instead add markdown links in text that refers to previous sections of same content applies)

First time non-standard acronym is used: include definition in round brackets (), for example: "It guard UST (User Security Tables) when configured."

First time non-standard definition is used: include an INFO block below the paragraph where it was used to explain what it is in < 20 words.

NEVER repeat definitions, only first occurrence.

NEVER mention deprecated tools or configs

Keep examples updated with current tools/APIs/configs