lda-wf/docs/superpowers/research/2026-06-01-wf-api-extraction-mapping-prompt.md

wf_api Extraction Mapping Prompt

You are investigating the codebase only. Do not edit files.

Goal: map how the current workflow application surface is implemented so we can extract a protocol-neutral wf_api package without breaking MCP, CLI, stores, or tests.

The current suspicion:

• src/wf_mcp/workflow_surface/handlers.py is a large application-service class.
• It depends on WfMcpService, which is also broad.
• We need to understand whether to move the class first, split it first, or introduce smaller services/facades.

Required Output

Write your findings to:

docs/superpowers/research/2026-06-01-wf-api-extraction-map.md

Keep it structured and link-heavy. Do not paste huge code blocks. Use file paths, symbol names, and short notes.

Investigation Scope

Focus on these files/symbols first:

src/wf_mcp/workflow_surface/handlers.py
  WorkflowSurfaceHandlers

src/wf_mcp/broker/service/core.py
  WfMcpService

src/wf_mcp/workflow_surface/tools.py
  register_workflow_tools

src/wf_cli/context.py
  CliContext
  load_cli_context

src/wf_cli/commands/*.py

src/wf_artifacts/
src/wf_platform/
src/wf_core/

Use ripgrep/symbol search. Prefer precise symbol references over broad file dumps.

Questions To Answer

1. What are the public operations?

List every WorkflowSurfaceHandlers public method and classify it:

capabilities
drafts
artifacts
deployments
runs
explain/next-actions
internal helper accidentally public

For each method, record:

• method name
• input parameters
• return shape summary
• direct dependencies
• current callers/tests

2. What parts of WfMcpService does it actually use?

For each access from WorkflowSurfaceHandlers to self.service, record the member:

self.service.artifact_store
self.service.draft_workspace_store
self.service.capability_sources
self.service._get_qualified_spec(...)
self.service._record_event(...)
...

Classify each dependency:

artifact storage
draft storage
run storage
source/capability inventory
MCP connection/catalog
event bus
private helper currently being used

Flag private-method dependencies such as _get_qualified_spec or _record_event.

3. Which dependencies are MCP-specific vs protocol-neutral?

Create a table:

Dependency | Package today | MCP-specific? | Should live in wf_artifacts/wf_platform/wf_api/wf_mcp?

Examples:

• artifact store likely protocol-neutral
• draft workspace store likely protocol-neutral
• source/capability refs likely protocol-neutral
• MCP connection config/adapters likely MCP-specific for now
• event bus may be platform-neutral

4. What is the safest extraction seam?

Compare these options:

Option A: Move class first

Move WorkflowSurfaceHandlers to wf_api.service.WorkflowApi, keep same constructor accepting WfMcpService.

Pros/cons.

Option B: Introduce API facade with ports

Create WorkflowApi that depends on a smaller WorkflowApiBackend/ports object instead of all WfMcpService, then adapt WfMcpService into that backend.

Pros/cons.

Option C: Split handlers by domain first

Split capabilities/drafts/artifacts/deployments/runs into separate classes before moving packages.

Pros/cons.

Recommend one first slice and explain why.

5. What should the target package shape be?

Propose a concrete package layout, for example:

src/wf_api/
  __init__.py
  service.py
  backend.py
  capabilities.py
  drafts.py
  artifacts.py
  deployments.py
  runs.py
  models.py

Do not overdesign. Identify which files are needed in the first slice vs later.

6. What tests protect the extraction?

List existing tests that must continue to pass, grouped by package:

tests/wf_mcp/workflow_surface/*
tests/wf_cli/*
tests/wf_mcp/test_server.py
...

Identify any missing tests needed before extraction.

7. What code should not move yet?

Explicitly list things that should stay in wf_mcp for now:

• MCP transport/proxy/runtime/session code
• FastMCP registration tools
• connection adapters if not protocol-neutral yet
• broker server construction

8. Risks and weirdness

Call out:

• circular import risks
• private method dependencies
• store ownership ambiguity
• naming confusion
• tests that monkeypatch wf_cli.commands.*.load_cli_context
• anything that would make FastAPI later harder or easier

Output Format

Use this exact outline:

# wf_api Extraction Map

## Executive Summary

## Public Operation Inventory

## WfMcpService Dependency Inventory

## Protocol-Neutral vs MCP-Specific Dependencies

## Extraction Options

## Recommended First Slice

## Proposed Package Shape

## Test Coverage

## Things To Keep In wf_mcp For Now

## Risks And Open Questions

## Suggested Next Plan

Constraints

• Do not edit code.
• Do not propose FastAPI implementation yet.
• Keep current process-local behavior as the default.
• Assume wf_mcp and wf_cli should become adapters over the same process-local API.
• Prefer small, behavior-preserving extraction steps over a large rewrite.