230 lines
5.0 KiB
Markdown
230 lines
5.0 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```markdown
|
|
# 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.
|