---
description: SRS-8 coordination JSON — incremental schema-valid features-list.json while discovering the repo; multi-pass refinement; .easyspecs/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>/.easyspecs/context/features-list.json` |
| **Pattern** | §3.5.2 — JSON list (coordination) |

## Responsibility

**`.opencode/` and `.claude/` exclusion:** The worktree may contain **`.opencode/`** or **`.claude/`** (materialized coding agent definitions, 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/`** or **`.claude/`** 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).

## Implementation-only (SRS-114)

Document **only** what is **implemented in this repository today**. Do **not** add knowledge nodes for planned, missing, roadmap, or spec-only capabilities.

- **Include** a row or detail section **only** when you can cite **implementation evidence** (§3.1 in SRS-114): wired entrypoints, executable bodies, real UI artefacts, schemas in use, or behavioural tests (QA/TC).
- **Omit** the node entirely when you find only SRS, PLAN, README, comments, types without callers, empty stubs, or configs nothing reads.
- **`sourceReferences`** and **Evidence index** **must** include **at least one implementation anchor** (non-`.md` path per §5.6.2). **`.md`** files (SRS, README, plans) **may** be cited **in addition**, never as the **only** cites.
- **Review passes:** drop unimplemented rows like false rows; log **`droppedCodes`** / **`revisionLog`** (SRS-50).
- **Do not** fill coordination lists with placeholders for future work. An empty array is valid when nothing is implemented.


## 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.

## SRS-50 — Stable coordination writes

EasySpecs **merge-by-code** after the run: **existing codes** keep their **previous file order**; **new** codes are moved to the **end** of each coded array (including nested BH/ME/FD/RL rows under the correct parent). **Append** new rows at the end while authoring.

## 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.
### JSON string literals (RFC 8259 — mandatory)

- Coordination artefacts use **double-quoted** JSON strings only.
- **Apostrophes / single quotes** inside text (e.g. user's, don't, it's) **must appear as the plain character** `'` — **never** as `\'`. In JSON, `\'` is **invalid** and causes `JSON.parse` to fail with *Bad escaped character*.
- **Only** escape `"` as `\"`, backslashes as `\\`, and use `\n`, `\t`, `\uXXXX` where needed. Do **not** use Python-, SQL-, or JavaScript-single-quote escaping in `.json` files.
- **Examples (description field):**
  - ✅ `"description": "API endpoint to update a user's password."`
  - ❌ `"description": "API endpoint to update a user\'s password."`
### Write real JSON files (mandatory)

- Write **parseable UTF-8 JSON** directly to disk — not a stringified or escaped JSON blob (no literal `\n` or `\"` sequences as file content).
- The on-disk file must be valid JSON that `JSON.parse` accepts without unescaping.

### sourceReferences shape (mandatory)

- Each `sourceReferences` entry must be an **object** `{ "path": "src/file.js", "startLine": 1, "endLine": 42 }`.
- **Never** use plain strings like `"src/router/index.js:145"` in `sourceReferences` arrays.
- If a path includes `:line`, split into `path`, `startLine`, and `endLine` fields instead.


3b. **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/`, `.easyspecs/`, 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

**SRS-114:** Including an unimplemented capability is worse than omitting it.

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*, *implemented workflows visible in code*, *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 **implemented** evidence (non-`.md` anchors per SRS-114). |
| **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>/.easyspecs/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).

## Harness wiring

Bind this logical agent to the active harness CLI (e.g. `runHarnessAgent` 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`.
