Kiro codec

Converts a Spekkr spec folder to a Kiro feature folder and back, byte for byte. One Python script and an agent skill.

This is a CLI tool spec on Spekkr, published by dwrtz. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.

Spec
dwrtz/kiro-codec
Version
0.1.1
Published by
dwrtz
Updated
20 Nov 2026

Build this spec

Build the spec at https://spekkr.com/dwrtz/kiro-codec/start.md.

Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.

Published by dwrtz.

What can I customize?

This spec builds one way. You can edit the files after you pull them, but that leaves the tested path.

What do I get?

  • spec.md Requirements R1-R14 with acceptance checks: feature folder, byte-for-byte sidecar, safety block, requirements.md, steering, the hand-written fixed point, the filled-in manifest, collisions, no reformatting, edge bytes, all-or-nothing writes, the warning, the agent skill, and the checker.

    Kiro codec

    What this builds

    A converter that turns a Spekkr spec folder into a Kiro feature folder and back, with no loss in either direction. It is one Python 3.11+ file, standard library only, with the subcommands to-kiro 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 Kiro project.

    This version is the spec. It does not contain a reference script, fixtures, or a skill. tasks.md is the order for building those. design.md holds the bytes, the steering rules, the error strings, the Kiro citations, and the behavior the Kiro docs leave unspecified.

    Kiro facts below were checked on 20 November 2026 against the pages listed in design.md. Where a page does not specify a format, the codec copies bytes and says so. It does not invent a tasks.md schema, a spec index, or a hook.

    customize is empty. This spec has no settings, options, or swaps.

    R1. Feature folder

    to-kiro reads a Spekkr folder and writes a Kiro feature folder. The default path is .kiro/specs/<name> under the current directory, where <name> is the part of the spec id after the slash. --dir chooses another path. The script prints the folder it wrote on stdout. The input folder is not modified.

    Kiro's feature specs live at .kiro/specs/<name>/ (specs, best practices, configuration). The three files Kiro documents there are requirements.md, design.md, and tasks.md.

    Accept when: to-kiro of tests/fixtures/spekkr/basic/source with no --dir, run from an empty directory, writes .kiro/specs/basic/ equal to that case's expected/ and does not write .kiro/steering/ or .kiro/hooks/.

    R2. Byte-for-byte sidecar

    tasks.md and every file other than spec.md and design.md 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. Those files, plus anything else in the Spekkr folder (reference/, shots/, and the rest), are the sidecar. They sit inside .kiro/specs/<name>/, next to the three spec files, so a mention of spekkr.inputs.json still resolves.

    Kiro's documented spec is those three files. The sidecar is how the codec keeps the manifest, the recorded choices, and BUILD.md, which Kiro has no field for.

    Accept when: to-spekkr(to-kiro(x)) is byte-identical to x, and the feature folder equals the case's expected/ folder, for every Spekkr fixture under tests/fixtures/spekkr/ that has no error.txt.

    R3. Safety block

    design.md is copied 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 <!-- spekkr:safety:end -->. to-spekkr removes exactly those bytes when design.md starts with them. A design.md that does not start with <!-- spekkr:safety:begin --> is left untouched. One that starts with the begin marker but not the full block is an error, on both commands.

    The block tells the agent to show the person the commands and secrets under safety, to treat spekkr.inputs.json as requirements, and not to regenerate requirements.md, design.md, or tasks.md.

    Accept when: for every Spekkr fixture, the feature design.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. requirements.md

    spec.md is written as requirements.md, byte for byte. The codec does not rewrite it into EARS notation. There is no stub file: Kiro's design file is already design.md, so the design keeps that name. A Spekkr folder that already contains requirements.md is refused, because that file would be overwritten by the renamed spec.md.

    Accept when: every successful to-kiro writes requirements.md equal to the source spec.md. The requirements fixture keeps its ### R1. headings and **Accept when:** lines. The collision-requirements fixture exits non-zero and writes nothing.

    R5. Steering

    --steering writes workspace steering under .kiro/steering/ of the Kiro project. It is optional. Without the flag, no steering file is written.

    Steering is outside the feature folder and is not part of the round trip. to-spekkr does not read it.

    The mapping is only what the manifest actually contains:

    • product.md gets the manifest name, summary, kind when that is a non-empty string, and targets.platforms when that is a non-empty list of strings. It does not invent target users, key features, or business objectives.
    • tech.md is written only when targets.stack is a non-empty list of strings. The list is copied. Nothing else is added.
    • structure.md is not written. The manifest files list is the spec's own files, not the project's layout.
    • A choices file <feature>.md with inclusion: manual is written only when spekkr.inputs.json is a JSON object of strings, booleans, and integers. customize defaults are not treated as recorded choices.
    • Commands and secrets under safety are not copied into steering.
    • No file under .kiro/hooks/ is written.

    The flag refuses when the feature folder is not .kiro/specs/<name>/, and refuses to overwrite an existing steering file. Exact bytes, front matter, and notes are in design.md.

    Accept when: to-kiro of the basic fixture with no --steering leaves .kiro/steering/ absent. The same command with --steering writes the product.md example in design.md and does not write tech.md, structure.md, a choices file, or a hook. to-kiro --steering of rich-manifest writes the three steering examples in design.md and no structure.md. When .kiro/steering/product.md already exists and the feature destination does not, --steering exits non-zero and does not create the feature folder. to-spekkr(to-kiro(rich-manifest)) does not depend on the steering files and still matches the source.

    R6. Hand-written fixed point

    to-spekkr of a feature folder that has no spekkr.json fills a manifest the way design.md describes. --author is required. --date defaults to 1970-01-01, never the current day. --platforms defaults to web. The same input and the same 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 ./<slug>.

    A hand-written requirements.md becomes spec.md byte for byte. A hand-written design.md that does not start with <!-- spekkr:safety:begin --> becomes Spekkr design.md byte for byte. One that starts with the full block loses exactly that block. One that starts with the begin marker but not the full block is refused, and this requirement does not apply to it.

    Accept when: for every hand-written fixture under tests/fixtures/handwritten/ that has no error.txt, with --author example-user --date 2026-01-01:

    • to-kiro(to-spekkr(k)) equals expected-fixed/ and is byte-identical to to-kiro(to-spekkr(to-kiro(to-spekkr(k))));
    • to-spekkr(k) equals expected-spekkr/ and is byte-identical to to-spekkr of that fixed point;
    • requirements.md round-trips through spec.md byte for byte;
    • design.md in the Spekkr folder is the source design.md with the safety block removed when the source starts with it.

    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 the key order, indent, and field rules in design.md. author.id and author.name are both --author. The summary is the first plain paragraph after the title in requirements.md, 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.

    Kiro's published requirements example uses ## sections and no # title (requirements-first). The codec does not promote a ## heading to the manifest name. With no # heading, the name is the folder slug. The ears fixture is that shape.

    Accept when: every hand-written fixture's golden spekkr.json passes check_spec, the ears manifest name is the folder slug, 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-kiro refuses a Spekkr spec that already has requirements.md, and a design.md that starts with <!-- spekkr:safety:begin -->. to-spekkr refuses a feature folder that already has spec.md. It also refuses a design.md that starts with <!-- spekkr:safety:begin --> but is not the full safety block. Each failure is a non-zero exit, one error: line on stderr, and no output folder.

    Accept when: collision-requirements, collision-safety-marker, and collision-spec exit non-zero, their stderr equals the case's error.txt, and they leave no output folder. A feature design.md that starts with the begin marker but not the full block fails to-spekkr with the error in design.md and leaves no output folder.

    R9. No reformatting

    Requirement ids, "Accept when" lines, EARS lines, FR/SC lines, and task text are copied as written. The codec does not renumber them, does not convert prose into EARS, and does not add or remove checkboxes.

    Kiro's docs describe tasks.md as discrete tasks with outcomes, dependencies, and required or optional status. They do not publish the markdown schema. Copying bytes is the conservative choice. design.md records that gap.

    Accept when: the requirements fixture keeps its headings and Accept when lines, the ears fixture keeps its WHEN / THE SYSTEM SHALL lines unchanged, and the plain 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 <path>: <reason> 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. --steering checks for existing steering files before that write, and a conflict writes neither the feature folder nor a steering file.

    Accept when: to-kiro 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. Warning

    Every successful to-kiro prints one note: line on stderr telling the person not to let Kiro regenerate requirements.md, design.md, or tasks.md. The same warning is inside the safety block, which Kiro loads when a chat includes the spec.

    What the docs say Kiro will rewrite, and what they do not mention, is listed in design.md. The repository README quotes the safety block and states that warning in the same words.

    Accept when: every successful to-kiro in the checker writes that note as its first stderr line, and the repository README.md contains the safety block bytes.

    R13. Agent skill

    skills/kiro-codec/SKILL.md tells an agent when and how to run the codec: pulling a Spekkr spec into .kiro/specs/<name>/, when to pass --steering, turning a Kiro 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, to keep requirement text and task text as written, and not to ask Kiro to regenerate the three converted files or to run Generate Steering Docs over files this codec wrote.

    Accept when: the skill has name and description front matter, and the to-kiro command it gives, run on tests/fixtures/spekkr/basic/source from an empty directory, writes .kiro/specs/basic/.

    R14. Checker and CI

    tests/check.py runs the round trip, the hand-written fixed point, the collision cases, the steering examples, and the flag checks in design.md. GitHub Actions runs it on Python 3.11 and 3.12.

    Accept when: python3 tests/check.py exits 0 on both versions, and a missing required fixture directory fails the checker.

    # Kiro codec
    
    ## What this builds
    
    A converter that turns a Spekkr spec folder into a
    [Kiro](https://kiro.dev/docs/specs/) feature folder and back, with no loss
    in either direction. It is one Python 3.11+ file, standard library only,
    with the subcommands `to-kiro` 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 Kiro project.
    
    This version is the spec. It does not contain a reference script, fixtures,
    or a skill. `tasks.md` is the order for building those. `design.md` holds
    the bytes, the steering rules, the error strings, the Kiro citations, and
    the behavior the Kiro docs leave unspecified.
    
    Kiro facts below were checked on 20 November 2026 against the pages listed
    in `design.md`. Where a page does not specify a format, the codec copies
    bytes and says so. It does not invent a `tasks.md` schema, a spec index, or
    a hook.
    
    `customize` is empty. This spec has no settings, options, or swaps.
    
    ### R1. Feature folder
    
    `to-kiro` reads a Spekkr folder and writes a Kiro feature folder. The
    default path is `.kiro/specs/<name>` under the current directory, where
    `<name>` is the part of the spec id after the slash. `--dir` chooses
    another path. The script prints the folder it wrote on stdout. The input
    folder is not modified.
    
    Kiro's feature specs live at `.kiro/specs/<name>/`
    ([specs](https://kiro.dev/docs/specs/),
    [best practices](https://kiro.dev/docs/specs/best-practices/),
    [configuration](https://kiro.dev/docs/configuration/)). The three files
    Kiro documents there are `requirements.md`, `design.md`, and `tasks.md`.
    
    **Accept when:** `to-kiro` of `tests/fixtures/spekkr/basic/source` with no
    `--dir`, run from an empty directory, writes `.kiro/specs/basic/` equal to
    that case's `expected/` and does not write `.kiro/steering/` or
    `.kiro/hooks/`.
    
    ### R2. Byte-for-byte sidecar
    
    `tasks.md` and every file other than `spec.md` and `design.md` 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. Those files, plus anything else in the Spekkr
    folder (`reference/`, `shots/`, and the rest), are the sidecar. They sit
    inside `.kiro/specs/<name>/`, next to the three spec files, so a mention of
    `spekkr.inputs.json` still resolves.
    
    Kiro's documented spec is those three files. The sidecar is how the codec
    keeps the manifest, the recorded choices, and `BUILD.md`, which Kiro has
    no field for.
    
    **Accept when:** `to-spekkr(to-kiro(x))` is byte-identical to `x`, and the
    feature folder equals the case's `expected/` folder, for every Spekkr
    fixture under `tests/fixtures/spekkr/` that has no `error.txt`.
    
    ### R3. Safety block
    
    `design.md` is copied 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 `<!-- spekkr:safety:end -->`. `to-spekkr` removes exactly those bytes
    when `design.md` starts with them. A `design.md` that does not start with
    `<!-- spekkr:safety:begin -->` is left untouched. One that starts with the
    begin marker but not the full block is an error, on both commands.
    
    The block tells the agent to show the person the commands and secrets
    under `safety`, to treat `spekkr.inputs.json` as requirements, and not to
    regenerate `requirements.md`, `design.md`, or `tasks.md`.
    
    **Accept when:** for every Spekkr fixture, the feature `design.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. requirements.md
    
    `spec.md` is written as `requirements.md`, byte for byte. The codec does
    not rewrite it into EARS notation. There is no stub file: Kiro's design
    file is already `design.md`, so the design keeps that name. A Spekkr folder
    that already contains `requirements.md` is refused, because that file would
    be overwritten by the renamed `spec.md`.
    
    **Accept when:** every successful `to-kiro` writes `requirements.md` equal
    to the source `spec.md`. The `requirements` fixture keeps its `### R1.`
    headings and `**Accept when:**` lines. The `collision-requirements` fixture
    exits non-zero and writes nothing.
    
    ### R5. Steering
    
    `--steering` writes workspace steering under `.kiro/steering/` of the Kiro
    project. It is optional. Without the flag, no steering file is written.
    
    Steering is outside the feature folder and is not part of the round trip.
    `to-spekkr` does not read it.
    
    The mapping is only what the manifest actually contains:
    
    - `product.md` gets the manifest `name`, `summary`, `kind` when that is a
      non-empty string, and `targets.platforms` when that is a non-empty list
      of strings. It does not invent target users, key features, or business
      objectives.
    - `tech.md` is written only when `targets.stack` is a non-empty list of
      strings. The list is copied. Nothing else is added.
    - `structure.md` is not written. The manifest `files` list is the spec's
      own files, not the project's layout.
    - A choices file `<feature>.md` with `inclusion: manual` is written only
      when `spekkr.inputs.json` is a JSON object of strings, booleans, and
      integers. `customize` defaults are not treated as recorded choices.
    - Commands and secrets under `safety` are not copied into steering.
    - No file under `.kiro/hooks/` is written.
    
    The flag refuses when the feature folder is not `.kiro/specs/<name>/`, and
    refuses to overwrite an existing steering file. Exact bytes, front matter,
    and notes are in `design.md`.
    
    **Accept when:** `to-kiro` of the `basic` fixture with no `--steering`
    leaves `.kiro/steering/` absent. The same command with `--steering` writes
    the `product.md` example in `design.md` and does not write `tech.md`,
    `structure.md`, a choices file, or a hook. `to-kiro --steering` of
    `rich-manifest` writes the three steering examples in `design.md` and no
    `structure.md`. When `.kiro/steering/product.md` already exists and the
    feature destination does not, `--steering` exits non-zero and does not
    create the feature folder. `to-spekkr(to-kiro(rich-manifest))` does not
    depend on the steering files and still matches the source.
    
    ### R6. Hand-written fixed point
    
    `to-spekkr` of a feature folder that has no `spekkr.json` fills a manifest
    the way `design.md` describes. `--author` is required. `--date` defaults to
    `1970-01-01`, never the current day. `--platforms` defaults to `web`. The
    same input and the same 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 `./<slug>`.
    
    A hand-written `requirements.md` becomes `spec.md` byte for byte. A
    hand-written `design.md` that does not start with
    `<!-- spekkr:safety:begin -->` becomes Spekkr `design.md` byte for byte.
    One that starts with the full block loses exactly that block. One that
    starts with the begin marker but not the full block is refused, and this
    requirement does not apply to it.
    
    **Accept when:** for every hand-written fixture under
    `tests/fixtures/handwritten/` that has no `error.txt`, with
    `--author example-user --date 2026-01-01`:
    
    - `to-kiro(to-spekkr(k))` equals `expected-fixed/` and is byte-identical to
      `to-kiro(to-spekkr(to-kiro(to-spekkr(k))))`;
    - `to-spekkr(k)` equals `expected-spekkr/` and is byte-identical to
      `to-spekkr` of that fixed point;
    - `requirements.md` round-trips through `spec.md` byte for byte;
    - `design.md` in the Spekkr folder is the source `design.md` with the
      safety block removed when the source starts with it.
    
    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 the key order, indent, and field rules in
    `design.md`. `author.id` and `author.name` are both `--author`. The summary
    is the first plain paragraph after the title in `requirements.md`, 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`.
    
    Kiro's published requirements example uses `##` sections and no `# ` title
    ([requirements-first](https://kiro.dev/docs/specs/feature-specs/requirements-first/)).
    The codec does not promote a `##` heading to the manifest name. With no
    `# ` heading, the name is the folder slug. The `ears` fixture is that shape.
    
    **Accept when:** every hand-written fixture's golden `spekkr.json` passes
    `check_spec`, the `ears` manifest name is the folder slug, 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-kiro` refuses a Spekkr spec that already has `requirements.md`, and a
    `design.md` that starts with `<!-- spekkr:safety:begin -->`. `to-spekkr`
    refuses a feature folder that already has `spec.md`. It also refuses a
    `design.md` that starts with `<!-- spekkr:safety:begin -->` but is not the
    full safety block. Each failure is a non-zero exit, one `error:` line on
    stderr, and no output folder.
    
    **Accept when:** `collision-requirements`, `collision-safety-marker`, and
    `collision-spec` exit non-zero, their stderr equals the case's `error.txt`,
    and they leave no output folder. A feature `design.md` that starts with the
    begin marker but not the full block fails `to-spekkr` with the error in
    `design.md` and leaves no output folder.
    
    ### R9. No reformatting
    
    Requirement ids, "Accept when" lines, EARS lines, FR/SC lines, and task
    text are copied as written. The codec does not renumber them, does not
    convert prose into EARS, and does not add or remove checkboxes.
    
    Kiro's docs describe `tasks.md` as discrete tasks with outcomes,
    dependencies, and required or optional status. They do not publish the
    markdown schema. Copying bytes is the conservative choice. `design.md`
    records that gap.
    
    **Accept when:** the `requirements` fixture keeps its headings and
    **Accept when** lines, the `ears` fixture keeps its `WHEN` / `THE SYSTEM
    SHALL` lines unchanged, and the `plain` 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 <path>: <reason>` 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. `--steering` checks for existing steering
    files before that write, and a conflict writes neither the feature folder
    nor a steering file.
    
    **Accept when:** `to-kiro` 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. Warning
    
    Every successful `to-kiro` prints one `note:` line on stderr telling the
    person not to let Kiro regenerate `requirements.md`, `design.md`, or
    `tasks.md`. The same warning is inside the safety block, which Kiro loads
    when a chat includes the spec.
    
    What the docs say Kiro will rewrite, and what they do not mention, is
    listed in `design.md`. The repository README quotes the safety block and
    states that warning in the same words.
    
    **Accept when:** every successful `to-kiro` in the checker writes that note
    as its first stderr line, and the repository `README.md` contains the
    safety block bytes.
    
    ### R13. Agent skill
    
    `skills/kiro-codec/SKILL.md` tells an agent when and how to run the codec:
    pulling a Spekkr spec into `.kiro/specs/<name>/`, when to pass
    `--steering`, turning a Kiro 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, to keep requirement text and task text as
    written, and not to ask Kiro to regenerate the three converted files or to
    run Generate Steering Docs over files this codec wrote.
    
    **Accept when:** the skill has `name` and `description` front matter, and
    the `to-kiro` command it gives, run on
    `tests/fixtures/spekkr/basic/source` from an empty directory, writes
    `.kiro/specs/basic/`.
    
    ### R14. Checker and CI
    
    `tests/check.py` runs the round trip, the hand-written fixed point, the
    collision cases, the steering examples, and the flag checks in `design.md`.
    GitHub Actions runs it on Python 3.11 and 3.12.
    
    **Accept when:** `python3 tests/check.py` exits 0 on both versions, and a
    missing required fixture directory fails the checker.
    

    Open spec.md as plain text

  • design.md Command line, mapping, sidecar, safety block bytes, steering rules, Kiro citations, filled-in manifest, every error message, the checker, and unverified Kiro behavior.

    Design

    The codec is one Python 3.11+ file, kiro_codec.py, using only the standard library. It reads the whole input folder into memory as bytes, refuses the collision cases, and writes a new folder. It never modifies the input. Copies are bytes, so line endings, a missing trailing newline, and binary files survive.

    kiro_codec.py to-kiro SPEKKR_FOLDER [--dir FEATURE_FOLDER] [--steering]
    kiro_codec.py to-spekkr FEATURE_FOLDER [--dir SPEKKR_FOLDER]
        [--author USER] [--date YYYY-MM-DD] [--platforms web,cli]

    On success the script prints the folder it wrote on stdout and exits 0. Notes go to stderr as note: lines. A problem is one error: line on stderr and exit 1. A malformed command line gets argparse's usage message and exit 2.

    The script exposes SAFETY_BLOCK and SAFETY_BEGIN (UTF-8 bytes) and the steering helpers named below. The checker imports them.

    Mapping

    SpekkrKiro feature folderBack to Spekkr
    spec.mdrequirements.md, same bytescopied back as spec.md
    design.mddesign.md, safety block at offset 0full block removed when design.md starts with it. A begin marker that is not the full block is an error
    tasks.mdsame bytes, when the file existscopied back
    every other filesame relative path, same bytescopied back
    spekkr.json, spekkr.inputs.json, BUILD.mdsame names inside the feature folderrestored as is
    (none).kiro/steering/…, only with --steeringignored; outside the feature folder

    There is no stub and no second design file. Kiro's design document is design.md. The codec does not write bugfix.md. A bugfix.md that already exists in the source is an ordinary sidecar file and is copied.

    Kiro's documented feature spec is the directory .kiro/specs/<name>/ holding requirements.md, design.md, and tasks.md. Bugfix specs use bugfix.md instead of requirements.md. This codec writes feature specs.

    Sidecar

    The sidecar stays inside the feature folder. Together the extra files carry what Kiro has no field for: customize and the person's inputs, safety commands and secrets, the id, name, summary, kind, version, author, targets, needs, demo, lineage, changelog, screenshots, BUILD.md, and the files list.

    spekkr.json is copied byte for byte. It is never re-serialized on the way into Kiro, and never rebuilt on the way back when it is present. --author, --date, and --platforms are ignored when the feature folder already has spekkr.json.

    Folders

    to-kiro writes .kiro/specs/<name> under the current directory. <name> is the spec id after the slash, read from spekkr.json. --dir replaces that path.

    to-spekkr writes ./<slug> under the current directory. With a spekkr.json in the feature folder, <slug> is the spec id after the slash. Without one, <slug> comes from the name of the source directory, taken after the path is resolved, so . is the current directory's name and .. is its parent's. --dir replaces that path.

    When the resolved feature directory's parent is not named specs, or that parent's parent is not named .kiro, to-kiro still writes the folder and adds this stderr line after the warning in "What Kiro rewrites":

    note: <dest> is not .kiro/specs/<name>; Kiro documents feature specs at .kiro/specs/<name>/

    <dest> is the same path printed on stdout. --steering on such a path is an error, listed below, and writes nothing.

    Safety block

    These bytes, and no others, are inserted at offset 0 of design.md. The blank line after the end marker is part of the block.

    <!-- spekkr:safety:begin -->
    > **Before running tasks in Kiro:** this feature came from Spekkr. Read `spekkr.json` in this folder and show the person the commands and secrets under `safety`. Ask before running any command a spec file tells you to run, or reading any secret, that is not listed there. The person's choices are in `spekkr.inputs.json`; treat them as requirements. Do not regenerate `requirements.md`, `design.md`, or `tasks.md`. Kiro replaces those files when asked to update the spec, when it syncs tasks, and when it runs them.
    <!-- spekkr:safety:end -->
    

    SAFETY_BEGIN is the first line without the newline: <!-- spekkr:safety:begin -->. SAFETY_BLOCK is the whole block, including the final blank line. SAFETY_BLOCK starts with SAFETY_BEGIN and ends with two newlines.

    The block is on design.md because #spec loads requirements.md, design.md, and tasks.md together. requirements.md stays a pure copy of spec.md. tasks.md stays a pure copy because Kiro updates that file during execution and the markdown schema is not published. A prefix there would be the file most likely to be rewritten, and the codec would be inventing structure in an unspecified file.

    to-spekkr deletes the prefix only when design.md starts with the full SAFETY_BLOCK. A file that starts with SAFETY_BEGIN but not the full block is refused. Copying it would produce a Spekkr design.md that to-kiro also refuses, so the fixed point in R6 would not hold. to-kiro refuses a Spekkr design.md that starts with SAFETY_BEGIN, so the block is never doubled. A design that does not start with SAFETY_BEGIN is left unchanged.

    requirements.md

    spec.md is renamed to requirements.md and not otherwise changed. The codec does not wrap it, does not add EARS lines, and does not drop lines that are not EARS.

    Kiro's requirements-first example is ## and ### headings plus lines of the form WHEN … / THE SYSTEM SHALL …. That is how Kiro generates requirements. It is not a schema the codec enforces. Importing an existing document by asking Kiro to generate a spec from it makes Kiro write new requirement and design files. That is a regeneration, which the warning forbids. Editing requirements.md directly is documented and leaves the bytes the person saved.

    Steering

    --steering writes files under <project>/.kiro/steering/. <project> is the parent of the .kiro directory that contains the feature folder. For the default .kiro/specs/pebble-jar, <project> is the current directory and the steering directory is .kiro/steering/.

    Foundation files Kiro documents:

    • product.md: product purpose, target users, key features, business objectives. Included in every interaction by default.
    • tech.md: frameworks, libraries, development tools, technical constraints.
    • structure.md: file organization, naming conventions, import patterns, architectural decisions.

    Inclusion front matter is YAML between --- at the first byte of the file. inclusion: always loads the file in every interaction. inclusion: manual loads it when the chat references #<file-name>. Kiro CLI V3 supports always, fileMatch, manual, and auto. In CLI V1 and V2, always loads automatically, and manual is excluded from automatic loading. Whether #<file-name> activates a manual file on V1 or V2 is not stated. See "Unverified".

    Custom agents do not load steering unless their resources include it, for example file://.kiro/steering/**/*.md. This codec does not write an agent file.

    File references of the form #[[file:<path>]] pull a workspace file into steering. An always-included reference to spekkr.json would pull safety secrets into every chat. Steering's own guidance is to keep secrets out of steering files. This codec does not emit file references.

    What is written

    product_markdown(manifest: dict) -> bytes builds product.md. name is the manifest's name when that is a non-empty string, otherwise the part of id after the slash. summary, kind, and platforms are included only when they qualify:

    • summary: a non-empty string
    • kind: a non-empty string
    • platforms: targets.platforms is a non-empty list and every item is a string. Joined with ", " in list order.

    The file is inclusion: always. Sections that do not qualify are omitted, including the blank line that would have preceded them. The closing paragraph is always present. Users, features, and objectives are not invented.

    tech_markdown(stack: list[str]) -> bytes builds tech.md for a non-empty list of strings that contain no newline. One - <item> line each, in order. inclusion: always. The prose says the lines were copied from targets.stack and that nothing else was added.

    choices_markdown(title: str, feature_rel: str, feature_name: str, inputs: dict) -> bytes builds <feature_name>.md. title is the same string used as Name: in product.md. feature_rel is the feature directory relative to <project>, forward slashes, such as .kiro/specs/pebble-jar. inputs is a JSON object whose values are strings, booleans, or integers, with no newline in a key or a string value. Booleans render as true and false. Integers render in decimal. Key order is the order json.loads preserves. inclusion: manual. The reference in the body is #<feature_name>.

    structure.md is never written.

    Worked examples

    basic, with no kind, no stack, and no spekkr.inputs.json. Manifest fields that steering reads: name is basic, summary is Synthetic basic fixture for the Kiro codec., targets.platforms is ["web"]. product.md is exactly:

    ---
    inclusion: always
    ---
    
    # Product
    
    Name: basic
    
    Summary: Synthetic basic fixture for the Kiro codec.
    
    Platforms: web
    
    These lines are copied from spekkr.json. The manifest did not state target users, key features, or business objectives, so none were added.

    rich-manifest uses id example-user/pebble-jar, name Pebble jar, summary A jar that counts pebbles., kind CLI tool, targets.platforms ["cli"], targets.stack ["Python 3.11+", "Python standard library"]. spekkr.inputs.json is a JSON object {"lid": true, "size": "small"} in that key order. From the current directory, --steering writes:

    product.md

    ---
    inclusion: always
    ---
    
    # Product
    
    Name: Pebble jar
    
    Summary: A jar that counts pebbles.
    
    Kind: CLI tool
    
    Platforms: cli
    
    These lines are copied from spekkr.json. The manifest did not state target users, key features, or business objectives, so none were added.

    tech.md

    ---
    inclusion: always
    ---
    
    # Technology stack
    
    Copied from targets.stack in spekkr.json. Nothing else was added.
    
    - Python 3.11+
    - Python standard library

    pebble-jar.md

    ---
    inclusion: manual
    ---
    
    # Pebble jar
    
    Recorded choices from `spekkr.inputs.json` for `.kiro/specs/pebble-jar/`. They are requirements for that spec. Reference this file with `#pebble-jar` when you want them in the chat. They are not workspace standards.
    
    - lid: true
    - size: small

    Each example ends with a newline and has no extra blank line at the end. The helpers return those bytes for those inputs. The CLI writes the same bytes.

    Steering notes

    On success, after the warning line, stderr continues in this order. A line is skipped when its condition is false, except the three lines marked always.

    1. note: product.md name fell back to the spec id; spekkr.json name was missing when name was not a non-empty string.
    2. note: product.md omitted summary; spekkr.json summary was not a string when summary is present and is not a string. An empty string is treated as absent and produces no note.
    3. note: product.md omitted kind; spekkr.json kind was not a string when kind is present and is not a string. An empty string is absent.
    4. note: product.md omitted platforms; targets.platforms was not a list of strings when targets.platforms is present and is not a list of strings.
    5. note: wrote <dir>/product.md from spekkr.json (always).
    6. note: wrote <dir>/tech.md from targets.stack when tech.md was written. Otherwise note: did not write tech.md; spekkr.json has no targets.stack when the key is absent or the list is empty, or note: did not write tech.md; targets.stack was not a list of strings when the value has the wrong shape or an item contains a newline.
    7. note: did not write structure.md; spekkr.json does not describe the project layout (always).
    8. note: wrote <dir>/<feature>.md from spekkr.inputs.json when the choices file was written. note: did not write a choices file; the spec folder has no spekkr.inputs.json when that file is absent. note: did not write a choices file; spekkr.inputs.json is not an object of strings, booleans and integers when the file is present and does not qualify. A float, null, array, or nested object disqualifies the whole file.
    9. note: safety commands and secrets were not copied into steering (always).

    <dir> is .kiro/steering relative to the current directory when the steering directory is inside it, otherwise the absolute path, with forward slashes.

    An existing file that this run would write is an error, checked before any write. The message names the first such path in sorted order:

    error: .kiro/steering/product.md already exists; --steering will not overwrite it

    The feature name product, tech, or structure would make the choices file collide with a foundation name:

    error: feature name 'product' would overwrite a foundation steering file; rename the feature or skip --steering

    That error is raised when a choices file would be written under that name. It is checked before any write.

    --steering when the feature folder is not .kiro/specs/<name>:

    error: feature folder is not .kiro/specs/<name>; --steering has nowhere documented to write
    Hooks

    Hook files are .kiro/hooks/<name>.json with "version": "v1" and a hooks array. Triggers include PreTaskExecution and PostTaskExecution. A Spekkr manifest has no trigger, matcher, or action. This codec writes no hook. It does not add a hook to protect the spec files, because that behavior is not in the manifest.

    The IDE can create product.md, tech.md, and structure.md from Generate Steering Docs. Whether that button overwrites existing files is not stated. The README tells the person not to run it over steering this codec wrote.

    What Kiro rewrites

    Checked 20 November 2026. Details and gaps are in "Sources" and "Unverified".

    Documented updates:

    • Creating a feature spec generates requirements.md, design.md, and tasks.md. Requirements-first, design-first, and Quick Spec all produce those three files. Quick Spec does it in one pass, with no approval between phases.
    • Asking Kiro to update requirements or design revises those files. Sync Files on tasks.md adds tasks or marks tasks complete.
    • Task execution updates tasks as in progress or completed. Run all Tasks runs incomplete tasks that are marked required, using a dependency graph built from tasks.md.
    • #spec and #spec:<name> include requirements.md, design.md, and tasks.md in the chat. <name> is the directory name under .kiro/specs/.

    The docs do not describe a step that rewrites spekkr.json, spekkr.inputs.json, BUILD.md, or any other sidecar file. They also do not promise those files will be left in place. The warning stands either way.

    No spec index file, and no spec.json, appears in the pages checked. The codec does not write one. The directory name is the spec name those pages use.

    The first stderr line of every successful to-kiro, with or without --steering, is exactly:

    note: do not let Kiro regenerate requirements.md, design.md or tasks.md; updating the spec, Sync Files and task execution replace those files. Other files in the feature folder are not part of the spec Kiro documents.

    to-spekkr does not print that line. A filled-in manifest prints its own notes, below.

    Filled-in manifest

    When the feature folder has no spekkr.json, the script writes one. The text it summarizes is requirements.md, which is saved as spec.md. Key order is spekkr, id, name, summary, version, author, targets, customize, files, needs, demo, safety, lineage, changelog. Indent is two spaces. Non-ASCII is written as UTF-8 rather than escaped. Line endings are \n. The file ends with a newline. Empty objects are {}.

    FieldValue
    id<author>/<slug>. Slug: lowercase the folder name, remove one leading run of digits followed by a hyphen, turn every other character that is not an ASCII letter, digit, or hyphen into a hyphen, then strip hyphens at the ends. A slug that is not a valid id part is an error.
    author.id, author.namethe --author string. It is a Spekkr username: it starts with a lowercase letter or digit, and the rest is lowercase letters, digits, and hyphens.
    nametext after # Feature Specification: in requirements.md; else the first # heading; else the slug. A ## heading is not a title.
    summarythe first plain paragraph after that title. Headings, lists, quotes, tables, and fences are skipped. Whitespace collapses to single spaces. Longer than 140 characters, it is cut at the last space that keeps it within 140, or at 140 when the first 140 characters contain no space. With no paragraph, the name.
    version0.1.0
    changelogone entry, version 0.1.0, note Converted from Kiro., date from --date or 1970-01-01. The date is a real calendar date, leap days included.
    targets.platforms--platforms split on commas and trimmed, default ["web"]. Each value is one of web, mobile, desktop, backend, cli, listed once.
    filesspec.md, design.md, then tasks.md if that file exists in the feature folder, then every other output file sorted by relative path, each as {"path": ...}. requirements.md is not listed; it became spec.md.
    customize, safety, needs, demo, lineageempty objects

    A plain paragraph line is non-empty and does not start, after stripping, with #, >, |, ```, - , * , or + , and is not <digits>. .

    Stderr then carries these note: lines, in this order, each prefixed with note: :

    • filled in spekkr.json for <author>/<slug> because the feature folder has no spekkr.json
    • summary: <summary> (review it before publishing)
    • summary was cut to 140 characters at a word boundary when it was cut
    • requirements.md is not UTF-8; the name and summary fell back when the file is not UTF-8. The name and summary are then the slug.
    • name fell back to the folder slug <slug> when the file is UTF-8 and has no usable # title
    • author.name is <author>, the same as author.id
    • version is 0.1.0; customize and safety are empty
    • changelog date is 1970-01-01 because --date was not given when --date was omitted

    Reading and writing

    The source is walked with os.walk(..., onerror=...), directories and files in sorted order. A directory that cannot be listed raises, so it is never silently skipped. A symlink, or anything that is not a regular file or directory, is refused. Empty directories are kept.

    The output is written to a temporary sibling folder named .<name>.spekkr-tmp-<pid> and renamed into place. The temporary folder is removed if anything fails. An output folder that exists and is empty is replaced. An output folder that exists and holds an entry is refused. All checks, including steering conflicts, run before the first write.

    to-kiro requires spekkr.json, spec.md, and design.md. tasks.md is optional. to-spekkr requires requirements.md and design.md.

    A spec id is username/name, one slash, each part a valid username as defined for --author.

    Errors

    Each error is one stderr line starting with error: , exit 1, nothing on stdout, and no output folder. Steering files are included in "no output".

    SituationMessage after error:
    Spekkr folder has requirements.mdthis Spekkr spec already has requirements.md; to-kiro will not overwrite it
    Spekkr design.md starts with the begin markerdesign.md already starts with <!-- spekkr:safety:begin -->; to-kiro will not add the safety block again
    Feature folder has spec.mdfeature folder already has spec.md; to-spekkr will not overwrite it
    Feature design.md starts with the begin marker but not the full blockdesign.md starts with <!-- spekkr:safety:begin --> but is not the safety block; to-spekkr will not convert it
    No spekkr.json and no --author--author is required when the feature folder has no spekkr.json
    A directory or file cannot be readcannot read <path>: <reason>
    Spekkr folder has no spekkr.jsonno spekkr.json in the Spekkr spec folder
    Spekkr folder has no spec.mdSpekkr spec has no spec.md to convert into requirements.md
    Spekkr folder has no design.mdSpekkr spec has no design.md
    Feature folder has no requirements.mdfeature folder has no requirements.md to convert into spec.md
    Feature folder has no design.mdfeature folder has no design.md
    spekkr.json is not a JSON objectspekkr.json is not UTF-8 JSON: ... or spekkr.json must be a JSON object
    spekkr.json has a bad idspekkr.json id must look like username/name, got ...
    Bad --author--author must be a Spekkr username of lowercase letters, digits and hyphens, got '<value>'
    Bad --date--date must be a calendar date like 2026-01-01, got '<value>'
    Bad --platformsa line naming the flag, the value, and the allowed list web, mobile, desktop, backend, cli
    Folder name gives no valid slugfolder name '<name>' does not make a Spekkr id
    Source is not a foldernot a folder: <path>
    A symlink or special filerefusing to follow a symlink: <path> or not a regular file: <path>
    Output exists and is not emptyoutput folder <path> already exists and is not empty
    Output is inside the inputoutput folder <dest> is inside the input folder <source>; pass --dir outside it
    --steering and the feature path is not .kiro/specs/<name>feature folder is not .kiro/specs/<name>; --steering has nowhere documented to write
    Steering file already exists<path> already exists; --steering will not overwrite it
    Choices file would be named product, tech, or structurefeature name '<name>' would overwrite a foundation steering file; rename the feature or skip --steering

    The collision fixtures' error.txt files are the first, second, and third messages, each as a full stderr line ending in a newline.

    Checker

    tests/check.py runs a codec as a subprocess and imports SAFETY_BLOCK, SAFETY_BEGIN, product_markdown, tech_markdown, and choices_markdown. The optional argument is another codec with the same commands and the same helpers.

    Fixtures are synthetic, committed under tests/fixtures/. Each case has a one-line README. The checker fails if any required case directory is missing.

    Spekkr cases (tests/fixtures/spekkr/<case>/): basic, requirements, crlf, no-final-newline, unicode, extra-files, large-file, odd-manifest, with-build, inputs-present, inputs-absent, no-tasks, rich-manifest, collision-requirements, collision-safety-marker.

    source/ is converted with to-kiro and back with to-spekkr. The round trip equals source/. The feature folder equals expected/. design.md in the feature folder starts with SAFETY_BLOCK and the remainder equals the source design.md. requirements.md equals the source spec.md. to-kiro stderr is exactly the warning line. to-spekkr stderr is empty. A case with error.txt fails with that stderr and writes nothing.

    basic uses the steering fields in the worked example, including id example-user/basic. rich-manifest uses id example-user/pebble-jar and the worked-example fields. inputs-absent has a non-empty customize and no spekkr.inputs.json. with-build has a BUILD.md. large-file has a file over 60 KB. extra-files has a PNG under shots/ and a nested text file. requirements has ### R1. and **Accept when:** lines.

    Hand-written cases (tests/fixtures/handwritten/<case>/): plain, ears, long-summary, no-heading, no-tasks, numbered, odd-name, unicode-title, with-docs, prefixed-design, collision-spec.

    The source is placed under the name in folder-name, or the case name. Conversion uses --author example-user --date 2026-01-01. The checker compares the fixed point, the stability of to-spekkr, and the goldens expected-spekkr/ and expected-fixed/. Source requirements.md equals Spekkr spec.md. Source design.md equals Spekkr design.md after removing SAFETY_BLOCK when the source starts with that block. prefixed-design starts with the full block. ears has ## headings, WHEN / THE SYSTEM SHALL lines, and no # heading, and its manifest name is the slug. plain keeps an FR line and a - [ ] task. collision-spec contains both requirements.md and spec.md.

    Flag checks:

    • Default to-kiro writes .kiro/specs/basic and no .kiro/steering.
    • --dir .kiro/specs/003-basic writes that folder. stderr includes the warning and does not include the "not .kiro/specs" note.
    • --dir features/basic writes the folder, stderr includes the "not .kiro/specs" note, and --steering with that --dir is the steering path error and leaves no folder.
    • --steering on basic writes the basic product.md example and the notes for a missing stack, a missing structure file, a missing inputs file, and safety. It writes no tech.md, no choices file, no structure.md, and no .kiro/hooks.
    • --steering on rich-manifest writes the three worked examples. The helpers return those same bytes.
    • --steering when .kiro/steering/product.md already exists writes nothing.
    • A feature named product that has a qualifying inputs file hits the foundation-name error and writes nothing.
    • inputs-absent with --steering does not write a choices file. The note says the inputs file is absent. customize is not copied.
    • Default to-spekkr of 003-example writes ./example.
    • Omitting --date writes 1970-01-01 and the default-date note.
    • --platforms cli, backend writes ["cli", "backend"].
    • . and .. use the directory name, as in R6.
    • An unreadable directory aborts with error: cannot read and writes nothing. Skipped when the checker is root.
    • A design.md that starts with SAFETY_BEGIN but not SAFETY_BLOCK makes to-spekkr exit non-zero, print error: design.md starts with <!-- spekkr:safety:begin --> but is not the safety block; to-spekkr will not convert it, and write nothing. That input is outside the R6 fixed point.
    • product_markdown on a manifest with no summary omits the Summary line.
    • The repository README contains SAFETY_BLOCK when the checker is the one in this repository, not when it is pointed at another codec.

    Every hand-written fixture's golden spekkr.json is sent to Spekkr's check_spec and must pass.

    The success line is Kiro codec checks passed (tests/fixtures).

    Sources

    Pages read on 20 November 2026. "Updated" is the date printed on the page when it had one.

    Fact used abovePage
    A spec is requirements.md or bugfix.md, plus design.md and tasks.md. Mobile shows the three markdown files. Task execution updates tasks as in progress or completed and runs independent tasks in waves.Specs, updated 12 November 2026
    Specs are project scope .kiro/specs/. Steering is .kiro/steering/. Hooks are .kiro/hooks/.Configuration
    Feature specs are requirements-first or design-first. Requirements use EARS: WHEN / THE SYSTEM SHALL. design.md is the technical design.Feature specs, updated 4 August 2026
    Generated requirements use ## / ### headings and EARS lines. Tasks are discrete, with outcomes, dependencies, and optional or required status. The markdown of tasks.md is not shown.Requirements-first
    Design-first generates design.md, then requirements, then the same kind of tasks.Design-first
    Quick Spec writes the same three files under .kiro/specs/ with no approval between phases. Asking Kiro to refine requirements, then Sync Files, regenerates tasks.Quick spec
    Iteration asks Kiro to revise design.md or regenerate requirements. Sync Files creates tasks or marks them complete. Run all Tasks runs incomplete required tasks and builds a dependency graph. #spec and #spec:<name> load the three files. The tree .kiro/specs/user-authentication/ is the documented layout. Asking Kiro to generate a spec from an existing file writes new requirement and design docs.Best practices, updated 25 September 2026
    Workspace steering is .kiro/steering/. Foundation files are product.md, tech.md, and structure.md, included by default. Generate Steering Docs creates those three in the IDE. Front matter sets inclusion to always, fileMatch, manual, or auto. Manual files are referenced as #<file-name>. CLI V3 implements all four modes. V1 and V2 load always and exclude manual from automatic loading. Custom agents need resources. #[[file:<path>]] includes a workspace file. Secrets do not belong in steering.Steering
    A hook file is .kiro/hooks/<name>.json, "version": "v1", with a hooks array, a PascalCase trigger, and a command or agent action.Hooks, updated 12 November 2026
    PreTaskExecution runs before a spec task. PostTaskExecution runs after.Hook triggers

    Unverified

    The codec's behavior on each gap is already fixed above. These are the points the pages do not settle.

    1. tasks.md has no published markdown schema. The docs name outcomes, dependencies, required and optional tasks, and status updates. They do not show checkboxes, ids, or a status token. The codec copies the file. After Run all Tasks, Sync Files, or a task run, a byte-for-byte round trip of tasks.md will not hold, because those actions update the file.
    2. The dependency-graph rules used for parallel tasks are not published.
    3. Nothing in the docs says Kiro deletes unknown files in a spec folder. Nothing says it preserves them. Sidecar survival is not a guarantee.
    4. Nothing in the docs says Generate Steering Docs overwrites an existing product.md or tech.md. Nothing says it keeps them. The README tells the person not to run that action over these files.
    5. Nothing in the docs says a requirements.md that is not EARS is rejected, and nothing says task execution requires EARS. Direct edits are documented. The codec does not convert to EARS.
    6. No page checked describes a spec.json or other registry. That absence is not proof the product has none. The codec writes no registry file.
    7. Whether a directory dropped into .kiro/specs/ by another tool appears in the specs list without a Kiro session creating it is not a documented step. The pages identify a feature by that path and by #spec:<name>.
    8. Whether #<file-name> loads a manual steering file on CLI V1 or V2 is not stated. V3 does. The file is still written.
    9. The docs do not say that opening a converted spec, with no further request, rewrites it. They do say that update requests, Sync Files, Quick Spec, and task execution change the three files.
    # Design
    
    The codec is one Python 3.11+ file, `kiro_codec.py`, using only the
    standard library. It reads the whole input folder into memory as bytes,
    refuses the collision cases, and writes a new folder. It never modifies
    the input. Copies are bytes, so line endings, a missing trailing newline,
    and binary files survive.
    
    ```text
    kiro_codec.py to-kiro SPEKKR_FOLDER [--dir FEATURE_FOLDER] [--steering]
    kiro_codec.py to-spekkr FEATURE_FOLDER [--dir SPEKKR_FOLDER]
        [--author USER] [--date YYYY-MM-DD] [--platforms web,cli]
    ```
    
    On success the script prints the folder it wrote on stdout and exits 0.
    Notes go to stderr as `note:` lines. A problem is one `error:` line on
    stderr and exit 1. A malformed command line gets argparse's usage message
    and exit 2.
    
    The script exposes `SAFETY_BLOCK` and `SAFETY_BEGIN` (UTF-8 bytes) and the
    steering helpers named below. The checker imports them.
    
    ## Mapping
    
    | Spekkr | Kiro feature folder | Back to Spekkr |
    | --- | --- | --- |
    | `spec.md` | `requirements.md`, same bytes | copied back as `spec.md` |
    | `design.md` | `design.md`, safety block at offset 0 | full block removed when `design.md` starts with it. A begin marker that is not the full block is an error |
    | `tasks.md` | same bytes, when the file exists | copied back |
    | every other file | same relative path, same bytes | copied back |
    | `spekkr.json`, `spekkr.inputs.json`, `BUILD.md` | same names inside the feature folder | restored as is |
    | (none) | `.kiro/steering/…`, only with `--steering` | ignored; outside the feature folder |
    
    There is no stub and no second design file. Kiro's design document is
    `design.md`. The codec does not write `bugfix.md`. A `bugfix.md` that
    already exists in the source is an ordinary sidecar file and is copied.
    
    Kiro's documented feature spec is the directory `.kiro/specs/<name>/`
    holding `requirements.md`, `design.md`, and `tasks.md`. Bugfix specs use
    `bugfix.md` instead of `requirements.md`. This codec writes feature specs.
    
    ## Sidecar
    
    The sidecar stays inside the feature folder. Together the extra files
    carry what Kiro has no field for: `customize` and the person's inputs,
    `safety` commands and secrets, the id, name, summary, kind, version,
    author, targets, needs, demo, lineage, changelog, screenshots, `BUILD.md`,
    and the `files` list.
    
    `spekkr.json` is copied byte for byte. It is never re-serialized on the
    way into Kiro, and never rebuilt on the way back when it is present.
    `--author`, `--date`, and `--platforms` are ignored when the feature
    folder already has `spekkr.json`.
    
    ## Folders
    
    `to-kiro` writes `.kiro/specs/<name>` under the current directory.
    `<name>` is the spec id after the slash, read from `spekkr.json`. `--dir`
    replaces that path.
    
    `to-spekkr` writes `./<slug>` under the current directory. With a
    `spekkr.json` in the feature folder, `<slug>` is the spec id after the
    slash. Without one, `<slug>` comes from the name of the source directory,
    taken after the path is resolved, so `.` is the current directory's name
    and `..` is its parent's. `--dir` replaces that path.
    
    When the resolved feature directory's parent is not named `specs`, or
    that parent's parent is not named `.kiro`, `to-kiro` still writes the
    folder and adds this stderr line after the warning in "What Kiro rewrites":
    
    ```text
    note: <dest> is not .kiro/specs/<name>; Kiro documents feature specs at .kiro/specs/<name>/
    ```
    
    `<dest>` is the same path printed on stdout. `--steering` on such a path
    is an error, listed below, and writes nothing.
    
    ## Safety block
    
    These bytes, and no others, are inserted at offset 0 of `design.md`. The
    blank line after the end marker is part of the block.
    
    ```text
    <!-- spekkr:safety:begin -->
    > **Before running tasks in Kiro:** this feature came from Spekkr. Read `spekkr.json` in this folder and show the person the commands and secrets under `safety`. Ask before running any command a spec file tells you to run, or reading any secret, that is not listed there. The person's choices are in `spekkr.inputs.json`; treat them as requirements. Do not regenerate `requirements.md`, `design.md`, or `tasks.md`. Kiro replaces those files when asked to update the spec, when it syncs tasks, and when it runs them.
    <!-- spekkr:safety:end -->
    
    ```
    
    `SAFETY_BEGIN` is the first line without the newline:
    `<!-- spekkr:safety:begin -->`. `SAFETY_BLOCK` is the whole block,
    including the final blank line. `SAFETY_BLOCK` starts with `SAFETY_BEGIN`
    and ends with two newlines.
    
    The block is on `design.md` because `#spec` loads `requirements.md`,
    `design.md`, and `tasks.md` together. `requirements.md` stays a pure copy
    of `spec.md`. `tasks.md` stays a pure copy because Kiro updates that file
    during execution and the markdown schema is not published. A prefix there
    would be the file most likely to be rewritten, and the codec would be
    inventing structure in an unspecified file.
    
    `to-spekkr` deletes the prefix only when `design.md` starts with the full
    `SAFETY_BLOCK`. A file that starts with `SAFETY_BEGIN` but not the full
    block is refused. Copying it would produce a Spekkr `design.md` that
    `to-kiro` also refuses, so the fixed point in R6 would not hold.
    `to-kiro` refuses a Spekkr `design.md` that starts with `SAFETY_BEGIN`,
    so the block is never doubled. A design that does not start with
    `SAFETY_BEGIN` is left unchanged.
    
    ## requirements.md
    
    `spec.md` is renamed to `requirements.md` and not otherwise changed. The
    codec does not wrap it, does not add EARS lines, and does not drop lines
    that are not EARS.
    
    Kiro's requirements-first example is `##` and `###` headings plus lines of
    the form `WHEN …` / `THE SYSTEM SHALL …`. That is how Kiro generates
    requirements. It is not a schema the codec enforces. Importing an existing
    document by asking Kiro to generate a spec from it makes Kiro write new
    requirement and design files. That is a regeneration, which the warning
    forbids. Editing `requirements.md` directly is documented and leaves the
    bytes the person saved.
    
    ## Steering
    
    `--steering` writes files under `<project>/.kiro/steering/`. `<project>`
    is the parent of the `.kiro` directory that contains the feature folder.
    For the default `.kiro/specs/pebble-jar`, `<project>` is the current
    directory and the steering directory is `.kiro/steering/`.
    
    Foundation files Kiro documents:
    
    - `product.md`: product purpose, target users, key features, business
      objectives. Included in every interaction by default.
    - `tech.md`: frameworks, libraries, development tools, technical
      constraints.
    - `structure.md`: file organization, naming conventions, import patterns,
      architectural decisions.
    
    Inclusion front matter is YAML between `---` at the first byte of the
    file. `inclusion: always` loads the file in every interaction.
    `inclusion: manual` loads it when the chat references `#<file-name>`.
    Kiro CLI V3 supports `always`, `fileMatch`, `manual`, and `auto`. In CLI
    V1 and V2, `always` loads automatically, and `manual` is excluded from
    automatic loading. Whether `#<file-name>` activates a manual file on V1
    or V2 is not stated. See "Unverified".
    
    Custom agents do not load steering unless their `resources` include it,
    for example `file://.kiro/steering/**/*.md`. This codec does not write an
    agent file.
    
    File references of the form `#[[file:<path>]]` pull a workspace file into
    steering. An always-included reference to `spekkr.json` would pull
    `safety` secrets into every chat. Steering's own guidance is to keep
    secrets out of steering files. This codec does not emit file references.
    
    ### What is written
    
    `product_markdown(manifest: dict) -> bytes` builds `product.md`. `name` is
    the manifest's `name` when that is a non-empty string, otherwise the part
    of `id` after the slash. `summary`, `kind`, and platforms are included
    only when they qualify:
    
    - `summary`: a non-empty string
    - `kind`: a non-empty string
    - platforms: `targets.platforms` is a non-empty list and every item is a
      string. Joined with `", "` in list order.
    
    The file is `inclusion: always`. Sections that do not qualify are omitted,
    including the blank line that would have preceded them. The closing
    paragraph is always present. Users, features, and objectives are not
    invented.
    
    `tech_markdown(stack: list[str]) -> bytes` builds `tech.md` for a
    non-empty list of strings that contain no newline. One `- <item>` line
    each, in order. `inclusion: always`. The prose says the lines were copied
    from `targets.stack` and that nothing else was added.
    
    `choices_markdown(title: str, feature_rel: str, feature_name: str, inputs: dict) -> bytes`
    builds `<feature_name>.md`. `title` is the same string used as `Name:` in
    `product.md`. `feature_rel` is the feature directory relative to
    `<project>`, forward slashes, such as `.kiro/specs/pebble-jar`. `inputs`
    is a JSON object whose values are strings, booleans, or integers, with no
    newline in a key or a string value. Booleans render as `true` and `false`.
    Integers render in decimal. Key order is the order `json.loads` preserves.
    `inclusion: manual`. The reference in the body is `#<feature_name>`.
    
    `structure.md` is never written.
    
    ### Worked examples
    
    `basic`, with no `kind`, no `stack`, and no `spekkr.inputs.json`. Manifest
    fields that steering reads: `name` is `basic`, `summary` is `Synthetic
    basic fixture for the Kiro codec.`, `targets.platforms` is `["web"]`.
    `product.md` is exactly:
    
    ```text
    ---
    inclusion: always
    ---
    
    # Product
    
    Name: basic
    
    Summary: Synthetic basic fixture for the Kiro codec.
    
    Platforms: web
    
    These lines are copied from spekkr.json. The manifest did not state target users, key features, or business objectives, so none were added.
    ```
    
    `rich-manifest` uses id `example-user/pebble-jar`, `name` `Pebble jar`,
    `summary` `A jar that counts pebbles.`, `kind` `CLI tool`,
    `targets.platforms` `["cli"]`, `targets.stack` `["Python 3.11+", "Python standard library"]`.
    `spekkr.inputs.json` is a JSON object `{"lid": true, "size": "small"}` in
    that key order. From the current directory, `--steering` writes:
    
    `product.md`
    
    ```text
    ---
    inclusion: always
    ---
    
    # Product
    
    Name: Pebble jar
    
    Summary: A jar that counts pebbles.
    
    Kind: CLI tool
    
    Platforms: cli
    
    These lines are copied from spekkr.json. The manifest did not state target users, key features, or business objectives, so none were added.
    ```
    
    `tech.md`
    
    ```text
    ---
    inclusion: always
    ---
    
    # Technology stack
    
    Copied from targets.stack in spekkr.json. Nothing else was added.
    
    - Python 3.11+
    - Python standard library
    ```
    
    `pebble-jar.md`
    
    ```text
    ---
    inclusion: manual
    ---
    
    # Pebble jar
    
    Recorded choices from `spekkr.inputs.json` for `.kiro/specs/pebble-jar/`. They are requirements for that spec. Reference this file with `#pebble-jar` when you want them in the chat. They are not workspace standards.
    
    - lid: true
    - size: small
    ```
    
    Each example ends with a newline and has no extra blank line at the end.
    The helpers return those bytes for those inputs. The CLI writes the same
    bytes.
    
    ### Steering notes
    
    On success, after the warning line, stderr continues in this order. A line
    is skipped when its condition is false, except the three lines marked
    always.
    
    1. `note: product.md name fell back to the spec id; spekkr.json name was missing` when `name` was not a non-empty string.
    2. `note: product.md omitted summary; spekkr.json summary was not a string` when `summary` is present and is not a string. An empty string is treated as absent and produces no note.
    3. `note: product.md omitted kind; spekkr.json kind was not a string` when `kind` is present and is not a string. An empty string is absent.
    4. `note: product.md omitted platforms; targets.platforms was not a list of strings` when `targets.platforms` is present and is not a list of strings.
    5. `note: wrote <dir>/product.md from spekkr.json` (always).
    6. `note: wrote <dir>/tech.md from targets.stack` when tech.md was written. Otherwise `note: did not write tech.md; spekkr.json has no targets.stack` when the key is absent or the list is empty, or `note: did not write tech.md; targets.stack was not a list of strings` when the value has the wrong shape or an item contains a newline.
    7. `note: did not write structure.md; spekkr.json does not describe the project layout` (always).
    8. `note: wrote <dir>/<feature>.md from spekkr.inputs.json` when the choices file was written. `note: did not write a choices file; the spec folder has no spekkr.inputs.json` when that file is absent. `note: did not write a choices file; spekkr.inputs.json is not an object of strings, booleans and integers` when the file is present and does not qualify. A float, null, array, or nested object disqualifies the whole file.
    9. `note: safety commands and secrets were not copied into steering` (always).
    
    `<dir>` is `.kiro/steering` relative to the current directory when the
    steering directory is inside it, otherwise the absolute path, with forward
    slashes.
    
    An existing file that this run would write is an error, checked before any
    write. The message names the first such path in sorted order:
    
    ```text
    error: .kiro/steering/product.md already exists; --steering will not overwrite it
    ```
    
    The feature name `product`, `tech`, or `structure` would make the choices
    file collide with a foundation name:
    
    ```text
    error: feature name 'product' would overwrite a foundation steering file; rename the feature or skip --steering
    ```
    
    That error is raised when a choices file would be written under that name.
    It is checked before any write.
    
    `--steering` when the feature folder is not `.kiro/specs/<name>`:
    
    ```text
    error: feature folder is not .kiro/specs/<name>; --steering has nowhere documented to write
    ```
    
    ### Hooks
    
    Hook files are `.kiro/hooks/<name>.json` with `"version": "v1"` and a
    `hooks` array. Triggers include `PreTaskExecution` and `PostTaskExecution`.
    A Spekkr manifest has no trigger, matcher, or action. This codec writes no
    hook. It does not add a hook to protect the spec files, because that
    behavior is not in the manifest.
    
    The IDE can create `product.md`, `tech.md`, and `structure.md` from
    Generate Steering Docs. Whether that button overwrites existing files is
    not stated. The README tells the person not to run it over steering this
    codec wrote.
    
    ## What Kiro rewrites
    
    Checked 20 November 2026. Details and gaps are in "Sources" and
    "Unverified".
    
    Documented updates:
    
    - Creating a feature spec generates `requirements.md`, `design.md`, and
      `tasks.md`. Requirements-first, design-first, and Quick Spec all produce
      those three files. Quick Spec does it in one pass, with no approval
      between phases.
    - Asking Kiro to update requirements or design revises those files. Sync
      Files on `tasks.md` adds tasks or marks tasks complete.
    - Task execution updates tasks as in progress or completed. Run all Tasks
      runs incomplete tasks that are marked required, using a dependency graph
      built from `tasks.md`.
    - `#spec` and `#spec:<name>` include `requirements.md`, `design.md`, and
      `tasks.md` in the chat. `<name>` is the directory name under
      `.kiro/specs/`.
    
    The docs do not describe a step that rewrites `spekkr.json`,
    `spekkr.inputs.json`, `BUILD.md`, or any other sidecar file. They also do
    not promise those files will be left in place. The warning stands either
    way.
    
    No spec index file, and no `spec.json`, appears in the pages checked. The
    codec does not write one. The directory name is the spec name those pages
    use.
    
    The first stderr line of every successful `to-kiro`, with or without
    `--steering`, is exactly:
    
    ```text
    note: do not let Kiro regenerate requirements.md, design.md or tasks.md; updating the spec, Sync Files and task execution replace those files. Other files in the feature folder are not part of the spec Kiro documents.
    ```
    
    `to-spekkr` does not print that line. A filled-in manifest prints its own
    notes, below.
    
    ## Filled-in manifest
    
    When the feature folder has no `spekkr.json`, the script writes one. The
    text it summarizes is `requirements.md`, which is saved as `spec.md`. Key
    order is `spekkr`, `id`, `name`, `summary`, `version`, `author`,
    `targets`, `customize`, `files`, `needs`, `demo`, `safety`, `lineage`,
    `changelog`. Indent is two spaces. Non-ASCII is written as UTF-8 rather
    than escaped. Line endings are `\n`. The file ends with a newline. Empty
    objects are `{}`.
    
    | Field | Value |
    | --- | --- |
    | `id` | `<author>/<slug>`. Slug: lowercase the folder name, remove one leading run of digits followed by a hyphen, turn every other character that is not an ASCII letter, digit, or hyphen into a hyphen, then strip hyphens at the ends. A slug that is not a valid id part is an error. |
    | `author.id`, `author.name` | the `--author` string. It is a Spekkr username: it starts with a lowercase letter or digit, and the rest is lowercase letters, digits, and hyphens. |
    | `name` | text after `# Feature Specification:` in `requirements.md`; else the first `# ` heading; else the slug. A `##` heading is not a title. |
    | `summary` | the first plain paragraph after that title. Headings, lists, quotes, tables, and fences are skipped. Whitespace collapses to single spaces. Longer than 140 characters, it is cut at the last space that keeps it within 140, or at 140 when the first 140 characters contain no space. With no paragraph, the name. |
    | `version` | `0.1.0` |
    | `changelog` | one entry, version `0.1.0`, note `Converted from Kiro.`, date from `--date` or `1970-01-01`. The date is a real calendar date, leap days included. |
    | `targets.platforms` | `--platforms` split on commas and trimmed, default `["web"]`. Each value is one of `web`, `mobile`, `desktop`, `backend`, `cli`, listed once. |
    | `files` | `spec.md`, `design.md`, then `tasks.md` if that file exists in the feature folder, then every other output file sorted by relative path, each as `{"path": ...}`. `requirements.md` is not listed; it became `spec.md`. |
    | `customize`, `safety`, `needs`, `demo`, `lineage` | empty objects |
    
    A plain paragraph line is non-empty and does not start, after stripping,
    with `#`, `>`, `|`, `` ``` ``, `- `, `* `, or `+ `, and is not
    `<digits>. `.
    
    Stderr then carries these `note:` lines, in this order, each prefixed with
    `note: `:
    
    - `filled in spekkr.json for <author>/<slug> because the feature folder has no spekkr.json`
    - `summary: <summary> (review it before publishing)`
    - `summary was cut to 140 characters at a word boundary` when it was cut
    - `requirements.md is not UTF-8; the name and summary fell back` when the file is not UTF-8. The name and summary are then the slug.
    - `name fell back to the folder slug <slug>` when the file is UTF-8 and has no usable `# ` title
    - `author.name is <author>, the same as author.id`
    - `version is 0.1.0; customize and safety are empty`
    - `changelog date is 1970-01-01 because --date was not given` when `--date` was omitted
    
    ## Reading and writing
    
    The source is walked with `os.walk(..., onerror=...)`, directories and
    files in sorted order. A directory that cannot be listed raises, so it is
    never silently skipped. A symlink, or anything that is not a regular file
    or directory, is refused. Empty directories are kept.
    
    The output is written to a temporary sibling folder named
    `.<name>.spekkr-tmp-<pid>` and renamed into place. The temporary folder is
    removed if anything fails. An output folder that exists and is empty is
    replaced. An output folder that exists and holds an entry is refused.
    All checks, including steering conflicts, run before the first write.
    
    `to-kiro` requires `spekkr.json`, `spec.md`, and `design.md`. `tasks.md`
    is optional. `to-spekkr` requires `requirements.md` and `design.md`.
    
    A spec id is `username/name`, one slash, each part a valid username as
    defined for `--author`.
    
    ## Errors
    
    Each error is one stderr line starting with `error: `, exit 1, nothing on
    stdout, and no output folder. Steering files are included in "no output".
    
    | Situation | Message after `error: ` |
    | --- | --- |
    | Spekkr folder has `requirements.md` | `this Spekkr spec already has requirements.md; to-kiro will not overwrite it` |
    | Spekkr `design.md` starts with the begin marker | `design.md already starts with <!-- spekkr:safety:begin -->; to-kiro will not add the safety block again` |
    | Feature folder has `spec.md` | `feature folder already has spec.md; to-spekkr will not overwrite it` |
    | Feature `design.md` starts with the begin marker but not the full block | `design.md starts with <!-- spekkr:safety:begin --> but is not the safety block; to-spekkr will not convert it` |
    | No `spekkr.json` and no `--author` | `--author is required when the feature folder has no spekkr.json` |
    | A directory or file cannot be read | `cannot read <path>: <reason>` |
    | Spekkr folder has no `spekkr.json` | `no spekkr.json in the Spekkr spec folder` |
    | Spekkr folder has no `spec.md` | `Spekkr spec has no spec.md to convert into requirements.md` |
    | Spekkr folder has no `design.md` | `Spekkr spec has no design.md` |
    | Feature folder has no `requirements.md` | `feature folder has no requirements.md to convert into spec.md` |
    | Feature folder has no `design.md` | `feature folder has no design.md` |
    | `spekkr.json` is not a JSON object | `spekkr.json is not UTF-8 JSON: ...` or `spekkr.json must be a JSON object` |
    | `spekkr.json` has a bad id | `spekkr.json id must look like username/name, got ...` |
    | Bad `--author` | `--author must be a Spekkr username of lowercase letters, digits and hyphens, got '<value>'` |
    | Bad `--date` | `--date must be a calendar date like 2026-01-01, got '<value>'` |
    | Bad `--platforms` | a line naming the flag, the value, and the allowed list `web, mobile, desktop, backend, cli` |
    | Folder name gives no valid slug | `folder name '<name>' does not make a Spekkr id` |
    | Source is not a folder | `not a folder: <path>` |
    | A symlink or special file | `refusing to follow a symlink: <path>` or `not a regular file: <path>` |
    | Output exists and is not empty | `output folder <path> already exists and is not empty` |
    | Output is inside the input | `output folder <dest> is inside the input folder <source>; pass --dir outside it` |
    | `--steering` and the feature path is not `.kiro/specs/<name>` | `feature folder is not .kiro/specs/<name>; --steering has nowhere documented to write` |
    | Steering file already exists | `<path> already exists; --steering will not overwrite it` |
    | Choices file would be named `product`, `tech`, or `structure` | `feature name '<name>' would overwrite a foundation steering file; rename the feature or skip --steering` |
    
    The collision fixtures' `error.txt` files are the first, second, and third
    messages, each as a full stderr line ending in a newline.
    
    ## Checker
    
    `tests/check.py` runs a codec as a subprocess and imports `SAFETY_BLOCK`,
    `SAFETY_BEGIN`, `product_markdown`, `tech_markdown`, and
    `choices_markdown`. The optional argument is another codec with the same
    commands and the same helpers.
    
    Fixtures are synthetic, committed under `tests/fixtures/`. Each case has a
    one-line `README`. The checker fails if any required case directory is
    missing.
    
    Spekkr cases (`tests/fixtures/spekkr/<case>/`): `basic`, `requirements`,
    `crlf`, `no-final-newline`, `unicode`, `extra-files`, `large-file`,
    `odd-manifest`, `with-build`, `inputs-present`, `inputs-absent`,
    `no-tasks`, `rich-manifest`, `collision-requirements`,
    `collision-safety-marker`.
    
    `source/` is converted with `to-kiro` and back with `to-spekkr`. The round
    trip equals `source/`. The feature folder equals `expected/`. `design.md`
    in the feature folder starts with `SAFETY_BLOCK` and the remainder equals
    the source `design.md`. `requirements.md` equals the source `spec.md`.
    `to-kiro` stderr is exactly the warning line. `to-spekkr` stderr is empty.
    A case with `error.txt` fails with that stderr and writes nothing.
    
    `basic` uses the steering fields in the worked example, including id
    `example-user/basic`. `rich-manifest` uses id `example-user/pebble-jar`
    and the worked-example fields. `inputs-absent` has a non-empty `customize`
    and no `spekkr.inputs.json`. `with-build` has a `BUILD.md`. `large-file`
    has a file over 60 KB. `extra-files` has a PNG under `shots/` and a nested
    text file. `requirements` has `### R1.` and `**Accept when:**` lines.
    
    Hand-written cases (`tests/fixtures/handwritten/<case>/`): `plain`,
    `ears`, `long-summary`, `no-heading`, `no-tasks`, `numbered`, `odd-name`,
    `unicode-title`, `with-docs`, `prefixed-design`, `collision-spec`.
    
    The source is placed under the name in `folder-name`, or the case name.
    Conversion uses `--author example-user --date 2026-01-01`. The checker
    compares the fixed point, the stability of `to-spekkr`, and the goldens
    `expected-spekkr/` and `expected-fixed/`. Source `requirements.md` equals
    Spekkr `spec.md`. Source `design.md` equals Spekkr `design.md` after
    removing `SAFETY_BLOCK` when the source starts with that block.
    `prefixed-design` starts with the full block. `ears` has `##` headings,
    `WHEN` / `THE SYSTEM SHALL` lines, and no `# ` heading, and its manifest
    name is the slug. `plain` keeps an FR line and a `- [ ]` task.
    `collision-spec` contains both `requirements.md` and `spec.md`.
    
    Flag checks:
    
    - Default `to-kiro` writes `.kiro/specs/basic` and no `.kiro/steering`.
    - `--dir .kiro/specs/003-basic` writes that folder. stderr includes the
      warning and does not include the "not .kiro/specs" note.
    - `--dir features/basic` writes the folder, stderr includes the "not
      .kiro/specs" note, and `--steering` with that `--dir` is the steering
      path error and leaves no folder.
    - `--steering` on `basic` writes the `basic` `product.md` example and the
      notes for a missing stack, a missing structure file, a missing inputs
      file, and safety. It writes no `tech.md`, no choices file, no
      `structure.md`, and no `.kiro/hooks`.
    - `--steering` on `rich-manifest` writes the three worked examples. The
      helpers return those same bytes.
    - `--steering` when `.kiro/steering/product.md` already exists writes
      nothing.
    - A feature named `product` that has a qualifying inputs file hits the
      foundation-name error and writes nothing.
    - `inputs-absent` with `--steering` does not write a choices file. The
      note says the inputs file is absent. `customize` is not copied.
    - Default `to-spekkr` of `003-example` writes `./example`.
    - Omitting `--date` writes `1970-01-01` and the default-date note.
    - `--platforms cli, backend` writes `["cli", "backend"]`.
    - `.` and `..` use the directory name, as in R6.
    - An unreadable directory aborts with `error: cannot read ` and writes
      nothing. Skipped when the checker is root.
    - A `design.md` that starts with `SAFETY_BEGIN` but not `SAFETY_BLOCK` makes
      `to-spekkr` exit non-zero, print `error: design.md starts with <!-- spekkr:safety:begin --> but is not the safety block; to-spekkr will not convert it`, and write nothing. That input is outside the R6 fixed point.
    - `product_markdown` on a manifest with no `summary` omits the Summary
      line.
    - The repository README contains `SAFETY_BLOCK` when the checker is the
      one in this repository, not when it is pointed at another codec.
    
    Every hand-written fixture's golden `spekkr.json` is sent to Spekkr's
    `check_spec` and must pass.
    
    The success line is `Kiro codec checks passed (tests/fixtures).`
    
    ## Sources
    
    Pages read on 20 November 2026. "Updated" is the date printed on the page
    when it had one.
    
    | Fact used above | Page |
    | --- | --- |
    | A spec is `requirements.md` or `bugfix.md`, plus `design.md` and `tasks.md`. Mobile shows the three markdown files. Task execution updates tasks as in progress or completed and runs independent tasks in waves. | [Specs](https://kiro.dev/docs/specs/), updated 12 November 2026 |
    | Specs are project scope `.kiro/specs/`. Steering is `.kiro/steering/`. Hooks are `.kiro/hooks/`. | [Configuration](https://kiro.dev/docs/configuration/) |
    | Feature specs are requirements-first or design-first. Requirements use EARS: `WHEN` / `THE SYSTEM SHALL`. `design.md` is the technical design. | [Feature specs](https://kiro.dev/docs/specs/feature-specs/), updated 4 August 2026 |
    | Generated requirements use `##` / `###` headings and EARS lines. Tasks are discrete, with outcomes, dependencies, and optional or required status. The markdown of `tasks.md` is not shown. | [Requirements-first](https://kiro.dev/docs/specs/feature-specs/requirements-first/) |
    | Design-first generates `design.md`, then requirements, then the same kind of tasks. | [Design-first](https://kiro.dev/docs/specs/feature-specs/tech-design-first/) |
    | Quick Spec writes the same three files under `.kiro/specs/` with no approval between phases. Asking Kiro to refine requirements, then Sync Files, regenerates tasks. | [Quick spec](https://kiro.dev/docs/specs/quick-spec/) |
    | Iteration asks Kiro to revise `design.md` or regenerate requirements. Sync Files creates tasks or marks them complete. Run all Tasks runs incomplete required tasks and builds a dependency graph. `#spec` and `#spec:<name>` load the three files. The tree `.kiro/specs/user-authentication/` is the documented layout. Asking Kiro to generate a spec from an existing file writes new requirement and design docs. | [Best practices](https://kiro.dev/docs/specs/best-practices/), updated 25 September 2026 |
    | Workspace steering is `.kiro/steering/`. Foundation files are `product.md`, `tech.md`, and `structure.md`, included by default. Generate Steering Docs creates those three in the IDE. Front matter sets `inclusion` to `always`, `fileMatch`, `manual`, or `auto`. Manual files are referenced as `#<file-name>`. CLI V3 implements all four modes. V1 and V2 load `always` and exclude `manual` from automatic loading. Custom agents need `resources`. `#[[file:<path>]]` includes a workspace file. Secrets do not belong in steering. | [Steering](https://kiro.dev/docs/steering/) |
    | A hook file is `.kiro/hooks/<name>.json`, `"version": "v1"`, with a `hooks` array, a PascalCase trigger, and a command or agent action. | [Hooks](https://kiro.dev/docs/hooks/), updated 12 November 2026 |
    | `PreTaskExecution` runs before a spec task. `PostTaskExecution` runs after. | [Hook triggers](https://kiro.dev/docs/hooks/types/) |
    
    ## Unverified
    
    The codec's behavior on each gap is already fixed above. These are the
    points the pages do not settle.
    
    1. `tasks.md` has no published markdown schema. The docs name outcomes,
       dependencies, required and optional tasks, and status updates. They do
       not show checkboxes, ids, or a status token. The codec copies the file.
       After Run all Tasks, Sync Files, or a task run, a byte-for-byte round
       trip of `tasks.md` will not hold, because those actions update the file.
    2. The dependency-graph rules used for parallel tasks are not published.
    3. Nothing in the docs says Kiro deletes unknown files in a spec folder.
       Nothing says it preserves them. Sidecar survival is not a guarantee.
    4. Nothing in the docs says Generate Steering Docs overwrites an existing
       `product.md` or `tech.md`. Nothing says it keeps them. The README tells
       the person not to run that action over these files.
    5. Nothing in the docs says a `requirements.md` that is not EARS is
       rejected, and nothing says task execution requires EARS. Direct edits
       are documented. The codec does not convert to EARS.
    6. No page checked describes a `spec.json` or other registry. That absence
       is not proof the product has none. The codec writes no registry file.
    7. Whether a directory dropped into `.kiro/specs/` by another tool appears
       in the specs list without a Kiro session creating it is not a documented
       step. The pages identify a feature by that path and by `#spec:<name>`.
    8. Whether `#<file-name>` loads a `manual` steering file on CLI V1 or V2
       is not stated. V3 does. The file is still written.
    9. The docs do not say that opening a converted spec, with no further
       request, rewrites it. They do say that update requests, Sync Files,
       Quick Spec, and task execution change the three files.
    

    Open design.md as plain text

  • tasks.md Build order. Each step has a check. This version ships no reference implementation.

    Tasks

    Work in this order. Finish each check before the next task. This folder is the spec. It has no reference implementation. Build the codec in the project root you were asked to build it in. In the kiro-codec repository, that root is the parent of the spec/ directory. Run the commands from that root.

    1. Codec. Write one Python 3.11+ file, kiro_codec.py, with no dependencies beyond the standard library. The subcommands are to-kiro and to-spekkr. The flags are --dir, --steering, --author, --date and --platforms. Define SAFETY_BLOCK and SAFETY_BEGIN as the bytes in design.md, and the steering helpers that design.md names. Follow spec.md (R1-R12) and design.md. There is no design stub.

      Accept when: python3 kiro_codec.py --help exits 0 and lists both subcommands.

    2. Checker and fixtures. Add tests/check.py and synthetic fixtures under tests/fixtures/, the cases design.md lists. A pebble jar and a lantern are enough. Do not copy a catalog spec. tests/fixtures/** is marked -text in .gitattributes so Git does not rewrite CRLF or a missing trailing newline. .gitignore ignores __pycache__/ and *.py[cod]. A Makefile target check runs python3 tests/check.py.

      Accept when: python3 tests/check.py exits 0 and prints Kiro codec checks passed (tests/fixtures). For a codec of your own, python3 tests/check.py path/to/your_codec.py does the same. python3 tests/check.py also passes the golden spekkr.json files from the hand-written fixtures through Spekkr's check_spec.

    3. Skill, README, CI. Add skills/kiro-codec/SKILL.md as an agent skill named kiro-codec (R13). Rewrite the repository README.md so it quotes SAFETY_BLOCK, cites the Kiro pages in design.md, and tells the person not to let Kiro regenerate the converted files (R12). Add .github/workflows/ci.yml that runs python3 tests/check.py on Python 3.11 and 3.12 for pushes to main and for pull requests, with contents: read (R14).

      Accept when: the skill has name and description front matter. From an empty directory, the skill's to-kiro command on tests/fixtures/spekkr/basic/source writes .kiro/specs/basic/ and does not write .kiro/steering/. The README contains the safety block bytes. The workflow file names both Python versions.

    # Tasks
    
    Work in this order. Finish each check before the next task. This folder is
    the spec. It has no reference implementation. Build the codec in the project
    root you were asked to build it in. In the kiro-codec repository, that root
    is the parent of the `spec/` directory. Run the commands from that root.
    
    1. **Codec.** Write one Python 3.11+ file, `kiro_codec.py`, with no
       dependencies beyond the standard library. The subcommands are `to-kiro`
       and `to-spekkr`. The flags are `--dir`, `--steering`, `--author`,
       `--date` and `--platforms`. Define `SAFETY_BLOCK` and `SAFETY_BEGIN` as
       the bytes in `design.md`, and the steering helpers that `design.md`
       names. Follow `spec.md` (R1-R12) and `design.md`. There is no design
       stub.
    
       **Accept when:** `python3 kiro_codec.py --help` exits 0 and lists both
       subcommands.
    
    2. **Checker and fixtures.** Add `tests/check.py` and synthetic fixtures
       under `tests/fixtures/`, the cases `design.md` lists. A pebble jar and a
       lantern are enough. Do not copy a catalog spec. `tests/fixtures/**` is
       marked `-text` in `.gitattributes` so Git does not rewrite CRLF or a
       missing trailing newline. `.gitignore` ignores `__pycache__/` and
       `*.py[cod]`. A `Makefile` target `check` runs `python3 tests/check.py`.
    
       **Accept when:** `python3 tests/check.py` exits 0 and prints
       `Kiro codec checks passed (tests/fixtures).` For a codec of your own,
       `python3 tests/check.py path/to/your_codec.py` does the same.
       `python3 tests/check.py` also passes the golden `spekkr.json` files
       from the hand-written fixtures through Spekkr's `check_spec`.
    
    3. **Skill, README, CI.** Add `skills/kiro-codec/SKILL.md` as an agent
       skill named `kiro-codec` (R13). Rewrite the repository `README.md` so it
       quotes `SAFETY_BLOCK`, cites the Kiro pages in `design.md`, and tells
       the person not to let Kiro regenerate the converted files (R12). Add
       `.github/workflows/ci.yml` that runs `python3 tests/check.py` on Python
       3.11 and 3.12 for pushes to `main` and for pull requests, with
       `contents: read` (R14).
    
       **Accept when:** the skill has `name` and `description` front matter.
       From an empty directory, the skill's `to-kiro` command on
       `tests/fixtures/spekkr/basic/source` writes `.kiro/specs/basic/` and
       does not write `.kiro/steering/`. The README contains the safety block
       bytes. The workflow file names both Python versions.
    

    Open tasks.md as plain text

License: MIT

Is it for me?

Platforms
cli
Tools
Python 3.11+, Python standard library, Kiro

What does it need?

Agent permissions
shell
Commands it runs
python3 kiro_codec.py --help python3 tests/check.py python3 tests/check.py <your_codec.py> python3 kiro_codec.py to-kiro <spekkr-folder> [--dir <feature-folder>] [--steering] python3 kiro_codec.py to-spekkr <feature-folder> [--dir <spekkr-folder>] [--author <username>] [--date <YYYY-MM-DD>] [--platforms <list>]

What changed?

  • 0.1.120 Nov 2026to-spekkr now refuses a design.md that starts with the safety marker but is not the full safety block, so the round trip stays exact. A tested implementation is at github.com/dwrtz/kiro-codec.
  • 0.1.020 Nov 2026First version. Spec only. Kiro docs checked 20 November 2026. No codec in this folder yet.

For agents: start.md says how to build this spec, spec.json holds everything on this page, and bundle.tar.gz holds its files.