Implementation Plan: AI-Assisted Rename Command

Branch: 008-ai-rename-command | Date: 2025-11-05 | Spec: specs/008-ai-rename-command/spec.md Input: Feature specification from /specs/008-ai-rename-command/spec.md

Note: This plan grounds the /speckit.plan prompt “Genkit Flow 设计 (Genkit Flow Design)” by detailing how the CLI and Genkit workflow collaborate to deliver structured AI rename suggestions.

Summary

Design and implement a renameFlow Genkit workflow that produces deterministic, JSON-formatted rename suggestions and wire it into a new renamer ai CLI path. The plan covers prompt templating, JSON validation, scope handling parity with existing commands, preview/confirmation UX, ledger integration, and fallback/error flows to keep AI-generated batches auditable and undoable.

Technical Context

Language/Version: Go 1.24 (CLI + Genkit workflow)
Primary Dependencies: spf13/cobra, spf13/pflag, internal traversal/history/output packages, github.com/firebase/genkit/go, OpenAI-compatible provider bridge
Storage: Local filesystem plus append-only .renamer ledger
Testing: go test ./... including flow unit tests for prompt/render/validation, contract + integration tests under tests/
Target Platform: Cross-platform CLI executed from local shells; Genkit workflow runs in-process via Go bindings
Project Type: Single Go CLI project with additional internal AI packages
Performance Goals: Generate rename suggestions for ≤200 files within 30 seconds end-to-end (per SC-001)
Constraints: Preview-first safety, undoable ledger entries, scope parity with existing commands, deterministic JSON responses, offline fallback excluded (network required)
Scale/Scope: Handles hundreds of files per invocation, with potential thousands when batched; assumes human-in-the-loop confirmation

Constitution Check

Preview flow MUST show deterministic rename mappings and require explicit confirmation (Preview-First Safety). ✅ renamer ai reuses preview renderer to display AI suggestions, blocks apply until --yes or interactive confirmation, and supports --dry-run.
Undo strategy MUST describe how the .renamer ledger entry is written and reversed (Persistent Undo Ledger). ✅ Accepted batches append AI metadata (prompt, model, rationale) to ledger entries; undo replays via existing ledger service with no schema break.
Planned rename rules MUST document their inputs, validations, and composing order (Composable Rule Engine). ✅ renameFlow enforces rename suggestion structure (original, suggested), keeps extensions intact, and CLI validates conflicts before applying.
Scope handling MUST cover files vs directories (-d), recursion (-r), and extension filtering via -e without escaping the requested path (Scope-Aware Traversal). ✅ CLI gathers scope using shared traversal component, honoring existing flags before passing filenames to Genkit.
CLI UX plan MUST confirm Cobra usage, flag naming, help text, and automated tests for preview/undo flows (Ergonomic CLI Stewardship). ✅ New ai command extends Cobra root with existing persistent flags, adds prompt/model overrides, and includes contract + integration coverage for preview/apply/undo.

Project Structure

Documentation (this feature)

specs/008-ai-rename-command/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
└── spec.md

Source Code (repository root)

cmd/
├── root.go
├── ai.go                # new Cobra command wiring + RunE
├── list.go
├── replace.go
├── remove.go
└── undo.go

internal/
├── ai/
│   ├── flow/
│   │   ├── rename_flow.go        # Genkit flow definition using Go SDK
│   │   └── prompt.tmpl           # prompt template with rules/formatting
│   ├── client.go                # wraps Genkit invocation + response handling
│   ├── preview.go               # maps RenameSuggestion -> preview rows
│   ├── validation.go            # conflict + filename safety checks
│   └── session.go               # manages user guidance refinements
├── traversal/
├── output/
├── history/
└── ...

tests/
├── contract/
│   └── ai_command_preview_test.go   # ensures JSON contract adherence
├── integration/
│   └── ai_flow_apply_test.go        # preview, confirm, undo happy path
└── fixtures/
    └── ai/
        └── sample_photos/          # test assets for AI rename flows

scripts/
└── smoke-test-ai.sh                 # optional future smoke harness (planned)

Structure Decision: Implement the Genkit renameFlow directly within Go (internal/ai/flow) while reusing shared traversal/output pipelines through the new ai command. Tests mirror existing command coverage with contract and integration suites.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
None	—	—

5.1 KiB Raw Blame History