Skip to content

Expanded CLI 0.0.9 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: Deliver the approved 18-issue release expansion with preserved defaults and verified library/CLI behaviour.

Architecture: Use a shared core protocol context, rich-ext policies/renderables and rich-art image processing. Keep the dependency directions CLI → ext/art → core; a single coordinator owns each Live writer.

Tech Stack: Rust 2021, Rust 1.90 minimum, Cargo, existing Rich rendering primitives, Python release/PTY tools, MkDocs.

Spec: Reviewed design; review findings and resolutions.

Status: design approved by the user's 2026-09-21 “Ok”; implementation plan awaits review and execution-method selection. This supersedes the earlier small-scope implementation plan for additional work only. PR #191 remains the implemented baseline.

Global Constraints

  • Rust 1.90; Rust 2021; unsafe_code = "deny" remains in effect.
  • Read AGENTS.md. Do not edit it. New feature implementations belong in rich-ext or rich-art; only the shared extension seam changes core.
  • Preserve default output byte-for-byte; no required method added to Renderable and no public field added to ConsoleOptions or ImageOptions.
  • Never install Python rich-cli in the Rich 15.0.0 golden-oracle environment.
  • Explicit targets do not read ambient terminal state; legacy paths retain their current detection semantics.
  • Each task includes a failing regression, minimal implementation, focused pass, docs and a reviewable commit.
  • Before each commit: cargo fmt --all --check, cargo clippy --all-targets -- -D warnings, env -u NO_COLOR cargo test. Clearing NO_COLOR is for the baseline test environment, not product behaviour.
  • Baseline: main fbb0887, plus design/review documentation from PR #193. No uncommitted user changes may be discarded.
  • Use an isolated implementation worktree under the using-git-worktrees skill at execution time. Planning has not modified product code.
  • Proposed package cohort: core 0.0.5, ext 0.0.7, art 0.0.7, CLI 0.0.9. Verify registry/tags immediately before versioning; never overwrite an existing release.
  • No tags, registry uploads or new external dependencies without the normal repository gates. Publication remains a separate handoff.

Review Focus

  1. Nested images inside legacy containers must use target capabilities; A2 tests nested Panel/ImageArt under contradictory environment values.
  2. Width/height zero and huge constraint inputs must not panic or emit partial glyphs; A1/B1/B2 pin empty rendering, checked arithmetic and grapheme boundaries.
  3. Live shutdown after a resize or partial writer failure must restore owned state once; D2 tests transitions and failing writes using visible terminal state.
  4. Template aliases and absent parents must not overwrite inputs or make dry-run mutate disk; E2 tests canonical aliases, symlinks and planned creation.
  5. Optional features must not leak logging/image dependencies into lean builds or alter worker settings; C3/F2/G1 check feature trees, lean builds and serial/parallel equivalence.

Workstream plans and ordering

Plan Tasks Prerequisites Issues
A: targets and snapshots A1–A3 baseline #132, #133, #150
B: layout and overflow B1–B2 A1 #134, #149
C: diagnostics and events C1–C3 A3, B2 #136, #146, #151, adapter portion of #10
D: Live regions D1–D2 A3, B2 #145, prerequisite portion of #6
E: batch exports E1–E2 baseline #142, #157
F: image transforms F1–F2 baseline; A2 for combined routing #125, #126, #144, #123, #124
G: integration and release G1–G2 A–F all selected issues

The plans produce working increments. Within A–D, finish prerequisite interfaces before dependents begin. E/F can proceed without waiting for library policy work; all manifest, CLI main/config and demo changes must be integrated serially.

Interface and error rules

Public signatures are defined in the owning task and consumed unchanged by later tasks. New error enums implement Debug, Display and std::error::Error. Preserve typed I/O errors where present; do not unwrap user input or writer operations. Enum additions to existing public image enums require a migration note for callers with exhaustive matches. Internal pub(crate) helpers need no public stability promise. A conflicting implementation discovery must amend the plan before a dependent task uses a different interface.

Completion and evidence

  • [ ] A1–A3, B1–B2, C1–C3, D1–D2, E1–E2, F1–F2 and G1–G2 complete.
  • [ ] Whole-branch independent review completed, findings resolved.
  • [ ] Main-target implementation PR green; docs and real media available in PR/chat.
  • [ ] Record actual scope against #192 and every selected issue; close only proven acceptance, retaining broad residual roadmaps.

Execution-method choice remains open. Native execution keeps tightly coupled API work in one context, with independent whole-branch review at the end. Subagent execution adds a fresh implementation/review gate per task and costs more contexts. Neither choice removes the required tests or final independent review.

Plan self-review — 2026-09-21

Checked all design sections against A1–G2 and all 18 selected issues against the workstream table. Each plan assigns tests to its five review concerns. Resolved missing capability-override/snapshot field types, the zero-target test location, and the fallible Live ID-allocation signature during the self-review. All local plan links resolve; no TODO/TBD markers remain. This is an author plan review, not an independent implementation review or a claim that the proposed APIs exist.