Skip to content

feat(code): add guided-manual-qa skill (ISS-11436) - #205

Merged
shafty023 merged 2 commits into
mainfrom
feat/iss-11436-guided-manual-qa
Sep 28, 2026
Merged

shafty023 merged 2 commits into
mainfrom
feat/iss-11436-guided-manual-qa

Conversation

@shafty023

Copy link
Copy Markdown
Collaborator

Summary

Ports the guided-manual-qa skill into the code plugin as code:guided-manual-qa (ISS-11436).

The skill derives and runs an interactive, evidence-recorded manual QA session for a change, ticket, branch, or PR:

  • maps candidate checkpoints to passing exact-head E2E first, and asks a human only about uncovered behavior
  • prepares a worktree-owned local environment and proves listener and persistence ownership before the first checkpoint
  • keeps a durable Markdown QA record outside the tracked tree
  • proves each checkpoint's oracle before presenting it, then records human PASS / FAIL / BLOCKED one checkpoint at a time

Placement

  • plugins/code/skills/guided-manual-qa/: SKILL.md plus references/ (plan methodology, browser-state fixtures, QA record template). code is the hub for coding-workflow skills and already owns the adjacent validation skills.
  • Codex-specific bits were adapted: dropped agents/openai.yaml, replaced the $CODEX_HOME script path with ${CLAUDE_SKILL_DIR} in SKILL.md (the only file where it is substituted), and replaced the Codex state directory with a harness-neutral user-level QA record location.

Browser launcher ported to TypeScript

Per the repo's TS-only policy for new tool scripts, the Codex .cjs launcher is rewritten as tools/guided-manual-qa/src/launch-interactive-browser.ts with a 40-case vitest suite, bundled to skills/guided-manual-qa/scripts/dist/launch-interactive-browser.mjs. Behavior is preserved: Playwright resolves from the repository under test (never bundled), non-HTTP(S) URLs and non-string fixture values are rejected, private auth state is merged without mutation, the --ready-selector gate and settled origin/path/Clerk-handshake check run before readiness, and only key names are printed.

Shared toolchain helpers

runWhenMain was already duplicated between design-inventory and code-review-cost, and their build.mjs files were near copies. Instead of a third copy, both now live in tools/shared/ (cli.ts, build-bundles.mjs), and all three packages import them by relative path. The CI TypeScript job becomes a matrix over all three toolchains (code-review-cost previously had no CI). The check for design-inventory keeps its name, TypeScript (design-inventory).

Rebuilt bundles differ only in the inlined helper's source-path comment. design-inventory no longer emits the unused cli.mjs bundle.

Versions

  • code 1.14.11 -> 1.15.0 (new skill)
  • code-review 3.10.1 -> 3.10.2 (rebuilt cost-report.mjs, comment-only diff)

Testing

  • npm run typecheck and npm test pass for all three toolchains (guided-manual-qa 40, design-inventory 393, code-review-cost 43); bundles rebuilt.
  • uv run ruff check . clean, uv run pyright 0 errors, uv run pytest plugins/ 2175 passed.
  • Smoke-tested the built launcher: --help works, and the missing-Playwright path fails with the expected error.
  • Not done: a real headed-browser launch. The local sandbox blocked starting Chromium, so the Playwright-driven path (context creation, ready-selector wait, storage verification in a live browser) has unit coverage of its logic but no live run.

Port the guided-manual-qa skill into the code plugin as
code:guided-manual-qa. It derives and runs an interactive,
evidence-recorded manual QA session: exact-head E2E coverage mapping,
worktree-owned environment and persistence proof, a durable QA record,
per-checkpoint oracle proof, and PASS/FAIL/BLOCKED human checkpoints.

The interactive browser launcher is ported to TypeScript under
tools/guided-manual-qa with vitest coverage, bundled to
scripts/dist/launch-interactive-browser.mjs. Playwright is still
resolved from the repository under test.

Extract the duplicated runWhenMain helper and esbuild driver into
tools/shared so design-inventory, code-review-cost and guided-manual-qa
share one copy, and run all three toolchains in a CI matrix. Rebuilt
bundles differ only in the inlined helper's source comment;
design-inventory no longer emits the unused cli.mjs bundle.
@shafty023
shafty023 merged commit ed49565 into main Sep 28, 2026
7 checks passed
@shafty023
shafty023 deleted the feat/iss-11436-guided-manual-qa branch September 28, 2026 16:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant