harness-everything 0.2.1 → 0.3.6

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

@@ -1,62 +1,69 @@
-# Workflow: Grill with Docs
-
-> Decision tracking, Glossary alignment, and ADR-driven (Architecture Decision Record) grilling to eliminate technical drift between code and documentation.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `grill-with-docs` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([Plan Proposed against Domain]) --> ReadDomainModel["Read CONTEXT.md and existing ADRs"]
-  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])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `grill-with-docs` 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: adr / decision / glossary| GWD["grill-with-docs / SKILL.md"]
-  GWD -->|Coordinates stress-tests using| GrillMe["grill-me / SKILL.md"]
-  GWD -->|Aligns documentation during macro work in| Fable["fable-mode / SKILL.md"]
-  GWD -->|Triggers todo tasks tracked by| Todo["todo-driven-workflow / SKILL.md"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `grill-with-docs` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Requirement: Change notification retry rate limits"] --> Trigger["grill-with-docs skill invoked"]
-  Trigger --> ReadDocs["Analyzes docs/adr/003-rate-limiting.md"]
-  ReadDocs --> CheckDrift["Finds that proposed change violates the maximum overload protection limit"]
-  CheckDrift --> RefinePlan["Plan updated to stay within the 003-rate-limiting contract"]
-  RefinePlan --> CreateADR["Create docs/adr/008-notification-retries.md"]
-  CreateADR --> SyncCode["Modify code and inject aligned TODO tags directly in code to maintain truth"]
-  SyncCode --> Done([Zero architectural drift achieved])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `grill-with-docs` 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: Grill with Docs
+
+> Decision tracking, Glossary alignment, and ADR-driven (Architecture Decision Record) grilling to eliminate technical drift between code and documentation.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `grill-with-docs` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  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 --> 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])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `grill-with-docs` 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: adr / decision / glossary| GWD["grill-with-docs / 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"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `grill-with-docs` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Requirement: Change notification retry rate limits"] --> Trigger["grill-with-docs skill invoked"]
+  Trigger --> ReadDocs["Analyzes docs/adr/003-rate-limiting.md"]
+  ReadDocs --> CheckDrift["Finds that proposed change violates the maximum overload protection limit"]
+  CheckDrift --> RefinePlan["Plan updated to stay within the 003-rate-limiting contract"]
+  RefinePlan --> CreateADR["Create docs/adr/008-notification-retries.md"]
+  CreateADR --> SyncCode["Modify code and inject aligned TODO tags directly in code to maintain truth"]
+  SyncCode --> Done([Zero architectural drift achieved])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `grill-with-docs` 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/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

@@ -1,60 +1,68 @@
-# Workflow: Improve Codebase Architecture
-
-> Finds deepening opportunities in the codebase, consolidating tightly-coupled modules and mapping dependencies visually using Mermaid diagram reports.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `improve-codebase-architecture` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```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])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `improve-codebase-architecture` 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: refactor / architecture / couple| ICA["improve-codebase-architecture / SKILL.md"]
-  ICA -->|Deductions challenged by SRE via| GrillMe["grill-me / SKILL.md"]
-  ICA -->|Guides large-scale structural rewrites in| Fable["fable-mode / SKILL.md"]
-  ICA -->|Extracts interfaces to simplify unit tests in| TDD["tdd / SKILL.md"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `improve-codebase-architecture` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Monolithic file 'utils.js' handles email, token creation, DB pooling, and logging"] --> Trigger["improve-codebase-architecture skill analyzed"]
-  Trigger --> Audit["Analyzes dependency graphs and calculates coupling scores"]
-  Audit --> FindSeams["Identifies three distinct interfaces: IEmailService, ITokener, IDbPool"]
-  FindSeams --> GenMermaid["Output detailed Mermaid diagram visualizing the proposed separated structure"]
-  GenMermaid --> RefactorPlan["Drafts multi-stage module extraction plan"]
-  RefactorPlan --> Done([Clear, modular architectural blueprint established])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `improve-codebase-architecture` 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: Improve Codebase Architecture
+
+> Finds deepening opportunities in the codebase, consolidating tightly-coupled modules and mapping dependencies visually using Mermaid diagram reports.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `improve-codebase-architecture` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  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"]
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `improve-codebase-architecture` 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: refactor / architecture / couple| ICA["improve-codebase-architecture / SKILL.md"]
+  ICA -->|Deductions challenged by SRE via| GrillMe["grill-me / SKILL.md"]
+  ICA -->|Guides large-scale structural rewrites in| Fable["fable-mode / SKILL.md"]
+  ICA -->|Extracts interfaces to simplify unit tests in| TDD["tdd / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `improve-codebase-architecture` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Monolithic file 'utils.js' handles email, token creation, DB pooling, and logging"] --> Trigger["improve-codebase-architecture skill analyzed"]
+  Trigger --> Audit["Analyzes dependency graphs and calculates coupling scores"]
+  Audit --> FindSeams["Identifies three distinct interfaces: IEmailService, ITokener, IDbPool"]
+  FindSeams --> GenMermaid["Output detailed Mermaid diagram visualizing the proposed separated structure"]
+  GenMermaid --> RefactorPlan["Drafts multi-stage module extraction plan"]
+  RefactorPlan --> Done([Clear, modular architectural blueprint established])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `improve-codebase-architecture` 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/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.