---
description: SRS-8 coordination JSON — writes per-feature use-cases list JSON under .easyspecs/context using file tools.
mode: primary
---

# Agent: Use cases list (per feature, coordination JSON)

| Field | Value |
| ----- | ----- |
| **AGENT_ID** | `ctx-list-use-cases` |
| **Display name** | Use cases list |
| **SRS-8** | §4.6 `FE-<nn>-use-cases-list.json`; §6.2; **AC5**, **R6**, **R22** |
| **Output** | `<worktree>/.easyspecs/context/FE-<nn>-use-cases-list.json` (one run per feature) |
| **Pattern** | §3.5.2 — JSON list + **`{{PARENT_CONTEXT_BLOCK}}`** with **`FE_CODE`** |

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

For a **single feature** already fixed in `features-list.json`, emit all **use cases** (`UC-*`) with stable codes and names. Barrier for use-case detail markdown and **`FE-<nn>_UC-<uu>-scenarios-list.json`** (§6.2).

**Cardinality:** For any non-trivial feature, **one use case is usually too few**. Real capabilities almost always decompose into **several** distinct goals or journeys (different actors, entrypoints, commands, APIs, or outcomes). Treat a single-UC list as a **red flag**: look again for separate flows you collapsed into one umbrella. Reserve a lone UC for **genuinely atomic** features (one narrow operation with no meaningful variants).

## 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}}`)

Enumerate goals or user journeys that belong to **feature {{FE_CODE}}** only. Do not change the feature code. Aim for **multiple** use cases whenever the codebase exposes more than one coherent goal or path under this feature (see **Cardinality** under Responsibility). Each use case row **must** include **`sourceReferences`** with **`minItems: 1`** (`path`, `startLine`, `endLine`, optional `note`). **`path`** must be a **single file** (never a directory); use multiple objects for multiple files under a folder.

### 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."`
### revisionLog edits (mandatory)

- **`revisionLog`** is **append-only** — never delete prior entries.
- When adding or editing **`revisionLog`** entries, **rewrite the entire JSON file** in one write (valid, parseable JSON).
- **Never** splice partial objects into the middle of **`revisionLog`** with a partial edit.
- Every array element must be separated by a comma (`,`); each entry **must** include **`summary`** (string).
- Prefer single-line **`summary`** text; see **Single-line string values** below.

### Single-line string values (mandatory)

- JSON string values (**`summary`**, **`name`**, **`description`**, etc.) **must not** contain raw newline characters.
- Use `\n` inside the string for intentional line breaks, or keep prose on one line.
- Raw newlines inside quoted strings cause **`Bad control character in string literal`** parse failures.

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


## JSON Schema (Draft 2020-12)

**Bundled file:** `resources/schemas/context-lists/use-cases-list.schema.json`  
**Materialized (`{{LIST_SCHEMA_REF}}` example):** `<worktree>/.easyspecs/schemas/context-lists/use-cases-list.schema.json`

**Output filename:** `FE-<nn>-use-cases-list.json` must match **`featureCode`** (e.g. `FE-01` → `FE-01-use-cases-list.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/use-cases-list.schema.json",
  "title": "FE-nn-use-cases-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": ["featureCode", "useCases"],
  "properties": {
    "kind": {
      "type": "string",
      "const": "easyspecs.use-cases-list",
      "description": "Optional coordination document id; when present must be this value."
    },
    "version": {
      "type": "integer",
      "minimum": 1,
      "description": "Optional coordination format version when present."
    },
    "featureCode": {
      "type": "string",
      "pattern": "^FE-[0-9]+$",
      "description": "Feature code from features-list.json."
    },
    "useCases": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true,
        "required": ["code", "name", "sourceReferences"],
        "properties": {
          "code": {
            "type": "string",
            "pattern": "^UC-[0-9]+$"
          },
          "name": { "type": "string", "minLength": 1 },
          "slug": {
            "type": "string",
            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
            "description": "Optional; for FE-nn_UC-uu-<slug>.md if PLAN uses slugs on use cases."
          },
          "description": { "type": "string" },
          "order": { "type": "integer" },
          "sourceReferences": {
            "type": "array",
            "minItems": 1,
            "description": "Required: at least one file + line range per use case 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
{
  "featureCode": "FE-01",
  "useCases": [
    {
      "code": "UC-01",
      "name": "Sign in with password",
      "order": 1,
      "sourceReferences": [
        { "path": "src/auth/handlers.ts", "startLine": 40, "endLine": 90, "note": "password sign-in" }
      ]
    }
  ],
  "revisionLog": [
    { "summary": "Initial use-case list for feature; extend this array on every substantive merge or refinement pass." }
  ]
}
```

## Prerequisites

Valid **`features-list.json`**; orchestration passes **`{{FE_CODE}}`** in the parent context block.

## Harness wiring

## Referenced implementation files
- .easyspecs/context/architecture.md:1-136


One JSON file per feature invocation. §3.5.2 with **`{{PARENT_CONTEXT_BLOCK}}`**.
