harness-everything 0.2.0 → 0.2.1

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([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.

package/docs/workflows/eval-harness.md

@@ -1,57 +1,57 @@
-# Workflow: Eval Harness
-
-> Evaluates AI developer agent performance based on accuracy, resource efficiency, and anti-loop metrics.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `eval-harness` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([Agent Execution Finished]) --> CollectExecutionMetrics["Gather total elapsed time, token count, and API calls"]
-  CollectExecutionMetrics --> EvaluateAccuracy["Compare completed task output against baseline correctness requirements"]
-  EvaluateAccuracy --> AnalyzeLoops["Check for repetitive tool invocations or redundant edits"]
-  AnalyzeLoops --> CalculateScores["Calculate performance and efficiency scores"]
-  CalculateScores --> GenerateEvalReport["Compile formal evaluation report and dashboard metrics"]
-  GenerateEvalReport --> End([Performance metrics indexed and logged])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `eval-harness` 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"] -->|Analyzes performance metrics| EH["eval-harness / SKILL.md"]
-  EH -->|Synthesizes lessons learned for| Evolve["self-evolve / SKILL.md"]
-  EH -->|Detects error loops triggering| ZoomOut["zoom-out / SKILL.md"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `eval-harness` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Agent session finishes implementing a complete backend server"] --> Trigger["eval-harness skill executed"]
-  Trigger --> Gather["Collects: 15 minutes elapsed, 32 tool calls, 45,000 tokens consumed"]
-  Gather --> Score["Scores: Correctness 10/10, Resource Efficiency 9/10, Anti-loop 10/10"]
-  Score --> Output["Generates benchmark report summarizing optimal execution speed and zero looping errors"]
-  Output --> Done([Benchmark logged for project history])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `eval-harness` 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: Eval Harness
+
+> Evaluates AI developer agent performance based on accuracy, resource efficiency, and anti-loop metrics.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `eval-harness` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Agent Execution Finished]) --> CollectExecutionMetrics["Gather total elapsed time, token count, and API calls"]
+  CollectExecutionMetrics --> EvaluateAccuracy["Compare completed task output against baseline correctness requirements"]
+  EvaluateAccuracy --> AnalyzeLoops["Check for repetitive tool invocations or redundant edits"]
+  AnalyzeLoops --> CalculateScores["Calculate performance and efficiency scores"]
+  CalculateScores --> GenerateEvalReport["Compile formal evaluation report and dashboard metrics"]
+  GenerateEvalReport --> End([Performance metrics indexed and logged])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `eval-harness` 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"] -->|Analyzes performance metrics| EH["eval-harness / SKILL.md"]
+  EH -->|Synthesizes lessons learned for| Evolve["self-evolve / SKILL.md"]
+  EH -->|Detects error loops triggering| ZoomOut["zoom-out / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `eval-harness` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Agent session finishes implementing a complete backend server"] --> Trigger["eval-harness skill executed"]
+  Trigger --> Gather["Collects: 15 minutes elapsed, 32 tool calls, 45,000 tokens consumed"]
+  Gather --> Score["Scores: Correctness 10/10, Resource Efficiency 9/10, Anti-loop 10/10"]
+  Score --> Output["Generates benchmark report summarizing optimal execution speed and zero looping errors"]
+  Output --> Done([Benchmark logged for project history])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `eval-harness` 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/fable-discipline.md

@@ -1,59 +1,59 @@
-# Workflow: Fable Discipline
-
-> Shadow guard for fable-mode preventing context bloat, enforcing physical boundaries, and tracking token burn metrics.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `fable-discipline` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([Fable Task Initiated]) --> AuditContext["Audit total file lengths in current context"]
-  AuditContext --> CheckTokenLimit{Tokens exceeding budget?}
-  CheckTokenLimit -->|Yes| TrimContext["Evict raw logs, completed tasks, and non-essential file contents"]
-  CheckTokenLimit -->|No| KeepState["Continue monitoring context state"]
-  TrimContext --> EnforceLimit["Enforce physical boundary guidelines"]
-  KeepState --> EnforceLimit
-  EnforceLimit --> LogMetrics["Track token utilization and distillation loops"]
-  LogMetrics --> End([Context maintained under safe, high-attention limits])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `fable-discipline` 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
-  Fable["fable-mode / SKILL.md"] -->|Monitors context on every turn| FD["fable-discipline / SKILL.md"]
-  FD -->|Trims and prunes files from| ActiveContext["Active AI Session Context"]
-  FD -->|Triggers high-level reflection when overloaded| ZoomOut["zoom-out / SKILL.md"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `fable-discipline` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Fable-mode is editing a large monorepo (context approaching 120k tokens)"] --> Monitor["Fable-discipline analyzes context size"]
-  Monitor --> TriggerPruning["Identifies 80k tokens of raw test execution logs & completed sub-task details"]
-  TriggerPruning --> Clean["Evicts completed step details and logs from immediate active context"]
-  Clean --> Compress["Summarizes historical state into a 50-line relational state.json"]
-  Compress --> Done([Active context drops back to 40k tokens, preserving model's reasoning precision])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `fable-discipline` 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: Fable Discipline
+
+> Shadow guard for fable-mode preventing context bloat, enforcing physical boundaries, and tracking token burn metrics.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `fable-discipline` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Fable Task Initiated]) --> AuditContext["Audit total file lengths in current context"]
+  AuditContext --> CheckTokenLimit{Tokens exceeding budget?}
+  CheckTokenLimit -->|Yes| TrimContext["Evict raw logs, completed tasks, and non-essential file contents"]
+  CheckTokenLimit -->|No| KeepState["Continue monitoring context state"]
+  TrimContext --> EnforceLimit["Enforce physical boundary guidelines"]
+  KeepState --> EnforceLimit
+  EnforceLimit --> LogMetrics["Track token utilization and distillation loops"]
+  LogMetrics --> End([Context maintained under safe, high-attention limits])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `fable-discipline` 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
+  Fable["fable-mode / SKILL.md"] -->|Monitors context on every turn| FD["fable-discipline / SKILL.md"]
+  FD -->|Trims and prunes files from| ActiveContext["Active AI Session Context"]
+  FD -->|Triggers high-level reflection when overloaded| ZoomOut["zoom-out / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `fable-discipline` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Fable-mode is editing a large monorepo (context approaching 120k tokens)"] --> Monitor["Fable-discipline analyzes context size"]
+  Monitor --> TriggerPruning["Identifies 80k tokens of raw test execution logs & completed sub-task details"]
+  TriggerPruning --> Clean["Evicts completed step details and logs from immediate active context"]
+  Clean --> Compress["Summarizes historical state into a 50-line relational state.json"]
+  Compress --> Done([Active context drops back to 40k tokens, preserving model's reasoning precision])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `fable-discipline` 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/fable-mode.md

@@ -1,32 +1,32 @@
-# Workflow: Fable Mode
-
-> Macro-task planning and execution engine. Like all Harness workflows, this is not a straight line to success. It requires continuous verification and course correction.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how `fable-mode` handles macro tasks. Subagent failure or integration crashes are expected realities, not edge cases.
-
-```mermaid
-graph TD
-  Start([Tier 3 Macro Task Triggered]) --> InitFable["Initialize Fable Execution Context"]
-  InitFable --> AnalyzeScope["Map system dependencies & files"]
-  AnalyzeScope --> GenerateContract["Generate Contract & Todo List"]
-  
-  GenerateContract --> RunStep["Try: Execute Step / Sub-agent"]
-  RunStep --> VerifyStep["Try: Run verify-gate.js for Integration"]
-  
-  VerifyStep --> Check{Gate: Exit Code?}
-  Check -->|Exit 1: Sub-agent Failed| Diagnose["Reflect: Why did sub-agent fail?"]
-  Diagnose --> InsertBlocker["Insert Blocker Todo: Fix Integration"]
-  InsertBlocker --> RunStep
-  
-  Check -->|Exit 0: Success| CheckAllSteps{All steps done?}
-  CheckAllSteps -->|No| RunStep
-  CheckAllSteps -->|Yes| FinalAudit["Perform system-wide verification loop"]
-  
-  FinalAudit --> FinalCheck{Gate: Exit Code?}
-  FinalCheck -->|Exit 1| Diagnose
-  FinalCheck -->|Exit 0| End([Macro rewrite successfully deployed])
-```
+# Workflow: Fable Mode
+
+> Macro-task planning and execution engine. Like all Harness workflows, this is not a straight line to success. It requires continuous verification and course correction.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how `fable-mode` handles macro tasks. Subagent failure or integration crashes are expected realities, not edge cases.
+
+```mermaid
+graph TD
+  Start([Tier 3 Macro Task Triggered]) --> InitFable["Initialize Fable Execution Context"]
+  InitFable --> AnalyzeScope["Map system dependencies & files"]
+  AnalyzeScope --> GenerateContract["Generate Contract & Todo List"]
+  
+  GenerateContract --> RunStep["Try: Execute Step / Sub-agent"]
+  RunStep --> VerifyStep["Try: Run verify-gate.js for Integration"]
+  
+  VerifyStep --> Check{Gate: Exit Code?}
+  Check -->|Exit 1: Sub-agent Failed| Diagnose["Reflect: Why did sub-agent fail?"]
+  Diagnose --> InsertBlocker["Insert Blocker Todo: Fix Integration"]
+  InsertBlocker --> RunStep
+  
+  Check -->|Exit 0: Success| CheckAllSteps{All steps done?}
+  CheckAllSteps -->|No| RunStep
+  CheckAllSteps -->|Yes| FinalAudit["Perform system-wide verification loop"]
+  
+  FinalAudit --> FinalCheck{Gate: Exit Code?}
+  FinalCheck -->|Exit 1| Diagnose
+  FinalCheck -->|Exit 0| End([Macro rewrite successfully deployed])
+```

package/docs/workflows/git-commit.md

@@ -1,62 +1,62 @@
-# Workflow: Git Commit
-
-> Generates semantic, Angular-style conventional commits after verifying the workspace, staged files, and active language contexts.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `git-commit` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([Trigger Commit Hook / Command]) --> DetectRepo["Detect main repo vs submodule"]
-  DetectRepo --> PreCheck["Verify unstaged changes & staged files"]
-  PreCheck --> StageCheck{Staged files present?}
-  StageCheck -->|No| Warning["Warn developer & exit"]
-  StageCheck -->|Yes| DetectLang["Analyze file extensions for active languages"]
-  DetectLang --> GenMessage["Analyze changes and generate Angular-style commit message"]
-  GenMessage --> FormatCheck["Format check: type, scope, subject, body, footer"]
-  FormatCheck --> WriteCommit["Commit staged files with formatted message"]
-  WriteCommit --> End([Staging clean and committed])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `git-commit` 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"] -->|Keyword: commit / git / save| GitCommit["git-commit / SKILL.md"]
-  GitCommit -->|Formats according to| Guide["git-commit / guides / ANGULAR_STYLE.md"]
-  GitCommit -->|Integrates with pre-commit gates| VerLoop["verification-loop / SKILL.md"]
-  GitCommit -->|Composed after history squashes| Rewrite["rewrite-commits / SKILL.md"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `git-commit` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Developer completes feature & runs 'git add .'"] --> Trigger["Invoke git-commit skill"]
-  Trigger --> Analyze["Skill parses staged diff: 'src/auth.js (+15,-2)'"]
-  Analyze --> DetectScope["Deduce scope: 'auth' and type: 'feat'"]
-  DetectScope --> BuildMessage["Build message: 'feat(auth): add JWT token expiration check'"]
-  BuildMessage --> Commit["Execute git commit -m 'feat(auth): add JWT token expiration check'"]
-  Commit --> Done(["Repository index updated cleanly"])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `git-commit` 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: Git Commit
+
+> Generates semantic, Angular-style conventional commits after verifying the workspace, staged files, and active language contexts.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `git-commit` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Trigger Commit Hook / Command]) --> DetectRepo["Detect main repo vs submodule"]
+  DetectRepo --> PreCheck["Verify unstaged changes & staged files"]
+  PreCheck --> StageCheck{Staged files present?}
+  StageCheck -->|No| Warning["Warn developer & exit"]
+  StageCheck -->|Yes| DetectLang["Analyze file extensions for active languages"]
+  DetectLang --> GenMessage["Analyze changes and generate Angular-style commit message"]
+  GenMessage --> FormatCheck["Format check: type, scope, subject, body, footer"]
+  FormatCheck --> WriteCommit["Commit staged files with formatted message"]
+  WriteCommit --> End([Staging clean and committed])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `git-commit` 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"] -->|Keyword: commit / git / save| GitCommit["git-commit / SKILL.md"]
+  GitCommit -->|Formats according to| Guide["git-commit / guides / ANGULAR_STYLE.md"]
+  GitCommit -->|Integrates with pre-commit gates| VerLoop["verification-loop / SKILL.md"]
+  GitCommit -->|Composed after history squashes| Rewrite["rewrite-commits / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `git-commit` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Developer completes feature & runs 'git add .'"] --> Trigger["Invoke git-commit skill"]
+  Trigger --> Analyze["Skill parses staged diff: 'src/auth.js (+15,-2)'"]
+  Analyze --> DetectScope["Deduce scope: 'auth' and type: 'feat'"]
+  DetectScope --> BuildMessage["Build message: 'feat(auth): add JWT token expiration check'"]
+  BuildMessage --> Commit["Execute git commit -m 'feat(auth): add JWT token expiration check'"]
+  Commit --> Done(["Repository index updated cleanly"])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `git-commit` 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.