harness-everything 0.2.0

package/docs/workflows/harness-everything.md

@@ -0,0 +1,92 @@
+# 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.

package/docs/workflows/improve-codebase-architecture.md

@@ -0,0 +1,60 @@
+# 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.

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

@@ -0,0 +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.

package/docs/workflows/repo-docs.md

@@ -0,0 +1,59 @@
+# Workflow: Repo Docs
+
+> Generates high-quality, professional README.md and AGENTS.md files based on actual workspace structures and product-archetype templates.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `repo-docs` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Generate Repository Docs]) --> AuditProjectStructure["Audit workspace directory tree"]
+  AuditProjectStructure --> ClassifyProductArchetype["Classify repository archetype: tool, library, platform"]
+  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])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `repo-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: doc / readme / agents-template| RepoDocs["repo-docs / SKILL.md"]
+  RepoDocs -->|Integrates frontmatter constraints into| BMAS["build-multi-agent-system / SKILL.md"]
+  RepoDocs -->|Leverages ADR details generated in| GWD["grill-with-docs / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `repo-docs` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["New library lacks onboarding docs and setup details"] --> Trigger["repo-docs skill invoked"]
+  Trigger --> Scan["Scans folders: discovers it's a TypeScript utility package"]
+  Scan --> MatchTemplate["Loads library archetype README template"]
+  MatchTemplate --> GenDocs["Outputs README.md with TypeScript usage examples, badges, and structure"]
+  GenDocs --> GenOnboarding["Outputs AGENTS.md defining the developer agent rules for the repo"]
+  GenOnboarding --> Done([Clean, standardized documentation committed])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `repo-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/rewrite-commits.md

@@ -0,0 +1,60 @@
+# Workflow: Rewrite Commits
+
+> Safely rewrites or squashes a specified range of commits into highly professional, Conventional Commits (Angular style) on a new branch.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `rewrite-commits` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Define Commit Range]) --> BackupBranch["Create a backup branch of current state"]
+  BackupBranch --> ReadCommits["Read all commit messages in the range"]
+  ReadCommits --> AnalyzeDiffs["Read files & diffs associated with each commit"]
+  AnalyzeDiffs --> GenNewMessages["Generate high-quality Angular-style messages for each diff"]
+  GenNewMessages --> SoftReset["Execute git reset --soft to merge range changes"]
+  SoftReset --> ReapplyCommits["Re-apply changes with perfectly clean, segmented commit history"]
+  ReapplyCommits --> VerifyBranch["Run verification checks on the final rebuilt branch"]
+  VerifyBranch --> End([Perfectly clean Git history on new branch])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `rewrite-commits` 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 / rewrite / squash| Rewrite["rewrite-commits / SKILL.md"]
+  Rewrite -->|Supplements convention templates in| GitCommit["git-commit / SKILL.md"]
+  Rewrite -->|Pre-verify rewritten commits via| VerLoop["verification-loop / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `rewrite-commits` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Branch has messy commits: 'fixed stuff', 'more fixes', 'bug'"] --> Trigger["Rewrite-commits skill run for HEAD~3"]
+  Trigger --> Backup["Backup branch 'backup-feature-x' created"]
+  Trigger --> GatherDiffs["Analyze total diff across the 3 messy commits"]
+  GatherDiffs --> Generate完美["Determine changes relate to user auth session handling"]
+  Generate完美 --> Rebuild["Reset and make 1 perfect commit: 'fix(auth): correct token refresh race condition'"]
+  Rebuild --> Done([Clean, reviewable PR history ready])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `rewrite-commits` 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/security-review.md

@@ -0,0 +1,58 @@
+# Workflow: Security Review
+
+> Automated security scanning, threat modeling, and input-validation reviews to identify potential security holes and enforce robust safety guardrails.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `security-review` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```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])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `security-review` 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 / Quality PR reviews| SecReview["security-review / SKILL.md"]
+  SecReview -->|Informs security tests written in| TDD["tdd / SKILL.md"]
+  SecReview -->|Integrated as mandatory PR gate in| VerLoop["verification-loop / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `security-review` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["New search feature: executes system shell query using raw user input string"] --> Trigger["security-review skill runs"]
+  Trigger --> Scan["Flags potential command injection vulnerability in search.js"]
+  Scan --> Propose["Propose input sanitization and switching to child_process.execFile with argument array"]
+  Propose --> Implement["Refactor code to use safe argument arrays instead of raw string shell execution"]
+  Implement --> Done([Critical remote code execution vulnerability resolved])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `security-review` 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/self-evolve.md

@@ -0,0 +1,59 @@
+# Workflow: Self-Evolve
+
+> Analyzes execution logs and session memories to extract underlying root causes, defining new error boundaries and compressing them into cognitive guardrails.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `self-evolve` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Task Completed / Error Loop Triggered]) --> ReadSessionLogs["Read active debugging logs & session history"]
+  ReadSessionLogs --> IdentifyRootCauses["Isolate and extract system failures or bottlenecks"]
+  IdentifyRootCauses --> SynthesizeGuardrails["Formulate actionable high-level cognitive guardrails"]
+  SynthesizeGuardrails --> CompressMemories["Compress repetitive events into compact markdown files in /memories/"]
+  CompressMemories --> UpdateUserMemory["Commit lessons learned to user memory space"]
+  UpdateUserMemory --> End([Agent cognitive defense expanded for future sessions])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `self-evolve` 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
+  SessionEnd["Task Completed / Session Closed"] --> Evolve["self-evolve / SKILL.md"]
+  Evolve -->|Reads from| HistoryLog["VS Code Debug logs & memory directories"]
+  Evolve -->|Writes permanent updates to| UserMemory["/memories/ / user-memory files"]
+  Evolve -->|Informs future task triage in| Router["harness-everything / tier-router.js"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `self-evolve` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Session ends after solving a recurring, messy Windows path-slashes bug"] --> Trigger["self-evolve skill runs automatically"]
+  Trigger --> Analyze["Reads last 5 execution logs"]
+  Analyze --> DetectPattern["Finds 3 consecutive terminal command failures caused by path backslashes in PowerShell"]
+  DetectPattern --> Formulate["Formulate new guardrail: 'When on Windows, convert backslashes to forward slashes for cross-shell command lines'"]
+  Formulate --> Write["Write bullet point to /memories/debugging.md"]
+  Write --> Done([Memory recorded: future sessions will automatically avoid Windows path errors])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `self-evolve` 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/skill-creator.md

@@ -0,0 +1,75 @@
+# Workflow: Skill Creator
+
+> Authors, audits, and evolves SKILL.md files against a single quality bar — the Skill Contract format plus predictability/pruning/progressive-disclosure principles from external skill-writing research — and is the required gate for skills `self-evolve` generates dynamically.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `skill-creator` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([New skill request / existing SKILL.md to audit / self-evolve dynamic-generation call]) --> Intent["Capture intent: what it does, the one canonical description sentence, which Tier, does an existing skill already own this ground"]
+  Intent --> Draft["Draft: Skill Contract table first, then body sized by information hierarchy (steps vs flat reference vs guides/references)"]
+  Draft --> Test["Test 2-3 realistic prompts via create-agent-launcher: with-skill subagent vs baseline subagent"]
+  Test --> Checklist{"Quality Checklist (§3): SSOT, no duplication >5 lines, every MUST has a real gate, no no-ops, info hierarchy, leading words reused, checkable completion criteria, human-facing description"}
+  Checklist -->|Fails| Prune["Prune and rewrite the failing item"]
+  Prune --> Checklist
+  Checklist -->|Passes| Route{Static or dynamic?}
+  Route -->|Static| Register["Register: harness-everything §5 row + tier-router.js keyword line"]
+  Route -->|Dynamic, from self-evolve| DynamicContract["§4 Dynamic Skill Generation Contract: write to .claude/harness-everything/skills/generated/<name>/, metadata.type=dynamic, status=draft"]
+  Register --> End([Skill live in the repo, single source of truth for its own description])
+  DynamicContract --> End
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how `skill-creator` 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: skill / skill.md / new skill / write a skill| Creator["skill-creator / SKILL.md"]
+  Creator -->|Table shape spec| SkillStyle["skill-style / SKILL.md"]
+  Creator -->|With/without test subagents| Launcher["create-agent-launcher / SKILL.md"]
+  Creator -->|Registers new static skills into| Registry["harness-everything / SKILL.md §5"]
+  Evolve["self-evolve / SKILL.md §4"] -->|MUST load before packaging a session insight| Creator
+  Creator -->|Writes dynamic skills to| Generated[".claude/harness-everything/skills/generated/"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `skill-creator` skill, illustrating standard success paths, error handling, or recovery loops — one for a human-directed static skill, one for `self-evolve`'s dynamic path.
+
+```mermaid
+graph TD
+  Start1["Developer: 'I want a skill for deploying to AWS'"] --> Intent1["skill-creator §2 Step 1: capture intent, one canonical description sentence"]
+  Intent1 --> Draft1["Draft Skill Contract table + steps, push detail to deploy-aws/guides/"]
+  Draft1 --> Test1["Spawn with/without subagents via create-agent-launcher on 2-3 realistic prompts"]
+  Test1 --> Check1{Quality Checklist passes?}
+  Check1 -->|No| Fix1["Fix flagged item, re-test"]
+  Fix1 --> Check1
+  Check1 -->|Yes| Reg1["Add row to harness-everything §5 + one line to tier-router.js"]
+  Reg1 --> Done1([deploy-aws/SKILL.md live as a static, reviewed skill])
+
+  Start2["zoom-out recovery ends: root cause found for a recurring connection-pool exhaustion bug"] --> Trigger2["self-evolve §3 Step 3: Dynamic Skill Generation"]
+  Trigger2 --> Load2["self-evolve MUST load skill-creator §4 before writing anything"]
+  Load2 --> Gate2{Quality Checklist §3 passes?}
+  Gate2 -->|No| Reject2["Do not persist — this checklist is the only review a dynamic skill gets"]
+  Gate2 -->|Yes| Write2["Write .claude/harness-everything/skills/generated/orm-transaction-batching/SKILL.md, metadata.type=dynamic, status=draft"]
+  Write2 --> Done2([Dynamic skill available next session, lifecycle tracked separately from static skills])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `skill-creator` 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/skill-style.md

@@ -0,0 +1,64 @@
+# Workflow: Skill Style
+
+> Guidelines and style rules for authoring, refactoring, and maintaining SKILL.md files to enforce clean frontmatter and logical boundaries.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `skill-style` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Authoring / Editing a SKILL.md]) --> ParseFrontmatter["Parse and validate YAML Frontmatter: name, description"]
+  ParseFrontmatter --> ValidateBoundary["Check for explicit physical boundaries & state checkpoints"]
+  ValidateBoundary --> VerifyCognitiveLoop["Verify integration with Cognitive Loop laws"]
+  VerifyCognitiveLoop --> CheckFormatting["Ensure clean markdown layout and bullet-style rules"]
+  CheckFormatting --> FormatApproved{Complies with STYLE.md?}
+  FormatApproved -->|No| FixSkillFile["Refactor and clean file formatting"]
+  FormatApproved -->|Yes| SaveSkillFile["Commit clean, validated SKILL.md"]
+  FixSkillFile --> SaveSkillFile
+  SaveSkillFile --> End([Skill document aligned with professional guidelines])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how `skill-style` is reached — as of the `skill-creator` split, it is no longer the first stop. `tier-router.js`'s `/\bskill\b|skill\.md|new skill|write a skill/` match now recommends `skill-creator` first (the full authoring/audit/testing workflow) and `skill-style` second (the terse Skill Contract table shape it builds on) — see `harness-everything/scripts/tier-router.js`.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Keyword: skill / skill.md / new skill| Creator["skill-creator / SKILL.md"]
+  Creator -->|Builds on the table shape defined in| SkillStyle["skill-style / SKILL.md"]
+  SkillStyle -->|Audits format correctness of| OtherSkills["Any SKILL.md in the workspace"]
+  SkillStyle -->|Pre-PR validation gate integration| VerLoop["verification-loop / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+§1 already walks the linear audit steps for a single file. This section instead shows the case that motivated splitting `skill-creator` out of this skill in the first place: a developer who needs the *fuller* workflow, not just the table shape.
+
+```mermaid
+graph TD
+  Start["Developer: 'help me write a new skill for deploying to AWS'"] --> Router["tier-router.js recommends skill-creator + skill-style"]
+  Router --> Creator["skill-creator: capture intent, draft, test against real prompts (§2)"]
+  Creator --> StyleCheck["skill-style: does the draft's Skill Contract table match the required shape?"]
+  StyleCheck -->|Missing/malformed table| Fix["Fix table shape per skill-style, re-run skill-creator's Quality Checklist"]
+  StyleCheck -->|Table shape OK| Checklist["skill-creator §3 Quality Checklist: no-op / duplication / negation / progressive-disclosure checks"]
+  Fix --> Checklist
+  Checklist --> Register["Register in harness-everything §5 + tier-router.js (skill-creator §2 Step 4)"]
+  Register --> Done([deploy-aws/SKILL.md committed, consistent with the rest of the repo])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `skill-style` 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/tdd.md

@@ -0,0 +1,39 @@
+# Workflow: Test-Driven Development (TDD)
+
+> Enforces the classic Red-Green-Refactor development cycle. Crucially, this is NOT a linear process. It is a loop driven by terminal exit codes.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes the script-gated reality of TDD. The AI cannot progress to the next phase until the terminal script explicitly confirms the state.
+
+```mermaid
+graph TD
+  Start([Identify Feature / Bug]) --> DesignInterface["Design interface & contract"]
+  DesignInterface --> WriteTest["Write unit/integration tests first"]
+  
+  WriteTest --> RunRed["Try: Run tests (EXPECT FAILURE)"]
+  RunRed --> VerifyRed{Gate: Exit Code 1?}
+  VerifyRed -->|Exit 0: Fake Test| FixTest["Reflect: Test is broken/fake. Fix it."]
+  FixTest --> RunRed
+  
+  VerifyRed -->|Exit 1: True Red| WriteCode["Write minimal code to pass test"]
+  
+  WriteCode --> RunGreen["Try: Run tests (EXPECT SUCCESS)"]
+  RunGreen --> VerifyGreen{Gate: verify-gate.js}
+  
+  VerifyGreen -->|Exit 1: Still Broken| DebugCode["Reflect: Read logs, fix code"]
+  DebugCode --> RunGreen
+  VerifyGreen -->|Exit 1: 3x Failures| CircuitBreaker["Trigger rule-of-3.js: ZOOM OUT"]
+  CircuitBreaker --> DebugCode
+  
+  VerifyGreen -->|Exit 0: Green| Refactor["Refactor code for readability"]
+  
+  Refactor --> RunVerify["Try: Run tests again"]
+  RunVerify --> VerifyRefactor{Gate: verify-gate.js}
+  VerifyRefactor -->|Exit 1| Revert["Revert refactor / Fix"]
+  Revert --> RunVerify
+  
+  VerifyRefactor -->|Exit 0| End([Feature verified & completed])
+```