moicle 3.0.1 → 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/architecture/_shared/read-project-first.md

@@ -0,0 +1,30 @@
+# Read the project first — architecture doc is only a fallback
+
+> **Match the project, not the textbook.** The pattern this repo *already uses* is the source of truth — for planning, coding, reviewing, and generating docs. Follow it, whatever it is (CRUD, MVC, feature-folder, service+repo, layered, script, DDD/hexagonal, or legacy with its own quirks).
+
+## 1. Learn how THIS project actually works
+
+Before planning or writing anything:
+
+1. **Read 1–2 existing modules/features closest to the task, end-to-end.** They tell you the real conventions: folder layout, naming, where business logic lives, where tests go, how things get wired/registered.
+2. **Follow that grain.** Your new code should look like it was written by the same team — same structure, same names, same test style.
+3. **Detect the stack** via `_shared/stack-detection.md` — but only to grab the concrete **build / test / lint commands** and stack idioms, not to decide the architecture.
+
+## 2. When architecture docs apply (fallback only)
+
+Open `~/.claude/architecture/*` (`ddd-architecture.md`, `clean-architecture.md`, `hexagonal-architecture.md`, the stack docs) **only** when one of these is true:
+
+- **(a)** the project **already uses** that pattern (you saw it in step 1), OR
+- **(b)** the task **explicitly asks** to refactor/migrate toward it, OR
+- **(c)** the project is **greenfield** with no pattern to copy yet (then the doc is your default), OR
+- **(d)** you just need the **commands/conventions** for the stack.
+
+## 3. Do NOT impose DDD
+
+Do **not** force DDD/Clean-Arch constructs — entities, value objects, ports, usecases, aggregates, event dispatchers, layer boundaries — onto a project that isn't built that way. That is overengineering: it produces code, plans, reviews, and docs that look foreign to the repo and confuse the team.
+
+- **Planning/building:** mirror the reference module you read, not a layer diagram.
+- **Reviewing:** score consistency with the *codebase's own* architecture, not with a textbook. A CRUD/MVC repo is not "broken architecture" — it just isn't DDD.
+- **Docs:** describe the structure you actually scanned, never a domain/layer skeleton the code doesn't have.
+
+DDD is a target to *opt into*, never a default to assume.

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/assets/skills/docs/sync/SKILL.md

@@ -18,9 +18,9 @@ One skill, two depths: hand-author a single doc, or batch-generate a whole docs
 - ❌ Just need API reference from OpenAPI → use `/feature-build` (API mode), Phase 4
 - ❌ Understand the codebase, not document it → use `/research-explore` (ONBOARDING)
 
-## Read Architecture First (both modes)
+## Read the project first (both modes)
 
-Detect stack via `~/.claude/architecture/_shared/stack-detection.md`. Read `ddd-architecture.md` + the stack doc. Docs must reflect the architecture, not contradict it.
+Detect stack via `~/.claude/architecture/_shared/stack-detection.md`. Then see `~/.claude/architecture/_shared/read-project-first.md`: **docs must describe the architecture the code ACTUALLY has** — derive structure, layers, and flows by scanning the code, never from a DDD template. Read `ddd-architecture.md` only if the project is genuinely DDD.
 
 ---
 ---
@@ -63,7 +63,7 @@ For each doc define: **Purpose** (what problem it solves), **Audience** (new con
 
 **API.md** — auth method + credentials · base URL per env · per endpoint (method, path, request, response, errors, example) · pagination (one block) · error format (one block) · rate limits, versioning
 
-**ARCHITECTURE.md** — one mermaid layer diagram · domain list with 1-line responsibility · cross-domain communication (events) · key tech decisions with rationale · link to `~/.claude/architecture/<stack>.md`
+**ARCHITECTURE.md** — one mermaid diagram of the REAL structure · list of the main parts (modules / features / packages) with 1-line responsibility · how they communicate (events / calls / imports — if applicable) · key tech decisions with rationale · link to `~/.claude/architecture/<stack>.md` (only if the project follows it)
 
 **CONTRIBUTING.md** — local dev setup (≤5 steps) · branch + commit conventions · PR flow + review expectations · test commands + coverage · where to ask for help
 
@@ -110,15 +110,16 @@ Create a resource. Idempotent via `Idempotency-Key` header.
 # Architecture
 ## Overview
 {1-2 paragraphs: what this system does, key constraints}
-## Layers
+## Structure
+{Diagram of the project's ACTUAL structure — layers if it's layered, a module/feature graph otherwise. The example below is layered; replace it with what you scanned.}
 ```mermaid
 graph TD
-  App[Application] --> Domain
-  Domain --> Infra[Infrastructure]
+  A[entry / routes] --> B[business logic]
+  B --> C[data access]
 ```
-See [DDD rules](~/.claude/architecture/ddd-architecture.md) for layer details.
-## Domains
-| Domain | Responsibility |
+Link to `~/.claude/architecture/<stack>.md` only if the project follows that pattern.
+## Main parts
+| Module / feature / package | Responsibility |
 ```
 
 **CONTRIBUTING.md** opener
@@ -218,8 +219,8 @@ docs/
 ### File rules
 - **`docs/README.md`** — index only (≤30 lines): one-line description, link to each sub-doc, last-updated timestamp.
 - **`docs/business.md`** — for non-engineers. NO API endpoints, NO code blocks, NO file paths. Cover: what problem this solves, who uses it, key user journeys (named like a PRD), success metrics. Plain language.
-- **`docs/architecture.md`** — for engineers. Layer diagram (mermaid), domain list, cross-domain communication, tech decisions with rationale, link to `~/.claude/architecture/<stack>.md`.
-- **`docs/use-cases/<name>.md`** — one per flow: trigger (who, what), preconditions, sequence diagram (mermaid `sequenceDiagram`: actor → handler → usecase → infra → response), postconditions / side effects, errors (HTTP code + meaning).
+- **`docs/architecture.md`** — for engineers. Diagram of the real structure (mermaid), the main parts, how they communicate (if applicable), tech decisions with rationale, link to `~/.claude/architecture/<stack>.md` (only if the project follows it).
+- **`docs/use-cases/<name>.md`** — one per flow: trigger (who, what), preconditions, sequence diagram (mermaid `sequenceDiagram` following the steps the code ACTUALLY takes — e.g. MVC: actor → controller → model → DB → response; DDD: actor → handler → usecase → infra → response), postconditions / side effects, errors (HTTP code + meaning).
 - **`docs/api.md`** — only if external API exists. Auth, base URL, error format, pagination → then endpoint table. Deep ref → link to OpenAPI spec.
 - **`docs/runbook.md`** — for ops/on-call: local dev (≤5 commands), deploy steps, common failures + recovery, monitoring dashboards + log queries.
 
@@ -234,7 +235,7 @@ Sequence diagrams for use cases · class diagrams only when ER is non-obvious ·
 For each iteration:
 - **3.1 Structure** — all target files exist · README links resolve · no duplicate content
 - **3.2 Business** — plain language (no `API`/`JSON`/`class`/file paths) · covers all top-level journeys
-- **3.3 Architecture** — layer diagram matches code · every domain has a table row
+- **3.3 Architecture** — diagram matches the code's real structure · every main part (module / feature) has a table row
 - **3.4 Use cases** — one file per identified use case · each has trigger/preconditions/sequence/postconditions/errors · diagrams render
 - **3.5 Consistency** — same terminology everywhere · no nonexistent file paths / endpoints referenced
 
@@ -276,7 +277,7 @@ For each iteration:
 
 | Phase | Agent | Purpose |
 |-------|-------|---------|
-| SCAN | `@clean-architect` | Identify doc needs / domains + patterns |
+| SCAN | `@clean-architect` | Identify doc needs / structure + patterns (any architecture) |
 | ANALYZE / GENERATE (API) | `@api-designer` | API doc structure + accuracy |
 | ANALYZE / GENERATE (DB) | `@db-designer` | Database doc structure + accuracy |
 | GENERATE | `@docs-writer` | Write all docs |

package/assets/skills/feature/build/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: feature-build
-description: Feature lifecycle workflow — build new DDD features, refactor existing code into DDD, add/integrate APIs, or deprecate features. Stack-aware with phase-based checks and a review loop. Use when user says "implement feature", "add feature", "build feature", "create feature", "new feature", "refactor", "clean up", "improve code", "restructure", "migrate to ddd", "refactor ddd", "integrate api", "add endpoint", "new api", "connect api", "api integration", "deprecate", "remove feature", "sunset", "phase out", "delete feature".
+description: Feature lifecycle workflow — build new features in the project's own architecture, refactor existing code (into DDD when asked), add/integrate APIs, or deprecate features. Stack-aware with phase-based checks and a review loop. Use when user says "implement feature", "add feature", "build feature", "create feature", "new feature", "refactor", "clean up", "improve code", "restructure", "migrate to ddd", "refactor ddd", "integrate api", "add endpoint", "new api", "connect api", "api integration", "deprecate", "remove feature", "sunset", "phase out", "delete feature".
 args: "[MODE] [DOMAIN] [FEATURE]"
 ---
 
 # Feature Build Workflow
 
-One skill for the full lifecycle of a feature: **create it, restructure it, expose it via API, or sunset it** — all following DDD layers with rule checks per phase and a review loop.
+One skill for the full lifecycle of a feature: **create it, restructure it, expose it via API, or sunset it** — following the project's own architecture (DDD when it uses DDD), with rule checks per phase and a review loop.
 
 **ARGUMENTS:** `<mode> <domain> <feature>` — `mode` ∈ `new | refactor | api | deprecate`. e.g. `new wallet savings`, `refactor marketing notification`, `api catalog`, `deprecate payments legacy-checkout`.
 
@@ -14,7 +14,7 @@ One skill for the full lifecycle of a feature: **create it, restructure it, expo
 
 | If you are… | Mode | Jump to |
 |-------------|------|---------|
-| Building a brand-new feature across DDD layers | **NEW** | [Mode NEW](#mode-new) |
+| Building a brand-new feature across the project's layers | **NEW** | [Mode NEW](#mode-new) |
 | Restructuring existing code into DDD / fixing drift | **REFACTOR** | [Mode REFACTOR](#mode-refactor) |
 | Adding an endpoint or integrating a third-party API | **API** | [Mode API](#mode-api) |
 | Safely sunsetting a feature / endpoint / module | **DEPRECATE** | [Mode DEPRECATE](#mode-deprecate) |
@@ -23,20 +23,22 @@ One skill for the full lifecycle of a feature: **create it, restructure it, expo
 - ❌ Don't know the right approach yet → `/research-explore` (WEB or SPIKE) first
 - ❌ Multi-step task you want to run as a tracked checklist loop → `/feature-track`
 
-## Read Architecture First (all modes)
+## Read the project first (all modes)
 
-Detect stack via `~/.claude/architecture/_shared/stack-detection.md`. Load `ddd-architecture.md` + the stack doc — extract directory layout, layer rules, forbidden imports, check scripts before any code. Severity definitions live in `~/.claude/architecture/_shared/severity-levels.md`.
+Detect stack via `~/.claude/architecture/_shared/stack-detection.md` for build/lint/test commands, then read a similar existing feature end-to-end to learn how THIS project is built. See `~/.claude/architecture/_shared/read-project-first.md`.
+
+**The phases below are written for DDD-layered projects.** Load `ddd-architecture.md` and follow the DDD scaffolding only when: the project already uses DDD, OR the task explicitly asks to build/refactor toward it, OR it's greenfield and you've chosen DDD. **If the project uses another pattern (CRUD, MVC, feature-folder, service+repo…), do NOT impose DDD — mirror the reference module** and read the layer names below as a mapping to whatever layers the project actually has. Severity definitions: `~/.claude/architecture/_shared/severity-levels.md`.
 
 ---
 ---
 
 # Mode NEW
 
-Build a new feature following DDD layers with rule checks per phase and a final review loop until score ≥ B.
+Build a new feature following the project's architecture, with rule checks per phase and a final review loop. The DDD scaffolding here applies when the project is DDD (or you're going DDD on greenfield) — otherwise mirror the reference module you read.
 
 ## When to use
 
-- ✅ Feature spans multiple DDD layers (domain + app + infra)
+- ✅ Feature spans multiple parts/layers of the project (not a one-liner)
 - ✅ The approach is well-understood (no major research / prototype needed)
 - ✅ You want automated architecture review at the end
 - ❌ Restructuring existing code → use **Mode REFACTOR**
@@ -88,6 +90,7 @@ Present to the user:
 - ...
 
 ### Files to create
+Mirror the reference module's paths + naming. (The example below is DDD; if the project uses another layout, follow that instead.)
 - `domain/wallet/entities/savings_account.go`
 - `domain/wallet/valueobjects/savings_status.go`
 - `domain/wallet/ports/savings_store.go`
@@ -98,7 +101,7 @@ Present to the user:
 ```
 
 ### Gate
-- [ ] Architecture docs read
+- [ ] Project pattern learned from the reference module (DDD docs read only if the project is DDD)
 - [ ] Reference module read end-to-end
 - [ ] Plan presented
 - [ ] **User CONFIRMED** before any code is written
@@ -197,10 +200,11 @@ Build in order: **value objects → entities → events → ports → usecases**
 
 ```
 LOOP:
-  1. /review-code architect {stack} {domain}
+  1. Review the touched code — DDD project: /review-code architect {stack} {domain}
+     · otherwise: /review-code SELF
   2. IF violations severity ≥ MEDIUM:
        fix all → build → tests → GOTO 1
-  3. IF score ≥ B → BREAK
+  3. IF review passes (DDD: score ≥ B) → BREAK
 ```
 
 ## Final Report (NEW)
@@ -498,9 +502,11 @@ paths:
 
 ## Phase 2: IMPLEMENT
 
-**Goal:** implement the contract per stack conventions, respecting DDD layers.
+**Goal:** implement the contract per stack conventions, in whatever layers the project already uses.
 
-### Layered placement (DDD)
+Place each concern where this project's **existing endpoints** put it (you read 1–2 as reference above). The mapping below is the DDD layout — apply it only if the project is DDD; otherwise map each row to the project's real location.
+
+### Layered placement (DDD projects)
 
 | Concern | Layer | Notes |
 |---------|-------|-------|
@@ -535,8 +541,8 @@ GET /resource?cursor=<opaque>&limit=<int 1..100, default 20>
 ### Gate
 - [ ] Routes registered in router / app module
 - [ ] Handler is thin (parse → service → respond)
-- [ ] Business logic in usecase, not handler
-- [ ] External calls go through infrastructure adapter
+- [ ] Business logic not inline in the handler (in whatever layer the project uses — service/usecase)
+- [ ] External calls isolated behind the project's client/adapter pattern
 - [ ] Auth + validation in middleware, not handler
 - [ ] Build passes: `{stack_build_command}`
 
@@ -606,12 +612,12 @@ Create a resource. Idempotent via `Idempotency-Key` header.
 
 ## Review Loop (API)
 
-Run `/review-code architect` for the touched domain. Loop until score ≥ B.
+Review the touched code and loop until it passes. DDD project: `/review-code architect {stack} {domain}` until score ≥ B. Otherwise: `/review-code SELF` until clean.
 
 ```
 LOOP:
-  1. /review-code architect {stack} {domain}
-  2. Fix violations → re-run tests + build → GOTO 1 (until score ≥ B)
+  1. /review-code architect {stack} {domain}  (DDD)  ·  otherwise /review-code SELF
+  2. Fix violations → re-run tests + build → GOTO 1 (until it passes)
 ```
 
 ## Final Report (API)
@@ -683,7 +689,7 @@ IDENTIFY → PLAN → MIGRATE → REMOVE → VERIFY
    {log_query for endpoint hits over last 30/90 days}
    ```
 3. Identify consumers: internal teams / services, external users / SDK consumers, third-party integrations, docs and tutorials that reference it
-4. Assess impact (per architecture layer): which layers reference it, cross-domain consumers, breaking change severity
+4. Assess impact: which parts/modules reference it, cross-module consumers, breaking-change severity
 5. Find replacement (or document "no replacement, here's the workaround")
 
 ### Output
@@ -705,7 +711,7 @@ IDENTIFY → PLAN → MIGRATE → REMOVE → VERIFY
 - Docs referencing it: {list}
 
 ### Impact
-- Layers affected: {domain / application / infra}
+- Areas affected: {modules / layers that reference it}
 - Severity: {breaking / non-breaking}
 - Estimated migration effort per consumer: {hours}
 ```
@@ -858,12 +864,12 @@ class OldWidget { ... }
 - **Read reference / old code first** — your code should look like the rest of the codebase; don't invent logic from variable names.
 - **User confirms the plan / contract** before any code is written.
 - **Phase order is sequential** — Rule Checks gate the next phase; don't skip ahead.
-- **Domain has zero framework imports** — enforce via grep in the domain gate.
-- **Listeners handle side-effects** — never call notifications/SSE/analytics from a usecase.
+- **When the project is DDD: domain has zero framework imports** — enforce via grep in the domain gate.
+- **When the project uses events: listeners handle side-effects** — never call notifications/SSE/analytics from a usecase.
 - **REFACTOR preserves behavior** — never change business logic; all endpoints keep their paths; read old tests so no scenario is lost.
-- **API:** never put business logic in the handler; never call an external API directly from a usecase (go through an adapter implementing a domain port); error codes are stable strings; one pagination style; idempotency key for any state-creating POST.
+- **API:** never put business logic in the handler; never call an external API directly from business logic — go through the project's client/adapter layer (a domain port if DDD); error codes are stable strings; one pagination style; idempotency key for any state-creating POST.
 - **DEPRECATE:** announce before removing; every `@deprecated` has a date + replacement; return 410 not 404; keep removal reversible.
-- **Don't merge with score < B** — fix violations or document the waiver.
+- **Don't merge until the applicable review passes** — DDD: architect score ≥ B; otherwise SELF/PR clean. Fix violations or document the waiver.
 
 ## Related Skills
 

package/assets/skills/feature/track/SKILL.md

@@ -20,12 +20,14 @@ Run a multi-step task as a controlled loop: **brainstorm + plan first, get appro
 - ❌ Single full DDD feature across all layers → use `/feature-build` (NEW mode)
 - ❌ Driving ONE unit test-first with no branch/checklist → use `/review-code` (TDD mode)
 
-## Read Architecture First
+## Read the project first
 
-Detect stack via `~/.claude/architecture/_shared/stack-detection.md`. The stack doc tells you:
+Detect stack via `~/.claude/architecture/_shared/stack-detection.md` for:
 - Test command + test file location convention
 - Build + lint commands (for the VERIFY step)
-- Mocking pattern for ports / dependencies
+- Mocking pattern for dependencies
+
+Then see `~/.claude/architecture/_shared/read-project-first.md`: the checklist and every item's implementation must match the pattern THIS project already uses (read a similar existing feature first) — not an assumed DDD layout.
 
 ---
 
@@ -45,25 +47,62 @@ Detect stack via `~/.claude/architecture/_shared/stack-detection.md`. The stack
 
 ## Phase 0: BRAINSTORM & PLAN
 
-**Goal:** understand the task, pick the simplest viable approach, draft the checklist — and get the user to approve before touching anything.
+**Goal:** understand the task deeply, pick the simplest approach that fits THIS project, decompose it into a high-quality checklist, self-critique the plan, and get the user to approve before touching anything. **A tracked loop is only as good as this plan** — a sloppy Phase 0 makes the whole loop sloppy, so this is where the rigor goes.
+
+> **Fast-path:** for a trivial/obvious task, collapse steps 3 & 5 into one quick pass — don't turn a one-item change into ceremony. The rigor below is for real multi-item tasks.
 
 ### Steps
-1. **Detect stack** — load the matching architecture doc for test/build/lint commands and conventions.
-2. **Understand the task** — read the relevant code/context. If `[TASK_DESCRIPTION]` is ambiguous (scope, acceptance criteria, edge cases), ask to clarify (AskUserQuestion). Don't assume.
-3. **Brainstorm the approach — invoke `/brainstorm`** to generate and compare options for the task (First Principles, SCAMPER, Working Backwards, 5 Whys…), then pick the simplest that works. For a trivial/obvious task a quick single-framework pass is enough — don't overengineer, but don't skip the step.
-4. **Draft the plan** — settle:
-   - the chosen approach,
-   - a proposed branch name (`feat/<slug>`),
-   - the **draft checklist** — each item = one verifiable unit = one test passing + one commit,
-   - files affected + how each item is tested.
-5. **Present the plan and WAIT for approval.** This is the last step of planning. No branch, no code, no `TaskCreate` yet.
+
+1. **Detect stack + read the project.** Get test/build/lint commands (`_shared/stack-detection.md`), then read 1–2 existing features closest to this task **end-to-end**. Write 2–3 lines capturing the *real* conventions (structure, naming, where logic lives, test style, wiring) — this proves you understood the codebase instead of guessing, and it's the pattern every item must match. See `_shared/read-project-first.md`.
+
+2. **Clarify if ambiguous.** If scope, acceptance criteria, or edge cases are unclear, ask (AskUserQuestion) before planning. Don't assume.
+
+3. **Choose the approach — brainstorm ≥2 options.** Invoke `/brainstorm` (First Principles, SCAMPER, Working Backwards, 5 Whys…). Compare options on effort / risk / blast-radius and pick the **simplest that fits the project's existing pattern**. Note in one line why the runner-up lost.
+   - **Unknown too big?** If you can't tell which approach works without building, STOP planning and run `/research-explore` (SPIKE) first, then return. Never commit a checklist around a guess.
+
+4. **Decompose into a checklist — every item must pass this rubric:**
+   - **Vertical slice** — delivers one behavior testable on its own (not "all models" then "all handlers").
+   - **Independently testable** — a single failing test can describe it.
+   - **Right-sized** — one focused commit; needs two unrelated tests → split it; can't stand alone → merge it up.
+   - **Ordered by dependency** — earlier items unblock later ones.
+   - **Matches the project** — files/naming mirror the reference feature from step 1, not a textbook layer.
+
+   Any item failing the rubric → split, merge, or reorder until it passes.
+
+5. **Self-challenge the plan — invoke `/challenge`.** Before showing the user, poke holes: over- or under-engineered? missing an edge case or acceptance criterion? wrong item order? any hidden **DB migration / security / performance** work? imposing structure this codebase doesn't use? Refine, then present.
+
+6. **Present the plan doc and WAIT for approval.** The last planning step — no branch, no code, no `TaskCreate` yet.
+
+```markdown
+## Track Plan: {task}
+
+### Goal + acceptance
+{What "done" means for the whole track — the observable outcome.}
+
+### Project fit (from step 1)
+{The reference feature you read + the conventions each item will follow.}
+
+### Approach
+{Chosen approach} — picked over {runner-up} because {one line}.
+
+### Checklist
+| # | Item (vertical slice) | Test that proves it | Files (match reference) |
+|---|-----------------------|---------------------|-------------------------|
+| 1 | … | … | … |
+| 2 | … | … | … |
+Proposed branch: `feat/<slug>`
+
+### Risks / rollback
+{Edge cases + any DB-migration / security / perf flag to confirm before that item runs.}
+```
 
 ### Gate
-- [ ] Stack detected
+- [ ] Stack detected + reference feature read (project pattern captured in 2–3 lines)
 - [ ] Requirements clear (clarified if they weren't)
-- [ ] Approach brainstormed via `/brainstorm` (simplest viable picked)
-- [ ] Plan + draft checklist presented
-- [ ] **User APPROVED the plan**
+- [ ] ≥2 approaches compared, simplest project-fitting one picked (or SPIKE run for unknowns)
+- [ ] Checklist drafted — **every item passes the rubric**
+- [ ] Plan self-challenged via `/challenge` and refined
+- [ ] Plan doc presented — **User APPROVED**
 
 ---
 
@@ -134,6 +173,7 @@ Branch: `feat/{slug}`
 - **One commit per item** — don't squash steps together, don't push automatically.
 - **DB operations (migrate / seed / drop)** inside any item: **CONFIRM with the user before running — every time, even if a previous item was already confirmed.**
 - **Simple first** — don't overengineer an item.
+- **Match the project** — every item mirrors an existing feature's structure/naming; never impose DDD/layers the codebase doesn't already use (see `~/.claude/architecture/_shared/read-project-first.md`).
 
 ---
 
@@ -142,8 +182,10 @@ Branch: `feat/{slug}`
 | When | Use |
 |------|-----|
 | Need idea frameworks for Phase 0 | `/brainstorm` |
+| Self-critique the plan in Phase 0 | `/challenge` |
+| De-risk an unknown before planning | `/research-explore` (SPIKE mode) |
 | Drive ONE unit deeper test-first | `/review-code` (TDD mode) |
-| Full DDD feature across all layers | `/feature-build` (NEW mode) |
+| Full feature across the project's own layers | `/feature-build` (NEW mode) |
 | Self-review the branch after the loop | `/review-code` (SELF mode) |
 | Urgent prod bug, no checklist | `/fix-bug` (QUICK mode) |
 

package/assets/skills/fix/bug/SKILL.md

@@ -21,9 +21,9 @@ One skill, two depths. Start in **QUICK** when the cause is clear; escalate to *
 - ❌ Bug is on an open PR review → use `/review-code` (ADDRESS mode).
 - ❌ Building a new feature → use `/feature-build` (NEW mode).
 
-## Read Architecture First (both modes)
+## Read the project first (both modes)
 
-Read `ddd-architecture.md` + the stack-specific doc — the fix must land in the right layer (usecase / handler / infra) per architecture rules. Severity definitions: `~/.claude/architecture/_shared/severity-levels.md` (incident table). QUICK typically covers P2-P4; P1 → start with `/fix-incident`.
+See `~/.claude/architecture/_shared/read-project-first.md`. Read the code around the bug to learn where a fix like this belongs in THIS project's structure — its own layers/modules, whatever they are (not an assumed DDD layout). Severity definitions: `~/.claude/architecture/_shared/severity-levels.md` (incident table). QUICK typically covers P2-P4; P1 → start with `/fix-incident`.
 
 ---
 ---
@@ -98,7 +98,7 @@ IDENTIFY → REPRODUCE → FIX → VERIFY → DEPLOY
 
 ### Rules
 - Fix at the **root cause**, not the symptom
-- Land the fix in the right layer (boundary validation → handler/DTO; business rule → usecase; data shape → infra mapper)
+- Land the fix where this codebase already puts that kind of logic — validate at the input/boundary, fix a business rule where the rule lives, fix a data-shape issue at the mapping/adapter step — using whatever the project's layers are named (don't invent DDD layers it doesn't have)
 - **Add a regression test first** (RED), then make it pass (GREEN). See `/review-code` (TDD mode).
 - Don't refactor on the fix — separate PR
 - If the fix requires schema migration, plan it as 2 deploys (compatible code first, then migration)
@@ -108,7 +108,7 @@ For data-shape bugs (null where not expected, type mismatch from external API):
 
 ### Gate
 - [ ] Regression test added (red → green)
-- [ ] Fix is in the right layer (per architecture)
+- [ ] Fix is where this codebase already puts that kind of logic
 - [ ] No unrelated changes in the PR
 - [ ] Existing tests still pass
 
@@ -181,7 +181,7 @@ Document **before** deploying:
 {From Phase 1, 5 Whys final answer}
 
 ### Fix
-- File: `path/to/file:line`  · Layer: {handler / usecase / infra}
+- File: `path/to/file:line`  · Where: {file/module + its role in the project's own structure}
 - Approach: {boundary defense / logic correction / data migration}
 
 ### Tests
@@ -356,7 +356,7 @@ Only after Step 4 is answered. The fix MUST:
 - Be defensive at **trust boundaries** (cache, DB, external API, user input) — NOT in internal logic
 - Handle the specific edge case found, without breaking the normal path
 - Be small + reviewable
-- Land in the correct layer (per `~/.claude/architecture/ddd-architecture.md`)
+- Land where this codebase puts that kind of logic — match the surrounding module, not a textbook layer (see `_shared/read-project-first.md`)
 
 ### Boundary defense pattern
 For data-shape bugs from external sources: validate / coerce at the adapter, not inside business logic.
@@ -400,7 +400,7 @@ For data-shape bugs from external sources: validate / coerce at the adapter, not
 {Cache / DB / Concurrency / Runtime / Env / Multi-tenant — or "none"}
 
 ### Fix
-- File: `path/to/file:line`  · Layer: {handler / usecase / infra adapter}
+- File: `path/to/file:line`  · Where: {file/module + its role in the project's own structure}
 - Approach: {boundary defense / type coercion / locking / cache invalidation / etc.}
 - Why this is root-cause, not symptom: {explanation}
 

package/assets/skills/fix/incident/SKILL.md

@@ -26,12 +26,11 @@ TRIAGE → INVESTIGATE → MITIGATE → RESOLVE → POSTMORTEM
  comms      comms        comms      comms      learn
 ```
 
-## Read Architecture First
+## Read the affected service first
 
-Before responding:
-1. `~/.claude/architecture/ddd-architecture.md`
-2. Stack-specific doc for the affected service
-3. Runbook for the affected component (`docs/runbooks/` or wiki)
+See `~/.claude/architecture/_shared/read-project-first.md`. Mid-incident, skip architecture theory — you only need what helps you mitigate fast:
+1. Stack-specific doc for the affected service (commands + conventions, if unfamiliar)
+2. Runbook for the affected component (`docs/runbooks/` or wiki)
 
 ## Severity
 

package/assets/skills/research/explore/SKILL.md

@@ -22,9 +22,9 @@ One skill for the three ways to reduce the unknown: read the web, build a throwa
 - ❌ Debugging a known bug → `/fix-bug` (DEEP mode)
 - ❌ Generate a full docs site → `/docs-sync`
 
-## Read Architecture First (all modes)
+## Read the project first (all modes)
 
-Detect stack via `~/.claude/architecture/_shared/stack-detection.md`. Read `ddd-architecture.md` + the stack doc — architecture context speeds up everything below.
+Detect stack via `~/.claude/architecture/_shared/stack-detection.md` for commands. Then see `~/.claude/architecture/_shared/read-project-first.md`: let the codebase reveal its own pattern — don't preload a DDD lens. (WEB only needs the stack to filter queries; ONBOARDING's whole job is to discover the *real* pattern, so preloading DDD works against it.)
 
 ---
 ---
@@ -67,7 +67,7 @@ IDENTIFY → DETECT STACK → SEARCH → SYNTHESIZE → PROPOSE
 
 ## Step 2: DETECT STACK
 
-Capture for filter use: language + version, framework + version, architecture pattern (DDD / hexagonal), hard constraints (license, runtime, infra).
+Capture for filter use: language + version, framework + version, architecture pattern (whatever it is — MVC, CRUD, feature-folder, layered, DDD/hexagonal…), hard constraints (license, runtime, infra).
 
 ## Step 3: SEARCH
 
@@ -191,7 +191,7 @@ Lock the question, success criteria, timebox. Without these the spike has no exi
 ### Timebox
 - Quick: 2-4h · Standard: 1-2d · Deep: 3-5d (rare — scope likely too big)
 ### Red flags (stop early if hit)
-- Scope creep into productionising · Option breaks architecture rules · Options converge after 1h
+- Scope creep into productionising · Option breaks the project's existing constraints/conventions · Options converge after 1h
 ```
 
 ### Gate
@@ -229,7 +229,7 @@ Build the smallest thing that answers the question.
 |-----------|----------|----------|-------|
 | Success criterion 1 (latency) | 42ms ✅ | 87ms ❌ | A at 1k rps |
 | Success criterion 2 (effort) | 1 sprint | 3 sprints | B needs new dep |
-| Fit with architecture | ✅ | ⚠️ port redesign | |
+| Fit with existing architecture | ✅ | ⚠️ needs structural change | |
 | Risk | low | medium | |
 
 ### ADR template
@@ -303,14 +303,14 @@ git shortlog -sn --since=3months | head -10
 ### Read in this order
 1. `README.md` — purpose + setup
 2. `ARCHITECTURE.md` / `CONTRIBUTING.md` if present
-3. **One existing module end-to-end** — smallest with a full layer stack. Trace: entity → port → usecase → handler → test.
-4. Cross-domain wiring (event bus / DI / router registration)
+3. **One existing module end-to-end** — the smallest representative one. Trace it through whatever layers the project *actually* has (e.g. MVC: route → controller → model → view → test; feature-folder: the feature's own files; DDD: entity → port → usecase → handler → test).
+4. How the pieces are wired together (router / DI / event bus registration, imports — however this project connects things)
 5. CI config (`.github/workflows/`, `Makefile`) — what's enforced?
 
 **Capture:** architecture pattern, naming conventions, where business logic lives, how errors are returned, test framework + folder convention, how code reaches prod.
 
 ### Gate
-- [ ] One module read end-to-end · Layer boundaries understood · Test + CI conventions known
+- [ ] One module read end-to-end · The project's actual structure understood (layers if it has any) · Test + CI conventions known
 
 ## Phase 3: EXPLAIN
 
@@ -323,18 +323,18 @@ Produce a 1-page mental model someone else can read.
 ### Stack
 - Language / Framework / DB / Infra
 ### Architecture
-{1 sentence: e.g., "DDD with hexagonal — domain-pure, infra implements ports"}
-{ascii or mermaid: top-level layer diagram}
-### Domains
-| Domain | Responsibility |
+{1 sentence describing the REAL pattern you saw — e.g. "MVC: fat models, thin controllers" / "feature-folders, hooks + services" / "DDD hexagonal — domain-pure, infra implements ports"}
+{ascii or mermaid: diagram of the project's actual structure}
+### Main parts
+| Module / feature / package | Responsibility |
 ### Where to find things
-| If you need to... | Look in |
-|-------------------|---------|
-| Add a route | `application/ports/http/<domain>_handler` |
-| Add business logic | `domain/<domain>/usecases` |
-| Add a DB query | `infrastructure/database/<domain>_store` |
-| Add a domain event | `domain/<domain>/events` + register in event bus |
-| Add a test | `*_test.go` next to the source file |
+Fill "Look in" from the REAL paths you found — these rows are prompts, not a required layout.
+| If you need to... | Look in (this project) |
+|-------------------|------------------------|
+| Add a route / endpoint | `{where routes actually live}` |
+| Add business logic | `{where this project puts logic — service / model / usecase…}` |
+| Add a DB query | `{where data access lives}` |
+| Add a test | `{project's test location + naming}` |
 ### Conventions
 - Error handling / Logging / Config / Branch + commit
 ### Gotchas
@@ -349,7 +349,7 @@ Produce a 1-page mental model someone else can read.
 Unblock the first real change. Pick a "quick win" (≤30 min, one layer, clear success criterion).
 
 - [ ] Local env runs: build + lint + tests all green from a fresh clone
-- [ ] Made the change in the right layer (per Phase 3 table)
+- [ ] Made the change in the right place (per Phase 3 table)
 - [ ] Added or updated 1 test
 - [ ] Followed naming + error-handling conventions
 - [ ] Commit message matches project style (`git log --oneline`)

package/assets/skills/review/code/SKILL.md

@@ -21,16 +21,16 @@ One skill covering the full review surface. Pick the mode that matches your situ
 - ❌ Security-only sweep → use `@security-audit` agent
 - ❌ Bug surfaced by review → use `/fix-bug`
 
-## Read Architecture First (all modes)
+## Read the project first (all modes)
 
-Detect stack via `~/.claude/architecture/_shared/stack-detection.md`. Load `ddd-architecture.md` + the stack doc — extract forbidden imports + conventions before reviewing. Severity definitions: `~/.claude/architecture/_shared/severity-levels.md` (code severity table).
+Detect stack via `~/.claude/architecture/_shared/stack-detection.md` for build/lint/test commands. Then see `~/.claude/architecture/_shared/read-project-first.md`: **review against the pattern the codebase ACTUALLY uses** — read 1–2 existing modules of the same kind and judge the changes for consistency with them. Load `ddd-architecture.md` + its rule set **only when the project is genuinely DDD** (or the task asks to move toward it) — a CRUD/MVC repo is not "non-compliant", it just isn't DDD. Severity definitions: `~/.claude/architecture/_shared/severity-levels.md` (code severity table).
 
 ---
 ---
 
 # Mode SELF
 
-Self-review your branch vs a base branch before pushing or opening a PR. Checks architecture compliance, stack conventions, and code quality — on **changed files only**, not the whole codebase.
+Self-review your branch vs a base branch before pushing or opening a PR. Checks consistency with the codebase's existing architecture, stack conventions, and code quality — on **changed files only**, not the whole codebase.
 
 **ARGUMENTS:** (optional) base branch. Default: `main` (fallback to `master`).
 
@@ -42,8 +42,9 @@ Self-review your branch vs a base branch before pushing or opening a PR. Checks
 
 ## Phase 0: DETECT
 - [ ] Stack detected (ask user if ambiguous, e.g., monorepo)
-- [ ] Architecture doc loaded
-- [ ] Forbidden-imports list extracted
+- [ ] Read ≥1 existing module of the same kind — learn the project's real pattern
+- [ ] Build / lint / test commands known
+- [ ] (If the project is DDD) forbidden-imports list extracted
 
 ## Phase 1: COLLECT
 
@@ -56,7 +57,7 @@ git diff "$BASE"...HEAD --stat
 git diff "$BASE"...HEAD --name-only --diff-filter=ACMR
 ```
 
-Categorize changed files by layer:
+Categorize changed files by how this repo groups code (feature-folder, MVC, layers…) — the table below is an example for layered/DDD repos, not a required shape:
 
 | Layer | Typical paths |
 |-------|---------------|
@@ -83,6 +84,10 @@ Run the stack's build + typecheck + lint commands. If any fail → mark **CRITIC
 
 ## Phase 3: ARCHITECTURE (changed files only)
 
+> **Gate first — is this project actually DDD/layered?** (Does it have `domain/`, `ports/`, `usecases/`, entities with behavior?)
+> - **No** → skip the D/A/I/M rule tables below. Review one question instead: *do the changed files stay consistent with how this codebase already organizes similar code* — same structure, same place for business logic, same naming, same test style? Flag inconsistencies with the repo, not missing DDD constructs.
+> - **Yes** (or the task is refactor-to-DDD) → run the rule tables below.
+
 ### 3.1 Domain (if changed)
 | # | Rule |
 |---|------|
@@ -253,11 +258,11 @@ gh pr view $PR --comments
 ## Phase 3: REVIEW — 5 dimensions
 
 ### 3.1 Architecture (CRITICAL / HIGH)
-- Domain has zero framework imports; no cross-domain imports
-- Business logic in usecases, not handlers / stores
-- Ports in `ports/` dir; entities raise events on state changes
-- Listeners use background context, not request context
-- **For deep DDD audit:** switch to **Mode ARCHITECT** and link result.
+- Code follows the architecture the rest of the repo already uses — business logic sits where this codebase puts it (service / model / controller / usecase — whatever it uses), not in the wrong place
+- No new cross-module coupling the codebase otherwise avoids
+- Async work uses background context, not request context
+- **If the repo is DDD:** domain has zero framework imports, no cross-domain imports, ports in `ports/`, entities raise events on state changes
+- **For deep DDD audit (DDD repos only):** switch to **Mode ARCHITECT** and link result.
 
 ### 3.2 Security (CRITICAL / HIGH)
 - Input validation at trust boundary (handler / DTO)
@@ -277,7 +282,7 @@ gh pr view $PR --comments
 - Synchronous external API calls have timeouts
 
 ### 3.4 Testing (HIGH / MEDIUM)
-- New business logic has unit tests (usecases, entities, value objects)
+- New business logic has unit tests (whatever unit holds it — usecase / service / model)
 - New endpoints have at least 1 integration test (happy + error)
 - Tests assert on behavior, not implementation
 - Tests don't depend on order, time, or env
@@ -369,6 +374,17 @@ RESOLVE → LOAD RULES → AUTOMATED CHECKS → MANUAL REVIEW → REPORT → FIX
 ### Gate
 - [ ] Architecture file loaded · Domain identified (if scoped)
 
+## Phase 0.5: CONFIRM DDD INTENT (before scoring)
+
+ARCHITECT scores against DDD. First confirm the project is actually *trying* to be DDD — otherwise the A–F score is meaningless: a clean CRUD/MVC app would score **F** for "missing" constructs it was never meant to have.
+
+Check: does the codebase have `domain/` + `ports/` + `usecases/` (or clear equivalents)? Do existing entities carry behavior? Any doc/convention declaring DDD?
+- **Yes** (or the task explicitly asks to audit/refactor toward DDD) → run Phase 1–5, score A–F against DDD rules as written.
+- **No** → **STOP** the DDD scoring. Tell the user: *"This repo isn't DDD — it uses {actual pattern: MVC / feature-folder / CRUD…}. Scoring it against DDD would produce a false F."* Then offer: **(a)** review against the repo's OWN pattern — score internal consistency (do new modules match existing ones in structure / naming / wiring?), **(b)** proceed with the DDD scale anyway (only if there's a real intent to migrate), or **(c)** stop.
+
+### Gate
+- [ ] Project's real architecture identified · DDD intent confirmed OR user picked a path
+
 ## Phase 1: LOAD RULES
 
 Read `ddd-architecture.md` (core) + the stack doc. Extract: DDD directory layout, layer import rules + forbidden imports, hard rules (HR1-HR15), stack-specific check scripts, wiring + test patterns.
@@ -423,7 +439,7 @@ Focus on **architecture structure**, not business correctness. 10 areas:
 | **B** | 0 CRITICAL/HIGH, max 3 MEDIUM |
 | **C** | 0 CRITICAL, max 2 HIGH |
 | **D** | Has CRITICAL or 3+ HIGH |
-| **F** | Multiple CRITICAL — architecture broken |
+| **F** | Multiple CRITICAL — architecture broken *against the project's own DDD goal* (never "isn't DDD"; see Phase 0.5) |
 
 ## Phase 5: FIX LOOP (if user confirms)
 
@@ -485,7 +501,9 @@ Red-Green-Refactor cycle: write failing test → write minimal code to pass →
 ### Gate
 - [ ] All tests still green · No new public API added · Code easier to read
 
-## Test patterns per layer (DDD)
+## Test patterns per layer (example: DDD layering)
+
+If the project isn't DDD, map these rows to the units it actually has (model / service / controller / component…).
 
 | Layer | Test type | Dependencies |
 |-------|-----------|--------------|
@@ -563,7 +581,7 @@ Ambiguous comment ("this feels off")? Ask the reviewer for specifics before gues
 - One concern per commit (`fix(handler): validate input in DTO per #pr-comment-1`)
 - After each batch: run build + lint + tests locally
 - Re-run **Mode SELF** before pushing
-- **Structural change requested** (move logic between layers, add a port) → use `/feature-build` (REFACTOR mode) for that subtree, then come back to respond
+- **Structural change requested** (move logic between the repo's layers, restructure a module) → use `/feature-build` (REFACTOR mode) for that subtree, then come back to respond
 
 ### Gate
 - [ ] All must-fix items addressed · Build + lint + tests green · Self-review clean
@@ -595,7 +613,7 @@ After replying, mark threads resolved. Don't leave dangling threads.
 - **Match severity honestly** — don't grade-inflate to push for a fix; one severity per finding.
 - **Always include "what went well"** in PR reviews — pure-criticism reviews demoralize.
 - **Don't bikeshed style** when the team has a linter — let the tool flag it.
-- **ARCHITECT:** all CRITICAL/HIGH fixed before merge; MEDIUM allowed with explicit waiver; don't skip manual review.
+- **ARCHITECT:** confirm DDD intent (Phase 0.5) before scoring — never grade a non-DDD repo as "broken"; all CRITICAL/HIGH fixed before merge; MEDIUM allowed with explicit waiver; don't skip manual review.
 - **TDD:** RED first always; minimal GREEN; REFACTOR is a phase, not optional; test behavior not implementation; unit tests <100ms.
 - **ADDRESS:** reply to every comment; push back politely with a real reason; one concern per commit.
 
@@ -612,7 +630,7 @@ After replying, mark threads resolved. Don't leave dangling threads.
 
 | Mode / Phase | Agent | Purpose |
 |--------------|-------|---------|
-| SELF/PR Architecture | `@clean-architect` | DDD compliance |
+| SELF/PR Architecture | `@clean-architect` | Consistency with the repo's architecture (DDD compliance if it's a DDD repo) |
 | SELF/PR Security | `@security-audit` | Vulnerability sweep |
 | PR Performance | `@perf-optimizer` | N+1, indexes, slow paths |
 | Quality | `@code-reviewer` | Code smells |

package/package.json

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