Project Implementation Plan

You are an expert software engineer. Implement the following project carefully, with minimal errors, following the plan, stack, and standards below. Ask clarifying questions only if truly necessary; otherwise proceed.

1. Project Overview

• Name: rubiks-cube-3x3-solver
• Description: rubiks cube 3x3 solver
• Type: cli
• Audience: developers
• Scale: small
• Created: 2026-10-25T18:57:35.937546439+00:00

2. Requirements

• project_type: cli
• database: none
• auth: none
• deployment: local
• scale: small
• feature: rubiks cube 3x3 solver

3. Chosen Stack

• Language: Rust
• Libraries: clap, rand, criterion, proptest
• Rationale: Rust chosen for cli project (scale: small).

4. Libraries (details)

• clap (rust, cli): Command-line argument parsing — derive macros
• rand (rust, general): Recommended by corpus
• criterion (rust, general): Recommended by corpus
• proptest (rust, general): Recommended by corpus

5. Architecture

Single binary CLI. Flow: main -> cli (clap) -> command dispatch -> domain logic -> io. Modules: main, cli, config, manifest, pack, hub, update, error, io. Use anyhow at boundaries, thiserror in library code. Keep main thin; all logic in lib/testable modules.

6. Suggested File Structure

• Cargo.toml
• src/main.rs
• src/lib.rs
• src/cube.rs
• src/moves.rs
• src/solver.rs
• src/scramble.rs
• src/notation.rs
• tests/cube.rs
• tests/solver.rs
• benches/solver.rs
• README.md

7. Feature Plan

• rubiks cube 3x3 solver

8. Implementation Plan (Milestones)

M0: Setup — Scaffold

• [ ] M0-1 Scaffold crate: cargo init, fmt, clippy, tests

M1: Cube model — State + moves

• [ ] M1-1 Cube state representation: 54-sticker or 20-cubie model with invariants
• [ ] M1-2 Move generation: U/D/L/R/F/B + inverses, undo support (depends on: M1-1)

M2: Solver — Search algorithm

• [ ] M2-1 Heuristic: Admissible heuristic (Manhattan/corner) (depends on: M1-2)
• [ ] M2-2 IDA* search: Depth-first iterative deepening (depends on: M2-1)
• [ ] M2-3 Validation: Parity/invariant checks, known-answer tests (depends on: M2-2)

M3: CLI — Commands

• [ ] M3-1 solve command: Parse scramble, solve, print moves (depends on: M2-3)
• [ ] M3-2 scramble command: Generate random valid scramble (depends on: M3-1)

M-Final: Polish — Docs/tests/release

• [ ] MF-1 Docs & benchmarks: README, criterion benches

9. Coding Standards

• Use strict typing; avoid any/unwrap in production paths.
• Handle errors explicitly; no silent failures.
• Add unit tests for core logic; integration tests for boundaries.
• Keep functions small; single responsibility.
• Document public API.
• Run cargo fmt, clippy; fix all warnings.
• Prefer anyhow for app errors, thiserror for library errors.

10. Risks & Mitigations

• Incorrect state representation causing illegal cubes to solve
• Heuristic not admissible → wrong shortest path
• Solver performance/termination
• Notation parsing ambiguity
• No input validation

Common Pitfalls

• Cubie vs sticker confusion; track orientation
• Move application order
• Parity/invariant checks missing
• Integer overflow in depth counters
• Forgetting inverse move tests

11. Template Used

• cli-tool

Language Guidance

Rust Project Guidance

Project Layout

• Prefer a workspace for multi-crate projects.
• Binary crate: src/main.rs thin; logic in src/lib.rs or modules.
• Library crate: src/lib.rs public API; internal modules private.
• Tests: tests/ integration; unit tests co-located.

Error Handling

• Libraries: define enum Error with thiserror.
• Applications: use anyhow::Result at boundaries.
• Avoid unwrap()/expect() in production.

Design Patterns

• Newtype, Builder, trait objects, From/Into, Default, enum state machines, RAII/Drop, interior mutability.

Async

• Use tokio; avoid blocking in async; use spawn_blocking; channels for message passing.

Testing

• Unit + integration; property tests with proptest.

Tooling

• cargo fmt, clippy, test, doc, audit, deny.

Common Crates

• CLI: clap, dialoguer, indicatif, console, tracing.
• Web: axum, actix-web, reqwest, tower, tower-http.
• DB: sqlx, diesel, sea-orm.
• Errors: thiserror, anyhow, miette.
• Testing: proptest, mockall, wiremock, assert_cmd.

Domain

• algorithmic

Domain Guidance

Algorithmic Problem Domain

Approach

• Model the problem state explicitly (structs/enums), separate from I/O.
• Define invariants and validate inputs before solving.
• Choose algorithm by constraints: brute force (small), BFS/DFS, IDA*, A*, dynamic programming, greedy, heuristic search.
• Provide a reference/naive implementation for correctness checking.
• Benchmark with criterion; profile before optimizing.

Common Patterns

• State-space search with visited set and pruning.
• Backtracking with constraint propagation.
• Memoization / DP tables.
• Bitmask representations for small state spaces.
• Move generation + undo (for puzzles/games).

Testing

• Unit tests for move/invariant correctness.
• Property tests (proptest) for round-trip moves.
• Known-answer tests (Kociemba, IDA* expected lengths).
• Fuzz input parsing.

Pitfalls

• Off-by-one in move indexing.
• Forgetting parity/invariant checks (illegal states "solve").
• Heuristic not admissible → wrong shortest path.
• State representation mismatch (cubie vs sticker).
• Overflow in depth/counters.
• Non-deterministic ordering breaking reproducibility.

Libraries (Rust)

• (none required) pure std; optional: rand (scrambles), criterion (bench), proptest (tests). "

Final Instructions to the LLM

1. Follow the milestones in order; do not skip setup.
2. Use ONLY the chosen stack and libraries unless a strong reason exists; explain deviations.
3. Produce complete, runnable code for each file in the suggested structure.
4. Include tests for core logic.
5. Handle errors and edge cases; no panics in production paths.
6. End with a short summary of what was implemented and how to run it.