harness-everything 0.2.2 → 0.4.0

package/install-cognitive-os/SKILL.md

@@ -1,95 +1,44 @@
 ---
 name: install-cognitive-os
-description: Defines the fundamental physical laws of behavior (Discover > Think > Try > Summarize > Record) for all Agents.
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
+description: "Explain or explicitly apply the Harness cognitive policy: Discover, Think, Try, Summarize, Record. It provides cross-cutting behavior without requiring this skill to be selected before domain skills."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
 ---
 
-# Agent Cognitive OS (Underlying Cognitive System)
+# Agent Cognitive OS
 
-## 📋 Skill Contract
+The Cognitive OS is policy, not a required peer-skill selection. Supported runtimes should establish the smaller Harness invariant contract before domain-skill execution; this skill remains its human-readable/manual entry point.
 
-| Component | Specification |
-| :--- | :--- |
-| **Trigger / Input** | Always — the foundational cognitive loop every other skill in this repository builds on; loaded before any action on any task. |
-| **Expected Output** | Every action passes through Discover → Think → Try → Summarize → Record, where Summarize is a script-gated reality check, not a self-assessment. |
-| **State Mutations** | None of its own — it is the meta-loop other skills' state changes (e.g. `todo-cli.js complete`) run inside. |
-| **Enforcement Gate** | Progress **MUST NOT** be recorded (`[Record]`) except after a verification script exits 0. A failing script (`verify-gate.js` or equivalent) forces a step back to `[Think]`; 3 consecutive failures forces `zoom-out` instead of a 4th blind retry. |
-
-This skill defines the most fundamental physical laws of behavior that all Agents in the Harness Skills system must obey. 
-
-## 🚫 The Anti-Linear Paradigm (拒絕直線思維)
-Software engineering is **NOT a linear 1 -> 2 -> 3 -> Done process**. It is a cyclical process of hypothesis, execution, failure, and correction.
-If you attempt to write code sequentially and assume it works without verification, you are hallucinating.
-Your progression is **STRICTLY GATED** by terminal scripts (like `verify-gate.js` and `todo-cli.js`). If a script fails, you MUST step back, re-evaluate, and fix the issue. You cannot progress until the environment allows you to.
-
-## Core Loop: The State Machine (Discover > Think > Try > Summarize > Record)
-
-```mermaid
-flowchart TD
-    State_Awake[Discover: Where am I?] --> State_Think[Think: Form Hypothesis]
-    State_Think --> State_Try[Try: Execute Code / Run Script]
-    State_Try --> Gate{Summarize: Verify via Gate}
-    
-    Gate -->|Exit 1: Reality Mismatch| State_Think
-    Gate -->|Exit 1: Repeated Failures| ZoomOut[Record: Zoom-Out / Reflect]
-    ZoomOut --> State_Think
-    Gate -->|Exit 0: Reality Match| State_Record[Record: Commit State]
-    State_Record --> State_Think
-```
-
-### 0. `[Discover]`: State Awakening & Deep Environment Discovery
-- **Action**: Before any thinking or execution, you **MUST confirm where you are first**.
-- **Environment Detection**: Detect the OS, and specifically verify the current shell/terminal environment.
-- **Deep Information Exploration**: Do not stop at reading a single file. Trace dependencies, check call sites, and cross-reference with architectural docs.
+## USE FOR:
+- Apply or explain Discover → Think → Try → Summarize → Record.
+- Debug Harness cognitive behavior.
+- Use the policy explicitly on hosts without automatic kernel context.
 
-### 1. `[Think]`: Form Hypothesis
-- Before executing any command or modifying code, confirm your high-level intent.
-- Predict possible failure paths. If a direction is doomed to fail, eliminate it early.
+## DO NOT USE FOR:
+- Skill authoring style (`skill-style`) or Git conventions.
+- Replacing domain expertise such as `tdd`, `security-review`, or `repo-docs`.
 
-### 2. `[Try]`: Execution and Action
-- Write the minimal amount of code to test your hypothesis.
-- Run terminal commands to test the code.
+## Skill Contract
 
-### 3. `[Summarize]`: The Script-Gated Reality Check
-- **CRITICAL**: You CANNOT summarize based on your own assumptions. You MUST run a verification script (e.g., tests, linter, `verify-gate.js`).
-- If the script fails (Exit Code 1), you have been slapped by reality. You MUST step back to `[Think]`, diagnose the failure using the terminal output, and try again.
-- **Deep Reflection**: If a trial fails 3 times, do NOT blindly retry. You MUST trigger a `zoom-out` reflection.
-
-### 4. `[Record]`: Commit State
-- ONLY when the verification script passes (Exit Code 0), you may use the task tracker (e.g., `todo-cli.js complete`) to record your progress and move to the next phase.
-
-## 🧠 Global Output Normalization: Always-On ADHD-Friendly Output Shaping
-Regardless of which tier is active, where you start, or which skill is currently executing, your response MUST strictly comply with the following communication standardization and formatting laws to eliminate cognitive overhead and LLM conversational bloat.
-
-### 1. Lead with the Action or Answer (開門見山)
-- **Direct Opener**: The first line of your response MUST contain the direct answer, the executed command, the code snippet, or the next concrete action.
-- **NO Preamble**: Absolutely forbidden openers include: "Sure!", "Great question!", "Let me help you...", "Let's look at this...", "Here is...", "I'll...", or any generic welcoming text. Start immediately with the substance.
-
-### 2. Complete the Task Autonomously (Don't Delegate Back / Agent 獨立自主)
-- **Do the Work**: If the task can be safely researched, written, edited, compiled, tested, or verified by you (using your available tools), you MUST complete it yourself.
-- **NO Command Lists for the User**: Do not present a list of commands for the user to run unless you are genuinely blocked by missing permissions, credentials, physical hardware interaction, or critical choices.
-
-### 3. Numbered & Bounded Multi-Step Work (步驟有邊界)
-- **Single-Action Steps**: For multi-step procedures, use numbered lists where each item is a single, bounded, actionable task. Avoid "and then" or compound steps.
-- **Cap at 5 Items**: Never exceed 5 items in a single list. If there are more, split them into "Do Now" vs "Later", or "Must-Haves" vs "Nice-to-Haves".
+| Component | Specification |
+| :--- | :--- |
+| **Input** | Explicit cognitive-loop use, or a host without automatic Harness kernel context. |
+| **Output** | Evidence-grounded work without a fixed domain-skill sequence. |
+| **State** | None directly. |
+| **Gate** | Completion claims need evidence; repeated same-signature failures require re-planning. |
 
-### 4. Continuous Progress Tracking (Turn-by-Turn State / 進度可見)
-- **Restate State**: For multi-stage tasks, explicitly restate the current state at the start or end of each turn in a single concise line (e.g., "Step 3 of 5 completed: [Action]. Next: [Action].").
-- **Concrete Next Step**: Every response that leaves tasks open MUST end with exactly ONE concrete action the user can do in under two minutes (or that you will perform next).
+## Core Loop
 
-### 5. Matter-of-Fact Error Diagnostics (除錯具體且客觀)
-- **Neutral Tone**: When errors, test failures, or bugs occur, state the failure line, the observed output, the diagnosed cause, and the fix in a completely matter-of-fact tone.
-- **NO Fluff**: Never use emotive phrases like "Uh oh," "Oh no," "Seems to be a problem," or undocumented speculation.
-- **Direct Cause Only**: If the user provides an error/cause, address that specific cause immediately. Do not extend into unverified hypotheses or generic diagnostics checklist unless requested.
+1. `[Discover]` Verify relevant workspace state.
+2. `[Think]` Establish intent, scope, and failure modes.
+3. `[Try]` Make the smallest useful change and gather evidence.
+4. `[Summarize]` Ground conclusions in tool output; after 3 same-signature failures use `zoom-out`.
+5. `[Record]` Record milestones only when evidence supports them.
 
-### 6. Zero Conversational Bloat (移除無資訊文字)
-- **NO Recaps**: Do not write paragraphs summarizing what you just did (e.g., "I have successfully modified X and Y to ensure..."). The code and git diff are the evidence.
-- **NO Closing Pleasantries**: Completely remove all polite sign-offs, such as "Hope this helps!", "Let me know if you need anything else," or "Happy coding!" End exactly when the final step or answer is displayed.
+Domain skills may define their own tactics and phases. They do not need to invoke this skill first as long as the Harness invariants remain satisfied.
 
-### 7. Language and Terminology Consistency (自然在地化繁中)
-- **User Language Alignment**: While this skill contract and files are in English, the final response MUST be in the language of the user's input (defaulting to Taiwanese Traditional Chinese (`zh-TW`) for Taiwanese requests).
-- **Natural Phrasing**: For Traditional Chinese, use natural Taiwanese engineering terminology. Avoid Chinese tech buzzwords or literal translationese.
-  - Use `程式碼` (not `代碼`), `資料/資料庫` (not `數據/數據庫`), `預設` (not `默認`), `資訊` (not `信息`), `相容` (not `兼容`), `最佳化` (not `優化`).
-  - Do not translate standard tech literals: keep code blocks, inline code, commands, paths, URLs, API/class/function names, and common industry terms (like `commit`, `PR`, `deploy`, `runtime`) exactly in their original English form.
+On advisory-only platforms, these rules are guidance rather than hard tool-call gates.
 
+Deep dive: <this-skill-dir>/references/cognitive-loop.md

package/install-cognitive-os/references/cognitive-loop.md

@@ -0,0 +1,27 @@
+# Agent Cognitive OS — Full Reference
+
+## The cyclical development paradigm
+
+Software development is iterative: hypothesis, execution, feedback, and
+refinement. Ground conclusions in objective verification (`npm test`,
+`pytest`, `harness-everything/scripts/verify-gate.js`, or the project gate) and
+an active native TODO tracker or Markdown checklist. When a check fails, return
+to Think, inspect the evidence, and update the hypothesis.
+
+## Core loop
+
+```mermaid
+flowchart TD
+  Discover[Discover workspace and environment] --> Think[Think and form hypothesis]
+  Think --> Try[Try a bounded change]
+  Try --> Summarize[Summarize with objective checks]
+  Summarize -->|pass| Record[Record milestone state]
+  Summarize -->|fail| Think
+  Record --> Think
+```
+
+## Platform note
+
+See the repository README for the distinction between Claude Code's hard
+hook enforcement and advisory-only platforms. Native TODO tools are preferred;
+`tasks/todo.md` is the portable fallback.

package/multi-agent-workspace/NOTICE-agency-agents.md

@@ -0,0 +1,27 @@
+Agency Agents provenance
+
+The optional catalog integration reads metadata from the upstream
+`msitarzewski/agency-agents` repository at scaffold time. Harness does not
+include the upstream agent bodies in this repository.
+
+The upstream source is distributed under the MIT License:
+
+Copyright (c) 2025 AgentLand Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/multi-agent-workspace/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: multi-agent-workspace
+description: "Scaffold a verified multi-agent workspace and select bounded specialists from an external agency-agents catalog without vendoring the full roster."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
+---
+
+# Multi-Agent Workspace
+
+## USE FOR:
+- A structured plan selecting `fable-multi-agent-workspace` for durable multi-session work with reusable specialists or indexed memory.
+- Scaffolding bounded specialist roles, launcher, memory index, and handoff metadata.
+
+## DO NOT USE FOR:
+- Single-agent/TDD/Fable-only work.
+- Choosing topology from file or line counts; the Harness router owns that decision.
+- Vendoring an entire external agent roster.
+
+## Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **State Mutations** | Writes derived metadata, roles, state, logs, launcher, router, handoff, and memory index under the global workspace-keyed Harness state home; writes decision, domain, and architecture records at resolver-selected committable repository paths. |
+
+## Workflow
+
+1. Require `strategy=fable-multi-agent-workspace` and `workspace.required=true`.
+2. Run `node <this-skill-dir>/scripts/scaffold.js --workspace <root>` with explicit selections.
+3. Run `node <this-skill-dir>/scripts/consume-workflow-plan.js --plan-file <router-contract.json> --root <root> --run-id <runId>`.
+4. Verify selected roles, provenance, memory index, and `<workspace>/.ai/handoff.json`; return the handoff to Fable for execution.
+
+The consumer adds plan/run correlation only. It does not spawn workers, choose models, replace role provenance, or add a new memory-write path. Missing source uses the existing unavailable-catalog fallback.
+
+Deep dive: <this-skill-dir>/references/orchestration.md
+Deep dive: <this-skill-dir>/references/architecture-guide.md
+Deep dive: <skills-repo-root>/docs/workflows/multi-agent-workspace.md

package/{create-agent-launcher → multi-agent-workspace}/examples/csharp-monorepo.md

@@ -1,123 +1,123 @@
----
-description: "Output example for create-agent-launcher applied to a fictional C# super-monorepo project (Contoso Workbench). Shows the Context Profile from project discovery and the expected generated agent content."
----
-
-# Example: C# Super-Monorepo (Contoso Workbench)
-
-This example shows what the Project Discovery step should extract from the project, and what the generated agent files should contain. **Contoso Workbench 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` (or `.github/copilot-instructions.md`), and `.gitmodules`, the LLM should record this Context Profile:
-
-```
-Project Name:       Contoso Workbench
-Primary Language:   C# (.NET Framework 4.7.2)
-Full Build Command: dotnet build Workbench.App/Workbench.App/WorkbenchApp.csproj  (or via ./compile)
-Local Build Command:dotnet build <specific.csproj> inside the affected submodule
-Key Source Paths:   Workbench.App/Workbench.App/ (main desktop app), Workbench.Common/ (shared utils),
-                    Workbench.VcsBridge/ (VCS integration), Workbench.Reporting/ (report engine)
-AI Plan Path:       docs/ai_plans/ at the MAIN REPO ROOT (not inside submodules)
-Monorepo Type:      git submodules (level-1 only)
-Workspace File:     Workbench.sln
-Special Constraints:Source code MUST live in submodules — never commit source to the main repo.
-                    Each submodule must be level-1.
-```
-
-**Key signals discovered from README.md:**
-- "In the super project, only solution file (.sln), cmake list and other collective control files are placed, and **no source code is allowed**."
-- "All reference projects in the super project must be located under the git submodule."
-- List of submodule directories: `Workbench.App/`, `Workbench.Common/`, `Workbench.VcsBridge/`, `Workbench.Reporting/`, etc.
-
----
-
-## 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 submodule(s): `Workbench.App/Workbench.App/` (main app
-   project), `Workbench.Common/` (shared utilities), `Workbench.VcsBridge/` (VCS
-   integration), and others as applicable. All source code lives in level-1 git
-   submodules — never in the main repo.
-2. **Handle Ambiguities**: Note critical ambiguities for the user; otherwise proceed.
-3. **Document**: Save a detailed implementation document at the **main repo root** as
-   `docs/ai_plans/implement_<feature-name>.md`
-   (e.g., `docs/ai_plans/implement_vcs_tag_merge_support.md`). Include:
-   - Implementation Goals
-   - Approach / Methodology
-   - Detailed Implementation Steps
-   - Implementation Details (classes, APIs, files, submodule paths)
-   - Architecture Diagrams (if applicable)
-```
-
-**`backend-developer.agent.md` — full file:**
-```markdown
----
-name: "Backend Developer"
-description: "Use when: you need to implement C# source code based on a requirement list or AI plan. This agent implements features and verifies them using 'dotnet build'."
-tools: [read, edit, search, execute]
----
-
-You are an expert C# Backend Developer working in the **Contoso Workbench** solution.
-Your primary responsibility is to implement C# 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 C# codebase
-   in the relevant submodule(s): `Workbench.App/Workbench.App/`, `Workbench.Common/`,
-   `Workbench.VcsBridge/`.
-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 C# source code inside the
-   appropriate submodule. Do NOT add source files to the main repo.
-4. **Verify via Compilation — choose minimum scope**:
-   - **Step 1 — Assess scope**: Did you only change private/internal code within a single `.csproj`
-     (method bodies, private fields, internal classes)? → **Local build**.
-     Did you change a public/protected API, an interface, an enum, or a `.csproj` dependency? → **Cross-project build**.
-   - **Local build** (single project, fastest): `dotnet build <changed-project>.csproj`
-     inside the affected submodule (e.g., `dotnet build Workbench.VcsBridge/VcsBridge/VcsBridge.csproj`).
-   - **Cross-project build** (when public API changes may break dependents):
-     `dotnet build Workbench.App/Workbench.App/WorkbenchApp.csproj`
-   - Prefer local build first. Escalate to cross-project only when the assessment above requires it.
-
-## Constraints
-
-- DO NOT modify the requirements. Your job is strictly implementation.
-- ALWAYS ensure the code compiles successfully before considering your task complete.
-- Fix all compiler errors before finishing.
-- All source code changes MUST be made inside the relevant submodule — never in the main repo.
-```
-
-**`agent-launcher/SKILL.md` — Project-Specific Notes section:**
-```markdown
-## Project-Specific Notes
-
-- **Build verification**: `dotnet build Workbench.App/Workbench.App/WorkbenchApp.csproj`
-  (or scope to specific `.csproj` for isolated changes)
-- **AI plan documents**: Save at `docs/ai_plans/implement_<name>.md` at the **main repo root**
-  (repo-root-relative — never an absolute disk path, and never inside a submodule)
-- **Primary language**: C# (.NET Framework 4.7.2)
-- **Monorepo notes**: Super monorepo — all source code lives in level-1 git submodules
-  (`Workbench.App/`, `Workbench.Common/`, `Workbench.VcsBridge/`, etc.). Never commit
-  source to the main repo.
-```
-
----
-
-## Key Specificity Points
-
-| Element | Expected in Generated Agent |
-|---------|-----------------------------|
-| Source paths | `Workbench.App/Workbench.App/`, `Workbench.Common/`, `Workbench.VcsBridge/` (with role annotations) |
-| AI plan location | `docs/ai_plans/` **at the main repo root** — explicitly, not inside submodules |
-| Path style | Always repo-root-relative — generated agents must never contain absolute disk paths |
-| Architecture constraint | "Never add source files to the main repo" |
-| Build scope decision | Assess scope first; prefer `dotnet build <X.csproj>` before escalating to solution-wide |
-| Project identity | "the **Contoso Workbench** solution" |
+---
+description: "Output example for multi-agent-workspace applied to a fictional C# super-monorepo project (Contoso Workbench). Shows the Context Profile from project discovery and the expected generated agent content."
+---
+
+# Example: C# Super-Monorepo (Contoso Workbench)
+
+This example shows what the Project Discovery step should extract from the project, and what the generated agent files should contain. **Contoso Workbench 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` (or `.github/copilot-instructions.md`), and `.gitmodules`, the LLM should record this Context Profile:
+
+```
+Project Name:       Contoso Workbench
+Primary Language:   C# (.NET Framework 4.7.2)
+Full Build Command: dotnet build Workbench.App/Workbench.App/WorkbenchApp.csproj  (or via ./compile)
+Local Build Command:dotnet build <specific.csproj> inside the affected submodule
+Key Source Paths:   Workbench.App/Workbench.App/ (main desktop app), Workbench.Common/ (shared utils),
+                    Workbench.VcsBridge/ (VCS integration), Workbench.Reporting/ (report engine)
+AI Plan Path:       docs/ai_plans/ at the MAIN REPO ROOT (not inside submodules)
+Monorepo Type:      git submodules (level-1 only)
+Workspace File:     Workbench.sln
+Special Constraints:Source code MUST live in submodules — never commit source to the main repo.
+                    Each submodule must be level-1.
+```
+
+**Key signals discovered from README.md:**
+- "In the super project, only solution file (.sln), cmake list and other collective control files are placed, and **no source code is allowed**."
+- "All reference projects in the super project must be located under the git submodule."
+- List of submodule directories: `Workbench.App/`, `Workbench.Common/`, `Workbench.VcsBridge/`, `Workbench.Reporting/`, etc.
+
+---
+
+## 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 submodule(s): `Workbench.App/Workbench.App/` (main app
+   project), `Workbench.Common/` (shared utilities), `Workbench.VcsBridge/` (VCS
+   integration), and others as applicable. All source code lives in level-1 git
+   submodules — never in the main repo.
+2. **Handle Ambiguities**: Note critical ambiguities for the user; otherwise proceed.
+3. **Document**: Save a detailed implementation document at the **main repo root** as
+   `docs/ai_plans/implement_<feature-name>.md`
+   (e.g., `docs/ai_plans/implement_vcs_tag_merge_support.md`). Include:
+   - Implementation Goals
+   - Approach / Methodology
+   - Detailed Implementation Steps
+   - Implementation Details (classes, APIs, files, submodule paths)
+   - Architecture Diagrams (if applicable)
+```
+
+**`backend-developer.agent.md` — full file:**
+```markdown
+---
+name: "Backend Developer"
+description: "Use when: you need to implement C# source code based on a requirement list or AI plan. This agent implements features and verifies them using 'dotnet build'."
+tools: [read, edit, search, execute]
+---
+
+You are an expert C# Backend Developer working in the **Contoso Workbench** solution.
+Your primary responsibility is to implement C# 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 C# codebase
+   in the relevant submodule(s): `Workbench.App/Workbench.App/`, `Workbench.Common/`,
+   `Workbench.VcsBridge/`.
+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 C# source code inside the
+   appropriate submodule. Do NOT add source files to the main repo.
+4. **Verify via Compilation — choose minimum scope**:
+   - **Step 1 — Assess scope**: Did you only change private/internal code within a single `.csproj`
+     (method bodies, private fields, internal classes)? → **Local build**.
+     Did you change a public/protected API, an interface, an enum, or a `.csproj` dependency? → **Cross-project build**.
+   - **Local build** (single project, fastest): `dotnet build <changed-project>.csproj`
+     inside the affected submodule (e.g., `dotnet build Workbench.VcsBridge/VcsBridge/VcsBridge.csproj`).
+   - **Cross-project build** (when public API changes may break dependents):
+     `dotnet build Workbench.App/Workbench.App/WorkbenchApp.csproj`
+   - Prefer local build first. Escalate to cross-project only when the assessment above requires it.
+
+## Constraints
+
+- DO NOT modify the requirements. Your job is strictly implementation.
+- ALWAYS ensure the code compiles successfully before considering your task complete.
+- Fix all compiler errors before finishing.
+- All source code changes MUST be made inside the relevant submodule — never in the main repo.
+```
+
+**`agent-launcher/SKILL.md` — Project-Specific Notes section:**
+```markdown
+## Project-Specific Notes
+
+- **Build verification**: `dotnet build Workbench.App/Workbench.App/WorkbenchApp.csproj`
+  (or scope to specific `.csproj` for isolated changes)
+- **AI plan documents**: Save at `docs/ai_plans/implement_<name>.md` at the **main repo root**
+  (repo-root-relative — never an absolute disk path, and never inside a submodule)
+- **Primary language**: C# (.NET Framework 4.7.2)
+- **Monorepo notes**: Super monorepo — all source code lives in level-1 git submodules
+  (`Workbench.App/`, `Workbench.Common/`, `Workbench.VcsBridge/`, etc.). Never commit
+  source to the main repo.
+```
+
+---
+
+## Key Specificity Points
+
+| Element | Expected in Generated Agent |
+|---------|-----------------------------|
+| Source paths | `Workbench.App/Workbench.App/`, `Workbench.Common/`, `Workbench.VcsBridge/` (with role annotations) |
+| AI plan location | `docs/ai_plans/` **at the main repo root** — explicitly, not inside submodules |
+| Path style | Always repo-root-relative — generated agents must never contain absolute disk paths |
+| Architecture constraint | "Never add source files to the main repo" |
+| Build scope decision | Assess scope first; prefer `dotnet build <X.csproj>` before escalating to solution-wide |
+| Project identity | "the **Contoso Workbench** solution" |