moicle 3.0.2 → 3.0.3

package/README.md

@@ -16,7 +16,7 @@ A toolkit to bootstrap and accelerate project development with Claude Code throu
 
 - **16 AI Agents** - 6 developer agents + 10 utility agents
 - **4 Commands** - Wizards for bootstrap, brainstorm, documentation, and marketing
-- **10 Skills** - Mode-based, auto-triggered workflows for the full SDLC (feature, bug, review, research, docs, marketing) plus a `/challenge` self-critique nudge
+- **11 Skills** - Mode-based, auto-triggered workflows for the full SDLC (feature, bug, review, research, docs, marketing) plus standalone `/challenge` (self-critique) and `/cleanup` (dead-code/duplicate)
 - **9 Architecture References** - DDD + Hexagonal + stack-specific patterns
 
 
@@ -124,9 +124,9 @@ moicle install --target cursor --project
 | `/brainstorm` | Brainstorm ideas with 6 frameworks |
 | `/doc` | Scan project and generate documentation |
 
-### Skills (10)
+### Skills (11)
 
-Skills are grouped by a `<group>-` prefix. Type `/<group>-` then `Tab` in Claude Code to see all skills in a group. Each skill bundles several related workflows into **modes** chosen at the top of the file — pick a mode (or let Claude pick it from your natural-language phrasing). One skill — `/challenge` — is intentionally standalone (no group, no modes).
+Skills are grouped by a `<group>-` prefix. Type `/<group>-` then `Tab` in Claude Code to see all skills in a group. Each skill bundles several related workflows into **modes** chosen at the top of the file — pick a mode (or let Claude pick it from your natural-language phrasing). Two skills — `/challenge` and `/cleanup` — are intentionally standalone (no group prefix).
 
 **`/feature-*` — Build & Change**
 
@@ -173,6 +173,12 @@ Skills are grouped by a `<group>-` prefix. Type `/<group>-` then `Tab` in Claude
 |-------|-------|-------------|
 | `/challenge` | — | A quick skeptical re-examination of what you just did (or selected code): simpler? duplicated? optimal? edge cases? — reports honest findings without self-congratulating. Lighter than `/review-code` SELF. |
 
+**`/cleanup` — Dead Code & Duplicate** (standalone, no group)
+
+| Skill | Modes | When to use |
+|-------|-------|-------------|
+| `/cleanup` | DEAD-CODE · DUPLICATE | Safely remove dead code / consolidate duplicates. Detects with stack tools, **verifies each hit with grep**, then classifies DELETE (true dead) vs KEEP (reusable utils/scopes/helpers — asks when unsure). Removes per-group with build+test each. |
+
 ### Skill decision matrix
 
 When more than one skill / mode could fit, use this matrix:

package/assets/skills/challenge/SKILL.md

@@ -1,57 +1,92 @@
 ---
 name: challenge
-description: A fast self-critique nudge — re-examine the thing you just did (or the selected/named code) with a skeptical eye and report what could be better, WITHOUT self-congratulating. Lighter than /review-code SELF; it is a single pass, not a full review process. Use when the user says "challenge", "rethink", "check kĩ hơn", "soi lại", "phản biện", "tối ưu chưa", "is this optimal", "double check this", "any duplication", "có lặp code không", "did I overengineer", "second-guess this", "review what you just did".
+description: Pause before committing to the current solution. Challenge your own reasoning, assumptions, and design. Look for a better approach before proceeding.
 ---
 
-# Challenge — Self-Critique Pass
+# Challenge
 
-A short, honest re-examination of the work in scope. The whole point is to **push back on your own output** instead of accepting it. You are the skeptic reviewing your own code, not the author defending it.
+You are no longer defending the current solution.
 
-## What's in scope
+Become its strongest critic.
 
-Pick the target in this order:
+Assume there may be a simpler, safer, or more correct approach.
 
-1. **Selected / named code** — if the user selected lines or named a file/function/change, critique exactly that.
-2. **The change you just made** — otherwise, critique the code you produced or edited most recently in this session (check the working diff if unsure).
+Your goal is not to find flaws at all costs.
 
-If neither is clear, ask one line: "Soi cái gì — thay đổi vừa rồi hay chỗ nào cụ thể?" — then proceed.
+Your goal is to determine whether the current direction is truly the best one.
 
-## The one rule
+---
+
+## Re-evaluate
+
+Ask yourself:
+
+### Did I understand the problem correctly?
+
+- Am I solving the actual problem?
+- Did I silently assume requirements?
+- Did I optimize for something the user never asked for?
+
+---
+
+### Is there a simpler solution?
+
+- Can I delete code instead of adding code?
+- Can an existing abstraction be reused?
+- Am I introducing flexibility that isn't needed?
+
+---
+
+### Am I overengineering?
+
+- Extra layers?
+- Extra configuration?
+- Generic framework for a single use case?
+- Future-proofing without evidence?
+
+---
+
+### What would I do if starting from scratch?
+
+Ignore the current implementation.
+
+Would I build it the same way?
+
+If not, why?
+
+---
 
-> **Do not conclude "it's fine / already optimal" without evidence.** Assume something can be better and go find it. If after a genuine pass nothing real turns up, say so plainly and state what you checked — do not pad with fake concerns, and do not praise the code.
+### What's the weakest assumption?
 
-No sycophancy. No "great job, but…". Just: here is what I'd change and why.
+Identify the assumption most likely to be wrong.
 
-## Pass — run every lens, keep only real hits
+Explain how it could fail.
 
-Go through each lens on the in-scope code. For each, either cite a concrete spot or move on silently.
+---
+
+### Explore one alternative
+
+Briefly describe one different approach.
+
+Do not choose it automatically.
+
+State its main tradeoff.
+
+---
 
-| Lens | Ask |
-|------|-----|
-| **Simpler** | Is there a shorter / more direct way? Am I solving a problem I don't have? Any premature abstraction, needless layer, config, or generality? |
-| **Duplication (DRY)** | Is this logic already implemented elsewhere in the codebase? Did I repeat a block that should be one helper? (Search before claiming "no dup".) |
-| **Optimal** | Redundant work, N+1, re-fetch, re-compute in a loop, unnecessary allocation? Is the data structure the right one? |
-| **Correctness edges** | Null / empty / boundary / large input / concurrent access / partial failure — which path did I not handle? |
-| **Error handling** | Any swallowed error (empty catch, ignored return)? Failures must surface clearly and be logged, not muffled. |
-| **Naming & footprint** | Misleading names? Did I rename/move things I didn't need to? Is any file getting too big / doing too much? |
-| **Tests** | Is the risky path actually covered, or just the happy one? |
+## Decision
 
-## Output
+Finish with one of:
 
-Keep it tight. For each real finding:
+### Keep current approach
 
-```
-⚠️ <one-line problem>  ·  <file:line>
-   → <concrete fix>
-```
+Explain *why* the alternatives are not better.
 
-Then end with exactly one of:
+or
 
-- **Findings exist** → list them worst-first, then ask: "Áp dụng mấy cái này không?" (do not auto-edit).
-- **Genuinely nothing** → "Đã soi <các lens> trên <scope>, không thấy vấn đề thực sự. Điểm cần lưu ý nếu mở rộng sau: <1 dòng, nếu có>." State what you searched so the "clean" verdict is earned, not assumed.
+### Better direction found
 
-## Boundaries
+Explain what should change and why.
 
-- ❌ Full architecture / DDD audit with scoring → use `/review-code` (ARCHITECT mode).
-- ❌ Reviewing a whole PR / branch to post to GitHub → use `/review-code` (PR mode).
-- ❌ Actually implementing the fixes now → this skill *proposes*; apply only after the user says go.
+Never change the code automatically.
+Never fabricate issues.

package/assets/skills/cleanup/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: cleanup
+description: Safely remove dead code and consolidate duplicates. Two modes — DEAD-CODE (remove unreachable/unused code) and DUPLICATE (merge copy-paste into one canonical). Detect with stack-appropriate tools, VERIFY every hit with grep, then classify DELETE (true dead) vs KEEP (reusable utilities/helpers/scopes — never delete on a tool signal alone). Stack-aware. Use when the user says "cleanup", "clean up codebase", "dead code", "remove dead code", "remove unused code", "find unused code", "unused code", "declutter", "tech debt", "duplicate code", "consolidate duplicates", "copy-paste code".
+args: "[MODE]"
+---
+
+# Cleanup Workflow
+
+Remove rot **without deleting things worth keeping**. Tools only propose candidates — grep and judgment decide what actually goes. The classic failure is trusting a dead-code tool blindly and deleting reusable helpers, which turns a "cleanup" into a rejected mess.
+
+## Pick your mode
+
+| Situation | Mode | Jump to |
+|-----------|------|---------|
+| Remove unreachable / unused code | **DEAD-CODE** | [Mode DEAD-CODE](#mode-dead-code) |
+| Consolidate copy-paste into one canonical | **DUPLICATE** | [Mode DUPLICATE](#mode-duplicate) |
+
+Run either, or both in sequence. If scope is unclear, ask one line: *"Whole repo or just `<module>`? Delete directly, or report for review first?"* then proceed.
+
+- ❌ Reformatting / renaming / restructuring working code → use `@refactor`.
+- ❌ Reviewing a branch/PR for quality → use `/review-code`.
+- ❌ A bug surfaced during cleanup → use `/fix-bug`.
+
+## ⛔ Rule #1 — Keep reusable, delete only true dead (both modes)
+
+> A tool reporting "unused / unreachable" is **not enough** to delete. Classify every candidate:
+
+| | **DELETE** (true dead) | **KEEP** (reusable — ask if unsure) |
+|---|---|---|
+| What | Leftover of a removed feature · orphaned unit after a refactor · a real duplicate · an unreachable business flow | Generic utility / formatter / parser / query-scope helper · value-object accessors · intended public API surface · "might need it later" generic code |
+| Tell | Tied to one specific dead feature/flow; deleting it, nobody rebuilds it | General-purpose helper not tied to any feature; deleting it means rewriting it later |
+| Action | Delete | **Keep.** If unsure, list it and ask the user — do not auto-delete |
+
+When torn between the two columns, **default to KEEP and ask**. A leftover helper is cheaper than deleting something the team meant to use.
+
+## Read stack first (both modes)
+
+Detect the stack via `~/.claude/architecture/_shared/stack-detection.md`, then use the matching tools. These only produce *candidates*; install if missing (tell the user).
+
+| Stack | Dead code | Duplicate | Unused deps |
+|---|---|---|---|
+| **Go** | `deadcode -test ./...` (whole-program) + `staticcheck -checks U1000 ./...` (unexported/const/type/field) | `dupl` | `go mod tidy` (diff) |
+| **TS/JS** | `knip` · `ts-prune` | `jscpd` | `depcheck` · `knip` |
+| **Python** | `vulture` | `pylint --enable=duplicate-code` | `deptry` |
+| **Dart/Flutter** | `dart analyze` | `dart_code_metrics` | `dart pub deps` |
+| **Any** | — | — | LSP "no references" / editor find-usages |
+
+> ⚠️ **Multiple entry points** (API + worker + cron/CLI): make **all** of them roots for the whole-program analysis. Otherwise code used only by one entry point is reported dead by mistake.
+
+<a id="mode-dead-code"></a>
+## Mode DEAD-CODE
+
+### 1. Detect
+Run the stack's dead-code tools to get the candidate list.
+
+### 2. Verify each candidate with grep — don't trust the tool
+Confirm **zero real references** before touching anything. Tools miss these cases:
+
+- **Same name in different packages/modules** — a naive count matches the wrong symbol. Confirm the exact definition (path + namespace).
+- **Interface / polymorphism** — several same-named constructors/handlers are separate *implementations of one contract* (one per adapter/driver). That is **not duplication — never merge them**; merging breaks the abstraction.
+- **Reflection / registered-by-name** — event listeners, queue/cron tasks registered by string, ORM callbacks, test-suite methods. Whole-program tools can't see these → false "dead".
+- **Test-only usage** — a helper only tests call: decide by policy (usually keep while tests use it).
+
+### 3. Classify
+Sort each verified candidate into **DELETE · KEEP · ASK · BACKLOG** (BACKLOG = dead but touches security/business semantics → don't decide alone; write it to a doc for the user).
+
+### 4. Remove safely
+1. **One commit per group** (by layer or by file); message states *what* and *why it's dead*.
+2. After each group, clean orphaned imports, then **build + test + lint must stay green**.
+3. Re-run the dead-code tool: removed symbols are gone, and **no new dead code appeared** (if deleting A orphaned B, handle B or stop and reassess).
+4. **Check for orphaned flows**: if you removed a producer, is a listener/handler left dangling? If you removed an enqueue helper, does a scheduler still enqueue that task another way? Confirm the real flow still lives.
+
+### 5. (Optional) Prevent regrowth
+Propose wiring the unused-code check into the project's existing lint/CI so dead code can't silently regrow. Keep any intentional-keep items (BACKLOG) **informational**, not a hard gate.
+
+<a id="mode-duplicate"></a>
+## Mode DUPLICATE
+
+### 1. Detect
+Run the duplicate detector to find copy-paste blocks.
+
+### 2. Confirm it's a REAL duplicate
+Diff the two versions. It's only a duplicate if the **logic and behavior are identical**.
+
+> **Never merge when semantics differ** — e.g. `""→nil` vs `""→pointer-to-empty`, `"1.000"` vs `"1,000"` formatting, two different normalization algorithms. Merging changes behavior = a bug. Write it to backlog instead of merging blindly.
+
+### 3. Choose one canonical
+Pick the correct home for the shared version, respecting the project's existing import/dependency direction (a helper used by lower-level code must live where that code can import it). Do **not** create a god `utils` package.
+
+### 4. Redirect and remove
+Point all call sites at the canonical, delete the extra copies, then build + test green.
+
+## Output
+
+```
+## Cleanup: <mode> — <scope>
+
+### Delete (verified 0 refs)
+- <file:symbol> — <why dead: leftover / orphan / true duplicate>
+
+### Keep (reusable — untouched)
+- <file:symbol> — <why kept>
+
+### Ask
+- <file:symbol> — dead, but <reason for doubt>
+
+### Backlog (dead, touches security/business)
+- <file:symbol> — <decision needed>
+
+### Verify: build ✅ · test ✅ · tool before→after: N → M
+```
+
+If deleting: one commit per group; do **not** commit / push / open a PR unless the user asks.
+
+## Boundaries
+
+- ❌ Do not delete a reusable helper/scope/utility just because a tool flags it unused → **KEEP or ASK**.
+- ❌ Do not merge functions with different semantics, and do not merge same-name interface implementations.
+- ❌ Do not drop DB tables/columns/migrations during cleanup — that needs a separate explicit confirmation.
+- ❌ Do not commit/push/open a PR unless the user explicitly asks.
+- ✅ When in doubt, default to KEEP and ask.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moicle",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "Reusable AI agents, commands, skills, and architecture references for Claude Code",
   "type": "module",
   "main": "dist/index.js",