Jade Feature Template

Use this template for any new Mercury Toolbox feature, command, subcommand, output mode, parser path, generated asset, or cross-tool behavior change. Keep the filled copy close to the work item, then remove sections that truly do not apply before merging.

Header

Feature:
Owner:
Date:
Status: draft | implementing | verifying | ready
Tracking issue or branch:
Affected crates, scripts, and docs:

Intent

User problem:
Primary workflow:
Non-goals:
Compatibility promise:
Rollback or fallback plan:

User-Facing Contract

Write the exact CLI shape before coding.

<command> --help
<command> <subcommand> --help
<command> --json <example-input>
<command> --toon <example-input>

Text output:
JSON schema or fields:
TOON shape:
Exit codes:
Stdin behavior:
Path, glob, and missing-root behavior:
Windows-specific behavior:
Cross-platform behavior:

Codebase Fit

Existing command or helper to mirror:
Shared helper APIs to reuse:
New dependencies: none | list with reason
Feature flags or platform cfgs:
Generated files that must be regenerated:
Packaging or install changes:

Test Plan First

Write the first failing test before implementation.

Red test command:

cargo nextest run -p <crate> --test <test-name> <filter>

Expected failing assertion:
Green command after implementation:
Regression cases:
Parser/help contract cases:
Error-path cases:
Platform-specific cases:

Implementation Checklist

Add or update failing tests first.
Reuse common helpers for shared CLI, path, stdin, format, color, and error behavior.
Keep public Rust APIs documented, including # Errors and # Panics where applicable.
Avoid .unwrap(), .expect(), and panic! in production paths unless a narrow // jade: allow-panic because: <reason> comment is justified beside the call site.
Keep subcommand --help aligned with parser-supported flags.
Preserve literal paths unless a documented glob mode is explicitly requested.
Keep --json, --toon, and --format text|json|toon behavior consistent with the toolbox contract.
Update README or command docs when user-facing behavior changes.
Update docs/ai/toolbox-ai-prompt-notes.json when AI routing, examples, caveats, or command coverage changes.
Regenerate generated AI assets instead of hand-editing them.
Update package/install scripts only when the shipped artifact surface changes.

Jade Verification

Focused loop:

cargo fmt --all --check
cargo nextest run -p <crate> --all-targets --all-features
cargo clippy -p <crate> --all-targets --all-features -- -D warnings -W clippy::pedantic -W clippy::nursery

Docs or generated AI asset loop:

just --summary
pwsh -NoProfile -File .\scripts\check-powershell.ps1
pwsh -NoProfile -File .\scripts\check-ai-prompt.ps1 -Configuration ReleaseFast -SkipBuild
pwsh -NoProfile -File .\scripts\check-ai-skill.ps1 -Configuration ReleaseFast -SkipBuild

Shared behavior or broad refactor loop:

$env:CARGO_INCREMENTAL = '0'
cargo nextest run --workspace --all-targets --all-features --no-fail-fast
Remove-Item Env:\CARGO_INCREMENTAL

Full Jade gate before claiming repository-clean status:

pwsh -NoProfile -File .\scripts\check-jade.ps1

If a hardening gate cannot run on the current machine, use only the specific -Exempt* flag with a non-empty reason. Do not add a CI skip, broad allow, or permanent template bypass.

Review Checklist

The diff is scoped to the feature and does not include unrelated cleanup.
Existing behavior is either preserved or deliberately documented as changed.
Help text, parser support, README/docs, generated AI prompt, and skill catalog agree.
Tests cover success, failure, and format-specific output where relevant.
cargo nextest is the test signal; plain cargo test is not used as the main proof.
Verification commands and outcomes are recorded in the final handoff.
Worktree is clean after commit or intentionally lists follow-up files.

Handoff Notes

What changed:
Tradeoffs:
Verification run:
Known follow-ups:
Commit:

4.2 KiB Raw Blame History