@venizia/vulcan 0.4.4 → 0.4.6

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 (88) hide show
  1. package/LICENSE.md +1 -1
  2. package/README.md +13 -0
  3. package/base/agents.json +22 -1
  4. package/base/checks/wiki-anchors.ts +8 -0
  5. package/base/checks/wiki-source-links.ts +8 -0
  6. package/base/claude/remote-hosts.json +1 -1
  7. package/base/claude/settings.json +12 -12
  8. package/base/extensions/vulcan-guards.ts +301 -0
  9. package/base/hooks/antigravity-guards.ts +68 -0
  10. package/base/hooks/codex-guards.ts +66 -0
  11. package/base/hooks/guard-git.ts +38 -9
  12. package/base/hooks/guard-outside.ts +29 -9
  13. package/base/hooks/guard-writes.ts +29 -1
  14. package/base/hooks/session-start.ts +14 -4
  15. package/base/make/vulcan.mk +12 -1
  16. package/base/references/delegation-brief.md +5 -4
  17. package/base/rules.md +2 -2
  18. package/base/skills/docs-writing/SKILL.md +1 -1
  19. package/base/skills/docs-writing/references/agent-documents.md +1 -1
  20. package/base/skills/knowledge-sync/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/SKILL.md +1 -1
  22. package/base/skills/report-back/SKILL.md +1 -1
  23. package/base/skills/retro/SKILL.md +1 -1
  24. package/base/skills/review-a-change/SKILL.md +1 -1
  25. package/base/skills/ship/SKILL.md +1 -1
  26. package/base/skills/visualize-work/SKILL.md +33 -11
  27. package/base/skills/visualize-work/references/spec.md +77 -12
  28. package/package.json +4 -4
  29. package/src/agents/codex-hooks.ts +133 -0
  30. package/src/agents/common/constants.ts +54 -0
  31. package/src/agents/common/schema.ts +10 -1
  32. package/src/agents/common/types.ts +3 -1
  33. package/src/agents/exclude.ts +4 -0
  34. package/src/agents/hooks-json.ts +111 -0
  35. package/src/agents/index.ts +2 -0
  36. package/src/agents/render.ts +5 -4
  37. package/src/agents/resolve.ts +24 -9
  38. package/src/config/common/constants.ts +12 -0
  39. package/src/config/common/types.ts +2 -1
  40. package/src/config/packages.ts +2 -1
  41. package/src/config/schema.ts +84 -5
  42. package/src/create/add-app.ts +2 -2
  43. package/src/create/add-lib.ts +21 -8
  44. package/src/create/common/constants.ts +12 -0
  45. package/src/create/common/types.ts +2 -1
  46. package/src/create/preset-diff.ts +4 -2
  47. package/src/create/workspace.ts +13 -9
  48. package/src/doctor/checks.ts +71 -1
  49. package/src/doctor/common/constants.ts +2 -0
  50. package/src/doctor/runner.ts +6 -0
  51. package/src/hooks/codex-patch.ts +47 -0
  52. package/src/hooks/command-view.ts +97 -0
  53. package/src/hooks/common/constants.ts +46 -0
  54. package/src/hooks/common/types.ts +9 -1
  55. package/src/hooks/decision.ts +50 -8
  56. package/src/hooks/guard-git.ts +64 -5
  57. package/src/hooks/guard-manifest.ts +22 -8
  58. package/src/hooks/guard-outside.ts +38 -6
  59. package/src/hooks/guard-package.ts +15 -12
  60. package/src/hooks/guard-writes.ts +72 -21
  61. package/src/hooks/index.ts +5 -0
  62. package/src/hooks/project-guards.ts +123 -0
  63. package/src/hooks/project-tmp.ts +36 -0
  64. package/src/hooks/remote-hosts.ts +38 -14
  65. package/src/hooks/session-digest.ts +5 -0
  66. package/src/hooks/shell.ts +665 -35
  67. package/src/hooks/trusted-scripts.ts +134 -0
  68. package/src/manifest/render.ts +38 -0
  69. package/src/sync/agent-files.ts +122 -4
  70. package/src/sync/agent-removal.ts +118 -4
  71. package/src/sync/claude-launch.ts +48 -0
  72. package/src/sync/index.ts +1 -0
  73. package/src/sync/local-choice.ts +2 -0
  74. package/src/visualize/assets.ts +195 -54
  75. package/src/visualize/charts.ts +235 -0
  76. package/src/visualize/constants.ts +122 -1
  77. package/src/visualize/diagrams.ts +224 -0
  78. package/src/visualize/icons.ts +28 -0
  79. package/src/visualize/layout.ts +58 -8
  80. package/src/visualize/page.ts +151 -145
  81. package/src/visualize/schema.ts +252 -2
  82. package/src/visualize/sections.ts +370 -0
  83. package/src/visualize/validate.ts +100 -7
  84. package/src/wiki/anchors.ts +118 -0
  85. package/src/wiki/command.ts +110 -0
  86. package/src/wiki/constants.ts +30 -0
  87. package/src/wiki/index.ts +4 -0
  88. package/src/wiki/source-links.ts +186 -0
@@ -0,0 +1,66 @@
1
+ /**
2
+ * Codex's PreToolUse hook command (`.codex/hooks.json`, written by `vulcan sync`): reads the event Codex
3
+ * sends (`tool_name`, `tool_input.command`, `cwd`), runs the same guard scripts Claude Code runs through the
4
+ * policy of `base/extensions/vulcan-guards.ts`, and prints Codex's deny. Codex cannot ask about a tool call
5
+ * (an `ask` marks the hook failed and the call continues), so an ask is printed as a deny that says a human
6
+ * must confirm. An `apply_patch` is read file by file: `*** Add File:` is a write, the other headers are
7
+ * edits. No output allows. Input it cannot read is allowed. `VULCAN_GUARDS=off` allows everything, read
8
+ * before anything is imported.
9
+ */
10
+
11
+ // A module, so the awaits below are top-level; it has no static import, by design.
12
+ export {};
13
+
14
+ if (process.env.VULCAN_GUARDS === 'off') {
15
+ process.exit(0);
16
+ }
17
+
18
+ const isRecord = (value: unknown): value is Record<string, unknown> =>
19
+ typeof value === 'object' && value !== null && !Array.isArray(value);
20
+
21
+ const textOf = (value: unknown): string | undefined =>
22
+ typeof value === 'string' && value !== '' ? value : undefined;
23
+
24
+ const parseJson = (opts: { text: string }): unknown => {
25
+ try {
26
+ return JSON.parse(opts.text);
27
+ } catch {
28
+ return undefined;
29
+ }
30
+ };
31
+
32
+ const parsed = parseJson({ text: await Bun.stdin.text() });
33
+ const toolInput = isRecord(parsed) ? parsed['tool_input'] : undefined;
34
+ const tool = isRecord(parsed) ? textOf(parsed['tool_name']) : undefined;
35
+ const command = isRecord(toolInput) ? textOf(toolInput['command']) : undefined;
36
+ const cwd = (isRecord(parsed) ? textOf(parsed['cwd']) : undefined) ?? process.cwd();
37
+
38
+ if (command !== undefined && (tool === 'Bash' || tool === 'apply_patch')) {
39
+ const { verdictOf } = await import('../extensions/vulcan-guards.ts');
40
+ const { patchedFilesOf } = await import('../../src/hooks/codex-patch.ts');
41
+ const verdicts =
42
+ tool === 'Bash'
43
+ ? [verdictOf({ toolName: 'bash', input: Object.fromEntries([['command', command]]), cwd })]
44
+ : patchedFilesOf({ patch: command, cwd }).map((file) =>
45
+ verdictOf({ toolName: file.tool, input: Object.fromEntries([['path', file.path]]), cwd }),
46
+ );
47
+ const refused = verdicts.find((verdict) => verdict.kind === 'deny');
48
+ const asked = verdicts.filter((verdict) => verdict.kind === 'ask');
49
+ const reason =
50
+ refused?.reason ??
51
+ (asked.length > 0
52
+ ? `${asked.map((verdict) => verdict.reason).join('\n\n')}\n(Codex cannot ask about a tool call: a human must confirm this)`
53
+ : undefined);
54
+
55
+ if (reason !== undefined) {
56
+ console.log(
57
+ JSON.stringify({
58
+ hookSpecificOutput: {
59
+ hookEventName: 'PreToolUse',
60
+ permissionDecision: 'deny',
61
+ permissionDecisionReason: reason,
62
+ },
63
+ }),
64
+ );
65
+ }
66
+ }
@@ -4,10 +4,13 @@
4
4
  * or main, `gh pr merge --delete-branch` on a pull request whose head is one of them (deny), and
5
5
  * `reset --hard`, other force-pushes and `branch -D` of an unmerged branch (ask).
6
6
  *
7
- * It fails OPEN: it guards against drift, it is not the last line of defence, and a guard that blocks
8
- * every command when it breaks costs more than it protects. Input it cannot read, a missing module or an
9
- * internal error pass the call with a note on stderr. `VULCAN_GUARDS=off` switches it off, read before
10
- * anything is imported. It imports only the modules it needs - no config, no zod.
7
+ * It guards against drift, it is not the last line of defence, and a guard that blocks every command when
8
+ * its install is broken costs more than it protects. So input it cannot read passes, and so does a missing
9
+ * package or `bun` (the settings wrapper says so on stderr). A guard that started and then failed - a crash
10
+ * or a timeout, here an internal error or an unloadable module - ASKS about a command that names `git` or
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. The branches the project lists in
13
+ * `guard.git.askPush` are read from the manifest, and a plain push to one of them asks.
11
14
  */
12
15
 
13
16
  // A module, so the awaits below are top-level; it has no static import, by design.
@@ -17,14 +20,22 @@ if (process.env.VULCAN_GUARDS === 'off') {
17
20
  process.exit(0);
18
21
  }
19
22
 
23
+ const text = await Bun.stdin.text();
24
+
20
25
  try {
21
26
  const { GuardDecisions } = await import('../../src/hooks/common/index.ts');
22
27
  const { buildToolDecision } = await import('../../src/hooks/decision.ts');
23
28
  const { inspectGit } = await import('../../src/hooks/guard-git.ts');
24
29
  const { parseHookCommand } = await import('../../src/hooks/guard-writes.ts');
25
- const hookCommand = parseHookCommand({ text: await Bun.stdin.text() });
30
+ const { readGuardPolicy } = await import('../../src/hooks/project-guards.ts');
31
+ const hookCommand = parseHookCommand({ text });
32
+ const cwd = hookCommand?.cwd ?? process.cwd();
26
33
  const hits = hookCommand
27
- ? 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
+ })
28
39
  : [];
29
40
 
30
41
  if (hits.length > 0) {
@@ -49,7 +60,25 @@ try {
49
60
  );
50
61
  }
51
62
  } catch (error) {
52
- console.error(
53
- `vulcan: the guard-git hook failed (${error instanceof Error ? error.message : String(error)}) - the call passes; run bun install`,
54
- );
63
+ const message = error instanceof Error ? error.message : String(error);
64
+
65
+ console.error(`vulcan: the guard-git hook failed (${message}); run bun install`);
66
+
67
+ // The imports may be what failed, so the answer is written by hand: no module is needed to ask.
68
+ if (/(^|[^A-Za-z0-9_])(git|gh)([^A-Za-z0-9_]|$)/.test(text)) {
69
+ console.log(
70
+ JSON.stringify({
71
+ hookSpecificOutput: {
72
+ hookEventName: 'PreToolUse',
73
+ permissionDecision: 'ask',
74
+ permissionDecisionReason: [
75
+ 'The guard-git hook failed, so this command was not checked:',
76
+ ` - ${message}`,
77
+ '',
78
+ 'Confirm only if the owner asked for exactly this; run bun install to repair the install, or VULCAN_GUARDS=off to switch the guards off for a session.',
79
+ ].join('\n'),
80
+ },
81
+ }),
82
+ );
83
+ }
55
84
  }
@@ -4,11 +4,13 @@
4
4
  * themselves are allowed - a default list, extended by `guard.toolOwnedPaths` in the project config.
5
5
  * `TMPDIR` or `mktemp` pointed at the system temp directory is not allowed.
6
6
  *
7
- * It fails OPEN: it guards against drift, not against an attacker, and a guard that blocks every call
8
- * when it breaks costs more than it protects. Input it cannot read, a missing module or an internal
9
- * error pass the call with a note on stderr; a project config that cannot be read leaves the default
10
- * allowlist. `VULCAN_GUARDS=off` switches it off, read before anything is imported. It imports only
11
- * the modules it needs - the config loader (and zod) is loaded on its own, last, and may fail alone.
7
+ * It guards against drift, not against an attacker, and a guard that blocks every call when its install
8
+ * is broken costs more than it protects. So input it cannot read passes, and so does a missing package or
9
+ * `bun` (the settings wrapper says so on stderr). A guard that started and then failed - a crash or a
10
+ * timeout, here an internal error or an unloadable module - ASKS instead of passing the call unchecked; a
11
+ * project config that cannot be read leaves the default allowlist. `VULCAN_GUARDS=off` switches it off,
12
+ * read before anything is imported. It imports only the modules it needs - the config loader (and zod) is
13
+ * loaded on its own, last, and may fail alone.
12
14
  */
13
15
 
14
16
  // A module, so the awaits below are top-level; it has no static import, by design.
@@ -18,12 +20,14 @@ if (process.env.VULCAN_GUARDS === 'off') {
18
20
  process.exit(0);
19
21
  }
20
22
 
23
+ const text = await Bun.stdin.text();
24
+
21
25
  try {
22
26
  const { GuardDecisions } = await import('../../src/hooks/common/index.ts');
23
27
  const { buildToolDecision } = await import('../../src/hooks/decision.ts');
24
28
  const { inspectOutside } = await import('../../src/hooks/guard-outside.ts');
25
29
  const { parseManifestHookInput } = await import('../../src/hooks/guard-manifest.ts');
26
- const input = parseManifestHookInput({ text: await Bun.stdin.text() });
30
+ const input = parseManifestHookInput({ text });
27
31
 
28
32
  if (input) {
29
33
  const projectRoot = process.env.CLAUDE_PROJECT_DIR ?? input.cwd ?? process.cwd();
@@ -51,7 +55,7 @@ try {
51
55
  'This would create files outside the project (V-B-08):',
52
56
  ...hits.map((hit) => ` - ${hit.message} (${hit.path})`),
53
57
  '',
54
- 'Everything an agent creates lives under .agents/local/ (tmp/, worktrees/, clones/). Use it, or confirm if the owner asked for this exact path.',
58
+ 'Scratch files go under .agents/local/tmp/<task>/ (worktrees under .agents/local/worktrees/, clones under .agents/local/clones/), never in /tmp or the home folder. Use that place, or confirm only if the owner asked for this exact path.',
55
59
  'A store a tool manages itself can be allowed with guard.toolOwnedPaths in .configs/vulcan.config.*.',
56
60
  ],
57
61
  }),
@@ -60,7 +64,23 @@ try {
60
64
  }
61
65
  }
62
66
  } catch (error) {
63
- console.error(
64
- `vulcan: the guard-outside hook failed (${error instanceof Error ? error.message : String(error)}) - the call passes; run bun install`,
67
+ const message = error instanceof Error ? error.message : String(error);
68
+
69
+ console.error(`vulcan: the guard-outside hook failed (${message}); run bun install`);
70
+
71
+ // The imports may be what failed, so the answer is written by hand: no module is needed to ask.
72
+ console.log(
73
+ JSON.stringify({
74
+ hookSpecificOutput: {
75
+ hookEventName: 'PreToolUse',
76
+ permissionDecision: 'ask',
77
+ permissionDecisionReason: [
78
+ 'The guard-outside hook failed, so this call was not checked for files outside the project (V-B-08):',
79
+ ` - ${message}`,
80
+ '',
81
+ 'Confirm only if the call stays inside the project; run bun install to repair the install, or VULCAN_GUARDS=off to switch the guards off for a session.',
82
+ ].join('\n'),
83
+ },
84
+ }),
65
85
  );
66
86
  }
@@ -1,6 +1,10 @@
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.
6
+ * A script the project lists in `guard.writes.trustedScripts` is not read for writes while git says it
7
+ * is tracked and unchanged; a config that cannot be read leaves the list empty, so every script is read.
4
8
  *
5
9
  * It fails closed: Claude Code blocks a PreToolUse call only on exit 2, so a hook that throws - a
6
10
  * partial install, say, where its own modules are missing - would let every command through. The
@@ -13,9 +17,33 @@ export {};
13
17
  try {
14
18
  const { buildGuardDecision, inspectCommand, parseHookCommand } =
15
19
  await import('../../src/hooks/guard-writes.ts');
20
+ const { readGuardPolicy } = await import('../../src/hooks/project-guards.ts');
16
21
  const hookCommand = parseHookCommand({ text: await Bun.stdin.text() });
22
+ const cwd = hookCommand?.cwd ?? process.cwd();
23
+ let scripts: string[] = [];
24
+
25
+ // Only a command that names a .ts file can use the list; the config loader (and zod) loads last, on its
26
+ // own, and may fail alone.
27
+ if (hookCommand && /\.ts\b/.test(hookCommand.command)) {
28
+ try {
29
+ const { loadConfig } = await import('../../src/config/index.ts');
30
+ const loaded = await loadConfig({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd });
31
+
32
+ scripts = loaded.ok ? loaded.config.guard.writes.trustedScripts : [];
33
+ } catch (error) {
34
+ console.error(
35
+ `vulcan: the guard-writes hook could not read the project config (${error instanceof Error ? error.message : String(error)}) - every script is read`,
36
+ );
37
+ }
38
+ }
39
+
17
40
  const hits = hookCommand
18
- ? inspectCommand({ command: hookCommand.command, cwd: hookCommand.cwd ?? process.cwd() })
41
+ ? inspectCommand({
42
+ command: hookCommand.command,
43
+ cwd,
44
+ trust: { root: process.env.CLAUDE_PROJECT_DIR ?? cwd, scripts },
45
+ extra: readGuardPolicy({ root: process.env.CLAUDE_PROJECT_DIR ?? cwd }).commands,
46
+ })
19
47
  : [];
20
48
 
21
49
  if (hits.length > 0) {
@@ -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
  ---
@@ -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.