Skip to content

AGENTS

Jump to bottom
RemyDuijkeren edited this page Aug 25, 2026 · 2 revisions

Flowline Wiki — writing instructions

This repo is the published GitHub Wiki for Flowline. Everything here is read by people using Flowline, not by people working on it.

The source code lives in the sibling folder ../Flowline. Its AGENTS.md is the contributor guide; this file governs the wiki only.

Audience rule

Write for someone who wants to get work done with the CLI. Before adding a sentence, ask what the reader does differently for having read it. If the answer is nothing, cut it.

Belongs here:

  • What a command does, when to reach for it, what changes after it runs
  • Flags, arguments, exit codes
  • Concrete examples they can paste
  • Manual steps Flowline can't do for them

Does not belong here:

  • Internals: class names, service names, file paths in the source, registration order, call flow
  • Design rationale, tradeoffs, why an approach was rejected
  • Caveats about paths that don't apply to them: what happens when an internal check can't run, what Flowline deliberately doesn't write, which cases are unmeasured
  • Measurement notes, dates, issue links used as evidence
  • Anything phrased as reassurance ("it never blocks", "nothing is written")

Those belong in the source repo: docs/solutions/ for problems and their fixes, docs/end-to-end-test-log.md for live measurements, CHANGELOG.md for what shipped.

Length follows the same rule. A behaviour that is automatic and needs no decision from the reader is usually one or two sentences: what happens, and that there's nothing to pass. Detail earns its place only where the reader has a choice to make.

Pages

Files are NN-Title.md. The number sets the order in GitHub's page list and is part of the page name, so it appears in links and URLs. Renaming or renumbering breaks every inbound link and any external URL, so don't.

Adding a page means: pick the next number, write the file, and add a line to the ## Pages list in Home.md. A page missing from that list is effectively unpublished.

There is no _Sidebar.md, and don't add one. Navigation is GitHub's own generated page list, which sorts by filename — so the number prefix is the ordering. A custom sidebar would replace that list with a hand-maintained one that drifts every time a page is added or renamed. Order a new page by choosing its number, not by editing a menu.

That list shows every .md file in this repo, so AGENTS.md and CLAUDE.md appear at the end of it. That's accepted: GitHub offers no way to exclude a page from the generated list, and they sort last anyway, below the numbered pages.

13-Planned-Features.md holds what's coming. When a feature ships, delete its entry there and document it on the page it belongs to. Never document something that isn't released as if it were.

Page shape

# Title                          <- H1, once, matches the page name without the number

One or two sentences: what this is and when you'd use it.

```bash
flowline <command> <typical invocation>
```

## Section                       <- H2 for main sections, H3 beneath them
  • Fence shell examples as bash, and keep them runnable and copy-pasteable
  • Tables for flags, options, exit codes, and comparisons
  • > [!TIP] and > [!WARNING] for things that bite. Sparingly — a page of callouts has none
  • Blockquote for a manual procedure the reader has to carry out themselves
  • Images go in images/

Links

Wiki links are [[04-Command-Reference]], or [[08-Deploy#package-assembly-check]] for a section.

Anchors come from heading text, so changing a heading breaks every link pointing at it. Before editing one, grep the repo for the anchor and update the callers in the same change, or leave the heading alone.

Voice

Match the page you're editing. House style across the wiki: second person, present tense, contractions, short sentences. Say what the tool does, not what it tries to do.

../Flowline/docs/tone-of-voice.md defines the voice for CLI output. The same personality applies to prose here — confident, casual, economical — but the wiki explains, so full sentences and paragraphs are right where a CLI message would be a fragment.

Accuracy

Every claim about behaviour is verified against the source in ../Flowline before it's written. Read the code, don't infer from the command name or from an older wiki page. If you can't confirm something, leave it out and say so rather than describing what you assume.

When Flowline's user-facing behaviour changes — commands, flags, exit codes, plugin registration, web resources, project structure — the wiki page changes in the same piece of work, not later.

Editing

Touch only what the change requires. Don't reflow paragraphs, renumber pages, or restyle sections you aren't otherwise editing. Prose wraps around 100 characters on newer pages and runs long on older ones; follow whatever the file you're in already does.

This is a git repo. Never commit or push without being asked.

Clone this wiki locally