Skip to content

specstoryai/getspecstory / lore

SpecStory Lore - mine your SpecStory coding histories (any agent - Claude Code, Codex, Cursor, Gemini, and more) into a persistent corpus, surface your reproducible workflows with corroborated evidence, and interactively forge the chosen ones into skills installed across all your agent harnesses. Use when the user wants to turn past AI coding sessions into reusable skills, asks "what could I make into a skill", "mine my lore", "forge skills from my history", or points at a .specstory/history directory.

FileKindSize
.claude-plugin/plugin.jsonconfig738 B
.gitattributesother342 B
.gitignoreother36 B
AGENTS.mdmarkdown1.6 KB
AS-BUILT-ARCHITECTURE.mdmarkdown27.6 KB
CHANGELOG.mdmarkdown12.7 KB
CLAUDE.mdmarkdown11 B
CONTRIBUTING.mdmarkdown5.1 KB
HOW-IT-WORKS.mdmarkdown20.7 KB
LICENSEother11.1 KB
README.mdmarkdown9.3 KB
SKILL.mdskill md32.9 KB
fixtures/golden/forge-plan.mdmarkdown1.7 KB
fixtures/projA/.specstory/.project.jsonconfig93 B
fixtures/projA/.specstory/history/2025-07-10_09-00-00Z-fix-the-gitignore.mdmarkdown736 B
fixtures/projA/.specstory/history/2026-05-01_10-00-00Z-can-we-run-a.mdmarkdown1.2 KB
fixtures/projA/.specstory/history/2026-05-02_11-00-00Z-can-we-run-a.mdmarkdown1015 B
fixtures/projA/.specstory/history/2026-05-03_12-00-00Z-can-we-run-a.mdmarkdown994 B
fixtures/projA/.specstory/history/2026-05-04_13-00-00Z-check-the-vet.mdmarkdown1.0 KB
fixtures/projA/tools/subpkg/.specstory/history/2026-05-07_10-00-00Z-tune-the-subpkg.mdmarkdown458 B
fixtures/projB/.specstory/.project.jsonconfig93 B
fixtures/projB/.specstory/history/2026-05-05_14-00-00Z-can-we-run-a.mdmarkdown795 B
fixtures/projC/.specstory/.project.jsonconfig93 B
fixtures/projC/.specstory/history/2026-05-10_09-00-00Z-where-is-save-implemented.mdmarkdown4.0 KB
fixtures/projC/.specstory/history/2026-05-11_10-00-00Z-where-is-token-validation.mdmarkdown1.9 KB
fixtures/provider-antigravity/.specstory/history/2026-05-23_09-00-00Z-run-the-linter.mdmarkdown567 B
fixtures/provider-deepseek/.specstory/history/2026-05-22_09-00-00Z-count-source-lines.mdmarkdown562 B
fixtures/provider-droid/.specstory/history/2026-05-21_09-00-00Z-show-git-status.mdmarkdown612 B
fixtures/provider-gemini/.specstory/history/2026-05-20_09-00-00Z-list-the-workspace.mdmarkdown610 B
package.jsonmanifest337 B
scripts/deep-mine.workflow.jsscript6.3 KB
scripts/hooks/validate-plan.mjsscript2.5 KB
scripts/lib/beats.mjsscript22.2 KB
scripts/lib/db.mjsscript3.8 KB
scripts/lib/discover.mjsscript3.3 KB
scripts/lib/forged.mjsscript6.5 KB
scripts/lib/indexer.mjsscript7.4 KB
scripts/lib/parse.mjsscript10.4 KB
scripts/lib/patterns.mjsscript14.4 KB
scripts/lib/report.mjsscript21.8 KB
scripts/mine-skills.mjsscript16.9 KB
scripts/theme-sweep.workflow.jsscript7.5 KB
tests/engine.test.mjsscript44.9 KB
<h1 align="center">๐Ÿ“œ Lore</h1>

<p align="center"><strong>Your sessions are your lore. Forge them into skills.</strong></p>

<p align="center">
  <a href="https://github.com/specstoryai/getspecstory/actions/workflows/lore-validate.yml"><img src="https://github.com/specstoryai/getspecstory/actions/workflows/lore-validate.yml/badge.svg" alt="Lore Validate"></a>
  <a href="https://github.com/specstoryai/getspecstory/releases?q=lore&expanded=true"><img src="https://img.shields.io/github/v/tag/specstoryai/getspecstory?filter=lore%2Fv*&label=release" alt="Latest lore release"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License: Apache-2.0"></a>
  <img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="Zero dependencies">
</p>

<p align="center">
Lore mines the SpecStory histories your coding agents leave behind  - <br>
finds the workflows you actually repeat, proves them with evidence and outcomes,<br>
and forges the ones you choose into skills installed across every agent you use.
</p>



https://github.com/user-attachments/assets/082b51e7-2283-4204-a093-45b8b1ce3ce1



---

## Install

```zsh
npx skills add specstoryai/getspecstory --skill lore
```

That detects every supported agent on your machine (Claude Code, Codex, Cursor, Gemini CLI, and
more) and installs lore into each. Requires Node โ‰ฅ 22.5.

Installs are copies, so they don't change until you update them:

```zsh
npx skills update lore    # or `npx skills update` to refresh every installed skill
```

Alternatively, in Claude Code, install it as a plugin:

```
/plugin marketplace add specstoryai/getspecstory
/plugin install lore@specstory
```

Plugin installs update via `/plugin update lore`.

## Get started

In any agent that reads [Agent Skills](https://agentskills.io) (Claude Code, Codex, Cursor, Gemini CLI, โ€ฆ):

```
/lore
```

(Invocation differs per harness - see
[Optimized for Claude Code, built for every harness](#optimized-for-claude-code-built-for-every-harness).)

Press Enter and it walks you through scope, time window, and goal - then mines, shows you
evidence-backed dossiers of your candidate skills, and presents a forge plan to approve. Or steer it
in plain English - there is no argument grammar to learn:

| Say | Get |
|---|---|
| *(just Enter)* | Guided setup, then the full pipeline. |
| `mine this project` | Mine this repo's history. |
| `across my projects in ~/code` | Cross-project mining: portable vs project-specific skills. |
| `last 30 days, just show candidates` | Dry run: evidence dossiers only, no forging. |
| `about supabase` / `only my judgment skills` | Narrow by topic, or by channel (themes vs runbooks). |
| `status` | What Lore has done: corpus, themes, forged skills, drift. |
| `what skills do I have?` | Inventory of every installed skill and what it does. |
| `show me the last plan` | Recall a canceled forge plan and resume. |
| `forge them all` | Batch forge after one confirmation. |
| `reset my lore` | Start fresh (asks first; forged skills stay installed). |

Everything accumulates in one file - `~/.specstory/lore.db` - incrementally and idempotently, across
all your projects and agents. Prefer the engine directly? It's one zero-dependency script - see
[Using the engine directly](HOW-IT-WORKS.md#using-the-engine-directly).

## What it finds

Lore's unit is the **beat**: your prompt (the intent), everything the agent did until your next
prompt (the method - real executed commands, files, exit codes), and your reply as a free outcome
label (approval โœ“ or correction โœ—). Patterns that recur across beats, sessions, projects, and
**teammates** become candidates; the strongest are **corroborated** - you asked for X and the agent
did Y, repeatedly, and it worked. And beyond commands, **theme mining** reads the conversational
beats - the reviews, decisions, and corrections - and surfaces the *latent* expertise you operate
without naming: how you review, how you diagnose, how you direct a model.

```
๐Ÿ“œ Lore mined!
โ”œโ”€ ๐Ÿ—‚  projects: stoa 1,243 ยท BearClaude 253
โ”œโ”€ ๐Ÿง  beats: 21,346 ยท โš™๏ธ executed commands: 36,474
โ”œโ”€ ๐Ÿค– agents: claude-code 1,375 ยท codex-cli 310 ยท cursor 6
โ”œโ”€ ๐Ÿ‘ฅ authors: Greg 1,243 ยท Sean 181 ยท Jake 72
โ”œโ”€ ๐ŸŽฏ outcomes: 744 โœ“ approvals ยท 693 โœ— corrections
โ””โ”€ ๐Ÿ“ฆ your lore: ~/.specstory/lore.db
```

## Why it's different

- **Deterministic engine, judging agent.** A zero-dependency parser + SQLite engine does the
  counting; your agent does the naming and judging. The engine can't hallucinate, and the agent
  never reads 400k-line transcripts - only engine-exported evidence, with credential values
  mechanically redacted before the model ever sees them.
- **Outcomes from your own replies.** "No, wait - " marks a failure; "perfect, commit it" marks
  success. Skills are ranked by what actually worked, not what merely happened.
- **Latent expertise, not just runbooks.** Thematic lenses mine your judgment work - review craft,
  decision-making, model direction - into skills you didn't know you had ("huh, I *do* do that").
  Verified themes then **expand from anecdote to measurement**: the engine finds every corpus
  occurrence deterministically and reports the practice's **outcome lift** over your baseline.
- **Deep-mine with an adversary.** Top candidates get one subagent reading *every* beat
  (failures first) and a second trying to refute the result. Failure modes with recoveries are what
  make a forged skill deep instead of a runbook.
- **Team-aware.** Histories committed by teammates are attributed (git author โ†’ home-dir โ†’
  machine user); a workflow several people share is a team skill, proposed for the repo - and never
  presented as yours when it isn't.
- **Forge once, install everywhere.** Skills land in `~/.agents/skills/<name>` and symlink into
  every harness. The registry remembers what was forged and declined, and proposes **updates** when
  the evidence grows - re-runs never duplicate.

<p align="center"><sub>Reads histories from every SpecStory provider: Claude Code ยท Codex ยท Cursor ยท Gemini ยท Factory Droid ยท DeepSeek ยท Antigravity - modern and legacy formats alike.</sub></p>

## Optimized for Claude Code, built for every harness

Lore is tuned for Claude Code: the two heavy phases ship as bundled **Workflow scripts** that fan
out subagents in parallel - deep mining runs one miner plus one adversarial verifier per candidate
cluster, theme sweeping runs one miner per thematic lens - and runs are resumable if interrupted.
Setup is a guided three-question start, and curation is presented as a **plan you approve** before
anything is written. The plan itself is engine-assembled and **hook-enforced**: a `PreToolUse` hook
bundled with the skill rejects any curation plan that does not embed the full evidence verbatim, so
you can never approve a forge you have not seen.

The skill is still harness-portable by design. The deterministic core (the parser, the corpus, the
registry) is a zero-dependency Node script that behaves identically everywhere, and the skill
contract degrades gracefully: harnesses with their own subagent mechanism fan out the same miner
and verifier briefs; harnesses without subagents mine the clusters sequentially with the agent
reading the engine's evidence exports directly. Forged skills are plain markdown either way, usable
from any agent.

After [installing](#install), invoke it per harness:

| Harness | Invocation |
|---|---|
| Claude Code | `/lore` |
| Codex | `$lore` (the `/` prefix is reserved for built-ins; also listed under `/skills`) |
| Cursor | skills load automatically - just ask, e.g. "mine my lore" |
| Gemini CLI | reads `~/.agents/skills` natively - just ask; the model activates the skill (with your consent) |

## Developing

Lore lives in the [getspecstory](https://github.com/specstoryai/getspecstory) monorepo, next to
the SpecStory CLI. For development, install from a clone - every install point is a symlink back
to it, so updating is just `git -C ~/getspecstory pull`:

```zsh
# 1. clone the monorepo anywhere you keep code
git clone git@github.com:specstoryai/getspecstory.git ~/getspecstory

# 2. canonical skill location (Codex and Gemini CLI read ~/.agents/skills natively)
mkdir -p ~/.agents/skills && ln -sfn ~/getspecstory/lore ~/.agents/skills/lore

# 3. fan out into every harness skills dir you have (symlink, never copy)
for h in ~/.claude/skills ~/.codex/skills; do
  [ -d "$h" ] && ln -sfn ~/.agents/skills/lore "$h/lore"
done
```

Releases: tags (`lore/vX.Y.Z`) run the test suite and publish a `lore.skill` artifact (the
upload-ready zip for claude.ai) via GitHub Actions - see [CHANGELOG.md](CHANGELOG.md) for what
shipped and [CONTRIBUTING.md](CONTRIBUTING.md) for the rules.

## Documentation

| Doc | What's in it |
|---|---|
| [HOW-IT-WORKS.md](HOW-IT-WORKS.md) | The narrative walkthrough - every pipeline stage, with diagrams. |
| [SKILL.md](SKILL.md) | The agent contract: the pipeline, the output-contract LAWs, forge templates. |
| [AS-BUILT-ARCHITECTURE.md](AS-BUILT-ARCHITECTURE.md) | Full technical architecture: schema, parsing rules, scoring, deep-mine, roadmap. |
| [CHANGELOG.md](CHANGELOG.md) | What's shipped, version by version. |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Dev setup, the two non-negotiable rules, fixtures-are-the-spec, releases. |

Licensed under [Apache-2.0](LICENSE).

```zsh
npm test    # 30 tests; the fixtures are the executable spec of every transcript format
```
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why โ€” repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" โ€” or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself โ€” your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall