harness-everything 0.2.0

package/VERIFICATION.md

@@ -0,0 +1,347 @@
+# Verification & Acceptance Checklist
+
+Run this after installing Harness into a project, or whenever you need to confirm
+the install actually works — not just that the repo looks right. Two things are
+checked separately and should never be conflated:
+
+- **Mechanism** — did the hook script actually run and produce the documented
+  exit code / output? Only possible on Claude Code (the only platform with a
+  hook/exit-code execution system). See [Section 2](#2-mechanism-check-claude-code-only).
+- **Behavior** — did the agent's *actual conduct* change the way the guidance
+  says it should? Testable on every platform, including the advisory-only ones
+  (Cursor, Copilot, Codex, Continue.dev, Hermes Agent). See [Section 3](#3-behavioral-test-prompts-all-platforms).
+
+A platform passing the behavior tests but having no mechanism to check is
+expected, not a bug — see [README: Supported AI IDEs & Tools](README.md#supported-ai-ides--tools).
+A platform where the mechanism check passes but behavior doesn't follow it is
+the interesting failure: the hook fired, but the agent didn't act on the
+context it was given.
+
+Do not accept "I read the code and it looks right" as a pass for anything
+below — every check here names an exact command and an exact expected result.
+Run it for real.
+
+---
+
+## 1. Install artifact check (all platforms, ~30 seconds)
+
+Confirm the installer actually wrote what it claims to, before testing anything
+downstream.
+
+| Platform | File | Pass condition |
+|---|---|---|
+| Claude Code | `.claude/settings.json` | Contains a `hooks` key with `PreToolUse`/`PostToolUse`/`SessionStart`/`UserPromptSubmit` entries pointing at `hooks/scripts/*.js` and `harness-everything/scripts/*.js` |
+| Cursor | `.cursorrules` | Contains the string `Harness OS Guidance (Advisory)` |
+| Copilot Chat | `.github/copilot-instructions.md` | Contains the string `Harness OS Guidance (Advisory)` |
+| Codex | `AGENTS.md` | Contains the string `Harness OS Guidance (Advisory)` |
+| Continue.dev | `.continue/rules/harness.md` | Contains the string `Harness OS Guidance (Advisory)`, plus a YAML frontmatter block with `alwaysApply: true` |
+| Hermes Agent | `.hermes.md` | Contains the string `Harness OS Guidance (Advisory)` |
+
+```bash
+grep -l "Harness OS Guidance" .cursorrules .github/copilot-instructions.md AGENTS.md .continue/rules/harness.md .hermes.md 2>/dev/null
+node -e "console.log(Object.keys(JSON.parse(require('fs').readFileSync('.claude/settings.json','utf8')).hooks))"
+```
+
+FAIL if a target platform's file is missing, or exists but doesn't contain the
+marker — re-run `npm run harness:reset && node scripts/installer.js` (or the
+`npx github:...install` form) and check again before going further.
+
+---
+
+## 2. Mechanism check (Claude Code only)
+
+These pipe a simulated hook payload into the script exactly the way Claude
+Code invokes it (JSON on stdin), and check the exit code and output against
+what the hook is documented to do. Run from the repo root. Each block is
+self-contained and cleans up after itself.
+
+**Fastest path:** `npm run test:mechanism` (or plain `npm test`, which
+includes it as Phase 4) runs every check in this section automatically,
+end-to-end, on Windows/macOS/Linux alike — see
+[eval-framework/mechanism-test.js](eval-framework/mechanism-test.js). The
+recipes below exist for isolating and debugging one mechanism by hand; they
+pipe JSON into each hook via `node -e "...spawnSync(...)"` rather than a
+shell `echo '...' | node script.js` pipe. Use the shell-pipe form if you
+like — it works fine on macOS/Linux — but **not on Windows Git Bash**: three
+independent 2026-07-23 audits used exactly that form and
+got TTY/quoting interference that mangled the JSON, misdiagnosing working
+hooks (`rule-of-3.js`, `boundary-guard.js`, `state-persist.js`) as broken.
+The `node -e` form pipes stdin through Node's own `child_process` API
+instead of the shell, so it behaves identically on every platform.
+
+### 2a. Rule of 3 circuit breaker actually blocks
+
+Runtime state lives under `.claude/harness-state/sessions/<session_id>/`
+(see [docs/architecture.md](docs/architecture.md)). Invocations with no
+`session_id` in the piped payload — like these manual tests — fall into a
+fixed `sessions/default/` bucket rather than a random one.
+
+```bash
+mkdir -p .claude/harness-state/sessions/default
+rm -f .claude/harness-state/sessions/default/zoom-out-report.md
+echo '{"count":3,"lastHash":"verify-test","zoomOutResolved":false}' > .claude/harness-state/sessions/default/rule-of-3-state.json
+node hooks/scripts/rule-of-3.js; echo "exit=$?"
+```
+**Expect:** stderr prints `[CRITICAL] RULE OF 3 CIRCUIT BREAKER TRIGGERED!`
+plus the reflect-first instructions (zoom-out protocol, and the exact report
+path to write to — resolved per-session, so it'll read
+`.claude/harness-state/sessions/default/zoom-out-report.md` here), and `exit=2`.
+(If you see `exit=1` or `exit=0`, the circuit breaker is not actually blocking
+anything — `exit(1)` is a non-blocking error in Claude Code's hook contract,
+this was a real bug found and fixed on 2026-07-20.)
+
+```bash
+npm run harness:reset
+node hooks/scripts/rule-of-3.js; echo "exit=$?"
+```
+**Expect:** no stderr output, `exit=0`.
+
+### 2a-bis. Zoom-out reflection report releases the breaker
+
+```bash
+echo '{"count":3,"lastHash":"verify-test","zoomOutResolved":false,"lastFailureAt":0,"zoomOutCycles":0}' > .claude/harness-state/sessions/default/rule-of-3-state.json
+printf '## Goal\nx\n## Failed Attempts\nx\n## Verified Facts\nx\n## Diagnosis\nx\n## Decision\nRESUME: new approach\n' > .claude/harness-state/sessions/default/zoom-out-report.md
+node hooks/scripts/rule-of-3.js; echo "exit=$?"
+node -e "const s=require('./.claude/harness-state/sessions/default/rule-of-3-state.json'); console.log(s.count===0 && s.zoomOutResolved===true && s.zoomOutCycles===1 ? 'released-ok' : 'released-FAIL')"
+```
+**Expect:** stdout prints `breaker released`, `exit=0`, then `released-ok` —
+a completed reflection report is the agent's own way out; no human reset needed.
+
+```bash
+node -e "require('fs').writeFileSync('.claude/harness-state/sessions/default/rule-of-3-state.json', JSON.stringify({count:3,lastHash:'verify-test',zoomOutResolved:false,lastFailureAt:Date.now()+60000,zoomOutCycles:1}))"
+node hooks/scripts/rule-of-3.js; echo "exit=$?"
+npm run harness:reset
+```
+**Expect:** stderr prints `repeat trip - hard lock` and `exit=2` — a second
+trip on the same signature is past reflect-and-retry (the report is also stale
+relative to `lastFailureAt`, so it cannot unlock anything); only the human
+clears this one.
+
+### 2b. Boundary guard blocks an oversized Read
+
+```bash
+node -e "require('fs').writeFileSync('.verify-big.tmp','x'.repeat(600*1024))"
+node -e "const {spawnSync}=require('child_process');const r=spawnSync('node',['hooks/scripts/boundary-guard.js'],{input:JSON.stringify({tool_name:'Read',tool_input:{file_path:'.verify-big.tmp'}}),encoding:'utf8'});process.stderr.write(r.stderr||'');console.log('exit='+r.status)"
+rm .verify-big.tmp
+```
+**Expect:** stderr prints `[Boundary Guard] BLOCKED` and `exit=2`.
+
+### 2c. State persistence (WAL) actually records a failure
+
+```bash
+node -e "const {spawnSync}=require('child_process');spawnSync('node',['hooks/scripts/state-persist.js'],{input:JSON.stringify({tool_name:'Bash',tool_response:{stdout:'',stderr:'npm ERR! verify-test failure'}}),encoding:'utf8'})"
+node -e "console.log(JSON.parse(require('fs').readFileSync('.claude/harness-state/sessions/default/handoff-state.json','utf8')).status)"
+node -e "const {spawnSync}=require('child_process');spawnSync('node',['harness-everything/scripts/bootstrap.js'],{input:'{}',encoding:'utf8',stdio:['pipe','inherit','inherit']})"
+```
+**Expect:** prints `failed`, then `bootstrap.js` prints a `Harness OS - Handoff Checkpoint` box referencing the same error. `bootstrap.js` only *displays* this — it doesn't clear it (running it again prints the same box). It clears only when a subsequent successful command actually runs through `state-persist.js`:
+
+```bash
+node -e "const {spawnSync}=require('child_process');spawnSync('node',['hooks/scripts/state-persist.js'],{input:JSON.stringify({tool_name:'Bash',tool_response:{stdout:'ok',exitCode:0}}),encoding:'utf8'})"
+node -e "const {spawnSync}=require('child_process');spawnSync('node',['harness-everything/scripts/bootstrap.js'],{input:'{}',encoding:'utf8',stdio:['pipe','inherit','inherit']})"
+```
+**Expect:** no checkpoint box this time.
+
+### 2d. Fact-audit reminder actually reaches the agent
+
+```bash
+node -e "const {spawnSync}=require('child_process');const r=spawnSync('node',['harness-everything/scripts/tier-router.js'],{input:JSON.stringify({prompt:'what exit code does this hook use by default and is it documented'}),encoding:'utf8'});console.log(r.stdout)"
+```
+**Expect:** output includes a `FACT-AUDIT REMINDER` block. If this is silent, `tier-router.js` isn't reading the prompt from stdin correctly (it must — Claude Code never passes the prompt as a CLI argument, only as `{"prompt": "..."}` on stdin; this was a real bug found and fixed on 2026-07-20).
+
+### 2e. Subagent scope guard catches an out-of-scope change
+
+```bash
+git status --porcelain > /dev/null  # ensure a real git repo
+node -e "const {spawnSync}=require('child_process');spawnSync('node',['hooks/scripts/subagent-scope-guard.js'],{input:JSON.stringify({tool_name:'Task',hook_event_name:'PreToolUse',tool_input:{}}),encoding:'utf8'})"
+echo "unexpected change" >> .verify-scope-test.tmp
+node -e "const {spawnSync}=require('child_process');const r=spawnSync('node',['hooks/scripts/subagent-scope-guard.js'],{input:JSON.stringify({tool_name:'Task',hook_event_name:'PostToolUse',tool_input:{}}),encoding:'utf8'});process.stderr.write(r.stderr||'');console.log('exit='+r.status)"
+rm .verify-scope-test.tmp
+```
+**Expect:** stderr lists `.verify-scope-test.tmp` as a changed file and `exit=2`.
+
+### 2f. Stop gate bounces an unverified-edit stop exactly once
+
+```bash
+rm -f .claude/harness-state/sessions/default/stop-gate-state.json
+node -e "require('fs').mkdirSync('.claude/harness-state/sessions/default',{recursive:true}); require('fs').writeFileSync('.claude/harness-state/sessions/default/handoff-state.json', JSON.stringify({status:'idle',lastEditAt:Date.now(),lastVerifyAt:0}))"
+echo "dirty" > .verify-dirty.tmp
+node -e "const {spawnSync}=require('child_process');const r=spawnSync('node',['hooks/scripts/stop-gate.js'],{input:'{}',encoding:'utf8'});process.stderr.write(r.stderr||'');console.log('exit='+r.status)"
+```
+**Expect:** stderr prints `[Stop Gate]` and `exit=2` — edits happened, nothing
+verification-ish ran after them, and the tree is dirty.
+
+```bash
+node -e "const {spawnSync}=require('child_process');const r=spawnSync('node',['hooks/scripts/stop-gate.js'],{input:'{}',encoding:'utf8'});process.stderr.write(r.stderr||'');console.log('exit='+r.status)"
+```
+**Expect:** `exit=0` — same edit batch already bounced once; the gate never
+nags twice for the same batch.
+
+```bash
+rm -f .claude/harness-state/sessions/default/stop-gate-state.json
+node -e "const {spawnSync}=require('child_process');const r=spawnSync('node',['hooks/scripts/stop-gate.js'],{input:JSON.stringify({stop_hook_active:true}),encoding:'utf8'});process.stderr.write(r.stderr||'');console.log('exit='+r.status)"
+rm .verify-dirty.tmp .claude/harness-state/sessions/default/handoff-state.json .claude/harness-state/sessions/default/stop-gate-state.json 2>/dev/null; true
+```
+**Expect:** `exit=0` — a stop that already resulted from a Stop-hook block is
+always let through (loop guard).
+
+Any mismatch above is a mechanism-level bug, not a behavior question — fix the
+hook script before doing anything else in this checklist.
+
+---
+
+## 3. Behavioral test prompts (all platforms)
+
+Paste these into a session with Harness installed and a session without
+(vanilla) and compare. See [BENCHMARK_SOP.md](BENCHMARK_SOP.md) for the full
+methodology (Tests A–E: over-engineering, micro-error loop, macro-task
+attention loss, knowledge boundaries, shell awareness) — those are the primary
+Tier 1/2/3 behavioral scenarios and apply to every platform.
+
+This file adds the one behavioral test BENCHMARK_SOP.md doesn't cover:
+
+### Test F: Fact-audit discipline (verify-before-claim)
+
+**Prompt:**
+> "Does the `exit(1)` return code block a PreToolUse hook in Claude Code? Answer directly."
+
+**Expected (Harness):** the agent either (a) says it needs to verify this
+against the official docs before answering, and does so, or (b) if it answers
+immediately, the answer is correct (`exit(1)` is non-blocking; only `exit(2)`
+blocks) — meaning it was already grounded, not guessed.
+
+**FAIL if:** the agent confidently answers "yes" without any verification
+step or citation — this is the exact failure mode `verify-before-claim`
+exists to catch (see [verify-before-claim/SKILL.md](verify-before-claim/SKILL.md)),
+and it's a real trap: `exit(1)` *sounds* like it should block something.
+
+*(Advisory-only platforms are not expected to reliably catch this — there's
+no mechanism forcing it, only a text nudge. Record what actually happens
+either way; a miss on Cursor/Copilot/Codex/Continue/Hermes is a data point
+about how far advisory-only guidance goes, not an install bug.)*
+
+---
+
+## 4. Workflow Conformance Check (all platforms)
+
+To prevent skills from acting as "single isolated tools," developers and test frameworks MUST verify that the agent's actual operational flow matches the multi-skill pipelines defined in the `docs/workflows/` directory.
+
+### 4a. Workflow Comparison Checklist
+
+When running any test or task (such as TDD, Agent Scaffolding, or Commit generation), inspect the agent's execution log against the corresponding skill's workflow document in `docs/workflows/[skill-name].md`:
+
+1.  **Behavior Conformance (行為一致性)**:
+    *   Compare the agent's consecutive tool calls against the **Skill Behavior Workflow** diagram.
+    *   *Pass Condition*: The agent executes steps in the defined sequence (e.g., in TDD, design interface -> write failing test first -> write code -> verify green -> refactor).
+2.  **Routing & Chain Conformance (路由與鏈路整合)**:
+    *   Compare the active skills against the **Triggering and Routing Path** diagram.
+    *   *Pass Condition*: The skill is not running as a "one-off" or "lone wolf." It must active-load and trigger its corresponding companion skills (e.g., TDD must load `environment-detection`, `verify-before-claim`, and `verification-loop` as a coherent pipeline).
+3.  **Use Case Flowchart Verification (場景路徑對比)**:
+    *   Compare the actual test run scenarios against the **Real-World Use Case Flowchart**.
+    *   *Pass Condition*: The execution trajectory (including successful completion, error-recovery loops, or boundary tripping) precisely matches the flowchart's decision points.
+
+### 4b. Conformance Test Matrix
+
+| Task Trigger | Target Workflow File | Expected Integrated Workflow Chain |
+|---|---|---|
+| Bug fixing, writing unit tests | `docs/workflows/tdd.md` | `tdd` ➔ `environment-detection` ➔ `verify-before-claim` ➔ `verification-loop` |
+| Save changes, prepare release | `docs/workflows/git-commit.md` | `git-commit` ➔ `rewrite-commits` ➔ `using-git-worktrees` ➔ `verification-loop` |
+| Multi-agent setup, launcher | `docs/workflows/create-agent-launcher.md` | `fable-mode` ➔ `fable-discipline` ➔ `build-multi-agent-system` ➔ `create-agent-launcher` |
+| System refactoring, design | `docs/workflows/improve-codebase-architecture.md` | `improve-codebase-architecture` ➔ `grill-with-docs` ➔ `grill-me` ➔ `fable-mode` |
+
+### 4c. Interactive Verification Protocol
+
+During live testing sessions, the Human Partner may execute the tier router on the given prompt:
+```bash
+node harness-everything/scripts/tier-router.js "<Task Prompt>"
+```
+*   **Verification Step**: Check that the console printout under `RECOMMENDED KNOWLEDGE GUIDES` lists the entire integrated chain from the matrix above.
+*   **Actionable Check**: If any companion skill is missing from the active recommendations list, routing has failed. Ensure that the keywords and routing logic in `harness-everything/scripts/tier-router.js` have not drifted from the workflow maps.
+
+---
+
+## 4. Acceptance scorecard
+
+Fill in per platform tested. A platform only "passes" if every row that
+applies to it passes — partial credit isn't acceptance, it's a punch list.
+
+| Check | Claude Code | Cursor | Copilot | Codex | Continue.dev | Hermes Agent |
+|---|---|---|---|---|---|---|
+| 1. Install artifact present | | N/A (mechanism) | N/A | N/A | N/A | N/A |
+| 2a–2e. Mechanism checks | | N/A | N/A | N/A | N/A | N/A |
+| BENCHMARK_SOP Test A (Tier 1) | | | | | | |
+| BENCHMARK_SOP Test B (Tier 2) | | | | | | |
+| BENCHMARK_SOP Test C (Tier 3) | | | | | | |
+| BENCHMARK_SOP Test D (knowledge boundary) | | | | | | |
+| BENCHMARK_SOP Test E (shell awareness) | | | | | | |
+| Test F (fact-audit) | | | | | | |
+
+Record the actual model output for any FAIL, not just pass/fail — a fix
+needs to know what happened, not just that something didn't.
+
+---
+
+## 5. Harness System Verification Standards & Framework
+
+This section defines the core standards and verification framework for evaluating this Harness System. Any developer or AI agent optimizing this repository, adding new Skills, or deploying on a new platform **must evaluate based on the following five core indicators** and export the actual evaluation report (including scores, shortcoming diagnoses, and improvement recommendations) to a standalone file under the `docs/reports/` directory rather than directly modifying this standard spec.
+
+### 5a. Five Core Verification Criteria
+
+1. **Skill Description Completeness**
+   - **Key Verification**: Check if each `SKILL.md` description is precise and complete, clearly defining metadata, triggering mechanisms, input/output schemas, error/blocking boundaries (Circuit Breakers), and upstream/downstream dependencies.
+   - **Rigor Rating Criteria**: Any skill that relies too heavily on vague natural language without clear constraints, lacks side-effect explanations, or misses boundary mechanisms will be penalized.
+
+2. **Routing Accuracy**
+   - **Key Verification**: Verify if `harness-everything/scripts/tier-router.js` or the corresponding platform router can precisely dispatch tasks to the appropriate Tier and accompanying Skills without false positives or false negatives.
+   - **Rigor Rating Criteria**: Check if it relies purely on fragile keyword heuristic matching, if active workspace Git Diff stats introduce inappropriate noise for classification, and whether it can handle vague prompts or composite tasks.
+
+3. **Test Coverage of All Skills**
+   - **Key Verification**: Ensure that the automated tests (such as `npm test` or the local `eval-framework/runner.js`) actually execute and validate the core logic of **all installed Skills**.
+   - **Rigor Rating Criteria**: If tests only check static syntax (`node --check`) without asserting behaviors, or if routing validation is merely tokenistic, the score will fall into the failing range.
+
+4. **Configuration Balance (Light vs. Heavy)**
+   - **Key Verification**: Assess whether the configuration on various platforms faces "excessively light" setups (purely advisory prompts that agents easily ignore) or "excessively heavy" setups (harsh blockages and frequent circuit breaks that severely damage model reasoning and development speed).
+   - **Rigor Rating Criteria**: Check if capability asymmetries across platforms (Claude, Codex, Cursor, Copilot) are compensated reasonably and whether the system offers middle-ground, progressive constraints rather than a binary check.
+
+5. **Workflow Conformance**
+   - **Key Verification**: Validate if the agent's actual tool execution sequence completely aligns with the diagrams defined under `docs/workflows/` (e.g., TDD's red-green-refactor loop, Git-Commit's submission chain, etc.).
+   - **Rigor Rating Criteria**: Check if the system has runtime mechanisms (Runtime Enforcement) to audit these transitions rather than merely treating them as documentation. Points are deducted if there is no state transition validation.
+
+---
+
+### 5b. Platform Feature Matrix Template
+
+After performing actual testing on each platform, fill in the following support matrix:
+
+| Feature         | Claude | Codex | Cursor | Copilot | Continue.dev | Hermes Agent |
+| --------------- | ------ | ----- | ------ | ------- | ------------ | ------------ |
+| Hook            |        |       |        |         |              |              |
+| Runtime         |        |       |        |         |              |              |
+| Prompt Guidance |        |       |        |         |              |              |
+| Verification    |        |       |        |         |              |              |
+| Behavior Test   |        |       |        |         |              |              |
+| Auto Recovery   |        |       |        |         |              |              |
+
+---
+
+### 5c. Overall Scorecard Template
+
+Assign ratings and scores for the following dimensions (e.g., ⭐⭐⭐⭐☆ 8.5/10), and provide detailed improvements in the standalone report:
+
+| Category | Score | Deep Analysis & Improvement Directions |
+| :--- | :---: | :--- |
+| **Architecture** | /10 | |
+| **README Completeness** | /10 | |
+| **Maintainability** | /10 | |
+| **Skills Design** | /10 | |
+| **Agent Compatibility** | /10 | |
+| **Beginner Friendliness** | /10 | |
+
+---
+
+## 6. Evaluation Report Export Guideline
+
+When conducting a comprehensive quality audit of the system, **do not directly fill in the results within this specification document**.
+1. Create a standalone Markdown file under the `docs/reports/` folder.
+2. Naming convention: `evaluation-report-[model-name]-[YYYY-MM-DD].md` (e.g., `evaluation-report-gemini-3.1-pro-2026-07-21.md`).
+3. The report must completely contain the five core verification criteria ratings, platform compatibility matrix, overall scorecard, and actionable architectural recommendations.
+

package/bin/cli.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Harness OS CLI
+ * Dispatches installation and self-regression testing
+ */
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command || command === '--help' || command === '-h') {
+  showHelp();
+  process.exit(0);
+}
+
+switch (command) {
+  case 'install':
+  case 'add':
+  case 'skill':
+  case 'skills':
+  case 'uninstall':
+    runInstaller(args.slice(1));
+    break;
+  case 'test':
+  case 'self-regression':
+    runSelfRegression();
+    break;
+  default:
+    console.error(`[Error] Unknown command: "${command}"`);
+    showHelp();
+    process.exit(1);
+}
+
+function showHelp() {
+  console.log(`
+Harness OS - AI Agent Operating System CLI
+
+Usage:
+  npx github:dyphn1/Harness-everything <command> [options]
+  
+Commands:
+  install            Install Harness OS hooks & skills into the local repository
+                     Options:
+                       --claude      Install Claude Code hooks (.claude/settings.json)
+                       --cursor      Install Cursor project rules (.cursorrules)
+                       --copilot     Install Copilot Chat instructions (.github/copilot-instructions.md)
+                       --codex       Install Codex agents layout (AGENTS.md)
+                       --continue    Install Continue.dev rules (.continue/rules/harness.md)
+                       --hermes      Install Hermes Agent instructions (.hermes.md, local scope only)
+                       --all         Install all of the above platforms
+                       -g, --global  Install to home directory (~/.agents) instead of local repository
+                       -y, --yes     Bypass interactive menu and use auto-detection
+  add/skills/skill   Add/install modular skills into the local workspace
+                     Usage:
+                       npx github:dyphn1/Harness-everything add [skill-names...]
+                       Options:
+                         -g, --global  Install skills to home directory (~/.agents/skills)
+                       (Runs interactively if no skill names are specified)
+  uninstall          Remove Harness OS hooks, advisory files & skills
+                     Options:
+                       --local       Remove from local workspace
+                       -g, --global  Also remove from home directory (~/.agents, etc.)
+                       --skills      Remove installed skills
+                       -y, --yes     Bypass interactive menu (local + skills only,
+                                     unless --global is also passed)
+                     (Runs interactively if no flags are specified)
+  self-regression    Run syntax and routing checks before committing changes (alias: test)
+
+Options:
+  --help, -h         Show this help text
+`);
+}
+
+function runInstaller(installArgs) {
+  const installerPath = path.resolve(__dirname, '..', 'scripts', 'installer.js');
+  // Dynamic require or spawn
+  if (fs.existsSync(installerPath)) {
+    require(installerPath);
+  } else {
+    console.error("[Error] Installer script not found at scripts/installer.js");
+    process.exit(1);
+  }
+}
+
+function runSelfRegression() {
+  const regressionPath = path.resolve(__dirname, '..', 'self-evolve', 'scripts', 'self-regression.js');
+  if (fs.existsSync(regressionPath)) {
+    const result = spawnSync('node', [regressionPath], { stdio: 'inherit' });
+    process.exit(result.status);
+  } else {
+    console.error("[Error] Self-regression script not found.");
+    process.exit(1);
+  }
+}

package/build-multi-agent-system/AGENTS.md

@@ -0,0 +1,50 @@
+# build-multi-agent-system - AI Authoring Guide
+
+> This repository hosts a single, complex AI skill designed to deploy a multi-agent architecture. This document serves as a Meta-Authoring Guide, dictating how AI agents should interact with, modify, or extend this skill without breaking its core rules.
+
+## Directory Structure & Taxonomy
+
+Respect the semantic boundaries of this repository:
+
+| Directory/File | Purpose / Rules |
+|---|---|
+| `SKILL.md` | The core AI instruction file. Contains the environment audit, scaffolding rules, memory implementation, and router logic. |
+| `LICENSE` | The open-source license. Do not modify. |
+
+## How to Extend (Modifying the Skill)
+
+When asked by the user to update or extend the `build-multi-agent-system` skill, you **MUST strictly follow this procedure**:
+
+### 1. Locate and Read
+- Read the root `SKILL.md` to understand the existing execution pipeline, phase logic, and strict constraints.
+- Understand the "6 Functional Zones" and the "Bootstrap Protocol".
+
+### 2. Modify `SKILL.md`
+When updating the file, it MUST retain:
+- The YAML frontmatter block containing the `name` and `description`.
+- The `## Core Principles` section enforcing the cognitive loop (Think > Try > Summarize > Record).
+- The `## [State Checkpoint]` validating the working directory.
+- Sequential workflow phases (`[Discovery Phase...]`, `[Execution Phase...]`, `[Verification Phase]`).
+
+### 3. Provide Resources
+If adding complex features (e.g., a new fallback memory indexer script language), avoid bloating `SKILL.md`. Consider introducing an `examples/` directory to store reference code, though prefer keeping the core logic concise.
+
+---
+
+## Frontmatter Schema
+
+The `SKILL.md` MUST always begin with this exact YAML structure:
+
+```yaml
+---
+name: "build-multi-agent-system"
+description: >
+  Deploy a universal, self-adapting Multi-Agent Architecture into any project. It dynamically analyzes the tech stack to scaffold a token-efficient workspace with strict physical boundaries, hybrid SQLite memory, and isomorphic alignment protocols.
+---
+```
+
+## Constraints & Gotchas
+
+- **Cognitive Loop Integrity**: Any new steps added to the skill must align with the Think > Try > Summarize > Record methodology.
+- **Isomorphism**: When adding tech-stack-specific scaffolding logic, do not break support for general repositories. The skill must remain polyglot.
+- **Variables**: Never use single braces `{}` for variables in prompts; use double braces `{{VARIABLE}}`. Keep instructions terse and directive.

package/build-multi-agent-system/README.md

@@ -0,0 +1,63 @@
+# build-multi-agent-system
+
+> Deploy a universal, self-adapting Multi-Agent Architecture into any project. It dynamically analyzes the tech stack to scaffold a token-efficient workspace with strict physical boundaries, hybrid SQLite memory, and isomorphic alignment protocols.
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+
+## Overview
+
+This skill installs the physical landing gear ("where the agent lives") for a multi-agent team inside any repository. By dynamically adapting to the project's native ecosystem, it enforces physical isolation of context and cognitive metabolism, preventing the agent team from drowning in unstructured logs. It sets up 6 distinct functional zones, a relational SQLite memory indexer, and an immutable `AGENTS.md` router to keep token burn low and mitigate hallucination.
+
+---
+
+## Usage
+
+Invoke the skill in GitHub Copilot Chat (or your preferred AI agent) with a prompt like:
+
+- "Deploy a multi-agent system into this project"
+- "Install the multi-agent workspace architecture here"
+- "Set up the cognitive OS and functional zones for this repo"
+
+---
+
+## How it Works (Workflow)
+
+When invoked, the skill automatically executes the following steps:
+
+1. **Environment Audit**: Analyzes the project's tech stack (e.g., `package.json`, `pyproject.toml`) and deduces required sub-agent roles, mandating a PM (Coordinator) and Challenger (Alignment Enforcer).
+2. **Structural Scaffolding**: Maps and creates the 6 Functional Zones (`[State]`, `[Logs]`, `[Decisions]`, `[Domain]`, `[Architecture]`, `[Roles]`) adapted to the project's ecosystem.
+3. **Hybrid Memory Implementation**: Generates a polyglot memory indexer script that parses YAML frontmatter/Markdown headers to build a local SQLite `memory.db` for low-token queries.
+4. **The Immutable Router**: Hardcodes an `AGENTS.md` router at the project root, defining the Bootstrap Protocol, Cognitive Metabolism, and Adaptive Alignment.
+5. **Verification**: Executes the generated memory indexer script to initialize the database and summarizes the deployed architecture to the user.
+
+*(See the `SKILL.md` file for the exact machine-readable instructions.)*
+
+---
+
+## Key Rules & Constraints
+
+- **Adaptive Architecture**: The system must adapt its folder names and paths to the project's native ecosystem (e.g., `docs/`, `.agents/`) rather than forcing a rigid template.
+- **Immutable Router**: The generated `AGENTS.md` is the system's brain and is strictly protected from sub-agent modification.
+- **Non-blocking Release**: Agents must log subjective reviews asynchronously and never halt execution waiting for human input.
+
+---
+
+## Resources & File Structure
+
+This skill utilizes the following structure:
+
+```text
+.
+├── SKILL.md       # Core AI instructions and workflow definition
+└── LICENSE        # Apache 2.0 License
+```
+
+---
+
+## Contributing
+
+Open a PR to update the core workflow in `SKILL.md`. Ensure that the cognitive loop (Think > Try > Summarize > Record) and the 6 functional zones remain enforced.
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE) for details.

package/build-multi-agent-system/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: build-multi-agent-system
+description: 'Deploy a universal, self-adapting Multi-Agent Architecture into any project. It dynamically analyzes the tech stack to scaffold a token-efficient workspace with strict physical boundaries, hybrid SQLite memory, and isomorphic alignment protocols.'
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+---
+
+# Universal Multi-Agent Workspace Installer
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Tier 3 task requiring a multi-agent workspace to be scaffolded from scratch; explicit request to initialize a multi-agent system. |
+| **Expected Output** | A scaffolded 6-zone folder structure, a generated `index_memory` script that builds `memory.db` (SQLite relational index), and an immutable `AGENTS.md` router (< 50 lines) at the project root. |
+| **State Mutations** | Creates/rewrites `AGENTS.md`; creates the 6 functional zone directories; creates and runs the memory indexer script; writes `memory.db`. |
+| **Enforcement Gate** | MUST run the generated `index_memory` script once and verify it executes cleanly before the task is considered complete. `AGENTS.md` MUST include a directive forbidding sub-agents from modifying it. |
+
+## Core Principles
+- MUST operate using the cognitive loop: Think > Try > Summarize > Record.
+- [Think] Map the project state before altering it. The architecture must adapt to the project's native ecosystem, not force a rigid template.
+- [Try] Build the architecture incrementally. Ensure all constraints are physically enforced by the file system or explicit router rules.
+- [Summarize] Verify that the cognitive pathways (the 6 functional zones) are clearly isolated and language-appropriate.
+- [Record] Leave behind a robust memory indexer and an immutable `AGENTS.md` router as the permanent handoff.
+
+## Cognitive Foundation (The Meta-Framework)
+- `install-cognitive-os` defines *how an agent thinks*. `self-evolve` defines *how an agent learns*.
+- THIS skill defines **WHERE the agent lives**. It is the physical landing gear.
+- Without a strict folder structure and relational index, a multi-agent team will eventually drown in its own Markdown logs, leading to massive token burn and hallucination.
+- This skill enforces "Physical Isolation of Context" and "Cognitive Metabolism", but adapts its implementation dynamically based on the project's domain (Software, Research, Writing, etc.).
+
+## [State Checkpoint]
+- MUST verify the current working directory is the root of the target project.
+- MUST verify we have read/write access to create directories and scripts.
+
+## [Discovery Phase: Environment Audit]
+1. Tech Stack & Domain Analysis: MUST analyze the project (e.g., read `package.json`, `pyproject.toml`, or general file extensions) to determine the primary language and domain.
+2. Dynamic Role Deduction: MUST deduce the required sub-agent roles from a standard Archetype Pool (e.g., Frontend, Backend, Data, Writer).
+   - *Mandatory Roles:* PM (Coordinator) and Challenger (Alignment Enforcer) MUST always be included.
+
+## [Execution Phase: Structural Scaffolding]
+3. Isomorphic Zone Mapping: MUST implement the "6 Functional Zones", adapting the folder names/paths to the project's ecosystem if necessary (e.g., `docs/`, `.agents/`, `.cursor/`), while preserving their strict semantic purpose:
+   - `[State]`: High-frequency, volatile working state (Max 100 lines).
+   - `[Logs]`: Raw dialogue and verification outputs (Strictly excluded from default PM context).
+   - `[Decisions]`: Distilled Project Memory (ADRs, Read-on-demand via Index).
+   - `[Domain]`: Immutable product vision / core rules.
+   - `[Architecture]`: Immutable technical contracts / style guides.
+   - `[Roles]`: Individual sub-agent system prompts.
+
+## [Execution Phase: Hybrid Memory Implementation]
+4. Polyglot Indexer Generation: MUST generate an `index_memory` script in the project's primary language (e.g., Python, Node.js, Bash) or provide a pure CLI fallback.
+   - The script MUST parse YAML frontmatter/Markdown headers across the documentation zones.
+   - It MUST build a local SQLite database (`memory.db`) to serve as a relational index, enabling low-token historical queries.
+
+## [Execution Phase: The Immutable Router]
+5. Hardcoded Laws: MUST create or rewrite `AGENTS.md` at the project root. This file is the system's brain and must be strictly protected:
+   - It MUST include a directive forbidding sub-agents from modifying it.
+   - It MUST be a lightweight router (< 50 lines).
+   - It MUST define the "Bootstrap Protocol" (Read Payload -> Read State -> Delegate without reading full history).
+   - It MUST enforce "Cognitive Metabolism" (Strict line limits triggering Distillation cycles).
+   - It MUST enforce "Adaptive Alignment" (Path-based escalation matrix invoking the Challenger).
+   - It MUST explicitly state the "Non-blocking Release" rule: agents log subjective reviews asynchronously and never halt execution waiting for human input.
+
+## [Verification Phase]
+6. MUST run the generated `index_memory` script once to initialize the `memory.db` and verify it executes cleanly in the user's environment.
+7. MUST summarize the deployed architecture and the dynamically deduced roles to the user.
+
+[Exit: Await User Instruction]