Split MATTER.md skill into using + building-clients

README.md

@@ -46,6 +46,8 @@ Use the `/v1/skills` endpoint or the `container.skills` parameter in Messages AP
 | [ocr](skills/casedev/ocr/) | Document OCR: process PDFs/images, word-level positional data |
 | [transcription](skills/casedev/transcription/) | Audio/video transcription with speaker diarization |
 | [search](skills/casedev/search/) | Web, legal, case law, patent, vault, and skills KB search |
+| [using-matter-md](skills/casedev/using-matter-md/) | Operational guidance for reading and updating MATTER.md durable matter context during legal work |
+| [building-matter-md-clients](skills/casedev/building-matter-md-clients/) | Spec and implementation guidance for adding MATTER.md support to an agent harness |
 
 ### Legal Skills
 

skills/casedev/building-matter-md-clients/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: building-matter-md-clients
+language: en
+description: Specification and implementation guidance for adding MATTER.md support to a legal agent harness or client. Use when building or extending an agent harness (such as a legal agent runtime) to discover, load, persist, and version MATTER.md durable context files. For how an agent should read and edit MATTER.md during matter work, see using-matter-md.
+---
+
+# Building MATTER.md Clients
+
+`MATTER.md` is a plain-Markdown durable context file for a legal matter — the matter-level equivalent of a project instructions file. A harness implements MATTER.md by discovering the file, loading it into the agent's context at the right point, and persisting agent edits through its own storage layer.
+
+Keep **transport separate from the file convention.** The file is just Markdown; the harness owns where it lives and how it is versioned.
+
+## File format
+
+A `MATTER.md` file is Markdown with optional YAML frontmatter:
+
+```markdown
+---
+mattermd: "0.1"
+title: "Smith v. Jones"
+---
+
+# Matter
+
+## What This Is
+...
+```
+
+- `mattermd`: format version string. Lets clients detect and migrate the convention over time.
+- `title`: human label for the matter.
+
+Frontmatter is optional except where the host platform needs a mechanical handle (lookup, display, indexing). Keep it small — matter *meaning* lives in the Markdown body, not in YAML. Do not require fields beyond what the platform mechanically needs.
+
+The body is freeform Markdown. `using-matter-md` ships a starter template with suggested sections (`What This Is`, `Goals`, `Source Map`, `Open Questions`, `Board`, etc.), but these are **illustrative, not normative** — legal work varies too much to fix a schema. Agents add, drop, and reshape sections per matter. Do not parse or validate the body against a section list; treat it as opaque Markdown.
+
+## Loading lifecycle
+
+A minimal implementation:
+
+1. **Discover** the file named `MATTER.md` at the root of the matter workspace (e.g. the vault root).
+2. **Load** it after global agent instructions and before matter task execution.
+3. **Preserve** it across context compaction — it is durable state, not a transient turn.
+4. Let the agent **read and update** the file through ordinary file tools.
+5. **Persist** the edited file using the host platform's storage layer.
+
+Edit via plain file tools. A client *may* add dedicated MATTER.md tools, but only if it accepts the schema that implies — the convention itself assumes nothing beyond "a Markdown file you can read and write."
+
+## Concurrency
+
+The convention does not define a locking model — clients own conflict resolution. If multiple agents can write one `MATTER.md`, keep edits append-friendly (append to list/table sections rather than rewriting prose) so concurrent writes are less likely to clobber each other, and resolve the rest with whatever your storage layer offers (e.g. conditional writes).
+
+## Principles
+
+- **No heavy infrastructure required.** Do not require a database, schema registry, CRDT, or sync protocol to support `MATTER.md`. A file and a place to put it are enough.
+- **Version history belongs to the host, not the file.** Snapshots, diffs, and audit trails are valuable for a legal matter — implement them in your storage layer, not inside the Markdown.
+- **Storage is the host's choice.** The file may live alongside working files, in a vault as a matter object, or both. Pick what fits your platform; the convention is location-agnostic.
+- **Confirm saves.** Surface real save success/failure to the agent so it does not tell the user the matter is synced when it is not.
+- **Keep it bounded.** The convention targets concise files (~500 lines). Clients should not auto-dump evidence or logs into it; that responsibility stays with the agent's editing discipline.
+
+## Relationship to using-matter-md
+
+This skill defines the format and the client contract. `using-matter-md` defines agent behavior — when to read, what is durable enough to write, and how to edit without bloating the file. Ship both: implement the contract here, load `using-matter-md` (or equivalent guidance) into the agent that operates on the file.

skills/casedev/using-matter-md/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: using-matter-md
+language: en
+description: Operational guidance for working with a MATTER.md durable context file during legal matter work. Use when working inside a legal matter, vault, case file, transaction, litigation, or investigation where a MATTER.md exists or should exist. Covers when to read it, what context is durable enough to write, and how to update it without bloating it. To implement MATTER.md support in a harness, see building-matter-md-clients.
+---
+
+# Using MATTER.md
+
+`MATTER.md` is the durable whiteboard for a legal matter. It tells you what the matter is, who the user represents, how they want it worked, what source rules apply, and what the current durable work state is — so you and future sessions can orient fast.
+
+Treat it as durable project state, **not** as source evidence. Evidence lives in the document system or vault; `MATTER.md` links to it.
+
+## At the start of matter work
+
+1. Locate and read `MATTER.md` before doing matter-specific work.
+2. Use it to orient: representation, goals, jurisdiction, source rules, open questions, current board.
+3. If it is missing and the workspace is clearly tied to a legal matter, create it from the starter template below.
+
+Read and persist `MATTER.md` through your harness's MATTER.md tools if it exposes them, otherwise through ordinary file tools.
+
+## Deciding whether to write
+
+Before editing, ask one question: **will this help a future agent or session orient faster?** If yes, it is durable and belongs. If it is temporary reasoning or raw evidence, keep it out.
+
+**Belongs in MATTER.md** (durable, matter-level):
+
+- what the matter is
+- who the user represents
+- adverse or important non-client parties
+- matter goals and things to avoid
+- jurisdiction, forum, or governing law
+- source rules and citation expectations
+- durable user preferences
+- stable working context and decisions
+- open questions that should survive future sessions
+- a lightweight board for durable tasks
+- short source-map entries that point to documents or vault objects
+
+**Does not belong** (keep it in the source system or discard it):
+
+- full document text, bulk OCR, transcript, or exhibit content
+- chat history or scratchpad reasoning
+- long legal-research dumps
+- every fact extracted from the sources
+- transient task notes
+- sync tokens, credentials, permissions, or storage internals
+
+If the content is evidence, keep it in the document system and link to it. If it is temporary reasoning, leave it out.
+
+## How to update
+
+1. Read the current `MATTER.md` first.
+2. Make the smallest edit that captures the new durable context.
+3. Prefer a short summary plus a source link over copied source text.
+4. When a factual statement comes from a source, include a short source pointer.
+5. Compress or remove stale details if the file is growing.
+6. Keep tables small and readable; preserve existing headings and table shapes unless a simpler structure is clearly better.
+7. Keep the file concise — under ~500 lines. If it grows past that, summarize durable points and replace bulky text with source links.
+
+Source pointers should fit the host environment. Examples:
+
+- `obj_123`
+- `vault:vault_abc/objects/obj_123`
+- `Smith Dep. 45:12-46:3`
+- `Generated memo: damages-summary.md`
+
+## During work
+
+- Use the source system or vault tools for evidence — not `MATTER.md`.
+- Add an **open question** when a missing fact materially affects the matter work.
+- Update the **board** only for tasks that should survive the current session, not for transient to-dos.
+
+## Before finishing
+
+- Save durable changes to `MATTER.md`.
+- Report material `MATTER.md` changes to the user.
+- Do not claim `MATTER.md` is synced or canonical unless the harness confirms the save succeeded.
+
+## Starter template
+
+If `MATTER.md` does not exist, create a concise file like this:
+
+```markdown
+---
+mattermd: "0.1"
+title: ""
+---
+
+# Matter
+
+## What This Is
+
+## Representation
+
+## Goals
+
+## Jurisdiction
+
+## Source Rules
+
+## Working Preferences
+
+## Source Map
+
+| Label | Source | Notes |
+|---|---|---|
+
+## Working State
+
+## Open Questions
+
+| Question | Why It Matters | Status |
+|---|---|---|
+
+## Board
+
+| Status | Task | Notes |
+|---|---|---|
+```
+
+Keep the matter's meaning in the Markdown body, not in YAML. Frontmatter stays small.
+
+## Examples
+
+Good durable update:
+
+```markdown
+## Goals
+
+- Primary: prepare a plaintiff-side damages demand package.
+- Avoid: overclaiming medical causation not supported by the records.
+```
+
+Good source-map entry:
+
+```markdown
+| Police report | obj_123 | Incident narrative and responding officer notes |
+```
+
+Bad update — copying source text bloats the file and hides provenance; link instead:
+
+```markdown
+## Durable Context
+
+[15 pages of copied deposition transcript]
+```
+
+## Troubleshooting
+
+- Missing file: create it only when the workspace is clearly tied to a legal matter.
+- File over ~500 lines: summarize durable points, replace bulky text with source links.
+- Multiple agents editing: prefer small section-level edits and preserve the latest visible user intent.
+- Harness claims sync support: verify the save succeeded before relying on it.