From 241da5f33722ca0a423a37eff59e64c5261616ec Mon Sep 17 00:00:00 2001 From: Max Sonderby Date: Mon, 8 Jun 2026 00:39:32 -0700 Subject: [PATCH 1/2] Add MATTER.md management skill --- README.md | 1 + skills/casedev/managing-matter-md/SKILL.md | 193 +++++++++++++++++++++ 2 files changed, 194 insertions(+) create mode 100644 skills/casedev/managing-matter-md/SKILL.md diff --git a/README.md b/README.md index f320b072..4da8a325 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,7 @@ 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 | +| [managing-matter-md](skills/casedev/managing-matter-md/) | MATTER.md durable legal matter context files: read, maintain, update, and implement | ### Legal Skills diff --git a/skills/casedev/managing-matter-md/SKILL.md b/skills/casedev/managing-matter-md/SKILL.md new file mode 100644 index 00000000..3b6c8ab0 --- /dev/null +++ b/skills/casedev/managing-matter-md/SKILL.md @@ -0,0 +1,193 @@ +--- +name: managing-matter-md +language: en +description: Helps agents read, maintain, and implement MATTER.md legal matter context files. Use when working in a legal matter, vault, case file, transaction, litigation, investigation, or legal workspace where durable context should survive across agent sessions. +--- + +# Managing MATTER.md + +`MATTER.md` is the durable matter whiteboard for legal agents. + +Use it to understand what the matter is, how the user wants it worked, what source rules apply, what context should survive future sessions, and what the current durable work state is. + +## Core Rules + +- Read `MATTER.md` before doing matter-specific work. +- Treat it as durable project state, not as source evidence. +- Update it only when the information should survive future sessions. +- Keep it concise. As a rule of thumb, keep `MATTER.md` under 500 lines. +- Link to source documents, vault objects, or generated artifacts instead of copying long excerpts. +- Preserve existing section headings and table shapes unless a simpler structure is clearly better. +- Do not store full source text, chat transcripts, long research notes, every extracted fact, or implementation-specific sync metadata. + +## What Belongs In MATTER.md + +Durable matter-level context belongs in `MATTER.md`: + +- 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 + +## What Does Not Belong + +Do not add: + +- full document text +- bulk OCR, transcript, or exhibit content +- chat history +- 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, keep it out of `MATTER.md`. + +## 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 | +|---|---|---| +``` + +Frontmatter is optional except when the host platform needs a mechanical handle. Keep it small. Put matter meaning in the Markdown body, not in YAML. + +## Updating MATTER.md + +Before editing, decide whether the change is durable. A good update helps a future agent or future session orient faster. + +When updating: + +1. Read the current `MATTER.md`. +2. Make the smallest edit that preserves the new durable context. +3. Prefer summary plus source link over copied source text. +4. Remove or compress stale details if the file is growing. +5. Keep tables small and readable. +6. If a factual statement comes from a source, include a short source pointer when available. + +Use source pointers that fit the host environment. Examples: + +- `obj_123` +- `vault:vault_abc/objects/obj_123` +- `Smith Dep. 45:12-46:3` +- `Generated memo: damages-summary.md` + +## Agent Behavior + +At the start of matter work: + +1. Locate and read `MATTER.md` if present. +2. Use it to orient to the matter, representation, goals, source rules, open questions, and current board. +3. If it is missing and the workspace is clearly matter-scoped, create it from the starter template. + +During work: + +- Use the source system or vault tools for evidence. +- Use `MATTER.md` for stable context and coordination. +- Add open questions when a missing fact affects the matter work. +- Update the board only for tasks that should survive the current session. + +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 host platform confirms that. + +## Implementing MATTER.md Support + +Host platforms should keep transport separate from the file convention. + +A minimal implementation: + +1. Discover `MATTER.md` in the matter workspace. +2. Load it after global agent instructions and before matter task execution. +3. Preserve it across context compaction. +4. Let the agent read and update the file through ordinary file tools or a small dedicated tool. +5. Persist the edited file using the host platform's storage layer. + +Recommended tool surface: + +- `matter_md_read`: return the current `MATTER.md`. +- `matter_md_save`: persist the current file. +- `matter_md_update_section`: replace one named section. +- `matter_md_append_open_question`: append a durable open question. +- `matter_md_upsert_board_item`: add or update a durable board item. + +Do not require a database, schema registry, CRDT, or sync protocol to support `MATTER.md`. Version history is useful, but it belongs to the host platform, not the file format. + +## 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: + +```markdown +## Durable Context + +[15 pages of copied deposition transcript] +``` + +Copying source text bloats the file and hides provenance. Link to the source instead. + +## Troubleshooting + +- If `MATTER.md` is missing, create it only when the workspace is clearly tied to a legal matter. +- If the file is longer than 500 lines, summarize durable points and replace bulky text with source links. +- If a host platform claims sync support, verify save behavior before relying on it. +- If multiple agents edit the file, prefer small section-level edits and preserve the latest visible user intent. From 0409d1af936c2f226a4d707be66f365ebd00cd9e Mon Sep 17 00:00:00 2001 From: Max Sonderby Date: Mon, 8 Jun 2026 01:31:07 -0700 Subject: [PATCH 2/2] Split MATTER.md skill into using + building-clients MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace managing-matter-md with two skills targeting distinct audiences: - using-matter-md: operational guidance for an agent doing matter work — when to read MATTER.md, what context is durable enough to write, how to edit without bloating it. - building-matter-md-clients: the convention/spec for harnesses adding MATTER.md support — discovery (MATTER.md at vault root), load lifecycle, client-owned conflict resolution. Keeps the convention loose: body is freeform Markdown, sections are illustrative not normative, edits go through plain file tools. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 3 +- .../building-matter-md-clients/SKILL.md | 62 ++++++ skills/casedev/managing-matter-md/SKILL.md | 193 ------------------ skills/casedev/using-matter-md/SKILL.md | 153 ++++++++++++++ 4 files changed, 217 insertions(+), 194 deletions(-) create mode 100644 skills/casedev/building-matter-md-clients/SKILL.md delete mode 100644 skills/casedev/managing-matter-md/SKILL.md create mode 100644 skills/casedev/using-matter-md/SKILL.md diff --git a/README.md b/README.md index 4da8a325..231c1eef 100644 --- a/README.md +++ b/README.md @@ -46,7 +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 | -| [managing-matter-md](skills/casedev/managing-matter-md/) | MATTER.md durable legal matter context files: read, maintain, update, and implement | +| [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/managing-matter-md/SKILL.md b/skills/casedev/managing-matter-md/SKILL.md deleted file mode 100644 index 3b6c8ab0..00000000 --- a/skills/casedev/managing-matter-md/SKILL.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -name: managing-matter-md -language: en -description: Helps agents read, maintain, and implement MATTER.md legal matter context files. Use when working in a legal matter, vault, case file, transaction, litigation, investigation, or legal workspace where durable context should survive across agent sessions. ---- - -# Managing MATTER.md - -`MATTER.md` is the durable matter whiteboard for legal agents. - -Use it to understand what the matter is, how the user wants it worked, what source rules apply, what context should survive future sessions, and what the current durable work state is. - -## Core Rules - -- Read `MATTER.md` before doing matter-specific work. -- Treat it as durable project state, not as source evidence. -- Update it only when the information should survive future sessions. -- Keep it concise. As a rule of thumb, keep `MATTER.md` under 500 lines. -- Link to source documents, vault objects, or generated artifacts instead of copying long excerpts. -- Preserve existing section headings and table shapes unless a simpler structure is clearly better. -- Do not store full source text, chat transcripts, long research notes, every extracted fact, or implementation-specific sync metadata. - -## What Belongs In MATTER.md - -Durable matter-level context belongs in `MATTER.md`: - -- 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 - -## What Does Not Belong - -Do not add: - -- full document text -- bulk OCR, transcript, or exhibit content -- chat history -- 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, keep it out of `MATTER.md`. - -## 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 | -|---|---|---| -``` - -Frontmatter is optional except when the host platform needs a mechanical handle. Keep it small. Put matter meaning in the Markdown body, not in YAML. - -## Updating MATTER.md - -Before editing, decide whether the change is durable. A good update helps a future agent or future session orient faster. - -When updating: - -1. Read the current `MATTER.md`. -2. Make the smallest edit that preserves the new durable context. -3. Prefer summary plus source link over copied source text. -4. Remove or compress stale details if the file is growing. -5. Keep tables small and readable. -6. If a factual statement comes from a source, include a short source pointer when available. - -Use source pointers that fit the host environment. Examples: - -- `obj_123` -- `vault:vault_abc/objects/obj_123` -- `Smith Dep. 45:12-46:3` -- `Generated memo: damages-summary.md` - -## Agent Behavior - -At the start of matter work: - -1. Locate and read `MATTER.md` if present. -2. Use it to orient to the matter, representation, goals, source rules, open questions, and current board. -3. If it is missing and the workspace is clearly matter-scoped, create it from the starter template. - -During work: - -- Use the source system or vault tools for evidence. -- Use `MATTER.md` for stable context and coordination. -- Add open questions when a missing fact affects the matter work. -- Update the board only for tasks that should survive the current session. - -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 host platform confirms that. - -## Implementing MATTER.md Support - -Host platforms should keep transport separate from the file convention. - -A minimal implementation: - -1. Discover `MATTER.md` in the matter workspace. -2. Load it after global agent instructions and before matter task execution. -3. Preserve it across context compaction. -4. Let the agent read and update the file through ordinary file tools or a small dedicated tool. -5. Persist the edited file using the host platform's storage layer. - -Recommended tool surface: - -- `matter_md_read`: return the current `MATTER.md`. -- `matter_md_save`: persist the current file. -- `matter_md_update_section`: replace one named section. -- `matter_md_append_open_question`: append a durable open question. -- `matter_md_upsert_board_item`: add or update a durable board item. - -Do not require a database, schema registry, CRDT, or sync protocol to support `MATTER.md`. Version history is useful, but it belongs to the host platform, not the file format. - -## 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: - -```markdown -## Durable Context - -[15 pages of copied deposition transcript] -``` - -Copying source text bloats the file and hides provenance. Link to the source instead. - -## Troubleshooting - -- If `MATTER.md` is missing, create it only when the workspace is clearly tied to a legal matter. -- If the file is longer than 500 lines, summarize durable points and replace bulky text with source links. -- If a host platform claims sync support, verify save behavior before relying on it. -- If multiple agents edit the file, prefer small section-level edits and preserve the latest visible user intent. 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.