harness-everything 0.2.2 → 0.3.6

package/create-agent-launcher/guidelines/platform-gemini.md

@@ -1,101 +0,0 @@
----
-description: "Platform guidelines for generating agent scaffolds targeting Gemini (Google). Covers strict naming rules, tool declarations via config.yaml, directory layout, and interaction mechanisms."
----
-
-# Platform Guidelines: Gemini (Google)
-
-## Naming Convention
-
-> **STRICT RULE — Naming validation regex**: `^[a-zA-Z0-9_-]{1,64}$`
-
-- **No spaces allowed.** Any space in an agent name will cause a **parse error**.
-- **No Chinese or special characters** — only letters, digits, underscores, and hyphens.
-- Use `snake_case` or `kebab-case` (e.g., `requirement_analyzer`, `backend-developer`).
-- Maximum 64 characters.
-
-| ❌ Invalid | ✅ Valid |
-|-----------|---------|
-| `Requirement Analyzer` | `requirement_analyzer` |
-| `Backend Developer` | `backend-developer` |
-| `Task Verifier` | `task_verifier` |
-
-## Tools Declaration
-
-Tools are declared in `.gemini/config.yaml`, not directly in agent files. Gemini supports MCP (Model Context Protocol) tool servers.
-
-When generating agent files from templates, substitute the placeholders as follows:
-- `{{TOOLS_ARRAY_DECLARATION}}`: *(Leave completely empty. Do not write `tools: []`)*
-- `{{READ_TOOL_NAME}}`: `read_file`
-- `{{EDIT_TOOL_NAME}}`: `edit_file`
-- `{{SEARCH_TOOL_NAME}}`: `search_codebase`
-- `{{EXECUTE_TOOL_NAME}}`: `run_in_terminal`
-
-```yaml
-# .gemini/config.yaml
-tools:
-  - name: read_file
-    type: builtin
-  - name: edit_file
-    type: builtin
-  - name: search_codebase
-    type: builtin
-  - name: my_mcp_server
-    type: mcp
-    server: "npx -y @my-org/mcp-server"
-```
-
-Note: Code modification tools (like `edit_file`) are subject to Google's safety review layer.
-
-## Directory Layout
-
-| Artifact | Path |
-|----------|------|
-| Agent definitions | `.gemini/agents/*.md` |
-| Tool config | `.gemini/config.yaml` |
-| System prompt / style guide | `.gemini/styleguide.md` |
-| Global config | `~/.config/google-gemini/` |
-
-Default target directory is `.gemini/`.
-
-## User Interaction Mechanism
-
-Gemini uses a built-in **block/confirmation mechanism** that pauses agent execution in the IDE Chat or terminal until the user responds.
-
-When making a workflow decision, output a clearly structured question block and wait for the user reply before proceeding:
-
-```
-[CONFIRMATION REQUIRED]
-Question: Which AI platform are you targeting?
-Options:
-  1. GitHub Copilot (VS Code)
-  2. Claude Code (Anthropic CLI)
-  3. Gemini (Google)
-  4. Codex / Custom API
-Please reply with the option number or your answer.
-```
-
-Do not proceed with file generation until the user has responded.
-
-## System Prompt / Instructions File
-
-After generating agents, ensure `.gemini/styleguide.md` contains the orchestrator rules and `.gemini/config.yaml` exists with tool declarations.
-
-## Agent File Format
-
-Markdown files under `.gemini/agents/`, using snake_case filenames:
-
-```markdown
-# requirement_analyzer
-
-**Role**: Requirement Analyzer
-
-You are an expert AI Architect...
-
-## Constraints
-...
-
-## Approach
-...
-```
-
-Combine with `.gemini/config.yaml` entries to declare which tools each conceptual agent can use.

package/create-agent-launcher/workflows/01-init.md

@@ -1,22 +0,0 @@
-# Phase 1: Platform & Location Preferences
-
-**[State Checkpoint]**
-- MUST verify the `Target Directory` absolute path passed from the previous step.
-
-## [Discovery & Inquiry Phase]
-1. Target Selection: MUST use `vscode_askQuestions` to ask platform and location in one prompt.
-   - Target Platform options MUST include Copilot, Claude, Gemini, and Codex.
-   - Target Location options MUST include Project Level and Global Level.
-   - MUST NOT auto-detect the platform.
-
-## [Validation & Research Phase]
-2. Load Guidelines: MUST read `guidelines/platform-<platform>.md` corresponding to the chosen platform. MUST treat this local file as the single source of truth. DO NOT perform web research for platform APIs unless explicitly instructed or if the file contains severe logic gaps.
-3. Conflict Assessment: MUST use the loaded layout rules to check if existing agents are already present in the target location within the `Target Directory`.
-
-## [Action Phase: Conflict Resolution]
-4. Preference Gathering: MUST use `vscode_askQuestions` to ask for Resilience Features configuration.
-5. Conflict Strategy: IF existing agents are found in the previous step, MUST ask for Conflict Resolution strategy (Safe Update, Backup & Overwrite, Smart Merge).
-
-## [Record: Handoff]
-6. State Packaging: MUST explicitly record the selected `Platform`, `Location`, `Resilience Features`, and `Conflict Strategy`.
-7. Handoff: MUST execute `workflows/02-analysis.md` and explicitly pass these variables alongside the `Target Directory`.

package/create-agent-launcher/workflows/02-analysis.md

@@ -1,26 +0,0 @@
-# Phase 2: Project Analysis
-
-**[State Checkpoint]**
-- MUST verify the inheritance of `Target Directory`, `Platform`, `Location`, `Resilience Features`, and `Conflict Strategy` from Phase 1.
-
-## [Discovery Phase: Content Extraction]
-1. Discovery Guide: MUST read `reference.md` for the discovery guide.
-2. Target Scanning: MUST scan the `Target Directory` for `README.md`, `AGENTS.md` (or `CLAUDE.md`), and build files (e.g., `package.json`, `*.sln`).
-3. Safe Extraction: For EACH discovered file, MUST read it securely and extract project name, tech stack, build commands, and architectural rules. IF a file does not exist, MUST skip it.
-4. Abstraction: MUST synthesize the extracted data into a `Context Profile` to prevent context bloat.
-
-## [Elimination & Evaluation Phase]
-5. Stack Detection: MUST determine the exact tech stack from the gathered signals (e.g., `.csproj` implies C#).
-6. Scope Limiting: MUST check for monorepo configuration (`pnpm-workspace.yaml`, `nx.json`).
-   - IF it IS a monorepo, MUST use `vscode_askQuestions` to ask the user to specify the target package/app. MUST NOT attempt to scaffold agents for the entire monorepo universally.
-7. Subagent Proposal: MUST propose specialist agents based on detected files (e.g., `.sh` implies Shell Expert). MUST NOT propose agents that duplicate core roles.
-
-## [Action Phase: User Confirmation & Gap Analysis]
-8. Selection: MUST use `vscode_askQuestions` to present a multi-select checklist of Subagents.
-   - MUST include Core agents: Requirement Analyzer, Backend Developer, Task Verifier.
-   - MUST include detected Specialist agents in the options.
-9. Batch Requirements Check: AFTER selection, MUST quickly assess the chosen templates for required Placeholders (e.g., `{{DB_TYPE}}`). IF the `Context Profile` lacks this data, MUST explicitly ask the user in ONE batched question to fill the gaps.
-10. Wait State: MUST wait for user to complete selection and variable input before proceeding.
-
-## [Record: Handoff]
-10. Handoff: MUST execute `workflows/03-generation.md` and explicitly pass the `Context Profile`, `Selected Agents`, and ALL Phase 1 variables.

package/create-agent-launcher/workflows/03-generation.md

@@ -1,29 +0,0 @@
-# Phase 3: Scaffold Generation
-
-**[State Checkpoint]**
-- MUST verify the inheritance of `Target Directory`, `Context Profile`, `Selected Agents`, and Phase 1 variables (`Platform`, `Conflict Strategy`, etc.).
-- MUST ensure terminal is located at the `Target Directory` BEFORE file modifications.
-
-## [Preparation Phase]
-1. Merge Strategy: MUST NOT overwrite existing agents blindly. MUST apply the `Conflict Strategy` selected in Phase 1. 
-   - IF `Smart Merge` is selected BUT the target agent belongs to a different platform architecture, MUST downgrade to `Backup & Overwrite` to prevent cross-platform hallucination.
-2. Semantic Integrity: IF Smart Merge, MUST perform Semantic Refactor aligning with Logical Consistency, Long-Term Memory, Self-Adaptation, and Self-Verification. MUST preserve original YAML Frontmatter.
-
-## [Action Phase: Generation]
-3. Template Iteration: For EACH selected agent in `Selected Agents`, MUST NOT read all templates at once to prevent context dilution. MUST process them one by one:
-   - MUST read the specific template.
-   - IF `Conflict Strategy` is Smart Merge AND the target file exists, MUST read the existing file BEFORE merging to prevent hallucination.
-   - MUST inject strict Cognitive Guardrails: MUST explicitly define Role Boundaries (refusing out-of-scope tasks), mandate the use of the Shared Memory Space (`memory-keeper`), and mandate deterministic outcome verification (no hallucinating success).
-   - MUST align generation with platform-specific capabilities (e.g., VS Code LSP tooltips vs Cursor rules) and inject localized task-tracking/TODO frameworks tailored to the target platform and specific agent role (ensuring each agent and platform gets its own isolated, native TODO tracking system, e.g., mapping to `manage_todo_list` for VS Code, `.cursorrules` checklists for Cursor, or unique agent-scoped status JSONs).
-   - MUST substitute placeholders using the `Context Profile`. IF a placeholder cannot be resolved, MUST NOT guess. MUST insert a conspicuous tag (e.g., `<<TODO: MANUAL_INPUT_REQUIRED>>` or localized `// TODO:` structured comments mapping to the active platform's task-tracking schema).
-   - MUST write files securely to destination paths from `guidelines/platform-<platform>.md`.
-4. Orchestrator Gen: MUST consult `guidelines/platform-<platform>.md` for Orchestrator requirements. MUST generate separate Orchestrator Instructions or update the root system prompt IF required.
-
-## [Summarize & Verification Phase]
-5. Integrity Check: MUST verify the generated files were written correctly to the disk by reading back portions or verifying their existence. Hallucinating success is forbidden.
-
-## [Record: Exit]
-6. Completion: MUST log successful Subagent generation.
-7. Handoff: MUST execute `workflows/04-launcher.md` and pass the `Context Profile`, `Selected Agents`, and paths of the newly created files to ensure the entry point is explicitly generated in a dedicated mental phase.
-
-[Exit: Await User Instruction]**'launch agent'** or describe your feature/task."

package/create-agent-launcher/workflows/04-launcher.md

@@ -1,20 +0,0 @@
-# Phase 4: Launcher Bootstrapping
-
-**[State Checkpoint]**
-- MUST verify the inheritance of `Target Directory`, `Context Profile`, `Selected Agents`, and paths of the newly created files from Phase 3.
-- MUST ensure terminal is located at the `Target Directory`.
-
-## [Action Phase: Entry Point Generation]
-1. Entry Point Gen: MUST read `templates/agent-launcher.md`.
-2. Handoff Integration: MUST substitute placeholders using the `Context Profile`. MUST dynamically inject the paths and roles of the `Selected Agents` into the Launcher, ensuring it accurately serves as the central router for the ecosystem.
-3. Disk Write: MUST save to the skill entry point path defined in the platform guidelines securely.
-
-## [Summarize: Verification]
-4. Check: MUST verify the Launcher was written successfully.
-
-## [Record: Exit]
-5. Completion: MUST report successful scaffold generation to the user. MUST provide a summary table of ALL generated files (including Subagents and the Launcher) and their status.
-6. UX Handoff: MUST prompt the user to launch their first agent workflow with a suggested message (e.g., "Agentic workflow scaffold is ready. To launch your first agent workflow, use the launcher...").
-7. Exit: MUST terminate execution.
-
-[Exit: Await User Instruction]

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

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

@@ -1,62 +0,0 @@
-# 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/eval-framework/behavioral-test.js

@@ -1,105 +0,0 @@
-#!/usr/bin/env node
-/**
- * Harness Behavioral Test Suite (E2E)
- * Simulates an AI agent attempting both valid and invalid state transitions
- * to mathematically prove the guardrails (Exit Code 1) are enforced.
- */
-const { execSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-const { getWorkspaceRoot, getStateRoot } = require('../hooks/scripts/lib/harness-state');
-
-console.log("=== 🧪 Harness Behavioral Test Suite ===");
-
-const todoCli = 'node harness-everything/scripts/todo-cli.js';
-const stateFile = path.join(getStateRoot(getWorkspaceRoot()), 'todo-state.json');
-
-function run(cmd, expectFail = false) {
-  try {
-    const out = execSync(cmd, { stdio: 'pipe', encoding: 'utf8' });
-    if (expectFail) {
-      console.error(`❌ FAILED: Expected command to fail, but it succeeded: ${cmd}`);
-      process.exit(1);
-    }
-    return out;
-  } catch (err) {
-    if (!expectFail) {
-      console.error(`❌ FAILED: Unexpected failure: ${cmd}\n${err.stderr || err.message}`);
-      process.exit(1);
-    }
-    return err.stderr || err.stdout || err.message;
-  }
-}
-
-// 0. Setup: Clean slate - but this suite runs against the REAL
-// .claude/harness-state/ directory of whatever project invokes it (e.g. via self-regression.js on
-// a contributor's machine), so any real in-flight todo-state.json must be
-// preserved, not clobbered. Back it up now and restore it on exit
-// (success, assertion failure, or process.exit alike - 'exit' fires on all
-// of them) instead of deleting real state outright.
-const stateBackup = stateFile + '.selfregression-backup';
-const hadExistingState = fs.existsSync(stateFile);
-if (hadExistingState) fs.copyFileSync(stateFile, stateBackup);
-if (fs.existsSync(stateFile)) fs.unlinkSync(stateFile);
-if (fs.existsSync('.verify-fail.tmp')) fs.unlinkSync('.verify-fail.tmp');
-console.log("🧹 State cleaned.");
-
-process.on('exit', () => {
-  try {
-    if (hadExistingState) {
-      fs.copyFileSync(stateBackup, stateFile);
-      fs.unlinkSync(stateBackup);
-    } else if (fs.existsSync(stateFile)) {
-      fs.unlinkSync(stateFile);
-    }
-    if (fs.existsSync('.verify-fail.tmp')) fs.unlinkSync('.verify-fail.tmp');
-  } catch (e) {
-    // Best-effort - don't mask the real test outcome with a cleanup error.
-  }
-});
-
-// 1. Initialize
-console.log("\n[Test 1] Agent initializes checklist...");
-run(`${todoCli} init "Setup DB" "Create API"`);
-console.log("✅ Passed: List initialized.");
-
-// 2. Premature Completion (Skipping 'start')
-console.log("\n[Test 2] Agent hallucinates completion without starting...");
-const res2 = run(`${todoCli} complete 1`, true);
-if (!res2.includes("NOT currently in-progress")) {
-  console.error("❌ FAILED: Did not catch premature completion.");
-  process.exit(1);
-}
-console.log("✅ Passed: Blocked premature completion (Exit Code 1).");
-
-// 3. Start Task
-console.log("\n[Test 3] Agent starts task 1...");
-run(`${todoCli} start 1`);
-console.log("✅ Passed: Task 1 started.");
-
-// 4. Multitasking (Attention Loss)
-console.log("\n[Test 4] Agent loses attention and tries to start Task 2 concurrently...");
-const res4 = run(`${todoCli} start 2`, true);
-if (!res4.includes("already IN-PROGRESS")) {
-  console.error("❌ FAILED: Did not block multitasking.");
-  process.exit(1);
-}
-console.log("✅ Passed: Blocked multitasking (Exit Code 1).");
-
-// 5. Verification Failure (Compliance Theater)
-console.log("\n[Test 5] Agent writes broken code and tries to force complete...");
-fs.writeFileSync('.verify-fail.tmp', 'broken');
-const res5 = run(`${todoCli} complete 1`, true);
-if (!res5.includes("Verification Gate Failed")) {
-  console.error("❌ FAILED: Verification gate failed to block completion.");
-  process.exit(1);
-}
-console.log("✅ Passed: Gate blocked completion and slapped agent (Exit Code 1).");
-
-// 6. Successful Verification and Completion
-console.log("\n[Test 6] Agent fixes code, verification passes, completes task...");
-fs.unlinkSync('.verify-fail.tmp'); // Fix the "bug"
-run(`${todoCli} complete 1`);
-console.log("✅ Passed: Task 1 completed successfully.");
-
-console.log("\n🎉 ALL BEHAVIORAL TESTS PASSED. Guardrails are mathematically enforced.");