Migration Importer

The importer brings an existing Spec-Kit or OpenSpec project into the unified .forge/ layout — non-destructively, and with the generated noise stripped out.

Command

forge import <specify|openspec> [--from <path>] [--cwd <dir>] \
  [--dry-run] [--force] [--include-generated]

• specify imports a Spec-Kit project (.specify).
• openspec imports an OpenSpec project (openspec).

Non-destructive by design

• The source is never modified.
• .forge/ is snapshotted (backup) before any write — reversible via forge restore.
• An existing target file is skipped and reported unless you pass --force.
• --dry-run prints the full plan and writes zero bytes.

Preview before you commit

Always run with --dry-run first. It shows exactly what would be written, skipped, and dropped — without touching disk.

Mapping — specify

Source	Target
memory/**	memory/**
specs/<feature>/	changes/<feature>/
branding/	design/
infra/	specs/infra/
anything unmapped	_imported/

Regenerable site/ and scripts/ are skipped by default (a note is printed) unless you pass --include-generated.

Mapping — openspec

A near 1:1 rename — config.yaml, specs/**, and changes/** (including changes/archive/**) map straight into .forge/.

Examples

Preview first:

$ forge import specify --from ../legacy-app --dry-run
Plan: import Spec-Kit project (dry-run, 0 bytes written)
  memory/**                 → memory/**
  specs/checkout/           → changes/checkout/
  branding/                 → design/
  infra/                    → specs/infra/
  site/, scripts/           skipped (generated; use --include-generated)
  239 source files → 23 files of spec content

Then the real import:

$ forge import specify --from ../legacy-app
Snapshot saved (restore with: forge restore)
Imported 23 files into .forge/

Generated noise is dropped by default

On a real Spec-Kit example, the default import took 239 files down to 23 files of actual spec content — the regenerable site/ and scripts/ were skipped. Pass --include-generated only if you truly need them.

Next steps

• Forge vs GitHub Spec Kit — what changes, and what does not, when you migrate.
• Forge vs OpenSpec — why this import is close to a rename.
• Project structure — the .forge/ layout the importer maps into.
• The forge CLI — the full forge import synopsis and its sibling commands.
• Spec-Viewer Dashboard — browse the imported specs and changes offline.
• Methodology — how specs and changes drive the SDD workflow.