djournal 0.10.0 → 0.11.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/.agents/adapters/contract.md +7 -0
- package/.grokbot/README.md +10 -0
- package/README.md +14 -6
- package/bin/journal.js +1 -1
- package/docs/architecture.md +4 -0
- package/docs/djournal-in-practice.md +2 -0
- package/docs/grok-bot.md +80 -0
- package/docs/installation.md +18 -3
- package/docs/read-only-team-journal.md +2 -1
- package/docs/recall.md +1 -0
- package/docs/remote-sync.md +1 -1
- package/docs/uninstalling.md +5 -2
- package/integrations/grok-bot/README.md +50 -0
- package/integrations/grok-bot/checkup.md +41 -0
- package/integrations/grok-bot/getting-started.md +50 -0
- package/integrations/grok-bot/peer-briefing.md +22 -0
- package/integrations/grok-bot/skill-registration.md +61 -0
- package/lib/installer/index.js +65 -1
- package/package.json +3 -1
|
@@ -16,6 +16,13 @@ second workflow engine and do not own durable state.
|
|
|
16
16
|
An adapter may omit events its harness cannot support reliably. Instruction-only
|
|
17
17
|
behavior remains the compatibility baseline.
|
|
18
18
|
|
|
19
|
+
Grok Bot is an instruction and skill-only harness. It has no SessionStart or
|
|
20
|
+
Stop hooks, so it omits every semantic event. Compliance is the installed
|
|
21
|
+
skills, `AGENTS.md`, and the `djournal` / `journal` CLI. The recipe lives at
|
|
22
|
+
`integrations/grok-bot/` and is described in `docs/grok-bot.md`. Adding that
|
|
23
|
+
harness does not change `AUTOMATION.md`. Hooks on other harnesses still must
|
|
24
|
+
not write semantic journal entries.
|
|
25
|
+
|
|
19
26
|
## Input
|
|
20
27
|
|
|
21
28
|
The shared checker accepts one JSON object on stdin. It uses only stable fields:
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# Grok Bot marker
|
|
2
|
+
|
|
3
|
+
This directory marks a project for the djournal `grok-bot` harness.
|
|
4
|
+
|
|
5
|
+
Grok Bot has no session hooks. Journal compliance comes from the installed
|
|
6
|
+
skills, `AGENTS.md`, and `djournal` / `journal` commands. The Journal Hub
|
|
7
|
+
recipe installed with this harness lives at `integrations/grok-bot/`.
|
|
8
|
+
|
|
9
|
+
Register skills from `integrations/grok-bot/skill-registration.md`. See
|
|
10
|
+
`docs/grok-bot.md` in the djournal package for the architecture.
|
package/README.md
CHANGED
|
@@ -20,9 +20,9 @@ models, people, and tools.
|
|
|
20
20
|
|
|
21
21
|
Long coding sessions do not survive tool boundaries well when the only handoff
|
|
22
22
|
format is a transcript. A useful session may start in Codex, continue in Claude
|
|
23
|
-
Code, and later resume somewhere else. The journal is the
|
|
24
|
-
layer: each agent can read the same Markdown spine, follow the
|
|
25
|
-
and research links, and close its work in the same structure.
|
|
23
|
+
Code or Grok Bot, and later resume in Pi or somewhere else. The journal is the
|
|
24
|
+
portable handoff layer: each agent can read the same Markdown spine, follow the
|
|
25
|
+
same decisions and research links, and close its work in the same structure.
|
|
26
26
|
|
|
27
27
|
The memory belongs to the project, not to a chat session, model, harness,
|
|
28
28
|
database, or proprietary service.
|
|
@@ -113,6 +113,7 @@ flowchart LR
|
|
|
113
113
|
- Skills handle planning, research, decisions, documentation, recall, audit,
|
|
114
114
|
reconciliation, and session closure.
|
|
115
115
|
- Codex, Claude Code, and Pi integrations provide reminders and closure validation.
|
|
116
|
+
- Grok Bot uses the same skills and instructions without session hooks.
|
|
116
117
|
- Hooks never create or modify semantic journal entries.
|
|
117
118
|
- Read-only and trivial requests do not generate unnecessary ceremony.
|
|
118
119
|
|
|
@@ -166,13 +167,14 @@ djournal install
|
|
|
166
167
|
```
|
|
167
168
|
|
|
168
169
|
The global install gives you the `djournal` and `journal` commands. The
|
|
169
|
-
installer targets the current directory and detects Codex, Claude Code,
|
|
170
|
-
explicitly when needed:
|
|
170
|
+
installer targets the current directory and detects Codex, Claude Code, Pi, or
|
|
171
|
+
a `.grokbot/` marker. Select explicitly when needed:
|
|
171
172
|
|
|
172
173
|
```bash
|
|
173
174
|
djournal install --harness codex
|
|
174
175
|
djournal install --harness claude-code
|
|
175
176
|
djournal install --harness pi
|
|
177
|
+
djournal install --harness grok-bot
|
|
176
178
|
djournal install --all
|
|
177
179
|
```
|
|
178
180
|
|
|
@@ -209,6 +211,11 @@ Pi, or use `pi --approve` for a non-interactive run. Pi has no built-in
|
|
|
209
211
|
filesystem sandbox; when an external sandbox or container is used, expose the
|
|
210
212
|
global store referenced by `.djournal.json`.
|
|
211
213
|
|
|
214
|
+
Grok Bot has no session hooks. `djournal install --harness grok-bot` installs
|
|
215
|
+
the shared skills and a Journal Hub recipe under `integrations/grok-bot/`.
|
|
216
|
+
Register those skills in Grok, then let engineering bots journal themselves.
|
|
217
|
+
See [Grok Bot](docs/grok-bot.md).
|
|
218
|
+
|
|
212
219
|
## Lifecycle
|
|
213
220
|
|
|
214
221
|
```bash
|
|
@@ -279,7 +286,7 @@ release data is refreshed in the background at most once every 24 hours. Run
|
|
|
279
286
|
|
|
280
287
|
## Status
|
|
281
288
|
|
|
282
|
-
Codex, Claude Code, and
|
|
289
|
+
Codex, Claude Code, Pi, and Grok Bot are supported. OpenCode and Zed adapters are planned. Grok Bot is instruction and skill only.
|
|
283
290
|
|
|
284
291
|
Git-backed sharing and automatic sync are opt-in so local-only work remains
|
|
285
292
|
private by default.
|
|
@@ -297,6 +304,7 @@ djournal is licensed under the [Apache License 2.0](LICENSE).
|
|
|
297
304
|
## Documentation
|
|
298
305
|
|
|
299
306
|
- [Installation and repository layouts](docs/installation.md)
|
|
307
|
+
- [Grok Bot](docs/grok-bot.md)
|
|
300
308
|
- [Fast recall: CLI and agent usage](docs/recall.md)
|
|
301
309
|
- [Remote Git sync setup](docs/remote-sync.md)
|
|
302
310
|
- [Read-only team journal access](docs/read-only-team-journal.md)
|
package/bin/journal.js
CHANGED
|
@@ -56,7 +56,7 @@ Options:
|
|
|
56
56
|
--limit N Limit recall results per kind (1-100)
|
|
57
57
|
--rebuild Rebuild the persistent recall cache from scratch
|
|
58
58
|
--no-cache Search with an ephemeral in-memory index
|
|
59
|
-
--harness LIST Comma-separated codex,claude-code,pi
|
|
59
|
+
--harness LIST Comma-separated codex, claude-code (claude), pi, grok-bot (grok, grokbot)
|
|
60
60
|
--all Select all work items for share, or every harness
|
|
61
61
|
--instructions-only Install core instructions without harness hooks
|
|
62
62
|
`;
|
package/docs/architecture.md
CHANGED
|
@@ -218,6 +218,10 @@ into the shared checker. Because Pi has no blocking stop hook,
|
|
|
218
218
|
an invalid final marker causes at most one follow-up turn. Pi project trust is
|
|
219
219
|
managed by Pi, and external sandboxes must expose the global store.
|
|
220
220
|
|
|
221
|
+
Grok Bot does not emit those events. Its install is the shared skills,
|
|
222
|
+
`AGENTS.md`, and the recipe under `integrations/grok-bot/`. Skill registration
|
|
223
|
+
and shell commands are the integration. See [Grok Bot](grok-bot.md).
|
|
224
|
+
|
|
221
225
|
Configured standalone session-start hooks invoke `djournal pull --auto` before
|
|
222
226
|
loading active work. Explicit journal-sync prompt intent invokes a manual pull.
|
|
223
227
|
Close hooks invoke `djournal sync --auto --work <slug>`, whose transport ordering
|
|
@@ -263,6 +263,8 @@ Because the journal is Markdown, different harnesses can read the same memory:
|
|
|
263
263
|
|
|
264
264
|
- Codex can start the work.
|
|
265
265
|
- Claude Code can continue from the same spine and decisions.
|
|
266
|
+
- Pi and Grok Bot can read the same files and links. Grok Bot does this with
|
|
267
|
+
skills and the CLI, without session hooks.
|
|
266
268
|
- A future harness can inspect the same files and links.
|
|
267
269
|
|
|
268
270
|
The journal keeps continuity outside any one model context.
|
package/docs/grok-bot.md
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Grok Bot
|
|
2
|
+
|
|
3
|
+
Grok Bot is a supported djournal harness. It uses the same rules, skills, and
|
|
4
|
+
Markdown journal as Codex, Claude Code, and Pi. It does not have SessionStart
|
|
5
|
+
or Stop hooks, so compliance is the installed skills plus the `djournal` /
|
|
6
|
+
`journal` CLI. Do not add hook files for this harness.
|
|
7
|
+
|
|
8
|
+
## Hub and peers
|
|
9
|
+
|
|
10
|
+
A **Journal Hub** bot installs djournal, registers skills, and reviews shared
|
|
11
|
+
history. **Engineering bots** journal their own work. The hub is an
|
|
12
|
+
asynchronous reconciler:
|
|
13
|
+
|
|
14
|
+
- peers self-serve skills and CLI commands
|
|
15
|
+
- the hub runs share, sync, and conflict review when asked
|
|
16
|
+
- `local_only` work is not published unless someone explicitly shares it
|
|
17
|
+
|
|
18
|
+
The hub does not take over a peer's session and does not need to be in the
|
|
19
|
+
turn path for the peer to write an entry.
|
|
20
|
+
|
|
21
|
+
The in-repo recipe is [`integrations/grok-bot/`](../integrations/grok-bot/README.md).
|
|
22
|
+
It is the open-source distribution path. Public bot templates are not part of
|
|
23
|
+
this package and may be unavailable on some teams. Publishing a live hub is a
|
|
24
|
+
follow-up, done from an account that can create the bot.
|
|
25
|
+
|
|
26
|
+
## Install
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
djournal install --harness grok-bot
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Aliases `grok` and `grokbot` normalize to `grok-bot`. `--all` includes it.
|
|
33
|
+
|
|
34
|
+
That install:
|
|
35
|
+
|
|
36
|
+
- copies `.agents/rules`, `.agents/skills`, and `.agents/adapters`
|
|
37
|
+
- writes the managed `AGENTS.md` block and `.djournal.json` project marker
|
|
38
|
+
- copies the recipe to `integrations/grok-bot/` and a marker README to
|
|
39
|
+
`.grokbot/`
|
|
40
|
+
|
|
41
|
+
It does not write `.codex/hooks.json`, `.claude/settings.json`, or
|
|
42
|
+
`.pi/extensions`. Uninstalling `grok-bot` removes only the djournal-owned
|
|
43
|
+
`.grokbot/` and `integrations/grok-bot/` files. Shared `.agents/` content stays
|
|
44
|
+
until a full uninstall, same as other harnesses.
|
|
45
|
+
|
|
46
|
+
Detection uses `--harness grok-bot` or an existing `.grokbot/` directory. A
|
|
47
|
+
`grok` executable is not treated as evidence.
|
|
48
|
+
|
|
49
|
+
`djournal doctor` reports the CLI, `.agents/` rules and skills, the project
|
|
50
|
+
marker, and the recipe files. Missing hooks are not a failure. The CLI check
|
|
51
|
+
stays informational when `djournal` is not on `PATH`, and the detail points at
|
|
52
|
+
`integrations/grok-bot/skill-registration.md`.
|
|
53
|
+
|
|
54
|
+
## Register skills
|
|
55
|
+
|
|
56
|
+
Grok Bot does not read `.agents/skills` automatically. Register each
|
|
57
|
+
`SKILL.md` with UpdateSkill using the ids in
|
|
58
|
+
[`integrations/grok-bot/skill-registration.md`](../integrations/grok-bot/skill-registration.md).
|
|
59
|
+
|
|
60
|
+
Rewrite command examples to `djournal <command> --target <project-root>` and
|
|
61
|
+
resolve rule paths from the install target and `STATE.md`. Sibling skill links
|
|
62
|
+
use `[Name](sand-workflow:<id>)`. Keep upstream skills free of machine-specific
|
|
63
|
+
paths.
|
|
64
|
+
|
|
65
|
+
Also register **Checkup with Journal Hub** from
|
|
66
|
+
[`integrations/grok-bot/checkup.md`](../integrations/grok-bot/checkup.md). The
|
|
67
|
+
getting-started prose asks for the project root, sync mode, which peers are
|
|
68
|
+
engineering bots, and the hub display name, one question at a time.
|
|
69
|
+
|
|
70
|
+
## Brief peers
|
|
71
|
+
|
|
72
|
+
Use [`integrations/grok-bot/peer-briefing.md`](../integrations/grok-bot/peer-briefing.md).
|
|
73
|
+
Peers should install or reuse the harness, run the journal skills, and call
|
|
74
|
+
the hub for checkup rather than for every journal write.
|
|
75
|
+
|
|
76
|
+
## Related docs
|
|
77
|
+
|
|
78
|
+
- [Installation and repository layouts](installation.md)
|
|
79
|
+
- [Harness adapter contract](../.agents/adapters/contract.md)
|
|
80
|
+
- [Uninstalling and reinstalling](uninstalling.md)
|
package/docs/installation.md
CHANGED
|
@@ -41,8 +41,9 @@ djournal install
|
|
|
41
41
|
This installs:
|
|
42
42
|
|
|
43
43
|
- shared journal rules and skills under `.agents/`
|
|
44
|
-
- harness-specific hook config when selected
|
|
44
|
+
- harness-specific hook config when a hook harness is selected
|
|
45
45
|
- a managed `.pi/extensions/djournal.ts` extension when Pi is selected
|
|
46
|
+
- a skill-only Journal Hub recipe and `.grokbot/` marker when Grok Bot is selected, with no hook config
|
|
46
47
|
- managed instruction blocks in `AGENTS.md` and/or `CLAUDE.md`
|
|
47
48
|
- `.djournal.json`, which points to the global project store
|
|
48
49
|
- for Claude Code installs, a narrow permission grant that lets the agent read
|
|
@@ -71,6 +72,14 @@ or RPC runs without a stored trust decision, pass `--approve`. djournal does not
|
|
|
71
72
|
edit Pi's trust file. Pi itself is not a filesystem sandbox; external containers
|
|
72
73
|
or sandboxes must expose the global store referenced by `.djournal.json`.
|
|
73
74
|
|
|
75
|
+
Grok Bot cannot run SessionStart or Stop hooks. `djournal install --harness
|
|
76
|
+
grok-bot` installs the portable skills, `AGENTS.md`, the project marker, and
|
|
77
|
+
the recipe at `integrations/grok-bot/`. It does not write `.codex/hooks.json`,
|
|
78
|
+
`.claude/settings.json`, or `.pi/extensions`. Register the skills in Grok from
|
|
79
|
+
that recipe. `djournal doctor` reports the CLI, `.agents/`, and the marker for
|
|
80
|
+
this harness and does not fail because hooks are absent. See
|
|
81
|
+
[Grok Bot](grok-bot.md).
|
|
82
|
+
|
|
74
83
|
To share selected work through the product repository, enable colocated
|
|
75
84
|
projection:
|
|
76
85
|
|
|
@@ -126,12 +135,15 @@ Install for one harness:
|
|
|
126
135
|
djournal install --harness codex
|
|
127
136
|
djournal install --harness claude-code
|
|
128
137
|
djournal install --harness pi
|
|
138
|
+
djournal install --harness grok-bot
|
|
129
139
|
```
|
|
130
140
|
|
|
141
|
+
`grok` and `grokbot` are aliases for `grok-bot`.
|
|
142
|
+
|
|
131
143
|
Install for multiple harnesses:
|
|
132
144
|
|
|
133
145
|
```bash
|
|
134
|
-
djournal install --harness codex,claude-code,pi
|
|
146
|
+
djournal install --harness codex,claude-code,pi,grok-bot
|
|
135
147
|
```
|
|
136
148
|
|
|
137
149
|
Install every supported harness:
|
|
@@ -158,7 +170,9 @@ djournal update check
|
|
|
158
170
|
project asset version, and cached npm release availability. `doctor` checks the
|
|
159
171
|
local environment and harness configuration. For Pi it reports extension
|
|
160
172
|
presence and reminds you that project trust is required; it does not inspect or
|
|
161
|
-
change Pi's private trust state.
|
|
173
|
+
change Pi's private trust state. For Grok Bot it reports the CLI, `.agents/`
|
|
174
|
+
skills and rules, the project marker, and recipe files, and points at skill
|
|
175
|
+
registration. Missing Grok hooks are expected and are not a failure.
|
|
162
176
|
|
|
163
177
|
## Update notifications
|
|
164
178
|
|
|
@@ -202,6 +216,7 @@ errors.
|
|
|
202
216
|
|
|
203
217
|
## Related docs
|
|
204
218
|
|
|
219
|
+
- [Grok Bot](grok-bot.md)
|
|
205
220
|
- [Remote Git sync setup](remote-sync.md)
|
|
206
221
|
- [Read-only team journal access](read-only-team-journal.md)
|
|
207
222
|
- [Uninstalling and reinstalling](uninstalling.md)
|
|
@@ -52,12 +52,13 @@ djournal status
|
|
|
52
52
|
|
|
53
53
|
Use `--instructions-only` when the person only needs portable journal skills and
|
|
54
54
|
does not need editor-specific hooks. Use a harness install instead when they
|
|
55
|
-
will use the journal from Codex, Claude Code, or
|
|
55
|
+
will use the journal from Codex, Claude Code, Pi, or Grok Bot:
|
|
56
56
|
|
|
57
57
|
```bash
|
|
58
58
|
djournal install --harness codex
|
|
59
59
|
djournal install --harness claude-code
|
|
60
60
|
djournal install --harness pi
|
|
61
|
+
djournal install --harness grok-bot
|
|
61
62
|
```
|
|
62
63
|
|
|
63
64
|
Do not run these commands in a read-only consumer setup:
|
package/docs/recall.md
CHANGED
package/docs/remote-sync.md
CHANGED
|
@@ -25,7 +25,7 @@ djournal config sync.mode colocated
|
|
|
25
25
|
djournal config sync.path .
|
|
26
26
|
djournal share --work 2026-07-03-01-example
|
|
27
27
|
djournal sync --work 2026-07-03-01-example
|
|
28
|
-
git add .agents .codex .claude AGENTS.md CLAUDE.md .djournal.json .journal
|
|
28
|
+
git add .agents .codex .claude .pi .grokbot integrations/grok-bot AGENTS.md CLAUDE.md .djournal.json .journal
|
|
29
29
|
git commit -m "chore: install djournal"
|
|
30
30
|
git push origin main
|
|
31
31
|
```
|
package/docs/uninstalling.md
CHANGED
|
@@ -25,16 +25,19 @@ so.
|
|
|
25
25
|
djournal uninstall --harness codex
|
|
26
26
|
djournal uninstall --harness claude-code
|
|
27
27
|
djournal uninstall --harness pi
|
|
28
|
+
djournal uninstall --harness grok-bot
|
|
28
29
|
```
|
|
29
30
|
|
|
30
31
|
## Uninstall multiple harnesses
|
|
31
32
|
|
|
32
33
|
```bash
|
|
33
|
-
djournal uninstall --harness codex,claude-code,pi
|
|
34
|
+
djournal uninstall --harness codex,claude-code,pi,grok-bot
|
|
34
35
|
```
|
|
35
36
|
|
|
36
37
|
Partial uninstall removes only the selected harness integration and keeps the
|
|
37
|
-
remaining harnesses installed.
|
|
38
|
+
remaining harnesses installed. For Grok Bot that is the owned `.grokbot/` and
|
|
39
|
+
`integrations/grok-bot/` files. Shared `.agents/` content remains until a full
|
|
40
|
+
uninstall.
|
|
38
41
|
|
|
39
42
|
## What remains durable
|
|
40
43
|
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Journal Hub recipe for Grok Bot
|
|
2
|
+
|
|
3
|
+
This directory is the shareable setup recipe for a Journal Hub bot. It is not
|
|
4
|
+
a published Team Bot or public template. Some teams cannot publish public bot
|
|
5
|
+
templates; this recipe is the open-source way to recreate the hub.
|
|
6
|
+
|
|
7
|
+
Install djournal into a project, register the portable journal skills, and
|
|
8
|
+
brief peer engineering bots. The hub does not replace those bots.
|
|
9
|
+
|
|
10
|
+
## Roles
|
|
11
|
+
|
|
12
|
+
**Journal Hub** installs and explains the journal, registers skills, and
|
|
13
|
+
reconciles shared history. Reconciliation is asynchronous: review `share`,
|
|
14
|
+
`sync`, and conflicts when asked. Do not block peer bots on that review.
|
|
15
|
+
|
|
16
|
+
**Engineering bots** write and resume their own journal entries. They use the
|
|
17
|
+
installed skills and the `djournal` / `journal` CLI against the project root.
|
|
18
|
+
They do not wait for the hub to take a turn before they can journal.
|
|
19
|
+
|
|
20
|
+
Local-only work stays unpublished until a person explicitly shares it. The hub
|
|
21
|
+
does not force publication.
|
|
22
|
+
|
|
23
|
+
## What the hub sets up
|
|
24
|
+
|
|
25
|
+
1. Confirm the project root, sync mode, peer engineering bots, and hub display
|
|
26
|
+
name by running [getting-started.md](getting-started.md). Ask one question
|
|
27
|
+
at a time.
|
|
28
|
+
2. Install the CLI (`npm install -g djournal`, or `npx djournal` for a one-off).
|
|
29
|
+
3. Run `djournal install --harness grok-bot --target <project-root>`.
|
|
30
|
+
4. Register each installed `.agents/skills/*/SKILL.md` as a Grok shared
|
|
31
|
+
workflow. Follow [skill-registration.md](skill-registration.md). Rewrite
|
|
32
|
+
paths from the install target. Do not hardcode a machine path, owner, or
|
|
33
|
+
agent id.
|
|
34
|
+
5. Register [checkup.md](checkup.md) as **Checkup with Journal Hub**.
|
|
35
|
+
6. Send [peer-briefing.md](peer-briefing.md) to the engineering bots named
|
|
36
|
+
during setup.
|
|
37
|
+
|
|
38
|
+
Grok Bot cannot emit SessionStart or Stop hooks. Do not invent hook files.
|
|
39
|
+
`AGENTS.md`, the skills, and the CLI are the harness.
|
|
40
|
+
|
|
41
|
+
## Files
|
|
42
|
+
|
|
43
|
+
| File | Use |
|
|
44
|
+
| --- | --- |
|
|
45
|
+
| `getting-started.md` | First-run questions and install steps |
|
|
46
|
+
| `skill-registration.md` | Map package skills to Grok workflow ids |
|
|
47
|
+
| `checkup.md` | Later share/sync/conflict review |
|
|
48
|
+
| `peer-briefing.md` | Short message for engineering bots |
|
|
49
|
+
|
|
50
|
+
Package docs: `docs/grok-bot.md`.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: Checkup with Journal Hub
|
|
3
|
+
description: Review djournal status, shared work, and sync conflicts for a project without taking over engineering bots or publishing local-only work.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Checkup with Journal Hub
|
|
7
|
+
|
|
8
|
+
Use this when someone asks the hub to review journal health. Engineering bots
|
|
9
|
+
keep writing their own entries. This checkup is an asynchronous reconcile
|
|
10
|
+
pass.
|
|
11
|
+
|
|
12
|
+
## Steps
|
|
13
|
+
|
|
14
|
+
1. If `<project-root>` is not already known, ask for the directory that
|
|
15
|
+
contains `.djournal.json`. Ask only that question, then continue.
|
|
16
|
+
2. Read status and install health:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
djournal status --target <project-root>
|
|
20
|
+
djournal doctor --target <project-root>
|
|
21
|
+
djournal work list --target <project-root>
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
3. Report which work items are `local_only` and which are shared. Do not run
|
|
25
|
+
`djournal share` unless the operator explicitly chooses a work item to
|
|
26
|
+
publish.
|
|
27
|
+
4. When sync is enabled, pull the shared projection and report conflicts:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
djournal pull --target <project-root>
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
If the command reports conflicts, quote the conflict paths and stop. Do not
|
|
34
|
+
overwrite either side.
|
|
35
|
+
5. Run `djournal sync --target <project-root>` only for a work item the
|
|
36
|
+
operator has already shared and only when they ask to project it.
|
|
37
|
+
6. Summarize what peers should do next. Point them at the journal skills and
|
|
38
|
+
`djournal` / `journal` commands. Do not ask them to wait for another hub
|
|
39
|
+
turn before they journal.
|
|
40
|
+
|
|
41
|
+
Hooks are not part of this harness. A missing hook file is healthy.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: journal-hub-getting-started
|
|
3
|
+
description: Set up djournal for Grok Bot by confirming the project root, sync mode, peer engineering bots, and hub display name, then installing the skill-only harness.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Journal Hub getting started
|
|
7
|
+
|
|
8
|
+
Run this once when a Journal Hub bot is imported. Ask the questions below one
|
|
9
|
+
at a time. Wait for the answer before asking the next question. Use the
|
|
10
|
+
answers only for this setup. Do not invent project paths, bot names, or a
|
|
11
|
+
display name.
|
|
12
|
+
|
|
13
|
+
## Questions
|
|
14
|
+
|
|
15
|
+
1. **Project root.** Which directory should receive the journal install? It
|
|
16
|
+
must be the directory that will contain `.djournal.json` and `.agents/`.
|
|
17
|
+
Call that path `<project-root>` in later commands.
|
|
18
|
+
2. **Sync mode.** Should shared journal history live in that same repository
|
|
19
|
+
(`colocated`) or in a separate journal repository (`standalone`)? Leave sync
|
|
20
|
+
disabled until the operator asks to turn it on.
|
|
21
|
+
3. **Engineering bots.** Which peer bots should write journal entries
|
|
22
|
+
themselves? Record display names only. Agent ids are not required.
|
|
23
|
+
4. **Hub display name.** What should people call this Journal Hub?
|
|
24
|
+
|
|
25
|
+
## After the answers
|
|
26
|
+
|
|
27
|
+
1. Install the CLI if it is not already available:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npm install -g djournal
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Use `npx djournal` when a global install is not appropriate.
|
|
34
|
+
|
|
35
|
+
2. Install the skill-only harness. This copies rules, skills, `AGENTS.md`, the
|
|
36
|
+
project marker, and this recipe. It does not write hook config.
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
djournal install --harness grok-bot --target <project-root>
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
3. Register journal skills from `<project-root>/.agents/skills` using
|
|
43
|
+
`skill-registration.md`. Resolve every rule path from `<project-root>`.
|
|
44
|
+
4. Register `checkup.md` as the shared workflow **Checkup with Journal Hub**
|
|
45
|
+
(`journal-hub-checkup`).
|
|
46
|
+
5. Send `peer-briefing.md` to each engineering bot from step 3, with
|
|
47
|
+
`<project-root>` and the hub display name filled in.
|
|
48
|
+
|
|
49
|
+
Do not publish a public bot template as part of this setup. Do not share or
|
|
50
|
+
sync work unless the operator explicitly asks.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Peer engineering bot briefing
|
|
2
|
+
|
|
3
|
+
Send this to each engineering bot named during getting started. Replace the
|
|
4
|
+
angle-bracket fields. Keep the message short.
|
|
5
|
+
|
|
6
|
+
```text
|
|
7
|
+
<hub-display-name> can help with the project journal, and you can use it
|
|
8
|
+
without waiting for the hub.
|
|
9
|
+
|
|
10
|
+
Project root: <project-root>
|
|
11
|
+
Install (already done when the hub finished setup):
|
|
12
|
+
djournal install --harness grok-bot --target <project-root>
|
|
13
|
+
|
|
14
|
+
Use the journal skills and the djournal / journal CLI against that root.
|
|
15
|
+
Start meaningful work with the journal workflow skill. Resume, plan, research,
|
|
16
|
+
decide, and close entries yourself.
|
|
17
|
+
|
|
18
|
+
<hub-display-name> is an async reconciler. Ask it to run Checkup with Journal
|
|
19
|
+
Hub when you want status, share/sync review, or conflict paths. Local-only
|
|
20
|
+
work stays unpublished until someone explicitly shares it. There are no Grok
|
|
21
|
+
session hooks; skills and the CLI are the integration.
|
|
22
|
+
```
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Register journal skills in Grok Bot
|
|
2
|
+
|
|
3
|
+
Grok Bot loads shared workflows. It does not load `.agents/skills` by itself
|
|
4
|
+
and it has no session hooks. After `djournal install --harness grok-bot`,
|
|
5
|
+
register each installed skill with the harness **UpdateSkill** action.
|
|
6
|
+
|
|
7
|
+
Keep the upstream skill files generic. Rewrite a copy for the payload. Do not
|
|
8
|
+
edit the installed `SKILL.md` files in place, and do not embed a workspace
|
|
9
|
+
path, owner name, or agent id.
|
|
10
|
+
|
|
11
|
+
## Suggested workflow ids
|
|
12
|
+
|
|
13
|
+
| Installed skill directory | Suggested workflow id |
|
|
14
|
+
| --- | --- |
|
|
15
|
+
| `journal-workflow` | `journal-workflow` |
|
|
16
|
+
| `resume` | `journal-resume` |
|
|
17
|
+
| `init-work` | `journal-init-work` |
|
|
18
|
+
| `switch` | `journal-switch` |
|
|
19
|
+
| `journal` | `journal-entry` |
|
|
20
|
+
| `plan` | `journal-plan` |
|
|
21
|
+
| `recall` | `journal-recall` |
|
|
22
|
+
| `decision` | `journal-decision` |
|
|
23
|
+
| `document` | `journal-document` |
|
|
24
|
+
| `research-codebase` | `journal-research-codebase` |
|
|
25
|
+
| `research-web` | `journal-research-web` |
|
|
26
|
+
| `reinforce` | `journal-reinforce` |
|
|
27
|
+
| `audit` | `journal-audit` |
|
|
28
|
+
| `reconcile` | `journal-reconcile` |
|
|
29
|
+
|
|
30
|
+
Hub-only prose in this recipe is not an upstream skill:
|
|
31
|
+
|
|
32
|
+
| Recipe file | Suggested workflow id | Title |
|
|
33
|
+
| --- | --- | --- |
|
|
34
|
+
| `getting-started.md` | `journal-hub-getting-started` | Journal Hub getting started |
|
|
35
|
+
| `checkup.md` | `journal-hub-checkup` | Checkup with Journal Hub |
|
|
36
|
+
|
|
37
|
+
## Build an UpdateSkill payload
|
|
38
|
+
|
|
39
|
+
1. Set `<project-root>` to the install target (the directory that contains
|
|
40
|
+
`.djournal.json` and `.agents/`).
|
|
41
|
+
2. Read `<project-root>/.agents/skills/<directory>/SKILL.md`.
|
|
42
|
+
3. Take `name` and `description` from the YAML frontmatter. Use the suggested
|
|
43
|
+
workflow id from the table. Do not invent a project-specific id.
|
|
44
|
+
4. Rewrite the body into the UpdateSkill payload:
|
|
45
|
+
- Point rule reads at `<project-root>/.agents/rules/...`. Journal root
|
|
46
|
+
resolution stays the procedure in `<project-root>/.agents/rules/STATE.md`:
|
|
47
|
+
use `.djournal.json` in the project root when it exists, otherwise the
|
|
48
|
+
project-local `.journal`.
|
|
49
|
+
- Write CLI examples as `djournal <command> --target <project-root>` or
|
|
50
|
+
`journal <command> --target <project-root>`. Replace `<project-root>` with
|
|
51
|
+
the confirmed install target at registration time.
|
|
52
|
+
- When one skill should point at another, use a Grok sibling link:
|
|
53
|
+
`[Journal workflow](sand-workflow:journal-workflow)`. Use the suggested id
|
|
54
|
+
after `sand-workflow:`.
|
|
55
|
+
5. Register that id, name, description, and rewritten body with UpdateSkill.
|
|
56
|
+
6. Repeat for every row, then register the two hub workflows from this
|
|
57
|
+
directory the same way.
|
|
58
|
+
|
|
59
|
+
Re-run this mapping after `djournal upgrade` when skill text changes. The
|
|
60
|
+
portable package files remain the source. The registered workflows are a
|
|
61
|
+
projection for Grok Bot.
|
package/lib/installer/index.js
CHANGED
|
@@ -23,12 +23,13 @@ const {
|
|
|
23
23
|
} = require("../update-checker.js");
|
|
24
24
|
|
|
25
25
|
const SCHEMA_VERSION = 1;
|
|
26
|
-
const SUPPORTED_HARNESSES = ["codex", "claude-code", "pi"];
|
|
26
|
+
const SUPPORTED_HARNESSES = ["codex", "claude-code", "pi", "grok-bot"];
|
|
27
27
|
const FUTURE_HARNESSES = ["opencode", "zed"];
|
|
28
28
|
const HARNESS_CONFIG_PATHS = {
|
|
29
29
|
codex: ".codex/hooks.json",
|
|
30
30
|
"claude-code": ".claude/settings.json",
|
|
31
31
|
};
|
|
32
|
+
const GROK_BOT_ASSET_DIRECTORIES = [".grokbot", "integrations/grok-bot"];
|
|
32
33
|
const MANIFEST_PATH = ".journal/.install/manifest.json";
|
|
33
34
|
const TRANSACTION_PATH = ".journal/.install/transaction.json";
|
|
34
35
|
const PROJECT_MARKER_PATH = ".djournal.json";
|
|
@@ -288,6 +289,7 @@ function detectHarnesses(target, options = {}) {
|
|
|
288
289
|
"claude-code": exists("claude") || fs.existsSync(path.join(target, ".claude")) || fs.existsSync(path.join(target, "CLAUDE.md")),
|
|
289
290
|
opencode: exists("opencode") || fs.existsSync(path.join(target, ".opencode")) || fs.existsSync(path.join(target, "opencode.json")),
|
|
290
291
|
pi: exists("pi") || fs.existsSync(path.join(target, ".pi")),
|
|
292
|
+
"grok-bot": fs.existsSync(path.join(target, ".grokbot")),
|
|
291
293
|
zed: exists("zed") || fs.existsSync(path.join(target, ".zed")),
|
|
292
294
|
};
|
|
293
295
|
return {
|
|
@@ -299,6 +301,7 @@ function detectHarnesses(target, options = {}) {
|
|
|
299
301
|
|
|
300
302
|
function normalizeHarness(name) {
|
|
301
303
|
if (name === "claude") return "claude-code";
|
|
304
|
+
if (name === "grok" || name === "grokbot") return "grok-bot";
|
|
302
305
|
return name;
|
|
303
306
|
}
|
|
304
307
|
|
|
@@ -500,6 +503,16 @@ function harnessFragment(sourceRoot, harness) {
|
|
|
500
503
|
return parseJson(fs.readFileSync(path.join(sourceRoot, relative)), relative);
|
|
501
504
|
}
|
|
502
505
|
|
|
506
|
+
function listOwnedAssets(sourceRoot, directory) {
|
|
507
|
+
const absolute = path.join(sourceRoot, directory);
|
|
508
|
+
if (!fs.existsSync(absolute) || !fs.statSync(absolute).isDirectory()) {
|
|
509
|
+
throw new InstallerError(`missing harness assets: ${directory}`, "MISSING_ASSETS");
|
|
510
|
+
}
|
|
511
|
+
const files = listFiles(absolute).map((relative) => `${directory}/${relative}`);
|
|
512
|
+
if (!files.length) throw new InstallerError(`missing harness assets: ${directory}`, "MISSING_ASSETS");
|
|
513
|
+
return files;
|
|
514
|
+
}
|
|
515
|
+
|
|
503
516
|
function planInstall(sourceRoot, target, harnesses, oldManifest, store) {
|
|
504
517
|
const old = recordMap(oldManifest);
|
|
505
518
|
const records = [];
|
|
@@ -538,6 +551,14 @@ function planInstall(sourceRoot, target, harnesses, oldManifest, store) {
|
|
|
538
551
|
);
|
|
539
552
|
records.push(extension.record); operations.push(extension.op);
|
|
540
553
|
}
|
|
554
|
+
if (harnesses.includes("grok-bot")) {
|
|
555
|
+
for (const directory of GROK_BOT_ASSET_DIRECTORIES) {
|
|
556
|
+
for (const relative of listOwnedAssets(sourceRoot, directory)) {
|
|
557
|
+
const result = copyRecord(sourceRoot, target, relative, old.get(relative), "grok-bot");
|
|
558
|
+
records.push(result.record); operations.push(result.op);
|
|
559
|
+
}
|
|
560
|
+
}
|
|
561
|
+
}
|
|
541
562
|
|
|
542
563
|
const desired = new Set(records.map((record) => record.path));
|
|
543
564
|
for (const record of oldManifest?.files || []) {
|
|
@@ -1212,6 +1233,49 @@ function doctor(options) {
|
|
|
1212
1233
|
detail: `${assetStatus}; Pi project trust required`,
|
|
1213
1234
|
});
|
|
1214
1235
|
}
|
|
1236
|
+
if (loadedManifest?.harnesses?.includes("grok-bot")) {
|
|
1237
|
+
const agentsReady = fs.existsSync(path.join(target, ".agents/rules")) && fs.existsSync(path.join(target, ".agents/skills"));
|
|
1238
|
+
checks.push({
|
|
1239
|
+
name: "grok-bot agents",
|
|
1240
|
+
ok: agentsReady,
|
|
1241
|
+
detail: agentsReady ? ".agents rules and skills present" : "missing .agents rules or skills",
|
|
1242
|
+
});
|
|
1243
|
+
let markerOk = false;
|
|
1244
|
+
let markerDetail = "missing project marker";
|
|
1245
|
+
try {
|
|
1246
|
+
const marker = readProjectMarker(target);
|
|
1247
|
+
markerOk = Boolean(marker?.projectKey && marker?.journalRoot);
|
|
1248
|
+
if (markerOk) markerDetail = "project marker present";
|
|
1249
|
+
} catch (error) {
|
|
1250
|
+
markerDetail = error.message;
|
|
1251
|
+
}
|
|
1252
|
+
checks.push({ name: "grok-bot marker", ok: markerOk, detail: markerDetail });
|
|
1253
|
+
const commandAvailable = options.commandExists || commandExists;
|
|
1254
|
+
const cli = ["djournal", "journal"].find((command) => commandAvailable(command));
|
|
1255
|
+
checks.push({
|
|
1256
|
+
name: "grok-bot cli",
|
|
1257
|
+
ok: true,
|
|
1258
|
+
detail: cli
|
|
1259
|
+
? `${cli} on PATH; register skills from integrations/grok-bot/skill-registration.md; hooks are not used`
|
|
1260
|
+
: "djournal CLI not on PATH; register skills from integrations/grok-bot/skill-registration.md; hooks are not used",
|
|
1261
|
+
});
|
|
1262
|
+
const owned = loadedManifest.files.filter((item) => item.harness === "grok-bot");
|
|
1263
|
+
const statuses = owned.map((record) => recordStatus(target, record));
|
|
1264
|
+
const assetStatus = owned.length && statuses.every((item) => item === "clean" || item === "modified")
|
|
1265
|
+
? (statuses.every((item) => item === "clean") ? "clean" : "modified")
|
|
1266
|
+
: "missing";
|
|
1267
|
+
checks.push({
|
|
1268
|
+
name: "grok-bot assets",
|
|
1269
|
+
ok: assetStatus === "clean" || assetStatus === "modified",
|
|
1270
|
+
detail: `${assetStatus}; instruction/skill-only; register skills from integrations/grok-bot/skill-registration.md`,
|
|
1271
|
+
});
|
|
1272
|
+
} else if (detected.evidence["grok-bot"]) {
|
|
1273
|
+
checks.push({
|
|
1274
|
+
name: "grok-bot",
|
|
1275
|
+
ok: true,
|
|
1276
|
+
detail: "marker present; install with djournal install --harness grok-bot. Hooks are not used. See docs/grok-bot.md",
|
|
1277
|
+
});
|
|
1278
|
+
}
|
|
1215
1279
|
const { inspectSnapshot } = require("../recall/snapshot.js");
|
|
1216
1280
|
const recallCache = inspectSnapshot(projectContext(target, options), options);
|
|
1217
1281
|
checks.push({
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "djournal",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.0",
|
|
4
4
|
"description": "Durable project memory for coding agents, stored as linked Markdown",
|
|
5
5
|
"type": "commonjs",
|
|
6
6
|
"bin": {
|
|
@@ -11,7 +11,9 @@
|
|
|
11
11
|
".agents/",
|
|
12
12
|
".claude/",
|
|
13
13
|
".codex/",
|
|
14
|
+
".grokbot/",
|
|
14
15
|
".pi/",
|
|
16
|
+
"integrations/",
|
|
15
17
|
"AGENTS.md",
|
|
16
18
|
"CLAUDE.md",
|
|
17
19
|
"LICENSE",
|