mikeparcewski/wicked-garden / skills/domain
wicked-garden-domain
VerifiedThe FOUNDATIONAL domain-model capability: extract a codebase's domain — testable business rules (with confidence + provenance), entities, requirements — as a schema-conformant model on the estate graph. The workers annotate the store; wicked-core reads it and builds the requirements graph, fail-closed below the configured minimum share of real requirements (80% by default). Steers three workers. A shared substrate, not a modernization tool. The `modernize` archetype DERIVES from it; build / migrate / review / specify / explore consume the SAME domain model — none OWN it. Use when: "extract the business rules / domain model from this codebase", "build a requirements graph from the code", "what does this system actually require", "reverse-engineer the domain before we build/port/migrate". Works on ANY codebase (modern or legacy) — the value is the domain model, not the porting. NOT the code transform itself (that is the archetype consuming this model). This skill produces the DOMAIN MODEL, not new code.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.3 KB |
| refs/domain-model-emit.md | markdown | 6.9 KB |
| refs/extraction-flow.md | markdown | 8.6 KB |
| refs/fixtures/example-domain-model.json | config | 6.7 KB |
refs/extraction-flow.md
View on GitHub# extraction-flow — how the extractor drives estate + core (with the mock seam)
The modernize workers never import estate or core code. They talk to a **fixed
interface** and — depending on whether the peer CLIs are installed — either the
**real CLI** (`scripts/domain/_clients.py`) or, hermetically, a **mock**
(`scripts/domain/_mocks.py`). This ref documents the interface (the real
CLI/engine contract) and the mock seam.
## Which implementation runs (the seam)
`scripts/domain/_clients.py` picks the backing at call time, mirroring
`scripts/_loom.py`'s precedence:
- `estate_client(db)` → the CLI-backed `CliEstateClient` when **`wicked-estate`**
resolves (`WICKED_ESTATE_BIN` env → config.json `tool_preferences.wicked-estate`
→ PATH → `node_modules/.bin`) **and** a store path is given; else the
fixture-backed `_mocks.EstateClient`.
- `core_client()` → the CLI-backed `CliCoreClient` when **`wicked-core`** resolves
(`WICKED_CORE_BIN` → config.json `tool_preferences.wicked-core` → PATH →
`node_modules/.bin`); else `None`, and the caller falls back to the hermetic
`_mocks.BrainClient` + `emit_domain_model` doc-assembly lane. Set-but-empty
`WICKED_*_BIN` is the kill-switch (force mock).
## The estate surface (what the extractor + modeler call)
estate is the sole authority for graph structure. In production the workers shell
its CLI (`CliEstateClient`); hermetically they call `_mocks.EstateClient`, which
returns canned fixtures and records writes. Same six method names either way:
| Method | Production CLI | Purpose |
|---|---|---|
| `read_clusters(params) -> [Community]` | `clusters --json --summary` | Full community membership (the `members:[symbol_id]` feed). The MCP `Communities` tool omits members, so the CLI (with `--summary`, for the object shape) is the contract. |
| `resolve(name, file?, kind?) -> [symbol_id]` | `resolve <name> --json [--file EXACT] [--kind]` | name → SymbolId. Returns an **object array**; the client extracts each `.symbol_id`. `--file` is **exact `location.file` equality**, not a basename. **A write keyed on a bare name is a silent no-op / silent fan-out** — always resolve first. |
| `annotate(symbol_id, type, key, value, confidence, provenance, replace)` | `annotate --symbol <id> --type … --key … --value … [--confidence] [--provenance] --replace` | Typed k/v annotation (multi-valued). The client **always** passes `--symbol` (a bare name fans out to every search hit) and **always** `--replace` (the CLI defaults to APPEND, which stacks duplicate rows across re-index runs). |
| `set_requirement(symbol_id, requirement, validated)` | `semantics <id> --requirement … --validated true\|false` | The single canonical requirement↔symbol link (node_semantics — a **separate** subcommand from `annotate`). |
| `read_annotations(symbol_id) -> [Annotation]` | `annotations --symbol <id> --json` | Read back. **Must** use `--symbol` — the positional `annotations <name>` form name-*searches* and returns an array, so a SymbolId there matches nothing and yields `[]` silently. `--symbol` returns the single-symbol object `{symbol, annotations[]}`. |
| `find_by_annotation(key, value?) -> [symbol_id]` | *(no CLI verb)* | Reverse lookup. **Not available on the CLI-backed path** — there is no reverse-annotation verb, and the real extractor resolves forward (name → SymbolId → annotate), so `CliEstateClient.find_by_annotation` raises. Mock-lane only. |
### The two coordinated writes per bound rule
Ported from anti-legacy's `annotate()`, both keyed by SymbolId, **neither copying
symbol structure**. On the real CLI each field is a **separate argument** — there
is no pipe-packed string:
1. **Native projection into estate** (so estate queries see it): a typed
annotation `annotate(symbol_id, type=<t>, key=<rule_id>, value=<statement>,
confidence=<c>, provenance=<p>, replace=True)`, where `type` is
`"business_rule"` when the rule is RESOLVED (confidence at/above the threshold)
or `"risk"` when it is below threshold.
2. **The canonical requirement link**: `set_requirement(symbol_id,
requirement=<statement>, validated=<resolved>)` (`semantics`). This is what the
later `wicked-core domain-graph` read counts: a resolved link is a real
requirement, a RISK one a placeholder that the minimum never counts.
The traceability thread the workers must not break:
`estate node (native file/line) → requirement/annotation → business_rules[].id →
legacy_components[] → crew task → UAT verdict`. A broken link is a gate failure,
not a warning.
## The core surface (owns doc assembly — the inversion)
**core owns the domain-model build.** The modeler does **not** hand core an
assembled document; it annotates the estate store (via the estate surface above),
then invokes core, which **reads the store and builds the requirements graph
itself**, saving it back into the store (the source of truth; crew reads it from
there). `CliCoreClient`:
| Method | Production | Purpose |
|---|---|---|
| `domain_graph(db, out, coverage?) -> doc` | `wicked-core domain-graph --db <db> --out requirements_graph.json [--coverage F]` | Reads the annotated store, **recomputes front-half coverage**, and builds the capability plan. **Fails closed below the configured minimum** (writes nothing, non-zero exit, "N% real requirements, minimum M% (…)"; only resolved behaviours count, placeholders never) — `--min-coverage-pct`, else the repository's own minimum (`wicked-core requirements-target`), else `WICKED_REQUIREMENTS_MIN_COVERAGE_PCT` (crew's `requirementsGraph.minCoveragePct`), else 80. At or above it, the graph is saved into the estate store with or without `--out` (domain, requirement and business-rule nodes, `SatisfiedBy` edges to code); `--out` writes the same document as a JSON export, and without it no file is written (the `domain-extraction` preset passes `--repo-root <dir>`, whose tracked files the corroboration reads, and no `--out`). A supplied `--coverage` file is an optional cross-check that must agree. |
| `coverage(db, out) -> report` | `wicked-core coverage --db <db> --out coverage.json` | Emit the store's front-half coverage report (optional — `domain_graph` recomputes internally). `--min-coverage-pct` makes it a check: exit 3 below the configured minimum. |
There is **no `--overlay`** and **no doc-in/summary-out** shape: the store is the
input, the built doc is the output. Garden's `validate_domain_model.py` then runs
as a **consumer-side cross-check** on core's output against the vendored schema.
## Config-driven miner kind-sets (invariant 6)
The extractor must read the behavior/type/structural kind-sets from
`config.coverage.*`, **never hardcode** them. The generic modern defaults:
| Config key | Feeds | Modern default |
|---|---|---|
| `coverage.behavior_kinds` | domain actions/verbs | `["module","function","method"]` |
| `coverage.type_kinds` | domain entities/nouns | `["class","interface","struct","trait","enum","record"]` |
| `coverage.structural_kinds` | field-level nouns | `["field","variable"]` |
| `coverage.estate_behavior_kinds` | mainframe/IaC only | `[]` for a pure modern repo; `["db2_table","cics_program","step"]` on a mainframe estate |
`emit_domain_model.py` accepts a `config` dict and defaults to these — the same
document contract serves a COBOL estate and a Rust monorepo. (These mirror
`wicked-core`'s `CoverageConfig.behavior_other_tags`; core is the coverage
authority on the real path.)
## The disjoint-build mock seam
`scripts/domain/_mocks.py` remains the hermetic lane: garden builds + tests
its side against fixtures while estate and core build theirs. The real path
(`_clients.py`) shells the peer CLIs — argv lists, never a shell string — so the
"imports NO other-product code" doctrine holds either way. The mocks:
- `EstateClient` — canned `read_clusters()` (a two-community fixture with member
SymbolIds), `resolve()` (name → deterministic fixture SymbolId), and
`annotate()`/`set_requirement()` that **record** calls so a test can assert the
write happened (the anti-legacy silent-no-op scar is caught by asserting the
recorded id is a real SymbolId, never a bare name).
- `BrainClient` — the **hermetic doc-assembly lane** only (`build_domain_graph(doc)`
returns a `{domains, requirements, dropped}` summary and `validate()` runs the
stdlib draft-07 schema check). This does **not** model the real core flow (which
reads the store); it exists so `emit_domain_model.py` can assemble + validate a
document with no peers present. On the real path, `core_client()` returns a
`CliCoreClient` and this stand-in is not used.
**No other-product code is imported.** When the peer CLIs are present the
`_clients.py` factories swap in the CLI-backed impls — the workers don't change.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |