harness-everything 0.2.1 → 0.3.6

package/docs/workflows/eval-harness.md

@@ -1,57 +1,64 @@
-# Workflow: Eval Harness
-
-> Evaluates AI developer agent performance based on accuracy, resource efficiency, and anti-loop metrics.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `eval-harness` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([Agent Execution Finished]) --> CollectExecutionMetrics["Gather total elapsed time, token count, and API calls"]
-  CollectExecutionMetrics --> EvaluateAccuracy["Compare completed task output against baseline correctness requirements"]
-  EvaluateAccuracy --> AnalyzeLoops["Check for repetitive tool invocations or redundant edits"]
-  AnalyzeLoops --> CalculateScores["Calculate performance and efficiency scores"]
-  CalculateScores --> GenerateEvalReport["Compile formal evaluation report and dashboard metrics"]
-  GenerateEvalReport --> End([Performance metrics indexed and logged])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `eval-harness` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
-```mermaid
-graph LR
-  Router["harness-everything / tier-router.js"] -->|Analyzes performance metrics| EH["eval-harness / SKILL.md"]
-  EH -->|Synthesizes lessons learned for| Evolve["self-evolve / SKILL.md"]
-  EH -->|Detects error loops triggering| ZoomOut["zoom-out / SKILL.md"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `eval-harness` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Agent session finishes implementing a complete backend server"] --> Trigger["eval-harness skill executed"]
-  Trigger --> Gather["Collects: 15 minutes elapsed, 32 tool calls, 45,000 tokens consumed"]
-  Gather --> Score["Scores: Correctness 10/10, Resource Efficiency 9/10, Anti-loop 10/10"]
-  Score --> Output["Generates benchmark report summarizing optimal execution speed and zero looping errors"]
-  Output --> Done([Benchmark logged for project history])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `eval-harness` skill is operating in strict compliance with Harness OS design laws, verify the following:
-
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+# Workflow: Eval Harness
+
+> Evaluates AI developer agent performance based on accuracy, resource efficiency, and anti-loop metrics.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `eval-harness` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Trigger: Benchmark / Evaluate Log]) --> ParseLog["1. Parse Log: Actions, Error Loops, Token Indicator"]
+  ParseLog --> CalcRubric["2. Calculate Scores across 4 Dimensions (0-10)"]
+  CalcRubric --> CheckScript{3. Is evaluate.js Executable?}
+  
+  CheckScript -->|Yes| RunScript["Run node eval-harness/scripts/evaluate.js"]
+  CheckScript -->|No / Fails| FileFallback{"4. Markdown File Fallback"}
+  
+  FileFallback -->|evals/ Exists| WriteEvals["Save Scorecard to evals/scorecard.md"]
+  FileFallback -->|No evals/ Folder| WritePlatform["Save Scorecard to .github/harness-everything/evals/scorecard.md"]
+  
+  RunScript --> End([Evaluation Scorecard Logged])
+  WriteEvals --> End
+  WritePlatform --> End
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `eval-harness` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Analyzes performance metrics| EH["eval-harness / SKILL.md"]
+  EH -->|Synthesizes lessons learned for| Evolve["self-evolve / SKILL.md"]
+  EH -->|Detects error loops triggering| ZoomOut["zoom-out / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `eval-harness` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Agent session finishes implementing a complete backend server"] --> Trigger["eval-harness skill executed"]
+  Trigger --> Gather["Collects: 15 minutes elapsed, 32 tool calls, 45,000 tokens consumed"]
+  Gather --> Score["Scores: Correctness 10/10, Resource Efficiency 9/10, Anti-loop 10/10"]
+  Score --> Output["Generates benchmark report summarizing optimal execution speed and zero looping errors"]
+  Output --> Done([Benchmark logged for project history])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `eval-harness` skill is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
+- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
+- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.

package/docs/workflows/fable-discipline.md

@@ -1,59 +1,59 @@
-# Workflow: Fable Discipline
-
-> Shadow guard for fable-mode preventing context bloat, enforcing physical boundaries, and tracking token burn metrics.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `fable-discipline` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([Fable Task Initiated]) --> AuditContext["Audit total file lengths in current context"]
-  AuditContext --> CheckTokenLimit{Tokens exceeding budget?}
-  CheckTokenLimit -->|Yes| TrimContext["Evict raw logs, completed tasks, and non-essential file contents"]
-  CheckTokenLimit -->|No| KeepState["Continue monitoring context state"]
-  TrimContext --> EnforceLimit["Enforce physical boundary guidelines"]
-  KeepState --> EnforceLimit
-  EnforceLimit --> LogMetrics["Track token utilization and distillation loops"]
-  LogMetrics --> End([Context maintained under safe, high-attention limits])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `fable-discipline` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
-```mermaid
-graph LR
-  Fable["fable-mode / SKILL.md"] -->|Monitors context on every turn| FD["fable-discipline / SKILL.md"]
-  FD -->|Trims and prunes files from| ActiveContext["Active AI Session Context"]
-  FD -->|Triggers high-level reflection when overloaded| ZoomOut["zoom-out / SKILL.md"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `fable-discipline` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Fable-mode is editing a large monorepo (context approaching 120k tokens)"] --> Monitor["Fable-discipline analyzes context size"]
-  Monitor --> TriggerPruning["Identifies 80k tokens of raw test execution logs & completed sub-task details"]
-  TriggerPruning --> Clean["Evicts completed step details and logs from immediate active context"]
-  Clean --> Compress["Summarizes historical state into a 50-line relational state.json"]
-  Compress --> Done([Active context drops back to 40k tokens, preserving model's reasoning precision])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `fable-discipline` skill is operating in strict compliance with Harness OS design laws, verify the following:
-
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+# Workflow: Fable Discipline
+
+> Shadow guard for fable-mode preventing context bloat, enforcing physical boundaries, and preserving compact stage handoffs.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `fable-discipline` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Fable Task Initiated]) --> AuditContext["Audit active context against the stage contract"]
+  AuditContext --> CheckTokenLimit{Context exceeds the active budget?}
+  CheckTokenLimit -->|Yes| TrimContext["Evict raw logs, completed tasks, and non-essential file contents"]
+  CheckTokenLimit -->|No| KeepState["Continue monitoring context state"]
+  TrimContext --> EnforceLimit["Enforce physical boundary guidelines"]
+  KeepState --> EnforceLimit
+  EnforceLimit --> RecordHandoff["Record a compact stage handoff"]
+  RecordHandoff --> End([Context maintained under safe, high-attention limits])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `fable-discipline` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
+
+```mermaid
+graph LR
+  Fable["fable-mode / SKILL.md"] -->|Monitors context on every turn| FD["fable-discipline / SKILL.md"]
+  FD -->|Trims and prunes files from| ActiveContext["Active AI Session Context"]
+  FD -->|Triggers high-level reflection when overloaded| ZoomOut["zoom-out / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `fable-discipline` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Fable-mode is editing a large monorepo with growing context"] --> Monitor["Fable-discipline analyzes active context"]
+  Monitor --> TriggerPruning["Identifies raw logs & completed sub-task details"]
+  TriggerPruning --> Clean["Evicts completed step details and logs from immediate active context"]
+  Clean --> Compress["Summarizes historical state into the stage handoff"]
+  Compress --> Done([Active context remains bounded while preserving required facts])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `fable-discipline` skill is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
+- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
+- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.

package/docs/workflows/fable-mode.md

@@ -10,23 +10,20 @@ This section visualizes how `fable-mode` handles macro tasks. Subagent failure o
 
 ```mermaid
 graph TD
-  Start([Tier 3 Macro Task Triggered]) --> InitFable["Initialize Fable Execution Context"]
-  InitFable --> AnalyzeScope["Map system dependencies & files"]
-  AnalyzeScope --> GenerateContract["Generate Contract & Todo List"]
+  Start([Tier 3 Macro Task Triggered]) --> Discovery["1. Discovery & Architectural Plan"]
+  Discovery --> InitTodo["2. Delegate Roadmap to todo-driven-workflow"]
   
-  GenerateContract --> RunStep["Try: Execute Step / Sub-agent"]
-  RunStep --> VerifyStep["Try: Run verify-gate.js for Integration"]
+  InitTodo --> Delegate{3. Delegate Sub-tasks}
+  Delegate -->|Sub-agent Tool Available| SpawnSub["Spawn Sub-agent via multi-agent-workspace"]
+  Delegate -->|No Sub-agent Tool| InlinePersona["Inline Persona Role-Switch Fallback"]
   
-  VerifyStep --> Check{Gate: Exit Code?}
-  Check -->|Exit 1: Sub-agent Failed| Diagnose["Reflect: Why did sub-agent fail?"]
-  Diagnose --> InsertBlocker["Insert Blocker Todo: Fix Integration"]
-  InsertBlocker --> RunStep
+  SpawnSub --> ScopeCheck["Monitor via hooks/scripts/subagent-scope-guard.js"]
+  InlinePersona --> ScopeCheck
   
-  Check -->|Exit 0: Success| CheckAllSteps{All steps done?}
-  CheckAllSteps -->|No| RunStep
-  CheckAllSteps -->|Yes| FinalAudit["Perform system-wide verification loop"]
+  ScopeCheck --> VerifyStep["4. Integration Verification via harness-everything/scripts/verify-gate.js"]
+  VerifyStep --> CheckGate{Integration Verification Passed?}
   
-  FinalAudit --> FinalCheck{Gate: Exit Code?}
-  FinalCheck -->|Exit 1| Diagnose
-  FinalCheck -->|Exit 0| End([Macro rewrite successfully deployed])
+  CheckGate -->|No: Integration Error| FixBlocker["Add Blocker Item to todo-driven-workflow & Fix"] --> VerifyStep
+  CheckGate -->|Yes: Gate Passes| Transition["5. Transition Scaffolding to TDD Iteration"]
+  Transition --> End([Macro Scaffolding Successfully Deployed])
 ```

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

@@ -1,62 +1,71 @@
-# Workflow: Git Commit
-
-> Generates semantic, Angular-style conventional commits after verifying the workspace, staged files, and active language contexts.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `git-commit` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```mermaid
-graph TD
-  Start([Trigger Commit Hook / Command]) --> DetectRepo["Detect main repo vs submodule"]
-  DetectRepo --> PreCheck["Verify unstaged changes & staged files"]
-  PreCheck --> StageCheck{Staged files present?}
-  StageCheck -->|No| Warning["Warn developer & exit"]
-  StageCheck -->|Yes| DetectLang["Analyze file extensions for active languages"]
-  DetectLang --> GenMessage["Analyze changes and generate Angular-style commit message"]
-  GenMessage --> FormatCheck["Format check: type, scope, subject, body, footer"]
-  FormatCheck --> WriteCommit["Commit staged files with formatted message"]
-  WriteCommit --> End([Staging clean and committed])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `git-commit` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
-
-```mermaid
-graph LR
-  Router["harness-everything / tier-router.js"] -->|Keyword: commit / git / save| GitCommit["git-commit / SKILL.md"]
-  GitCommit -->|Formats according to| Guide["git-commit / guides / ANGULAR_STYLE.md"]
-  GitCommit -->|Integrates with pre-commit gates| VerLoop["verification-loop / SKILL.md"]
-  GitCommit -->|Composed after history squashes| Rewrite["rewrite-commits / SKILL.md"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `git-commit` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Developer completes feature & runs 'git add .'"] --> Trigger["Invoke git-commit skill"]
-  Trigger --> Analyze["Skill parses staged diff: 'src/auth.js (+15,-2)'"]
-  Analyze --> DetectScope["Deduce scope: 'auth' and type: 'feat'"]
-  DetectScope --> BuildMessage["Build message: 'feat(auth): add JWT token expiration check'"]
-  BuildMessage --> Commit["Execute git commit -m 'feat(auth): add JWT token expiration check'"]
-  Commit --> Done(["Repository index updated cleanly"])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `git-commit` skill is operating in strict compliance with Harness OS design laws, verify the following:
-
-- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
-- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
-- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.
+# Workflow: Git Commit
+
+> Generates semantic, Angular-style conventional commits after verifying the workspace, staged files, and active language contexts.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `git-commit` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Trigger Commit 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])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `git-commit` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Keyword: commit / git / save| GitCommit["git-commit / SKILL.md"]
+  GitCommit -->|Formats according to| Guide["git-commit / guides / ANGULAR_STYLE.md"]
+  GitCommit -->|Integrates with pre-commit gates| VerLoop["verification-loop / SKILL.md"]
+  GitCommit -->|Composed after history squashes| Rewrite["rewrite-commits / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `git-commit` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Developer completes feature & runs 'git add .'"] --> Trigger["Invoke git-commit skill"]
+  Trigger --> Analyze["Skill parses staged diff: 'src/auth.js (+15,-2)'"]
+  Analyze --> DetectScope["Deduce scope: 'auth' and type: 'feat'"]
+  DetectScope --> BuildMessage["Build message: 'feat(auth): add JWT token expiration check'"]
+  BuildMessage --> Commit["Execute git commit -m 'feat(auth): add JWT token expiration check'"]
+  Commit --> Done(["Repository index updated cleanly"])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `git-commit` skill is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
+- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
+- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.

package/docs/workflows/grill-me.md

@@ -1,62 +1,62 @@
-# Workflow: Grill Me
-
-> Relentless Challenger interview process that stress-tests architectural plans, highlights hidden assumptions, and demands explicit edge-case handling.
-
----
-
-## 1. Skill Behavior Workflow
-
-This section visualizes how the `grill-me` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
-
-```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])
-```
-
----
-
-## 2. Triggering and Routing Path
-
-This diagram illustrates how the `grill-me` 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: 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"]
-```
-
----
-
-## 3. Real-World Use Case Flowchart
-
-Here we model concrete real-world scenarios and use cases of the `grill-me` skill, illustrating standard success paths, error handling, or recovery loops.
-
-```mermaid
-graph TD
-  Start["Proposal: 'I will write a fast cron job to sync database tables directly'"] --> Trigger["grill-me skill activated"]
-  Trigger --> Challenger["Challenger SRE: 'What happens if the cron script fails mid-sync? Will there be database lock contention? How do we prevent partial/corrupt states?'"]
-  Challenger --> Answer1["Dev: 'I'll add database transaction wraps and skip locks'"]
-  Answer1 --> Challenger2["Challenger: 'How will we monitor and alert if locks are skipped repeatedly?'"]
-  Challenger2 --> Answer2["Dev: 'I'll add structured logging and trigger a standard Slack web-hook alerting'"]
-  Answer2 --> Approve["Challenger: 'Excellent. Let's record these lock-skip alerts as mandatory requirements.'"]
-  Approve --> Done([Plan hardened and logged])
-```
-
----
-
-## 4. Verification Check
-
-To ensure that the `grill-me` 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 Me
+
+> Relentless Challenger interview process that stress-tests architectural plans, highlights hidden assumptions, and demands explicit edge-case handling.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `grill-me` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  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])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `grill-me` 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: grill / debate / plan| GrillMe["grill-me / 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"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `grill-me` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Proposal: 'I will write a fast cron job to sync database tables directly'"] --> Trigger["grill-me skill activated"]
+  Trigger --> Challenger["Challenger SRE: 'What happens if the cron script fails mid-sync? Will there be database lock contention? How do we prevent partial/corrupt states?'"]
+  Challenger --> Answer1["Dev: 'I'll add database transaction wraps and skip locks'"]
+  Answer1 --> Challenger2["Challenger: 'How will we monitor and alert if locks are skipped repeatedly?'"]
+  Challenger2 --> Answer2["Dev: 'I'll add structured logging and trigger a standard Slack web-hook alerting'"]
+  Answer2 --> Approve["Challenger: 'Excellent. Let's record these lock-skip alerts as mandatory requirements.'"]
+  Approve --> Done([Plan hardened and logged])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `grill-me` 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.