{"_id":"@dannylee1020/kkt","_rev":"7-3e0ea49ac27784bdadd33cd761b31940","name":"@dannylee1020/kkt","dist-tags":{"latest":"0.8.1"},"versions":{"0.5.0":{"name":"@dannylee1020/kkt","version":"0.5.0","keywords":["pi-package","agent-skills","coding-agent","claude-code","codex","opencode","pi","kkt"],"license":"Apache-2.0","_id":"@dannylee1020/kkt@0.5.0","maintainers":[{"name":"dannylee1020","email":"dannylee1020@gmail.com"}],"homepage":"https://github.com/dannylee1020/kkt#readme","bugs":{"url":"https://github.com/dannylee1020/kkt/issues"},"pi":{"image":"https://raw.githubusercontent.com/dannylee1020/kkt/main/assets/kkt-readme-modern.png","skills":["./skills"]},"bin":{"kkt-install":"bin/kkt-install.mjs"},"dist":{"shasum":"bdbca71ffbefea09d81eb5d2a50b469b65005260","tarball":"https://registry.npmjs.org/@dannylee1020/kkt/-/kkt-0.5.0.tgz","fileCount":50,"integrity":"sha512-BXKRFIPh4eNvmfx2ALELdUNWRP2QPD0aKRI2LC6kDuZFYQ20CB8UKQ3Ak9nqZNVb/u453VEHKUG04UxyggrGew==","signatures":[{"sig":"MEYCIQCNc3/mZxDf1pdA9C//sZ17+l9k211MW2w2cpiOmi9LOgIhANLpqMZH5PsQe5V4n55ZdoepBVJt7gyk6r4bwtCppEHD","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":387244},"type":"module","gitHead":"97c3f1caefada06ad9df58c832cfd36fae6871ca","_npmUser":{"name":"dannylee1020","email":"dannylee1020@gmail.com"},"repository":{"url":"git+https://github.com/dannylee1020/kkt.git","type":"git"},"_npmVersion":"11.3.0","description":"KKT constrained-optimization workflow skills and CLI installer for coding agents.","directories":{},"_nodeVersion":"24.0.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/kkt_0.5.0_1783470669873_0.8465613268843486","host":"s3://npm-registry-packages-npm-production"}},"0.5.1":{"name":"@dannylee1020/kkt","version":"0.5.1","keywords":["pi-package","agent-skills","coding-agent","claude-code","codex","opencode","pi","kkt"],"license":"Apache-2.0","_id":"@dannylee1020/kkt@0.5.1","maintainers":[{"name":"dannylee1020","email":"dannylee1020@gmail.com"}],"homepage":"https://github.com/dannylee1020/kkt#readme","bugs":{"url":"https://github.com/dannylee1020/kkt/issues"},"pi":{"image":"https://raw.githubusercontent.com/dannylee1020/kkt/main/assets/kkt-readme-modern.png","skills":["./skills"]},"bin":{"kkt-install":"bin/kkt-install.mjs"},"dist":{"shasum":"646e040beab64aae9bddb0d48f8977a01137e558","tarball":"https://registry.npmjs.org/@dannylee1020/kkt/-/kkt-0.5.1.tgz","fileCount":50,"integrity":"sha512-UnTPrQPLB3utlXHsn30nlO9tyHXBQZcmVS07GbPDib6tiOttQMW/UqwXWm+OdyZrkStT+RZSPYBVLiVbycunYw==","signatures":[{"sig":"MEUCIQCJ8SIup++BFpnU4HVj7plFzc5EeSBNLVg9MX96uBbeZQIgXL9fABRvsr5vHdl//WhmFRyVTOjRqGA2fkfJyx7F6Bc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":386842},"type":"module","_npmUser":{"name":"dannylee1020","email":"dannylee1020@gmail.com"},"repository":{"url":"git+https://github.com/dannylee1020/kkt.git","type":"git"},"_npmVersion":"11.3.0","description":"KKT constrained-optimization workflow skills and CLI installer for coding agents.","directories":{},"_nodeVersion":"24.0.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/kkt_0.5.1_1783527123399_0.7428250795573019","host":"s3://npm-registry-packages-npm-production"}},"0.5.2":{"name":"@dannylee1020/kkt","version":"0.5.2","keywords":["pi-package","agent-skills","coding-agent","claude-code","codex","opencode","pi","kkt"],"license":"Apache-2.0","_id":"@dannylee1020/kkt@0.5.2","maintainers":[{"name":"dannylee1020","email":"dannylee1020@gmail.com"}],"homepage":"https://github.com/dannylee1020/kkt#readme","bugs":{"url":"https://github.com/dannylee1020/kkt/issues"},"pi":{"image":"https://raw.githubusercontent.com/dannylee1020/kkt/main/assets/kkt-readme-modern.png","skills":["./skills"]},"bin":{"kkt-install":"bin/kkt-install.mjs"},"dist":{"shasum":"208677c5bf088a16a079f305b3a03dbf6d40cfd3","tarball":"https://registry.npmjs.org/@dannylee1020/kkt/-/kkt-0.5.2.tgz","fileCount":56,"integrity":"sha512-ml2z9fP388bVA2Kf04nNs8fo+2ySLRk2B8lBlTF7jSpWaTZgHTOuGFRak2VXbQO0aEq6Y5pWJBAm4KMhTPvUCA==","signatures":[{"sig":"MEUCIElSskPrLunhTQfoBpePmHRh8ebp4oZ8uxbGx0E3WbwvAiEAmngRnEEP/ZyupRTzwYRyWITRjNGcQLkgEiGhPm7LxF0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@dannylee1020%2fkkt@0.5.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":433278},"type":"module","gitHead":"fe4eb1aabc7660c19b8b8c383c09113a00e99421","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:8176bf36-773b-4b5f-9c03-217a4d56cad3"}},"repository":{"url":"git+https://github.com/dannylee1020/kkt.git","type":"git"},"_npmVersion":"12.0.1","description":"KKT constrained-optimization workflow skills and CLI installer for coding agents.","directories":{},"_nodeVersion":"24.18.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/kkt_0.5.2_1784656341931_0.5454040095476977","host":"s3://npm-registry-packages-npm-production"}},"0.6.0":{"name":"@dannylee1020/kkt","version":"0.6.0","keywords":["pi-package","agent-skills","coding-agent","claude-code","codex","opencode","pi","kkt"],"license":"Apache-2.0","_id":"@dannylee1020/kkt@0.6.0","maintainers":[{"name":"dannylee1020","email":"dannylee1020@gmail.com"}],"homepage":"https://github.com/dannylee1020/kkt#readme","bugs":{"url":"https://github.com/dannylee1020/kkt/issues"},"pi":{"image":"https://raw.githubusercontent.com/dannylee1020/kkt/main/assets/kkt-readme-modern.png","skills":["./skills"]},"bin":{"kkt-install":"bin/kkt-install.mjs"},"dist":{"shasum":"48b5286d32d598856e814c561b468c14e39a1c8a","tarball":"https://registry.npmjs.org/@dannylee1020/kkt/-/kkt-0.6.0.tgz","fileCount":62,"integrity":"sha512-O75wZirD1opp45VQgM1opB9PWhzFbRtPFgM+VU0CaidKNNGpX9An0xWISkNaiXHxTVnCtjL/EkKyle7QV2OfnA==","signatures":[{"sig":"MEYCIQC4vVYicZouX1k+TN2duWzeJiSsuGM7t0yOg/nwWvHQFwIhAPg8fTnCT8yhxaqobE4uBg91QFWC4GJzijSH0Slm+9wu","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@dannylee1020%2fkkt@0.6.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":459022},"type":"module","gitHead":"7f5dbbb89fca93703184970bcdc0a51ae95f7f38","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:8176bf36-773b-4b5f-9c03-217a4d56cad3"}},"repository":{"url":"git+https://github.com/dannylee1020/kkt.git","type":"git"},"_npmVersion":"12.0.1","description":"KKT constrained-optimization workflow skills and CLI installer for coding agents.","directories":{},"_nodeVersion":"24.18.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/kkt_0.6.0_1784665864673_0.22378522651797805","host":"s3://npm-registry-packages-npm-production"}},"0.7.0":{"name":"@dannylee1020/kkt","version":"0.7.0","keywords":["pi-package","agent-skills","coding-agent","claude-code","codex","opencode","pi","kkt"],"license":"Apache-2.0","_id":"@dannylee1020/kkt@0.7.0","maintainers":[{"name":"dannylee1020","email":"dannylee1020@gmail.com"}],"homepage":"https://github.com/dannylee1020/kkt#readme","bugs":{"url":"https://github.com/dannylee1020/kkt/issues"},"pi":{"image":"https://raw.githubusercontent.com/dannylee1020/kkt/main/assets/kkt-readme-modern.png","skills":["./skills"]},"bin":{"kkt-install":"bin/kkt-install.mjs"},"dist":{"shasum":"09049477abd1f9c515808f095e8a3c5240baff24","tarball":"https://registry.npmjs.org/@dannylee1020/kkt/-/kkt-0.7.0.tgz","fileCount":66,"integrity":"sha512-TDc//nmzFKxICgyRNgqSu6GIeqKdUQEkbACtfU4u2Emy9rJErlCLWUUrlQlVm81DYCtcy6fjEiIIFVLRDqNYjg==","signatures":[{"sig":"MEYCIQCOEbIYX/+PHB2n3DWmK5O7JFC3yltFA/6ty6filQYwAgIhAPLFIpMyGbba5UdruPkoQdl5TbiuQQq0fwJw/srSgrGa","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@dannylee1020%2fkkt@0.7.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":470612},"type":"module","gitHead":"9cde9200787d8829cd3a22d4a12454637f36d6b4","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:8176bf36-773b-4b5f-9c03-217a4d56cad3"}},"repository":{"url":"git+https://github.com/dannylee1020/kkt.git","type":"git"},"_npmVersion":"12.0.1","description":"KKT constrained-optimization workflow skills and CLI installer for coding agents.","directories":{},"_nodeVersion":"24.18.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/kkt_0.7.0_1785295653179_0.31472469434420325","host":"s3://npm-registry-packages-npm-production"}},"0.8.0":{"name":"@dannylee1020/kkt","version":"0.8.0","keywords":["pi-package","agent-skills","coding-agent","claude-code","codex","opencode","pi","kkt"],"license":"Apache-2.0","_id":"@dannylee1020/kkt@0.8.0","maintainers":[{"name":"dannylee1020","email":"dannylee1020@gmail.com"}],"homepage":"https://github.com/dannylee1020/kkt#readme","bugs":{"url":"https://github.com/dannylee1020/kkt/issues"},"pi":{"image":"https://raw.githubusercontent.com/dannylee1020/kkt/main/assets/kkt-readme-modern.png","skills":["./skills"]},"bin":{"kkt-install":"bin/kkt-install.mjs"},"dist":{"shasum":"8159d5d4b2c6ec6caad2e2bf0f24f1572459fb86","tarball":"https://registry.npmjs.org/@dannylee1020/kkt/-/kkt-0.8.0.tgz","fileCount":42,"integrity":"sha512-g1o5SfVHDYDP/TUVrclLtaroI3pJmYMTgeveotDBulR5w9VWSYkSI1Wrz4XeA7hX9qeXYKDbkeVNY5X+eNZG7Q==","signatures":[{"sig":"MEQCIEJkK0qqpseL9XHwzkHfamjSRU2twt0qL/Ca25SlHhE6AiAt8NWqaLUyFDoftRcIHY+cC7Xz+9JDKBZx1ZbfhEoXOw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@dannylee1020%2fkkt@0.8.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":314403},"type":"module","gitHead":"1a185fc762db64c65fa6c2b6ad88cbedf35f0eb9","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:8176bf36-773b-4b5f-9c03-217a4d56cad3"}},"repository":{"url":"git+https://github.com/dannylee1020/kkt.git","type":"git"},"_npmVersion":"12.0.1","description":"KKT constrained-optimization workflow skills and CLI installer for coding agents.","directories":{},"_nodeVersion":"24.18.0","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/kkt_0.8.0_1786468549249_0.15513254768957663","host":"s3://npm-registry-packages-npm-production"}},"0.8.1":{"name":"@dannylee1020/kkt","version":"0.8.1","description":"KKT constrained-optimization workflow skills and CLI installer for coding agents.","license":"Apache-2.0","type":"module","repository":{"type":"git","url":"git+https://github.com/dannylee1020/kkt.git"},"bugs":{"url":"https://github.com/dannylee1020/kkt/issues"},"homepage":"https://github.com/dannylee1020/kkt#readme","keywords":["pi-package","agent-skills","coding-agent","claude-code","codex","opencode","pi","kkt"],"bin":{"kkt-install":"bin/kkt-install.mjs"},"pi":{"skills":["./skills"],"image":"https://raw.githubusercontent.com/dannylee1020/kkt/main/assets/kkt-readme-modern.png"},"gitHead":"739445924e6804eda97591ff541a1bfddec7e420","_id":"@dannylee1020/kkt@0.8.1","_nodeVersion":"24.19.0","_npmVersion":"12.0.1","dist":{"integrity":"sha512-exTraUtvxd9u5wJaBS0vjA9arvkoP+pLOoYCcm0Kab/98VcCnfzGfngrrPhJ7tKGVFWY1dIEvF3w1EkAU3Ku2w==","shasum":"52a3112523d2291d435395df44aadf49203632fa","tarball":"https://registry.npmjs.org/@dannylee1020/kkt/-/kkt-0.8.1.tgz","fileCount":42,"unpackedSize":320596,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@dannylee1020%2fkkt@0.8.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIF71MDVQz2hu1YVfGMkdiDdEsQkl9NSgUgoHkZ7X9HXHAiEA1ARvn+mrP4Z951Xz8MgUYaj+/qod6EO5tRla9h7sDGI="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:8176bf36-773b-4b5f-9c03-217a4d56cad3"}},"directories":{},"maintainers":[{"name":"dannylee1020","email":"dannylee1020@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/kkt_0.8.1_1787164695800_0.4630949257524535"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-08T00:31:09.721Z","modified":"2026-08-19T18:38:16.359Z","0.5.0":"2026-07-08T00:31:10.016Z","0.5.1":"2026-07-08T16:12:03.572Z","0.5.2":"2026-07-21T17:52:22.114Z","0.6.0":"2026-07-21T20:31:04.859Z","0.7.0":"2026-07-29T03:27:33.340Z","0.8.0":"2026-08-11T17:15:49.404Z","0.8.1":"2026-08-19T18:38:15.972Z"},"bugs":{"url":"https://github.com/dannylee1020/kkt/issues"},"license":"Apache-2.0","homepage":"https://github.com/dannylee1020/kkt#readme","keywords":["pi-package","agent-skills","coding-agent","claude-code","codex","opencode","pi","kkt"],"repository":{"type":"git","url":"git+https://github.com/dannylee1020/kkt.git"},"description":"KKT constrained-optimization workflow skills and CLI installer for coding agents.","maintainers":[{"name":"dannylee1020","email":"dannylee1020@gmail.com"}],"readme":"![kkt](assets/kkt-readme-modern.png)\n\n<p align=\"center\">\n  <strong>Start modeling your implementation</strong>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/dannylee1020/kkt/actions/workflows/release-binaries.yml\"><img alt=\"ci status\" src=\"https://img.shields.io/github/actions/workflow/status/dannylee1020/kkt/release-binaries.yml?label=ci\"></a>\n  <a href=\"https://github.com/dannylee1020/kkt/actions/workflows/codeql.yml\"><img alt=\"security status\" src=\"https://img.shields.io/github/actions/workflow/status/dannylee1020/kkt/codeql.yml?label=security\"></a>\n  <a href=\"https://github.com/dannylee1020/kkt/releases/latest\"><img alt=\"release version\" src=\"https://img.shields.io/github/v/release/dannylee1020/kkt?sort=semver&display_name=tag\"></a>\n  <a href=\"LICENSE\"><img alt=\"license: Apache 2.0\" src=\"https://img.shields.io/badge/license-Apache--2.0-2563eb.svg\"></a>\n</p>\n\n<hr style=\"width: 100%; border: 0; border-top: 2px solid #e5e7eb;\">\n\nkkt applies [constrained optimization](https://en.wikipedia.org/wiki/Constrained_optimization) to coding-agent workflows. Named after the [Karush-Kuhn-Tucker conditions](https://en.wikipedia.org/wiki/Karush%E2%80%93Kuhn%E2%80%93Tucker_conditions), it translates mathematical modeling discipline into a practical framework for identifying application constraints, choosing feasible implementation paths, and validating the result.\n\n## How It Works\n\n```text\nWithout kkt:\n\nrequest --> agent --> plan --> edits --> validation\n\n\nWith kkt:\n\nrequest --> agent --> kkt(optimization modeling) --> edits --> validation\n                                 |\n                                 v\n         objective + constraints + decision variables + proof\n```\n\n\n## The Model\n\nThe core idea:\n\n```text\nchoose\n  x in X\n\nmaximize\n  alignment(user_goal, x)\n\nsubject to\n  C_app(x)\n  C_arch(x)\n  C_data(x)\n  C_ui(x)\n  C_infra(x)\n  C_validation(x)\n```\n\nwhere:\n\n- `x` is the implementation decision vector\n- `X` is the feasible implementation region\n- `C_*` are application constraints\n- the selected plan is the best feasible plan, not the first plausible plan\n- validation is the certificate that the selected plan satisfies the model\n\nkkt does not implement a literal numerical solver. It borrows the discipline of constrained optimization and applies it to coding-agent decisions: feasibility first, optimization second, validation as the certificate.\n\n`$kkt-deep` also applies CP-SAT-inspired constraint-search discipline through agent reasoning: explicit decision domains, conditional constraints, feasibility propagation, conflict recording, bounded candidate search, and falsification. It does not run CP-SAT or claim globally proven optimality.\n\n## Install\n\nRecommended install:\n\n```bash\nnpx @dannylee1020/kkt install\n```\n\nThis automatically detects all supported agents available on your system and installs the kkt skills for each one:\n\n- Claude Code: `~/.claude/skills`\n- Codex, Pi, and OpenCode: `~/.agents/skills`\n\nUpgrade kkt with the same automatic detection:\n\n```bash\nnpx @dannylee1020/kkt upgrade\n```\n\nTo target one agent explicitly, use `--target` as an override:\n\n```bash\nnpx @dannylee1020/kkt install --target claude\nnpx @dannylee1020/kkt upgrade --target codex\n```\n\nChoose a CLI install location:\n\n```bash\nnpx @dannylee1020/kkt install --bin-dir ~/.local/bin\n```\n\nAlternative shell installer:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/dannylee1020/kkt/main/scripts/install.sh | bash\n```\n\nThe CLI uses a release binary when available, or builds from source with Go. Use `KKT_VERSION` to pin a release tag, or `KKT_BINARY_URL` to install from an explicit binary URL.\n\n## Why kkt\n\nMost coding-agent workflows turn a request into a plan. That helps, but it carries risk: the plan focuses on what to change, not what must stay unchanged.\n\nkkt shifts the frame from planning to modeling, so the solution is built around the constraints already present in the codebase. It treats implementation as a constrained optimization problem: define the objective, mark the boundaries that cannot move, compare the viable paths, and name the proof that will make the result credible.\n\nInstead of:\n\n```text\nbuild xyz\n```\n\nkkt pushes the agent toward:\n\n```text\nwhat is the best feasible implementation,\ngiven what must stay true?\n```\n\nFor coding agents, \"what must stay true\" is usually concrete:\n\n- public contracts and API behavior\n- architecture boundaries\n- files, modules, endpoints, schemas, and migrations\n- security, privacy, and data-integrity rules\n- UI and product boundaries\n- infrastructure and runtime limits\n- validation evidence required before completion\n\nThe value is forcing feasibility before optimization: reject plans that violate hard constraints, compare the remaining plans, choose the best feasible path, then validate against the model.\n\n## Benchmark\n\nWe tested Vanilla, Plan, KKT, and KKT Deep on 13 [SWE-bench Verified](https://www.swebench.com/SWE-bench/) tasks: 2 easy, 6 medium, and 5 hard. Within each campaign, every workflow used the same tasks, model configuration, resources, and official SWE-bench evaluator.\n\n| Mode | Resolved | Tokens | Production LOC |\n| --- | ---: | ---: | ---: |\n| vanilla | 9/13 | 11.30M | 280 |\n| plan mode | 9/13 | 15.98M | 296 |\n| kkt | 9/13 | 15.84M | **249** |\n| kkt-deep | **10/13** | 21.41M | 305 |\n\nKKT matched Vanilla's solve rate with **11% less code churn**. KKT Deep solved one additional hard task for the best overall result. Both used more tokens, showing a tradeoff between compute and stronger implementation discipline. See the [results and methodology](benchmarks/results/swebench-summary.json).\n\n## kkt vs plan mode\n\nkkt can replace plan mode, or it can run after plan mode to harden a rough plan. Default plan mode already provides read-only exploration, clarification, alternatives, and approval. kkt adds an explicit feasibility model and carries it into execution.\n\n| question | default plan mode | kkt |\n| --- | --- | --- |\n| What is it optimizing for? | Coordination and sequencing | Best feasible implementation |\n| What comes before edits? | Exploration, questions, and an agreed plan | Provisional constraints, feasibility, chosen path, and validation proof |\n| How are assumptions handled? | Usually remain narrative | Verified or marked as assumptions |\n| How are alternatives selected? | Discussed and recommended | Hard-constraint violations rejected before feasible options are compared |\n| How is execution bounded? | Primarily by the approved plan | Model-derived execution bounds, stop conditions, and approval state |\n| When is it enough? | Small or straightforward work | Work where boundaries, contracts, tradeoffs, or proof matter |\n| Where does state live? | Usually chat context | `$kkt` is chat-first; durable `.kkt/` state is opt-in or used by deeper workflows |\n\nPlan mode asks, \"What should we do?\" kkt asks, \"What is the best feasible implementation, given what must stay true?\"\n\n### Constraint-driven clarification\n\nKKT does not add a generic interview before modeling. It uses a short, read-only grounding pass to build a provisional frame, then asks only questions that can change feasibility, scope, the selected optimum, execution bounds, or validation:\n\n```text\ninitial intent\n  -> quick repository grounding\n  -> provisional objective and constraint frame\n  -> targeted owner clarification, if needed\n  -> complete discovery and reject infeasible candidates\n  -> select optimum and binding constraints\n  -> derive and approve the execution plan\n```\n\nClear work can proceed without questions. Imported completed models do not repeat intake unless new evidence causes material drift.\n\n## Quick Start\n\nMost users start with `$kkt`:\n\n```text\n$kkt <feature, bug fix, or refactor>\n```\n\nUse the deeper workflow when the task needs it:\n\n```text\n$kkt-deep <architecture, tradeoff, or complex implementation>\n```\n\n`$kkt` and `$kkt-deep` are separate end-to-end skills. `$kkt` does not invoke, load, or delegate to `$kkt-deep`; when compact modeling is insufficient, it explains the trigger and waits for the user to choose `$kkt-deep`. `$kkt-deep` performs its own modeling, approval, implementation, and validation.\n\nSkill invocation syntax varies by agent:\n\n```text\nCodex:       $kkt, $kkt-deep\nClaude Code: /kkt, /kkt-deep\nPi:          /skill:kkt, /skill:kkt-deep\nOpenCode:    ask OpenCode to use the relevant kkt skill\n```\n\n## Choose a Workflow\n\n| workflow | use it for | what it produces | durable state |\n| --- | --- | --- | --- |\n| `$kkt` | normal feature work, bug fixes, and refactors | compact optimized plan and implementation | none by default |\n| `$kkt-deep` | architecture choices, tradeoffs, and complex implementation | approved deep model, implementation, and validation | optional `.kkt/model/<slug>/` |\n\n### Execution ownership and delegation\n\nKKT keeps the daily path lightweight:\n\n- `$kkt` uses the main agent for discovery and implementation; it does not delegate by default.\n- `$kkt-deep` may use bounded read-only delegation for independent modeling discovery or challenge only when the current harness exposes a compatible native capability and the coordination benefit outweighs its cost. Investigation tracks are generated from the model rather than hardcoded as agent personas; the main agent reconciles their evidence and owns approval, implementation, and final validation. Without that capability, it continues alone.\n\nKKT's CLI remains a deterministic state control plane. It does not spawn agents, route skills, or merge delegated changes. Delegated investigations receive bounded read-only briefs and cannot ask user questions, mutate project or `.kkt/` state, grant approval, select the model, implement changes, or replace final validation.\n\nAll candidate search is correctness-first: complete request coverage, public contracts, and repository-evidenced invariants are the feasibility gate. Among feasible candidates, KKT prefers repairing the invariant at its owner and changing the smallest semantic production surface, then uses production LOC as a tie-breaker. Required validation and safety behavior are part of completeness; raw LOC never makes an unverified solution preferable.\n\nFor ordinary bug fixes, KKT uses a compact causal trace — symptom → producer → invariant owner → consumer → sibling implementations/tests — and performs a focused owner-level or disconfirming check before approval when a plausible alternative remains. After correctness is established, it may remove unnecessary production hunks and rerun the affected checks.\n\nBoth active skills require explicit approval before mutation and finish with validation evidence.\n\nkkt turns rough input into an intent frame:\n\n```text\nuser goal\ndesired behavior\nuser-visible success\nscope boundary\nexplicit user constraints\n```\n\nThe user does not need to provide all of this upfront. Repo constraints, affected files, and validation paths are discovered from the codebase when possible and marked as assumptions when needed.\n\nWhen kkt is invoked after a prior plan, it treats the plan as untrusted scaffold:\n\n```text\nplan output --> extract signals --> classify claims --> verify facts --> optimize kkt model\n```\n\nPlan claims do not become kkt facts until it verifies them or explicitly carries them as assumptions.\n\nBefore edits, every selected model must define its objective, constraints, feasible choice, selected plan, and validation proof. Routine work uses a compact contract; complex or high-risk work uses the deep contract.\n\nExpected final audit:\n\n```text\nObjective: satisfied\nHard constraints: satisfied\nBinding constraints: respected\nValidation evidence: tests, checks, artifacts, or reason validation was not possible\nResidual risk: remaining uncertainty\n```\n\n## CLI and State\n\nMost users do not need to run the CLI directly. The installed skills use it as a deterministic control plane for durable state, execution bounds, approval, validation evidence, and workflow progress.\n\nReference command groups:\n\n```bash\n# workspace creation\nkkt start plan|model \"<request>\"\n\n# record planning and validation state\nkkt intent\nkkt discovery\nkkt model\nkkt evidence\n\n# workflow transitions and diagnostics\nkkt done\nkkt block\nkkt status\nkkt show model\n```\n\nRun `kkt help` for exact syntax. The active skills remain chat-first; durable model workspaces store intent, discovery, model, and evidence under the project root's `.kkt/` directory. Legacy run/loop CLI commands may remain available for compatibility but are no longer documented or packaged as skills.\n\n## Validation evidence\n\nKKT is a workflow guide and state recorder, not a sandbox. Both active skills own implementation after approval and must report validation commands, checks, artifacts, or an explicit validation limitation. Durable model workspaces preserve the reasoning and evidence needed for handoff without introducing a separate execution skill.\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md"}