Skip to content

Finn-style ​

The style module is Finn's writing and code style authority for the harness. finn-style and finn-style-lite carry the same rules at two levels of detail – the full skill with real source examples and every reference file, the lite twin trimmed to about a fifth the size with no reference docs at all – and only one of the two is ever meant to be installed in a project at once. Beside them sits git-style, the same authority pointed at a commit message rather than a file, derived off 104 of Finn's real commits rather than any published convention. Two gates enforce the mechanical half of all of it: style-lint checks every file Claude Code writes, and commit-lint checks the one thing a file-write hook can never see, a commit message drafted as a fenced block in chat rather than saved to disk. finn-style-sweep rounds it out, pulling an existing file into conformance after the fact rather than catching it as it's written.

In Practice ​

Write code under the full ruleset. finn-style/references/CODE.md is not a style guide in the abstract, it is one enforced shape: a class body splits into two phases (all member variables first, then all member functions, never interleaved), every user type takes a _t suffix, and a function definition, declaration, or call each sit on one line however long that gets, in every language, with a lambda argument past roughly 75 characters pulled out into a named variable above the call instead.

Trip the enforcement gate. style-lint.nu runs as a PostToolUse hook on every Edit, Write, and MultiEdit. It reads the file that was just written and checks the handful of rules a script can actually see – trailing full stops on comments, curly quotes, em dashes and en dashes, apostrophes outside the tiered allow list. A hit exits 2 with the violations printed to stderr, which Claude Code feeds straight back into the same turn instead of letting the drift land in the repo. In the session that prompted this page's regen, the gate blocked three writes this way, over trailing full stops and a stray prose apostrophe.

Trip the commit gate. commit-lint.nu runs on Stop instead of a file write, since a commit message here is usually a fenced block pasted into chat for Finn to paste, not a file Claude Code saved. Say the drafted subject opens built the new gate – built is a banned opener in banned.nuon, with the fix named right there in the data, "say added, or finished". The hook reads the transcript for the assistant turn that just ended, pulls any fenced block that reads like a commit message, and on a real break exits 2 with the break and the fix on stderr so the message gets rewritten in the same turn. It never rewrites the message itself, same posture as style-lint.

Choose lite over full. The two skills fire on the same triggers, so a project holding both pays for both and gets the same rules stated twice in one context window. finn-style-lite/USAGE.md puts the choice plainly: pick the lite one when the code is throwaway, exploratory, or just has to read like Finn wrote it, pick the full one when the code is being kept, shown to someone, or handed in.

The Full Ruleset ​

finn-style/SKILL.md ​

The prose half – voice, vocabulary, punctuation, spelling, comment shape and density, it governs everything written, docs, context files, comments, commit messages, or chat, whether code is involved or not. The frontmatter description is written in MUST and "deviations are bugs" language on purpose, that tone is what keeps it firing on every writing task rather than quietly degrading into an optional suggestion. It carries the tiered apostrophe rule (tier 1 always apostrophises the we're/we've/we'll/we'd family plus here's and it's meaning "it is", tier 2 never apostrophises negatives and i- contractions, tier 3 is check-the-project-then-ask) and a matching tiered hyphenation rule, both of which replaced older by-feel or flat-ban rules on 2026-08-20 after a survey of hyphenated and apostrophised phrases across nine of Finn's own projects. It also carries the newest dialect change, and is written out, never shortened to n (2026-09-10, Finn only types n on his phone where it's quicker), the one shortening that came back out of the abbreviation dialect after everything else in it stood.

finn-style/references/CODE.md ​

The code half – loads the moment the work touches code. Naming (lower_snake_case, a mandatory _t suffix on every user type, m_ on class members, bare struct fields, g_ reserved for true globals), the two-phase class layout with its fixed visibility and function ordering, and the alignment and macro conventions. It also carries the 2026-08-25 rule widening "one line" from function signatures to declarations and calls as well, and the lambda-extraction rule for an argument that would otherwise blow past roughly 75 characters inline. It closes with a cross-project drift table naming which legacy patterns (unscoped enums, the CAST_TO macro name, possessive apostrophes) are worth sweeping the moment a file is touched.

finn-style/references/FORMAT.md ​

Naming and comment-content detail, a sibling to LAYOUT.md and COMMENTS.md that the same skill also references. It works through the _t suffix pattern by type kind, the manager/data class split (xxx_manager_t aliased down to xxx_t), boolean naming that differs by whether the variable is a class member, a struct field, a function, or an argument, and the possessive-apostrophe ban with a before/after table. Its own hyphenation section is marked superseded, pointing back at the three-tier rule now owned by SKILL.md.

finn-style/references/COMMENTS.md ​

The rules the boid project derived them from – the original comment-refactoring ruleset the tiered apostrophe and hyphenation rules were extracted from, kept for the worked before-and-after pairs (a bad namespace header that explains the mechanism against a good one that just names the thing) rather than as an active source of truth. Its own apostrophe and hyphenation sections point straight back at SKILL.md's three tiers, and it too carries the 2026-09-10 note that and is written out now, the older comments under references/examples/ are a record of what was written rather than a pattern to copy.

The Trimmed Twin ​

finn-style-lite/SKILL.md ​

Same rules, one file – no reference docs, no examples tree, roughly a fifth the size of the full skill. It keeps the mechanical rules a reader would actually notice on the page (tiered apostrophes, no full stops on comments, tabs, the _t suffix, the two-phase class layout) and drops the fine detail: alignment nuance, the canonical macro library, the print-macro set, and the cross-file walkthrough example. Its description says explicitly not to install it alongside finn-style, since the two fire on identical triggers. It carries the and-not-n rule too, one line in its own abbreviation-dialect section rather than a cross-reference, so a project running the lite twin alone still gets it.

Git Conventions ​

git-style/SKILL.md ​

The commit-message half finn-style never states – the subject line (lowercase, no trailing full stop, past tense or a bare noun phrase, about 10 words hard), when a body is earned (one kind of change needs none, a few changes under one theme get a themed subject and an itemised body, a big mixed push with no theme is the only place a generic subject like big update is honest), and the closed set of openers a body item can start with (added, created, finished, more work on X, fixed, renamed X to Y, moved X into Y, cleaned up, updated). It bans conventional-commits prefixes, plan or task ids, counts and metrics, and bullets outright, "no bullets, ever" is Finn's own 2026-09-10 ruling after reading three drafted attempts. and written out, never n landed here first, 46 against 1 in the real commit corpus, and finn-style adopted the same rule the same day, so the two now say it in step rather than one departing from the other.

git-style/references/examples.md ​

The real corpus, quoted byte exact – 36 genuine commits from this repo and 23 from D:/Documents/AutoHotkey, filtered to Finn's own hand with merges and anything carrying a Co-Authored-By trailer dropped. It names two RETIRED shapes directly, a bullet list hanging off a bare point and a bold-headed structured mode with per-file dashes, both real patterns in the corpus that Finn ruled out on 2026-09-10 and that an agent re-reading the raw log would otherwise re-derive. It closes with a ranked phrase table, added X as the dominant opener, updated X as the failure mode when it's the whole subject but fine inside a body.

See harness/modules/style/git-style/USAGE.md for how it installs and what it doesn't cover, branch names, PR text, tags, and changelogs are all explicitly out of scope.

The Enforcement Gates ​

style-lint/style-lint.nu ​

The live check on a file write – a PostToolUse hook registered on Edit|Write|MultiEdit that string-matches the mechanical fraction of finn-style: em dashes and en dashes, curly quotes, tiered apostrophes in prose, and trailing full stops on comments and bullet lines. It reads the hook payload natively off stdin with nu --stdin rather than shelling out to cat, after the old ^cat-piped version was found to silently lint nothing on a bare Windows PATH with no cat on it. A run of two or more em dashes is exempt as a deliberate section-divider shape (// – – – – setup – – – – ); a lone em dash still fails, since a model reaching for punctuation writes exactly one every time. Six trees are skipped outright: Claude Code's own memory store (its index format wants the em dash), a vendored extern/ bank entry (not Finn's to restyle, and a reformat would break the three-way merge), a generated VitePress wiki page (mechanical checks only, the prose rules step aside for the wiki's own proper-prose exception), a role file (formal prose is the correct register there), a lesson or rule file (added 2026-09-09, most of what's in one is a direct quote, and the rendered lesson slices are regenerated anyway so a fix there reverts on the next mutation), and the finn-style docs themselves (a style doc has to spell out what it bans, so its own counter-examples would trip the rule it's stating). The newest change (2026-09-11) strips inline code spans off a line before the char and apostrophe checks run, so a backticked path or a nushell regex full of single quotes doesn't trip the gate the way one did on a planner doc quoting a regex delimited by single quotes.

style-lint/USAGE.md ​

The end-user doc for the gate – how it installs (copy the two files, merge the settings fragment, nothing to invoke by hand), what it skips and why across all six exempted trees, and the standing gaps it owns up to: the CRLF check is disabled, hyphens were never enforced here even before they went optional, and the style-doc exemption is named directly as "a real hole" since it leaves the finn-style docs themselves as the one prose in the repo nothing checks.

commit-lint/commit-lint.nu ​

style-lint's twin for the one thing it can never see – a commit message is a git commit -m string or, far more often here, a fenced block pasted into chat, never a file write, so it runs on Stop instead. It reads the transcript for the last assistant turn (subagent output is sidechain and gets skipped), pulls every fenced block whose first line reads like a commit subject, and lints it against banned.nuon. A real break exits 2 with the break and the fix printed to stderr, so Claude Code hands the turn straight back and the message gets rewritten before it ends; the soft item-length rule only ever reports, it never blocks. It never rewrites the message itself, naming the break and stopping is the whole job.

commit-lint/banned.nuon ​

The one list, as data rather than prose – every banned word (sidecar, triages, leverages, utilises, facilitates), banned opener (built, kept working on, implemented, refactored, introduced, enhanced), and line-shape rule (a conventional-commits prefix, a plan or task id, a count or metric, a bullet, a heading, n written for and, a trailing full stop, addressing a reader) that git-style states in prose, commit-lint.nu is the only reader. Stating the rules as data rather than restating them in the hook is deliberate, so a rule lands in both places or neither, the exact drift that let the n-versus-and copies disagree before Finn reconciled them 2026-09-10.

commit-lint/USAGE.md ​

The end-user doc for the Stop gate – install steps, the commit-lint.nuon config (enabled and block, both default true, block off downgrades every break to a note), and the gotchas it owns up to: it only ever sees the main agent's turn, it can't check a claim against the actual diff (the worst break the agent runs produced was retired limiter and skill-smith when both had only moved), and detection leans toward firing on purpose, a false positive costs one ignored report and a miss costs the whole gate.

Connects to ​

  • finn-style-sweep declares a hard needs on finn-style and restates none of its rules, so installing the sweep alone gives a project a skill with nothing to apply until the full ruleset lands too.
  • git-style declares no hard needs on either depth of finn-style, on purpose. Either depth satisfies the prose voice it assumes, and a needs can't say OR, so the skill restates the few voice rules that carry (unapostrophed negatives, bc, no em dashes) and stays usable on its own.
  • commit-lint pairs with git-style the same way, no hard needs, since the gate carries every pattern itself in banned.nuon and works in a project that only wants the enforcement.
  • The global coding-style skill is superseded wherever the two disagree, finn-style wins.
  • The wiki skill's references/style.md carries a deliberate finn-style exception for generated pages – proper prose, contractions, full stops – and style-lint reads a .vitepress/config.* file on disk to know when to step its prose checks aside for exactly that reason.
  • harness/CLAUDE.md states "finn-style always" as a standing repo rule for every code file, comment, and doc, this module is what that rule actually resolves to.
  • The condensed, end-user version of each part is its own USAGE.md – harness/modules/style/finn-style/USAGE.md, harness/modules/style/finn-style-lite/USAGE.md, harness/modules/style/git-style/USAGE.md, harness/modules/style/commit-lint/USAGE.md, and harness/modules/style/style-lint/USAGE.md – this page is the fuller depth behind all five.