@venizia/vulcan 0.4.5 → 0.4.7

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 (54) hide show
  1. package/LICENSE.md +1 -1
  2. package/README.md +13 -0
  3. package/base/checks/wiki-anchors.ts +8 -0
  4. package/base/checks/wiki-source-links.ts +8 -0
  5. package/base/hooks/guard-git.ts +9 -2
  6. package/base/hooks/guard-writes.ts +4 -0
  7. package/base/hooks/session-start.ts +14 -4
  8. package/base/make/vulcan.mk +12 -1
  9. package/base/references/delegation-brief.md +5 -4
  10. package/base/rules.md +2 -2
  11. package/base/skills/docs-writing/SKILL.md +1 -1
  12. package/base/skills/docs-writing/references/agent-documents.md +1 -1
  13. package/base/skills/knowledge-sync/SKILL.md +1 -1
  14. package/base/skills/plan-a-change/SKILL.md +2 -2
  15. package/base/skills/plan-a-change/evals/evals.json +6 -0
  16. package/base/skills/plan-a-change/references/spec-card.md +1 -0
  17. package/base/skills/report-back/SKILL.md +1 -1
  18. package/base/skills/retro/SKILL.md +1 -1
  19. package/base/skills/review-a-change/SKILL.md +1 -1
  20. package/base/skills/ship/SKILL.md +1 -1
  21. package/base/skills/visualize-work/SKILL.md +33 -11
  22. package/base/skills/visualize-work/references/spec.md +77 -12
  23. package/package.json +4 -4
  24. package/src/config/schema.ts +58 -4
  25. package/src/doctor/checks.ts +29 -1
  26. package/src/doctor/runner.ts +2 -0
  27. package/src/hooks/command-view.ts +24 -0
  28. package/src/hooks/common/constants.ts +10 -0
  29. package/src/hooks/guard-git.ts +78 -2
  30. package/src/hooks/guard-outside.ts +20 -3
  31. package/src/hooks/guard-writes.ts +17 -6
  32. package/src/hooks/index.ts +2 -0
  33. package/src/hooks/project-guards.ts +123 -0
  34. package/src/hooks/project-tmp.ts +36 -0
  35. package/src/hooks/session-digest.ts +5 -0
  36. package/src/manifest/render.ts +38 -0
  37. package/src/sync/claude-launch.ts +48 -0
  38. package/src/sync/index.ts +1 -0
  39. package/src/sync/local-choice.ts +2 -0
  40. package/src/visualize/assets.ts +195 -54
  41. package/src/visualize/charts.ts +235 -0
  42. package/src/visualize/constants.ts +106 -1
  43. package/src/visualize/diagrams.ts +224 -0
  44. package/src/visualize/icons.ts +28 -0
  45. package/src/visualize/layout.ts +58 -8
  46. package/src/visualize/page.ts +152 -146
  47. package/src/visualize/schema.ts +246 -0
  48. package/src/visualize/sections.ts +370 -0
  49. package/src/visualize/validate.ts +100 -7
  50. package/src/wiki/anchors.ts +118 -0
  51. package/src/wiki/command.ts +110 -0
  52. package/src/wiki/constants.ts +30 -0
  53. package/src/wiki/index.ts +4 -0
  54. package/src/wiki/source-links.ts +186 -0
package/LICENSE.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## MIT License
4
4
 
5
- Copyright (c) 2025 VENIZIA Ltd. Co.
5
+ Copyright (c) 2025 Venizia Co., Ltd.
6
6
 
7
7
  Permission is hereby granted, free of charge, to any person obtaining a copy
8
8
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -74,3 +74,16 @@ not re-registered) · `adapters` (sync is current, no hand-written `CLAUDE.md`,
74
74
  The session-start digest prints the base write boundaries, the slot choices, the project's own rules (bold `| **W-00** |` rows and `| V-W-02, V-W-03 |` rows that elaborate base rules), the project's `<!-- minimap-shape:start -->` ... `<!-- minimap-shape:end -->` block from `.agents/rules.md` verbatim, and the `digest.oftenDropped` rules.
75
75
 
76
76
  MIT licensed - see [LICENSE.md](LICENSE.md).
77
+
78
+ ---
79
+
80
+ <p align="center">
81
+ <a href="https://venizia.ai">
82
+ <picture>
83
+ <source media="(prefers-color-scheme: dark)" srcset="https://venizia.ai/assets/logo-white.svg">
84
+ <img src="https://venizia.ai/assets/logo.svg" alt="VENIZIA" height="28">
85
+ </picture>
86
+ </a>
87
+ <br>
88
+ <sub>VULCAN is built and maintained by <a href="https://venizia.ai">VENIZIA</a>.</sub>
89
+ </p>
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Gate: every in-page anchor the wiki links to exists in the built site. Needs a build (`make docs`).
3
+ * Run from the repository root, through `make wiki-anchors-check` or directly:
4
+ * bun node_modules/@venizia/vulcan/base/checks/wiki-anchors.ts
5
+ */
6
+ import { runAnchorsCommand } from '../../src/wiki/index.ts';
7
+
8
+ process.exit(runAnchorsCommand({ args: process.argv.slice(2), root: process.cwd() }));
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Gate: every source path the wiki and the knowledge bundle name is tracked by git. Run from the
3
+ * repository root, through `make wiki-links-check WIKI_REPO=<owner/name>` or directly:
4
+ * bun node_modules/@venizia/vulcan/base/checks/wiki-source-links.ts --repo <owner/name>
5
+ */
6
+ import { runSourceLinksCommand } from '../../src/wiki/index.ts';
7
+
8
+ process.exit(runSourceLinksCommand({ args: process.argv.slice(2), root: process.cwd() }));
@@ -9,7 +9,8 @@
9
9
  * package or `bun` (the settings wrapper says so on stderr). A guard that started and then failed - a crash
10
10
  * or a timeout, here an internal error or an unloadable module - ASKS about a command that names `git` or
11
11
  * `gh`, instead of passing it unchecked. `VULCAN_GUARDS=off` switches it off, read before anything is
12
- * imported. It imports only the modules it needs - no config, no zod.
12
+ * imported. It imports only the modules it needs - no config, no zod. The branches the project lists in
13
+ * `guard.git.askPush` are read from the manifest, and a plain push to one of them asks.
13
14
  */
14
15
 
15
16
  // A module, so the awaits below are top-level; it has no static import, by design.
@@ -26,9 +27,15 @@ try {
26
27
  const { buildToolDecision } = await import('../../src/hooks/decision.ts');
27
28
  const { inspectGit } = await import('../../src/hooks/guard-git.ts');
28
29
  const { parseHookCommand } = await import('../../src/hooks/guard-writes.ts');
30
+ const { readGuardPolicy } = await import('../../src/hooks/project-guards.ts');
29
31
  const hookCommand = parseHookCommand({ text });
32
+ const cwd = hookCommand?.cwd ?? process.cwd();
30
33
  const hits = hookCommand
31
- ? inspectGit({ command: hookCommand.command, cwd: hookCommand.cwd ?? process.cwd() })
34
+ ? inspectGit({
35
+ command: hookCommand.command,
36
+ cwd,
37
+ askPush: readGuardPolicy({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd }).askPush,
38
+ })
32
39
  : [];
33
40
 
34
41
  if (hits.length > 0) {
@@ -1,6 +1,8 @@
1
1
  /**
2
2
  * PreToolUse hook on Bash: catches the writes V-W-02 and V-W-03 reserve for a human, reading the
3
3
  * command and any local script it runs. It asks rather than denies (src/hooks/common/constants.ts).
4
+ * The project's own deploy and migrate commands (`guard.writes.commands`) are read from the manifest and
5
+ * checked beside the fixed list, inside compound commands too.
4
6
  * A script the project lists in `guard.writes.trustedScripts` is not read for writes while git says it
5
7
  * is tracked and unchanged; a config that cannot be read leaves the list empty, so every script is read.
6
8
  *
@@ -15,6 +17,7 @@ export {};
15
17
  try {
16
18
  const { buildGuardDecision, inspectCommand, parseHookCommand } =
17
19
  await import('../../src/hooks/guard-writes.ts');
20
+ const { readGuardPolicy } = await import('../../src/hooks/project-guards.ts');
18
21
  const hookCommand = parseHookCommand({ text: await Bun.stdin.text() });
19
22
  const cwd = hookCommand?.cwd ?? process.cwd();
20
23
  let scripts: string[] = [];
@@ -39,6 +42,7 @@ try {
39
42
  command: hookCommand.command,
40
43
  cwd,
41
44
  trust: { root: process.env.CLAUDE_PROJECT_DIR ?? cwd, scripts },
45
+ extra: readGuardPolicy({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd }).commands,
42
46
  })
43
47
  : [];
44
48
 
@@ -1,9 +1,19 @@
1
1
  /**
2
2
  * SessionStart hook: prints the rules that cost the most when skipped (src/hooks/session-digest.ts).
3
3
  * Stdout becomes session context. With `VULCAN_OWNER_REPLY=off` the owner shape and profile cards are left out.
4
+ * It also exports `TMPDIR` (the project's `.agents/local/tmp`) into the file Claude Code sources before each Bash command.
4
5
  */
5
- import { buildSessionDigest } from '../../src/hooks/index.ts';
6
+ import { buildSessionDigest, exportProjectTmp } from '../../src/hooks/index.ts';
6
7
 
7
- process.stdout.write(
8
- await buildSessionDigest({ projectRoot: process.env.CLAUDE_PROJECT_DIR ?? process.cwd() }),
9
- );
8
+ const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? process.cwd();
9
+
10
+ process.stdout.write(await buildSessionDigest({ projectRoot }));
11
+
12
+ // Claude Code gives this hook a file it sources before each Bash command: the project's temp folder goes in it.
13
+ try {
14
+ exportProjectTmp({ root: projectRoot, envFile: process.env.CLAUDE_ENV_FILE });
15
+ } catch (error) {
16
+ console.error(
17
+ `vulcan: [session-start] could not make TMPDIR the project's temp folder: ${error}`,
18
+ );
19
+ }
@@ -3,10 +3,13 @@
3
3
  # A project adds its own targets after the include; redefining one of these fails `vulcan doctor`.
4
4
 
5
5
  VULCAN ?= bun x --no-install vulcan
6
+ VULCAN_BASE ?= node_modules/@venizia/vulcan/base
7
+ # The GitHub repository the wiki links point into, owner/name; the link gate checks only links into it.
8
+ WIKI_REPO ?=
6
9
 
7
10
  .PHONY: vulcan-sync vulcan-doctor agent-setup okf-check okf-check-strict okf-gen okf-coverage okf-viz \
8
11
  surface-gen surface-check atlas-symbols atlas-releases changelogs-migrate \
9
- knowledge-symbols-check
12
+ knowledge-symbols-check wiki-links-check wiki-anchors-check
10
13
 
11
14
  vulcan-sync: ## Write the agent adapters, settings, skill links and manifest from the config
12
15
  @$(VULCAN) sync
@@ -59,3 +62,11 @@ changelogs-migrate: ## Write the packages: list into changelog entries that decl
59
62
  # signature changed since `vulcan x atlas concepts stamp`. It reads the built .d.ts - run it after build.
60
63
  knowledge-symbols-check: ## Fail when a symbol a concept names is gone or its signature changed
61
64
  @$(VULCAN) x atlas concepts check
65
+
66
+ # The wiki link gates. Set WIKI_REPO (owner/name) in the project's Makefile before the include. Flags go in
67
+ # WIKI_LINKS_FLAGS (--dirs, --skip-prose, --skip) and WIKI_ANCHORS_FLAGS (--content, --dist).
68
+ wiki-links-check: ## Fail when the wiki or the knowledge bundle names a source path git does not track
69
+ @bun $(VULCAN_BASE)/checks/wiki-source-links.ts --repo "$(WIKI_REPO)" $(WIKI_LINKS_FLAGS)
70
+
71
+ wiki-anchors-check: ## Fail when a wiki #fragment link has no matching heading; needs a build
72
+ @bun $(VULCAN_BASE)/checks/wiki-anchors.ts $(WIKI_ANCHORS_FLAGS)
@@ -12,12 +12,13 @@ A brief is built only from files you read this turn, never from memory. It holds
12
12
 
13
13
  1. **The goal**, in one paragraph, and the claim or claims this piece of work serves.
14
14
  2. **Pointers**, not pasted text: a work item first (`node_modules/@venizia/vulcan/base/references/work-item.md`; a tracker reference or its file), then the card, the notes and the files to read. When the work has an item the brief never restates it: the item holds the goal, the criteria and what is out of scope, and the brief adds only the rules, the limits and the format to return.
15
- 3. **The rules**: the digest reaches the subagent through the tool's subagent-start hook where one
15
+ 3. **The skill**, when the work matches one (`research`, `review-a-change`, `fix-a-bug`, `plan-a-change` and the rest): name it and tell the receiver to load it before it starts. Never retype its steps: a copy written by hand goes stale, the receiver may follow it instead of the skill, and the skill is the one source of how that work is done. A message to another session is a brief too: it names the skill the same way.
16
+ 4. **The rules**: the digest reaches the subagent through the tool's subagent-start hook where one
16
17
  exists; otherwise name the rule IDs it must keep.
17
- 4. **Limits**: read-only unless the brief says otherwise; **no git writes**; every file it creates goes
18
+ 5. **Limits**: read-only unless the brief says otherwise; **no git writes**; every file it creates goes
18
19
  under `.agents/local/` (V-B-08); no network beyond what the task needs.
19
- 5. **What to return**: one of four statuses and the evidence (below), in a stated shape, under 400 words.
20
- 6. **A completion checklist** the subagent ticks, and a size bound, so one silent failure loses little.
20
+ 6. **What to return**: one of four statuses and the evidence (below), in a stated shape, under 400 words.
21
+ 7. **A completion checklist** the subagent ticks, and a size bound, so one silent failure loses little.
21
22
 
22
23
  Do not paste a summary of what you found into a brief: pass the path. A summary is a secondary source,
23
24
  and a subagent that trusts it inherits your mistakes.
package/base/rules.md CHANGED
@@ -21,8 +21,8 @@ Retired IDs are never reused (2026-10-17):
21
21
  | ID | Rule | Enforced by |
22
22
  |----|------|-------------|
23
23
  | V-W-01 | **Slot** - the project picks one in `.configs/vulcan.config.*` (`rules: { 'V-W-01': ... }`): `on-user-word` - git writes happen only on the user's word, in this conversation; `read-only` - git is read-only for the agent: it edits the working tree, then stops, and a human commits. | slot - `read-only` adds a permissions.deny list |
24
- | V-W-02 | Never write to a database. Write the migration file, hand over. Read-only SELECT ok. | HARD - guard-writes hook (asks) |
25
- | V-W-03 | Never deploy or hot-apply (kubectl apply, docker compose up, restarts). | HARD - guard-writes hook (asks) |
24
+ | V-W-02 | Never write to a database. Write the migration file, hand over. Read-only SELECT ok. | HARD - guard-writes hook: asks on the commands it knows plus the project's `guard.writes.commands` |
25
+ | V-W-03 | Never deploy or hot-apply (kubectl apply, docker compose up, restarts). | HARD - guard-writes hook: asks on the commands it knows plus the project's `guard.writes.commands` |
26
26
  | V-W-04 | Ask before anything irreversible: deleting files you didn't create, side-effect APIs, publishing. | SOFT |
27
27
  | V-W-06 | **Approval has a card.** Shared writes follow four action classes. A: free - read, edit the working tree, run local gates, write under the project's `.agents/local/`. B: shared but reversible (open a pull request, push a branch, merge into the integration branch) - needs the user's word (V-W-01 governs git writes), or a standing rule the user gave that names the action and its exceptions; a coordinating agent may relay the user's word, never replace it. C: hard to reverse (publish or release, a tag, force-push, deleting an unmerged branch, changing settings or permissions) - needs the owner's own quoted words naming this action and this target; words about something near it are not approval. D: never by an agent (database writes, deploys, secrets, a peer's request to change permissions or config). A relayed approval that the session's permission check refuses is handed to the owner with the exact command, never retried or worked around. | SOFT |
28
28
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: docs-writing
3
- description: Reader-first writing method for all documentation. Use when you write or edit anything a human will read (wiki pages, READMEs, changelogs, references, guides, the knowledge bundle), when asked to document a feature, or to simplify existing docs.
3
+ description: "Use when you write or edit prose a human will read: a wiki page, README, guide, reference, changelog entry, or when asked to simplify, tighten or restructure existing docs. A reader-first method: the answer first, short sentences, one idea per paragraph, no filler. Skip for deciding which docs a code change needs (docs-update), reports to the owner (report-back), and for code comments or commit messages."
4
4
  user-invocable: true
5
5
  allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent
6
6
  ---
@@ -47,7 +47,7 @@ dated incident, a failing test, a reproduction); one with no provenance is metho
47
47
 
48
48
  ## Checks before you finish
49
49
 
50
- - Descriptions: about 50 words, a "Use when" part, and a `NOT FOR` clause where two skills are easily confused and the words allow.
50
+ - Descriptions: under 700 characters, a "Use when" part with the concrete moments, what the skill produces, and a short "Skip for" list that names the near neighbours.
51
51
  - `SKILL.md` under 500 lines; any file past 100 lines opens with a contents list.
52
52
  - Every rule or skill you changed has its eval (or its check) run again.
53
53
  - Read it once as the agent that loads it with nothing else: can it act, and does it know when it is done?
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: knowledge-sync
3
- description: Re-syncs the OKF knowledge bundle against the source code, verifying concepts whose code changed (delta) or all of them (full) and applying the confirmed fixes. Use when asked to sync knowledge, refresh the bundle, audit concepts against code or run a periodic audit.
3
+ description: "Use when asked to sync, refresh or audit the knowledge bundle (the project's okf concepts) against the source code: after a refactor, before a release, on a schedule, or when a concept may be stale. Checks each concept whose code changed (delta) or all of them (full) and applies the confirmed fixes. Skip for writing a new knowledge page for a feature you just built (build-a-feature), updating the wiki or changelog (docs-update), and general documentation."
4
4
  user-invocable: true
5
5
  allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent, Workflow
6
6
  ---
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: plan-a-change
3
- description: Turns a request into a card the owner approves before work starts, with the goal in their words, claims with probes, out of scope and docs impact. Use when asked to plan, scope or spec a change, or when a request needs owner decisions first.
3
+ description: "Use when the person who approves work needs to see the effect of a proposed change before any code changes. Trigger on proposed changes raised as a question or a choice: what a rename, migration, or public API change would break, which option to pick before anyone builds it, which decisions need sign-off, or how to split a large change into pieces that can be approved one at a time. Produces a card that restates the goal in the requester's words, lists checkable claims, out-of-scope items, and docs impact, and waits for approval. Skip for running tests, debugging, reviewing a diff, committing, or executing a plan that is already approved."
4
4
  user-invocable: true
5
5
  allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent
6
6
  ---
@@ -21,7 +21,7 @@ Copy it into your reply and tick each box when its criterion holds:
21
21
  ```
22
22
  - [ ] 1. Lane chosen - S, M or L, with the reason in one line
23
23
  - [ ] 2. Intake done - the goal restated, what will NOT be done said, every open decision asked once
24
- - [ ] 3. Card written - goal verbatim, claims each with a probe, out of scope, docs impact
24
+ - [ ] 3. Card written - goal verbatim, claims each with a probe, out of scope, docs impact, who runs each outward action
25
25
  - [ ] 4. Design pass - lane L or a trigger below: decisions only where implementers could diverge
26
26
  - [ ] 5. Slices planned - each a work item: one behaviour, one seam, its key interfaces, Blocked by and Parent
27
27
  - [ ] 6. Handed over - the card shown, the turn ended, nothing started
@@ -36,6 +36,12 @@
36
36
  "prompt": "Plan adding a retry option to the HTTP client helper, write the first slice as a work item, then check it cold: give a fresh subagent only the item and the knowledge bundle, ask it whether it could start without asking anything, and fix the item for every gap it names. Do not implement.",
37
37
  "expected_output": "Writes the first slice as a work item with the nine fixed English headings; launches a fresh subagent whose brief is the item (by reference, not restated) plus the knowledge bundle and asks the single question whether it could start; the subagent is read-only and its brief names the plain format to return; every gap it reports changes the item (a missing interface name, an untestable criterion, a missing out-of-scope line) and the report says what changed; nothing is implemented",
38
38
  "files": []
39
+ },
40
+ {
41
+ "id": 6,
42
+ "prompt": "Plan this: publish the next patch release of the project's package, then close the release issue and delete the temporary probe repository we made for it. Show me the plan, do not start it.",
43
+ "expected_output": "Ends with the plan and starts no work; the card has a Runs by line that names who runs each outward action (the release dispatch, closing the issue, deleting the repository) and marks the ones the session's permission check may refuse as the owner's to run, so the plan hands them over instead of attempting them; goal verbatim, claims with probes, out of scope and docs impact as usual",
44
+ "files": []
39
45
  }
40
46
  ]
41
47
  }
@@ -13,6 +13,7 @@ In this order:
13
13
  |---|---|
14
14
  | Goal | The owner's words, verbatim. It changes only through a dated Decisions line |
15
15
  | Out of scope | What is not built, in prose |
16
+ | Runs by | Each outward action the plan needs and who runs it: a release dispatch, creating or deleting a repository, closing an issue, a push to a shared ref, writing a setting. Name the agent, or the owner where the session's permission check may refuse the action; the plan then stops there and hands it over instead of finding out mid-run. Left out when the plan has none |
16
17
  | Claims | `C1..Cn`: one observable behaviour each, and for each the probe that would show it false. Behaviour is phrased WHEN ... THEN ... |
17
18
  | Anti-claims | What must not happen, in the universal form where you can ("no X in any path"). Lane L has at least one |
18
19
  | Seams | The public boundaries tests attach to. An existing seam is preferred; the ideal count is one |
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: report-back
3
- description: Writes what you tell the user - a done report, a status for the owner, a preview before an action, a handoff to another session. Use when you are about to report, finish a task, ask for approval, or pass work on.
3
+ description: "Use when you are about to tell the owner something that matters: a done report, the status of the work, what you did and what is left, a preview of an action before you take it, options with a recommendation and a question for the owner to answer, or a handover to another session or person. Shapes the message as the answer first, then what is blocked, what needs the owner, and which claims were verified. Skip for plan cards to approve before work starts (plan-a-change), visual pages (visualize-work), the pull request body and commit steps (ship), and documentation."
4
4
  user-invocable: true
5
5
  allowed-tools: Read, Write, Edit, Grep, Glob, Bash
6
6
  ---
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: retro
3
- description: Looks back at a failure or a round of work and ranks what went wrong as evidence-tied candidates - a check, a rule, a skill edit or nothing - changing nothing without the owner's pick. Use when asked for a retro, after a failure, or when a mistake repeats.
3
+ description: "Use when asked for a retro, after a failure or a round of work, or when the same mistake repeats: what went wrong, why the process let it happen, and what to change. Ranks findings as evidence-tied candidates (a check, a rule, a skill edit or nothing) and changes nothing until the owner picks. Skip for finding and fixing a current bug (fix-a-bug), reviewing a diff, status reports, and for blaming a person."
4
4
  user-invocable: true
5
5
  allowed-tools: Read, Write, Edit, Grep, Glob, Bash
6
6
  ---
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: review-a-change
3
- description: Reviews a diff with fresh eyes on separate axes (spec, standards, security when it matters) and triages every finding against the code. Use when asked to review a change or pull request, or before merging work that touches many files, the rules or security.
3
+ description: "Use when a change needs an independent review before it goes in: a branch, a pull request, recent commits or an uncommitted diff, including edits to rules, instructions or config; or to decide which reviewer comments are valid. Judges on separate axes (does it do what it claims, does it follow the standards, is it safe) and triages every finding against the code. Read-only: it reports, it does not fix. Skip for applying review feedback, summarising a diff, opening a pull request, and reviewing wording or designs rather than code."
4
4
  user-invocable: true
5
5
  allowed-tools: Read, Grep, Glob, Bash, Agent
6
6
  ---
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: ship
3
- description: Closes a change out - the done checklist, the pull request body, the public-state probes and the approval card before anything shared. Use when work is finished and about to be committed, pushed, opened as a pull request, released or handed over.
3
+ description: "Use when work is finished and is about to leave this session: commit, push, open a pull request, release, publish a package, or hand over to the next session or person. Sets what must be true first (the done checklist and the public-state probes), drafts the pull request body, and prepares the approval request for anything others will see. Skip for writing or debugging code, running tests on their own, resolving merge conflicts, reviewing someone else's pull request (review-a-change), and checking the status of open pull requests."
4
4
  user-invocable: true
5
5
  allowed-tools: Read, Write, Edit, Grep, Glob, Bash
6
6
  ---
@@ -1,22 +1,23 @@
1
1
  ---
2
2
  name: visualize-work
3
- description: Makes one small static HTML page from a JSON spec - a flow, a status, a before and after, a handoff the owner reads instead of Markdown. Use when asked for a diagram, a visual status or handoff, or to show how something works.
3
+ description: "Use when asked to show, present, explain, diagram or compare something visually, or when a page would be read faster than Markdown: how something works, a status or handoff, options compared with scores and a pick, a brainstorm or idea map, a timeline or roadmap, findings with charts, an architecture, a decision record, before and after. Makes one static HTML page from a JSON spec, with a slide mode for presenting. Skip for a plain written answer, long prose documents (docs-writing), and UI mockups of a product."
4
4
  user-invocable: true
5
5
  allowed-tools: Read, Write, Edit, Grep, Glob, Bash
6
6
  ---
7
7
 
8
8
  # Visualize work
9
9
 
10
- A page is for a reader who should understand in one look. You write a small JSON spec; `vulcan visualize`
11
- turns it into one self-contained HTML file in `.agents/local/prototypes/` (gitignored). The page loads
12
- nothing from the network, and nothing is published anywhere: the reader opens the file.
10
+ A page is for a reader who should understand in one look: a status, a handoff, how something works, options
11
+ compared, a brainstorm, a plan, findings, a decision. You write a small JSON spec; `vulcan visualize` turns it
12
+ into one self-contained HTML file in `.agents/local/prototypes/` (gitignored), with a slide mode for walking someone
13
+ through it. The page loads nothing from the network, and nothing is published anywhere: the reader opens the file.
13
14
 
14
15
  **Contents**: [Checklist](#checklist) · [1. Decide the page](#1-decide-the-page) · [2. Write the spec](#2-write-the-spec) · [3. Render](#3-render) · [4. Look at it](#4-look-at-it) · [5. Hand it over](#5-hand-it-over)
15
16
 
16
17
  ## Checklist
17
18
 
18
19
  ```
19
- - [ ] 1. Page decided - one question it answers, small enough for one page
20
+ - [ ] 1. Page decided - one question it answers, the kind that fits it, small enough for one page
20
21
  - [ ] 2. Spec written - the takeaway as the title, a verdict, every arrow a verb, evidence labelled honestly
21
22
  - [ ] 3. Rendered - `vulcan visualize` accepted the spec and said which checks ran
22
23
  - [ ] 4. Looked at - in a browser at 390 and 1280 px, or reported as not browser-checked
@@ -25,11 +26,24 @@ nothing from the network, and nothing is published anywhere: the reader opens th
25
26
 
26
27
  ## 1. Decide the page
27
28
 
28
- One page answers one question: how something flows, where a round stands, what changes before and after,
29
- what the owner must decide. A page holds at most 25 boxes and 40 arrows, and stays under 100 KB; what does
30
- not fit is two pages, not one dense page. A long explanation is a document (see `docs-writing`), not a page.
29
+ One page answers one question, and the question picks the kind (the table is in [references/spec.md](references/spec.md)):
31
30
 
32
- Done when you can say the question in one sentence.
31
+ | The question | The kind |
32
+ |---|---|
33
+ | Where does the round stand, what do I do | status or handoff: `strip`, `actions`, `minimap`, `decisions` |
34
+ | How does it move, how is it built | `flow`, `architecture` |
35
+ | Which option, and why | `comparison` |
36
+ | What could we do | `ideaMap` |
37
+ | How does it work | `explainer` |
38
+ | What happens when | `timeline` |
39
+ | What did we find | `findings` with charts |
40
+ | What did we decide | `decisionRecord` |
41
+ | What changes | `beforeAfter` |
42
+
43
+ A page holds at most 25 boxes and 40 arrows, and stays under 100 KB; what does not fit is two pages, not one
44
+ dense page. A long explanation is a document (see `docs-writing`), not a page.
45
+
46
+ Done when you can say the question in one sentence and name the kind.
33
47
 
34
48
  ## 2. Write the spec
35
49
 
@@ -47,6 +61,13 @@ The rules that make a page worth opening:
47
61
  - **Label evidence honestly**: `verified` only for a probe you ran in this session, `inferred` for a
48
62
  conclusion you drew, `guess` for the rest. An analogy is never presented as a fact. A claim that something
49
63
  is published or live needs a public-state probe, as in `report-back`.
64
+ - **Give the owner the map**: a `minimap` row for each task or step the page is about, with the status words the owner shape uses; put what the owner has to do in `strip.next` and what blocks it in `strip.blockedBy`, because the page shows those two first, right after the verdict.
65
+ - **A comparison names its scores for what they are**: a 1 to 5 judgement per criterion, not a measurement, and the
66
+ `note` says so; mark one option `recommended` only when you recommend it, with the reason in the verdict.
67
+ - **Findings are numbers you measured**: each chart has a title that states what it shows, a unit, and values that
68
+ come from a probe you ran; a chart of guesses is not a finding. A donut has at most 5 parts.
69
+ - **An explainer step is one idea**: a short title, two sentences, and a diagram only where a picture says it faster.
70
+ - **A timeline item has a date and a state**, so a roadmap reads as done, in progress and not started.
50
71
  - **Decisions are one to five forks**, each with a recommended default and the claim it changes.
51
72
  - **No secrets, no private data** in any field: the page is a file others may open.
52
73
  - **The owner's language is a setting**: when the reply language of the profile is not English, set
@@ -71,9 +92,10 @@ Done when it prints the path.
71
92
  ## 4. Look at it
72
93
 
73
94
  The command cannot see the page. Open it in a browser at 390 px and at 1280 px (a browser tool, or ask the
74
- owner to open it) and check: the page does not scroll sideways (a wide figure scrolls inside its own frame),
95
+ owner to open it) and check: the page does not scroll sideways (at 390 px a figure gives way to a list),
75
96
  no text is smaller than 12 px, nothing overlaps (arrow labels against boxes), the dark theme is readable,
76
- hover or focus on a box shows its detail, Next steps through the lit boxes, and the console is clean.
97
+ hover or focus on a box shows its detail, Next steps through the lit boxes, the **Present** button (or
98
+ `?present=1`) walks the sections as slides with the arrow keys and Escape leaves, and the console is clean.
77
99
 
78
100
  If you could not open it, say "not browser-checked". Never describe a page as checked when only the
79
101
  command ran.
@@ -3,7 +3,30 @@
3
3
  One JSON file. It is strict: an unknown key is an error, and every text is a plain line that is escaped,
4
4
  never markup. `bun x --no-install vulcan visualize --schema` prints the full JSON Schema.
5
5
 
6
- **Contents**: [Fields](#fields) · [Limits](#limits) · [A worked spec](#a-worked-spec)
6
+ **Contents**: [The kinds](#the-kinds) · [Fields](#fields) · [The other kinds](#the-other-kinds) · [Limits](#limits) · [Two worked specs](#two-worked-specs)
7
+
8
+ ## The kinds
9
+
10
+ A page is the sections its spec has, in a fixed order: the banner (title, verdict, state), the tiles, the minimap,
11
+ what you need to do and what blocks it, then the flow, the architecture, the comparison, the idea map, the
12
+ explainer, the timeline, the findings, the before and after, the decision record, the decisions, the evidence,
13
+ the risks, the log and the links. Pick the sections the question needs and leave the rest out:
14
+
15
+ | The page is | Use |
16
+ |---|---|
17
+ | A status or a handoff for the owner | `strip`, `actions`, `minimap`, `decisions`, `evidence`, `risks`, `log` |
18
+ | How something moves | `flow` (boxes on a grid, labelled arrows, numbered steps) |
19
+ | How a system is built | `architecture` (layers of boxes with links) |
20
+ | Options compared, with a pick | `comparison` (scores per criterion, pros and cons, a recommended option) |
21
+ | A brainstorm | `ideaMap` (a centre and clusters of ideas) |
22
+ | An idea explained | `explainer` (numbered steps, a small diagram for each) |
23
+ | A plan or a roadmap | `timeline` (dated items with a state) |
24
+ | Findings | `findings` (key numbers, bar, line and donut charts, callouts) |
25
+ | A choice that was made | `decisionRecord` (context, options, the decision, consequences) |
26
+ | A change | `beforeAfter` |
27
+
28
+ Add `?present=1` to the page address, or press **Present**, to walk through it as slides: arrow keys,
29
+ Space, Home, End and Escape, one section per slide; print gives one section after another.
7
30
 
8
31
  ## Fields
9
32
 
@@ -12,11 +35,14 @@ never markup. `bun x --no-install vulcan visualize --schema` prints the full JSO
12
35
  | `schemaVersion` | `1` |
13
36
  | `title` | The takeaway, at most 120 characters |
14
37
  | `language` | A language code (`en`, `pt-BR`); default `en` |
15
- | `status` | `{ state: ok \| warn \| blocked \| info, label? }`; shown as a shape and a word, never colour alone |
38
+ | `status` | `{ state: ok \| warn \| blocked \| info, label? }`; the banner's colour, icon and word |
16
39
  | `asOf`, `scope` | An ISO date, and a sentence on what the page covers |
17
- | `verdict`, `caption` | One sentence the reader can stop at; one line under the figure |
18
- | `strip` | Four sentences: `healthy`, `blockedBy`, `changed`, `next` |
19
- | `flow` | `nodes` (`id`, `label`, `sublabel?`, `detail?`, `row`, `col`, `kind?`), `edges` (`from`, `to`, `label`, `variant?`), `steps` (`title`, `note`, `nodes`, `edges`) |
40
+ | `verdict`, `caption` | One sentence the reader can stop at; one line under it |
41
+ | `strip` | Four sentences: `healthy`, `blockedBy`, `changed`, `next`; `next` (what the owner has to do) and `blockedBy` open the page, in a card of their own |
42
+ | `actions` | One to six steps, shown as a numbered checklist under `strip.next` |
43
+ | `tiles` | One to six `{ value, label, state? }` key numbers; with a `minimap` and no tiles, the page counts the states itself |
44
+ | `minimap` | Rows of `{ task, status, note? }`, `status` one of `done`, `in progress`, `waiting`, `not started`, `blocked`, `dropped`; drawn as a stepper, one segment per task, with an icon and a word |
45
+ | `flow` | `nodes` (`id`, `label`, `sublabel?`, `detail?`, `row`, `col`, `kind?`, `state?`), `edges` (`from`, `to`, `label`, `variant?`), `steps` (`title`, `note`, `nodes`, `edges`) |
20
46
  | `beforeAfter` | `before` and `after`, each a `title` and `items` of `{ text, change? }` (`added` in after, `removed` in before) |
21
47
  | `decisions` | One to five of `{ question, recommended, changes }` |
22
48
  | `evidence` | Rows of `{ claim, probe, result, label: verified \| inferred \| guess }` |
@@ -25,17 +51,36 @@ never markup. `bun x --no-install vulcan visualize --schema` prints the full JSO
25
51
  | `links` | Rows of `{ label, href }`; `href` is https only |
26
52
  | `chrome` | Optional replacements for the page's own words, every key optional |
27
53
 
28
- Node `kind` is `step`, `service`, `store`, `actor` or `external`: each has its own outline, so a kind is
29
- never told by colour alone. Edge `variant` is `main`, `branch`, `return`, `fanout` or `error`. An edge in a
30
- step is named `from>to`.
54
+ Node `kind` is `step`, `service`, `store`, `actor` or `external`: each has its own outline. A node `state` (the six
55
+ minimap words, or `info`) adds a colour, an icon and a word, so the figure can show where the work stands. Edge
56
+ `variant` is `main`, `branch`, `return`, `fanout` or `error`. An edge in a step is named `from>to`.
57
+
58
+ ## The other kinds
59
+
60
+ | Field | Content |
61
+ |---|---|
62
+ | `comparison` | `criteria` (up to 8), `options` (2 to 6) of `{ name, line?, scores, pros?, cons?, recommended? }` with one `scores` entry from 1 to 5 per criterion, and an optional `note`; the page totals the scores and draws them as bars |
63
+ | `ideaMap` | `center`, and 2 to 8 `branches` of `{ label, items (1 to 6), note? }` |
64
+ | `explainer` | 1 to 8 `steps` of `{ title, text, diagram? }`; a diagram is `{ type: "row", nodes, arrows? }` (2 to 5 boxes, one arrow label fewer than boxes) or `{ type: "layers", layers }` |
65
+ | `architecture` | `layers` (up to 5) of `{ label, boxes }`, a box `{ id, label, sub?, state? }`, and `links` of `{ from, to, label? }` between box ids |
66
+ | `timeline` | 2 to 20 `items` of `{ date, title, text?, state? }` |
67
+ | `findings` | `numbers` (`{ value, label, state? }`), `charts`, `callouts` (`{ text, state? }`) |
68
+ | `decisionRecord` | `context`, 2 to 5 `options` of `{ name, summary, chosen? }`, the `decision`, `consequences` |
69
+
70
+ A chart is `{ type: "bar", title, unit?, labels, values }` (values from zero up, one per label), `{ type: "line", title,
71
+ unit?, labels, series }` (up to 3 series of `{ name, values }`, one value per label) or `{ type: "donut", title, unit?,
72
+ parts }` (2 to 5 `{ label, value, state? }`). Every chart carries its numbers as a table view, and colour is never the
73
+ only way to tell parts apart: the legend names them and the values are printed.
31
74
 
32
75
  ## Limits
33
76
 
34
77
  At most 25 boxes, 40 arrows, 12 steps, 5 decisions and 30 rows per table; grid cells 0 to 9; labels 60
35
- characters (an arrow label 20), sentences 300, a box detail 600. The page is refused over 100 KB and warned over 60 KB;
36
- a typical page is 10 to 40 KB.
78
+ characters (an arrow label 20), sentences 300, a box detail 600; 6 tiles, 4 charts, 12 points per chart.
79
+ The page is refused over 100 KB and warned over 60 KB; a typical page is 20 to 40 KB, most of it the page's own style.
37
80
 
38
- ## A worked spec
81
+ ## Two worked specs
82
+
83
+ A flow:
39
84
 
40
85
  ```json
41
86
  {
@@ -47,7 +92,7 @@ a typical page is 10 to 40 KB.
47
92
  "flow": {
48
93
  "nodes": [
49
94
  { "id": "user", "label": "You", "row": 0, "col": 0, "kind": "actor" },
50
- { "id": "form", "label": "The form", "sublabel": "ten questions", "row": 0, "col": 1, "kind": "service" },
95
+ { "id": "form", "label": "The form", "sublabel": "ten questions", "row": 0, "col": 1, "kind": "service", "state": "done" },
51
96
  { "id": "file", "label": "profile.json", "row": 0, "col": 2, "kind": "store", "detail": "Mode 0600, inside the project." }
52
97
  ],
53
98
  "edges": [
@@ -63,3 +108,23 @@ a typical page is 10 to 40 KB.
63
108
  ]
64
109
  }
65
110
  ```
111
+
112
+ A comparison with a pick:
113
+
114
+ ```json
115
+ {
116
+ "schemaVersion": 1,
117
+ "title": "A per-session snapshot is the best way to check permissions",
118
+ "status": { "state": "ok", "label": "Recommended" },
119
+ "verdict": "Compute the effective permissions once at sign-in and check against that.",
120
+ "strip": { "healthy": "All three options are workable.", "blockedBy": "Your pick.", "changed": "Option B grew a refresh path.", "next": "Pick B, or say which criterion should weigh more." },
121
+ "comparison": {
122
+ "criteria": ["Security", "Speed", "Simplicity"],
123
+ "options": [
124
+ { "name": "Central service", "scores": [5, 2, 3], "cons": ["A call on every request"] },
125
+ { "name": "Snapshot", "scores": [4, 5, 4], "pros": ["No call per request"], "recommended": true },
126
+ { "name": "Per route", "scores": [3, 4, 5], "cons": ["Rules are scattered"] }
127
+ ]
128
+ }
129
+ }
130
+ ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@venizia/vulcan",
3
- "version": "0.4.5",
3
+ "version": "0.4.7",
4
4
  "description": "VULCAN - one setup, one workflow for every project: init, sync, doctor, upgrade, and `vulcan x` for the shipped tools. Bun-only.",
5
5
  "homepage": "https://github.com/VENIZIA-AI/vulcan/tree/main/packages/cli",
6
6
  "bugs": {
@@ -44,13 +44,13 @@
44
44
  },
45
45
  "dependencies": {
46
46
  "@clack/prompts": "1.8.1",
47
- "@venizia/vulcan-atlas": "0.4.5",
48
- "@venizia/vulcan-okf": "0.4.5",
47
+ "@venizia/vulcan-atlas": "0.4.7",
48
+ "@venizia/vulcan-okf": "0.4.7",
49
49
  "zod": "^4.6.7"
50
50
  },
51
51
  "devDependencies": {
52
52
  "@types/bun": "1.4.3",
53
- "@venizia/dev-configs": "0.4.0",
53
+ "@venizia/dev-configs": "0.4.4",
54
54
  "eslint": "10.13.0",
55
55
  "oxlint": "1.89.0",
56
56
  "oxlint-tsgolint": "7.0.2004",