reducerspec

docs/superpowers/plans/2026-05-17-reducer-source-inventory.md

@@ -0,0 +1,64 @@
+# Reducer Source Inventory Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Represent reducers as first-class source-owned capabilities and expose the built-in reducer catalog through existing source inventory.
+
+**Architecture:** Add a small immutable `ReducerSpec` model in `wf_core`, keep runtime reducer execution where it is, and extend `wf_mcp` capability buckets with reducer ownership metadata. Register the three built-in reducer specs under `wf.std` so inventory becomes honest without adding reducer-authoring UX yet.
+
+**Tech Stack:** Python, dataclasses/Pydantic, pytest, existing capability source inventory.
+
+---
+
+## File Structure
+
+- Create `src/wf_core/models/reducers.py`
+  - reducer capability metadata
+- Modify `src/wf_core/models/__init__.py` and `src/wf_core/__init__.py`
+  - export `ReducerSpec`
+- Modify `src/wf_mcp/broker/service/capability_sources.py`
+  - add reducer bucket, counts, and inventory listing
+- Modify `src/wf_mcp/broker/service/builtins.py`
+  - define/register built-in reducer specs under `wf.std`
+- Modify `tests/wf_mcp/test_service.py`
+  - assert reducer inventory
+- Update `docs/wf_mcp_capability_sources.md`
+  - document reducers under `wf.std`
+- Update `docs/workflow_capabilities.md`
+  - name reducers as workflow-facing capabilities
+
+## Tasks
+
+### Task 1: Pin Inventory Behavior
+
+- [ ] Add failing tests proving:
+  - `wf.std` owns built-in reducers
+  - source status exposes `reducer_count`
+  - source inventory exposes reducer names
+- [ ] Run focused service tests and confirm failure before implementation.
+
+### Task 2: Add ReducerSpec and Source Buckets
+
+- [ ] Add `ReducerSpec` with `name`, `description`, and optional value-shape notes.
+- [ ] Export `ReducerSpec` from core.
+- [ ] Extend `CapabilityBuckets`, `as_status()`, and `as_inventory()` with reducers.
+- [ ] Register `wf.std.replace`, `wf.std.append`, and `wf.std.merge_object` in built-ins.
+- [ ] Run focused service tests and confirm they pass.
+
+### Task 3: Update Docs
+
+- [ ] Add reducers to the source vocabulary docs.
+- [ ] Clarify that reducers are selected from sources; LLMs are not expected to author reducer code.
+
+### Task 4: Verify
+
+- [ ] Run `uv run --with pytest pytest tests/wf_mcp -q`
+- [ ] Run `uv run --with pytest pytest -q`
+- [ ] Run `uv run basedpyright --level error`
+
+## Non-Goals
+
+- reducer decorators
+- reducer runtime dependency resolution from external sources
+- reducer MCP tools
+- non-built-in reducer libraries

docs/wf_mcp_capability_sources.md

@@ -30,6 +30,7 @@ CapabilitySource
   capabilities:
     tools
     node_specs
+    reducers
     prompts
     resources
 ```
@@ -60,6 +61,7 @@ Expected capabilities:
   `wf.std.truthy`, `wf.std.first_item`, `wf.std.first_item_maybe`,
   `wf.std.first_item_or_none`, `wf.std.last_item`, `wf.std.last_item_or_none`,
   `wf.std.length`, `wf.std.is_empty`.
+- `reducers`: `wf.std.replace`, `wf.std.append`, `wf.std.merge_object`.
 - `prompts`: workflow authoring guide, error-handling guide, mapping guide.
 - `resources`: reference docs for stdlib node behavior.
 
@@ -215,6 +217,7 @@ Current code has several useful pieces but the boundaries are blurred.
 | Current location | Current role | Target source |
 | --- | --- | --- |
 | `wf_authoring.ops` | reusable workflow node specs | `wf.std.node_specs` |
+| `wf_core` built-in reducers | reusable workflow state reducers | `wf.std.reducers` |
 | `wf_mcp.broker.service.builtins` | local workflow specs | `wf.std`, `wf.mcp` |
 | `wf_mcp.broker.tools` | compatibility wrapper over shared service-admin registration | `wf.admin.tools` |
 | `wf_mcp.admin_surface.tools` | shared service-backed admin tool registration | `wf.admin.tools` |

docs/workflow_capabilities.md

@@ -21,7 +21,8 @@ A source is a named owner of capabilities.
 Examples:
 
 - `everything.default`: an upstream MCP connection source
-- `wf.std`: the local workflow standard library
+- `wf.std`: the local workflow standard library, including reusable nodes and
+  reducers
 - `wf.mcp`: local workflow helpers for interacting with MCP backends
 - `wf.admin`: privileged control-plane capabilities
 
@@ -237,6 +238,7 @@ Sources own capability kinds:
 ```text
 tools
 node_specs
+reducers
 prompts
 resources
 ```
@@ -262,7 +264,7 @@ Today:
 - `CapabilitySource` already owns buckets for tools, node specs, prompts, and
   resources
 - connection sources represent upstream MCP snapshots
-- `wf.std` owns local reusable workflow node specs
+- `wf.std` owns local reusable workflow node specs and reducers
 - `wf.mcp` owns workflow-facing MCP runtime helpers
 - discovered upstream tools can already become workflow node specs
 - saved artifacts can be tagged with `kind="workflow"` or `kind="wrapper"`