harness-everything 0.2.2 → 0.4.0

package/plugins/harness-everything/skills/improve-codebase-architecture/guides/HTML-REPORT.md

@@ -0,0 +1,123 @@
+# HTML Report Format
+
+The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two — don't lean on Mermaid for everything, it'll start to look generic.
+
+## Scaffold
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Architecture review — {{repo name}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+    <style>
+      /* small custom layer for things Tailwind doesn't cover cleanly:
+         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
+      .seam { stroke-dasharray: 4 4; }
+      .leak { stroke: #dc2626; }
+      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
+    </style>
+  </head>
+  <body class="bg-stone-50 text-slate-900 font-sans">
+    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
+      <header>...</header>
+      <section id="candidates" class="space-y-10">...</section>
+      <section id="top-recommendation">...</section>
+    </main>
+  </body>
+</html>
+```
+
+## Header
+
+Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph — straight into the candidates.
+
+## Candidate card
+
+The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms ([LANGUAGE.md](LANGUAGE.md)) without ceremony.
+
+Each candidate is one `<article>`:
+
+- **Title** — short, names the deepening (e.g. "Collapse the Order intake pipeline").
+- **Badge row** — recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
+- **Files** — monospaced list, `font-mono text-sm`.
+- **Before / After diagram** — the centrepiece. Two columns, side by side. See patterns below.
+- **Problem** — one sentence. What hurts.
+- **Solution** — one sentence. What changes.
+- **Wins** — bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
+- **ADR callout** (if applicable) — one line in an amber-tinted box.
+
+No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
+
+## Diagram patterns
+
+Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same — variety is part of the point.
+
+### Mermaid graph (the workhorse for dependencies / call flow)
+
+Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
+
+```html
+<div class="rounded-lg border border-slate-200 bg-white p-4">
+  <pre class="mermaid">
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+  </pre>
+</div>
+```
+
+### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
+
+Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals — Mermaid won't render that with the right weight.
+
+### Cross-section (good for layered shallowness)
+
+Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
+
+### Mass diagram (good for "interface as wide as implementation")
+
+Two rectangles per module — one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
+
+### Call-graph collapse
+
+Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
+
+## Style guidance
+
+- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
+- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
+- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
+- Use `text-xs uppercase tracking-wider` for module labels inside diagrams — they should read as schematic, not as UI.
+- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static — no app code, no interactivity beyond Mermaid's own rendering.
+
+## Top recommendation section
+
+One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
+
+## Tone
+
+Plain English, concise — but the architectural nouns and verbs come straight from [LANGUAGE.md](LANGUAGE.md). Concision is not an excuse to drift.
+
+**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
+
+**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
+
+**Phrasings that fit the style:**
+
+- "Order intake module is shallow — interface nearly matches the implementation."
+- "Pricing leaks across the seam."
+- "Deepen: one interface, one place to test."
+- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
+
+**Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"* — those terms aren't in the glossary and don't earn their place.
+
+No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in [LANGUAGE.md](LANGUAGE.md), reach for one that is before inventing a new one.

package/plugins/harness-everything/skills/improve-codebase-architecture/guides/INTERFACE-DESIGN.md

@@ -0,0 +1,44 @@
+# Interface Design
+
+When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
+
+Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
+
+## Process
+
+### 1. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md))
+- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
+
+Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
+
+### 2. Spawn sub-agents
+
+Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
+
+- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
+- Agent 2: "Maximise flexibility — support many use cases and extension."
+- Agent 3: "Optimise for the most common caller — make the default case trivial."
+- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
+
+Include both [LANGUAGE.md](LANGUAGE.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
+
+Each sub-agent outputs:
+
+1. Interface (types, methods, params — plus invariants, ordering, error modes)
+2. Usage example showing how callers use it
+3. What the implementation hides behind the seam
+4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md))
+5. Trade-offs — where leverage is high, where it's thin
+
+### 3. Present and compare
+
+Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**.
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.

package/plugins/harness-everything/skills/improve-codebase-architecture/guides/LANGUAGE.md

@@ -0,0 +1,53 @@
+# Language
+
+Shared vocabulary for every suggestion this skill makes. Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
+
+## Terms
+
+**Module**
+Anything with an interface and an implementation. Deliberately scale-agnostic — applies equally to a function, class, package, or tier-spanning slice.
+_Avoid_: unit, component, service.
+
+**Interface**
+Everything a caller must know to use the module correctly. Includes the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics.
+_Avoid_: API, signature (too narrow — those refer only to the type-level surface).
+
+**Implementation**
+What's inside a module — its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
+
+**Depth**
+Leverage at the interface — the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface. A module is **shallow** when the interface is nearly as complex as the implementation.
+
+**Seam** _(from Michael Feathers)_
+A place where you can alter behaviour without editing in that place. The *location* at which a module's interface lives. Choosing where to put the seam is its own design decision, distinct from what goes behind it.
+_Avoid_: boundary (overloaded with DDD's bounded context).
+
+**Adapter**
+A concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
+
+**Leverage**
+What callers get from depth. More capability per unit of interface they have to learn. One implementation pays back across N call sites and M tests.
+
+**Locality**
+What maintainers get from depth. Change, bugs, knowledge, and verification concentrate at one place rather than spreading across callers. Fix once, fixed everywhere.
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, the module wasn't hiding anything (it was a pass-through). If complexity reappears across N callers, the module was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
+
+## Relationships
+
+- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
+- **Depth** is a property of a **Module**, measured against its **Interface**.
+- A **Seam** is where a **Module**'s **Interface** lives.
+- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
+- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
+
+## Rejected framings
+
+- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
+- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
+- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.

package/plugins/harness-everything/skills/improve-codebase-architecture/guides/refactoring-workflow.md

@@ -0,0 +1,59 @@
+# Improve Codebase Architecture — Full Workflow
+
+## Process & Refactoring Flow
+
+Follow the decision matrix below when refactoring codebase architecture or splitting objects:
+
+```mermaid
+flowchart TD
+    Start[Trigger: Architecture Refactoring / SRP Object Splitting] --> Scan[1. Scan CONTEXT.md, ADRs & Module Interfaces]
+    Scan --> Analyze{2. Identify Architectural Anti-Patterns}
+
+    Analyze -- Oversized Object / Monolith --> SRPPlan[Plan SRP Extraction: Split Class / Extract Function]
+    Analyze -- Shallow Module / Tight Coupling --> DeepenPlan[Plan Interface Deepening & Seam Extraction]
+
+    SRPPlan --> Report[3. Present Refactoring & Extraction Proposal]
+    DeepenPlan --> Report
+
+    Report --> Approved{User Approves Proposal?}
+
+    Approved -- No --> Adjust[Adjust Proposal & Scope] --> Report
+    Approved -- Yes --> CheckTest{4. Existing Test Safety Net Present?}
+
+    CheckTest -- No Tests --> WriteCharTest[Write Characterization Tests First] --> Execute
+    CheckTest -- Tests Pass --> Execute[5. Execute Refactoring via TDD]
+
+    Execute --> ErrorsCheck{6. Cascading Errors > 3?}
+
+    ErrorsCheck -- Yes --> Rollback[Rollback Changes & Trigger zoom-out]
+    ErrorsCheck -- No --> Complete[Refactoring Complete & Record Lessons in self-evolve]
+```
+
+## 1. Architectural Exploration & Discovery `[Discover]`
+- **Blind Refactoring Prohibited**: Before proposing any modification suggestions, you MUST first scan `CONTEXT.md`, `docs/adr/`, and core interface definitions (Interfaces/Types).
+- **Identify Refactoring Targets**:
+  - **Single Responsibility Principle (SRP) Violations**: Oversized objects, classes, or functions (>300 lines or >10 cyclomatic complexity) handling multiple uncoupled concerns.
+  - **Shallow Modules**: Complex, wide interfaces with minimal internal implementation.
+  - **Improperly Coupled Seams**: Modules directly referencing implementation details instead of clean abstraction interfaces.
+
+## 2. Analysis & Proposal `[Think]`
+Use consistent domain terminology (Module, Interface, Implementation, Depth, Seam, SRP, Extraction) to communicate with the human.
+- Submit a "Deepening & SRP Refactoring" proposal to the user detailing:
+  1. **Object Splitting Strategy**: Which responsibilities will be extracted into focused helper objects or separate modules.
+  2. **Interface Abstraction**: Which boundaries (Seams) will be extracted into clean interfaces or adapters.
+
+## 3. Implementation Refactoring `[Try]`
+- After gaining human approval, launch `tdd` mode.
+- **Iron Rule of Refactoring**: MUST be done under the safety net of test coverage. If there are no tests, the first step MUST be to "write Characterization Tests for the legacy code" before modifying the architecture.
+- **Extract Safely**: Extract objects/functions incrementally, verifying test suite execution after each atomic change.
+
+## 4. Circuit Breaker & Evolution `[Summarize]` & `[Self-Evolve]`
+- If refactoring triggers more than 3 cascading compilation errors that cannot be fixed immediately, trigger the `zoom-out` circuit breaker and Rollback.
+- Write the discovered coupling traps into `self-evolve` memory, ensuring future newly generated code does not repeat the same mistakes.
+
+## Reference Guides
+For precise architectural paradigms and deep module analysis, refer to:
+- `improve-codebase-architecture/guides/DEEPENING.md` — Deepening opportunities & modular depth rules
+- `improve-codebase-architecture/guides/INTERFACE-DESIGN.md` — Principles of interface design and seams
+- `improve-codebase-architecture/guides/LANGUAGE.md` — Language-specific refactoring and pattern guidelines
+- `improve-codebase-architecture/guides/HTML-REPORT.md` — Creating visual reports with Mermaid diagrams

package/plugins/harness-everything/skills/improve-codebase-architecture/references/README.md

@@ -0,0 +1,16 @@
+# Architecture References
+
+Load the guide that matches the current refactoring decision. The index keeps
+the short `SKILL.md` entry point stable while the detailed material stays
+lazy-loaded.
+
+- [Refactoring workflow](../guides/refactoring-workflow.md): Discover, Think,
+  Try, and recover from cascading failures.
+- [Deepening](../guides/DEEPENING.md): find seams and choose the right depth
+  for each dependency.
+- [Interface design](../guides/INTERFACE-DESIGN.md): shape ports, adapters,
+  and testable boundaries.
+- [Language](../guides/LANGUAGE.md): use precise refactoring vocabulary and
+  describe rejected designs.
+- [HTML reports](../guides/HTML-REPORT.md): present dependency and call-flow
+  findings with diagrams.

package/plugins/harness-everything/skills/install-cognitive-os/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: install-cognitive-os
+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
+
+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.
+
+## USE FOR:
+- Apply or explain Discover → Think → Try → Summarize → Record.
+- Debug Harness cognitive behavior.
+- Use the policy explicitly on hosts without automatic kernel context.
+
+## DO NOT USE FOR:
+- Skill authoring style (`skill-style`) or Git conventions.
+- Replacing domain expertise such as `tdd`, `security-review`, or `repo-docs`.
+
+## Skill Contract
+
+| 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. |
+
+## Core Loop
+
+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.
+
+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.
+
+On advisory-only platforms, these rules are guidance rather than hard tool-call gates.
+
+Deep dive: <this-skill-dir>/references/cognitive-loop.md

package/plugins/harness-everything/skills/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/plugins/harness-everything/skills/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/plugins/harness-everything/skills/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/plugins/harness-everything/skills/multi-agent-workspace/examples/csharp-monorepo.md

@@ -0,0 +1,123 @@
+---
+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" |