Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Reference a starter pack for inspiration (ok seed --dry-run + skill + handoff pointer) (#1982)

tim-inkeep1e55fa496825
diff --git a/packages/app/src/components/handoff/useHandoffDispatch.test.ts b/packages/app/src/components/handoff/useHandoffDispatch.test.ts
index 9f6045f68..42edf4eb6 100644
--- a/packages/app/src/components/handoff/useHandoffDispatch.test.ts
+++ b/packages/app/src/components/handoff/useHandoffDispatch.test.ts
@@ -1,6 +1,7 @@
import { describe, expect, mock, test } from 'bun:test';
import { setTimeout as wait } from 'node:timers/promises';
import type { HandoffOutcome, HandoffPayload, HandoffTarget } from '@inkeep/open-knowledge-core';
+import { withSkillPointer } from '@inkeep/open-knowledge-core';
import type {
HandoffDispatchDeps,
HandoffDispatchInput,
@@ -187,7 +188,9 @@ describe('runHandoffDispatch — success path', () => {
'/tmp/demo-project/specs/2026-04-21-open-in-agent-desktop/SPEC.md',
);
expect(payload.prompt).toBe(
- "Let's work on `specs/2026-04-21-open-in-agent-desktop/SPEC.md` using Open Knowledge. Open the OK editor in web view.",
+ withSkillPointer(
+ "Let's work on `specs/2026-04-21-open-in-agent-desktop/SPEC.md` using Open Knowledge. Open the OK editor in web view.",
+ ),
);
});
@@ -225,9 +228,11 @@ describe('runHandoffDispatch — success path', () => {
expect(payload.target).toBe('codex');
expect(payload.projectDir).toBe('/Users/sarah/proj');
expect(payload.docPath).toBe('');
- expect(payload.prompt).toBe(composeEmptySpacePrompt(true));
+ expect(payload.prompt).toBe(withSkillPointer(composeEmptySpacePrompt(true)));
expect(payload.prompt).toBe(
- "Let's work on this project using Open Knowledge. Open the OK editor in web view.",
+ withSkillPointer(
+ "Let's work on this project using Open Knowledge. Open the OK editor in web view.",
+ ),
);
});
@@ -251,10 +256,12 @@ describe('runHandoffDispatch — success path', () => {
expect(payload.projectDir).toBe('/Users/sarah/proj');
expect(payload.docPath).toBe('');
expect(payload.prompt).toBe(
- composeFolderPrompt('specs/2026-05-16-sidebar-context-menus', true),
+ withSkillPointer(composeFolderPrompt('specs/2026-05-16-sidebar-context-menus', true)),
);
expect(payload.prompt).toBe(
- "Let's work on the `specs/2026-05-16-sidebar-context-menus` folder using Open Knowledge. Open the OK editor in web view.",
+ withSkillPointer(
+ "Let's work on the `specs/2026-05-16-sidebar-context-menus` folder using Open Knowledge. Open the OK editor in web view.",
+ ),
);
});
});
@@ -267,7 +274,9 @@ describe('runHandoffDispatch — autoOpen=false honors the user preference', ()
const [payload] = (deps.dispatchHandoff as ReturnType<typeof mock>).mock.calls[0] as [
HandoffPayload,
];
- expect(payload.prompt).toBe("Let's work on `specs/foo/SPEC.md` using Open Knowledge.");
+ expect(payload.prompt).toBe(
+ withSkillPointer("Let's work on `specs/foo/SPEC.md` using Open Knowledge."),
+ );
expect(payload.prompt).not.toContain('Open the OK editor');
});
@@ -284,7 +293,9 @@ describe('runHandoffDispatch — autoOpen=false honors the user preference', ()
const [payload] = (deps.dispatchHandoff as ReturnType<typeof mock>).mock.calls[0] as [
HandoffPayload,
];
- expect(payload.prompt).toBe("Let's work on the `specs/notes` folder using Open Knowledge.");
+ expect(payload.prompt).toBe(
+ withSkillPointer("Let's work on the `specs/notes` folder using Open Knowledge."),
+ );
expect(payload.prompt).not.toContain('Open the OK editor');
});
@@ -300,7 +311,9 @@ describe('runHandoffDispatch — autoOpen=false honors the user preference', ()
const [payload] = (deps.dispatchHandoff as ReturnType<typeof mock>).mock.calls[0] as [
HandoffPayload,
];
- expect(payload.prompt).toBe("Let's work on this project using Open Knowledge.");
+ expect(payload.prompt).toBe(
+ withSkillPointer("Let's work on this project using Open Knowledge."),
+ );
expect(payload.prompt).not.toContain('Open the OK editor');
});
});
@@ -783,9 +796,11 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () =
'claude-code',
true,
);
- expect(out).toBe(composeFilePrompt('notes/today.md', true));
+ expect(out).toBe(withSkillPointer(composeFilePrompt('notes/today.md', true)));
expect(out).toBe(
- "Let's work on `notes/today.md` using Open Knowledge. Open the OK editor in web view.",
+ withSkillPointer(
+ "Let's work on `notes/today.md` using Open Knowledge. Open the OK editor in web view.",
+ ),
);
});
@@ -800,7 +815,7 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () =
'claude-code',
false,
);
- expect(out).toBe("Let's work on `notes/today.md` using Open Knowledge.");
+ expect(out).toBe(withSkillPointer("Let's work on `notes/today.md` using Open Knowledge."));
});
test('folder scope (docContext null + folderRelativePath set) returns composeFolderPrompt with autoOpen=true trailer', async () => {
@@ -816,9 +831,11 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () =
'claude-code',
true,
);
- expect(out).toBe(composeFolderPrompt('notes', true));
+ expect(out).toBe(withSkillPointer(composeFolderPrompt('notes', true)));
expect(out).toBe(
- "Let's work on the `notes` folder using Open Knowledge. Open the OK editor in web view.",
+ withSkillPointer(
+ "Let's work on the `notes` folder using Open Knowledge. Open the OK editor in web view.",
+ ),
);
});
@@ -834,7 +851,7 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () =
'claude-code',
false,
);
- expect(out).toBe("Let's work on the `notes` folder using Open Knowledge.");
+ expect(out).toBe(withSkillPointer("Let's work on the `notes` folder using Open Knowledge."));
});
test('empty-space scope (both null/absent) returns composeEmptySpacePrompt(autoOpen=true)', async () => {
@@ -849,9 +866,11 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () =
'claude-code',
true,
);
- expect(out).toBe(composeEmptySpacePrompt(true));
+ expect(out).toBe(withSkillPointer(composeEmptySpacePrompt(true)));
expect(out).toBe(
- "Let's work on this project using Open Knowledge. Open the OK editor in web view.",
+ withSkillPointer(
+ "Let's work on this project using Open Knowledge. Open the OK editor in web view.",
+ ),
);
});
@@ -866,7 +885,7 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () =
'claude-code',
false,
);
- expect(out).toBe("Let's work on this project using Open Knowledge.");
+ expect(out).toBe(withSkillPointer("Let's work on this project using Open Knowledge."));
});
test('file scope threads the toolbar instruction into the directive prompt', async () => {
@@ -882,7 +901,9 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () =
'claude-code',
true,
);
- expect(out).toBe(composeFilePrompt('notes/today.md', true, 'Tighten the intro'));
+ expect(out).toBe(
+ withSkillPointer(composeFilePrompt('notes/today.md', true, 'Tighten the intro')),
+ );
expect(out).toContain('Instruction:\n\n> Tighten the intro');
});
@@ -988,7 +1009,9 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () =
'claude-code',
true,
);
- expect(out).toBe(composeCreatePrompt('a worldbuilding wiki', true, 'new-project'));
+ expect(out).toBe(
+ withSkillPointer(composeCreatePrompt('a worldbuilding wiki', true, 'new-project')),
+ );
expect(out).toContain('> a worldbuilding wiki');
expect(out).toContain('Open the OK editor in web view.');
});
@@ -1018,7 +1041,7 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () =
'claude-code',
false,
);
- expect(out).toBe(composeCreatePrompt('a wiki', false, 'new-project'));
+ expect(out).toBe(withSkillPointer(composeCreatePrompt('a wiki', false, 'new-project')));
});
test('create scope with empty createDescription routes to the create composer, NOT empty-space', async () => {
@@ -1037,8 +1060,8 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () =
'claude-code',
true,
);
- expect(out).toBe(composeCreatePrompt('', true, 'new-project'));
- expect(out).not.toBe(composeEmptySpacePrompt(true));
+ expect(out).toBe(withSkillPointer(composeCreatePrompt('', true, 'new-project')));
+ expect(out).not.toBe(withSkillPointer(composeEmptySpacePrompt(true)));
});
test('precedence: docContext beats folderRelativePath when both are set (defensive ordering)', async () => {
@@ -1054,7 +1077,7 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () =
'claude-code',
true,
);
- expect(out).toBe(composeFilePrompt('a.md', true));
+ expect(out).toBe(withSkillPointer(composeFilePrompt('a.md', true)));
});
test('selection scope (selection set) returns composeSelectionPrompt for the target', async () => {
@@ -1078,6 +1101,43 @@ describe('selectScopedPrompt — template selection across autoOpen modes', () =
expect(out).toBe(composeSelectionPrompt({ ...selection, target: 'cursor' }));
});
+ test('the standing skill pointer rides every directive scope but NOT selection', async () => {
+ const { selectScopedPrompt } = await import('./useHandoffDispatch');
+ const { OK_PROJECT_SKILL_POINTER } = await import('@inkeep/open-knowledge-core');
+ const base = { projectDir: '/proj', docPath: '' } as const;
+
+ const file = selectScopedPrompt(
+ { ...base, docContext: { relativePath: 'a.md' }, docPath: '/proj/a.md' },
+ 'claude-code',
+ true,
+ );
+ const folder = selectScopedPrompt(
+ { ...base, docContext: null, folderRelativePath: 'specs' },
+ 'claude-code',
+ true,
+ );
+ const empty = selectScopedPrompt({ ...base, docContext: null }, 'claude-code', true);
+ const create = selectScopedPrompt(
+ { ...base, docContext: null, createDescription: 'a wiki' },
+ 'claude-code',
+ true,
+ );
+ const selection = selectScopedPrompt(
+ {
+ ...base,
+ docContext: null,
+ selection: { relativePath: 'a.md', instruction: 'x', selectionMarkdown: 'y' },
+ },
+ 'claude-code',
+ true,
+ );
+
+ for (const prompt of [file, folder, empty, create]) {
+ expect(prompt.startsWith(OK_PROJECT_SKILL_POINTER)).toBe(true);
+ }
+ expect(selection).not.toContain(OK_PROJECT_SKILL_POINTER);
+ });
+
test('precedence: selection beats docContext when both are set (defensive ordering)', async () => {
const { selectScopedPrompt } = await import('./useHandoffDispatch');
const { composeSelectionPrompt } = await import('@inkeep/open-knowledge-core');
@@ -1309,7 +1369,7 @@ describe('composeTerminalLaunchPrompt — docked-terminal launcher always suppre
projectDir: '/proj',
docPath: '/proj/notes/today.md',
});
- expect(out).toBe("Let's work on `notes/today.md` using Open Knowledge.");
+ expect(out).toBe(withSkillPointer("Let's work on `notes/today.md` using Open Knowledge."));
expect(out).not.toContain('Open the OK editor');
});
@@ -1321,7 +1381,9 @@ describe('composeTerminalLaunchPrompt — docked-terminal launcher always suppre
projectDir: '/proj',
docPath: '',
});
- expect(out).toBe("Let's work on the `specs/foo` folder using Open Knowledge.");
+ expect(out).toBe(
+ withSkillPointer("Let's work on the `specs/foo` folder using Open Knowledge."),
+ );
expect(out).not.toContain('Open the OK editor');
});
@@ -1332,7 +1394,7 @@ describe('composeTerminalLaunchPrompt — docked-terminal launcher always suppre
projectDir: '/proj',
docPath: '',
});
- expect(out).toBe("Let's work on this project using Open Knowledge.");
+ expect(out).toBe(withSkillPointer("Let's work on this project using Open Knowledge."));
expect(out).not.toContain('Open the OK editor');
});
diff --git a/packages/app/src/components/handoff/useHandoffDispatch.ts b/packages/app/src/components/handoff/useHandoffDispatch.ts
index 38bf136c1..d1a8271fd 100644
--- a/packages/app/src/components/handoff/useHandoffDispatch.ts
+++ b/packages/app/src/components/handoff/useHandoffDispatch.ts
@@ -11,6 +11,7 @@ import {
type HandoffScope,
type HandoffTarget,
type TargetData,
+ withSkillPointer,
} from '@inkeep/open-knowledge-core';
import { toast as sonnerToast } from 'sonner';
import { useConfigContext } from '@/lib/config-context';
@@ -224,20 +225,19 @@ export function selectScopedPrompt(
if (input.selection) {
return composeSelectionPrompt({ ...input.selection, target });
}
- if (input.docContext !== null) {
- return composeFilePrompt(input.docContext.relativePath, autoOpen, input.instruction);
- }
- if (input.folderRelativePath) {
- return composeFolderPrompt(input.folderRelativePath, autoOpen, input.instruction);
- }
- if (input.createDescription !== undefined) {
- return composeCreatePrompt(
- input.createDescription,
- autoOpen,
- input.createScenario ?? 'new-project',
- );
- }
- return composeEmptySpacePrompt(autoOpen, input.instruction);
+ const directive =
+ input.docContext !== null
+ ? composeFilePrompt(input.docContext.relativePath, autoOpen, input.instruction)
+ : input.folderRelativePath
+ ? composeFolderPrompt(input.folderRelativePath, autoOpen, input.instruction)
+ : input.createDescription !== undefined
+ ? composeCreatePrompt(
+ input.createDescription,
+ autoOpen,
+ input.createScenario ?? 'new-project',
+ )
+ : composeEmptySpacePrompt(autoOpen, input.instruction);
+ return withSkillPointer(directive);
}
export function composeTerminalLaunchPrompt(input: HandoffDispatchInput): string {
diff --git a/packages/cli/src/commands/seed.test.ts b/packages/cli/src/commands/seed.test.ts
index f981cd110..45a501999 100644
--- a/packages/cli/src/commands/seed.test.ts
+++ b/packages/cli/src/commands/seed.test.ts
@@ -79,6 +79,20 @@ describe('runSeed — --dry-run', () => {
}
expect(existsSync(join(testDir, 'log.md'))).toBe(false);
});
+
+ test('surfaces the pack rationale (per-folder why) + anti-clone note for inspiration', async () => {
+ scaffoldOkDir(testDir);
+ const result = await runSeed({ cwd: testDir, pack: 'worldbuilding', dryRun: true });
+ expect(result.status).toBe('dry-run');
+ const pack = STARTER_PACKS.worldbuilding;
+ for (const folder of pack.folders) {
+ expect(result.message).toContain(folder.description);
+ }
+ expect(result.message.toLowerCase()).toContain('adapt'); // anti-clone framing
+ for (const folder of pack.folders) {
+ expect(existsSync(join(testDir, folder.path))).toBe(false);
+ }
+ });
});
describe('runSeed — no-op', () => {
diff --git a/packages/cli/src/commands/seed.ts b/packages/cli/src/commands/seed.ts
index cccc468d3..13420d27c 100644
--- a/packages/cli/src/commands/seed.ts
+++ b/packages/cli/src/commands/seed.ts
@@ -3,6 +3,7 @@ import { createInterface } from 'node:readline/promises';
import {
applySeed,
DEFAULT_PACK_ID,
+ formatPackRationale,
type PackId,
planSeed,
type ScaffoldPlan,
@@ -74,9 +75,10 @@ export async function runSeed(opts: SeedCommandOptions = {}): Promise<SeedComman
}
if (opts.dryRun) {
+ const rationale = formatPackRationale(STARTER_PACKS[packId]);
return {
status: 'dry-run',
- message: `${accent('Plan (dry-run — no changes made):')}\n\n${formatPlanBody(plan, cwd)}`,
+ message: `${accent('Reference this pack for inspiration (dry-run — no changes made):')}\n\n${rationale}\n\n${accent('Plan:')}\n\n${formatPlanBody(plan, cwd)}`,
plan,
exitCode: 0,
};
diff --git a/packages/core/src/handoff/index.ts b/packages/core/src/handoff/index.ts
index c34c5f5b5..131e56b6e 100644
--- a/packages/core/src/handoff/index.ts
+++ b/packages/core/src/handoff/index.ts
@@ -8,6 +8,8 @@ export {
composeFilePrompt,
composeFolderPrompt,
composeSelectionPrompt,
+ OK_PROJECT_SKILL_POINTER,
+ withSkillPointer,
} from './prompt-composer.ts';
export { buildClaudeLaunchCommand, shellSingleQuote } from './terminal-launch.ts';
export type {
diff --git a/packages/core/src/handoff/prompt-composer.test.ts b/packages/core/src/handoff/prompt-composer.test.ts
index aa8542fc0..1251eed5a 100644
--- a/packages/core/src/handoff/prompt-composer.test.ts
+++ b/packages/core/src/handoff/prompt-composer.test.ts
@@ -8,6 +8,7 @@ import {
composeFilePrompt,
composeFolderPrompt,
composeSelectionPrompt,
+ withSkillPointer,
} from './prompt-composer.ts';
import type { HandoffPayload, HandoffTarget } from './types.ts';
@@ -198,9 +199,9 @@ test('composeEmptySpacePrompt blockquotes every line of a multi-line instruction
test('directive composers keep the dispatched URL within 4096 chars for an oversized instruction (every target)', () => {
const hugeInstruction = 'please tighten this prose for clarity and concision '.repeat(200);
const composed = [
- composeFilePrompt('specs/deep/nested/SPEC.md', true, hugeInstruction),
- composeFolderPrompt('specs/deep/nested', true, hugeInstruction),
- composeEmptySpacePrompt(true, hugeInstruction),
+ withSkillPointer(composeFilePrompt('specs/deep/nested/SPEC.md', true, hugeInstruction)),
+ withSkillPointer(composeFolderPrompt('specs/deep/nested', true, hugeInstruction)),
+ withSkillPointer(composeEmptySpacePrompt(true, hugeInstruction)),
];
for (const target of ALL_TARGETS) {
for (const prompt of composed) {
diff --git a/packages/core/src/handoff/prompt-composer.ts b/packages/core/src/handoff/prompt-composer.ts
index 74ccf6a10..cba40946a 100644
--- a/packages/core/src/handoff/prompt-composer.ts
+++ b/packages/core/src/handoff/prompt-composer.ts
@@ -34,6 +34,13 @@ function sanitizePathForAtMention(path: string): string {
return path.replace(AT_MENTION_PATH_INJECTION_SANITIZE_RE, '_');
}
+export const OK_PROJECT_SKILL_POINTER =
+ "This is an Open Knowledge project: load the `open-knowledge` skill and use the Open Knowledge MCP tools for all markdown — don't probe for `.ok/` or use native file tools on `.md` / `.mdx`.";
+
+export function withSkillPointer(directive: string): string {
+ return `${OK_PROJECT_SKILL_POINTER} ${directive}`;
+}
+
export function composeFilePrompt(
relativePath: string,
autoOpen: boolean,
@@ -112,6 +119,10 @@ const URL_OVERHEAD_RESERVE = 1024;
* to locus mode. */
const INLINE_PROMPT_ENCODED_BUDGET = MAX_HANDOFF_URL_LENGTH - URL_OVERHEAD_RESERVE;
+const POINTER_ENCODED_RESERVE = encodedPromptLength(`${OK_PROJECT_SKILL_POINTER} `, 'cursor');
+const DIRECTIVE_INLINE_PROMPT_ENCODED_BUDGET =
+ INLINE_PROMPT_ENCODED_BUDGET - POINTER_ENCODED_RESERVE;
+
const LOCUS_ANCHOR_MAX_CHARS = 160;
const MIN_FENCE_LENGTH = 3;
@@ -184,9 +195,9 @@ function fitInstruction(
compose: (instruction: string) => string,
instruction: string,
target: HandoffTarget,
+ budget: number = INLINE_PROMPT_ENCODED_BUDGET,
): string {
- const fits = (instr: string): boolean =>
- encodedPromptLength(compose(instr), target) <= INLINE_PROMPT_ENCODED_BUDGET;
+ const fits = (instr: string): boolean => encodedPromptLength(compose(instr), target) <= budget;
if (fits(instruction)) return instruction;
const codePoints = Array.from(instruction);
let lo = 0;
@@ -206,6 +217,7 @@ function fitInstructionForDirective(directive: string, instruction: string): str
(instr) => directiveWithInstruction(directive, instr),
instruction,
'cursor',
+ DIRECTIVE_INLINE_PROMPT_ENCODED_BUDGET,
);
}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 9862e8c0d..111507ce9 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -369,11 +369,13 @@ export {
type IpcChannelReason,
type IpcChannelWithUrn,
lookupUrnInRegistry,
+ OK_PROJECT_SKILL_POINTER,
shellSingleQuote,
type TargetData,
URN_HTTP_ONLY,
URN_IPC_REGISTRY,
type UrnIpcLookup,
+ withSkillPointer,
} from './handoff/index.ts';
export type {
BundleManifest,
diff --git a/packages/server/assets/skills/project/SKILL.md b/packages/server/assets/skills/project/SKILL.md
index 3169d3c4a..305facc57 100644
--- a/packages/server/assets/skills/project/SKILL.md
+++ b/packages/server/assets/skills/project/SKILL.md
@@ -483,7 +483,19 @@ Typical day-2 flow: user shares a URL → `ingest` (preserve) → user asks "now
**Repeat invocations.** The `workflow` tool returns its full instructional body on every call, including 2nd / 3rd / Nth invocation in the same session. If you've already received a tool's body earlier this session, you can skim the repeat for changes (the body can evolve across server versions) but you don't need to re-internalize it — proceed to the next step with the new arguments.
-**Project scaffolding — two paths.** **Empty repo:** run `ok seed` once from a terminal (scaffolds Karpathy three-layer + seeds `log.md` + registers folder defaults). **Existing content:** invoke `workflow({ kind: 'discover' })` (table above — extracts conventions from siblings, sets folder frontmatter + templates, curates `.okignore`, activates link graph; per-phase confirmation gates). Neither is required; the four workflow kinds work against any folder structure. Only mention each when explicitly relevant.
+**Project scaffolding — two paths.** **Empty repo:** run `ok seed` once from a terminal (scaffolds the layout + seeds `log.md` + folder defaults). **Existing content:** invoke `workflow({ kind: 'discover' })` (table above). Neither is required; the four workflow kinds work against any folder structure. Only mention each when explicitly relevant.
+
+**Starter packs — reference for inspiration.** The `ok` CLI (a Bash surface beside the MCP tools; other verbs `ok start` / `ok open` are documented above) ships proven layouts you can study to build a *similar* structure of your own — adapt the idea, don't clone the pack:
+
+- `knowledge-base` — source-grounded research articles
+- `software-lifecycle` — proposals, decisions, specs
+- `plain-notes` — notes + daily journal
+- `worldbuilding` — fiction story wiki
+- `writing-pipeline` — drafts → published
+- `entity-vault` — people / companies / meetings (personal CRM)
+- `okf` — Open Knowledge Format–conformant base
+
+To reference one **without installing it**: `ok seed --list-packs` (the menu) → `ok seed --pack <name> --dry-run` (its folders + the *why* of each folder + templates; writes nothing). Then either adapt the ideas into your own folders (`write({ folder })` + a template) or adopt the pack as-is by re-running without `--dry-run`. Reach for this when a user wants structure and an archetype fits — propose a tailored variant, not a verbatim copy.
## Server lifecycle
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
index e226979f4..42a52f2e9 100644
--- a/packages/server/src/index.ts
+++ b/packages/server/src/index.ts
@@ -338,6 +338,7 @@ export {
coercePackId,
DEFAULT_PACK_ID,
type FileEntry,
+ formatPackRationale,
isKnownPackId,
LOG_MD_TEMPLATE,
listStarterPacks,
diff --git a/packages/server/src/seed/index.ts b/packages/server/src/seed/index.ts
index 96c77a015..aa3375a6d 100644
--- a/packages/server/src/seed/index.ts
+++ b/packages/server/src/seed/index.ts
@@ -1,5 +1,6 @@
export { applySeed } from './apply.ts';
export { planSeed } from './plan.ts';
+export { formatPackRationale } from './rationale.ts';
export {
buildStarterFolderFrontmatterYaml,
coercePackId,
diff --git a/packages/server/src/seed/rationale.test.ts b/packages/server/src/seed/rationale.test.ts
new file mode 100644
index 000000000..86d5dcb3f
--- /dev/null
+++ b/packages/server/src/seed/rationale.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, test } from 'bun:test';
+import { formatPackRationale, PACK_INSPIRATION_NOTE } from './rationale.ts';
+import { STARTER_PACK_IDS, STARTER_PACKS } from './starter.ts';
+
+describe('formatPackRationale', () => {
+ test('headers with the pack name + description', () => {
+ const out = formatPackRationale(STARTER_PACKS.worldbuilding);
+ expect(out).toContain(STARTER_PACKS.worldbuilding.name);
+ expect(out).toContain(STARTER_PACKS.worldbuilding.description);
+ });
+
+ test('surfaces every folder’s "why" + template names, for every pack', () => {
+ for (const id of STARTER_PACK_IDS) {
+ const pack = STARTER_PACKS[id];
+ const out = formatPackRationale(pack);
+ for (const folder of pack.folders) {
+ expect(out).toContain(`${folder.path}/`);
+ expect(out).toContain(folder.description);
+ expect(out).toContain(folder.starterTemplate);
+ for (const extra of folder.extraTemplates ?? []) {
+ expect(out).toContain(extra);
+ }
+ }
+ }
+ });
+
+ test('carries the anti-clone inspiration note (adapt, not clone)', () => {
+ expect(formatPackRationale(STARTER_PACKS['knowledge-base'])).toContain(PACK_INSPIRATION_NOTE);
+ expect(PACK_INSPIRATION_NOTE.toLowerCase()).toContain('adapt');
+ expect(PACK_INSPIRATION_NOTE).toContain('--dry-run');
+ });
+
+ test('lists root files when a pack ships them, omits the section otherwise', () => {
+ const kbPack = STARTER_PACKS['knowledge-base'];
+ const kbRootFiles = Object.keys(kbPack.rootFiles ?? {});
+ expect(kbRootFiles.length).toBeGreaterThan(0); // guards the fixture choice below
+ const kb = formatPackRationale(kbPack);
+ expect(kb).toContain('Root files:');
+ for (const fileName of kbRootFiles) {
+ expect(kb).toContain(fileName);
+ }
+ const noRootFilesPack = STARTER_PACK_IDS.map((id) => STARTER_PACKS[id]).find(
+ (p) => Object.keys(p.rootFiles ?? {}).length === 0,
+ );
+ expect(noRootFilesPack).toBeDefined();
+ if (noRootFilesPack) {
+ expect(formatPackRationale(noRootFilesPack)).not.toContain('Root files:');
+ }
+ });
+});
diff --git a/packages/server/src/seed/rationale.ts b/packages/server/src/seed/rationale.ts
new file mode 100644
index 000000000..7742d2b49
--- /dev/null
+++ b/packages/server/src/seed/rationale.ts
@@ -0,0 +1,34 @@
+import type { StarterFolder, StarterPack } from './starter.ts';
+
+export const PACK_INSPIRATION_NOTE = [
+ 'These are patterns to adapt to your domain, not a layout to copy verbatim.',
+ 'To build a variant: create your own folders (via `write` or your editor) and reuse only the ideas that fit.',
+ 'To adopt this pack as-is: re-run without `--dry-run`.',
+].join('\n');
+
+function folderTemplateNames(folder: StarterFolder): string {
+ return [folder.starterTemplate, ...(folder.extraTemplates ?? [])].join(', ');
+}
+
+export function formatPackRationale(pack: StarterPack): string {
+ const lines: string[] = [
+ `Pack: ${pack.name} — ${pack.description}`,
+ '',
+ PACK_INSPIRATION_NOTE,
+ '',
+ ];
+
+ lines.push('Layout & rationale:');
+ for (const folder of pack.folders) {
+ lines.push(` ${folder.path}/ — ${folder.title}`);
+ lines.push(` why: ${folder.description}`);
+ lines.push(` templates: ${folderTemplateNames(folder)}`);
+ }
+
+ const rootFiles = pack.rootFiles ? Object.keys(pack.rootFiles) : [];
+ if (rootFiles.length > 0) {
+ lines.push('', `Root files: ${rootFiles.join(', ')}`);
+ }
+
+ return lines.join('\n');
+}
diff --git a/packages/server/src/seed/skill-pack-list-drift.test.ts b/packages/server/src/seed/skill-pack-list-drift.test.ts
new file mode 100644
index 000000000..0605fa08b
--- /dev/null
+++ b/packages/server/src/seed/skill-pack-list-drift.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { STARTER_PACK_IDS } from './starter.ts';
+
+const SKILL_PATH = join(import.meta.dir, '../../assets/skills/project/SKILL.md');
+const PACK_BULLET_RE = /^- `([a-z][a-z0-9-]+)` —/gm;
+
+describe('project SKILL.md starter-pack awareness list', () => {
+ test('lists exactly the packs in STARTER_PACK_IDS (drift guard)', () => {
+ const skill = readFileSync(SKILL_PATH, 'utf-8');
+ const listed = [...skill.matchAll(PACK_BULLET_RE)].map((m) => m[1]);
+ expect(listed.length).toBeGreaterThan(0);
+ expect(new Set(listed)).toEqual(new Set(STARTER_PACK_IDS));
+ });
+
+ test('points the agent at the reference ladder (--list-packs → --dry-run)', () => {
+ const skill = readFileSync(SKILL_PATH, 'utf-8');
+ expect(skill).toContain('ok seed --list-packs');
+ expect(skill).toContain('--dry-run');
+ });
+});