Stef

Simple Technical English Flavored — a deterministic prose linter, a mechanical fixer, and a bounded LLM rewrite loop.

The design is a split, not a pipeline. A linter decides the eleven mechanical ASD-STE100 rules a script can decide. An LLM handles the rules no script can judge, and reworks the draft until the linter is clean or the attempt budget runs out. The linter is the oracle and the model is the writer, so nothing grades its own work and the retry loop has a real exit condition.

Methods

• lint — run the eleven checks and emit kind: findings. Deterministic, no model call, no API key.
• normalize — apply the fixes a script can make without judgement, then re-lint. Deterministic, no model call, no API key.
• rewrite — tool-call mode: run the whole loop in one command by spawning claude -p. Runs on whatever credential Claude Code already holds, so no API key is stored in a vault.
• start / record — referee mode: hold state and enforce the attempt cap while a driving agent does the writing. Executes nothing, needs no credential. The bundled simple-english skill drives this loop.

Every method takes the same arguments. Pass text or path to say what to read. Pass session to name the state slot to write, so two drafts in flight never overwrite each other.

Mechanical fixes

Three checks have deterministic repairs: emphasis punctuation, Latin abbreviations, and unambiguous contractions. rewrite and start both apply them first, which spends no model call on work a script can do. Set normalizeFirst: false in globalArguments to turn this off.

Checks

long-sentence (25 words descriptive / 20 procedural), contraction, banned-modal, perfect-tense, ing-clause, semicolon, latin-abbrev, slop-word, trailing-condition, synonym-rotation, and emphasis. Code blocks, inline code, headings, tables, URLs, blockquotes, and shell-prompt lines are stripped before any check runs, so a command or a quoted log line is never rewritten.

Interoperability

Findings use the kind: findings contract that @swamp/software-factory's findings-clear gate consumes, so a scripted rule and a judgement-based LLM reviewer merge behind one gate.

Configuration

The style guide is data, not code. Per-check severities, the blocking severity list, the sentence limit, the reason-checked guidance block, and wrong/right anti-pattern examples all live in globalArguments, so a writer tunes the style without republishing the extension.

Prerequisites

• swamp initialized in the repository (swamp repo init)
• Claude Code on PATH, for rewrite only (referee mode needs nothing)