Repository navigation
Releases
qk v0.8.0
qk now keeps evidence. Runs, evals, findings and decisions go into a local append-only ledger, and a new qk CLI reads it. On top of the ledger, qk can record mistakes AI agents repeat as lessons, but a lesson can be turned on only after a measurement shows that it helps.
Added
- Evidence ledger and
qkCLI (scripts/qk.py):show,stats,log claim, read-only PRsyncwith run backfill, and an offlinebriefthat marks evidence stale when a PR head changes.qk run …andqk eval …wrap the existing scripts, which stay supported. The ledger lives outside the repository (~/.local/state/qk/ledger.jsonl); ledger failures warn without failing the task. (#34, #35, #36) - Lessons:
qk lesson suggest/propose/list/decide(#37);--lessonsforqk-runandqk_eval, at most 5 lessons and about 800 tokens per turn, prompts unchanged without it (#38);qk lesson measure ID --runtime SPEC, which runs the lesson's case twice with and twice without it plus same-stage controls (#39). Activation needs a helping measurement under 60 days old; a run that failscleanvoids the measurement. Guide:docs/{en,vi}/lessons.md. - Eval cases:
pip-config-reviewfrom a public pip pull request (#33),test-failure-triageandhandoff-drift. Kit comparison results (no kit, Superpowers, qk) are on the test evidence page (#32).
Verified
- CI on each pull request:
scripts/validate.pyand the unit tests on Python 3.9 and 3.12, plus gitleaks. - #37, #38 and #39 were cross-audited by two model families (Claude and Codex); four findings were fixed before merge.
- The first real lesson (
parser-reuseonpip-config-review, Codexgpt-6.1-sol) did not help: with it 1/2, without it 1/2. It was dismissed; the table is indocs/en/evidence.md. No lesson is active by default.
Upgrade
npx skills add 'dakiquang/qk#v0.8.0' -g -a claude-code codex qwen-code -yOr npx skills update -g -y if you installed without a pin. No skill invocation changed.
What changes on your machine:
qk-runandqk_evalnow record runs and eval attempts in the local ledger automatically. It lives at~/.local/state/qk/ledger.jsonl; setQK_STATE_DIRorXDG_STATE_HOMEto move it.qk-cook,qk-testandqk-handoffmay save one conclusion withqk log claimwhen theqkCLI is installed, a ledger ID is known and writes are authorised; otherwise they skip it.- Lessons stay off unless you pass
--lessons.
qk v0.7.0
qk's eval harness can now compare kits. qk_eval.py --kit none|qk|superpowers runs the same fixed cases with no kit, with Superpowers, or with qk, on one Claude Code base, so the question "how is qk different?" can be answered with numbers instead of descriptions.
Added
qk_eval.py --kit none|qk|superpowers(with--superpowers-dirfor a Superpowers checkout). All three kits run on one base: no user skills or plugins (--setting-sources project), no MCP in read-only turns, and Claude Code's own skills kept.nonegets only the task,superpowersloads with--plugin-dirso it activates as designed, andqkgets the qk skill or the runner's review prompt. The output format the graders need is given in the same words to every kit, so no kit wins on format alone. Comparison results never compare with or updatebaseline.json. (#30)
Fixed
- The Claude Code
bundle-malformedbaseline is re-recorded with the v0.6.0 review prompt; it was the only review-case entry still from the previous prompt, which could have hidden a later token increase of about 20%. Found by a cross-model audit of v0.6.0. (#29)
Upgrade
npx skills add 'dakiquang/qk#v0.7.0' -g -a claude-code codex qwen-code -yOr npx skills update -g -y if you installed without a pin. No skill invocation or configuration changed.
Verified
- CI on each pull request:
scripts/validate.pyand the unit tests (121) on Python 3.9 and 3.12, plus a gitleaks scan. - Checked on this machine before building
--kit:--setting-sources projectkeeps Claude Code logged in and drops user skills and plugins; a separateCLAUDE_CONFIG_DIRloses the login. Superpowers 7.0.2 loads with--plugin-dirand its session-start hook runs. - Not yet published: the comparison results themselves (4 cases × 3 kits × 2 runs on Claude Code). They are running and will be added to the test evidence page.
qk v0.6.0
qk can now measure itself. scripts/qk_eval.py runs fixed cases from real work, grades them by code, and tells you whether a change to a skill or to the runner made things better or worse. The first change it measured is a new review prompt.
Evidence, not claims. A change to qk is now judged by a before/after table, not by how it reads.
Added
scripts/qk_eval.py: runs each case as one real agent turn in a throwaway repository (with the runner's isolation and read-only guard), grades it with the case's owncheck.py, prints criteria, tokens and time, and compares them withevals/baseline.json. A lost criterion, an agent error, or tokens more than 10% and more than 25,000 above the baseline exits 1; a case whose result flips is rerun once;--update-baselinerecords an accepted result. Graders run from a copy taken before the turn, and a turn that touches the case directory fails acleancriterion. (#23, #26)- Four cases in
evals/cases/:csv-export(qk-cook),pagination-empty-page(qk-debug),bundle-malformedandwaf-bundle-review(the runner's review step).waf-bundle-reviewreplays a real 1,200-line pull request with eight real defects put back. (#23, #25) - Baselines for omp and Claude Code with Claude Opus 5.5. (#24, #26)
Changed
- Review prompt (
qk_run.review_prompt): reviewers name the defect class of each finding and search the whole diff for every other instance in the same pass; a crash or unhandled error on input the code accepts from outside is at least important; read-only reviewers read files only and do not call MCP. (#26)
Measured
| Case | Runtime | Previous prompt | New prompt (each run) |
|---|---|---|---|
waf-bundle-review (8 real defects) |
omp | 0/8 | 5, 5, 4 |
waf-bundle-review |
Claude Code | 0/8 | 3, 6, 5 |
bundle-malformed (3 defects) |
both | 6/6 | 6/6 |
Tokens on the hard case stayed flat on omp and fell 24–38% on Claude Code. On the small case, six omp runs showed the new prompt costs about 4% more at the same number of agent turns; a first run that looked like +36% was one extra turn spent re-reading cited lines. Details and raw numbers: Test evidence.
Upgrade
npx skills add 'dakiquang/qk#v0.6.0' -g -a claude-code codex qwen-code -yOr npx skills update -g -y if you installed without a pin. No skill invocation or configuration changed. Running the evals costs real tokens: each case is a full agent turn.
Verified
- CI on each pull request:
scripts/validate.pyand the unit tests on Python 3.9 and 3.12, plus a gitleaks scan. - Cross-model audits (Claude and GPT through Codex) of the harness PR found six important issues, including graders an agent could edit and a test criterion any failure could satisfy; all were fixed with tests before merge.
- Not yet verified: how qk compares with no kit and with other kits on the same cases. That comparison is the next step.
qk v0.5.0
qk-run now shows what the agent is doing, and it runs agents with only qk's own skills: no globally installed skills, and no MCP in read-only stages.
Evidence, not claims. This release makes the runner's own work visible: every tool action, every MCP call, and the tokens each stage used.
Added
- Live progress: each agent tool action is printed as one line (
read,edit,write,run), withstill running (...)after 60 s of silence. Raw events of every turn are saved to<stage>-<ts>.events.jsonl, andstatusprints the run directory and the last 10 log lines. (#18) - Token usage per agent call:
tokens in=... cached=... out=...(pluscost=$...when the runtime reports it) inrun.log, and per stage underusageinstate.json. (#20) qk-run start --read-only-mcp NAME(repeatable, Claude and omp only) lets planning and review call one named MCP server, for example AWS documentation. (#20)
Changed
- Isolation. Agents no longer load globally installed skills: Claude runs with
--disable-slash-commands, omp with--no-skills --no-extensions --no-rules, and Codex in a private home inside the run directory with plugins, remote plugins and apps turned off. Read-only Claude stages also run with--strict-mcp-config. (#20, #21) - Read-only guard. A planning or review stage that calls MCP or another
xd://device is stopped and blocks withread-only stage called <action>. omp cannot turn MCP off in advance, so its first such call has already run when the guard stops it. (#20) - Resume after a hand fix. After a block at verify, review or fix, edit the worktree and
resume: the runner logsmanual changes recorded: <files>and verifies and reviews your fix. Edits made while a read-only stage ran still keep the run blocked, and the single fix round is not reset. (#20) - MCP calls are logged as
mcp <identifier>andxd://report_issueastool report_issue, instead ofwrite xd://.... (#20) - A timeout stops the agent's whole process group (SIGTERM, then SIGKILL after 10 s). Commit and PR titles are cut at a word boundary. (#18)
Upgrade
npx skills add 'dakiquang/qk#v0.5.0' -g -a claude-code codex qwen-code -yOr npx skills update -g -y if you installed without a pin. No skill invocation or configuration changed. qk-run users: Codex turns now run with a private HOME, so tools Codex starts do not see your ~/.gitconfig or gh login.
Verified
- CI on each pull request:
scripts/validate.pyand the unit tests (95) on Python 3.9 and 3.12, plus a gitleaks scan. - Cross review of #20 by two model families (Claude and GPT through Codex): two important findings (the guard blocked a plain
grep 'xd://'; an empty--read-only-mcpletmcp://resources through) and two nits, all fixed with regression tests that fail on the earlier code. - Live check after merge, on a scratch repository with the new runner:
- omp, read-only, asked to call an MCP tool: blocked after 12 s with
read-only stage called mcp mcp__onedevtool_tasks_list. - omp, read-only,
grepfor the patternxd://: not blocked. - Claude, read-only: no MCP servers and no skills visible.
- Codex (after #21): only its built-in skills (
imagegen,openai-docs,skill-creator,skill-installer), no user MCP. - A
tokensline was logged on all three runtimes.
- omp, read-only, asked to call an MCP tool: blocked after 12 s with
- Not yet verified: a full
qk-runstart-to-PR run on the new runner; this is the next run.
qk v0.4.0
qk now has a one-page philosophy, and the skills that check work stop at "enough".
Understand enough to decide. Getting code to run is easy now; what stays hard is seeing clearly enough to make the call. qk optimizes only for that.
Added
- A philosophy page in English and Vietnamese: the core idea and three principles (three roles: make, check, decide; evidence, not claims; enough), each with what it does and does not mean, plus the role of every skill. The README and docs index now point to it instead of keeping their own lists. (#15)
Changed
qk-cook,qk-test,qk-debug,qk-researchandqk-planaudit now check only what could change the decision, once, the cheapest sufficient way, and reuse what the session already saw, instead of re-verifying everything. (#16)
Upgrade
npx skills add 'dakiquang/qk#v0.4.0' -g -a claude-code codex qwen-code -yOr npx skills update -g -y if you installed without a pin. No invocation syntax, configuration or script path changed.
Verified
- CI on each pull request:
scripts/validate.pyand the unit tests on Python 3.9 and 3.12, plus a gitleaks scan. - One before/after run of
qk-cookon Claude Code 2.1.325 with a fixed failing-test task: 5 turns each, 250,999 tokens before and 251,201 after; both fixed the test, ran it, and ended with the four report labels. This shows the rule did not break the skill or add cost; the task was too small to show savings. Details are on the Test evidence page. - Not yet verified: the changed skills on Codex, omp and Qwen Code.
qk v0.3.0
qk now installs with one command into Claude Code, Codex, Qwen Code and other tools that read ~/.agents/skills:
npx skills add dakiquang/qk -g -a claude-code codex qwen-code -ySkills keep their plain names, so on Claude Code you still call /qk-plan. omp reads the same directories and needs no separate step. To pin this release, use npx skills add 'dakiquang/qk#v0.3.0' …; the part after @ is read as a skill name, not a version. See Getting started for updating, removing, and the manual clone-and-link install.
Added
- One-command installation with
npx skills, documented in English and Vietnamese with pinning, update and removal. The clone-and-link install stays forqk-run, the validator, editing skills, or machines without Node.js. (#12)
Changed
qk-commitandqk-prefsnow carry their helper scripts inside their own skill folders, so they keep working when an installer copies only the skill folder. (#11)
Upgrade notes
- If you registered the preference hook with
scripts/qk_prefs.pyin a qk clone, point it atskills/qk-prefs/scripts/qk_prefs.py. - Releases before
v0.3.0cannot be installed withnpx skills: theirqk-commitandqk-prefslook for scripts outside the skill folder. Pin those through a clone. - Switching from a manual install: remove the old links first, because
npx skillsreplaces a skill of the same name.
Verified
- CI on each pull request:
scripts/validate.pyand the unit tests on Python 3.9 and 3.12, plus a gitleaks scan. A new test copies each skill folder elsewhere and runs its scripts from the copy. - With skills 1.8.1 in an empty temporary
HOME: installs from GitHub and from a local clone placed all twelve skills with theiragents/openai.yaml,disable-model-invocationand scripts; Claude Code 2.1.325 listed them without aqk:prefix; pinning with#<tag>,checkandremoveworked. Details are on the Test evidence page. - Not yet verified: calling the skills after this install on Codex and omp, and Qwen Code.
v0.2.0
qk is a small set of agent skills for Claude Code, Codex and omp: compare approaches, plan, implement with verification, debug, test, hand off between sessions, coordinate a second model, commit, and draft release notes. Every skill runs only when you call it by name (configured and checked on Claude Code, Codex and omp), states what it may and may not do, and ends its report with Done, Evidence, Not verified and Needs your decision. It extends the runtime you already use and does not replace it.
This is the first release published on GitHub. Start with the README and Getting started; the full list of skills and what each one returns is in the docs index. Earlier changes are in the changelog.
Changed
- qk-run follows your repository's commit convention. When most of the base branch's last 20 non-merge commits look like
type(scope): subject, the runner prefixes the commit and PR title with a type (feat,fix,docs,testorrefactor, taken from the plan title's first word) and lowercases the first letter, keeping acronyms such asREADMEorCI. A plan title that is already conventional is kept as written, and repositories without the convention see no change. (#8) - Documentation rewritten for a public audience. A new README explains what qk is and why it exists. The docs index is grouped into Start here, Guides and Reference, and dated test records now live on one Test evidence page so the guides stay current. Both English and Vietnamese are updated. (#7)
Removed
- Internal planning notes and a dated project summary that were not user documentation. (#7)
Upgrade notes
- If you run
qk-runon a repository that uses Conventional Commits, its commit and PR titles change from the bare plan title totype: subject. To choose the type yourself, give the plan a conventional title beforeapprove. - No skill instructions, invocation syntax or configuration changed.
Install or pin
git clone https://github.com/dakiquang/qk ~/src/qk
git -C ~/src/qk checkout v0.2.0Then link the skill folders into your runtime as described in Getting started. If you already have a clone, git -C ~/src/qk fetch --tags and check out v0.2.0.
Verified
- CI on each pull request passed:
scripts/validate.pyand the unit tests on Python 3.9 and 3.12, plus a gitleaks scan. - The new title rules are covered by unit tests, including merge commits in history and acronyms. The runner has not yet been run end to end with this new code.
- Runtime smoke results and their limits are recorded on the Test evidence page. Qwen Code is not yet checked.