{"id":28317569,"url":"https://github.com/agagniere/speky","last_synced_at":"2026-05-20T14:18:34.340Z","repository":{"id":294985297,"uuid":"988019368","full_name":"agagniere/speky","owner":"agagniere","description":"Manage your specifications with git, render them as PDF and HTML","archived":false,"fork":false,"pushed_at":"2025-06-12T09:07:07.000Z","size":103,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-12T10:24:38.509Z","etag":null,"topics":["specifications","sphinx","typst"],"latest_commit_sha":null,"homepage":"https://agagniere.github.io/speky/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agagniere.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-21T23:57:45.000Z","updated_at":"2025-06-12T09:07:10.000Z","dependencies_parsed_at":"2025-05-23T02:29:58.602Z","dependency_job_id":"82bc6236-336a-4b56-a32e-8601f8022440","html_url":"https://github.com/agagniere/speky","commit_stats":null,"previous_names":["agagniere/speky"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/agagniere/speky","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agagniere%2Fspeky","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agagniere%2Fspeky/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agagniere%2Fspeky/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agagniere%2Fspeky/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agagniere","download_url":"https://codeload.github.com/agagniere/speky/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agagniere%2Fspeky/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261694013,"owners_count":23195498,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["specifications","sphinx","typst"],"created_at":"2025-05-25T06:12:20.614Z","updated_at":"2026-05-20T14:18:34.335Z","avatar_url":"https://github.com/agagniere.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Speky: Specifications in YAML/TOML\n\n![logo](sphinx/assets/Speky-256.png)\n\nWrite your requirements and functional tests in a textual format to easily version it with Git,\nthen generate a PDF and a static website.\n\n## Roadmap\n- [x] PDF with all relevant cross references\n- [x] Static website\n- [ ] Differential PDF to see what changed since last version\n- [x] Coverage report to see in a glimpse how much of your requirements are tested\n- [x] MCP server for LLMs to discover and query your spec\n- [x] Claude plugin to help onboard new projects, or write test plans\n- [x] Subagents that review requirements and test plans (and can also draft new ones)\n\n## Generate a static website\n\nRequires [uv](https://github.com/astral-sh/uv) \u003e= 0.8.0\n\n1. Install speky\n   ```shell\n   uv tool install git+https://github.com/agagniere/speky#master\n   ```\n1. Create a manifest listing your spec files:\n   ```yaml\n   # speky.yaml\n   kind: project\n   name: my-project\n   files:\n     - requirements.yaml\n     - tests.yaml\n     - comments/*.yaml\n   ```\n1. Generate MyST Markdown:\n   ```shell\n   speky speky.yaml --output-folder markdown\n   ```\n1. Configure Sphinx:\n   ```python\n   # conf.py\n   project    = 'My Project'\n   language   = 'en'\n   extensions = [ 'myst_parser', 'sphinx_design' ]\n   html_theme = 'furo'\n   myst_enable_extensions = [ 'colon_fence', 'substitution' ]\n   myst_substitutions     = {'project': project}\n   ```\n1. Generate HTML with Sphinx:\n   ```shell\n   uv tool install sphinx --with furo,sphinx-design,sphinx-copybutton,myst-parser\n   sphinx-build -M html markdown sphinx --conf-dir .\n   ```\n1. Open the website in a browser\n   ```shell\n   open sphinx/html/index.html\n   ```\n\n## Generate a PDF\n\nRequires [Typst](https://github.com/typst/typst) \u003e= 0.13.0\n\n### Install locally\n\n```shell\nSPEKYTMP=$(mktemp -d)\ngit clone https://github.com/agagniere/speky $SPEKYTMP --depth=1\nmake -C $SPEKYTMP/typst PACKAGE_VERSION=0.3.0\nrm -rf $SPEKYTMP\n```\n\n### Use from typst\n\n```typst\n#import \"@local/speky:0.3.0\": speky\n\n#speky((\n  \"requirements.yaml\",\n  \"tests.yaml\",\n  \"comments.yaml\",\n).map(yaml))\n```\n\n## Use with Claude Code\n\nRequires [uv](https://github.com/astral-sh/uv).\n\n### 1. Install the plugin\n\nThe plugin adds workflow skills and two MCP servers.\n\n```shell\n# Share with everyone in the repo (both commands need the same scope)\nclaude plugin marketplace add agagniere/speky --scope project\nclaude plugin install speky@speky --scope project\n\n# Or just for yourself\nclaude plugin marketplace add agagniere/speky --scope user\nclaude plugin install speky@speky --scope user\n```\n\nThe plugin registers two MCP servers automatically:\n- **`speky`** — queries your project's specification\n- **`speky-selfspec`** — queries Speky's own spec, available as a reference at any time\n\n### 2. First time?\n\nIf 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`.\n\n## Use with other MCP clients\n\nRequires [uv](https://github.com/astral-sh/uv). Add to your client's config:\n\n```json\n{\n  \"mcpServers\": {\n    \"speky\": {\n      \"command\": \"uvx\",\n      \"args\": [\"--from\", \"git+https://github.com/agagniere/speky\", \"speky-mcp\", \"speky.yaml\"]\n    }\n  }\n}\n```\n\nReplace `speky.yaml` with the path to your manifest, or list individual YAML/TOML specification files.\n\n## Used by\n\n![safran](https://upload.wikimedia.org/wikipedia/fr/thumb/5/5f/Safran_-_logo_2016.png/330px-Safran_-_logo_2016.png)\n\n## AI usage disclosure\n\nWritten 100% by hand (without even a language server):\n- Speky's specification\n- The PDF generation in typst\n- Python CLI (spec checker, markdown generation, common code reused by the MCP server, ...)\n- Tests and spec samples\n- This README.md\n- Makefiles, the Yamale schema, pyproject.toml, ...\n\nWritten with LLM assistance:\n- MCP server specification, implementation and related tests\n- [DEVELOPMENT.md](DEVELOPMENT.md), [MCP.md](MCP.md), [AGENTS.md](AGENTS.md)\n- All files in [.claude-plugin](.claude-plugin), [skills](skills)\n- `python/speky/scanner.py`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagagniere%2Fspeky","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagagniere%2Fspeky","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagagniere%2Fspeky/lists"}