Skip to content
Back to search

krypton

Goal-based planning and proof gate for AI coding agents

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/jturntdev--krypton/badge.svg)](/listings/jturntdev--krypton)

HTML

<a href="/listings/jturntdev--krypton"><img src="/api/listings/jturntdev--krypton/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.

Recommended: skills.sh

Use the open skills CLI when you want Krypton installed into supported agent skill directories:

Codex only:

npx --yes skills add jturntdev/krypton --skill '*' --agent codex --copy -y

Claude Code only:

npx --yes skills add jturntdev/krypton --skill '*' --agent claude-code --copy -y

That installs every Krypton skill for the named agent only. If you want Codex, Claude Code, OpenCode, or another agent together, run the command without `--agent ...` and use the interactive selector:

npx --yes skills add jturntdev/krypton

See the package page:

https://skills.sh/jturntdev/krypton

Codex Repo Marketplace

This repo ships a Codex marketplace file at `.agents/plugins/marketplace.json`. For Codex clients that support repo marketplaces:

codex plugin marketplace add \
  "https://github.com/jturntdev/krypton.git" \
  --ref "main" \
  --sparse ".agents/plugins" \
  --sparse ".codex-plugin" \
  --sparse "assets" \
  --sparse "skills"

codex plugin install krypton --source krypton

Claude Code Plugin

Use the plugin route when you want Claude Code to manage Krypton as a plugin:

/plugin marketplace add jturntdev/krypton
/plugin install krypton@krypton-dev
/reload-plugins

Claude Code namespaces plugin skills, so invoke them as:

/krypton:krypton-planning
/krypton:krypton-execution

This repo includes the Claude plugin files Claude Code expects:

.claude-plugin/plugin.json
.claude-plugin/marketplace.json
skills/krypton-planning/SKILL.md
skills/krypton-execution/SKILL.md

Claude Code Manual Skills

Use manual install when you want the skills available as personal Claude Code skills without the plugin marketplace:

git clone https://github.com/jturntdev/krypton.git
mkdir -p ~/.claude/skills
cp -R krypton/skills/krypton-planning ~/.claude/skills/
cp -R krypton/skills/krypton-execution ~/.claude/skills/

Manual personal skills invoke without a plugin namespace:

/krypton-planning
/krypton-execution

Codex

For Codex skills:

git clone https://github.com/jturntdev/krypton.git
mkdir -p ~/.codex/skills
cp -R krypton/skills/* ~/.codex/skills/

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.

.claude-plugin/marketplace.json · Manifest · 20 lines

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

  1. {
  2. "name": "krypton-dev",
  3. "description": "Development marketplace for Krypton operator skills",
  4. "owner": {
  5. "name": "jturntdev",
  6. "email": "197428481+jturntdev@users.noreply.github.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "krypton",
  11. "description": "Goal-based planning and proof gate for production-grade AI coding agent work.",
  12. "version": "0.3.2",
  13. "source": "./",
  14. "author": {
  15. "name": "jturntdev",
  16. "email": "197428481+jturntdev@users.noreply.github.com"
  17. }
  18. }
  19. ]
  20. }
README.md · README · 430 lines

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

  1. # Krypton
  2. Current version: `0.3.2`
  3. [![skills.sh](https://skills.sh/b/jturntdev/krypton)](https://skills.sh/jturntdev/krypton)
  4. Stop AI agents from shipping plausible wrong work.
  5. Krypton is the goal-based planning and proof gate for running Claude Code,
  6. Codex, and other AI coding agents against production-grade codebases.
  7. The failure mode Krypton is built for is not bad syntax. It is the right-looking
  8. feature that compiles while living on the wrong layer, inventing a second source
  9. of truth, skipping cutover, or claiming success without proof from the real path.
  10. Krypton forces the plan before the code:
  11. - truth owner
  12. - contract boundary
  13. - displaced path
  14. - cutover decision
  15. - acceptance evidence
  16. - review gates
  17. Built for `/goals`, equivalent goal-based agent workflows, Claude Code
  18. skills/plugins, Codex skills, and operators who need agent speed without letting
  19. the codebase rot.
  20. ## What's Included
  21. - **New beta: VPS Codex setup** (`krypton-vps-codex-app`): a guided workflow for
  22. using a Linux VPS as the remote machine for Codex App work, including VPS
  23. readiness questions, SSH aliases, GitHub repo access, local config choices,
  24. Codex CLI auth, port forwarding, and proof checks.
  25. - **Krypton planning** (`krypton-planning`): turns a request into a goal package
  26. with the truth owner, boundary, cutover decision, task plan, review gates, and
  27. acceptance evidence.
  28. - **Krypton execution** (`krypton-execution`): keeps an approved plan on track
  29. while the main agent implements, verifies, and records proof.
  30. - **GitHub Action beta**: checks pull requests for the goal-package evidence
  31. Krypton expects before non-trivial code changes ship.
  32. Jump to: [Install](#install) | [Skills And Beta Workflows](#skills-and-beta-workflows) |
  33. [VPS Setup Workflow Beta](#vps-setup-workflow-beta) |
  34. [GitHub Action Beta](#github-action-beta)
  35. ## Why Operators Need It
  36. Modern agents can create weeks of architectural debt in one enthusiastic
  37. session. Krypton turns "build this" into an operational contract before the
  38. agent touches code:
  39. - what product or engineering outcome the work serves
  40. - what current behavior is replaced, redirected, deleted, or demoted
  41. - who owns the truth
  42. - what contract crosses the boundary
  43. - what evidence proves the result from the target person's perspective
  44. - what kill criteria prevent duplicate paths from living forever
  45. That contract is what lets an operator keep using agents on production systems
  46. without letting the codebase become a pile of current-looking alternatives.
  47. ## Designed For `/goals`
  48. Krypton is best used with `/goals` or any equivalent goal-based agent workflow.
  49. It is not meant to be a one-shot "please implement this" prompt.
  50. The planning session creates the durable handoff:
  51. ```text
  52. docs/goals/<goal-slug>/PLAN.md
  53. docs/goals/<goal-slug>/GOAL.md
  54. docs/goals/<goal-slug>/EVIDENCE.md
  55. ```
  56. `PLAN.md` is the source plan. `GOAL.md` is the compact `/goal` prompt.
  57. `EVIDENCE.md` is where execution records the actual proof from the real command,
  58. artifact, payload, browser state, trace, or operator-visible result. Start the
  59. execution session with the GOAL prompt, then load `krypton-execution` so the
  60. main agent preserves the plan's ownership, cutover, review, and evidence gates.
  61. If your harness does not have `/goals`, paste the contents of `GOAL.md` into a
  62. fresh Codex or Claude session. The shape still works.
  63. ## Install
  64. ### Recommended: skills.sh
  65. Use the open skills CLI when you want Krypton installed into supported agent
  66. skill directories:
  67. Codex only:
  68. ```bash
  69. npx --yes skills add jturntdev/krypton --skill '*' --agent codex --copy -y
  70. ```
  71. Claude Code only:
  72. ```bash
  73. npx --yes skills add jturntdev/krypton --skill '*' --agent claude-code --copy -y
  74. ```
  75. That installs every Krypton skill for the named agent only. If you want Codex,
  76. Claude Code, OpenCode, or another agent together, run the command without
  77. `--agent ...` and use the interactive selector:
  78. ```bash
  79. npx --yes skills add jturntdev/krypton
  80. ```
  81. See the package page:
  82. ```text
  83. https://skills.sh/jturntdev/krypton
  84. ```
  85. ### Codex Repo Marketplace
  86. This repo ships a Codex marketplace file at `.agents/plugins/marketplace.json`.
  87. For Codex clients that support repo marketplaces:
  88. ```bash
  89. codex plugin marketplace add \
  90. "https://github.com/jturntdev/krypton.git" \
  91. --ref "main" \
  92. --sparse ".agents/plugins" \
  93. --sparse ".codex-plugin" \
  94. --sparse "assets" \
  95. --sparse "skills"
  96. codex plugin install krypton --source krypton
  97. ```
  98. ### Claude Code Plugin
  99. Use the plugin route when you want Claude Code to manage Krypton as a plugin:
  100. ```text
  101. /plugin marketplace add jturntdev/krypton
  102. /plugin install krypton@krypton-dev
  103. /reload-plugins
  104. ```
  105. Claude Code namespaces plugin skills, so invoke them as:
  106. ```text
  107. /krypton:krypton-planning
  108. /krypton:krypton-execution
  109. ```
  110. This repo includes the Claude plugin files Claude Code expects:
  111. ```text
  112. .claude-plugin/plugin.json
  113. .claude-plugin/marketplace.json
  114. skills/krypton-planning/SKILL.md
  115. skills/krypton-execution/SKILL.md
  116. ```
  117. ### Claude Code Manual Skills
  118. Use manual install when you want the skills available as personal Claude Code
  119. skills without the plugin marketplace:
  120. ```bash
  121. git clone https://github.com/jturntdev/krypton.git
  122. mkdir -p ~/.claude/skills
  123. cp -R krypton/skills/krypton-planning ~/.claude/skills/
  124. cp -R krypton/skills/krypton-execution ~/.claude/skills/
  125. ```
  126. Manual personal skills invoke without a plugin namespace:
  127. ```text
  128. /krypton-planning
  129. /krypton-execution
  130. ```
  131. ### Codex
  132. For Codex skills:
  133. ```bash
  134. git clone https://github.com/jturntdev/krypton.git
  135. mkdir -p ~/.codex/skills
  136. cp -R krypton/skills/* ~/.codex/skills/
  137. ```
  138. ## Skills And Beta Workflows
  139. Stable skills:
  140. - `krypton-planning`: turn a request into an outcome contract, architecture
  141. slice, task plan, evidence gate, and `/goal` handoff prompt.
  142. - `krypton-execution`: execute an approved plan without drifting from ownership,
  143. cutover, or proof requirements.
  144. Beta workflow:
  145. - `krypton-vps-codex-app` beta: guide a user through setting up a Linux VPS as
  146. a Codex App SSH host, including VPS provisioning questions, SSH aliases,
  147. GitHub repo access, local config choices, Codex CLI auth, port forwarding,
  148. and proof checks.
  149. The beta workflow points at where Krypton is going: not just plans and review
  150. gates, but repeatable operator workflows that help a user move from local
  151. agent work to durable remote development without hiding the security,
  152. credential, and proof decisions.
  153. ## How It Works
  154. 1. Load `krypton-planning` with a feature request, bug, refactor, migration, or
  155. architecture goal.
  156. 2. The agent produces a goal package:
  157. ```text
  158. docs/goals/<goal-slug>/PLAN.md
  159. docs/goals/<goal-slug>/GOAL.md
  160. docs/goals/<goal-slug>/EVIDENCE.md
  161. ```
  162. 3. `PLAN.md` is the full implementation plan. `GOAL.md` is the short `/goal`
  163. prompt or handoff prompt for the next session.
  164. 4. Paste or run the `GOAL.md` prompt in Codex or Claude.
  165. 5. Pair it with `krypton-execution` when you want the main agent to use the same
  166. ownership, cutover, review, and evidence discipline.
  167. 6. Finish only when the acceptance evidence is captured from the real route,
  168. artifact, payload, trace, browser state, or operator-visible output and
  169. recorded in `EVIDENCE.md`.
  170. The workflow is intentionally two-stage:
  171. ```text
  172. rough request
  173. -> krypton-planning
  174. -> PLAN.md + GOAL.md + EVIDENCE.md
  175. -> /goal handoff
  176. -> krypton-execution
  177. -> main-agent implementation + review gates + acceptance evidence
  178. ```
  179. ## GitHub Action Beta
  180. Krypton also ships a reusable PR gate, but treat it as beta until you have
  181. tested it in a throwaway repo that matches your workflow. The primary install
  182. path is still the `skills.sh` command above.
  183. The gate fails non-trivial code changes that do not include a changed Krypton
  184. goal package with:
  185. - `PLAN.md`
  186. - `GOAL.md`
  187. - `EVIDENCE.md`
  188. - truth owner text
  189. - deletion or cutover text
  190. - evidence gate and acceptance evidence text
  191. Beta workflow example:
  192. ```yaml
  193. name: Krypton Goal Gate
  194. on:
  195. pull_request:
  196. permissions:
  197. contents: read
  198. jobs:
  199. krypton:
  200. runs-on: ubuntu-latest
  201. steps:
  202. - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
  203. with:
  204. fetch-depth: 0
  205. - uses: jturntdev/krypton@v0.3.2
  206. ```
  207. Run the same gate locally:
  208. ```bash
  209. python3 scripts/check-krypton-goal.py --base-ref origin/main
  210. ```
  211. Goal package templates live in:
  212. ```text
  213. templates/goal-package/
  214. ```
  215. Before relying on the Action in a real repo, test three cases in a throwaway
  216. repository:
  217. - code change with no goal package should fail
  218. - docs-only change should pass
  219. - code change with `PLAN.md`, `GOAL.md`, and `EVIDENCE.md` should pass
  220. ## VPS Setup Workflow Beta
  221. Krypton also includes a clearly marked beta Codex App remote-development setup
  222. workflow:
  223. `krypton-vps-codex-app`.
  224. Use it when you want a VPS to be the machine that does the work while Codex App
  225. on your Mac or Windows machine connects over SSH. The VPS owns the repo,
  226. toolchain, builds, tests, tmux/cmux sessions, dev servers, and Codex CLI auth.
  227. This is beta because VPS providers, Codex App remote connections, GitHub access
  228. choices, and project setup commands vary by operator. The goal is for Krypton to
  229. become the clean setup lane: Codex asks the right questions, explains the safest
  230. default, waits for user-owned steps, runs only approved setup or audit commands,
  231. and finishes with proof from the real remote project.
  232. The skill is intentionally consent-based. Codex should ask before each
  233. operator-owned decision:
  234. - whether the user already has a VPS or still needs to provision one
  235. - whether Codex may edit `~/.ssh/config` or should only show the snippet
  236. - whether GitHub should be the source of truth for the VPS checkout
  237. - which GitHub access path to use: GitHub CLI login, account SSH key, read-only
  238. deploy key, public HTTPS clone, or no GitHub setup yet
  239. - whether local config should be recreated from examples, copied selectively, or
  240. skipped
  241. - whether Codex should only audit or may bootstrap tools over SSH
  242. GitHub is the recommended code path. Local-only config and secrets are a
  243. separate step. The skill tells Codex not to bulk-copy `.ssh`, `.codex`, browser
  244. profiles, home directories, caches, `node_modules`, build outputs, private keys,
  245. or random dotfiles.
  246. Read the beta setup guide:
  247. ```text
  248. docs/vps-codex-app-beta.md
  249. ```
  250. The skill includes a read-only audit script:
  251. ```bash
  252. skills/krypton-vps-codex-app/scripts/audit-vps-codex-app.sh \
  253. --host krypton-vps \
  254. --repo-url git@github.com:ORG/REPO.git \
  255. --repo-path ~/src/REPO
  256. ```
  257. Passing the audit proves the SSH host prerequisites. It does not replace the
  258. final Codex App remote-thread proof.
  259. ## Agent Roles
  260. Krypton works best when the harness supports named agents:
  261. - `explorer`: read-only source-of-truth and architecture mapping
  262. - `plan-reviewer`: PRE and POST alignment checks
  263. - `reviewer`: runtime correctness, security, and evidence check
  264. - `maintainer`: codebase-shape, duplication, and cutover-debt check
  265. - `verifier`: focused proof from the real path
  266. See `docs/required-roles.md` for the role expectations. If your harness does
  267. not support named agents, the main agent can still follow the same gates, but
  268. independent exploration and review will be weaker.
  269. ## Prompt Files
  270. Krypton keeps prompt templates individual instead of centralizing them into one
  271. large prompt file. Each skill owns the prompts it actually uses:
  272. - `skills/krypton-planning/plan-reviewer-prompt.md`
  273. - `skills/krypton-execution/post-plan-reviewer-prompt.md`
  274. - `skills/krypton-execution/reviewer-prompt.md`
  275. - `skills/krypton-execution/maintainer-prompt.md`
  276. ## Example
  277. Bad agent path:
  278. ```text
  279. "Add sentiment to the dashboard."
  280. ```
  281. The agent adds frontend-only sentiment logic and calls it done.
  282. Krypton path:
  283. ```text
  284. Truth owner: market intelligence producer
  285. Contract boundary: typed sentiment payload
  286. Cutover: dashboard reads producer output only
  287. Evidence: API response plus browser state showing the real payload
  288. ```
  289. See `examples/` and `tests/pressure-scenarios/` for more.
  290. ## Status
  291. This is the first public cut. It is intentionally small: three skills,
  292. individual prompt templates, agent role expectations, goal package templates, a
  293. local gate script, beta GitHub Action and VPS setup workflows, examples,
  294. pressure scenarios, and validation scripts.
  295. ## Versioning
  296. Krypton uses SemVer-style versions while the public package stabilizes.
  297. - Version source of truth: `VERSION`
  298. - Plugin metadata must match: `.codex-plugin/plugin.json`,
  299. `.claude-plugin/plugin.json`, and `.claude-plugin/marketplace.json`
  300. - Release tags should use `vX.Y.Z`
  301. Version policy:
  302. - Patch: README, examples, prompt wording, metadata, validation improvements
  303. - Minor: new skills, new gates, changed `/goal` workflow shape
  304. - Major: breaking skill names, removed gates, incompatible plan or goal format
  305. ## Development
  306. Run:
  307. ```bash
  308. ./scripts/validate.sh
  309. ```
  310. The validator checks required files, skill metadata, JSON plugin metadata, and
  311. public-safety issues such as placeholders or private project references.
  312. ## License
  313. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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