operate-openbb-workspace

name	operate-openbb-workspace
description	Operates the local OpenBB Workspace research system, Serenity radar, and token-efficient CLI. Use when the user asks an agent to work with the OpenBB Workspace dashboard, Serenity-style stock research, local OpenBB API/MCP, or workspace-first investment research workflows.

Operate the local OpenBB Workspace research system as an agent-facing research cockpit. The user should be able to stay inside OpenBB Workspace while the agent uses the local backend, Serenity CLI, and dry-run write actions to read, summarize, propose, and verify research operations.

This skill is not allowed to treat the local Serenity store as a complete research source. The local store is a queue, memory, and approval system. Real investment research must add a fresh external evidence pass before any new thesis, upgrade, or proposal is presented as research output.

This skill is about workflow control, not stock promotion. Treat Serenity scores as research-priority and thesis-quality signals, never as investment advice or expected-return guarantees.

<quick_start> Default to compact CLIs because they save tokens versus listing MCP tools or pasting large JSON:

• ./backend/openbb-agent-tools/serenity-agent for research data and dry-run writes
• ./backend/openbb-agent-tools/workspace-agent for Workspace dashboard, backend, widget, and layout operations

1. Confirm the API is reachable:

lsof -iTCP:6900 -sTCP:LISTEN
lsof -iTCP:6901 -sTCP:LISTEN

2. If needed, start the local OpenBB API backend:

./backend/openbb-agent-tools/start-openbb-api.sh

3. Get the agent brief:

./backend/openbb-agent-tools/serenity-agent brief --limit 3
./backend/openbb-agent-tools/serenity-agent daily-brief --limit 8

3b. Check Workspace UI control when dashboard operations are needed:

./backend/openbb-agent-tools/workspace-agent health
./backend/openbb-agent-tools/workspace-agent backends

4. Drill into one name:

./backend/openbb-agent-tools/serenity-agent scorecard DEMO1
./backend/openbb-agent-tools/serenity-agent evidence DEMO1 --limit 8

5. Propose research writes as dry-runs first:

./backend/openbb-agent-tools/serenity-agent dry-run-evidence DEMO1 \
  --level inferred \
  --source-type filing \
  --source "company update" \
  --date 2026-06-03 \
  --claim "Customer qualification evidence needs verification before promotion."

</quick_start>

<workspace_model> The human-facing surface is OpenBB Workspace. The agent-facing surfaces are, in priority order:

1. Serenity CLI: ./backend/openbb-agent-tools/serenity-agent
2. Workspace CLI: ./backend/openbb-agent-tools/workspace-agent
3. OpenBB API backend: http://127.0.0.1:6900 or http://127.0.0.1:6901; the Serenity CLI auto-detects both
4. Workspace MCP sidecar: http://127.0.0.1:8787/mcp for raw browser/session/widget control when the Workspace CLI does not cover the operation
5. Optional OpenBB data MCP: http://127.0.0.1:8790/mcp only when direct MCP data tools are needed
6. Browser/Chrome automation: only when the user asks to inspect or operate the visible Workspace UI

Do not put the OpenBB data MCP on 8787. That port belongs to the official Workspace MCP sidecar. The optional data MCP exposes backend tools and data; it does not see the user's current dashboard selection, scroll position, highlighted row, or visible browser state. </workspace_model>

<dashboard_workflow> Use this mental model when explaining or operating the dashboard:

• Radar: ranked candidates and current research priority
• Action Inbox: what needs attention next
• Scorecard: why a ticker is ranked where it is
• Evidence: confirmed, inferred, speculative, and unverified proof chain
• Catalysts: upcoming proof points and monitoring triggers
• Add Candidate / Add Evidence / Add Catalyst: structured intake widgets
• Update Status / Archive Candidate: lifecycle control

The preferred agent loop:

1. Read brief.
2. Pick the highest-priority action, not necessarily the highest score.
3. Read the ticker scorecard.
4. Read evidence and catalyst rows when the scorecard is not enough.
5. Run an external evidence pass unless the task is explicitly only local triage.
6. Produce a short conclusion with evidence level, uncertainty, source dates, and next action.
7. Create a pending proposal instead of leaving the conclusion as chat text.
8. Use Workspace proposal widgets for human approval.
9. Approve executes the proposal payload; reject preserves the history. </dashboard_workflow>

<external_evidence_inputs> For one-stop research, local Serenity data is only the starting queue. Before creating a substantive proposal, pull or verify outside evidence from the smallest source set that can answer the question:

1. Official OpenBB Workspace widgets for prices, fundamentals, estimates, earnings, news, ownership, analyst data, macro, and sector context.
2. Optional OpenBB data MCP at http://127.0.0.1:8790/mcp when direct data-tool access is more efficient than Workspace UI operations.
3. Primary company sources such as SEC filings, earnings transcripts, investor presentations, press releases, and customer announcements.
4. Industry and supply-chain sources only when they clearly identify the actor, date, claim, and uncertainty.
5. Web/search/browser research when recent or niche facts are needed and OpenBB data is insufficient.

Every external evidence item that affects the recommendation should preserve:

• source type
• source name
• publication or access date
• URL when available
• exact claim being supported
• evidence level: confirmed, inferred, speculative, or unverified
• what would invalidate the claim

If no fresh external evidence was checked, say the output is local triage only and do not present it as a completed research conclusion. </external_evidence_inputs>

<cli_commands> Compact read commands:

./backend/openbb-agent-tools/serenity-agent brief --limit 3
./backend/openbb-agent-tools/serenity-agent radar --limit 5
./backend/openbb-agent-tools/serenity-agent inbox --limit 8
./backend/openbb-agent-tools/serenity-agent inbox --symbol DEMO1 --limit 8
./backend/openbb-agent-tools/serenity-agent scorecard DEMO2
./backend/openbb-agent-tools/serenity-agent evidence DEMO2 --limit 10
./backend/openbb-agent-tools/serenity-agent proposals
./backend/openbb-agent-tools/serenity-agent proposal-history
./backend/openbb-agent-tools/serenity-agent daily-brief --limit 8

Structured output for downstream tools:

./backend/openbb-agent-tools/serenity-agent brief --limit 3 --json
./backend/openbb-agent-tools/serenity-agent scorecard DEMO2 --json

Dry-run write proposal:

./backend/openbb-agent-tools/serenity-agent dry-run-evidence SYMBOL \
  --level inferred \
  --source-type mapping \
  --source "source name" \
  --date YYYY-MM-DD \
  --claim "one concise claim"

Create a pending proposal:

./backend/openbb-agent-tools/serenity-agent propose-evidence SYMBOL \
  --level inferred \
  --source-type mapping \
  --source "source name" \
  --date YYYY-MM-DD \
  --claim "one concise claim" \
  --risk "main uncertainty" \
  --why-now "why this needs review now"

Approve or reject:

./backend/openbb-agent-tools/serenity-agent approve PROPOSAL_ID
./backend/openbb-agent-tools/serenity-agent reject PROPOSAL_ID --reason "why rejected"

</cli_commands>

<workspace_cli_commands> Compact Workspace MCP commands:

./backend/openbb-agent-tools/workspace-agent health
./backend/openbb-agent-tools/workspace-agent backends
./backend/openbb-agent-tools/workspace-agent ensure-backend
./backend/openbb-agent-tools/workspace-agent widgets --backend-id BACKEND_ID --query agent_serenity --limit 20
./backend/openbb-agent-tools/workspace-agent create-dashboard "Serenity Agent Ops"
./backend/openbb-agent-tools/workspace-agent read-dashboard DASHBOARD_ID
./backend/openbb-agent-tools/workspace-agent add-serenity-core DASHBOARD_ID
./backend/openbb-agent-tools/workspace-agent add-proposal-layer DASHBOARD_ID
./backend/openbb-agent-tools/workspace-agent add-external-evidence-layer DASHBOARD_ID --symbol DEMO1

Use raw Companion MCP only for operations not yet wrapped by workspace-agent, such as custom one-off widget schemas, parameter options, generated notes, or unusual layout edits. </workspace_cli_commands>

<api_reference> Use direct API calls only when the CLI does not cover the needed operation.

Read endpoints:

• GET /agent/serenity/radar
• GET /agent/serenity/action_inbox
• GET /agent/serenity/scorecard?symbol=DEMO2
• GET /agent/serenity/bottlenecks
• GET /agent/serenity/evidence?symbol=DEMO2
• GET /agent/serenity/catalysts?symbol=DEMO2
• GET /agent/serenity/report

Write endpoints exist for candidate, evidence, catalyst, status, and archive operations. Default to dry_run: true; only use non-dry-run writes when the user explicitly authorizes the exact action.

Proposal endpoints:

• GET /agent/serenity/proposals
• GET /agent/serenity/proposal_history
• GET /agent/serenity/daily_brief
• POST /agent/serenity/create_proposal
• POST /agent/serenity/approve_proposal
• POST /agent/serenity/reject_proposal </api_reference>

<one_stop_research_workflow> When asked to produce investment research inside Workspace, follow this fixed workflow without needing extra instructions:

1. Run serenity-agent daily-brief --limit 8.
2. If the user named a symbol, run serenity-agent scorecard SYMBOL and serenity-agent evidence SYMBOL --limit 10.
3. Run the external evidence pass defined in <external_evidence_inputs>. Use Workspace/OpenBB data first, then primary company sources or web research when the data is missing, stale, or thesis-critical.
4. Convert outside evidence into a concise evidence judgment: confirmed, inferred, speculative, or unverified.
5. Write the finding as a proposal, not as final-only chat text. Use serenity-agent propose-evidence for evidence additions.
6. Run serenity-agent proposals and summarize the proposal ID, symbol, action, risk, why now, and external sources checked.
7. Ensure the dashboard has the approval surface: workspace-agent add-proposal-layer DASHBOARD_ID when those widgets are missing.
8. Ensure the dashboard has the external evidence surface: workspace-agent add-external-evidence-layer DASHBOARD_ID --symbol SYMBOL when official OpenBB evidence widgets are missing.
9. Stop before real writes unless the user explicitly approves, or unless the user has already instructed you to approve a specific proposal ID.

The expected end state is a visible Workspace proposal queue plus a concise text summary of what was queued. </one_stop_research_workflow>

<research_rules>

• Separate evidence from inference. Label claims as confirmed, inferred, speculative, or unverified.
• Prefer primary sources: filings, company releases, transcripts, customer disclosures, credible supply-chain reports.
• Do not upgrade a speculative thesis to confirmed without direct evidence.
• Do not treat price momentum as business validation.
• Preserve invalidation criteria. A good thesis must say what would break it.
• Surface valuation and chase risk, especially after sharp rerates.
• Use recent data for current market facts; verify unstable facts before relying on them.
• Keep output concise enough for the user to act inside the dashboard. </research_rules>

<browser_rules> Only use Chrome or Browser automation when the user asks about what is visibly on the Workspace page or asks the agent to operate the UI.

If browser inspection is needed:

• Use Chrome for the user's existing authenticated Workspace tab.
• Use Browser/in-app browser for local URLs and reproducible UI testing.
• State clearly that MCP itself cannot see the rendered Workspace UI. </browser_rules>

When changing this system, run the focused tests:

PYTHONPATH=./backend/openbb-agent-tools/scripts ~/OpenBB/conda/envs/openbb/bin/python -m pytest ./backend/openbb-agent-tools/tests -v

For a quick runtime check:

./backend/openbb-agent-tools/serenity-agent brief --limit 3
./backend/openbb-agent-tools/serenity-agent scorecard DEMO1
./backend/openbb-agent-tools/serenity-agent proposals
./backend/openbb-agent-tools/workspace-agent health
./backend/openbb-agent-tools/workspace-agent backends

<anti_patterns>

• Do not make the user leave Workspace for routine research operations.
• Do not paste full MCP tool lists when the CLI can return a compact answer.
• Do not claim the agent can see the user's dashboard through MCP.
• Do not write real research data when a dry-run proposal is enough.
• Do not present Serenity rank as a buy/sell instruction.
• Do not bury the next action under long narrative. </anti_patterns>

<success_criteria> This skill is working when an agent can:

• Start or detect the local OpenBB API backend
• Use the Serenity CLI for compact brief, radar, inbox, scorecard, and evidence reads
• Use the Workspace CLI for compact backend, dashboard, widget, and layout operations
• Run a fresh external evidence pass before treating a thesis as completed research
• Create structured proposals instead of leaving agent research as chat-only text
• Present proposal approval widgets in Workspace
• Explain how the OpenBB Workspace dashboard maps to the backend workflow
• Produce dry-run research proposals before any real write
• Keep evidence levels and uncertainty explicit
• Avoid confusing the data MCP with rendered Workspace UI visibility </success_criteria>