harness-everything 0.2.0 → 0.2.1

package/docs/workflows/verification-loop.md

@@ -1,69 +1,69 @@
-# Workflow: Verification Loop
-
-> Comprehensive pre-PR quality gate executing builds, linting, type-checking, test suites, and security scans before claiming a task complete.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `verification-loop` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([Pre-PR Quality Check Triggered]) --> RunBuild["Execute compilation / project build"]
-  RunBuild --> CheckBuild{Build succeeded?}
-  CheckBuild -->|No| FixBuild["Debug and fix build errors"]
-  CheckBuild -->|Yes| RunTypeCheck["Execute language type-checking compiler"]
-  RunTypeCheck --> CheckTypes{Typecheck green?}
-  CheckTypes -->|No| FixTypes["Correct type-definition errors"]
-  CheckTypes -->|Yes| RunLint["Execute code linter checks"]
-  RunLint --> CheckLint{Lint clean?}
-  CheckLint -->|No| FixLint["Correct code-style and syntax errors"]
-  CheckLint -->|Yes| RunTests["Execute complete automated test suite"]
-  RunTests --> CheckTests{Tests passed?}
-  CheckTests -->|No| FixTests["Debug and correct failing tests"]
-  CheckTests -->|Yes| End([Pre-PR verification gate cleared successfully])
-  FixBuild & FixTypes & FixLint & FixTests --> RunBuild
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `verification-loop` 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-PR checks / gate| VerLoop["verification-loop / SKILL.md"]
-  VerLoop -->|Guards finalize step in| Todo["todo-driven-workflow / SKILL.md"]
-  VerLoop -->|Requires test environment setup from| Env["environment-detection / SKILL.md"]
-  VerLoop -->|Precedes safe commit push in| GitCommit["git-commit / SKILL.md"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `verification-loop` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Feature code written; ready to claim task complete"] --> Trigger["verification-loop skill runs"]
-  Trigger --> Build["Run 'npm run build' -> Succeeded"]
-  Build --> Type["Run 'npm run typecheck' -> Found 2 type mismatches in routes.ts"]
-  Type --> FixT["Fix incorrect type casting in routes.ts"]
-  FixT --> Recheck["Re-run typecheck -> Succeeded"]
-  Recheck --> Lint["Run 'npm run lint' -> Clean"]
-  Lint --> Tests["Run 'npm run test' -> 24 tests passed"]
-  Tests --> Done([Verification loop complete; safe to open PR])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `verification-loop` 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: Verification Loop
+
+> Comprehensive pre-PR quality gate executing builds, linting, type-checking, test suites, and security scans before claiming a task complete.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `verification-loop` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Pre-PR Quality Check Triggered]) --> RunBuild["Execute compilation / project build"]
+  RunBuild --> CheckBuild{Build succeeded?}
+  CheckBuild -->|No| FixBuild["Debug and fix build errors"]
+  CheckBuild -->|Yes| RunTypeCheck["Execute language type-checking compiler"]
+  RunTypeCheck --> CheckTypes{Typecheck green?}
+  CheckTypes -->|No| FixTypes["Correct type-definition errors"]
+  CheckTypes -->|Yes| RunLint["Execute code linter checks"]
+  RunLint --> CheckLint{Lint clean?}
+  CheckLint -->|No| FixLint["Correct code-style and syntax errors"]
+  CheckLint -->|Yes| RunTests["Execute complete automated test suite"]
+  RunTests --> CheckTests{Tests passed?}
+  CheckTests -->|No| FixTests["Debug and correct failing tests"]
+  CheckTests -->|Yes| End([Pre-PR verification gate cleared successfully])
+  FixBuild & FixTypes & FixLint & FixTests --> RunBuild
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `verification-loop` 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-PR checks / gate| VerLoop["verification-loop / SKILL.md"]
+  VerLoop -->|Guards finalize step in| Todo["todo-driven-workflow / SKILL.md"]
+  VerLoop -->|Requires test environment setup from| Env["environment-detection / SKILL.md"]
+  VerLoop -->|Precedes safe commit push in| GitCommit["git-commit / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `verification-loop` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Feature code written; ready to claim task complete"] --> Trigger["verification-loop skill runs"]
+  Trigger --> Build["Run 'npm run build' -> Succeeded"]
+  Build --> Type["Run 'npm run typecheck' -> Found 2 type mismatches in routes.ts"]
+  Type --> FixT["Fix incorrect type casting in routes.ts"]
+  FixT --> Recheck["Re-run typecheck -> Succeeded"]
+  Recheck --> Lint["Run 'npm run lint' -> Clean"]
+  Lint --> Tests["Run 'npm run test' -> 24 tests passed"]
+  Tests --> Done([Verification loop complete; safe to open PR])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `verification-loop` 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/verify-before-claim.md

@@ -1,60 +1,60 @@
-# Workflow: Verify Before Claim
-
-> Fact-audit discipline requiring empirical verification of external claims, SDK configurations, defaults, and unmeasured performance estimates.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `verify-before-claim` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([Claim or Estimate Proposed]) --> IdentifyAssumptions["Isolate any claim or performance assumption"]
-  IdentifyAssumptions --> QueryAuthoritative["Execute WebSearch or read local code sources"]
-  QueryAuthoritative --> CrossVerify["Cross-verify details with authoritative documentation"]
-  CrossVerify --> RunLocalExperiment["Run quick script to empirically test the assumption"]
-  RunLocalExperiment --> CaptureResult["Log actual measured results and exit-codes"]
-  CaptureResult --> AssertFact["Assert verified fact based on objective data"]
-  AssertFact --> End([Hypothesis replaced with empirical truth])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `verify-before-claim` 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"] -->|Requires fact checking or estimates| VBC["verify-before-claim / SKILL.md"]
-  VBC -->|Empirical verification helper| RunCode["mcp_provides_tool_pylanceRunCodeSnippet / run_in_terminal"]
-  VBC -->|Secures quality of decisions in| GWD["grill-with-docs / SKILL.md"]
-  VBC -->|Verifies assertions in testing suite| TDD["tdd / SKILL.md"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `verify-before-claim` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Developer assumes: 'Node.js fs.rmSync returns boolean upon success'"] --> Trigger["verify-before-claim skill triggered"]
-  Trigger --> ReadDocs["Checks Node.js documentation via WebSearch"]
-  ReadDocs --> FindTrue["Discovers fs.rmSync returns 'undefined' on success, and throws on failure"]
-  FindTrue --> TestCode["Executes quick Node snippet to confirm empirical behavior"]
-  TestCode --> UpdateCode["Refactors proposed catch-blocks to handle exceptions instead of checking booleans"]
-  UpdateCode --> Done([Potential production runtime crash prevented])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `verify-before-claim` 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: Verify Before Claim
+
+> Fact-audit discipline requiring empirical verification of external claims, SDK configurations, defaults, and unmeasured performance estimates.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `verify-before-claim` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Claim or Estimate Proposed]) --> IdentifyAssumptions["Isolate any claim or performance assumption"]
+  IdentifyAssumptions --> QueryAuthoritative["Execute WebSearch or read local code sources"]
+  QueryAuthoritative --> CrossVerify["Cross-verify details with authoritative documentation"]
+  CrossVerify --> RunLocalExperiment["Run quick script to empirically test the assumption"]
+  RunLocalExperiment --> CaptureResult["Log actual measured results and exit-codes"]
+  CaptureResult --> AssertFact["Assert verified fact based on objective data"]
+  AssertFact --> End([Hypothesis replaced with empirical truth])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `verify-before-claim` 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"] -->|Requires fact checking or estimates| VBC["verify-before-claim / SKILL.md"]
+  VBC -->|Empirical verification helper| RunCode["mcp_provides_tool_pylanceRunCodeSnippet / run_in_terminal"]
+  VBC -->|Secures quality of decisions in| GWD["grill-with-docs / SKILL.md"]
+  VBC -->|Verifies assertions in testing suite| TDD["tdd / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `verify-before-claim` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Developer assumes: 'Node.js fs.rmSync returns boolean upon success'"] --> Trigger["verify-before-claim skill triggered"]
+  Trigger --> ReadDocs["Checks Node.js documentation via WebSearch"]
+  ReadDocs --> FindTrue["Discovers fs.rmSync returns 'undefined' on success, and throws on failure"]
+  FindTrue --> TestCode["Executes quick Node snippet to confirm empirical behavior"]
+  TestCode --> UpdateCode["Refactors proposed catch-blocks to handle exceptions instead of checking booleans"]
+  UpdateCode --> Done([Potential production runtime crash prevented])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `verify-before-claim` 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/zoom-out.md

@@ -1,62 +1,62 @@
-# Workflow: Zoom Out
-
-> High-level reflection report generation to break out of error loops, analyze failure patterns, and backtrack to alternative paths.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `zoom-out` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([3 Consecutive Errors Triggered]) --> Tripped{Rule of 3 Tripped?}
-  Tripped -->|No| Backtrack["Review code change and retry"]
-  Tripped -->|Yes| LockWork["Lock all file edit capabilities"]
-  LockWork --> GatherState["Analyze current working directory, file states, and errors"]
-  GatherState --> GenReport["Compile formal Reflection Report: what failed, assumptions, backtracking options"]
-  GenReport --> PresentReport["Present report to human partner and request guidance"]
-  PresentReport --> End([Workforce unlocked after human direction received])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `zoom-out` 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
-  RuleOf3["Rule of 3 Circuit Breaker"] -->|Tripped!| ZoomOut["zoom-out / SKILL.md"]
-  ZoomOut -->|Halts execution for| ActiveWork["Active workspace edits"]
-  ZoomOut -->|Asks for human direction via| AskQuestions["vscode_askQuestions"]
-  ZoomOut -->|Unlocks workspace state after| HumanReset["Human Partner Response"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `zoom-out` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Attempting to fix Python import error; fails 3 times consecutively with same trace"] --> Trigger["Rule of 3 circuit breaker trips"]
-  Trigger --> Lock["Workspace writes locked"]
-  Trigger --> Collect["Collect error traces and diff history"]
-  Collect --> WriteReport["Create docs/reflection/zoom-out-report.md detailing the import cyclic dependency"]
-  WriteReport --> Present["Present options to human: Option A - Merge imports, Option B - Extract shared modules"]
-  Present --> UserChoice["User select: 'Option B'"]
-  UserChoice --> Unlock["Unlock workspace and execute Option B"]
-  Unlock --> Done([Error loop successfully broken and resolved])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `zoom-out` 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: Zoom Out
+
+> High-level reflection report generation to break out of error loops, analyze failure patterns, and backtrack to alternative paths.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `zoom-out` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([3 Consecutive Errors Triggered]) --> Tripped{Rule of 3 Tripped?}
+  Tripped -->|No| Backtrack["Review code change and retry"]
+  Tripped -->|Yes| LockWork["Lock all file edit capabilities"]
+  LockWork --> GatherState["Analyze current working directory, file states, and errors"]
+  GatherState --> GenReport["Compile formal Reflection Report: what failed, assumptions, backtracking options"]
+  GenReport --> PresentReport["Present report to human partner and request guidance"]
+  PresentReport --> End([Workforce unlocked after human direction received])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `zoom-out` 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
+  RuleOf3["Rule of 3 Circuit Breaker"] -->|Tripped!| ZoomOut["zoom-out / SKILL.md"]
+  ZoomOut -->|Halts execution for| ActiveWork["Active workspace edits"]
+  ZoomOut -->|Asks for human direction via| AskQuestions["vscode_askQuestions"]
+  ZoomOut -->|Unlocks workspace state after| HumanReset["Human Partner Response"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `zoom-out` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Attempting to fix Python import error; fails 3 times consecutively with same trace"] --> Trigger["Rule of 3 circuit breaker trips"]
+  Trigger --> Lock["Workspace writes locked"]
+  Trigger --> Collect["Collect error traces and diff history"]
+  Collect --> WriteReport["Create docs/reflection/zoom-out-report.md detailing the import cyclic dependency"]
+  WriteReport --> Present["Present options to human: Option A - Merge imports, Option B - Extract shared modules"]
+  Present --> UserChoice["User select: 'Option B'"]
+  UserChoice --> Unlock["Unlock workspace and execute Option B"]
+  Unlock --> Done([Error loop successfully broken and resolved])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `zoom-out` 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/environment-detection/SKILL.md

@@ -1,77 +1,77 @@
----
-name: environment-detection
-description: Use at the very beginning of the session (Discover phase) to automatically detect and align with the operating system, terminal shell (e.g. Git Bash vs PowerShell vs Command Prompt), package managers, and development tools. Prevents blind command execution and repetitive tool-related errors.
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
----
-
-# Environment Detection & Shell Alignment
-
-## 📋 Skill Contract
-
-| Component | Specification |
-| :--- | :--- |
-| **Trigger / Input** | Session Start (Discover Phase), or before executing a complex terminal command sequence. |
-| **Expected Output** | Terminal execution of `node <this-skill-dir>/scripts/preflight.js`. Output of the detected OS and Shell. |
-| **State Mutations** | Context is updated with the correct path separator (`/` vs `\`) and environment variable syntax (`$VAR` vs `%VAR%`). |
-| **Enforcement Gate** | You MUST read the terminal output of `preflight.js`. If you use the wrong syntax (e.g. `%VAR%` in bash), the terminal will naturally Exit 1 and block your progress. |
-
-## Core Principles
-- **MUST** operate using the cognitive loop: Think > Try > Summarize > Record.
-- **[Think]**: Before running any terminal commands, check your environment. Blind execution is the primary source of agent step waste.
-- **[Try]**: Run the automated preflight check script to determine exact platform properties.
-- **[Summarize]**: Output the detected terminal, OS, and toolchains so the session context retains these bounds.
-- **[Record]**: Adopt the corresponding command syntax rules for the rest of the conversation.
-
-## Strict Workspace Boundary (僅偵測與操作當前工作區)
-- **Current Workspace Only**: 必須僅偵測與操作當前活動工作區目錄（即當前專案根目錄，亦為 `process.cwd()`）。
-- **Ignore Other Workspaces**: 即使 VS Code 內容或歷史記錄中暴露了其他工作區、暫存路徑或最近開啟的專案（例如 `d:\super.h2o.sbom`、`d:\DeveloperDocs`、`c:\Users\DanielCH.Chang\Desktop\XinputDxe_V0.0.5` 等），你也 **必須完全忽略它們**。絕對不要對這些非當前專案之路徑進行結構分析、工具檢查，更不能在其中執行任何終端機指令。
-- **Single-Workspace Execution**: 所有終端機指令、工具可用性檢查、路徑解析均必須嚴格限制在當前專案根目錄內。嚴格禁止跨越邊界操作鄰近或無關的資料夾。
-
-## [State Checkpoint]
-- Verify your environment details *before* executing commands or writing files.
-- If you just started a session, run the preflight script immediately.
-
-## [Discovery Phase: Environment Audit]
-1. Run the preflight script that lives at `scripts/preflight.js` **inside this skill's own directory** — resolve the path from wherever this SKILL.md was loaded (do not guess a hard-coded location):
-   ```bash
-   node "<this-skill-dir>/scripts/preflight.js"
-   ```
-2. Parse the output and understand:
-   - Operating System (Windows vs. macOS vs. Linux)
-   - Active Shell (Git Bash vs. PowerShell vs. Command Prompt)
-   - Available CLI Tools (node, pnpm, docker, python, etc.)
-3. **Toolchain Self-Heal (工欲善其事,必先利其器)**: The harness itself is part of the environment. Audit whether this workspace's integration touchpoints (`.claude/settings.json` hooks, `.cursorrules`, `.github/copilot-instructions.md`, `AGENTS.md`) are installed, and repair any missing ones — e.g., installed via Claude Code but now opened in Copilot:
-   ```bash
-   node "<skills-repo-root>/harness-everything/scripts/self-heal.js"
-   ```
-   The script is idempotent (it delegates to the installer, which merges hooks by id and never duplicates advisory text), so running it on an already-healthy workspace is a no-op. Skip only if the user intentionally removed a touchpoint file.
-
-## [Execution Phase: Syntax and Command Alignment]
-Choose the correct syntax matching your active shell:
-
-### 1. Git Bash on Windows (User's Preferred Terminal)
-- **Path Slashes**: Always use forward slashes `/` (e.g., `scripts/lib/utils.js`). Never use raw backslashes `\` because they act as escape characters in Bash.
-- **Env Variables**: Use `$VARIABLE_NAME` syntax. Do NOT use `%VARIABLE_NAME%` or `$env:VARIABLE_NAME`.
-- **Command Set**: Standard Unix commands are fully supported (`ls`, `rm -rf`, `mkdir -p`, `cp`, `mv`). Do NOT run CMD native commands like `dir`, `del`, or `copy`.
-- **No PowerShell syntax**: Do not run PowerShell-specific scripts or syntax.
-
-### 2. PowerShell on Windows
-- **Path Slashes**: Forward slashes `/` or backslashes `\\` are both acceptable.
-- **Env Variables**: Use `$env:VARIABLE_NAME` syntax.
-- **Command Set**: Use standard PowerShell commands or common aliases (e.g., `New-Item`, `Remove-Item`).
-
-### 3. Windows Command Prompt (CMD)
-- **Path Slashes**: Use backslashes `\` for file paths.
-- **Env Variables**: Use `%VARIABLE_NAME%` syntax.
-- **Command Set**: Use `dir`, `del`, `copy`, `mkdir`. Do NOT use `ls`, `rm`, `cp`, `mkdir -p`.
-
-## [Verification & Reflection Phase]
-3. If any shell command fails, do **not** blindly retry the exact same command. 
-4. Stop and ask yourself: "Did I use the wrong syntax for this terminal? Is this a Git Bash vs. PowerShell syntax issue?"
-5. If you fail 3 times on the same command, trigger the `zoom-out` circuit breaker.
-
-## Red Flags & Common Errors
-- ❌ **CMD commands in Git Bash**: Attempting to run `dir` or `del` when the terminal is actually running Git Bash.
-- ❌ **PowerShell commands in Bash**: Attempting to run `$env:PATH` or `.ps1` files in a Bash environment.
-- ❌ **Path escape failures**: Sending raw Windows paths like `scripts\run.js` inside a Bash terminal, which interprets `\r` as a carriage return or escapes characters.
+---
+name: environment-detection
+description: Use at the very beginning of the session (Discover phase) to automatically detect and align with the operating system, terminal shell (e.g. Git Bash vs PowerShell vs Command Prompt), package managers, and development tools. Prevents blind command execution and repetitive tool-related errors.
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+---
+
+# Environment Detection & Shell Alignment
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Session Start (Discover Phase), or before executing a complex terminal command sequence. |
+| **Expected Output** | Terminal execution of `node <this-skill-dir>/scripts/preflight.js`. Output of the detected OS and Shell. |
+| **State Mutations** | Context is updated with the correct path separator (`/` vs `\`) and environment variable syntax (`$VAR` vs `%VAR%`). |
+| **Enforcement Gate** | You MUST read the terminal output of `preflight.js`. If you use the wrong syntax (e.g. `%VAR%` in bash), the terminal will naturally Exit 1 and block your progress. |
+
+## Core Principles
+- **MUST** operate using the cognitive loop: Think > Try > Summarize > Record.
+- **[Think]**: Before running any terminal commands, check your environment. Blind execution is the primary source of agent step waste.
+- **[Try]**: Run the automated preflight check script to determine exact platform properties.
+- **[Summarize]**: Output the detected terminal, OS, and toolchains so the session context retains these bounds.
+- **[Record]**: Adopt the corresponding command syntax rules for the rest of the conversation.
+
+## Strict Workspace Boundary (僅偵測與操作當前工作區)
+- **Current Workspace Only**: 必須僅偵測與操作當前活動工作區目錄（即當前專案根目錄，亦為 `process.cwd()`）。
+- **Ignore Other Workspaces**: 即使 VS Code 內容或歷史記錄中暴露了其他工作區、暫存路徑或最近開啟的專案（例如 `d:\super.h2o.sbom`、`d:\DeveloperDocs`、`c:\Users\DanielCH.Chang\Desktop\XinputDxe_V0.0.5` 等），你也 **必須完全忽略它們**。絕對不要對這些非當前專案之路徑進行結構分析、工具檢查，更不能在其中執行任何終端機指令。
+- **Single-Workspace Execution**: 所有終端機指令、工具可用性檢查、路徑解析均必須嚴格限制在當前專案根目錄內。嚴格禁止跨越邊界操作鄰近或無關的資料夾。
+
+## [State Checkpoint]
+- Verify your environment details *before* executing commands or writing files.
+- If you just started a session, run the preflight script immediately.
+
+## [Discovery Phase: Environment Audit]
+1. Run the preflight script that lives at `scripts/preflight.js` **inside this skill's own directory** — resolve the path from wherever this SKILL.md was loaded (do not guess a hard-coded location):
+   ```bash
+   node "<this-skill-dir>/scripts/preflight.js"
+   ```
+2. Parse the output and understand:
+   - Operating System (Windows vs. macOS vs. Linux)
+   - Active Shell (Git Bash vs. PowerShell vs. Command Prompt)
+   - Available CLI Tools (node, pnpm, docker, python, etc.)
+3. **Toolchain Self-Heal (工欲善其事,必先利其器)**: The harness itself is part of the environment. Audit whether this workspace's integration touchpoints (`.claude/settings.json` hooks, `.cursorrules`, `.github/copilot-instructions.md`, `AGENTS.md`) are installed, and repair any missing ones — e.g., installed via Claude Code but now opened in Copilot:
+   ```bash
+   node "<skills-repo-root>/harness-everything/scripts/self-heal.js"
+   ```
+   The script is idempotent (it delegates to the installer, which merges hooks by id and never duplicates advisory text), so running it on an already-healthy workspace is a no-op. Skip only if the user intentionally removed a touchpoint file.
+
+## [Execution Phase: Syntax and Command Alignment]
+Choose the correct syntax matching your active shell:
+
+### 1. Git Bash on Windows (User's Preferred Terminal)
+- **Path Slashes**: Always use forward slashes `/` (e.g., `scripts/lib/utils.js`). Never use raw backslashes `\` because they act as escape characters in Bash.
+- **Env Variables**: Use `$VARIABLE_NAME` syntax. Do NOT use `%VARIABLE_NAME%` or `$env:VARIABLE_NAME`.
+- **Command Set**: Standard Unix commands are fully supported (`ls`, `rm -rf`, `mkdir -p`, `cp`, `mv`). Do NOT run CMD native commands like `dir`, `del`, or `copy`.
+- **No PowerShell syntax**: Do not run PowerShell-specific scripts or syntax.
+
+### 2. PowerShell on Windows
+- **Path Slashes**: Forward slashes `/` or backslashes `\\` are both acceptable.
+- **Env Variables**: Use `$env:VARIABLE_NAME` syntax.
+- **Command Set**: Use standard PowerShell commands or common aliases (e.g., `New-Item`, `Remove-Item`).
+
+### 3. Windows Command Prompt (CMD)
+- **Path Slashes**: Use backslashes `\` for file paths.
+- **Env Variables**: Use `%VARIABLE_NAME%` syntax.
+- **Command Set**: Use `dir`, `del`, `copy`, `mkdir`. Do NOT use `ls`, `rm`, `cp`, `mkdir -p`.
+
+## [Verification & Reflection Phase]
+3. If any shell command fails, do **not** blindly retry the exact same command. 
+4. Stop and ask yourself: "Did I use the wrong syntax for this terminal? Is this a Git Bash vs. PowerShell syntax issue?"
+5. If you fail 3 times on the same command, trigger the `zoom-out` circuit breaker.
+
+## Red Flags & Common Errors
+- ❌ **CMD commands in Git Bash**: Attempting to run `dir` or `del` when the terminal is actually running Git Bash.
+- ❌ **PowerShell commands in Bash**: Attempting to run `$env:PATH` or `.ps1` files in a Bash environment.
+- ❌ **Path escape failures**: Sending raw Windows paths like `scripts\run.js` inside a Bash terminal, which interprets `\r` as a carriage return or escapes characters.