lorecraft

Read the Docs · Report Bug · Request Feature

A toolkit for the agent-facing documentation of a repository: the coding rules, feature docs and skills that agents read while they work.

Lorecraft keeps that documentation consistent as it grows. A repository declares the shape each kind of document must have, and Lorecraft checks every document against it, locally or in CI. It checks the repository's agent skills too, against the Agent Skills specification. Its own agent skills cover the rest, guiding an agent as it writes and reviews those documents.

Installation

lorecraft requires Python 3.12 or later.

With uv, install the lorecraft command as a tool, or run it on demand without installing it:

uv tool install lorecraft
uvx lorecraft check

To pin it to a uv project instead, add it as a development dependency and run it through the project's environment:

uv add --dev lorecraft
uv run lorecraft check

Or install it in an isolated environment with pipx:

pipx install lorecraft

Confirm which build you are running with lorecraft version. Every command also runs as lc, a shorter name for lorecraft.

uv tool install "git+https://github.com/lnsd/lorecraft"

Quickstart

Write your coding rules as documents in docs/code/, and describe what a rule document looks like in docs/__meta__/:

docs/
├── __meta__/
│   ├── code.md                     # what every rule document looks like, in prose
│   ├── code.spec.json              # its frontmatter, sections, word caps and token budget
│   ├── code-python.md              # narrower rules for the python-* documents
│   └── code-python.spec.json       # the frontmatter and sections they add
└── code/
    ├── logging.md                  # governed_by: [code]
    ├── python-modules.md           # governed_by: [code, code-python]
    ├── python-typing.md            # governed_by: [code, code-python]
    └── tests-functions.md          # governed_by: [code]

Each specification is a pair of files that share a specification name, such as code: the prose, <name>.md, and the structure specification, <name>.spec.json, which the checks apply. code governs every document in docs/code/, and code-python adds its rules to the python-* documents.

Keep the rule documents in shape, from the repository root:

lorecraft inspect  # which specifications govern which rule document
lorecraft check    # check every rule document against them, and every agent skill
lorecraft rule     # every rule, in code order; `lorecraft rule OUT006` explains one

lorecraft check exits 0 when it reports no error, 1 when it reports one, and 2 when it could not run, so it can gate a CI job as it is. Both commands take --format json for a script to read.

Then let your agent use them, through the skills: /code-rules loads the rules that apply before it writes code, and /code-rules-check checks its changes against them. This repository's own docs/code/ is a working example.

Skills

The skills/ directory holds agent skills that put the rules to work:

• During development, code-rules loads the coding rules that apply before the agent writes code, and docs-rules does the same for your documents.
• During review, code-rules-check checks a change for compliance with those same rules, and docs-rules-check does the same for your documents.
• When authoring the rules, docs-rules-creator helps the agent write the specifications that govern your documents.
• When writing agent skills, skills-check guides the agent through the Agent Skills specification and checks your skills against it with lorecraft check.

Install the skills with Vercel's skills CLI:

npx skills add https://github.com/lnsd/lorecraft/tree/main/skills

Or copy them into your agent's skills directory, such as .claude/skills/ or .agents/skills/.

Contributing

Read CONTRIBUTING.md before opening a pull request. Pull requests opened by autonomous agents are closed without review.

License