@behaghel/pi-domain-tree 0.4.0

package/skills/domain-navigator/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: domain-navigator
+description: |
+  Navigate and enforce domain-driven codebase structure. Use when the user references a domain, asks where code or specs live, wants to understand project structure, asks about domain boundaries, or when you need to locate the right spec or code for a given feature area. Also use when creating new files to ensure they land in the correct domain namespace.
+---
+
+# Domain Navigator
+
+Provides domain-aware navigation and enforcement for codebases structured around `domains.yaml`.
+
+Load `references/manifest-schema.md` when working with `domains.yaml`.
+Load `references/conventions.md` when making decisions about file placement or domain boundaries.
+
+## When to activate
+
+- User references a domain or feature area ("the issuance flow", "wallet onboarding")
+- User creates a new file and you need to decide where it belongs
+- User asks "where does X live?" or "what domain owns Y?"
+- Before starting spec collection (to scope which domain the spec belongs to)
+- Before planning TDD iterations (to scope which domain boundaries apply)
+
+## Core behavior
+
+### 1. Load the domain tree
+
+1. Read `domains.yaml` at the project root.
+2. If it doesn't exist, tell the user: "No domain tree found. Run `/domain-tree:init` to create one."
+3. Parse explicit `kind: group` entries as structural namespaces, then build a model of bounded-context domains, subdomains, code paths, and spec paths. Groups are not domains and own no code or specifications.
+
+### 2. Resolve domain from context
+
+When the user describes work or you're about to modify code:
+
+1. Match the target file(s) against `code` paths in the manifest; the most-specific child path wins.
+2. Identify the governing domain, subdomain, and **domain type** (core/supporting/generic/shared-kernel).
+3. Locate the corresponding colocated spec path (by default, the first `code` path; `spec` may override it).
+4. Report: "This is in the **[domain] > [subdomain]** namespace (type: **[type]**). Spec at `[code path]/README.md`. Code at `[code paths]`."
+
+If a file doesn't match any domain:
+- Flag it: "This file isn't covered by any domain in `domains.yaml`. Should we add it to an existing domain or create a new one?"
+
+### 3. Enforce placement on new files
+
+When creating new files:
+
+1. Determine which domain the file belongs to based on its purpose.
+2. Check that the target path is within that domain's `code` paths.
+3. If it isn't, suggest the correct location: "This looks like it belongs in **[domain]**. The convention is `[correct path]`."
+4. If a new subdomain is needed, propose updating `domains.yaml` first.
+
+### 4. Spec-on-touch (classification-aware)
+
+Default to a domain specification containing durable, present-tense domain truth. Define each concept, invariant, or contract once at its narrowest owner and link to it elsewhere. Use standard relative Markdown links and resolve canonical terms or aliases with `domain_tree_resolve_term`; link meaningful first occurrences to the one repository-wide owner. Use a declared system spec only for a stable RFC 2119 requirement that cannot belong to one domain. Keep temporary scope, acceptance criteria, sequencing, rollout, migration, progress, and verification plans in non-normative iteration artifacts outside both corpora.
+
+When editing production code:
+
+1. Resolve the governing domain and its `type`.
+2. Check for the domain's normative `README.md`; sibling Markdown is normative only when it declares `domain` and `status` frontmatter.
+3. Apply rigor based on domain type:
+   - **core** — Hard block. "No spec exists for **[domain]** (core). This domain requires a spec before any code change."
+   - **supporting** — Warning. "No spec exists for **[domain]** yet. Consider writing one before this change."
+   - **generic** — Soft note. "No spec for **[domain]**. Only needed if you're changing the integration boundary."
+   - **shared-kernel** — Hard block. "This is shared kernel — changes affect all consumers. Spec required, and consumers must be notified."
+4. If a spec exists, check its `status` field:
+   - `draft` — "This spec is a draft. Verify it's accurate before implementing against it."
+   - `approved` — proceed normally.
+   - `stale` — "This spec may be outdated. Review it before implementation."
+
+### 5. Cross-domain awareness (context-map-driven)
+
+When work spans multiple domains:
+
+1. Identify all affected domains.
+2. Consult semantic `context-map` entries (`provider`, `consumers`, `pattern`, and canonical `contract`) for the declared relationship.
+3. If a relationship exists:
+   - Report the pattern: "This crosses **[domain A]** → **[domain B]** (pattern: **[pattern]**)."
+   - Guide based on pattern:
+     - **shared-kernel**: "Both domains consume this. Update the kernel spec and notify all consumers."
+     - **customer-supplier**: "**[upstream]** owns the contract. Check if the change is compatible."
+     - **anti-corruption-layer**: "Changes should go through the ACL at `[via path]`, not bypass it."
+     - **conformist**: "**[downstream]** conforms to **[upstream]**'s model. Update the downstream's mapping."
+4. If no relationship is declared:
+   - Flag it: "This crosses **[domain A]** and **[domain B]** but no relationship is declared in the context map. Add one before proceeding."
+5. Note which specs need updating in each affected domain.
+
+### 6. Shared kernel awareness
+
+When editing code in a `shared-kernel` domain:
+
+1. Identify all consumers from the `context-map` (domains with `pattern: shared-kernel` pointing to this domain).
+2. Warn: "This is shared kernel. Changes affect: **[list of consuming domains]**."
+3. Check for contract tests in each consuming domain.
+4. Recommend: "Run contract tests for [consumers] after this change."
+
+## Guardrails
+
+- Do NOT create files outside the domain tree without flagging it.
+- Do NOT let domain boundaries drift silently — every new code path should map to a domain.
+- Allow parent/child overlap under subsidiarity; reject unrelated domains claiming the same path.
+- Do NOT treat `domains.yaml` as documentation — it is a structural contract.
+- Do NOT enforce domains on non-production files (tests, scripts, CI) unless they have their own technical domain.
+- Do NOT allow cross-domain changes without consulting the context map.
+- Do NOT allow shared-kernel changes without notifying all consumers.

package/skills/domain-navigator/references/conventions.md

@@ -0,0 +1,228 @@
+# Domain Tree Conventions
+
+Rules for maintaining the 1:1 mirror between colocated domain specs and code namespaces, informed by Domain-Driven Design.
+
+## The colocation principle
+
+`domains.yaml` lives at the project root. Domain specs live beside the code they govern: the first `code` path is the default spec directory, `README.md` is the main domain spec, and additional behavior specs are sibling `*.md` files. If specs cannot live in the first `code` path, an explicit `spec:` override may point to the colocated spec directory.
+
+For a project that uses `src/`, the common shape is:
+
+```
+.
+├── domains.yaml               (the manifest)
+└── src/
+    ├── verification/
+    │   ├── README.md          (main domain spec)
+    │   ├── presentation.md    (specific behavior spec)
+    │   └── ...code...
+    ├── issuance/
+    │   ├── README.md
+    │   └── ...code...
+    └── shared-kernel/
+        ├── README.md
+        └── ...code...
+```
+
+The domain tree SHOULD mirror the code's module/package structure. When they diverge, make the drift visible in `/domain-tree:check` and decide whether to refactor code or update `domains.yaml`.
+
+## Ubiquitous language
+
+Each domain has its own vocabulary. The same word can mean different things in different domains — that's expected and healthy. What matters is consistency WITHIN a domain.
+
+- Define key terms in the domain's `language` field in `domains.yaml` or in `<domain code path>/README.md`
+- Code names (types, functions, variables) MUST use the domain's vocabulary
+- Spec text MUST use the domain's vocabulary
+- When two domains need to communicate, the context map defines how terms translate
+
+Example: "Credential" means an SD-JWT VC in the issuance domain, but a displayable card in the wallet domain. The ACL between them handles the translation.
+
+## Domain classification and spec rigor
+
+Not all domains deserve equal investment. Classification drives how thoroughly you spec:
+
+### Core domains (`type: core`)
+
+The competitive advantage. Invest the most here.
+
+- **Spec rigor:** Full spec-driven collection (all 6 phases). Every behavioral change specced before code.
+- **TDD rigor:** Thorough iteration plans, small slices, careful red-green-refactor.
+- **Review:** Specs need human approval before implementation.
+- **Spec-on-touch:** Hard requirement — no code changes without a spec.
+- **Modeling:** Rich domain models with explicit aggregates, value objects, domain events.
+
+### Supporting domains (`type: supporting`)
+
+Necessary, custom-built, not differentiating.
+
+- **Spec rigor:** Good specs but lighter process. Can skip some collection phases.
+- **TDD rigor:** Standard TDD. Larger slices acceptable.
+- **Review:** Self-approval OK for straightforward specs.
+- **Spec-on-touch:** Warning when missing, not blocking.
+- **Modeling:** Simpler models. CRUD-like patterns are fine.
+
+### Generic domains (`type: generic`)
+
+Solved problems. Use existing libraries, standards, infrastructure.
+
+- **Spec rigor:** Spec the integration boundary only. Don't spec the internals of something you didn't build.
+- **TDD rigor:** Contract tests at the boundary. Don't unit-test the library.
+- **Review:** Minimal — the standard/library IS the spec.
+- **Spec-on-touch:** Only when the integration surface changes.
+- **Modeling:** Thin wrappers. Anti-corruption layers where the external model leaks.
+
+### Shared kernel (`type: shared-kernel`)
+
+Shared types and contracts across domains. Treated with the rigor of core, because changes ripple everywhere.
+
+- **Spec rigor:** High. Every shared type must be explicitly specced.
+- **TDD rigor:** High. Contract tests from every consumer.
+- **Review:** Joint approval from all consuming domains.
+- **Spec-on-touch:** Always — any change to shared kernel needs spec update.
+- **Modeling:** Value objects and immutable types preferred. Minimize the kernel surface.
+
+## Context map conventions
+
+The context map in `domains.yaml` declares cross-domain relationships. These relationships are architectural decisions, not just documentation.
+
+### Integration patterns and what to spec
+
+| Pattern | Spec location | What the spec covers |
+|---------|--------------|---------------------|
+| shared-kernel | The kernel domain's colocated spec directory | The shared types, their invariants, and which domains consume them |
+| customer-supplier | Upstream domain's spec | The contract — what the upstream promises and what can change |
+| conformist | Downstream domain's spec | How the downstream maps upstream concepts to its own model |
+| anti-corruption-layer | Downstream domain's spec | The ACL: what comes in, what comes out, where it lives in code |
+| open-host-service | Upstream domain's spec | The protocol or API definition (often a published standard) |
+| published-language | `<domain code path>/` of the publisher | The schema or interchange format |
+
+### Cross-domain changes with context map awareness
+
+When a change spans domains, the context map tells you how to handle it:
+
+1. **shared-kernel change** → Update the kernel spec. Notify ALL consuming domains. Run contract tests from each consumer.
+2. **customer-supplier change** → Upstream changes its contract → downstream must update its conformance. Check the downstream's ACL or conformist layer.
+3. **anti-corruption-layer change** → Only the downstream's ACL needs updating. The upstream is unaware.
+4. **partnership change** → Both domains update together. Coordinate specs.
+
+If a cross-domain change doesn't fit any declared relationship, the context map is incomplete — add the relationship before proceeding.
+
+## Spec file conventions
+
+### Naming
+
+- One spec per bounded concern: `src/issuance/credential-flow.md`
+- Use the behavior name, not the implementation name: `verification-request.md` not `verify-handler.md`
+- Keep iteration plans outside domain and system corpora; delete them when no longer operationally useful.
+
+### Frontmatter
+
+Every spec file should have YAML frontmatter:
+
+```yaml
+---
+domain: issuance
+status: draft | approved | stale
+---
+```
+
+- `domain` — must match a domain in `domains.yaml`
+- `status` — lifecycle state (`draft` → `approved` → `stale` when code outpaces spec)
+- canonical term pages additionally declare `term` and may declare `aliases`
+
+Keep normative metadata minimal. Do NOT use `last-reviewed`, delivery state, or `governs:`. Code ownership is already declared in `domains.yaml`; Git preserves review and delivery history.
+
+### Domain-level spec
+
+A domain MAY have a `README.md` at its code root:
+
+```
+src/issuance/
+├── README.md             ← main domain spec: ubiquitous language, invariants, domain events
+├── credential-flow.md    ← specific behavior spec
+├── webhook-handling.md
+└── ...code...
+```
+
+`README.md` is the required domain overview. Keep it concise and substantive: ubiquitous language, responsibilities, invariants, boundaries, or domain events. Do not create an overview that only repeats manifest metadata.
+
+`README.md` does NOT duplicate information already in `domains.yaml`:
+- Description
+- Domain type/classification
+- Code paths
+- Context map relationships
+- Consumer lists
+
+### Specification DRY
+
+Define each concept, invariant, or contract once at its narrowest semantic owner. Other specifications link to that canonical definition and describe only their local use, constraints, or consequences. Domain specifications are the default normative artifact.
+
+Use a declared system spec only for a durable RFC 2119 requirement that cannot be assigned to one domain by subsidiarity. Keep temporary acceptance criteria, implementation scope, sequencing, rollout, migration, progress, and verification plans in non-normative iteration artifacts outside both corpora. Normative specs describe current durable behavior in the present tense; they do not preserve legacy or transitional commentary.
+
+### Specification wiki links
+
+Use standard relative Markdown links, never a separate wikilink syntax. Canonical term pages declare `term` and optional `aliases`; canonical terms and aliases form one case-insensitive repository-wide namespace with one semantic owner per label. A term-labelled link must target that owner. Link meaningful first occurrences, not every repetition. Relative targets must exist, and fragments on Markdown targets must resolve to real heading anchors. External URLs are allowed but are outside repository-integrity checks.
+
+## Code-paths rules
+
+`code-paths` in `domains.yaml` should be **directories, not individual files**. A code-path means "everything under this directory belongs to this domain."
+
+### Signals that code-paths need attention
+
+1. **Individual files listed**: If a domain lists `ui/FooScreen.kt`, `ui/BarScreen.kt` instead of `ui/foo/`, the code likely needs refactoring into subdirectories that match the domain boundary.
+2. **Many subdirectories of the same parent**: If a domain lists `ui/mapper/`, `ui/model/`, `ui/components/` — the parent `ui/` probably belongs to the domain. List the parent, not each child.
+3. **Overlapping paths**: Parent/child overlap is valid and the most-specific matching child owns the file. If unrelated domains claim the same path, establish one semantic owner or refactor into distinct directories.
+
+When `/domain-tree:check` detects these patterns, it should recommend the refactoring rather than silently accepting the file-level mappings.
+
+### Spec files live next to code, not in docs/
+
+All behavioral specifications must live under the domain's colocated spec directory (normally the first `code` path). `README.md` and sibling Markdown with `domain`/`status` frontmatter form the normative corpus. Prompts, agent instructions, guides, plans, and historical documents without that frontmatter are non-normative. If a spec-like document exists in `docs/`, move it next to the owning domain's code; keep only non-normative material in `docs/`.
+
+## When to create a new domain
+
+Create a new domain when:
+- New code doesn't fit any existing domain's description
+- An existing domain has grown to cover two distinct responsibilities
+- A technical concern (monitoring, deployment) becomes complex enough to spec
+
+Do NOT create a new domain when:
+- The code is a utility used by exactly one domain (put it in that domain)
+- The code is shared across domains (add it to the shared kernel)
+- The work is a one-off script (not everything needs a domain)
+
+## When to split a domain into subdomains
+
+Split when:
+- The domain has more than 5 spec files
+- Two parts of the domain can change independently
+- Different people/teams own different parts
+- The code already has natural package boundaries
+- The ubiquitous language has started to diverge within the domain (same word, different meanings)
+
+## Shared kernel rules
+
+The shared kernel is the most constrained domain:
+
+1. **Minimize the surface.** The less you share, the less coupling.
+2. **Prefer value objects.** Immutable, identity-less types are safe to share. Entities with lifecycles are not.
+3. **No business logic.** The kernel is types and contracts, not behavior.
+4. **Explicit consumers.** The context map must list every domain that depends on the kernel.
+5. **Joint approval.** No unilateral changes — all consumers must agree.
+6. **Contract tests.** Every consumer maintains tests that verify the kernel's contracts.
+
+## Technical domains vs business domains
+
+Technical domains follow the same rules but spec different things:
+
+| Domain type | Spec contains |
+|------------|---------------|
+| Business | Acceptance criteria, user behavior, data flow |
+| Security | Threat model, cryptographic requirements, invariants |
+| UX | Design tokens, component behavior, accessibility rules |
+| Infra | Deployment topology, scaling rules, network policies |
+| CI/CD | Pipeline stages, quality gates, release process |
+
+The common thread: if it has behavior or constraints worth verifying, it gets a spec.
+
+Technical domains CAN be `type: core` — security in a trust provider is absolutely core, even though it's not "business logic" in the traditional DDD sense.

package/skills/domain-navigator/references/manifest-schema.md

@@ -0,0 +1,277 @@
+# Domain Manifest Schema
+
+The domain manifest lives at `domains.yaml` and is the structural contract between specs and code. It encodes the domain tree, subdomain classifications, and the context map.
+
+## Structure
+
+```yaml
+# domains.yaml
+
+# Optional project-level metadata
+project:
+  name: my-project
+  description: One-line project description
+
+# Optional project-level normative corpus for requirements that cannot
+# be assigned to one domain by subsidiarity.
+system-specs: [doc/system/]
+
+# Structural groups and domains
+domains:
+  <group-name>:
+    kind: group
+    description: Optional navigation context
+    domains:
+      <domain-name>:
+        description: What this domain is responsible for
+        type: core | supporting | generic | shared-kernel  # default: supporting
+        status: active | deprecated | planned              # default: active
+        owners: [team-or-person]                           # optional
+        language:                                          # optional: ubiquitous language
+          - term: Cachet
+            meaning: A privacy-preserving trust badge issued after credential verification
+
+        # Specs live in the first code path by default.
+        code: [path/to/code/, another/path/]
+        # Optional override when specs cannot live in the first code path:
+        spec: path/to/code/
+
+        # Bounded contexts may contain narrower bounded contexts.
+        subdomains:
+          <subdomain-name>:
+            description: ...
+            type: core | supporting | generic    # inherits from parent if omitted
+            code: [path/to/code/]
+            # Optional override; otherwise specs live in path/to/code/.
+            # subdomains can nest further
+
+# Cross-context relationships
+context-map:
+  - provider: <fully-qualified/domain-name>
+    consumers: [<fully-qualified/consumer-name>]
+    pattern: <relationship-pattern>
+    contract: <canonical spec path>
+```
+
+## Structural groups
+
+A `kind: group` entry provides namespace and presentation structure only. Its `domains` may contain domains or nested groups. Groups are not bounded contexts: they have no classification, lifecycle, owners, language, code ownership, specification, subdomains, or context-map relationships. The only allowed group fields are `kind`, `description`, and `domains`. Fully qualified domain names retain their group path, such as `business/time-management`.
+
+Entries without `kind: group` remain domains. Domain nesting uses `subdomains`, not `domains`. A domain must declare `code` or an explicit `spec`; a node with only children is invalid and should normally become a group.
+
+## Normative corpora
+
+Domain specifications are the default. They contain durable, present-tense behavior, ubiquitous language, boundaries, invariants, and semantic contracts owned by one domain.
+
+`system-specs` may declare Markdown files or directories. Directories are scanned recursively. Every included file is normative and must use only this frontmatter:
+
+```yaml
+---
+system: my-project
+status: draft | approved | stale
+---
+```
+
+The `system` value must equal `project.name`, and every system spec must contain at least one uppercase RFC 2119 keyword: `MUST`, `MUST NOT`, `SHOULD`, `SHOULD NOT`, or `MAY`. System specs cannot own ubiquitous terms; they link to domain-owned canonical pages. Use system specs only for stable requirements that subsidiarity cannot assign to one domain.
+
+Iteration specs are temporary delivery artifacts. They remain outside domain spec directories and declared `system-specs`, carry no normative frontmatter, and are deleted when no longer useful.
+
+Together, normative files form a standard relative-Markdown wiki. Canonical term pages declare `term` and optional `aliases`. Every case-insensitive canonical term or alias has one repository-wide owner. Relative targets and Markdown heading anchors must resolve; term-labelled links must target the canonical owner. Meaningful first-occurrence linking remains a semantic authoring rule rather than a noisy lexical hard check.
+
+Normative domain and system specs reject project-management sections such as roadmaps, rollout or migration plans, progress, delivery status, milestones, and verification plans. They state durable behavior rather than legacy comparisons or temporary implementation concerns.
+
+## Domain classification
+
+Every domain has a `type` that determines how much modeling rigor it deserves. This comes from DDD's subdomain classification:
+
+| Type | What it means | Spec rigor | Example |
+|------|--------------|------------|---------|
+| **core** | Competitive advantage. The reason the project exists. | High — thorough specs, careful TDD, deep modeling | verification, issuance |
+| **supporting** | Necessary, custom-built, but not differentiating. | Moderate — good specs, standard TDD | registry, receipts |
+| **generic** | Solved problem. Use existing solutions where possible. | Light — spec the integration, not the internals | auth, email, payment |
+| **shared-kernel** | Shared types and contracts across domains. Joint ownership. | High — changes affect all consumers, must be explicit | common types, shared events |
+
+### How classification drives behavior
+
+- **spec-on-touch**: Core domains require a spec before any code change. Supporting domains get a warning. Generic domains only need an integration spec.
+- **spec-driven collection**: Core domains get the full 6-phase treatment. Supporting domains can use a lighter format. Generic domains spec only the boundary.
+- **spec-tdd planning**: Core domains get thorough iteration plans. Supporting domains can take larger slices. Generic domains focus on contract tests.
+- **code review**: Core domain specs need human approval before implementation. Supporting specs can be self-approved.
+
+## Context map
+
+The `context-map` section declares semantic contracts between domains. Each entry names one provider, one or more consumers, an integration pattern, and the canonical contract. Ordinary imports do not require context-map entries.
+
+### Relationship patterns
+
+| Pattern | Meaning | What to spec |
+|---------|---------|-------------|
+| **shared-kernel** | Both domains share a small, explicit set of types. Changes require agreement from both. | The shared types themselves — what's in the kernel and what's not |
+| **customer-supplier** | Upstream domain provides what downstream needs. Downstream can negotiate. | The API contract between them — what's promised, what can change |
+| **conformist** | Downstream accepts upstream's model as-is. No negotiation. | Only the downstream's usage — how it maps upstream concepts to its own |
+| **anti-corruption-layer** | Downstream translates upstream's model to protect its own. | The translation layer — what comes in, what comes out, where the ACL lives |
+| **open-host-service** | Upstream exposes a general-purpose protocol for many consumers. | The protocol spec (often an existing standard like OpenID4VCI) |
+| **published-language** | A shared, documented interchange format. Often paired with open-host-service. | The schema or format definition |
+| **separate-ways** | No integration. Domains are independent. | Nothing — but document WHY they're separate |
+| **partnership** | Two domains evolve together with coordinated planning. | Joint specs that cover the shared evolution |
+
+### How the context map drives behavior
+
+- **boundary-enforcer**: When a cross-domain change is detected, consult the context map. The provider owns the canonical `contract`; consumers follow the declared pattern.
+- **domain-tree:check**: Validate that providers and consumers exist, patterns are supported, and canonical contract paths resolve.
+- **spec-driven collection**: When speccing a domain that consumes another, the context map tells you which integration pattern to follow — and therefore what to spec.
+
+## Manifest integrity
+
+The manifest is validated strictly. Unknown fields, malformed value types, unsupported classifications or lifecycle states, incomplete context relationships, and group references in the context map are errors. When any error exists, ownership resolution, maps, and spec coverage fail closed rather than using a partial tree. `/domain-tree:check` reports all diagnostics; malformed YAML includes line and column when available.
+
+Legacy structural-only nodes are never rewritten automatically. Convert them explicitly to `kind: group` with `domains`, or give a real bounded context a `code` or `spec` anchor.
+
+## Path rules
+
+- `code` paths are relative to project root, always end with `/`.
+- The most-specific matching child path owns a file. Parent/child overlap is valid; unrelated domains cannot claim the same path.
+- Specs live next to code. The first `code` path is the default spec directory; `README.md` is the required main domain spec.
+- `spec` is optional and only overrides the inferred spec directory when specs cannot live in the first `code` path.
+- Groups use `domains`; bounded contexts use `subdomains`.
+- Groups never own code or specifications and are excluded from domain coverage counts.
+- A domain is either a **leaf** (has `code`) or a **branch** (has `subdomains`).
+- Branch domains may also have `code` + `spec` for domain-level concerns (shared types, domain events).
+
+## Domain types
+
+Domains are not limited to business logic. The tree covers everything with behavior worth specifying:
+
+| Category | Examples | What gets specced |
+|----------|----------|------------------|
+| **Business** | verification, issuance, registry | User-facing behavior, acceptance criteria |
+| **Technical** | security, crypto, infra | Architectural constraints, invariants |
+| **Platform** | ux, cicd, observability | Conventions, patterns, tooling behavior |
+| **Integration** | webhooks, external-apis | Contract specs, error handling |
+
+Domain category is about WHAT it covers. Domain type (core/supporting/generic) is about HOW MUCH rigor it deserves. They're orthogonal — a technical domain like security can be `core`.
+
+## Naming conventions
+
+- Domain names: lowercase, hyphenated (`issuance-gateway`, `receipts-log`)
+- Match existing module/package names where possible
+- Prefer domain language over implementation language ("verification" not "verifier-service")
+
+## Coverage
+
+Not every file needs to be in a domain. Exclude:
+- Generated files (build output, lock files)
+- Configuration that doesn't encode behavior (.editorconfig, .gitignore)
+- Third-party code (vendor/, node_modules/)
+
+Everything else should map to a domain. Unmapped production code is a smell.
+
+## Example
+
+```yaml
+project:
+  name: cachet
+  description: Privacy-preserving trust provider
+
+domains:
+  verification:
+    description: Credential presentation and cach'pack verification
+    type: core
+    language:
+      - term: Cach'Pack
+        meaning: Reusable, privacy-preserving credential template
+      - term: Presentation
+        meaning: Verifiable credential bundle verified against a policy
+    subdomains:
+      presentation:
+        description: Verify credential presentations against policies
+        code: [services/verifier/presentation/]
+      packs:
+        description: Cach'pack list management and definitions
+        code: [services/verifier/packs/]
+
+  issuance:
+    description: OpenID4VCI credential issuance via Veriff
+    type: core
+    code: [services/issuance-gateway/]
+
+  registry:
+    description: Policy and pack registry with DID-signed manifests
+    type: supporting
+    code: [services/registry/]
+
+  receipts:
+    description: Consent receipts and transparency logging
+    type: supporting
+    code: [services/receipts-log/]
+
+  wallet:
+    description: Mobile wallet application
+    type: core
+    subdomains:
+      onboarding:
+        description: First-run experience and identity verification
+        code: [mobile/shared/.../onboarding/, mobile/androidApp/.../onboarding/]
+      credentials:
+        description: Credential storage, display, and management
+        code: [mobile/shared/.../credentials/, mobile/androidApp/.../credentials/]
+      verification-flow:
+        description: QR scan, consent, presentation flow
+        code: [mobile/shared/.../verification/, mobile/androidApp/.../verification/]
+
+  common:
+    description: Shared types, value objects, and contracts across services
+    type: shared-kernel
+    code: [services/common/]
+
+  security:
+    description: Cryptographic operations, key management, threat model
+    type: core
+    code: [services/common/crypto/]
+
+  ux:
+    description: Design system, theming, shared UI components
+    type: supporting
+    code: [mobile/androidApp/.../ui/theme/, mobile/androidApp/.../ui/components/]
+
+  infra:
+    description: Deployment, Cloud Run, networking, service mesh
+    type: generic
+    code: [deploy/, terraform/]
+
+  cicd:
+    description: CI/CD pipelines, pre-commit hooks, release automation
+    type: generic
+    code: [.github/workflows/, scripts/]
+
+context-map:
+  - provider: issuance
+    consumers: [wallet]
+    pattern: open-host-service
+    contract: services/issuance-gateway/README.md
+
+  - provider: verification
+    consumers: [wallet]
+    pattern: anti-corruption-layer
+    contract: services/verifier/presentation/README.md
+
+  - provider: registry
+    consumers: [verification]
+    pattern: customer-supplier
+    contract: services/registry/README.md
+
+  - provider: common
+    consumers: [issuance, verification]
+    pattern: shared-kernel
+    contract: services/common/README.md
+```
+
+## Lifecycle
+
+1. **Init** — `/domain-tree:init` proposes the initial tree from codebase analysis
+2. **Classify** — Assign core/supporting/generic to each domain based on business value
+3. **Map** — Declare cross-context relationships in `context-map`
+4. **Grow** — Add domains/subdomains as the project evolves
+5. **Split** — When a domain gets too large, split into subdomains
+6. **Deprecate** — Mark domains `status: deprecated` before removing
+7. **Validate** — `/domain-tree:check` verifies the tree matches reality