---
name: mapwrite
description: Navigate repo-specific wiki protocols, code-index maps, and agent update rules. Use when Codex needs to work in a repository that has `wiki/index.md`, `wiki/code-index/`, `AGENTS.md`, or `CLAUDE.md`; when creating, updating, or following wiki specs/plans; when creating or maintaining nested code indexes; when deciding which project files to read before code changes; or when updating agent-facing project navigation instructions.
---

# Mapwrite

## Purpose

Use this skill to keep project context discovery small, layered, and current. Treat wiki indexes and
code indexes as one navigation workflow with separate artifacts.

## First Pass

1. Read the repo's root agent instructions, usually `AGENTS.md` and/or `CLAUDE.md`.
2. Read `wiki/index.md` when it exists.
3. Read `wiki/code-index/index.md` when it exists and the task touches code.
4. Follow only the relevant narrow spec, plan, or code-index shard.
5. Use `rg` or `rg --files` to verify symbols and files before opening large code files.

Do not read all wiki files, all logs, generated mega-indexes, caches, env files, session data, or
test scratch directories unless the user explicitly asks for that history or artifact.

## Artifact Roles

Keep these responsibilities separate:

- `wiki/index.md`: wiki-only map for specs, plans, shards, runbooks, and high-level knowledge
  documents.
- `wiki/code-index/index.md`: top-level human-readable code navigation map.
- `wiki/code-index/**/*.md`: narrow maps for subsystems, entrypoints, facades, boundaries, and
  related tests.
- `wiki/spec/**/*.md`: behavior and architecture source of truth.
- `wiki/plan/**/*.md`: implementation sequence and acceptance criteria.
- `wiki/log.md`: append-only change history; inspect recent headings or tail only unless a
  historical task requires more.
- `.agent-index/`: optional generated symbol or call-graph helpers, not a substitute for targeted
  reads and `rg` verification.

## Code-Index Protocol

When creating or updating code indexes:

1. Prefer a nested map over one large file.
2. Start with `wiki/code-index/index.md`, then add subsystem shards only as needed.
3. Keep each shard concise and navigational; do not turn it into a behavior spec.
4. Include subsystem purpose, read-first files, entrypoints/facades, boundaries, related tests, and
   common spec/plan links.
5. Add more shards when a parent file becomes too broad.

Recommended shape:

```text
wiki/code-index/
  index.md
  backend.md
  bot.md
  tests.md
  scripts.md
  alembic.md
  backend/
    api.md
    services.md
    workers.md
    db.md
  bot/
    engagement.md
    search.md
    accounts.md
    formatting.md
```

## Generated Index Policy

Generated symbol indexes are optional helper artifacts. Keep them outside the human-authored wiki
maps, preferably under `.agent-index/`, and exclude:

- `wiki/llm-wiki.md`
- `wiki/llm-wiki-md.txt`
- `wiki/log.md`
- `.claude/`
- env files
- sessions, data volumes, caches, and pytest scratch directories

Never rely on generated indexes alone before editing. Verify with `rg` and targeted file reads.

## After Changes

Update only the artifacts whose responsibility changed:

- Update `wiki/index.md` when specs, plans, shard directories, runbooks, or code-index entrypoints
  change.
- Update the relevant `wiki/code-index/` shard when code files, ownership boundaries, facades,
  entrypoints, or related test maps change.
- Update relevant specs only when behavior or architecture changed.
- Append `wiki/log.md` for code or wiki changes.
- Run the repo's local validation gates from `AGENTS.md` or `CLAUDE.md`; if a gate cannot run, note
  why in the handoff and, when required by the repo, in `wiki/log.md`.