@gluecharm-lab/easyspecs-cli 0.0.3

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

@@ -0,0 +1,179 @@
+---
+description: SRS-8 coordination JSON — writes per-use-case scenarios list JSON under .gluecharm/context using file tools.
+mode: primary
+---
+
+# Agent: Scenarios list (per use case, coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-list-scenarios` |
+| **Display name** | Scenarios list |
+| **SRS-8** | §4.6 `FE-<nn>_UC-<uu>-scenarios-list.json`; §6.2; **AC6**, **R6**, **R22** |
+| **Output** | `<worktree>/.gluecharm/context/FE-<nn>_UC-<uu>-scenarios-list.json` |
+| **Pattern** | §3.5.2 — JSON list + parent **`FE_CODE`**, **`UC_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 **use case**, emit all **scenarios** (`SC-*`). Barrier for parallel **`FE-<nn>_UC-<uu>_SC-<ss>.md`** detail agents (§6.2).
+
+**Cardinality:** For any non-trivial use case, **one scenario is usually too few**. Expect **several** scenarios: at minimum happy path plus meaningful variants (validation failures, auth/permission denials, empty or boundary data, conflicts, retries, optional branches). Treat a single-SC list as a **red flag** unless the use case is truly a single linear path with no testable branches.
+
+## 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}}`)
+
+List concrete scenarios (flows, test-like paths, edge cases) for **feature {{FE_CODE}}**, **use case {{UC_CODE}}**. Do not alter parent codes. Aim for **multiple** scenarios when the implementation or tests support distinct paths (see **Cardinality** under Responsibility). Each scenario **must** include **`sourceReferences`** with **`minItems: 1`** (`path`, `startLine`, `endLine`, optional `note`). **`path`** is always one **file**, never a folder; split folder evidence across multiple entries.
+
+## JSON Schema (Draft 2020-12)
+
+**Bundled file:** `resources/schemas/context-lists/scenarios-list.schema.json`  
+**Materialized (`{{LIST_SCHEMA_REF}}` example):** `<worktree>/.opencode/schemas/context-lists/scenarios-list.schema.json`
+
+**Output filename:** `FE-<nn>_UC-<uu>-scenarios-list.json` must match **`featureCode`** and **`useCaseCode`**.
+
+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/scenarios-list.schema.json",
+  "title": "FE-nn_UC-uu-scenarios-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", "useCaseCode", "scenarios"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "easyspecs.scenarios-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."
+    },
+    "useCaseCode": {
+      "type": "string",
+      "pattern": "^UC-[0-9]+$"
+    },
+    "scenarios": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["code", "name", "sourceReferences"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^SC-[0-9]+$"
+          },
+          "name": { "type": "string", "minLength": 1 },
+          "description": { "type": "string" },
+          "order": { "type": "integer" },
+          "sourceReferences": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Required: at least one file + line range per scenario 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",
+  "useCaseCode": "UC-01",
+  "scenarios": [
+    {
+      "code": "SC-01",
+      "name": "Valid credentials redirect to home",
+      "order": 1,
+      "sourceReferences": [
+        { "path": "test/e2e/login.spec.ts", "startLine": 10, "endLine": 35, "note": "happy path" }
+      ]
+    }
+  ],
+  "revisionLog": [
+    { "summary": "Initial scenario list for use case; extend this array on every substantive merge or refinement pass." }
+  ]
+}
+```
+
+## Prerequisites
+
+Corresponding **`FE-<nn>-use-cases-list.json`** exists.
+
+## OpenCode wiring
+
+§3.5.2; fill **`{{PARENT_CONTEXT_BLOCK}}`** with FE and UC codes.

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

@@ -0,0 +1,208 @@
+---
+description: SRS-8 coordination JSON — writes services-list.json under .gluecharm/context using file tools.
+mode: primary
+---
+
+# Agent: Services list (coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-list-services` |
+| **Display name** | Services list |
+| **SRS-8** | §4.6 `services-list.json`; §6.4 Service scope; **R6**, **R13**, **R22** |
+| **Output** | `<worktree>/.gluecharm/context/services-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 **services** (`SV-*`) and **methods** (`ME-*`) as a structured list (methods nested under services or via optional per-service list files per PLAN). Barrier for **`SV-<nn>-<slug>.md`** and **`SV-<nn>_ME-<mm>-<slug>.md`** (§6.4).
+
+## 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}}`)
+
+Identify bounded contexts, APIs, backend services, or modules that expose callable operations. Assign stable **`SV-*`** and **`ME-*`** codes and names. Each **service** and each **method** **must** include **`sourceReferences`** with **`minItems: 1`** (`path`, `startLine`, `endLine`, optional `note`). **`path`** must be a **file** path only, not a module directory; one array element per file.
+
+## JSON Schema (Draft 2020-12)
+
+**Bundled file:** `resources/schemas/context-lists/services-list.schema.json`  
+**Materialized (`{{LIST_SCHEMA_REF}}` example):** `<worktree>/.opencode/schemas/context-lists/services-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/services-list.schema.json",
+  "title": "services-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" }
+    },
+    "methodItem": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["code", "name", "sourceReferences"],
+      "properties": {
+        "code": {
+          "type": "string",
+          "pattern": "^ME-[0-9]+$"
+        },
+        "name": { "type": "string", "minLength": 1 },
+        "slug": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+          "description": "Recommended for SV-<nn>_ME-<mm>-<slug>.md detail basenames."
+        },
+        "description": { "type": "string" },
+        "order": { "type": "integer" },
+        "sourceReferences": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Required: at least one file + line range per method row.",
+          "items": { "$ref": "#/$defs/sourceReference" }
+        }
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["services"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "easyspecs.services-list",
+      "description": "Optional coordination document id; when present must be this value."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional coordination format version when present."
+    },
+    "services": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["code", "name", "sourceReferences"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^SV-[0-9]+$"
+          },
+          "name": { "type": "string", "minLength": 1 },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "description": "Recommended for SV-<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 service row.",
+            "items": { "$ref": "#/$defs/sourceReference" }
+          },
+          "methods": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/methodItem" }
+          }
+        }
+      }
+    },
+    "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
+{
+  "services": [
+    {
+      "code": "SV-01",
+      "name": "Auth API",
+      "slug": "auth-api",
+      "sourceReferences": [
+        { "path": "src/api/auth/index.ts", "startLine": 1, "endLine": 60, "note": "service module" }
+      ],
+      "methods": [
+        {
+          "code": "ME-01",
+          "name": "POST /login",
+          "slug": "post-login",
+          "sourceReferences": [
+            { "path": "src/api/auth/index.ts", "startLine": 100, "endLine": 180, "note": "login route" }
+          ]
+        }
+      ]
+    }
+  ],
+  "revisionLog": [
+    { "summary": "Initial services/methods discovery; extend this array on every substantive merge or refinement pass." }
+  ]
+}
+```
+
+## Barriers
+
+After this list is valid, parallel service markdown and (once ME codes are fixed) method markdown agents may run.
+
+## OpenCode wiring
+
+§3.5.2; enforce single JSON output path. No writes to `index-application-context.json`.

package/resources/opencode-agents/agent-list-tech-stack.md

@@ -0,0 +1,176 @@
+---
+description: SRS-8 coordination JSON — writes tech-stack-list.json under .gluecharm/context using file tools.
+mode: primary
+---
+
+# Agent: Tech stack list (coordination JSON)
+
+| Field | Value |
+| ----- | ----- |
+| **AGENT_ID** | `ctx-list-tech-stack` |
+| **Display name** | Tech stack list |
+| **SRS-8** | §4.6 `tech-stack-list.json`; §6.6 Tech stack scope; **R6**, **R13**, **R22** |
+| **Output** | `<worktree>/.gluecharm/context/tech-stack-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 **tools** (`TS-*`): languages, frameworks, infra, key libraries. Usually one level of detail; PLAN may add depth. Barrier for parallel **`TS-<nn>-<slug>.md`** (§6.6).
+
+## 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}}`)
+
+Inventory the technology stack from manifest files, configs, and repo structure. Each tool gets a stable **`TS-<nn>`** code and **`name`**. Each tool **must** include **`sourceReferences`**: a non-empty array (`minItems: 1`) of `{ path, startLine, endLine, note? }` — **`path`** must name a **file** (e.g. `package.json`, `pnpm-lock.yaml`), never a directory; use several entries if evidence spans multiple files.
+
+## JSON Schema (Draft 2020-12)
+
+**Bundled file:** `resources/schemas/context-lists/tech-stack-list.schema.json`  
+**Materialized (`{{LIST_SCHEMA_REF}}` example):** `<worktree>/.opencode/schemas/context-lists/tech-stack-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/tech-stack-list.schema.json",
+  "title": "tech-stack-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": ["tools"],
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "easyspecs.tech-stack-list",
+      "description": "Optional coordination document id; when present must be this value."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Optional coordination format version when present."
+    },
+    "tools": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["code", "name", "sourceReferences"],
+        "properties": {
+          "code": {
+            "type": "string",
+            "pattern": "^TS-[0-9]+$"
+          },
+          "name": { "type": "string", "minLength": 1 },
+          "slug": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+            "description": "Recommended for TS-<nn>-<slug>.md detail basenames."
+          },
+          "category": {
+            "type": "string",
+            "description": "e.g. runtime, framework, infra, library"
+          },
+          "version": { "type": "string", "description": "Tool or library version string (not coordination `version`)." },
+          "description": { "type": "string" },
+          "order": { "type": "integer" },
+          "sourceReferences": {
+            "type": "array",
+            "minItems": 1,
+            "description": "Required: at least one repo file + line range grounding this tool (e.g. package.json, lockfile, tsconfig).",
+            "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
+{
+  "tools": [
+    {
+      "code": "TS-01",
+      "name": "TypeScript",
+      "slug": "typescript",
+      "category": "language",
+      "version": "5.x",
+      "sourceReferences": [
+        { "path": "package.json", "startLine": 1, "endLine": 80, "note": "devDependencies" }
+      ]
+    }
+  ],
+  "revisionLog": [
+    { "summary": "Initial tech-stack discovery; extend this array on every substantive merge or refinement pass." }
+  ]
+}
+```
+
+## Barriers
+
+After this file is valid, parallel tool detail markdown agents may run.
+
+## OpenCode wiring
+
+§3.5.2. Single JSON output file only.