lore-init

Lore Init

Read ${CLAUDE_PLUGIN_ROOT}/reference/lore-spec.md before doing anything — it defines the structure, frontmatter, and entry meta you will create. The seed files you copy live in ${CLAUDE_PLUGIN_ROOT}/reference/templates/.

When to use

• The project has no docs/lore/ yet and you want to bootstrap one.
• The user asks to initialize, bootstrap, or set up project lore.

If docs/lore/ already exists, do NOT overwrite it. Switch to augment-mode: add only the missing core files and report what you added.

Procedure

1. Detect existing lore. Check whether docs/lore/ already exists. If it does, switch to augment-mode — add only missing core files (README.md, an area's pitfalls.md / business-rules.md) and never clobber anything that is already there.
2. Infer the project type. Decide whether this is a frontend app, a backend service, a library, or a CLI. Use that to judge whether api-map.md is worth seeding (it pays off for API-heavy projects). When you are unsure, ask the user instead of guessing. If you still can't tell and the user doesn't answer, fall back to the safe minimum: scaffold only the core files and skip api-map.md and architecture/.
3. Infer the initial areas. Look at the codebase's top-level domains or subsystems and propose one or two starter areas (for example payments/, auth/). Confirm the list with the user before creating anything. Never create areas without explicit confirmation — if the user doesn't respond, propose them and stop there, don't create them. While confirming, also ask which area (if any) is the project's core — the part that makes it worth building — and mark it in the Areas table's Core column only on explicit confirmation (see lore-spec's Core areas).
4. Create from the templates in ${CLAUDE_PLUGIN_ROOT}/reference/templates/:
   • docs/lore/README.md from README.md.tmpl — fill the Areas table with the areas you chose.
   • For each starter area, docs/lore/<area>/pitfalls.md and docs/lore/<area>/business-rules.md from pitfalls.md.tmpl and business-rules.md.tmpl, replacing the <AREA> placeholder with the real area name.
   • Optionally docs/lore/api-map.md from api-map.md.tmpl and/or docs/lore/architecture/index.md from architecture-index.md.tmpl, only when the project type warrants them.
5. Check the glossary — but never scaffold it here. Resolve the glossary per lore-spec: if a root CONTEXT.md / CONTEXT-MAP.md exists, the vocabulary already lives there — report it as the project's canonical glossary and skip the lore-ul suggestion below. Otherwise look for docs/lore/glossary.md. Per lore-spec it is created lazily, the moment the first term is agreed with the user via lore-ul — never templated in bulk at init time, since terms must be user-confirmed, not generated. If it's missing (true for both a fresh scaffold and an existing base you're augmenting), say so plainly in your report and suggest running lore:lore-ul whenever the user wants to start aligning vocabulary. This is a report line, not an action — do not create the file yourself.
6. Wire up the trigger. Offer to add a one-line lore pointer to the project's CLAUDE.md (or AGENTS.md) yourself — for example: "Project lore lives in docs/lore/ — consult it before planning or bug-fixing, guard diffs against it before committing, and capture implicit knowledge into it." Add it on the user's confirmation; if they decline, just show them the line to paste. The plugin's SessionStart hook already nudges toward the lore skills in repos that have docs/lore/, but the pointer makes triggering robust for teammates and agents running without the plugin installed.

Guardrail

This skill is idempotent: never overwrite existing content. Running it on a project that already has lore should only fill in missing core files, and it should report exactly what it added.

Note on content

What you scaffold is generic structure, not real knowledge. The areas start empty — the user fills them with actual lore later via lore-capture.