lore

Files (16)

• LICENSE
• README.md
• SKILL.md
• hero.png · images/
• deep-mine.workflow.js · scripts/
• validate-plan.mjs · scripts/hooks/
• beats.mjs · scripts/lib/
• db.mjs · scripts/lib/
• discover.mjs · scripts/lib/
• forged.mjs · scripts/lib/
• indexer.mjs · scripts/lib/
• parse.mjs · scripts/lib/
• patterns.mjs · scripts/lib/
• report.mjs · scripts/lib/
• mine-skills.mjs · scripts/
• theme-sweep.workflow.js · scripts/

SKILL.md (first lines)

> **Project:** [specstoryai/getspecstory / `lore`](https://github.com/specstoryai/getspecstory/tree/dev/lore). "SpecStory Lore - mine your coding histories into a corpus; forge your workflows into skills."
>
> **License:** [Apache License 2.0](https://github.com/specstoryai/getspecstory/blob/dev/lore/LICENSE). Full license text is in [`LICENSE`](LICENSE) alongside this file.
>
> **Snapshot:** Frozen copy of [`specstoryai/getspecstory/lore`](https://github.com/specstoryai/getspecstory/tree/dev/lore) as of 2026-07-18. The maintained version lives upstream and may have evolved since this snapshot.

# Lore

Your sessions are your lore. This skill turns a user's real coding history into installed skills.
A deterministic engine (`scripts/mine-skills.mjs`) parses their SpecStory transcripts - from **every
agent** SpecStory captures (Claude Code, Codex CLI, Cursor CLI, Gemini CLI, Factory Droid, DeepSeek,
Antigravity, ...) - into a persistent corpus of **beats**, and returns corroborated candidates.
You - the calling agent, whichever harness you are - supply all judgment: name them, discard the
generic ones, and interactively forge the good ones into `SKILL.md` packages grounded in the user's
own commands.

The engine does the retrieval and counting; **you do the synthesis.** Do not try to read raw
transcripts yourself - they can be hundreds of thousands of lines. Run the engine and work from
its output.

This skill is **harness-portable** (agentskills.io format). Where it names a specific tool
(e.g. `AskUserQuestion`), treat that as "use your harness's equivalent; fall back to plain chat."

**Voice:** when narrating to the user, talk about *mining their lore* and *skill candidates* -
e.g. "I'll mine your lore here in <project> for skill candidates." Reserve the word **forge** for
the final act only: creating the skills the user selected (Step 4). Never describe mining, judging,
or candidates as "forge-…" anything.

## OUTPUT CONTRACT - three LAWS, read before emitting anything to the user

**Named failure mode #1 (2026-06-09, BearClaude run):** the agent indexed, deep-mined four skills,
then jumped straight to AskUserQuestion with bare option labels - ZERO dossiers rendered in chat. The
user declined every question because they had nothing to judge by. The entire mining run was wasted.

**Named failure mode #2 (2026-06-09, BearClaude run, SAME DAY, fresh session, LAWs in effect):** the
agent narrated phases correctly, did verification reads, then asked again with NO dossier message -
its last message before the question was process narration ("CodeMirrorBundle is alive in today's
repo…") - and the question text falsely claimed "dossiers above". Lesson: a *felt* self-check is not
a check. Compliance must be MECHANICAL: the sentinel line below is the check, not your impression.

**Named failure mode #3 (2026-06-10, teammate's machine, Opus 4.8, plan-mode path):** the agent DID
use plan-mode curation but presented a THIN plan - skill names and skip reasons with the dossiers
summarized away - so the user approved a forge they never saw the evidence for. The plan UI makes
skipping the *display step* impossible, not skipping the *content*. Lesson: the plan body must BE
the engine's `plan render` artifact (Step 3), which embeds every card verbatim and ends with the
LAW 1 sentinel. In Claude Code this is now HOOK-ENFORCED: a PreToolUse hook in this skill's
frontmatter denies any `ExitPlanMode` whose plan is not that artifact.

**LAW 1 - DOSSIERS BEFORE CANDIDATE QUESTIONS, PROVEN BY SENTINEL.** This law governs **candidate
decisions** - any prompt where the user chooses which skills to forge, skip, or update. (Navigation
questions like the Step 0.25 guided start, or scope confirmations, are exempt - they decide nothing
about candidates.) Before any candidate prompt you must emit one chat message that contains a full
dossier block (`### <name> …`, per Step 3) for EVERY candidate, and that message must END with this
exact line:

```
=== dossiers above: N ===
```

where N equals the number of candidates you are about to offer. At the moment of asking, the check is
mechanical: *"Does a prior message of mine end with `=== dossiers above: N ===` and does N match my
option count?"* No sentinel → you have not rendered dossiers, whatever you remember - STOP and write
them. Process narration between tool calls does NOT count; interim notes do NOT count.

**The strongest form of LAW 1 is plan-style curation (Claude Code, see Step 3): present the dossiers
AS the plan via `ExitPlanMode` - then showing the evidence and asking for the decision are the same
act, and skipping the display is structurally impossible.** But the plan only enforces that
*something* is shown, not *what* (failure mode #3): the plan body must embed the engine-rendered
dossier cards verbatim and end with the sentinel, same mechanical check as chat. The sentinel path
alone is the fallback for harnesses without plan mode.

**LAW 2 - RENDER THE ENGINE'S VISUALS VERBATIM, IN A REAL MESSAGE.** After the report, you must emit
a user-facing mining summary MESSAGE (tool output alone does not count - the user should not need to
expand collapsed tool results). It opens with the engine's `📜 lore · …` badge line and ends with the
`<!-- PASS-THROUGH FOOTER -->` block, both verbatim. The same rule covers every PASS-THROUGH
block the engine emits (STATUS, THEMES, DOSSIERS). Going tool → tool → question with no synthesis
message in between is failure mode #2.

**LAW 3 - NARRATE PHASES.** Before every long-running engine or deep-mine call, emit one short
status line so the window always shows what is happening: `📜 indexing BearClaude (253 sessions)…`,
`📜 deep-mining 4 clusters (this runs subagents; a few minutes)…`, `📜 checking the forged-skill
registry…`. Never leave the user staring at a silent tool call.

## What makes a candidate skill-worthy

A reproducible skill is a behavior that **recurs, is regular, and has a clear trigger**.
The engine scores for recurrence/span/recency/specificity/outcomes; you apply the judgment it cannot:

- **Keep it** when the procedure is distinctive and specific to how this user/project works
  (e.g. `supabase link → supabase db → supabase migration`, `gh run watch` CI-watching,
  "write a comprehensive commit", "fix git divergence against origin/main", a read-only diagnosis).
- **Discard it** when it is generic to all coding and carries no project-specific procedure
  (e.g. bare `git status → git diff`, a lone "yes"/"do 1,2,3" confirmation). High session
  counts alone do not make a skill - ubiquity is not a trigger.

In **cross-project mode** the engine splits candidates into **PORTABLE** (recurs across ≥2 projects)
and **PROJECT-SPECIFIC** (one project). Portability is the strongest signal of a real transferable
skill: forge PORTABLE ones to the personal canonical dir and PROJECT-SPECIFIC ones into that repo.

**Authorship (shared repos):** committed histories carry their session owner - the engine attributes
every session (git add-author > home-dir sniff > machine user) and candidates show `👥 N authors`
when several people exhibit the behavior. Use it:

- **Multi-author candidate** = a TEAM practice, the strongest forge signal of all - propose it at
  project scope (committed `.claude/skills`) so the whole team benefits.
- **Single-author, and it's the current user** = personal candidate, personal scope.
- **Single-author, a TEAMMATE's** = say so plainly in the dossier ("mined from Jake's sessions") and
  recommend team scope or checking with them before forging it as the user's own practice. Never
  present a teammate's workflow as the user's.
- **Privacy:** teammate names may appear in team-scoped (committed) skills; scrub them from
  personal-scope skills.

Note on the evidence: every command candidate comes from an actually-executed shell `<tool-use>` block
(detected by the provider-set `data-tool-type="shell"` attribute, so it works for Bash, Shell,
run_shell_command, exec_command, and every other provider's runner). It is real agent activity, not a
pasted example. Single-line commands (inline backtick or in the tool `<summary>`) and multi-line
```bash blocks are read alike.

## Process

From hugobowne/show-us-your-agent-skills, Apache-2.0.

More from hugobowne/show-us-your-agent-skills