Project context and navigation

Select and route

Read agent_context/MAP.yaml first. Select navigate (current code facts), read (context), refresh (update a topic), or add (register a topic). Specialized skills such as /add-robot own implementation; use this skill for orientation and context maintenance.

Use the deterministic helper when matching is unclear or needs verification:

python .agents/skills/project-dev-context/scripts/context.py route 'QUERY'

Match a complete topic id first, including an explicitly named id within a request; otherwise match aliases, then keywords. ASCII tokens have boundaries, so sim does not match simready; Chinese phrases support substring matching. Within the first matching alias/keyword tier, prefer the longest matching phrase, then additional distinct matches. Equal best matches remain candidates; never silently choose the first topic in MAP.

For ambiguity, use the request's subsystem/owning path to narrow candidates, or inspect the specific symbol in their source files. If that still leaves different answers, ask one concise clarifying question. For example, SceneManifest belongs to both visualization and Task Program semantics; visualization SceneManifest identifies the visualization topic.

Read progressively

1. Load only the selected topic's paths (the overview).
2. Follow only the overview's detail links relevant to the question. related_topics is navigation metadata, not an automatic load list.
3. For navigation, inspect the relevant symbols in source_of_truth, expanding to callees/tests as needed. A listed directory is a search scope, not a request to read every file. Current code takes precedence over context prose.
4. If nothing matches, use rg --files and rg -n for symbols, flags, config keys, registries and imports. CLI ownership starts in embodichain/cli/ and pyproject.toml; embodichain/__main__.py is an entry wrapper.
5. Do not read docs/source/ unless the user asks for Sphinx documentation.

Do not load writing conventions, this skill's reference schema or agent UI metadata for ordinary reads/navigation. Answer with the owning entry point, resolution path, recommended change site and focused validation when relevant.

Maintain context

For refresh/add, read references/context-system.md and the conventions in defaults.write_contexts. Use current implementation as evidence, not old notes. Keep one owner for each contract and link from other topics. Preserve stable topic ids and overview paths; linked detail pages carry optional depth.

Find topics potentially affected by a code change:

python .agents/skills/project-dev-context/scripts/context.py affected --base origin/main --explain
python .agents/skills/project-dev-context/scripts/context.py affected embodichain/lab/gym/envs/base_env.py

Review affected topics in the same change; this is an impact hint, not proof that prose is stale or that unchanged paths are fresh. Choose no update, revise, or add using conventions/topic-lifecycle.md, and briefly state the outcome in the PR or task result. Edit only guidance or metadata made inaccurate or materially incomplete. Replace/consolidate the owning passage; do not append a PR summary. Add a topic for a requested or recurring missing domain, not automatically for every unmatched lookup.

After editing:

python .agents/skills/project-dev-context/scripts/context.py check
python .agents/skills/project-dev-context/scripts/context.py stats --base origin/main
python -m pytest -q -c /dev/null --noconftest tests/test_agent_context_map.py tests/test_agent_context_tools.py

Validate representative natural-language routes before and after routing changes, including ambiguous and unmatched requests. For content restructuring, follow representative questions from overview to owner and check how much unrelated content must be read. Size/growth statistics are advisory, not a length gate. Thin adapters only point here; they need changes only when their local entry hints change.