Karvey Import

Karvey Import — convert Kiro / gstack specs into Karvey

Purpose

Bring pre-existing specifications from Kiro (cc-sdd) or gstack into the Karvey docs/spec/ structure, so they can continue through the Karvey pipeline. This is a cross-cutting support skill (cross-cutting layer): it does NOT advance spec.json:phase of any change — it materializes the imported documents and leaves the change at the phase its content supports.

It is idempotent and non-destructive: it never deletes the source (.kiro/, gstack docs); it only creates/updates files under docs/spec/. Generated artifacts follow the project's language (per spec.json language).

Mode selection

• --from kiro → import from a Kiro .kiro/ directory.
• --from gstack → import from gstack artifacts (design docs, specs, plans).
• If --from is omitted, detect: if a .kiro/ directory exists → kiro; otherwise ask the user which source to use.

Step 1 — Ensure project config

Read docs/spec/project.json (see karvey/rules/project-config.md). If it does not exist, create it (or run /karvey-init's project-config step): ask/infer git_platform, cloud, iac_tool, knowledge_sync, targets, repos (min 1), spec_repo, branch_flow. For Kiro, pre-fill targets/stack from .kiro/steering/tech.md if present.

Step 2A — Import from Kiro (--from kiro)

Kiro layout (source):

.kiro/
├── steering/{product.md, tech.md, structure.md, ...}   ← project-level context
└── specs/{feature-name}/
    ├── spec.json            ← kiro metadata + approvals
    ├── requirements.md      ← EARS requirements
    ├── design.md            ← technical design
    └── tasks.md             ← implementation tasks

For each .kiro/specs/{feature-name}/:

1. change-id: use {feature-name} (or --change-id). Make it URL-safe; prefix with add|fix|update if it improves clarity. Avoid collisions in docs/spec/changes/.

2. Create docs/spec/changes/{change-id}/.

3. Map files into Karvey:

   Kiro source	→ Karvey target	Notes
   requirements.md (EARS)	requirements.md	Compatible. Add a Traces to PRD: line per requirement (point to the PRD section once the PRD exists).
   design.md	architecture.md	Map onto Karvey's architecture template. Sections Karvey requires but Kiro lacks (Cloud Infrastructure, edge cases, trust boundaries, test-coverage plan, diagrams) are added as > TODO (karvey-architecture): ... placeholders, NOT invented.
   tasks.md	tasks.md	Keep tasks; re-label to E{n}.F{n}.T{n} [layer] if feasible, otherwise keep and note.
   steering/product.md	feeds prd.md	Problem, goals, users.
   steering/tech.md	feeds project.json (stack/targets) + architecture context

4. Generate prd.md (Kiro has no formal PRD): synthesize from steering/product.md + the intent of requirements.md into Karvey's PRD structure (executive summary, problem & context, goals & success metrics, user stories, scope/out-of-scope, stakeholders, constraints, acceptance criteria). Mark inferred parts as > inferred from Kiro — review.

5. Generate spec.json: change_id, capability (infer or ask), goal (from product/requirements; ask if unclear), language, management, security_tier (ask; default per project), phase and approvals set to the furthest phase the imported content supports (e.g. if requirements+design+tasks exist → phase: "tasks", with requirements/architecture/tasks marked generated; approvals left approved:false so the user re-validates each gate). Map Kiro approvals where present.

6. spec-delta.md / living specs: create a spec-delta.md stub for karvey-archive to merge later.

7. Report per feature: what mapped cleanly vs. what needs review (the TODO placeholders).

Step 2B — Import from gstack (--from gstack)

gstack does not persist a fixed on-disk spec layout, so this mode is heuristic and confirmation-driven.

1. Discover candidate artifacts (ask the user to confirm/point if ambiguous):

   • Design docs / "10-star" or office-hours outputs, CEO/eng review plans.
   • /spec outputs (executable specs, backlog-ready).
   • Plan files (e.g. PLAN.md, docs/plan*, *.spec.md, design notes).

2. Map onto Karvey:

   gstack artifact	→ Karvey target
   office-hours / CEO review / 10-star doc	prd.md (vision + problem + goals)
   /spec executable spec	requirements.md (convert to EARS; mark non-EARS items)
   eng-review plan / architecture notes	architecture.md (+ TODO placeholders for missing Karvey sections)
   task/backlog list	tasks.md
   design-system notes	design-spec.md

3. Generate prd.md, spec.json and (if missing) project.json as in the Kiro flow. Set phase/approvals to the furthest phase the mapped content supports; leave approvals approved:false for re-validation.

4. Because mapping is heuristic, always present the proposed file map to the user for confirmation before writing.

Step 3 — Knowledge sync

After writing, run the sync step per karvey/rules/knowledge-sync.md (Obsidian if available; otherwise /graphify docs/spec/ --update).

Step 4 — Output

Report, per imported change:

✅ Imported {change-id} from {kiro|gstack}
   Created: prd.md, requirements.md, architecture.md, tasks.md, spec.json
   Resume phase: {phase}  (all gates require re-approval)
   ⚠️ Needs review: {list of TODO placeholders / non-EARS items}

Next step: /karvey {change-id}   → see status and continue the pipeline

Safety

• Never delete or modify the source (.kiro/, gstack docs) — read-only on the origin.
• Do not invent content Karvey requires but the source lacks — use clearly marked > TODO placeholders so the user fills them via the proper phase.
• All gates are imported as not approved, so the user re-validates requirements/architecture/etc. through Karvey.
• Generated artifacts follow the project's language (spec.json language), never forced to English.

Part of the Karvey™ Method — © HainTech, by Mauricio Quezada Ibáñez · Apache 2.0 · see karvey/LICENSE and karvey/TRADEMARK.md.