Brainforge Knowledge

cursor-agent-operating-workflow

3 min read

Cursor agent workflow: Operating.app

Date: 2026-04-06
Audience: Cursor agents and delivery team members (Head of Delivery, CSOs, Service Leads) working in brainforge-ai/brainforge-platform

This doc describes how an agent should interact with Operating.app when the task requires it. It does not replace the credential and API reference in Operating MCP + API setup.

1. Surfaces (pick the right one)

SurfaceWhen to use
Operating MCP (operating in .cursor/mcp.json)List/read people, projects, positions, allocations, roles; create/update positions; create/delete allocations. Prefer MCP for these when the server is authenticated in the IDE.
Direct REST API (https://api.operating.app/v1)Create/archive projects, create/update/delete clients, list clients, bulk or unsupported MCP operations. Use op for the API key per the standards doc—never commit secrets.
Web app (https://use.operating.app)Human verification, UI workflows, or when deep links are enough. URL patterns: /projects/{id}, /clients/{id} (SPA; cmd+k if the shell loads without the entity).
Vault markdown onlyCross-linking IDs, Q2 allocation tables, audit narratives—no live call required.

2. MCP usage in Cursor

  1. Confirm the server is enabled and authenticated (Operating may expose an auth flow; follow any mcp_auth pattern for that server if tools fail with auth errors).
  2. Read tool schemas first before calling tools (project rule: inspect MCP descriptor JSON under the Cursor mcps folder for the Operating server when available).
  3. Typical read order: list_roles (resolve CSO/SL role IDs) → list_projects / list_people → list_positions / list_allocations for the slice you care about.
  4. Writes: Use MCP create_position / update_position / create_allocation / delete_allocation when the operation is supported; otherwise drop to REST with curl + API_KEY from 1Password CLI.

Capability matrix and examples: Operating MCP + API setup §5–7.

3. Documenting outcomes in knowledge/

After material changes in Operating (or when confirming state during an audit):

  • Execution / audit trail: Update or append the active delivery plans under knowledge/delivery/plans/active/ (e.g. execution report, allocation updates, executed changes log) so humans have a dated record next to the audit plan in knowledge/executive/plans/planned/.
  • Head-of-delivery planning: Resource allocation summaries live under knowledge/delivery/ (e.g. Q2 continuing-clients doc) with HubSpot, Linear, and Operating links where IDs are known.
  • Skills: Repo-local automation and prompts live under .cursor/skills/ (see operating-audit hub and SL allocation skills); they orchestrate API patterns already documented in standards.

4. Git and repo layout

Operating-related standards live under knowledge/standards/03-knowledge/engineering/setup/ (not legacy standards/ at repo root). If main renames knowledge folders, merge conflicts may appear as “add in renamed directory”—resolve by placing the same file content on the current path on main, then git add to clear conflicts.

5. What counts as “interacting with Operating”

  • Live interaction: MCP tool calls or authenticated curl to api.operating.app that read or mutate data.
  • Indirect interaction: Editing markdown that references Operating project/client IDs and use.operating.app URLs, or shipping those edits via PR—no API call in that step, but still part of the Operating toolchain for humans.

Both are valid; be explicit in execution logs which one occurred.

Graph View

Backlinks