px0 init scaffolds a set of starter guidelines. Read them, rewrite them, or delete them - they are ordinary Markdown files, and they are yours. px0 guidelines edit opens one in $VISUAL, $EDITOR, or the first of nano, vim, vi that exists; what you save is recorded as a change. px0 guidelines show <name> prints one verbatim - the same text a workflow inlines.
How a workflow uses them
A workflow names the guideline files it needs in its frontmatter:{{guidelines}} placeholder if the body has one, otherwise prepended before it.
Two design choices here are worth understanding, because they explain behaviour you will notice:
Guidelines are matched by name, never by similarity. Unlike brain/, which is retrieved, a guideline is either in the list or it is not. A convention you rely on should not depend on a search hit - “sometimes it follows my commit style” is worse than useless.
Which also means an irrelevant guideline actively hurts. Since the whole file is inlined, an unrelated guideline costs tokens and misleads the model. This is why the builder attaches a guideline only when it genuinely matches the task: a commit-message workflow gets commit-messages.md, a workflow about haikus gets none.
The run record notes which guideline files were inlined and at which version. If output that used to be right starts looking wrong, comparing versions is the first thing to check.
Writing a good guideline
Guidelines work best when they read like instructions to a new colleague who is competent but does not know your team.- Be prescriptive, not descriptive. “Start each bullet with an imperative verb” beats “we tend to use imperative verbs.”
- Say what not to do, too. “Never comment on formatting, that is the linter’s job” removes a whole category of noise.
- Use
##headings per rule. Each heading becomes an addressable claim, which is what makes history and reverts work at the level of one convention rather than the whole file. - Keep one topic per file. Files are inlined whole, so a file covering three topics gets pulled in for all three.
- Short is fine. Three sentences that are actually followed beat two pages that get ignored.
Guidelines px0 offers to write for you
Near the end of a workflow build, px0 asks itself whether the job depends on a convention it cannot guess - the voice of a public comment, what counts as worth flagging in a review - and no file inguidelines/ covers it. When it does, px0 drafts that guideline from the workflow itself and offers it:
again redraws it, n skips it, anything else saves it. What gets saved is an ordinary guideline file with version history from v1, added to that workflow’s guidelines: list - so px0 guidelines log works on it from day one.
This is the only way a guideline gets created - there is no px0 guidelines new. Asking someone to compose a convention from a blank page is the step that stopped guidelines from being written at all, so the build drafts a defensible version and leaves editing to you. Nothing is proposed for a workflow that already says what to do, and nothing on a topic you already have a guideline for. Skipped entirely under --yes: there is nobody to show a draft to, and a convention nobody saw should not land in the store. See Build a workflow.
Removing a guideline
px0 changes revert puts it back.
Next steps
History
Trace any claim or output back to its sources, and undo a change.