@dzhechkov/skills-book-digitizer 0.2.4 → 0.2.8
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 +50 -8
- package/book-brain-register/SKILL.md +108 -0
- package/digitize-book/SKILL.md +28 -12
- package/package.json +3 -2
- package/sources.json +3 -1
package/README.md
CHANGED
|
@@ -12,16 +12,17 @@ Knowledge Base behind them. dz-original; design & rationale in
|
|
|
12
12
|
methods at the decisions it's about — e.g. DDIA → `ddia-replication-topology-choice`,
|
|
13
13
|
`ddia-partitioning-strategy`, `ddia-consistency-model-selection`.
|
|
14
14
|
|
|
15
|
-
## The skills (a checkpointed pipeline + one sibling)
|
|
15
|
+
## The skills (a checkpointed pipeline + a terminal promote + one sibling)
|
|
16
16
|
|
|
17
17
|
| Skill | Stage |
|
|
18
18
|
|-------|-------|
|
|
19
|
-
| `digitize-book` | **Orchestrator** — runs the pipeline through
|
|
19
|
+
| `digitize-book` | **Orchestrator** — runs the pipeline through up to 6 human checkpoints (CP6 promote-to-brain optional), resumable across sessions |
|
|
20
20
|
| `book-ingest` | PDF → chunked, page-anchored corpus + manifest (deterministic: poppler + heuristics, no LLM) |
|
|
21
21
|
| `book-knowledge-extract` | corpus → **verified** Knowledge Units (map-reduce, dedup, KU-verify entailment, FACTS-verbatim/PROSE-paraphrase regime) |
|
|
22
22
|
| `book-skill-distill` | verified KUs → **decision-moment** skills (slug-prefixed, routing evals + activation gate, KU→skill traceability) |
|
|
23
23
|
| `book-pack-assemble` | skills → installable pack (`references/` deep-lookup + the per-book `brain/<slug>.sqlite` KB slice shipped inside, **private-by-default** distribution, collision gate, Copilot policy) |
|
|
24
24
|
| `book-kb-index` | KUs → the memory layer: `.dz/memory/books.sqlite` (lexical) + shared agentdb (vector) |
|
|
25
|
+
| `book-brain-register` | **Terminal promote (optional, CP6, ADR §5.1)** — promote this project's KUs into the durable **cross-project brain** (`~/.dz/brain/`) via `dz brain add --project . --source <slug>`. Default project-local only; an explicit, IP-relevant opt-in like CP5. The in-pipeline promote (vs the manual `dz brain add`). |
|
|
25
26
|
| `source-brain-ingest` | **Sibling (not a book stage, ADR §6)** — deep-walk a **repo/dir** → the *same* Knowledge Units → the *same* brain via `dz brain add --from-kus … --kind repo`. One brain, two ingest front-ends (books + code). |
|
|
26
27
|
|
|
27
28
|
## Install & use
|
|
@@ -44,7 +45,8 @@ Full design + the RU version: [ADR-001 Knowledge Brain](https://github.com/djd1m
|
|
|
44
45
|
### 1. Digitize a book → skills + KB
|
|
45
46
|
|
|
46
47
|
The core pipeline. Install the orchestrator, then hand it a PDF; it runs `book-ingest → extract →
|
|
47
|
-
distill → assemble → book-kb-index` through 5 human checkpoints
|
|
48
|
+
distill → assemble → book-kb-index` through 5 human checkpoints (CP1–CP5), plus an optional CP6
|
|
49
|
+
`book-brain-register` to promote the book into the cross-project brain (scenario 3).
|
|
48
50
|
|
|
49
51
|
```bash
|
|
50
52
|
dz init --target claude-code --select digitize-book
|
|
@@ -54,6 +56,37 @@ dz init --target claude-code --select digitize-book
|
|
|
54
56
|
Output: a `skills-book-<slug>` pack (decision-moment skills) **and** the two-store KB behind it. Live
|
|
55
57
|
run: DDIA → «Высоконагруженные приложения» digitized to **116 Knowledge Units**.
|
|
56
58
|
|
|
59
|
+
#### Install the generated pack into an agent
|
|
60
|
+
|
|
61
|
+
The generated pack lives as a local skill-pack directory (`packages/@dzhechkov/skills-book-<slug>`),
|
|
62
|
+
version-controlled but — for a copyrighted book — **`private: true`, never published to npm** (CP5 / IP).
|
|
63
|
+
Install its skills into any agent with one command (`dz` discovers the local pack; run it in the
|
|
64
|
+
target project, wherever the pack/monorepo is available):
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
# one or more skills (comma-separated), for any target: claude-code | codex | opencode | hermes | openclaude | copilot
|
|
68
|
+
dz init --target claude-code --select ddia-replication-topology-choice,ddia-partitioning-strategy
|
|
69
|
+
|
|
70
|
+
# the whole pack — list every skill id (dz registry | grep <slug> to see them)
|
|
71
|
+
dz init --target claude-code --select <id1>,<id2>,…
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Writes `SKILL.md` into `.claude/skills/<id>/` (compiled to the target's format); the agent then
|
|
75
|
+
activates each on its decision moment. NB: `npx @dzhechkov/skills-book-<slug>` does **not** work for a
|
|
76
|
+
private book pack — it's not on npm; install from a machine that has the pack.
|
|
77
|
+
|
|
78
|
+
#### Make a portable bundle from them
|
|
79
|
+
|
|
80
|
+
To hand the skills to a generic / LangGraph consumer (self-contained, no `dz` needed downstream):
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
dz bundle --select ddia-replication-topology-choice,ddia-partitioning-strategy --out ./ddia-bundle
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Emits a self-contained `skills/` tree (+ any cross-skill deps, with a warning if one is missing).
|
|
87
|
+
Same CP5 rule applies: a copyrighted book's bundle stays owner-controlled — share only under your
|
|
88
|
+
licence decision (permissive/public-domain sources can be shared freely).
|
|
89
|
+
|
|
57
90
|
### 2. Query one book's knowledge
|
|
58
91
|
|
|
59
92
|
Lexical (FTS5) recall over a single digitized book's KB, in the project that ingested it. `--book`
|
|
@@ -68,20 +101,29 @@ Pull-based: you ask, you get KU hits back with source + page anchors. No hook, n
|
|
|
68
101
|
### 3. Build a cross-project brain from N books
|
|
69
102
|
|
|
70
103
|
Promote each project's digitized-book KUs into **one shared brain** (`~/.dz/brain/` — lexical
|
|
71
|
-
`books.sqlite` + vector `agentdb.db`), then query across every ingested book at once
|
|
104
|
+
`books.sqlite` + vector `agentdb.db`), then query across every ingested book at once. There are two
|
|
105
|
+
ways to promote — **in-pipeline** and **manual** — both drive the same `dz brain add`:
|
|
106
|
+
|
|
107
|
+
- **In-pipeline (preferred): `book-brain-register`** — the optional terminal stage of `digitize-book`,
|
|
108
|
+
gated at **CP6 (promote?)**. After the pack + project KB are built, the orchestrator offers to promote
|
|
109
|
+
the book into the brain; the default is *project-local only* and promotion is an explicit, IP-relevant
|
|
110
|
+
opt-in (like CP5's distribution decision). It runs `dz brain add --project . --source <slug>` for you.
|
|
111
|
+
- **Manual:** run the CLI yourself against a project whose book is already indexed.
|
|
72
112
|
|
|
73
113
|
```bash
|
|
74
|
-
dz brain add
|
|
75
|
-
dz brain list
|
|
76
|
-
dz brain query "replication topology"
|
|
114
|
+
dz brain add --project . --source <slug> # promote this project's KUs into the brain (idempotent)
|
|
115
|
+
dz brain list # what's in the brain: slug, kind, KU count, corpus version
|
|
116
|
+
dz brain query "replication topology" # cross-source recall over ALL books
|
|
77
117
|
dz brain query "replication topology" --source <slug> # optional: narrow to one book
|
|
118
|
+
dz brain update <slug> --project . # non-clobbering refresh of a re-digitized book
|
|
78
119
|
```
|
|
79
120
|
|
|
80
121
|
One shared store, not per-book packages: you do **not** install anything to query the brain — it
|
|
81
122
|
accretes on `dz brain add`. The *right* book surfaces by **relevance** (KUs rank on one common scale,
|
|
82
123
|
each hit labelled with its source book + page); `--source` is a label filter, not a manual routing
|
|
83
124
|
pick. Cross-source is the default — multiple books scoring on a query is a feature (richer grounding),
|
|
84
|
-
not a bug.
|
|
125
|
+
not a bug. The brain is **private by default and never distributed** (ADR §8): CP6 promotes a
|
|
126
|
+
copyrighted book into your *local* brain only.
|
|
85
127
|
|
|
86
128
|
### 4. Grounded answering (the hook)
|
|
87
129
|
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: book-brain-register
|
|
3
|
+
description: >
|
|
4
|
+
Optional TERMINAL stage of the book digitizer (ADR-001 §5.1): after book-kb-index has loaded this
|
|
5
|
+
project's verified Knowledge Units into the project-local KB, PROMOTE them into the durable,
|
|
6
|
+
cross-project Knowledge Brain (`~/.dz/brain/`, `DZ_BRAIN_HOME`) via `dz brain add --project . --source
|
|
7
|
+
<slug>` — so the book's know-how is recallable in OTHER projects, not just the one that ingested it.
|
|
8
|
+
Gated at CP6 (promote?): default is project-local only; promotion is an explicit, IP-relevant
|
|
9
|
+
decision. Non-clobbering (upsert on (book, ku_id, corpus_version); refresh via `dz brain update`).
|
|
10
|
+
Triggers on: "promote the book into the brain", "book-brain-register", "dz brain add this book",
|
|
11
|
+
"add this digitized book to my knowledge brain". Invoked by `digitize-book` at CP6.
|
|
12
|
+
trust_tier: 1
|
|
13
|
+
trust_tier_label: "Structured"
|
|
14
|
+
trust_tier_path: "Run /bto-test to promote to Tier 2"
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
# book-brain-register — promote a digitized book into the durable brain
|
|
18
|
+
|
|
19
|
+
The **terminal** stage, after `book-kb-index`. `book-kb-index` owns the **project** stores (the
|
|
20
|
+
source of truth for the pack — it always runs). This stage does one more, **optional** thing: it
|
|
21
|
+
**promotes** this project's verified KUs into the **durable cross-project brain** at `~/.dz/brain/`
|
|
22
|
+
(override `DZ_BRAIN_HOME`) so the book's know-how is considered *later, in other projects* — not just
|
|
23
|
+
the one that digitized it. It does not re-extract, re-index the project KB, or reimplement mirroring:
|
|
24
|
+
it drives the already-built `dz brain add`, which mirrors both stores (lexical + vector), writes the
|
|
25
|
+
registry entry, and generates the primer card.
|
|
26
|
+
|
|
27
|
+
## When to use / NOT
|
|
28
|
+
|
|
29
|
+
- **Use** as the OPTIONAL final stage of `digitize-book`, at **CP6**, when the owner wants this book's
|
|
30
|
+
knowledge available across all their projects (the durable `~/.dz/brain/`).
|
|
31
|
+
- **NOT** to build the project KB — that is `book-kb-index`, which still runs regardless of CP6. This
|
|
32
|
+
stage promotes an *already-indexed* project's KUs upward; it is additive and opt-in.
|
|
33
|
+
- **NOT for repos/dirs** → those take the SIBLING path `source-brain-ingest` (deep-walk → same KU
|
|
34
|
+
shape → `dz brain add --from-kus … --kind repo --license <spdx>`, ADR §6). Same brain, different
|
|
35
|
+
front-end. This stage is the **book** path.
|
|
36
|
+
- **NOT** to publish or share the brain — the brain is **private by default and never distributed**
|
|
37
|
+
(ADR §8). A copyrighted book's promotion stays local; the shareable unit is the per-book KB slice
|
|
38
|
+
riding inside the `skills-book-<slug>` pack under the CP5 licence decision (that's `book-pack-assemble`).
|
|
39
|
+
|
|
40
|
+
## Prerequisites
|
|
41
|
+
|
|
42
|
+
- `book-kb-index` has run: this project's verified KUs are in the project-local stores
|
|
43
|
+
(`.dz/memory/books.sqlite` + `.dz/agentdb.db`) with a settled `corpus_version`.
|
|
44
|
+
- The brain stores (`dz setup --memory agentdb`) — the same `agentdb` + `better-sqlite3` primitives,
|
|
45
|
+
the `dz brain add` command just points `dbPath` at the brain home instead of the project.
|
|
46
|
+
- A **CP6 promote decision** from the owner (see the checkpoint below) — this stage does nothing
|
|
47
|
+
without it; default is project-local only.
|
|
48
|
+
|
|
49
|
+
## Protocol
|
|
50
|
+
|
|
51
|
+
1. **CP6 (promote?)** — offer promotion explicitly. DEFAULT is *project-local only* (do nothing): the
|
|
52
|
+
book's KB already exists in this project. Promotion moves book-derived knowledge into a long-lived,
|
|
53
|
+
cross-project location, so — like CP5's distribution decision — it is an IP-relevant call the owner
|
|
54
|
+
makes deliberately, never auto-approved. If the owner declines, stop here (the project KB stands).
|
|
55
|
+
2. **Promote** — on an explicit yes, drive the existing CLI (do NOT reimplement the mirroring):
|
|
56
|
+
```bash
|
|
57
|
+
dz brain add --project . --source <slug>
|
|
58
|
+
```
|
|
59
|
+
This resolves the brain home (`DZ_BRAIN_HOME` → `~/.dz/brain/`, created if absent), reads this
|
|
60
|
+
project's verified KUs for `<slug>`, and **idempotently upserts** them into BOTH brain stores
|
|
61
|
+
(lexical `books.sqlite` + vector `agentdb.db`) keyed on `(book, ku_id, corpus_version)`, then writes
|
|
62
|
+
the `brain.json` registry entry (slug, kind `book`, isbn/license, corpus_version, ku_count, lang,
|
|
63
|
+
primer path, added_ts) and generates `primers/<slug>.md`. All reused primitives — nothing new here.
|
|
64
|
+
3. **Non-clobbering by construction** — the upsert evicts stale-corpus rows for **this source only**;
|
|
65
|
+
adding this book never touches other sources already in the brain. A re-digitized / updated book
|
|
66
|
+
does NOT duplicate: refresh it with
|
|
67
|
+
```bash
|
|
68
|
+
dz brain update <slug> --project .
|
|
69
|
+
```
|
|
70
|
+
which re-mirrors this source at its new `corpus_version` (stale-corpus rows evicted, other sources
|
|
71
|
+
left intact). Never `dz brain add` a second time hoping to "append" — the refresh verb is the path.
|
|
72
|
+
4. **Verify** — confirm the promotion landed in the brain, labeled from the brain (not the project):
|
|
73
|
+
```bash
|
|
74
|
+
dz brain query "<a KU name>" --source <slug> # returns the KU, labeled with its source book + page
|
|
75
|
+
dz brain primer <slug> # shows the capability card (synopsis + KU-type histogram)
|
|
76
|
+
```
|
|
77
|
+
Also `dz brain list` should show the source with its ku_count and corpus_version.
|
|
78
|
+
|
|
79
|
+
## Anti-patterns
|
|
80
|
+
|
|
81
|
+
| Anti-pattern | Why it fails | Instead |
|
|
82
|
+
|--------------|--------------|---------|
|
|
83
|
+
| Promoting by default / auto-approving CP6 | moves book-derived IP into a durable cross-project home silently | CP6 is explicit, owner-decided, like CP5 |
|
|
84
|
+
| Skipping `book-kb-index` and promoting straight to the brain | there are no settled project KUs to mirror; provenance/corpus_version unset | index the project first; promote after |
|
|
85
|
+
| Re-running `dz brain add` to update a book | INSERT path can leave stale-corpus rows | `dz brain update <slug>` (eviction + upsert) |
|
|
86
|
+
| Reimplementing the store mirroring in this skill | the CLI already mirrors lexical+vector, writes the registry, builds the primer | drive `dz brain add` — reuse, don't rebuild |
|
|
87
|
+
| Routing a repo/dir through this stage | book path assumes book KUs + slug provenance | sibling `source-brain-ingest` → `dz brain add --from-kus … --kind repo --license` |
|
|
88
|
+
| Treating the brain as publishable | the accreted personal brain is private, never distributed (§8) | share the per-book pack slice (CP5), not the brain |
|
|
89
|
+
|
|
90
|
+
## Self-check
|
|
91
|
+
|
|
92
|
+
- [ ] `book-kb-index` ran first; this project's verified KUs + corpus_version are settled?
|
|
93
|
+
- [ ] CP6 honored — an EXPLICIT owner promote decision (never auto-approved), default project-local?
|
|
94
|
+
- [ ] Promoted via `dz brain add --project . --source <slug>` (reused CLI; both brain stores mirrored, registry + primer written)?
|
|
95
|
+
- [ ] Non-clobbering: upsert on (book, ku_id, corpus_version); a re-run uses `dz brain update <slug>`, not a second add?
|
|
96
|
+
- [ ] Verified: `dz brain query "<KU>" --source <slug>` returns it labeled from the brain; `dz brain primer <slug>` shows the card?
|
|
97
|
+
- [ ] Brain kept private (never distributed); a copyrighted book's promotion stays local?
|
|
98
|
+
|
|
99
|
+
## Examples
|
|
100
|
+
|
|
101
|
+
- «Оцифровал DDIA, теперь хочу, чтобы эти знания были доступны и в других проектах» → at CP6 the owner
|
|
102
|
+
says promote → `dz brain add --project . --source ddia` → 116 KU mirrored into `~/.dz/brain/`;
|
|
103
|
+
`dz brain query "репликация" --source ddia` returns them labeled from the brain; `dz brain primer ddia`
|
|
104
|
+
shows the card. In a later project, `dz brain query` recalls DDIA KUs with no re-ingest.
|
|
105
|
+
- «Обновил книгу, переоцифровал — не хочу дублей в brain» → `dz brain update ddia --project .` re-mirrors
|
|
106
|
+
the new corpus_version, evicting stale rows for ddia only; other sources untouched.
|
|
107
|
+
- «Промоутить только КБ, пак не публиковать» → CP6 (brain) and CP5 (pack distribution) are separate
|
|
108
|
+
decisions: promote to the private brain, keep the pack `private: true`.
|
package/digitize-book/SKILL.md
CHANGED
|
@@ -4,8 +4,8 @@ description: >
|
|
|
4
4
|
Orchestrator: turn an engineering book/textbook/monograph (PDF, 100–1000+ pages) into an
|
|
5
5
|
INSTALLABLE skill pack whose skills make AI coders (Claude Code, Codex, …) work within the
|
|
6
6
|
book's methodologies at real decision moments — plus a searchable Knowledge Base behind them.
|
|
7
|
-
Drives the
|
|
8
|
-
checkpoints, resumable across sessions. Triggers on: "оцифруй книгу", "digitize this book",
|
|
7
|
+
Drives the pipeline (ingest → extract → distill → pack → index, then an optional promote-to-brain)
|
|
8
|
+
through up to 6 human checkpoints, resumable across sessions. Triggers on: "оцифруй книгу", "digitize this book",
|
|
9
9
|
"сделай скилл-пак из книги", "turn this textbook into skills", "book to skill pack".
|
|
10
10
|
trust_tier: 1
|
|
11
11
|
trust_tier_label: "Structured"
|
|
@@ -19,9 +19,10 @@ agent **apply the book's methodologies** when it hits the decisions the book is
|
|
|
19
19
|
`ddia-replication-topology-choice`, `ddia-partitioning-strategy`). Design & rationale:
|
|
20
20
|
[ADR-001 v2](https://github.com/djd1m/dz-harness-hub/blob/main/features/book-knowledge-digitizer/03_adr/001-book-to-skillpack-pipeline.md).
|
|
21
21
|
|
|
22
|
-
> **This is an orchestrator.** It sequences
|
|
23
|
-
> your judgment. It never runs the whole book unattended — book
|
|
24
|
-
> operation, and the panel-confirmed cost is **~2.5–4M agent-tokens per
|
|
22
|
+
> **This is an orchestrator.** It sequences the stage-skills and stops at up to six checkpoints for
|
|
23
|
+
> your judgment (CP6, promote-to-brain, is optional). It never runs the whole book unattended — book
|
|
24
|
+
> digitization is a steered operation, and the panel-confirmed cost is **~2.5–4M agent-tokens per
|
|
25
|
+
> 640-page book**.
|
|
25
26
|
|
|
26
27
|
## When to use / NOT
|
|
27
28
|
|
|
@@ -33,8 +34,11 @@ agent **apply the book's methodologies** when it hits the decisions the book is
|
|
|
33
34
|
|
|
34
35
|
- `poppler-utils` (`pdftotext`, `pdfinfo`, `pdfimages`) for ingest.
|
|
35
36
|
- For the KB layers: `dz setup --memory agentdb` (installs `agentdb` + `better-sqlite3`).
|
|
36
|
-
- The
|
|
37
|
-
`book-ingest`, `book-knowledge-extract`, `book-skill-distill`, `book-pack-assemble`, `book-kb-index
|
|
37
|
+
- The stage skills of this pack installed (they auto-install together):
|
|
38
|
+
`book-ingest`, `book-knowledge-extract`, `book-skill-distill`, `book-pack-assemble`, `book-kb-index`,
|
|
39
|
+
and the optional terminal `book-brain-register` (CP6 promote-to-brain).
|
|
40
|
+
- For CP6 promotion into the durable cross-project brain (`~/.dz/brain/`, `DZ_BRAIN_HOME`): the same
|
|
41
|
+
`agentdb` stores (`dz setup --memory agentdb`).
|
|
38
42
|
|
|
39
43
|
## Pipeline & checkpoints
|
|
40
44
|
|
|
@@ -42,6 +46,7 @@ agent **apply the book's methodologies** when it hits the decisions the book is
|
|
|
42
46
|
book.pdf ─[book-ingest]─► corpus/ + manifest ─[book-knowledge-extract]─► Knowledge Units (+KU-verify)
|
|
43
47
|
─[book-skill-distill]─► SKILL.md's ─[book-pack-assemble]─► skills-book-<slug> ─[book-kb-index]─► KB
|
|
44
48
|
CP1 scope CP2 sample KUs CP3 skill list CP3.5 routing CP4 pack CP5 distribute
|
|
49
|
+
····optional terminal····► ─[book-brain-register]─► ~/.dz/brain (CP6 promote?)
|
|
45
50
|
```
|
|
46
51
|
|
|
47
52
|
| CP | After | You decide |
|
|
@@ -51,7 +56,8 @@ book.pdf ─[book-ingest]─► corpus/ + manifest ─[book-knowledge-extract]
|
|
|
51
56
|
| **CP3** | distill triage | approve the candidate skill list (decision moments); flat vs gateway layout |
|
|
52
57
|
| **CP3.5** | routing evals | the routing gate report (≥80% correct activation / ≤10% sibling-steal) — fix or proceed |
|
|
53
58
|
| **CP4** | pack assembled | shingling-gate result (no uncited verbatim run ≥8 words) + L0 report + install smoke (+ Copilot instruction-byte total if that target) |
|
|
54
|
-
| **CP5** |
|
|
59
|
+
| **CP5** | pack + KB indexed | distribution: keep `private` (default) or record an explicit publish decision |
|
|
60
|
+
| **CP6** | `book-brain-register` | **promote** the book's KUs into the durable **cross-project brain** (`~/.dz/brain/`) — **default: project-local only**; an explicit opt-in, IP-relevant like CP5 (moves book-derived knowledge into a long-lived home). Optional terminal stage |
|
|
55
61
|
|
|
56
62
|
## Protocol
|
|
57
63
|
|
|
@@ -68,13 +74,22 @@ book.pdf ─[book-ingest]─► corpus/ + manifest ─[book-knowledge-extract]
|
|
|
68
74
|
5. **Distill** → `book-skill-distill` proposes decision-moment skills; **CP3**; then **CP3.5** on
|
|
69
75
|
the routing evals.
|
|
70
76
|
6. **Assemble** → `book-pack-assemble`; **CP4**.
|
|
71
|
-
7. **Index** → `book-kb-index` loads KUs into the KB (lexical `books.sqlite` + agentdb vector).
|
|
77
|
+
7. **Index** → `book-kb-index` loads KUs into the project KB (lexical `books.sqlite` + agentdb vector).
|
|
78
|
+
This always runs — it is the project's KB, independent of any brain decision.
|
|
72
79
|
8. **Distribute** → **CP5**; then hand over: `dz init --select <the new skills>` and how to use.
|
|
80
|
+
9. **Promote (optional)** → `book-brain-register`: at **CP6**, offer to `dz brain add --project . --source
|
|
81
|
+
<slug>` this book's KUs into the durable **cross-project brain** (`~/.dz/brain/`, `DZ_BRAIN_HOME`).
|
|
82
|
+
**Default is project-local only** — promotion is an explicit, IP-relevant opt-in (like CP5). A
|
|
83
|
+
re-digitized book refreshes non-clobbering via `dz brain update <slug>`; verify with
|
|
84
|
+
`dz brain query "<a KU name>" --source <slug>` + `dz brain primer <slug>`. The brain is private,
|
|
85
|
+
never distributed (§IP). Sibling: repos/dirs take `source-brain-ingest` → the same brain instead.
|
|
73
86
|
|
|
74
87
|
## `--trusted` mode
|
|
75
88
|
|
|
76
|
-
After you've approved 2–3 books, `--trusted` makes CP2 an async spot-check; **CP1, CP3, CP5
|
|
77
|
-
|
|
89
|
+
After you've approved 2–3 books, `--trusted` makes CP2 an async spot-check; **CP1, CP3, CP5, and CP6
|
|
90
|
+
stay interactive** (scope, the skill list, distribution, and brain-promotion are the irreducible
|
|
91
|
+
judgment calls). **CP6 is never auto-approved** — promoting book-derived knowledge into the durable
|
|
92
|
+
cross-project brain is an IP decision, exactly like CP5, so `--trusted` never green-lights it.
|
|
78
93
|
|
|
79
94
|
## Anti-patterns
|
|
80
95
|
|
|
@@ -89,8 +104,9 @@ mandatory** (scope, the skill list, and distribution are the irreducible judgmen
|
|
|
89
104
|
|
|
90
105
|
- [ ] Resumed from the manifest (no completed phase re-run)?
|
|
91
106
|
- [ ] CP1–CP5 honored (scope, samples, skill list, routing gate, distribution)?
|
|
107
|
+
- [ ] CP6 honored — brain promotion was an explicit opt-in (default project-local; never auto-approved, even under `--trusted`)?
|
|
92
108
|
- [ ] Only verified KUs fed distill; every skill claim traces to a KU?
|
|
93
|
-
- [ ] Pack is `private` unless a CP5 decision says otherwise?
|
|
109
|
+
- [ ] Pack is `private` unless a CP5 decision says otherwise; brain kept private (never distributed)?
|
|
94
110
|
- [ ] User got: install command + how the new skills trigger?
|
|
95
111
|
|
|
96
112
|
## Examples
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dzhechkov/skills-book-digitizer",
|
|
3
|
-
"version": "0.2.
|
|
4
|
-
"description": "Canonical book-digitizer skill pack —
|
|
3
|
+
"version": "0.2.8",
|
|
4
|
+
"description": "Canonical book-digitizer skill pack — 8 skills that turn an engineering book/textbook/monograph into an installable skill pack whose skills make AI coders work within the book's methodologies: digitize-book (orchestrator), book-ingest, book-knowledge-extract, book-skill-distill, book-pack-assemble, book-kb-index, book-brain-register (terminal promote-to-brain, CP6), source-brain-ingest (repo/dir sibling).",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "dzhechko",
|
|
7
7
|
"keywords": [
|
|
@@ -22,6 +22,7 @@
|
|
|
22
22
|
"book-skill-distill",
|
|
23
23
|
"book-pack-assemble",
|
|
24
24
|
"book-kb-index",
|
|
25
|
+
"book-brain-register",
|
|
25
26
|
"source-brain-ingest",
|
|
26
27
|
"scripts",
|
|
27
28
|
"sources.json",
|
package/sources.json
CHANGED
|
@@ -16,6 +16,8 @@
|
|
|
16
16
|
"book-knowledge-extract": { "upstream_type": "original", "upstream_path": null, "description": "Corpus → verified Knowledge Units (map-reduce, KU-verify, fidelity regime)" },
|
|
17
17
|
"book-skill-distill": { "upstream_type": "original", "upstream_path": null, "description": "Verified KUs → decision-moment skills (routing evals, traceability)" },
|
|
18
18
|
"book-pack-assemble": { "upstream_type": "original", "upstream_path": null, "description": "Skills → installable pack (references/, private-default, collision gate)" },
|
|
19
|
-
"book-kb-index": { "upstream_type": "original", "upstream_path": null, "description": "KUs → books.sqlite (lexical) + agentdb (vector) KB, upsert not append" }
|
|
19
|
+
"book-kb-index": { "upstream_type": "original", "upstream_path": null, "description": "KUs → books.sqlite (lexical) + agentdb (vector) KB, upsert not append" },
|
|
20
|
+
"book-brain-register": { "upstream_type": "original", "upstream_path": null, "description": "Optional terminal stage (CP6) — promote a project's KUs into the durable cross-project brain (~/.dz/brain/) via dz brain add" },
|
|
21
|
+
"source-brain-ingest": { "upstream_type": "original", "upstream_path": null, "description": "Sibling (ADR §6) — deep-walk a repo/dir into the same KUs → same brain via dz brain add --from-kus --kind repo" }
|
|
20
22
|
}
|
|
21
23
|
}
|