# Harness agents (bundled)

Shared EasySpecs **agent prompt definitions** for all harness kinds (OpenCode, Claude Code, and future CLI adapters). On **Materialize agents**, adapters copy this folder into the active harness worktree layout:

- **OpenCode:** **`<analysisCheckout>/.opencode/agents/`** (+ schemas under **`.easyspecs/schemas/`**)
- **Claude Code:** **`<analysisCheckout>/.claude/agents/`** (+ schemas under **`.easyspecs/schemas/`**)

**`analysisCheckout`** is the temp path from EasySpecs **workspace storage** (`adHocWorktreePath`, e.g. `…/easyspecs-analysis/<id>`).

- **`resources/schemas/`** is copied into **`.easyspecs/schemas/`** (`context-lists/` and `ace/`) for **`{{LIST_SCHEMA_REF}}`** and ACE validation (SRS-154).
- Materialized harness trees (**.opencode/**, **`.claude/`**, etc.) are **EasySpecs tooling**, not the analyzed product codebase. Every bundled **`agent-*.md`** instructs the model to **ignore** those directories for repo discovery and to **never** cite paths under them in **`sourceReferences`**, Evidence index bullets, or equivalent evidence fields.

## Harness CLI notes

Each **`agent-*.md`** describes **one logical agent role** from SRS-8 §4–§6 (`.easyspecs/docs/srs/srs-8.md` in this repo). They are **human-readable specs** for wiring the active **coding agent** harness. EasySpecs passes **`--agent`** with the file stem (filename without `.md`) and attaches the filled §3.5 prompt via **`-f`** (OpenCode-shaped argv; Claude Code and other adapters translate paths). The **`AGENT_ID`** table inside a file (often `ctx-*`) is the SRS logical id, not necessarily the CLI **`--agent`** stem.

### OpenCode kind

Per [OpenCode agents](https://opencode.ai/docs/agents), the CLI agent id is the **filename without `.md`** (e.g. `agent-md-docs-project.md` → **`opencode run --agent agent-md-docs-project`**).

### Mermaid diagrams

Agents that produce **` ```mermaid `** blocks must follow **[MERMAID.md](./MERMAID.md)**: target **Mermaid 11.13**, **neutral** theme (first line inside each fence: `%%{init: {'theme':'neutral'}}%%`), **11.x**-compatible syntax, **no** per-element styling (`style`, `classDef`, `linkStyle`, etc.), and **no** built-in **`C4*`** diagram types (including **`C4Component`**—use **`flowchart`** / **`graph`** / **`sequenceDiagram`** instead).

**List agents** (`agent-list-*.md`) include YAML **frontmatter** (`description`, **`mode: primary`**) so the OpenCode harness registers them like a full session agent and non-interactive runs are more likely to use **file write** tools instead of chat-only replies.

- **List agents** embed the **JSON Schema (Draft 2020-12)** the model must satisfy (kept in sync with the bundled `.schema.json` files). Every **leaf** row in coordination list JSON includes **`sourceReferences`**: a non-empty array (`minItems: 1`) of `{ "path", "startLine", "endLine", "note"? }` — **`path`** must be a **single repo-relative file** (forward slashes, no trailing slash); **never a directory**. Spread evidence across several files as **several** array entries, not one folder path (1-based inclusive line range per entry). **Exception:** **`repo-surface-scan.json`** does not use per-row **`sourceReferences`**; it uses **`uiSourceReferences`** / **`backendSourceReferences`** (or absence reasons) per **`hasUi`** / **`hasBackend`**. Do **not** use any path whose **basename** is `readme.md` in any casing (`README.md`, etc.) inside evidence arrays. Do **not** use paths under **`.opencode/`** there either.
- **Markdown agents** include an **output template** (headings + **`## Revision`** + **Evidence index**) aligned with **R21**. **`## Revision`** is **append-only**: each pass that changes the body adds at least one bullet describing the delta; it sits **immediately before** **`## Evidence index`**. When the parent coordination JSON row includes **`sourceReferences`**, carry those file+line anchors into the **Evidence index** and extend them with deeper reading as needed (same file-not-folder rule in list JSON).
- **List agents** (JSON): optional root **`revisionLog`** (array of `{ "summary", "at"? }`) in each coordination schema—**append** an entry on every substantive file write; **never delete** prior entries. See **`## Revision`** in each **`agent-list-*.md`** / **`agent-repo-surface-scan.md`**.

### Markdown agents — Evidence index (references) and non-empty chapters

- **`## Evidence index`** is the **references / code-grounding** chapter. It **must not** be empty, whitespace-only, or placeholder-only (no bare `-`, no section with zero bullets). A generated `.md` with **no** substantive grounding bullets there is **invalid** and is **rejected** by policy—the model must not deliver that outcome.
- **Preferred:** at least one concrete `path:line` or `path:start-end` cite from real implementation paths in the worktree.
- **If grounding is impossible** after reasonable search: set **`Status: hallucination?`** on its **own line immediately under the document’s top-level `#` title**, **and** still add **at least one** Evidence index bullet describing search effort, partial findings, and that narrative is not implementation-backed. The Evidence index must never be omitted or left without substantive bullets.
- **Other headings** in the template must not be left empty; if unknown, add a short note under that heading explaining why (Evidence index is **not** exempt—you cannot substitute an empty section with “see above”).
- **Banned:** never cite a file whose **basename** is `readme.md` in **any** casing (`README.md`, `readme.md`, etc.) in the Evidence index (or as a list-agent `sourceReferences` path). Use source, config, tests, schemas, etc. **Also banned:** any path under **`.opencode/`** (tooling copy, not product source).

## Coordination list (JSON) agents

| File | Output (under `.easyspecs/context/`) |
| ---- | ------------------------------------ |
| [agent-list-features.md](./agent-list-features.md) | `features-list.json` |
| [agent-repo-surface-scan.md](./agent-repo-surface-scan.md) | `repo-surface-scan.json` (SRS-20 pre-flight) |
| [agent-list-experiences.md](./agent-list-experiences.md) | `experiences-list.json` |
| [agent-list-services.md](./agent-list-services.md) | `services-list.json` |
| [agent-list-data-model.md](./agent-list-data-model.md) | `data-model-list.json` (entities only; no nested FD/RL) |
| [agent-list-entity-fields.md](./agent-list-entity-fields.md) | `DM-<nn>-fields-list.json` (per entity) |
| [agent-list-tech-stack.md](./agent-list-tech-stack.md) | `tech-stack-list.json` |
| [agent-list-use-cases.md](./agent-list-use-cases.md) | `FE-<nn>-use-cases-list.json` (per feature) |
| [agent-list-scenarios.md](./agent-list-scenarios.md) | `FE-<nn>_UC-<uu>-scenarios-list.json` (per use case) |

## Markdown detail agents

| File | Output pattern |
| ---- | ---------------- |
| [agent-md-architecture.md](./agent-md-architecture.md) | `architecture.md` (Mermaid **required**, more diagrams optional) |
| [agent-md-feature-detail.md](./agent-md-feature-detail.md) | `FE-<nn>-<slug>.md` |
| [agent-md-use-case-detail.md](./agent-md-use-case-detail.md) | `FE-<nn>_UC-<uu>.md` |
| [agent-md-scenario-detail.md](./agent-md-scenario-detail.md) | `FE-<nn>_UC-<uu>_SC-<ss>.md` |
| [agent-md-view-detail.md](./agent-md-view-detail.md) | `XP-<nn>-<slug>.md` |
| [agent-md-interaction-detail.md](./agent-md-interaction-detail.md) | `XP-<nn>_BH-<ii>-<slug>.md` |
| [agent-md-service-detail.md](./agent-md-service-detail.md) | `SV-<nn>-<slug>.md` |
| [agent-md-method-detail.md](./agent-md-method-detail.md) | `SV-<nn>_ME-<mm>-<slug>.md` |
| [agent-md-entity-detail.md](./agent-md-entity-detail.md) | `DM-<nn>-<slug>.md` |
| [agent-md-field-detail.md](./agent-md-field-detail.md) | `DM-<nn>_FD-<ff>-<slug>.md` |
| [agent-md-relationship-detail.md](./agent-md-relationship-detail.md) | `DM-<nn>_RL-<rr>-<slug>.md` |
| [agent-md-tool-detail.md](./agent-md-tool-detail.md) | `TS-<nn>-<slug>.md` |
| [agent-md-docs-project.md](./agent-md-docs-project.md) | `.easyspecs/context/project.md` |

## Not a bundled coding agent

**`index-application-context.json`** is built **only** by the programmatic assembler (SRS-8 **R8**, **R9**), not by a model.

## Maintainer note

The **JSON Schema** blocks inside each **`agent-list-*.md`** must stay identical to the matching file under **`resources/schemas/context-lists/`** (single source of truth for validators and **`{{LIST_SCHEMA_REF}}`**), including shared **`$defs`** for **`sourceReferences`** where present.

## History

- Coordination JSON and context markdown lived under **`.gluecharm/context/`** before the EasySpecs workspace rename; bundled agents now use **`.easyspecs/context/`** only (SRS-133). Re-materialize agents after upgrading the CLI so **`.opencode/agents/`** copies stay in sync.
