Skip to content

storm-software/sourcebook

v0.0.1Apache-2.0

Generate workspace documentation and update blog articles and project READMEs, and record architecture decisions with the Sourcebook agent skills.

GitHubOpen Website

📓 Sourcebook helps you automate your technical docs and blog content.

github Commitizen friendly semantic-release GitHub Workflow Status (with event)

Important

This repository, and the apps, libraries, and tools contained within, is still in it's initial development phase. As a result, bugs and issues are expected with it's usage. When the main development phase completes, a proper release will be performed, the packages will be available through NPM (and other distributions), and this message will be removed. However, in the meantime, please feel free to report any issues you may come across.

Table of Contents

Quick Features

Sourcebook is an agent skill that generates Markdown documentation for an application, library, or design system from a workspace's sourcebook.config.* file.

How it works

The skill loads the config with c12, selects instructions by type, inspects the configured source paths, and writes documentation. The reader prints the validated config as JSON; the agent writes the prose.

Configure a workspace

Create sourcebook.config.ts in the workspace root:

import { defineConfig } from "@sourcebook/config";

export default defineConfig({
  type: "application",
  frontend: "apps/web/src",
  backend: "apps/api/src",
  outputPath: "docs",
  useLocalOutput: true,
  displayName: "Example",
  instructions: "Include a developer setup guide."
});

type is application, library, or design-system. Application configs accept src, frontend, and backend; library configs accept packages; design system configs accept fonts, icons, illustrations, components, blocks, and layouts. Each path field accepts a workspace-relative string or array of strings. Shared options are outputPath (default docs), useLocalOutput (default true), displayName, homepage, description, and instructions. The config may also be an array of project configs.

With local output, the skill writes under each identified project directory; otherwise it writes under the workspace root. c12 also supports JavaScript, JSON, YAML, TOML, and other config formats.

Installation

Install the Sourcebook plugin from this repository to use the sourcebook-docs, sourcebook-blog, sourcebook-editor, sourcebook-readme, and sourcebook-adr agent skills. The plugin bundles the readers, references, and helper scripts needed by each skill. sourcebook-editor reviews and polishes existing documentation or blog updates, sourcebook-readme updates a project's README.md, and sourcebook-adr records significant technology and design decisions as log4brains-compatible Architecture Decision Records; none of them requires a Sourcebook configuration file.

Before using sourcebook-docs or sourcebook-blog, add sourcebook.config.* to the target workspace and make sure node is available on PATH for the bundled configuration reader. TypeScript configuration files import defineConfig from @sourcebook/config; JSON, YAML, and TOML configurations do not require that package.

Claude Code:

/plugin marketplace add storm-software/sourcebook
/plugin install sourcebook@sourcebook

Codex:

codex plugin marketplace add storm-software/sourcebook
codex plugin add sourcebook@sourcebook

Factory Droid:

droid plugin marketplace add https://github.com/storm-software/sourcebook
droid plugin install sourcebook@sourcebook --scope user

GitHub Copilot CLI:

copilot plugin marketplace add storm-software/sourcebook
copilot plugin install sourcebook@sourcebook

Copilot uses the portable plugin.json manifest and the same marketplace manifest as Claude Code. In the Copilot app, add the marketplace from Customize → Plugins and install Sourcebook.

Cursor:

The repository includes Cursor's marketplace and plugin manifests. Install Sourcebook from Cursor Settings → Plugins or run /add-plugin sourcebook after its marketplace is available in Cursor. For a local checkout, place it at ~/.cursor/plugins/local/sourcebook.

After installation, start a new agent session in the target workspace. Ask the agent to generate or update documentation, enhance blog articles, or update a project's README; it selects the matching Sourcebook skill from the request.

Development

pnpm test:sourcebook
pnpm typecheck:sourcebook

The TypeScript config contract is in packages/config. Run pnpm --filter @sourcebook/config build to build it.

Roadmap

See the open issues for a list of proposed features (and known issues).

Contributing

First off, thanks for taking the time to contribute! Contributions are what makes the open-source community such an amazing place to learn, inspire, and create. Any contributions you make will benefit everybody else and are greatly appreciated.

Please try to create bug reports that are:

  • Reproducible. Include steps to reproduce the problem.
  • Specific. Include as much detail as possible: which version, what environment, etc.
  • Unique. Do not duplicate existing opened issues.
  • Scoped to a Single Bug. One bug per report.

Please adhere to this project's code of conduct.

You can use markdownlint-cli to check for common markdown style inconsistency.

Support

Reach out to the maintainer at one of the following places:

License

This project is licensed under the Apache License 2.0. Feel free to edit and distribute this template as you like. If you have any specific questions, please reach out to the Storm Software development team.

See LICENSE for more information.

FOSSA Status

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

Storm Software is an open source software development organization and creator of Acidic, StormStack and StormCloud.

Our mission is to make software development more accessible. Our ideal future is one where anyone can create software without years of prior development experience serving as a barrier to entry. We hope to achieve this via LLMs, Generative AI, and intuitive, high-level data modeling/programming languages.

Join us on Discord to chat with the team, receive release notifications, ask questions, and get involved.

If this sounds interesting, and you would like to help us in creating the next generation of development tools, please reach out on our website or join our Slack channel!