harness-everything 0.3.6 → 0.4.0

package/plugins/harness-everything/skills/multi-agent-workspace/examples/typescript-cli.md

@@ -0,0 +1,126 @@
+---
+description: "Output example for multi-agent-workspace applied to a fictional TypeScript npm-workspaces monorepo CLI project (Acme CLI). Shows the Context Profile from project discovery and the expected generated agent content."
+---
+
+# Example: TypeScript npm Monorepo CLI (Acme CLI)
+
+This example shows what the Project Discovery step should extract from the project, and what the generated agent files should contain. **Acme CLI is a fictional project** — substitute your own project's real names, paths, and build commands.
+
+---
+
+## Input: Project Discovery Findings
+
+After reading `README.md`, `AGENTS.md` (project-specific AI notes), and `package.json`, the LLM should record this Context Profile:
+
+```
+Project Name:       Acme CLI
+Primary Language:   TypeScript / Node.js
+Full Build Command: npm run build  (runs scripts/build.sh across all packages)
+Local Build Command:npm run build -w packages/<package-name>
+Key Source Paths:   packages/core/src/ (core agent logic),
+                    packages/cli/src/ (CLI entry point and commands),
+                    packages/vscode-companion/ (VSCode integration)
+AI Plan Path:       docs/ai_plans/ at the repo root
+Monorepo Type:      npm workspaces
+Workspace File:     package.json (workspaces: ["packages/*"])
+Special Constraints:Run 'npm run lint' after build. Integration tests in integration-tests/.
+```
+
+**Key signals discovered from README.md and package.json:**
+- `"workspaces": ["packages/*"]` → npm workspaces monorepo
+- `"build": "scripts/build.sh"` → custom build script (not bare `tsc`)
+- `"lint": "eslint ."` → ESLint configured
+- Packages: `@acme/cli` (CLI entry), `@acme/cli-core` (core logic)
+- TypeScript config at root `tsconfig.json` and per-package
+
+---
+
+## Output: Generated Agent Files
+
+**`requirement-analyzer.agent.md` — Approach section:**
+```markdown
+## Approach
+
+1. **Analyze Requirements**: Review the requirements. Use `search` and `read` tools to
+   gather context from the relevant packages: `packages/core/src/` (core logic, tools,
+   and model integration), `packages/cli/src/` (CLI entry point, commands, and REPL),
+   and `packages/vscode-companion/` (VSCode companion extension) as applicable.
+2. **Handle Ambiguities**: Note critical ambiguities for the user; otherwise proceed.
+3. **Document**: Save a detailed implementation document at `docs/ai_plans/` as
+   `implement_<feature-name>.md` (e.g., `docs/ai_plans/implement_cli_auth.md`).
+   Include:
+   - Implementation Goals
+   - Approach / Methodology
+   - Detailed Implementation Steps
+   - Implementation Details (classes, APIs, files, package paths)
+   - Architecture Diagrams (if applicable)
+```
+
+**`backend-developer.agent.md` — full file:**
+```markdown
+---
+name: "Backend Developer"
+description: "Use when: you need to implement TypeScript/Node.js source code based on a requirement list or AI plan. This agent implements features and verifies them using 'npm run build'."
+tools: [read, edit, search, execute]
+---
+
+You are an expert TypeScript/Node.js Developer working in the **Acme CLI** monorepo.
+Your primary responsibility is to implement TypeScript source code strictly based on a
+provided requirement list or AI implementation document.
+
+## Approach
+
+1. **Analyze Requirements**: Read the provided implementation document in `docs/ai_plans/`.
+   Use `search` and `read` to understand the existing codebase in the relevant packages:
+   `packages/core/src/` (core logic and tools), `packages/cli/src/` (CLI commands
+   and REPL), and `packages/vscode-companion/` (VSCode integration).
+2. **Review Codebase (MANDATORY)**: Before making ANY modifications, read all source
+   files that will be affected.
+3. **Implement**: Use the `edit` tool to modify or create TypeScript source code.
+4. **Verify via Compilation/Linting — choose minimum scope**:
+   - **Step 1 — Assess scope**: Did you only change files inside a single package (e.g., only
+     `packages/cli/src/`)? → **Local build**. Did you change a shared type, a public export
+     from `packages/core/`, or a root-level config? → **Full workspace build**.
+   - **Local build** (single package, fastest):
+     `npm run build -w packages/<package-name>`
+     (e.g., `npm run build -w packages/cli`)
+   - **Full workspace build** (when shared exports or cross-package types change):
+     `npm run build` (runs the full `scripts/build.sh` pipeline)
+   - **After any build**: Run `npm run lint` to ensure linting passes.
+   - Prefer local build first. Escalate to full workspace only when the assessment above requires it.
+
+## Constraints
+
+- DO NOT modify the requirements. Your job is strictly implementation.
+- You MUST thoroughly read all relevant existing files before writing any code.
+- ALWAYS ensure the code compiles and lint passes before considering your task complete.
+- Fix all compilation and lint errors before finishing.
+```
+
+**`agent-launcher/SKILL.md` — Project-Specific Notes section:**
+```markdown
+## Project-Specific Notes
+
+- **Build verification**: `npm run build` (full workspace via `scripts/build.sh`)
+  or `npm run build -w packages/<name>` for a single package
+- **Lint**: Always run `npm run lint` after build
+- **AI plan documents**: Save at `docs/ai_plans/implement_<name>.md` (or `fix_<name>.md`),
+  repo-root-relative — never an absolute disk path
+- **Primary language**: TypeScript / Node.js
+- **Monorepo notes**: npm workspaces (`packages/*`). Key packages:
+  `packages/core` (`@acme/cli-core`) and `packages/cli` (`@acme/cli`).
+  Integration tests live in `integration-tests/`.
+```
+
+---
+
+## Key Specificity Points
+
+| Element | Expected in Generated Agent |
+|---------|-----------------------------|
+| Source paths | `packages/core/src/` (core logic), `packages/cli/src/` (CLI commands), with role annotations |
+| Path style | Always repo-root-relative — generated agents must never contain absolute disk paths |
+| Build scope decision | Assess scope first; prefer `npm run build -w packages/<name>` before escalating to full build |
+| Lint requirement | Explicit: always run `npm run lint` after any build |
+| Package identity | `@acme/cli-core` and `@acme/cli` (not just "the workspace") |
+| AI plan example | `docs/ai_plans/implement_cli_auth.md` (real naming pattern) |

package/plugins/harness-everything/skills/multi-agent-workspace/guidelines/platform-claude.md

@@ -0,0 +1,77 @@
+---
+description: "Platform guidelines for generating agent scaffolds targeting Claude Code (Anthropic CLI). Covers naming, tool declarations, directory layout, and interaction mechanisms."
+---
+
+# Platform Guidelines: Claude Code (Anthropic CLI)
+
+## Naming Convention
+
+- Agent names must use **lowercase with hyphens** (e.g., `requirement-analyzer`, `backend-developer`).
+- No spaces allowed in agent names or identifiers.
+- File names follow the same convention (e.g., `requirement-analyzer.md`).
+
+## Tools Declaration
+
+Use Claude Code's exact tool name strings as a YAML array:
+
+```yaml
+tools: ["Read", "Edit", "Glob", "Grep", "Bash", "AskUserQuestion"]
+```
+
+When generating agent files from templates, substitute the placeholders as follows:
+- `{{TOOLS_ARRAY_DECLARATION}}`: `tools: ["Read", "Edit", "Glob", "Grep", "Bash", "AskUserQuestion"]` (exclude `"Bash"` for Requirement Analyzer)
+- `{{READ_TOOL_NAME}}`: `"Read"`
+- `{{EDIT_TOOL_NAME}}`: `"Edit"`
+- `{{SEARCH_TOOL_NAME}}`: `"Glob" and "Grep"`
+- `{{EXECUTE_TOOL_NAME}}`: `"Bash"`
+
+> **CRITICAL RULE — AskUserQuestion is MANDATORY**: When generating a **restricted** tool list (i.e., any list that does not include all tools), you MUST always include `"AskUserQuestion"` in the array. If this tool is omitted, the agent will lose the ability to ask clarifying questions and will enter a **deadlock state** — unable to proceed or request help.
+
+## Directory Layout
+
+| Artifact | Path |
+|----------|------|
+| Agent definitions | `.claude/agents/*.md` |
+| Output styles | `.claude/output-styles/` |
+| System prompt | `CLAUDE.md` (project root) |
+| Global config | `~/.claude/output-styles/` |
+
+Default target directory is `.claude/`.
+
+## User Interaction Mechanism
+
+Use the built-in `AskUserQuestion` tool to pause the agent loop and prompt the user:
+
+```
+AskUserQuestion(
+  question: "Where should the agent scaffold be created?",
+  options: [".claude/ (default)", "Custom path"]
+)
+```
+
+This renders as an interactive prompt in the CLI terminal, blocking execution until the user responds.
+
+## System Prompt / Instructions File
+
+After generating agents, ensure `CLAUDE.md` at the project root contains the orchestrator rules. If `CLAUDE.md` does not exist, create it with the State Machine block.
+
+## Agent File Format
+
+Plain Markdown files under `.claude/agents/`:
+
+```markdown
+# requirement-analyzer
+
+**Role**: Requirement Analyzer  
+**Tools**: Read, Edit, Glob, Grep, AskUserQuestion
+
+You are an expert AI Architect...
+
+## Constraints
+...
+
+## Approach
+...
+```
+
+YAML frontmatter is optional in Claude agents; use a `# heading` and `**field**:` pattern instead if preferred.

package/plugins/harness-everything/skills/multi-agent-workspace/guidelines/platform-codex.md

@@ -0,0 +1,146 @@
+---
+description: "Platform guidelines for generating agent scaffolds targeting Codex / Custom API environments. Covers naming, OpenAI Tool Spec / JSON Schema format, directory layout, and custom ask_user function calling."
+---
+
+# Platform Guidelines: Codex / Custom API Environment
+
+## Naming Convention
+
+- Follow system variable / key-value naming conventions (e.g., `requirement_analyzer`, `backend_developer`).
+- Use lowercase with underscores or hyphens; avoid spaces.
+- Names serve as JSON object keys — they must be valid identifiers in most languages.
+
+## Tools Declaration
+
+There are **no built-in tools**. All tools must be defined using the **OpenAI Tool Spec (JSON Schema)** format and implemented in your local orchestrator code.
+
+When generating agent files from templates (if not using pure JSON), substitute the placeholders as follows:
+- `{{TOOLS_ARRAY_DECLARATION}}`: *(Leave empty in Markdown, handled via JSON configuration)*
+- `{{READ_TOOL_NAME}}`: `read_file`
+- `{{EDIT_TOOL_NAME}}`: `write_file`
+- `{{SEARCH_TOOL_NAME}}`: `search`
+- `{{EXECUTE_TOOL_NAME}}`: `execute_command`
+
+Each agent definition includes a `tools` array of JSON Schema objects:
+
+```json
+{
+  "agents": {
+    "requirement_analyzer": {
+      "name": "requirement_analyzer",
+      "description": "Analyzes user requirements and creates implementation documents.",
+      "tools": [
+        {
+          "type": "function",
+          "function": {
+            "name": "read_file",
+            "description": "Read a file from the project.",
+            "parameters": {
+              "type": "object",
+              "properties": {
+                "path": { "type": "string", "description": "File path to read." }
+              },
+              "required": ["path"]
+            }
+          }
+        },
+        {
+          "type": "function",
+          "function": {
+            "name": "ask_user",
+            "description": "Pause the agent loop and ask the user a question.",
+            "parameters": {
+              "type": "object",
+              "properties": {
+                "question": { "type": "string" },
+                "options": {
+                  "type": "array",
+                  "items": { "type": "string" }
+                }
+              },
+              "required": ["question"]
+            }
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+## Directory Layout
+
+All paths are **custom** — defined by the local orchestrator implementation:
+
+| Artifact | Suggested Path |
+|----------|---------------|
+| Agent definitions | `config/agents/*.json` or `config/agents.json` |
+| System prompt | `config/system_prompt.txt` |
+| Tool schemas | `config/tools/*.json` |
+| Global config | `~/.config/myapp/` or as defined by your app |
+
+Default target directory is `config/`.
+
+## User Interaction Mechanism
+
+There is **no built-in confirmation mechanism**. Implement a custom `ask_user` function tool that follows the OpenAI Function Calling / Tool Use pattern:
+
+1. The agent calls `ask_user` with a `question` and optional `options`.
+2. The API returns the function call in its response.
+3. Your **local orchestrator code** intercepts the call, renders the UI (terminal prompt, web form, etc.), and submits the user's answer back as a tool result.
+4. The agent resumes execution.
+
+The `ask_user` schema should mirror `vscode_askQuestions` for portability:
+
+```json
+{
+  "type": "function",
+  "function": {
+    "name": "ask_user",
+    "description": "Ask the user a question and wait for their response before continuing.",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "header": { "type": "string", "description": "Short identifier for the question." },
+        "question": { "type": "string", "description": "The question to ask." },
+        "options": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "label": { "type": "string" },
+              "recommended": { "type": "boolean" }
+            },
+            "required": ["label"]
+          }
+        },
+        "allowFreeformInput": { "type": "boolean", "default": true }
+      },
+      "required": ["header", "question"]
+    }
+  }
+}
+```
+
+## System Prompt / Instructions File
+
+The system prompt format is fully custom. Suggested location: `config/system_prompt.txt` or `config/system_prompt.md`. Include the orchestrator rules adapted for your API loop implementation.
+
+## Agent File Format
+
+Agent definitions are typically JSON objects:
+
+```json
+{
+  "name": "requirement_analyzer",
+  "description": "Analyzes requirements and creates implementation documents.",
+  "system_prompt": "You are an expert AI Architect...",
+  "tools": ["read_file", "edit_file", "ask_user"],
+  "constraints": [
+    "DO NOT implement features yourself.",
+    "ALWAYS create a structured implementation document first."
+  ]
+}
+```
+
+Implement `read_file`, `edit_file`, and all other tools referenced in `tools` arrays in your orchestrator's backend code.

package/plugins/harness-everything/skills/multi-agent-workspace/guidelines/platform-continue.md

@@ -0,0 +1,38 @@
+---
+description: "Platform guidelines for generating agent scaffolds targeting Continue.dev. Covers naming, tool declarations, directory layout, and interaction mechanisms."
+---
+
+# Platform Guidelines: Continue.dev
+
+## Naming Convention
+
+- Rule files use kebab-case (e.g., `harness.md`, `backend-developer.md`).
+
+## Tools Declaration
+
+Continue manages tool execution permissions at the extension level. Use standard intent names:
+
+```yaml
+tools: [read, edit, search, execute]
+```
+
+When generating agent files from templates, substitute the placeholders as follows:
+- `{{TOOLS_ARRAY_DECLARATION}}`: `tools: [read, edit, search, execute]`
+- `{{READ_TOOL_NAME}}`: `read`
+- `{{EDIT_TOOL_NAME}}`: `edit`
+- `{{SEARCH_TOOL_NAME}}`: `search`
+- `{{EXECUTE_TOOL_NAME}}`: `execute`
+
+## Directory Layout
+
+| Artifact | Path |
+|----------|------|
+| Native Project Rules | `.continue/rules/*.md` (project) / `~/.continue/rules/*.md` (global) |
+| System Prompt | `.continue/rules/harness.md` (with YAML frontmatter `alwaysApply: true`) |
+
+Default target directory is `.continue/rules/`.
+
+## User Interaction & Enforcement Mechanism
+
+Continue.dev does not provide lifecycle execution hooks. Rules are loaded with `alwaysApply: true` frontmatter and act as **Advisory Guidance**.
+Ask clarifying questions directly within the Continue Chat interface.

package/plugins/harness-everything/skills/multi-agent-workspace/guidelines/platform-copilot.md

@@ -0,0 +1,74 @@
+---
+description: "Platform guidelines for generating agent scaffolds targeting GitHub Copilot (VS Code). Covers naming, tool declarations, directory layout, and interaction mechanisms."
+---
+
+# Platform Guidelines: GitHub Copilot (VS Code)
+
+## Naming Convention
+
+- Agent names are **flexible** — spaces, Chinese characters, and mixed case are allowed.
+- Recommended style: Title Case with spaces (e.g., `Requirement Analyzer`, `Backend Developer`).
+- File names use kebab-case (e.g., `requirement-analyzer.agent.md`).
+
+## Tools Declaration
+
+Use the VS Code-encapsulated permission names as a YAML array:
+
+```yaml
+tools: [read, edit, search, execute]
+```
+
+When generating agent files from templates, substitute the placeholders as follows:
+- `{{TOOLS_ARRAY_DECLARATION}}`: `tools: [read, edit, search, execute]` (exclude `execute` for Requirement Analyzer)
+- `{{READ_TOOL_NAME}}`: `read`
+- `{{EDIT_TOOL_NAME}}`: `edit`
+- `{{SEARCH_TOOL_NAME}}`: `search`
+- `{{EXECUTE_TOOL_NAME}}`: `execute`
+
+## Directory Layout
+
+| Artifact | Path |
+|----------|------|
+| Agent definitions | `<target_dir>/agents/*.agent.md` |
+| Orchestrator instructions | `<target_dir>/instructions/orchestrator.instructions.md` |
+| Skill entry point | `<target_dir>/skills/agent-launcher/SKILL.md` |
+| System prompt | `.github/copilot-instructions.md` |
+| Global config | `~/.config/github-copilot/` |
+
+Default `<target_dir>` is `.github/`.
+
+## User Interaction Mechanism
+
+Use the `vscode_askQuestions` tool to pause the workflow and prompt the user for decisions.
+
+```json
+[{
+  "header": "unique_key",
+  "question": "Your question here?",
+  "options": [
+    { "label": "Option A", "recommended": true },
+    { "label": "Option B" }
+  ],
+  "allowFreeformInput": true
+}]
+```
+
+This renders as a dropdown or input box in the VS Code window.
+
+## System Prompt / Instructions File
+
+After generating agents, ensure `.github/copilot-instructions.md` contains the `## 🤖 State Machine Orchestrator Instructions` block. If the file does not exist, create it.
+
+## Agent File Format
+
+Standard `.agent.md` file with YAML frontmatter:
+
+```yaml
+---
+name: "Requirement Analyzer"
+description: "Use when: ..."
+tools: [read, edit, search]
+---
+```
+
+All files MUST include a YAML frontmatter `description` field for context optimization.

package/plugins/harness-everything/skills/multi-agent-workspace/guidelines/platform-cursor.md

@@ -0,0 +1,40 @@
+---
+description: "Platform guidelines for generating agent scaffolds targeting Cursor. Covers naming, tool declarations, directory layout, and interaction mechanisms."
+---
+
+# Platform Guidelines: Cursor
+
+## Naming Convention
+
+- Agent/Rule names use lower-kebab-case (e.g., `requirement-analyzer`, `backend-developer`).
+- File names follow `.cursorrules` or `.cursor/rules/*.mdc` depending on project structure.
+
+## Tools Declaration
+
+Cursor manages tool permissions natively through its IDE setting UI. Use standard tool intent categories:
+
+```yaml
+tools: [read, edit, search, execute]
+```
+
+When generating agent files from templates, substitute the placeholders as follows:
+- `{{TOOLS_ARRAY_DECLARATION}}`: `tools: [read, edit, search, execute]`
+- `{{READ_TOOL_NAME}}`: `read`
+- `{{EDIT_TOOL_NAME}}`: `edit`
+- `{{SEARCH_TOOL_NAME}}`: `search`
+- `{{EXECUTE_TOOL_NAME}}`: `execute`
+
+## Directory Layout
+
+| Artifact | Path |
+|----------|------|
+| Native Project Rules | `.cursorrules` (project root) |
+| Modular Rule Definitions | `.cursor/rules/*.mdc` |
+| System Prompt | `.cursorrules` |
+
+Default target directory is `.cursor/`.
+
+## User Interaction & Enforcement Mechanism
+
+Cursor does not provide lifecycle hooks or exit code interception. All rule files operate as **Advisory Context** injected into the model prompt.
+Ask questions directly in chat or request user confirmation before major file modifications.

package/plugins/harness-everything/skills/multi-agent-workspace/guidelines/platform-hermes.md

@@ -0,0 +1,38 @@
+---
+description: "Platform guidelines for generating agent scaffolds targeting Hermes Agent (Nous Research). Covers naming, tool declarations, directory layout, and interaction mechanisms."
+---
+
+# Platform Guidelines: Hermes Agent (Nous Research)
+
+## Naming Convention
+
+- Uses `.hermes.md` project-level context file or standard markdown rules files.
+
+## Tools Declaration
+
+Hermes Agent auto-detects CLI capabilities. Use standard tool declarations:
+
+```yaml
+tools: [read, edit, search, execute]
+```
+
+When generating agent files from templates, substitute the placeholders as follows:
+- `{{TOOLS_ARRAY_DECLARATION}}`: `tools: [read, edit, search, execute]`
+- `{{READ_TOOL_NAME}}`: `read`
+- `{{EDIT_TOOL_NAME}}`: `edit`
+- `{{SEARCH_TOOL_NAME}}`: `search`
+- `{{EXECUTE_TOOL_NAME}}`: `execute`
+
+## Directory Layout
+
+| Artifact | Path |
+|----------|------|
+| Native Context | `.hermes.md` (project root) |
+| Fallback Context | Reads `AGENTS.md` / `CLAUDE.md` / `.cursorrules` if present |
+
+Default target directory is project root (`.hermes.md`).
+
+## User Interaction & Enforcement Mechanism
+
+Hermes Agent loads `.hermes.md` into session context. Like other non-hook platforms, enforcement is **Advisory Only**.
+Interactions and question prompting happen in the Hermes terminal or web UI session.

package/plugins/harness-everything/skills/multi-agent-workspace/guidelines/role-capabilities.md

@@ -0,0 +1,108 @@
+---
+description: >
+  Capability menu for multi-agent-workspace. Maps Karpathy behavioral guidelines and
+  skill-derived behaviors to each subAgent role. Consult when generating any agent file.
+  Core roles use the templates directly. Specialist and custom roles inject the blocks below
+  into templates/specialist-agent.md.
+---
+
+# Agent Role Capabilities Reference
+
+## How to Use This File
+
+When generating a specialist or custom agent (using `templates/specialist-agent.md`), pick the appropriate `## Behavioral Guidelines` block from this file and inject it into the `{{BEHAVIORAL_GUIDELINES_BLOCK}}` placeholder. Do not mix capabilities — keep roles strictly separated to avoid LLM context dilution.
+
+---
+
+## Specialist Role Blocks
+
+### Document Writer (Markdown Editor)
+
+**Purpose**: Edit, format, and structure Markdown files (e.g., `README.md`, `docs/`) without touching source code.
+
+**Ready-to-Embed Block**:
+
+```markdown
+### Architect, Not a Coder
+*(from Karpathy: Think Before Coding)*
+- Your domain is strictly documentation and markdown. DO NOT write or modify application source code.
+- If documentation requirements are unclear, provide 2-3 structured outline options for the user to choose from. Do not guess.
+
+### Surgical Documentation Updates
+*(from Karpathy: Surgical Changes)*
+- When updating an existing document, touch ONLY the section that requires changes.
+- Preserve existing prose, formatting, and screenshots exactly as they are.
+- Do not "improve" or rewrite adjacent paragraphs unless explicitly asked.
+```
+
+---
+
+### Shell Script Expert
+
+**Purpose**: Create, fix, and maintain bash, batch, or CI pipeline scripts.
+
+**Ready-to-Embed Block**:
+
+```markdown
+### Blind Obedience to the Task
+*(from Karpathy: Simplicity First)*
+- ONLY implement exactly what the task requires. DO NOT question the design or add pre-emptive abstraction.
+- Keep scripts as simple and POSIX-compliant as possible unless a specific shell (e.g., bash) is requested.
+
+### Instrument and Diagnose Silently
+*(from Karpathy: Goal-Driven Execution + skill: diagnose)*
+- If a script fails during verification, do not immediately ask for help.
+- Generate a hypothesis, add echo/set -x instrumentation, run it to confirm, and fix it silently.
+- Only output a Handover Block when the script executes successfully.
+```
+
+---
+
+### Frontend Developer
+
+**Purpose**: Implement UI components and styling based on design requirements.
+
+**Ready-to-Embed Block**:
+
+```markdown
+### Blind Obedience to the Design
+*(from Karpathy: Simplicity First)*
+- Implement exactly what the UI specification requires. Do not add unsolicited animations, extra state management, or "future-proofing".
+- If a simpler DOM structure achieves the exact same visual result, prefer it.
+
+### Surgical UI Changes
+*(from Karpathy: Surgical Changes)*
+- Touch only the components explicitly mentioned in the plan.
+- Match the existing project styling system (e.g., Tailwind, CSS Modules) exactly.
+- Do not refactor adjacent UI components just because you are in the file.
+```
+
+---
+
+### Architecture Reviewer
+
+**Purpose**: Perform broad structural audits and compliance checks. Read-only.
+
+**Ready-to-Embed Block**:
+
+```markdown
+### Map Before Analyzing
+*(from skill: zoom-out)*
+- Before rendering a verdict, you MUST map all relevant modules and architectural boundaries.
+- Do not make assumptions based on a single file; trace the dependency graph.
+
+### Strict Compliance Verification
+*(from skill: grill-with-docs)*
+- Compare the current structure against the project's Architectural Decision Records (ADRs) or established patterns.
+- Do not suggest subjective "clean code" improvements; only report objective architectural violations.
+- You are Read-Only. Do not modify files to fix the architecture.
+```
+
+---
+
+## Custom Roles (Decision Matrix)
+
+If the user asks for a completely undefined role (e.g., "Database Expert"), compose a custom block using this philosophy:
+1. Is this a **thinking/planning** role? → Give it *Think Before Coding* (propose options, don't guess).
+2. Is this an **execution/coding** role? → Give it *Blind Obedience* (execute exactly, keep it simple) and *Surgical Changes* (touch only what's needed).
+3. Is this an **auditing/QA** role? → Give it *Strict Binary Verification* (pass/fail only, no modifications).

package/plugins/harness-everything/skills/multi-agent-workspace/references/agency-agents.md

@@ -0,0 +1,31 @@
+# agency-agents source contract
+
+`agency-agents` is an optional development-time source input. The merged skill
+does not vendor its agent bodies or assume a machine-specific source path.
+
+## Verified source snapshot
+
+The local source used for issue 26 verification contains:
+
+- 18 divisions and 258 Markdown agent files with YAML frontmatter.
+- Source revision `3c9588880b7cafaec325a104899fd8bbe27e7d72`.
+- Frontmatter keys observed across the roster: `name`, `description`,
+  `color`, `emoji`, and `vibe`.
+- 14 converter targets: `antigravity`, `gemini-cli`, `opencode`, `cursor`,
+  `aider`, `windsurf`, `openclaw`, `qwen`, `zcode`, `kimi`, `codex`,
+  `osaurus`, `hermes`, and `vibe`.
+
+Counts and revision are evidence from the local checkout, not a promise that
+future upstream revisions are identical. `scaffold.js` records the revision,
+rejects empty divisions and duplicate names/slugs, and requires
+`--allow-source-drift` before refreshing an existing generated catalog.
+
+## Selection and provenance
+
+Pass `--agency-source <path>` or set `AGENCY_AGENTS_SOURCE`. Use repeated
+`--division` or `--agent` options to select roles; use `--all-agents` only when
+the complete metadata catalog is deliberately needed. The generated catalog
+stores metadata and relative source files, not specialist bodies. Load a body
+on demand after a bounded brief has been assigned.
+
+The upstream repository is [msitarzewski/agency-agents](https://github.com/msitarzewski/agency-agents), licensed under MIT by AgentLand Contributors. Harness preserves that provenance; see `NOTICE-agency-agents.md` for the license notice.