CODITECT README Standard
Purpose
This standard defines requirements for README.md files across all CODITECT projects, ensuring consistent documentation that answers What, Why, and How.
Scope
Applies to:
- Root README.md in every repository
- Directory README.md files
- README.md in documentation folders
1. Core Requirements
1.1 Every README MUST Answer
| Question | Section | Content |
|---|---|---|
| What | Title + Overview | What is this? What does it do? |
| Why | Purpose/Motivation | Why does it exist? Why use it? |
| How | Quick Start/Usage | How do I use it? How do I get started? |
1.2 Required Sections (Minimum)
# Project Name
Brief one-line description.
## Overview
2-3 sentences explaining what this is and who it's for.
## Quick Start
```bash
# Installation/setup commands
Usage
Basic usage examples.
Documentation
Links to additional docs.
License
License information.
---
## 2. Section Requirements by Type
### 2.1 Root Repository README
| Section | Required | Description |
|---------|----------|-------------|
| Title & Badge | YES | Project name, status badges |
| Overview | YES | What and why, 2-3 sentences |
| Quick Start | YES | Get running in <5 minutes |
| Prerequisites | YES | What's needed before starting |
| Installation | YES | Step-by-step setup |
| Usage | YES | Basic examples |
| Documentation | YES | Links to docs/ |
| Contributing | Recommended | How to contribute |
| License | YES | License type and link |
| Support | Recommended | How to get help |
### 2.2 Directory README
| Section | Required | Description |
|---------|----------|-------------|
| Title | YES | Directory name/purpose |
| Overview | YES | What's in this directory |
| Contents | YES | List of key files/subdirs |
| Usage | If applicable | How to use contents |
### 2.3 Documentation README
| Section | Required | Description |
|---------|----------|-------------|
| Title | YES | Documentation section name |
| Overview | YES | What docs are here |
| Document List | YES | Organized list with descriptions |
| Navigation | Recommended | Links to other doc sections |
---
## 3. Formatting Standards
### 3.1 Header Hierarchy
```markdown
# Title (H1) - Only ONE per file
## Major Section (H2)
### Subsection (H3)
#### Detail (H4) - Use sparingly
3.2 Code Blocks
Always specify language for syntax highlighting:
```bash
# Shell commands
npm install
// TypeScript code
const foo: string = "bar";
# Python code
def hello():
return "world"
### 3.3 Tables
Use for structured information:
```markdown
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data | Data | Data |
3.4 Lists
- Use
-for unordered lists - Use
1.for ordered lists - Nest with 2 spaces
4. Status Badges
4.1 Recommended Badges
4.2 Badge Order
- Build status
- Test coverage
- Version
- License
- Other badges
5. Templates
5.1 Minimal README (Directory)
# Directory Name
Brief description of what this directory contains.
## Contents
| File/Folder | Description |
|-------------|-------------|
| `file.md` | Description |
| `subfolder/` | Description |
## Usage
How to use contents of this directory.
5.2 Standard README (Project)
# Project Name
 
Brief one-line description.
## Overview
2-3 sentences explaining what this is, who it's for, and why it exists.
## Quick Start
```bash
# Get up and running in 2 minutes
npm install
npm start
Prerequisites
- Node.js 18+
- npm 9+
Installation
git clone https://github.com/org/project.git
cd project
npm install
Usage
Basic Example
import { something } from 'project';
something.doThing();
Advanced Usage
See Advanced Guide.
Documentation
Contributing
See CONTRIBUTING.md.
License
MIT License - see LICENSE.
Support
- Issues: GitHub Issues
- Documentation: Docs
### 5.3 Comprehensive README (Framework)
See `templates/README-TEMPLATE.md` for full template.
---
## 6. Anti-Patterns
### 6.1 Avoid These
| Anti-Pattern | Problem | Solution |
|--------------|---------|----------|
| No Quick Start | Users can't get started fast | Add 2-minute Quick Start |
| Wall of text | Hard to scan | Use headers, lists, tables |
| Outdated info | Misleads users | Keep synchronized |
| No examples | Users don't understand usage | Add code examples |
| Broken links | Frustrates users | Validate links regularly |
| Missing prerequisites | Setup fails | List all requirements |
### 6.2 Common Mistakes
```markdown
❌ WRONG
# readme
this is a project that does stuff
✅ CORRECT
# Project Name
Project Name is a tool for [specific purpose] designed for [target audience].
## Quick Start
```bash
npm install project-name
npm start
---
## 7. Validation Checklist
### 7.1 Required Elements
- [ ] Title (H1) present
- [ ] Overview/description present
- [ ] Quick Start section
- [ ] Usage examples
- [ ] License mentioned
### 7.2 Quality Check
- [ ] Answers What, Why, How
- [ ] Code blocks have language specified
- [ ] Links are valid
- [ ] No spelling/grammar errors
- [ ] Appropriate length (not too short, not overwhelming)
---
## 8. Enforcement
### 8.1 Automated Validation
```bash
# Validate README
/readme-check path/to/README.md
# Generate missing sections
/readme-gen --template standard
8.2 CI/CD Integration
- name: Validate README
run: python scripts/validate-readme.py README.md
References
- CODITECT-STANDARD-README-MD.md - Full specification
- FILE-NAMING-CONVENTIONS.md - Naming rules
templates/README-TEMPLATE.md- Copy-paste templates
Version: 1.0.0 Status: Active Owner: CODITECT Core Team Last Updated: 2026-01-02