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.claude/skills/jc-roadmap-changelog/SKILL.md
GitHubJapaConnect 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 carryagent.use(door scope) plusagent.write(elevated scope) to reach the write tools.agent.writeis admin-only (api.keys.manage); mint it from the control panel orPOST /api/v1/control/api-keys. Withoutagent.writethe key sees the read-only gate map only.Authorization: Bearer <JWT>— session token of a user holding theroadmap.*nodes andagent.usegets the full RBAC-filtered catalog.Authorization: Bearer jcpat_...— OAuth tokens (§120) act as the granting user but can never carryagent.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
- 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. - Dedupe —
roadmap.items.listwithq=<feature name>(and optionallystatusfilters) to find an existing item for the feature. - Write — for a new feature:
roadmap.item.create(title, summary, markdownbody,category_id). For an existing item:roadmap.item.update. - Ship —
roadmap.item.set_statuswithstatus="shipped". Valid chains:pending → under_review,under_review → planned|testing,planned → in_progress|testing,in_progress → testing|shipped,testing → shipped. Apending → shippedjump fails — create withstatus:"shipped"instead, or walk the chain.- The entry appears on
/roadmap/changelogimmediately (grouped byshipped_atmonth) and voters are notified viaroadmap:ship_notify.
- The entry appears on
- Flag-linked items — if
feature_flag_keyis set,set_statusreturnsstatus_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
summaryper entry; details go inbody(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.listonly withinclude_deleted: true; never resurrect one unless asked — slugs of deleted rows stay reserved.