Agent workflow¶
The uncoded skills tell the agent when to load the index, read source, and check references. Once the developer has set uncoded up, the agent follows this workflow during a task.
Start a task¶
The agent runs uncoded sync, so that the index is current. It then loads
.uncoded/namespace.yaml in full to learn the Python symbols that exist. For a
documentation task, it loads .uncoded/docs.yaml to find the relevant file and
heading.
Navigation skills load once per session. Their instructions apply throughout the session.
Read code¶
The agent adds detail only when the task needs it. This progressive disclosure keeps broad work on compact views and limits source reads to the implementations that matter.
- The namespace map shows every indexed symbol and its file. It is often enough for questions about structure or where a feature lives.
- The file's stub under
.uncoded/stubs/adds imports, parameter names and annotations, return types, and assignments. It omits parameter defaults, decorators, docstrings, and function bodies. It is often enough for questions about names and types. uncoded bodyreturns one symbol's exact source when the task needs it:
uv run uncoded body greet --in src/greetings.py
This example assumes greet is defined in src/greetings.py. For a method, use
ClassName/method_name. See the command reference for
supported symbols and paths.
A file with no indexed symbols has no stub, so the agent reads the file directly. Free text and patterns still belong in a text search.
Change a symbol¶
Before renaming, changing a signature, or deleting a symbol, the agent checks its references:
uv run uncoded refs greet --in src/greetings.py
The results identify the sites to inspect and update. After changing indexed
Python or Markdown files, the agent runs uncoded sync before navigating again.
Review consistency¶
With source-roots configured, uncoded also generates a consistency review
skill. It looks for concrete disagreements between names, signatures,
docstrings, and behavior. Every finding must quote both conflicting claims and
show that they describe the same concept.
Invoke it with $uncoded-consistency-review in Codex or
/uncoded-consistency-review in Claude Code.
Know the limits¶
The code index describes static Python structure. It does not run imports or resolve runtime registration. Files that cannot be parsed or decoded are skipped with a warning.
The documentation index records ATX headings. It excludes underlined headings
and headings inside fenced code blocks. Read documentation sections directly;
body and refs operate on Python symbols.
Keep using tests and type checks to verify changes.