Skip to content

docs(skill): use mureo_state_* MCP tools for STATE.json mutations on Code (#341)#344

Merged
hyoshi merged 1 commit into
mainfrom
fix/skill-state-json-mcp-guidance
Jun 26, 2026
Merged

docs(skill): use mureo_state_* MCP tools for STATE.json mutations on Code (#341)#344
hyoshi merged 1 commit into
mainfrom
fix/skill-state-json-mcp-guidance

Conversation

@hyoshi

@hyoshi hyoshi commented Jun 26, 2026

Copy link
Copy Markdown
Collaborator

Summary

skills/_mureo-shared/SKILL.md's "Tool Selection" table told Claude Code
agents to upsert campaign snapshots / append action_log entries to STATE.json
via the raw Edit tool. But the v2 schema the dashboard reads is non-trivial —
a platforms[<platform>] section with a required account_id — and a
platform/campaign missing it is silently dropped, so the workspace renders
empty / "not yet bootstrapped" even after campaigns were written
(mureo/context/state.py:386, mureo/_data/web/dashboard.js:2155). The
mureo_state_* MCP tools encode that schema atomically and are available on
Code too. Separately, mureo_state_upsert_campaign (and the metrics/report
setters) stamp the top-level last_synced_at that drives the dashboard's
"Synced N ago" freshness — and that field was entirely absent from the
SKILL.md STATE.json Schema docs.

Changes (mirrored to both skills/ and mureo/_data/skills/)

  • _mureo-shared/SKILL.md
    • Table "Append action_log entry" / "Upsert campaign snapshot" Code column:
      Edit → the mureo_state_* MCP tool (matches the issue's suggested diff).
    • Note: STATE.json mutations prefer the MCP tool on every host; direct
      Write on Code is reserved for the bulk-snapshot flows
      (sync-state / daily-check), where the agent must replicate the full
      schema incl. a fresh last_synced_at.
    • Added last_synced_at as a required top-level field (bullet + JSON
      example) — the missing piece behind the reported failure.
  • daily-check/SKILL.md step 11: a last_synced_at reminder for the Code
    Write path (sync-state already had step 9).

Verification

  • Code-reviewed (code-reviewer agent). It caught two prose inaccuracies in an
    earlier draft, now corrected and re-verified against the implementation:
    • platforms / account_id incompleteness — not last_synced_at — is
      what renders a workspace empty/inactive (dashboard.js:2155 gates on
      platforms.length === 0); last_synced_at only drives the freshness label.
    • mureo_state_action_log_append does not re-stamp last_synced_at
      (state.py:463 preserves it); only the campaign/metrics/report writers do.
  • Mirror parity test tests/test_plugin_manifests.py passes (skills/ ↔
    mureo/_data/skills/ byte-identical); skill suite green (247 passed).
  • Docs-only change.

Closes #341

https://claude.ai/code/session_011rAu94b1o1xWYZhARk1VmL

…Code (#341)

The `_mureo-shared` "Tool Selection" table told Claude Code agents to upsert
campaign snapshots / append action_log entries to STATE.json via the raw
`Edit` tool. But the v2 schema the dashboard reads is non-trivial — a
`platforms[<platform>]` section with a required `account_id` — and a
platform/campaign missing it is silently dropped, so the workspace renders
empty / "not yet bootstrapped" even after campaigns were written. The MCP
tools (`mureo_state_upsert_campaign` / `mureo_state_action_log_append`) encode
that schema atomically and are available on Code too. Separately,
`mureo_state_upsert_campaign` (and the metrics/report setters) stamp the
top-level `last_synced_at` that drives the dashboard's freshness — and that
field was entirely absent from the SKILL.md STATE.json Schema docs.

Changes (mirrored to both skills/ and mureo/_data/skills/):
- `_mureo-shared/SKILL.md`: table "Append action_log entry" / "Upsert campaign
  snapshot" Code column `Edit` -> the `mureo_state_*` MCP tool; a note that
  STATE.json mutations prefer the MCP tool on every host, with direct `Write`
  on Code reserved for the bulk-snapshot flows (sync-state / daily-check)
  where the agent must replicate the full schema incl. a fresh
  `last_synced_at`; and `last_synced_at` added as a required top-level field
  (bullet + JSON example).
- `daily-check/SKILL.md` step 11: a `last_synced_at` reminder for the Code
  `Write` path (sync-state already has step 9).

Wording verified against the implementation (code-reviewed): `platforms` /
`account_id` incompleteness — not `last_synced_at` — is what renders a
workspace empty/inactive; `last_synced_at` only drives the "Synced N ago"
freshness; and `mureo_state_action_log_append` does NOT re-stamp it (only the
campaign/metrics/report writers do).

Closes #341

Claude-Session: https://claude.ai/code/session_011rAu94b1o1xWYZhARk1VmL
@hyoshi hyoshi merged commit 709d144 into main Jun 26, 2026
9 checks passed
@hyoshi hyoshi deleted the fix/skill-state-json-mcp-guidance branch June 26, 2026 12:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bug(skill): SKILL.md prescribes Edit tool for STATE.json in Claude Code, but upsert_campaign() is required to guarantee platform and last_synced_at

1 participant