harness-everything 0.2.2 → 0.3.6

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.3.6
 ---
 
-# 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 `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 `skill-creator/SKILL.md`.
+
+Deep dive: `references/style-guide.md`

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

@@ -0,0 +1,36 @@
+# 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 harness-everything/scripts/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.

package/tdd/SKILL.md

@@ -1,8 +1,10 @@
 ---
 name: tdd
-description: Test-Driven Development mode (Red-Green-Refactor) for Standard Tasks (Tier 2).
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
+description: "Drive Standard Tasks (Tier 2) with Test-Driven Development (RED/GREEN/REFACTOR) backed by terminal test evidence. USE FOR: \"implement a feature test-first\", \"fix a bug with a regression test\", \"refactor safely under tests\". DO NOT USE FOR: \"macro planning or scaffolding\", \"docs-only work with no testable logic\"."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.3.6
 ---
 
 # Test-Driven Development (TDD) Mode
@@ -11,43 +13,32 @@ version: 0.2.0
 
 | Component | Specification |
 | :--- | :--- |
-| **Trigger / Input** | Tier 2 Task identification. Input: The specific feature or bug requirement. |
-| **Expected Output** | 1. Failing test terminal output. 2. Implementation code. 3. Passing test terminal output (Exit Code 0). |
-| **State Mutations** | Handled by `todo-cli.js` (tracked via `.claude/harness-state/todo-state.json`). |
-| **Enforcement Gate** | You MUST run the test runner in the terminal. If it does not fail first (RED), you MUST fix the test. If it fails later (GREEN phase), you MUST reflect and fix the code. |
-
-This skill is automatically triggered and loaded by the `harness-everything` router when a task is judged as a **Tier 2 (Standard Task)**.
-It applies to adding a single feature, fixing a specific Bug, or medium-sized changes with clear expected outcomes.
-
-Tier 2 tasks run on the `todo-driven-workflow` base execution loop: initialize the checklist first, and map each Red / Green / Refactor phase (per feature or bug) onto its own verifiable todo item.
-
-## TDD Core Discipline (Red-Green-Refactor)
-
-When this skill is loaded, you MUST suppress the urge to write implementation code directly, and strictly follow these three phases:
-
-### 1. RED (Write a Failing Test)
-- **Action**: Before implementing the requested feature or Bug fix, write the corresponding Unit Test or Integration Test in the test folder.
-- **Validation**: Run the test to **ensure the test fails** (this proves the test actually covers unimplemented functionality, rather than being a fake test).
-- **Note**: If the test passes immediately, it means your test is wrong or the Bug doesn't actually exist. You must fix the test.
-
-### 2. GREEN (Implement Minimal Code to Pass Test)
-- **Action**: Switch to the implementation code and write the "minimum amount of code just enough to pass the test". Do not over-engineer or consider future extensibility at this stage.
-- **Validation**: Run the test to ensure it passes.
-
-### 3. REFACTOR (Refactor and Optimize)
-- **Action**: Under the safety net of passing tests, begin optimizing the code.
-- Checks: Is the naming clear? Is there duplicated code? Can performance be improved? Does it comply with the project's Clean Code standards?
-- **Validation**: After every modification, re-run the tests to ensure refactoring hasn't broken the original functionality.
-
-## Circuit Breaker Defense
-If during a TDD cycle you get stuck in the **GREEN phase**, and 3 consecutive implementation attempts fail to pass the test:
-- **Trigger Condition Met**: You might have hit the reasoning ceiling, or the initial test logic (RED) was written incorrectly.
-- **Mandatory Action**: Stop guessing blindly. Immediately abort the TDD process and call the `zoom-out` skill: fact-check the assumption behind each failing attempt — including whether the RED test itself encodes the wrong expectation — and resume on a fresh diagnosis. Bring the human in only if the reflection surfaces a genuine decision (e.g., the test contradicts the requirement).
-
-## Deep Reference Guides
-For advanced testing, design, and mocking strategies, you MUST refer to:
-- `tdd/guides/mocking.md` — Mocking and stubbing principles
-- `tdd/guides/interface-design.md` — Interface and contract-driven design
-- `tdd/guides/deep-modules.md` — Testing deeply nested/complex modules
-- `tdd/guides/tests.md` — General test architecture and assertions
-- `tdd/guides/refactoring.md` — Refactoring techniques under safety nets
+| **Trigger / Input** | Tier 2 task; feature or bug requirement. |
+| **Expected Output** | Failing test (RED), minimal code (GREEN), refactor. |
+| **State Mutations** | Native host TODO tracker or Markdown checklist (`tasks/todo.md`). |
+| **Enforcement Gate** | `npm test` / `pytest`; >3 GREEN failures force `zoom-out`. |
+
+## TDD Discipline (Red-Green-Refactor)
+
+Every phase obeys the **Evidence Assertion Law**: real test logs prove pass/fail; assumed passes are PROHIBITED.
+
+1. **RED**: write the failing test; confirm it fails (a pass means wrong test or no bug).
+2. **GREEN**: minimal code just enough to pass; re-run until green.
+3. **REFACTOR**: optimize naming/duplication/performance with green tests. **Code-Doc Alignment Law**: code matches contracts, no cheating mocks; audit vs `todo-driven-workflow` checklist; re-run tests each change.
+
+## Circuit Breaker
+3 straight GREEN failures: call `zoom-out`; fact-check each attempt's assumptions (including the RED test's own expectation); resume fresh; human only for genuine decisions.
+
+Guides: `tdd/guides/{mocking,interface-design,deep-modules,tests,refactoring}.md`.
+
+## USE FOR:
+- implement this feature test-first
+- fix this bug with a regression test
+- prove this change works
+- refactor safely under tests
+
+## DO NOT USE FOR:
+- macro planning or scaffolding (use `fable-mode`)
+- prototyping or docs-only work with no testable logic
+
+Deep dive: references/core-discipline.md

package/tdd/guides/deep-modules.md

@@ -1,33 +1,33 @@
-# Deep Modules
-
-From "A Philosophy of Software Design":
-
-**Deep module** = small interface + lots of implementation
-
-```
-┌─────────────────────┐
-│   Small Interface   │  ← Few methods, simple params
-├─────────────────────┤
-│                     │
-│                     │
-│  Deep Implementation│  ← Complex logic hidden
-│                     │
-│                     │
-└─────────────────────┘
-```
-
-**Shallow module** = large interface + little implementation (avoid)
-
-```
-┌─────────────────────────────────┐
-│       Large Interface           │  ← Many methods, complex params
-├─────────────────────────────────┤
-│  Thin Implementation            │  ← Just passes through
-└─────────────────────────────────┘
-```
-
-When designing interfaces, ask:
-
-- Can I reduce the number of methods?
-- Can I simplify the parameters?
-- Can I hide more complexity inside?
+# Deep Modules
+
+From "A Philosophy of Software Design":
+
+**Deep module** = small interface + lots of implementation
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid)
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing interfaces, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?

package/tdd/guides/interface-design.md

@@ -1,31 +1,31 @@
-# Interface Design for Testability
-
-Good interfaces make testing natural:
-
-1. **Accept dependencies, don't create them**
-
-   ```typescript
-   // Testable
-   function processOrder(order, paymentGateway) {}
-
-   // Hard to test
-   function processOrder(order) {
-     const gateway = new StripeGateway();
-   }
-   ```
-
-2. **Return results, don't produce side effects**
-
-   ```typescript
-   // Testable
-   function calculateDiscount(cart): Discount {}
-
-   // Hard to test
-   function applyDiscount(cart): void {
-     cart.total -= discount;
-   }
-   ```
-
-3. **Small surface area**
-   - Fewer methods = fewer tests needed
-   - Fewer params = simpler test setup
+# Interface Design for Testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area**
+   - Fewer methods = fewer tests needed
+   - Fewer params = simpler test setup