@pellux/goodvibes-agent 1.1.7 → 1.3.0

package/src/agent/skill-registry-types.ts

@@ -0,0 +1,102 @@
+export type AgentSkillSource = 'user' | 'agent' | 'imported' | 'system';
+export type AgentSkillReviewState = 'fresh' | 'reviewed' | 'stale';
+export type AgentSkillRequirementKind = 'env' | 'command';
+
+export interface AgentSkillRequirement {
+  readonly kind: AgentSkillRequirementKind;
+  readonly name: string;
+  readonly description?: string;
+}
+
+export interface AgentSkillReadiness {
+  readonly ready: boolean;
+  readonly met: readonly AgentSkillRequirement[];
+  readonly missing: readonly AgentSkillRequirement[];
+}
+
+export interface AgentSkillBundleReadiness {
+  readonly ready: boolean;
+  readonly includedSkills: readonly AgentSkillRecord[];
+  readonly missingSkillIds: readonly string[];
+  readonly missingRequirements: readonly AgentSkillRequirement[];
+}
+
+export interface AgentSkillRecord {
+  readonly id: string;
+  readonly name: string;
+  readonly description: string;
+  readonly procedure: string;
+  readonly triggers: readonly string[];
+  readonly tags: readonly string[];
+  readonly requirements: readonly AgentSkillRequirement[];
+  readonly enabled: boolean;
+  readonly source: AgentSkillSource;
+  readonly provenance: string;
+  readonly reviewState: AgentSkillReviewState;
+  readonly staleReason?: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly reviewedAt?: string;
+}
+
+export interface AgentSkillBundleRecord {
+  readonly id: string;
+  readonly name: string;
+  readonly description: string;
+  readonly skillIds: readonly string[];
+  readonly enabled: boolean;
+  readonly source: AgentSkillSource;
+  readonly provenance: string;
+  readonly reviewState: AgentSkillReviewState;
+  readonly staleReason?: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly reviewedAt?: string;
+}
+
+export interface AgentSkillCreateInput {
+  readonly name: string;
+  readonly description: string;
+  readonly procedure: string;
+  readonly triggers?: readonly string[];
+  readonly tags?: readonly string[];
+  readonly requirements?: readonly AgentSkillRequirement[];
+  readonly enabled?: boolean;
+  readonly source?: AgentSkillSource;
+  readonly provenance?: string;
+}
+
+export interface AgentSkillBundleCreateInput {
+  readonly name: string;
+  readonly description: string;
+  readonly skillIds: readonly string[];
+  readonly enabled?: boolean;
+  readonly source?: AgentSkillSource;
+  readonly provenance?: string;
+}
+
+export interface AgentSkillUpdateInput {
+  readonly name?: string;
+  readonly description?: string;
+  readonly procedure?: string;
+  readonly triggers?: readonly string[];
+  readonly tags?: readonly string[];
+  readonly requirements?: readonly AgentSkillRequirement[];
+  readonly provenance?: string;
+}
+
+export interface AgentSkillBundleUpdateInput {
+  readonly name?: string;
+  readonly description?: string;
+  readonly skillIds?: readonly string[];
+  readonly provenance?: string;
+}
+
+export interface AgentSkillSnapshot {
+  readonly path: string;
+  readonly skills: readonly AgentSkillRecord[];
+  readonly enabledSkills: readonly AgentSkillRecord[];
+  readonly bundles: readonly AgentSkillBundleRecord[];
+  readonly enabledBundles: readonly AgentSkillBundleRecord[];
+  readonly activeSkills: readonly AgentSkillRecord[];
+}

package/src/agent/skill-registry.ts

@@ -4,109 +4,34 @@ import type { ShellPathService } from '@/runtime/index.ts';
 import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
 import { assertNoSecretLikeText } from './persona-registry.ts';
 import { formatAgentRecordReviewState } from './record-labels.ts';
-
-export type AgentSkillSource = 'user' | 'agent' | 'imported' | 'system';
-export type AgentSkillReviewState = 'fresh' | 'reviewed' | 'stale';
-export type AgentSkillRequirementKind = 'env' | 'command';
-
-export interface AgentSkillRequirement {
-  readonly kind: AgentSkillRequirementKind;
-  readonly name: string;
-  readonly description?: string;
-}
-
-export interface AgentSkillReadiness {
-  readonly ready: boolean;
-  readonly met: readonly AgentSkillRequirement[];
-  readonly missing: readonly AgentSkillRequirement[];
-}
-
-export interface AgentSkillBundleReadiness {
-  readonly ready: boolean;
-  readonly includedSkills: readonly AgentSkillRecord[];
-  readonly missingSkillIds: readonly string[];
-  readonly missingRequirements: readonly AgentSkillRequirement[];
-}
-
-export interface AgentSkillRecord {
-  readonly id: string;
-  readonly name: string;
-  readonly description: string;
-  readonly procedure: string;
-  readonly triggers: readonly string[];
-  readonly tags: readonly string[];
-  readonly requirements: readonly AgentSkillRequirement[];
-  readonly enabled: boolean;
-  readonly source: AgentSkillSource;
-  readonly provenance: string;
-  readonly reviewState: AgentSkillReviewState;
-  readonly staleReason?: string;
-  readonly createdAt: string;
-  readonly updatedAt: string;
-  readonly reviewedAt?: string;
-}
-
-export interface AgentSkillBundleRecord {
-  readonly id: string;
-  readonly name: string;
-  readonly description: string;
-  readonly skillIds: readonly string[];
-  readonly enabled: boolean;
-  readonly source: AgentSkillSource;
-  readonly provenance: string;
-  readonly reviewState: AgentSkillReviewState;
-  readonly staleReason?: string;
-  readonly createdAt: string;
-  readonly updatedAt: string;
-  readonly reviewedAt?: string;
-}
-
-export interface AgentSkillCreateInput {
-  readonly name: string;
-  readonly description: string;
-  readonly procedure: string;
-  readonly triggers?: readonly string[];
-  readonly tags?: readonly string[];
-  readonly requirements?: readonly AgentSkillRequirement[];
-  readonly enabled?: boolean;
-  readonly source?: AgentSkillSource;
-  readonly provenance?: string;
-}
-
-export interface AgentSkillBundleCreateInput {
-  readonly name: string;
-  readonly description: string;
-  readonly skillIds: readonly string[];
-  readonly enabled?: boolean;
-  readonly source?: AgentSkillSource;
-  readonly provenance?: string;
-}
-
-export interface AgentSkillUpdateInput {
-  readonly name?: string;
-  readonly description?: string;
-  readonly procedure?: string;
-  readonly triggers?: readonly string[];
-  readonly tags?: readonly string[];
-  readonly requirements?: readonly AgentSkillRequirement[];
-  readonly provenance?: string;
-}
-
-export interface AgentSkillBundleUpdateInput {
-  readonly name?: string;
-  readonly description?: string;
-  readonly skillIds?: readonly string[];
-  readonly provenance?: string;
-}
-
-export interface AgentSkillSnapshot {
-  readonly path: string;
-  readonly skills: readonly AgentSkillRecord[];
-  readonly enabledSkills: readonly AgentSkillRecord[];
-  readonly bundles: readonly AgentSkillBundleRecord[];
-  readonly enabledBundles: readonly AgentSkillBundleRecord[];
-  readonly activeSkills: readonly AgentSkillRecord[];
-}
+import type {
+  AgentSkillBundleCreateInput,
+  AgentSkillBundleReadiness,
+  AgentSkillBundleRecord,
+  AgentSkillBundleUpdateInput,
+  AgentSkillCreateInput,
+  AgentSkillReadiness,
+  AgentSkillRecord,
+  AgentSkillRequirement,
+  AgentSkillRequirementKind,
+  AgentSkillSnapshot,
+  AgentSkillUpdateInput,
+} from './skill-registry-types.ts';
+export type {
+  AgentSkillBundleCreateInput,
+  AgentSkillBundleReadiness,
+  AgentSkillBundleRecord,
+  AgentSkillBundleUpdateInput,
+  AgentSkillCreateInput,
+  AgentSkillReadiness,
+  AgentSkillRecord,
+  AgentSkillRequirement,
+  AgentSkillRequirementKind,
+  AgentSkillReviewState,
+  AgentSkillSnapshot,
+  AgentSkillSource,
+  AgentSkillUpdateInput,
+} from './skill-registry-types.ts';
 
 interface SkillStoreFile {
   readonly version: 1;
@@ -754,13 +679,55 @@ export function evaluateAgentSkillBundleReadiness(
 
 export function buildEnabledSkillsPrompt(shellPaths: ShellPathService): string | null {
   const snapshot = AgentSkillRegistry.fromShellPaths(shellPaths).snapshot();
-  const active = snapshot.activeSkills;
-  if (active.length === 0 && snapshot.enabledBundles.length === 0) return null;
+  const enabledBundles = snapshot.enabledBundles.filter((bundle) => {
+    if (bundle.reviewState !== 'reviewed') return false;
+    const readiness = evaluateAgentSkillBundleReadiness(bundle, snapshot.skills);
+    return readiness.ready && readiness.includedSkills.every((skill) => skill.reviewState === 'reviewed');
+  });
+  const activeSkillIds = new Set([
+    ...snapshot.enabledSkills.map((skill) => skill.id),
+    ...enabledBundles.flatMap((bundle) => bundle.skillIds),
+  ]);
+  const active = snapshot.skills.filter((skill) => (
+    activeSkillIds.has(skill.id)
+    && skill.reviewState === 'reviewed'
+    && evaluateAgentSkillReadiness(skill).ready
+  ));
+  const candidateSkillIds = new Set([
+    ...snapshot.enabledSkills.map((skill) => skill.id),
+    ...snapshot.enabledBundles.flatMap((bundle) => bundle.skillIds),
+  ]);
+  const suppressedSkills = snapshot.skills
+    .filter((skill) => candidateSkillIds.has(skill.id) && !active.some((activeSkill) => activeSkill.id === skill.id))
+    .slice(0, 8)
+    .map((skill) => {
+      const readiness = evaluateAgentSkillReadiness(skill);
+      const review = skill.reviewState === 'reviewed' ? '' : `review=${formatAgentRecordReviewState(skill.reviewState)}`;
+      const setup = readiness.ready ? '' : `missing=${readiness.missing.map(formatAgentSkillRequirement).join(', ')}`;
+      return `- ${skill.name}: ${[review, setup].filter(Boolean).join('; ')}`;
+    });
+  const suppressedBundles = snapshot.enabledBundles
+    .filter((bundle) => !enabledBundles.some((activeBundle) => activeBundle.id === bundle.id))
+    .slice(0, 4)
+    .map((bundle) => {
+      const readiness = evaluateAgentSkillBundleReadiness(bundle, snapshot.skills);
+      const review = bundle.reviewState === 'reviewed' ? '' : `review=${formatAgentRecordReviewState(bundle.reviewState)}`;
+      const setup = readiness.ready ? '' : `missing=${[
+        ...readiness.missingRequirements.map(formatAgentSkillRequirement),
+        ...readiness.missingSkillIds.map((skillId) => `skill:${skillId}`),
+      ].join(', ')}`;
+      const unreviewedSkills = readiness.includedSkills
+        .filter((skill) => skill.reviewState !== 'reviewed')
+        .map((skill) => `${skill.id}:${formatAgentRecordReviewState(skill.reviewState)}`);
+      const memberReview = unreviewedSkills.length === 0 ? '' : `member-review=${unreviewedSkills.join(', ')}`;
+      return `- ${bundle.name}: ${[review, setup, memberReview].filter(Boolean).join('; ')}`;
+    });
+  if (active.length === 0 && enabledBundles.length === 0 && suppressedSkills.length === 0 && suppressedBundles.length === 0) return null;
   return [
     '## Enabled GoodVibes Agent Skills',
-    'Use these local reusable procedures inside the same serial assistant conversation when they fit the user request.',
+    'Use only reviewed, setup-ready local reusable procedures inside the same serial assistant conversation when they fit the user request.',
     '',
-    ...snapshot.enabledBundles.slice(0, 4).flatMap((bundle) => {
+    ...enabledBundles.slice(0, 4).flatMap((bundle) => {
       const readiness = evaluateAgentSkillBundleReadiness(bundle, snapshot.skills);
       const missing = [
         ...readiness.missingRequirements.map(formatAgentSkillRequirement),
@@ -784,5 +751,12 @@ export function buildEnabledSkillsPrompt(shellPaths: ShellPathService): string |
       skill.procedure,
       '',
     ]),
+    ...(suppressedBundles.length > 0 || suppressedSkills.length > 0 ? [
+      '### Suppressed Skills Pending Review Or Setup',
+      'Do not apply these skills until the user reviews them or resolves setup through the learning curator.',
+      ...suppressedBundles,
+      ...suppressedSkills,
+      '',
+    ] : []),
   ].join('\n').trim();
 }

package/src/agent/vibe-confirmation-routes.ts

@@ -0,0 +1,62 @@
+export function vibeRouteArg(value: string): string {
+  return JSON.stringify(value);
+}
+
+function routeLine(id: string, route: string): string {
+  return `    ${id} ${route}`;
+}
+
+export function vibeInitConfirmationRoutes(scope: 'project' | 'global', force = false): Record<string, string> {
+  const model = [
+    'vibe action:"init"',
+    `scope:${vibeRouteArg(scope)}`,
+    force ? 'force:true' : '',
+    'confirm:true',
+    'explicitUserRequest:"..."',
+  ].filter(Boolean).join(' ');
+  const cli = [
+    '/vibe init',
+    scope === 'global' ? '--global' : '',
+    force ? '--force' : '',
+    '--yes',
+  ].filter(Boolean).join(' ');
+  return { model, cli };
+}
+
+export function vibeImportPersonaConfirmationRoutes(input: {
+  readonly reference: string;
+  readonly name: string;
+  readonly description: string;
+  readonly review: boolean;
+  readonly use: boolean;
+}): Record<string, string> {
+  const model = [
+    'vibe action:"import_persona"',
+    `reference:${vibeRouteArg(input.reference)}`,
+    input.name ? `name:${vibeRouteArg(input.name)}` : '',
+    input.description ? `description:${vibeRouteArg(input.description)}` : '',
+    input.review ? 'review:true' : '',
+    input.use ? 'use:true' : '',
+    'confirm:true',
+    'explicitUserRequest:"..."',
+  ].filter(Boolean).join(' ');
+  const cli = [
+    '/vibe import-persona',
+    vibeRouteArg(input.reference),
+    input.name ? `--name ${vibeRouteArg(input.name)}` : '',
+    input.description ? `--description ${vibeRouteArg(input.description)}` : '',
+    input.review ? '--review' : '',
+    input.use ? '--use' : '',
+    '--yes',
+  ].filter(Boolean).join(' ');
+  return { model, cli };
+}
+
+export function formatVibeConfirmationRouteLines(routes: Record<string, string>): readonly string[] {
+  const entries = Object.entries(routes).filter(([, route]) => route.trim() !== '');
+  if (entries.length === 0) return [];
+  return [
+    '  confirmationRoutes',
+    ...entries.map(([id, route]) => routeLine(id, route)),
+  ];
+}

package/src/agent/vibe-file.ts

@@ -0,0 +1,285 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import type { ShellPathService } from '@/runtime/index.ts';
+import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
+import { assertNoSecretLikeText } from './persona-registry.ts';
+
+export type AgentVibeScope = 'project' | 'global';
+
+export interface AgentVibeFile {
+  readonly path: string;
+  readonly scope: AgentVibeScope;
+  readonly body: string;
+  readonly frontmatter: Record<string, string>;
+  readonly truncated: boolean;
+}
+
+export interface BlockedAgentVibeFile {
+  readonly path: string;
+  readonly scope: AgentVibeScope;
+  readonly reason: string;
+}
+
+export interface AgentVibeSnapshot {
+  readonly files: readonly AgentVibeFile[];
+  readonly blocked: readonly BlockedAgentVibeFile[];
+  readonly searchedPaths: readonly string[];
+  readonly projectInitPath: string;
+  readonly globalInitPath: string;
+}
+
+export interface AgentVibeInitOptions {
+  readonly scope?: AgentVibeScope;
+  readonly force?: boolean;
+}
+
+export interface AgentVibeInitResult {
+  readonly path: string;
+  readonly created: boolean;
+}
+
+export interface AgentVibeImportSource {
+  readonly name: string;
+  readonly description: string;
+  readonly body: string;
+  readonly path: string;
+  readonly scope: AgentVibeScope;
+}
+
+const MAX_VIBE_BODY_CHARS = 8_000;
+const MAX_PROJECT_DEPTH = 32;
+
+const DEFAULT_VIBE_BODY = [
+  '# VIBE.md',
+  '',
+  'Describe how GoodVibes Agent should feel and work with you.',
+  '',
+  '- Be direct about tradeoffs.',
+  '- Prefer visible, reversible actions.',
+  '- Keep autonomous work user-supervised with clear status and cancel paths.',
+  '- Ask before sending messages, changing settings, or starting recurring work.',
+].join('\n');
+
+type AgentVibePaths = Pick<ShellPathService,
+  'workingDirectory' | 'homeDirectory' | 'resolveUserPath' | 'expandHomePath' | 'resolveWorkspacePath'
+>;
+
+function parseFrontmatter(content: string): Record<string, string> {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!match) return {};
+  const result: Record<string, string> = {};
+  for (const line of match[1].split('\n')) {
+    const [key, ...rest] = line.split(':');
+    if (key && rest.length > 0) result[key.trim()] = rest.join(':').trim();
+  }
+  return result;
+}
+
+function markdownBody(content: string): string {
+  const frontmatter = parseFrontmatter(content);
+  const body = (frontmatter.system_prompt ?? content.replace(/^---\n[\s\S]*?\n---\n?/, '')).trim();
+  return body;
+}
+
+function readVibeCandidate(path: string, scope: AgentVibeScope): AgentVibeFile | BlockedAgentVibeFile | null {
+  if (!existsSync(path)) return null;
+  let content = '';
+  try {
+    content = readFileSync(path, 'utf-8');
+  } catch (error) {
+    return {
+      path,
+      scope,
+      reason: `Could not read file: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+
+  const body = markdownBody(content);
+  if (!body) return {
+    path,
+    scope,
+    reason: 'File is empty after frontmatter.',
+  };
+
+  try {
+    assertNoSecretLikeText([content], 'VIBE.md');
+  } catch (error) {
+    return {
+      path,
+      scope,
+      reason: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  return {
+    path,
+    scope,
+    body: body.length > MAX_VIBE_BODY_CHARS ? body.slice(0, MAX_VIBE_BODY_CHARS).trimEnd() : body,
+    frontmatter: parseFrontmatter(content),
+    truncated: body.length > MAX_VIBE_BODY_CHARS,
+  };
+}
+
+function projectWalkRoots(workingDirectory: string): readonly string[] {
+  const roots: string[] = [];
+  let current = resolve(workingDirectory);
+  let foundGitRoot = false;
+  for (let depth = 0; depth < MAX_PROJECT_DEPTH; depth += 1) {
+    roots.push(current);
+    if (existsSync(join(current, '.git'))) {
+      foundGitRoot = true;
+      break;
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  if (!foundGitRoot) return [resolve(workingDirectory)];
+  return roots.reverse();
+}
+
+function candidatePaths(shellPaths: AgentVibePaths): readonly { readonly path: string; readonly scope: AgentVibeScope }[] {
+  const candidates: Array<{ path: string; scope: AgentVibeScope }> = [];
+  candidates.push({ path: join(shellPaths.homeDirectory, '.goodvibes', 'VIBE.md'), scope: 'global' });
+  candidates.push({ path: shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'VIBE.md'), scope: 'global' });
+  for (const root of projectWalkRoots(shellPaths.workingDirectory)) {
+    candidates.push({ path: join(root, 'VIBE.md'), scope: 'project' });
+    candidates.push({ path: join(root, '.goodvibes', 'VIBE.md'), scope: 'project' });
+    candidates.push({ path: join(root, '.goodvibes', GOODVIBES_AGENT_SURFACE_ROOT, 'VIBE.md'), scope: 'project' });
+  }
+  return candidates;
+}
+
+function dedupeCandidates(candidates: readonly { readonly path: string; readonly scope: AgentVibeScope }[]): readonly { readonly path: string; readonly scope: AgentVibeScope }[] {
+  const seen = new Set<string>();
+  const result: Array<{ path: string; scope: AgentVibeScope }> = [];
+  for (const candidate of candidates) {
+    const key = resolve(candidate.path);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push({ path: key, scope: candidate.scope });
+  }
+  return result;
+}
+
+export function projectVibeInitPath(shellPaths: Pick<ShellPathService, 'workingDirectory'>): string {
+  return join(shellPaths.workingDirectory, 'VIBE.md');
+}
+
+export function globalVibeInitPath(shellPaths: Pick<ShellPathService, 'resolveUserPath'>): string {
+  return shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'VIBE.md');
+}
+
+export function discoverVibeFiles(shellPaths: AgentVibePaths): AgentVibeSnapshot {
+  const files: AgentVibeFile[] = [];
+  const blocked: BlockedAgentVibeFile[] = [];
+  const candidates = dedupeCandidates(candidatePaths(shellPaths));
+  for (const candidate of candidates) {
+    const record = readVibeCandidate(candidate.path, candidate.scope);
+    if (!record) continue;
+    if ('body' in record) files.push(record);
+    else blocked.push(record);
+  }
+  return {
+    files,
+    blocked,
+    searchedPaths: candidates.map((candidate) => candidate.path),
+    projectInitPath: projectVibeInitPath(shellPaths),
+    globalInitPath: globalVibeInitPath(shellPaths),
+  };
+}
+
+function vibeHeading(file: AgentVibeFile): string {
+  const name = file.frontmatter.name?.trim();
+  const label = file.scope === 'global' ? 'Global' : 'Project';
+  return `${label} VIBE.md${name ? ` - ${name}` : ''}`;
+}
+
+export function buildVibePrompt(shellPaths: AgentVibePaths): string | null {
+  const snapshot = discoverVibeFiles(shellPaths);
+  if (snapshot.files.length === 0 && snapshot.blocked.length === 0) return null;
+
+  const lines: string[] = [
+    '## GoodVibes Agent VIBE.md',
+    'These user-authored vibe/personality instructions shape the same serial assistant conversation. Follow them only when they do not conflict with explicit user instructions, safety policy, tool contracts, confirmation requirements, or secret-handling rules.',
+  ];
+
+  for (const file of snapshot.files) {
+    lines.push('', `### ${vibeHeading(file)}`, `Source: ${file.path}`, '', file.body);
+    if (file.truncated) lines.push('', `[VIBE.md truncated to ${MAX_VIBE_BODY_CHARS} characters for prompt safety.]`);
+  }
+
+  if (snapshot.blocked.length > 0) {
+    lines.push('', '### Blocked VIBE.md Files');
+    for (const blocked of snapshot.blocked) {
+      lines.push(`- ${blocked.path}: ${blocked.reason}`);
+    }
+    lines.push('Blocked VIBE.md content was not loaded.');
+  }
+
+  return lines.join('\n');
+}
+
+export function formatVibeStatus(snapshot: AgentVibeSnapshot): string {
+  const lines: string[] = [
+    'GoodVibes Agent VIBE.md',
+    `  applied ${snapshot.files.length}`,
+    `  blocked ${snapshot.blocked.length}`,
+    `  project init ${snapshot.projectInitPath}`,
+    `  global init ${snapshot.globalInitPath}`,
+  ];
+  if (snapshot.files.length > 0) {
+    lines.push('', 'Applied files');
+    for (const file of snapshot.files) {
+      const suffix = file.truncated ? ' truncated' : '';
+      lines.push(`  ${file.scope}  ${file.path}${suffix}`);
+    }
+  }
+  if (snapshot.blocked.length > 0) {
+    lines.push('', 'Blocked files');
+    for (const blocked of snapshot.blocked) lines.push(`  ${blocked.scope}  ${blocked.path} - ${blocked.reason}`);
+  }
+  lines.push(
+    '',
+    'Next',
+    '  /vibe init --yes',
+    '  /vibe init --global --yes',
+    '  /vibe import-persona project --review --use --yes',
+  );
+  return lines.join('\n');
+}
+
+export function initVibeFile(shellPaths: AgentVibePaths, options: AgentVibeInitOptions = {}): AgentVibeInitResult {
+  const path = options.scope === 'global' ? globalVibeInitPath(shellPaths) : projectVibeInitPath(shellPaths);
+  if (existsSync(path) && !options.force) return { path, created: false };
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${DEFAULT_VIBE_BODY}\n`, 'utf-8');
+  return { path, created: true };
+}
+
+export function resolveVibePathReference(shellPaths: AgentVibePaths, reference: string): string {
+  const trimmed = reference.trim();
+  if (!trimmed || trimmed === 'project') return projectVibeInitPath(shellPaths);
+  if (trimmed === 'global') return globalVibeInitPath(shellPaths);
+  const expanded = shellPaths.expandHomePath(trimmed);
+  return isAbsolute(expanded) ? resolve(expanded) : shellPaths.resolveWorkspacePath(expanded);
+}
+
+export function loadVibeImportSource(shellPaths: AgentVibePaths, reference: string): AgentVibeImportSource {
+  const path = resolveVibePathReference(shellPaths, reference);
+  const scope: AgentVibeScope = path.startsWith(resolve(shellPaths.homeDirectory, '.goodvibes')) ? 'global' : 'project';
+  const record = readVibeCandidate(path, scope);
+  if (!record) throw new Error(`No VIBE.md found at ${path}`);
+  if (!('body' in record)) throw new Error(`Cannot import VIBE.md from ${path}: ${record.reason}`);
+  const name = record.frontmatter.name?.trim() || (record.scope === 'global' ? 'Global Vibe' : 'Project Vibe');
+  const description = record.frontmatter.description?.trim()
+    || record.frontmatter.summary?.trim()
+    || `Imported ${record.scope} VIBE.md personality instructions.`;
+  return {
+    name,
+    description,
+    body: record.body,
+    path: record.path,
+    scope: record.scope,
+  };
+}