lda-wf/docs/historical/superpowers/plans/2026-05-17-reducer-authoring.md

Reducer Authoring 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: Add Python authoring ergonomics for reducer definitions, including optional Pydantic config models.

Architecture: Keep wf_core reducer execution as the runtime layer. Add wf_authoring.reducers as the ergonomic layer that builds ReducerDefinition objects from Python functions, similar to how node authoring builds NodeSpecs. Config models are optional; when present, they generate ReducerSpec.config_schema and receive parsed config objects at call time.

Tech Stack: Python, Pydantic BaseModel, pytest, existing reducer runtime.

---

File Structure

• Create src/wf_authoring/reducers/
  • callables.py: reducer callable protocols
  • decorator.py: @reducer(...)
  • catalog.py: ReducerCatalog
  • __init__.py: reducer authoring exports
• Modify src/wf_authoring/__init__.py
  • export reducer authoring API
• Add tests/authoring/test_reducers.py
  • plain reducer authoring
  • configured reducer authoring with BaseModel config
  • catalog specs/definitions

Tasks

Task 1: Pin Authoring API

• Add tests proving:
  • @reducer(name="wf.std.add") wraps a two-arg callable
  • @reducer(name="wf.std.modulo_add", config_model=ModuloConfig) wraps a callable receiving parsed config
  • config model JSON Schema becomes ReducerSpec.config_schema
  • ReducerCatalog.from_reducers(...) exposes definitions and specs
• Run focused tests and confirm failure before implementation.

Task 2: Implement Reducer Authoring

• Add typed callable protocols for plain/config reducers.
• Add a small wrapper object that owns a ReducerDefinition.
• Add @reducer(...) overloads for bare and configured reducers.
• Add ReducerCatalog.
• Export from wf_authoring.

Task 3: Verify

• Run uv run --with pytest pytest tests/authoring/test_reducers.py -q
• Run uv run --with pytest pytest tests/authoring -q
• Run full suite and basedpyright.

Non-Goals

• MCP tools for authoring reducers
• LLM-authored reducer code
• external reducer packages
• replacing current built-in registration in this pass