harness-everything 0.2.1 → 0.3.6

package/docs/reflection.md

@@ -1,34 +1,48 @@
-# Harness Reflection, Memory & Self-Evolution
-
-AI models are notorious for forgetting lessons learned in previous coding sessions. When a bug is solved, if the developer opens a new terminal or launches a new AI session, the agent may encounter the same environment quirks or framework gotchas and make the exact same mistakes again.
-
-Harness solves this through its **Self-Evolution and Persistent Memory system**.
-
----
-
-## The Transaction Log (WAL) & Session Handoff
-
-Harness maintains a lightweight transaction log (analogous to a Write-Ahead Log in databases) via `hooks/scripts/state-persist.js`.
-
-*   **Continuous Capture:** Every successful tool use or milestone is recorded in the session transaction log.
-*   **Handoff File:** A session handoff checkpoint is saved in the workspace.
-*   **Session Start Recovery:** Upon starting a new session, the `bootstrap.js` hook reads the handoff file. It automatically "wakens" the agent, restoring the previous task state, completed milestones, and pending actions. This completely eliminates "session restart amnesia."
-
----
-
-## Long-term Memory & Workspace Rules
-
-When a complex issue—such as an environment-specific bug, a unique framework quirk, or a custom build command requirement—is successfully resolved:
-
-1.  **Deep Reflection:** Harness triggers the `self-evolve` skill, directing the model to reflect on the root cause and extract the exact pattern.
-2.  **Rule Generation:** The model abstracts the learning into a concise rule (avoiding generic prompt prose).
-3.  **RULES.md Integration:** The rule is appended or merged into local workspace rules (usually under a `RULES.md` or a customized folder).
-4.  **Self-Regression Validation:** Before any new rule is persisted, Harness executes the `self-regression.js` test suite. This ensures that the generated rules do not conflict with existing core rules and that all script syntax is 100% correct, preventing behavior decay.
-
----
-
-## The Benefits of Self-Evolution
-
-*   **Immunization:** The workspace is permanently "immunized" against recurring bugs.
-*   **Team Alignment:** Because rules are checked into Git, every developer (and every AI agent they launch) immediately benefits from the shared, updated knowledge base.
-*   **Token Efficiency:** Rather than the user repeatedly reminding the AI about custom project structures or conventions, the agent reads them natively from the immunized RULES file.
+# Harness Reflection, Memory & Self-Evolution
+
+AI models are notorious for forgetting lessons learned in previous coding sessions. When a bug is solved, if the developer opens a new terminal or launches a new AI session, the agent may encounter the same environment quirks or framework gotchas and make the exact same mistakes again.
+
+Harness solves this through its **Self-Evolution and Persistent Memory system**.
+
+---
+
+## The Transaction Log (WAL) & Session Handoff
+
+Harness maintains a lightweight transaction log (analogous to a Write-Ahead Log in databases) via `hooks/scripts/state-persist.js`.
+
+*   **Continuous Capture:** Every successful tool use or milestone is recorded in the session transaction log.
+*   **Handoff File:** A session handoff checkpoint is saved in the workspace.
+*   **Session Start Recovery:** Upon starting a new session, the `bootstrap.js` hook reads the handoff file. It automatically "wakens" the agent, restoring the previous task state, completed milestones, and pending actions. This completely eliminates "session restart amnesia."
+
+---
+
+## Long-term Memory & Workspace Rules
+
+When a complex issue—such as an environment-specific bug, a unique framework quirk, or a custom build command requirement—is successfully resolved:
+
+1.  **Deep Reflection:** Harness triggers the `self-evolve` skill, directing the model to reflect on the root cause and extract the exact pattern.
+2.  **Rule Generation:** The model abstracts the learning into a concise rule (avoiding generic prompt prose).
+3.  **Memory vs. Dynamic Skill Judgment:** The model decides whether the insight is a simple, localized tip or a reusable, complex procedure — packaging every lesson as a skill would bloat context for no benefit, so this is a deliberate gate, not the default.
+    *   **Simple Rule (default path):** Appended to local workspace rules (`RULES.md`, or a customized folder) via `persist-memory.js`.
+    *   **Dynamic Skill (exception path):** Written as a standalone `SKILL.md` under `.claude/harness-everything/skills/generated/<name>/` per `skill-creator`'s Dynamic Skill Generation Contract (with `status: draft` lifecycle metadata and required `triggers:` keywords), then registered via `register-dynamic-skill.js` into `manifest.json`. From there, `tier-router.js` scans and auto-surfaces it in future sessions whenever its triggers match the prompt — closing the loop from "learned once" to "discovered automatically," not just recorded.
+4.  **Self-Regression Validation:** Before any new rule or dynamic skill is persisted, Harness executes the `self-regression.js` test suite. This ensures that the generated rules/skills do not conflict with existing core rules and that all script syntax is 100% correct, preventing behavior decay.
+
+---
+
+## External Skills: A Deliberately *Different* Loop for Third-Party Content
+
+`self-evolve`'s `generated[]` skills are self-authored — this workspace's own agent wrote them, `skill-creator` quality-gates them, and their lifecycle (`draft` → `active` → `deprecated`) is entirely Harness's to track. `find-skills` closes an adjacent gap — a capability that's neither in the static registry nor something this workspace has already learned, but that a third-party skill on `skills.sh` covers — and it was tempting to mirror `generated[]`'s exact mechanism for it (cache the skill's path + triggers in `manifest.json`, let `tier-router.js` auto-surface it the same way).
+
+That mirroring was tried and deliberately reverted: `generated[]` is safe to cache because Harness owns the whole lifecycle behind it. A skill fetched via `npx skills add` has none of that guarantee — its author can update the `SKILL.md` at any time, or the user can run `npx skills update`/`remove` independently of Harness, and a cached copy of its `description`/`triggers` from install time would silently drift out of sync with no mechanism to notice. Caching it anyway would launder unaudited, unowned third-party content into the same trust tier as `generated[]`'s self-authored, quality-gated content — a category error, not just a missing feature.
+
+So `find-skills` queries live instead of caching bookkeeping, and — a step further — defaults to never installing anything in the first place. `npx skills` already ships an ephemeral mode built for exactly this (`npx skills use <source>`): it fetches a skill and prints its content as a ready-to-follow prompt without installing it anywhere. `find-skills/scripts/use-skill.js` wraps that call behind a content-addressed cache under the OS temp directory (`os.tmpdir()/harness-find-skills-cache/<sha1-of-source>.md`, default 6h freshness) — a real fetch on first lookup, then zero network cost on repeat lookups of the same source, and nothing written to the repo, to a platform's native skill directory, or to `manifest.json`. When the OS eventually reclaims that temp directory, that's the entire "cleanup" story - no explicit expiry logic to maintain, because there was never any permanent state to expire.
+
+Permanent install (`npx skills add`) still exists, but only as an explicit exception the user opts into when they know they'll reuse a skill across many future sessions - never the default `find-skills` reaches for. Checking `npx skills list` (§0.3 in `find-skills/SKILL.md`) only ever finds something from that rare path; the default ephemeral path never shows up there, by design, because it never installs. This is the actual answer to "won't skills pile up and bloat context over time?" - most borrowed knowledge is solved-once, applied-once, and leaves nothing behind. Only the deliberate minority a human chooses to keep ever accumulates, and that minority is small enough to stay legible without any Harness-side tracking.
+
+---
+
+## The Benefits of Self-Evolution
+
+*   **Immunization:** The workspace is permanently "immunized" against recurring bugs.
+*   **Team Alignment:** Because rules are checked into Git, every developer (and every AI agent they launch) immediately benefits from the shared, updated knowledge base.
+*   **Token Efficiency:** Rather than the user repeatedly reminding the AI about custom project structures or conventions, the agent reads them natively from the immunized RULES file.

package/docs/routing.md

@@ -1,45 +1,58 @@
-# Harness Routing & Task Triage
-
-To prevent both over-engineering and under-planning, Harness classifies every user request into one of three execution tiers. This ensures that trivial tasks are executed instantly without unnecessary bloat, while complex architectural refactoring is strictly designed and verified.
-
----
-
-## The Three-Tier Routing System
-
-Upon receiving a request, the `tier-router.js` script analyzes the scope, affected files, and instruction patterns to route the task:
-
-```
-                  [ User Request ]
-                         |
-                         v
-                [ Triage Analysis ]
-               /         |         \
-              /          |          \
-     (Trivial)       (Standard)      (Macro)
-     /                   |                  \
-    v                    v                   v
-[ Tier 1 ]           [ Tier 2 ]          [ Tier 3 ]
-Direct Edit       Test-Driven (TDD)     Multi-Agent Flow
-(No plans)        (Red-Green-Refactor)   (Fable-Mode)
-```
-
-### Tier 1: Trivial Tasks (Direct Execution)
-*   **Trigger criteria:** Single-file edits, typos, simple styling fixes, readme corrections, or clean-up tasks.
-*   **Behavior:** Harness bypasses plans, code-reviews, and sub-agents. The model is directed to make the edit directly and complete the task, consuming minimal tokens.
-*   **Verification:** Basic syntax checks or a quick compile verify success.
-
-### Tier 2: Standard Tasks (Test-Driven Development)
-*   **Trigger criteria:** Normal feature requests, bug fixes, algorithm additions, API endpoint creations, or any task affecting multiple files with logical risk.
-*   **Behavior:** Harness enforces the `todo-driven-workflow` base execution loop (initialize a 3-7 item verifiable checklist before editing, one item in-progress at a time) and the `tdd` skill. The model is strictly guided through the Red-Green-Refactor loop:
-    1.  **Red:** Write an automated test first that reproduces the issue or covers the feature, then run it to verify failure.
-    2.  **Green:** Implement the minimal amount of code to make the test pass.
-    3.  **Refactor:** Polish the code, clean up duplicates, and ensure coverage targets (minimum 80%) are met.
-*   **Verification:** Strict execution of the test suite.
-
-### Tier 3: Macro Tasks (Multi-Agent/Fable-Mode)
-*   **Trigger criteria:** High-level design changes, migration of modules, large-scale refactoring, or major capability additions affecting multiple domains.
-*   **Behavior:** Harness automatically spawns the multi-agent orchestration engine (`fable-mode` and `create-agent-launcher`), with the macro plan materialized as the `todo-driven-workflow` checklist.
-    1.  **Planning:** An agent constructs a rigorous, phase-based implementation plan.
-    2.  **Delegation:** Specialized sub-agents (e.g., `security-reviewer`, `database-reviewer`, `code-reviewer`) are created to handle specific work streams or audits.
-    3.  **Handoffs:** Session handoffs are saved periodically to ensure that if a session limits out or restarts, the progress is seamlessly restored.
-*   **Verification:** Multi-layer unit, integration, and E2E verification loops.
+# Harness Routing & Task Triage
+
+To prevent both over-engineering and under-planning, Harness classifies every user request into one of three execution tiers. This ensures that trivial tasks are executed instantly without unnecessary bloat, while complex architectural refactoring is strictly designed and verified.
+
+This is a default, not an order: `tier-router.js`'s own output tells the agent to follow its own read of the task when it clearly disagrees, and an explicit instruction from the Human Partner always wins. The keyword heuristic exists to catch the common case cheaply and deterministically, not to override judgment when it's wrong - the tier-router hook and the `zoom-out` step-back-and-retry loop are the safety net for when a hard call is actually needed, not the routing keywords themselves.
+
+## Tuning the keyword heuristic
+
+`tier-router.js` reads its keyword/guide tables from the sibling `harness-everything/scripts/routing-keywords.json` instead of hardcoding them. Edit that file directly to retune which prompts route to Tier 2/3 or surface a given knowledge guide - no code changes, no re-install, and it travels with `tier-router.js` automatically on every install/update since it lives in the same skill folder. Each `guideGroups` entry matches via a plain-substring `keywords` array (case-insensitive OR) or a `regex` source string; if the file is missing or hand-edited into invalid JSON, the router fails open (empty tables, Tier 1 default) instead of breaking the hook.
+
+## Non-Software Task Bypass
+
+If the user's prompt is non-software engineering (general Q&A, text translation, web searching, or conversational chat), Harness OS routing is **bypassed completely**. The model replies directly and naturally without emitting a Routing Checkpoint block.
+
+---
+
+## The Three-Tier Routing System
+
+Upon receiving a software engineering request, the `tier-router.js` script analyzes the scope, affected files, and instruction patterns to route the task:
+
+```
+                  [ User Request ]
+                         |
+                 [ Software Task? ]
+                /                  \
+             (No)                  (Yes)
+             /                        \
+    [ Bypass Router ]          [ Triage Analysis ]
+    Direct Response           /        |         \
+                             /         |          \
+                    (Trivial)      (Standard)     (Macro)
+                    /                  |                 \
+                   v                   v                  v
+               [ Tier 1 ]          [ Tier 2 ]         [ Tier 3 ]
+               Direct Edit      Test-Driven (TDD)    Multi-Agent Flow
+               (No plans)      (Red-Green-Refactor)   (Fable-Mode)
+```
+
+### Tier 1: Trivial Tasks (Direct Execution)
+*   **Trigger criteria:** Single-file edits, typos, simple styling fixes, readme corrections, or clean-up tasks.
+*   **Behavior:** Harness bypasses plans, code-reviews, and sub-agents. The model makes the edit directly, emitting a brief single-line routing checkpoint or direct response.
+*   **Verification:** Basic syntax checks or a quick compile verify success.
+
+### Tier 2: Standard Tasks (Test-Driven Development)
+*   **Trigger criteria:** Normal feature requests, bug fixes, algorithm additions, API endpoint creations, SRP object splitting, or security reviews affecting multiple files.
+*   **Behavior:** Harness enforces the `todo-driven-workflow` base execution loop (prioritizing native IDE tools like `manage_todo_list`, with `tasks/todo.md` as the portable fallback) and the `tdd` skill. The model is strictly guided through the Red-Green-Refactor loop:
+    1.  **Red:** Write an automated test first that reproduces the issue or covers the feature, then run it to verify failure.
+    2.  **Green:** Implement the minimal amount of code to make the test pass.
+    3.  **Refactor:** Polish the code, clean up duplicates, and ensure coverage targets are met.
+*   **Verification:** Strict execution of the test suite and pre-delivery checks (`verification-loop`).
+
+### Tier 3: Macro Tasks (Multi-Agent/Fable-Mode)
+*   **Trigger criteria:** High-level design changes, migration of modules, large-scale refactoring, or major capability additions affecting multiple domains.
+*   **Behavior:** Harness routes the macro task to `fable-mode` and `multi-agent-workspace`, with the macro plan materialized via `todo-driven-workflow`. Hosts that support sub-agents may then delegate bounded work streams.
+    1.  **Planning & Alignment:** Perform grilling (`grill-me` / `grill-with-docs`), present an outline preview via `to-spec`, and publish formal specs or vertical-slice tickets (`to-tickets`).
+    2.  **Delegation:** Specialized sub-agents (or inline persona role-switches) handle specific work streams or audits.
+    3.  **Handoffs & Memory:** Milestone progress is saved to `todo-driven-workflow` state, and lessons learned are recorded via `self-evolve` (enforcing the 60-line cleanliness and lazy-loading rule).
+*   **Verification:** Multi-layer unit, integration, and E2E verification loops (`verification-loop`).

package/docs/troubleshooting.md

@@ -0,0 +1,284 @@
+# Harness OS Troubleshooting Guide
+
+This guide helps you resolve common issues with Harness OS installation and usage.
+
+## Installation Issues
+
+### Permission Denied Errors
+
+**Symptom:** `EACCES: permission denied` during installation
+
+**Solution:**
+```bash
+# Option 1: Install without sudo (recommended)
+npx github:dyphn1/Harness-everything install
+
+# Option 2: If you need global installation
+npx github:dyphn1/Harness-everything install --global
+
+# Option 3: Fix npm permissions (if using npm)
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+export PATH=~/.npm-global/bin:$PATH
+```
+
+### Node.js Version Issues
+
+**Symptom:** `SyntaxError` or unsupported engine errors
+
+**Solution:**
+```bash
+# Check your Node.js version
+node --version
+
+# Harness requires Node.js 18 or higher
+# Update using nvm (recommended):
+nvm install 18
+nvm use 18
+
+# Or download from https://nodejs.org/
+```
+
+### Network Issues
+
+**Symptom:** `npm ERR! network` or timeout errors
+
+**Solution:**
+```bash
+# Check your internet connection
+npm ping
+
+# Try with different registry
+npm config set registry https://registry.npmjs.org/
+
+# Clear npm cache
+npm cache clean --force
+
+# Use yarn instead
+yarn install
+```
+
+## Hook Issues
+
+### Hooks Not Firing (Claude Code)
+
+**Symptom:** Harness rules not being enforced
+
+**Solution:**
+1. Verify hooks are installed:
+   ```bash
+   cat .claude/settings.json | grep -A 10 "hooks"
+   ```
+
+2. Check hook file permissions:
+   ```bash
+   ls -la hooks/scripts/*.js
+   ```
+
+3. Restart Claude Code session
+
+### Hook Execution Errors
+
+**Symptom:** `Error: Cannot find module` or similar
+
+**Solution:**
+```bash
+# Verify Node.js is in PATH
+which node
+
+# Check if hooks directory exists
+ls -la hooks/scripts/
+
+# Reinstall Harness
+npx github:dyphn1/Harness-everything uninstall
+npx github:dyphn1/Harness-everything install
+```
+
+### Circuit Breaker Tripping Too Often
+
+**Symptom:** `RULE OF 3 CIRCUIT BREAKER TRIGGERED!` frequently
+
+**Solution:**
+1. This is normal behavior - Harness is protecting you from infinite loops
+2. Follow the zoom-out instructions in the error message
+3. If it's a false positive, check the error signature:
+   ```bash
+   cat .claude/harness-everything/state/sessions/default/rule-of-3-state.json
+   ```
+
+4. Reset if needed:
+   ```bash
+   npm run harness:reset
+   ```
+
+## Platform-Specific Issues
+
+### Cursor Not Showing Rules
+
+**Symptom:** `.cursorrules` file not created
+
+**Solution:**
+1. Verify file exists:
+   ```bash
+   cat .cursorrules | head -20
+   ```
+
+2. If missing, reinstall with Cursor flag:
+   ```bash
+   npx github:dyphn1/Harness-everything install --cursor
+   ```
+
+3. Restart Cursor
+
+### Copilot Not Following Rules
+
+**Symptom:** GitHub Copilot ignoring Harness guidance
+
+**Solution:**
+1. Check file exists:
+   ```bash
+   cat .github/copilot-instructions.md | head -20
+   ```
+
+2. Ensure Copilot is using the instructions file
+3. Restart VS Code/GitHub Copilot
+
+### Codex/AGENTS.md Issues
+
+**Symptom:** Codex not recognizing Harness
+
+**Solution:**
+1. Check AGENTS.md exists:
+   ```bash
+   cat AGENTS.md | head -20
+   ```
+
+2. Reinstall with Codex flag:
+   ```bash
+   npx github:dyphn1/Harness-everything install --codex
+   ```
+
+## Performance Issues
+
+### Slow Hook Execution
+
+**Symptom:** Terminal commands feel slower
+
+**Solution:**
+1. Check hook execution time:
+   ```bash
+   time node hooks/scripts/rule-of-3.js < /dev/null
+   ```
+
+2. If >200ms, check for:
+   - Large state files
+   - Network calls in hooks
+   - Complex file operations
+
+3. Reset state:
+   ```bash
+   rm -rf .claude/harness-everything/state/sessions/
+   ```
+
+### High Memory Usage
+
+**Symptom:** Node.js processes consuming too much memory
+
+**Solution:**
+1. Check for memory leaks:
+   ```bash
+   # Monitor Node.js processes
+   ps aux | grep node
+   ```
+
+2. Restart session if needed
+3. Report issue if persistent
+
+## Debugging
+
+### Enable Verbose Logging
+
+```bash
+# Set debug environment variable
+export HARNESS_DEBUG=1
+
+# Run with verbose output
+node hooks/scripts/rule-of-3.js < payload.json
+```
+
+### Check State Files
+
+```bash
+# View current state
+cat .claude/harness-everything/state/sessions/default/rule-of-3-state.json
+cat .claude/harness-everything/state/sessions/default/handoff-state.json
+
+# Reset all state
+rm -rf .claude/harness-everything/state/sessions/
+npm run harness:reset
+```
+
+### Manual Hook Testing
+
+```bash
+# Test rule-of-3 hook
+echo '{"tool_name":"Bash","tool_input":{"command":"test"}}' | node hooks/scripts/rule-of-3.js
+
+# Test state-persist hook
+echo '{"tool_name":"Edit","tool_input":{"file_path":"test.js"}}' | node hooks/scripts/state-persist.js
+```
+
+## Getting Help
+
+### Collect Diagnostic Information
+
+```bash
+# Generate diagnostic report
+echo "=== System Info ===" > harness-diagnostic.txt
+node --version >> harness-diagnostic.txt
+npm --version >> harness-diagnostic.txt
+echo "" >> harness-diagnostic.txt
+
+echo "=== Harness Version ===" >> harness-diagnostic.txt
+cat package.json | grep version >> harness-diagnostic.txt
+echo "" >> harness-diagnostic.txt
+
+echo "=== Installed Platforms ===" >> harness-diagnostic.txt
+ls -la .claude/ .cursorrules .github/copilot-instructions.md AGENTS.md .continue/rules/ .hermes.md 2>/dev/null >> harness-diagnostic.txt
+echo "" >> harness-diagnostic.txt
+
+echo "=== Hook Status ===" >> harness-diagnostic.txt
+cat .claude/settings.json | grep -A 20 "hooks" >> harness-diagnostic.txt 2>/dev/null
+echo "" >> harness-diagnostic.txt
+
+echo "=== Recent Errors ===" >> harness-diagnostic.txt
+# Add any recent error logs here
+```
+
+### Contact Support
+
+1. **GitHub Issues:** https://github.com/dyphn1/Harness-everything/issues
+2. **Include:** Diagnostic report, error messages, steps to reproduce
+3. **Platform:** Specify which AI tool you're using (Claude Code, Cursor, etc.)
+
+## Common Error Messages
+
+### "Cannot find module './lib/harness-state'"
+- **Cause:** Missing dependencies
+- **Solution:** Run `npm install` or reinstall Harness
+
+### "Routing-keywords.json missing/invalid"
+- **Cause:** Configuration file corrupted
+- **Solution:** Will fail open to Tier 1 - reinstall to restore
+
+### "Session state not found"
+- **Cause:** First run or state cleared
+- **Solution:** Normal - state will be created on first use
+
+### "Zoom-out report not found"
+- **Cause:** Circuit breaker tripped but no report written
+- **Solution:** Follow the zoom-out instructions in the error message
+
+---
+
+*This troubleshooting guide covers the most common issues. For other problems, please open a GitHub issue with diagnostic information.*

package/docs/workflows/environment-detection.md

@@ -1,63 +1,63 @@
-# Workflow: Environment Detection
-
-> Active shell, operating system, and toolset environment detection, providing safety guardrails and running preflight syntactic verification.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `environment-detection` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([Before Command Execution]) --> DetectOS["Detect Operating System: Windows, macOS, Linux"]
-  DetectOS --> DetectShell["Detect Shell: Bash, PowerShell, CMD, Zsh"]
-  DetectShell --> ScanCapabilities["Scan available runtimes: Node, Python, .NET, Docker"]
-  ScanCapabilities --> CheckSyntax["Inspect command for active shell compatibilities"]
-  CheckSyntax --> SyntaxGuard{Syntax safe for shell?}
-  SyntaxGuard -->|No| RewriteCmd["Transform/Rewrite command syntax to match active shell"]
-  SyntaxGuard -->|Yes| Execute["Run command in persistent terminal"]
-  RewriteCmd --> Execute
-  Execute --> CaptureOutput["Interleave output and exit code correctly"]
-  CaptureOutput --> End([Secure terminal result returned])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `environment-detection` 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.
-
-```mermaid
-graph LR
-  Router["harness-everything / tier-router.js"] -->|Pre-flight command execution| Env["environment-detection / SKILL.md"]
-  Env -->|Guards runner execution commands in| TDD["tdd / SKILL.md"]
-  Env -->|Guards script installations in| InstallOS["install-cognitive-os / SKILL.md"]
-  Env -->|Guards PR quality checks in| VerLoop["verification-loop / SKILL.md"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `environment-detection` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Agent wants to run: 'rm -rf build && mkdir build' on Windows Powershell"] --> Trigger["Environment detection pre-flight check"]
-  Trigger --> Detect["Identifies OS: Windows, Shell: PowerShell"]
-  Detect --> AnalyzeSyntax["Identifies that 'rm -rf' will fail or behave unexpectedly in PowerShell"]
-  AnalyzeSyntax --> Rewrite["Rewrites command to PowerShell equivalent or executes using native node commands"]
-  Rewrite --> Run["Executes safely with exit code 0"]
-  Run --> Done([Syntax error and execution crash avoided])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `environment-detection` 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: Environment Detection
+
+> Active shell, operating system, and toolset environment detection, providing safety guardrails and running preflight syntactic verification.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `environment-detection` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Session Start / Discover Phase]) --> CheckNode{Node.js Executable?}
+  CheckNode -->|Yes| RunPreflight["Run scripts/preflight.js"]
+  CheckNode -->|No / Fails| Heuristic["Inspect <environment_info> & Probe Shell via echo/env"]
+  
+  RunPreflight --> ParseOutput["Parse OS, Shell, Path Separators & CLI Runtimes"]
+  Heuristic --> ParseOutput
+  
+  ParseOutput --> SelfHeal["Run self-heal.js if Node available"]
+  SelfHeal --> AlignSyntax["Adopt Path Slash (/ vs \\) & Env Var Syntax ($VAR vs %VAR%)"]
+  AlignSyntax --> End([Environment Context Established])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `environment-detection` 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.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Pre-flight command execution| Env["environment-detection / SKILL.md"]
+  Env -->|Guards runner execution commands in| TDD["tdd / SKILL.md"]
+  Env -->|Guards script installations in| InstallOS["install-cognitive-os / SKILL.md"]
+  Env -->|Guards PR quality checks in| VerLoop["verification-loop / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `environment-detection` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Agent wants to run: 'rm -rf build && mkdir build' on Windows Powershell"] --> Trigger["Environment detection pre-flight check"]
+  Trigger --> Detect["Identifies OS: Windows, Shell: PowerShell"]
+  Detect --> AnalyzeSyntax["Identifies that 'rm -rf' will fail or behave unexpectedly in PowerShell"]
+  AnalyzeSyntax --> Rewrite["Rewrites command to PowerShell equivalent or executes using native node commands"]
+  Rewrite --> Run["Executes safely with exit code 0"]
+  Run --> Done([Syntax error and execution crash avoided])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `environment-detection` 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.