harness-everything 0.2.2 → 0.4.0

package/skill-creator/references/authoring-workflow.md

@@ -0,0 +1,14 @@
+# Authoring Workflow Detail
+
+Keep the Contract table as the source of truth for input, output, state, and
+the enforcement gate. Use short ordered steps for actions and move branch-only
+detail into references or guides.
+
+Before registering a skill, check the Harness registry for overlap, define one
+human-readable frontmatter description, run realistic with/without tests using
+`multi-agent-workspace`, and complete the Quality Checklist. Static skills
+belong in the root catalog and need a routing eval; dynamic skills use the
+generated manifest flow from `self-evolve`.
+
+The canonical multi-agent entrypoint is `multi-agent-workspace`; it owns
+bounded delegation and workspace isolation.

package/skill-creator/references/dynamic-generation-contract.md

@@ -0,0 +1,21 @@
+# Dynamic Skill Generation Contract (for self-evolve)
+
+## 4. Dynamic Skill Generation Contract (for `self-evolve`)
+
+`self-evolve`'s Step 3 optionally packages a hard-won session insight into a new, standalone skill. This process **MUST** only occur if the LLM has judged that the lesson warrants an independent, complex structural skill rather than a simple memory rule:
+
+- **The Judgment Criterion**: Simple constraints or localized tips **MUST** only be written to `memories/repo/RULES.md`. Only highly generalizable, multi-step procedures or custom enforcement contracts (e.g. transaction pooling patterns) should be packaged as a dynamic skill.
+- **Location**: `.claude/harness-everything/skills/generated/<kebab-case-name>/SKILL.md` — not the repo root. `.claude/harness-everything/skills` is already a scope the installer recognizes (`scripts/lib/skills.js`'s `getInstalledSkills`), which keeps dynamically-generated skills discoverable without mixing them into the reviewed, static skill set at the repo root. `generated/` is deliberately excluded from the installer's manifest-tracked, bulk-removable skill set — these are the user's own accumulated learning, not package content, so "uninstall skills" must never sweep them.
+- **Required frontmatter**, in addition to `name`/`description`:
+  ```yaml
+  triggers: [<3-6 specific keywords a real prompt would contain, EN and/or 中文 — not generic words like "error" or "using">]
+  metadata:
+    type: dynamic
+    generated: <YYYY-MM-DD>
+    source: <one-line pointer to the session/root-cause that produced it, e.g. "zoom-out recovery, 2026-07-22, ORM connection-pool exhaustion">
+    status: draft
+  ```
+  `triggers` is what `tier-router.js` matches against to auto-surface this skill in future sessions — pick words specific enough to the actual problem domain (e.g. `connection-pool`, `transaction-batching`), not words generic enough to fire on unrelated prompts. Omitting this field falls back to `register-dynamic-skill.js`'s naive keyword inference from the name/description, which is intentionally conservative and a worse signal than a deliberate list — don't rely on it.
+- **Gate**: run the Quality Checklist (§3) before the skill file is written. A dynamic skill skips human PR review by design, so this checklist is the only review it gets — don't skip it because the insight "feels obviously right" in the moment; that's exactly the state self-evolve is triggered from.
+- **Lifecycle**: `status: draft` at birth. Promote to `status: active` once it fires successfully in a *different* task than the one that produced it — a skill that has only proven itself on the bug that spawned it hasn't proven generality yet. If a dynamic skill goes unused or stops matching reality, mark `status: deprecated` rather than deleting it silently — deleting is fine once something else supersedes it, but a silent disappearance is harder to debug later than a stale-but-labeled file.
+- **Promotion to static**: once a dynamic skill has proven itself general — used successfully across genuinely unrelated tasks, not repeated instances of the same bug — promote it: move it to the repo root, drop the `metadata.type: dynamic` block, and register it in `harness-everything/SKILL.md` §5 like any other skill. At that point it's subject to the same review/PR discipline as everything else here.

package/skill-creator/references/quality-checklist.md

@@ -0,0 +1,16 @@
+# Quality Checklist (the actual gate)
+
+## 3. Quality Checklist (the actual gate)
+
+A skill isn't done until every line here is true. This is deliberately a flat checklist, not steps — check them in any order, but check all of them.
+
+- [ ] **Skill Contract table present and accurate** — all four rows; Enforcement Gate names a real script/exit-code or an explicit "None" if the skill is pure reference.
+- [ ] **`## USE FOR:` and `## DO NOT USE FOR:` sections present**, each a flat bullet list starting on its own line (`^## USE FOR:` / `^## DO NOT USE FOR:`). Required by `<skills-repo-root>/ci/consistency-check.js` (`npm run test:consistency`) — missing either fails the repo's own consistency gate, not just this checklist.
+- [ ] **Single source of truth**: the frontmatter `description` is the *only* place this skill's purpose is originally written. The registry row and any `tier-router.js` line quote or tightly paraphrase it — they don't independently re-describe the skill.
+- [ ] **No block over ~5 lines duplicated verbatim elsewhere** — in this file or in another always/near-always-loaded skill. (`install-cognitive-os` vs. `harness-everything`'s 33-line ADHD-output block, flagged in the audit report, is the canonical counter-example — don't add a second one.)
+- [ ] **Every `MUST`/`MUST NOT`/`PROHIBITED` has a real gate behind it**, or is rewritten as a positive statement of the target behavior. A prohibition with no gate and no "why" sentence next to it is a smell, not a strength.
+- [ ] **No no-op lines** — for each imperative sentence, ask whether it changes behavior versus what the model already does by default. ("Be thorough" reads as a no-op; a concrete completion criterion or a stronger leading word doesn't.)
+- [ ] **Body fits the information hierarchy** — steps for ordered action, flat reference for rules, detail past what every branch needs pushed to `guides/`/`references/` with a "when to open this" pointer.
+- [ ] **Reuses existing leading words** (`Tier 1/2/3`, `circuit breaker`/`zoom out`, `Rule of 3`, `Red/Green/Refactor`, `Discover > Think > Try > Summarize > Record`) instead of naming a new concept for something this repo already has a word for.
+- [ ] **Completion criteria are checkable** — tied to an exit code, a file's existence, a grep result, or explicit human confirmation, not "when it feels done."
+- [ ] **Description reads as a human-facing sentence**, not just a trigger-phrase list — `scripts/installer.js`'s interactive picker prints it next to a checkbox for a person deciding whether to install this skill; that's its real first reader in this architecture (audit report §2.1).

package/skill-creator/references/quality-principles.md

@@ -1,81 +1,81 @@
-# Quality Principles — condensed from `writing-great-skills` and Anthropic's `skill-creator`
-
-Read this when `skill-creator/SKILL.md`'s Quality Checklist flags something and you need the reasoning behind the check, not just the checkbox. Each term below is condensed from the two source skills and paired with a Harness-specific example — good or bad — found during the 2026-07-22 audit.
-
-## Contents
-- [The root idea: Predictability](#the-root-idea-predictability)
-- [Information hierarchy](#information-hierarchy)
-- [Pruning](#pruning)
-- [Leading words](#leading-words)
-- [Negation](#negation)
-- [Invocation, adapted for Harness's router](#invocation-adapted-for-harnesss-router)
-- [Anthropic `skill-creator`'s anatomy conventions](#anthropic-skill-creators-anatomy-conventions)
-
-## The root idea: Predictability
-
-A skill exists to make the agent take the same *process* on every run — not the same output. A skill that should diverge (brainstorming, `grill-me`'s interrogation) is still predictable if it reliably takes the same *kind* of path every time. Every other term here is a lever on this one thing. Harness reaches for the same goal through a different lever — a physical Enforcement Gate instead of a cognitive one — see `skill-creator/SKILL.md` §1 for how the two combine.
-
-## Information hierarchy
-
-Content in a skill ranks by how immediately the agent needs it:
-
-1. **Steps** — ordered actions in the SKILL.md body. Each ends on a completion criterion. Harness's Skill Contract table makes this criterion unusually concrete by default (an exit code, a file write) — keep that when you write new steps; don't downgrade a checkable criterion to a vague one for the sake of shorter prose.
-2. **In-file reference** — rules, tables, decision lists consulted on demand. A skill can be *all* reference with no steps at all (`skill-style` itself, most review-shaped skills) — that's a legitimate shape, not a smell.
-3. **Disclosed / external reference** — pushed into a linked file, reached by a pointer, loaded only when the pointer fires.
-
-**Good Harness example**: `git-commit/SKILL.md` keeps the core Angular-style rules inline and pushes submodule handling, language detection, and generation strategy into `git-commit/guides/*.md`, each named for what it holds. `tdd/SKILL.md` does the same with `tdd/guides/mocking.md`, `interface-design.md`, etc.
-
-**Bad Harness example**: `security-review/SKILL.md` is 508 lines — the longest in the repo — with no reference-file split. It wasn't re-read line-by-line for this audit, but its length alone is the sprawl smell described below; it's the next candidate if this skill's checklist gets applied broadly.
-
-A **context pointer**'s *wording* decides whether the agent actually opens the linked file — not just its existence. "See `guides/mocking.md` for more" is weak; "before writing any test double, read `guides/mocking.md`" is a pointer that actually fires. Every "Deep Reference Guides" section in this repo should name *when*, not just *what*.
-
-## Pruning
-
-Four related failure modes, roughly in order of how much they cost:
-
-- **Duplication** — the same meaning stated in more than one place. Costs tokens on every load, and drifts over time because nobody remembers to edit both copies. The audit report's §1.1 (33 lines shared verbatim between `install-cognitive-os` and `harness-everything`) and §1.2 (one skill's description independently rewritten in four places, two of which already disagree) are the two worst confirmed cases in this repo. **Test**: could you point to exactly one place that defines this, and would editing only that place actually change the behavior everywhere it matters?
-- **Sediment** — stale content nobody removes because adding feels safe and removing feels risky. `docs/workflows/skill-style.md`'s three Mermaid diagrams (audit §1.4) are a mild case: not wrong, just three restatements of one flow that accreted instead of being consolidated.
-- **Sprawl** — a skill simply too long, even if every line is live and unique. The cure is always the information hierarchy above: push reference behind a pointer, split by branch.
-- **No-op** — an instruction the model already follows by default, so you pay tokens to say nothing. Test it against the actual default, not against how important the rule feels: "MUST operate using the cognitive loop" repeated inside a sub-skill when `install-cognitive-os` already declares itself always-loaded (audit §2.3) is a borderline example — not egregious, but a candidate to cut the next time that file is touched.
-
-## Leading words
-
-A leading word is a compact, already-understood concept the model can think *with*, repeated as a token (not re-explained as a sentence) everywhere it applies. This repo already has strong ones — don't invent synonyms for them:
-
-| Leading word | What it compresses |
-|---|---|
-| `Tier 1 / 2 / 3` | Task-complexity routing and the whole action-strategy that follows from each |
-| `circuit breaker` / `zoom out` | The entire reflect-before-retry protocol in `zoom-out/SKILL.md` |
-| `Rule of 3` | "three failed attempts on the same signature ⇒ stop and reflect" |
-| `Red / Green / Refactor` | The TDD cycle and which actions are legal in each phase |
-| `Discover > Think > Try > Summarize > Record` | The base cognitive loop every tier and skill runs inside |
-
-When a new skill needs to say "stop and reflect on repeated failure," write `trigger zoom-out`, not a fresh paragraph re-explaining the reflection protocol. That's the whole payoff of a leading word: one anchored phrase instead of a restated idea.
-
-## Negation
-
-A prohibition drags the forbidden behavior into the model's attention rather than out of it — "don't think of an elephant" makes the elephant the only thing present. This repo uses `MUST NOT`/`PROHIBITED` heavily and by design (`skill-style` mandates it), so the actual lever available isn't "stop using negation" — it's **reserve it for gates that are real**, and pair the rest with the positive target:
-
-- **Does this well**: `zoom-out/SKILL.md`'s "ABSOLUTELY PROHIBITED from proposing any new code modification" is immediately followed by *why* ("that sentence is the tunnel talking") and by what to do instead (Phase 2's read-only fact-checking). The prohibition isn't left to stand alone.
-- **Could do better**: `environment-detection/SKILL.md`'s "Red Flags & Common Errors" section restates, as a list of ❌ prohibitions, rules the same file already gave positively one section earlier (which shell uses which syntax). The information isn't wrong, it's just said twice in two moods.
-
-If you're about to write `MUST NOT X`, check: is there a script or state mutation that actually enforces this, or human cost if violated (data loss, a broken build, a security gap)? If yes, keep the imperative — that's this repo's real strength, don't soften it. If no, try stating what *good* looks like instead and see if the `MUST NOT` was even carrying information.
-
-## Invocation, adapted for Harness's router
-
-The original framework's "model-invoked vs. user-invoked" split assumes a native skill system where an agent autonomously reads `description` fields and decides what to fire. That's not how this repo's skills are actually reached — confirmed by reading `scripts/installer.js` and `harness-everything/scripts/tier-router.js` directly rather than assuming:
-
-- `harness-everything/SKILL.md` §5's Skill Registry table is a hand-maintained index — functionally Harness's own version of the framework's **router skill** pattern (a single place a human, or `tier-router.js` on their behalf, can look up "what exists and when to reach for it").
-- `tier-router.js` prints keyword-triggered recommendations from its own hardcoded strings — a second, independent "what does this skill do" list that must be kept in sync with the registry and the frontmatter by hand (this is where the drift in audit §1.2 came from).
-- `scripts/installer.js`'s interactive CLI picker is the one place that *does* read frontmatter `description` directly and shows it to a live reader — a **human**, choosing checkboxes at install time. That makes the real invocation axis in this repo closer to "does a human need to understand this in one line while skimming a checklist" than "will an autonomous model decide to fire this."
-
-Practical upshot: write `description` as a plain, scannable sentence for that installer screen. Trigger-condition phrasing ("Use when...") isn't wrong, but it's optimizing for a reader (an autonomous picker) that doesn't exist in this deployment yet. If this repo's skills are ever installed as native Claude Skills (`.claude/skills/`) rather than the current `.claude/harness-everything/skills` / hook-advisory model, this section should be revisited — the trigger-phrasing advice becomes directly relevant again at that point.
-
-## Anthropic `skill-creator`'s anatomy conventions
-
-Kept because they don't conflict with anything above — they're just concrete, useful defaults:
-
-- Bundled resources split by purpose: `scripts/` for things that execute deterministically, `references/` for things loaded into context on demand (this file is one), `guides/`/`templates/` (Harness's existing naming) for the same idea.
-- A reference file past ~300 lines gets a table of contents (this file has one).
-- Domain-organized skills (a skill that supports several distinct variants) split by variant, one file per variant, so only the relevant one loads — `repo-docs/templates/*.md` already does this for different README/AGENTS.md archetypes.
-- Draft first, then re-read with fresh eyes and cut. Don't try to write the pruned version on the first pass.
+# Quality Principles — condensed from `writing-great-skills` and Anthropic's `skill-creator`
+
+Read this when `skill-creator/SKILL.md`'s Quality Checklist flags something and you need the reasoning behind the check, not just the checkbox. Each term below is condensed from the two source skills and paired with a Harness-specific example — good or bad — found during the 2026-07-22 audit.
+
+## Contents
+- [The root idea: Predictability](#the-root-idea-predictability)
+- [Information hierarchy](#information-hierarchy)
+- [Pruning](#pruning)
+- [Leading words](#leading-words)
+- [Negation](#negation)
+- [Invocation, adapted for Harness's router](#invocation-adapted-for-harnesss-router)
+- [Anthropic `skill-creator`'s anatomy conventions](#anthropic-skill-creators-anatomy-conventions)
+
+## The root idea: Predictability
+
+A skill exists to make the agent take the same *process* on every run — not the same output. A skill that should diverge (brainstorming, `grill-me`'s interrogation) is still predictable if it reliably takes the same *kind* of path every time. Every other term here is a lever on this one thing. Harness reaches for the same goal through a different lever — a physical Enforcement Gate instead of a cognitive one — see `skill-creator/SKILL.md` §1 for how the two combine.
+
+## Information hierarchy
+
+Content in a skill ranks by how immediately the agent needs it:
+
+1. **Steps** — ordered actions in the SKILL.md body. Each ends on a completion criterion. Harness's Skill Contract table makes this criterion unusually concrete by default (an exit code, a file write) — keep that when you write new steps; don't downgrade a checkable criterion to a vague one for the sake of shorter prose.
+2. **In-file reference** — rules, tables, decision lists consulted on demand. A skill can be *all* reference with no steps at all (`skill-style` itself, most review-shaped skills) — that's a legitimate shape, not a smell.
+3. **Disclosed / external reference** — pushed into a linked file, reached by a pointer, loaded only when the pointer fires.
+
+**Good Harness example**: `git-commit/SKILL.md` keeps the core Angular-style rules inline and pushes submodule handling, language detection, and generation strategy into `git-commit/guides/*.md`, each named for what it holds. `tdd/SKILL.md` does the same with `tdd/guides/mocking.md`, `interface-design.md`, etc.
+
+**Bad Harness example**: `security-review/SKILL.md` is 508 lines — the longest in the repo — with no reference-file split. It wasn't re-read line-by-line for this audit, but its length alone is the sprawl smell described below; it's the next candidate if this skill's checklist gets applied broadly.
+
+A **context pointer**'s *wording* decides whether the agent actually opens the linked file — not just its existence. "See `guides/mocking.md` for more" is weak; "before writing any test double, read `guides/mocking.md`" is a pointer that actually fires. Every "Deep Reference Guides" section in this repo should name *when*, not just *what*.
+
+## Pruning
+
+Four related failure modes, roughly in order of how much they cost:
+
+- **Duplication** — the same meaning stated in more than one place. Costs tokens on every load, and drifts over time because nobody remembers to edit both copies. The audit report's §1.1 (33 lines shared verbatim between `install-cognitive-os` and `harness-everything`) and §1.2 (one skill's description independently rewritten in four places, two of which already disagree) are the two worst confirmed cases in this repo. **Test**: could you point to exactly one place that defines this, and would editing only that place actually change the behavior everywhere it matters?
+- **Sediment** — stale content nobody removes because adding feels safe and removing feels risky. `docs/workflows/skill-style.md`'s three Mermaid diagrams (audit §1.4) are a mild case: not wrong, just three restatements of one flow that accreted instead of being consolidated.
+- **Sprawl** — a skill simply too long, even if every line is live and unique. The cure is always the information hierarchy above: push reference behind a pointer, split by branch.
+- **No-op** — an instruction the model already follows by default, so you pay tokens to say nothing. Test it against the actual default, not against how important the rule feels: "MUST operate using the cognitive loop" repeated inside a sub-skill when `install-cognitive-os` already declares itself always-loaded (audit §2.3) is a borderline example — not egregious, but a candidate to cut the next time that file is touched.
+
+## Leading words
+
+A leading word is a compact, already-understood concept the model can think *with*, repeated as a token (not re-explained as a sentence) everywhere it applies. This repo already has strong ones — don't invent synonyms for them:
+
+| Leading word | What it compresses |
+|---|---|
+| `Tier 1 / 2 / 3` | Task-complexity routing and the whole action-strategy that follows from each |
+| `circuit breaker` / `zoom out` | The entire reflect-before-retry protocol in `zoom-out/SKILL.md` |
+| `Rule of 3` | "three failed attempts on the same signature ⇒ stop and reflect" |
+| `Red / Green / Refactor` | The TDD cycle and which actions are legal in each phase |
+| `Discover > Think > Try > Summarize > Record` | The base cognitive loop every tier and skill runs inside |
+
+When a new skill needs to say "stop and reflect on repeated failure," write `trigger zoom-out`, not a fresh paragraph re-explaining the reflection protocol. That's the whole payoff of a leading word: one anchored phrase instead of a restated idea.
+
+## Negation
+
+A prohibition drags the forbidden behavior into the model's attention rather than out of it — "don't think of an elephant" makes the elephant the only thing present. This repo uses `MUST NOT`/`PROHIBITED` heavily and by design (`skill-style` mandates it), so the actual lever available isn't "stop using negation" — it's **reserve it for gates that are real**, and pair the rest with the positive target:
+
+- **Does this well**: `zoom-out/SKILL.md`'s "ABSOLUTELY PROHIBITED from proposing any new code modification" is immediately followed by *why* ("that sentence is the tunnel talking") and by what to do instead (Phase 2's read-only fact-checking). The prohibition isn't left to stand alone.
+- **Could do better**: `environment-detection/SKILL.md`'s "Red Flags & Common Errors" section restates, as a list of ❌ prohibitions, rules the same file already gave positively one section earlier (which shell uses which syntax). The information isn't wrong, it's just said twice in two moods.
+
+If you're about to write `MUST NOT X`, check: is there a script or state mutation that actually enforces this, or human cost if violated (data loss, a broken build, a security gap)? If yes, keep the imperative — that's this repo's real strength, don't soften it. If no, try stating what *good* looks like instead and see if the `MUST NOT` was even carrying information.
+
+## Invocation, adapted for Harness's router
+
+The original framework's "model-invoked vs. user-invoked" split assumes a native skill system where an agent autonomously reads `description` fields and decides what to fire. That's not how this repo's skills are actually reached — confirmed by reading `scripts/installer.js` and `harness-everything/scripts/tier-router.js` directly rather than assuming:
+
+- `harness-everything/SKILL.md` §5's Skill Registry table is a hand-maintained index — functionally Harness's own version of the framework's **router skill** pattern (a single place a human, or `tier-router.js` on their behalf, can look up "what exists and when to reach for it").
+- `tier-router.js` prints keyword-triggered recommendations from its own hardcoded strings — a second, independent "what does this skill do" list that must be kept in sync with the registry and the frontmatter by hand (this is where the drift in audit §1.2 came from).
+- `scripts/installer.js`'s interactive CLI picker is the one place that *does* read frontmatter `description` directly and shows it to a live reader — a **human**, choosing checkboxes at install time. That makes the real invocation axis in this repo closer to "does a human need to understand this in one line while skimming a checklist" than "will an autonomous model decide to fire this."
+
+Practical upshot: write `description` as a plain, scannable sentence for that installer screen. Trigger-condition phrasing ("Use when...") isn't wrong, but it's optimizing for a reader (an autonomous picker) that doesn't exist in this deployment yet. If this repo's skills are ever installed as native Claude Skills (`.claude/skills/`) rather than the current `.claude/harness-everything/skills` / hook-advisory model, this section should be revisited — the trigger-phrasing advice becomes directly relevant again at that point.
+
+## Anthropic `skill-creator`'s anatomy conventions
+
+Kept because they don't conflict with anything above — they're just concrete, useful defaults:
+
+- Bundled resources split by purpose: `scripts/` for things that execute deterministically, `references/` for things loaded into context on demand (this file is one), `guides/`/`templates/` (Harness's existing naming) for the same idea.
+- A reference file past ~300 lines gets a table of contents (this file has one).
+- Domain-organized skills (a skill that supports several distinct variants) split by variant, one file per variant, so only the relevant one loads — `repo-docs/templates/*.md` already does this for different README/AGENTS.md archetypes.
+- Draft first, then re-read with fresh eyes and cut. Don't try to write the pruned version on the first pass.

package/skill-creator/references/testing-workflow.md

@@ -1,32 +1,27 @@
-# Testing Workflow — adapted from Anthropic's `skill-creator` eval loop
-
-Read this when `skill-creator/SKILL.md` §2 Step 3 says "test against real prompts" and you need the mechanics. Anthropic's `skill-creator` runs this through a Python eval-viewer with subagent grading and a `claude -p`-based description-optimization loop. Harness doesn't import that toolchain — it already has `create-agent-launcher` for resource-isolated subagent spawning, and its skill-routing is deterministic keyword matching rather than autonomous LLM judgment, so the equivalent checks are cheaper and don't need a second dependency.
-
-## When to bother
-
-Not every skill needs this. A short, low-stakes reference skill (a rule table, a style guide) is fine to ship on a careful re-read. Run the full loop when:
-- The skill has real **Steps** the agent must execute in a specific order, especially ones with an Enforcement Gate — you want to see the gate actually fire on a bad run, not just assume it will.
-- The skill is going to be recommended automatically (registered in `harness-everything/SKILL.md` §5 and/or `tier-router.js`) rather than only invoked by name — automatic recommendation means it'll be loaded in situations you didn't personally test by hand.
-- You're refactoring an existing skill based on a specific complaint, and want to confirm the fix actually lands rather than just looking right on the page.
-
-## With/without comparison via `create-agent-launcher`
-
-1. Write 2-3 prompts a real user would actually type — concrete, with the kind of incidental detail real requests carry (a file path, a framework name, a half-finished thought). Anthropic's `skill-creator` has good guidance on this: avoid both sides being trivially obvious. A bad "should trigger" prompt is abstract ("test the skill"); a bad "should not trigger" prompt is unrelated to anything the skill touches. The useful test cases are near-misses in both directions.
-2. Per `create-agent-launcher/SKILL.md` §2 (Persona Definition, Resource Isolation): spawn one subagent with the draft skill's file path given to it explicitly and instructed to follow it, and one baseline subagent given the same prompt with no mention of the skill.
-3. Compare outputs side by side, but **read the transcripts, not just the final result** — a skill that produces a fine final answer while making the agent thrash through three dead-end tool calls first is still under-specifying something; the final output alone won't show you that.
-4. Where the skill has a real Enforcement Gate, deliberately construct one test case that should trip it (e.g., for a skill gating on a failing test, hand it a prompt implying the test currently fails) and confirm the with-skill run actually stops/reflects instead of pushing through.
-
-## Checking trigger phrasing against a deterministic router
-
-Anthropic's `skill-creator` has a whole optimization loop (`run_loop.py`) that runs a description against dozens of realistic queries through the actual model, because native Claude Skills decide to fire based on an LLM reading the description at run time. Harness's routing recommendation layer (`tier-router.js`) is **not** an LLM judgment call — it's `promptLower.includes(keyword)` string matching against hardcoded arrays. That means you can check trigger coverage deterministically, without spawning a single subagent:
-
-1. Write the same kind of realistic should-trigger / should-not-trigger prompt set described above (8-10 each is plenty for a new skill; fewer is fine for a small change).
-2. For each should-trigger prompt, check by eye (or a one-line `node -e` snippet) whether it contains at least one keyword from the relevant array in `harness-everything/scripts/tier-router.js`. If a realistic phrasing doesn't hit any keyword, that's a real gap — add the missing term (bilingual, if this repo's convention applies — most keyword arrays here carry both English and Chinese terms side by side).
-3. For each should-not-trigger prompt — especially near-misses that share vocabulary with the skill but need something else — confirm it does *not* spuriously match. A keyword that's too broad (a single common English word with no qualifying context) is the usual cause of a false positive; narrow it or require it alongside a second signal.
-4. This check is cheap enough to re-run by hand every time a keyword array changes — there's no reason to skip it even for a one-line addition.
-
-This isn't a replacement for the with/without subagent comparison above — it only tells you whether the skill gets *recommended* at the right moments, not whether it's good once loaded. Both checks matter; they're checking different failure modes.
-
-## Folding feedback back in
-
-If a human reviewer (or your own re-read) flags something in the output, resist the urge to patch the skill with a rule that only fixes that one test case. Ask what the *general* version of the complaint is first — the same discipline `skill-creator/SKILL.md` §3's Quality Checklist asks for: is this a genuinely missing rule, or does an existing rule already cover it and just needs a stronger leading word to actually land? Re-test after any change, including the baseline — a skill's environment (the rest of the repo, the router keywords around it) can shift under it between iterations.
+# Testing Workflow
+
+Read this when `skill-creator/SKILL.md` asks for realistic trigger tests or a
+with/without comparison. Harness uses deterministic routing and the merged
+`multi-agent-workspace` skill for bounded sub-agent spawning.
+
+## With/without comparison
+
+1. Write 2-3 realistic prompts with paths, framework names, and near-misses.
+2. Use `multi-agent-workspace` to spawn one sub-agent with the draft skill
+   loaded and one baseline with no mention of it.
+3. Read both transcripts, not only final answers; record thrashing and missed
+   gates as evidence.
+4. Construct one prompt that should trigger the skill's enforcement gate and
+   verify that the treatment reflects instead of pushing through.
+
+## Deterministic trigger check
+
+Check realistic positive and negative prompts against the keyword table in
+`harness-everything/scripts/routing-keywords.json`. A positive miss is a
+routing gap; a negative hit usually means a keyword is too broad.
+
+## Completion
+
+Keep the canonical frontmatter description identical in the positive eval's
+`description:` field. Run the relevant `waza spec verify` and repository
+consistency checks before registration.

package/skill-style/SKILL.md

@@ -1,48 +1,42 @@
 ---
 name: skill-style
-description: Guidelines for writing and refactoring skills in the Harness ecosystem.
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
+description: Apply Harness style guidelines when writing or refactoring SKILL.md files. Use when creating a new skill, reviewing skill structure, enforcing naming and frontmatter conventions, or standardizing tone, formatting, and progressive disclosure across the skill catalog.
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
 ---
 
-# Skill Style (Harness Ecosystem Skill Development Guidelines)
+# Skill Style
 
-When you need to create a new Skill or refactor an existing one, strictly adhere to the writing style in this document to ensure all Skills seamlessly integrate into the `harness-everything` routing system and are mathematically enforced by scripts.
+Apply the Harness writing standard when creating or refactoring `SKILL.md` files.
 
-## 0. Triggers
-This skill should be loaded when:
-- Creating a new SKILL.md file.
-- Refactoring or reviewing an existing SKILL.md file.
-
-## 1. Structured Definition
-Every Skill file (`SKILL.md`) MUST contain the following standard structure:
-
-1.  **Title & Introduction**: Clearly state the purpose of this Skill.
-2.  **📋 Skill Contract (CRITICAL)**: A strict Markdown table defining inputs, outputs, state mutations, and script gates. This replaces vague prose.
-3.  **Triggers / Usage**: Explicitly tell the system when this skill applies.
-4.  **Core Rules / Action List**: Specific, actionable commands tied to Terminal Scripts. Avoid vague suggestions.
-
-### 📋 The Skill Contract Format
-Every SKILL.md MUST include this table exactly:
-
-```markdown
-## 📋 Skill Contract
+## Skill Contract
 
 | Component | Specification |
 | :--- | :--- |
-| **Trigger / Input** | (What causes this skill to execute? What exact data/args does it expect?) |
-| **Expected Output** | (What specific files, artifacts, or Terminal Exit Codes are produced?) |
-| **State Mutations** | (What JSON/files are written to track progress? e.g., `.claude/harness-state/todo-state.json`) |
-| **Enforcement Gate** | (Which exact CLI script slaps the LLM with Exit Code 1 if it fails?) |
-```
-
-## 2. Tone & Voice
-- **Anti-Linear / Anti-Prose**: Do not write long paragraphs. Map actions to specific `run_in_terminal` commands.
-- **Absolute Imperatives**: Use "MUST", "MUST NOT", "ALWAYS". Do not use "suggest".
-- **Script-Driven Enforcement**: Do not write "You should check your code". Write "You MUST run `node verify-gate.js`. If Exit Code 1, you MUST reflect and retry."
-
-## 3. Avoid Functional Overlap
-- **OS Skills vs. Domain Skills**: Distinguish between the OS layer (which routes and constrains behavior) and the Domain layer (which provides deep technical expertise).
-
-## 4. For the fuller authoring & quality workflow, see `skill-creator`
-This document is the terse format spec — the Skill Contract table shape and the tone rules. For interviewing intent, drafting, testing a skill against real prompts, pruning duplication/no-op/sprawl, and the rules for skills `self-evolve` generates dynamically mid-session, load `skill-creator/SKILL.md` instead. It builds on this spec rather than replacing it.
+| **Trigger / Input** | Creating, reviewing, or refactoring a Harness `SKILL.md`. |
+| **Expected Output** | A concise, complete, non-overlapping `SKILL.md`. |
+| **State Mutations** | None; this is a writing and review standard. |
+| **Enforcement Gate** | `npm run test:consistency` plus style-guide review. |
+
+## USE FOR:
+- Creating a new SKILL.md file
+- Refactoring or reviewing an existing SKILL.md
+- Deciding tone, structure, or enforcement style for skills
+- Checking whether a skill overlaps an existing OS/domain skill
+
+## DO NOT USE FOR:
+- Interviewing intent, drafting, or testing a skill against real prompts (load `<skills-repo-root>/skill-creator/SKILL.md`)
+- Routing rules for dynamically generated mid-session skills owned by `self-evolve`
+- Non-Harness skill formats outside `harness-everything`
+
+## Core Rules
+
+1. MUST keep frontmatter accurate and the description routeable.
+2. MUST include, in order: title, introduction, Skill Contract, usage, and actionable rules.
+3. MUST use imperative language and name the enforcing command or gate.
+4. MUST avoid overlap with OS-layer routing or domain expertise.
+5. For intent interviews, drafting, and prompt tests, load `<skills-repo-root>/skill-creator/SKILL.md`.
+
+Deep dive: `<this-skill-dir>/references/style-guide.md`

package/skill-style/references/style-guide.md

@@ -0,0 +1,62 @@
+# Skill Style Guide — Full Detail
+
+When you need to create a new Skill or refactor an existing one, strictly adhere to the writing style in this document to ensure all Skills seamlessly integrate into the `harness-everything` routing system and are mathematically enforced by scripts.
+
+## 1. Structured Definition
+Every Skill file (`SKILL.md`) MUST contain the following standard structure:
+
+1.  **Title & Introduction**: Clearly state the purpose of this Skill.
+2.  **📋 Skill Contract (CRITICAL)**: A strict Markdown table defining inputs, outputs, state mutations, and script gates. This replaces vague prose.
+3.  **Triggers / Usage**: Explicitly tell the system when this skill applies.
+4.  **Core Rules / Action List**: Specific, actionable commands tied to Terminal Scripts. Avoid vague suggestions.
+
+### 📋 The Skill Contract Format
+Every SKILL.md MUST include this table exactly:
+
+```markdown
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | (What causes this skill to execute? What exact data/args does it expect?) |
+| **Expected Output** | (What specific files, artifacts, or Terminal Exit Codes are produced?) |
+| **State Mutations** | (What JSON/files are written to track progress? e.g., a stage audit JSONL file under `.claude/harness-everything/state/`) |
+| **Enforcement Gate** | (Which exact CLI script slaps the LLM with Exit Code 1 if it fails?) |
+```
+
+## 2. Tone & Voice
+- **Anti-Linear / Anti-Prose**: Do not write long paragraphs. Map actions to specific `run_in_terminal` commands.
+- **Absolute Imperatives**: Use "MUST", "MUST NOT", "ALWAYS". Do not use "suggest".
+- **Script-Driven Enforcement**: Do not write "You should check your code". Write "You MUST run `node <skills-repo-root>/harness-everything/scripts/verify-gate.js`. If Exit Code 1, you MUST reflect and retry."
+
+## 3. Path Notation
+Every path a `SKILL.md` names is checked by `node <skills-repo-root>/ci/reference-check.js`. Every checked path MUST name its base explicitly: use `<this-skill-dir>/` for the skill that names it, `<skills-repo-root>/` for this package, and `<workspace>/` for the user's project.
+
+| Form | Base | Checked? |
+| :--- | :--- | :--- |
+| `<this-skill-dir>/references/x.md`, `<this-skill-dir>/../x.md` | this skill's own directory | yes |
+| `<skills-repo-root>/skill-creator/SKILL.md` | another skill in this package | yes |
+| `<skills-repo-root>/hooks/x.js` | the root of this package | yes |
+| `<workspace>/anywhere/x.md` | a path in the USER's project | no - recorded as intentional |
+
+- **MUST** use one of the three markers. Bare `references/x.md`, `../x.md`, or `ci/x.js` is a hard failure, not a guess.
+- **MUST NOT** invent a new placeholder. An unrecognised one is a hard failure, not a skip - a typo like `<this_folder>/` would otherwise make every path in the file invisible to the gate. Register a genuinely new one in `<skills-repo-root>/ci/reference-check.js`.
+- Use `<workspace>/` for every user-project path. It always wins over any package rule.
+- Markers cost words, but explicit bases prevent a top-level directory from silently changing a path's meaning. Keep the top-level body short and put explanation in the workflow or references rung.
+- A bare filename with no directory (`CONTEXT.md`, `package.json`) is prose and stays unchecked. Give it a directory when you mean a specific file.
+
+## 4. Progressive Disclosure
+
+Keep each skill in three clear rungs:
+
+1. `SKILL.md` contains the trigger, contract, short imperative workflow, `USE FOR`/`DO NOT USE FOR`, and one valid `Deep dive:` entry point. Keep its body at or below 330 words, the local proxy for waza's 500-token limit.
+2. `docs/workflows/<skill>.md` explains the same workflow in plain language. It must contain at least one meaningful Mermaid diagram showing a real sequence, state change, or decision. Complex workflows need separate diagrams for distinct branches; repeated decorative graphs do not count.
+3. `references/` or `guides/` holds detailed procedures, examples, and checklists. Load these files only when the task reaches that detail.
+
+Do not put Mermaid source in `SKILL.md`, copy a full guide into the top-level file, or change a `description:` during a content-only rewrite. The description is a routing API and must remain byte-identical unless a routing change is intentional.
+
+## 5. Avoid Functional Overlap
+- **OS Skills vs. Domain Skills**: Distinguish between the OS layer (which routes and constrains behavior) and the Domain layer (which provides deep technical expertise).
+
+## 6. For the fuller authoring & quality workflow, see `skill-creator`
+This document is the terse format spec — the Skill Contract table shape and the tone rules. For interviewing intent, drafting, testing a skill against real prompts, pruning duplication/no-op/sprawl, and the rules for skills `self-evolve` generates dynamically mid-session, load `skill-creator/SKILL.md` instead. It builds on this spec rather than replacing it.

package/submission/openai/README.md

@@ -0,0 +1,67 @@
+# OpenAI Public Plugin Submission
+
+This directory contains repository-owned source material for OpenAI’s public **Skills only** plugin submission portal. It is separate from both the local `.codex-plugin` package manifest and the managed-workspace marketplace manifests.
+
+## Build the final skills bundle
+
+Run:
+
+```bash
+npm run plugin:sync
+npm run plugin:submission:build
+```
+
+The builder writes:
+
+```text
+dist/openai-submission/
+├── harness-everything-skills.zip
+└── harness-everything-skills.manifest.json
+```
+
+The ZIP contains exactly the synchronized `plugins/harness-everything/skills/` tree under `skills/`. It does not contain the local `.codex-plugin` lifecycle hooks, MCP definitions, or app wrappers. The manifest records every file path, byte count, content hash, and final bundle SHA-256. Rebuilding the same revision must produce the same bundle hash.
+
+## Official portal workflow
+
+1. Select **Create plugin**.
+2. Choose **Skills only**.
+3. Provide the listing metadata from `listing.json`.
+4. Upload the final `harness-everything-skills.zip` bundle.
+5. Provide the starter prompts and exactly five positive plus three negative reviewer cases from `test-cases.json`.
+6. Select the verified developer/business identity, production logo, availability, and policy attestations.
+7. Confirm the submitter has **Apps Management: Write** access.
+8. Submit for review and publish only after approval.
+
+Official documentation: [Submit a plugin](https://developers.openai.com/plugins/deploy/submission).
+
+The review cases follow the documented shape. Each positive case includes a prompt, expected skill/workflow behavior, expected result shape, and fixture/account data. Each negative case includes a prompt/scenario, expected refusal/clarification/safe fallback, and a reason not to complete.
+
+## Public submission boundary
+
+The public **Skills only** bundle contains skills, scripts, templates, and assets referenced by those skills. It does not contain the local `.codex-plugin` lifecycle hooks. Therefore public review material must not claim that `SessionStart`, `UserPromptSubmit`, or other host-specific hooks provide hard enforcement in the published artifact.
+
+The skills still provide routing, verification, failure recovery, TDD, security review, documentation, and other reusable workflow guidance. The test cases evaluate those workflows against the final skills tree rather than depending on local hook execution.
+
+## Manual requirements and evidence boundary
+
+CI cannot complete these portal operations:
+
+- verify the developer or business identity;
+- confirm **Apps Management: Write** access;
+- upload or confirm a production logo;
+- select countries/regions and complete attestations;
+- run reviewer cases in the final host environment;
+- submit, receive approval, or publish to the public directory.
+
+The repository therefore claims a reproducible, review-ready submission artifact only. It does not claim public-directory approval, managed-workspace import success, or live host execution until those external artifacts are preserved.
+
+## Repository checks
+
+Run:
+
+```bash
+npm run test:plugin:openai
+npm run test:plugin:submission
+```
+
+The checks verify listing/manifest alignment, official-source metadata, public support/privacy/terms URLs, exactly five positive and three negative review cases, deterministic bundle generation, and exact file parity between the generated bundle manifest and the packaged skill tree.

package/submission/openai/listing.json

@@ -0,0 +1,31 @@
+{
+  "format": "harness-openai-plugin-submission-source-v1",
+  "note": "Repository source of truth for manually completing the OpenAI plugin submission portal; this is not an OpenAI import schema.",
+  "official_docs": [
+    "https://developers.openai.com/plugins/deploy/submission",
+    "https://developers.openai.com/plugins/build/plugins"
+  ],
+  "submission_type": "skills_only",
+  "plugin_name": "Harness Everything",
+  "short_description": "Route, verify, and recover coding work",
+  "long_description": "Harness Everything adds reusable software-engineering workflows for task routing, test-driven development, verification, security review, documentation, failure recovery, and related coding-agent work. It keeps a small set of cross-cutting invariants while allowing the agent to choose, combine, reorder, or skip domain skills as appropriate.",
+  "category": "Developer Tools",
+  "website_url": "https://github.com/dyphn1/Harness-everything",
+  "support_url": "https://github.com/dyphn1/Harness-everything/blob/main/SUPPORT.md",
+  "privacy_policy_url": "https://github.com/dyphn1/Harness-everything/blob/main/PRIVACY.md",
+  "terms_url": "https://github.com/dyphn1/Harness-everything/blob/main/TERMS.md",
+  "starter_prompts": [
+    "Route this software task with Harness and use only the skills that help.",
+    "Review this change and verify it with objective evidence before claiming completion."
+  ],
+  "release_notes": "Initial public skills-only submission of Harness Everything. Includes 26 reusable engineering skills plus invariant-first routing and verification guidance. No remote MCP server, hosted backend, authentication, or external account is required by the plugin package.",
+  "availability": {
+    "selection": "manual_in_portal",
+    "guidance": "Select only countries or regions where the publisher, support process, privacy notice, and terms are ready for users."
+  },
+  "manual_requirements": {
+    "developer_identity": "Select the verified individual or business identity in the OpenAI Platform organization used for submission.",
+    "logo": "Upload a production-ready logo in the submission portal.",
+    "apps_management_write_access": "The submitter must have Apps Management write access in the publishing organization."
+  }
+}