Skip to content
Back to search

gap-trap

Turns vibe coding into high quality code. Sets up rules and gates in your repo so AI-written code stays correct without you reviewing every line.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pliablepixels--gap-trap/badge.svg)](/listings/pliablepixels--gap-trap)

HTML

<a href="/listings/pliablepixels--gap-trap"><img src="/api/listings/pliablepixels--gap-trap/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

With the [skills](https://github.com/vercel-labs/skills) CLI:

npx skills add pliablepixels/gap-trap

Or by hand. Claude Code reads `~/.claude/skills`, Codex reads `~/.agents/skills`:

git clone https://github.com/pliablepixels/gap-trap.git
mkdir -p ~/.claude/skills            # Codex: mkdir -p ~/.agents/skills
cp -r gap-trap/gap-trap ~/.claude/skills/

The skill runs on the top coding model of the harness (Opus or better in Claude Code, the frontier coding model at high reasoning in Codex) and stops on anything smaller. Choosing the wrong contracts costs every later session.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 160 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center"><img src="assets/gap-trap.png" alt="gap-trap logo: a net catching code puzzle pieces" width="200"></p>
  2. # gap-trap
  3. Turns vibe coding into high quality code. Complements SDD if you are using it (think of it as the inner loop within)
  4. ## The problem
  5. An agent writes most of your code. It is fast, so you stop reading
  6. every diff. Quality drifts, and you find out when something breaks.
  7. The drift looks the same in every codebase. The agent writes a helper
  8. that already exists. It crosses a layer boundary because the shortcut
  9. compiled. It writes a test that asserts the code ran, not that it did
  10. the right thing. It follows a rule in your instructions file for a
  11. week and then forgets it.
  12. Nothing stops any of this. The rules are text, and the only thing that
  13. reads them is the agent that breaks them.
  14. ## What gap-trap does
  15. Run it once in a repository. It reads the code, writes the rules that
  16. fit that codebase, and adds a gate for each rule. A gate is a check that
  17. fails the commit or the CI run when the rule is broken. The agent cannot
  18. skip a gate.
  19. It sets up four things:
  20. | | What it is |
  21. |---|---|
  22. | **Contracts** | One entry per part of the code that has one right way to do things (HTTP, logging, settings, auth). Each says what to use, what never to use, and which check finds bypasses. |
  23. | **Proven red** | A CI job that runs every new test against the old code and fails when the test passes there. A test that cannot fail proves nothing. |
  24. | **Ratchets** | Counts of known problems, such as the lint backlog or files over 400 lines. They may go down, never up. |
  25. | **Playbooks** | The facts the project learned the hard way, written down so the next session does not learn them again. |
  26. It also installs [slop-mop](https://github.com/pliablepixels/slop-mop),
  27. a sibling skill, so the agent's docs, commit messages, and PR bodies read
  28. like a person wrote them. A harness loads its skills when the session
  29. starts, so slop-mop applies from the session after the one that installs
  30. it.
  31. Works with any language. Node and Python repos get gates inside their
  32. test suite; everything else (Go, Rust, Java, Ruby, .NET, PHP, Swift, C++)
  33. gets shell versions that need only git, grep, awk, and your test command.
  34. **IMPORTANT**: Validate the rules/contracts that are generated. This is where it is important to review thoroughly so you start with a strong foundation.
  35. ## Install
  36. With the [skills](https://github.com/vercel-labs/skills) CLI:
  37. ```
  38. npx skills add pliablepixels/gap-trap
  39. ```
  40. Or by hand. Claude Code reads `~/.claude/skills`, Codex reads
  41. `~/.agents/skills`:
  42. ```
  43. git clone https://github.com/pliablepixels/gap-trap.git
  44. mkdir -p ~/.claude/skills # Codex: mkdir -p ~/.agents/skills
  45. cp -r gap-trap/gap-trap ~/.claude/skills/
  46. ```
  47. The skill runs on the top coding model of the harness (Opus or better in
  48. Claude Code, the frontier coding model at high reasoning in Codex) and
  49. stops on anything smaller. Choosing the wrong contracts costs every later
  50. session.
  51. ## Update
  52. Every push to `main` is a new version. With the skills CLI:
  53. ```
  54. npx skills update gap-trap
  55. ```
  56. For a hand install, pull the clone and replace the copy, so files
  57. removed upstream do not linger:
  58. ```
  59. git -C gap-trap pull
  60. rm -rf ~/.claude/skills/gap-trap # Codex: ~/.agents/skills/gap-trap
  61. cp -r gap-trap/gap-trap ~/.claude/skills/
  62. ```
  63. A repository you already set up keeps the files setup wrote. Updating
  64. the skill changes what the next `setup` or `refine` run does.
  65. ## Run
  66. In the repository you want to set up:
  67. ```
  68. /gap-trap setup
  69. ```
  70. Codex invokes the same skill as `$gap-trap setup`.
  71. The skill reads the repo, shows you a short plan (contracts, gates,
  72. commands), asks about anything it could not settle, then writes the
  73. files, proves each gate red, and commits. It does not push. At the end
  74. it asks whether to check the repo against the new framework. On yes, it
  75. lists the existing violations by contract and rule and changes nothing.
  76. Later, after the first incidents or about once a month:
  77. ```
  78. /gap-trap refine
  79. ```
  80. This looks for rules without gates, contracts that name code that no
  81. longer exists, and lessons in the commit history nobody wrote down. It
  82. proposes one PR.
  83. ## Where it comes from
  84. The framework is the one [zmNinjaNg](https://github.com/ZoneMinder/zmNinjaNg)
  85. runs on. Agents write most of its code and no one reads the diffs line
  86. by line. Chapter 14 of its developer guide,
  87. [Agent development model](https://zmninjang.readthedocs.io/en/latest/developer-guide/14-agent-development-model.html),
  88. is the inspiration for gap-trap. It explains rules, contracts, and
  89. gates, and follows one feature from spec to merge.
  90. ## What it costs
  91. The origin repo's full gate set (4,400 unit tests, a build, three lints)
  92. runs in about a minute locally. The instruction gate adds about a second.
  93. Proven red runs only in CI.
  94. ## Release
  95. For the maintainer. `scripts/release.sh` bumps the version tag, writes
  96. the notes from the commits since the last tag, and publishes the release
  97. with `gh`:
  98. ```
  99. scripts/release.sh # patch bump
  100. scripts/release.sh minor # feature bump
  101. scripts/release.sh v1.0.0 # that exact version
  102. scripts/release.sh --dry-run # print the version and notes, change nothing
  103. ```
  104. It stops if you are not on `main`, the tree has uncommitted changes, or
  105. `main` and `origin/main` differ. The skills CLI installs from `main`, so
  106. a tag marks a version rather than gating one.
  107. ## Layout
  108. ```
  109. gap-trap/
  110. SKILL.md the skill: model gate, setup, refine
  111. reference/ the framework, discovery, gates, refine
  112. templates/ AGENTS.md, AGENTS.project.md, playbooks, gate scripts
  113. ```
  114. ## License
  115. MIT.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.