Repository guidance

This repository contains one shared writing skill packaged for Codex and Claude Code.

Source of truth

• skills/nuko-nova-unslop/SKILL.md defines runtime behavior.
• skills/unslop/SKILL.md is the short explicit alias and must only route to the canonical skill.
• skills/tighten/SKILL.md is the focused compression command. It must route through the complete canonical skill before the second-stage rules in skills/nuko-nova-unslop/references/tighten.md.
• skills/super-tighten/SKILL.md is a standalone combined Unslop, compression, and ASD-STE100 workflow. Its runtime instructions must not route to another writing skill or reference. Preserve the distinction between applying STE rules and verifying full vocabulary conformance against the official standard.
• output-styles/nuko-nova-unslop.md makes the standard apply to every Claude Code response while the plugin is enabled.
• skills/nuko-nova-unslop/agents/openai.yaml keeps implicit Codex invocation enabled.
• The files under skills/nuko-nova-unslop/references/ hold detailed runtime rules. Maintainer material lives in docs/: follow docs/evolution.md for upstream review, and record sources in docs/source-map.md. That folder is not shipped in the skill or served by the MCP host.
• evals/ holds claude plugin eval cases that measure behavior with and without the plugin. Change skill prose against eval results, not against exact-wording checks.
• skills/nuko-nova-unslop/scripts/markdown_source.py owns shared Markdown recognition and offset-preserving masking. The linter and preservation guard apply their own editorial policies to its results.
• .codex-plugin/plugin.json and .claude-plugin/plugin.json must keep name, version, description, author, repository, and license aligned.
• upstreams.lock.json records reviewed upstream state; a new SHA is not accepted until its relevant diff has been reviewed and the package gates pass.
• A recurring owner-created automation may publish only when its prompt explicitly grants the exact Nuko Nova Unslop push, release, marketplace, and client-update actions and every target is reverified during that run.

Editing contract

• Preserve the skill's fact and voice safeguards when changing pattern rules.
• Keep the zero-em-dash house preference subordinate to quotations and fixed strings, but not to an author sample unless the user explicitly requests em dashes for the current piece. Never satisfy it with spaced double hyphens or staccato fragments.
• Keep personality inside an owned voice; never let an edit donate opinions or experiences to a represented author.
• Treat human writing as purposeful, audience-aware, emotionally proportionate language, not as automatic slang, casualness, quirks, fragments, or deliberate mistakes.
• Apply the no-cringe standard through ownership, proportion, audience fit, and substance. Keep subjective cringe signals contextual and advisory.
• Treat delegated prose as source material and apply the skill in the parent before delivery because client output styles may not propagate to subagents.
• Do not ship lifecycle hooks or any final-output interceptor. The writing skill may advise and lint, but it must never block, rewrite, or delay an answer at a client lifecycle boundary.
• Add a regression fixture for every non-obvious behavioral fix.
• Never ingest a third-party phrase corpus wholesale. Curate small, explainable rules with false-positive boundaries.
• Keep the skill body concise and route detailed material into one-level references.
• Treat unslopped human-facing prose as the default acceptance criterion, not an optional user-requested pass.
• On authorized automated evolution runs, publish accepted behavioral changes through the full repository, release, marketplace, and client-update sequence. Report a no-op when no justified change exists.

Required checks

Run these before committing:

pnpm check
python3 /Users/judiazm/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/nuko-nova-unslop
python3 /Users/judiazm/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/unslop
python3 /Users/judiazm/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/tighten
python3 /Users/judiazm/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/super-tighten

pnpm check runs the portable bundle, Python, and MCP checks and is also the CI entry point. tests/validate_bundle.py is the required repository-owned plugin validator; it checks both client manifests, shipped resources, invocation metadata, and hook-free packaging. Install workspace dependencies with pnpm install --frozen-lockfile first. The skill creator checks above depend on the local Codex installation and remain separate.

After changing skill or output-style prose, run the behavior evals and compare the score with the previous run and with the no-plugin arm:

claude plugin eval . --runs 3 --judge-model sonnet --no-publish --threshold 0 --output-dir /tmp/unslop-eval

Evals call models and cost money, so they are not part of pnpm check or CI.

Run claude plugin validate . when Claude Code is available. Treat package validation, marketplace registration, installation, and client reload as separate states.