djournal 0.12.1 → 0.13.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.
Files changed (39) hide show
  1. package/.agents/adapters/contract.md +5 -0
  2. package/.agents/adapters/shared/journal-hook.js +2 -2
  3. package/.agents/rules/AUTOMATION.md +30 -7
  4. package/.agents/rules/FEAT.md +1 -1
  5. package/.agents/rules/STATE.md +3 -3
  6. package/.agents/skills/{audit → journal-audit}/SKILL.md +1 -1
  7. package/.agents/skills/journal-audit/agents/openai.yaml +4 -0
  8. package/.agents/skills/{decision → journal-decision}/SKILL.md +1 -1
  9. package/.agents/skills/journal-decision/agents/openai.yaml +4 -0
  10. package/.agents/skills/{document → journal-document}/SKILL.md +2 -2
  11. package/.agents/skills/{journal → journal-entry}/SKILL.md +2 -2
  12. package/.agents/skills/{init-work → journal-init-work}/SKILL.md +1 -1
  13. package/.agents/skills/{plan → journal-plan}/SKILL.md +9 -3
  14. package/.agents/skills/journal-plan/agents/openai.yaml +4 -0
  15. package/.agents/skills/{recall → journal-recall}/SKILL.md +9 -4
  16. package/.agents/skills/journal-recall/agents/openai.yaml +4 -0
  17. package/.agents/skills/{reconcile → journal-reconcile}/SKILL.md +3 -3
  18. package/.agents/skills/journal-reconcile/agents/openai.yaml +4 -0
  19. package/.agents/skills/{reinforce → journal-reinforce}/SKILL.md +4 -4
  20. package/.agents/skills/{research-codebase → journal-research-codebase}/SKILL.md +1 -1
  21. package/.agents/skills/{research-web → journal-research-web}/SKILL.md +1 -1
  22. package/.agents/skills/{resume → journal-resume}/SKILL.md +8 -3
  23. package/.agents/skills/journal-resume/agents/openai.yaml +4 -0
  24. package/.agents/skills/{switch → journal-switch}/SKILL.md +3 -3
  25. package/.agents/skills/journal-workflow/SKILL.md +31 -12
  26. package/AGENTS.md +11 -2
  27. package/README.md +5 -1
  28. package/docs/installation.md +48 -0
  29. package/docs/read-only-team-journal.md +2 -2
  30. package/docs/recall.md +7 -2
  31. package/docs/remote-sync.md +1 -1
  32. package/integrations/grok-bot/skill-registration.md +17 -17
  33. package/lib/installer/index.js +1 -1
  34. package/lib/setup.js +1 -1
  35. package/package.json +1 -1
  36. package/spec.md +26 -24
  37. package/.agents/skills/audit/agents/openai.yaml +0 -4
  38. package/.agents/skills/decision/agents/openai.yaml +0 -4
  39. package/.agents/skills/reconcile/agents/openai.yaml +0 -4
@@ -16,6 +16,11 @@ 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
+ Start/prompt reminders name the `journal-*` skills and point to the invocation
20
+ contract in `AUTOMATION.md`. They do not infer which skill a request needs,
21
+ track skill calls, or block native memory or planning tools. Closure validation
22
+ does not prove that resume, recall, or planning happened earlier.
23
+
19
24
  Grok Bot is an instruction and skill-only harness. It has no SessionStart or
20
25
  Stop hooks, so it omits every semantic event. Compliance is the installed
21
26
  skills, `AGENTS.md`, and the `djournal` / `journal` CLI. The recipe lives at
@@ -303,7 +303,7 @@ function handle(payload, options = {}) {
303
303
  ? updateNotice(runUpdateCheck(root, options.updateRunner))
304
304
  : "";
305
305
  const suffix = selectionSuffix(root, payload, env);
306
- return context(event, `Follow AGENTS.md and .agents/rules/AUTOMATION.md.${pullMessage}${updateMessage}${suffix}`);
306
+ return context(event, `Follow AGENTS.md and .agents/rules/AUTOMATION.md.${pullMessage}${updateMessage}${suffix} When project context is needed, load journal-resume; for prior decisions/history, load journal-recall; before work meeting the planning threshold, load journal-plan. Invoke the exact skill name, or read .agents/skills/<skill-name>/SKILL.md if unavailable. Native memory, conversation resume, and plan mode do not replace these journal steps. Honor journal: off.`);
307
307
  }
308
308
 
309
309
  if (event === "UserPromptSubmit") {
@@ -318,7 +318,7 @@ function handle(payload, options = {}) {
318
318
  : `The requested journal pull failed and must be resolved before publication: ${result.message}`;
319
319
  return context(event, `${pullMessage} Classify this request using the ambient journal workflow and run journal sync if publication was requested.`);
320
320
  }
321
- return context(event, "Classify this request using the ambient journal workflow. Close meaningful changed state before the final response, without adding ceremony to read-only or trivial work.");
321
+ return context(event, "Classify this request using the ambient journal workflow. Load journal-workflow and the selected journal-* skills when required; invoke the skill or read its .agents/skills/<skill-name>/SKILL.md. Close meaningful changed state before the final response, without adding ceremony to read-only or trivial work.");
322
322
  }
323
323
 
324
324
  if (event !== "Stop") return {};
@@ -17,20 +17,43 @@ Classify each request before acting:
17
17
  Classification requires semantic judgment. File changes alone do not establish
18
18
  that a task was meaningful.
19
19
 
20
+ ## Skill invocation
21
+
22
+ When a checkpoint calls for a skill, load it by its exact `journal-*` name
23
+ through the harness skill tool. If that mechanism is unavailable or the skill
24
+ is not listed, read `.agents/skills/<skill-name>/SKILL.md` and follow it. Naming
25
+ a skill in a response, recalling a conversation, or entering native plan mode
26
+ does not execute its procedure. If neither the skill nor its file is available,
27
+ report the missing installation instead of claiming it ran.
28
+
29
+ Use these routes when the request needs project memory:
30
+
31
+ | Intent | Skill | Required evidence or output |
32
+ | --- | --- | --- |
33
+ | Continue work, recover state after compaction, find next steps | `journal-resume` | Session-selected work and latest canonical spine entry |
34
+ | Explain an earlier choice, retrieve project history or related evidence | `journal-recall` | Relevant canonical entries and source citations |
35
+ | Design work meeting the plan threshold below | `journal-plan` | Canonical plan before implementation, or an existing applicable plan |
36
+
37
+ Native memory and session summaries can help locate evidence; they do not
38
+ replace canonical journal reads. Do not rerun a skill or reload unchanged
39
+ context already available for this task. Keep the opt-out and trivial-work
40
+ exceptions below. A harness read-only/plan mode still forbids writes: defer
41
+ persisting a journal plan until writes are allowed, and state that limitation.
42
+
20
43
  ## Start checkpoint
21
44
 
22
45
  - If the user says `journal: off`, skip ambient journal reads and writes for the
23
46
  request unless another explicit instruction requires them.
24
- - If the resolved journal root's `state.json` selects active work, use `resume`
47
+ - If the resolved journal root's `state.json` selects active work, use `journal-resume`
25
48
  when historical context can affect the result.
26
49
  - If no active work exists and the request clearly starts a new durable work
27
- stream, use `init-work`. Ask only when its identity or scope is materially
50
+ stream, use `journal-init-work`. Ask only when its identity or scope is materially
28
51
  ambiguous.
29
52
  - Do not create a work item for a read-only question or incidental edit.
30
53
 
31
54
  ## Plan threshold
32
55
 
33
- Use `plan` before implementation when the work has multiple dependent phases,
56
+ Use `journal-plan` before implementation when the work has multiple dependent phases,
34
57
  meaningful design choices, risky migration behavior, cross-component effects,
35
58
  or a validation strategy that should survive the current conversation.
36
59
 
@@ -39,10 +62,10 @@ validate. Existing user-approved plans do not need another plan.
39
62
 
40
63
  ## Work checkpoint
41
64
 
42
- - Use `research-codebase` or `research-web` only when the findings should remain
65
+ - Use `journal-research-codebase` or `journal-research-web` only when the findings should remain
43
66
  durable evidence.
44
- - Use `decision` when an accepted choice and its rationale constrain later work.
45
- - Use `document` for a durable synthesized reference.
67
+ - Use `journal-decision` when an accepted choice and its rationale constrain later work.
68
+ - Use `journal-document` for a durable synthesized reference.
46
69
  - Never copy semantic write logic into an orchestration hook or adapter.
47
70
 
48
71
  ## Closure checkpoint
@@ -50,7 +73,7 @@ validate. Existing user-approved plans do not need another plan.
50
73
  Before the final response:
51
74
 
52
75
  1. Decide whether meaningful journal state changed.
53
- 2. If it did, use `journal` once after validation and reference supporting
76
+ 2. If it did, use `journal-entry` once after validation and reference supporting
54
77
  entries actually used.
55
78
  3. Check the latest spine entry before writing. Update or skip when a new entry
56
79
  would describe the same completed outcome.
@@ -43,7 +43,7 @@ Example: `2026-06-29-01-portable-journal-skill-improvements`.
43
43
 
44
44
  ## Initialization
45
45
 
46
- `init-work` MUST:
46
+ `journal-init-work` MUST:
47
47
 
48
48
  1. Inspect existing work folders to select a non-conflicting daily sequence.
49
49
  2. Create the complete directory structure above.
@@ -43,9 +43,9 @@ Session binding does not change this file and is not durable journal history.
43
43
 
44
44
  ## Missing or invalid state
45
45
 
46
- - `init-work` may create `<journal-root>/state.json` after creating the work
46
+ - `journal-init-work` may create `<journal-root>/state.json` after creating the work
47
47
  folder and `work.md`.
48
- - `switch` may repair state only after the user selects an existing work item.
49
- - Other write skills MUST stop with: `No active work found. Run init-work or switch first.`
48
+ - `journal-switch` may repair state only after the user selects an existing work item.
49
+ - Other write skills MUST stop with: `No active work found. Run journal-init-work or journal-switch first.`
50
50
  - Read-only recall across all work items may proceed without active state.
51
51
  - Never guess the active work item from recency when a write would result.
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: audit
2
+ name: journal-audit
3
3
  description: Inspect filesystem journal integrity without making changes. Use to report malformed or legacy metadata, broken links, misclassified entries, buried decisions, orphan supporting files, weak summaries, wrong work status, duplicate numbering, timeline drift, or safety concerns.
4
4
  ---
5
5
 
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Journal Audit"
3
+ short_description: "Report journal integrity issues without changes"
4
+ default_prompt: "Use $journal-audit to inspect the active journal work item and report integrity issues."
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: decision
2
+ name: journal-decision
3
3
  description: Record a clear technical or product decision as a standalone canonical supporting entry and link its evidence. Use when an option has been chosen, rationale must be preserved, or a prior decision is explicitly superseded.
4
4
  ---
5
5
 
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Journal Decision"
3
+ short_description: "Record and link a durable technical decision"
4
+ default_prompt: "Use $journal-decision to record this decision and link its supporting context."
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: document
2
+ name: journal-document
3
3
  description: Synthesize existing journal, codebase research, and web research into a concise canonical supporting document. Use when the user asks for a durable technical decision aid, how-to, walkthrough, tutorial, or architecture reference.
4
4
  ---
5
5
 
@@ -28,7 +28,7 @@ Distill and connect evidence; do not concatenate source material.
28
28
  - Reconcile codebase reality with external findings.
29
29
  - Retain source attribution and note unresolved contradictions.
30
30
  - Produce a standalone reference shorter than its inputs.
31
- - Do not turn a decision aid into a recorded decision; use `decision` after an
31
+ - Do not turn a decision aid into a recorded decision; use `journal-decision` after an
32
32
  option is actually chosen.
33
33
 
34
34
  ## Create the supporting entry
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: journal
2
+ name: journal-entry
3
3
  description: Write a canonical journal entry for meaningful work completed in the current session. Use at the end of implementation, investigation, or a material status update.
4
4
  ---
5
5
 
@@ -102,6 +102,6 @@ diffs, transcripts, environment dumps, secrets, or unbounded command output.
102
102
 
103
103
  - Document only the current logical session.
104
104
  - Do not claim tests passed unless they were run successfully.
105
- - Do not create standalone decision entries implicitly; use `decision` when the
105
+ - Do not create standalone decision entries implicitly; use `journal-decision` when the
106
106
  rationale deserves durable supporting context.
107
107
  - Keep the entry concise and evidence-backed.
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: init-work
2
+ name: journal-init-work
3
3
  description: Initialize a new filesystem journal work item and make it active. Use when starting a new project or durable unit of work that does not already exist.
4
4
  ---
5
5
 
@@ -1,6 +1,6 @@
1
1
  ---
2
- name: plan
3
- description: Design a concrete unit of work and write a canonical plan entry before implementation. Use for features, fixes, migrations, or improvements that need a durable phased plan.
2
+ name: journal-plan
3
+ description: Design and persist a djournal plan before multi-phase features, risky fixes, migrations, or changes with cross-component decisions. Use when implementation needs a durable plan; a chat checklist or native plan mode alone is not a journal plan. Skip trivial changes and reuse an applicable accepted plan.
4
4
  ---
5
5
 
6
6
  # Plan work
@@ -8,6 +8,12 @@ description: Design a concrete unit of work and write a canonical plan entry bef
8
8
  This skill produces a plan entry only. Do not implement source changes while
9
9
  using it.
10
10
 
11
+ A native planning tool may help develop the design. The durable output of this
12
+ skill is the canonical journal plan linked to its work item. If the harness is
13
+ in a read-only mode, prepare the proposal and defer the write until permitted;
14
+ do not claim the journal plan was saved. Reuse an applicable accepted journal
15
+ plan instead of creating a duplicate.
16
+
11
17
  ## Load context
12
18
 
13
19
  1. Read completely:
@@ -21,7 +27,7 @@ using it.
21
27
  active work is unavailable.
22
28
  3. Read the latest spine entry when present. Its timeline is the primary index.
23
29
  4. List `_research/`, `docs/`, and `decisions/`; read only files relevant to the requested plan.
24
- 5. If essential codebase context is absent, invoke `research-codebase` first.
30
+ 5. If essential codebase context is absent, invoke `journal-research-codebase` first.
25
31
  Use sub-agents only when the current collaboration policy and user allow it.
26
32
 
27
33
  ## Analyze
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Journal Plan"
3
+ short_description: "Write a durable djournal implementation plan"
4
+ default_prompt: "Use $journal-plan to design this change and save the implementation plan in the journal."
@@ -1,12 +1,17 @@
1
1
  ---
2
- name: recall
3
- description: Retrieve read-only historical knowledge from filesystem journal metadata, timelines, links, research, decisions, and docs. Use for project overviews, rationale, technical history, status, chronology, onboarding, or locating a specific past entry.
2
+ name: journal-recall
3
+ description: Search djournal project history and cite canonical Markdown when asked why a decision was made, what was tried, what changed, or what prior work constrains a task. Use for project history, rationale, onboarding, and evidence lookup even when native agent memory has a possible answer. Read-only.
4
4
  ---
5
5
 
6
6
  # Recall journal history
7
7
 
8
8
  Answer from journal evidence. Do not modify files or invent missing history.
9
9
 
10
+ Use canonical journal entries as sources. Native memory and conversation history
11
+ may suggest search terms, but do not substitute for retrieving the journal
12
+ evidence. A CLI search locates sources; read the relevant entries before drawing
13
+ conclusions or claiming the recall procedure is complete.
14
+
10
15
  ## Load contracts
11
16
 
12
17
  Read `.agents/rules/METADATA.md`, `LINKS.md`, `SAFETY.md`, `JOURNAL.md`, and
@@ -103,5 +108,5 @@ work, add a brief `Reinforcement` note before the Sources table:
103
108
  steps, or the user asked to connect it to current work.
104
109
  - `ambiguous`: list candidate source paths and say what target is unclear.
105
110
 
106
- The surrounding workflow, not recall, decides whether to call `journal`,
107
- `decision`, or `reinforce` before the final response.
111
+ The surrounding workflow, not recall, decides whether to call `journal-entry`,
112
+ `journal-decision`, or `journal-reinforce` before the final response.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Journal Recall"
3
+ short_description: "Find prior project decisions and journal evidence"
4
+ default_prompt: "Use $journal-recall to find the prior project decisions relevant to this task."
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: reconcile
2
+ name: journal-reconcile
3
3
  description: Audit and conservatively repair clear filesystem journal discrepancies. Use to add legacy frontmatter incrementally, repair deterministic metadata or links, extract explicit decisions, improve weak summaries, or correct unambiguous work status while preserving history.
4
4
  ---
5
5
 
@@ -29,7 +29,7 @@ Flags may be combined. Never infer an ambiguous scope for writes.
29
29
  - `.agents/rules/LINKS.md`
30
30
  - `.agents/rules/SAFETY.md`
31
31
  - `.agents/rules/STATE.md`
32
- - `.agents/skills/audit/SKILL.md`
32
+ - `.agents/skills/journal-audit/SKILL.md`
33
33
  2. Perform the audit procedure over the complete scope before changing files.
34
34
  3. Present each proposed fix with path, fields, evidence, and reason.
35
35
 
@@ -51,7 +51,7 @@ Apply a fix only when its result is unique and supported by the contracts:
51
51
  - Add a missing link when the body explicitly cites one uniquely resolved target
52
52
  and relation semantics are clear.
53
53
  - Link an orphan supporting entry when one unique owning entry explicitly uses it.
54
- - Extract an explicit buried decision through the `decision` workflow, preserve
54
+ - Extract an explicit buried decision through the `journal-decision` workflow, preserve
55
55
  the original body, and add a concise pointer only when useful.
56
56
  - Set work status to `completed` only when the recorded outcome is unequivocally
57
57
  complete; otherwise flag it.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Journal Reconcile"
3
+ short_description: "Repair clear journal integrity issues safely"
4
+ default_prompt: "Use $journal-reconcile to report and safely repair clear journal integrity issues."
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: reinforce
2
+ name: journal-reinforce
3
3
  description: "Link recalled journal evidence into current or already-closed work. Use when recall found material sources that should reinforce, clarify, contradict, or supersede an existing journal entry, especially after recall ended read-only with `journal-status: not-needed` or when the user explicitly asks to update entries with recalled evidence."
4
4
  ---
5
5
 
@@ -49,12 +49,12 @@ follow-up entry would be misleading.
49
49
 
50
50
  ## Choose the mutation
51
51
 
52
- - Current in-progress closure: let `journal` create the entry and include the
52
+ - Current in-progress closure: let `journal-entry` create the entry and include the
53
53
  recalled source links.
54
54
  - Explicit link-only update: add frontmatter links to the target when source and
55
55
  target resolve uniquely and the relation is clear.
56
56
  - Already-closed entry with substantive correction: create a follow-up `status`
57
- entry, or use `decision` when a decision is accepted or superseded.
57
+ entry, or use `journal-decision` when a decision is accepted or superseded.
58
58
  - Closed body edits: avoid them. Do only narrow, explicit edits requested by the
59
59
  user, and never rewrite wholesale.
60
60
 
@@ -79,7 +79,7 @@ For link-only edits:
79
79
  3. Update `updatedAt`.
80
80
  4. Leave the body unchanged except for an optional concise pointer when useful.
81
81
 
82
- For follow-up entries, use `journal` or `decision` and link both the prior entry
82
+ For follow-up entries, use `journal-entry` or `journal-decision` and link both the prior entry
83
83
  and recalled evidence.
84
84
 
85
85
  After every write, re-read changed files and link targets. Verify IDs, paths,
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: research-codebase
2
+ name: journal-research-codebase
3
3
  description: Research and document how a topic currently works in the codebase, producing a canonical supporting entry. Use for implementation maps, integration analysis, type discovery, usage patterns, tests, and dependencies before planning or changing code.
4
4
  ---
5
5
 
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: research-web
2
+ name: journal-research-web
3
3
  description: Research a current external topic on the internet and write a sourced canonical supporting entry. Use for official documentation, standards, libraries, best practices, examples, or other temporally unstable external knowledge relevant to active work.
4
4
  ---
5
5
 
@@ -1,12 +1,17 @@
1
1
  ---
2
- name: resume
3
- description: Bootstrap concise context from the active filesystem journal work item. Use at session start or after switching work to load current state, pending next steps, relevant linked evidence, and signs of unjournaled work.
2
+ name: journal-resume
3
+ description: Restore djournal work-item context from canonical Markdown when continuing a project, asking where we left off or what is next, switching work, or recovering after compaction. Read-only project continuity; distinct from reopening a chat session or loading native agent memory.
4
4
  ---
5
5
 
6
6
  # Resume active work
7
7
 
8
8
  Operate read-only.
9
9
 
10
+ Read the selected work item's canonical state and latest entry before reporting
11
+ continuity. A resumed conversation or native memory summary can provide hints,
12
+ but does not establish the journal's current state. Reuse canonical context
13
+ already loaded for this task when it is still current.
14
+
10
15
  ## Load
11
16
 
12
17
  1. Read completely:
@@ -23,7 +28,7 @@ Operate read-only.
23
28
  is available, ask the user to choose one before doing meaningful writes.
24
29
  After the user chooses, bind the session with
25
30
  `djournal work bind <slug> --session <id>` when a session id is available,
26
- or use `switch` only when the user wants to change the global fallback.
31
+ or use `journal-switch` only when the user wants to change the global fallback.
27
32
  3. If `work.md` is legacy/missing, infer a temporary title/slug and clearly mark
28
33
  metadata as incomplete. Do not repair it.
29
34
  4. Index entry frontmatter under `journal/`, `_research/`, `docs/`, and
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Journal Resume"
3
+ short_description: "Restore current project state from djournal"
4
+ default_prompt: "Use $journal-resume to restore the active work context and identify the next steps."
@@ -1,5 +1,5 @@
1
1
  ---
2
- name: switch
2
+ name: journal-switch
3
3
  description: Change the active filesystem journal work item without changing Git state. Use when moving journal context to another existing project or work stream.
4
4
  ---
5
5
 
@@ -28,10 +28,10 @@ not Git branches. For parallel sessions, prefer binding the session with
28
28
  using the exact shape in `STATE.md`.
29
29
  9. Re-read state and verify the target folder and `work.md` slug.
30
30
  10. Present the selected work's latest spine summary and next steps using the
31
- `resume` retrieval procedure.
31
+ `journal-resume` retrieval procedure.
32
32
 
33
33
  ## Constraints
34
34
 
35
35
  - Do not modify work-item status, visibility, IDs, or timestamps.
36
- - Do not create a missing work item; use `init-work` instead.
36
+ - Do not create a missing work item; use `journal-init-work` instead.
37
37
  - Never infer an ambiguous write target from recency.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: journal-workflow
3
- description: Coordinate the default-on filesystem journal workflow by classifying a request and composing existing resume, plan, research, decision, document, and journal skills. Use for meaningful implementation, durable research or documentation, accepted decisions, migrations, or material status changes that should preserve project context without requiring the user to invoke journal steps manually.
3
+ description: Coordinate djournal project memory for meaningful implementation, investigation, decisions, and status changes. Select and load the required journal-* skills for context, evidence, planning, and closure even when the user does not mention journaling.
4
4
  ---
5
5
 
6
6
  # Coordinate the journal workflow
@@ -14,10 +14,29 @@ the underlying journal skills.
14
14
  2. Read `.agents/rules/STATE.md` before any write.
15
15
  3. Load other journal rules only through the selected underlying skill.
16
16
 
17
+ ## Select and load skills
18
+
19
+ Follow the intent routes and invocation contract in `AUTOMATION.md`. Invoke the
20
+ exact `journal-*` skill through the harness skill tool when available; otherwise
21
+ read `.agents/skills/<skill-name>/SKILL.md`. Do this before the selected work,
22
+ not merely by mentioning the skill or doing a CLI search.
23
+
24
+ - Continue or recover active work: `journal-resume` when journal context is
25
+ needed and is not already loaded.
26
+ - Answer from past project decisions or history: `journal-recall` and its
27
+ canonical evidence, even when native memory suggests an answer.
28
+ - Plan a multi-phase or risky change: `journal-plan` before implementation,
29
+ unless an applicable accepted plan already exists.
30
+
31
+ Native conversation resume, auto memory, and plan mode remain useful but do not
32
+ complete these journal steps. Preserve read-only restrictions and the existing
33
+ opt-out, trivial-work, and plan-threshold rules. No repeated invocation is needed
34
+ for unchanged skill instructions already loaded in this context.
35
+
17
36
  ## Classify
18
37
 
19
38
  - Honor `journal: off` and finish with `<!-- journal-status: off -->`.
20
- - For read-only work, use `recall` or `resume` only when history matters. Do not
39
+ - For read-only work, use `journal-recall` or `journal-resume` only when history matters. Do not
21
40
  write an entry; finish with `<!-- journal-status: not-needed -->` unless
22
41
  recalled evidence materially affects current or closed work as described
23
42
  below.
@@ -27,16 +46,16 @@ the underlying journal skills.
27
46
 
28
47
  ## Recall reinforcement
29
48
 
30
- Keep `recall` itself read-only. After a recall/resume answer, decide whether the
49
+ Keep `journal-recall` itself read-only. After a recall/resume answer, decide whether the
31
50
  retrieved evidence materially affects current journal work before finalizing:
32
51
 
33
52
  - Immaterial recall: answer from sources and finish `not-needed`.
34
- - Current closure in progress: pass the recalled source entries to `journal` so
53
+ - Current closure in progress: pass the recalled source entries to `journal-entry` so
35
54
  the new spine entry links them with `references`, `relates_to`, or
36
55
  `supersedes` as appropriate.
37
- - Explicit current/closed target: use `reinforce` to add conservative links or a
56
+ - Explicit current/closed target: use `journal-reinforce` to add conservative links or a
38
57
  follow-up spine entry.
39
- - Accepted contradiction or replacement: use `decision` or `journal` to record
58
+ - Accepted contradiction or replacement: use `journal-decision` or `journal-entry` to record
40
59
  the correction and link the recalled evidence.
41
60
 
42
61
  Material evidence includes recalled sources that confirm a claim being recorded,
@@ -64,15 +83,15 @@ Pass materially used entries to the closing journal skill for typed citations.
64
83
 
65
84
  ## Run checkpoints
66
85
 
67
- 1. **Start:** use `resume` when active-work history can affect the task. Use
68
- `init-work` only for an unambiguous new durable work stream.
69
- 2. **Plan:** use `plan` for multi-phase, risky, cross-component, or
86
+ 1. **Start:** use `journal-resume` when active-work history can affect the task. Use
87
+ `journal-init-work` only for an unambiguous new durable work stream.
88
+ 2. **Plan:** use `journal-plan` for multi-phase, risky, cross-component, or
70
89
  decision-heavy implementation. Do not plan again when an accepted plan exists.
71
- 3. **Support:** route durable evidence to `research-codebase`, `research-web`,
72
- `decision`, `document`, or `reinforce` as appropriate.
90
+ 3. **Support:** route durable evidence to `journal-research-codebase`, `journal-research-web`,
91
+ `journal-decision`, `journal-document`, or `journal-reinforce` as appropriate.
73
92
  4. **Implement and validate:** make the requested changes and gather bounded,
74
93
  deterministic evidence.
75
- 5. **Close:** check the latest spine entry for duplication, then use `journal`
94
+ 5. **Close:** check the latest spine entry for duplication, then use `journal-entry`
76
95
  once when meaningful state changed.
77
96
 
78
97
  ## Finish
package/AGENTS.md CHANGED
@@ -9,12 +9,21 @@ For every request:
9
9
 
10
10
  1. Honor an explicit `journal: off` instruction for that request.
11
11
  2. Classify the work using `.agents/rules/AUTOMATION.md`.
12
- 3. Use `.agents/skills/journal-workflow/SKILL.md` for meaningful mutations,
13
- durable research, decisions, documentation, or material status changes.
12
+ 3. Load `journal-workflow` for meaningful mutations, durable research,
13
+ decisions, documentation, or material status changes. Invoke the exact skill
14
+ name through the harness skill tool when available; otherwise read
15
+ `.agents/skills/journal-workflow/SKILL.md` and follow it.
14
16
  4. Do not force a plan or journal entry for read-only or trivial work.
15
17
  5. Before the final response, close meaningful changed state through the
16
18
  existing journal skills. Hooks never write entries.
17
19
 
20
+ Journal skills use the `journal-*` namespace. Route project continuity to
21
+ `journal-resume`, past decisions/history to `journal-recall`, and work meeting
22
+ the planning threshold to `journal-plan`. Load the selected skill before its
23
+ work; native conversation resume, auto memory, and plan mode do not perform
24
+ these journal procedures. Use native tools alongside the journal as useful.
25
+ After compaction or a work switch, reload journal context only as needed.
26
+
18
27
  End every final response with exactly one hidden status marker:
19
28
 
20
29
  - `<!-- journal-status: closed .journal/work/<slug>/journal/<entry>.md -->`
package/README.md CHANGED
@@ -275,7 +275,7 @@ djournal recall search "billing webhook retries" --type decision,research --limi
275
275
  ```
276
276
 
277
277
  Or install a harness and ask its agent naturally: “Recall why we chose the
278
- current billing webhook retry strategy.” The bundled `recall` skill calls the
278
+ current billing webhook retry strategy.” The bundled `journal-recall` skill calls the
279
279
  same CLI, selects the best journal paths, reads the canonical Markdown, follows
280
280
  relevant links, and returns an evidence-backed answer.
281
281
 
@@ -284,6 +284,10 @@ items and entry paths before reading canonical Markdown. Warm queries reuse the
284
284
  snapshot; additions, edits, deletes, and work-metadata changes refresh it on the
285
285
  next search. Use `--no-cache` for a one-call in-memory index. Cache corruption or
286
286
  write denial is recoverable and never triggers a share, sync, commit, or push.
287
+ All bundled skills use the `journal-*` namespace, including `journal-resume`,
288
+ `journal-plan`, and `journal-entry`. See [skill names and invocation](docs/installation.md#journal-skill-names-and-invocation)
289
+ for the rename mapping and upgrade behavior.
290
+
287
291
  See [Fast recall](docs/recall.md) for standalone CLI examples, agent behavior,
288
292
  filters, and cache lifecycle details.
289
293
 
@@ -283,6 +283,54 @@ Claude integration removes its unchanged installed skills while retaining
283
283
  `.agents/skills/`. Existing or locally modified skill files are preserved;
284
284
  different content at an installation destination produces an `ASSET_CONFLICT`.
285
285
 
286
+ ### Journal skill names and invocation
287
+
288
+ All bundled skills use `journal-*` names. Their folder and frontmatter names
289
+ match across `.agents/skills/`, Claude's project copies, and Grok registration.
290
+
291
+ | Previous skill | Current skill |
292
+ | --- | --- |
293
+ | `resume` | `journal-resume` |
294
+ | `recall` | `journal-recall` |
295
+ | `plan` | `journal-plan` |
296
+ | `journal` | `journal-entry` |
297
+ | `init-work` | `journal-init-work` |
298
+ | `switch` | `journal-switch` |
299
+ | `decision` | `journal-decision` |
300
+ | `document` | `journal-document` |
301
+ | `research-codebase` | `journal-research-codebase` |
302
+ | `research-web` | `journal-research-web` |
303
+ | `reinforce` | `journal-reinforce` |
304
+ | `audit` | `journal-audit` |
305
+ | `reconcile` | `journal-reconcile` |
306
+ | `journal-workflow` | `journal-workflow` (unchanged) |
307
+
308
+ In Claude, invoke `/journal-resume`, `/journal-recall`, or `/journal-plan`
309
+ directly. In Codex, use `$journal-resume`, `$journal-recall`, or `$journal-plan`.
310
+ Natural requests such as “where did we leave off?” or “why did we choose this?”
311
+ should route through the corresponding skill when project memory is needed.
312
+ If a skill is missing from the catalog, the workflow reads its canonical
313
+ `.agents/skills/<skill-name>/SKILL.md` file. If that file is also missing,
314
+ upgrade or repair the installation; do not assume the journal was consulted.
315
+
316
+ Run `djournal upgrade` after updating the CLI to migrate managed copies.
317
+ Unchanged installer-created old skill files are removed. Modified managed
318
+ files produce a conflict and remain intact; pre-existing unowned copies are
319
+ preserved. No generic aliases are installed. Manually installed personal skills
320
+ are outside this migration: review those separately if old names remain visible.
321
+ Restart the agent after upgrading, and re-register Grok workflows as needed.
322
+ CLI commands such as `djournal recall` and entry types such as `plan` keep
323
+ their names.
324
+
325
+ Claude's native `/resume` and `/plan` commands and auto memory serve different
326
+ purposes from journal context retrieval and durable planning. The namespace and
327
+ explicit routing help distinguish them; native tools remain available. Automatic
328
+ selection still depends on the model, available skills, permissions, and context
329
+ budget. These instructions do not guarantee a skill call. If selection is skipped,
330
+ invoke the journal skill directly and confirm it cites or writes the expected
331
+ canonical journal entry. See [Claude's skill selection and troubleshooting](https://code.claude.com/docs/en/skills)
332
+ and [native commands](https://code.claude.com/docs/en/commands).
333
+
286
334
  ### Missing instruction blocks
287
335
 
288
336
  Reinstall and upgrade restore a completely missing djournal block in `AGENTS.md`
@@ -15,8 +15,8 @@ read-only setup is achieved by combining three controls:
15
15
  push to it.
16
16
  - djournal sync config that enables `pull` but does not enable automatic
17
17
  publication.
18
- - Agent prompts that ask for read-only skills such as `recall`, `research`, and
19
- `document`, not implementation or journal closure.
18
+ - Agent prompts that ask for read-only skills such as `journal-recall` and
19
+ `journal-resume`, not implementation or journal closure.
20
20
 
21
21
  This still writes local files under the user's djournal home. "Read-only" means
22
22
  read-only with respect to the organization remote, not a filesystem mode that
package/docs/recall.md CHANGED
@@ -2,7 +2,12 @@
2
2
 
3
3
  Recall finds the journal files most likely to answer a question before anyone
4
4
  spends time opening and summarizing them. It can be used directly as a small
5
- search CLI, or indirectly through an agent that has djournal's `recall` skill.
5
+ search CLI, or indirectly through an agent that has djournal's `journal-recall` skill.
6
+
7
+ For an explicit skill invocation, use `/journal-recall` in Claude or
8
+ `$journal-recall` in Codex. Ask `journal-resume` for the selected work item's
9
+ current state and next steps. Native agent memory may help locate information,
10
+ but journal answers cite the canonical Markdown sources.
6
11
  Both paths use the same local index and keep Markdown as the source of truth.
7
12
 
8
13
  ## Use it as a standalone CLI
@@ -65,7 +70,7 @@ Then ask naturally:
65
70
  Recall why we chose the current billing webhook retry strategy.
66
71
  ```
67
72
 
68
- The `recall` skill classifies the question, calls the same CLI with `--json`,
73
+ The `journal-recall` skill classifies the question, calls the same CLI with `--json`,
69
74
  uses the ranked paths to select a small evidence set, and reads those canonical
70
75
  Markdown files before answering. It follows relevant entry links and starts
71
76
  from the latest spine entry when the question needs chronology or current
@@ -146,7 +146,7 @@ response that closes `.journal/work/<slug>/journal/...` synchronizes that
146
146
  `<slug>` even if `state.json` currently selects a different active work item.
147
147
 
148
148
  Configured standalone automatic sync also pulls when a new chat/session starts.
149
- The `init-work` and `switch` workflows pull before enumerating work, and an
149
+ The `journal-init-work` and `journal-switch` workflows pull before enumerating work, and an
150
150
  explicit request such as “sync the journal” triggers a pull before the agent
151
151
  handles publication. Automatic hook failures are reported as bounded context;
152
152
  explicit pull/sync conflicts exit nonzero for manual resolution.
@@ -4,28 +4,28 @@ Grok Bot loads shared workflows. It does not load `.agents/skills` by itself
4
4
  and it has no session hooks. After `djournal install --harness grok-bot`,
5
5
  register each installed skill with the harness **UpdateSkill** action.
6
6
 
7
- Keep the upstream skill files generic. Rewrite a copy for the payload. Do not
7
+ Keep the upstream skill files portable. Rewrite a copy for the payload. Do not
8
8
  edit the installed `SKILL.md` files in place, and do not embed a workspace
9
9
  path, owner name, or agent id.
10
10
 
11
- ## Suggested workflow ids
11
+ ## Workflow ids
12
12
 
13
- | Installed skill directory | Suggested workflow id |
13
+ | Installed skill directory | Workflow id |
14
14
  | --- | --- |
15
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` |
16
+ | `journal-resume` | `journal-resume` |
17
+ | `journal-init-work` | `journal-init-work` |
18
+ | `journal-switch` | `journal-switch` |
19
+ | `journal-entry` | `journal-entry` |
20
+ | `journal-plan` | `journal-plan` |
21
+ | `journal-recall` | `journal-recall` |
22
+ | `journal-decision` | `journal-decision` |
23
+ | `journal-document` | `journal-document` |
24
+ | `journal-research-codebase` | `journal-research-codebase` |
25
+ | `journal-research-web` | `journal-research-web` |
26
+ | `journal-reinforce` | `journal-reinforce` |
27
+ | `journal-audit` | `journal-audit` |
28
+ | `journal-reconcile` | `journal-reconcile` |
29
29
 
30
30
  Hub-only prose in this recipe is not an upstream skill:
31
31
 
@@ -39,7 +39,7 @@ Hub-only prose in this recipe is not an upstream skill:
39
39
  1. Set `<project-root>` to the install target (the directory that contains
40
40
  `.djournal.json` and `.agents/`).
41
41
  2. Read `<project-root>/.agents/skills/<directory>/SKILL.md`.
42
- 3. Take `name` and `description` from the YAML frontmatter. Use the suggested
42
+ 3. Take `name` and `description` from the YAML frontmatter. Use the same namespaced
43
43
  workflow id from the table. Do not invent a project-specific id.
44
44
  4. Rewrite the body into the UpdateSkill payload:
45
45
  - Point rule reads at `<project-root>/.agents/rules/...`. Journal root
@@ -601,7 +601,7 @@ function readActiveWork(context, requested) {
601
601
  slug = state.active_work_name;
602
602
  }
603
603
  if (typeof slug !== "string" || !slug) {
604
- throw new InstallerError("No active work found. Run init-work or switch first.", "NO_ACTIVE_WORK");
604
+ throw new InstallerError("No active work found. Run journal-init-work or journal-switch first.", "NO_ACTIVE_WORK");
605
605
  }
606
606
  if (slug.includes("/") || slug.includes("\\") || slug === "." || slug === "..") {
607
607
  throw new InstallerError(`invalid work slug: ${slug}`, "INVALID_WORK");
package/lib/setup.js CHANGED
@@ -209,7 +209,7 @@ async function setup(options, dependencies = {}) {
209
209
  try { result = await api.listWork(base); }
210
210
  catch (error) {
211
211
  if (error.code !== "NO_ACTIVE_WORK") throw error;
212
- ui.write("No work items yet. Ask your coding agent to start a new work item with init-work.");
212
+ ui.write("No work items yet. Ask your coding agent to start a new work item with journal-init-work.");
213
213
  return;
214
214
  }
215
215
  const selected = await menu("Choose a work item", [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "djournal",
3
- "version": "0.12.1",
3
+ "version": "0.13.0",
4
4
  "description": "Durable project memory for coding agents, stored as linked Markdown",
5
5
  "type": "commonjs",
6
6
  "bin": {
package/spec.md CHANGED
@@ -42,18 +42,20 @@ project/
42
42
  │ │ ├── SAFETY.md
43
43
  │ │ └── STATE.md
44
44
  │ └── skills/
45
- │ ├── audit/
46
- │ ├── decision/
47
- │ ├── document/
48
- │ ├── init-work/
49
- │ ├── journal/
50
- │ ├── plan/
51
- │ ├── recall/
52
- │ ├── reconcile/
53
- │ ├── research-codebase/
54
- │ ├── research-web/
55
- │ ├── resume/
56
- │ └── switch/
45
+ │ ├── journal-audit/
46
+ │ ├── journal-decision/
47
+ │ ├── journal-document/
48
+ │ ├── journal-init-work/
49
+ │ ├── journal-entry/
50
+ │ ├── journal-workflow/
51
+ │ ├── journal-reinforce/
52
+ │ ├── journal-plan/
53
+ │ ├── journal-recall/
54
+ │ ├── journal-reconcile/
55
+ │ ├── journal-research-codebase/
56
+ │ ├── journal-research-web/
57
+ │ ├── journal-resume/
58
+ │ └── journal-switch/
57
59
  └── .journal/
58
60
  ├── state.json
59
61
  └── work/
@@ -209,15 +211,15 @@ original wall-clock creation time.
209
211
  Typical flow:
210
212
 
211
213
  ```text
212
- init-work or switch
213
- → resume
214
- → research-codebase / research-web
215
- → plan
214
+ journal-init-work or journal-switch
215
+ → journal-resume
216
+ → journal-research-codebase / journal-research-web
217
+ → journal-plan
216
218
  → implementation
217
- → decision / document when needed
218
- → journal
219
- → audit or reconcile periodically
220
- → recall for historical questions
219
+ → journal-decision / journal-document when needed
220
+ → journal-entry
221
+ → journal-audit or journal-reconcile periodically
222
+ → journal-recall for historical questions
221
223
  ```
222
224
 
223
225
  Producer skills emit exact metadata and follow the shared safety/link contracts.
@@ -225,12 +227,12 @@ Retrieval skills index frontmatter first, then deep-read only selected bodies.
225
227
 
226
228
  ## 12. Resume and recall
227
229
 
228
- `resume` loads work metadata, latest spine state/timeline/next steps, five recent
230
+ `journal-resume` loads work metadata, latest spine state/timeline/next steps, five recent
229
231
  spine entries as fallback, and at most three relevant linked supporting entries.
230
232
  It reports possible unjournaled Git changes and unmatched plans without claiming
231
233
  formal session recovery.
232
234
 
233
- `recall` ranks work items from `work.md`, filters entries by metadata, and follows
235
+ `journal-recall` ranks work items from `work.md`, filters entries by metadata, and follows
234
236
  typed links lazily. Deep reads are bounded to eight spine and three supporting
235
237
  entries; technical verification is bounded to five code files.
236
238
 
@@ -239,7 +241,7 @@ filename, and heading.
239
241
 
240
242
  ## 13. Audit and reconciliation
241
243
 
242
- `audit` is strictly read-only and walks every entry in scope. It checks the
244
+ `journal-audit` is strictly read-only and walks every entry in scope. It checks the
243
245
  filesystem contract plus the reconciliation checklist:
244
246
 
245
247
  1. misclassified type
@@ -250,7 +252,7 @@ filesystem contract plus the reconciliation checklist:
250
252
  6. wrong work status
251
253
  7. forked/duplicate entry numbers, flag only
252
254
 
253
- `reconcile` runs audit first, reports proposed changes, then applies only clear
255
+ `journal-reconcile` runs audit first, reports proposed changes, then applies only clear
254
256
  fixes. It may enrich legacy metadata, repair deterministic links, improve factual
255
257
  summaries, extract explicit decisions, and correct unequivocal status.
256
258
 
@@ -1,4 +0,0 @@
1
- interface:
2
- display_name: "Audit Journal"
3
- short_description: "Report journal integrity issues without changes"
4
- default_prompt: "Use $audit to inspect the active journal work item and report integrity issues."
@@ -1,4 +0,0 @@
1
- interface:
2
- display_name: "Decision"
3
- short_description: "Record and link a durable technical decision"
4
- default_prompt: "Use $decision to record this decision and link its supporting context."
@@ -1,4 +0,0 @@
1
- interface:
2
- display_name: "Reconcile Journal"
3
- short_description: "Repair clear journal integrity issues safely"
4
- default_prompt: "Use $reconcile to report and safely repair clear journal integrity issues."