# Implementation Plan: Replace Command with Multi-Pattern Support

**Branch**: `002-add-replace-command` | **Date**: 2025-10-29 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/002-add-replace-command/spec.md`

**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.

## Summary

Introduce a `renamer replace` subcommand that accepts multiple literal patterns and replaces them
with a single target string while honoring existing preview → confirm → ledger → undo guarantees.
The feature will extend shared scope flags, reuse traversal/filtering pipelines, and add
automation-friendly validation and help documentation.

## Technical Context

**Language/Version**: Go 1.24  
**Primary Dependencies**: `spf13/cobra`, `spf13/pflag`  
**Storage**: Local filesystem (no persistent database)  
**Testing**: Go `testing` package with CLI integration/contract tests  
**Target Platform**: Cross-platform CLI (Linux, macOS, Windows)  
**Project Type**: Single CLI project  
**Performance Goals**: Complete preview + apply for 100 files within 2 minutes  
**Constraints**: Deterministic previews, reversible ledger entries, conflict detection before apply  
**Scale/Scope**: Handles hundreds of files per invocation; patterns limited to user-provided literals

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- Preview flow MUST show deterministic rename mappings and require explicit confirmation (Preview-First Safety).
- Undo strategy MUST describe how the `.renamer` ledger entry is written and reversed (Persistent Undo Ledger).
- Planned rename rules MUST document their inputs, validations, and composing order (Composable Rule Engine).
- Scope handling MUST cover files vs directories (`-d`), recursion (`-r`), and extension filtering via `-e` without escaping the requested path (Scope-Aware Traversal).
- CLI UX plan MUST confirm Cobra usage, flag naming, help text, and automated tests for preview/undo flows (Ergonomic CLI Stewardship).

**Gate Alignment**:
- Replace command will reuse preview + confirmation pipeline; no direct rename without preview.
- Ledger entries will include replacement mappings to maintain undo guarantees.
- Replacement logic will be implemented as composable rule(s) integrating with existing rename engine.
- Command will rely on shared scope flags (`--path`, `-r`, `-d`, `--hidden`, `-e`) to avoid divergence.
- Cobra command structure and automated tests will cover help/validation/undo parity.

## Project Structure

### Documentation (this feature)

```text
specs/002-add-replace-command/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
└── tasks.md
```

### Source Code (repository root)

```text
cmd/
├── root.go
└── list.go (existing CLI commands; replace command will be added here or alongside)

internal/
├── listing/
├── output/
├── traversal/
└── (new replace-specific packages under internal/replace/)

scripts/
└── smoke-test-list.sh

tests/
├── contract/
├── integration/
└── fixtures/

docs/
└── cli-flags.md
```

**Structure Decision**: Single CLI repository with commands under `cmd/` and reusable logic under
`internal/`. Replace-specific logic will live in `internal/replace/` (request parsing, rule engine,
summary). CLI command wiring will reside in `cmd/replace.go`. Tests will follow existing
contract/integration directories.

## Complexity Tracking

No constitution gate violations identified; additional complexity justification not required.