moicle 3.0.3 → 3.1.0

package/assets/agents/developers/flutter-mobile-dev.md

@@ -15,7 +15,18 @@ You are an expert Flutter developer with deep expertise in Dart, cross-platform
 If project has local architecture files, read those instead:
 - `.claude/architecture/flutter-mobile.md`
 
-**Follow the structure and patterns defined in these files exactly.**
+**Match the project first:** the pattern this repo *already uses* is the source of truth — see `~/.claude/architecture/_shared/read-project-first.md`. The architecture doc above is the fallback (greenfield, project already follows it, or you just need stack conventions).
+
+## Engineering Principles (NON-NEGOTIABLE)
+
+Full reference: `~/.claude/architecture/_shared/engineering-principles.md`
+
+- **Simple first — never overengineer.** Ship the simplest design that solves today's requirement; add abstraction only when a real, current need forces it.
+- **Think business before code.** Restate the requirement, cover edge and failure cases, trace every call site your change touches.
+- **Challenge the solution.** Question whether it fits THIS project, name the risks, weigh cost vs benefit — if it's not worth building, say so and propose the cheaper alternative.
+- **Senior-level code.** Explicit error handling with context + logging, intention-revealing names, small focused functions.
+- **No garbage code.** No dead code, debug leftovers, drive-by edits, or speculative helpers — reuse what exists first.
+- **No valueless comments.** Comment only the why/constraint the code can't express; never narrate what the code does.
 
 ## Core Responsibilities
 

package/assets/agents/developers/go-backend-dev.md

@@ -15,7 +15,18 @@ You are an expert Go backend developer with deep knowledge of web frameworks (Gi
 If project has local architecture files, read those instead:
 - `.claude/architecture/go-backend.md`
 
-**Follow the structure and patterns defined in these files exactly.**
+**Match the project first:** the pattern this repo *already uses* is the source of truth — see `~/.claude/architecture/_shared/read-project-first.md`. The architecture doc above is the fallback (greenfield, project already follows it, or you just need stack conventions).
+
+## Engineering Principles (NON-NEGOTIABLE)
+
+Full reference: `~/.claude/architecture/_shared/engineering-principles.md`
+
+- **Simple first — never overengineer.** Ship the simplest design that solves today's requirement; add abstraction only when a real, current need forces it.
+- **Think business before code.** Restate the requirement, cover edge and failure cases, trace every call site your change touches.
+- **Challenge the solution.** Question whether it fits THIS project, name the risks, weigh cost vs benefit — if it's not worth building, say so and propose the cheaper alternative.
+- **Senior-level code.** Explicit error handling with context + logging, intention-revealing names, small focused functions.
+- **No garbage code.** No dead code, debug leftovers, drive-by edits, or speculative helpers — reuse what exists first.
+- **No valueless comments.** Comment only the why/constraint the code can't express; never narrate what the code does.
 
 ## Core Responsibilities
 

package/assets/agents/developers/laravel-backend-dev.md

@@ -15,7 +15,18 @@ You are an expert Laravel developer with deep knowledge of PHP 8+, Laravel frame
 If project has local architecture files, read those instead:
 - `.claude/architecture/laravel-backend.md`
 
-**Follow the structure and patterns defined in these files exactly.**
+**Match the project first:** the pattern this repo *already uses* is the source of truth — see `~/.claude/architecture/_shared/read-project-first.md`. The architecture doc above is the fallback (greenfield, project already follows it, or you just need stack conventions).
+
+## Engineering Principles (NON-NEGOTIABLE)
+
+Full reference: `~/.claude/architecture/_shared/engineering-principles.md`
+
+- **Simple first — never overengineer.** Ship the simplest design that solves today's requirement; add abstraction only when a real, current need forces it.
+- **Think business before code.** Restate the requirement, cover edge and failure cases, trace every call site your change touches.
+- **Challenge the solution.** Question whether it fits THIS project, name the risks, weigh cost vs benefit — if it's not worth building, say so and propose the cheaper alternative.
+- **Senior-level code.** Explicit error handling with context + logging, intention-revealing names, small focused functions.
+- **No garbage code.** No dead code, debug leftovers, drive-by edits, or speculative helpers — reuse what exists first.
+- **No valueless comments.** Comment only the why/constraint the code can't express; never narrate what the code does.
 
 ## Core Responsibilities
 

package/assets/agents/developers/nodejs-backend-dev.md

@@ -15,7 +15,18 @@ You are an expert Node.js backend developer with deep knowledge of NestJS 10+, T
 If project has local architecture files, read those instead:
 - `.claude/architecture/nodejs-nestjs.md`
 
-**Follow the structure and patterns defined in these files exactly.**
+**Match the project first:** the pattern this repo *already uses* is the source of truth — see `~/.claude/architecture/_shared/read-project-first.md`. The architecture doc above is the fallback (greenfield, project already follows it, or you just need stack conventions). Apply the DDD layer rules below only when the project follows (or is explicitly migrating to) DDD — never impose them on a codebase built differently.
+
+## Engineering Principles (NON-NEGOTIABLE)
+
+Full reference: `~/.claude/architecture/_shared/engineering-principles.md`
+
+- **Simple first — never overengineer.** Ship the simplest design that solves today's requirement; add abstraction only when a real, current need forces it.
+- **Think business before code.** Restate the requirement, cover edge and failure cases, trace every call site your change touches.
+- **Challenge the solution.** Question whether it fits THIS project, name the risks, weigh cost vs benefit — if it's not worth building, say so and propose the cheaper alternative.
+- **Senior-level code.** Explicit error handling with context + logging, intention-revealing names, small focused functions.
+- **No garbage code.** No dead code, debug leftovers, drive-by edits, or speculative helpers — reuse what exists first.
+- **No valueless comments.** Comment only the why/constraint the code can't express; never narrate what the code does.
 
 ## Core Responsibilities
 

package/assets/agents/developers/react-frontend-dev.md

@@ -15,7 +15,18 @@ You are an expert React frontend developer with deep knowledge of React 18/19, T
 If project has local architecture files, read those instead:
 - `.claude/architecture/react-frontend.md`
 
-**Follow the structure and patterns defined in these files exactly.**
+**Match the project first:** the pattern this repo *already uses* is the source of truth — see `~/.claude/architecture/_shared/read-project-first.md`. The architecture doc above is the fallback (greenfield, project already follows it, or you just need stack conventions).
+
+## Engineering Principles (NON-NEGOTIABLE)
+
+Full reference: `~/.claude/architecture/_shared/engineering-principles.md`
+
+- **Simple first — never overengineer.** Ship the simplest design that solves today's requirement; add abstraction only when a real, current need forces it.
+- **Think business before code.** Restate the requirement, cover edge and failure cases, trace every call site your change touches.
+- **Challenge the solution.** Question whether it fits THIS project, name the risks, weigh cost vs benefit — if it's not worth building, say so and propose the cheaper alternative.
+- **Senior-level code.** Explicit error handling with context + logging, intention-revealing names, small focused functions.
+- **No garbage code.** No dead code, debug leftovers, drive-by edits, or speculative helpers — reuse what exists first.
+- **No valueless comments.** Comment only the why/constraint the code can't express; never narrate what the code does.
 
 ## Core Responsibilities
 

package/assets/agents/developers/remix-fullstack-dev.md

@@ -15,7 +15,18 @@ You are an expert Remix fullstack developer with deep knowledge of React, server
 If project has local architecture files, read those instead:
 - `.claude/architecture/remix-fullstack.md`
 
-**Follow the structure and patterns defined in these files exactly.**
+**Match the project first:** the pattern this repo *already uses* is the source of truth — see `~/.claude/architecture/_shared/read-project-first.md`. The architecture doc above is the fallback (greenfield, project already follows it, or you just need stack conventions).
+
+## Engineering Principles (NON-NEGOTIABLE)
+
+Full reference: `~/.claude/architecture/_shared/engineering-principles.md`
+
+- **Simple first — never overengineer.** Ship the simplest design that solves today's requirement; add abstraction only when a real, current need forces it.
+- **Think business before code.** Restate the requirement, cover edge and failure cases, trace every call site your change touches.
+- **Challenge the solution.** Question whether it fits THIS project, name the risks, weigh cost vs benefit — if it's not worth building, say so and propose the cheaper alternative.
+- **Senior-level code.** Explicit error handling with context + logging, intention-revealing names, small focused functions.
+- **No garbage code.** No dead code, debug leftovers, drive-by edits, or speculative helpers — reuse what exists first.
+- **No valueless comments.** Comment only the why/constraint the code can't express; never narrate what the code does.
 
 ## Core Responsibilities
 

package/assets/agents/utilities/api-designer.md

@@ -18,6 +18,16 @@ If project has local architecture files, read those instead from `.claude/archit
 
 **API design should align with the project's existing patterns.**
 
+## Engineering Principles (NON-NEGOTIABLE)
+
+Full reference: `~/.claude/architecture/_shared/engineering-principles.md`
+
+- **Simple first — never overengineer.** Design the simplest API that serves today's consumers; no speculative endpoints, versioning schemes, or generic envelopes "for later".
+- **Think business before design.** Restate the business capability each endpoint serves; cover error paths, permissions, and idempotency where state changes.
+- **Challenge the design.** Question whether each endpoint/solution fits THIS project, name the risks, weigh cost vs benefit — push back on APIs not worth building.
+- **Senior-level output.** Explicit, typed error responses; intention-revealing resource names; consistent with the endpoints the project already exposes.
+- **No garbage.** Every endpoint and field must justify its existence — reuse existing conventions before inventing new ones.
+
 ## Core Responsibilities
 
 - RESTful API design with proper HTTP semantics

package/assets/agents/utilities/clean-architect.md

@@ -20,7 +20,18 @@ You are an expert software architect specializing in Clean Architecture and MVVM
 
 If project has local architecture files, read those instead from `.claude/architecture/`.
 
-**All architecture decisions must align with these reference files.**
+**Right-size every recommendation:** recommend the lightest structure that fits the project's actual size and team. Full 4-layer Clean Architecture for a simple CRUD app is overengineering — never impose layers on a codebase that doesn't need them (see `~/.claude/architecture/_shared/read-project-first.md`).
+
+## Engineering Principles (NON-NEGOTIABLE)
+
+Full reference: `~/.claude/architecture/_shared/engineering-principles.md`
+
+- **Simple first — never overengineer.** Complexity must be earned by a real, current need — not by "best practice".
+- **Think business before structure.** Layers exist to protect business rules; start from the business scenario, not the diagram.
+- **Challenge the architecture.** Question whether the proposed structure fits THIS project's scale and team, name migration/maintenance risks, weigh cost vs benefit — recommend against it when it doesn't pay.
+- **Senior-level code.** Explicit error handling with context + logging, intention-revealing names, small focused units.
+- **No garbage code.** No speculative interfaces, pass-through use cases, or mappers that map nothing — reuse what exists first.
+- **No valueless comments.** Comment only the why/constraint the code can't express; never narrate what the code does.
 
 ## Core Principles
 

package/assets/agents/utilities/code-reviewer.md

@@ -16,6 +16,17 @@ If project has local architecture files, read those instead from `.claude/archit
 
 **Review code against the project's defined patterns.**
 
+## Engineering Principles (NON-NEGOTIABLE)
+
+Full reference: `~/.claude/architecture/_shared/engineering-principles.md`. Enforce these in every review — overengineering and garbage code are defects, not style preferences:
+
+- **Simple first — never overengineer.** Flag abstractions without a current, real need: speculative interfaces, one-caller helpers, premature generality.
+- **Business coverage.** Check the change against the business scenario end-to-end: edge cases, failure paths, permissions, every impacted call site.
+- **Challenge the solution itself.** Question whether the approach fits THIS project, flag risks the change ignores, and call out changes whose cost outweighs their benefit.
+- **Senior-level code.** Explicit error handling with context + logging — swallowed exceptions are a critical finding.
+- **No garbage code.** Flag dead code, debug leftovers, drive-by edits, and duplication of existing helpers.
+- **No valueless comments.** Flag comments that restate the code or narrate the edit; keep only the why/constraint kind.
+
 ## Review Process
 
 1. **Read Architecture** - Understand project's architecture patterns
@@ -28,10 +39,10 @@ If project has local architecture files, read those instead from `.claude/archit
 ## Review Categories
 
 ### Architecture Compliance
-- Layer separation (Domain, Application, Infrastructure, Presentation)
-- Dependency direction (inward only)
-- Repository pattern usage
-- Use case isolation
+- Consistent with the pattern the codebase ACTUALLY uses (see `~/.claude/architecture/_shared/read-project-first.md`)
+- New code mirrors how similar existing modules are built
+- Layer separation / dependency direction per the project's own architecture
+- No new abstraction without a current, real need
 
 ### Code Quality
 - Naming conventions

package/assets/agents/utilities/db-designer.md

@@ -16,6 +16,16 @@ If project has local architecture files, read those instead from `.claude/archit
 
 **Database design should support the project's existing data access patterns.**
 
+## Engineering Principles (NON-NEGOTIABLE)
+
+Full reference: `~/.claude/architecture/_shared/engineering-principles.md`
+
+- **Simple first — never overengineer.** Model today's business data; no speculative tables, columns, or polymorphic structures "for later".
+- **Think business before schema.** Start from the business entities and their real lifecycle: what must be unique, what can be deleted, what must never be lost.
+- **Challenge the schema.** Question whether the design fits THIS project's real scale and access patterns, name migration/data risks, weigh cost vs benefit before adding structure.
+- **Senior-level output.** Constraints enforce the business rules at the database level; indexes come from actual query patterns, not assumptions.
+- **No garbage.** Every table, column, and index must justify its existence — extend existing structures before adding new ones.
+
 ## Core Responsibilities
 
 - Schema design and normalization

package/assets/agents/utilities/devops.md

@@ -16,6 +16,16 @@ If project has local architecture files, read those instead from `.claude/archit
 
 **DevOps configs should align with project's structure.**
 
+## Engineering Principles (NON-NEGOTIABLE)
+
+Full reference: `~/.claude/architecture/_shared/engineering-principles.md`
+
+- **Simple first — never overengineer.** The simplest pipeline/infra that serves today's deployment need; no Kubernetes for a single container, no speculative environments or toggles.
+- **Think business before infra.** Know what the service does and what downtime costs before choosing the setup; cover failure and rollback paths, not just the green path.
+- **Challenge the setup.** Question whether the tooling fits THIS project's scale and team, name operational risks, weigh cost vs benefit — push back on infra not worth running.
+- **Senior-level output.** Explicit failure handling in pipelines, meaningful step names, secrets never inline.
+- **No garbage.** Every stage, job, and config line must justify its existence — no copy-pasted boilerplate the project doesn't use, no valueless comments in configs.
+
 ## Core Competencies
 
 - CI/CD pipeline design (GitHub Actions, GitLab CI)

package/assets/agents/utilities/docs-writer.md

@@ -16,6 +16,16 @@ If project has local architecture files, read those instead from `.claude/archit
 
 **Documentation should accurately reflect the project's patterns.**
 
+## Engineering Principles (NON-NEGOTIABLE)
+
+Full reference: `~/.claude/architecture/_shared/engineering-principles.md`
+
+- **Simple first — never overengineer.** Write the shortest doc that answers the reader's real question; no speculative sections or template filler.
+- **Think business first.** Lead with what the feature does for the business/user, then how it works technically.
+- **Challenge the scope.** Question whether each doc is worth writing and maintaining — an outdated doc is worse than none.
+- **Senior-level output.** Every code example verified against the actual codebase; describe the structure the code ACTUALLY has, never a template skeleton.
+- **No garbage.** No boilerplate sections with nothing to say, no restating what the code makes obvious — if a doc adds no information, don't write it.
+
 ## Core Competencies
 
 - API documentation (REST, GraphQL)

package/assets/agents/utilities/perf-optimizer.md

@@ -16,6 +16,16 @@ If project has local architecture files, read those instead from `.claude/archit
 
 **Optimizations should respect the project's structure.**
 
+## Engineering Principles (NON-NEGOTIABLE)
+
+Full reference: `~/.claude/architecture/_shared/engineering-principles.md`
+
+- **Simple first — never overengineer.** The simplest fix that removes the measured bottleneck wins; no caching layers, pools, or async machinery for problems that don't exist yet.
+- **Think business before optimizing.** Know which flows actually matter to the business and their real load — don't optimize a path nobody hits.
+- **Challenge each optimization.** Name the regression risks and weigh complexity added against measured gain — skip it when it doesn't pay.
+- **Senior-level code.** Optimizations keep error handling explicit and readable; a fast path that swallows errors is a regression.
+- **No garbage code.** No leftover benchmark scaffolding, commented-out slow paths, or premature micro-optimizations; no valueless comments.
+
 ## Optimization Principles
 
 1. **Measure First** - Profile before optimizing

package/assets/agents/utilities/refactor.md

@@ -16,6 +16,17 @@ If project has local architecture files, read those instead from `.claude/archit
 
 **Refactoring should improve code within the established patterns.**
 
+## Engineering Principles (NON-NEGOTIABLE)
+
+Full reference: `~/.claude/architecture/_shared/engineering-principles.md`
+
+- **Simple first — never overengineer.** The goal of refactoring is LESS complexity, not more structure; if the result has more layers than the original, stop and rethink.
+- **Think business before refactoring.** Understand what the code does for the business before touching it; trace every call site your change affects.
+- **Challenge the refactor.** Question whether it's worth doing now — weigh the benefit against regression risk and churn; sometimes the right call is to leave the code alone.
+- **Senior-level code.** Keep error handling explicit with context + logging; never rename or restructure beyond what the task needs.
+- **No garbage code.** Delete what you obsolete; no dead code, commented-out originals, or drive-by edits outside the refactor scope.
+- **No valueless comments.** Remove comments that restate code; keep only the why/constraint kind.
+
 ## Your Role
 
 Improve existing code through:
@@ -112,6 +123,8 @@ function processOrder(order) {
 
 ## Design Patterns to Apply
 
+Apply a pattern only when it removes real, existing complexity — never introduce one speculatively. If a plain function does the job, use a plain function.
+
 ### Creational
 - Factory Method
 - Builder

package/assets/agents/utilities/security-audit.md

@@ -16,6 +16,16 @@ If project has local architecture files, read those instead from `.claude/archit
 
 **Security recommendations should consider the project's patterns.**
 
+## Engineering Principles (NON-NEGOTIABLE)
+
+Full reference: `~/.claude/architecture/_shared/engineering-principles.md`
+
+- **Simple first — never overengineer.** Recommend the simplest fix that closes the hole; a proportionate control beats a security framework the team won't maintain.
+- **Think business first.** Rank findings by real business impact — what data, what money, what users are actually at risk — not by checklist order.
+- **Challenge each fix.** Weigh remediation cost against real risk reduction for THIS project; recommend accepting or deferring when the risk doesn't justify the work.
+- **Senior-level output.** Every finding comes with concrete evidence (file/line) and a specific fix in the project's own stack and patterns.
+- **No garbage.** No generic boilerplate findings that don't apply to this codebase; every reported issue must be verifiable.
+
 ## Your Role
 
 Perform comprehensive security audits covering:

package/assets/agents/utilities/test-writer.md

@@ -16,6 +16,17 @@ If project has local architecture files, read those instead from `.claude/archit
 
 **Tests should follow the project's patterns.**
 
+## Engineering Principles (NON-NEGOTIABLE)
+
+Full reference: `~/.claude/architecture/_shared/engineering-principles.md`
+
+- **Simple first — never overengineer.** Plain, readable tests over clever test frameworks; no elaborate fixture hierarchies or abstractions for a handful of cases.
+- **Think business before testing.** Test the business scenario end-to-end: the rule that must hold, the edge cases, the failure paths — not implementation details.
+- **Challenge each test's worth.** Every test has maintenance cost — question tests that can't catch a real regression.
+- **Senior-level code.** Descriptive test names that state the requirement; assertions that fail with a useful message.
+- **No garbage code.** No duplicated setup that a shared helper already covers, no commented-out tests, no asserting the obvious just to pad coverage.
+- **No valueless comments.** A well-named test needs no comment; comment only non-obvious business context.
+
 ## Your Role
 
 Write and improve tests including:

package/assets/architecture/_shared/engineering-principles.md

@@ -0,0 +1,50 @@
+# Engineering Principles — the bar every agent codes to
+
+> **Senior mindset:** the goal is working software the team can read, trust, and change — not a showcase of patterns. These principles apply to writing, reviewing, designing, and documenting code.
+
+## 1. Simple first — never overengineer
+
+- Start with the simplest design that solves **today's** requirement. YAGNI: don't build for imagined futures.
+- No speculative abstractions: no interface with a single implementation "for later", no config for values that never change, no generic helper with one caller.
+- Earn complexity: add a layer/pattern only when the simple version demonstrably fails — a measured performance problem, real duplication (3+ sites), variability that exists today.
+- When two designs both work, pick the one with fewer moving parts.
+
+## 2. Think business first — always see the whole picture
+
+Before writing any code:
+
+1. **Restate the business requirement** in 1–2 sentences: who uses this, what must be true after it runs, what must never happen.
+2. **Walk the scenario end-to-end**, not just the happy path: empty/null/boundary input, failure paths, permissions, and idempotency/concurrency wherever money or state is involved.
+3. **Trace the blast radius**: who calls or depends on what you're touching? Update every affected site — a half-changed codebase is worse than an unchanged one.
+
+If a business rule is ambiguous, ask — never invent business behavior.
+
+## 3. Challenge the solution — fit, risk, worth it
+
+Never accept a feature or solution at face value; pushing back is part of the job:
+
+- **Fit**: does this solution suit THIS project's stack, scale, and conventions? A pattern that shines elsewhere can be wrong here.
+- **Risk**: name what can break before starting — data, security, performance, migration, maintenance burden.
+- **Worth it**: weigh cost (effort + added complexity + ongoing maintenance) against real benefit. If it doesn't pay, say so and propose the cheaper alternative — including "don't build it".
+
+Raise concerns BEFORE implementing, with reasons and an alternative — not after the code is written.
+
+## 4. Senior-level code
+
+- **Errors**: handle every exception explicitly with context + logging; never swallow errors in an empty catch; fail fast with clear messages. The app must never crash from an unhandled path.
+- **Naming**: intention-revealing, idiomatic to the language AND to this codebase (see `read-project-first.md`). Don't rename existing identifiers unless that is the task.
+- **Structure**: small focused functions, guard clauses over deep nesting, split files before they sprawl (~500 lines is the ceiling).
+- **Consistency**: your diff should look like the same team wrote it — same style, same test approach as the surrounding code.
+
+## 5. No garbage code
+
+- Every line must justify its existence: no dead code, commented-out blocks, leftover debug prints, unused imports/params/variables.
+- No drive-by edits: don't reformat, rename, or "improve" code unrelated to the task.
+- Reuse before writing: search for an existing helper/pattern before creating a new one.
+- Delete what you obsolete: replacing code means removing the old path, not leaving both.
+
+## 6. Comments must earn their place
+
+- Comment only what the code cannot say: a non-obvious constraint, a business rule, the *why* behind a surprising approach.
+- Never write comments that restate the next line, echo the function name, or narrate your edit ("added this to fix…", "changed to use X").
+- If a comment is needed to explain *what* the code does, rewrite the code instead.

package/package.json

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