diff --git a/workplans/STATE-WP-0058-agent-skill-hub-interaction.md b/workplans/STATE-WP-0058-agent-skill-hub-interaction.md new file mode 100644 index 0000000..f48ad60 --- /dev/null +++ b/workplans/STATE-WP-0058-agent-skill-hub-interaction.md @@ -0,0 +1,85 @@ +--- +id: STATE-WP-0058 +type: workplan +title: "State Hub Agent Skill — front-load tool schemas + batched writes" +domain: custodian +repo: state-hub +status: ready +owner: codex +topic_slug: custodian +created: "2026-06-07" +updated: "2026-06-07" +state_hub_workstream_id: "163b5646-163e-41a0-b60d-c402b578a4d1" +--- + +# State Hub Agent Skill — front-load tool schemas + batched writes + +**Origin:** requested by the `helix_forge` domain from a data-driven friction +assessment of captured agent coding sessions +(`agentic-resources/docs/ASSESSMENT-infra-friction.md`, AGENTIC-WP-0005). Across +27 real coding sessions, **~17.6 % of all tool calls were hub/task/schema +plumbing**, and `ToolSearch` (loading the *deferred* State Hub MCP tool schemas) +fired in **22 of 27 sessions (81 %)**. State Hub MCP alone was 10.3 % of calls, +with one session making **231 hub calls**. + +This workplan cuts that overhead at the source. Two levers: + +1. **Front-load tool knowledge** so agents stop re-discovering hub tool schemas + via `ToolSearch` every session. +2. **Batch the writes** so a session makes a handful of coarse hub calls instead + of hundreds of fine-grained ones. + +Effectiveness will be re-measured later by Helix Forge against the recorded +baseline (infra-overhead share: median 11.7 %, p90 26.1 %; `ToolSearch` in 81 % +of sessions). + +## Skill Scaffold — Front-load Common Hub Tool Schemas + +```task +id: STATE-WP-0058-T01 +status: todo +priority: high +state_hub_task_id: "6f211ccc-e505-419d-90cc-25874ba98f39" +``` + +Author a Claude Code skill (`SKILL.md` + supporting reference) for State Hub +interaction that front-loads the high-frequency tool signatures so agents do not +re-discover them via `ToolSearch`. Cover at minimum: `get_domain_summary`, +`create_workstream`, `create_task`, `update_task_status`, `add_progress_event`, +`record_decision`, `get_messages` / `send_message` — with argument signatures, the +session-start orientation flow, and the ADR-001 files-first boundary (hub is a read +model). Directly targets the `ToolSearch`-thrash finding. + +## Batched Writes + Bulk Task-Status Sync Op + +```task +id: STATE-WP-0058-T02 +status: todo +priority: high +state_hub_task_id: "2138505a-ea49-4ccc-9dec-a176badaa7a5" +``` + +Add a **bulk task-status sync** endpoint/op so a session updates N task statuses in +one call instead of N (the single biggest call-volume driver — one session made +231 hub calls). Document batched-write guidance in the skill: fewer, coarser +progress events; sync at checkpoints, not per event. Keep the hub a read model and +preserve the automatic `progress_event` semantics on each write. + +## Validate Against Friction Baseline + Coordinate Back to helix_forge + +```task +id: STATE-WP-0058-T03 +status: todo +priority: medium +state_hub_task_id: "cf8d41f8-7831-4c1b-9dfa-58660174294b" +``` + +Verify the skill + bulk op reduce plumbing overhead (dry-run a representative +session flow; confirm `ToolSearch` calls drop and task updates batch). Reply to the +helix_forge coordination message with completion and the new bulk-op signature so a +later Measure pass can compare infra-overhead share against the baseline. After +workplan updates, notify the operator to run from `~/state-hub`: + +```bash +make fix-consistency REPO=state-hub +```