@rmrdeveloper/sideroom-pi 8.13.0 → 8.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@rmrdeveloper/sideroom-pi",
|
|
3
|
-
"version": "8.
|
|
3
|
+
"version": "8.14.0",
|
|
4
4
|
"description": "Pi coding-agent package that asks clarifying questions, shows a live todo board, enforces coding guidelines, and will not call it done while your checks are red.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|
|
@@ -4,7 +4,7 @@ description: "Improve an existing codebase for long-term maintainability and sca
|
|
|
4
4
|
license: MIT
|
|
5
5
|
metadata:
|
|
6
6
|
author: RMRdeveloper
|
|
7
|
-
version: "1.
|
|
7
|
+
version: "1.1"
|
|
8
8
|
---
|
|
9
9
|
|
|
10
10
|
# Sideroom codebase design
|
|
@@ -33,6 +33,29 @@ A review request does not authorize a rewrite. An implementation request does
|
|
|
33
33
|
not require pausing after every recommendation. Ask only about consequential
|
|
34
34
|
choices or missing facts that the user and repository have not settled.
|
|
35
35
|
|
|
36
|
+
## Vocabulary (use these terms exactly)
|
|
37
|
+
|
|
38
|
+
Use these terms consistently in all recommendations and designs. Do not substitute "component", "service", "API", "boundary", "unit" or similar loose words. Consistent language is the point.
|
|
39
|
+
|
|
40
|
+
| Term | Meaning | Avoid |
|
|
41
|
+
|------|---------|-------|
|
|
42
|
+
| **Module** | Anything with an interface and an implementation. Scale-agnostic: a function, class, package, or tier-spanning slice. | unit, component, service |
|
|
43
|
+
| **Interface** | Everything a caller must know to use the module correctly: the type signature, plus invariants, ordering constraints, error modes, required configuration, and relevant performance or resource behaviour. | API, signature |
|
|
44
|
+
| **Implementation** | The code inside the module. Distinct from Adapter. | — |
|
|
45
|
+
| **Depth** | Leverage at the interface: the amount of useful behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation. | — |
|
|
46
|
+
| **Seam** | A place where you can alter behaviour without editing in that place (Michael Feathers). It is the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. | boundary |
|
|
47
|
+
| **Adapter** | A concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance. | — |
|
|
48
|
+
| **Leverage** | What callers get from depth: more capability per unit of interface they learn. One implementation pays back across many call sites and tests. | — |
|
|
49
|
+
| **Locality** | What maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. | — |
|
|
50
|
+
|
|
51
|
+
**Principles that follow from the vocabulary:**
|
|
52
|
+
- Depth is a property of the **interface**, not of the implementation size. A deep module can be internally composed of small, mockable, swappable parts; they just aren't part of the interface.
|
|
53
|
+
- The **deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across callers, it was earning its keep.
|
|
54
|
+
- The interface is the test surface. Callers and tests cross the same seam. If you want to test past the interface, the module is probably the wrong shape.
|
|
55
|
+
- One adapter means a hypothetical seam. Two adapters (e.g. production + test stand-in) means a real one. Don't introduce a seam unless something actually varies across it.
|
|
56
|
+
|
|
57
|
+
When writing recommendations, use these terms. Explain any necessary design term once if the user is unfamiliar, then stick to them. Respect the project's existing domain vocabulary (`CONTEXT.md` or equivalent) for business concepts — do not replace established domain names just to impose this design glossary.
|
|
58
|
+
|
|
36
59
|
## Inspect before recommending
|
|
37
60
|
|
|
38
61
|
1. Read project instructions, existing domain vocabulary (`CONTEXT.md`, or the
|
|
@@ -55,6 +78,8 @@ choices or missing facts that the user and repository have not settled.
|
|
|
55
78
|
|
|
56
79
|
## Design principles
|
|
57
80
|
|
|
81
|
+
Apply the vocabulary above. In particular:
|
|
82
|
+
|
|
58
83
|
- A **module** presents an **interface** and hides an implementation. Its
|
|
59
84
|
interface includes everything callers must understand: inputs, outputs,
|
|
60
85
|
invariants, errors, ordering, configuration, and relevant resource behavior.
|
|
@@ -141,6 +166,8 @@ verification, and unresolved facts. After implementation, report changes,
|
|
|
141
166
|
checks, and remaining limitations. Keep review results in the conversation
|
|
142
167
|
unless the user requests a document. No graphic or HTML artifact is produced.
|
|
143
168
|
|
|
169
|
+
**Use the design vocabulary (module, interface, depth, seam, adapter, leverage, locality) consistently** in all recommendations and designs.
|
|
170
|
+
|
|
144
171
|
## Attribution
|
|
145
172
|
|
|
146
173
|
Adapted from Matt Pocock's
|