state-hub/workplans/STATE-WP-0058-agent-skill-hub-interaction.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
STATE-WP-0058	workplan	State Hub Agent Skill — front-load tool schemas + batched writes	custodian	state-hub	finished	codex	custodian	2026-06-07	2026-06-07	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

id: STATE-WP-0058-T01
status: done
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

id: STATE-WP-0058-T02
status: done
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

id: STATE-WP-0058-T03
status: done
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:

make fix-consistency REPO=state-hub

Verification Notes

Completed 2026-06-07:

• Added skills/state-hub/SKILL.md plus skills/state-hub/references/tool-signatures.md to front-load the high-frequency State Hub MCP signatures, session flow, ADR-001 files-first boundary, REST fallbacks, and batched-write guidance.
• Added POST /tasks/bulk-status-sync for checkpoint task-status batching. The endpoint updates all requested task statuses in one transaction, rejects duplicate task ids with 400, rejects missing task ids with 404, and emits one task_status_changed progress event per successful item.
• Added MCP wrapper bulk_update_task_statuses(updates, author?, session_id?) and documented it in mcp_server/TOOLS.md.
• Sent completion/signature handoff to helix_forge as message 7236bd1c-b60d-481a-bc05-3080c4b46f72, followed by tracked-path correction 1a322eed-96d6-45d4-9e0a-685a6f66e180.

Verification:

• .venv/bin/python -m pytest tests/test_task_bulk_status_sync.py tests/test_mcp_write_tools.py -q -> 12 passed
• .venv/bin/python -m pytest tests/test_task_bulk_status_sync.py tests/test_mcp_write_tools.py tests/test_mcp_smoke.py -q -> 25 passed
• git diff --check -> clean