134 lines
4.2 KiB
Markdown
134 lines
4.2 KiB
Markdown
# 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:
|