Engineering guidance and executable evidence gates for coding agents and people.
VisionCraft helps you define a change, test it and give reviewers a clear record of what the results support. Use its coding-agent skill, Rust library or CLI with your existing repository, CI and issue tracker.
For an empty-search bug, that might mean reproducing the error, fixing it and checking both empty and ordinary queries. A shared event-format change needs consumer, compatibility and migration checks too. The method scales with the consequences, while keeping a merged fix distinct from a deployed one.
| Component | What it provides |
|---|---|
| Skill | Expectation-driven development, TDD, debugging, architecture decisions and review practices |
| Rust core | Typed plans, evidence verification and deterministic gate decisions; no process or network calls |
| CLI | Explicit command execution, bounded captures and source/evidence freshness checks |
Required missing, failed, stale or incomplete evidence cannot earn a pass. Passing means the declared checks satisfied their policy; it does not establish complete coverage, correctness, security or deployment. No Agentbox installation, agent framework or model subscription is required for the core.
Crates.io · Rust API · VisionFlow estate
Rust 1.88 or later is required. Native execution currently supports Linux with glibc or musl; the deterministic library remains independent of the operating system.
cargo install visioncraft --locked --version 0.3.0
visioncraft --helpFor the pure Rust library without CLI/process dependencies:
[dependencies]
visioncraft = { version = "0.3.0", default-features = false }For a coding agent, install the complete skills/visioncraft/ directory from the
same release using your harness's skill mechanism. Keep its references/ and
assets/ alongside SKILL.md; they contain the actual engineering method.
Create a small Git repository with a real assertion. The input list explicitly includes the files whose bytes the check claims to cover.
mkdir visioncraft-example
cd visioncraft-example
git init -q
printf '12\n' > limit.txt
git add limit.txt
git -c user.name=Example -c user.email=example@example.invalid commit -qm baseline
visioncraft plan init --out quality.json --input limit.txt \
--configuration 'POSIX assertion of configured limit' \
-- sh -c 'test "$(cat limit.txt)" = 12'
visioncraft plan check quality.json --json
visioncraft run quality.json --all --out evidence-1
visioncraft evaluate quality.json --receipts evidence-1 --jsonrun captures execution; evaluate verifies the plan, source and capture hashes,
invocation and exit status. Commands use argument arrays without an implicit
shell; this example explicitly requests sh -c.
Change limit.txt and repeat evaluate: the old receipt no longer satisfies the
input. After intentionally changing scope or configuration, create a new plan
and run directory. Existing output paths are refused.
Include relevant source, lockfiles and configuration in --input. Only environment
variables named through --env are inherited. Set --timeout-ms and
--max-output-bytes; aggregate limits are 1,024 checks, one day of declared
deadlines and one GiB of capture per plan.
Repository/configuration labels are caller declarations, reported as
plan-declared-unverified. To attest current labels, supply a Subject record:
visioncraft evaluate quality.json --receipts evidence-1 \
--current-subject current-subject.json --jsonIts source fields are checked against disk; matching repository/configuration
labels remain caller-attested. A digest written in a label does not verify a
file: include the actual configuration in --input to bind its bytes.
The EDD reference explains how to bind expectations to checks, positive controls, regression tests and independent review requirements.
visioncraft expectations check quality.json --receipts evidence-1 --json
visioncraft gate evaluate quality.json --receipts evidence-1 --jsonBoth assess the entire required gate, including checks not referenced by an expectation. Optional failures stay visible. Actual test or line coverage remains unknown unless an observer supplies it.
For imported findings, VisionCraft uses Sealmap's receipt contract:
sealmap review init findings.json --out finding-receipts.json
# Add actual reproductions and dispositions, preserving the original findings.
sealmap review check finding-receipts.json --json
sealmap review summary finding-receipts.jsonThese checks establish structure and byte identity; an auditor judges whether the observations support the findings.
Deepsec is an optional, independently installed security reviewer with a versioned adapter contract.
# Inspect the resolved plan without running a reviewer.
visioncraft deepsec --diff origin/main --dry-run
# Run the explicitly requested review using already configured local credentials.
visioncraft deepsec --diff origin/main
# Candidate discovery only; SCANNED is not a completed review.
visioncraft deepsec --scan-onlyThe adapter freezes file selection, checks source bytes before and after, and requires fresh analysis evidence. Staged mode refuses differing index and working-tree bytes. Empty exports, refusals, partial reviews and unsupported versions cannot pass. Full mode covers the scanner's pending candidates, not the whole program; historical findings may remain in threshold assessment. See the integration guide for scope, routes and spend controls, and maintenance procedure for qualifying upgrades.
Agentic QE supplies optional test and coverage tools through its own CLI/MCP
surface. Follow its worked integration
and result contract. Inspect and execute generated
tests in the project; keep measured coverage distinct from estimates and retain
insufficient-evidence results.
Reading the skill does not install, authenticate or activate either service.
Keep decisions and diagrams in the project's existing corpus, linked to requirements, inspected commits, governed source paths and release observations. Rendering a diagram does not verify its claims.
See decision guidance, diagram diagnosis, traceability and this project's verified ADRs and diagrams.
The core accepts typed data and supplied bytes. It does not trust an artifact because its filename or claimed hash looks plausible:
use visioncraft::{Artifact, VerifiedArtifacts};
let bytes = b"actual check output\n";
let artifact = Artifact {
path: "attempt/stdout.log".into(),
sha256: visioncraft::sha256(bytes),
};
let mut verified = VerifiedArtifacts::default();
verified.insert(&artifact, bytes)?;
assert!(verified.contains(&artifact));
# Ok::<(), visioncraft::ContractError>(())QualityPlan, ExecutionReceipt and EvaluationContext describe the policy,
observations and verified current inputs. evaluate returns both the aggregate
outcome and individual check/expectation results. See the generated rustdoc and
executable contract tests for complete typed examples.
VisionCraft succeeds the Build with Quality skill developed across DreamLab-AI's estate. The migration guide accounts for every former resource. It remains independently usable.
| Project | Connection |
|---|---|
| VisionFlow | Cross-project architecture, audit records and documentation |
| Sealmap | Shared diagram, review and model-family contracts consumed by VisionCraft |
| Agentbox | Installs a pinned release and canonical skill, supplies host policy and credentials, and routes agents through Jev |
Agentbox's Deepsec adapter projects policy into the same VisionCraft executable; it retains no parallel gate implementation. Ruflo handles coordination and Agentic QE provides direct testing tools. A source pin does not establish live activation. The Agentbox integration reference tracks memory, routing and deployment responsibilities.
The process runner is not a sandbox. Children retain the caller's filesystem
and network authority; environment filtering is not secret isolation. Linux
process groups support cancellation and deadlines, but a deliberately escaping
process or a blocked kernel filesystem call needs host-level containment.
Private capture directories protect ordinary local handling, not a hostile
concurrent filesystem. Keep source-bearing evidence out of public commits.
Linux can recognise exited zombie group members through an unrestricted /proc
view; hidden, unreadable or uncertain state remains non-passing. Native execution
on other platforms returns unsupported before spawning a child. Process-wide
child reapers must not compete with the runner's ownership of its children.
Run cargo test, cargo clippy --all-targets -- -D warnings, cargo fmt --check
and RUSTDOCFLAGS='-D warnings' cargo doc --no-deps. The
implementation contract records acceptance boundaries.
The release review records reproduced counterexamples
and their dispositions.
See evaluation evidence for the bounded comparison; no
measured success-rate improvement is claimed.
MIT OR Apache-2.0. Attributed BeautifulRust material retains its original MIT notice. See provenance, MIT and Apache-2.0.