oh-my-opencode-slim/src/skills/codemap/codemap.md

src/skills/codemap/

Responsibility

• Provide a command-style skill package that standardizes repository mapping workflows for unfamiliar codebases.
• Define the task contract used by Orchestrator/fixer agents via SKILL.md and operational guidance via README.md.
• Generate and evolve change-aware codemap state artifacts (.slim/codemap.json) and scaffold placeholders (codemap.md).

Design

• Contract layer: SKILL.md (machine prompt contract) + README.md (human-facing operation notes).
• Execution layer: scripts/codemap.mjs exports deterministic helper functions:
  • parseArgs(argv)
  • cmdInit, cmdChanges, cmdUpdate
  • selectFiles, computeFileHash, computeFolderHash, createEmptyCodemap
  • loadState, saveState, migrateLegacyState
• Persistence model: JSON state at .slim/codemap.json with metadata, file_hashes, and folder_hashes.
• Testing layer: scripts/codemap.test.ts validates pattern matching, hash determinism, and migration behavior.
• The script intentionally avoids network and mutates only filesystem-local state and codemap templates.

Flow

• Entry point main(argv) parses command and arguments (init|changes|update, --root, --include, --exclude, --exception) and dispatches via strict branches.
• cmdInit() computes include/exclude candidate sets using selectFiles() and writes: 1) .slim/codemap.json via saveState() 2) one codemap.md per discovered folder via createEmptyCodemap().
• cmdChanges() reloads state (loadState() + migrateLegacyState()), recomputes current hashes, emits added/removed/modified diffs and affected folder list, and exits non-zero if state is absent.
• cmdUpdate() recomputes full state from existing metadata and persists it, used after targeted fixers finish updates.
• codemap skill invocation path in SKILL workflow is explicit: Step 1 checks .slim/codemap.json or .slim/cartography.json, then Step 2/3 selects init or incremental path.

Integration

• Installed under OpenCode through src/cli/custom-skills.ts as name: 'codemap', sourcePath: 'src/skills/codemap'.
• src/cli/install.ts copies this directory into the user skill directory; OpenCode executes scripts/codemap.mjs from that context.
• src/hooks/filter-available-skills/index.ts applies agent-level skill gating via names from getSkillPermissionsForAgent().
• scripts/verify-release-artifact.ts includes codemap skill metadata and runtime checks as required packaged files.