Codestory Grounding

CodeStory Grounding

CodeStory keeps a local repository map and broad-search index so agents can reach useful evidence without rediscovering the same code every turn.

The target is always the repository being grounded. Pass its exact absolute root as project on every CodeStory call. Never rely on a global active workspace.

Direct Tool Loop

Call the tool that matches the task. Do not call status first.

Using this skill does not require an MCP call when the requested work is fully local to an already named evidence surface—for example, inspecting or editing the content of assets/desk.svg. Inspect that surface directly. Naming a path does not make the evidence surface complete when the task asks about ownership, dependencies, runtime behavior, architecture, change impact, or another claim whose evidence extends beyond the file. For those tasks, select the narrowest CodeStory tool that can add evidence; do not call broad ground as a pre-edit ceremony.

1. Resolve the target repository root.
2. Call the intended tool with project=<absolute-root>.
3. If the result says state=preparing or state=updating and includes retry_after_ms, wait for that delay and retry the same tool with the same arguments. The delay tracks observed preparation progress, so honor the reported value instead of a fixed poll interval. Do not poll status or ask the user to set up CodeStory.
4. Preserve cited anchors in source claims. Read focused source only for the remaining evidence gaps.

CodeStory prepares its local repository map and shared per-user retrieval server automatically. status and the project-bound codestory://status{?project} resource are optional diagnostics for a failed or unexpectedly slow request, not prerequisites for normal grounding.

If CodeStory tools are hidden and deferred discovery is available, search only for the intended tool, for example codestory mcp packet, then call it directly. If the plugin MCP is unavailable, use ordinary source inspection and report the visibility gap. Do not substitute CLI diagnostics for a live plugin result unless the user explicitly asks.

Task Router

Evidence Rules

• Treat CodeStory output as evidence, not omniscience.
• An irrelevant CodeStory call adds no evidence. Skipping one for a complete, file-local surface is a valid use of this router; do not report that as plugin unavailability.
• Local repository-map output is navigation evidence. Broad packet/search output is stronger only when the response reports full retrieval readiness.
• When packet reports supported, not_established, or unavailable, stop. For supported, answer from the compiled support units. For not_established, answer every claim those units directly establish, then name the material links or claims that remain unproven; do not turn a partial chain into a complete one. For unavailable, report the typed preparation reason. Do not search to recover.
• When packet reports drill_once, call packet once more with the exact original question, parent_packet_id, and the listed option_ids (and the pinned generation ids when present). Then answer. Do not start a free-form search / context / trail / snippet loop from packet.
• affected is planning evidence, not a guarantee that every runtime effect was found.
• Tagged probes select exact or additional evidence work. They do not choose route order or replace the packet disposition.
• Do not paste empty grounding output as context. If a repository truly has no supported files, fall back to ordinary inspection or resolve the intended root when it is ambiguous.

Failure Handling

• preparing: retry the same tool after its delay.
• updating: the last complete repository map remains usable; retry the same tool when current publication evidence is required.
• working_locally: use local navigation while broad search prepares.
• unavailable: use ordinary source inspection and report that CodeStory was unavailable for this task.

Maintainer commands such as doctor, ready, and retrieval status are debug transcript tools. They do not prove that the installed plugin is live in the agent host.

setup.ps1 and setup.sh under this skill are build-from-source paths for contributors, not normal installation steps.

References

• Generated MCP syntax is the agent argument source of truth. Do not send CLI flags as MCP fields.
• status contract
• repository map
• files
• affected
• packet
• search
• context
• symbols
• trails
• snippets

Maintainer CLI --help lives in generated CLI syntax and is not an MCP calling convention.