Menu
Run an integration test (Docker-based, optionally AWS-deploy-backed for `*-from-cfn-stack` tests) and refresh the `integ` markgate marker on a clean run.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | run-integ |
| description | Run an integration test (Docker-based, optionally AWS-deploy-backed for `*-from-cfn-stack` tests) and refresh the `integ` markgate marker on a clean run. |
| argument-hint | <test-name> |
Run an integration test against real Docker (and, for *-from-cfn-stack tests, a real CloudFormation stack deployed via the upstream cdk CLI).
cdk-local is a local-execution CLI — it does NOT deploy resources itself. The only AWS-side activity in any integ test is when a fixture's verify.sh invokes the upstream cdk deploy to create a target stack for --from-cfn-stack to point at. Cleanup is always done by the fixture's own verify.sh.
test-name: Which test to run. Run ls tests/integration/ to see all available tests. If not specified, use the AskUserQuestion tool to ask which test to run, showing the available options.Build first: Run vp run build to ensure dist/cli.js is up to date. The fixture's verify.sh resolves the binary via node ../../../dist/cli.js, so source changes without a build have no runtime effect.
Resolve the fixture path: tests/integration/<test-name>/. Confirm verify.sh exists; if not, the test does not have a Docker-driven flow yet and this skill exits with a clear error pointing the user at the missing script.
Pre-flight Docker sweep: docker ps --filter name=cdkl- -q | wc -l and docker network ls --filter name=cdkl-task- -q | wc -l should both return 0. If either is non-zero, abort and ask the user to run /cleanup first — running on top of orphans causes name collisions and confusing failures.
For *-from-cfn-stack tests only — AWS pre-flight:
cdk CLI is on $PATH: which cdk.aws sts get-caller-identity.aws cloudformation describe-stacks --stack-name <FixtureStackName> 2>/dev/null && echo "ORPHAN" || echo "(no orphan stack)"
cdk destroy <FixtureStackName> recipe — do NOT proceed.Run the test: bash tests/integration/<test-name>/verify.sh. Propagate the script's exit code — a non-zero exit must drive this skill into the failure path so step 7's cleanup verification fires. Do NOT swallow verify.sh failures.
Verify Docker cleanup (mandatory regardless of pass/fail):
docker ps --filter name=cdkl- -q | wc -l # must be 0
docker network ls --filter name=cdkl-task- -q | wc -l # must be 0
docker network ls --filter name=cdkl-svc- -q | wc -l # must be 0
If any are non-zero, dispatch /cleanup (no --detect-only) and re-run the checks. Never end the run with orphan Docker resources still present.
Verify AWS cleanup (only for *-from-cfn-stack tests):
aws cloudformation describe-stacks --stack-name <FixtureStackName> 2>/dev/null \
&& echo "ORPHAN STACK REMAINS" \
|| echo "AWS clean"
If the stack remains, run cdk destroy <FixtureStackName> --force until clean. Same rule: never end the run with orphan AWS resources.
Report results: Show pass/fail for the test, plus a one-line cleanup summary ("docker: 0 orphans, network: 0 orphans" / for from-cfn-stack: "+ AWS: 0 orphan stacks").
Set the integ markgate marker (only on full clean success):
When — and ONLY when — all of the following hold:
verify.sh step finished with exit code 0,record the gate so subsequent gh pr merge calls are unblocked:
mise exec -- markgate set integ
If any of the above failed, do NOT set the marker — that is the whole point of the gate. The integ gate (see .markgate.yml) blocks gh pr merge for any PR that touches src/** or tests/integration/** until this marker is fresh.
verify.sh directly from a shell — the cleanup verification + markgate set are part of the contract.markgate set integ directly to skip the verification. The marker only earns its place by completing the full sequence above.ls tests/integration/) — typos lead to confusing "no verify.sh" errors..markgate.yml) accepts that Docker base-image behavior drifts over time even when the repo doesn't; re-running an integ after two weeks is the explicit revalidation.Proactively hunt for cdk-local bugs by synthesizing real CDK apps that exercise common-but-untested AWS resources, configs, and CloudFormation notations, then RUNNING them locally in Docker (invoke / start-api / run-task / start-service / start-alb / start-cloudfront / invoke-agentcore / studio) and catching local-execution failures + divergences from deployed behavior. Use for a periodic "find latent bugs" sweep, not for verifying a specific change.
Work through already-filed GitHub issues (typically the bug-hunt's output) end to end — triage safely, pick a few FILE-DISJOINT issues to fix in parallel, claim each on the issue before starting (collision-safe with other agents), verify, then carry each through merge (via /merge-pr) → pull → worktree cleanup. Use when asked to "handle/address filed issues", not to hunt for new bugs (that is /hunt-bugs).
Squash-merge a PR and fully clean up the feature worktree + local branch, without tripping the side-worktree `'main' is already used by worktree` fatal and without bypassing the merge-time gates.
Detect and delete leftovers from interrupted cdk-local runs — Docker containers / networks, AND orphaned vitest forks worker processes that failed to terminate (issue
Triggers when a PR adds a new subcommand factory, CLI option, public helper, or behavior change to cdk-local that cdkd (host CLI) may need to inherit. Walks the diff and pins each category to "exported via internal.ts / inside add<Cmd>SpecificOptions / cdkd notified" — sets the cdkd-parity marker so gh pr create can fire.
Check if documentation (README.md, .claude/CLAUDE.md) is up to date with recent code changes. Use when code has been modified and docs may be stale.