Five separate layers
Blueprint keeps testing and automatic checks explicit. Each layer has a different job.
| Layer | Purpose |
|---|---|
| Unit test command | Exercises project logic with the stack-native runner |
| Browser test command | Exercises repeatable UI and flow behavior in an automated browser |
| Verify command | Runs the configured typecheck, tests, and build as one local recipe |
| GitHub Actions workflow | Runs that exact Verify recipe for pull requests and default-branch pushes |
| GitHub ruleset | Optionally prevents a merge until the GitHub check passes |
/tests configures unit testing. /browser-tests configures the optional browser harness. /ci configures the Verify command and GitHub Actions. A required ruleset is a separate remote GitHub choice.
Testing is opt-in
Blueprint cannot know the correct runner for every stack, so it does not install one by default. Run $tests in Codex or /tests in Claude Code when the project is ready to make unit tests part of the workflow.
A real test command in the AGENTS.md Commands section turns tests into a gate. Logic-bearing implementation steps must add focused coverage and keep the suite green. UI and integration work still need browser, build, API, or other direct evidence.
If a Verify command already exists, /tests adds the configured test command between typechecking and the build. It never creates CI only because testing was added.
Browser testing is also opt-in
Run $browser-tests in Codex or /browser-tests in Claude Code when the project needs repeatable automated browser checks. The skill reuses an existing runner or defaults to Playwright for compatible JavaScript and TypeScript web or extension projects, adds one smoke flow, and records the exact Browser tests command in AGENTS.md.
That command remains separate from the default Verify and CI recipe. Feature and Implement can add focused coverage, while Check and Continuous Mode can run the harness when behavior needs proof.
One shared Verify recipe
Run $ci in Codex or /ci in Claude Code after onboarding or adoption when you want automatic GitHub checks. The skill detects the real project and combines only checks that already exist, in this order:
- Typecheck
- Tests, when a real runner and command are configured
- Build
Missing checks are omitted. For JavaScript and TypeScript projects, this is usually a package script named verify. Other stacks use their native task runner or a clear combined command.
/onboard or /adopt -> /ci -> Verify locally -> GitHub runs Verify/implement, /complete, /autopilot, and every feature completed by
/continuous use the documented Verify command when it exists. /doctor
reports drift when AGENTS.md, the project command, and the GitHub workflow
disagree.
Existing CI stays intact
/ci inspects existing GitHub workflows and documented external CI before it edits anything. It preserves custom checks, reports overlap, and asks before changing an existing verify.yml. The generated beginner workflow uses the detected runtime, lockfile-safe install command, pull_request, pushes to the detected default branch, and contents: read.
The beginner setup does not add lint, formatting, test runners, local git hooks, coverage thresholds, browser tests, security scans, dependency audits, version matrices, or GitHub rulesets. Existing CI checks in those categories stay intact. The skill also stops before push. A local workflow has no effect on GitHub until you approve publishing it.
Match proof to the work
| Work | Best evidence |
|---|---|
| Parser, validator, formatter, or action | Focused unit test with edge cases |
| Responsive UI or visual component | Production build and browser screenshot |
| Form, navigation, or download flow | Real browser interaction and console check |
| API endpoint | Representative request, response, and error path |
| Repository-wide automated gate | The exact documented Verify command |
Browser evidence
UI and flow checks need direct browser evidence. When AGENTS.md declares a Browser tests command, Check runs it and reviews the resulting evidence. It still uses direct browser observation for claims the harness does not cover, including visual fidelity, browser chrome, and authenticated real-profile behavior.
Avoid false confidence
An empty suite should not report success. A build does not prove a click flow. A screenshot does not prove a validator handles malformed input. CI does not improve weak checks merely by running them remotely. Use the smallest evidence that directly tests the claim.