@regardio/dev 2.4.1 → 2.6.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/README.md +1 -1
- package/dist/bin/ship/hotfix.bin.mjs +23 -25
- package/dist/bin/ship/production.bin.mjs +24 -26
- package/dist/bin/ship/staging.bin.mjs +1 -1
- package/dist/bin/ship/{utils-rnvdLrkF.mjs → utils-sL-BT4MX.mjs} +11 -3
- package/docs/en/README.md +11 -3
- package/docs/en/documentation.md +170 -0
- package/docs/en/principles.md +83 -0
- package/docs/en/tools/biome.md +6 -18
- package/docs/en/tools/husky.md +3 -6
- package/docs/en/tools/markdownlint.md +3 -12
- package/docs/en/tools/releases.md +137 -160
- package/docs/en/tools/vitest.md +1 -1
- package/docs/en/writing.md +118 -0
- package/package.json +3 -3
- package/templates/actions/forgejo-release.yml +116 -0
- package/templates/actions/github-release.yml +93 -0
- package/templates/agents/CLAUDE.md +37 -0
- package/templates/versionrc/.versionrc.json +42 -10
- package/templates/github/release.yml +0 -68
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
|
|
3
3
|
title: "Release Workflow"
|
|
4
|
-
description: "
|
|
5
|
-
publishedAt: 2026-
|
|
4
|
+
description: "GitLab-flow release workflow for Regardio repos — branches mirror environments, ship tooling drives versioning, CI carries it out."
|
|
5
|
+
publishedAt: 2026-05-07
|
|
6
6
|
language: "en"
|
|
7
7
|
status: "published"
|
|
8
8
|
kind: "guide"
|
|
@@ -11,115 +11,92 @@ area: "dev"
|
|
|
11
11
|
|
|
12
12
|
# Release Workflow
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
Branches mirror environments. `main` is where development happens. `staging` reflects what is deployed to the staging server. `production` reflects what is live. Version bumps happen locally at ship time — CI on `production` carries the result out (publishes to npm or deploys to a server).
|
|
15
15
|
|
|
16
|
-
##
|
|
16
|
+
## The Three-Branch Model
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
```text
|
|
19
|
+
main ──── ship:staging ────► staging (optional staging server)
|
|
20
|
+
│
|
|
21
|
+
└──── ship:production ──► production (live / npm)
|
|
22
|
+
│
|
|
23
|
+
sync back to staging
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
| Branch | Contains | CI role |
|
|
27
|
+
|--------|----------|---------|
|
|
28
|
+
| `main` | All committed, tested work | None (Husky runs local gates on commit) |
|
|
29
|
+
| `staging` | Deployed to staging server or preview | Verify + deploy to staging |
|
|
30
|
+
| `production` | Only shipped, versioned releases | Verify + deploy or publish |
|
|
31
|
+
|
|
32
|
+
**Why version bumps happen locally, not in CI.** Hotfixes start from `production` and must write their version bump back up through `staging` and `main` in one pass. Keeping the bump local means both the normal ship path and the hotfix path behave identically — there is no special case in CI.
|
|
33
|
+
|
|
34
|
+
## Hotfix Flow
|
|
35
|
+
|
|
36
|
+
A hotfix is an urgent fix that must go to production immediately, without pulling in unreleased changes from `main`.
|
|
19
37
|
|
|
20
38
|
```text
|
|
21
|
-
|
|
39
|
+
production ──► hotfix/<name> (fix here with conventional commits)
|
|
40
|
+
│
|
|
41
|
+
└──► production ──► staging ──► main
|
|
22
42
|
```
|
|
23
43
|
|
|
24
|
-
|
|
25
|
-
- **`staging`** — optional validation environment. No versioning happens here.
|
|
26
|
-
- **`production`** — versioned, published code only.
|
|
44
|
+
`ship:hotfix start <name>` creates the branch from `production`, not from `main`. This is deliberate: it avoids accidentally shipping work-in-progress that has not yet been reviewed for production.
|
|
27
45
|
|
|
28
|
-
|
|
46
|
+
`ship:hotfix finish` versions the fix, merges it into `production`, then propagates through `staging` and back to `main` so nothing is lost.
|
|
29
47
|
|
|
30
|
-
##
|
|
48
|
+
## Commands
|
|
31
49
|
|
|
32
|
-
|
|
50
|
+
| Command | Purpose |
|
|
51
|
+
|---------|---------|
|
|
52
|
+
| `pnpm ship:staging` | Fast-forward `main` → `staging`, push. Triggers staging CI. |
|
|
53
|
+
| `pnpm ship:production` | Version selected packages (if any), fast-forward `main` → `production`, sync `staging`. Triggers production CI. |
|
|
54
|
+
| `pnpm ship:hotfix start <name>` | Create `hotfix/<name>` from `production`. |
|
|
55
|
+
| `pnpm ship:hotfix finish` | Version selected packages (if any), merge hotfix → `production` → `staging` → `main`. |
|
|
33
56
|
|
|
34
|
-
|
|
35
|
-
2. **You choose the bump per package at ship time.** When running `ship-production` or `ship-hotfix finish`, every publishable package is listed and you assign it `0` (skip), `1` (patch), `2` (minor), or `3` (major). Packages you skip are untouched. The conventional commits in the log inform each choice; the decisions are always explicit.
|
|
36
|
-
3. **Version numbers are a production guarantee.** Bumps are applied only at `ship-production` time. Every version tag in git and every release on npm corresponds to code that has been validated and shipped.
|
|
37
|
-
4. **Staging is optional.** You can ship directly from `main` to `production`. Use `ship-staging` when you want to test changes in a staging environment first.
|
|
38
|
-
5. **Tests are a local gate, not a CI gate.** Quality checks (`lint`, `typecheck`, `test`) run on your machine before any commit is made. Broken code cannot enter the repository.
|
|
39
|
-
6. **You always land back on `main`.** Every command returns you to `main` when it finishes.
|
|
57
|
+
## Versioning — Per-Package, at Ship Time
|
|
40
58
|
|
|
41
|
-
|
|
59
|
+
`ship:production` and `ship:hotfix finish` discover all workspace packages that have a `.versionrc.json` and ask you to assign a bump type to each:
|
|
42
60
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
│ ff-merge main → staging │
|
|
48
|
-
└──────────────────────────┘
|
|
49
|
-
│
|
|
50
|
-
(validated in staging)
|
|
51
|
-
│
|
|
52
|
-
▼
|
|
53
|
-
ship-production
|
|
54
|
-
┌──────────────────────────┐
|
|
55
|
-
│ quality checks on main │
|
|
56
|
-
│ select packages/bumps │
|
|
57
|
-
│ pnpm release:<type>* │
|
|
58
|
-
main ───────────┤ bumps version + ├──► production
|
|
59
|
-
│ rewrites CHANGELOG.md │
|
|
60
|
-
│ ff-merge main → prod │
|
|
61
|
-
│ ff-merge prod → staging │
|
|
62
|
-
│ push --follow-tags main │
|
|
63
|
-
└──────────────────────────┘
|
|
64
|
-
│
|
|
65
|
-
(CI: pnpm -r publish → npm)
|
|
66
|
-
▼
|
|
67
|
-
production
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
ship-hotfix start fix-name
|
|
71
|
-
┌──────────────────────────┐
|
|
72
|
-
production ─────┤ create hotfix/fix-name ├──► hotfix/fix-name
|
|
73
|
-
└──────────────────────────┘
|
|
74
|
-
│
|
|
75
|
-
(author fixes with conventional commits)
|
|
76
|
-
│
|
|
77
|
-
ship-hotfix finish
|
|
78
|
-
┌──────────────────────────┐
|
|
79
|
-
│ quality checks │
|
|
80
|
-
│ pnpm release:<type>* │
|
|
81
|
-
hotfix/fix-name ┤ bumps version + ├──► production → staging → main
|
|
82
|
-
│ rewrites CHANGELOG.md │
|
|
83
|
-
│ merge to production │
|
|
84
|
-
│ propagate to staging │
|
|
85
|
-
│ propagate to main │
|
|
86
|
-
└──────────────────────────┘
|
|
87
|
-
```
|
|
61
|
+
- `0` — skip (no version change)
|
|
62
|
+
- `1` — patch
|
|
63
|
+
- `2` — minor
|
|
64
|
+
- `3` — major
|
|
88
65
|
|
|
89
|
-
|
|
66
|
+
For each selected package, `commit-and-tag-version` runs from within that package's directory, reading the package's own `.versionrc.json`. It bumps the `version` field in `package.json`, rewrites `CHANGELOG.md` to include only commits that touched files under that package's directory (`gitRawCommitsOpts.path: "."`), commits the bump, and creates a scoped tag (e.g. `@regardio/dev@v1.2.0`).
|
|
90
67
|
|
|
91
|
-
|
|
92
|
-
|--------|----------|-----------------|
|
|
93
|
-
| `main` | All committed, tested work | Only after `ship-production` / `ship-hotfix finish` |
|
|
94
|
-
| `staging` | Synced from `production` after each ship, or from `main` via `ship-staging` | After a ship propagates |
|
|
95
|
-
| `production` | Only shipped, versioned releases | Yes — always |
|
|
68
|
+
If no packages have a `.versionrc.json`, the versioning UI is skipped and `ship:production` proceeds directly to the git merge.
|
|
96
69
|
|
|
97
|
-
|
|
70
|
+
## CI — What Happens on Each Branch
|
|
98
71
|
|
|
99
|
-
CI
|
|
72
|
+
CI behaviour differs by what the repo produces.
|
|
100
73
|
|
|
101
|
-
|
|
102
|
-
2. Runs `pnpm -r publish --access public --no-git-checks` — publishes every workspace package whose current version is not yet on npm, skipping `private: true` packages
|
|
103
|
-
3. Tags are already present (pushed by `ship-production` via `--follow-tags`)
|
|
74
|
+
### Publishing monorepos
|
|
104
75
|
|
|
105
|
-
|
|
76
|
+
- **staging**: Run typecheck and tests. Nothing is published.
|
|
77
|
+
- **production**: Run typecheck, tests, then `pnpm -r publish --access public --no-git-checks`. Only packages whose current version is not yet on npm are published — packages with `"private": true` are skipped automatically.
|
|
106
78
|
|
|
107
|
-
|
|
108
|
-
|---------|-------|---------|
|
|
109
|
-
| `pnpm release` | auto | Bump version from conventional commits, update CHANGELOG.md, commit |
|
|
110
|
-
| `pnpm release:patch` | explicit | Force a patch bump |
|
|
111
|
-
| `pnpm release:minor` | explicit | Force a minor bump |
|
|
112
|
-
| `pnpm release:major` | explicit | Force a major bump |
|
|
113
|
-
| `ship-staging` | `ship-staging` | (Optional) Deploy changes to staging for testing |
|
|
114
|
-
| `ship-production` | `ship-production` | Bump version, merge main → production, trigger publish |
|
|
115
|
-
| `ship-hotfix start <name>` | `ship-hotfix start <name>` | Create a hotfix branch from production |
|
|
116
|
-
| `ship-hotfix finish` | `ship-hotfix finish` | Bump version, propagate hotfix through production → staging → main |
|
|
79
|
+
### Server-deployed apps with Docker
|
|
117
80
|
|
|
118
|
-
|
|
81
|
+
- **staging**: Run tests, build the Docker image, push to the container registry, trigger a staging deploy (e.g. Coolify webhook).
|
|
82
|
+
- **production**: Run typecheck + tests, build and push the Docker image, trigger a production deploy.
|
|
83
|
+
|
|
84
|
+
### Cloudflare Workers apps
|
|
85
|
+
|
|
86
|
+
- **staging**: Run tests, then `wrangler versions upload --preview-alias preview`.
|
|
87
|
+
- **production**: Run typecheck + tests, then `wrangler deploy`.
|
|
88
|
+
|
|
89
|
+
### Documentation / vocabulary repos
|
|
119
90
|
|
|
120
|
-
|
|
91
|
+
- **staging** and **production**: Verify the repo is well-formed (build, typecheck, test). No publishing or deployment — the repo is distributed via git clone, not npm.
|
|
121
92
|
|
|
122
|
-
|
|
93
|
+
### Static sites without a configured deployment
|
|
94
|
+
|
|
95
|
+
- **staging** and **production**: Run tests, typecheck (production only), and build. A deployment step is left as a TODO until the hosting platform is chosen.
|
|
96
|
+
|
|
97
|
+
## Typical Release Flow
|
|
98
|
+
|
|
99
|
+
### 1. Develop on `main` with conventional commits
|
|
123
100
|
|
|
124
101
|
```bash
|
|
125
102
|
feat: add user authentication # → minor bump
|
|
@@ -127,111 +104,111 @@ fix: resolve login redirect loop # → patch bump
|
|
|
127
104
|
feat!: redesign authentication API # → major bump
|
|
128
105
|
```
|
|
129
106
|
|
|
130
|
-
### 2.
|
|
107
|
+
### 2. (Optional) Test in staging first
|
|
131
108
|
|
|
132
109
|
```bash
|
|
133
|
-
pnpm ship:
|
|
110
|
+
pnpm ship:staging
|
|
134
111
|
```
|
|
135
112
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
1. Guard: must be on `main`, working tree clean
|
|
139
|
-
2. Fetch and verify `staging` + `production` branches exist
|
|
140
|
-
3. Show commits to be shipped
|
|
141
|
-
4. Run full quality suite on `main` — aborts on failure
|
|
142
|
-
5. For each publishable package: choose `0 (skip) / 1 (patch) / 2 (minor) / 3 (major)`
|
|
143
|
-
6. Confirm the planned bumps — abort if declined or all skipped
|
|
144
|
-
7. Run `pnpm release:<type>` at the root (highest bump type) — bumps versions, rewrites `CHANGELOG.md`, commits. If no release script exists, skip versioning.
|
|
145
|
-
8. Fast-forward merge `main` into `production` and push
|
|
146
|
-
9. Sync `staging` with `production`
|
|
147
|
-
10. Push `main` with `--follow-tags` to push all new version tags
|
|
148
|
-
11. Return to `main`
|
|
149
|
-
|
|
150
|
-
CI on `production` runs `pnpm -r publish` to push changed packages to npm.
|
|
113
|
+
Deploys `main` to `staging` without touching versions.
|
|
151
114
|
|
|
152
|
-
###
|
|
115
|
+
### 3. Ship to production
|
|
153
116
|
|
|
154
117
|
```bash
|
|
155
|
-
pnpm ship:
|
|
118
|
+
pnpm ship:production
|
|
156
119
|
```
|
|
157
120
|
|
|
158
|
-
|
|
121
|
+
1. Guard: must be on `main`, working tree clean.
|
|
122
|
+
2. Fetch and verify `staging` and `production` branches exist.
|
|
123
|
+
3. Show commits to be shipped.
|
|
124
|
+
4. Run full quality suite — aborts on failure.
|
|
125
|
+
5. If packages have `.versionrc.json`: assign a bump type to each; confirm the planned bumps.
|
|
126
|
+
6. If no packages have `.versionrc.json`: confirm whether to ship (versioning is skipped).
|
|
127
|
+
7. For each selected package: run `commit-and-tag-version --release-as <type>` from within the package directory.
|
|
128
|
+
8. Fast-forward merge `main` → `production`, push.
|
|
129
|
+
9. Sync `staging` with `production`, push.
|
|
130
|
+
10. Push `main` with `--follow-tags` to carry the new version tags.
|
|
131
|
+
11. Return to `main`.
|
|
159
132
|
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
For urgent fixes that must go directly to production:
|
|
133
|
+
### 4. Hotfix flow
|
|
163
134
|
|
|
164
135
|
```bash
|
|
165
136
|
pnpm ship:hotfix start fix-auth-bug
|
|
166
|
-
# apply
|
|
137
|
+
# apply fix with conventional commits
|
|
167
138
|
git add . && git commit -m "fix: ..."
|
|
168
139
|
pnpm ship:hotfix finish
|
|
169
140
|
```
|
|
170
141
|
|
|
171
|
-
`finish`
|
|
142
|
+
`finish` fetches origin, runs quality checks, assigns bump types (for packages with `.versionrc.json`), versions the fix, then merges `hotfix → production → staging → main` and deletes the hotfix branch.
|
|
172
143
|
|
|
173
144
|
## Adoption
|
|
174
145
|
|
|
175
|
-
|
|
146
|
+
### 1. Add ship scripts to `package.json`
|
|
147
|
+
|
|
148
|
+
```json
|
|
149
|
+
{
|
|
150
|
+
"scripts": {
|
|
151
|
+
"ship:hotfix": "ship-hotfix",
|
|
152
|
+
"ship:production": "ship-production",
|
|
153
|
+
"ship:staging": "ship-staging"
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
### 2. Add `.versionrc.json` to each package you want versioned
|
|
176
159
|
|
|
177
|
-
|
|
160
|
+
```bash
|
|
161
|
+
cp node_modules/@regardio/dev/templates/versionrc/.versionrc.json packages/my-pkg/.versionrc.json
|
|
162
|
+
```
|
|
178
163
|
|
|
179
|
-
|
|
164
|
+
Then replace both `@my-scope/my-pkg` placeholders in that file with your actual package name:
|
|
180
165
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
"release:patch": "commit-and-tag-version --release-as patch",
|
|
188
|
-
"ship:hotfix": "ship-hotfix",
|
|
189
|
-
"ship:production": "ship-production",
|
|
190
|
-
"ship:staging": "ship-staging"
|
|
191
|
-
}
|
|
192
|
-
}
|
|
193
|
-
```
|
|
166
|
+
```json
|
|
167
|
+
{
|
|
168
|
+
"tagPrefix": "@my-scope/my-pkg@v",
|
|
169
|
+
"releaseCommitMessageFormat": "chore(release): @my-scope/my-pkg@v{{currentTag}}"
|
|
170
|
+
}
|
|
171
|
+
```
|
|
194
172
|
|
|
195
|
-
|
|
173
|
+
`tagPrefix` scopes the git tag to the package. `releaseCommitMessageFormat` puts the full package identifier in the release commit subject, so the monorepo history reads `chore(release): @my-scope/my-pkg@v1.2.0` rather than a bare version number.
|
|
196
174
|
|
|
197
|
-
|
|
175
|
+
Every `.versionrc.json` must include `"gitRawCommitsOpts": { "path": "." }` to filter the git log to commits that actually touched files under that package's directory. Without this, the changelog accumulates noise from unrelated packages.
|
|
198
176
|
|
|
199
|
-
|
|
200
|
-
cp node_modules/@regardio/dev/templates/versionrc/.versionrc.json packages/my-pkg/.versionrc.json
|
|
201
|
-
# then set "tagPrefix": "@my-scope/my-pkg@v" inside that file
|
|
202
|
-
```
|
|
177
|
+
For a single-package repo, place `.versionrc.json` at the root instead.
|
|
203
178
|
|
|
204
|
-
|
|
179
|
+
### 3. Create the branches
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
git checkout -b staging && git push -u origin staging
|
|
183
|
+
git checkout -b production && git push -u origin production
|
|
184
|
+
git checkout main
|
|
185
|
+
```
|
|
205
186
|
|
|
206
|
-
|
|
187
|
+
### 4. Copy and adapt the CI workflow
|
|
207
188
|
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
```
|
|
189
|
+
```bash
|
|
190
|
+
# Forgejo / Codeberg
|
|
191
|
+
mkdir -p .forgejo/workflows
|
|
192
|
+
cp node_modules/@regardio/dev/templates/actions/forgejo-release.yml .forgejo/workflows/release.yml
|
|
213
193
|
|
|
214
|
-
|
|
194
|
+
# GitHub
|
|
195
|
+
mkdir -p .github/workflows
|
|
196
|
+
cp node_modules/@regardio/dev/templates/actions/github-release.yml .github/workflows/release.yml
|
|
197
|
+
```
|
|
215
198
|
|
|
216
|
-
|
|
217
|
-
# GitHub
|
|
218
|
-
mkdir -p .github/workflows
|
|
219
|
-
cp node_modules/@regardio/dev/templates/github/release.yml .github/workflows/release.yml
|
|
199
|
+
Both templates cover the npm-publishing case. Adapt the publish job for Docker / Cloudflare deployments as described in the CI section above.
|
|
220
200
|
|
|
221
|
-
|
|
222
|
-
mkdir -p .forgejo/workflows
|
|
223
|
-
cp node_modules/@regardio/dev/templates/github/release.yml .forgejo/workflows/release.yml
|
|
224
|
-
```
|
|
201
|
+
### 5. First publish of any new package must be done locally
|
|
225
202
|
|
|
226
|
-
|
|
203
|
+
```bash
|
|
204
|
+
pnpm build && npm publish --access public
|
|
205
|
+
```
|
|
227
206
|
|
|
228
|
-
|
|
229
|
-
pnpm build && npm publish --access public
|
|
230
|
-
```
|
|
207
|
+
CI publishes subsequent versions; the very first one requires a local publish because the package does not yet exist on npm.
|
|
231
208
|
|
|
232
209
|
## Quality Gates
|
|
233
210
|
|
|
234
|
-
Every ship command enforces the same gates
|
|
211
|
+
Every ship command enforces the same gates before any commit or merge:
|
|
235
212
|
|
|
236
213
|
```bash
|
|
237
214
|
pnpm build # Must succeed
|
|
@@ -239,11 +216,11 @@ pnpm typecheck # Must succeed
|
|
|
239
216
|
pnpm test # Must succeed
|
|
240
217
|
```
|
|
241
218
|
|
|
242
|
-
##
|
|
219
|
+
## Publishing vs Non-Publishing Repos
|
|
243
220
|
|
|
244
|
-
Packages
|
|
221
|
+
Packages with `"private": true` are skipped by `pnpm -r publish` automatically — CI only publishes public packages to npm.
|
|
245
222
|
|
|
246
|
-
|
|
223
|
+
Whether a package is published to npm is independent of whether it gets versioned. The ship tooling uses `.versionrc.json` presence as the signal for versioning, not the `private` flag. A private channel app or a vocabulary repo can run `ship:production`, get a version bump, a CHANGELOG entry, and a scoped git tag, without ever touching npm.
|
|
247
224
|
|
|
248
225
|
## Related
|
|
249
226
|
|
package/docs/en/tools/vitest.md
CHANGED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
---
|
|
2
|
+
|
|
3
|
+
title: "Writing"
|
|
4
|
+
description: "Voice, tone, and language Regardio content carries, in English and German."
|
|
5
|
+
publishedAt: 2026-04-17
|
|
6
|
+
order: 2
|
|
7
|
+
language: "en"
|
|
8
|
+
status: "published"
|
|
9
|
+
kind: "concept"
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
The voice in which Regardio writes about itself and its tools.
|
|
13
|
+
|
|
14
|
+
## What you are doing
|
|
15
|
+
|
|
16
|
+
You write *from within* the System, not *about* it. Your aim is to trigger recognition. The reader you are writing for should be able to think *Yes, that's how it is.*
|
|
17
|
+
|
|
18
|
+
Two trains of thought carry everything the System does — and everything you write about it.
|
|
19
|
+
|
|
20
|
+
**Any one object can be observed from two sides.** Front and back, inside and outside, past and future, still and moving, question and answer, start and finish. A thing that looks complete from one angle shows something new from the other. Writing that only shows one side flattens what it describes. Writing that acknowledges both gives the reader room to stand where they already stand.
|
|
21
|
+
|
|
22
|
+
**A whole becomes graspable when it is cut into a few distinct parts.** Six is the number to return to: enough variety to cover what matters, few enough to hold in the head at once, clear enough to name and locate each piece. A pie cut into six slices is something anyone can picture. When a subject resists clarity, the move is not more words — it is better cuts.
|
|
23
|
+
|
|
24
|
+
These two habits are the grammar underneath the System. Carry them quietly. You rarely name them. They are just the shape of the thinking.
|
|
25
|
+
|
|
26
|
+
## How to meet the reader
|
|
27
|
+
|
|
28
|
+
Every reader comes with their own life and their own pursuit. Assume they notice things for themselves. Trust them to do their own connecting. Address them directly, without talking up or down.
|
|
29
|
+
|
|
30
|
+
The ground under the writing is careful observation of how people actually feel, think, and act — not advice about how they should. When an idea becomes personally recognizable while staying broadly true, it has landed. When it only flatters or only instructs, it hasn't.
|
|
31
|
+
|
|
32
|
+
## Stance
|
|
33
|
+
|
|
34
|
+
Six movements carry every piece.
|
|
35
|
+
|
|
36
|
+
1. **Derive, don't declare.** One thought leads to the next. "The System recognizes…" speaks from above. Better: the observation that leads to the structure. Readers follow a line of thought, not an instruction.
|
|
37
|
+
2. **Observe, don't instruct.** Write like someone who has listened carefully and is sharing an observation, not like someone explaining a method.
|
|
38
|
+
3. **Structure offers freedom, not rules.** The cuts exist to widen a view that has become too narrow, not to discipline one that is already broad.
|
|
39
|
+
4. **Suggest possibilities to choose from.** Offer angles, not answers. Let the reader decide what fits. Suggest questions that people have, not riddles to solve.
|
|
40
|
+
5. **Turned toward what could be, without promises.** Warm, attentive, spacious. Curious about people rather than diagnostic. No salvation talk, no coaching register.
|
|
41
|
+
6. **Good humor makes the deepest thought approachable.** Lightness when it fits. Not forced, not absent. When the moment is right, a small wink can carry weight without claiming it.
|
|
42
|
+
|
|
43
|
+
## Before and after
|
|
44
|
+
|
|
45
|
+
**Instead of:** *"Apply this framework to align your team."*
|
|
46
|
+
**Try:** *"What does the decision we made last week have to do with what's slowing us down now?"*
|
|
47
|
+
|
|
48
|
+
**Instead of:** *"The System helps you gain clarity."*
|
|
49
|
+
**Try:** *"A few angles worth looking at, whatever the pursuit."*
|
|
50
|
+
|
|
51
|
+
**Instead of:** *"Pursuits flourish with a clear core."*
|
|
52
|
+
**Try:** *"How will we know when we've arrived?"*
|
|
53
|
+
|
|
54
|
+
The System's questions are not headers. They are real questions, worth sitting with.
|
|
55
|
+
|
|
56
|
+
## Language
|
|
57
|
+
|
|
58
|
+
Language that leaves room lets readers think. Language that pushes does the thinking for them. Given the choice, choose room.
|
|
59
|
+
|
|
60
|
+
**Favor:** notice, explore, find, might, could, pattern, rhythm, carry, hold — words that leave room.
|
|
61
|
+
|
|
62
|
+
**Avoid:** must, potential, resources, values, purpose, sustainability, growth, leverage, empower, ownership, good, bad. These either push or have been worn down to noise.
|
|
63
|
+
|
|
64
|
+
**No method jargon.** Not from business, not from coaching, not from therapy, not from spirituality. If a term has a clear everyday word behind it, use the everyday word.
|
|
65
|
+
|
|
66
|
+
**People are not categories.** Describe what people do and bring about, not what they are. This is also how gendered forms are handled — name actions, not groups.
|
|
67
|
+
|
|
68
|
+
**The System is humane.** Equal, free cooperation is built in. Avoid connotations of hierarchy, ownership, dominance, control, or force. Reflect that without announcing it.
|
|
69
|
+
|
|
70
|
+
**Complexity earns its place or goes.** Make hard ideas reachable without flattening them. If a sentence has to be read twice, shorten it. If an idea has been reduced past recognition, let it breathe again.
|
|
71
|
+
|
|
72
|
+
## System terms
|
|
73
|
+
|
|
74
|
+
System terms carry precisely defined concepts. Use them as they are; don't swap in synonyms for variety. When tempted to reach for a buzzword, reach for a System term instead — if it fits. If no System term fits, the buzzword probably isn't earning its place either.
|
|
75
|
+
|
|
76
|
+
In every language the System is written in, the terms are chosen to capture the spirit of each concept in that language — not to translate literally from another. Don't import words from other languages into the prose. Let each language stand on its own.
|
|
77
|
+
|
|
78
|
+
## Roots, kept in the background
|
|
79
|
+
|
|
80
|
+
The System draws from many traditions of thought. Reference intents and ideas, not names or schools. The sources show themselves in the structure, not in citation. This is working craft carried by collective intelligence, not an elaborate treatise.
|
|
81
|
+
|
|
82
|
+
## Format and craft
|
|
83
|
+
|
|
84
|
+
**Headers** for orientation. **Prose** for connected thought. **Bold** for System terms at first introduction. *Italics* for genuine emphasis. No emojis. Lists only when the content is genuinely a list — bullets never replace a thought.
|
|
85
|
+
|
|
86
|
+
## Language-specific caveats
|
|
87
|
+
|
|
88
|
+
### German
|
|
89
|
+
|
|
90
|
+
- Address the reader with *du* unless the context clearly calls for *Sie* (formal contracts, legal notices). Keep it direct, without affectation.
|
|
91
|
+
- No gendering artifacts: no *:innen*, no asterisks, no *(m/w/d)*. Prefer action-based descriptions over group labels: *wer etwas vorhat*, *ein Mensch, der …*, *die Person, die …*, *Mitwirkende*, *Beteiligte*.
|
|
92
|
+
- Quotation marks: German low-high („…") in body text.
|
|
93
|
+
|
|
94
|
+
### English
|
|
95
|
+
|
|
96
|
+
- American English: *organize*, *color*, *toward*, *behavior*, *center*. Periods and commas inside quotation marks.
|
|
97
|
+
- No gendered forms. Name actions: *the person pursuing this*, *contributors*, *those involved*. Singular *they* is fine where a pronoun is unavoidable.
|
|
98
|
+
- Quotation marks: straight double quotes (") in Markdown source; typographic quotes ("…") in rendered prose.
|
|
99
|
+
|
|
100
|
+
## Check before publishing
|
|
101
|
+
|
|
102
|
+
- Does it sound like a conversation the reader would want to be in?
|
|
103
|
+
- Does the text derive rather than declare?
|
|
104
|
+
- Are abstract thoughts grounded in concrete examples?
|
|
105
|
+
- Are System terms used consistently, in their precise meaning?
|
|
106
|
+
- Is it free of coaching register, pigeonholing, and tired buzzwords?
|
|
107
|
+
- Could the honest response be *"Yes, that's how it is"*?
|
|
108
|
+
|
|
109
|
+
*This guide is itself a living text. When in doubt: would you enjoy reading this?*
|
|
110
|
+
|
|
111
|
+
## Related
|
|
112
|
+
|
|
113
|
+
- [Documentation](./documentation.md) — How Regardio shapes its documents
|
|
114
|
+
- [Principles](./principles.md) — Shared principles
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
**License**: [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) © Regardio
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://www.schemastore.org/package.json",
|
|
3
3
|
"name": "@regardio/dev",
|
|
4
|
-
"version": "2.
|
|
4
|
+
"version": "2.6.0",
|
|
5
5
|
"private": false,
|
|
6
6
|
"description": "Regardio development presets: biome, typescript, commitlint, markdownlint, vitest, playwright, sqlfluff, husky, and GitLab-flow ship tooling",
|
|
7
7
|
"keywords": [
|
|
@@ -74,7 +74,7 @@
|
|
|
74
74
|
],
|
|
75
75
|
"devDependencies": {
|
|
76
76
|
"@total-typescript/ts-reset": "0.6.1",
|
|
77
|
-
"@types/node": "25.6.
|
|
77
|
+
"@types/node": "25.6.2",
|
|
78
78
|
"@vitest/coverage-v8": "4.1.5",
|
|
79
79
|
"tsdown": "0.22.0",
|
|
80
80
|
"vitest": "4.1.5"
|
|
@@ -101,7 +101,7 @@
|
|
|
101
101
|
"fix:biome": "biome check --write --unsafe .",
|
|
102
102
|
"fix:md": "markdownlint-cli2 --config ../../.markdownlint-cli2.jsonc --fix",
|
|
103
103
|
"fix:pkg": "sort-package-json",
|
|
104
|
-
"lint": "run-
|
|
104
|
+
"lint": "run-p lint:*",
|
|
105
105
|
"lint:biome": "biome check .",
|
|
106
106
|
"lint:md": "markdownlint-cli2 --config ../../.markdownlint-cli2.jsonc",
|
|
107
107
|
"lint:pkg": "sort-package-json --check",
|