@zalom/plastic 1.0.0-beta.9 → 1.0.0

package/skills/creating-skills/scripts/scaffold.rb

@@ -0,0 +1,313 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# scaffold.rb - born-slim starting files for a new skill, agent, or hook.
+#
+# Plastic skills, agents, and hooks start small and grow by progressive
+# disclosure. This scaffolder emits the minimum valid skeleton so the body
+# stays slim and detail moves into references/ as the work earns it.
+#
+# Usage:
+#   ruby scaffold.rb skill <name> [--out <dir>] [dest]
+#   ruby scaffold.rb agent <name> [--out <dir>] [dest]
+#   ruby scaffold.rb hook  [<Event>] <name> [--out <dir>] [dest]
+#   ruby scaffold.rb --help
+#
+# All input is positional plus flags. There are no interactive prompts, so an
+# agent never hangs waiting on input. The destination defaults to the current
+# directory; pass --out or a trailing positional to choose another directory.
+#
+# Exit codes:
+#   0  success, or --help
+#   1  usage error (unknown subcommand, missing argument)
+#   2  validation error (bad name or event)
+#   3  refused to overwrite an existing target, or a filesystem error
+#
+# This script and every file it emits contain no em-dashes; the emitted files
+# are user-facing.
+
+require "json"
+require "fileutils"
+
+EXIT_OK = 0
+EXIT_USAGE = 1
+EXIT_VALIDATION = 2
+EXIT_CONFLICT = 3
+
+NAME_PATTERN = /\A[a-z0-9]+(-[a-z0-9]+)*\z/.freeze
+EVENT_PATTERN = /\A[A-Z][A-Za-z]+\z/.freeze
+DEFAULT_EVENT = "PostToolUse"
+
+USAGE = <<~TEXT
+  scaffold.rb - born-slim starting files for a new skill, agent, or hook.
+
+  Usage:
+    ruby scaffold.rb skill <name> [--out <dir>] [dest]
+    ruby scaffold.rb agent <name> [--out <dir>] [dest]
+    ruby scaffold.rb hook  [<Event>] <name> [--out <dir>] [dest]
+    ruby scaffold.rb --help
+
+  Subcommands:
+    skill   Emit <dest>/<name>/SKILL.md, references/.gitkeep, evals/evals.json.
+    agent   Emit <dest>/<name>.md agent role file.
+    hook    Emit <dest>/<name> no-op hook handler (Ruby) wired for <Event>.
+
+  Names must be lowercase alphanumeric and hyphens, with no leading,
+  trailing, or repeated hyphens, 1 to 64 characters.
+  The hook <Event> is optional and defaults to #{DEFAULT_EVENT}.
+  The destination defaults to the current directory.
+
+  Exit codes:
+    0  success, or --help
+    1  usage error (unknown subcommand, missing argument)
+    2  validation error (bad name or event)
+    3  refused to overwrite an existing target, or a filesystem error
+TEXT
+
+# A small error that carries the exit code to use when it reaches the top.
+class ScaffoldError < StandardError
+  attr_reader :code
+
+  def initialize(message, code)
+    super(message)
+    @code = code
+  end
+end
+
+def fail_with(message, code)
+  raise ScaffoldError.new(message, code)
+end
+
+def validate_name!(name)
+  if name.nil? || name.empty?
+    fail_with("missing <name>. See --help for usage.", EXIT_USAGE)
+  end
+  unless name.length <= 64 && name =~ NAME_PATTERN
+    fail_with(
+      "invalid name #{name.inspect}: use lowercase letters, digits, and " \
+      "hyphens, no leading, trailing, or repeated hyphens, 1 to 64 chars.",
+      EXIT_VALIDATION
+    )
+  end
+  name
+end
+
+def validate_event!(event)
+  unless event =~ EVENT_PATTERN
+    fail_with(
+      "invalid event #{event.inspect}: use a CamelCase hook event name, " \
+      "for example PostToolUse or SessionStart.",
+      EXIT_VALIDATION
+    )
+  end
+  event
+end
+
+# Separate --out and any trailing positional dest from the bare positionals.
+# Returns [positionals, out_dir]. out_dir is nil when not given.
+def parse_args(args)
+  positionals = []
+  out_dir = nil
+  i = 0
+  while i < args.length
+    arg = args[i]
+    case arg
+    when "--out"
+      out_dir = args[i + 1]
+      if out_dir.nil?
+        fail_with("--out needs a directory argument.", EXIT_USAGE)
+      end
+      i += 2
+    else
+      if arg.start_with?("--")
+        fail_with("unknown option #{arg.inspect}. See --help for usage.", EXIT_USAGE)
+      end
+      positionals << arg
+      i += 1
+    end
+  end
+  [positionals, out_dir]
+end
+
+def refuse_if_exists!(path)
+  if File.exist?(path)
+    fail_with("refusing to overwrite existing #{path}. Remove it or pick another destination.", EXIT_CONFLICT)
+  end
+end
+
+def write_file(path, content)
+  refuse_if_exists!(path)
+  FileUtils.mkdir_p(File.dirname(path))
+  File.write(path, content)
+  puts "created #{path}"
+end
+
+# -- generators ----------------------------------------------------------
+
+def skill_body(name)
+  <<~MD
+    ---
+    name: #{name}
+    description: >
+      Use when the user needs #{name}. State here WHEN this skill should
+      trigger, in the third person, so the agent can match it. Replace this
+      placeholder with one or two concrete trigger conditions before shipping.
+    ---
+
+    # #{name}
+
+    One line on what this skill does and why it exists.
+
+    ## Gotchas
+
+    - List the non-obvious failure modes here, one per line.
+
+    ## Tasks
+
+    Keep the body slim. Route detail to references as the work earns it.
+
+    | Task | Reference |
+    | ---- | --------- |
+    | Replace this row with a real task | references/REPLACE-ME.md |
+  MD
+end
+
+def eval_stub(name)
+  data = {
+    "skill_name" => name,
+    "evals" => [
+      {
+        "id" => 1,
+        "prompt" => "",
+        "expected_output" => "",
+        "files" => [],
+        "assertions" => []
+      }
+    ]
+  }
+  JSON.pretty_generate(data) + "\n"
+end
+
+def generate_skill(name, out_dir)
+  base = File.join(out_dir, name)
+  refuse_if_exists!(base)
+  write_file(File.join(base, "SKILL.md"), skill_body(name))
+  write_file(File.join(base, "references", ".gitkeep"), "")
+  write_file(File.join(base, "evals", "evals.json"), eval_stub(name))
+  puts "skill scaffold ready at #{base}"
+end
+
+def agent_body(name)
+  <<~MD
+    ---
+    name: #{name}
+    description: >
+      Use this agent when the user needs #{name}. State here WHEN to delegate
+      to this agent, in the third person, so the orchestrator can route to it.
+      Replace this placeholder with concrete delegation conditions.
+    tools: Read, Edit, Bash
+    ---
+
+    You are the #{name} agent.
+
+    ## Responsibilities
+
+    - One line per durable responsibility this agent owns.
+
+    ## How you work
+
+    Keep this body slim. State the contract, the inputs, and the outputs.
+    Move long procedures into a references file as the work earns it.
+
+    ## Completion
+
+    End your turn with a short report of what you did and how you verified it.
+  MD
+end
+
+def generate_agent(name, out_dir)
+  write_file(File.join(out_dir, "#{name}.md"), agent_body(name))
+  puts "agent scaffold ready at #{File.join(out_dir, "#{name}.md")}"
+end
+
+def hook_body(name, event)
+  <<~RUBY
+    #!/usr/bin/env ruby
+    # frozen_string_literal: true
+
+    # #{name} - #{event} hook handler (no-op by default).
+    #
+    # This skeleton does nothing until you opt in. Set the environment flag
+    # below to a non-empty value to activate the real behavior. Until then it
+    # exits 0 so it never blocks the session.
+    #
+    # Wire it in settings.json under hooks.#{event}:
+    #   { "type": "command", "command": "ruby /absolute/path/to/#{name}" }
+    #
+    # Exit codes:
+    #   0  no-op, or success
+    #   2  block the action (only when you add real logic that should block)
+
+    OPT_IN = "#{name.tr("-", "_").upcase}_ENABLED"
+
+    if ENV[OPT_IN].nil? || ENV[OPT_IN].empty?
+      exit 0
+    end
+
+    # Opt-in is set. Add the real handler here. The hook receives event JSON on
+    # stdin; parse it only when you need it. Exit 0 to allow, exit 2 to block.
+    exit 0
+  RUBY
+end
+
+def generate_hook(name, event, out_dir)
+  path = File.join(out_dir, name)
+  write_file(path, hook_body(name, event))
+  FileUtils.chmod("+x", path)
+  puts "hook scaffold ready at #{path} (executable, #{event}, no-op until opt-in)"
+end
+
+# -- dispatch ------------------------------------------------------------
+
+def run(argv)
+  if argv.empty? || argv.include?("--help") || argv.include?("-h")
+    puts USAGE
+    return EXIT_OK
+  end
+
+  subcommand = argv.shift
+  positionals, out_flag = parse_args(argv)
+
+  case subcommand
+  when "skill", "agent"
+    name = validate_name!(positionals[0])
+    out_dir = out_flag || positionals[1] || "."
+    subcommand == "skill" ? generate_skill(name, out_dir) : generate_agent(name, out_dir)
+  when "hook"
+    # Accept "hook <name>" or "hook <Event> <name>", with an optional trailing dest.
+    if positionals.length >= 2 && positionals[0] =~ EVENT_PATTERN
+      event = validate_event!(positionals[0])
+      name = validate_name!(positionals[1])
+      out_dir = out_flag || positionals[2] || "."
+    else
+      event = DEFAULT_EVENT
+      name = validate_name!(positionals[0])
+      out_dir = out_flag || positionals[1] || "."
+    end
+    generate_hook(name, event, out_dir)
+  else
+    fail_with("unknown subcommand #{subcommand.inspect}. See --help for usage.", EXIT_USAGE)
+  end
+
+  EXIT_OK
+end
+
+begin
+  exit run(ARGV.dup)
+rescue ScaffoldError => e
+  warn "scaffold.rb: #{e.message}"
+  exit e.code
+rescue Errno::EACCES, Errno::ENOENT, Errno::EEXIST => e
+  warn "scaffold.rb: filesystem error: #{e.message}"
+  exit EXIT_CONFLICT
+end

package/skills/dashboard/SKILL.md

@@ -61,9 +61,17 @@ Fill mechanically — no rewriting, no re-sorting:
 
 ### Step 3 — Present it (mandatory, every invocation)
 
-**Paste the filled Markdown into your reply.** This is non-optional: the board only reaches
-the user when it is in the chat reply, not in tool-call stdout. Never describe the board
-instead of showing it.
+**Paste the filled Markdown into your reply.** This is non-optional: if the reply does not
+contain the filled Markdown, the user sees nothing — tool-call stdout and hook
+`additionalContext` are both invisible to them. Never describe the board instead of showing
+it, and never assume a hook already showed it for you.
+
+`hook-continue` also emits a one-line `systemMessage` summary (counts, and the next big thing
+when there is one) as a hook-owned fallback, independent of the agent's reply. Treat that line
+as a floor only, not a substitute for this step: it carries no matrix, no recently-worked
+section, and no entry-flow prompt. Presenting the full board here remains mandatory regardless
+of whether the summary line fired. This stays a soft, agent-followed mechanism — there is no
+stronger enforcement for a full multi-section Markdown document in this harness today.
 
 ### Step 4 — Entry flow (the board is the menu)
 
@@ -102,14 +110,8 @@ a raw terminal. The Markdown board (`--data` + template) is the surface for the
 
 ## How classification works (deterministic)
 
-- **Effort** — small for `research`/`exploration`/`bugfix`, for already-scoped intents
-  (plan/checklist exists), or deep refinement branches; big otherwise.
-- **Value → high** when any of: explicit `value: high`; a human-authored **root** intent; an
-  intent with a non-empty `chain`; or an intent that is a `source` of ≥1 other intent. Else low.
-- **Flags** — `unblocked` only when a **future** intent has **all** its `sources` done;
-  `stale` only on future intents past the staleness threshold. Both kept low-noise by design.
-- **Override** — a `value: high|low` frontmatter field always wins (pre-stamped data, never
-  model judgment at render time).
+The script computes Effort/Value/Flags/Override/Caps; the agent never re-derives them.
+To explain or debug a quadrant assignment, read `references/classification.md`.
 
 ## Eval
 

package/skills/dashboard/references/classification.md

@@ -0,0 +1,22 @@
+# How Classification Works (Deterministic)
+
+The script (`dashboard.rb`) computes Effort/Value/Flags/Override/Caps deterministically;
+the agent never re-derives them. Read this to explain or debug a quadrant assignment.
+
+- **Effort** — small for `research`/`exploration`/`bugfix`, for already-scoped intents
+  (plan/checklist exists), or a **branch id** (folgezettel depth ≥ 2, e.g. `4a`, `12b3`); big
+  otherwise. A root id (a bare number) is always depth 1, so it is never demoted by this rule.
+- **Value → high** when any of: explicit `value: high`; a human-authored **root** intent; or
+  an intent that is a `source` of ≥1 other intent (it has spawned follow-on work). A purely
+  relational `chain` entry alone is **not** a value signal (intent 68) — else low.
+- **Flags** — `unblocked` only when a **future** intent has **all** its `sources` done AND at
+  least one source's completion date is strictly later than the intent's own `created` date (a
+  genuine wait, not a birth-time default); `in-progress` only when the savepoint ledger shows
+  real post-birth activity, not just the creation stamp; `stale` only on future intents past
+  the staleness threshold. All three kept low-noise by design.
+- **Override** — a `value: high|low` frontmatter field always wins (pre-stamped data, never
+  model judgment at render time).
+- **Caps** — quadrant lists and the project board's `active`/`future` lists are capped at 8
+  entries plus a trailing "+N more" line; each entry's text is truncated to 120 characters
+  with a trailing ellipsis. Applies to the Markdown board only (the ASCII renderer has its own
+  separate `CELL_CAP`).

package/skills/doctor/SKILL.md

@@ -3,7 +3,7 @@ name: plastic-doctor
 description: Use when diagnosing Plastic installation health, after updates, or when something seems broken. Runs checks and reports findings with fix options.
 ---
 
-# Doctor — Plastic Health Check
+# Doctor: Plastic Health Check
 
 ## Scopes
 
@@ -67,9 +67,9 @@ Parse the JSON output from stdout. The script is read-only and never modifies
 files. Errors go to stderr.
 
 Exit codes indicate check results, not script failure:
-- `0` — all checks passed
-- `1` — warnings found
-- `2` — failures found
+- `0`: all checks passed
+- `1`: warnings found
+- `2`: failures found
 
 All three exit codes mean the script ran successfully. Do not treat non-zero
 as an error.
@@ -118,10 +118,13 @@ Use the `fix_hint` value to determine the correct action:
 | "Remove stale references from INDEX.md" | Edit INDEX.md to remove ghost references |
 | "Inject the missing required frontmatter field(s)" | Edit the intent's `{ID}--{slug}.md` frontmatter to add the missing key (e.g. `chain: []`) without touching other keys |
 | "Run: provision-project-store {slug}" | Run `provision-project-store <slug>` (or invoke the `plastic-add-project-store` skill) to create the missing store |
-| "Re-run installer" | Run `npx @zalom/plastic@latest --agent` |
+| "Re-run installer" | Run `npx -y @zalom/plastic@<channel> install --agent <agent>` (channel: -alpha->@alpha, -beta->@beta, else @latest) |
+| "Dispatch plastic-intent-curator ... revisions.md ..." | Invoke the `plastic-intent-curator` (or the agent) to relocate the flagged section or ref into the intent's `revisions.md` via move-and-record (one dated, `[rule: <tag>]`-tagged entry per item), per PLASTIC.md > Structural maintenance and revisions.md. For a missing required section, restore or reproject it instead. |
 
 For fixes the agent cannot handle automatically, explain what the user needs
-to do manually.
+to do manually. The `revisions.md` remedy is curator-applied (a move-and-record
+relocation, not a mechanical edit) and stays human-gated by the Step 4
+Fix / Select / Skip prompt.
 
 ### Step 6: Verify
 
@@ -141,7 +144,7 @@ Show the updated results.
 When invoked from `plastic-update` (not directly by the user):
 
 1. Run the diagnostic script as in Step 1.
-2. If all checks pass: show a single line — **"Health check: all clear."**
+2. If all checks pass, show a single line: **"Health check: all clear."**
 3. If issues are found: show the full report (Steps 3-6).
 
 This keeps the update flow clean when nothing is wrong.

package/skills/executing-plan/SKILL.md

@@ -70,12 +70,12 @@ After all tasks complete, dispatch a final reviewer for the entire implementatio
 ### Step 4: Update Intent and Complete
 Capture observations in `## Insights`. When ALL checklist items are checked:
 
-1. Write `outcome.md` with detailed results in the intent directory, using the `${CLAUDE_PLUGIN_ROOT}/templates/outcome.md` form
+1. Write `outcome.md` with detailed results in the intent directory, using the `${CLAUDE_PLUGIN_ROOT}/templates/outcome.md` form. Set the frontmatter `disposition: delivered` (the delivered terminal). `outcome.md` is mandatory at every terminal and self-declares its disposition (canonical done-marker in PLASTIC.md).
 2. Write `## Outcome` summary in the intent file (1-2 sentences)
 3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 4. Update cluster entries to show `_(completed)_`
 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> — <name>"`
-6. On completion, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent), running in the background so it never blocks the turn: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`. Completion is the lifecycle event that keeps the search index fresh.
+6. QMD reindex LAST (canonical End tail). As the final End-tail step, after the terminal move and any disarm, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent), running in the background so it never blocks the turn: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`. Completion is the lifecycle event that keeps the search index fresh, and the reindex runs last so the index never references a bridge or lock that is about to disappear (see PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`).
 
 **This is NOT optional.** An intent with all checklist items done but no Outcome is a broken state. Complete the intent immediately — do not leave it for later.
 
@@ -96,12 +96,12 @@ For each task:
 ### Step 3: Update Intent and Complete
 Capture observations in `## Insights`. When ALL checklist items are checked:
 
-1. Write `outcome.md` with detailed results in the intent directory, using the `${CLAUDE_PLUGIN_ROOT}/templates/outcome.md` form
+1. Write `outcome.md` with detailed results in the intent directory, using the `${CLAUDE_PLUGIN_ROOT}/templates/outcome.md` form. Set the frontmatter `disposition: delivered` (the delivered terminal). `outcome.md` is mandatory at every terminal and self-declares its disposition (canonical done-marker in PLASTIC.md).
 2. Write `## Outcome` summary in the intent file (1-2 sentences)
 3. Move intent from `## Active` to `## Completed` in INDEX.md (with today's date)
 4. Update cluster entries to show `_(completed)_`
 5. Auto-commit: `cd <store-root> && git add . && git commit -m "feat: complete intent <ID> — <name>"`
-6. On completion, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent), running in the background so it never blocks the turn: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`. Completion is the lifecycle event that keeps the search index fresh.
+6. QMD reindex LAST (canonical End tail). As the final End-tail step, after the terminal move and any disarm, ALWAYS refresh the QMD search index for this store (no-op when QMD is absent), running in the background so it never blocks the turn: `ruby ~/.plastic/scripts/qmd-sync reindex --store <store-root> --async`. Completion is the lifecycle event that keeps the search index fresh, and the reindex runs last so the index never references a bridge or lock that is about to disappear (see PLASTIC.md `## Delivery Isolation and the Single-Owner Lock`).
 
 **This is NOT optional.** Complete the intent immediately when work is done.
 

package/skills/humanizer/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: plastic-humanizer
+description: Use to clean authored prose so it reads human and clutter-free. Removes AI tells and slop from a document, spec, outcome, README, report, or release note. Use when the user says "humanize", "de-slop", "remove the AI tells", or "clean up the wording". For documents, not for every chat reply, and not for code.
+---
+
+# Humanizer
+
+Make writing read like a person wrote it: plain, direct, low-clutter. Run this as a pass over authored prose (specs, outcomes, README, reports). Do not run it on code or on every chat turn.
+
+## Lead (house style)
+Reframe your answers and any questions you have for me like you are speaking to a well-educated non-English native person. Reduce slang, and rarely used words and terms in the general communication. And cut all the fancy words from explanations. Technical terms and concepts are fine and need no gloss.
+
+## Voice
+Answer like a busy bartender or a senior support engineer who has seen almost every ticket. Help fast, give the fix first, earn the tip.
+
+## Job 1 - remove these surface tells
+1. Em-dashes and en-dashes - use a comma or a full stop.
+2. "Not X but Y" (and "it's not just X, it's Y").
+3. Rule of three - three items only for rhythm.
+4. Hype / AI words - delve, robust, comprehensive, seamless, leverage, crucial, unlock, landscape.
+5. Filler openers / signposting - "It's worth noting", "It's important to", "Let's dive in".
+6. Hedging pile-up - might, could, perhaps, generally, when not needed.
+7. Sycophancy - "Great question", "You're absolutely right".
+8. Over-bolding - bold only what carries weight.
+
+## Job 2 - fix the structure
+- Lead with the one main point.
+- Cut sentences that only restate.
+- Pick concrete words over abstract ones.
+- Match the user's voice when samples of their writing exist.
+
+## Process
+Write, check once against the rules above, then send. On documents, run this pass last.
+
+## Length
+Keep it short. If a sentence does not help the reader, cut it.
+
+## More
+For before/after examples, read `references/examples.md`. To make the house style always-on in chat, see `references/always-on-snippet.md`. The full 33-pattern catalog and the research behind this skill live in intent 92's `resources/`. They are background and are not loaded here.

package/skills/humanizer/evals/evals.json

@@ -0,0 +1,70 @@
+{
+  "skill_name": "plastic-humanizer",
+  "notes": "Intent 92. Cleans authored prose: removes 8 surface tells and applies structural levers (one point, cut restatement, concrete words, match voice). Triggers on document-cleanup asks, not on code. Runner is intent 76; assertions are human for now.",
+  "evals": [
+    {
+      "id": 1,
+      "scope": "trigger",
+      "set": "validation",
+      "prompt": "Humanize this README - it reads like AI wrote it.",
+      "expected_output": "Selects plastic-humanizer and runs the cleanup pass over the document.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "plastic-humanizer is selected for a document-cleanup request",
+          "observed": "description triggers on 'humanize' / 'reads like AI' for a document",
+          "result": "pass"
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "scope": "trigger",
+      "set": "validation",
+      "prompt": "Clean up the wording in this spec.",
+      "expected_output": "Selects plastic-humanizer and cleans the spec prose.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "plastic-humanizer is selected for 'clean up the wording'",
+          "observed": "description triggers on 'clean up the wording'",
+          "result": "pass"
+        }
+      ]
+    },
+    {
+      "id": 3,
+      "scope": "non-trigger",
+      "set": "validation",
+      "prompt": "Fix the failing test in foo.rb.",
+      "expected_output": "Does NOT select plastic-humanizer; this is a code task, not prose cleanup.",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "plastic-humanizer is not selected for a code task",
+          "observed": "description scopes the skill to documents, not code",
+          "result": "pass"
+        }
+      ]
+    },
+    {
+      "id": 4,
+      "scope": "output",
+      "set": "validation",
+      "prompt": "Given a slop sample: 'It's worth noting that this is not just a fix, but a comprehensive, robust, and seamless improvement that will unlock real value.' Humanize it.",
+      "expected_output": "Cleaned text has no em-dashes and none of the 8 tells, leads with one point, and drops restatement. For example: 'This fix makes X faster.'",
+      "files": [],
+      "assertions": [
+        {
+          "type": "human",
+          "check": "output drops the 8 tells, leads with one point, cuts restatement",
+          "observed": "no em-dashes; no 'not X but Y'; no rule-of-three; no hype words; no filler opener; one load-bearing point",
+          "result": "pass"
+        }
+      ]
+    }
+  ]
+}

package/skills/humanizer/references/always-on-snippet.md

@@ -0,0 +1,9 @@
+# Always-on chat style (copy-paste)
+
+Paste this into your global `CLAUDE.md` (applies to all projects) or a project `AGENTS.md` (one project). It keeps the chat style on at near-zero cost. The full cleanup for documents is the `plastic-humanizer` skill.
+
+```
+Reframe your answers and any questions like you are speaking to a well-educated person who is not a native English speaker. Reduce slang and rarely used words. Cut fancy words from explanations. Technical terms and concepts are fine.
+
+Answer like a busy bartender or a senior support engineer who has seen almost every ticket: help fast, give the fix first, earn the tip.
+```

package/skills/humanizer/references/examples.md

@@ -0,0 +1,48 @@
+# Examples - before and after
+
+Each pair shows a tell or a slop pattern, then the fix.
+
+## 1. Em-dash
+Before: The release is ready - we just need sign-off.
+After: The release is ready. We just need sign-off.
+Why: Use a full stop or comma, not an em-dash.
+
+## 2. "Not X but Y"
+Before: This is not just a config change, it's a rethink of the flow.
+After: This change reworks the flow.
+Why: State the point directly.
+
+## 3. Rule of three
+Before: The tool is fast, robust, and powerful.
+After: The tool is fast.
+Why: Drop the list-for-rhythm; keep the claim you can back.
+
+## 4. Hype / AI word
+Before: We leverage a comprehensive caching layer to unlock performance.
+After: We cache results to make it faster.
+Why: Plain verbs and nouns.
+
+## 5. Filler opener / signposting
+Before: It's worth noting that the cache expires after five minutes.
+After: The cache expires after five minutes.
+Why: Say the thing; skip the runway.
+
+## 6. Hedging pile-up
+Before: This might possibly help reduce cost in some cases, generally.
+After: This reduces cost.
+Why: One clear claim. Add a caveat only if it is real.
+
+## 7. Sycophancy
+Before: Great question! That's a really insightful point. Here's the answer.
+After: Here's the answer.
+Why: Drop the praise; answer.
+
+## 8. Structural fix (the mush)
+Before: There are several important considerations to keep in mind when thinking about how best to approach the broad and multifaceted topic of caching, each of which carries its own trade-offs.
+After: Cache reads, not writes. Reads repeat; writes do not.
+Why: One load-bearing point. Cut the restatement and the abstract throat-clearing.
+
+## 9. Over-bolding
+Before: **Note:** the cache **expires** after **five minutes**, so **always** check it.
+After: The cache expires after five minutes, so check it first.
+Why: Bold nothing here; the sentence carries itself.