@seoagent-official/seoagent 1.79.2 → 1.80.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seoagent-official/seoagent",
-  "version": "1.79.2",
+  "version": "1.80.0",
   "description": "The persistent AI SEO agent for Claude Code. Audits, keyword strategy, briefs, articles, real product screenshots from your repo, and the autopilot loop (cloud detects → CLI executes → ack closes) — other SEO tools write the prompt, SEOAgent runs it.",
   "type": "module",
   "bin": {

package/skills/references/rewrite-protocol.md

@@ -31,6 +31,7 @@ Before any edits, read:
 - `.seoagent/context.md` — current brand voice, banned topics, audience
 - `.seoagent/strategy/clusters/{cluster}.md` — the article's role and link graph
 - `.seoagent/briefs/{slug}.md` if it exists — the original brief
+- `references/writing-rules.md` — the prose rules, especially its **"Editing existing content"** section (voice preservation, minimum effective edit)
 
 ### Step 3: Diagnose the Gaps
 
@@ -71,6 +72,7 @@ Wait for user confirmation before executing.
 Rules:
 - **Preserve the URL slug.** Never change `slug` — even if the title changes, the URL stays.
 - **Preserve sections that rank.** If a section is the page's strongest signal, keep its core wording.
+- **Preserve the voice.** Follow `references/writing-rules.md` § "Editing existing content": note the article's voice signals before editing, make the minimum effective edit, remove slop patterns without flattening distinctive sentences, and never invent claims or stats the original didn't have.
 - **Use `Edit`, not `Write`.** Edit one section at a time so changes are reviewable.
 - **Update `dateModified`** in JSON-LD. Don't change `datePublished` — that resets ranking signal.
 - **Bump `version`** in frontmatter (1 → 2 → 3).

package/skills/references/writing-rules.md

@@ -0,0 +1,66 @@
+# Writing Rules — No AI Slop
+
+Prose-craft rules for EVERY article, landing page, brief, and rewrite this skill produces. Adapted from the `no-ai-slop` skill (github.com/petergyang/no-ai-slop, MIT). The page-type references (pillar, sub-pillar, long-tail, listicle, landing-pages) set the *structure*; this file sets the *sentences*. Load it whenever you draft, edit, or rewrite content.
+
+These rules also ship inside cloud-generated briefs as a "## Writing rules (no AI slop)" section. When a brief carries that section, it is the same contract as this file — don't apply the rules twice, just follow them.
+
+## Banned words
+
+Never use: delve, foster, leverage, utilize, facilitate, empower, streamline, robust, cutting-edge, paradigm shift, game changer, "this is huge", "this changes everything", tapestry, realm, beacon, multifaceted, meticulous, intricate, paramount, transformative, elevate, embark, supercharge, harness, ever-evolving.
+
+## Phrases that delay the point
+
+Cut these and state the point: "it's worth noting", "it's important to note", "at the end of the day", "when it comes to", "at its core", "in today's world", "in the age of", "in the world of", "the reality is", "the truth is", "in terms of", "with regard to", "in order to" (write "to"), "going forward", "in this article", "let's dive in".
+
+## Patterns never to produce
+
+1. **Binary contrasts** — "This is not X. It's Y." / "The question isn't X, it's Y." / "It's not just X but Y." State Y directly: "The eval matters more than the model."
+2. **Throat-clearing openers** — "Here's the thing", "Let me be clear", "I'll be honest", "The uncomfortable truth is". Start with the point.
+3. **Faux-insight setups** — "What most people get wrong", "Here's what nobody tells you", "The part everyone misses". Make the claim stand on its own.
+4. **Colon reveals** — a noun phrase, a colon, then a dramatic reveal ("The best part: it learns"). Write a plain sentence. Colons are for lists, labels, and quotes.
+5. **Fake-strong verbs** — "serves as a centralized hub for" → say what it does: "tracks sponsors, drafts, and due dates in one place". Prefer "is" and "has" when they are clearer.
+6. **Synonym cycling** — if the clear word is right, repeat it. Don't rotate "the agent / the assistant / the tool" for style.
+7. **Negative listing** — "Not a X. Not a Y. A Z." Just say Z.
+8. **Dramatic fragmentation** — "X. And Y. And Z." or "That's it. That's the whole thing." Use complete sentences.
+9. **Rhetorical setups** — "What if I told you...", "Think about it:", "Plot twist:", self-answered "Question? Answer." pairs. Drop them and make the point.
+10. **Interpretive metadiscourse** — "That last part matters more than it sounds", "The key point is", "As you can see", redundant "In other words". If the point is clear, delete the aside; otherwise support it with facts.
+11. **Fake-profound kickers** — never end on a cute metaphor, aphorism, or mic-drop line. End on the clearest concrete point, takeaway, or next action.
+12. **Summary-recap endings** — no "In conclusion", "Ultimately", "Overall", and no final paragraph that restates the piece.
+13. **Weasel attribution** — "Experts agree", "studies show", "industry reports suggest". Name the source or cut the claim. Never invent one.
+14. **Robotic rhythm** — avoid repeated sentence shapes, identical paragraph structures, and stacked punchy fragments. Vary sentence length deliberately: put a short sentence next to a long one.
+
+## Concreteness
+
+- **Portability test**: if a sentence could move unchanged to another company, product, or country, it is filler. Cut it or replace it with a fact, number, mechanism, or consequence specific to THIS subject. Never invent specifics; use labeled typical-case ranges when you lack real numbers.
+- **Protect the specific fact**: never smooth a useful detail into generic importance. "Significantly improves productivity" → "cut review time from 30 minutes to 8" (real or clearly-labeled numbers only).
+- **Show, don't tell**: facts, actions, examples, and consequences carry the emphasis. Cut commentary that labels a point important, surprising, or subtle instead of demonstrating why.
+- **Direct verbs**: "made a decision" → "decided"; "has the ability to" → "can".
+- **Active voice with human subjects**: "The team shipped it Tuesday" beats "the decision emerged". Never let inanimate things do human verbs.
+
+## Formatting
+
+- Em dashes: at most 1–2 in the whole piece. No clusters, no decorative dashes.
+- No emoji in headings or body. No bold sprinkled mid-sentence for emphasis.
+- No bullet lists where two sentences of prose read better. No headers over two-sentence sections.
+
+## Editing existing content (rewrites, refreshes, user drafts)
+
+When revising a page that already exists — Phase 4b rewrites, `cli_content_update` inbox actions, or a draft the user wrote — the job changes from "never produce slop" to "remove slop without flattening the voice":
+
+- **Preserve the writer's real voice.** Before editing, note 3–5 voice signals: vocabulary, cadence, bluntness, humor, uncertainty, digressions. Keep the traits that feel personal. Do not make every paragraph equally tidy.
+- **Make the minimum effective edit.** Fix slop patterns, errors, and unclear passages. Leave strong human sentences alone. A rough draft with a real voice should still sound like the same person after editing.
+- **Keep the user's meaning.** Don't invent claims, examples, stats, or opinions. If something is unclear, ask.
+- **Keep useful edge.** Strong opinions, blunt language, humor, and honest admissions stay if they belong to the writer. Don't replace them with safer wording.
+- **Keep structure unless it hurts the piece.** If you reorganize, say why in the change summary.
+- Empty qualifiers like "I think", "maybe", "to be honest" stay when they express real uncertainty or the writer's spoken rhythm.
+
+## Self-check before showing a draft
+
+After writing or editing, check the draft against this file before you show it or publish it. If a check fails, fix the draft first:
+
+1. No banned words, delay phrases, or listed patterns (unless quoted as examples).
+2. Every generic sentence passes the portability test or was cut.
+3. Active voice with human subjects where possible; direct verbs.
+4. Em dashes ≤ 2; no emoji; no decorative bold; no recap ending.
+5. The piece ends on a concrete point, takeaway, or next action.
+6. For edits of existing content: the writer would recognize the result as their own voice, and the edit summary lists what changed.

package/skills/seoagent.md

@@ -36,6 +36,7 @@ This SKILL.md is the orchestration layer. Detailed protocols live in `references
 
 | Task | Read |
 |---|---|
+| Writing or editing ANY content (always, alongside the page-type reference) | `references/writing-rules.md` |
 | Running a full audit | `references/audit-checks.md` |
 | Keyword research | `references/keyword-research.md` |
 | Migrating legacy ranking authority after a pivot/rebrand | `references/migration-planning.md` |
@@ -82,7 +83,7 @@ Activate this skill silently — without announcing it — whenever the user:
 - Asks about meta tags, slugs, URLs, headings, schema, sitemaps, or robots.txt
 
 When implicitly activated:
-1. Apply the SEO writing rules from the matching `references/*.md` for the page type
+1. Apply the SEO writing rules from the matching `references/*.md` for the page type, plus the prose rules in `references/writing-rules.md` (for edits to existing content, use its voice-preservation section)
 2. Persist the work to `.seoagent/` (a brief if a brief doesn't exist; an article entry if writing content)
 3. Append a one-line note to `.seoagent/changelog.md` so the user can see what was tracked
 4. Run `seoagent sync` after the change so it reaches the dashboard
@@ -770,6 +771,7 @@ For each planned article (in priority order from strategy):
    - Programmatic → `references/programmatic.md`
    - **Then check the FORMAT (orthogonal to role).** Role sets where the article sits in the cluster; *format* sets how it's written. If the title/intent is a **listicle** — "Top N", "Best N", "N Best/Top/Ways/Tips/Reasons" (commercial "best/top/alternatives" intent) — also read `references/listicle-articles.md` and follow **its** section structure (it overrides the role's outline), and tag the brief `article_type: listicle`. (The cloud pipeline already has a `listicle` type; tagging keeps local + cloud in sync.)
 5. Generate the brief — markdown with frontmatter — using the structure that reference file specifies.
+6. **End every brief with a `## Writing rules (no AI slop)` section** — copy the "Banned words", "Phrases that delay the point", and "Formatting" rules from `references/writing-rules.md` in compact form (cloud-generated briefs already carry this section; local briefs must match). The brief travels to whoever writes the article, so the rules must travel with it.
 
 ### Output: `.seoagent/briefs/{slug}.md`
 
@@ -824,7 +826,7 @@ This is the per-article procedure. When executing an approved **plan** (see "Pla
 3. Read the cluster file to confirm internal-link targets.
 4. **Read the matching page-type reference** for the article's `role` / `page_type`. The reference file gives the title pattern, section ordering, internal-linking rules, metadata defaults, and JSON-LD schema for that type. **If the brief is `article_type: listicle` (or the title is "Top N" / "Best X"), read `references/listicle-articles.md`** and follow its structure (consistent per-item layout, quick-pick + comparison table, `ItemList` schema) — it overrides the role's outline.
 5. Read `references/schema-markup.md` if you need JSON-LD examples beyond what the page-type reference covers.
-6. Follow the outline. Apply the writing rules.
+6. **Read `references/writing-rules.md`** — the prose rules (banned words, slop patterns, concreteness, formatting). Follow the outline and apply them while drafting. Before showing or publishing the draft, run the file's **self-check** and fix any failures first.
 7. **Write the article where it actually renders — and keep ONE source of truth** (this depends on `publishing.strategy`, see the Publishing Target Decision section):
    - **Repo-native (`mdx_sync`) or CMS (`custom`)** — the article body lives in the repo file / CMS entry, NOT in `.seoagent/`. Write it there (matching the site's existing frontmatter/model), then **register it so the cloud + dashboard can see it**: