harness-everything 0.2.0

package/self-evolve/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: self-evolve
+description: Extracts root causes from resolved difficult problems and persists them as new error boundaries in memory.
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+---
+
+# Self Evolve (Self Evolution & Memory Extraction)
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Task completion after a major struggle, or post-zoom-out recovery. Input: The root cause of the previous failure. |
+| **Expected Output** | Terminal execution of the persistence script. |
+| **State Mutations** | Updates workspace memory/rules files (e.g., `RULES.md` or `.claude/harness-state/memories.json`). |
+| **Enforcement Gate** | You MUST run `node <this-skill-dir>/scripts/self-regression.js`. You MUST run `node <this-skill-dir>/scripts/persist-memory.js "<rule>"`. |
+
+This skill is responsible for the long-term learning and error prevention of the system.
+It ensures that the entire Harness ecosystem becomes smarter and avoids repeating mistakes after solving difficult problems every time.
+
+## 1. Triggers
+- **Post-Circuit Breaker**: When `zoom-out` was triggered, and the difficult problem was ultimately solved — via the reflection report's fresh diagnosis or with the human's hints.
+- **Major Breakthrough**: Completed an extremely complex Tier 3 task, and discovered some previously unknown framework limitations or architectural pitfalls during the process.
+- **Human Instruction**: The user explicitly requests "remember this lesson" or "add this to memory".
+
+## 2. Execution Process (The Evolution Loop)
+
+### Step 1: Deep Reflection & Root Cause Extraction
+- **Reflection is Core**: Reflection is the true focus of the memory system. Mere recording cannot improve accuracy; you must continuously reflect to self-evolve.
+- Analyze the problem just solved, discarding specific variable names or specific line numbers of code.
+- Extract the **high-level, universally applicable root cause**.
+- *Incorrect Extraction*: "Do not use `forEach` to call the database on line 45 of `auth.js`."
+- *Correct Extraction*: "When handling ORM relational writes in this project, you MUST use Transactions and batch writes. Sending Queries individually in a loop is PROHIBITED, otherwise it will cause connection pool exhaustion."
+
+### Step 2: Define Error Boundaries
+- Transform the extracted root cause into a defensive rule for `install-cognitive-os` to reference in the future.
+- Explicitly define which domain this new rule applies to (e.g., Database, React Hooks, specific API integration).
+- **Anti-Focus Loss**: This rule must be able to directly guide future Agents to notice this landmine during the `[Discover]` phase, instead of finding out only after writing it wrong.
+
+### Step 3: Memory Persistence & Dynamic Skill Generation
+- **MANDATORY**: Before persisting or committing any dynamically generated skills or memories, you MUST run the self-regression suite to ensure no behavioral regressions or syntax errors were introduced. Both scripts below live in the `scripts/` directory **inside this skill's own directory** — resolve paths from wherever this SKILL.md was loaded (do not guess a hard-coded location):
+  ```bash
+  node "<this-skill-dir>/scripts/self-regression.js"
+  ```
+- **MANDATORY**: You MUST execute the persistence script instead of manually editing files or calling write tools:
+  ```bash
+  node "<this-skill-dir>/scripts/persist-memory.js" "<Your extracted root cause and defensive rule here>"
+  ```
+- **Dynamic Skill Generation (Session Packaging)**: Through self-review, package the successful session summary (hard boundary) into a new, dynamic skill. **You MUST load `skill-creator/SKILL.md` and follow its §4 Dynamic Skill Generation Contract** before writing the file — it defines the required location (`.claude/harness-everything/skills/generated/<name>/SKILL.md`, not the repo root), the required lifecycle frontmatter (`metadata.type: dynamic`, `status: draft`), and the Quality Checklist gate this file must pass since it skips human PR review by design. Do not hand-write a `SKILL.md` inline here; that checklist is the only review a dynamically generated skill gets. These dynamically generated skills have a lifecycle — draft → active → deprecated, or promoted to a static skill once proven general — distinct from the system's foundational static skills.
+- **Note**: Only record "Key Insights", keeping the memory document short and punchy. Avoid stuffing it with lengthy conversation logs or useless narratives.
+
+## 3. Purpose
+Through `self-evolve`, we transform "invalid trial-and-error", which might otherwise waste Tokens, into a valuable "moat" for the system. Even if the underlying model doesn't become inherently smarter, equipped with these memories, the system will automatically avoid known traps and break through its original reasoning ceiling.

package/self-evolve/scripts/persist-memory.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+const args = process.argv.slice(2);
+const memoryText = args[0];
+
+if (!memoryText) {
+  console.error("Usage: node persist-memory.js \"<insight to remember>\"");
+  process.exit(1);
+}
+
+function getWorkspaceRoot() {
+  let dir = path.resolve(process.cwd());
+  while (dir !== path.parse(dir).root) {
+    if (fs.existsSync(path.join(dir, '.git'))) return dir;
+    dir = path.dirname(dir);
+  }
+  return process.cwd();
+}
+
+// Ensure the memory is written to the project root's /memories/repo/ directory
+const currentDir = getWorkspaceRoot();
+const memoryDir = path.join(currentDir, 'memories', 'repo');
+const rulesFile = path.join(memoryDir, 'RULES.md');
+
+try {
+  if (!fs.existsSync(memoryDir)) {
+    fs.mkdirSync(memoryDir, { recursive: true });
+  }
+
+  const timestamp = new Date().toISOString().split('T')[0];
+  const formattedMemory = `\n## [${timestamp}] Self-Evolution Insight\n- ${memoryText}\n`;
+
+  fs.appendFileSync(rulesFile, formattedMemory, 'utf8');
+  console.log(`[Success] Memory persisted to ${rulesFile}`);
+} catch (err) {
+  console.error(`[Error] Failed to write memory: ${err.message}`);
+  process.exit(1);
+}

package/self-evolve/scripts/self-regression.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/**
+ * Harness Self-Regression Test Suite
+ * Compiles and validates all Javascript files and runs routing verification framework
+ * before dynamic evolution / dynamic skills are officially persisted.
+ */
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const projectRoot = path.resolve(__dirname, '..', '..');
+
+console.log("=================================================");
+console.log("     Harness OS - Self-Regression Test Suite     ");
+console.log("=================================================");
+
+let hasErrors = false;
+
+// 1. Walk and syntax check all Javascript files
+console.log("\n[Phase 1] Static Syntax Check...");
+const foldersToScan = ['harness-everything', 'hooks', 'environment-detection', 'self-evolve', 'eval-framework', 'eval-harness', 'scripts', 'bin'];
+const jsFiles = [];
+
+function walkDir(dir) {
+  if (!fs.existsSync(dir)) return;
+  const list = fs.readdirSync(dir);
+  list.forEach(file => {
+    const filePath = path.join(dir, file);
+    const stat = fs.statSync(filePath);
+    if (stat && stat.isDirectory()) {
+      walkDir(filePath);
+    } else if (filePath.endsWith('.js')) {
+      jsFiles.push(filePath);
+    }
+  });
+}
+
+foldersToScan.forEach(folder => {
+  walkDir(path.join(projectRoot, folder));
+});
+
+jsFiles.forEach(file => {
+  const relativePath = path.relative(projectRoot, file);
+  // node --check checks syntax without execution
+  const check = spawnSync('node', ['--check', file]);
+  if (check.status !== 0) {
+    console.error(`  ❌ Syntax Error in ${relativePath}`);
+    console.error(check.stderr.toString().trim());
+    hasErrors = true;
+  } else {
+    console.log(`  ✅ ${relativePath.padEnd(50)} [Valid Syntax]`);
+  }
+});
+
+// 2. Run Tier Verification Framework
+console.log("\n[Phase 2] Routing Verification Check...");
+const runnerPath = path.join(projectRoot, 'eval-framework', 'runner.js');
+if (fs.existsSync(runnerPath)) {
+  const runnerCheck = spawnSync('node', [runnerPath], { stdio: 'inherit' });
+  if (runnerCheck.status !== 0) {
+    console.error("\n  ❌ Routing verification framework failed!");
+    hasErrors = true;
+  } else {
+    console.log("\n  ✅ Routing verification framework 100% Passed!");
+  }
+} else {
+  console.warn("  ⚠️  eval-framework/runner.js not found. Skipping Phase 2.");
+}
+
+// 3. Run Behavioral Test Suite (E2E state-machine transitions, not just syntax)
+console.log("\n[Phase 3] Behavioral Test Suite...");
+const behavioralTestPath = path.join(projectRoot, 'eval-framework', 'behavioral-test.js');
+if (fs.existsSync(behavioralTestPath)) {
+  const behavioralCheck = spawnSync('node', [behavioralTestPath], { stdio: 'inherit', cwd: projectRoot });
+  if (behavioralCheck.status !== 0) {
+    console.error("\n  ❌ Behavioral test suite failed!");
+    hasErrors = true;
+  } else {
+    console.log("\n  ✅ Behavioral test suite 100% Passed!");
+  }
+} else {
+  console.warn("  ⚠️  eval-framework/behavioral-test.js not found. Skipping Phase 3.");
+}
+
+// 4. Run Mechanism Test Suite (VERIFICATION.md §2 hook contract, automated)
+console.log("\n[Phase 4] Mechanism Test Suite (Claude Code hooks)...");
+const mechanismTestPath = path.join(projectRoot, 'eval-framework', 'mechanism-test.js');
+if (fs.existsSync(mechanismTestPath)) {
+  const mechanismCheck = spawnSync('node', [mechanismTestPath], { stdio: 'inherit', cwd: projectRoot });
+  if (mechanismCheck.status !== 0) {
+    console.error("\n  ❌ Mechanism test suite failed!");
+    hasErrors = true;
+  } else {
+    console.log("\n  ✅ Mechanism test suite 100% Passed!");
+  }
+} else {
+  console.warn("  ⚠️  eval-framework/mechanism-test.js not found. Skipping Phase 4.");
+}
+
+// 5. Final verdict
+console.log("\n=================================================");
+if (hasErrors) {
+  console.error(" ❌ REGRESSION DETECTED! Self-evolution rejected.");
+  console.error(" Please fix the errors listed above before persisting changes.");
+  console.log("=================================================");
+  process.exit(1);
+} else {
+  console.log(" 🎉 SUCCESS! All self-regression checks passed 100%.");
+  console.log(" Dynamic skills and memories are safe to be committed.");
+  console.log("=================================================");
+  process.exit(0);
+}

package/skill-creator/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: skill-creator
+description: Author, audit, and refactor SKILL.md files against a single quality bar — the Skill Contract format plus predictability/pruning/progressive-disclosure principles from external skill-writing research. Use when creating a new skill from scratch, reviewing or refactoring an existing SKILL.md, checking whether two skills overlap, or when self-evolve needs to package a session's learning into a durable dynamic skill.
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+---
+
+# Skill Creator (Skill Authoring, Audit & Evolution Workflow)
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Creating a new skill from scratch; auditing/refactoring an existing `SKILL.md`; `self-evolve`'s Step 3 packaging a session's insight into a durable dynamic skill. Input: a task description, an existing SKILL.md, or a root-cause insight from self-evolve. |
+| **Expected Output** | A `SKILL.md` that passes the Quality Checklist (§3) — static skills at `<skill-name>/SKILL.md` with a `harness-everything` registry row, dynamic skills at `.harness/skills/generated/<skill-name>/SKILL.md` with lifecycle metadata (§4). |
+| **State Mutations** | Writes/edits `<skill>/SKILL.md` (+ optional `guides/`/`references/`); for new static skills, adds one row to `harness-everything/SKILL.md` §5 and, if keyword-routable, one line to `tier-router.js`'s `recommendedGuides`. |
+| **Enforcement Gate** | A new or edited `SKILL.md` **MUST NOT** be registered or persisted until every item in the Quality Checklist (§3) is checked off — for dynamic skills this is self-evolve's actual persistence gate, not optional polish. |
+
+`skill-style/SKILL.md` defines *the shape* a SKILL.md must take (the Skill Contract table, the imperative tone) but not *how to get there well* — how to size a skill, when to push detail into a reference file, how to tell a real enforcement gate from a restated default, or where a rule belongs before it starts drifting across three files. Those questions come from two sources studied for this skill: [`writing-great-skills`](../mattpocock-skills/skills/productivity/writing-great-skills/SKILL.md) and Anthropic's own `skill-creator`. Neither is followed blindly — §1 says where Harness's own conventions override them, and why.
+
+## 1. Two philosophies, reconciled
+
+Harness gets predictability from a **physical** mechanism: the Skill Contract table's Enforcement Gate row, backed by a script that exits non-zero. External skill-writing research gets predictability from a **cognitive** mechanism: minimal context load, leading words, explaining *why* instead of just forbidding. Both are real and both are validated — see the 2026-07-22 skill quality audit for the evidence — and they don't actually conflict where it counts:
+
+- **Keep** the Skill Contract table and `MUST`/`PROHIBITED` for anything with a real Enforcement Gate: an irreversible action, a script that can exit non-zero, a state mutation another skill depends on. That's a hard guardrail; state it as one.
+- **Don't** reach for `MUST`/`PROHIBITED` as the default tone for style preferences with no gate behind them — "don't write long paragraphs" doesn't need to be a `MUST NOT`; say what good output looks like instead. Every imperative not backed by an actual gate is a candidate for rewriting positively.
+- **Always** apply the parts with no philosophical conflict at all: don't duplicate a meaning across files, don't restate what the model already does by default, push detail behind a pointer once a skill grows past what every reader needs inline, and reuse this repo's own leading words (`Tier 1/2/3`, `circuit breaker`/`zoom out`, `Rule of 3`, `Red/Green/Refactor`) instead of coining new ones for the same concept.
+
+Full glossary and worked examples from both sources: `references/quality-principles.md`.
+
+## 2. Authoring workflow
+
+### Step 1 — Capture intent (before writing a word of SKILL.md)
+Answer these, pulling from the conversation first if it already has the answers:
+1. What should this skill make the agent do that it wouldn't do by default?
+2. What's the *one* canonical sentence describing when it fires? This sentence becomes the frontmatter `description` — and nothing else. Don't let the registry row or `tier-router.js` invent independent wording later: the audit report §1.2 found the same skill carrying two different one-line descriptions inside `tier-router.js` itself, because nobody treated the frontmatter line as the source of truth.
+3. Which Tier does it belong to, or is it an always-on discipline / meta skill outside the tier system?
+4. Does an existing skill already own this ground? Grep `harness-everything/SKILL.md` §5 first — a near-duplicate skill is worse than a slightly-too-broad existing one.
+
+### Step 2 — Draft
+Write the Skill Contract table first — it forces you to know the Enforcement Gate before you write a paragraph. Then the body, sized by the information hierarchy:
+- **Steps** (ordered, each ending on a checkable completion criterion) for anything the agent *does*, in order.
+- **Flat reference** (a rule table, a decision list) for anything the agent *consults*. A skill can be all steps, all reference, or both — a flat rule table is a legitimate shape, not a smell.
+- Past ~100-150 lines of body, or once a piece of detail is only needed on some branches rather than every invocation, push it to `guides/` or `references/` with a pointer sentence that says *when* to open it, not a bare link. Past 300 lines in a reference file, add a table of contents. `git-commit`, `tdd`, `repo-docs`, and `improve-codebase-architecture` already do this well — copy their shape.
+
+### Step 3 — Test against real prompts
+Don't ship on vibes alone. Write 2-3 prompts a real user would actually type — not "test the skill," the kind of message that should trigger it. Using this repo's own `create-agent-launcher`, spawn one subagent *with* the draft skill loaded and one *without* (baseline), same prompt, and compare. This is the same with/without comparison Anthropic's `skill-creator` runs through a Python eval-viewer — Harness doesn't need a second toolchain for it; `create-agent-launcher` already does resource-isolated subagent spawning. Read both transcripts, not just final outputs — repeated dead-end exploration in the with-skill transcript is a sign the skill under-specifies something, not that the model is weak.
+
+Full adapted testing loop — when to bother, what to look for in transcripts, how a router-based system checks trigger phrasing without a native autonomous picker: `references/testing-workflow.md`.
+
+### Step 4 — Prune, then register
+Run the Quality Checklist (§3). Then:
+- **Static skill**: add one row to `harness-everything/SKILL.md` §5 (Layer + "Activated when," quoting the frontmatter description rather than rewriting it), and if the trigger is keyword-detectable, one line to the matching keyword block in `harness-everything/scripts/tier-router.js`.
+- **Dynamic skill** (from `self-evolve`): follow §4 instead — different location, different lifecycle, same checklist.
+
+## 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.
+- [ ] **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).
+
+## 4. Dynamic Skill Generation Contract (for `self-evolve`)
+
+`self-evolve`'s Step 3 packages a hard-won session insight into a new, standalone skill. That new skill **MUST** go through this skill, not be hand-written inline:
+
+- **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
+  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
+  ```
+- **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.
+
+## 5. Related skills
+
+- `skill-style/SKILL.md` — the terse Skill Contract format spec this skill builds on. Read it if you just need the table shape, not the full workflow.
+- `create-agent-launcher/SKILL.md` — used in §2 Step 3 to spawn with/without-skill test subagents.
+- `self-evolve/SKILL.md` — the caller for §4; it loads this skill rather than duplicating the Dynamic Skill Generation Contract inline.

package/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/skill-creator/references/testing-workflow.md

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

package/skill-style/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: skill-style
+description: Guidelines for writing and refactoring skills in the Harness ecosystem.
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+---
+
+# Skill Style (Harness Ecosystem Skill Development Guidelines)
+
+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.
+
+## 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
+
+| 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.

package/skill-style/STYLE.md

@@ -0,0 +1,37 @@
+# SKILL Document Writing Guidelines
+
+> Target: Markdown files read and executed as Prompts during SKILL execution (excludes Template files).
+
+## [Language & Syntax]
+1. All content MUST be in English (All English).
+2. MUST exclusively use task-based syntax (Imperative verbs, numbered lists).
+3. Vague tone is strictly forbidden. MUST use uppercase `MUST` or `MUST NOT` to define behaviors. Words like `should` or `may` are forbidden.
+4. The length of each rule MUST NOT exceed 150 characters.
+
+## [Skill Architecture: OS vs Domain]
+5. **OS Skills (Process Control)**: e.g., `install-cognitive-os`, `harness-everything`. These dictate *how* to work. They MUST be strictly linear and MUST NOT exceed 60 lines per file.
+6. **Domain Skills (Expertise)**: e.g., `api-design`, `security-review`. These provide *what* to write. They are EXEMPT from the 60-line and linearity limits. They are encouraged to be comprehensive, containing rich anti-patterns, code examples, and deep domain guardrails.
+
+## [Flow & Linearity (Applies to OS Skills)]
+7. The SKILL entry point (SKILL.md) MUST be executed only once.
+8. The flow from OS SKILL.md to the end MUST be a flattened straight line. Infinite loops or branching trees are forbidden.
+9. All OS files MUST form a logical closed loop. If split, the current file MUST end with a unique pointer to maintain linearity.
+
+## [Cognitive Loop & Execution]
+9. Steps MUST be written sequentially. Every SKILL file MUST explicitly include this declaration:
+   ```markdown
+   ## Core Principles
+   - MUST operate using the cognitive loop: Think > Try > Summarize > Record.
+   - [Think] MUST build a holistic mental router map before starting. Use elimination to discard impossible approaches. Perform forward prediction to simplify actions.
+   - [Try] MUST verify current environment boundaries BEFORE taking action. Execute steps sequentially and NEVER combine commands, ensuring errors remain isolated and traceable.
+   - [Summarize] MUST verify actual outcomes against initial intent; hallucinating success is forbidden. If an attempt fails, diagnose, zoom out, and backtrack.
+   - [Record] MUST explicitly state variables and context to carry over.
+   - [Reflect & Re-Think] MUST actively feed the `[Record]` (especially past failures and state changes) back into the next `[Think]` cycle. Use historical context to refine forward predictions and strictly avoid repeating previously diagnosed errors.
+   
+   ## Cognitive Foundation (Why we do this)
+   - Recording is not the end; it is the absolute prerequisite for the next Think cycle.
+   - Trying validates the predicted steps.
+   - Summarizing confirms if the outcome aligns with the initial intent.
+   - The loop is continuous. Converging the chain of thought is the absolute priority; divergent thinking causes attention loss. This cycle (Think > Try > Summarize > Record > Re-Think) drives self-adaptation and evolution.
+   - Treat these rules as strict guardrails. Autonomous optimization within these boundaries is expected.
+   ```

package/tdd/SKILL.md

@@ -0,0 +1,53 @@
+---
+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
+---
+
+# Test-Driven Development (TDD) Mode
+
+## 📋 Skill Contract
+
+| 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

package/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?