harness-everything 0.3.6 → 0.4.1

package/plugins/harness-everything/skills/skill-creator/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: skill-creator
+description: Author, audit, and refactor SKILL.md files against one quality bar — the Skill Contract format. Use when creating a new skill, refactoring a SKILL.md, checking overlap, or packaging an insight as a dynamic skill.
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
+---
+
+# Skill Creator
+
+## USE FOR:
+- Create a skill from scratch
+- Audit/refactor a SKILL.md; check overlap between skills
+- Packaging a session insight as a dynamic skill
+
+## DO NOT USE FOR:
+- Non-skill project docs — use `repo-docs`/`to-spec`
+- Third-party skill installs (find-skills)
+- Code style outside SKILL.md files
+
+## Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | New skill; SKILL.md audit; self-evolve packaging. |
+| **Expected Output** | SKILL.md passing the Quality Checklist. |
+| **State Mutations** | Writes `<skill>/SKILL.md`; updates registry/generated folder. |
+| **Enforcement Gate** | Quality Checklist before registering, incl. USE FOR/DO NOT USE FOR (`<skills-repo-root>/ci/consistency-check.js`). |
+
+## Authoring Workflow
+
+1. Grep the registry for near-duplicates; the when-to-fire sentence becomes the description.
+2. Draft the Contract table first (forces the Enforcement Gate), then `## USE FOR:`/`## DO NOT USE FOR:`, then steps/flat reference; push branch-only detail to references/.
+3. A/B-test via `multi-agent-workspace` subagents; read both transcripts.
+4. Run the Quality Checklist; register (static quotes the description; dynamic below).
+
+## Dynamic Skill Generation Contract
+
+Only generalizable procedures/enforcement contracts qualify; simple constraints go to `<workspace>/memories/repo/RULES.md`.
+
+- Location: `<workspace>/.claude/harness-everything/skills/generated/<kebab-case-name>/SKILL.md`
+- Frontmatter: triggers (3-6 keywords), metadata type/generated/source/status: draft.
+- Gate: Quality Checklist first.
+- Lifecycle: draft → active after firing elsewhere; deprecate, don't delete; promote once proven general.
+
+Deep dive: <this-skill-dir>/references/quality-checklist.md

package/plugins/harness-everything/skills/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/plugins/harness-everything/skills/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/plugins/harness-everything/skills/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/plugins/harness-everything/skills/skill-creator/references/quality-principles.md

@@ -0,0 +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.

package/plugins/harness-everything/skills/skill-creator/references/testing-workflow.md

@@ -0,0 +1,27 @@
+# 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/plugins/harness-everything/skills/skill-style/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: skill-style
+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
+
+Apply the Harness writing standard when creating or refactoring `SKILL.md` files.
+
+## Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **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/plugins/harness-everything/skills/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/plugins/harness-everything/skills/tdd/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: tdd
+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.4.0
+---
+
+# Test-Driven Development
+
+**ROUTER:** Select unit or integration evidence before RED/GREEN/REFACTOR.
+
+## Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Tier 2 feature, bugfix, or behavior-preserving refactor. |
+| **Expected Output** | RED/GREEN logs and a profile-tagged quality report. |
+| **State Mutations** | Tests, implementation, TODO state, and optional report JSON. |
+| **Enforcement Gate** | Project tests plus `npm run tdd:quality -- <evidence.json>`; exit 1 blocks completion. |
+
+## USE FOR:
+- implementing behavior test-first
+- bug regression tests
+- safe refactors under tests
+
+## DO NOT USE FOR:
+- macro planning or scaffolding
+- docs-only or non-testable work
+
+## Route the Behavior
+
+Load `<this-skill-dir>/references/core-discipline.md` and the quality model, then only the unit or integration guide needed. Keep their applicability rules separate.
+
+Deep dive: <this-skill-dir>/references/core-discipline.md
+
+After three failed GREEN attempts, invoke `zoom-out` before another edit.

package/plugins/harness-everything/skills/tdd/fixtures/pass-evidence.json

@@ -0,0 +1,100 @@
+{
+  "schemaVersion": "1.0.0",
+  "requirements": [
+    {
+      "requirementId": "REQ-001",
+      "testProfile": "integration",
+      "source": {
+        "type": "SPEC",
+        "path": "docs/example.md",
+        "section": "Expected behavior",
+        "status": "AUTHORITATIVE"
+      },
+      "sourceConformance": "PASS",
+      "sourceValidity": "VALID",
+      "dimensions": {
+        "positiveParameters": {
+          "applicable": true,
+          "checks": [{ "id": "positive-supported", "class": "supported-partition", "status": "PASS", "evidence": "tests/example.test.js#positive" }]
+        },
+        "negativeParameters": {
+          "applicable": true,
+          "checks": [{ "id": "negative-rejected", "class": "rejected-partition", "status": "PASS", "evidence": "tests/example.test.js#negative" }]
+        },
+        "inputCompleteness": {
+          "applicable": true,
+          "checks": [
+            { "id": "input-required", "class": "required", "status": "PASS", "evidence": "tests/example.test.js#input-required" },
+            { "id": "input-optional", "class": "optional", "status": "PASS", "evidence": "tests/example.test.js#input-optional" },
+            { "id": "input-omitted", "class": "omitted", "status": "PASS", "evidence": "tests/example.test.js#input-omitted" },
+            { "id": "input-empty", "class": "empty", "status": "PASS", "evidence": "tests/example.test.js#input-empty" },
+            { "id": "input-null", "class": "null", "status": "PASS", "evidence": "tests/example.test.js#input-null" },
+            { "id": "input-min", "class": "min", "status": "PASS", "evidence": "tests/example.test.js#input-min" },
+            { "id": "input-max", "class": "max", "status": "PASS", "evidence": "tests/example.test.js#input-max" },
+            { "id": "input-boundary", "class": "boundary", "status": "PASS", "evidence": "tests/example.test.js#input-boundary" }
+          ]
+        },
+        "outputCompleteness": {
+          "applicable": true,
+          "checks": [
+            { "id": "output-value", "class": "value", "status": "PASS", "evidence": "tests/example.test.js#output-value" },
+            { "id": "output-type", "class": "type", "status": "PASS", "evidence": "tests/example.test.js#output-type" },
+            { "id": "output-schema", "class": "schema", "status": "PASS", "evidence": "tests/example.test.js#output-schema" },
+            { "id": "output-required-field", "class": "required-field", "status": "PASS", "evidence": "tests/example.test.js#output-required-field" },
+            { "id": "output-no-extra", "class": "prohibited-extra-field", "status": "PASS", "evidence": "tests/example.test.js#output-no-extra" },
+            { "id": "output-side-effect", "class": "side-effect", "status": "PASS", "evidence": "tests/example.test.js#output-side-effect" }
+          ]
+        },
+        "errorHandling": {
+          "applicable": true,
+          "checks": [
+            { "id": "error-type", "class": "error-type", "status": "PASS", "evidence": "tests/example.test.js#error-type" },
+            { "id": "error-code", "class": "error-code", "status": "PASS", "evidence": "tests/example.test.js#error-code" },
+            { "id": "error-message", "class": "message", "status": "PASS", "evidence": "tests/example.test.js#error-message" },
+            { "id": "error-cleanup", "class": "state-cleanup", "status": "PASS", "evidence": "tests/example.test.js#error-cleanup" },
+            { "id": "error-rollback", "class": "rollback", "status": "PASS", "evidence": "tests/example.test.js#error-rollback" },
+            { "id": "error-no-output", "class": "no-unintended-output", "status": "PASS", "evidence": "tests/example.test.js#error-no-output" }
+          ]
+        },
+        "unexpectedInput": {
+          "applicable": true,
+          "checks": [
+            { "id": "unexpected-malformed", "class": "malformed", "status": "PASS", "evidence": "tests/example.test.js#unexpected-malformed" },
+            { "id": "unexpected-unknown", "class": "unknown", "status": "PASS", "evidence": "tests/example.test.js#unexpected-unknown" },
+            { "id": "unexpected-extra", "class": "extra", "status": "PASS", "evidence": "tests/example.test.js#unexpected-extra" },
+            { "id": "unexpected-unsupported", "class": "unsupported", "status": "PASS", "evidence": "tests/example.test.js#unexpected-unsupported" },
+            { "id": "unexpected-range", "class": "out-of-range", "status": "PASS", "evidence": "tests/example.test.js#unexpected-range" },
+            { "id": "unexpected-duplicate", "class": "duplicate", "status": "PASS", "evidence": "tests/example.test.js#unexpected-duplicate" },
+            { "id": "unexpected-type", "class": "wrong-type", "status": "PASS", "evidence": "tests/example.test.js#unexpected-type" }
+          ]
+        },
+        "determinism": {
+          "applicable": true,
+          "runs": [
+            {
+              "id": "run-1",
+              "input": { "value": 1 },
+              "exitStatus": 0,
+              "errorCategory": null,
+              "output": { "value": 2 },
+              "sideEffects": { "createdFiles": [], "changedFiles": [], "deletedFiles": [], "persistentState": {}, "events": [], "logs": [], "externalCalls": [] }
+            },
+            {
+              "id": "run-2",
+              "input": { "value": 1 },
+              "exitStatus": 0,
+              "errorCategory": null,
+              "output": { "value": 2 },
+              "sideEffects": { "createdFiles": [], "changedFiles": [], "deletedFiles": [], "persistentState": {}, "events": [], "logs": [], "externalCalls": [] }
+            }
+          ],
+          "normalizations": []
+        },
+        "sourceTraceability": { "applicable": true }
+      },
+      "skippedTests": [],
+      "flakyTests": [],
+      "naDeclarations": []
+    }
+  ]
+}

package/plugins/harness-everything/skills/tdd/fixtures/quality-scenarios.json

@@ -0,0 +1,20 @@
+{
+  "baseFixture": "pass-evidence.json",
+  "description": "Focused mutations used to audit every required issue #58 outcome without duplicating the full evidence document.",
+  "scenarios": [
+    { "name": "PASS", "mutation": "none", "expectedResult": "PASS" },
+    { "name": "unit profile", "mutation": "testProfile = unit and determinism is reasoned N/A", "expectedResult": "PASS" },
+    { "name": "integration profile", "mutation": "testProfile = integration and determinism has two matching runs", "expectedResult": "PASS" },
+    { "name": "weighted integration failure", "mutation": "the 0.15 positive dimension scores zero", "expectedScore": 85, "expectedResult": "FAIL" },
+    { "name": "weighted unit failure", "mutation": "unit determinism is N/A and the 0.15 positive dimension scores zero", "expectedScore": 83.33, "expectedResult": "FAIL" },
+    { "name": "NON_CONFORMANT", "mutation": "sourceConformance = NON_CONFORMANT", "expectedResult": "FAIL" },
+    { "name": "SOURCE_DEFECT", "mutation": "sourceValidity = SOURCE_DEFECT and sourceNotes is present", "expectedResult": "PASS" },
+    { "name": "SOURCE_CONFLICT", "mutation": "sourceValidity = SOURCE_CONFLICT with a traced additional source", "expectedResult": "FAIL" },
+    { "name": "malformed input", "mutation": "requirements is not an array", "expectedResult": "FAIL" },
+    { "name": "unexpected input", "mutation": "one unexpectedInput check is FAIL", "expectedResult": "FAIL" },
+    { "name": "error handling", "mutation": "one errorHandling check is SKIPPED", "expectedResult": "FAIL" },
+    { "name": "nondeterministic output", "mutation": "run-2 output differs from run-1", "expectedResult": "FAIL" },
+    { "name": "auditable N/A", "mutation": "a check is N/A with a written reason", "expectedResult": "PASS" },
+    { "name": "skipped test", "mutation": "a required check is SKIPPED", "expectedResult": "FAIL" }
+  ]
+}

package/plugins/harness-everything/skills/tdd/guides/deep-modules.md

@@ -0,0 +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?

package/plugins/harness-everything/skills/tdd/guides/interface-design.md

@@ -0,0 +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

package/plugins/harness-everything/skills/tdd/guides/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/plugins/harness-everything/skills/tdd/guides/refactoring.md

@@ -0,0 +1,10 @@
+# Refactor Candidates
+
+After TDD cycle, look for:
+
+- **Duplication** → Extract function/class
+- **Long methods** → Break into private helpers (keep tests on public interface)
+- **Shallow modules** → Combine or deepen
+- **Feature envy** → Move logic to where data lives
+- **Primitive obsession** → Introduce value objects
+- **Existing code** the new code reveals as problematic