Merge pull request #160 from mex-memory/codex/agent-skills

feat: ship managed MEX agent skills

Author: theDakshJaitly

.agents/skills/mex-inbox/.mex-managed.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "owner": "mex-agent",
+  "skill": "mex-inbox",
+  "packageVersion": "0.7.3",
+  "files": {
+    "SKILL.md": "ec0e61b45c9f2e2d70074bd613c0d294dd4d88ec73964e6187f0ac8d51de1505",
+    "agents/openai.yaml": "4dbdf205a76ba17d9fd8984c8d546b1d6628f0e135bbaf0c16c773f8fa6fc765",
+    "references/cli-workflows.md": "5147aa68c8fea7a96dd5c569c23570238e2a32a46655fd14267e31a7c5d12c30"
+  }
+}

.agents/skills/mex-inbox/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: mex-inbox
+description: Prepare and manage governed MEX Inbox proposals for durable Spec-family knowledge. Use when the user clearly asks to capture, create, save, or draft a MEX product Spec, requirement, constraint, acceptance criterion, or durable product-spec decision for team review, or explicitly invokes /mex-inbox or $mex-inbox. Do not use for email inboxes, generic notes, vague brainstorming, OpenAPI or test specs mentioned only by the word "spec," architecture pages, conventions, patterns, Workstreams, Relays, arbitrary Wiki pages, or generic memory.
+---
+
+# MEX Inbox
+
+Prepare governed Spec-memory proposals. Treat Inbox as a proposal workflow, not email and not a general Wiki mutation system.
+
+## Keep the scope honest
+
+- Create exactly one `spec.create` or `spec.update` change per draft.
+- Support only `spec`, `requirement`, `constraint`, and `acceptance_criterion` entities.
+- Reject unsupported durable knowledge honestly. Do not silently translate architecture, conventions, patterns, Workstreams, Relays, or arbitrary Wiki pages into Specs.
+- Require a clear durable claim. Do not capture unresolved brainstorming as team memory.
+
+## Prepare a draft
+
+1. Distill the durable knowledge, rationale, and useful evidence from the conversation.
+2. Decide whether it creates a new Spec-family entity or updates an existing exact entity.
+3. For an update, resolve the canonical target and current revisions before drafting. Never guess an ID or revision.
+4. Preserve useful files, code, commits, entities, and external links as evidence only when actually available. Never invent provenance, authors, dates, events, or history.
+5. Build one request against the action-scoped runtime contract.
+6. Run the exact preview flow and summarize the human effect before technical details.
+7. When the user already asked to create, save, or draft it, apply that exact successful checkout-local draft preview without asking again.
+8. Return `/inbox?view=drafts&draft=<id>` and state that the draft is checkout-local, nothing was published or shared, and review or publication happens in Hub.
+
+Read [references/cli-workflows.md](references/cli-workflows.md) before executing any Inbox mutation. Load only the operation being performed.
+
+## Apply the approval policy
+
+- Proceed with read-only list, show, and target resolution.
+- Treat an explicit create/save/draft request as authorization only for the local draft preview and exact apply.
+- Preview a local draft deletion, explain that the checkout-local draft will be removed, and obtain fresh confirmation before applying.
+- For publish, approve, reject, withdraw, mark stale, or repair: create a semantic preview, explain the local-versus-Git-tracked effect, and wait for fresh explicit confirmation. Apply the exact preview unchanged only after confirmation.
+- Keep Git commit, push, pull, and staging separate from every MEX authorization.
+- Never approve or publish merely because this skill activated.
+
+## Report effects precisely
+
+- Lead with what the proposal means to a person. Do not expose envelopes, hashes, revision machinery, or raw diffs unless diagnosis requires them.
+- After a local draft write, say exactly what changed and that it remains checkout-only.
+- After a canonical write, say which Git-tracked MEX artifacts were written to the working tree and that commit/push is still required to share them. Never claim that MEX committed or pushed.
+- When MEX context materially affects the answer, add one concise acknowledgement: `MEX context used: <specific records/files/entities consulted>.`

.agents/skills/mex-inbox/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "MEX Inbox"
+  short_description: "Draft governed MEX Spec proposals"
+  default_prompt: "Use $mex-inbox to draft this durable requirement for MEX team review."

.agents/skills/mex-inbox/references/cli-workflows.md

@@ -0,0 +1,76 @@
+# Inbox CLI workflows
+
+Use JSON mode for deterministic agent work. Keep request and preview files temporary and avoid displaying them unless troubleshooting.
+
+## Resolve only the needed contract
+
+Run:
+
+```text
+mex inbox contract --action <command-id> --json
+```
+
+Use one of these command IDs:
+
+- `inbox.draft.save`
+- `inbox.draft.delete`
+- `inbox.publish`
+- `inbox.proposal.approve`
+- `inbox.proposal.reject`
+- `inbox.proposal.withdraw`
+- `inbox.proposal.mark-stale`
+- `inbox.proposal.repair`
+
+Treat this bounded action result as the exact runtime source for the request shape, available examples, constraints, preview command, and apply command. Do not dump `mex capabilities --json` or the full Inbox contract during ordinary execution. Write request and preview JSON only to ordinary regular files inside the checkout or an approved temporary directory; do not use symlinks.
+
+## Resolve a Spec update
+
+1. Use `mex spec list --json` to identify candidates.
+2. Use `mex spec show <entity-id> --json` for the exact candidate.
+3. Match the requested durable claim to one exact entity and kind.
+4. Copy `version.contentHash` as the entity revision and `version.semanticRevision` as the semantic revision exactly as the selected contract requires. For nested requirements, constraints, or acceptance criteria, take both from the enclosing `mex spec show` projection.
+5. Stop and ask for target clarification when multiple candidates remain plausible.
+
+Do not invent target IDs, relation endpoints, topic IDs, or revisions. For a create request with relations or topics, resolve every referenced entity and its current revisions first.
+
+## Save a checkout-local draft
+
+1. Resolve `inbox.draft.save`.
+2. Create a unique operation ID and a request containing one `spec.create` or `spec.update` draft.
+3. For a new draft, provide no unrelated expectations. For an existing draft update, read it with `mex inbox draft show <draft-id> --json` and use its exact current local revision.
+4. Preview with `mex inbox draft save <request-file> --json` and capture the complete successful JSON wrapper unchanged. Require `ok: true`, `mode: "preview"`, and `data.preview.valid: true`.
+5. Summarize the proposed local effect. If the user asked to create/save/draft, apply with `mex inbox draft save --apply <preview-envelope> --json` without another confirmation.
+6. Read the returned draft ID and respond with `/inbox?view=drafts&draft=<id>`.
+
+The apply writes only checkout-local draft state. It does not create a canonical proposal, Activity record, commit, push, or notification. Apply before the preview expires; if anything changes or the preview becomes stale, preview again instead of reconstructing it.
+
+## Delete a local draft
+
+1. Read the exact draft and current local revision.
+2. Resolve and preview `inbox.draft.delete`.
+3. Explain that the checkout-local draft will be deleted and wait for fresh confirmation.
+4. Apply the captured preview unchanged with `mex inbox draft delete --apply <preview-envelope> --json`.
+
+## Publish a draft
+
+1. Read the exact draft and resolve `inbox.publish`.
+2. Build the request with the exact local draft revision and preview using `mex inbox publish <request-file> --json`.
+3. Explain that applying writes a canonical proposal and Activity artifact into the working tree while leaving Git commit/push separate.
+4. Wait for fresh explicit confirmation.
+5. Apply the exact preview with `mex inbox publish --apply <preview-envelope> --json`.
+6. Return `/inbox?view=review&proposal=<proposal-id>`.
+
+Publishing removes the exact local draft after creating the pending proposal. It does not approve the proposal or write the requested Spec change.
+
+## Review canonical proposals
+
+Use `mex inbox proposal list --json` and `mex inbox proposal show <proposal-id> --json` for read-only review. For approve, reject, withdraw, mark-stale, or repair:
+
+1. Resolve the matching command ID.
+2. Use the proposal's exact current artifact revision and any action-specific rationale or replacement draft.
+3. Preview with the corresponding `mex inbox proposal <action> <request-file> --json` command.
+4. Explain the semantic outcome and which canonical Git-tracked MEX records would change.
+5. Wait for fresh explicit confirmation.
+6. Apply the exact preview with the same command plus `--apply <preview-envelope> --json`.
+
+Approval writes the proposed Spec-family entity change, proposal decision, Wiki ledger, and Activity records to the working tree. Reject and withdraw make a terminal proposal decision without changing the Spec. Mark stale changes a pending proposal to stale only when MEX proves dependency drift. Repair replaces stale intent, clears prior review, and returns the proposal to pending without changing the Spec. These canonical transitions write Activity records; none commits, pushes, pulls, stages, or notifies teammates.

.agents/skills/mex-relay/.mex-managed.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "owner": "mex-agent",
+  "skill": "mex-relay",
+  "packageVersion": "0.7.3",
+  "files": {
+    "SKILL.md": "70fa6eb782225f6357b0046ea9449e80095e6c01bc5e960886a2f60fad7e3f25",
+    "agents/openai.yaml": "9c2e9c2e34d60ec0f4d07089b07d9e49a6c8210c2a3e277593c15a2635f03076",
+    "references/cli-workflows.md": "98be305e6d941acdd5caa7697317c963343bb62ddcc25af8e129d0af1ea0aaa8"
+  }
+}

.agents/skills/mex-relay/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: mex-relay
+description: Prepare and manage durable MEX team handoffs. Use when the user asks to hand work to a person or team, prepare an end-of-session handoff, save what the next engineer needs, create a MEX Relay, take or close a Relay, or explicitly invokes /mex-relay or $mex-relay. Treat Relay as a memory and context baton, not chat, notifications, task assignment, issue tracking, or a Jira replacement; do not activate for ordinary status messages that are not durable handoffs.
+---
+
+# MEX Relay
+
+Prepare durable team handoffs that another engineer can continue from. Never represent a Relay as a sent message or notification.
+
+## Prepare a Relay draft
+
+1. Infer the useful session state: a concise summary, current position, completed work, in-progress work, blockers, unresolved questions, next actions, and relevant decisions, files, code, commits, or external links.
+2. Resolve intended recipients against active MEX Members. Never fabricate member IDs.
+3. Default to a standalone Relay.
+4. Include a Workstream only when a real, relevant Workstream already exists. Preserve it as supported typed context; never invent one or turn Relay creation into Workstream creation.
+5. Add optional typed context references only when the referenced IDs, paths, commits, or URLs are known. Never invent provenance.
+6. Build one request against the action-scoped runtime contract and run the exact preview.
+7. When the user already asked to create, save, or draft the handoff, apply that exact checkout-local draft preview without another confirmation.
+8. Return `/relays?view=drafts&draft=<id>` and state that the draft is checkout-local and nothing has been delivered or shared.
+
+Read [references/cli-workflows.md](references/cli-workflows.md) before executing any Relay mutation. Load only the operation being performed.
+
+## Apply the approval policy
+
+- Proceed with read-only member, Workstream, draft, and Relay resolution.
+- Treat an explicit create/save/draft request as authorization only for the local draft preview and exact apply.
+- Preview a local draft deletion, explain its consequence, and obtain fresh confirmation before applying.
+- For publish, take, or close: generate a semantic preview, explain the local-versus-Git-tracked effect, and wait for fresh explicit confirmation. Apply the exact preview unchanged only after confirmation.
+- Keep Git commit, push, pull, and staging separate from every MEX authorization.
+- Never publish, take, or close merely because this skill activated.
+
+## Preserve lifecycle meaning
+
+- Treat taking as the explicit canonical acknowledge action by an intended recipient.
+- Treat closing as “this handoff no longer needs attention.” Do not claim it completes a linked task, issue, pull request, or Workstream.
+- After publication, say that Git-tracked Relay and Activity records were written to the working tree. Explain that teammates receive them only after commit/push and their own pull or refresh.
+- Never claim that MEX sent a notification, committed, pushed, pulled, staged, assigned work, or completed another system's object.
+- When MEX context materially affects the answer, add one concise acknowledgement: `MEX context used: <specific records/files/entities consulted>.`

.agents/skills/mex-relay/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "MEX Relay"
+  short_description: "Prepare durable MEX team handoffs"
+  default_prompt: "Use $mex-relay to prepare a durable handoff for the next engineer."

.agents/skills/mex-relay/references/cli-workflows.md

@@ -0,0 +1,77 @@
+# Relay CLI workflows
+
+Use JSON mode for deterministic agent work. Keep request and preview files temporary and avoid displaying them unless troubleshooting.
+
+## Resolve only the needed contract
+
+Run:
+
+```text
+mex relay contract --action <command-id> --json
+```
+
+Use one of these command IDs:
+
+- `relay.draft.save`
+- `relay.draft.delete`
+- `relay.publish`
+- `relay.acknowledge`
+- `relay.close`
+
+Treat this bounded action result as the exact runtime source for the request shape, available examples, constraints, preview command, and apply command. Do not dump `mex capabilities --json` or the full Relay contract during ordinary execution. Write request and preview JSON only to ordinary regular files inside the checkout or an approved temporary directory; do not use symlinks.
+
+## Resolve recipients and optional context
+
+1. Run `mex member list --active --limit 100 --json`, following bounded cursors when present, and match the user's names or team intent to active Members.
+2. Use `mex member show <member-id> --json` when a candidate needs disambiguation or a current artifact revision is required.
+3. Stop and ask for recipient clarification when multiple active Members remain plausible, no active Member matches, or bounded results cannot prove uniqueness. Relay stores individual Members, so never fabricate a group for “the backend team.”
+4. Default to no Workstream lookup. If the user named a Workstream or the handoff clearly belongs to an existing one, run `mex workstream list --json` and `mex workstream show <workstream-id> --json` to resolve it exactly.
+5. In Relay v3, preserve a relevant Workstream as typed entity evidence when the selected contract supports it; do not author the legacy top-level Workstream field.
+
+Never fabricate recipient IDs, entity IDs, revisions, commits, code fingerprints, paths, URLs, or provenance.
+
+## Save a checkout-local draft
+
+1. Resolve `relay.draft.save`.
+2. Create a unique operation ID and a standalone draft with active recipient references and a concise summary.
+3. Include only useful non-empty context sections. Prefer accurate omissions over invented completeness.
+4. For a new draft, provide no unrelated expectations. For an existing draft update, read it with `mex relay draft show <draft-id> --json` and use its exact local revision.
+5. Preview with `mex relay draft save <request-file> --json` and capture the complete successful JSON wrapper unchanged. Require `ok: true`, `mode: "preview"`, and `data.preview.valid: true`.
+6. Summarize recipients and continuation state. If the user asked to create/save/draft, apply with `mex relay draft save --apply <preview-envelope> --json` without another confirmation.
+7. Read the returned draft ID and respond with `/relays?view=drafts&draft=<id>`.
+
+The apply writes only checkout-local draft state in `.mex/local/team.db`. It does not create a canonical Relay or Activity record, deliver a handoff, commit, push, or notify anyone. Apply before the preview expires; if anything changes or the preview becomes stale, preview again instead of reconstructing it.
+
+## Delete a local draft
+
+1. Read the exact draft and current local revision.
+2. Resolve and preview `relay.draft.delete`.
+3. Explain that the checkout-local draft will be deleted and wait for fresh confirmation.
+4. Apply the captured preview unchanged with `mex relay draft delete --apply <preview-envelope> --json`.
+
+## Publish a Relay
+
+1. Read the exact draft and every active recipient Member required by the selected contract.
+2. Resolve `relay.publish`, build exact draft/member expectations, and preview with `mex relay publish <request-file> --json`.
+3. Explain that applying replaces the private local draft with canonical Git-tracked Relay and Activity records in the working tree, records the service-observed branch/HEAD/dirty repository state without copying dirty source contents, and does not deliver through a notification service or share before Git commit/push and teammate pull/refresh.
+4. Wait for fresh explicit confirmation.
+5. Apply the exact preview with `mex relay publish --apply <preview-envelope> --json`.
+6. Return `/relays?view=sent&state=open&relay=<relay-id>`.
+
+## Take a Relay
+
+1. Resolve the exact published Relay with `mex relay show <relay-id> --json` and verify that the current actor is an intended active recipient.
+2. Resolve `relay.acknowledge` and preview with `mex relay acknowledge <request-file> --json`.
+3. Explain that applying makes the current recipient the sole claimant, prevents another recipient from taking it, and writes canonical Relay/Activity state in the working tree. There is no unclaim or reassignment action, and it does not assign or start a task elsewhere.
+4. Wait for fresh explicit confirmation, then apply the exact preview with `mex relay acknowledge --apply <preview-envelope> --json`.
+5. Return `/relays?view=mine&state=open&relay=<relay-id>`.
+
+## Close a Relay
+
+1. Resolve the exact acknowledged Relay and its current revision.
+2. Resolve `relay.close` and preview with `mex relay close <request-file> --json`.
+3. Explain that applying irreversibly marks only the handoff as no longer needing attention and writes canonical Relay/Activity state in the working tree.
+4. Wait for fresh explicit confirmation, then apply the exact preview with `mex relay close --apply <preview-envelope> --json`.
+5. Return `/relays?view=all&state=closed&relay=<relay-id>`.
+
+Closing does not complete a linked task, issue, pull request, or Workstream. No lifecycle command stages, commits, pushes, pulls, or sends a notification.

.claude/skills/mex-inbox/.mex-managed.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "owner": "mex-agent",
+  "skill": "mex-inbox",
+  "packageVersion": "0.7.3",
+  "files": {
+    "SKILL.md": "ec0e61b45c9f2e2d70074bd613c0d294dd4d88ec73964e6187f0ac8d51de1505",
+    "agents/openai.yaml": "4dbdf205a76ba17d9fd8984c8d546b1d6628f0e135bbaf0c16c773f8fa6fc765",
+    "references/cli-workflows.md": "5147aa68c8fea7a96dd5c569c23570238e2a32a46655fd14267e31a7c5d12c30"
+  }
+}