harness-everything 0.2.1 → 0.2.2

package/self-evolve/SKILL.md

@@ -1,54 +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.
+---
+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/skill-creator/SKILL.md

@@ -1,91 +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.
+---
+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/testing-workflow.md

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

@@ -1,48 +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.
+---
+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/tdd/SKILL.md

@@ -1,53 +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
+---
+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