speky

Speky: Specifications in YAML/TOML

Write your requirements and functional tests in a textual format to easily version it with Git, then generate a PDF and a static website.

Roadmap

• PDF with all relevant cross references
• Static website
• Differential PDF to see what changed since last version
• Coverage report to see in a glimpse how much of your requirements are tested
• MCP server for LLMs to discover and query your spec
• Claude plugin to help onboard new projects, or write test plans
• Subagents that review requirements and test plans (and can also draft new ones)

Generate a static website

Requires uv >= 0.8.0

1. Install speky

   uv tool install git+https://github.com/agagniere/speky#master
   

2. Create a manifest listing your spec files:

   # speky.yaml
   kind: project
   name: my-project
   files:
     - requirements.yaml
     - tests.yaml
     - comments/*.yaml
   

3. Generate MyST Markdown:

   speky speky.yaml --output-folder markdown
   

4. Configure Sphinx:

   # conf.py
   project    = 'My Project'
   language   = 'en'
   extensions = [ 'myst_parser', 'sphinx_design' ]
   html_theme = 'furo'
   myst_enable_extensions = [ 'colon_fence', 'substitution' ]
   myst_substitutions     = {'project': project}
   

5. Generate HTML with Sphinx:

   uv tool install sphinx --with furo,sphinx-design,sphinx-copybutton,myst-parser
   sphinx-build -M html markdown sphinx --conf-dir .
   

6. Open the website in a browser

   open sphinx/html/index.html
   

Generate a PDF

Requires Typst >= 0.13.0

Install locally

SPEKYTMP=$(mktemp -d)
git clone https://github.com/agagniere/speky $SPEKYTMP --depth=1
make -C $SPEKYTMP/typst PACKAGE_VERSION=0.3.0
rm -rf $SPEKYTMP

Use from typst

#import "@local/speky:0.3.0": speky

#speky((
  "requirements.yaml",
  "tests.yaml",
  "comments.yaml",
).map(yaml))

Use with Claude Code

Requires uv.

1. Install the plugin

The plugin adds workflow skills and two MCP servers.

# Share with everyone in the repo (both commands need the same scope)
claude plugin marketplace add agagniere/speky --scope project
claude plugin install speky@speky --scope project

# Or just for yourself
claude plugin marketplace add agagniere/speky --scope user
claude plugin install speky@speky --scope user

The plugin registers two MCP servers automatically:

• speky — queries your project's specification
• speky-selfspec — queries Speky's own spec, available as a reference at any time

2. First time?

If you don't have a specification yet, the speky MCP server will fail to start — the manifest doesn't exist yet. That's expected. Run /speky:init in Claude Code: it will guide you through writing your first requirements and creating the manifest. Then restart the speky MCP server via /mcp.

Use with other MCP clients

Requires uv. Add to your client's config:

{
  "mcpServers": {
    "speky": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/agagniere/speky", "speky-mcp", "speky.yaml"]
    }
  }
}

Replace speky.yaml with the path to your manifest, or list individual YAML/TOML specification files.

Used by

AI usage disclosure

Written 100% by hand (without even a language server):

• Speky's specification
• The PDF generation in typst
• Python CLI (spec checker, markdown generation, common code reused by the MCP server, ...)
• Tests and spec samples
• This README.md
• Makefiles, the Yamale schema, pyproject.toml, ...

Written with LLM assistance:

• MCP server specification, implementation and related tests
• DEVELOPMENT.md, MCP.md, AGENTS.md
• All files in .claude-plugin, skills
• python/speky/scanner.py