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. Its agent skills cover the rest, guiding an agent as it writes and reviews those documents.

Installation

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.

Installing from the Git repository

To run a commit that has not been released yet, install from the repository:

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

pipx install takes the same URL. It builds from the default branch. Append @<tag>, @<branch> or @<commit> to the repository URL to install a specific revision instead. The version is derived from the repository's git tags, so a build between two releases reports a development version, such as 0.2.1.dev3+g93b1ed1fb.

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.header.json            # its frontmatter schema
│   ├── code.structure.json         # its sections, word caps and token budget
│   ├── code-python.md              # narrower rules for the python-* documents
│   └── code-python.structure.json  # the sections they must add
└── code/
    ├── logging.md                  # governed_by: [code]
    ├── python-modules.md           # governed_by: [code, code-python]
    ├── python-typing.md            # governed_by: [code, code-python]
    └── test-functions.md           # governed_by: [code]

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

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.

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/.

License

^{Licensed under either of Apache License, Version 2.0 or MIT License, at your option.}
_{Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.}