@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.
- package/LICENSE.md +1 -1
- package/README.md +13 -0
- package/base/agents.json +22 -1
- package/base/checks/wiki-anchors.ts +8 -0
- package/base/checks/wiki-source-links.ts +8 -0
- package/base/claude/remote-hosts.json +1 -1
- package/base/claude/settings.json +12 -12
- package/base/extensions/vulcan-guards.ts +301 -0
- package/base/hooks/antigravity-guards.ts +68 -0
- package/base/hooks/codex-guards.ts +66 -0
- package/base/hooks/guard-git.ts +38 -9
- package/base/hooks/guard-outside.ts +29 -9
- package/base/hooks/guard-writes.ts +29 -1
- package/base/hooks/session-start.ts +14 -4
- package/base/make/vulcan.mk +12 -1
- package/base/references/delegation-brief.md +5 -4
- package/base/rules.md +2 -2
- package/base/skills/docs-writing/SKILL.md +1 -1
- package/base/skills/docs-writing/references/agent-documents.md +1 -1
- package/base/skills/knowledge-sync/SKILL.md +1 -1
- package/base/skills/plan-a-change/SKILL.md +1 -1
- package/base/skills/report-back/SKILL.md +1 -1
- package/base/skills/retro/SKILL.md +1 -1
- package/base/skills/review-a-change/SKILL.md +1 -1
- package/base/skills/ship/SKILL.md +1 -1
- package/base/skills/visualize-work/SKILL.md +33 -11
- package/base/skills/visualize-work/references/spec.md +77 -12
- package/package.json +4 -4
- package/src/agents/codex-hooks.ts +133 -0
- package/src/agents/common/constants.ts +54 -0
- package/src/agents/common/schema.ts +10 -1
- package/src/agents/common/types.ts +3 -1
- package/src/agents/exclude.ts +4 -0
- package/src/agents/hooks-json.ts +111 -0
- package/src/agents/index.ts +2 -0
- package/src/agents/render.ts +5 -4
- package/src/agents/resolve.ts +24 -9
- package/src/config/common/constants.ts +12 -0
- package/src/config/common/types.ts +2 -1
- package/src/config/packages.ts +2 -1
- package/src/config/schema.ts +84 -5
- package/src/create/add-app.ts +2 -2
- package/src/create/add-lib.ts +21 -8
- package/src/create/common/constants.ts +12 -0
- package/src/create/common/types.ts +2 -1
- package/src/create/preset-diff.ts +4 -2
- package/src/create/workspace.ts +13 -9
- package/src/doctor/checks.ts +71 -1
- package/src/doctor/common/constants.ts +2 -0
- package/src/doctor/runner.ts +6 -0
- package/src/hooks/codex-patch.ts +47 -0
- package/src/hooks/command-view.ts +97 -0
- package/src/hooks/common/constants.ts +46 -0
- package/src/hooks/common/types.ts +9 -1
- package/src/hooks/decision.ts +50 -8
- package/src/hooks/guard-git.ts +64 -5
- package/src/hooks/guard-manifest.ts +22 -8
- package/src/hooks/guard-outside.ts +38 -6
- package/src/hooks/guard-package.ts +15 -12
- package/src/hooks/guard-writes.ts +72 -21
- package/src/hooks/index.ts +5 -0
- package/src/hooks/project-guards.ts +123 -0
- package/src/hooks/project-tmp.ts +36 -0
- package/src/hooks/remote-hosts.ts +38 -14
- package/src/hooks/session-digest.ts +5 -0
- package/src/hooks/shell.ts +665 -35
- package/src/hooks/trusted-scripts.ts +134 -0
- package/src/manifest/render.ts +38 -0
- package/src/sync/agent-files.ts +122 -4
- package/src/sync/agent-removal.ts +118 -4
- package/src/sync/claude-launch.ts +48 -0
- package/src/sync/index.ts +1 -0
- package/src/sync/local-choice.ts +2 -0
- package/src/visualize/assets.ts +195 -54
- package/src/visualize/charts.ts +235 -0
- package/src/visualize/constants.ts +122 -1
- package/src/visualize/diagrams.ts +224 -0
- package/src/visualize/icons.ts +28 -0
- package/src/visualize/layout.ts +58 -8
- package/src/visualize/page.ts +151 -145
- package/src/visualize/schema.ts +252 -2
- package/src/visualize/sections.ts +370 -0
- package/src/visualize/validate.ts +100 -7
- package/src/wiki/anchors.ts +118 -0
- package/src/wiki/command.ts +110 -0
- package/src/wiki/constants.ts +30 -0
- package/src/wiki/index.ts +4 -0
- 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
|
+
}
|
package/base/hooks/guard-git.ts
CHANGED
|
@@ -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
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
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
|
|
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({
|
|
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
|
-
|
|
53
|
-
|
|
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
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
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
|
|
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
|
-
'
|
|
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
|
-
|
|
64
|
-
|
|
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({
|
|
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.
|
|
8
|
-
|
|
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
|
+
}
|
package/base/make/vulcan.mk
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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
|
-
|
|
20
|
-
|
|
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
|
|
25
|
-
| V-W-03 | Never deploy or hot-apply (kubectl apply, docker compose up, restarts). | HARD - guard-writes hook
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
|
11
|
-
|
|
12
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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,
|
|
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.
|