moicle 3.0.1 → 3.0.2

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/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.2",
   "description": "Reusable AI agents, commands, skills, and architecture references for Claude Code",
   "type": "module",
   "main": "dist/index.js",