| name | codestory-grounding |
| description | Use when an agent should ground a local repository with CodeStory before making source claims, planning edits, choosing tests, reviewing changes, or using broad retrieval evidence through the CodeStory plugin MCP. |
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.
- Resolve the target repository root.
- Call the intended tool with
project=<absolute-root>.
- If the result says
state=preparing, wait for retry_after_ms 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.
- 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
| Situation | Route |
|---|
| Repository orientation | ground; use files for language mix or coverage gaps. |
| Exact named file, path, or static asset with file-local evidence | Inspect it directly. When adding it to a packet, use an exact_path tagged probe; do not run broad grounding merely to rediscover the path. If the task asks about relationships, ownership, or impact, use the corresponding narrow tool. |
| Find a symbol | symbol, then definition or snippet. |
| Follow a call path | callers, callees, trace, or trail. |
| Review change impact | affected with explicit Git-changed paths, then focused symbol or trace evidence. |
| Broad structural question | packet; use search or context for bounded follow-up. |
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 sufficient, answer from the packet and cited anchors.
When it reports partial, run the named follow-up before making proof claims.
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 upgrade packet sufficiency.
- 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
