diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 39b27b9..360f86d 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,6 +1,6 @@ { "name": "anti-slop", - "description": "The antislop skill/plugin: Anti AI Slop, Design & Copy Rules for AI coding agents.", + "description": "The antislop skill/plugin. Anti Slop: Rules for AI Coding Agents.", "owner": { "name": "miqdadbadjuber" }, @@ -8,8 +8,8 @@ { "name": "antislop", "source": "./", - "version": "3.0.2", - "description": "Anti AI Slop: Design & Copy Rules. A rules filter for AI coding agents that stops generic AI slop UI and copy. Loads as five skills." + "version": "3.1.0", + "description": "Anti Slop: Rules for AI Coding Agents. Stops generic AI slop in generated UI, copy, and code. Loads as six skills." } ] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 607aa00..8c01948 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,8 +1,8 @@ { "name": "antislop", "displayName": "antislop", - "version": "3.0.2", - "description": "Anti AI Slop: Design & Copy Rules. A rules filter for AI coding agents that stops generic AI slop UI and copy. Loads as five skills.", + "version": "3.1.0", + "description": "Anti Slop: Rules for AI Coding Agents. Stops generic AI slop in generated UI, copy, and code. Loads as six skills.", "author": { "name": "miqdadbadjuber" }, diff --git a/README.md b/README.md index 1ebf8d0..8a97641 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ # antislop -> **Anti AI Slop: Design & Copy Rules.** A rules file for AI coding agents. It stops them from generating generic "AI slop" UI and copy, without letting the result turn sterile. It is a **filter, not a style guide**: no prescribed colors, fonts, or layouts. It is not only for building pages: it also writes and audits copy, so AI text stops reading like AI. And it never beautifies on its own; `DESIGN.md` (yours) is where beauty and direction come from. +> **Anti Slop: Rules for AI Coding Agents.** It stops them from generating generic "AI slop" UI and copy, without letting the result turn sterile. It is a **filter, not a style guide**: no prescribed colors, fonts, or layouts. It is not only for building pages: it also writes and audits copy, so AI text stops reading like AI. And it never beautifies on its own; `DESIGN.md` (yours) is where beauty and direction come from. > **New here? Start with the [guide](guide.md).** It explains what antislop is and how to install it, from zero. @@ -70,8 +70,9 @@ curl -o antislop.md https://raw.githubusercontent.com/miqdadbadjuber/anti-slop/m | `antislop-copywriting` | Copy & text: headlines, CTAs, tone, fake stats, anti-AI-writing patterns, markdown hygiene | v2.3.0 | | `antislop-human` | Human: contrast (with the checker), keyboard, focus, states | v2.4.0 | | `antislop-layoutmobile` | Mobile layout: responsive breakpoints, grids, overflow, tap targets, navigation | v2.5.0 | +| `antislop-code` | Code comments: remove generic AI-slop comments, keep the valuable ones, never touch the code | v3.1.0 | -Pick what matches the work: UI work → `antislop-ui`, copy work → `antislop-copywriting`, people work → `antislop-human`, mobile layout work → `antislop-layoutmobile`, more than one → install several, or none (the core alone is a complete filter). +Pick what matches the work: UI work → `antislop-ui`, copy work → `antislop-copywriting`, people work → `antislop-human`, mobile layout work → `antislop-layoutmobile`, code comments work → `antislop-code`, more than one → install several, or none (the core alone is a complete filter). ## Usage Modes @@ -82,7 +83,7 @@ antislop is used one of two ways, chosen at the start of a session: ## Roadmap -**v3.0.0 shipped**: antislop is packaged as installable skills. See [ROADMAP.md](ROADMAP.md). The skill plan that built toward it (one skill per version) is complete; `antislop-docs` and `antislop-identity` are candidates for after v3. +**v3.0.0 shipped**: antislop is packaged as installable skills, then refined through v3.0.1 and v3.0.2. The next release, **v3.1.0**, ships the `antislop-code` skill. See [ROADMAP.md](ROADMAP.md) for the tracker, including the cross-agent plugin plan. ## FAQ diff --git a/ROADMAP.md b/ROADMAP.md index 516cd56..8f66046 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,10 +1,10 @@ -# antislop: Roadmap to v3.0.0 +# antislop: Roadmap > How antislop grows from a single rules file into an installable, cross-agent skill/plugin. New to antislop? Read the [guide](guide.md) first. See [README.md](README.md) for the product. ## Where we are -The latest release is **v3.0.0**. antislop is now a **packaged system**: a lean, always-loaded **core** plus four **skills**, each shipped as a standard agent skill folder (`skills//SKILL.md`): +The latest release is **v3.0.2**. antislop is a **packaged system**: a lean, always-loaded **core** plus four **skills**, each shipped as a standard agent skill folder (`skills//SKILL.md`): - `antislop`: the core rules filter (rules, tiers, Delivery Gate, liveliness) - `antislop-ui`: UI / visual @@ -12,7 +12,9 @@ The latest release is **v3.0.0**. antislop is now a **packaged system**: a lean, - `antislop-human`: human / accessibility, home of the contrast checker - `antislop-layoutmobile`: mobile / responsive -The system installs three ways from one repo: the interactive picker (`npx antislop-ai`), the skills directory (`npx skills add miqdadbadjuber/anti-slop`, listed on skills.sh), and the Claude Code plugin marketplace (`.claude-plugin/plugin.json`). The contrast checker is also exposed as an MCP tool inside the plugin. +The next release, **v3.1.0**, ships a fifth skill: `antislop-code`, the code comment filter. + +The system installs three ways from one repo: the interactive picker (`npx antislop-ai`), the skills directory (`npx skills add miqdadbadjuber/anti-slop`, listed on skills.sh), and the Claude Code plugin marketplace (`.claude-plugin/plugin.json`). The contrast checker is also exposed as an MCP tool inside the plugin. Each skill folder also carries a short `README.md` that says on GitHub what the skill is for. The **First-Run Install Wizard** still lives inside `antislop.md` as the manual path. The single-file core remains a complete filter you can paste into any chat window. @@ -26,7 +28,7 @@ v3.0.0 was reached by adding one concern per version, each as a separate **skill That kept the filter pull-only-what-you-need and made the v3 packaging mechanical rather than a rewrite. Occasional +0.1 patches shipped something that is not a skill, like v2.4.1's plain-English `guide.md`; those did not change the skill plan. -### The skill plan (complete) +### The skill plan | Version | Skill | Concern | |---------|-------|---------| @@ -34,8 +36,9 @@ That kept the filter pull-only-what-you-need and made the v3 packaging mechanica | v2.3.0 | `antislop-copywriting` | Copy and text: headlines, CTAs, tone, fake stats, markdown hygiene | | v2.4.0 | `antislop-human` | Human: contrast, keyboard, focus, states (home of the contrast checker) | | v2.5.0 | `antislop-layoutmobile` | Mobile layout: responsive breakpoints, grids, overflow, tap targets, navigation | +| v3.1.0 | `antislop-code` | Code comments: remove generic AI-slop comments, keep the valuable ones, never touch the code | -`antislop-docs` and `antislop-identity` are candidates for after v3, not part of the shipped plan. +The plan to v3.0.0 is complete. `antislop-code` is the first skill added after v3. `antislop-docs` and `antislop-identity` remain candidates for later, not part of the shipped plan. ## v3.0.0: the skill/plugin @@ -58,11 +61,15 @@ What v3.0.0 shipped: - [x] v2.4.2 - skill checklist polarity fix (#9) and docs cleanup, merged from PRs #8 and #10 - [x] v2.5.0 - `antislop-layoutmobile` (breakpoints, scale, grids, overflow, tap targets, navigation) - [x] v3.0.0 - skill/plugin packaging: `skills/` folders, two doors, picker CLI, MCP contrast tool, MIT license +- [x] v3.0.1 - Snyk W012 fix (no runtime curl in the packaged core), npm package author to antislop, docs clarity +- [x] v3.0.2 - adaptive python (python3 on macOS/Linux, python on Windows), App & Dashboard + copy voice patterns, pointer fix +- [ ] v3.1.0 - `antislop-code` skill, per-skill READMEs, Filler Data and Emoji as Decoration patterns ## After v3 - [ ] `antislop-docs` (skill candidate) - [ ] `antislop-identity` (skill candidate) +- [ ] **Cross-agent plugin** (plan, no promised version): antislop installs as a plugin on more agents the way superpowers installs everywhere from one repo, with paths for Antigravity, Codex, Cursor, Gemini CLI, and others. Estimate: Q3-Q4 2026. ## Not in scope diff --git a/antislop.md b/antislop.md index a2980a6..9ae5b6b 100644 --- a/antislop.md +++ b/antislop.md @@ -1,6 +1,6 @@ # antislop -> Anti AI Slop: Design & Copy Rules +> Anti Slop: Rules for AI Coding Agents > Follow these rules whenever generating or building UI for a website, web app, or any interface. > The goal: the design should feel **crafted by a designer**, not generated by AI. @@ -18,13 +18,14 @@ If no antislop pointer exists and this file is being read for the first time, ru > If the user can use a terminal, the packaged install is better: run `npx antislop-ai` (interactive picker) or `npx skills add miqdadbadjuber/anti-slop`, then skip this section. The steps below are the manual fallback for chat-only setups. -1. **Declare the setup before doing anything.** Tell the user you will (a) download the skill(s) they choose into `skills//` subfolders next to this file, and (b) append an antislop pointer block at the end of the project's entry file. Get approval. Never modify the entry file silently. +1. **Declare the setup before doing anything.** Tell the user you will (a) get the chosen skill(s) in place in `skills//` subfolders next to this file (the user fetches them; the agent never downloads from the network, see step 4), and (b) append an antislop pointer block at the end of the project's entry file. Get approval. Never modify the entry file silently. 2. **Ask which skills to install** (multi-select, in the user's chat language). List only the skills that exist in this version of antislop: - **1. All** (recommended): install every available skill. Choose this when the work spans UI, copy, people, or mobile layout. - **2. `antislop-ui`** (UI / visual): pick this for building or editing a website, web app, or interface: color, layout, components, decoration, motion. - **3. `antislop-copywriting`** (copy & text): pick this for writing or editing copy: headlines, CTAs, value propositions, tone, landing-page text, product prose. - **4. `antislop-human`** (people): pick this for making sure a UI works for people with different eyes, hands, and setups: contrast, keyboard, focus, states. - **5. `antislop-layoutmobile`** (mobile / responsive): pick this for layouts that have to hold up on a phone: breakpoints, scale, grids, overflow, tap targets. + - **6. `antislop-code`** (code comments): pick this for writing or editing code comments: remove generic AI-slop comments, keep the valuable ones, never touch the code. - New skills appear here as they ship; never offer a skill that does not exist in this version. If the user declines or says "core only", stop here and use this file alone as the filter. Do not install anything. @@ -37,11 +38,12 @@ If no antislop pointer exists and this file is being read for the first time, ru ```md ## antislop - For UI, copy, people, or mobile layout work, read `antislop.md` (core) and then the skill for the task: + For UI, copy, people, mobile layout, or code comments work, read `antislop.md` (core) and then the skill for the task: - UI / visual: `skills/antislop-ui/SKILL.md` - Copy & text: `skills/antislop-copywriting/SKILL.md` - People: `skills/antislop-human/SKILL.md` - Mobile / responsive: `skills/antislop-layoutmobile/SKILL.md` + - Code comments: `skills/antislop-code/SKILL.md` Before starting, ask the user when antislop applies: during the work, or after it is done. ``` diff --git a/cli/index.mjs b/cli/index.mjs index ac36bc3..5ba236d 100644 --- a/cli/index.mjs +++ b/cli/index.mjs @@ -17,6 +17,7 @@ const EXTRA_SKILLS = [ { value: 'antislop-copywriting', label: 'antislop-copywriting', hint: 'copywriting and text rules' }, { value: 'antislop-human', label: 'antislop-human', hint: 'accessibility, with the contrast checker' }, { value: 'antislop-layoutmobile', label: 'antislop-layoutmobile', hint: 'mobile layout rules' }, + { value: 'antislop-code', label: 'antislop-code', hint: 'code comment rules' }, ] function stop(message) { @@ -26,7 +27,7 @@ function stop(message) { async function main() { if (process.argv.includes('--version') || process.argv.includes('-v')) { - console.log('antislop 3.0.2') + console.log('antislop 3.1.0') return } diff --git a/cli/lib/banner.mjs b/cli/lib/banner.mjs index a2bb3b9..b85a3e5 100644 --- a/cli/lib/banner.mjs +++ b/cli/lib/banner.mjs @@ -14,8 +14,8 @@ export function banner() { '', ...LOGO, '', - ' ' + pc.dim('Anti AI Slop: Design & Copy Rules'), - ' ' + pc.dim('installer v3.0.2'), + ' ' + pc.dim('Anti Slop: Rules for AI Coding Agents'), + ' ' + pc.dim('installer v3.1.0'), '', ].join('\n') } diff --git a/cli/lib/install.mjs b/cli/lib/install.mjs index 357eb00..2529703 100644 --- a/cli/lib/install.mjs +++ b/cli/lib/install.mjs @@ -87,6 +87,7 @@ const SKILL_LINES = { 'antislop-copywriting': 'Copy & text: `antislop-copywriting`', 'antislop-human': 'People: `antislop-human`', 'antislop-layoutmobile': 'Mobile / responsive: `antislop-layoutmobile`', + 'antislop-code': 'Code comments: `antislop-code`', } // Names the skills instead of importing the core. The skills sit in the agent's @@ -96,7 +97,7 @@ function pointerBlock(skills) { return [ POINTER_START, '## antislop', - 'For UI, copy, people, or mobile layout work, load the antislop skill for the task:', + 'For UI, copy, people, mobile layout, or code comments work, load the antislop skill for the task:', ...skills.filter((s) => SKILL_LINES[s]).map((s) => `- ${SKILL_LINES[s]}`), 'Before starting, ask the user when antislop applies: during the work, or after it is done.', POINTER_END, diff --git a/cli/package-lock.json b/cli/package-lock.json index 172f593..b7973cc 100644 --- a/cli/package-lock.json +++ b/cli/package-lock.json @@ -1,12 +1,12 @@ { "name": "antislop-ai", - "version": "3.0.2", + "version": "3.1.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "antislop-ai", - "version": "3.0.2", + "version": "3.1.0", "license": "MIT", "dependencies": { "@clack/prompts": "^1.7.0", diff --git a/cli/package.json b/cli/package.json index c9f012d..51c26d8 100644 --- a/cli/package.json +++ b/cli/package.json @@ -1,7 +1,7 @@ { "name": "antislop-ai", - "version": "3.0.2", - "description": "Interactive installer for the antislop skills. Anti AI Slop: Design & Copy Rules.", + "version": "3.1.0", + "description": "Interactive installer for the antislop skills. Anti Slop: Rules for AI Coding Agents.", "type": "module", "bin": { "antislop-ai": "index.mjs" diff --git a/cli/scripts/sync-skills.mjs b/cli/scripts/sync-skills.mjs index f48f888..773f661 100644 --- a/cli/scripts/sync-skills.mjs +++ b/cli/scripts/sync-skills.mjs @@ -10,7 +10,7 @@ const cliSkills = path.join(__dirname, '..', 'skills') const CORE_FRONTMATTER = [ '---', 'name: antislop', - 'description: "Anti AI Slop: Design & Copy Rules. The core rules filter for AI coding agents. Load always to stop generic AI slop."', + 'description: "Anti Slop: Rules for AI Coding Agents. The core filter. Load always to stop generic AI slop."', 'allowed-tools: Read Write Edit Glob Grep', '---', '', diff --git a/guide.md b/guide.md index 6766b6d..8205958 100644 --- a/guide.md +++ b/guide.md @@ -19,6 +19,7 @@ antislop is not only for building pages. Any AI output that can get sloppy benef - Build a new page or app: layout, color, parts of the page, animation, structure. - Write or rewrite copy: headlines, buttons, emails, and tone that do not sound AI-made. - Keep the page usable by people: readable colors, keyboard use, clear focus, and button states. +- Clean up code comments: remove the generic AI ones, keep the ones that matter. - Check work you already have: it can list what to fix. The main file (the core) covers all of it. Skills (see What is a skill?) go deeper into one concern when you want more. @@ -49,8 +50,9 @@ A skill is an optional folder (with a `SKILL.md` inside) that goes deeper into o - `antislop-copywriting`: the text. Headlines, buttons, tone, made-up statistics. - `antislop-human`: the people. Readable colors, keyboard use, clear focus, and button states. - `antislop-layoutmobile`: the small screen. Layout that reflows on a phone, tap targets, navigation. +- `antislop-code`: the comments in your code. Remove the generic AI ones, keep the ones that carry information. -Pick the one that matches your work. UI work means `antislop-ui`. Copy work means `antislop-copywriting`. People work means `antislop-human`. Mobile layout work means `antislop-layoutmobile`. More than one? Ask for "All". None? The core alone is enough. +Pick the one that matches your work. UI work means `antislop-ui`. Copy work means `antislop-copywriting`. People work means `antislop-human`. Mobile layout work means `antislop-layoutmobile`. Code comments work means `antislop-code`. More than one? Ask for "All". None? The core alone is enough. ## How to install @@ -118,7 +120,7 @@ The main file holds everything: the rules and the wizard. Skills are optional de ## Where is this going? -The skill plan is complete. antislop v3.0.0 is now packaged: installable as skills, installable as a plugin, and still available as one file. See the roadmap, the page that lists what is coming next, [here](ROADMAP.md). +antislop is packaged: installable as skills, installable as a plugin, and still available as one file. Skills keep shipping as they are ready; the next one is `antislop-code`. See the roadmap, the page that lists what is coming next, [here](ROADMAP.md). ## Feedback diff --git a/skills/antislop-code/README.md b/skills/antislop-code/README.md new file mode 100644 index 0000000..ace6bf0 --- /dev/null +++ b/skills/antislop-code/README.md @@ -0,0 +1,11 @@ +# antislop-code + +Code comment rules for generated code. When your AI tool writes or edits code comments, this skill removes the ones that read as generic AI (decorative separators, restating the obvious, step-by-step narration) and keeps the ones that carry real information. Part of the antislop system. + +## What it is not + +Not about banning comments, and it never rewrites your code. It only removes comments that read as generic AI and keeps the ones that matter. The code stays exactly as it is. + +## Where the rules live + +Your AI agent loads this together with the core rules in `antislop.md`. The full detail is in `SKILL.md` in this folder. diff --git a/skills/antislop-code/SKILL.md b/skills/antislop-code/SKILL.md new file mode 100644 index 0000000..dddad43 --- /dev/null +++ b/skills/antislop-code/SKILL.md @@ -0,0 +1,119 @@ +--- +name: antislop-code +description: "Code comment hygiene for AI coding agents: remove generic AI-slop comments, keep the valuable ones, never touch the code." +allowed-tools: Read Write Edit Glob Grep +--- +# antislop-code + +> Anti Slop: Rules for AI Coding Agents. Code Comments skill + +> Part of the antislop system. Read together with `antislop.md` (the core). This skill filters comments that read as generically AI (decorative, restating the obvious, stiff, loud) while preserving the comments that carry real information. It references core rules by number and never duplicates or renumbers them. Load it when the task writes or edits code comments. + +## How to use this skill + +- Load together with `antislop.md` whenever the task touches code comments. The core holds the mechanism (the purpose test, the three tiers, the Delivery Gate); this skill holds comment-specific depth. +- Every entry has the same shape: **Tell** (the pattern), **Why** (why it reads as slop), **Fix** (what to do instead), with the governing core rule cited as R-XX. +- **Scope guardrail:** this skill only modifies comments. Never modify executable code, identifiers, imports, formatting, indentation, whitespace, control flow, or logic. When in doubt, leave the code untouched. +- The Delivery Gate in the core remains the gate. The "Code Comment Checklist" at the end of this file is the comment-specific supplement to run alongside it. + +## Comments That Add Nothing + +### Decorative Separators + +- **Tell:** banner comments built from repeated characters, ALL CAPS labels, or box drawing around a section name: `// =======================` around `Authentication`, `// -------- WORKFLOW --------`, or a `/* ---- ROUTES ---- */` header. +- **Why:** the decoration is the message. A label wrapped in `=` or `-` signals "AI made this" without adding information, and ALL CAPS reads as shouting. +- **Fix:** replace with a single plain line, or remove entirely if the label adds nothing (R-31). + +### Restating the Obvious + +- **Tell:** a comment that repeats what the next line or declaration already shows, like `// Initialize the variable` above `let count = 0`, `// User class` above `class User {}`, `// Validate user` above `function validateUser()`, or `const userAge = 25; // User age is 25`. +- **Why:** it doubles the reading load without adding anything. The code already says it; the comment just repeats it. +- **Fix:** remove and leave the line of code alone. + +### Workflow Narration + +- **Tell:** comments that narrate the flow step by step, like `// Step 1: Validate input`, `// Step 2: Process request`, `// Step 3: Return response`, or `// First...`, `// Next...`, `// Finally...`. +- **Why:** the control flow is visible in the code itself. Numbering it reads as a checklist, not an explanation. +- **Fix:** remove. If the flow is genuinely hard to follow, that is a structure problem, not a missing comment problem. + +### Empty Labels + +- **Tell:** generic labels with no information behind them: `// Main logic`, `// Core logic`, `// Business logic`, `// Helper function`, `// Entry point`, `// Error handling`, or `// Note: This is important.` / `// Important: Please read.` +- **Why:** the label names a category, not a fact. "Main logic" tells the reader nothing they could not infer from the code. +- **Fix:** remove unless the label carries specific information. "Note: retries happen only on 5xx" earns its place; "Note: this is important" does not. + +### Vague Placeholders + +- **Tell:** comments that promise future work without saying what: `// TODO: Improve this`, `// Future improvements`, `// Additional optimization can be added here`, `// Add more validation`. +- **Why:** a vague TODO is noise. It names a feeling (this could be better) instead of a task (what, and why). +- **Fix:** remove. Keep a TODO only when it names a specific task with enough context to act on. + +### Signature Echo + +- **Tell:** documentation that only restates the signature, like a JSDoc block that repeats `@param price The price.` and `@returns Total price.` for a function whose name and parameters already say all of it. +- **Why:** docs that echo the signature add length, not understanding. The reader learns nothing new. +- **Fix:** simplify or remove the echo. Keep documentation that explains business rules, edge cases, assumptions, algorithms, limitations, side effects, API behavior, or security implications. Never strip real documentation. + +### Decorative Emoji + +- **Tell:** emoji used as decoration in comments, like `// ✅ Validation` or `// 🚀 Performance`. +- **Why:** emoji is visual noise in code, and the specific set (✅, 🚀, 🔒) is the AI default vocabulary. +- **Fix:** replace with plain English, or remove if the label adds nothing. + +### End Markers + +- **Tell:** comments that only mark the end of a block, like `} // end if`, `# End of function`, or `// End processOrder`. +- **Why:** the closing brace already ends the block. The marker exists out of habit, not need. +- **Fix:** remove. In the rare case an end marker genuinely helps a long file, keep it only where it prevents confusion, not as a habit. + +## How It Should Read + +### Line-by-Line Narration + +- **Tell:** a comment on every trivial statement, narrating each line as it is written: `// Initialize count`, then `// Loop items`, then `// Get item`, then `// Increment`, then `// Return result`. +- **Why:** when every line is commented, none of the comments matter. The reader has to check each one to find the one that carries meaning. +- **Fix:** write one concise comment per logical block instead of one per line. If the block needs no comment, write none. + +### Stiff or Loud Wording + +- **Tell:** comments that sound formal, long, or shout: "This function is responsible for validating whether the supplied credentials are valid before continuing with the authentication process", or `// MAIN LOGIC` in caps. +- **Why:** formal and loud wording reads as generated, not as an engineer leaving a note for the next person. +- **Fix:** write short, sentence-case lines in a natural developer voice: `// Validate credentials before issuing a token.` Good comments explain why, not what, and they stay short. + +## Not a Ban (preserve these) + +Never remove comments that explain: + +- business logic and intent +- architectural decisions +- security considerations +- performance trade-offs +- concurrency behavior +- protocol details +- API contracts +- workarounds +- edge cases and assumptions +- licensing and legal notices + +Example that must stay: + +```js +// Stripe may retry webhook deliveries for up to three days. +// Ignore duplicate events using the event ID. +``` + +A comment earns its place when it explains something the code does not already show: the reason, the constraint, the non-obvious behavior. + +## Code Comment Checklist + +Run these alongside the core Delivery Gate when the task touches comments. All answers must be **yes**: + +- [ ] Does every comment add information the code does not already show? (R-31) +- [ ] Do the comments avoid decorative separators, ALL CAPS banners, and box-drawn headers? +- [ ] Do the comments avoid restating the obvious line, declaration, or signature? +- [ ] Do the comments avoid step-by-step workflow narration? +- [ ] Do the comments avoid empty labels and vague TODOs that name no task? +- [ ] Do the comments avoid decorative emoji and end markers? +- [ ] Is the comment density one per logical block, not one per line? +- [ ] Do the remaining comments read short, natural, and in sentence case? +- [ ] Is the scope guardrail held: only comments changed, the code untouched? diff --git a/skills/antislop-copywriting/README.md b/skills/antislop-copywriting/README.md new file mode 100644 index 0000000..90be8ed --- /dev/null +++ b/skills/antislop-copywriting/README.md @@ -0,0 +1,11 @@ +# antislop-copywriting + +Copy and text rules for generated prose. When your AI tool writes headlines, landing pages, or product copy, this skill checks the text for the patterns that give AI-written prose away and fixes them. Part of the antislop system. + +## What it is not + +Not a thesaurus, and not a tone guide that makes your text fancier. It only removes the patterns that make AI-written prose easy to spot. The voice and the actual wording stay yours. + +## Where the rules live + +Your AI agent loads this together with the core rules in `antislop.md`. The full detail is in `SKILL.md` in this folder. diff --git a/skills/antislop-copywriting/SKILL.md b/skills/antislop-copywriting/SKILL.md index 89b1aa5..84d8ffc 100644 --- a/skills/antislop-copywriting/SKILL.md +++ b/skills/antislop-copywriting/SKILL.md @@ -5,7 +5,7 @@ allowed-tools: Read Write Edit Glob Grep --- # antislop-copywriting -> Anti AI Slop: Design & Copy Rules. Copy & Text skill +> Anti Slop: Rules for AI Coding Agents. Copy & Text skill > Part of the antislop system. Read together with `antislop.md` (the core). This skill deep-dives the copy and text concern: headlines, CTAs, tone, value propositions, and the patterns that make AI-written prose easy to spot. It references core rules by number and never duplicates or renumbers them. Load it when the task writes or edits marketing copy, product copy, landing-page text, or any prose meant for people to read. diff --git a/skills/antislop-human/README.md b/skills/antislop-human/README.md new file mode 100644 index 0000000..d86a8cc --- /dev/null +++ b/skills/antislop-human/README.md @@ -0,0 +1,11 @@ +# antislop-human + +Human and accessibility rules for generated UI. When your AI tool builds an interface, this skill checks that real people with different eyes, hands, and setups can use it: contrast, keyboard, focus, and states. Part of the antislop system. + +## What it is not + +Not a replacement for real accessibility testing, and not a style pass. It keeps the UI usable by people. A human check still runs last. + +## Where the rules live + +Your AI agent loads this together with the core rules in `antislop.md`. The full detail is in `SKILL.md` in this folder. diff --git a/skills/antislop-human/SKILL.md b/skills/antislop-human/SKILL.md index cf065b1..0287951 100644 --- a/skills/antislop-human/SKILL.md +++ b/skills/antislop-human/SKILL.md @@ -5,7 +5,7 @@ allowed-tools: Bash(python *) Bash(python3 *) Read Write Edit Glob Grep --- # antislop-human -> Anti AI Slop: Design & Copy Rules. Human skill +> Anti Slop: Rules for AI Coding Agents. Human skill > Part of the antislop system. Read together with `antislop.md` (the core). This skill deep-dives the human concern: the UI must stay usable by people with different eyes, hands, and setups. Contrast, keyboard, focus, states, and the mobile details that exclude people. diff --git a/skills/antislop-human/contrast-mcp.py b/skills/antislop-human/contrast-mcp.py index 7cba5b0..045c01b 100644 --- a/skills/antislop-human/contrast-mcp.py +++ b/skills/antislop-human/contrast-mcp.py @@ -9,7 +9,7 @@ import sys PROTOCOL_VERSION = "2024-11-05" SERVER_NAME = "antislop-contrast" -SERVER_VERSION = "3.0.2" +SERVER_VERSION = "3.1.0" TOOLS = [ { diff --git a/skills/antislop-layoutmobile/README.md b/skills/antislop-layoutmobile/README.md new file mode 100644 index 0000000..2a1c43a --- /dev/null +++ b/skills/antislop-layoutmobile/README.md @@ -0,0 +1,11 @@ +# antislop-layoutmobile + +Mobile layout rules for generated interfaces. When your AI tool builds a layout, this skill checks that it still holds up on a small screen: breakpoints, grids, overflow, tap targets, and navigation. Part of the antislop system. + +## What it is not + +Not a responsive framework, and it will not write your CSS. It checks that a layout holds up on a phone and fixes what breaks. The layout structure stays yours. + +## Where the rules live + +Your AI agent loads this together with the core rules in `antislop.md`. The full detail is in `SKILL.md` in this folder. diff --git a/skills/antislop-layoutmobile/SKILL.md b/skills/antislop-layoutmobile/SKILL.md index e3033bf..7a143b1 100644 --- a/skills/antislop-layoutmobile/SKILL.md +++ b/skills/antislop-layoutmobile/SKILL.md @@ -5,7 +5,7 @@ allowed-tools: Read Write Edit Glob Grep --- # antislop-layoutmobile -> Anti AI Slop: Design & Copy Rules. Mobile Layout skill +> Anti Slop: Rules for AI Coding Agents. Mobile Layout skill > Part of the antislop system. Read together with `antislop.md` (the core). This skill deep-dives the mobile layout concern: how a layout must reflow on small screens. Breakpoints, scale, grids, overflow, tap targets, and navigation. It references core rules by number and never duplicates or renumbers them. Load it when the task builds or edits a layout that has to hold up on a phone. diff --git a/skills/antislop-ui/README.md b/skills/antislop-ui/README.md new file mode 100644 index 0000000..8212990 --- /dev/null +++ b/skills/antislop-ui/README.md @@ -0,0 +1,11 @@ +# antislop-ui + +UI and visual rules for generated interfaces. When your AI tool builds or edits a website, app, or dashboard, this skill checks the result for the patterns that give AI-generated work away (decorative emoji, filler data like "John Doe", generic AI icons) and fixes them. Part of the antislop system. + +## What it is not + +Not a design system, and not a way to make your design prettier or more modern. It only filters the slop. The visual taste and the actual design stay with you. + +## Where the rules live + +Your AI agent loads this together with the core rules in `antislop.md`. The full detail is in `SKILL.md` in this folder. diff --git a/skills/antislop-ui/SKILL.md b/skills/antislop-ui/SKILL.md index 5d25188..4badc42 100644 --- a/skills/antislop-ui/SKILL.md +++ b/skills/antislop-ui/SKILL.md @@ -5,7 +5,7 @@ allowed-tools: Read Write Edit Glob Grep --- # antislop-ui -> Anti AI Slop: Design & Copy Rules. UI & Visual skill +> Anti Slop: Rules for AI Coding Agents. UI & Visual skill > Part of the antislop system. Read together with `antislop.md` (the core). This skill deep-dives the UI/visual concern: color, layout, components, decoration, structural flow, and motion. It references core rules by number and never duplicates or renumbers them. Load it when the task builds or edits a website, web app, or any interface. @@ -135,6 +135,12 @@ allowed-tools: Read Write Edit Glob Grep - **Why:** these glyphs are the generic vocabulary of "AI product". They communicate nothing about the specific feature. - **Fix:** use icons genuinely relevant to the content, with the relevance written down when the glyph is generic (R-04). If no appropriate icon exists, use none. The feature label does the work. +### Emoji as Decoration + +- **Tell:** literal emoji scattered through the copy, headings, badges, and buttons: 🚀 in a headline, ✅ beside every feature bullet, 🔥 on a CTA, 📈 above a chart title. +- **Why:** emoji is the loudest shorthand for "this was generated, not written". In a UI it competes with the content for attention and flattens the product's voice into the same cheerful default as every other AI site. +- **Fix:** remove emoji from UI text. If a concept needs a mark, use a real, relevant icon with the reason written down (R-04), or no mark at all. The copy carries the meaning; the emoji adds nothing. + ### Small Arrows on Every Button - **Tell:** `→` or `↗` placed on almost every button as pure decoration. @@ -213,6 +219,12 @@ The patterns above are landing-page shapes. These are the app-side equivalents: - **Why:** the columns come from the table component, not from the data. The user scans for the field that decides their next move and it is not there. - **Fix:** pick columns from the decision the user makes in this table, and put the deciding field early. The row menu holds actions that exist; anything that does nothing comes out (R-26). +### Filler Data in Fields and Columns + +- **Tell:** empty form fields and table columns filled with fake but plausible data: `John Doe`, `johndoe@example.com`, `"Let's build something"`, phone numbers and dates that belong to nobody. +- **Why:** fabricated content disguised as real. It reads fine in a mockup and falls apart the moment a real user looks: the name is not a customer, the email is not a lead, and the message is a tagline. It is the strongest tell that the screen was generated, not built. +- **Fix:** leave empty cells empty, or use placeholders that clearly say what goes there: `Your Name`, `email@example.com`, `Drop your message here...`, or `[REAL DATA]` when a value is expected (R-23, R-38). Real data goes in when it exists. Generic filler copy like "Let's build something" is buzzword slop and does not belong in a data column (R-16). + ### Placeholder Empty and Loading States - **Tell:** "No data available" with an illustration, a bare spinner, or a full-page skeleton that mimics a layout the real data never fills. @@ -239,11 +251,13 @@ Run these alongside the core Delivery Gate when the task is UI work. All answers - [ ] Is the palette derived from `DESIGN.md` or a written brand identity, not the default gradient set? (R-01, R-29) - [ ] Is the accent used at the key moment only, not spread across every element? (core Part 3, one deliberate accent) +- [ ] Is the copy free of decorative emoji scattered through headings, bullets, and buttons? (R-04) - [ ] Do section compositions vary according to the declared RHYTHM dial instead of repeating one template? (R-05) - [ ] Does every navigation item and interactive element have a real destination or behavior, or a visible "Coming soon" label? (R-24, R-26) - [ ] Does motion follow the declared MOTION dial and serve a written purpose, with no endless loops? (R-19) - [ ] Is glass, glow, shadow, and radius used at their dose caps, not as a page-wide default? (R-10, R-11, R-12, R-13) - [ ] On an app screen, is the layout built around the decision the user makes there, rather than the sidebar plus stat row plus chart plus table default? (C-3, R-20) - [ ] Is every number, delta, feed entry, and table row real or a labelled placeholder, with no invented metrics? (R-17, R-18, R-38) +- [ ] Do empty form fields and table cells stay empty or carry honest placeholders (Your Name, email@example.com) instead of fake-looking data (John Doe, johndoe@example.com)? (R-23, R-38) - [ ] Do the empty, loading, and error states name the cause and the next action instead of saying "No data"? (R-27) - [ ] Does the page hold up at every breakpoint, theme, and state, and pass keyboard-only use? (R-03, R-34, C-4) diff --git a/skills/antislop/README.md b/skills/antislop/README.md new file mode 100644 index 0000000..31c46dc --- /dev/null +++ b/skills/antislop/README.md @@ -0,0 +1,15 @@ +# antislop + +The core. Anti Slop: Rules for AI Coding Agents. A filter that stops generated UI and copy from reading as generic "AI slop". It is a filter, not a style guide: no prescribed colors, fonts, or layouts. + +## What it is + +The core rules always load. They have mandatory rules in three tiers, a Liveliness Toolkit, and a Delivery Gate that checks the work before it ships. The core works alone or with the deeper skills next to it (ui, copywriting, human, layoutmobile, code), one per concern. + +## What it is not + +Not a style guide and not a design system. It does not pick colors, fonts, or layouts, and it never beautifies on its own. Direction comes from you and your DESIGN.md. + +## Where the rules live + +The source is `antislop.md` at the repo root. `SKILL.md` in this folder is the same rules packaged as a skill so your AI agent can load it directly. diff --git a/skills/antislop/SKILL.md b/skills/antislop/SKILL.md index f256f0b..3860b39 100644 --- a/skills/antislop/SKILL.md +++ b/skills/antislop/SKILL.md @@ -1,11 +1,11 @@ --- name: antislop -description: "Anti AI Slop: Design & Copy Rules. The core rules filter for AI coding agents. Load always to stop generic AI slop." +description: "Anti Slop: Rules for AI Coding Agents. The core filter. Load always to stop generic AI slop." allowed-tools: Read Write Edit Glob Grep --- # antislop -> Anti AI Slop: Design & Copy Rules +> Anti Slop: Rules for AI Coding Agents > Follow these rules whenever generating or building UI for a website, web app, or any interface. > The goal: the design should feel **crafted by a designer**, not generated by AI. @@ -23,13 +23,14 @@ If no antislop pointer exists and this file is being read for the first time, ru > If the user can use a terminal, the packaged install is better: run `npx antislop-ai` (interactive picker) or `npx skills add miqdadbadjuber/anti-slop`, then skip this section. The steps below are the manual fallback for chat-only setups. -1. **Declare the setup before doing anything.** Tell the user you will (a) download the skill(s) they choose into `skills//` subfolders next to this file, and (b) append an antislop pointer block at the end of the project's entry file. Get approval. Never modify the entry file silently. +1. **Declare the setup before doing anything.** Tell the user you will (a) get the chosen skill(s) in place in `skills//` subfolders next to this file (the user fetches them; the agent never downloads from the network, see step 4), and (b) append an antislop pointer block at the end of the project's entry file. Get approval. Never modify the entry file silently. 2. **Ask which skills to install** (multi-select, in the user's chat language). List only the skills that exist in this version of antislop: - **1. All** (recommended): install every available skill. Choose this when the work spans UI, copy, people, or mobile layout. - **2. `antislop-ui`** (UI / visual): pick this for building or editing a website, web app, or interface: color, layout, components, decoration, motion. - **3. `antislop-copywriting`** (copy & text): pick this for writing or editing copy: headlines, CTAs, value propositions, tone, landing-page text, product prose. - **4. `antislop-human`** (people): pick this for making sure a UI works for people with different eyes, hands, and setups: contrast, keyboard, focus, states. - **5. `antislop-layoutmobile`** (mobile / responsive): pick this for layouts that have to hold up on a phone: breakpoints, scale, grids, overflow, tap targets. + - **6. `antislop-code`** (code comments): pick this for writing or editing code comments: remove generic AI-slop comments, keep the valuable ones, never touch the code. - New skills appear here as they ship; never offer a skill that does not exist in this version. If the user declines or says "core only", stop here and use this file alone as the filter. Do not install anything. @@ -42,11 +43,12 @@ If no antislop pointer exists and this file is being read for the first time, ru ```md ## antislop - For UI, copy, people, or mobile layout work, read `antislop.md` (core) and then the skill for the task: + For UI, copy, people, mobile layout, or code comments work, read `antislop.md` (core) and then the skill for the task: - UI / visual: `skills/antislop-ui/SKILL.md` - Copy & text: `skills/antislop-copywriting/SKILL.md` - People: `skills/antislop-human/SKILL.md` - Mobile / responsive: `skills/antislop-layoutmobile/SKILL.md` + - Code comments: `skills/antislop-code/SKILL.md` Before starting, ask the user when antislop applies: during the work, or after it is done. ```