@gluecharm-lab/easyspecs-cli 0.0.3

package/resources/opencode-agents/agent-list-entity-fields.md

@@ -0,0 +1,191 @@
+---
+description: SRS-8 coordination JSON — writes per-entity DM-nn-fields-list.json under .gluecharm/context using file tools.
+mode: primary
+---
+
+# Agent: Entity fields list (per entity, coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-list-entity-fields` |
+| **Display name** | Entity fields list |
+| **SRS-8** | §4.6 `DM-<nn>-fields-list.json`; §6.5 Data model scope; **R6**, **R22** |
+| **Output** | `<worktree>/.gluecharm/context/DM-<nn>-fields-list.json` (one run per entity) |
+| **Pattern** | §3.5.2 — JSON list + **`{{PARENT_CONTEXT_BLOCK}}`** with **`DM_CODE`** |
+
+## Responsibility
+
+**`.opencode/` exclusion:** The worktree may contain **`.opencode/`** (materialized OpenCode agents, schemas, and tooling). It is **not** part of the analyzed product codebase. **Do not** use it to infer application behavior. **Never** cite paths under **`.opencode/`** in **`sourceReferences`**, UI/backend evidence arrays, Evidence index bullets, **`evidenceRefs`**, or any other code-grounding output.
+
+For **one entity** already fixed in `data-model-list.json`, emit all **fields** (`FD-*`) with stable codes, names, URL-safe **slugs** for detail markdown basenames **`DM-<nn>_FD-<ff>-<slug>.md`**, and **mandatory `sourceReferences`** on **every** field row (same object shape as features / entities / other coordination lists). Barrier for **field detail** markdown runs.
+
+## Revision
+
+Coordination output is **JSON** (no markdown `##` headings in the artifact). Maintain an append-only root **`revisionLog`** array (see schema): each pass that **adds, merges, refines, or rewrites** field rows must **append** at least `{ "summary": "…" }` (optional `"at"` ISO-8601). **Never delete** prior `revisionLog` entries. Prefer emitting **`revisionLog`** once the file holds real content; keep it updated alongside **Incremental JSON** writes.
+
+## Task (for `{{LIST_TASK_DESCRIPTION}}`)
+
+The orchestrator fills the task line with the target **DM-** code and output basename. Enumerate attributes, columns, or properties for **that entity only**. Do not change **`entityCode`**.
+
+### `sourceReferences` (required per field)
+
+- **Every** object in **`fields`** **must** include **`sourceReferences`**: a non-empty array (`minItems: 1`).
+- Each element: **`path`** (single repo-relative **file**, forward slashes, **never** a directory or trailing slash), **`startLine`**, **`endLine`** (1-based inclusive), optional **`note`**.
+- Cite schema, ORM models, migrations, DTOs, or types that justify the field — not narrative-only docs.
+- **Do not** use any path whose **basename** is `readme.md` in any casing (`README.md`, etc.).
+- **Do not** use paths under **`.opencode/`** (see **`.opencode/` exclusion** above).
+
+## JSON Schema (Draft 2020-12)
+
+**Bundled file:** `resources/schemas/context-lists/entity-fields-list.schema.json`  
+**Materialized (`{{LIST_SCHEMA_REF}}` example):** `<worktree>/.opencode/schemas/context-lists/entity-fields-list.schema.json`
+
+**Output filename:** `DM-<nn>-fields-list.json` must match **`entityCode`** (e.g. `DM-01` → `DM-01-fields-list.json`).
+
+**Keep this embedded block identical** to the bundled `.schema.json` (maintainer rule). Emit **only** JSON that validates (UTF-8, no comments):
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.ai/schemas/context-lists/entity-fields-list.schema.json",
+  "title": "DM-nn-fields-list",
+  "$defs": {
+    "sourceReference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "startLine", "endLine"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[^/]+(/[^/]+)*$",
+          "description": "Repo-relative path to a single file (forward slashes). Not a directory: no trailing slash; list each file in a folder as its own sourceReferences entry."
+        },
+        "startLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based inclusive start line."
+        },
+        "endLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based inclusive end line; should be >= startLine."
+        },
+        "note": {
+          "type": "string",
+          "description": "Optional short label for this evidence span."
+        }
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["entityCode", "fields"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "easyspecs.entity-fields-list",
+      "description": "Optional coordination document id; when present must be this value."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional coordination format version when present."
+    },
+    "entityCode": {
+      "type": "string",
+      "pattern": "^DM-[0-9]+$",
+      "description": "Must match the entity row in data-model-list.json and the output basename DM-nn-fields-list.json."
+    },
+    "fields": {
+      "type": "array",
+      "description": "Each field must include implementation evidence via sourceReferences (same shape as other coordination lists).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["code", "name", "slug", "sourceReferences"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^FD-[0-9]+$"
+          },
+          "name": { "type": "string", "minLength": 1 },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "description": "URL-safe slug for DM-nn_FD-ff-<slug>.md detail basename."
+          },
+          "description": { "type": "string" },
+          "order": { "type": "integer" },
+          "sourceReferences": {
+            "type": "array",
+            "minItems": 1,
+            "description": "At least one file + line span per field; each path is a single repo file (never a directory). Do not use readme.md basenames.",
+            "items": { "$ref": "#/$defs/sourceReference" }
+          }
+        }
+      }
+    },
+    "revisionLog": {
+      "type": "array",
+      "description": "Append-only log of substantive edits; add an entry whenever this pass changes rows, merges, or refines the coordination file.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["summary"],
+        "properties": {
+          "at": {
+            "type": "string",
+            "description": "ISO-8601 timestamp when known."
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000,
+            "description": "What was added, changed, or refined in this write."
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Example instance:**
+
+```json
+{
+  "entityCode": "DM-01",
+  "fields": [
+    {
+      "code": "FD-01",
+      "name": "email",
+      "slug": "email",
+      "description": "User login email",
+      "sourceReferences": [
+        {
+          "path": "prisma/schema.prisma",
+          "startLine": 12,
+          "endLine": 18,
+          "note": "User model column"
+        }
+      ]
+    }
+  ],
+  "revisionLog": [
+    { "summary": "Initial field list for entity; extend this array on every substantive merge or refinement pass." }
+  ]
+}
+```
+
+## Output rules
+
+- Write exactly one file at **`{{OUTPUT_FILE_ABSOLUTE}}`**.
+- Set **`entityCode`** to the **DM-** code from the parent context block (must match the basename prefix).
+- Use sequential **FD-01**, **FD-02**, … unless the repo already uses stable FD codes—then preserve them.
+- **Slug** must match `^[a-z0-9]+(?:-[a-z0-9]+)*$` (lowercase, hyphens).
+- If **`fields`** is empty (`[]`), no row-level **`sourceReferences`** are required (valid for entities with no persisted attributes found).
+
+## OpenCode wiring
+
+Bind this logical agent to your OpenCode CLI. Supply **`{{LIST_SCHEMA_REF}}`**, **`{{WORKTREE_ROOT}}`**, **`{{OUTPUT_FILE_ABSOLUTE}}`**, **`{{OUTPUT_BASENAME}}`**, **`{{PARENT_CONTEXT_BLOCK}}`**. Do **not** write `index-application-context.json`.

package/resources/opencode-agents/agent-list-experiences.md

@@ -0,0 +1,252 @@
+---
+description: SRS-8 coordination JSON — writes experiences-list.json under .gluecharm/context; repo-grounded views (web, desktop, CLI/TUI, hybrid); no invented surfaces.
+mode: primary
+---
+
+# Agent: Experiences list (coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-list-experiences` |
+| **Display name** | Experiences list |
+| **SRS-8** | §4.6 `experiences-list.json`; §6.3 Experience scope; §6.1 parallel with other global lists; **R6**, **R13**, **R22** |
+| **Output** | `<worktree>/.gluecharm/context/experiences-list.json` |
+| **Pattern** | §3.5.2 — JSON list (coordination) |
+
+## Responsibility
+
+**`.opencode/` exclusion:** The worktree may contain **`.opencode/`** (materialized OpenCode agents, schemas, and tooling). It is **not** part of the analyzed product codebase. **Do not** use it to infer application behavior. **Never** cite paths under **`.opencode/`** in **`sourceReferences`**, UI/backend evidence arrays, Evidence index bullets, **`evidenceRefs`**, or any other code-grounding output.
+
+Emit **views** (`XP-*`) and their **interactions** (`BH-*`) in a machine-readable tree or structure agreed by PLAN (nested under views or flat with parent references). This list is the barrier for parallel **`XP-<nn>-<slug>.md`** and then **`XP-<nn>_BH-<ii>-<slug>.md`** (§6.3).
+
+A **view** is any **distinct user-facing surface** the repository actually implements: graphical windows/pages, **terminal / CLI flows** (subcommands, prompts, help surfaces), **TUIs**, IDE/extension panels, etc. **Do not assume** a browser SPA or a single “routes folder” mental model.
+
+**Grounding rule:** Every **`XP-*`** and **`BH-*`** you emit must be **supportable from product source files** via **`sourceReferences`** with **`minItems: 1`** (one file per array entry, line range)—**not** from **`.opencode/`** or other tooling-only paths (see **`.opencode/` exclusion** above). If you cannot point to implementation or definitive wiring (e.g. form unit, route file, CLI dispatcher, contribution manifest), **omit** that view or interaction—do not invent placeholders to match a generic app shape.
+
+## Reasoning workflow (mandatory order)
+
+Follow this sequence before fixing codes and writing JSON. Skipping it produces **hallucinated views** (especially fake routes or screens).
+
+### 1. Classify UI paradigm(s)
+
+From **`{{WORKTREE_ROOT}}`** (projects, packages, entrypoints, frameworks—**not** assumptions), decide which apply:
+
+- **Web** (browser): SPA, SSR, static site, server templates.
+- **Desktop GUI**: Electron, Qt, WPF, WinForms, **Embarcadero Delphi / VCL / FMX**, etc.
+- **CLI**: binaries, scripted tools, multi-command CLIs, interactive prompts.
+- **TUI**: ncurses-style or modern terminal UIs.
+- **Hybrid**: e.g. desktop + embedded webview; CLI + optional GUI.
+- **No end-user UI in-repo** (library, pure backend): emit **only** what the schema and PLAN allow—typically **no** fabricated XP rows; if the product is “used via API only,” say so in `revisionLog` and keep the list minimal or empty per schema.
+
+### 2. Map where “views” live for each paradigm
+
+| Paradigm | Where to look (verify; examples only) |
+| -------- | ------------------------------------- |
+| Web | Router config, page/layout components, app entry, templates |
+| Desktop (generic) | Main window, scenes, XAML/storyboards, window classes |
+| **Delphi (Object Pascal)** | **`.dproj` / `.dpr`** → units; **forms**: **`.dfm`** + matching **`.pas`**; frames/datamodules may compose surfaces—trace **user-openable** forms/dialogs/wizards, not every internal module unless it is itself an interactive surface |
+| CLI | Entrypoint, command/subcommand registration, flag definitions, help text sources |
+| TUI | Screen definitions, panels, keybinding maps |
+| VS Code / extension | `package.json` `contributes`, webview registration, command IDs |
+
+Discovery for Delphi and many desktop stacks is **not linear** (unlike “one routes file”). Follow project and unit references until each claimed view has a **concrete** file span.
+
+### 3. Enumerate views and interactions from evidence
+
+- Name views by **what the user actually encounters** (e.g. “Main window”, “`migrate` subcommand”, “Settings dialog”).
+- Under each view, list **`BH-*`** interactions grounded in handlers, menu actions, CLI verbs, or control event code.
+- Prefer **fewer, verifiable** rows over a large speculative catalog.
+
+### 4. Emit schema-valid JSON
+
+Assign stable **`code`** values per srs-4 Experience scope, fill **`sourceReferences`** for views and interactions, maintain **`revisionLog`**.
+
+## Revision
+
+Coordination output is **JSON** (no markdown `##` headings in the artifact). Maintain an append-only root **`revisionLog`** array (see schema): each pass that **adds, merges, refines, or rewrites** rows must **append** at least `{ "summary": "…" }` (optional `"at"` ISO-8601). **Never delete** prior `revisionLog` entries. Prefer emitting **`revisionLog`** once the file holds real content; keep it updated alongside **Incremental JSON** writes.
+
+## Task (for `{{LIST_TASK_DESCRIPTION}}`)
+
+Run the **reasoning workflow**, then discover **only** user-facing surfaces and interactions **evidenced in the repo**. Assign stable **`code`** values consistent with srs-4 Experience scope.
+
+On each **view** (`XP-*`) and **interaction** (`BH-*`), include **`sourceReferences`** with **`minItems: 1`**: `path`, `startLine`, `endLine`, optional `note` (e.g. form unit + key procedure, route/component file, CLI dispatcher line range, `contributes.commands` span). Each **`path`** is one **file**, never a folder; enumerate files separately. If you cannot ground a row, **omit** it—do not emit views or interactions without evidence.
+
+## JSON Schema (Draft 2020-12)
+
+**Bundled file:** `resources/schemas/context-lists/experiences-list.schema.json`  
+**Materialized (`{{LIST_SCHEMA_REF}}` example):** `<worktree>/.opencode/schemas/context-lists/experiences-list.schema.json`
+
+Emit **only** JSON that validates against this schema:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.ai/schemas/context-lists/experiences-list.schema.json",
+  "title": "experiences-list",
+  "$defs": {
+    "sourceReference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "startLine", "endLine"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[^/]+(/[^/]+)*$",
+          "description": "Repo-relative path to a single file (forward slashes). Not a directory: no trailing slash; list each file in a folder as its own sourceReferences entry."
+        },
+        "startLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based inclusive start line."
+        },
+        "endLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based inclusive end line; should be >= startLine."
+        },
+        "note": {
+          "type": "string",
+          "description": "Optional short label for this evidence span."
+        }
+      }
+    },
+    "sourceReferenceList": {
+      "type": "array",
+      "description": "Evidence spans: each item references one file + line range, never a folder path.",
+      "items": { "$ref": "#/$defs/sourceReference" }
+    },
+    "interactionItem": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["code", "name", "sourceReferences"],
+      "properties": {
+        "code": {
+          "type": "string",
+          "pattern": "^BH-[0-9]+$"
+        },
+        "name": { "type": "string", "minLength": 1 },
+        "slug": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+          "description": "Recommended for XP-<nn>_BH-<ii>-<slug>.md detail basenames."
+        },
+        "description": { "type": "string" },
+        "order": { "type": "integer" },
+        "sourceReferences": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Required: at least one file + line range per interaction row.",
+          "items": { "$ref": "#/$defs/sourceReference" }
+        }
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["views"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "easyspecs.experiences-list",
+      "description": "Optional coordination document id; when present must be this value."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional coordination format version when present."
+    },
+    "views": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["code", "name", "sourceReferences"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^XP-[0-9]+$"
+          },
+          "name": { "type": "string", "minLength": 1 },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "description": "Recommended for XP-<nn>-<slug>.md detail basenames."
+          },
+          "description": { "type": "string" },
+          "order": { "type": "integer" },
+          "sourceReferences": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Required: at least one file + line range per view row.",
+            "items": { "$ref": "#/$defs/sourceReference" }
+          },
+          "interactions": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/interactionItem" }
+          }
+        }
+      }
+    },
+    "revisionLog": {
+      "type": "array",
+      "description": "Append-only log of substantive edits; add an entry whenever this pass changes rows, merges, or refines the coordination file.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["summary"],
+        "properties": {
+          "at": {
+            "type": "string",
+            "description": "ISO-8601 timestamp when known."
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000,
+            "description": "What was added, changed, or refined in this write."
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Example instance (web SPA shape—illustrative only):** For CLI-only repos, a “view” might be **`XP-01` = root CLI / help** with **`BH-*`** per subcommand file; for Delphi, cite **`.pas` + `.dfm`** pairs per form. **Do not copy** this example’s paths or structure when the repo is not a web app.
+
+```json
+{
+  "views": [
+    {
+      "code": "XP-01",
+      "name": "Login screen",
+      "slug": "login-screen",
+      "sourceReferences": [
+        { "path": "src/views/Login.vue", "startLine": 1, "endLine": 200, "note": "screen shell" }
+      ],
+      "interactions": [
+        {
+          "code": "BH-01",
+          "name": "Submit credentials",
+          "slug": "submit-credentials",
+          "sourceReferences": [
+            { "path": "src/views/Login.vue", "startLine": 80, "endLine": 120, "note": "submit handler" }
+          ]
+        }
+      ]
+    }
+  ],
+  "revisionLog": [
+    { "summary": "Initial experiences/views discovery; extend this array on every substantive merge or refinement pass." }
+  ]
+}
+```
+
+## Barriers
+
+- **After** `experiences-list.json` is valid, parallel view detail agents may run; after BH codes are fixed per view, parallel interaction detail agents may run (§6.3).
+
+## OpenCode wiring
+
+§3.5.2 prompt. Supply **`{{LIST_SCHEMA_REF}}`**, **`{{WORKTREE_ROOT}}`**, **`{{OUTPUT_FILE_ABSOLUTE}}`**, **`{{OUTPUT_BASENAME}}`**. Fill **`{{PARENT_CONTEXT_BLOCK}}`** only if generating a child list file in a split PLAN. Never write the final index JSON.

package/resources/opencode-agents/agent-list-features.md

@@ -0,0 +1,218 @@
+---
+description: SRS-8 coordination JSON — incremental schema-valid features-list.json while discovering the repo; multi-pass refinement; .gluecharm/context (file tools; chat-only insufficient).
+mode: primary
+---
+
+# Agent: Features list (coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-list-features` |
+| **Display name** | Features list |
+| **SRS-8** | §4.6 `features-list.json`; §6.1 global discovery; §6.2 Feature scope entry; **R6**, **R22** |
+| **Output** | `<worktree>/.gluecharm/context/features-list.json` |
+| **Pattern** | §3.5.2 — JSON list (coordination) |
+
+## Responsibility
+
+**`.opencode/` exclusion:** The worktree may contain **`.opencode/`** (materialized OpenCode agents, schemas, and tooling). It is **not** part of the analyzed product codebase. **Do not** use it to infer application behavior. **Never** cite paths under **`.opencode/`** in **`sourceReferences`**, UI/backend evidence arrays, Evidence index bullets, **`evidenceRefs`**, or any other code-grounding output.
+
+Emit the **canonical registry of features**: stable **`code`** (`FE-01` …), human-readable **`name`**, and **`<slug>`** for each feature’s detail file basename **`FE-<nn>-<slug>.md`** (§4.1, §4.3). This file is the **barrier input** for parallel feature-detail markdown and per-feature use-case list agents (§6.2).
+
+## Revision
+
+Coordination output is **JSON** (no markdown `##` headings in the artifact). Maintain an append-only root **`revisionLog`** array (see schema): each pass that **adds, merges, refines, or rewrites** rows must **append** at least `{ "summary": "…" }` (optional `"at"` ISO-8601). **Never delete** prior `revisionLog` entries. Prefer emitting **`revisionLog`** once the file holds real content; keep it updated alongside **Incremental JSON** writes.
+
+## Task (for `{{LIST_TASK_DESCRIPTION}}`)
+
+Produce **`features-list.json`** by **discovering every meaningful feature or capability** this repository implements—not a quick skim of `README.md`. Each row must be suitable for driving downstream use-case and scenario work. Do **not** write markdown lists; output **one JSON file** only.
+
+### Incremental JSON (mandatory)
+
+Treat **`{{OUTPUT_FILE_ABSOLUTE}}`** as a **living document** while you navigate and read the project:
+
+1. **Create early** — After your initial tree map (or as soon as you have the path), write a **schema-valid** starting document, e.g. `{ "features": [] }`, or seed it with the first features you already identified from `package.json` / entrypoints.
+2. **Expand as you learn** — Whenever exploration surfaces a **new** capability (new subsystem, command surface, pipeline, integration, or operator workflow), **read** the current file, **merge** in new objects (or enrich `description` / `name` / `slug` / **`sourceReferences`** on an existing row if it is the same theme), then **write back the full JSON object** in one shot. Do not accumulate features only in chat: the file must grow with your understanding of the codebase. Each feature **must** include **`sourceReferences`** with **`minItems: 1`** — **files** with line ranges only, **never** a folder path; add one object per evidence file.
+3. **Always valid** — Every write must be **parseable JSON** and satisfy **`features-list.schema.json`** (no comments, no trailing text). Prefer rewriting the whole file rather than risky partial edits.
+4. **Stable codes** — Assign **`FE-01`, `FE-02`, …** as you add rows; **do not renumber** existing codes during incremental adds (downstream agents depend on stability). Use later consolidation passes only to merge duplicates (drop one code), split overloaded rows (add new codes at the end), or fix slugs/text—not to shuffle codes arbitrarily.
+
+### Repository discovery (mandatory)
+
+1. **Map the tree first** — List top-level directories and important roots (`src/`, `resources/`, `test/` or `tests/`, `docs/`, `.gluecharm/`, scripts, config). **Skip** **`.opencode/`** for product discovery (materialized agents/schemas only — see **`.opencode/` exclusion** above). Note entry points: `package.json` (scripts, `contributes`, activation), extension host registration, CLI binaries, webviews, and any `README*` / architecture notes.
+2. **Read broadly, then deeply** — Open files that define behavior: implementation modules, command handlers, providers, stores, analysis/orchestration pipelines, onboarding, integration with external tools, and user-visible surfaces (commands, settings, UI strings). Use cross-references (imports, manifests) to find related areas you have not opened yet.
+3. **Cover non-UI capability** — Include developer tooling, background jobs, file watchers, worktrees, schema generation, test harnesses, and packaging concerns **when they constitute a coherent product capability** (not every private helper).
+4. **Trace boundaries** — If the repo is an extension plus CLI (or multiple surfaces), ensure each **distinct user- or operator-facing theme** gets its own feature or is clearly scoped under one feature with a description that states the scope.
+
+### Exhaustiveness
+
+The list must be **as complete as the repository allows**: prefer **splitting** distinct themes over merging unrelated behavior under one vague feature. Before finalizing, mentally check: *commands/settings from `package.json`*, *major `src/` subsystems*, *documented workflows*, *tests that name product areas*, and *anything a user or integrator could invoke or depend on*. Missing a real capability is worse than briefly overlapping two entries you later refine in description.
+
+**Downstream cardinality:** For each **meaningful** product feature, the later **use-cases list** should **usually** enumerate **several** use cases (different goals, surfaces, or actors). When scoping a row, avoid one **over-broad** FE that hides multiple independent journeys in a way that would pressure authors into a **single** UC; split themes when the code supports distinct stories.
+
+### Quality: refine in passes (mandatory)
+
+Discovery and **incremental file updates** above are the primary way the list grows. When navigation is substantially complete, run **at least three** refinement passes **against the current JSON on disk** (read → edit → write full valid JSON each time; no separate staging file):
+
+| Pass | Goal |
+| ---- | ---- |
+| **1 — Coverage check** | Re-walk the repo tree and manifests against the file; append missing features; remove entries with no evidence in code or docs. |
+| **2 — Consolidation** | Merge true duplicates; split overloaded rows; tighten `name` and optional `description`; ensure slugs are kebab-case per schema; set sensible **`order`** if used. |
+| **3 — Final sanity** | Unique `code` values, schema-valid document, each feature has **`sourceReferences`** with **`minItems: 1`** (**file** paths + line ranges, no directories); plus command ids in prose/`description` where useful. |
+| **4 (optional)** | Second gap hunt if the repo is large or you touched new areas late. |
+
+The file at **`{{OUTPUT_FILE_ABSOLUTE}}`** must already contain the near-final list before these passes; passes **refine** it, not replace a chat-only draft.
+
+## JSON Schema (Draft 2020-12)
+
+**Bundled file:** `resources/schemas/context-lists/features-list.schema.json`  
+**Materialized (`{{LIST_SCHEMA_REF}}` example):** `<worktree>/.opencode/schemas/context-lists/features-list.schema.json`
+
+**`sourceReferences` (this list):** **required** on each feature row (`minItems: 1`). Each object cites **one file** with a line range — **`path`** is repo-relative, forward slashes, **no trailing slash**, **never a directory**. **Never** use paths under **`.opencode/`** (see **`.opencode/` exclusion** above). To cover a folder’s “contents”, emit **one array element per file** (each with its own `startLine`/`endLine`), not one entry for the folder. Optional **`note`**.
+
+Emit **only** JSON that validates against this schema (UTF-8, no comments, no trailing text):
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://easyspecs.ai/schemas/context-lists/features-list.schema.json",
+  "title": "features-list",
+  "$defs": {
+    "sourceReference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "startLine", "endLine"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[^/]+(/[^/]+)*$",
+          "description": "Repo-relative path to a single file (forward slashes). Not a directory: no trailing slash; list each file in a folder as its own sourceReferences entry."
+        },
+        "startLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based inclusive start line."
+        },
+        "endLine": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "1-based inclusive end line; should be >= startLine."
+        },
+        "note": {
+          "type": "string",
+          "description": "Optional short label for this evidence span."
+        }
+      }
+    },
+    "sourceReferenceList": {
+      "type": "array",
+      "description": "Evidence spans: each item references one file + line range, never a folder path.",
+      "items": { "$ref": "#/$defs/sourceReference" }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["features"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "easyspecs.features-list",
+      "description": "Optional coordination document id; when present must be this value."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional coordination format version when present."
+    },
+    "features": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["code", "name", "slug", "sourceReferences"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^FE-[0-9]+$",
+            "description": "Stable feature code; FE- plus one or more digits (e.g. FE-1, FE-01, FE-120)."
+          },
+          "name": { "type": "string", "minLength": 1 },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "description": "URL-safe slug for FE-<nn>-<slug>.md basename."
+          },
+          "description": { "type": "string" },
+          "order": { "type": "integer" },
+          "featureKind": {
+            "type": "string",
+            "enum": ["product", "infrastructure", "testing"],
+            "description": "SRS-27: classify product vs platform/ops vs verification-only surface; omit to treat as product in consumers that care."
+          },
+          "sourceReferences": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Required: at least one file + line range per feature row.",
+            "items": { "$ref": "#/$defs/sourceReference" }
+          }
+        }
+      }
+    },
+    "revisionLog": {
+      "type": "array",
+      "description": "Append-only log of substantive edits; add an entry whenever this pass changes rows, merges, or refines the coordination file.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["summary"],
+        "properties": {
+          "at": {
+            "type": "string",
+            "description": "ISO-8601 timestamp when known."
+          },
+          "summary": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 2000,
+            "description": "What was added, changed, or refined in this write."
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Example instance:**
+
+```json
+{
+  "features": [
+    {
+      "code": "FE-01",
+      "name": "User authentication",
+      "slug": "user-authentication",
+      "order": 1,
+      "sourceReferences": [
+        {
+          "path": "src/auth/login.ts",
+          "startLine": 1,
+          "endLine": 120,
+          "note": "login flow"
+        }
+      ]
+    }
+  ],
+  "revisionLog": [
+    { "summary": "Initial features discovery; extend this array on every substantive merge or refinement pass." }
+  ]
+}
+```
+
+## Barriers
+
+- **After** this file exists and is valid, orchestration may fan out **`FE-<nn>-<slug>.md`** and **`FE-<nn>-use-cases-list.json`** in parallel (§6.2).
+
+## OpenCode wiring
+
+Bind this logical agent to your OpenCode CLI (e.g. `runOpenCodeAgent` with a prompt constructed from §3.5.2). Supply **`{{LIST_SCHEMA_REF}}`**, **`{{WORKTREE_ROOT}}`**, **`{{OUTPUT_FILE_ABSOLUTE}}`**, **`{{OUTPUT_BASENAME}}`**. Do **not** write `index-application-context.json`.