transmute-lore

name

transmute-lore

description

Operate a project's body of criteria in five modes — migrate scattered criteria to the six-artifact Lore standard (ADD); remove project copies of criteria already owned by its area (CLEAN); standardize language without changing meaning (TRANSLATE); arbitrate healthy Lore against a newer kit and raise it without rewriting earned criterion (UPGRADE); or generate a safe, traceable single-Markdown snapshot for chats, AI projects and notebooks without replacing the live artifacts (CRYSTALLIZE). Trigger on requests to transmute, migrate, clean, translate, upgrade, bring Lore up to date, crystallize Lore, export Lore to one Markdown, or prepare Lore as a chat/notebook source.

Transmute Lore

Operates a project's body of criteria. Five modes, one skill:

• ADD — the project never applied the Lore method (or has a rough/incomplete lore/). Valuable criteria is trapped in non-distillable forms: long READMEs, an everything-mixed CLAUDE.md, comments, tacit knowledge. ADD extracts it and lifts it to the six-artifact standard without losing it and without inventing what never existed.
• CLEAN — the project already has the standard, but carries per-project copies of thematic modules that duplicate what its area already owns. CLEAN removes those modules, keeps identidad.md / principios.md / index.md, and rewrites index.md to point at the area's modules — but only after confirming that criteria already lives in the area (or reporting it if it does not).
• TRANSLATE — the Lore exists but its language is mixed or wrong (e.g. artifacts generated in English when the user works in Spanish). TRANSLATE standardizes every Lore artifact into one target language — content and localizable filenames — preserving structure, link integrity, confidence markers and — above all — meaning: it is a translation, never a rewrite.
• UPGRADE — the Lore is in the standard and in active use, but was written against an older version of these skills. It is structurally fine and materially behind: it lacks the gates and distinctions the kit learned after it was written. UPGRADE arbitrates the existing Lore against the current version of the kit and raises it, without rewriting what is already earned.
• CRYSTALLIZE — the Lore is healthy and must travel as a single Markdown derivative into a chat, an AI project, or a notebook such as NotebookLM. It resolves the live routing into one traceable snapshot while leaving every source untouched. It does not replace the six live artifacts and is not the normal format for work inside an agent or IDE that can read the tree.

When to use

• ADD: a project with real criteria but no standard structure — no lore/identidad.md or lore/principios.md, state living inline in CLAUDE.md, or an incomplete/stale lore/. Triggers: "transmute the lore of {project}", "this old project isn't in the new format", "migrate this project to the lore standard".
• CLEAN: a project inside an area that has redundant thematic modules (e.g. its own lore/animation.md identical to the area's). Trigger: "clean the lore of {project}".
• TRANSLATE: a Lore whose content is in the wrong language, or mixes languages across artifacts. Triggers: "standardize the language of the lore of {project}", "translate the lore of {project} to {language}", "estandariza el idioma del lore".
• UPGRADE: a healthy Lore that predates the installed version of the kit — nothing looks broken, which is the point. Triggers: "improve the lore of {project} with the new version", "bring this lore up to date with the plugin", "arbitra mi lore contra la versión nueva", "mejora este lore con lo nuevo del plugin". Also the natural next step right after updating the plugin.
• CRYSTALLIZE: a project or bot whose routed criteria must be attached to a chat, AI project, or notebook as one .md. Triggers: "crystallize this Lore", "export this Lore to one Markdown", "prepare this bot as a ChatGPT source", "cristaliza el lore en un solo archivo".

Detect the area: a project living in {area}/proyectos/{name}/ inherits from {area}/lore/. If the project is standalone (no parent area), CLEAN does not apply — say so.

Target — the six-artifact standard

Artifact	Holds	Location
identidad.md	What the project is, its purpose, its quality floor (the north star).	lore/
principios.md	Invariant laws (technical + business): prohibitions and imperatives.	lore/
Thematic modules	Technical scars by topic (animation, layout, scroll…) as clues.	lore/
index.md	Navigation map of the lore: one line per pattern.	lore/
FASES.md	The project's state and plan (current phase, focus). Outside lore/.	root
CLAUDE.md	The contract slimmed to pointers (no duplicated criteria).	root

No logos.md is generated. That is specific to research projects, not the generic standard.

Artifact names are localized. The names above are the Spanish canonical forms; per the kit's language rule they render in the user's language (e.g. English: identity.md, principles.md, PHASES.md). Fixed in every language: CLAUDE.md, lore/, index.md, golden-paths.md. Inside an existing corpus, its established names win.

---

ADD mode — procedure (7 phases · single gate with content in view)

Phase 0 — Safety precondition

Run git status in the target repo. If there are uncommitted changes, stop and ask the user to commit or stash first. Reason: the transmutation must land as a clean, reviewable diff. If the project is not a git repo, warn (no diff safety net) and ask to confirm before continuing.

Phase 1 — Diagnosis

Inventory the existing sources of criteria and their state:

• CLAUDE.md / AGENTS.md — often the biggest deposit of mixed criteria.
• README.md, PROJECT.md, loose docs at the root.
• Old lore/ (if any) — assess format and currency.
• incidents/, design/, reports/, soluciones.md — scars and decisions.
• GOLDEN_PATHS.md / equivalent — critical paths.
• Code comments carrying criteria (grep for "never", "always", "WARNING", "NO ", "hack", "workaround" and their localized equivalents).
• Free notes about this project — an Obsidian inbox at the vault root, a folder of Markdown, meeting minutes. They are source like any other, and most of what they hold is information rather than criteria: keep only what constrains a future decision, and report the rest as discarded. If the inbox is large, obsidian-lore sweeps it and hands over what is distillable.

Report what exists, where, and in what state (current / stale / narrative).

Binaries: check before extracting, and leave a trace after

A .pdf, .docx or .xlsx in the sources looks like pending work forever, because a binary that has already been transcribed is indistinguishable from one that has not. Transmutation writes the .md under the name the content deserves and leaves the binary exactly where it was, extension intact and nothing recording the correspondence — so the only evidence is the resemblance between two texts whose filenames do not resemble each other at all.

• Before extracting one, compare its text against the .md corpus already there. Normalizing whitespace and measuring literal overlap in chunks is enough and costs seconds. High overlap means it was already transcribed: report it and do not extract it again.
• When you do transcribe one, record the correspondence in the destination — one line in the corpus index.md, or in the header of the generated .md, naming the binary it came from. That single line is what prevents the whole pending item from being written in the first place.
• Write pending extraction items by content, never by extension. «Extract the binaries» sends the next person to redo work that is done; «extract what is not yet in the corpus» does not.

Boundary: this applies to a corpus that has been through a prior distillation — in one that has not, there is nothing to compare against and every extraction is real work. Literal comparison catches faithful transcriptions; a deep rewrite of the same content can fall under the threshold, so low overlap does not prove the material is new.

Phase 2 — Criteria extraction

Walk the sources separating criteria from noise with the heuristics below. Criteria is anything that constrains a future decision. Noise is descriptive and constrains nothing.

Phase 3 — Classification by destination

Criteria type	Destination
Purpose, what the project is, quality floor, aesthetic standard	identidad.md
Invariant laws: prohibitions/imperatives (technical and business)	principios.md
Technical scar by topic (bug → cause → fix)	module lore/<topic>.md (clue)
State, current phase, work focus, active branch	FASES.md
Critical paths / mandatory verification	golden-paths.md (if applicable)
Stack, folder structure, navigation map	CLAUDE.md (pointers/reference)
Descriptive with no constraint	discard (reported, see invariants)

Area-aware routing: if the project belongs to an area, a generic thematic clue that the area already owns does NOT get copied into the project — the project's index.md points to the area's module instead. Only project-specific scars become project-local modules.

Phase 4 — Rewrite to target format

• Scars → invariant clue: Context → Probable cause → Clue → Confidence (confirmed/conjecture).
• Laws → imperative lines in principios.md, grouped (technical / business).
• Purpose + quality floor → identidad.md in brief prose (what we are, what we are NOT, the north).
• State → FASES.md with the current phase and focus.
• Index → index.md, one line per pattern (topic · symptom · confidence · file), area modules linked by relative path (../../../lore/<topic>.md).

Phase 5 — HARD-GATE

Do not write yet. Present one mapping document containing:

1. The real proposed content of each new artifact (not just a routing table).
2. What changes in CLAUDE.md (what moves to lore, what stays as a pointer).
3. The discarded-noise report, justified piece by piece.
4. Any discrepancy found between old lore/docs and the code or the user's description.

Wait for explicit approval before writing.

Phase 6 — Writing (only after approval)

Create the artifacts, slim CLAUDE.md to pointers, build/update index.md. Do not overwrite old lore/ without surfacing discrepancies: if old content contradicts current code or the user's words, report it instead of proceeding blind.

Phase 7 — Final report

Summarize: what was transmuted (by artifact), what was discarded as noise (justified), and the diff summary. Do not commit the target project — the diff stays for the user to review and commit.

---

CLEAN mode — procedure

Phase 0 — Safety precondition

Same as ADD: require a clean git tree (or warn if not a repo). The cleanup must be a reviewable diff.

Phase 1 — Locate the area and compare

1. Resolve the parent area: the project is at {area}/proyectos/{name}/; the area lore is {area}/lore/. If there is no parent area, stop — CLEAN does not apply.
2. List the project's thematic modules (everything in the project's lore/ except identidad.md, principios.md, index.md).
3. For each project module, compare against the area's counterpart ({area}/lore/<topic>.md):
   • Every clue in the project module already present in the area module → redundant, removable.
   • Any clue not in the area → project-specific (or not yet promoted). Do not delete it. Report it so the user can decide (keep as project module, or promote to the area first).

Phase 2 — HARD-GATE

Present: which modules will be removed (fully redundant with the area), which are kept (and why), and the exact rewritten index.md pointing to the area modules. Wait for explicit approval.

Phase 3 — Clean (only after approval)

• Delete the fully-redundant project thematic modules. Never delete identidad.md, principios.md, or index.md.
• Rewrite index.md: entries for area-owned topics link to ../../../lore/<topic>.md; entries for any kept project-specific module keep their local link.

  Three ../, not two: index.md sits in {area}/proyectos/{slug}/lore/, so the area is three levels up. Verify each rewritten link resolves to a real file in {area}/lore/.

• Leave identidad.md / principios.md untouched (they carry the project's own layer).

Phase 4 — Final report

Report what was removed, what was kept and why, any clue that was NOT in the area (so nothing is lost silently), and the diff summary. Do not commit.

---

TRANSLATE mode — procedure

Standardizes the language of the Lore's content. It translates; it never restructures, adds, or drops criteria. If while translating you spot a structural problem, report it and propose ADD/CLEAN as a separate pass.

Phase 0 — Safety precondition

Same as ADD/CLEAN: require a clean git tree (or warn if not a repo) so the translation lands as a reviewable diff.

Phase 1 — Language inventory

1. Resolve the target language: the one the user asked for; if unstated, the user's own language (the one they are speaking in).
2. Scan the scope's artifacts — lore/*.md, FASES.md, CLAUDE.md, golden-paths.md if present — and record each file's current language (or "mixed").
3. Scope boundary: translating a project does NOT touch its area's lore/; translating an area does NOT touch its projects. If the other level is in a different language, report the mismatch and let the user decide whether to run TRANSLATE there too.

Phase 2 — HARD-GATE

Present the plan before writing: file-by-file current language → target, including renames — localizable artifact names move to the target language too (e.g. identidad.md ↔ identity.md, principios.md ↔ principles.md, FASES.md ↔ PHASES.md, proyectos/ ↔ projects/, fuente/ ↔ source/, thematic modules) — plus what will NOT be translated or renamed:

• the fixed names: CLAUDE.md, lore/, index.md, golden-paths.md, _starter/;
• code blocks, identifiers, commands, quoted error messages / log excerpts;
• confidence markers (conjecture / confirmed) and the promotion glyph · ↑;
• English terms of general technical use (workflow, commit, stack, scaffold…);
• proper nouns and brand names.

Renaming proyectos/ (or moving anything referenced outside the scope) is opt-in: propose it, but only include it if the user accepts — external references (other repos' FASES rows, scripts) may point at the old path.

Wait for explicit approval.

Phase 3 — Translate (only after approval)

Translate each file's prose to the target language, preserving Markdown structure (headings, tables, list shapes) line-for-line where possible. Apply the approved renames with git mv and rewrite every link that touches a renamed file — in the scope's index.md, CLAUDE.md, cross-references between artifacts, and inherited-path links. Meaning-preserving above all: a clue's constraint must survive translation intact — when a nuance is ambiguous, flag it in the report instead of guessing.

Link integrity crosses the scope boundary even though translation does not: when translating an area, grep its projects' lore files for links into any renamed area file and update those links too (or report them if the projects cannot be touched).

Phase 4 — Final report

Report files translated (with source language), files renamed (old → new), links rewritten, files skipped and why, any nuance flagged for human review, and the diff summary. Do not commit — the user reviews the diff and decides.

---

UPGRADE mode — procedure

The premise: these skills accumulate scars. A Lore written against an older version is structurally correct and materially behind — it never got the chance to carry defeats that were paid for after it was written. Nothing about it looks wrong, which is exactly why nobody upgrades it.

What this mode is not: it is not a rewrite, not a style pass, and not an excuse to regenerate a Lore that works. A clue that was earned with real friction outranks any improvement the kit learned later. The upgrade adds what is missing and marks what is now known to be wrong; it does not relitigate what the project already paid for.

Phase 0 — Safety precondition

Inspect git status and report whether the tree is clean, but do not stop the diagnosis. UPGRADE is useful before the user is ready to write: it can read, arbitrate and present the full HARD-GATE in a dirty or read-only tree. A clean tree is a precondition for Phase 4 (writing), not for Phases 1–3. If the target is not a repository, warn that there will be no diff safety net.

Phase 1 — Establish both versions

• Installed version: read it from the active plugin manifest (.claude-plugin/plugin.json, .codex-plugin/plugin.json, or the equivalent manifest used by the current agent). If the installed copy is stale, stop and say so: upgrading a Lore against an outdated kit writes yesterday's standard into it and marks it as done. Update first.
• The Lore's version: it is usually not written down. Infer it from what the artifacts carry — presence of confidence markers, validity boundaries, the · ↑ promotion glyph, the index line format, whether imported modules declare provenance and defeats.

Report both, and say plainly when the second is a guess.

Phase 2 — Arbitrate the existing Lore against the current kit

Before the artifact pass, detect a local notas/ or notes/ inbox. If one exists, invoke obsidian-lore to report its debt and mine it through its own HARD-GATE. The notes stay in their inbox after mining; they are source and provenance, never migration debris. UPGRADE must not move, delete or absorb them into lore/.

Go artifact by artifact and produce a finding list. Each finding is one of exactly three kinds, and naming the kind is what keeps this from becoming a rewrite:

Kind	What it means	What it produces
Missing	The kit now requires something this artifact never had (a validity boundary, a confidence marker, a defeats section on an imported module, a provenance header).	Add it — asking the user for anything not derivable from the text. Never fabricate a boundary.
Superseded	The kit now knows this practice is wrong (e.g. a fact duplicated across artifacts, a rule stated by category rather than by condition, a module copied from an area).	Propose the correction, citing which rule supersedes it.
Earned	It departs from the current standard because this project paid for it.	Leave it, and write down why so the next upgrade does not flag it again.

The third row is the one that makes the mode safe. A finding list with no Earned entries in a Lore with real history is a sign the pass is being run as a formatter.

Phase 3 — HARD-GATE

Show the full finding list with content in view: file, kind, what changes, and what rule of the current version demands it. Nothing is written before approval. The user can accept per finding.

Phase 4 — Upgrade (only after approval)

Re-check git status now. Require a clean tree before the first write so the upgrade lands as a reviewable diff. If it is dirty, keep the approved findings intact, report the blocker and stop before modifying anything; do not force the user to repeat the diagnosis.

Apply the accepted findings. Two limits that do not move:

• Confidence is never raised. A conjecture that survived three versions is still a conjecture: time is not validation. Only real friction promotes it.
• A missing boundary is asked, never inferred. The boundary says where the clue stops being true, and that is knowledge from whoever lived it. If the user does not know it either, the clue is marked as boundary-less rather than given a plausible one.

Phase 5 — Final report

Report per kind: what was added, what was corrected, what was left as Earned and why, and what was left pending because only the user could answer it. Record the version upgraded to, in the project's FASES.md — not in the Lore. Do not commit.

---

CRYSTALLIZE mode — procedure

The premise: some destinations can accept one attached Markdown but cannot navigate a live folder tree. CRYSTALLIZE resolves the project's routing into a portable reading copy. The source remains authoritative; the derivative never becomes a second Lore to maintain.

Phase 0 — Resolve target and destination

Identify whether the target is a project, area, or bot and where the derivative will be used: a chat, an AI project, a notebook, or another Markdown-only reader. Default to a localized filename such as lore-crystallized.md / lore-cristalizado.md at a user-approved export location, not inside lore/.

CRYSTALLIZE does not replace the six live artifacts. It writes no source artifact and never changes CLAUDE.md, FASES.md, lore/, a bot's canon, or any federated source.

Phase 1 — Resolve the live routing

Read in this order and record every resolved path:

1. the target contract (CLAUDE.md or the bot's equivalent);
2. FASES.md or the target's current state artifact;
3. lore/index.md, identity, and principles;
4. thematic modules routed by the index, including inherited area modules;
5. for a federated bot, its routing table and the exact canon/Lore sources it points to.

Follow links to their owners rather than copying adjacent files by directory. Deduplicate the same source reached through multiple routes and preserve ownership in the resulting headings.

Phase 2 — Apply the privacy boundary

Exclude by default conversations, secrets, ignored files, undistilled notes, environment files, credentials, private histories, caches, and any corpus or directory not explicitly routed by the target's contract. An ignored file is excluded even when a routed directory contains it.

For research or personal bots, do not infer that a conversation is safe because it is Markdown. Public corpus and private continuity are different sources. If the user wants an excluded source included, name it separately in the preview and require explicit approval for that source.

If a source carries its own visibility or distribution rule, that rule outranks convenience. A source that cannot be redistributed is represented only by a notice that it was omitted.

Phase 3 — Build the preview and HARD-GATE

Before writing, present:

• destination path and intended platform;
• the exact source manifest, in output order, with owner and resolved path;
• every excluded category found and its count;
• any source whose visibility is uncertain;
• the proposed title and section outline;
• whether an existing derivative would be overwritten.

Wait for explicit approval. Approval to crystallize the normal route does not approve an uncertain or private source. If the destination already exists, show that fact and obtain overwrite approval; otherwise choose a new filename.

Phase 4 — Compose the derivative

Write one Markdown in this order:

1. title and target identity;
2. a warning that this is a generated reading copy;
3. generation date, source root, intended destination, and exact source manifest;
4. purpose and quality north;
5. principles;
6. routed thematic criterion, grouped by owner and original file;
7. current state from FASES.md, clearly labeled as volatile state rather than Lore;
8. bot routing/canon instructions when applicable;
9. omissions and privacy boundary;
10. regeneration notice.

Preserve the source language and substantive content. Normalize heading levels only so the combined file remains navigable. Do not summarize away examples, confidence markers, defeats, validity boundaries, or provenance: those are what let criterion participate rather than merely be named.

The header must say plainly: this snapshot may become stale. It must direct the reader back to the live project tree for updates and warn agents not to write changes back into the derivative.

Phase 5 — Verify and report

• Compare source hashes or byte counts before and after: CRYSTALLIZE writes no source artifact.
• Confirm every manifest entry has one corresponding section or an explicit omission notice.
• Scan the derivative for excluded filenames and known secret markers before reporting success.
• Confirm links that only made sense inside the tree are either expanded with source context or labeled as non-portable; do not leave silent broken navigation.
• Report output path, size, source count, excluded count, and the command/request needed to regenerate it. Do not commit.

---

Criteria-extraction heuristics (ADD)

Signals of CRITERIA (enters the corpus):

• Imperatives and prohibitions: "never", "always", "mandatory", "do not use", "without exception".
• Concrete values with a reason: "#60A0FF in dark because #0057FF is illegible".
• Scars: a bug with its cause and fix (even in incidents/ or comments).
• Quality standard: "the approved landing is the floor", "Awwwards level".
• Justified decisions: any claim with a "because" that binds a future decision.

Signals of NOISE (does not enter principios/identidad; stays as descriptive doc or is discarded):

• Description of what a component does without constraining anything.
• Folder-structure and stack inventories → CLAUDE.md as reference, not principios.md.
• Historical narrative with no criteria ("first we tried X, then Y").
• One-off process instructions already completed.

Cutting rule: if a sentence changes no future decision, it is not invariant criteria.

Invariants

• Criteria is never invented. Only already-scattered criteria is transmuted. An artifact that would be empty because the project lacks that criteria stays minimal and says so — never padded.
• A transcribed binary is not told apart by its extension. Compare a binary's text against the existing corpus before extracting it, and when transcribing one, record the correspondence binary → transcription in the destination. Pending extraction items are written by content, not by file type.
• Discarded noise is reported, not silently deleted (filter transparency).
• Clean tree gates writing, not diagnosis: ADD/CLEAN/TRANSLATE keep their existing Phase 0 precondition; UPGRADE may diagnose and present its HARD-GATE in a dirty/read-only tree, then requires a clean tree immediately before applying the approved findings.
• Free notes survive transmutation. A notas/ / notes/ inbox is mined by obsidian-lore, receives traceable frontmatter, and remains in place. No transmute mode deletes it as cleanup.
• Do not overwrite old lore/docs without surfacing discrepancies with code or the description.
• HARD-GATE: present the mapping with content in view and wait for approval before writing.
• Do not auto-commit the target project. The user reviews the diff and decides.
• CLEAN never deletes identidad.md / principios.md / index.md — only thematic modules, and only after confirming their criteria already lives in the area (otherwise reported, not deleted).
• ADD writes new artifacts in the user's language — content and filenames (fixed names CLAUDE.md / lore/ / index.md / golden-paths.md and general technical English terms excluded) — never in English just because this skill is.
• TRANSLATE is meaning-preserving: it changes the language of content and localizable filenames, never the criteria or the structure, and never leaves a broken link behind. Ambiguous nuances are flagged, not guessed.
• CRYSTALLIZE is a derivative, never authority. It follows routed owners, excludes private and unrouted material by default, writes no source artifact, and declares that its snapshot may become stale. Regenerate it from the live tree instead of editing it as Lore.