harness-everything 0.2.0

package/docs/routing.md

@@ -0,0 +1,45 @@
+# Harness Routing & Task Triage
+
+To prevent both over-engineering and under-planning, Harness classifies every user request into one of three execution tiers. This ensures that trivial tasks are executed instantly without unnecessary bloat, while complex architectural refactoring is strictly designed and verified.
+
+---
+
+## The Three-Tier Routing System
+
+Upon receiving a request, the `tier-router.js` script analyzes the scope, affected files, and instruction patterns to route the task:
+
+```
+                  [ User Request ]
+                         |
+                         v
+                [ Triage Analysis ]
+               /         |         \
+              /          |          \
+     (Trivial)       (Standard)      (Macro)
+     /                   |                  \
+    v                    v                   v
+[ Tier 1 ]           [ Tier 2 ]          [ Tier 3 ]
+Direct Edit       Test-Driven (TDD)     Multi-Agent Flow
+(No plans)        (Red-Green-Refactor)   (Fable-Mode)
+```
+
+### Tier 1: Trivial Tasks (Direct Execution)
+*   **Trigger criteria:** Single-file edits, typos, simple styling fixes, readme corrections, or clean-up tasks.
+*   **Behavior:** Harness bypasses plans, code-reviews, and sub-agents. The model is directed to make the edit directly and complete the task, consuming minimal tokens.
+*   **Verification:** Basic syntax checks or a quick compile verify success.
+
+### Tier 2: Standard Tasks (Test-Driven Development)
+*   **Trigger criteria:** Normal feature requests, bug fixes, algorithm additions, API endpoint creations, or any task affecting multiple files with logical risk.
+*   **Behavior:** Harness enforces the `todo-driven-workflow` base execution loop (initialize a 3-7 item verifiable checklist before editing, one item in-progress at a time) and the `tdd` skill. The model is strictly guided through the Red-Green-Refactor loop:
+    1.  **Red:** Write an automated test first that reproduces the issue or covers the feature, then run it to verify failure.
+    2.  **Green:** Implement the minimal amount of code to make the test pass.
+    3.  **Refactor:** Polish the code, clean up duplicates, and ensure coverage targets (minimum 80%) are met.
+*   **Verification:** Strict execution of the test suite.
+
+### Tier 3: Macro Tasks (Multi-Agent/Fable-Mode)
+*   **Trigger criteria:** High-level design changes, migration of modules, large-scale refactoring, or major capability additions affecting multiple domains.
+*   **Behavior:** Harness automatically spawns the multi-agent orchestration engine (`fable-mode` and `create-agent-launcher`), with the macro plan materialized as the `todo-driven-workflow` checklist.
+    1.  **Planning:** An agent constructs a rigorous, phase-based implementation plan.
+    2.  **Delegation:** Specialized sub-agents (e.g., `security-reviewer`, `database-reviewer`, `code-reviewer`) are created to handle specific work streams or audits.
+    3.  **Handoffs:** Session handoffs are saved periodically to ensure that if a session limits out or restarts, the progress is seamlessly restored.
+*   **Verification:** Multi-layer unit, integration, and E2E verification loops.

package/docs/workflows/build-multi-agent-system.md

@@ -0,0 +1,62 @@
+# Workflow: Build Multi-Agent System
+
+> Deploys an industrial-grade, self-adapting Multi-Agent Workspace architecture, scaffolding physical boundaries and relational SQLite context indexes.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `build-multi-agent-system` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Workspace Scaffolding Requested]) --> DiscoverStack["Analyze project package.json/runtimes"]
+  DiscoverStack --> DeduceRoles["Deduce required specialist roles & PM / Challenger"]
+  DeduceRoles --> ScaffoldZones["Scaffold '6 Functional Zones' directories: State, Decisions, Logs, etc."]
+  ScaffoldZones --> GenMemoryIndexer["Generate language-appropriate index_memory script"]
+  GenMemoryIndexer --> GenAgentsRouter["Generate AGENTS.md routing brain"]
+  GenAgentsRouter --> RunIndexer["Execute memory indexer to initialize local memory.db SQLite index"]
+  RunIndexer --> VerifyExecution["Verify schema, tables, and execution status"]
+  VerifyExecution --> End([Scaffolding and hybrid relational memory initialized])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `build-multi-agent-system` 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: agent / workspace / multi-agent| BMAS["build-multi-agent-system / SKILL.md"]
+  BMAS -->|Works hand-in-hand with spawning tool| CAL["create-agent-launcher / SKILL.md"]
+  BMAS -->|Stores architectural contracts in| GWD["grill-with-docs / SKILL.md"]
+  BMAS -->|Initializes memory rules via| Evolve["self-evolve / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `build-multi-agent-system` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["User asks to set up an AI developer workspace for a Python backend"] --> Trigger["Invoke build-multi-agent-system"]
+  Trigger --> DetectStack["Identifies Python/Django stack"]
+  DetectStack --> BuildDirs["Creates .agents/, docs/decisions/, docs/architecture/, state/ folders"]
+  BuildDirs --> WriteIndexer["Creates python indexer script parsing markdown frontmatter"]
+  WriteIndexer --> CreateDB["Runs indexer, generating SQLite memory.db schema"]
+  CreateDB --> WriteAgentsRouter["Generates AGENTS.md with routing matrix"]
+  WriteAgentsRouter --> Done([Professional Multi-Agent Workspace deployed and indexed])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `build-multi-agent-system` 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/create-agent-launcher.md

@@ -0,0 +1,62 @@
+# Workflow: Create Agent Launcher
+
+> Sub-agent generator for orchestrating multi-domain specialized agents to avoid token context waste and preserve developer focus.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `create-agent-launcher` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Complex Task Demands Division of Labor]) --> AssessComplexity{Too complex for 1 context?}
+  AssessComplexity -->|No| Reject["Reject creation, resolve in current context via TDD"]
+  AssessComplexity -->|Yes| DefinePersona["Define highly restrictive specialized sub-agent persona"]
+  DefinePersona --> IsolateResources["Map exact, minimum file paths needed for sub-task"]
+  IsolateResources --> SelectModel["Select cost-effective model based on task weight"]
+  SelectModel --> WriteHandoff["Define strict input/output contract for sub-agent return report"]
+  WriteHandoff --> LaunchAgent["Launch specialized sub-agent under isolated sandbox"]
+  LaunchAgent --> MergeReport["Validate and merge sub-agent findings into main orchestrator"]
+  MergeReport --> End([Sub-agent work verified and closed])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `create-agent-launcher` 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"] -->|Requires agent specialization| CAL["create-agent-launcher / SKILL.md"]
+  CAL -->|Spawns agent on scaffolding provided by| BMAS["build-multi-agent-system / SKILL.md"]
+  CAL -->|Plans agent tasks using macro planner| Fable["fable-mode / SKILL.md"]
+  CAL -->|Limits child memory to prevent bloat via| FD["fable-discipline / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `create-agent-launcher` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Refactoring task involves SQL Schema migrations, Node endpoints, and React forms"] --> Trigger["create-agent-launcher skill executed"]
+  Trigger --> SpawnDB["Spawn 'Database Architect': Only views 'schema.sql' and outputs raw SQL migration"]
+  Trigger --> SpawnFE["Spawn 'Frontend Specialist': Only views 'Login.tsx' and outputs validated form code"]
+  SpawnDB & SpawnFE --> Collect["Main orchestrator receives isolated, highly focused diff reports from both"]
+  Collect --> Merge["Integrate changes and run integration testing"]
+  Merge --> Done([Complex task completed with 70% lower token cost and zero context confusion])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `create-agent-launcher` 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/environment-detection.md

@@ -0,0 +1,63 @@
+# Workflow: Environment Detection
+
+> Active shell, operating system, and toolset environment detection, providing safety guardrails and running preflight syntactic verification.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `environment-detection` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Before Command Execution]) --> DetectOS["Detect Operating System: Windows, macOS, Linux"]
+  DetectOS --> DetectShell["Detect Shell: Bash, PowerShell, CMD, Zsh"]
+  DetectShell --> ScanCapabilities["Scan available runtimes: Node, Python, .NET, Docker"]
+  ScanCapabilities --> CheckSyntax["Inspect command for active shell compatibilities"]
+  CheckSyntax --> SyntaxGuard{Syntax safe for shell?}
+  SyntaxGuard -->|No| RewriteCmd["Transform/Rewrite command syntax to match active shell"]
+  SyntaxGuard -->|Yes| Execute["Run command in persistent terminal"]
+  RewriteCmd --> Execute
+  Execute --> CaptureOutput["Interleave output and exit code correctly"]
+  CaptureOutput --> End([Secure terminal result returned])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `environment-detection` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Pre-flight command execution| Env["environment-detection / SKILL.md"]
+  Env -->|Guards runner execution commands in| TDD["tdd / SKILL.md"]
+  Env -->|Guards script installations in| InstallOS["install-cognitive-os / SKILL.md"]
+  Env -->|Guards PR quality checks in| VerLoop["verification-loop / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `environment-detection` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Agent wants to run: 'rm -rf build && mkdir build' on Windows Powershell"] --> Trigger["Environment detection pre-flight check"]
+  Trigger --> Detect["Identifies OS: Windows, Shell: PowerShell"]
+  Detect --> AnalyzeSyntax["Identifies that 'rm -rf' will fail or behave unexpectedly in PowerShell"]
+  AnalyzeSyntax --> Rewrite["Rewrites command to PowerShell equivalent or executes using native node commands"]
+  Rewrite --> Run["Executes safely with exit code 0"]
+  Run --> Done([Syntax error and execution crash avoided])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `environment-detection` skill is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
+- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
+- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.

package/docs/workflows/eval-harness.md

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

package/docs/workflows/fable-discipline.md

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

package/docs/workflows/fable-mode.md

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

package/docs/workflows/git-commit.md

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

package/docs/workflows/grill-me.md

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

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

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