Developer Docs

Agent Patterns

Common REST and MCP workflows for external agents.

Project Status Briefing

Use MCP when the caller is an agent:

  1. get_project
  2. get_project_readiness_rollup
  3. get_project_workstreams
  4. calendar.list_events
  5. get_project_economics when the key has PM/admin scope

Return links back to the app instead of duplicating editable UI.

QA Extension And Site Review

Use REST for browser extension runtime calls:

  1. GET /api/qa-extension/client-bootstrap
  2. GET /api/projects/{id}/qa-config
  3. POST /api/projects/{id}/qa-items

Use willa-qa-extension or a scoped user key. Keep screenshots and attachment uploads out of prompt context unless the workflow explicitly needs visual analysis.

Meeting Notes Ingestion

Use REST or MCP depending on source:

  • Slack slash command or external transcript tool: POST /api/meeting-transcripts
  • Agent tool call: meeting_transcript.ingest

Store plaintext transcripts as documents and extract structured actions/decisions through the shared ingestion helper.

Shopify App Coordination

Use:

  • GET /api/shopify/app-bootstrap
  • GET /api/shopify/store-snapshots
  • POST /api/shopify/staged-actions
  • MCP shopify_staged_action_create

Staged actions are submitted for Willa approval. Agents should not execute irreversible Shopify writes directly.

Figma Section Ledger

Use:

  • GET /api/figma/projects/resolve
  • POST /api/figma/section-ledgers
  • POST /api/figma/section-ledgers/{id}/events
  • MCP list_figma_section_ledgers
  • MCP get_figma_comment_mirror

Agents should preserve the distinction between internal and client Figma files.