Part 2 of kurrent-io/kcap-server Linear issue AI-2774 (Plan ledger: declared plans, documents and tasks across harnesses). Spec lives in kcap-server at docs/superpowers/specs/2026-09-14-ai2774-plan-ledger-design.md, D7 and D8. This PR is the hypothesis the whole design tests: it is the first moment an agent can declare anything.
Scope
New MCP server kcap-plans (kcap mcp plans): one entry in KcapMcpServers.All, NeedsProjectCwd: true, not read-only, registered in every harness like kcap-workitems. Session id resolution identical to work items: explicit argument, KCAP_SESSION_ID, CODEX_THREAD_ID.
Tools (all keys on the wire snake_case; server routes under /api/plans):
declare_plan_document(kind: plan|spec|design, path, argues_from?, work_item_id?, session_id?) — the CLI reads the file, computes SHA-256, fills workspace_root from the git top-level (same source as the session-start hook), attaches the content when ≤ 256 KB. Returns plan_id, document_key, created.set_plan_tasks(tasks: [{task_id?, title, status?, note?}], plan_id?, session_id?) — full ordered snapshot; without plan_id targets the session's plan (most recently declared/attached, else creates the session's explicit plan). Returns the list with ids.update_plan_task(task_id | ordinal, status: pending|in_progress|completed|skipped, note?, plan_id?)get_plan(plan_id?, session_id?) — documents, tasks with status and source, progress {completed, total, total_known}. Every result states which plan it acted on.
Skill kcap:plans (kcap/skills/plans/SKILL.md): triggers on writing or reading a plan, spec or design document, on starting to execute a plan, and on any mention of a task list or todo. Says three things and nothing else: when you write or are handed a plan, spec or design document, declare it; when a plan has discrete steps, declare them and update each transition; keep whatever ledger your own workflow asks for as well — this replaces the harness's task list, not your notes. It must not name any other skill's file or grammar.
SessionStart nudge: PlansNudgeEmitter beside WorkItemsNudgeEmitter, same gating (opt-out flag, kcap-plans materialised in that harness's config, usable session id), two sentences.
kcap validate-plan: new ## Tasks section (ordinal, title, status, source) and ## Plan prefers the declared plan document; help text updated.
Tests
MCP tool schema tests; snake_case wire keys; session-id resolution across the three sources; nudge gating; declare_plan_document hash and size-cap behaviour; validate-plan rendering with and without tasks. Run scripts/check-linear-ids.sh before pushing (no Linear ids in C# comments).
After merge
Submodule bump in kcap-server, then the adoption measurement described in AI-2774 starts when the release reaches npm latest.
Part 2 of kurrent-io/kcap-server Linear issue AI-2774 (Plan ledger: declared plans, documents and tasks across harnesses). Spec lives in kcap-server at
docs/superpowers/specs/2026-09-14-ai2774-plan-ledger-design.md, D7 and D8. This PR is the hypothesis the whole design tests: it is the first moment an agent can declare anything.Scope
New MCP server
kcap-plans(kcap mcp plans): one entry inKcapMcpServers.All,NeedsProjectCwd: true, not read-only, registered in every harness likekcap-workitems. Session id resolution identical to work items: explicit argument,KCAP_SESSION_ID,CODEX_THREAD_ID.Tools (all keys on the wire snake_case; server routes under
/api/plans):declare_plan_document(kind: plan|spec|design, path, argues_from?, work_item_id?, session_id?)— the CLI reads the file, computes SHA-256, fillsworkspace_rootfrom the git top-level (same source as the session-start hook), attaches the content when ≤ 256 KB. Returnsplan_id,document_key,created.set_plan_tasks(tasks: [{task_id?, title, status?, note?}], plan_id?, session_id?)— full ordered snapshot; withoutplan_idtargets the session's plan (most recently declared/attached, else creates the session's explicit plan). Returns the list with ids.update_plan_task(task_id | ordinal, status: pending|in_progress|completed|skipped, note?, plan_id?)get_plan(plan_id?, session_id?)— documents, tasks with status and source,progress {completed, total, total_known}. Every result states which plan it acted on.Skill
kcap:plans(kcap/skills/plans/SKILL.md): triggers on writing or reading a plan, spec or design document, on starting to execute a plan, and on any mention of a task list or todo. Says three things and nothing else: when you write or are handed a plan, spec or design document, declare it; when a plan has discrete steps, declare them and update each transition; keep whatever ledger your own workflow asks for as well — this replaces the harness's task list, not your notes. It must not name any other skill's file or grammar.SessionStart nudge:
PlansNudgeEmitterbesideWorkItemsNudgeEmitter, same gating (opt-out flag,kcap-plansmaterialised in that harness's config, usable session id), two sentences.kcap validate-plan: new## Taskssection (ordinal, title, status, source) and## Planprefers the declared plan document; help text updated.Tests
MCP tool schema tests; snake_case wire keys; session-id resolution across the three sources; nudge gating;
declare_plan_documenthash and size-cap behaviour;validate-planrendering with and without tasks. Runscripts/check-linear-ids.shbefore pushing (no Linear ids in C# comments).After merge
Submodule bump in kcap-server, then the adoption measurement described in AI-2774 starts when the release reaches npm
latest.