# 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

```sh
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**.

::: warning 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:

```sh
$ 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:

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

::: info 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](/compare/spec-kit) — what changes, and what does not, when you migrate.
- [Forge vs OpenSpec](/compare/openspec) — why this import is close to a rename.
- [Project structure](/guide/project-structure) — the `.forge/` layout the importer maps into.
- [The forge CLI](/reference/cli) — the full `forge import` synopsis and its sibling commands.
- [Spec-Viewer Dashboard](/features/dashboard) — browse the imported specs and changes offline.
- [Methodology](/concepts/methodology) — how specs and changes drive the SDD workflow.