harness-everything 0.2.2 → 0.3.6

package/docs/workflows/self-evolve.md

@@ -1,59 +1,42 @@
 # Workflow: Self-Evolve
 
-> Analyzes execution logs and session memories to extract underlying root causes, defining new error boundaries and compressing them into cognitive guardrails.
+> The host agent supplies relevant session evidence and a generalized root-cause analysis. `self-evolve` classifies, validates, and persists the lesson; it does not collect host transcripts.
 
----
+Load `self-evolve/references/memory-resolution.md` on demand when the persistence decision, fallback path, lazy-loading rule, or dynamic-skill registration details are needed.
 
-## 1. Skill Behavior Workflow
+## 1. Responsibility boundary
 
-This section visualizes how the `self-evolve` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+The host agent may inspect the current session and any history explicitly exposed by the host. It selects the evidence and states the reusable root cause. `self-evolve` MUST NOT scan global host transcript stores or persist raw transcripts.
 
-```mermaid
-graph TD
-  Start([Task Completed / Error Loop Triggered]) --> ReadSessionLogs["Read active debugging logs & session history"]
-  ReadSessionLogs --> IdentifyRootCauses["Isolate and extract system failures or bottlenecks"]
-  IdentifyRootCauses --> SynthesizeGuardrails["Formulate actionable high-level cognitive guardrails"]
-  SynthesizeGuardrails --> CompressMemories["Compress repetitive events into compact markdown files in /memories/"]
-  CompressMemories --> UpdateUserMemory["Commit lessons learned to user memory space"]
-  UpdateUserMemory --> End([Agent cognitive defense expanded for future sessions])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `self-evolve` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
+## 2. Persistence flow
 
 ```mermaid
-graph LR
-  SessionEnd["Task Completed / Session Closed"] --> Evolve["self-evolve / SKILL.md"]
-  Evolve -->|Reads from| HistoryLog["VS Code Debug logs & memory directories"]
-  Evolve -->|Writes permanent updates to| UserMemory["/memories/ / user-memory files"]
-  Evolve -->|Informs future task triage in| Router["harness-everything / tier-router.js"]
+graph TD
+  Start([Agent has resolved a recurring problem]) --> Evidence["Agent selects allowed evidence and states root cause"]
+  Evidence --> Memory{Existing workspace memory?}
+  Memory -->|Yes| Lines{Target under 60 lines?}
+  Memory -->|No| Route["Choose workspace memory fallback"]
+  Lines -->|Yes| Append["Append concise rule"]
+  Lines -->|No| Modular["Create topic memory and add lazy-load pointer"]
+  Route --> Append
+  Append --> Validate["Run self-evolve self-regression and quality gates"]
+  Modular --> Validate
+  Evidence -->|Reusable multi-step pattern| Dynamic["Load skill-creator, create draft skill, register generated[]"]
+  Dynamic --> Validate
+  Validate --> Done([Lesson persisted])
 ```
 
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `self-evolve` skill, illustrating standard success paths, error handling, or recovery loops.
+## 3. Triggering and routing
 
-```mermaid
-graph TD
-  Start["Session ends after solving a recurring, messy Windows path-slashes bug"] --> Trigger["self-evolve skill runs automatically"]
-  Trigger --> Analyze["Reads last 5 execution logs"]
-  Analyze --> DetectPattern["Finds 3 consecutive terminal command failures caused by path backslashes in PowerShell"]
-  DetectPattern --> Formulate["Formulate new guardrail: 'When on Windows, convert backslashes to forward slashes for cross-shell command lines'"]
-  Formulate --> Write["Write bullet point to /memories/debugging.md"]
-  Write --> Done([Memory recorded: future sessions will automatically avoid Windows path errors])
-```
+The agent invokes `self-evolve/SKILL.md` after a resolved struggle, zoom-out recovery, or explicit request. It passes the selected evidence and root cause to `persist-memory.js`, or routes a reusable pattern through `skill-creator` and `register-dynamic-skill.js`. The router later matches registered `generated[]` metadata; this is not an automatic transcript scan.
 
----
+## 4. Example
 
-## 4. Verification Check
+After resolving a recurring Windows path error, the agent summarizes the cause, checks existing memory, and chooses either a concise rule or a draft dynamic skill. It runs the relevant quality/self-regression gate before persistence and records only the generalized lesson.
 
-To ensure that the `self-evolve` skill is operating in strict compliance with Harness OS design laws, verify the following:
+## 5. Verification checklist
 
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+- [ ] Evidence came from the host context the agent is authorized to inspect.
+- [ ] No raw transcript, secret, or one-off detail was persisted.
+- [ ] Rule/dynamic-skill classification and deduplication passed.
+- [ ] Self-regression passed before the memory or manifest changed.

package/docs/workflows/skill-creator.md

@@ -1,75 +1,80 @@
-# Workflow: Skill Creator
-
-> Authors, audits, and evolves SKILL.md files against a single quality bar — the Skill Contract format plus predictability/pruning/progressive-disclosure principles from external skill-writing research — and is the required gate for skills `self-evolve` generates dynamically.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `skill-creator` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([New skill request / existing SKILL.md to audit / self-evolve dynamic-generation call]) --> Intent["Capture intent: what it does, the one canonical description sentence, which Tier, does an existing skill already own this ground"]
-  Intent --> Draft["Draft: Skill Contract table first, then body sized by information hierarchy (steps vs flat reference vs guides/references)"]
-  Draft --> Test["Test 2-3 realistic prompts via create-agent-launcher: with-skill subagent vs baseline subagent"]
-  Test --> Checklist{"Quality Checklist (§3): SSOT, no duplication >5 lines, every MUST has a real gate, no no-ops, info hierarchy, leading words reused, checkable completion criteria, human-facing description"}
-  Checklist -->|Fails| Prune["Prune and rewrite the failing item"]
-  Prune --> Checklist
-  Checklist -->|Passes| Route{Static or dynamic?}
-  Route -->|Static| Register["Register: harness-everything §5 row + tier-router.js keyword line"]
-  Route -->|Dynamic, from self-evolve| DynamicContract["§4 Dynamic Skill Generation Contract: write to .claude/harness-everything/skills/generated/<name>/, metadata.type=dynamic, status=draft"]
-  Register --> End([Skill live in the repo, single source of truth for its own description])
-  DynamicContract --> End
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how `skill-creator` is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
-```mermaid
-graph LR
-  Router["harness-everything / tier-router.js"] -->|Keyword: skill / skill.md / new skill / write a skill| Creator["skill-creator / SKILL.md"]
-  Creator -->|Table shape spec| SkillStyle["skill-style / SKILL.md"]
-  Creator -->|With/without test subagents| Launcher["create-agent-launcher / SKILL.md"]
-  Creator -->|Registers new static skills into| Registry["harness-everything / SKILL.md §5"]
-  Evolve["self-evolve / SKILL.md §4"] -->|MUST load before packaging a session insight| Creator
-  Creator -->|Writes dynamic skills to| Generated[".claude/harness-everything/skills/generated/"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `skill-creator` skill, illustrating standard success paths, error handling, or recovery loops — one for a human-directed static skill, one for `self-evolve`'s dynamic path.
-
-```mermaid
-graph TD
-  Start1["Developer: 'I want a skill for deploying to AWS'"] --> Intent1["skill-creator §2 Step 1: capture intent, one canonical description sentence"]
-  Intent1 --> Draft1["Draft Skill Contract table + steps, push detail to deploy-aws/guides/"]
-  Draft1 --> Test1["Spawn with/without subagents via create-agent-launcher on 2-3 realistic prompts"]
-  Test1 --> Check1{Quality Checklist passes?}
-  Check1 -->|No| Fix1["Fix flagged item, re-test"]
-  Fix1 --> Check1
-  Check1 -->|Yes| Reg1["Add row to harness-everything §5 + one line to tier-router.js"]
-  Reg1 --> Done1([deploy-aws/SKILL.md live as a static, reviewed skill])
-
-  Start2["zoom-out recovery ends: root cause found for a recurring connection-pool exhaustion bug"] --> Trigger2["self-evolve §3 Step 3: Dynamic Skill Generation"]
-  Trigger2 --> Load2["self-evolve MUST load skill-creator §4 before writing anything"]
-  Load2 --> Gate2{Quality Checklist §3 passes?}
-  Gate2 -->|No| Reject2["Do not persist — this checklist is the only review a dynamic skill gets"]
-  Gate2 -->|Yes| Write2["Write .claude/harness-everything/skills/generated/orm-transaction-batching/SKILL.md, metadata.type=dynamic, status=draft"]
-  Write2 --> Done2([Dynamic skill available next session, lifecycle tracked separately from static skills])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `skill-creator` skill is operating in strict compliance with Harness OS design laws, verify the following:
-
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+# Workflow: Skill Creator
+
+> Authors, audits, and evolves SKILL.md files against a single quality bar — the Skill Contract format plus predictability/pruning/progressive-disclosure principles from external skill-writing research — and is the required gate for skills `self-evolve` generates dynamically.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `skill-creator` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([New skill request / existing SKILL.md to audit / self-evolve dynamic-generation call after LLM selection]) --> Intent["Capture intent: what it does, the one canonical description sentence, which Tier, does an existing skill already own this ground"]
+  Intent --> Draft["Draft: Skill Contract table first, then body sized by information hierarchy (steps vs flat reference vs guides/references)"]
+  Draft --> Test["Test 2-3 realistic prompts via multi-agent-workspace: with-skill subagent vs baseline subagent"]
+  Test --> Checklist{"Quality Checklist (§3): SSOT, no duplication >5 lines, every MUST has a real gate, no no-ops, info hierarchy, leading words reused, checkable completion criteria, human-facing description"}
+  Checklist -->|Fails| Prune["Prune and rewrite the failing item"]
+  Prune --> Checklist
+  Checklist -->|Passes| Route{Static or dynamic?}
+  Route -->|Static| Register["Register: harness-everything §5 row + tier-router.js keyword line"]
+  Route -->|Dynamic, from self-evolve| DynamicContract["§4 Dynamic Skill Generation Contract: write to .claude/harness-everything/skills/generated/<name>/ & register-dynamic-skill.js to manifest.json, metadata.type=dynamic, status=draft"]
+  Register --> End([Skill live in the repo, single source of truth for its own description])
+  DynamicContract --> End
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how `skill-creator` is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Keyword: skill / skill.md / new skill / write a skill| Creator["skill-creator / SKILL.md"]
+  Creator -->|Table shape spec| SkillStyle["skill-style / SKILL.md"]
+  Creator -->|With/without test subagents| Launcher["multi-agent-workspace / SKILL.md"]
+  Creator -->|Registers new static skills into| Registry["harness-everything / SKILL.md §5"]
+  Evolve["self-evolve / SKILL.md §4"] -->|LLM decides to promote insight| Creator
+  Creator -->|Writes dynamic skills to| Generated[".claude/harness-everything/skills/generated/"]
+  Generated -->|Registered in| Manifest["manifest.json 'generated' registry"]
+  Manifest -->|Matched & auto-loaded by| Router
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `skill-creator` skill, illustrating standard success paths, error handling, or recovery loops — one for a human-directed static skill, one for `self-evolve`'s dynamic path.
+
+```mermaid
+graph TD
+  Start1["Developer: 'I want a skill for deploying to AWS'"] --> Intent1["skill-creator §2 Step 1: capture intent, one canonical description sentence"]
+  Intent1 --> Draft1["Draft Skill Contract table + steps, push detail to deploy-aws/guides/"]
+  Draft1 --> Test1["Spawn with/without subagents via multi-agent-workspace on 2-3 realistic prompts"]
+  Test1 --> Check1{Quality Checklist passes?}
+  Check1 -->|No| Fix1["Fix flagged item, re-test"]
+  Fix1 --> Check1
+  Check1 -->|Yes| Reg1["Add row to harness-everything §5 + one line to tier-router.js"]
+  Reg1 --> Done1([deploy-aws/SKILL.md live as a static, reviewed skill])
+
+  Start2["zoom-out recovery ends: root cause found for a recurring connection-pool exhaustion bug"] --> Decide2{"LLM: Does it warrant a standalone complex skill?"}
+  Decide2 -->|No: Simple Tip| Save2["persist-memory.js writes simple rule to RULES.md"]
+  Decide2 -->|Yes: Complex Skill| Trigger2["self-evolve §3 Step 3: Promote to Dynamic Skill"]
+  Trigger2 --> Load2["self-evolve MUST load skill-creator §4 before writing anything"]
+  Load2 --> Gate2{Quality Checklist §3 passes?}
+  Gate2 -->|No| Reject2["Do not persist — this checklist is the only review a dynamic skill gets"]
+  Gate2 -->|Yes| Write2["Write .claude/harness-everything/skills/generated/orm-transaction-batching/SKILL.md & run register-dynamic-skill.js"]
+  Write2 --> Done2([Dynamic skill available next session via manifest registration and tier-router.js scan])
+  Save2 --> Done3([Simple memory rule available in RULES.md])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `skill-creator` skill is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
+- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
+- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.

package/docs/workflows/skill-style.md

@@ -1,64 +1,64 @@
-# Workflow: Skill Style
-
-> Guidelines and style rules for authoring, refactoring, and maintaining SKILL.md files to enforce clean frontmatter and logical boundaries.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `skill-style` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([Authoring / Editing a SKILL.md]) --> ParseFrontmatter["Parse and validate YAML Frontmatter: name, description"]
-  ParseFrontmatter --> ValidateBoundary["Check for explicit physical boundaries & state checkpoints"]
-  ValidateBoundary --> VerifyCognitiveLoop["Verify integration with Cognitive Loop laws"]
-  VerifyCognitiveLoop --> CheckFormatting["Ensure clean markdown layout and bullet-style rules"]
-  CheckFormatting --> FormatApproved{Complies with STYLE.md?}
-  FormatApproved -->|No| FixSkillFile["Refactor and clean file formatting"]
-  FormatApproved -->|Yes| SaveSkillFile["Commit clean, validated SKILL.md"]
-  FixSkillFile --> SaveSkillFile
-  SaveSkillFile --> End([Skill document aligned with professional guidelines])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how `skill-style` is reached — as of the `skill-creator` split, it is no longer the first stop. `tier-router.js`'s `/\bskill\b|skill\.md|new skill|write a skill/` match now recommends `skill-creator` first (the full authoring/audit/testing workflow) and `skill-style` second (the terse Skill Contract table shape it builds on) — see `harness-everything/scripts/tier-router.js`.
-
-```mermaid
-graph LR
-  Router["harness-everything / tier-router.js"] -->|Keyword: skill / skill.md / new skill| Creator["skill-creator / SKILL.md"]
-  Creator -->|Builds on the table shape defined in| SkillStyle["skill-style / SKILL.md"]
-  SkillStyle -->|Audits format correctness of| OtherSkills["Any SKILL.md in the workspace"]
-  SkillStyle -->|Pre-PR validation gate integration| VerLoop["verification-loop / SKILL.md"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-§1 already walks the linear audit steps for a single file. This section instead shows the case that motivated splitting `skill-creator` out of this skill in the first place: a developer who needs the *fuller* workflow, not just the table shape.
-
-```mermaid
-graph TD
-  Start["Developer: 'help me write a new skill for deploying to AWS'"] --> Router["tier-router.js recommends skill-creator + skill-style"]
-  Router --> Creator["skill-creator: capture intent, draft, test against real prompts (§2)"]
-  Creator --> StyleCheck["skill-style: does the draft's Skill Contract table match the required shape?"]
-  StyleCheck -->|Missing/malformed table| Fix["Fix table shape per skill-style, re-run skill-creator's Quality Checklist"]
-  StyleCheck -->|Table shape OK| Checklist["skill-creator §3 Quality Checklist: no-op / duplication / negation / progressive-disclosure checks"]
-  Fix --> Checklist
-  Checklist --> Register["Register in harness-everything §5 + tier-router.js (skill-creator §2 Step 4)"]
-  Register --> Done([deploy-aws/SKILL.md committed, consistent with the rest of the repo])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `skill-style` skill is operating in strict compliance with Harness OS design laws, verify the following:
-
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+# Workflow: Skill Style
+
+> Guidelines and style rules for authoring, refactoring, and maintaining SKILL.md files to enforce clean frontmatter and logical boundaries.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `skill-style` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Authoring / Editing a SKILL.md]) --> ParseFrontmatter["Parse and validate YAML Frontmatter: name, description"]
+  ParseFrontmatter --> ValidateBoundary["Check for explicit physical boundaries & state checkpoints"]
+  ValidateBoundary --> VerifyCognitiveLoop["Verify integration with Cognitive Loop laws"]
+  VerifyCognitiveLoop --> CheckFormatting["Ensure clean markdown layout and bullet-style rules"]
+  CheckFormatting --> FormatApproved{Complies with STYLE.md?}
+  FormatApproved -->|No| FixSkillFile["Refactor and clean file formatting"]
+  FormatApproved -->|Yes| SaveSkillFile["Commit clean, validated SKILL.md"]
+  FixSkillFile --> SaveSkillFile
+  SaveSkillFile --> End([Skill document aligned with professional guidelines])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how `skill-style` is reached — as of the `skill-creator` split, it is no longer the first stop. `tier-router.js`'s `/\bskill\b|skill\.md|new skill|write a skill/` match now recommends `skill-creator` first (the full authoring/audit/testing workflow) and `skill-style` second (the terse Skill Contract table shape it builds on) — see `harness-everything/scripts/tier-router.js`.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Keyword: skill / skill.md / new skill| Creator["skill-creator / SKILL.md"]
+  Creator -->|Builds on the table shape defined in| SkillStyle["skill-style / SKILL.md"]
+  SkillStyle -->|Audits format correctness of| OtherSkills["Any SKILL.md in the workspace"]
+  SkillStyle -->|Pre-PR validation gate integration| VerLoop["verification-loop / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+§1 already walks the linear audit steps for a single file. This section instead shows the case that motivated splitting `skill-creator` out of this skill in the first place: a developer who needs the *fuller* workflow, not just the table shape.
+
+```mermaid
+graph TD
+  Start["Developer: 'help me write a new skill for deploying to AWS'"] --> Router["tier-router.js recommends skill-creator + skill-style"]
+  Router --> Creator["skill-creator: capture intent, draft, test against real prompts (§2)"]
+  Creator --> StyleCheck["skill-style: does the draft's Skill Contract table match the required shape?"]
+  StyleCheck -->|Missing/malformed table| Fix["Fix table shape per skill-style, re-run skill-creator's Quality Checklist"]
+  StyleCheck -->|Table shape OK| Checklist["skill-creator §3 Quality Checklist: no-op / duplication / negation / progressive-disclosure checks"]
+  Fix --> Checklist
+  Checklist --> Register["Register in harness-everything §5 + tier-router.js (skill-creator §2 Step 4)"]
+  Register --> Done([deploy-aws/SKILL.md committed, consistent with the rest of the repo])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `skill-style` skill is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
+- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
+- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.

package/docs/workflows/tdd.md

@@ -1,39 +1,42 @@
-# Workflow: Test-Driven Development (TDD)
-
-> Enforces the classic Red-Green-Refactor development cycle. Crucially, this is NOT a linear process. It is a loop driven by terminal exit codes.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes the script-gated reality of TDD. The AI cannot progress to the next phase until the terminal script explicitly confirms the state.
-
-```mermaid
-graph TD
-  Start([Identify Feature / Bug]) --> DesignInterface["Design interface & contract"]
-  DesignInterface --> WriteTest["Write unit/integration tests first"]
-  
-  WriteTest --> RunRed["Try: Run tests (EXPECT FAILURE)"]
-  RunRed --> VerifyRed{Gate: Exit Code 1?}
-  VerifyRed -->|Exit 0: Fake Test| FixTest["Reflect: Test is broken/fake. Fix it."]
-  FixTest --> RunRed
-  
-  VerifyRed -->|Exit 1: True Red| WriteCode["Write minimal code to pass test"]
-  
-  WriteCode --> RunGreen["Try: Run tests (EXPECT SUCCESS)"]
-  RunGreen --> VerifyGreen{Gate: verify-gate.js}
-  
-  VerifyGreen -->|Exit 1: Still Broken| DebugCode["Reflect: Read logs, fix code"]
-  DebugCode --> RunGreen
-  VerifyGreen -->|Exit 1: 3x Failures| CircuitBreaker["Trigger rule-of-3.js: ZOOM OUT"]
-  CircuitBreaker --> DebugCode
-  
-  VerifyGreen -->|Exit 0: Green| Refactor["Refactor code for readability"]
-  
-  Refactor --> RunVerify["Try: Run tests again"]
-  RunVerify --> VerifyRefactor{Gate: verify-gate.js}
-  VerifyRefactor -->|Exit 1| Revert["Revert refactor / Fix"]
-  Revert --> RunVerify
-  
-  VerifyRefactor -->|Exit 0| End([Feature verified & completed])
-```
+# Workflow: Test-Driven Development (TDD)
+
+> Enforces the classic Red-Green-Refactor development cycle. Crucially, this is NOT a linear process. It is a loop driven by terminal exit codes.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes the script-gated reality of TDD. The AI cannot progress to the next phase until the terminal script explicitly confirms the state.
+
+```mermaid
+graph TD
+  Start([Identify Feature / Bug]) --> DesignInterface["Design interface & contract"]
+  DesignInterface --> WriteTest["Write unit/integration tests first"]
+  
+  WriteTest --> RunRed["Try: Run tests (EXPECT FAILURE)"]
+  RunRed --> AssertRed["Assert: Present terminal logs as evidence (Law 4)"]
+  AssertRed --> VerifyRed{Gate: Exit Code 1?}
+  VerifyRed -->|Exit 0: Fake Test| FixTest["Reflect: Test is broken/fake. Fix it."]
+  FixTest --> RunRed
+  
+  VerifyRed -->|Exit 1: True Red| WriteCode["Write minimal code to pass test"]
+  
+  WriteCode --> RunGreen["Try: Run tests (EXPECT SUCCESS)"]
+  RunGreen --> AssertGreen["Assert: Present terminal logs as evidence (Law 4)"]
+  AssertGreen --> VerifyGreen{Gate: verify-gate.js}
+  
+  VerifyGreen -->|Exit 1: Still Broken| DebugCode["Reflect: Read logs, fix code"]
+  DebugCode --> RunGreen
+  VerifyGreen -->|Exit 1: 3x Failures| CircuitBreaker["Trigger rule-of-3.js: ZOOM OUT"]
+  CircuitBreaker --> DebugCode
+  
+  VerifyGreen -->|Exit 0: Green| Refactor["Refactor: Optimize & audit Code-Doc Alignment (Law 6)"]
+  
+  Refactor --> RunVerify["Try: Run tests again"]
+  RunVerify --> AssertRefactor["Assert: Present terminal logs as evidence (Law 4)"]
+  AssertRefactor --> VerifyRefactor{Gate: verify-gate.js}
+  VerifyRefactor -->|Exit 1| Revert["Revert refactor / Fix"]
+  Revert --> RunVerify
+  
+  VerifyRefactor -->|Exit 0| End([Feature verified & completed])
+```

package/docs/workflows/to-spec.md

@@ -0,0 +1,83 @@
+# Workflow: To Spec
+
+> Synthesizes an already-discussed conversation into whichever written artifact actually fits — feature spec, CLI/API reference, schema doc, or dev doc — and publishes it per this repo's own `projectDocs` entry inside `harness-everything/manifest.json`. Advisory in both Tier 2 and Tier 3 toward other skills; its own Step 0 framework check is a mechanized script gate, not advisory.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `to-spec` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start(["/to-spec invoked"]) --> OutlinePreview["Phase 1: Present 10-20 Line Outline Preview & Path to User"]
+  OutlinePreview --> UserApproved{"User Approves Outline?"}
+  UserApproved -->|No / Adjustments Needed| AdjustOutline["Refine Template Shape & Outline"] --> OutlinePreview
+  
+  UserApproved -->|Yes| CheckScript["Phase 2: node to-spec/scripts/check-project-docs.js check"]
+  CheckScript --> ExitCode{"Exit code?"}
+  ExitCode -->|0: projectDocs complete or inferred| ResolveConfig["Use Configured / Inferred docLocation"]
+  ExitCode -->|1 / Script Missing| InspectWorkspace{"Inspect Workspace Folders"}
+  
+  InspectWorkspace -->|Folder Found| ResolveWorkspace["Use docs/specs/, docs/reference/, docs/adr/, .scratch/"]
+  InspectWorkspace -->|No Folder| ResolvePlatform["Fallback to .github/harness-everything/specs/"]
+  
+  ResolveConfig --> WriteDoc["Generate & Publish Full Document"]
+  ResolveWorkspace --> WriteDoc
+  ResolvePlatform --> WriteDoc
+  
+  WriteDoc --> End(["Spec Document Published Successfully"])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how `to-spec` is reached through user requests and how it chains with companion skills in the Harness OS ecosystem.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Keyword: spec / PRD / cli reference / schema doc / dev doc| Suggest["Suggests to-spec/SKILL.md - advisory only, still explicit-invoke"]
+  Suggest --> TS["to-spec / SKILL.md"]
+  TS -->|Step 0, mandatory| Gate["check-project-docs.js check - scans repo-local manifest.json homes only"]
+  Gate -->|Exit 1, first run only| Init["check-project-docs.js init writes projectDocs into manifest.json"]
+  Init --> TS
+  Manifest["harness-everything/manifest.json (also owned by scripts/lib/manifest.js + self-evolve's generated registry)"] -.->|same file, different key| Gate
+  GWD["grill-with-docs / SKILL.md"] -->|Settles decisions BEFORE, feeds feature-spec shape| TS
+  GM["grill-me / SKILL.md"] -->|Settles decisions BEFORE| TS
+  TDD["tdd / SKILL.md (Tier 2)"] -.->|Optional pre-implementation doc, never blocks Red/Green/Refactor| TS
+  TS -->|Unresolved fork found mid-synthesis| GWD
+  TS -->|Published doc becomes input for| ToTickets["to-tickets / SKILL.md (planned)"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+```mermaid
+graph TD
+  Start["Tier 2 task: add a new `harness todo export` CLI command"] --> Invoke["/to-spec invoked (optional, offered by router)"]
+  Invoke --> RunCheck["node check-project-docs.js check"]
+  RunCheck --> Exit0["Exit 0 - .claude/harness-everything/manifest.json already has projectDocs from a prior run"]
+  Exit0 --> Gather2["Gathers context: existing native or Markdown checklist conventions"]
+  Gather2 --> PickShape2["Picks cli-reference.md - not feature-spec, no user stories needed"]
+  PickShape2 --> ConfirmFlags["Confirms --format and --since flag names with user"]
+  ConfirmFlags --> Draft["Writes doc from templates/cli-reference.md, adapted headings"]
+  Draft --> ReadDocLoc["projectDocs.docLocation says docs/reference/"]
+  ReadDocLoc --> PublishLocal["docs/reference/todo-export.md - not filed as an issue"]
+  PublishLocal --> Done(["Doc published; TDD proceeds unblocked either way"])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure `to-spec` is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Mechanized Gate, Not Prose**: Step 0 ran `check-project-docs.js check` and honored its exit code — it did not skip straight to inferring the framework from prose memory of past runs.
+- [ ] **Repo-Local, Not Global**: `projectDocs` was read from / written to a workspace-relative platform home only (`.claude/`, `.cursor/`, `.github/`, `.codex/`, `.continue/` under this repo) — never `~/.agents` or the global `~/.claude` manifest, which would leak this repo's tracker into unrelated projects.
+- [ ] **Pointer, Not Payload**: Every `projectDocs` field is a short pointer (≤ 200 chars, enforced by `init`) — elaborate content (a full issue template, a per-context doc map) lives in its own file, referenced by path, not inlined into `manifest.json`.
+- [ ] **No Re-Interview Violation**: Beyond the one-time Step 0 setup, the skill did not ask the user questions that a prior `grill-me`/`grill-with-docs` pass, or the conversation itself, already answered.
+- [ ] **Adaptive Shape Selection**: The template picked (feature-spec / cli-reference / schema-doc / dev-doc) actually matches the artifact being documented — not defaulted to the heaviest shape out of habit.
+- [ ] **Shape-Correct Destination**: A feature-spec was filed as an issue; a CLI-reference/schema-doc/dev-doc was written under `docLocation` instead, unless the user explicitly confirmed it should also be an issue.
+- [ ] **Non-Blocking Toward Other Skills**: The Step 3 confirmation happened before publishing, and to-spec's own execution never delayed or gated `tdd`/`verification-loop` in a Tier 2 flow.