playbook/antigravity-awesome-skills/skills/lore/WORKFLOWS.md

Workflows

lore has seven workflows. This document explains when to use each one, in plain language. For the operational specification the agent follows when running them, see SKILL.md.

中文版

Overview

Workflow	What it does	Frequency
init	Set up .lore/ and platform mirror files	Once per project
sync	Update .lore/ after a code change	After each feature
query	Search .lore/ for an answer	Every session
audit	Find stale or contradictory entries	Quarterly
compress	Rebuild SUMMARY.md	When SUMMARY is stale
mirror	Regenerate platform files from .lore/	After batch of syncs
history	Show git commits for an entry / file / scope	When investigating

---

init

One-line: Create .lore/ and take over your existing CLAUDE.md / AGENTS.md.

When you say it: "lore init" — once per project, or when adding lore to a project that already has platform files.

What happens:

1. Agent scans for existing platform files (CLAUDE.md, AGENTS.md, .cursorrules, etc.)
2. For each file found, asks you: take over / preserve / abort
3. Detects monorepo structure (pnpm workspaces, Cargo workspace, etc.) and proposes scope list
4. Writes initial .lore/ draft (entries with #added:<today> + deterministic IDs)
5. Shows you a summary of what will be created
6. On your confirm: moves draft to .lore/, generates SUMMARY.md, refreshes platform files

Real scenarios:

• New project, first time using lore → lore init
• Old project already has CLAUDE.md, want lore to manage it → lore init and take over
• Monorepo with separate frontend/ and backend/ → init detects both, asks for scope names

Output: Full .lore/ directory + updated platform files + populated .config.json.

---

sync

One-line: After a code change, update .lore/ with what changed.

When you say it: "lore sync" — after committing a feature, refactor, or new dependency.

What happens:

1. Agent runs git diff --stat HEAD to see what changed
2. If changes are significant (≥50 lines / ≥2 dirs, or new module/dir/dep), agent proactively proposes
3. For each change, agent classifies it as [NEW] / [STALE] / [REFINED]
4. Emits a proposal with markers
5. You accept or reject per marker
6. Accepted markers get applied to .lore/*.md

Real scenarios:

• "I just added a new dependency — update lore" → lore sync
• "We decided to stop using React Query, switch to SWR" → lore sync after the code change
• "There's a new module — capture it" → lore sync

Output: Updated .lore/*.md files with new entries (and #verified / #stale tags where appropriate).

Note: sync does NOT update platform mirror files (that's a separate mirror command). Reason: keeps git log of agent-facing files readable.

---

query

One-line: Search .lore/ for an answer to a question.

When you say it: "lore query " — any time you want to know what's in memory.

What happens:

1. Agent reads .lore/SUMMARY.md (the table of contents)
2. Fuzzy matches your query against entries
3. Returns matched entries with stable [file#ID] references
4. Optionally drills into specific scope files for more detail

Real scenarios:

• "What database does this project use?" → lore query database
• "Why did we pick Zustand?" → lore query zustand
• "What are the conventions for backend modules?" → lore query backend:conventions

Output: Bounded list of matched entries:

[_global/DECISIONS.md#DEC-2026-07-11-6137] Picked OpenAI-compatible LLM API
[scopes/backend/CONVENTIONS.md#CONV-2026-07-11-9b89] Embedding has two backends

The [file#ID] reference lets the agent cat the file for full text.

---

audit

One-line: Find stale or contradictory entries in .lore/.

When you say it: "lore audit" — quarterly review, or before a big refactor.

What happens:

1. Runs find_stale.py to find entries with #added > 90 days ago and no #verified
2. Runs find_duplicates.py to find entries that contradict each other
3. Cross-checks entry-referenced code paths against current filesystem
4. Emits an [ALERT] report

Real scenarios:

• "Are there any lore entries that contradict the current code?" → lore audit
• Quarterly hygiene check → lore audit
• Before onboarding a new contributor → lore audit to clean up stale entries

Output: A report grouped by issue type:

[ALERT] 5 entries may be stale (no #verified in >90 days):
  - ARCH-2026-01-15-d7a3  last verified 2026-04-12
  ...

[ALERT] 2 entries contradict current code:
  - CONV-2026-03-01-1f8c  says "use webpack"; project now uses Vite

Note: audit does NOT modify files. To act on findings, run sync with proposal-driven updates.

---

compress

One-line: Rebuild .lore/SUMMARY.md from current entries.

When you say it: "lore compress" — when SUMMARY is stale (entries > 500, or > 30 days since last compress), or before sharing lore with someone new.

What happens:

1. Enumerates all entries via list_entries.py
2. Skips recently-stale entries
3. For each (scope, layer) pair, picks 3–5 most important entries
4. Writes SUMMARY.md per template
5. If auto_mirror: true in config, regenerates platform mirrors; otherwise asks per target and only writes the ones you accept. (This is the second mirror update trigger — sync deliberately does not regenerate mirrors.)
6. Stops after mirror regeneration has either written or been declined per target.

Real scenarios:

• "Refresh the summary" → lore compress
• "I haven't compressed in 2 months" → lore compress
• "Onboard a new contributor — make sure SUMMARY is fresh" → lore compress

Output: Updated SUMMARY.md (and possibly mirror files).

Idempotent: Running twice produces the same result (modulo date stamp).

---

mirror

One-line: Regenerate platform files (CLAUDE.md, AGENTS.md, etc.) from current .lore/.

When you say it: "lore mirror" — after a batch of syncs, or to manually sync mirrors after editing .lore/*.md.

What happens:

1. Reads current .lore/SUMMARY.md and scope indices
2. For each target, detects section boundary (## Lore / --- / ## My notes)
3. Computes new Lore section content
4. Content-based dedup: skips write if byte-identical to existing
5. Replaces Lore section; preserves My notes verbatim
6. Writes file back

Real scenarios:

• "I just did a batch of syncs — update the agent-facing files" → lore mirror
• "I edited .lore/SUMMARY.md manually — propagate to mirrors" → lore mirror
• "Verify the mirror hasn't drifted" → lore mirror (no-op reports confirm)

Output: Updated CLAUDE.md / AGENTS.md / etc., or "No changes needed" if nothing changed.

---

history

One-line: Show git commits related to an entry, file, or scope.

When you say it: "lore history ||--scope=" — when investigating "why does this exist" or "when did this change".

What happens:

• Entry form: lore history DEC-2026-02-03-7c19 — finds the entry, derives its #added date, runs git log --since=<date> on the referenced code file
• File form: lore history frontend/src/store.ts — runs git log --since=1970 on that path
• Scope form: lore history --scope=frontend — runs file form on every .lore/scopes/frontend/*.md

Real scenarios:

• "Why did we pick Postgres?" → find the entry via query, then lore history <id>
• "When did this file change?" → lore history <file>
• Debugging: "what's the recent history of this module?" → lore history <path>

Output:

# history: [DEC-2026-02-03-7c19]

  abc1234  2026-05-12  refactor: extract chat agent_loop (#87)
  def5678  2026-03-08  feat: switch chat chain to chat_fast (#74)

---

Quick reference

I want to...	Use
Start lore on a project	init
Update lore after a code change	sync
Find what's in memory	query
Find stale entries	audit
Refresh the summary	compress
Update agent-facing files	mirror
Trace why something exists	history

For the operational specification (what the agent actually does step-by-step), see SKILL.md. For per-platform file mapping (which platforms read which files), see references/platform-mirrors.md.