jc-roadmap-changelog

Generate and publish JapaConnect roadmap/changelog entries through the §103 agent tool catalog — reachable via the MCP bridge (§119, POST /api/v1/mcp) for external agents (Devin CLI, Claude Code, any

SKILL.md

GitHub

JapaConnect Roadmap Changelog via Agent Tools

The public changelog (/roadmap/changelog) has no separate store — it renders roadmap_items rows whose status = 'shipped', grouped by shipped_at month (§113, ADR-127). Publishing a changelog entry = creating/updating a roadmap item and driving it to shipped.

Where the tools live

Migration 000928 seeds six tools into the ai_tools catalog (internal/ai/tools_roadmap.go, registered in tools_register.go):

Tool RBAC gate Purpose
roadmap.categories.list roadmap.view category slugs/ids for mapping
roadmap.items.list roadmap.view dedupe read — filter by status/q/category, paginated; bodies omitted, use item.get
roadmap.item.get roadmap.view full item incl. body + deleted_at
roadmap.item.create roadmap.create new item; status:"shipped" lands on the changelog directly
roadmap.item.update roadmap.edit patch title/slug/summary/body/category/flag/window — status is rejected, use set_status
roadmap.item.set_status roadmap.moderate lifecycle state machine — → shipped stamps shipped_at and enqueues roadmap:ship_notify voter notifications

Every call is authorized as the calling principal — the same nodes gate the /admin/roadmap/* REST routes, so the agent can only do what its user could.

Calling from an external agent (Devin CLI, Claude Code, MCP hosts)

Endpoint: POST {API_BASE}/api/v1/mcp — JSON-RPC 2.0 (tools/list, tools/call).

Auth — pick one:

  • X-API-Key: <key> — key must carry agent.use (door scope) plus agent.write (elevated scope) to reach the write tools. agent.write is admin-only (api.keys.manage); mint it from the control panel or POST /api/v1/control/api-keys. Without agent.write the key sees the read-only gate map only.
  • Authorization: Bearer <JWT> — session token of a user holding the roadmap.* nodes and agent.use gets the full RBAC-filtered catalog.
  • Authorization: Bearer jcpat_... — OAuth tokens (§120) act as the granting user but can never carry agent.write — read tools only.

Example tools/call:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "roadmap.item.create",
    "arguments": {
      "title": "Embassy appointment alerter",
      "summary": "Get notified the moment embassy slots open.",
      "category_id": "<uuid from roadmap.categories.list>",
      "status": "shipped"
    }
  }
}

Each tools/call creates an ai_agent_sessions row + ai_agent_tool_calls audit row (§119). Error payloads arrive as {"error","code"} inside isError: true results — codes: item_not_found, invalid_status_transition, status_derived, unknown_feature_flag, flag_already_linked, duplicate_slug, validation_error.

Changelog-generation workflow

  1. Gather changes — git log <prev-tag>..HEAD --oneline, gh pr list --state merged, or release notes. Keep only user-facing changes; skip chores, refactors, internal tooling.
  2. Dedupe — roadmap.items.list with q=<feature name> (and optionally status filters) to find an existing item for the feature.
  3. Write — for a new feature: roadmap.item.create (title, summary, markdown body, category_id). For an existing item: roadmap.item.update.
  4. Ship — roadmap.item.set_status with status="shipped". Valid chains: pending → under_review, under_review → planned|testing, planned → in_progress|testing, in_progress → testing|shipped, testing → shipped. A pending → shipped jump fails — create with status:"shipped" instead, or walk the chain.
    • The entry appears on /roadmap/changelog immediately (grouped by shipped_at month) and voters are notified via roadmap:ship_notify.
  5. Flag-linked items — if feature_flag_key is set, set_status returns status_derived: change the flag's rollout phase instead (the item status follows the flag automatically).

Rules (non-negotiable)

  • Rule 17 — never write "AI-generated", "auto-generated by agent", or any agent attribution into titles, summaries, bodies, or commit messages. Changelog text is product copy in the project's voice.
  • Write for end users: "You can now X", not "Implemented Y endpoint". One sentence summary per entry; details go in body (markdown).
  • Reuse existing categories (roadmap.categories.list) — do not invent slugs.
  • Respect roadmap.enabled — the whole surface 404s when the flag is off.
  • Soft-deleted items are visible to roadmap.items.list only with include_deleted: true; never resurrect one unless asked — slugs of deleted rows stay reserved.