generated from coulomb/repo-seed
110 lines
4.3 KiB
Markdown
110 lines
4.3 KiB
Markdown
---
|
|
id: STATE-WP-0058
|
|
type: workplan
|
|
title: "State Hub Agent Skill — front-load tool schemas + batched writes"
|
|
domain: custodian
|
|
repo: state-hub
|
|
status: finished
|
|
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: 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
|
|
|
|
```task
|
|
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
|
|
|
|
```task
|
|
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`:
|
|
|
|
```bash
|
|
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
|