MercuryToolbox/docs/superpowers/plans/2026-04-21-toolbox-reading-v2-plan.md

Toolbox Reading V2 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add four new reading-oriented CLI commands that let PowerShell and AI workflows inspect files precisely without dumping whole files.

Architecture: Keep each command as its own crate in the workspace and keep language or file-type heuristics inside focused helpers rather than shared heavyweight parsers. Reuse the existing common CLI contract for stdin behavior, JSON output, and exit codes, while letting each command define small, stable domain-specific JSON payloads.

Tech Stack: Rust stable, lexopt-style manual CLI parsing, shared common crate, regex, serde_json, toml, assert_cmd, and existing workspace verification scripts.

---

Task 1: Manifest And Documentation Wiring

Files:

• Create: docs/superpowers/specs/2026-04-21-toolbox-reading-v2-design.md

• Create: docs/superpowers/plans/2026-04-21-toolbox-reading-v2-plan.md

• Modify: Cargo.toml

• Modify: README.md

• Record the reading-tool batch scope in repo docs.

• Register crates/snip, crates/outline, crates/fileprobe, and crates/chunkcat in the workspace.

• Add any workspace dependencies needed by the four crates.

• Update README command inventory and usage examples.

Task 2: snip

Files:

• Create: crates/snip/Cargo.toml

• Create: crates/snip/src/lib.rs

• Create: crates/snip/src/main.rs

• Create: crates/snip/tests/snip_cli.rs

• Create: fixtures/reading/sample.rs

• Create: fixtures/reading/sample.cs

• Write failing tests for --lines, --around, --symbol, and --help.

• Run targeted snip tests and confirm failure for the new behavior.

• Implement snippet selection, numbered text rendering, and JSON output.

• Add heuristic symbol extraction for Rust and C# plus safe fallback behavior.

• Re-run targeted snip tests until green.

Task 3: outline

Files:

• Create: crates/outline/Cargo.toml

• Create: crates/outline/src/lib.rs

• Create: crates/outline/src/main.rs

• Create: crates/outline/tests/outline_cli.rs

• Create: fixtures/reading/config.json

• Create: fixtures/reading/config.toml

• Create: fixtures/reading/config.yaml

• Write failing tests for Rust/C#/config outline extraction, JSON shape, and --help.

• Run targeted outline tests and confirm failure.

• Implement heuristic outline extraction and depth limiting.

• Re-run targeted outline tests until green.

Task 4: fileprobe

Files:

• Create: crates/fileprobe/Cargo.toml

• Create: crates/fileprobe/src/lib.rs

• Create: crates/fileprobe/src/main.rs

• Create: crates/fileprobe/tests/fileprobe_cli.rs

• Create: fixtures/reading/minified.js

• Create: fixtures/reading/generated.lock

• Create: fixtures/reading/binary.bin

• Write failing tests for text/binary detection, heuristic flags, JSON output, and --help.

• Run targeted fileprobe tests and confirm failure.

• Implement lightweight probing, line stats, and file family heuristics.

• Re-run targeted fileprobe tests until green.

Task 5: chunkcat

Files:

• Create: crates/chunkcat/Cargo.toml

• Create: crates/chunkcat/src/lib.rs

• Create: crates/chunkcat/src/main.rs

• Create: crates/chunkcat/tests/chunkcat_cli.rs

• Write failing tests for chunk inventory, selected chunk rendering, JSON output, and --help.

• Run targeted chunkcat tests and confirm failure.

• Implement deterministic chunk planning and selected chunk extraction.

• Re-run targeted chunkcat tests until green.

Task 6: Final Verification

Files:

• Modify only as required by verification failures

• Run cargo fmt --all.

• Run cargo nextest run --all-targets --all-features.

• Run cargo clippy --all-targets --all-features -- -D warnings -W clippy::pedantic -W clippy::nursery.

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

• Fix any regressions and repeat until the full workspace passes.