malkuthroandClaude Opus 4.7
413b153702
Audit triggered while debugging the v0.2.0 release surfaced drift in the maintainer docs vs current code: dead curated_defaults.json references (file replaced by starter_preset.json in PR #72), the v1_0_1 fork example (removed in v0.1.5), and a "tooling we don't have yet" entry that's now covered by tools/preflight_release.py. Adds a new conventions.md for cross-cutting rules — currently the Mermaid-for-diagrams convention. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1.4 KiB
Project conventions
Cross-cutting rules that apply anywhere in the repo — docs, issues,
PRs, commit messages, agent output. Topic-specific procedures live in
their own docs/maintainers/<topic>.md; this file is for the rules
that don't have a single home.
Diagrams: use Mermaid
When producing a diagram (architecture sketch, sequence flow, decision
tree, version-state graph), render it as a fenced mermaid block.
Write:
```mermaid
flowchart LR
A[v0.1.9 Active] --> B[v0.1.10 Flagged]
B --> C[v0.2.0 Flagged]
```
Which renders on GitHub as:
flowchart LR
A[v0.1.9 Active] --> B[v0.1.10 Flagged]
B --> C[v0.2.0 Flagged]
Why: the maintainer reviews diagrams visually, and a Mermaid block is
easier to read than ASCII art or paragraph prose. GitHub renders
Mermaid natively in .md files, issue / PR bodies, and discussions.
Apply in:
- markdown docs under
docs/ CHANGELOG.mdentries explaining a structural change- issue / PR bodies where a flow or state graph would clarify
- release-notes drafts
In-app caveat: Claude Code's desktop file-preview panel does not render Mermaid (open feature request anthropics/claude-code#14375); the diagram only renders when viewed on GitHub or in Obsidian. So the working loop is "write Mermaid → push or open in Obsidian to verify rendering."