slopornot

Imported from numen-tech/slopornot (AGENTS.md). Install upstream with npx skills add numen-tech/slopornot. Copyright stays with the author.

SlopOrNot: agent guide

Brief for AI coding agents (Claude Code, Codex, Cursor, Gemini CLI, Aider) editing this repo. The runtime skill itself is skills/agentic-humanizer/SKILL.md; this file is for agents working on the repo, not running the skill.

What this repo is

SlopOrNot is a plugin bundle for assistant workflows built around Slop or Not. It ships two skills. agentic-humanizer runs a full 5-pass humanization workflow with saved preferences and optional voice matching. It works without Slop or Not; Slop or Not Pro only adds on-device AI detector scoring, readability checks, Text Cleanup before and after humanization, and cleanup stats. slop-check is a self-contained one-shot router for the same on-device tools (text and image detection, readability, cleanup, status) with no interview and no harness routing files.

Layout

Critical rules

1. Pre-PR gate, these commands must pass:

   npx markdownlint-cli2@0.18.1 "**/*.md" "#node_modules" "#WARP.md"
   node scripts/check-frontmatter.mjs
   node scripts/check-links.mjs
   node scripts/sync-plugins.mjs --check
   node scripts/check-plugin-packaging.mjs
   node scripts/check-versions.mjs
   node --test scripts/*.test.mjs
   make -C claude-skills check

   GitHub also requires lint and Run zizmor on every PR. Do not add PR path filters to required workflows unless the repository ruleset is updated in the same change.

   Releases are automated: run the "Prepare release" workflow with a version, review and merge the release/v* PR it opens, and the publish workflow tags, creates the GitHub Release, and runs make dist to attach agentic-humanizer-claude-desktop.zip and agentic-humanizer-chatgpt.zip. The prepare workflow needs the RELEASE_APP_TOKEN repo secret (a GitHub App or fine-grained PAT with contents and pull-requests write). It also honors an optional DEEPSEEK_API_KEY secret: when set, prepare auto-drafts a Highlights summary atop the release notes for review; when absent, the release proceeds unchanged.

2. No em-dashes in README.md, SKILL.md, CHANGELOG.md, AGENTS.md, commits, tag annotations, or release notes. Use commas, colons, or parentheses. The user-facing surface of a humanizer can't credibly ship em-dash-laden copy. (Inherited em-dashes in skills/agentic-humanizer/references/ and skills/agentic-humanizer/harnesses/ predate the rule and are getting cleaned up incrementally; do not introduce new ones.)

3. Change skills/agentic-humanizer/references/patterns.md deliberately. The 33-pattern catalogue is the rewrite vocabulary the whole skill depends on; edit it intentionally and keep the numbering and format consistent.

4. Conventional Commits are required, not optional. Format: type(scope): subject. Subject is imperative, lowercase, no trailing period. Allowed types and their changelog mapping:

   Type	Changelog section	Use for
   feat	Added	new behavior, new harness, new reference doc
   fix	Fixed	bug fixes in scripts, lint rules, runtime logic
   perf	Changed	measurable speed or token wins
   refactor	Changed	restructuring without behavior change
   docs	Changed (or omit)	README, AGENTS.md, CHANGELOG, CONTRIBUTING edits
   build / ci	(omit)	workflow, lint config, release tooling
   test	(omit)	adding or fixing tests and fixtures
   chore	(omit)	housekeeping, dependency bumps
   revert	matches reverted type	use revert: <original subject>

   Use ! after the type/scope or a BREAKING CHANGE: footer for breaking changes (these always land in changelog under "Changed" with a "BREAKING" prefix). Common scopes: harnesses, references, docs, ci, chore, scripts. There is no automated commit-to-changelog generator: hand-write each user-visible change into CHANGELOG.md [Unreleased] under the mapped section, and the release script promotes that section verbatim. An entry you forget to add never appears in the next release notes.

5. Doc-sync is part of the change, not a follow-up. Any PR that changes runtime behavior MUST update every affected surface in the same commit (or stack of commits). Use this matrix:

   What you changed	Update these in the same PR
   Runtime constant (AI_THRESHOLD, MAX_ITER, grade tolerance)	skills/agentic-humanizer/SKILL.md, README.md, CHANGELOG.md (Unreleased)
   Interview shape, question count, or order	skills/agentic-humanizer/SKILL.md, README.md, every skills/agentic-humanizer/harnesses/*.md, CHANGELOG.md
   Output format (Step 7 structure, fields, ordering)	skills/agentic-humanizer/SKILL.md, README.md, CHANGELOG.md
   Inline-override grammar or saved-profile schema	skills/agentic-humanizer/SKILL.md, README.md, CHANGELOG.md
   Voice fingerprint behavior, schema, or extraction prompt	skills/agentic-humanizer/SKILL.md, README.md, skills/agentic-humanizer/references/voice-fingerprint.md, skills/agentic-humanizer/references/per-iteration-strategies.md, CHANGELOG.md
   New or renamed reference doc under skills/agentic-humanizer/references/	skills/agentic-humanizer/SKILL.md (links), AGENTS.md (Layout table), scripts/check-links.mjs if it hardcodes paths
   Supported languages, variants, readability kinds, or band mapping in references/multilingual.md	skills/agentic-humanizer/SKILL.md (Steps 3/6/7), all 6 harnesses/*.md, references/per-iteration-strategies.md, claude-skills/agentic-humanizer/SKILL.md, skills/slop-check/SKILL.md, skills/slop-check/references/slop-tools.md, README.md, CHANGELOG.md
   Per-language tell file (references/ai-tells/<code>.md) or a new fixture	AGENTS.md (Layout table), CHANGELOG.md; then run node scripts/sync-plugins.mjs and make -C claude-skills build (the packaging check derives its file list from skills/, so no script edit is needed)
   Harness routing (added, removed, renamed harness)	skills/agentic-humanizer/SKILL.md Step 1, skills/agentic-humanizer/harnesses/<name>.md, README.md, CHANGELOG.md
   Lint rules, CI gates, release scripts	AGENTS.md (Critical rules § 1), CONTRIBUTING.md, CHANGELOG.md
   Slop CLI / MCP install steps	skills/agentic-humanizer/references/slop-cli-setup.md or skills/agentic-humanizer/references/slop-mcp-setup.md, README.md, CHANGELOG.md
   Anything the Desktop fork mirrors (interview shape, output format, runtime constants, inline-override grammar, voice behavior)	claude-skills/agentic-humanizer/SKILL.md and claude-skills/agentic-humanizer/README.md (hand-authored; port the change, keep harness routing out), then make -C claude-skills

   If you can't tell whether a doc is affected, grep it for the symbol you changed. Stale runtime docs mislead users and corrupt the changelog.

6. Every user-visible change appends to CHANGELOG.md § [Unreleased] under the matching Keep-a-Changelog heading (Added, Changed, Fixed, Removed, Deprecated, Security). Internal-only changes (ci, build, test, chore) skip the changelog. The release script promotes [Unreleased] to a versioned section; missing entries can't be recovered after the tag.

7. Don't add new per-iteration strategies that replace the 5-iteration schedule. New strategies must compose with it. Open an issue first.

8. Harness-specific instructions stay in skills/agentic-humanizer/harnesses/<name>.md. Don't sprinkle "Claude Code users…" / "Codex users…" through skills/agentic-humanizer/SKILL.md.

9. Plugin payloads are generated distribution artifacts. Both skills are self-contained: edit canonical runtime files under skills/agentic-humanizer/ or skills/slop-check/, then run node scripts/sync-plugins.mjs. Never hand-edit files under plugins/*/slopornot/skills/. Manifest-only changes may be made directly inside plugin folders.

   The Claude Desktop bundle is a separate generated artifact. Its SKILL.md and README.md under claude-skills/agentic-humanizer/ are hand-authored and intentionally diverge from canonical (no harness routing). Its references/ and examples/ are copied verbatim by make -C claude-skills build; never hand-edit those copies. Run make -C claude-skills check before a PR to catch drift, and make -C claude-skills to rebuild the shippable zip.

Smoke test

/agentic-humanizer
<paste contents of skills/agentic-humanizer/examples/sample-ai-text.md>

Expect convergence by iteration 3 or 4 on the sample fixture. Output structure must match skills/agentic-humanizer/SKILL.md Step 7. With Slop or Not unavailable, expect the same five rewrite passes with n/a score and grade values, no detector-convergence claim, and no Text Cleanup summary.