{"id":51171670,"url":"https://github.com/dannylee1020/kkt","last_synced_at":"2026-06-27T01:01:37.681Z","repository":{"id":365602587,"uuid":"1272677604","full_name":"dannylee1020/kkt","owner":"dannylee1020","description":"Start modeling your implementation","archived":false,"fork":false,"pushed_at":"2026-06-26T23:07:35.000Z","size":162,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T00:34:05.021Z","etag":null,"topics":["agentic-coding","ai-agents","mathematical-modelling","mathematics","skills"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dannylee1020.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-17T20:54:02.000Z","updated_at":"2026-06-26T23:07:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dannylee1020/kkt","commit_stats":null,"previous_names":["dannylee1020/kkt"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dannylee1020/kkt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannylee1020%2Fkkt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannylee1020%2Fkkt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannylee1020%2Fkkt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannylee1020%2Fkkt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dannylee1020","download_url":"https://codeload.github.com/dannylee1020/kkt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dannylee1020%2Fkkt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34838035,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-coding","ai-agents","mathematical-modelling","mathematics","skills"],"created_at":"2026-06-27T01:01:15.831Z","updated_at":"2026-06-27T01:01:37.667Z","avatar_url":"https://github.com/dannylee1020.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"![kkt](assets/kkt-readme-modern.png)\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eStart modeling your implementation\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/dannylee1020/kkt/actions/workflows/release-binaries.yml\"\u003e\u003cimg alt=\"ci status\" src=\"https://img.shields.io/github/actions/workflow/status/dannylee1020/kkt/release-binaries.yml?label=ci\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/dannylee1020/kkt/actions/workflows/codeql.yml\"\u003e\u003cimg alt=\"security status\" src=\"https://img.shields.io/github/actions/workflow/status/dannylee1020/kkt/codeql.yml?label=security\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/dannylee1020/kkt/releases/latest\"\u003e\u003cimg alt=\"release version\" src=\"https://img.shields.io/github/v/release/dannylee1020/kkt?sort=semver\u0026display_name=tag\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"license: Apache 2.0\" src=\"https://img.shields.io/badge/license-Apache--2.0-2563eb.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003chr style=\"width: 100%; border: 0; border-top: 2px solid #e5e7eb;\"\u003e\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 --\u003e agent --\u003e plan --\u003e edits --\u003e validation --\u003e finish\n\n\nWith KKT:\n\nrequest --\u003e agent --\u003e KKT modeling --\u003e edits --\u003e validation --\u003e finish\n                           |\n                           v\n        constraints --\u003e optimization --\u003e verification\n```\n\n## Why kkt\nGood implementation plans are shaped as much by what not to do as by what to do.\n\nkkt makes those limits explicit. Before choosing an implementation path, it pushes the agent to identify the constraints that define a safe change: public contracts that must not break, architecture boundaries that must not be crossed, data rules that must not be weakened, and validation that must not be skipped.\n\nInstead of:\n\n```text\nbuild xyz\n```\n\nmodel the work as:\n\n```text\nwhat is the optimized implementation,\ngiven what must stay true?\n```\n\nThe result is a more disciplined implementation plan: fewer accidental side effects, clearer tradeoffs, smaller edits, and validation tied to the actual constraints of the work.\n\nFor coding agents, those constraints are usually concrete:\n\n- existing architecture and public contracts\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 to prove completion\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\n## Interface\n\nKKT is skill-first. Invoke `$kkt`, `$kkt-model`, or `$kkt-loop` from your coding agent. The CLI is the tool those skills rely on for `.kkt/` scaffolding, status, state persistence and validation,\n\n| piece | what it offers | use when |\n| --- | --- | --- |\n| Skills | Primary KKT workflows inside your coding agent. Includes `$kkt`, `$kkt-model`, and `$kkt-loop`. | You want KKT to guide planning, approval, implementation, and validation. |\n| CLI | Deterministic `.kkt/` state scaffolding and validation used by the skills. | Durable state needs to stay consistent across KKT layers and continuations. |\n\n\n## Install\n\nInstall KKT:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/dannylee1020/kkt/main/scripts/install.sh | bash\n```\n\nThe installer auto-detects supported coding agents, installs KKT skills into their global skill directories, and installs the companion CLI. Plain `install` is safe to rerun: it installs missing skills, keeps existing skills unchanged, and still installs or updates the CLI. Use `upgrade` when you want to replace installed KKT skills with the latest downloaded copy.\n\n```bash\nscripts/install.sh --target codex\nscripts/install.sh --target claude\nscripts/install.sh --target all\nscripts/install.sh --bin-dir ~/.local/bin\nscripts/install.sh upgrade\n```\n\nFrom a checkout:\n\n```bash\nscripts/install.sh\n```\n\n## Quick Start\n\nInvoke the skill directly:\n\n```text\n$kkt \u003cfeature to implement\u003e\n$kkt-model \u003carchitecture or tradeoff question\u003e\n$kkt-loop \u003clong-running implementation\u003e\n```\n\nSkill invocation syntax varies by agent:\n\n```text\nCodex:       $kkt\nClaude Code: /kkt\nPi:          /skill:kkt\nOpenCode:    ask OpenCode to use the kkt skill\n```\n\nThe skills are installed from the downloaded source archive. The CLI is downloaded as a release binary when available, or built from source with Go. Use `KKT_VERSION` to pin a release tag, or `KKT_BINARY_URL` to install from an explicit binary URL.\n\nCLI workflow commands:\n\n```bash\nkkt start plan|model|loop \"\u003crequest\u003e\"\nkkt status\nkkt next [--json]\nkkt show [artifact]\nkkt intent|discovery|model|plan|progress|evidence|notes\nkkt evidence --for \u003ccriterion-id\u003e --command \"\u003ccommand\u003e\" \"\u003cvalidation evidence\u003e\"\nkkt criteria add|satisfy|block\nkkt task add|start|done|skip|block\nkkt approve\nkkt block\nkkt validate\nkkt done\nkkt resume\nkkt replay --check\n```\n\nFor loop workspaces, `kkt.yaml` is the canonical current contract, `events.jsonl` is the append-only audit and resume history, and Markdown files hold rich context and evidence. `kkt replay --check` reports drift between the event history and current state without mutating either file.\n\n\n## Skills\n\n| skill | use it for | output | durable state |\n| --- | --- | --- | --- |\n| `$kkt` | normal feature work, bug fixes, and refactors | lightweight model, approval, implementation, validation | optional `.kkt/kkt.yaml` |\n| `$kkt-model` | architecture choices and tradeoff analysis | selected model or decision brief | `.kkt/model/\u003cslug\u003e/`|\n| `$kkt-loop` | long-running or autonomous work | deeper planning, approval, durable workspace, progress, evidence | `.kkt/loop/\u003cslug\u003e/`|\n\nAll durable state lives under `.kkt/`. `kkt.yaml` is the canonical state index. Markdown files hold richer context when YAML would lose detail. Advanced methods such as coupling maps, decision trees, staged-path planning, and tradeoff ranking are available when deeper modeling is needed, while `$kkt` stays compact.\n\n## Request Shape\n\nkkt turns rough input into an intent frame before modeling:\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\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## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannylee1020%2Fkkt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdannylee1020%2Fkkt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdannylee1020%2Fkkt/lists"}