okforge 1.0.2 → 1.0.3
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 +28 -16
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -16,6 +16,34 @@ target's `.claude/` by `okforge install`); its deterministic mechanics live in
|
|
|
16
16
|
[`src/`](src) as a small TypeScript CLI. The model writes the prose; the CLI
|
|
17
17
|
answers "what is each folder derived from?" and "is the bundle still well-formed?".
|
|
18
18
|
|
|
19
|
+
## Blog series
|
|
20
|
+
|
|
21
|
+
A four-part series on the ideas behind okforge — keeping knowledge in sync with code:
|
|
22
|
+
|
|
23
|
+
1. [The Faster AI Writes Code, the Faster Your Docs Rot](docs/blog_posts/post-1-the-faster-ai-writes-code-the-faster-your-docs-rot.md) — AI-accelerated coding compounds knowledge debt; treat documentation as derived state, not hand-maintained prose.
|
|
24
|
+
2. [Give the Model Less](docs/blog_posts/post-2-give-the-model-less.md) — reliability comes from drawing the model/deterministic boundary deliberately, and drawing it small.
|
|
25
|
+
3. [Don't Make It Remember, Make It Read](docs/blog_posts/post-3-dont-make-it-remember-make-it-read.md) — grounding output in real source; hallucination is a design failure, not a model failure.
|
|
26
|
+
4. [Bet on Boring Formats](docs/blog_posts/post-4-bet-on-boring-formats.md) — why okforge ships plain markdown, an open spec, and an installable skill instead of a clever app.
|
|
27
|
+
|
|
28
|
+
## How to install
|
|
29
|
+
|
|
30
|
+
Run `install` from the root of the repository you want to add OKF to (Node >=
|
|
31
|
+
20.12, no install step — `npx` fetches it):
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npx okforge install .claude
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
When the destination folder is named `.claude`, this drops the skill prose into
|
|
38
|
+
`.claude/skills/okf/` **and** registers the `npx okforge nudge` Stop hook in
|
|
39
|
+
`.claude/settings.json` (idempotent and non-destructive — existing settings and
|
|
40
|
+
hooks are preserved). For any other destination it copies the skill only and
|
|
41
|
+
leaves `settings.json` untouched.
|
|
42
|
+
|
|
43
|
+
Then write an `.okforge.config.json` at the project root describing that repo's
|
|
44
|
+
folder-to-source mapping (see [`.okforge.config.json`](#usable-in-any-repository-okforgeconfigjson)
|
|
45
|
+
below), and ask Claude to "set up okf" — or run `/okf` — to scaffold the bundle.
|
|
46
|
+
|
|
19
47
|
## Why a skill
|
|
20
48
|
|
|
21
49
|
The `okf/` bundle is **derived** from source — each folder is generated from
|
|
@@ -139,22 +167,6 @@ dotclaude_folder/ data shipped to a target's .claude/ by `okforge inst
|
|
|
139
167
|
- Ground every claim in real source. Do not invent fields, routes, flags, or
|
|
140
168
|
states; if uncertain, omit.
|
|
141
169
|
|
|
142
|
-
## Reusing this in another project
|
|
143
|
-
|
|
144
|
-
```bash
|
|
145
|
-
npx okforge install .claude
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
When the destination folder is named `.claude`, `install` both drops the skill
|
|
149
|
-
prose into `.claude/skills/okf/` **and** registers the `npx okforge nudge` Stop
|
|
150
|
-
hook in `.claude/settings.json` (idempotent and non-destructive — existing
|
|
151
|
-
settings and hooks are preserved). For any other destination it copies the skill
|
|
152
|
-
only and leaves `settings.json` untouched.
|
|
153
|
-
|
|
154
|
-
Then write an `.okforge.config.json` at the project root describing that repo's
|
|
155
|
-
folder-to-source mapping. The mapping is the only project-specific part — both the
|
|
156
|
-
skill and the nudge read it from there.
|
|
157
|
-
|
|
158
170
|
## License
|
|
159
171
|
|
|
160
172
|
MIT © Jerome Etienne
|