supported
Linear imports
Linear workspace exports are treated as a first-class migration source for projects, issues, labels, statuses, users, comments, and attachments.
Formats: Linear, CSV, JSON
Migration guide
Import/export migration guide.
Move planning data into and out of buildr-plannr with dry-run previews, explicit mapping rules, validation errors, rollback evidence, and export retention. The guide covers Linear, CSV, JSON, and future provider assumptions for human and agent-ready work.
Import and export guide summary
Sources
4
Mapping rules
8
Workflow stages
6
Progress steps
6
Recovery states
7
Source assumptions
Linear, CSV, JSON, and future providers all start with preview.
Imports should never mutate workspace data until mapping, validation, entitlement, and recovery evidence are visible.
supported
CSV imports
CSV is the lowest-friction path for issue lists, labels, owners, statuses, priorities, and simple dependency columns.
Formats: CSV
supported
JSON imports and exports
JSON is the canonical loss-minimizing format for buildr-plannr backups, agent task contracts, context references, dependencies, and evidence.
Formats: JSON, backup
planned
Future provider imports
Future connectors follow the same mapping contract: preview first, validate ownership and limits, then commit with audit evidence.
Formats: GitHub, Jira CSV, Markdown, Notion
Mapping rules
Projects, issues, features, labels, statuses, users, comments, and attachments need explicit targets.
| Target | Import rule | Export rule | Validation rule |
|---|---|---|---|
| Projects | Source projects map to buildr-plannr projects by stable ID when present, then normalized name. Missing projects block commit. | Exports include project IDs and names so downstream systems can preserve workspace structure. | Dry runs report missing project IDs, name collisions, and workspace mismatches. |
| Issues | Issues map by stable source ID first, then title within project. Existing issues are updated only when the preview shows changed fields. | Exports include title, description, status, priority, dependencies, agent instructions, acceptance checks, and verification evidence. | Dry runs classify each row as create, update, unchanged, conflict, or error. |
| Features | Feature records map to project milestones, labels, or parent issues until a dedicated feature object is available. | Exports preserve feature-like grouping through project, milestone, label, and dependency fields. | Unmapped feature fields must be reviewed before commit so agent work does not lose product intent. |
| Labels | Labels are normalized by lowercase name within the workspace and merged when they differ only by spacing or case. | Exports include labels as readable names rather than internal-only identifiers. | Dry runs flag conflicting label meanings and unsupported label groups. |
| Statuses | Source statuses map into the target workflow by configured status names, then by category such as backlog, todo, in progress, done, or canceled. | Exports include the current status name and preserve active versus completed meaning. | Unknown statuses block commit until a target status or fallback category is selected. |
| Users | Users map by verified email where available; otherwise they are preserved as external authors until invited. | Exports avoid secrets and include only safe assignee or author references needed for migration. | Dry runs identify unresolved owners and never create active members without workspace admin approval. |
| Comments | Comments keep author display name, created date, body, and source ID when available. Private comments require explicit inclusion. | Exports preserve comment order and redact secrets according to workspace policy. | Dry runs flag oversized comments, unsupported markdown, and comments with blocked attachments. |
| Attachments | Attachments import only from allowed URLs or uploaded archives after size, type, malware, and ownership checks pass. | Exports include attachment metadata and references; binary payload export is handled by plan-gated backup paths. | Dry runs block inaccessible, oversized, suspicious, or cross-workspace attachment references. |
Bulk progress
Large imports expose row counts, blockers, active checkpoints, and final commit progress.
Progress metadata is derived from preview and commit results so users and agents can resume from the same checkpoint without reading raw import files.
Source received
The upload is accepted with filename, byte size, checksum, record count, and idempotency key before parsing starts.
Metric: Source artifact and checksum
Payload parsed
Rows are parsed into stable row numbers and source paths so users can locate malformed JSON, CSV, or Markdown records.
Metric: Parsed rows
Rows validated
Workspace, project, milestone, relationship, duplicate, and schema checks classify rows as complete or blocked.
Metric: Completed and blocked rows
Quota checked
Plan limits are evaluated after validation so bulk imports show whether active issue limits block commit.
Metric: Remaining active issue capacity
Preview finalized
The preview is marked ready, blocked, or expired and carries the active checkpoint for customer support.
Metric: Preview status and active step
Commit applied
A committed import updates history with created, updated, skipped, percent complete, and final progress metadata.
Metric: Created, updated, and skipped rows
Migration workflow
Dry runs, errors, rollback, and retention are part of the product contract.
Source inventory
Confirm source system, export format, record counts, owner mapping, attachment scope, and plan limits before upload.
Evidence: Source export checksum, Expected project and issue counts, Owner mapping decision
Dry run preview
Run preview first. The preview shows creates, updates, unchanged rows, conflicts, validation errors, quota impact, and recovery metadata.
Evidence: Preview ID, Idempotency key, Create/update/conflict counts
Validation errors
Resolve row and path errors before commit. Missing workspaces, projects, milestones, unsupported statuses, malformed JSON, and relationship mismatches block commit.
Evidence: Row number, Path-like error, Customer-facing fix instruction
Commit
Commit only an unexpired, unblocked preview. Commit operations are idempotent and report created, updated, skipped, and failed rows.
Evidence: Commit ID, Operation summary, Audit event
Rollback and recovery
Use preview output, source checksums, export snapshots, and audit events to recover from bad mappings without deleting unrelated workspace data.
Evidence: Pre-commit export, Affected issue IDs, Recovery owner
Export retention
Exports are plan-gated artifacts with schema ID, schema version, compatible import versions, filename, size, hash, filters, created date, and retention expectations.
Evidence: Export ID, SHA-256 hash, Retention window
Failure recovery
Failed or paused imports route to a clear next action.
Ready to commit
Commit with an explicit commit idempotency key.
Owner: Workspace admin
Fix source
Correct row-level source errors and rerun preview.
Owner: Migration owner
Resolve conflicts
Resolve duplicate IDs, duplicate titles, or workspace mismatches.
Owner: Migration owner
Reduce scope
Reduce rows, archive existing work, or upgrade before retry.
Owner: Workspace admin
Rerun preview
Create a fresh dry run because the preview is missing or expired.
Owner: Migration owner
Inspect commit
Compare target records with preview output before retrying commit.
Owner: Support
Resolved
Retain commit evidence and complete post-import verification.
Owner: Migration owner
Need help?
Support uses metadata, checksums, row errors, and affected IDs, not raw exports or private issue content.
Keep source checksums, preview IDs, commit IDs, export IDs, and redacted examples available before requesting migration support.