Manage · Engagements

Run a customer engagement in its own scope

One customer, one container, one scope. An engagement records who the customer is, what vertical they are in, where it sits in its lifecycle, and which slice of RepoOps it can see. Scoping reuses the isolation primitives already in the product: a brain slice filter, a per-client budget id, and an MCP tenant id. It does not add a new isolation mechanism.

Where to find it

  • Desktop: http://localhost:4000/, then Manage → Engagements in the sidebar.
  • Hosted: desktop-only. The repoops.ai sidebar carries an “On the desktop app” pointer for it.
  • Keyboard: ⌘ K, then type “Engagements”.
  • API: GET /api/engagements, POST /api/engagements, PATCH /api/engagements/<id>

Create one

Post a customerLabel, and optionally a vertical and a scope. A new engagement opens with status open.

  • Scope holds three fields, all optional: brainSliceFilter, budgetClientId, tenantId.
  • Passing template as finserv, healthcare, or defense seeds the vertical, a scope preset, and a starter discovery skeleton. Everything it seeds stays editable, and an explicit vertical or scope in the body wins over the template.
  • GET /api/engagements/templates lists the three templates.

The lifecycle

An engagement holds one of three statuses: open, handed-off when you hand the customer back to the account team, and archived when it is closed out. PATCH /api/engagements/<id> moves the status, edits the scope, or both, and it needs at least one of the two.

  • You can move between the three states in any order.
  • An archived engagement is read-only: a scope edit on one is refused with a 409.
  • The list excludes archived engagements unless you ask for them with ?includeArchived=1 or ?status=archived.

Capture what you learned

Discovery records the four things that decide whether an engagement succeeds: constraints, signoff, goodEnough, and willNotBuild. Post them to /api/engagements/<id>/discovery and RepoOps folds a markdown twin into the engagement's brain slice.

  • GET /api/engagements/discovery-templates returns the starter questions that get you to those four fields, merged per vertical.
  • GET /api/engagements/discovery-search?q= ranks captured discoveries across every engagement, archived included, so you can ask what constraints you have already hit in a vertical. Each hit names the engagement and the field it matched.

Scoped MCP for a deployed agent

GET /api/engagements/<id>/mcp?repo=<id> emits an MCP server config limited to that engagement's brain slice, so an agent you deploy for a customer sees only that customer's files. It fails closed: an engagement with no brainSliceFilter yields an empty corpus, never the whole brain.

Export, hand off, and close out

  • GET /api/engagements/<id>/export returns the engagement plus its scoped slice manifest as JSON.
  • GET /api/engagements/<id>/handoff renders the compliance-and-handoff pack as markdown and HTML: attestation trail, audit ledger, redaction posture, eval pass-rates, and brain slice. Add ?repo= to join the attestation and eval data.
  • GET /api/engagements/<id>/postmortem renders the post-mortem: the workflow before, the constraints, what you did not build, what broke in week two, and the measured after. Every dollar figure traces to a linked outcome, and none is estimated. ?unit=hours&rate= speaks in hours at a rate you state.
  • GET /api/engagements/<id>/postmortem/onepager renders the same data as a self-contained branded HTML one-pager for the customer.

Share a post-mortem read-only

POST /api/engagements/<id>/postmortem/share freezes the rendered artifact (markdown, figures, brand, unit) into a snapshot behind a non-guessable token and returns a URL. The public render at /api/postmortem-share/<token> takes no auth: the token is the capability. Revoke with DELETE /api/engagements/<id>/postmortem/share/<token>, after which the link stops working. List the live links with GET /api/engagements/<id>/postmortem/shares.

Where it is stored

One append-only JSONL file at <dataDir>/engagements/engagements.jsonl. A status change appends a line rather than rewriting the file, and a read folds the lines into the latest state per engagement. Unlike the high-volume event stores, this reads the whole file rather than a bounded month window, so an engagement you opened months ago still resurfaces. The directory honors REPO_DASHBOARD_DATA_DIR.

Read more