harness-everything 0.2.2 → 0.3.6

package/docs/workflows/find-skills.md

@@ -0,0 +1,36 @@
+# Workflow: Find Skills
+
+> Discover a third-party skill only after the reviewed local catalog and
+> self-evolved manifest do not cover the requested capability.
+
+## 1. Decision flow
+
+```mermaid
+flowchart TD
+  Start([Capability request]) --> Local{Covered locally?}
+  Local -->|Yes| UseLocal[Use the existing Harness skill]
+  Local -->|No| Installed[Run npx skills list --json]
+  Installed --> Search[Search skills.sh and npx skills find]
+  Search --> Review[Read source SKILL.md and assess trust]
+  Review --> Approval{Human approval?}
+  Approval -->|No| Fallback[Handle directly or stop]
+  Approval -->|Yes| Apply[Apply through use-skill.js or install explicitly]
+```
+
+## 2. Operating contract
+
+1. Check `harness-everything`'s registry and `generated[]` entries first.
+2. Query project and global installs live with `npx skills list --json`.
+3. Search `skills.sh` and `npx skills find <query>` only when local coverage is
+   absent; inspect the actual `SKILL.md`, source, and install signal.
+4. Present the candidate and source. Do not fetch or apply it without explicit
+   user approval.
+5. Use `node "<this-skill-dir>/scripts/use-skill.js" <owner/repo[@skill]>` for
+   the default six-hour OS-temp application. Use `npx skills add` only when the
+   user explicitly wants a permanent install.
+
+## 3. Verification
+
+If search, network, or application fails, report the failure and continue with
+the direct built-in solution. Never treat an unaudited third-party skill as a
+first-party Harness skill or add it to the static manifest.

package/docs/workflows/git-commit.md

@@ -10,15 +10,24 @@ This section visualizes how the `git-commit` skill executes internally, detailin
 
 ```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])
+  Start([Trigger Commit Request / Task Complete]) --> CheckGit{Is Git Repo Initialized?}
+  CheckGit -->|No| OfferInit["Prompt User: Run git init or Skip Commit"]
+  CheckGit -->|Yes| CheckSubmodules{Has Submodule Changes?}
+  
+  CheckSubmodules -->|Yes| CommitSubmodules["Commit Submodules First (Bottom-Up)"] --> CheckStatus
+  CheckSubmodules -->|No| CheckStatus["Run git status & git diff --cached"]
+  
+  CheckStatus --> StageCheck{Are Files Staged?}
+  StageCheck -->|No| AskStage["Prompt User / Stage Targeted Files"] --> FormatMessage
+  StageCheck -->|Yes| FormatMessage["Format Angular Commit Message"]
+  
+  FormatMessage --> CheckShell{Shell / Multiline Escaping Check?}
+  CheckShell -->|Simple Single Line| DirectCommit["Run git commit -m 'type(scope): subject'"]
+  CheckShell -->|Multiline / Windows| TempFileCommit["Write .git-commit-msg.txt -> Run git commit -F -> Cleanup"]
+  
+  DirectCommit --> VerifyCommit["Run git log -1 to Verify"]
+  TempFileCommit --> VerifyCommit
+  VerifyCommit --> End([Staging Clean and Committed])
 ```
 
 ---

package/docs/workflows/grill-me.md

@@ -10,15 +10,14 @@ This section visualizes how the `grill-me` skill executes internally, detailing
 
 ```mermaid
 graph TD
-  Start([Developer Proposes Plan]) --> IntroduceChallenger["Introduce 'Challenger' adversarial persona"]
-  IntroduceChallenger --> ProbeAssumptions["Analyze proposal and probe soft/mocked points"]
-  ProbeAssumptions --> AskHardQuestions["Ask 3-5 aggressive, non-trivial stress-testing questions"]
-  AskHardQuestions --> ReceiveAnswers["Developer provides details & arguments"]
-  ReceiveAnswers --> ValidateResilience{Answers robust & handle failures?}
-  ValidateResilience -->|No| GrillDeeper["Grill deeper on specific vulnerabilities"]
-  ValidateResilience -->|Yes| DistillDecisions["Distill final agreed design decisions"]
-  GrillDeeper --> ReceiveAnswers
-  DistillDecisions --> End([Proposal approved and hardened against failures])
+  Start([Developer Proposes Plan]) --> Discovery["Scan Related Code, CONTEXT.md & Existing ADRs"]
+  Discovery --> AskQuestion["Ask Exactly ONE Question at a Time (with AI Recommendation)"]
+  AskQuestion --> ReceiveAnswer["Receive Developer Answer & Resolve Branch"]
+  ReceiveAnswer --> UpdateGlossary["Update CONTEXT.md Glossary Inline"]
+  UpdateGlossary --> ValidateResilience{All Decision Tree Branches Resolved?}
+  ValidateResilience -->|No| AskQuestion
+  ValidateResilience -->|Yes| HandoffToSpec["Hand off to to-spec for Outline Preview & Spec/ADR Publishing"]
+  HandoffToSpec --> End([Route to to-tickets / fable-mode / tdd])
 ```
 
 ---
@@ -30,8 +29,9 @@ This diagram illustrates how the `grill-me` skill is triggered through user requ
 ```mermaid
 graph LR
   Router["harness-everything / tier-router.js"] -->|Keyword: grill / debate / plan| GrillMe["grill-me / SKILL.md"]
-  GrillMe -->|Writes final hardened agreements into| GWD["grill-with-docs / SKILL.md"]
-  GrillMe -->|Directs macro execution strategies of| Fable["fable-mode / SKILL.md"]
+  GrillMe -->|Vague proposal or technical robustness needed| GrillMe
+  GrillMe -->|Needs glossary/ADR documentation alignment| GWD["grill-with-docs / SKILL.md"]
+  GWD -->|Directs macro execution strategies of| Fable["fable-mode / SKILL.md"]
 ```
 
 ---

package/docs/workflows/grill-with-docs.md

@@ -10,14 +10,20 @@ This section visualizes how the `grill-with-docs` skill executes internally, det
 
 ```mermaid
 graph TD
-  Start([Plan Proposed against Domain]) --> ReadDomainModel["Read CONTEXT.md and existing ADRs"]
+  Start([Plan Proposed against Domain]) --> CheckCoreValidity{Plan vague or unverified?}
+  CheckCoreValidity -->|Yes| RecommendGrillMe["Recommend running grill-me first"]
+  CheckCoreValidity -->|No| ReadDomainModel["Read CONTEXT.md and existing ADRs"]
+  RecommendGrillMe --> EndVague([Postponed until plan is hardened])
   ReadDomainModel --> ChallengeDrift["Examine plan for term drift or architectural violations"]
   ChallengeDrift --> UpdateGlossary["Refine and match terminology with current Glossary"]
-  UpdateGlossary --> DraftADR["Draft formal Architecture Decision Record in ADR format"]
-  DraftADR --> StressTestADR["Stress-test ADR against error boundaries and fail-safes"]
-  StressTestADR --> WriteDocs["Commit ADR to docs/adr/ and update CONTEXT.md"]
-  WriteDocs --> InjectTodos["Inject critical TODO: [CRITICAL BUG FIX] tags into corresponding code"]
-  InjectTodos --> End([Code and documentation are perfectly aligned])
+  UpdateGlossary --> ResolveADRPath{Resolve ADR Storage Path}
+  
+  ResolveADRPath -->|docs/adr/ or CONTEXT-MAP.md Exists| WriteDocs["Write ADR to docs/adr/ or CONTEXT-MAP.md Location"]
+  ResolveADRPath -->|No Folder Found| WritePlatform["Write to .github/harness-everything/adr/ or Delegate to to-spec"]
+  
+  WriteDocs --> ToSpec["Hand off to to-spec for Outline Preview & Spec/ADR Publishing"]
+  WritePlatform --> ToSpec
+  ToSpec --> End([Route to to-tickets / fable-mode / tdd])
 ```
 
 ---
@@ -29,9 +35,10 @@ This diagram illustrates how the `grill-with-docs` skill is triggered through us
 ```mermaid
 graph LR
   Router["harness-everything / tier-router.js"] -->|Keyword: adr / decision / glossary| GWD["grill-with-docs / SKILL.md"]
-  GWD -->|Coordinates stress-tests using| GrillMe["grill-me / SKILL.md"]
+  GrillMe["grill-me / SKILL.md"] -->|Hardened plan ready for formalization| GWD
   GWD -->|Aligns documentation during macro work in| Fable["fable-mode / SKILL.md"]
   GWD -->|Triggers todo tasks tracked by| Todo["todo-driven-workflow / SKILL.md"]
+  GWD -->|Hands off to generate specifications| ToSpec["to-spec / SKILL.md"]
 ```
 
 ---

package/docs/workflows/harness-everything.md

@@ -1,92 +1,95 @@
-# Workflow: Harness Everything
-
-> The single entry point and dynamic router of Harness OS, triaging tasks into appropriate tiers and auto-loading synergistic knowledge guides.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `harness-everything` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([User Prompt Received]) --> ExecuteRouter["Execute tier-router.js OR check UserPromptSubmit hook output"]
-  ExecuteRouter --> DetectNewFeature{Contains new logic/files?}
-  DetectNewFeature -->|Yes, enforce Tier 2+| PreventDegrade["Prevent Silent Degrade to Tier 1"]
-  PreventDegrade --> TriageTier
-  DetectNewFeature -->|No| TriageTier{Triage Tier}
-  
-  TriageTier -->|Tier 1: Trivial| Tier1Route["Tier 1: Direct Edit No Checklist"]
-  TriageTier -->|Tier 2: Standard| Tier2Route["Tier 2: TDD & Todo-driven work"]
-  TriageTier -->|Tier 3: Macro| Tier3Route["Tier 3: Fable Planning & Agent Scaffolding"]
-  
-  Tier1Route --> LoadGuides["Auto-load & output Synergistic Guides"]
-  Tier2Route --> LoadGuides
-  Tier3Route --> LoadGuides
-  
-  LoadGuides --> FactCheck{External Claims / Estimates?}
-  FactCheck -->|Yes| FactReminder["Append Fact-Audit Reminder"]
-  FactCheck -->|No| FinalizeOutput["Finalize Routing Checkpoint Output"]
-  FactReminder --> FinalizeOutput
-  FinalizeOutput --> Normalization["Apply Always-On ADHD-Friendly Output Shaping (Global Normalization)"]
-  Normalization --> End([Developer receives highly focused, concise response])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `harness-everything` 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
-  UserPrompt([User Input]) --> Router["harness-everything / tier-router.js"]
-  
-  Router -->|Keyword Matches| Guides["Synergistic Workflow Guides"]
-  
-  Guides -->|TDD/Test/Bug| Ch1["tdd + environment-detection + verify-before-claim + verification-loop"]
-  Guides -->|Git/Commit/PR| Ch2["git-commit + rewrite-commits + using-git-worktrees + verification-loop"]
-  Guides -->|Agent/Fable/Macro| Ch3["fable-mode + fable-discipline + build-multi-agent-system + create-agent-launcher"]
-  Guides -->|Refactor/Architecture| Ch4["improve-codebase-architecture + grill-with-docs + grill-me + fable-mode"]
-  
-  Ch1 --> ADHD["Always-On ADHD-Friendly Output Shaping (Global Normalization)"]
-  Ch2 --> ADHD
-  Ch3 --> ADHD
-  Ch4 --> ADHD
-  
-  style Router fill:#d35400,stroke:#e67e22,stroke-width:2px,color:#ffffff
-  style ADHD fill:#1abc9c,stroke:#16a085,stroke-width:2px,color:#ffffff
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `harness-everything` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Input1["User: 'Add a new settings page'"] --> Router1["tier-router.js executes"]
-  Router1 --> TrapCheck["Trap Avoided: Feature request correctly blocked from Tier 1 degrade"]
-  TrapCheck --> Triage2["Triaged as Tier 2: Standard Task"]
-  Triage2 --> DomainSummon["Load 'tdd' & frontend Domain Experts"]
-  DomainSummon --> BaseLoop["Initialize 'todo-driven-workflow' checklist"]
-  BaseLoop --> VerifyGate["Complete feature & run 'verification-loop' pre-delivery gate"]
-  VerifyGate --> Done1([Feature delivered safely with proof])
-  
-  Input2["User: 'Refactor DB architecture and grill my plan'"] --> Router2["tier-router.js executes"]
-  Router2 --> Triage3["Triaged as Tier 3: Macro Task"]
-  Triage3 --> RecGuides["Auto-load: improve-codebase-architecture, grill-with-docs, fable-mode"]
-  RecGuides --> Process["Developer completes Grilling session to finalize ADRs"]
-  Process --> Execute["fable-mode generates execution checklist & spawns sub-agents"]
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `harness-everything` 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: Harness Everything
+
+> The single entry point and dynamic router of Harness OS, triaging tasks into appropriate tiers and auto-loading synergistic knowledge guides.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `harness-everything` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([User Prompt Received]) --> CheckSoftware{Software / Engineering Task?}
+  CheckSoftware -->|No: Pure Chat / Translation / Web Search| BypassHarness["Bypass Harness OS Completely - Reply Directly"]
+  CheckSoftware -->|Yes: Code / Architecture / Project| ExecuteRouter["Execute tier-router.js OR check UserPromptSubmit hook output"]
+  ExecuteRouter --> DetectNewFeature{Contains new logic/files?}
+  DetectNewFeature -->|Yes, enforce Tier 2+| PreventDegrade["Prevent Silent Degrade to Tier 1"]
+  PreventDegrade --> TriageTier
+  DetectNewFeature -->|No| TriageTier{Triage Tier}
+  
+  TriageTier -->|Tier 1: Trivial| Tier1Route["Tier 1: Direct Edit No Checklist"]
+  TriageTier -->|Tier 2: Standard| Tier2Route["Tier 2: TDD & Todo-driven work"]
+  TriageTier -->|Tier 3: Macro| Tier3Route["Tier 3: Fable Planning & Agent Scaffolding"]
+  
+  Tier1Route --> LoadGuides["Auto-load & output Synergistic Guides"]
+  Tier2Route --> LoadGuides
+  Tier3Route --> LoadGuides
+  
+  LoadGuides --> FactCheck{External Claims / Estimates?}
+  FactCheck -->|Yes| FactReminder["Append Fact-Audit Reminder"]
+  FactCheck -->|No| FinalizeOutput["Finalize Routing Checkpoint Output"]
+  FactReminder --> FinalizeOutput
+  FinalizeOutput --> Normalization["Apply Always-On ADHD-Friendly Output Shaping (Global Normalization)"]
+  Normalization --> End([Developer receives highly focused, concise response])
+  BypassHarness --> End
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `harness-everything` 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
+  UserPrompt([User Input]) --> Router["harness-everything / tier-router.js"]
+  
+  Router -->|Keyword Matches| Guides["Synergistic Workflow Guides"]
+  
+  Guides -->|TDD/Test/Bug| Ch1["tdd + environment-detection + verify-before-claim + verification-loop"]
+  Guides -->|Git/Commit/PR| Ch2["git-commit + rewrite-commits + using-git-worktrees + verification-loop"]
+  Guides -->|Agent/Fable/Macro| Ch3["fable-mode + fable-discipline + multi-agent-workspace"]
+  Guides -->|Refactor/Architecture| Ch4["improve-codebase-architecture + grill-with-docs + grill-me + fable-mode"]
+  
+  Ch1 --> ADHD["Always-On ADHD-Friendly Output Shaping (Global Normalization)"]
+  Ch2 --> ADHD
+  Ch3 --> ADHD
+  Ch4 --> ADHD
+  
+  style Router fill:#d35400,stroke:#e67e22,stroke-width:2px,color:#ffffff
+  style ADHD fill:#1abc9c,stroke:#16a085,stroke-width:2px,color:#ffffff
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `harness-everything` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Input1["User: 'Add a new settings page'"] --> Router1["tier-router.js executes"]
+  Router1 --> TrapCheck["Trap Avoided: Feature request correctly blocked from Tier 1 degrade"]
+  TrapCheck --> Triage2["Triaged as Tier 2: Standard Task"]
+  Triage2 --> DomainSummon["Load 'tdd' & frontend Domain Experts"]
+  DomainSummon --> BaseLoop["Initialize 'todo-driven-workflow' checklist"]
+  BaseLoop --> VerifyGate["Complete feature & run 'verification-loop' pre-delivery gate"]
+  VerifyGate --> Done1([Feature delivered safely with proof])
+  
+  Input2["User: 'Refactor DB architecture and grill my plan'"] --> Router2["tier-router.js executes"]
+  Router2 --> Triage3["Triaged as Tier 3: Macro Task"]
+  Triage3 --> RecGuides["Auto-load: improve-codebase-architecture, grill-with-docs, fable-mode"]
+  RecGuides --> Process["Developer completes Grilling session to finalize ADRs"]
+  Process --> Execute["fable-mode generates execution checklist & spawns sub-agents"]
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `harness-everything` 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/improve-codebase-architecture.md

@@ -10,13 +10,21 @@ This section visualizes how the `improve-codebase-architecture` skill executes i
 
 ```mermaid
 graph TD
-  Start([Audit Request / Refactoring]) --> ScanDirectories["Scan code directories for coupling"]
-  ScanDirectories --> IdentifyTightlyCoupled["Locate highly coupled modules / wide files"]
-  IdentifyTightlyCoupled --> DeepModuleTest["Analyze modules against Deep Module Design rules"]
-  DeepModuleTest --> DefineSeams["Identify clean seams & write interface abstractions"]
-  DefineSeams --> GenMermaidReport["Generate visual HTML / Mermaid codebase dependency map"]
-  GenMermaidReport --> ProposeDecomposition["Formulate restructuring and extraction proposal"]
-  ProposeDecomposition --> End([Actionable refactoring strategy compiled])
+  Start([Audit Request / Refactoring / SRP Object Splitting]) --> ScanDirectories["Scan code directories, CONTEXT.md & ADRs"]
+  ScanDirectories --> IdentifyTarget["Identify Monolithic Objects (>300 lines) or Shallow Modules"]
+  IdentifyTarget --> FormulatePlan["Formulate Deepening & SRP Object Extraction Plan"]
+  FormulatePlan --> Propose["Present Deepening & SRP Proposal to User"]
+  Propose --> UserApproved{"User Approves Proposal?"}
+  
+  UserApproved -->|Yes| CheckTests{"Existing Test Safety Net Present?"}
+  UserApproved -->|No| AdjustPlan["Adjust Proposal Scope"] --> Propose
+  
+  CheckTests -->|No Tests| WriteCharTests["Write Characterization Tests First"] --> ExecuteTDD
+  CheckTests -->|Tests Present| ExecuteTDD["Execute Object Extraction via TDD"]
+  
+  ExecuteTDD --> CheckErrors{"Cascading Errors > 3?"}
+  CheckErrors -->|Yes| Rollback["Rollback Changes & Trigger zoom-out"]
+  CheckErrors -->|No| Complete["Refactoring Complete & Record Lessons in self-evolve"]
 ```
 
 ---

package/docs/workflows/install-cognitive-os.md

@@ -1,60 +1,60 @@
-# Workflow: Install Cognitive OS
-
-> Automates the installation of the Agent Cognitive Loop (Think > Try > Summarize > Record) into the user's active workspace and environment configs.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `install-cognitive-os` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([Bootstrap Hook Triggered]) --> DetectTargetEnv["Scan for active IDE / Client config paths"]
-  DetectTargetEnv --> InjectAdvisoryRules["Append advisory rules to .cursorrules, .github/copilot-instructions.md, or AGENTS.md"]
-  InjectAdvisoryRules --> InstallHooks["Configure Claude Code settings.json hook pre-flights"]
-  InstallHooks --> DeployScripts["Deploy core bootstrap.js, self-heal.js, and tier-router.js scripts"]
-  DeployScripts --> RunVerification["Execute self-heal audit test to confirm platform integrations"]
-  RunVerification --> End([Harness cognitive guardrails fully established])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `install-cognitive-os` 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
-  BootstrapCmd["Bootstrap CLI Command / npm install"] --> InstallSkill["install-cognitive-os / SKILL.md"]
-  InstallSkill -->|Deploys core router script| Router["harness-everything / scripts / tier-router.js"]
-  InstallSkill -->|Establishes memory loop configs for| Evolve["self-evolve / SKILL.md"]
-  InstallSkill -->|Guards all file edits using| Todo["todo-driven-workflow / SKILL.md"]
-  InstallSkill -->|Enforces Always-On Normalization for all responses| ADHD["Always-On ADHD-Friendly Output Shaping"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `install-cognitive-os` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Fresh repository checkout"] --> Trigger["Run 'node scripts/installer.js install --all --yes'"]
-  Trigger --> Scan["Detects Cursor editor rules and GitHub action configurations"]
-  Scan --> BuildAdvisory["Appends mandatory routing checkpoint and cognitive compliance blocks to .cursorrules"]
-  BuildAdvisory --> CopySkills["Copies all 23 core skills into .cursor/skills/ and .github/skills/"]
-  CopySkills --> CheckHeal["Runs preflight audit to confirm 100% path coverage"]
-  CheckHeal --> Done([Harness OS environment setup is complete and active])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `install-cognitive-os` 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: Install Cognitive OS
+
+> Automates the installation of the Agent Cognitive Loop (Think > Try > Summarize > Record) into the user's active workspace and environment configs.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `install-cognitive-os` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Bootstrap Hook Triggered]) --> DetectTargetEnv["Scan for active IDE / Client config paths"]
+  DetectTargetEnv --> InjectAdvisoryRules["Append advisory rules to .cursorrules, .github/copilot-instructions.md, or AGENTS.md"]
+  InjectAdvisoryRules --> InstallHooks["Configure Claude Code settings.json hook pre-flights"]
+  InstallHooks --> DeployScripts["Deploy core bootstrap.js, self-heal.js, and tier-router.js scripts"]
+  DeployScripts --> RunVerification["Execute self-heal audit test to confirm platform integrations"]
+  RunVerification --> End([Harness cognitive guardrails fully established])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `install-cognitive-os` 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
+  BootstrapCmd["Bootstrap CLI Command / npm install"] --> InstallSkill["install-cognitive-os / SKILL.md"]
+  InstallSkill -->|Deploys core router script| Router["harness-everything / scripts / tier-router.js"]
+  InstallSkill -->|Establishes memory loop configs for| Evolve["self-evolve / SKILL.md"]
+  InstallSkill -->|Guards all file edits using| Todo["todo-driven-workflow / SKILL.md"]
+  InstallSkill -->|Enforces Always-On Normalization for all responses| ADHD["Always-On ADHD-Friendly Output Shaping"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `install-cognitive-os` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Fresh repository checkout"] --> Trigger["Run 'node scripts/installer.js install --all --yes'"]
+  Trigger --> Scan["Detects Cursor editor rules and GitHub action configurations"]
+  Scan --> BuildAdvisory["Appends mandatory routing checkpoint and cognitive compliance blocks to .cursorrules"]
+  BuildAdvisory --> CopySkills["Copies all current skills into .cursor/skills/ and .github/skills/"]
+  CopySkills --> CheckHeal["Runs preflight audit to confirm 100% path coverage"]
+  CheckHeal --> Done([Harness OS environment setup is complete and active])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `install-cognitive-os` 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/multi-agent-workspace.md

@@ -0,0 +1,42 @@
+# Workflow: Multi-Agent Workspace
+
+`multi-agent-workspace` is the single routed entrypoint for permanent
+multi-agent infrastructure. It combines the former launcher and workspace
+scaffold responsibilities and adds an optional agency-agents metadata source.
+
+```text
+Discover target + source
+        |
+Validate divisions, frontmatter, names, slugs, revision, platform
+        |
+Scaffold .harness/multi-agent/
+  state / logs / decisions / domain / architecture / roles
+        |
+Write router + catalog + selected roles + launcher + handoff
+        |
+Run generated index_memory.js -> memory-index.md
+```
+
+## Selection contract
+
+Use `--agency-source <path>` or `AGENCY_AGENTS_SOURCE`. Select by repeated
+`--division` or `--agent`; `--all-agents` is explicit and metadata-only. The
+generated launcher lists each selected role's division, source-relative file,
+description, and boundary. Specialist bodies are loaded only on demand after a
+bounded brief is assigned.
+
+## Failure contract
+
+No source creates a visible `agency.status: unavailable` fallback. Invalid
+frontmatter, missing or empty divisions, duplicate names/slugs, unknown
+agents, and unsupported platforms fail before output is written. A changed
+source revision requires `--allow-source-drift` to refresh a Harness-owned
+catalog. Existing generated artifacts require `--force` only when they are
+not identical.
+
+## Handoff
+
+The launcher and `handoff.json` require `status`, `changes`, `verification`,
+`risks`, and `nextAction`. The immutable generated router directs agents to
+the six zones and forbids router edits. Fable remains responsible for macro
+planning; TDD remains responsible for ordinary feature implementation.

package/docs/workflows/repo-docs.md

@@ -10,13 +10,18 @@ This section visualizes how the `repo-docs` skill executes internally, detailing
 
 ```mermaid
 graph TD
-  Start([Generate Repository Docs]) --> AuditProjectStructure["Audit workspace directory tree"]
-  AuditProjectStructure --> ClassifyProductArchetype["Classify repository archetype: tool, library, platform"]
+  Start([Generate / Update Repository Docs]) --> AuditProjectStructure["Audit workspace directory tree & build configs"]
+  AuditProjectStructure --> CheckExisting{Existing README / AGENTS File Found?}
+  
+  CheckExisting -->|Yes| ReadOld["Read Existing File & Extract Bespoke Notes (env vars, URLs, gotchas)"]
+  CheckExisting -->|No| ClassifyProductArchetype["Classify repository archetype"]
+  
+  ReadOld --> ClassifyProductArchetype
   ClassifyProductArchetype --> LoadTemplates["Load standard README and AGENTS templates"]
-  LoadTemplates --> InjectCustomStructure["Populate files with actual paths, licenses, and badges"]
-  InjectCustomStructure --> FormatMarkdown["Format documents following clean layout rules"]
-  FormatMarkdown --> WriteFiles["Commit README.md and AGENTS.md to workspace root"]
-  WriteFiles --> End([Professional onboarding documentation created])
+  LoadTemplates --> SmartMerge["Smartly Merge Codebase Facts + Bespoke Notes + Template Structure"]
+  SmartMerge --> FormatMarkdown["Format documents following clean layout rules"]
+  FormatMarkdown --> WriteFiles["Save / Merge README.md and AGENTS.md at Root or .github/"]
+  WriteFiles --> End([Professional onboarding documentation created without losing history])
 ```
 
 ---
@@ -28,7 +33,7 @@ This diagram illustrates how the `repo-docs` skill is triggered through user req
 ```mermaid
 graph LR
   Router["harness-everything / tier-router.js"] -->|Keyword: doc / readme / agents-template| RepoDocs["repo-docs / SKILL.md"]
-  RepoDocs -->|Integrates frontmatter constraints into| BMAS["build-multi-agent-system / SKILL.md"]
+  RepoDocs -->|Integrates frontmatter constraints into| BMAS["multi-agent-workspace / SKILL.md"]
   RepoDocs -->|Leverages ADR details generated in| GWD["grill-with-docs / SKILL.md"]
 ```
 

package/docs/workflows/security-review.md

@@ -10,13 +10,32 @@ This section visualizes how the `security-review` skill executes internally, det
 
 ```mermaid
 graph TD
-  Start([Code Refactoring / Feature Done]) --> ScanInputs["Locate all user input and API boundary points"]
-  ScanInputs --> ThreatModeling["Perform threat modeling on data flow"]
-  ThreatModeling --> CheckCommonVulnerabilities["Check for SQL Injection, XSS, CSRF, and broken access controls"]
-  CheckCommonVulnerabilities --> AuditDependencies["Scan package dependencies for known CVE vulnerabilities"]
-  AuditDependencies --> FlagSinks["Flag insecure coding patterns, hardcoded secrets, or raw exec commands"]
-  FlagSinks --> CompileSecurityReport["Compile actionable security hardening proposal"]
-  CompileSecurityReport --> End([Codebase hardened and verified secure])
+  Start([Code Refactoring / Feature Done / Security Audit]) --> STRIDE["1. STRIDE Threat Modeling & Abuse Case Design"]
+  STRIDE --> CheckScript{2. Is audit-secrets.js Executable?}
+  
+  CheckScript -->|Yes| RunAudit["Run node security-review/scripts/audit-secrets.js"]
+  CheckScript -->|No / Fails| GrepFallback["Scan Workspace Secrets & Inputs via grep_search"]
+  
+  RunAudit --> CheckVun{3. Detect Vulnerabilities or Leaks?}
+  GrepFallback --> CheckVun
+  
+  CheckVun -->|Hardcoded Secrets| FixSecrets["Always Do: Refactor to process.env & .env.local"]
+  CheckVun -->|SQL Concatenation| FixSQL["Always Do: Refactor to Parameterized Queries / ORM"]
+  CheckVun -->|Unvalidated Input| FixInput["Always Do: Add Zod Schema Validation"]
+  CheckVun -->|High-Risk Auth Shift| AskUser["Ask First: Require User Approval for Auth Shift"]
+  
+  FixSecrets --> CompileSecurityReport["4. Compile Security Audit Report"]
+  FixSQL --> CompileSecurityReport
+  FixInput --> CompileSecurityReport
+  AskUser -->|Approved| CompileSecurityReport
+  CheckVun -->|Clean| CompileSecurityReport
+  
+  CompileSecurityReport --> ResolveReportPath{5. Resolve Audit Report Path}
+  ResolveReportPath -->|docs/ Exists| WriteDocs["Save to docs/security-audit.md"]
+  ResolveReportPath -->|Protected / No Folder| WritePlatform["Save to .github/harness-everything/security-audit.md"]
+  
+  WriteDocs --> End([Codebase hardened and verified secure])
+  WritePlatform --> End
 ```
 
 ---