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

CONTRIBUTING.md

View on GitHub
# Contributing to Lore

Thanks for wanting to make Lore better. This guide covers the project's structure, the rules that
keep the engine trustworthy, and how to land a change.

## Development setup

```zsh
git clone git@github.com:specstoryai/getspecstory.git ~/getspecstory
mkdir -p ~/.agents/skills && ln -sfn ~/getspecstory/lore ~/.agents/skills/lore

# fan out into the harnesses you use (symlink, never copy)
for h in ~/.claude/skills ~/.codex/skills; do
  [ -d "$h" ] && ln -sfn ~/.agents/skills/lore "$h/lore"
done

npm test    # Node >= 22.5; no install step - there are no dependencies
```

Because the install is a symlink, every edit is live in your harness immediately.

> [!WARNING]
> If you have ever run `npx skills add` for lore on this machine, it left a frozen COPY at
> `~/.agents/skills/lore` - a real directory, not a symlink. `ln -sfn` against it silently
> creates a nested link inside instead of replacing it, and your dev install gets shadowed by
> the stale copy. Check with `readlink ~/.agents/skills/lore`; if it prints nothing,
> `rm -rf ~/.agents/skills/lore` first, then symlink.

Use a scratch corpus while developing so you never pollute your real one:

```zsh
node scripts/mine-skills.mjs index --scan <some-project> --db /tmp/dev-lore.db
```

## The two rules that are not negotiable

1. **Zero dependencies.** The engine is plain Node (`node:sqlite`, `node:fs`, `node:crypto`). No
   npm packages, no network calls, no API keys. If a change seems to need a dependency, open an
   issue first - the answer is almost always a small amount of plain code.
2. **The engine is deterministic; the agent judges.** Parsing, counting, fingerprinting, and
   rendering live in `scripts/` and must be reproducible byte for byte. Anything requiring
   judgment (naming, theme proposal, verification) belongs in `SKILL.md`'s contract or the
   workflow scripts, never in the engine.

## Layout

```
SKILL.md                    the agent contract (the skill itself; repo root = skill dir)
scripts/mine-skills.mjs     thin CLI entry
scripts/lib/                the engine: patterns (format grammar), parse, db, indexer,
                            report, beats (themes/dossiers/plans), forged (registry), discover
scripts/hooks/              harness enforcement (ExitPlanMode plan validation)
scripts/*.workflow.js       Claude Code Workflow fan-outs (deep-mine, theme-sweep)
fixtures/                   the executable spec - see below
tests/engine.test.mjs       the suite (node --test)
```

## Fixtures are the spec

Every parsing or rendering claim must be backed by a fixture, in the should-flag/should-pass style:

- **A new transcript format or provider**: add a minimal session under
  `fixtures/provider-<name>/.specstory/history/` with the provider's REAL header and tool-envelope
  bytes (verify against specstory-cli's writers - do not invent formats), plus a test asserting
  the agent slug, outcome labeling, and command capture.
- **A new extraction rule**: add the verbatim byte example to the relevant section of
  `scripts/lib/patterns.mjs` (every regex there is preceded by the real bytes it matches) and a
  fixture or inline case exercising it.
- **A parser behavior change**: bump `PARSER_VERSION` in `scripts/lib/db.mjs` so existing corpora
  re-parse automatically on the next index.
- **A plan/render layout change**: the golden file will fail - regenerate with
  `UPDATE_GOLDEN=1 npm test` and include the `fixtures/golden/forge-plan.md` diff in your PR so
  the layout change is reviewable.

Run the full suite after every change: `npm test` (29 tests and growing; all must pass).

## Style

- Idiomatic modern Node ESM; small pure functions; comments explain WHY, not what.
- No em dashes anywhere - in docs, code comments, or engine-emitted strings (use " - ").
- Engine output that the agent must render verbatim is wrapped in PASS-THROUGH markers and ends
  with a machine-checkable sentinel; never weaken these (they are LAW 1/2 of the output contract).
- SKILL.md changes: keep the Voice rule (mining/candidates language; "forge" only for the final
  act) and never remove a named failure mode - they are the contract's institutional memory.

## Commits and PRs

- Conventional commits: `type(scope): subject` with a body that explains the why
  (`feat(theme): ...`, `fix(forged): ...`, `docs(readme): ...`).
- One logical change per PR. If you touched the golden file, say why in the body.
- CI (`validate.yml`) runs the suite and syntax checks on every PR; it must be green.

## Releases (maintainers)

1. Update `CHANGELOG.md`.
2. Bump the version in FOUR places: `SKILL.md` frontmatter (`metadata.version`),
   `lore/.claude-plugin/plugin.json`, the repo-root `.claude-plugin/marketplace.json`, and
   `lore/package.json`.
3. Tag and push: `git tag lore/vX.Y.Z && git push origin lore/vX.Y.Z`.
4. `lore-release.yml` runs the suite, verifies the tag matches all four version spots, and
   publishes the GitHub Release (`lore-vX.Y.Z`, never marked latest - that pointer belongs to
   the CLI installer) with the `lore.skill` artifact.

## License

By contributing, you agree that your contributions are licensed under the
[Apache License 2.0](LICENSE).
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: 471kUpdated 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