harness-everything 0.2.2 → 0.3.6

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,37 @@
+---
+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.3.6
+---
+
+# Multi-Agent Workspace
+
+## USE FOR:
+- Scaffolding six-zone multi-agent workspaces with a launcher, memory index, and handoff manifest.
+- Selecting and delegating bounded specialists from an agency-agents source catalog.
+
+## DO NOT USE FOR:
+- A single-agent task, ordinary TDD, or Fable-only orchestration.
+- Preloading or vendoring an entire external agent body roster.
+
+## Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Tier 3 workspace scaffold or specialist-selection request; optional `--agency-source`. |
+| **Expected Output** | Six zones, immutable router, selected-agent catalog, launcher, local indexer, and structured handoff. |
+| **State Mutations** | Writes only `.harness/multi-agent/` in the target workspace; never edits the external source. |
+| **Enforcement Gate** | Run `scripts/scaffold.js`; it validates source metadata, conflicts, revision drift, and generated artifacts. |
+
+## Workflow
+
+1. Discover the target stack, source availability, requested platform, divisions, and agents.
+2. Run `node multi-agent-workspace/scripts/scaffold.js --workspace <root>` with explicit selections.
+3. Read the generated router and handoff before delegating. Pass each specialist only its declared scope.
+4. Run the generated `index_memory.js`; verify `manifest.json`, `memory-index.md`, and all six zones.
+5. Record the handoff and continue through `fable-mode` verification gates.
+
+The source is optional: missing source produces an explicit unavailable-catalog fallback, never a fake complete roster. `--allow-source-drift` is required to refresh an existing catalog at a different source revision. See `references/orchestration.md` and `references/agency-agents.md` for migration and source rules.

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" |

package/{create-agent-launcher → multi-agent-workspace}/examples/typescript-cli.md

@@ -1,126 +1,126 @@
----
-description: "Output example for create-agent-launcher 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) |
+---
+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) |