External plan and PRD import with conflict detection (/gsd-import)

[davesienkowski]

Pre-submission checklist

• I have searched existing issues and discussions -- this has not been proposed and declined before
• I have read CONTRIBUTING.md and understand that I must wait for approved-feature before writing any code
• I have read the existing GSD commands and workflows and confirmed this feature does not duplicate existing behavior
• This feature solves a problem for solo developers using AI coding tools, not a personal preference or workflow I happen to like

Feature name

External plan and PRD import with conflict detection (/gsd-import)

Type of addition

New command (slash command or CLI flag)

The solo developer problem

A solo developer may have an existing plan document, specification, or PRD from a stakeholder, a competitor analysis, or a previous project that they want to bring into GSD's planning system. Currently there is no way to ingest external planning artifacts while checking for conflicts against existing project decisions. The developer must manually reformat the document and hope it does not contradict decisions already recorded in PROJECT.md.

What this feature adds

A new /gsd-import command with two modes:

Mode 1: --from <filepath> (plan import)

1. Reads an external plan file
2. Detects conflicts against existing project decisions in PROJECT.md and REQUIREMENTS.md
3. Converts to GSD PLAN.md format
4. Validates via gsd-plan-checker agent before writing

Mode 2: --prd <filepath> (PRD import)

1. Reads a Product Requirements Document
2. Extracts and generates PROJECT.md and REQUIREMENTS.md
3. Delegates ROADMAP.md generation to gsd-planner agent
4. Validates consistency across generated artifacts

Both modes surface conflicts before writing anything, giving the developer a chance to resolve contradictions.

Example usage:

/gsd-import --from path/to/external-plan.md
> Detected 2 conflicts with existing project decisions:
>   1. External plan specifies PostgreSQL; PROJECT.md decided on MongoDB (decision #3)
>   2. External plan includes WebSocket support; marked Out of Scope in REQUIREMENTS.md
> Resolve conflicts before importing? [y/N]

/gsd-import --prd path/to/product-spec.md
> Extracted: 12 requirements, 3 milestones, 8 user stories
> Generating PROJECT.md, REQUIREMENTS.md, ROADMAP.md...

Full scope of changes

Files created:

• commands/gsd/import.md -- slash command definition with --from and --prd flags
• get-shit-done/workflows/import.md -- import workflow with conflict detection, format conversion, agent delegation

Files modified:

• None required. The command and workflow are self-contained.

User stories

1. As a solo developer who received a plan from a stakeholder, I want to run /gsd-import --from plan.md and have GSD detect conflicts with my existing project decisions before I adopt the plan.
2. As a solo developer starting a new project from an existing PRD, I want to run /gsd-import --prd spec.md to bootstrap PROJECT.md, REQUIREMENTS.md, and ROADMAP.md from the document rather than re-entering everything manually.

Acceptance criteria

• /gsd-import --from <path> reads the file, detects conflicts against PROJECT.md decisions, and converts to GSD PLAN.md format
• /gsd-import --prd <path> extracts requirements and generates PROJECT.md + REQUIREMENTS.md + ROADMAP.md
• Conflicts are surfaced to the developer before any files are written
• Plan import validates via gsd-plan-checker before committing
• PRD import delegates ROADMAP.md generation to gsd-planner
• The command exits with an error if the file path does not exist
• Running with no arguments displays usage help
• The command is discoverable via /gsd-help

Which area does this primarily affect?

Planning system (phases, roadmap, state)

Applicable runtimes

• Claude Code
• All runtimes (runtime-agnostic)

Breaking changes assessment

None. This is an entirely new command. No existing behavior is modified.

Maintenance burden

Medium. The conflict detection logic must stay in sync with how PROJECT.md records decisions. The PLAN.md format conversion needs updating if the plan format changes. The PRD extraction is heuristic and may need tuning for different PRD formats.

Alternatives considered

1. Manual copy and reformat -- Error-prone and misses conflicts with existing decisions. The developer must know the GSD format and remember all recorded decisions.
2. plan-phase --prd flag on existing command -- Mixes import with planning. A standalone import command is cleaner and allows the developer to review imported artifacts before planning.

Prior art and references

Replaces #1720 (which described this more generically). Split from #1686 per maintainer feedback.

[trek-e]

✅ Approved as feature — with caveats to address in the PR.

The concept is solid and the conflict detection approach is the right design. Two caveats that must be addressed during implementation:

1. PRD extraction needs a concrete strategy.
The --prd mode says "extracts and generates PROJECT.md and REQUIREMENTS.md" from an arbitrary PRD, but PRDs vary wildly in format and structure. The PR must define:

• What input formats are expected (markdown? plain text? structured sections?)
• What happens when extraction fails or produces incomplete results (graceful degradation, not silent partial output)
• Whether the extraction is best-effort with user confirmation or requires a specific input structure

2. The two modes have different complexity — implement --from first.
--from (conflict detection + format conversion) is straightforward. --prd (full project bootstrap from a spec) is substantially more complex. If the PR becomes unwieldy, consider shipping --from first and --prd as a follow-up. The command structure supports this naturally — --prd can land in a second PR without changing the command definition.

Implementation notes:

• Conflict detection against PROJECT.md decisions is the highest-value piece — get this right
• Always surface conflicts before writing, never auto-resolve
• validatePath() from security.cjs for the file path argument
• Consider what happens when PROJECT.md or REQUIREMENTS.md don't exist yet (--from with a fresh project)

@davesienkowski — labeled approved-feature. You're clear to implement. Address the caveats above in the PR.