# 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.

```powershell
<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:

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
$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:

```powershell
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: