# Spec Kit codec ## What this builds A converter that turns a Spekkr spec folder into a [GitHub Spec Kit](https://github.com/github/spec-kit) feature folder and back, with no loss in either direction. It is one Python 3.11+ file, standard library only, with the subcommands `to-speckit` and `to-spekkr`, plus an agent skill that says when to run it. The conversion runs on the person's machine. Spekkr's `pull_spec`, `check_spec` and `publish_spec` keep reading and writing Spekkr folders; the codec sits between them and a Spec Kit project. This spec carries a working reference build in `reference/`: | File | What it is | | --- | --- | | `reference/spec_kit_codec.py` | The codec. | | `reference/SKILL.md` | The agent skill. | | `reference/check.py` | The checker: round trips, goldens, collisions and flags. | | `reference/fixtures.tar.gz` | Golden fixtures (unpacks to `reference/fixtures/`, read directly by `reference/check.py`). | | `reference/LICENSE` | MIT, for the files in `reference/`. | The same files are published at [github.com/dwrtz/spec-kit-codec](https://github.com/dwrtz/spec-kit-codec) as `spec_kit_codec.py`, `skills/spec-kit-codec/SKILL.md`, `tests/check.py`, `tests/fixtures/` and `LICENSE`. An agent may use the reference script as it is, or write its own codec and prove it against the fixtures with `python3 reference/check.py path/to/your_codec.py`. The fixtures are synthetic: a pebble jar and a lantern. None of them copies a spec from the Spekkr catalog. Each case has a one-line `README`. `design.md` holds the exact bytes of the safety block and the stub, the filled-in manifest rules and the error messages. `tasks.md` is the build order. ### R1. Feature folder `to-speckit` reads a Spekkr folder and writes a Spec Kit feature folder. The default path is `specs/` under the current directory, where `` is the part of the spec id after the slash. `--dir` chooses another path, including a numbered `specs/NNN-` or a folder outside `specs/`. The script prints the folder it wrote on stdout. **Accept when:** `to-speckit` of `reference/fixtures/spekkr/basic/source` with no `--dir`, run from an empty directory, writes `specs/basic/` equal to `reference/fixtures/spekkr/basic/expected/` and no `.specify/` directory. ### R2. Byte-for-byte files `spec.md`, `tasks.md` and every other file keep their relative paths and their bytes. `spekkr.json` is copied, never re-serialized. `spekkr.inputs.json` and `BUILD.md` are copied when present and omitted when absent. The input folder is never modified. **Accept when:** `to-spekkr(to-speckit(x))` is byte-identical to `x`, and the feature folder equals the case's `expected/` folder, for every Spekkr fixture under `reference/fixtures/spekkr/` that has no `error.txt`. ### R3. plan.md and the safety block `design.md` becomes `plan.md` with the safety block from `design.md` of this spec at offset 0. The block is always the same bytes, including one blank line after ``. `to-spekkr` removes exactly those bytes when `plan.md` starts with them, and leaves `plan.md` untouched otherwise. **Accept when:** for every Spekkr fixture, `plan.md` starts with that block and the bytes after it equal the fixture's `design.md`, and the reverse conversion restores `design.md` byte for byte. ### R4. design.md stub Spec Kit form has a `design.md` stub whose bytes are exactly the stub in `design.md` of this spec. It says the design lives in `plan.md`, so a mention of `design.md` in the spec still leads somewhere. `to-spekkr` drops that file. A hand-written feature folder has no stub, so nothing is dropped. **Accept when:** every successful `to-speckit` result has that stub as `design.md`, and the `mentions-design` fixture round-trips with its mentions of `design.md` unchanged. ### R5. Activation `--activate` writes `.specify/feature.json` in the Spec Kit project, which is how Spec Kit 1.4 finds the active feature for `/speckit.plan`, `/speckit.tasks` and `/speckit.implement`. When the current directory already belongs to a project that contains the feature folder, that project's `.specify` is the one updated, including when `--dir` is not under `specs/`. The value is `{"feature_directory":""}` and a trailing newline. Relative paths use forward slashes. The file is not part of the round trip. Without `--activate` it is not written. **Accept when:** `to-speckit --dir specs/003-basic --activate`, run from an empty directory, writes `.specify/feature.json` containing `{"feature_directory":"specs/003-basic"}` and a non-empty `specs/003-basic/plan.md`. When the current directory already has `.specify/feature.json`, `to-speckit --dir features/basic --activate` rewrites that file to `{"feature_directory":"features/basic"}` and does not create `features/.specify`. ### R6. Hand-written fixed point `to-spekkr` of a feature folder that has no `spekkr.json` fills a manifest in the way `design.md` of this spec describes. `--author` is required. `--date` defaults to `1970-01-01`, never the current day. `--platforms` defaults to `web`. The same input and flags always produce the same bytes. The slug comes from the name of the directory the source path refers to, after the path is resolved, so `.` and `..` give that directory's own name. The default output folder is `./`. **Accept when:** for every hand-written fixture under `reference/fixtures/handwritten/` that has no `error.txt`, with `--author example-user --date 2026-01-01`: - `to-speckit(to-spekkr(k))` equals `expected-fixed/` and is byte-identical to `to-speckit(to-spekkr(to-speckit(to-spekkr(k))))`; - `to-spekkr(k)` equals `expected-spekkr/` and is byte-identical to `to-spekkr` of that fixed point; - its `design.md` is the original `plan.md`. The source folder is named by the case's `folder-name` file when it has one. Run from inside the `numbered` fixture placed as `003-example`, `to-spekkr . --dir ../from-dot` writes `expected-spekkr/`, and `to-spekkr ..` from an empty child folder writes the id `example-user/example`. With no `--dir`, the same folder converts to `./example`. ### R7. Filled-in manifest The filled-in `spekkr.json` uses a fixed key order, 2-space indent, `\n` line endings and a final newline. `author.id` and `author.name` are both `--author`. The summary is the first plain paragraph after the title, cut to 140 characters at a word boundary. `files` lists `spec.md`, `design.md`, `tasks.md` when present, then every other file sorted by path. `customize` and `safety` are empty. Notes on stderr include the summary, so the person can fix it before publishing. The file passes `check_spec`. **Accept when:** every hand-written fixture's golden `spekkr.json` passes `check_spec`, the `long-summary` summary is at most 140 characters and ends on the word `pebble`, omitting `--date` writes `1970-01-01` and says so on stderr, and `--platforms "cli, backend"` writes `["cli", "backend"]`. ### R8. Collisions `to-speckit` refuses a Spekkr spec that already has `plan.md`, and a `design.md` that starts with ``. `to-spekkr` refuses a `design.md` that is not the codec stub. Each failure is a non-zero exit, one `error:` line on stderr, and no output folder. **Accept when:** the `collision-plan`, `collision-safety-marker` and `collision-stub` fixtures exit non-zero and their stderr equals the case's `error.txt`. ### R9. No reformatting Requirement ids, "Accept when" lines, FR/SC lines and task text are copied as written. The codec does not renumber them and does not add or remove checkboxes. **Accept when:** the `requirements` fixture keeps its `### R1.` headings and **Accept when** lines, and the `plain` hand-written fixture keeps its FR/SC lines and its `- [ ]` task. ### R10. Edge bytes CRLF line endings, a missing trailing newline, non-ASCII UTF-8, binary files and a file over 60 KB are copied as bytes. A manifest with unusual spacing is copied as bytes. **Accept when:** the `crlf`, `no-final-newline`, `unicode`, `extra-files`, `large-file` and `odd-manifest` fixtures round-trip byte for byte, including `spekkr.json` and the PNG files under `shots/`. ### R11. All or nothing A conversion either writes the whole output folder or writes nothing. A directory in the source that cannot be listed, or a file that cannot be read, stops the command with `error: cannot read : ` before anything is written; it is never skipped. Symlinks and other non-regular files are refused. An output folder that already holds files, or one inside the input folder, is refused. The tree is written to a temporary sibling folder and renamed into place. **Accept when:** `to-speckit` of a copy of the `basic` fixture with an added `reference/` directory that cannot be listed exits non-zero, prints a stderr line starting with `error: cannot read `, prints nothing on stdout, and leaves no output folder. (The checker skips this case when it runs as root, because root can list any directory.) ### R12. Agent skill `reference/SKILL.md` tells an agent when and how to run the codec: pulling a Spekkr spec into a Spec Kit project with `--activate`, choosing `--dir`, turning a Spec Kit feature into a Spekkr spec for `check_spec` and `publish_spec`, and checking a self-built codec. It tells the agent to show the person the stderr notes about a filled-in manifest, and to keep requirement ids and task text as written. **Accept when:** the skill has `name` and `description` front matter, and the commands it gives for a pulled spec, `python3 reference/spec_kit_codec.py` and `python3 reference/check.py`, run from the spec folder.