@massa-ai/claude-plugin 1.6.0

package/skills/massa-ai/references/architecture-deepening-lens.md

@@ -0,0 +1,136 @@
+# Architecture Deepening Lens
+
+Use this detail reference when an architecture audit or execution task needs module depth, seams, adapters, testability, locality, or AI-navigability analysis.
+
+## Contents
+
+- Vocabulary
+- Deepening Signals
+- Deletion Test
+- Dependency Categories
+- Recommendation Template
+- Interface Design Method
+- Rejected Framings
+- Seam Discipline
+- Test Surface
+- Fix Direction
+
+## Vocabulary
+
+Use these terms exactly:
+
+- Module: anything with an interface and an implementation.
+- Interface: everything a caller must know, including types, invariants, ordering, errors, configuration, and performance.
+- Implementation: code inside the module.
+- Seam: where an interface lives and behavior can be varied without editing callers.
+- Adapter: concrete thing satisfying an interface at a seam.
+- Depth: leverage at the interface.
+- Leverage: capability callers get per unit of interface learned.
+- Locality: change, bugs, knowledge, and verification concentrated in one place.
+
+Avoid using `boundary` for module seams; reserve bounded context language for the domain lens.
+
+## Deepening Signals
+
+Flag candidates when evidence shows:
+
+- module interface is nearly as complex as its implementation
+- pass-through wrappers or one-use helpers add navigation cost
+- one concept is split across many files without leverage
+- callers must know ordering, invariants, config, or error modes that should be hidden
+- tests reach past the interface into internals because the interface is the wrong shape
+- extracted pure functions improve unit-test access but lose locality for real bugs
+- seams exist only for hypothetical future adapters
+
+## Deletion Test
+
+Ask what happens if the module is deleted:
+
+- If complexity disappears, the module was likely shallow.
+- If complexity spreads across callers, the module was probably earning its keep.
+- If behavior becomes harder to verify through one surface, the module likely has useful depth.
+
+Use this as evidence, not as a mechanical rule.
+
+## Dependency Categories
+
+Classify dependencies before recommending seams:
+
+- In-process: pure computation or in-memory state. Usually deepen by merging and testing through the new interface.
+- Local-substitutable: dependency has a local test stand-in. Keep seam internal when possible and test the deep module with the stand-in.
+- Remote but owned: own service across network. Define a port only when it keeps domain logic local and production/test adapters are both real.
+- True external: third-party dependency. Inject a port and use mock/fake adapters for tests when behavior cannot be run locally.
+
+### Recommendation Template
+
+For each dependency, state: Category → recommended seam → stand-in used in tests.
+
+| Category | Recommended seam | Stand-in example |
+|---|---|---|
+| In-process | deepen by merging | none — test through the new interface |
+| Local-substitutable | keep seam internal | in-memory fake |
+| Remote but owned | port only if domain stays local | owned-service test adapter |
+| True external | inject a port | PGLite (database), Stripe test mode (payment) |
+
+A stand-in is required evidence before introducing a port: "inject a port for
+Stripe, with the Stripe test-mode adapter as the production-shape stand-in" —
+not "add a port because it is cleaner."
+
+## Interface Design Method
+
+When a deepening candidate has two or more viable interface shapes, do not pick
+one by instinct. Design it twice: draft two parallel implementations (two
+sub-agents, or two sides authored yourself), each behind a different interface
+against the same caller need, then choose by leverage and locality.
+
+Four canned design constraints force distinct shapes:
+
+1. Minimal surface: hide every field and ordering the caller does not name.
+2. Batchable: one call serves many items, not one call per item.
+3. Policy-free: the interface states what, not how; no strategy leaks out.
+4. Substitutable: a second adapter can satisfy it without caller edits.
+
+Load this method from `architecture-fix.md` or `refactor.md` only when a
+candidate has >= 2 viable interface shapes; otherwise deepen directly.
+
+## Rejected Framings
+
+Avoid these misreadings of depth; record the rejection so it is not re-litigated:
+
+- Depth is NOT a lines-of-code ratio. A deep module can be tiny; a shallow
+  wrapper can be long. Padding an implementation to raise a "depth" metric is
+  exactly the anti-pattern this lens exists to find.
+- Interface is NOT a language keyword (`interface`, `protocol`, `trait`). It is
+  everything a caller must know — types, invariants, ordering, errors.
+- Seam is NOT a class boundary. Reserve `seam` for where behavior can vary
+  without editing callers; reserve bounded-context language for the domain lens.
+
+## Seam Discipline
+
+- One adapter means a hypothetical seam. Two adapters means a real seam.
+- Production plus test adapter can justify a seam when the dependency is remote or external.
+- Internal seams can exist inside the implementation without becoming part of the module interface.
+- Do not expose internal seams just because tests use them.
+- Do not introduce ports/adapters to decorate one local concrete call.
+
+## Test Surface
+
+The interface is the test surface:
+
+- prefer behavior tests through the module interface
+- delete or replace shallow-module tests once deep-module tests cover observable behavior
+- tests should survive implementation refactors
+- if tests must change for implementation-only movement, they are probably testing past the interface
+
+## Fix Direction
+
+Prefer:
+
+- delete shallow pass-through modules
+- inline one-use abstractions
+- merge split concepts when locality improves
+- deepen a useful module by hiding invariants and ordering
+- move validation and transformation behind the interface when callers should not know it
+- add a seam only where variation, dependency direction, external I/O, or test substitution is real
+
+Avoid broad rewrites, VSA migrations, or new service boundaries unless audit evidence shows current module shape blocks change or verification.

package/skills/massa-ai/references/architecture-domain-lens.md

@@ -0,0 +1,186 @@
+# Architecture Domain Lens
+
+Use this detail reference when an architecture audit or execution task needs domain boundaries, bounded contexts, subdomain classification, ubiquitous language, or cohesion analysis.
+
+## Contents
+
+- Inputs
+- Concept Inventory
+- Language Grouping
+- Subdomain Classification
+- Cohesion Score
+- Rubric Anchors
+- Worked Examples
+- Low-Cohesion Rules
+- Bounded Context Size
+- Findings To Report
+- Integration Pattern Selection
+- Anti-Patterns
+- Guardrails
+
+## Inputs
+
+Prefer current project evidence in this order:
+
+- `CONTEXT.md`, glossary files, product docs, issue/spec text, and user-provided business context
+- ADRs and architecture docs for accepted boundaries or rejected refactors
+- code names, route names, schemas, tests, fixtures, and use-case names
+- git history only as supporting evidence for change cohesion
+
+Code vocabulary is evidence, not truth. Mark conclusions as `suspect` when business intent is inferred only from names.
+
+## Concept Inventory
+
+Extract business concepts, not technical plumbing:
+
+- Entities: domain models with identity or lifecycle
+- Services: business operations, not generic helpers
+- Use cases: workflows, commands, handlers, jobs, or policies
+- Entry points: routes, resolvers, CLIs, events, screens, or cron jobs that expose business capabilities
+- Contracts: DTOs, events, schemas, published language, or anti-corruption layers
+
+Skip pure infrastructure unless it is mixed into core business behavior.
+
+## Language Grouping
+
+Group concepts by ubiquitous language:
+
+- same terms with the same meaning usually belong together
+- same term with different meanings signals separate bounded contexts
+- different vocabularies in one module signal a possible boundary mismatch
+- generic terms such as `User`, `Account`, `Customer`, `Order`, or `Policy` need local definitions before judging
+
+When a domain term is unclear, report the ambiguity instead of inventing a context.
+
+## Subdomain Classification
+
+Use this decision rule:
+
+```text
+Competitive advantage or fast-evolving proprietary business logic -> Core
+Business-specific but not differentiating -> Supporting
+Commodity or replaceable capability -> Generic
+```
+
+Static indicators:
+
+- Core: complex business rules, frequent domain changes, domain expert language, differentiating algorithms
+- Supporting: CRUD or workflow support with business-specific vocabulary
+- Generic: auth, logging, email, storage, payment gateway plumbing, metrics, generic notification transport
+
+Do not classify something as Core just because it is central in the import graph.
+
+## Cohesion Score
+
+Use scoring only when enough evidence exists:
+
+```text
+Linguistic cohesion: 0-3
+Usage cohesion: 0-3
+Data cohesion: 0-2
+Change cohesion: 0-2
+Total: 0-10
+```
+
+Interpretation:
+
+- 8-10: strong subdomain candidate
+- 5-7: mixed or evolving boundary
+- 0-4: likely wrong grouping or generic utility cluster
+
+If git history is absent or too expensive, score change cohesion as `unknown` and explain the gap.
+
+### Rubric Anchors
+
+Score each axis against these anchors (highest row that fits):
+
+| Axis | 3 | 2 | 1 | 0 |
+|---|---|---|---|---|
+| Linguistic | one shared ubiquitous term, one meaning | mostly shared terms | some shared terms | unrelated vocabularies |
+| Usage | all concepts used in the same use cases | most concepts co-used | partly co-used | rarely co-used |
+| Data | shared identity or aggregate root | shared attributes | read-only overlap | no shared data |
+| Change | always change together | usually change together | sometimes change together | change independently |
+
+Data and Change max at 2; Linguistic and Usage max at 3. The anchors make the
+0-10 total reproducible across auditors.
+
+### Worked Examples
+
+- Same term, three contexts: `Patient` in scheduling (availability), billing
+  (invoice line), and clinical (record) is three bounded contexts sharing a
+  published language — not one `Patient` model. Score linguistic 1 (shared term)
+  but usage 0 and change 0; the total flags a boundary, not a single aggregate.
+- Identity-leak fix: an order DTO field `user: User` leaks the auth context's
+  model into billing. Replace it with `customerId: CustomerId`, a value object
+  owned by billing, so billing no longer depends on `User`'s shape or lifecycle.
+
+## Low-Cohesion Rules
+
+A grouping is likely wrong when:
+
+1. Mixed vocabulary: one module speaks two or more ubiquitous languages (for
+   example `Invoice` beside `RenderFrame`). Action: split by language.
+2. Shotgun change: one business change edits many modules that share no domain
+   term. Action: find the missing boundary, or merge the co-changing parts.
+3. God aggregate: one root owns unrelated data (orders + notifications + audit).
+   Action: split into per-language aggregates.
+4. Technical grouping: modules clustered by layer ("all controllers", "all
+   repositories") instead of by language. Action: re-group vertically.
+5. Cross-context ownership: one context reads or writes another's tables or
+   invariants directly. Action: expose an owned contract or anti-corruption layer.
+
+## Bounded Context Size
+
+| Signal | Meaning |
+|---|---|
+| 1-2 aggregates, single use-case family | too small — likely a layer, not a context; merge or drop |
+| coherent language, 3-8 aggregates, clear integration contract | right-sized |
+| 12+ aggregates or multiple unrelated languages | too large — split along the next language boundary |
+
+## Findings To Report
+
+Report domain findings when evidence shows:
+
+- mixed vocabularies in one module create change friction
+- one context directly owns another context's model, persistence, or invariants
+- generic/supporting infrastructure is embedded in core business logic
+- a bounded context lacks an explicit integration contract
+- a term has colliding meanings across modules and causes bugs or coordination cost
+
+Useful integration directions:
+
+- Published Language: documented DTO/event/schema shared across contexts
+- Anti-Corruption Layer: translation when upstream language should not leak downstream
+- Open Host Service: stable public interface for multiple consumers
+- Shared Kernel: shared model only when ownership is explicit and scope is tiny
+- Customer/Supplier or Conformist: acceptable only when dependency direction and ownership are intentional
+
+## Integration Pattern Selection
+
+Pick the integration pattern from the need, not from familiarity:
+
+| Need | Pattern |
+|---|---|
+| upstream is legacy or external; its language must not leak downstream | Anti-Corruption Layer |
+| upstream publishes a stable API many consumers depend on | Open Host Service / Published Language |
+| many consumers need the same domain occurrence | Domain Events (published language) |
+| two contexts must share a tiny, co-owned slice | Shared Kernel (only with explicit shared ownership) |
+| downstream must conform to an upstream it cannot influence | Conformist |
+
+## Anti-Patterns
+
+- ❌ Grouping by technical layer ("all controllers", "all services", "all
+  repositories") instead of by ubiquitous language — hides boundaries and
+  causes shotgun change.
+- ❌ One bounded context per directory — boundaries follow language, not folders.
+- ❌ Service extraction from language evidence alone — requires change and
+  ownership evidence.
+- ❌ Re-litigating an ADR-backed boundary without new concrete friction.
+
+## Guardrails
+
+- Do not force one bounded context per directory.
+- Do not propose service extraction from language evidence alone.
+- Do not relitigate ADR-backed boundaries unless current friction is concrete.
+- Do not mutate `CONTEXT.md`, ADRs, or docs during an audit.
+- Prefer move, rename, or contract clarification before new layers.

package/skills/massa-ai/references/architecture-lenses.md

@@ -0,0 +1,108 @@
+# Architecture Lenses
+
+Use this reference for architecture audits, architecture-focused reviews, and refactor planning. It is the shared index and vocabulary guard; load the detail references only when a workflow needs that lens:
+
+- `references/architecture-domain-lens.md` for bounded contexts, ubiquitous language, subdomain classification, cohesion, and integration patterns.
+- `references/architecture-coupling-lens.md` for dependency graphs, strength/distance/volatility, dependency direction, and contract health.
+- `references/architecture-deepening-lens.md` for module depth, seams, adapters, deletion tests, locality, and interface-as-test-surface analysis.
+
+Do not load all detail references by default. Pick the smallest lens set that can prove or disprove the architecture claim.
+
+## Domain Lens
+
+Map problem-space boundaries before proposing structural changes.
+
+Load `references/architecture-domain-lens.md` when the audit target includes domain language, bounded contexts, subdomain classification, cross-domain ownership, or integration pattern choices.
+
+Check:
+
+- subdomains: Core, Supporting, Generic
+- bounded contexts and ubiquitous language
+- concept cohesion: language, usage, data, change
+- cross-domain dependencies
+- generic functionality mixed into core logic
+
+Report:
+
+- domain or subdomain
+- type: Core, Supporting, or Generic
+- key terms and concepts
+- cohesion score when useful
+- dependency direction
+- boundary or language mismatch
+- simplest corrective direction
+- mark as `suspect` when business intent is inferred only from code names
+
+## Coupling Lens
+
+Analyze dependency cost with strength, distance, and volatility.
+
+Load `references/architecture-coupling-lens.md` when the audit target includes dependencies, imports, service calls, shared schemas/models, direct persistence access, co-change, or contract leakage.
+
+Strength levels:
+
+- Intrusive: downstream depends on internals not designed for integration.
+- Functional: sequential, transactional, or duplicated symmetric business rules.
+- Model: upstream exposes internal domain model to downstream.
+- Contract: integration-specific DTO/protocol hides internals.
+
+Distance levels:
+
+- same function or class
+- same package
+- same module/library
+- different service
+- external system or team
+
+Volatility signals:
+
+- core business logic
+- frequent git changes or co-change
+- TODO/FIXME clusters
+- evolving API versions
+- fragile tests or recurring regressions
+
+Flag highest risk when high strength, high distance, and high volatility combine.
+
+Do not flag strong local coupling as bad when the modules change together and locality is better than separation.
+
+## Deepening Lens
+
+Use these terms exactly:
+
+- Module: anything with an interface and implementation.
+- Interface: everything a caller must know, including invariants, ordering, errors, config, and performance.
+- Seam: where an interface lives.
+- Adapter: concrete thing satisfying an interface at a seam.
+- Depth: leverage at the interface.
+- Leverage: capability callers get per unit of interface learned.
+- Locality: change, bugs, and verification concentrated in one place.
+
+Load `references/architecture-deepening-lens.md` when the audit target includes shallow modules, pass-through abstractions, seams, adapters, tests that reach past interfaces, or AI-navigability concerns.
+
+Check:
+
+- shallow modules whose interface is nearly as complex as implementation
+- pass-through wrappers
+- seams with only one adapter and no actual variation
+- test-only extraction that loses locality
+- concepts split across many files without leverage
+
+Use the deletion test:
+
+- If deleting a module removes complexity, it was probably shallow.
+- If deleting it spreads complexity across callers, it was probably earning its keep.
+
+Only recommend a new seam when variation, dependency direction, external I/O, or test substitution is real.
+
+## Findings Format
+
+```md
+Severity: Critical | High | Medium | Low | Suspect
+Lens: Domain | Coupling | Deepening
+Location: path:line or module
+Evidence: concrete source, dependency, or history signal
+Impact: maintenance, change-risk, testability, or AI-navigability cost
+Recommendation: simplest sufficient action
+Tradeoff: what improves and what gets worse
+```