Mapwrite

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:

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.