Markdown Instructions
These rules apply to all markdown the AI writes — project files (README, rules, skills, docs), plans, and inline markdown in responses.
File Path References
Strictly enforce minimalist path references to reduce noise:
- Follow platform link requirements first: If the active harness requires clickable file references or line numbers, that requirement overrides this section.
- Default for markdown files: When no platform requirement says otherwise, use plain backticks instead of
[name](path)syntax. - Line numbers: Include line numbers only when the active harness or planning workflow requires them.
- No redundancy: Do not repeat the filename in both brackets and parentheses.
- Contextual pointers: Reference section names instead of line numbers.
Exceptions: Planner modes (architect, planner-a, planner-b, planner-c) may use links when creating or modifying a plan; any harness-level clickable-link rule also overrides the default plain-backtick preference.
Examples:
- Bad:
[app/models/user.py](app/models/user.py)→ Good:`app/models/user.py` - Bad:
[user.py](app/models/user.py:50)→ Good:`app/models/user.py` - Bad:
See \rules/01-general.md`→ Good:See 'Critical Resources' in `rules/01-general.md``
Formatting Standards
Style & Typography
- Files/code: Prefer inline backticks (
file.py) unless the active harness requires clickable file links. - Indentation: Use exactly 4 spaces for nested items.
Lists & Spacing
- Numbering: Use
)as separator (e.g.,1),2)). Never use periods (1.). - Density: No empty lines between list items. Group related items tightly.
- Headers: Start content on the very next line after a header — no blank line between them.
- Punctuation: Period at the end of every list item line.
- Sections: Single empty line between major sections only.
Ordered list example Bad (wrong separator, extra spacing, missing punctuation):
## Steps
1. First item
2. Second item
Good (correct separator, compact, punctuated):
## Steps
1) First item.
- Nested detail.
2) Second item.
Un-ordered list example Good:
## Points
- First item.
- Nested detail.
- Second item.
Tables: Do NOT use markdown tables (| col | col | syntax). They are hard for humans to scan and expensive for LLMs to parse (pipe alignment, separator rows, cross-referencing headers). Use linear format instead — bold labels with dashes and indentation.
This applies everywhere: markdown files, skill definitions, plans, and inline markdown in responses.
- Wrong (table):
| Category | Chimp | Octopus |
|---|---|---|
| Tool use | 50 | 40 |
| Swimming | 40 | 95 |
- Right (linear):
**Tool use**:
- Chimp: 50, Octopus: 40
**Swimming**:
- Chimp: 40, Octopus: 95
- Also right (single-line per item when columns are few):
**Tool use** — Chimp: 50, Octopus: 40
**Swimming** — Chimp: 40, Octopus: 95
Mermaid diagrams: Use only when requested by user.