---
name: operate-from-customer-context
description: Build and execute evidence-backed business workflows with CrowdListen. Use when an agent must research customer or market signals, recall how a company operates, turn approved Codex or Claude work into durable entity context, derive an Action, or prepare completed workflows for explicitly approved internal or external harness training.
---

# Operate from Customer Context

Use CrowdListen as the reasoning layer between company evidence and an execution agent. Keep sources, durable understanding, and execution plans distinct.

## Core loop

1. Scope the entity and business decision.
2. Recall existing evidence, insights, and Actions.
3. Fill only material evidence gaps.
4. Ingest approved evidence with provenance.
5. Wait for enrichment, then recall the resulting insight or Action.
6. Execute through the user's chosen agent or business tool with appropriate consent.
7. Capture the outcome so the next run starts from learned context.

## Scope before searching

Identify:

- the CrowdListen entity and workspace;
- the decision or workflow being improved;
- whether the evidence is public, internal, or customer-confidential;
- the minimum sources needed to answer the decision;
- who may approve an external side effect or portable training use.

Use `recall({ mode: "entities" })` when the entity ID is unknown. Never mix evidence across entities or workspaces.

## Recall before acquiring

Check the compounding layer before starting new research:

```js
recall({ mode: "insights", entity_id: "...", include_evidence: true })
recall({ mode: "actions", entity_id: "..." })
recall({ mode: "content", entity_id: "...", query: "the decision topic" })
```

Reuse sufficiently recent, well-proven context. Research again when evidence is stale, thin, contradictory, or missing for a material segment.

## Acquire missing evidence

For public customer and market evidence, run live research:

```js
analyze({
  question: "What evidence would change this decision?",
  entity_id: "...",
  search_mode: "multi_source",
  platforms: ["reddit", "youtube", "hackernews", "web"],
  depth: "deep"
})
```

For a durable entity run, prefer:

```js
const started = analyze({
  action: "start",
  question: "What evidence would change this decision?",
  entity_id: "...",
  platforms: ["reddit", "youtube", "hackernews", "web"],
  depth: "deep"
})
analyze({ action: "status", job_id: started.job_id })
```

Poll with bounded retries until `completed`, `partial`, or `failed`. A completed result includes the canonical ingestion and enrichment summary; a queued response is not evidence that insights or Actions exist yet.

Treat provider failures, sampled coverage, and missing dates as limitations. Do not convert an empty or partial run into a confident business conclusion.

For internal evidence available to the host agent—such as an approved Slack thread, Granola note, support conversation, or code-agent result—normalize it through `ingest` instead of leaving it only in the chat.

## Add evidence to the compounding layer

Use `destination: "evidence"` only for source material that may influence entity insights and Actions:

```js
ingest({
  destination: "evidence",
  entity_id: "...",
  title: "Renewal escalation decision",
  content: "The approved source text or bounded workflow outcome",
  source_platform: "codex",
  source_url: "codex://session/stable-trace-id",
  author: "Codex",
  published_at: "2026-08-02T00:00:00Z",
  metadata: {
    task: "triage renewal risk",
    outcome: "approved",
    sensitivity: "internal",
    evidence_scope: "selected excerpt"
  }
})
```

Include stable provenance, time, executor or author, approval state, and sensitivity. Prefer the smallest sufficient excerpt. Do not ingest whole private conversations, secrets, credentials, unrelated personal data, or unapproved drafts.

Supported evidence origins are `agent`, `codex`, `claude_code`, `slack`, `granola`, and `web`. Use a stable URI when no web URL exists, such as `claude-code://session/<trace-id>`.

The evidence call writes to `content_store`, runs the entity's canonical sweep with a stable idempotency key, and returns the persisted terminal sweep result. Require `enrichment.status: "ok"` and `enrichment.results[0].status: "completed"` before treating extraction or Action materialization as complete. Use the returned `collection_run_id` and `run_id` as the audit trail, then confirm the expected Insight or Action with `recall`.

Use ordinary `ingest({ title, content, path, tags, project_id })` for curated instructions and briefs that should remain authored context rather than raw evidence. Put provenance inside the authored document when it matters; context saves do not persist the evidence metadata fields.

## Convert understanding into execution

After enrichment is triggered, recall the entity's insights and Actions. Enrichment may automatically materialize an Action. The MCP surface cannot currently create an arbitrary Action; use the signed-in Insight detail's `Create action` control or the authenticated Actions API when an editor needs a user-defined workflow.

An Action is execution-ready only when it has:

- direct source evidence;
- a bounded objective;
- ordered steps;
- an owner and timeframe;
- a measurable success criterion;
- explicit assumptions and confidence;
- planning projections labeled as estimates, not measured outcomes.

Use the saved Action plan or its prompt handoff as input for Codex, Claude Code, or another executor. CrowdListen does not expose a generic `execute` MCP tool. The host agent performs the approved steps with its own tools. Require human confirmation before sending messages, changing CRM records, publishing content, modifying production, or making another external side effect.

Before execution, create the audit record through the existing `ingest` tool:

```js
const execution = ingest({
  destination: "execution",
  action_id: "...",
  executor_platform: "codex",
  approved_for_execution: true,
  steps: ["The exact approved step", "The next bounded step"]
})
```

Creation fails unless approval is explicitly `true`. Persist the returned execution ID before the host performs a side effect.

## Capture the result

After execution, update the same record rather than leaving the result only in chat:

```js
ingest({
  destination: "execution",
  execution_id: execution.execution.id,
  execution_status: "completed",
  step_results: [{ step: "The exact approved step", status: "completed", result: "Bounded result" }],
  outcome_summary: "The observable result, including what did not happen",
  metrics: { measured_count: 12 },
  review_status: "pending"
})
```

The bounded execution record should contain:

- what was attempted;
- which approved workflow was used;
- the observable result;
- exceptions or corrections;
- whether the result was reviewed;
- the next decision date.

Do not label a plan successful merely because its steps were completed. Distinguish execution completion from measured business outcome.

## Create reusable skills and training examples

Promote a workflow plan only after it is completed, reviewed, and explicitly approved for portability. Use `buildActionTrainingExport` and `serializeActionTrainingExamples` from `@crowdlisten/harness/dist/action-training-export.js` with a workspace-owner-approved Action ID allowlist.

For outcome-aware examples, first have a workspace owner update the completed execution to `review_status: "approved"` with one or more persisted `training_scopes`. Then use `buildReviewedExecutionTrainingExport` and `serializeReviewedExecutionTrainingExamples` with the same requested scope and an explicit execution-ID allowlist. See `docs/ACTION_TRAINING_EXPORT.md` in the package. The converter uses only bounded steps, step results, outcome summary, and numeric/boolean metrics; it excludes raw evidence, URLs, identity fields, secret fields, and raw tool traces.

Persisted scope and caller approval are separate gates: the execution record says which use is approved, while the local allowlist says which exact records this export invocation may include. Both must pass.

Keep separate approval scopes for:

- internal skill reuse inside the same workspace;
- cross-workspace templates;
- model fine-tuning or other training;
- external-facing product behavior.

Before external use, version the workflow, define evaluation cases and failure behavior, and test it against held-out examples. A useful internal workflow is not automatically safe or complete enough for a customer-facing agent.

## Completion evidence

Do not call the loop complete until the same object can be traced through:

`source → content_store → extracted signal → insight → Action → executor → recorded outcome`

Verify rendered UI visibility and MCP recall parity. API success alone is insufficient.

## Current unsupported boundaries

- No generic execution tool exists; the approved host performs the actual side effect.
- No server-side dataset export exists; the privacy-minimized converters run locally with a second allowlist gate.
- Slack and Granola inbound connectors are not ready merely because their platform values can be ingested.
- Raw tool-call traces are intentionally not captured as training data.