Skip to content

Releases

qk v0.8.0

Choose a tag to compare

@dakiquang dakiquang released this 18 Nov 07:45
be07abd

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 qk CLI (scripts/qk.py): show, stats, log claim, read-only PR sync with run backfill, and an offline brief that marks evidence stale when a PR head changes. qk run … and qk 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); --lessons for qk-run and qk_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 fails clean voids the measurement. Guide: docs/{en,vi}/lessons.md.
  • Eval cases: pip-config-review from a public pip pull request (#33), test-failure-triage and handoff-drift. Kit comparison results (no kit, Superpowers, qk) are on the test evidence page (#32).

Verified

  • CI on each pull request: scripts/validate.py and 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-reuse on pip-config-review, Codex gpt-6.1-sol) did not help: with it 1/2, without it 1/2. It was dismissed; the table is in docs/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 -y

Or npx skills update -g -y if you installed without a pin. No skill invocation changed.

What changes on your machine:

  • qk-run and qk_eval now record runs and eval attempts in the local ledger automatically. It lives at ~/.local/state/qk/ledger.jsonl; set QK_STATE_DIR or XDG_STATE_HOME to move it.
  • qk-cook, qk-test and qk-handoff may save one conclusion with qk log claim when the qk CLI 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

Choose a tag to compare

@dakiquang dakiquang released this 15 Nov 01:06
bc2fa21

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-dir for 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. none gets only the task, superpowers loads with --plugin-dir so it activates as designed, and qk gets 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 update baseline.json. (#30)

Fixed

  • The Claude Code bundle-malformed baseline 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 -y

Or 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.py and the unit tests (121) on Python 3.9 and 3.12, plus a gitleaks scan.
  • Checked on this machine before building --kit: --setting-sources project keeps Claude Code logged in and drops user skills and plugins; a separate CLAUDE_CONFIG_DIR loses the login. Superpowers 7.0.2 loads with --plugin-dir and 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

Choose a tag to compare

@dakiquang dakiquang released this 15 Nov 00:00
4f58452

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 own check.py, prints criteria, tokens and time, and compares them with evals/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-baseline records an accepted result. Graders run from a copy taken before the turn, and a turn that touches the case directory fails a clean criterion. (#23, #26)
  • Four cases in evals/cases/: csv-export (qk-cook), pagination-empty-page (qk-debug), bundle-malformed and waf-bundle-review (the runner's review step). waf-bundle-review replays 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 -y

Or 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.py and 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

Choose a tag to compare

@dakiquang dakiquang released this 14 Nov 13:36
1502544

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), with still running (...) after 60 s of silence. Raw events of every turn are saved to <stage>-<ts>.events.jsonl, and status prints the run directory and the last 10 log lines. (#18)
  • Token usage per agent call: tokens in=... cached=... out=... (plus cost=$... when the runtime reports it) in run.log, and per stage under usage in state.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 with read-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 logs manual 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> and xd://report_issue as tool report_issue, instead of write 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 -y

Or 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.py and 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-mcp let mcp:// 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, grep for the pattern xd://: 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 tokens line was logged on all three runtimes.
  • Not yet verified: a full qk-run start-to-PR run on the new runner; this is the next run.

qk v0.4.0

Choose a tag to compare

@dakiquang dakiquang released this 14 Nov 02:44
c7041ba

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-research and qk-plan audit 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 -y

Or 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.py and the unit tests on Python 3.9 and 3.12, plus a gitleaks scan.
  • One before/after run of qk-cook on 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

Choose a tag to compare

@dakiquang dakiquang released this 14 Nov 00:12
c55ce3a

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 -y

Skills 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 for qk-run, the validator, editing skills, or machines without Node.js. (#12)

Changed

  • qk-commit and qk-prefs now 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.py in a qk clone, point it at skills/qk-prefs/scripts/qk_prefs.py.
  • Releases before v0.3.0 cannot be installed with npx skills: their qk-commit and qk-prefs look for scripts outside the skill folder. Pin those through a clone.
  • Switching from a manual install: remove the old links first, because npx skills replaces a skill of the same name.

Verified

  • CI on each pull request: scripts/validate.py and 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 their agents/openai.yaml, disable-model-invocation and scripts; Claude Code 2.1.325 listed them without a qk: prefix; pinning with #<tag>, check and remove worked. 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

Choose a tag to compare

@dakiquang dakiquang released this 13 Nov 23:39
82a05ed

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, test or refactor, taken from the plan title's first word) and lowercases the first letter, keeping acronyms such as README or CI. 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-run on a repository that uses Conventional Commits, its commit and PR titles change from the bare plan title to type: subject. To choose the type yourself, give the plan a conventional title before approve.
  • 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.0

Then 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.py and 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.