@maestroagora/agora 1.0.0 → 1.0.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-agora",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "displayName": "Maestro: Agora",
   "description": "Turn verified product truth into concise, argument-first marketing and sales copy across written and spoken channels with the /agora skill.",
   "author": {

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-agora",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Maestro: Agora turns verified product truth into concise, argument-first copy across written and spoken channels.",
   "author": {
     "name": "Mark Laursen",

package/README.md

@@ -12,15 +12,15 @@
   <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-7c3aed" /></a>
 </p>
 
-Agora is a portable Agent Skill for marketing, sales, editorial, interface, outreach, and spoken copy. It gives an AI agent a research-backed argument method, a strict claim gate, channel-aware brevity rules, and written GEO/AEO guidance—without treating a persuasive framework as permission to invent the proof.
+Agora is a portable Agent Skill for marketing, sales, editorial, interface, outreach, and spoken copy. It gives an AI agent a research-backed argument method, a strict claim gate, channel-aware brevity rules, and written GEO/AEO guidance. A persuasive framework is never permission to invent the proof.
 
 Give it product truth, evidence, constraints, and one desired action. The skill instructs the agent to return the shortest complete, ready-to-use draft first.
 
 **One suite: fuse the answer, make the case, guard the spend.**
 
-- **[Maestro Frontier](https://github.com/mbanderas/maestro)** — Fuses the model CLIs you already run into one judged, grounded answer.
-- **[Maestro Agora](https://github.com/mbanderas/maestro-agora)** — Turns verified product truth into concise, argument-first copy without inventing the proof.
-- **[Maestro CostGuard](https://github.com/mbanderas/costguard)** — Audits CI and cloud infrastructure for cost leaks and shows what to fix.
+- **[Maestro Frontier](https://github.com/mbanderas/maestro):** Fuses the model CLIs you already run into one judged, grounded answer.
+- **[Maestro Agora](https://github.com/mbanderas/maestro-agora):** Turns verified product truth into concise, argument-first copy without inventing the proof.
+- **[Maestro CostGuard](https://github.com/mbanderas/costguard):** Audits CI and cloud infrastructure for cost leaks and shows what to fix.
 
 ## Install
 
@@ -71,7 +71,7 @@ Invoke the skill directly, then provide the facts it may use:
 /agora Rewrite this upgrade screen. Keep one CTA. Use only these verified facts: ...
 ```
 
-In Codex, `$agora` and the skills picker can also select the installed skill. Other hosts may expose skills through their own picker or mention syntax; asking the agent to “use the agora skill” remains portable.
+In Codex, `$agora` and the skills picker can also select the installed skill. Other hosts may expose skills through their own picker or mention syntax; asking the agent to "use the agora skill" remains portable.
 
 Agora activates for writing, rewriting, shortening, critiquing, and planning:
 
@@ -89,7 +89,7 @@ Agora silently routes each asset as indexable public, public non-indexable writt
 - **Argument before ornament.** Build one defensible belief shift, one decision path, and one primary action.
 - **Proof beside the claim.** Preserve source, scope, date, qualification, and material limitations.
 - **Shortest complete draft.** Remove repetition before evidence, legal meaning, accessibility, or next-step clarity.
-- **Human voice controls.** Cut stock openings, vague hype, fabricated texture, template residue, and decorative recaps.
+- **Hard writing-tell bans.** Cut Wikipedia-style flagged vocabulary, connectives, templates, significance tails, generated em dashes, curly quotes, fabricated texture, and decorative recaps.
 - **Claim gate.** Narrow, omit, or flag unsupported claims instead of supplying missing features, prices, routes, urgency, scarcity, testimonials, or results.
 - **Ready copy first.** Return one usable draft without exposing private reasoning or producing near-duplicate variants unless asked.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestroagora/agora",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Install Maestro: Agora, the evidence-led marketing skill for AI coding agents.",
   "type": "module",
   "bin": {

package/skills/agora/SKILL.md

@@ -15,6 +15,8 @@ Read [references/agora-marketing.md](references/agora-marketing.md) before produ
 
 Treat current user-supplied facts, product documentation, live behavior, legal constraints, brand guidance, and approved claim sources as product truth. Never treat an example or marketing principle in the reference as authorization for a product claim.
 
+Apply the human-voice and AI-writing-tell gate to every Agora deliverable, regardless of brand, channel, privacy, or indexability. Treat the reference's banned vocabulary, connectives, phrase templates, significance tails, structural patterns, and typography as prohibited by default. Retain an item only when immutable verbatim material, verified proper names, required technical or legal language, or an explicit user or house requirement makes it necessary. Do not generate em dashes or curly or smart quotes in final copy; use straight quotes. Treat these as global `HOUSE` rules, not detector science.
+
 Apply CiteSurge-specific controls only when the request, named product, or active repository is CiteSurge. Ignore those controls for every other brand or app; use that project's verified rules instead. When giving engine-specific technical advice, recheck current official documentation because crawler and product behavior can change.
 
 ## Route the asset
@@ -40,7 +42,7 @@ Classify silently before working:
 7. Make the CTA the logical next step. Name one real action, predict the next screen or commitment, match intent, and add no new claim. Verify the destination or action exists.
 8. Apply written GEO/AEO and citability rules to every written asset: answer early when appropriate, name entities and scope, create self-contained evidence blocks, keep proof beside claims, add genuine information value, structure for reader intent, expose provenance, link contextually, and keep visible and machine-readable facts consistent. Add technical eligibility checks only for indexable public work. Never promise retrieval, selection, quotation, citation, ranking, recommendation, referral, conversion, or revenue.
 9. Skip GEO/AEO formatting for spoken-only delivery. Optimize spoken copy for natural cadence, breath, timing, emphasis, and comprehension. Apply written rules separately to any published derivative.
-10. Run the competitor-swap, read-aloud, defense, continuity, and density tests. Remove vague hype, stock openings, prompt acknowledgements, repeated templates, decorative recaps, generic conclusions, fabricated human texture, and detector-evasion claims.
+10. Run the global competitor-swap, read-aloud, defense, continuity, and tell-density tests. Enforce the output bans: remove banned vocabulary and connectives without a narrow documented exception; prompt acknowledgements; stock phrase templates; significance tails; generated em dashes; curly or smart quotes; generated tripartite templates; `Not only... but also...` constructions; heading restatements; symmetrical blocks; templated bold-label bullets; decorative recaps; unneeded conclusions; fabricated human texture; and detector-evasion claims. Match supplied author samples without copying phrases or inventing biography, experience, motives, opinions, or mistakes.
 11. Compress in the reference's order. Preserve evidence, qualifications, legal terms, accessibility, and next-step clarity. Do not convert `HOUSE`, `C`, `EVIDENCE-INFORMED`, or `TEST` guidance into universal performance claims.
 12. Verify every final factual statement and CTA against supplied sources and current project truth. For CiteSurge work only, apply its claim-ledger, methodology, AI-writing scanner, GEO/AEO positioning, and release controls from the reference.
 

package/skills/agora/references/agora-marketing.md

@@ -64,21 +64,27 @@ When activated, the LLM must:
    captions, show notes, or companion page.
 7. Never invent a product fact, route, price, deadline, result, testimonial,
    source, urgency, scarcity, or proof point.
+8. Apply the human-voice and AI-writing-tell gate to every deliverable. Enforce
+   its global output bans, including zero generated em dashes and zero curly or
+   smart quotes. Use straight quotes.
 
 This is a decision system, not a visible fill-in-the-blanks template. Use only
 the moves the asset needs, and vary the surface structure naturally.
 
 ## Source basis and authority
 
-This handbook synthesizes the two writing references and three research
-reports listed below. The research reports inform the rules but do
-not override the scope or limits of their underlying evidence.
+This handbook synthesizes the Agora writing reference, the consolidated
+human-voice reference, and three research reports listed below. The research
+reports inform the rules but do not override the scope or limits of their
+underlying evidence.
 
 Supplied source set:
 
 - User-provided transcript: `agora style marketing.md` (received 2026-07-17).
-- User-provided reference: `ai-writing-tells-reference (1).md` (received
-  2026-07-17).
+- User-maintained consolidated reference: `Anti-AI-Writing-Tells.md` (updated
+  2026-07-17). It preserves every operational ban from the earlier
+  `ai-writing-tells-reference (1).md`, removes only unsupported numerical
+  detection claims and fixed editing quotas, and adds evidence-backed limits.
 - User-provided research: `Emotional Persuasion and Argument Sequencing in
   Marketing and Sales.md` (received 2026-07-17).
 - User-provided research: `Evidence on Marketing Copy Length and Structure
@@ -508,10 +514,45 @@ response time must be verified before use.
 
 ## Human voice and AI-writing-tell gate
 
-The goal is not to disguise authorship. The goal is specific, accurate,
-author-owned writing that fits the channel.
-
-### Core tests
+Apply this gate to every Agora deliverable, including private writing, public
+copy, interface text, outreach, editorial work, and spoken scripts. The goal is
+not to disguise authorship. Produce specific, accurate, author-owned writing
+that fits its channel and survives factual review.
+
+The consolidated human-voice reference originates in Wikipedia's operational
+AI-cleanup guidance. Editors use those patterns to flag and clean likely
+model-written prose, and related editorial systems can adopt the same cues.
+Agora therefore treats the listed items as mandatory output bans. One cue does
+not prove authorship, and following the bans cannot guarantee non-detection.
+Detector scores remain secondary signals with false-positive, domain-shift, and
+versioning limits.
+
+### Global output bans
+
+Unless immutable source text or an explicit legal, technical, brand, or user
+requirement makes preservation necessary, final Agora copy must contain:
+
+- zero generated em dashes;
+- zero curly or smart quotation marks;
+- zero prompt acknowledgements or task meta-commentary;
+- zero stock phrase templates;
+- zero generic significance tails;
+- zero fabricated citations, quotations, anecdotes, memories, motives,
+  credentials, opinions, comparisons, or facts;
+- zero banned vocabulary or connectives without a narrow documented exception;
+- zero unneeded conclusion or recap paragraphs;
+- zero generated tripartite templates;
+- zero generated `Not only... but also...` constructions;
+- zero deliberate errors, fake informality, synonym soup, or detector-evasion
+  promises.
+
+Use straight quotes. Replace each generated em dash with a comma, colon,
+parentheses, or a new sentence. Preserve banned text only inside verified
+quotations, legal wording, code, identifiers, proper names, required technical
+terms, or other immutable material. `HOUSE` records the operational basis of
+these rules; it does not make them optional.
+
+### Global core tests
 
 - **Competitor-swap test:** if replacing the subject with any competitor leaves
   the paragraph accurate, rewrite it with a real mechanism, fact, situation,
@@ -521,40 +562,174 @@ author-owned writing that fits the channel.
   of the buyer, verify, qualify, or remove it.
 - **Density test:** judge clusters and repeated templates, not one ordinary word
   in isolation.
-
-High-risk clusters include vague verbs such as `unlock`, `leverage`, `elevate`,
-and `transform`; inflated adjectives such as `seamless`, `robust`,
-`groundbreaking`, and `world-class`; and generic nouns such as `landscape`,
-`ecosystem`, `journey`, and `game-changer`.
-
-Review or remove:
-
-- stock openers and prompt acknowledgements;
-- formal connective chains;
-- significance tails that explain why a sentence matters instead of adding
-  evidence;
-- repeated three-part lists;
-- repeated `Not only... but also...` structures;
-- heading restatements and automatic paragraph summaries;
-- symmetrical sections that give every point equal weight;
-- generic conclusions that do not decide, request, or direct;
-- repeated bold-label bullets and decorative mid-prose emphasis;
-- fabricated citations, anecdotes, motives, opinions, or credentials;
-- random errors or slang added to look human.
-
-Necessary technical terms, an earned rhetorical triplet, a natural fragment,
-or an author-consistent punctuation choice may remain in ordinary writing. For
-gated CiteSurge public pages, the repository scanner is stricter:
+- **Fidelity test:** compare the revision against the fact ledger. Restore every
+  material condition, uncertainty, attribution, name, number, date, quotation,
+  citation, and technical term.
+
+### Banned vocabulary and connectives
+
+Strip these terms by default. Retain one only when it is exact, load-bearing,
+technically required, a verified proper name, immutable verbatim text, or an
+explicit user or house requirement. Document why no concrete alternative is
+more accurate.
+
+- **Verbs:** `delve`, `underscore`, `showcase`, `foster`, `navigate` as a
+  metaphor, `harness`, `leverage`, `unlock`, `unleash`, `empower`, `streamline`,
+  `bolster`, `elevate`, `facilitate`, `enhance`, vague `optimize`, metaphorical
+  `drive`, metaphorical `craft`, `forge`, and `spearhead`.
+- **Adjectives:** `pivotal`, `crucial`, `vital`, `essential`, `robust`,
+  `seamless`, `holistic`, `comprehensive`, `multifaceted`, `nuanced`,
+  `intricate`, `meticulous`, `profound`, `transformative`, `groundbreaking`,
+  `revolutionary`, `cutting-edge`, `state-of-the-art`, `world-class`,
+  `best-in-class`, `unparalleled`, `unprecedented`, `remarkable`, `noteworthy`,
+  `notable`, `significant`, `invaluable`, `indispensable`, `paramount`,
+  `breathtaking`, `stunning`, `vibrant`, `rich` in phrases such as `rich
+  history`, `bespoke`, and `curated`.
+- **Nouns, especially as metaphors:** `tapestry`, `landscape`, `realm`,
+  `ecosystem`, `journey`, `testament`, `frontier`, `forefront`, `cornerstone`,
+  `backbone`, `lifeblood`, `powerhouse`, `trailblazer`, and `game-changer`.
+- **Connectives:** `moreover`, `furthermore`, `additionally`, `in addition`,
+  `notably`, `importantly`, `indeed`, `in essence`, `in summary`, `in
+  conclusion`, `ultimately`, `that said`, `on the other hand`, and `on one
+  hand`.
+
+Delete a connective when the relationship remains clear. When one is required
+by a formal genre, use the shortest accurate transition.
+
+### Banned templates and significance tails
+
+Delete every generated occurrence of:
+
+- `It's important to note that...`;
+- `It's worth noting` or `It's worth mentioning`;
+- `In today's fast-paced world...`;
+- `In the ever-evolving landscape of...`;
+- `In the realm of...`;
+- `A testament to...`;
+- `Stands as a...`;
+- `Serves as a...`;
+- `Plays a crucial`, `pivotal`, or `vital role in...`;
+- `Not only X but also Y`;
+- `Whether you're X or Y...`;
+- `From X to Y, [subject] has...`;
+- `At its core...`;
+- `When it comes to...`;
+- `Navigating the complexities of...`;
+- `Unlocking the potential of...`;
+- `Harnessing the power of...`;
+- `Paving the way for...`;
+- `Setting the stage for...`;
+- `Bringing X to the forefront`.
+
+Delete generated tails such as:
+
+- `..., emphasizing the significance of...`;
+- `..., reflecting the continued relevance of...`;
+- `..., underscoring the importance of...`;
+- `..., highlighting its role in...`;
+- `..., demonstrating its impact on...`;
+- `..., marking a turning point in...`;
+- `..., cementing its place as...`;
+- `..., solidifying its reputation for...`;
+- `..., showcasing its commitment to...`.
+
+End with information or a specific, supportable inference.
+
+### Banned structural and typography patterns
+
+Remove:
+
+- prompt acknowledgements, including `Certainly`, `Of course`, `Absolutely`,
+  `Great question`, or any acknowledgement of the prompt;
+- every paragraph ending with a summary or significance sentence;
+- generated tripartite parallelism used as a rhetorical template;
+- repeated or generated `Not only... but also...` structures;
+- headings followed by a sentence that restates the heading;
+- repeated `**Bold label:** sentence` bullets;
+- balanced both-sides framing that refuses to make a supported claim;
+- conclusions or summary sections in formats that do not need them;
+- generic positive framing that replaces a fact;
+- `Some argue... others contend...` without named sources;
+- definitions repeated across sections;
+- smooth transitions that conceal unrelated facts;
+- topic sentences that restate headings;
+- title case for generic concepts;
+- mid-paragraph bold outside technical, accessibility, or explicit house needs.
+
+Use zero generated em dashes and zero curly or smart quotes. Use straight
+quotes. Use an en dash only when formal publication style requires it;
+otherwise use a hyphen.
+
+Reject prompt leakage immediately, including `Here is your article`, `As an AI
+language model`, `Up to my last training update`, `I hope this helps`, `Let me
+know if you would like`, `Certainly! Here's a`, `Sure, I can help with that`,
+any task meta-commentary, or any reference to the commissioning user inside the
+deliverable. Return the deliverable itself.
+
+### Author voice, genre, and meaning
+
+When authentic author samples are available, profile recurring sentence length,
+paragraph rhythm, formality, contractions, function words, punctuation,
+qualification, directness, humor, openings, turns, and endings. Use stable habits
+without copying phrases, subject matter, or one-off quirks. When samples are
+missing, preserve credible individual choices and request author review rather
+than inventing an idiolect.
+
+Fit the genre. A professional email should surface context and request quickly.
+An executive memo should lead with the decision or finding. Academic and legal
+work must preserve required terminology and citations. Spoken work must sound
+natural when read aloud. Written GEO/AEO work must remain specific without
+forcing identical headings, paragraph lengths, or miniature conclusions.
+
+Never humanize by changing facts, names, figures, dates, quotations, citations,
+causality, uncertainty, legal meaning, or product terminology. Never upload
+confidential, privileged, unpublished, regulated, or personally sensitive text
+to an external detector or rewriting service without authorization and a review
+of its retention and training terms.
+
+### Detector limits and research basis
+
+Never promise that copy is "undetectable", claim that a detector score proves
+authorship, or optimize toward one changing classifier at the expense of truth,
+voice, or clarity. If detector testing is authorized, calibrate against several
+known-human samples from the same author and genre, use multiple methods when
+feasible, record tool and version, and stop detector-driven editing after two
+rounds unless another pass independently improves the prose.
+
+The earlier source gave `3-5x` em-dash usage and about `90%` experienced-reader
+detection as numerical claims without a supporting source. Do not repeat those
+numbers as scientific facts. This does not weaken any output ban. The bans are
+mandatory because the source patterns are used operationally in Wikipedia-style
+AI cleanup and related editorial screening, not because a percentage guarantees
+detection or non-detection.
+
+The human-voice reference grounds these limits in:
+
+- [RAID benchmark](https://arxiv.org/abs/2405.07940);
+- [Krishna et al. on paraphrasing attacks](https://arxiv.org/abs/2303.13408);
+- [DAMAGE shared task overview](https://aclanthology.org/2025.genaidetect-1.9/);
+- [Practical examination of AI-generated text detectors](https://aclanthology.org/2025.findings-naacl.271/);
+- [Detector bias against non-native English writers](https://arxiv.org/abs/2304.02819);
+- [GPTZero detector methodology](https://arxiv.org/abs/2602.13042);
+- [Can AI-Generated Text be Reliably Detected?](https://arxiv.org/abs/2303.11156);
+- [Almost AI, Almost Human](https://arxiv.org/abs/2502.15666);
+- [Human heuristics for AI-generated language are flawed](https://arxiv.org/abs/2206.07271);
+- [Function Word Adjacency Networks](https://arxiv.org/abs/1406.4469).
+
+### CiteSurge-only scanner controls
+
+For gated CiteSurge public pages, the repository scanner enforces the global
+prompt-leakage and quote bans and adds CiteSurge-only machine thresholds:
 
 - prompt leakage or acknowledgement openers fail immediately;
-- em dashes and curly quote characters or entities in prose fail;
+- curly quote characters or entities in prose fail under the global rule;
 - three or more watchlist indicators in one prose block fail;
 - the same template or significance-tail fingerprint repeated twice fails;
 - a single watchlist occurrence is informational, not an automatic failure.
 
-Use `content/ai-writing-tells.md` for rationale and
-`content/ai-writing-tells.ts` for the current machine-readable rules. Never
-promise that copy is "undetectable" or optimize it toward one detector score.
+Use `content/ai-writing-tells.md` for CiteSurge rationale and
+`content/ai-writing-tells.ts` for its current scanner rules. Do not apply those
+CiteSurge-specific thresholds, files, or release gates to another brand.
 
 ## Written GEO/AEO and citability gate
 
@@ -782,7 +957,11 @@ context and reduces uncertainty.
   as a universal performance law.
 - [ ] CTA names a real next action and adds no new claim.
 - [ ] Competitor-swap, read-aloud, defense, and density tests pass.
-- [ ] No fabricated detail, fake urgency, prompt leakage, or detector promise.
+- [ ] Zero banned vocabulary, connectives, templates, significance tails,
+  generated em dashes, and curly or smart quotes without a narrow documented
+  exception.
+- [ ] No fabricated detail, fake urgency, prompt leakage, artificial human
+  texture, or detector promise.
 - [ ] Written utility, product, comparison, and question-led copy answers early;
   all written copy names entities and keeps key evidence blocks self-contained.
 - [ ] Material written claims have exact, current, preferably primary sources.