codagent-ai/agent-skills/test-flows

Test Flows

Exercise the checked-out product as a user or real client would. This is a lightweight flow check, not automated validation or formal acceptance preparation.

Inputs

Read the caller-supplied:

• approved behavior or planning artifacts;
• concise implementation summary;
• verification scope: representative full pass or named targeted flows;
• evidence directory when the selected scope includes UI flows or durable evidence is requested;
• optional scratch_dir, the caller-provided scratch folder (for example, a per-step Agent Runner folder).

If expected behavior is unavailable, report what is missing instead of inferring the contract from implementation alone. If a selected UI flow has no evidence directory, report the missing input instead of testing that flow without its required screenshot.

Select flows

Size the pass to what changed. Identify the meaningful changed journeys and public surfaces, and keep the inventory proportional to the small change rather than replaying every requirement scenario or input variation. Skip anything an existing automated test already asserts properly; check before assuming it does.

For targeted verification, exercise the named affected flows and obvious direct dependencies. Verify the prior finding first. Do not start a new broad review or search unrelated surfaces for additional issues.

Use typical data, configuration, and roles. Do not fuzz or build an exhaustive edge-case matrix; keep exploration targeted by risk rather than volume. Running the same operation twice is cheap and catches a large share of real defects.

Before each flow, write down the expected result in specifics. A wrong prediction means the model and the system disagree, and one of them is a defect. Emit actual values rather than pass or fail, since a boolean can only answer the question already thought of.

For a deeper pass on a substantial change, use codagent:prepare-acceptance instead.

Scratch space

Check each candidate location: scratch_dir, the evidence directory, and the report path folder. Consider only locations the caller supplied. Resolve relative paths and symlinks for each candidate and both comparison roots. Get the worktree root with git rev-parse --show-toplevel. Reject any candidate inside the git worktree or the system temp folder. Use the first allowed location in that order. Never use a hard-coded temp path.

When scratch_dir is allowed, put every temporary file, clone, fixture project, seeded data, and server working folder inside it. Leave cleanup of a caller-provided scratch folder to the caller. Otherwise, create a new, unique scratch subfolder under the allowed evidence directory or report path folder. Do not reuse an existing folder. Copy any evidence to be retained out of this folder, then remove only the folder this skill created before the skill ends on any path, including early stops when a defect makes remaining flows unreachable, unsafe, or untrustworthy, and failures.

If no allowed scratch location exists, exercise only flows that need no scratch files, list each skipped flow under untested or blocked flows with the reason, and never create scratch files in the worktree or the system temp folder.

Exercise the public surface

Use the project's normal setup, build, install, seed, and start commands needed to expose the current worktree. Do not run automated unit, integration, or end-to-end suites, linters, Validator, or CI.

• Operate web, mobile, desktop, and terminal UIs through their real interface.
• Call APIs through their documented HTTP, SDK, or CLI surface as a client would.
• Invoke CLIs and libraries through their public commands or APIs.
• Trigger background behavior through its normal entry point and inspect the observable result.

For each selected flow, verify resulting state rather than trusting an agent assertion or successful command exit. Continue through independently testable flows after finding a defect; stop only when the problem makes remaining flows unreachable, unsafe, or untrustworthy.

For any tested UI flow, capture a meaningful stable screenshot under the caller's evidence directory. Capture more than one only when multiple states are necessary to understand the flow. Record what the reviewer should notice and a concise text equivalent. For non-visual surfaces, retain a sanitized request/output excerpt or comparable client-visible evidence.

Report

Return a concise report containing:

• checked-out HEAD as context;
• each selected flow, action, expected result, observed result, and evidence;
• clear defects with reproduction steps and affected flows;
• product, scope, or design ambiguity separated from defects;
• what was deliberately not exercised, and why;
• untested or blocked flows and practical limitations;
• the scratch folder used and, when this skill created it, confirmation that it was removed.

Write the same report to a caller-specified path when requested. Do not create status markers or machine-control files.

Do not fix defects, modify approved artifacts, commit, push, wait for CI, inspect PR state, or claim human acceptance. The caller decides how findings are handled and whether targeted verification is needed after a fix.