@specmarket/cli 0.0.5 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specmarket/cli",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "type": "module",
   "description": "SpecMarket CLI - discover, validate, execute, and publish AI specs",
   "bin": {

package/src/commands/init.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { readFile, rm, access } from 'fs/promises';
+import { readFile, rm, access, writeFile, mkdir } from 'fs/promises';
 import { join } from 'path';
 import { tmpdir } from 'os';
 import { randomUUID } from 'crypto';
@@ -29,6 +29,7 @@ vi.mock('inquirer', () => ({
 const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
 
 import { handleInit } from './init.js';
+import { SIDECAR_FILENAME } from '@specmarket/shared';
 
 describe('handleInit', () => {
   let tmpDir: string;
@@ -43,17 +44,21 @@ describe('handleInit', () => {
   });
 
   it('creates spec directory with all required files', async () => {
-    mockPrompt.mockResolvedValue({
-      name: 'test-spec',
-      displayName: 'Test Spec',
-      replacesSaas: '',
-      outputType: 'web-app',
-      primaryStack: 'nextjs-typescript',
-    });
+    // Path provided + empty dir: first prompt "Create from scratch?", then full spec answers
+    mockPrompt
+      .mockResolvedValueOnce({ createNew: true })
+      .mockResolvedValueOnce({
+        name: 'test-spec',
+        displayName: 'Test Spec',
+        replacesSaas: '',
+        outputType: 'web-app',
+        primaryStack: 'nextjs-typescript',
+      });
 
     await handleInit({ path: tmpDir });
 
-    // Verify all required files were created
+    // Verify all required files were created (specmarket.yaml is required for validate/publish)
+    await expect(access(join(tmpDir, SIDECAR_FILENAME))).resolves.toBeUndefined();
     await expect(access(join(tmpDir, 'spec.yaml'))).resolves.toBeUndefined();
     await expect(access(join(tmpDir, 'PROMPT.md'))).resolves.toBeUndefined();
     await expect(access(join(tmpDir, 'SPEC.md'))).resolves.toBeUndefined();
@@ -67,13 +72,15 @@ describe('handleInit', () => {
   });
 
   it('writes correct spec.yaml content based on prompts', async () => {
-    mockPrompt.mockResolvedValue({
-      name: 'my-project',
-      displayName: 'My Project',
-      replacesSaas: 'Notion',
-      outputType: 'web-app',
-      primaryStack: 'nextjs-typescript',
-    });
+    mockPrompt
+      .mockResolvedValueOnce({ createNew: true })
+      .mockResolvedValueOnce({
+        name: 'my-project',
+        displayName: 'My Project',
+        replacesSaas: 'Notion',
+        outputType: 'web-app',
+        primaryStack: 'nextjs-typescript',
+      });
 
     await handleInit({ path: tmpDir });
 
@@ -86,13 +93,15 @@ describe('handleInit', () => {
   });
 
   it('shows next-steps instructions after creation', async () => {
-    mockPrompt.mockResolvedValue({
-      name: 'test-spec',
-      displayName: 'Test Spec',
-      replacesSaas: '',
-      outputType: 'cli-tool',
-      primaryStack: 'go',
-    });
+    mockPrompt
+      .mockResolvedValueOnce({ createNew: true })
+      .mockResolvedValueOnce({
+        name: 'test-spec',
+        displayName: 'Test Spec',
+        replacesSaas: '',
+        outputType: 'cli-tool',
+        primaryStack: 'go',
+      });
 
     await handleInit({ path: tmpDir });
 
@@ -103,4 +112,134 @@ describe('handleInit', () => {
       expect.stringContaining('specmarket validate')
     );
   });
+
+  it('adds only specmarket.yaml when -p points at existing Spec Kit dir (no overwrites)', async () => {
+    await mkdir(tmpDir, { recursive: true });
+    await writeFile(join(tmpDir, 'spec.md'), '# My Spec Kit spec\nDo not overwrite.');
+    await writeFile(join(tmpDir, 'tasks.md'), '# Tasks');
+
+    mockPrompt.mockResolvedValue({
+      displayName: 'Spec Kit Spec',
+      description: 'A spec kit spec for the marketplace.',
+      replacesSaas: '',
+      outputType: 'web-app',
+      primaryStack: 'nextjs-typescript',
+    });
+
+    await handleInit({ path: tmpDir });
+
+    await expect(access(join(tmpDir, SIDECAR_FILENAME))).resolves.toBeUndefined();
+    const sidecar = await readFile(join(tmpDir, SIDECAR_FILENAME), 'utf-8');
+    expect(sidecar).toContain('spec_format: speckit');
+    expect(sidecar).toContain('display_name: "Spec Kit Spec"');
+    const specMd = await readFile(join(tmpDir, 'spec.md'), 'utf-8');
+    expect(specMd).toBe('# My Spec Kit spec\nDo not overwrite.');
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Added specmarket.yaml'));
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('specmarket validate'));
+  });
+
+  it('exits without overwriting when specmarket.yaml already exists in -p dir', async () => {
+    await mkdir(tmpDir, { recursive: true });
+    await writeFile(
+      join(tmpDir, SIDECAR_FILENAME),
+      'spec_format: speckit\ndisplay_name: X\ndescription: Already have a sidecar here.\noutput_type: web-app\nprimary_stack: nextjs-typescript\n'
+    );
+
+    await handleInit({ path: tmpDir });
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      expect.stringContaining('already exists')
+    );
+    const sidecar = await readFile(join(tmpDir, SIDECAR_FILENAME), 'utf-8');
+    expect(sidecar).toContain('Already have a sidecar here.');
+  });
+
+  // --from flag tests (import-only mode)
+
+  it('--from: adds specmarket.yaml sidecar to existing Spec Kit dir', async () => {
+    await mkdir(tmpDir, { recursive: true });
+    await writeFile(join(tmpDir, 'spec.md'), '# My Spec Kit spec');
+    await writeFile(join(tmpDir, 'tasks.md'), '# Tasks');
+
+    mockPrompt.mockResolvedValue({
+      displayName: 'Imported Spec',
+      description: 'An imported spec kit spec for testing.',
+      replacesSaas: '',
+      outputType: 'web-app',
+      primaryStack: 'nextjs-typescript',
+    });
+
+    await handleInit({ from: tmpDir });
+
+    await expect(access(join(tmpDir, SIDECAR_FILENAME))).resolves.toBeUndefined();
+    const sidecar = await readFile(join(tmpDir, SIDECAR_FILENAME), 'utf-8');
+    expect(sidecar).toContain('spec_format: speckit');
+    expect(sidecar).toContain('display_name: "Imported Spec"');
+    // Original files must not be modified
+    const specMd = await readFile(join(tmpDir, 'spec.md'), 'utf-8');
+    expect(specMd).toBe('# My Spec Kit spec');
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Added specmarket.yaml'));
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('specmarket validate'));
+  });
+
+  it('--from: adds specmarket.yaml sidecar to BMAD dir', async () => {
+    await mkdir(tmpDir, { recursive: true });
+    await writeFile(join(tmpDir, 'prd.md'), '# PRD');
+    await writeFile(join(tmpDir, 'architecture.md'), '# Architecture');
+
+    mockPrompt.mockResolvedValue({
+      displayName: 'BMAD App',
+      description: 'A bmad formatted spec for the marketplace.',
+      replacesSaas: 'Jira',
+      outputType: 'web-app',
+      primaryStack: 'nextjs-typescript',
+    });
+
+    await handleInit({ from: tmpDir });
+
+    const sidecar = await readFile(join(tmpDir, SIDECAR_FILENAME), 'utf-8');
+    expect(sidecar).toContain('spec_format: bmad');
+    expect(sidecar).toContain('display_name: "BMAD App"');
+  });
+
+  it('--from: errors when directory does not exist', async () => {
+    const nonExistentDir = join(tmpDir, 'does-not-exist');
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((_code?: number | string | null) => { throw new Error('process.exit called'); });
+
+    await expect(handleInit({ from: nonExistentDir })).rejects.toThrow('process.exit called');
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('Directory not found'));
+    exitSpy.mockRestore();
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('--from: errors when directory is empty', async () => {
+    await mkdir(tmpDir, { recursive: true });
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((_code?: number | string | null) => { throw new Error('process.exit called'); });
+
+    await expect(handleInit({ from: tmpDir })).rejects.toThrow('process.exit called');
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('Directory is empty'));
+    exitSpy.mockRestore();
+    consoleErrorSpy.mockRestore();
+  });
+
+  it('--from: warns and exits without overwriting when specmarket.yaml already exists', async () => {
+    await mkdir(tmpDir, { recursive: true });
+    await writeFile(join(tmpDir, 'spec.md'), '# Spec');
+    await writeFile(
+      join(tmpDir, SIDECAR_FILENAME),
+      'spec_format: speckit\ndisplay_name: Existing\ndescription: Already have sidecar.\noutput_type: web-app\nprimary_stack: nextjs-typescript\n'
+    );
+
+    await handleInit({ from: tmpDir });
+
+    expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('already exists'));
+    const sidecar = await readFile(join(tmpDir, SIDECAR_FILENAME), 'utf-8');
+    expect(sidecar).toContain('Already have sidecar.');
+    // mockPrompt should NOT have been called (no prompts for metadata)
+    expect(mockPrompt).not.toHaveBeenCalled();
+  });
 });

package/src/commands/init.ts

@@ -1,13 +1,54 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import ora from 'ora';
-import { mkdir, writeFile } from 'fs/promises';
-import { join, resolve } from 'path';
-import { EXIT_CODES } from '@specmarket/shared';
+import { mkdir, writeFile, readdir } from 'fs/promises';
+import { join, resolve, basename } from 'path';
+import { EXIT_CODES, SIDECAR_FILENAME } from '@specmarket/shared';
 import createDebug from 'debug';
+import { detectSpecFormat, fileExists, directoryExists } from '../lib/format-detection.js';
 
 const debug = createDebug('specmarket:cli');
 
+type MetadataData = {
+  displayName: string;
+  description: string;
+  replacesSaas?: string;
+  outputType: string;
+  primaryStack: string;
+};
+
+/** Build specmarket.yaml for any spec format (single source of truth for validate/publish) */
+function buildSpecmarketYaml(data: MetadataData & { specFormat: string }): string {
+  return `# SpecMarket metadata (required for validate/publish)
+# Single source of truth for format and marketplace fields.
+# Your existing spec files (Spec Kit, BMAD, Ralph, etc.) are not modified.
+
+spec_format: ${data.specFormat}
+display_name: "${data.displayName.replace(/"/g, '\\"')}"
+description: "${data.description.replace(/"/g, '\\"')}"
+output_type: ${data.outputType}
+primary_stack: ${data.primaryStack}
+${data.replacesSaas ? `replaces_saas: "${data.replacesSaas.replace(/"/g, '\\"')}"` : '# replaces_saas: "ProductName"'}
+# replaces_pricing: "$0-16/mo"
+tags: []
+estimated_tokens: 50000
+estimated_cost_usd: 2.50
+estimated_time_minutes: 30
+`;
+}
+
+/** specmarket.yaml for new SpecMarket (classic) specs */
+const SPECMARKET_YAML_TEMPLATE = (data: {
+  displayName: string;
+  replacesSaas?: string;
+  outputType: string;
+  primaryStack: string;
+}) => buildSpecmarketYaml({
+  ...data,
+  specFormat: 'specmarket',
+  description: `A ${data.outputType} spec${data.replacesSaas ? ` that replaces ${data.replacesSaas}` : ''}.`,
+});
+
 const SPEC_YAML_TEMPLATE = (data: {
   name: string;
   displayName: string;
@@ -162,12 +203,274 @@ const TASKS_MD_TEMPLATE = (displayName: string) => `# Tasks
 ## Discovered Issues
 `;
 
+/** Prompt for marketplace metadata only (used when adding sidecar to existing spec) */
+async function promptMetadataOnly(defaultDisplayName?: string): Promise<MetadataData> {
+  const { default: inquirer } = await import('inquirer');
+  const answers = await inquirer.prompt<{
+    displayName: string;
+    description: string;
+    replacesSaas: string;
+    outputType: string;
+    primaryStack: string;
+  }>([
+    {
+      type: 'input',
+      name: 'displayName',
+      message: 'Display name for the marketplace:',
+      default: defaultDisplayName ?? 'My Spec',
+    },
+    {
+      type: 'input',
+      name: 'description',
+      message: 'Short description (min 10 characters):',
+      default: 'A spec ready to validate and publish on SpecMarket.',
+      validate: (v: string) => (v.length >= 10 ? true : 'Description must be at least 10 characters'),
+    },
+    {
+      type: 'input',
+      name: 'replacesSaas',
+      message: 'What SaaS product does this replace? (optional, Enter to skip):',
+      default: '',
+    },
+    {
+      type: 'list',
+      name: 'outputType',
+      message: 'Output type:',
+      choices: [
+        { name: 'Web Application', value: 'web-app' },
+        { name: 'CLI Tool', value: 'cli-tool' },
+        { name: 'API Service', value: 'api-service' },
+        { name: 'Library/Package', value: 'library' },
+        { name: 'Mobile App', value: 'mobile-app' },
+      ],
+    },
+    {
+      type: 'list',
+      name: 'primaryStack',
+      message: 'Primary stack:',
+      choices: [
+        { name: 'Next.js + TypeScript', value: 'nextjs-typescript' },
+        { name: 'Astro + TypeScript', value: 'astro-typescript' },
+        { name: 'Python + FastAPI', value: 'python-fastapi' },
+        { name: 'Go', value: 'go' },
+        { name: 'Rust', value: 'rust' },
+        { name: 'Other', value: 'other' },
+      ],
+    },
+  ]);
+  return {
+    displayName: answers.displayName,
+    description: answers.description,
+    replacesSaas: answers.replacesSaas || undefined,
+    outputType: answers.outputType,
+    primaryStack: answers.primaryStack,
+  };
+}
+
+/** Returns true if directory exists and has at least one file (not just subdirs). */
+async function dirHasFiles(dir: string): Promise<boolean> {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries.some((e) => e.isFile());
+  } catch {
+    return false;
+  }
+}
+
 export async function handleInit(opts: {
   name?: string;
   path?: string;
+  from?: string;
 }): Promise<void> {
   const { default: inquirer } = await import('inquirer');
 
+  // --from: strict import-only mode. Errors if directory doesn't exist or has no spec files.
+  if (opts.from !== undefined && opts.from !== '') {
+    const targetDir = resolve(opts.from);
+
+    const dirExists = await directoryExists(targetDir);
+    if (!dirExists) {
+      console.error(chalk.red(`Directory not found: ${targetDir}`));
+      console.error(chalk.gray('--from requires an existing spec directory. Run specmarket init (no flags) to create a new spec from scratch.'));
+      process.exit(EXIT_CODES.INVALID_SPEC);
+    }
+
+    const hasAnyFiles = await dirHasFiles(targetDir);
+    if (!hasAnyFiles) {
+      console.error(chalk.red(`Directory is empty: ${targetDir}`));
+      console.error(chalk.gray('--from requires a directory with spec files (Spec Kit, BMAD, Ralph, or custom markdown). Run specmarket init to create a new spec.'));
+      process.exit(EXIT_CODES.INVALID_SPEC);
+    }
+
+    const sidecarPath = join(targetDir, SIDECAR_FILENAME);
+    if (await fileExists(sidecarPath)) {
+      console.log(chalk.yellow(`${SIDECAR_FILENAME} already exists in this directory.`));
+      console.log(chalk.gray('Run specmarket validate to check your spec, then specmarket publish to publish.'));
+      return;
+    }
+
+    const detection = await detectSpecFormat(targetDir);
+    const formatLabel =
+      detection.format === 'specmarket'
+        ? 'SpecMarket (spec.yaml + PROMPT.md + …)'
+        : detection.format === 'speckit'
+          ? 'Spec Kit'
+          : detection.format === 'bmad'
+            ? 'BMAD'
+            : detection.format === 'ralph'
+              ? 'Ralph'
+              : 'custom markdown';
+    console.log(chalk.gray(`Detected ${formatLabel} spec. Adding SpecMarket metadata only; your files will not be modified.`));
+    console.log('');
+
+    const metadata = await promptMetadataOnly(basename(targetDir));
+    const yaml = buildSpecmarketYaml({ ...metadata, specFormat: detection.format });
+    await writeFile(sidecarPath, yaml);
+
+    console.log('');
+    console.log(chalk.green(`Added ${SIDECAR_FILENAME} to ${targetDir}`));
+    console.log('');
+    console.log(chalk.bold('Next steps:'));
+    console.log(`  1. Run ${chalk.cyan('specmarket validate')} to check your spec`);
+    console.log(`  2. Run ${chalk.cyan('specmarket publish')} to publish to the marketplace`);
+    console.log(`  3. Run ${chalk.cyan('specmarket run')} to execute the spec locally`);
+    return;
+  }
+
+  // When -p/--path is set, we're initializing in an existing directory (safe add-sidecar flow)
+  if (opts.path !== undefined && opts.path !== '') {
+    const targetDir = resolve(opts.path);
+    await mkdir(targetDir, { recursive: true });
+
+    const sidecarPath = join(targetDir, SIDECAR_FILENAME);
+    if (await fileExists(sidecarPath)) {
+      console.log(chalk.yellow(`${SIDECAR_FILENAME} already exists in this directory.`));
+      console.log(chalk.gray('Run specmarket validate to check your spec, then specmarket publish to publish.'));
+      return;
+    }
+
+    const detection = await detectSpecFormat(targetDir);
+    const hasAnyFiles = await dirHasFiles(targetDir);
+
+    if (hasAnyFiles && detection.format !== 'custom') {
+      // Recognized format (specmarket, speckit, bmad, ralph): add sidecar only, no overwrites
+      const formatLabel =
+        detection.format === 'specmarket'
+          ? 'SpecMarket (spec.yaml + PROMPT.md + …)'
+          : detection.format === 'speckit'
+            ? 'Spec Kit'
+            : detection.format === 'bmad'
+              ? 'BMAD'
+              : detection.format === 'ralph'
+                ? 'Ralph'
+                : detection.format;
+      console.log(chalk.gray(`Detected ${formatLabel} spec. Adding SpecMarket metadata only; your files will not be modified.`));
+      console.log('');
+
+      const metadata = await promptMetadataOnly(basename(targetDir));
+      const yaml = buildSpecmarketYaml({
+        ...metadata,
+        specFormat: detection.format,
+      });
+      await writeFile(sidecarPath, yaml);
+
+      console.log('');
+      console.log(chalk.green(`Added ${SIDECAR_FILENAME} to ${targetDir}`));
+      console.log('');
+      console.log(chalk.bold('Next steps:'));
+      console.log(`  1. Run ${chalk.cyan('specmarket validate')} to check your spec`);
+      console.log(`  2. Run ${chalk.cyan('specmarket publish')} to publish to the marketplace`);
+      console.log(`  3. Run ${chalk.cyan('specmarket run')} to execute the spec locally`);
+      return;
+    }
+
+    if (hasAnyFiles && detection.format === 'custom') {
+      // Custom (e.g. random .md): still add sidecar so they can validate/publish
+      console.log(chalk.gray('Detected markdown spec. Adding SpecMarket metadata only; your files will not be modified.'));
+      console.log('');
+      const metadata = await promptMetadataOnly(basename(targetDir));
+      const yaml = buildSpecmarketYaml({
+        ...metadata,
+        specFormat: 'custom',
+      });
+      await writeFile(sidecarPath, yaml);
+      console.log('');
+      console.log(chalk.green(`Added ${SIDECAR_FILENAME} to ${targetDir}`));
+      console.log('');
+      console.log(chalk.bold('Next steps:'));
+      console.log(`  1. Run ${chalk.cyan('specmarket validate')} to check your spec`);
+      console.log(`  2. Run ${chalk.cyan('specmarket publish')} to publish to the marketplace`);
+      return;
+    }
+
+    // Empty directory: offer to create from scratch
+    console.log(chalk.gray('Directory is empty or has no recognized spec format.'));
+    const { createNew } = await inquirer.prompt<{ createNew: boolean }>([
+      {
+        type: 'confirm',
+        name: 'createNew',
+        message: 'Create a new SpecMarket spec from scratch here?',
+        default: true,
+      },
+    ]);
+    if (!createNew) {
+      console.log(chalk.gray('Exiting. Add spec files (e.g. Spec Kit, BMAD) and run specmarket init -p . again.'));
+      return;
+    }
+    const spinner = ora(`Creating spec at ${targetDir}...`).start();
+    const fullAnswers = await inquirer.prompt<{
+      name: string;
+      displayName: string;
+      replacesSaas: string;
+      outputType: string;
+      primaryStack: string;
+    }>([
+      { type: 'input', name: 'name', message: 'Spec name (lowercase, hyphens only):', default: opts.name ?? (basename(targetDir) || 'my-spec'), validate: (v: string) => /^[a-z0-9-]+$/.test(v) || 'Must be lowercase alphanumeric with hyphens' },
+      { type: 'input', name: 'displayName', message: 'Display name:', default: (a: { name: string }) => a.name.split('-').map((w) => w[0]?.toUpperCase() + w.slice(1)).join(' ') },
+      { type: 'input', name: 'replacesSaas', message: 'What SaaS product does this replace? (optional):', default: '' },
+      { type: 'list', name: 'outputType', message: 'Output type:', choices: [
+        { name: 'Web Application', value: 'web-app' },
+        { name: 'CLI Tool', value: 'cli-tool' },
+        { name: 'API Service', value: 'api-service' },
+        { name: 'Library/Package', value: 'library' },
+        { name: 'Mobile App', value: 'mobile-app' },
+      ]},
+      { type: 'list', name: 'primaryStack', message: 'Primary stack:', choices: [
+        { name: 'Next.js + TypeScript', value: 'nextjs-typescript' },
+        { name: 'Astro + TypeScript', value: 'astro-typescript' },
+        { name: 'Python + FastAPI', value: 'python-fastapi' },
+        { name: 'Go', value: 'go' },
+        { name: 'Rust', value: 'rust' },
+        { name: 'Other', value: 'other' },
+      ]},
+    ]);
+    const data = {
+      name: fullAnswers.name,
+      displayName: fullAnswers.displayName,
+      replacesSaas: fullAnswers.replacesSaas || undefined,
+      outputType: fullAnswers.outputType,
+      primaryStack: fullAnswers.primaryStack,
+    };
+    await mkdir(join(targetDir, 'stdlib'), { recursive: true });
+    await Promise.all([
+      writeFile(sidecarPath, SPECMARKET_YAML_TEMPLATE(data)),
+      writeFile(join(targetDir, 'spec.yaml'), SPEC_YAML_TEMPLATE(data)),
+      writeFile(join(targetDir, 'PROMPT.md'), PROMPT_MD_TEMPLATE(data)),
+      writeFile(join(targetDir, 'SPEC.md'), SPEC_MD_TEMPLATE(data)),
+      writeFile(join(targetDir, 'SUCCESS_CRITERIA.md'), SUCCESS_CRITERIA_TEMPLATE),
+      writeFile(join(targetDir, 'stdlib', 'STACK.md'), STACK_MD_TEMPLATE(fullAnswers.primaryStack)),
+      writeFile(join(targetDir, 'TASKS.md'), TASKS_MD_TEMPLATE(fullAnswers.displayName)),
+    ]);
+    spinner.succeed(chalk.green(`Spec created at ${targetDir}`));
+    console.log('');
+    console.log(chalk.bold('Next steps:'));
+    console.log(`  1. Edit ${chalk.cyan('SPEC.md')} with your application requirements`);
+    console.log(`  2. Edit ${chalk.cyan('SUCCESS_CRITERIA.md')} with pass/fail criteria`);
+    console.log(`  3. Run ${chalk.cyan('specmarket validate')} then ${chalk.cyan('specmarket run')}`);
+    return;
+  }
+
+  // No path: create new directory (or add sidecar if that directory already exists with content)
   const answers = await inquirer.prompt<{
     name: string;
     displayName: string;
@@ -187,11 +490,8 @@ export async function handleInit(opts: {
       type: 'input',
       name: 'displayName',
       message: 'Display name:',
-      default: (answers: { name: string }) =>
-        answers.name
-          .split('-')
-          .map((w) => w[0]?.toUpperCase() + w.slice(1))
-          .join(' '),
+      default: (ans: { name: string }) =>
+        ans.name.split('-').map((w) => w[0]?.toUpperCase() + w.slice(1)).join(' '),
     },
     {
       type: 'input',
@@ -226,14 +526,44 @@ export async function handleInit(opts: {
     },
   ]);
 
-  const targetDir = resolve(opts.path ?? answers.name);
+  const targetDir = resolve(answers.name);
   const spinner = ora(`Creating spec directory at ${targetDir}...`).start();
 
   try {
-    // Create directory structure
     await mkdir(targetDir, { recursive: true });
-    await mkdir(join(targetDir, 'stdlib'), { recursive: true });
 
+    const sidecarPath = join(targetDir, SIDECAR_FILENAME);
+    if (await fileExists(sidecarPath)) {
+      spinner.stop();
+      console.log(chalk.yellow(`${SIDECAR_FILENAME} already exists in ${targetDir}.`));
+      console.log(chalk.gray('Run specmarket validate to check your spec, then specmarket publish to publish.'));
+      return;
+    }
+
+    const hasFiles = await dirHasFiles(targetDir);
+    if (hasFiles) {
+      const detection = await detectSpecFormat(targetDir);
+      spinner.stop();
+      console.log(chalk.gray(`Directory already has files (detected: ${detection.format}). Adding ${SIDECAR_FILENAME} only; no files overwritten.`));
+      const metadata: MetadataData = {
+        displayName: answers.displayName,
+        description: `A ${answers.outputType} spec${answers.replacesSaas ? ` that replaces ${answers.replacesSaas}` : ''}.`,
+        replacesSaas: answers.replacesSaas || undefined,
+        outputType: answers.outputType,
+        primaryStack: answers.primaryStack,
+      };
+      const yaml = buildSpecmarketYaml({ ...metadata, specFormat: detection.format });
+      await writeFile(sidecarPath, yaml);
+      console.log('');
+      console.log(chalk.green(`Added ${SIDECAR_FILENAME} to ${targetDir}`));
+      console.log('');
+      console.log(chalk.bold('Next steps:'));
+      console.log(`  1. Run ${chalk.cyan('specmarket validate')} to check your spec`);
+      console.log(`  2. Run ${chalk.cyan('specmarket publish')} to publish to the marketplace`);
+      return;
+    }
+
+    await mkdir(join(targetDir, 'stdlib'), { recursive: true });
     const data = {
       name: answers.name,
       displayName: answers.displayName,
@@ -242,8 +572,8 @@ export async function handleInit(opts: {
       primaryStack: answers.primaryStack,
     };
 
-    // Write all template files
     await Promise.all([
+      writeFile(sidecarPath, SPECMARKET_YAML_TEMPLATE(data)),
       writeFile(join(targetDir, 'spec.yaml'), SPEC_YAML_TEMPLATE(data)),
       writeFile(join(targetDir, 'PROMPT.md'), PROMPT_MD_TEMPLATE(data)),
       writeFile(join(targetDir, 'SPEC.md'), SPEC_MD_TEMPLATE(data)),
@@ -253,14 +583,13 @@ export async function handleInit(opts: {
     ]);
 
     spinner.succeed(chalk.green(`Spec created at ${targetDir}`));
-
     console.log('');
     console.log(chalk.bold('Next steps:'));
     console.log(`  1. ${chalk.cyan(`cd ${answers.name}`)}`);
     console.log(`  2. Edit ${chalk.cyan('SPEC.md')} with your application requirements`);
     console.log(`  3. Edit ${chalk.cyan('SUCCESS_CRITERIA.md')} with specific pass/fail criteria`);
-    console.log(`  4. Run ${chalk.cyan(`specmarket validate`)} to check your spec`);
-    console.log(`  5. Run ${chalk.cyan(`specmarket run`)} to execute the spec`);
+    console.log(`  4. Run ${chalk.cyan('specmarket validate')} to check your spec`);
+    console.log(`  5. Run ${chalk.cyan('specmarket run')} to execute the spec`);
   } catch (err) {
     spinner.fail(chalk.red(`Failed to create spec: ${(err as Error).message}`));
     throw err;
@@ -269,9 +598,12 @@ export async function handleInit(opts: {
 
 export function createInitCommand(): Command {
   return new Command('init')
-    .description('Create a new spec directory with template files')
+    .description(
+      'Create a new SpecMarket spec or add specmarket.yaml to an existing spec (Spec Kit, BMAD, Ralph). Use -p . to init in current directory without overwriting existing files.'
+    )
     .option('-n, --name <name>', 'Spec name (skip prompt)')
-    .option('-p, --path <path>', 'Target directory path (defaults to spec name)')
+    .option('-p, --path <path>', 'Target directory (e.g. . or ./my-spec). When set, detects existing format and adds only specmarket.yaml if present; no files overwritten.')
+    .option('--from <path>', 'Import an existing spec directory (Spec Kit, BMAD, Ralph, or custom markdown). Detects format and adds specmarket.yaml metadata sidecar without modifying original files. Errors if the directory is missing or empty.')
     .action(async (opts) => {
       try {
         await handleInit(opts);