Steer agents to declare work-item breakdown and relations via kcap mcp workitems

[realtonyyoung]

Why

Follow-up to the Manage-tab "steering" work in kcap-server (Home tabs round 4). Lever (a) — the Home Start-plan prompt declaring a breakdown — shipped server-side in kurrent-io/kcap-server#1409. This PR ships the three CLI-side levers (b/c/d).

Nothing told coding agents to declare a work item's structure, so the breakdown (parent → parts) and dependency (blocks / blocked-by) topology stayed empty in practice — and Home's "Blockers & dependencies" view and n/m parts progress figures had nothing to render. The declare_work_breakdown / declare_work_relation tools existed; agents just weren't steered to use them.

What

• MCP instructions preamble on the kcap mcp workitems server (surfaced on initialize, kcap-memory style): steers agents to create part items and declare the parent→parts breakdown + blocks/blocked-by relations, and states plainly that these are declared, never inferred.
• work-items plugin skill (kcap/skills/work-items/SKILL.md) teaching the create-parts → declare_work_breakdown → declare_work_relation flow, the same-repo / one-parent / no-self-relation rules, and when NOT to declare.
• Stale-help fix: help-mcp.txt and README.md both claimed the workitems MCP server exposes "two tools" — updated to the actual seven-tool surface.

Tests

• McpWorkItemsServerTests.Server_instructions_steer_agents_to_declare_breakdown_and_relations pins that the preamble names both declare tools + the declared-never-inferred rule.
• Existing workitems MCP tests green (39/39). AOT publish clean (no IL30xx/IL20xx).

Linear: AI-1901 (follow-up to AI-1894). No server change; the kcap-server submodule pin bump is a separate step.

🤖 Generated with Claude Code

[linear-code]

AI-1901

[qodo-code-review]

PR Summary by Qodo

Add MCP steering so agents declare work-item breakdowns and dependencies

✨ Enhancement 📝 Documentation 🧪 Tests 🕐 20-40 Minutes

AI Description

• Add MCP instructions preamble steering agents to declare breakdowns and dependencies.
• Document the create-parts → declare-breakdown → declare-relations workflow as a CLI skill.
• Update MCP help/docs to reflect the full seven-tool workitems surface and add a regression test.

Diagram

graph TD
  A["Coding agent"] --> B["kcap mcp workitems server"] --> C["MCP initialize response"] --> A
  A --> D["Declare tools"] --> E["Work items API"] --> F[("Work item store")]
  G["Docs & skill"] --> A
  subgraph Legend
    direction LR
    _u["User/agent"] ~~~ _s["Service"] ~~~ _d[("Data store")] ~~~ _doc["Documentation"]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Rely on docs/skill only (no MCP initialize instructions)

• ➕ No protocol-level change; purely documentation-based
• ➕ Avoids any risk of instruction text affecting MCP clients
• ➖ Guidance is easy for agents to miss; doesn’t reach agents that never read repo docs
• ➖ Fails the stated goal: steering at tool-connection time

2. Embed steering into each tool description only

• ➕ Keeps guidance close to each tool; potentially more granular
• ➕ May reduce reliance on a single global prompt block
• ➖ Harder to convey the end-to-end flow (create parts → declare breakdown → declare relations)
• ➖ Still risks agents missing the “declared, never inferred” rule unless repeated everywhere

Recommendation: Keep the current approach: an MCP instructions preamble is the most reliable way to steer agents at connection time, while the skill + help/README provide durable, human-readable guidance. The added unit test appropriately pins the key steering invariants (names both declare tools and reinforces declared-not-inferred).

Files changed (5) +131 / -7

Enhancement (1) +15 / -1

McpWorkItemsServer.csAdd MCP initialize 'instructions' preamble steering declaration of topology +15/-1

Add MCP initialize 'instructions' preamble steering declaration of topology

• Adds a server-level 'ServerInstructions' constant that tells agents to create part items and declare breakdowns and dependency relations, emphasizing that structure is declared (not inferred). Wires the preamble into the MCP initialize response so clients receive it on connect.

src/Capacitor.Cli/Commands/McpWorkItemsServer.cs

Tests (1) +13 / -0

McpWorkItemsServerTests.csAdd regression test pinning the MCP instructions steering text +13/-0

Add regression test pinning the MCP instructions steering text

• Adds a unit test asserting that the initialize 'instructions' mention both declare tools and include the declared-not-inferred rule. Prevents regressions back to correlation-only guidance.

test/Capacitor.Cli.Tests.Unit/McpWorkItemsServerTests.cs

Documentation (3) +103 / -6

README.mdDocument full workitems MCP surface and purpose (7 tools, declared topology) +8/-3

Document full workitems MCP surface and purpose (7 tools, declared topology)

• Expands the workitems MCP server description to include declaring breakdowns and dependencies, not just session correlation. Updates the tool list from two to seven and clarifies that Home UI renders only from declared parts/relations.

README.md

SKILL.mdAdd work-items skill describing how to declare breakdowns and dependencies +80/-0

Add work-items skill describing how to declare breakdowns and dependencies

• Introduces a new skill document that teaches agents when and how to create part work items, declare parent→parts breakdowns, declare blocks/blocked-by relations, and verify topology. Captures server-enforced rules (same repo, one parent per part, no self-relation) and retraction guidance.

kcap/skills/work-items/SKILL.md

help-mcp.txtFix stale MCP help for workitems (7 tools, declared-not-inferred guidance) +15/-3

Fix stale MCP help for workitems (7 tools, declared-not-inferred guidance)

• Updates CLI help text to describe the full seven-tool workitems surface and explicitly states that breakdowns/relations are declared, never inferred. Adds brief per-tool descriptions for breakdown/relation declare/retract and topology readback.

src/Capacitor.Cli.Core/Resources/help-mcp.txt

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. ServerInstructions comment too verbose ✓ Resolved 📘 Rule violation ⚙ Maintainability

Description

New multi-line comments were added that restate guidance already conveyed by the
ServerInstructions constant and by the test name plus straightforward assertions, adding noise and
reducing readability/maintainability. This conflicts with the repo guideline (PR Compliance ID 5) to
keep comments concise and avoid redundant narration when the code is self-explanatory.

Code

src/Capacitor.Cli/Commands/McpWorkItemsServer.cs[R130-133]

+    // Server-level usage preamble (MCP `instructions`) — steers agents to DECLARE a work item's
+    // structure, not just attach to it. A work item's breakdown (parent→parts) and dependencies
+    // (blocks/blocked-by) are declared facts, never inferred, so an item whose structure nobody
+    // declares has an empty topology and renders no blockers/dependencies or progress figure.

Evidence

PR Compliance ID 5 calls for concise comments that add only essential context; in
McpWorkItemsServer.cs, the newly added 4-line comment repeats details that are already present
immediately below in the ServerInstructions constant, making it redundant. Similarly, in the new
test, the added multi-line explanatory comment is unnecessary because the test name and the direct
Contains(...) assertions that follow already clearly express the intent, so the comment is longer
than needed and adds verbosity without new information.

CLAUDE.md: Keep code comments concise; prefer self-explanatory code over verbose commentary
src/Capacitor.Cli/Commands/McpWorkItemsServer.cs[130-133]
test/Capacitor.Cli.Tests.Unit/McpWorkItemsServerTests.cs[169-172]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Remove or significantly shorten the newly added multi-line comments that redundantly restate what is already clear from `ServerInstructions` and from the test name/assertions, to align with PR Compliance ID 5’s guidance for concise, non-redundant comments.

## Issue Context
The repo prefers brief comments that explain non-obvious “why” context rather than re-describing “what/how” already expressed by self-explanatory code (e.g., constants, descriptive test names, and direct assertions). These added comments largely repeat adjacent code, increasing maintenance cost and reducing readability.

## Fix Focus Areas
- src/Capacitor.Cli/Commands/McpWorkItemsServer.cs[130-133]
- test/Capacitor.Cli.Tests.Unit/McpWorkItemsServerTests.cs[169-172]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can enable the Remediation agent and Qodo fixes findings in a dedicated fix PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗