diff --git a/README.md b/README.md index f320b072..231c1eef 100644 --- a/README.md +++ b/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 diff --git a/skills/casedev/building-matter-md-clients/SKILL.md b/skills/casedev/building-matter-md-clients/SKILL.md new file mode 100644 index 00000000..f65050a6 --- /dev/null +++ b/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. diff --git a/skills/casedev/using-matter-md/SKILL.md b/skills/casedev/using-matter-md/SKILL.md new file mode 100644 index 00000000..d89fecaa --- /dev/null +++ b/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.