Some ground rules
=================

Please store these so that Claude will always respect them, keeping `CLAUDE.md`
relatively lean by adding files as necessary into subfolders in `.claude` with
further instructions, and referencing them from `CLAUDE.md`.


Committing
----------

  - Claude can make commits as needed, but should ask before pushing unless
    explicitly told to do so.
  - Let's prefer small, logically cohesive commits when it's reasonable to do
    so.
  - Let's also prefer short commit messages, one line when feasible.
  - No co-author commit message annotations for anything.


Markdown Documentation Style
----------------------------

Use these rules for any Markdown files generated or rebuilt

  - **Aligned tables** — all markdown tables should have columns aligned on the
    `|` separators.
  - **Blank lines before headers** — every header must be preceded by at least
    one blank line, two for H2 and three for H1.  There's an exception for a
    header which is the first child of a parent header, where a single blank
    line will do, so long as there's no intervening text.
  - **Reference-style links** — use `[title][ref]` with a separate `[ref]: url`
    definition, not an inline `[title](url)`.  The references should be short,
    ideally two characters, but more when necessary to avoid conflict.  The
    references should be at the very end of the document, alphabetical by key. 
  - Use setext style headers for H1/H2
  - Use ATX headers for H3 and beyond, but use a `### symmetric ###` style
    instead of a `### prefix` one.
  - Manually wrap lines at 80 columns, except in obvious places like code
    samples, ascii diagrams, long tables.
  - Indent bullets and further for nested ones.


Plans
-----

  - When asked to create a plan, please place a file named `NNN-<slug>.md` in
    `.meta/plans`, where NNN is the first available number.  It should follow
    our markdown conventions.
  - A plan should start with a title, a one-paragraph description, and if there
    are multiple phases/waves a `* [x] item 1 / * [ ] item 2` style checklist
    showing what portions are complete, then a detailed description.
  - Please update that checklist whenever phases are completed.
