Cursor rule

1---
2description: "Detect GSD, spec-kit, or BMAD spec artifacts and transform them into bigpowers YAML layout (state.yaml, release-plan.yaml, epics/, requirements/, plans/, ADRs). Use when migrating foreign spec docs."
3alwaysApply: false
4---
5 
6# story: e25s01
7# story: e25s02
8# story: e25s03
9# story: e25s04
10# story: e25s05
11# story: e25s06
12 
13# Migrate Spec
14 
15Transform existing GSD, spec-kit, or BMAD planning artifacts into the bigpowers `specs/` model. No code is written — the output is a set of bigpowers-format spec files the user can use immediately.
16 
17## Quick start
18 
191. Run this skill from the root of the project being migrated (not the bigpowers repo itself).
202. The skill auto-detects the source framework and presents its findings before transforming anything.
213. All output goes to `specs/` at the project root.
22 
23---
24 
25## Red flags — stop and ask
26 
27Before proceeding, check for these rationalization traps:
28 
29- **Partial artifact set** — only one fingerprint file found (e.g. just `spec.md` with no `plan.md`). Don't assume it's a complete project. Ask: "I found only X — is this the full set of your spec artifacts?"
30- **Wrong trigger** — user said "migrate my code" or "migrate the database", not "migrate my specs". Confirm before running.
31- **Stale source** — source artifacts have commit dates older than 6 months with no recent activity. Flag: "These specs appear inactive since <date>. Are they still the source of truth?"
32- **Active divergence** — source `state.yaml` or `sprint-status.yaml` shows in-progress work. Flag: "There is active work in flight. Migrating now may lose in-progress context. Proceed?"
33 
34If any red flag fires: surface it, wait for explicit user confirmation before continuing.
35 
36---
37 
38## Process
39 
40### Step 1 — Detect the source framework
41 
42Scan for the fingerprints below. Stop at first match; if multiple match, list them and ask the user which is primary.
43 
44| Framework | Fingerprints (any one is sufficient) |
45|-----------|--------------------------------------|
46| **GSD** | `.planning/` directory; `.planning/ROADMAP.md`; `.planning/REQUIREMENTS.md` with `REQ-` IDs |
47| **spec-kit** | `.specify/` directory; `spec.md` + `plan.md` at root; `.github/skills/speckit-*/SKILL.md` |
48| **BMAD** | `_bmad/` directory; `_bmad-output/` directory; `prd.md` with `FR-` IDs; `epic-*.md` or `story-*.md` |
49 
50If none found: ask the user which framework before proceeding.
51 
52→ verify: `test -d specs && test -f specs/state.yaml`
53 
54### Step 2 — Inventory the source artifacts
55 
56List every artifact found matching the detected framework. Present the list to the user:
57 
58See [REFERENCE.md](REFERENCE.md) — `Detected: GSD...`
59 
60→ verify: `test -d specs && test -w specs`
61 
62### Step 3 — Transform (one artifact at a time, show diffs)
63 
64Apply the mapping from [REFERENCE.md](./REFERENCE.md) and [REFERENCE-GSD.md](./REFERENCE-GSD.md). For each target file:
65 
661. Show what will be created or appended (title + first 20 lines).
672. Ask: "Create this? [yes / edit / skip]"
683. On yes: write to `specs/`.
69 
70#### ID Tracking (REQ-XX, FR-XX, UJ-XX)
71 
72When source artifacts contain IDs (REQ-XX, FR-XX, UJ-XX), emit them as **first-class YAML fields** in `in_scope` entries, not YAML comments:
73 
74See [REFERENCE.md](REFERENCE.md) — `# CORRECT — first-class id: field...`
75 
76**When source has no IDs:** Prompt the user: "No IDs found. Assign auto-generated IDs? [yes / no]". If yes, emit `REQ-{NNN}` with `# auto-generated` annotation.
77 
78**When source has MIXED IDs:** Items with IDs get `id:` fields; items without IDs receive auto-generated `REQ-NNN` entries. Document which were auto-generated in a comment block at the top of `in_scope`.
79 
80See [REFERENCE.md — in_scope format with ID tracking](./REFERENCE.md#in_scope-format-with-id-tracking) for examples.
81 
82#### Traceability Output (FR-XX, UJ-XX)
83 
84When source has FR-XX or UJ-XX IDs, emit `specs/product/REQUIREMENTS_TRACE.yaml` for end-to-end requirement traceability:
85 
86See [REFERENCE.md](REFERENCE.md) — `trace:...`
87 
88**Existing trace file:** If `REQUIREMENTS_TRACE.yaml` already exists, prompt: "REQUIREMENTS_TRACE.yaml exists. [overwrite / merge / skip]"
89 
90**No FR-XX/UJ-XX found:** Skip trace file; add note to state.yaml handoff: "No FR-XX/UJ-XX IDs found — traceability file skipped".
91 
92See [REFERENCE.md — REQUIREMENTS_TRACE.yaml format](./REFERENCE.md#requirements_traceyaml-format) for the complete schema.
93 
94> **HARD GATE** — Never overwrite an existing `specs/` file without explicit user confirmation. Merge into it if it exists; don't clobber.
95>
96> → verify: `git rev-parse --git-dir >/dev/null 2>&1 && test -d specs`
97 
98→ verify: `test -d specs && [ "$(ls specs/*.md specs/*.yaml 2>/dev/null | wc -l | tr -d " ")" -gt 0 ]`
99 
100### Step 4 — Generate state.yaml
101 
102Always regenerate `specs/state.yaml` from scratch in bigpowers YAML format (see REFERENCE.md for template). The **handoff block is mandatory** and must include all four fields:
103 
104See [REFERENCE.md](REFERENCE.md) — `active_flow: null...`
105 
106If no open decisions were found during migration, the `open_decisions` list may be empty with an explanatory comment:
107 
108See [REFERENCE.md](REFERENCE.md) — `handoff:...`
109 
110→ verify: `grep -q handoff: specs/state.yaml`
111 
112---
113 
114# migrate-spec Reference — GSD
115 
116Full artifact transformation rules for migrating GSD projects to bigpowers YAML layout.
117 
118See [REFERENCE.md](./REFERENCE.md) for spec-kit, BMAD, learnings, and ADR/DECISION-LOG formats.
119 
120---
121 
122## Artifact Locations
123 
124GSD stores everything under `.planning/` at the project root.
125 
126```
127.planning/
128├── ROADMAP.md
129├── STATE.md
130├── REQUIREMENTS.md
131├── METHODOLOGY.md
132├── HANDOFF.json
133├── .continue-here.md
134└── phases/
135    └── XX-name/
136        ├── XX-CONTEXT.md
137        ├── XX-YY-PLAN.md
138        ├── XX-YY-SUMMARY.md
139        └── XX-DISCUSSION-LOG.md
140    spikes/
141        └── SPIKE-NNN/README.md
142```
143 
144---
145 
146## Transformation Rules
147 
148### `.planning/ROADMAP.md` → `specs/release-plan.yaml` + `specs/epics/eNN-*.yaml`
149 
150GSD ROADMAP has: milestone name, phases, success criteria per phase, plan count.
151 
152Transform:
153- Each GSD phase → one epic entry in `release-plan.yaml` (`id`, `title`, `wsjf`, `file`)
154- Phase detail → matching `specs/epics/eNN-slug.yaml` (stories, tasks, `verify`)
155- Completed phases → `done` in `execution-status.yaml`; active → `in_progress`
156 
157---
158 
159### `.planning/REQUIREMENTS.md` → `specs/product/SCOPE_LATEST.yaml`
160 
161GSD REQUIREMENTS has: REQ-XX IDs, Validated/Active/Out-of-Scope categories, traceability.
162 
163Transform:
164- Preserve REQ-XX IDs as **first-class `id:` fields** in `in_scope` entries (see [REFERENCE.md — ID tracking format](./REFERENCE.md#in_scope-format-with-id-tracking))
165- Validated requirements → `in_scope` entries with `id:`, `description:`, `source:` fields
166- Out-of-Scope → `out_of_scope` entries (preserve IDs if present)
167- Active (in-progress) → `in_scope` with status note
168 
169---
170 
171### `.planning/phases/XX-name/XX-CONTEXT.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/adr/`
172 
173GSD CONTEXT.md has 6 sections: domain, decisions, canonical_refs, code_context, specifics, deferred.
174 
175Transform:
176- `domain` → `plans/TECH_STACK_LATEST.md` Domain section
177- `decisions` → scan each: if hard-to-reverse + surprising → `specs/adr/NNNN-{slug}.md`; if lightweight → `specs/DECISION-LOG_LATEST.md`
178- `canonical_refs` → Reference links in TECH_STACK
179- `code_context` → Architecture section
180- `deferred` → `SCOPE_LATEST.yaml` `out_of_scope` (with "(deferred from GSD)" note)
181 
182---
183 
184### `.planning/phases/XX-name/XX-YY-PLAN.md` → `specs/epics/eNN-*.yaml` tasks
185 
186GSD PLAN has: frontmatter (depends-on, verify), objective, typed tasks, success criteria, output spec.
187 
188Transform:
189- Preserve task structure as `tasks[]` in epic shard
190- Keep `verify: <command>` lines
191- Map GSD `depends-on` to task `depends-on` notes
192- SUMMARY.md (execution record) → skip or append to `specs/archive/`
193 
194---
195 
196### `.planning/METHODOLOGY.md` → `specs/tech-architecture/METHODOLOGY_LATEST.md`
197 
198GSD METHODOLOGY.md is a standing reference for analytical lenses (Bayesian updating, STRIDE, cost-of-delay).
199 
200Transform:
201- Copy each lens as a section in `specs/tech-architecture/METHODOLOGY_LATEST.md`
202- Note: "These lenses should inform `plan-work` and `audit-code` sessions."
203 
204---
205 
206### `.planning/HANDOFF.json` + `.continue-here.md` → `specs/state.yaml` `handoff`
207 
208GSD HANDOFF has: current phase, last plan, blocking reason, required reading list.
209 
210Transform — populate `handoff` in `state.yaml`:
211 
212```yaml
213handoff:
214  last_step_completed: "<phase/plan from HANDOFF>"
215  open_decisions:
216    - "<blocking reason if any>"
217  required_reading:
218    - "<required_reading list>"
219  next_skill: survey-context
220```
221 
222---
223 
224### `.planning/spikes/SPIKE-NNN/README.md` → `specs/archive/spikes/SPIKE-{name}.md`
225 
226GSD spike README has: YAML frontmatter (verdict, validates, related), methodology, findings, recommendation.
227 
228Transform:
229- Flatten directory into `specs/archive/spikes/SPIKE-{name}.md`
230- Preserve frontmatter as YAML block at top
231- Keep verdict prominently: `**Verdict:** ADOPTED / REJECTED / DEFERRED`
232 
233---
234 
235## Skip List
236 
237These GSD artifacts are not migrated — they are execution records, not planning inputs:
238 
239| Artifact | Reason |
240|----------|--------|
241| `.planning/phases/XX/XX-YY-SUMMARY.md` | Execution log; no bigpowers equivalent |
242| `.planning/phases/XX/XX-DISCUSSION-LOG.md` | Audit trail only; not consumed by agents |
243| `.planning/USER-PROFILE.md` | User calibration; bigpowers has no profile system |
244| `.planning/sketches/` | Visual exploration; not spec artifacts |
245 
246---
247 
248# Migrate Spec — Reference
249 
250## Navigation
251 
252| Lines | Section |
253|-------|---------|
254| 1 | Title |
255| 3–68 | Navigation |
256| 69–70 | spec-kit → bigpowers Mapping |
257| 71–84 | Artifact Locations |
258| 85–94 | `spec.md` → `specs/product/SCOPE_LATEST.yaml` + `specs/tech-architecture/TECH_STACK_LATEST.md` |
259| 95–105 | `plan.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/release-plan.yaml` + `specs/epics/` |
260| 106–114 | `tasks.md` → `specs/epics/` (via slice-tasks) |
261| 115–120 | `.specify/` state |
262| 121–122 | BMAD → bigpowers Mapping |
263| 123–141 | Artifact Locations |
264| 142–148 | `product-brief.md` / `prfaq-{project}.md` → `specs/product/VISION_LATEST.yaml` |
265| 149–160 | `prd.md` → `specs/product/SCOPE_LATEST.yaml` + `GLOSSARY_LATEST.yaml` |
266| 161–167 | `addendum.md` + `decision-log.md` → `specs/adr/` + `specs/DECISION-LOG_LATEST.md` |
267| 168–174 | `architecture.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/adr/` |
268| 175–178 | `epic-*.md` → `specs/release-plan.yaml` + `specs/epics/eNN-*.yaml` |
269| 179–182 | `story-*.md` → `specs/epics/` stories |
270| 183–188 | `project-context.md` → `CLAUDE.md` |
271| 189–192 | Learnings to Adopt |
272| 193–198 | From GSD |
273| 199–204 | From spec-kit |
274| 205–212 | From BMAD |
275| 213–214 | Output Formats |
276| 215–224 | ADR format (bigpowers) |
277| 225–227 | Context |
278| 228–230 | Decision |
279| 231–234 | Consequences |
280| 235–246 | DECISION-LOG.md format |
281| 247–257 | MIGRATION-AUDIT.md format |
282| 258–264 | Summary |
283| 265–274 | High Priority Findings |
284| 275–278 | Information |
285| 279–285 | Next Steps |
286| 286–306 | in_scope format with ID tracking |
287| 307–341 | REQUIREMENTS_TRACE.yaml format |
288| 342–397 | `specs/state.yaml` template format |
289| 398–416 | Reference block 1 |
290| 417–432 | Reference block 2 |
291| 433–451 | Reference block 3 |
292| 452–474 | Reference block 4 |
293| 475–482 | Reference block 5 |
294| 483–484 | Findings |
295| 485–489 | High Priority |
296| 490–495 | Information |
297| 496–509 | Reference block 6 |
298| 510–542 | Step 7 — Post-migration: Optional two-pass spec writing gate |
299| 543–574 | Step 8 — Post-migration: Optional methodology doc template |
300| 575–600 | Artifact Mapping Summary |
301| 601–610 | Rules |
302| 611–621 | Step 5 — Surface learnings (optional) |
303| 622–644 | Step 6 — Adversarial review (optional) |
304| 645–646 | Findings |
305| 647–651 | High Priority |
306| 652–660 | Information |
307 
308# migrate-spec Reference — spec-kit, BMAD, Learnings
309 
310Transformation rules for spec-kit and BMAD projects, plus learnings to adopt and output formats.
311 
312See [REFERENCE-GSD.md](./REFERENCE-GSD.md) for full GSD → bigpowers YAML mapping.
313 
314---
315 
316## spec-kit → bigpowers Mapping
317 
318### Artifact Locations
319 
320```
321project-root/
322├── spec.md         ← user journeys, success criteria, scope
323├── plan.md         ← technology, architecture, constraints
324├── tasks.md        ← atomic task list
325└── .specify/
326    ├── workflow-catalogs.yml
327    └── workflows/runs/<id>/
328        ├── state.json
329        └── log.jsonl
330```
331 
332### `spec.md` → `specs/product/SCOPE_LATEST.yaml` + `specs/tech-architecture/TECH_STACK_LATEST.md`
333 
334spec-kit `spec.md` focuses on: who uses it, user journeys, success criteria, what's in/out of scope.
335 
336Transform:
337- User journeys → `SCOPE_LATEST.yaml` success criteria / `in_scope` entries
338- In/out of scope → `in_scope` / `out_of_scope` sections
339- Domain terms / glossary → `requirements/GLOSSARY_LATEST.yaml`
340- Problem statement / vision → `requirements/VISION_LATEST.yaml`
341 
342### `plan.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/release-plan.yaml` + `specs/epics/`
343 
344spec-kit `plan.md` covers: technology stack, architectural patterns, implementation constraints.
345 
346Transform:
347- Technology decisions → `plans/TECH_STACK_LATEST.md` Technology section
348- Architecture patterns → Architecture section
349- Hard decisions with trade-offs → `specs/adr/NNNN-{slug}.md`
350- Phased approach / milestones → `release-plan.yaml` epic entries
351- Implementation steps → `epics/eNN-*.yaml` task list with `verify:`
352 
353### `tasks.md` → `specs/epics/` (via slice-tasks)
354 
355spec-kit tasks are atomic, verifiable in isolation — same principle as bigpowers `verify:` mandate.
356 
357Transform:
358- Copy tasks into epic shard `tasks[]`; preserve task numbers
359- Add `verify:` line if spec-kit task has an acceptance criterion
360- Group into epics matching `release-plan.yaml` entries
361 
362### `.specify/` state
363 
364Discard — workflow engine state; not meaningful in the bigpowers skill model.
365 
366---
367 
368## BMAD → bigpowers Mapping
369 
370### Artifact Locations
371 
372```
373project-root/
374├── _bmad/bmm/config.yaml
375├── _bmad-output/
376│   ├── product-brief.md
377│   ├── prfaq-{project}.md
378│   ├── prd.md
379│   ├── addendum.md
380│   ├── decision-log.md
381│   ├── ux-spec.md
382│   └── architecture.md
383├── project-context.md
384└── docs/
385    ├── epic-{slug}.md
386    └── story-{slug}.md
387```
388 
389### `product-brief.md` / `prfaq-{project}.md` → `specs/product/VISION_LATEST.yaml`
390 
391Transform:
392- Vision + core value → `VISION_LATEST.yaml` north_star / success_criteria
393- Target users → notes in VISION or SCOPE
394- prfaq customer FAQ → can inform success criteria in SCOPE
395 
396### `prd.md` → `specs/product/SCOPE_LATEST.yaml` + `GLOSSARY_LATEST.yaml`
397 
398BMAD `prd.md` has: Glossary, FR-XX functional requirements, UJ-XX user journeys, NFRs, assumptions.
399 
400Transform:
401- Glossary → `GLOSSARY_LATEST.yaml`
402- FR-XX items → `in_scope` with IDs preserved
403- UJ-XX user journeys → success criteria
404- NFRs → `constraints` section
405- `[ASSUMPTION: ...]` inline tags → collected in scope YAML
406- Out-of-scope features → `out_of_scope`
407 
408### `addendum.md` + `decision-log.md` → `specs/adr/` + `specs/DECISION-LOG_LATEST.md`
409 
410Transform:
411- Hard, irreversible, surprising decisions → individual `specs/adr/NNNN-{slug}.md`
412- Lightweight decisions → `specs/DECISION-LOG_LATEST.md` (date | decision | rationale)
413- `addendum.md` change signals → note in `SCOPE_LATEST.yaml` metadata
414 
415### `architecture.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/adr/`
416 
417Transform:
418- ADR sections → individual `specs/adr/NNNN-{slug}.md` files
419- System overview / data models → TECH_STACK Architecture section
420- API contracts → keep at `docs/api.md` or similar; link from TECH_STACK
421 
422### `epic-*.md` → `specs/release-plan.yaml` + `specs/epics/eNN-*.yaml`
423 
424Each epic → one release-plan entry + one epic shard. Acceptance criteria → story tasks with `verify:`.
425 
426### `story-*.md` → `specs/epics/` stories
427 
428Each story → one story entry in epic shard. Acceptance criteria → `verify:` lines.
429 
430### `project-context.md` → `CLAUDE.md`
431 
432Add a "## Project Context" section to `CLAUDE.md`. Copy tech stack, coding rules, preferences verbatim.
433 
434---
435 
436## Learnings to Adopt
437 
438Optional enhancements to offer the user after migration. Present as checkboxes.
439 
440### From GSD
441 
442- [x] **`specs/tech-architecture/METHODOLOGY_LATEST.md`** — Standing analytical lenses. Agents read before planning. (adopted: optional Step 8 template scaffold)
443- [x] **`handoff` block in state.yaml** — Last skill, last step, required reading for next session. (adopted: mandatory in Step 4 output)
444- [x] **ID tracking in SCOPE_LATEST.yaml** — FR/UJ IDs for spec → plan → verification traceability. (adopted in Step 3 transform)
445 
446### From spec-kit
447 
448- [x] **Two-pass spec writing** — User-journey pass first, then technical-decisions pass. (adopted: optional post-migration gate)
449- [ ] **Explicit inter-phase gate** — "Approve to proceed?" at end of `elaborate-spec`.
450- [ ] **Epic task isolation** — Each task completable in isolation; `depends-on` explicit in epic YAML.
451 
452### From BMAD
453 
454- [x] **FR-XX + UJ-XX in SCOPE_LATEST.yaml** — Rigorous traceability. (adopted: REQUIREMENTS_TRACE.yaml emitted on migration)
455- [ ] **`specs/DECISION-LOG_LATEST.md`** — Lightweight decisions below ADR threshold.
456- [x] **Adversarial review pass** — Critique epic shard before `develop-tdd`. (adopted: optional Step 6 in migration)
457 
458---
459 
460## Output Formats
461 
462### ADR format (bigpowers)
463 
464Use `model-domain/ADR-FORMAT.md`. Only create when all three apply: hard to reverse, surprising without context, result of a real trade-off.
465 
466```markdown
467# ADR-NNNN: {Title}
468 
469**Status:** Accepted
470**Date:** YYYY-MM-DD
471 
472## Context
473[What situation forced this decision?]
474 
475## Decision
476[What was decided?]
477 
478## Consequences
479[What becomes easier or harder?]
480```
481 
482### DECISION-LOG.md format
483 
484For lightweight decisions that don't warrant a full ADR:
485 
486```markdown
487# Decision Log
488 
489| Date | Decision | Rationale | Alternatives |
490|------|----------|-----------|--------------|
491| 2026-05-19 | Use Postgres | Existing ops expertise | SQLite (limited), DynamoDB (no local dev) |
492```
493 
494### MIGRATION-AUDIT.md format
495 
496Post-migration adversarial review report. Written to `specs/archive/MIGRATION-AUDIT.md` when Step 6 runs:
497 
498```markdown
499# Migration Audit — <project-name>
500 
501**Source Framework:** <GSD|spec-kit|BMAD>  
502**Date:** <ISO 8601>  
503**Status:** <Pass|Findings|Critical>
504 
505## Summary
506 
507- TODO markers: N
508- FIXME markers: N
509- MISSING markers: N
510- Epics without verify: N
511 
512## High Priority Findings
513 
514- **Artifact:** specs/epics/e02-auth-ui/epic.yaml
515  **Issue:** Story e02s01 has no verify: commands in tasks
516  **Recommendation:** Add runnable verify command before develop-tdd
517 
518- **Artifact:** specs/state.yaml
519  **Issue:** open_decisions list empty without comment explanation
520  **Recommendation:** Add # comment if all decisions were resolved during migration
521 
522## Information
523 
524- Artifact specs/epics/e01-auth/epic.yaml contains TODO: "Define Neon Auth client URL injection" (normal for fresh migration)
525 
526## Next Steps
527 
5281. Address high-priority findings before plan-work
5292. Run bash scripts/audit-compliance.sh to enforce code quality gates
5303. Begin develop-tdd on highest-WSJF epic
531```
532 
533### in_scope format with ID tracking
534 
535Source IDs (REQ-XX, FR-XX, UJ-XX) are emitted as first-class YAML fields:
536 
537```yaml
538in_scope:
539  - id: REQ-001
540    description: "User can register with email and password"
541    source: "REQUIREMENTS.md"
542  - id: FR-015
543    description: "Auth service must support OAuth2 token flow"
544    source: "prd.md"
545  - id: REQ-AUTO-002  # auto-generated when source had no ID
546    description: "Dashboard displays user profile"
547    # auto-generated: true  (optional comment for tracking)
548```
549 
550**When source has no IDs:** If the user opts in, auto-generated IDs follow the `REQ-{NNN}` format with an optional `# auto-generated` comment.
551 
552**When source has mixed IDs:** Entries with source IDs get `id:` fields; entries without IDs receive auto-generated IDs. A comment block at the top of `in_scope` documents which IDs were auto-generated.
553 
554### REQUIREMENTS_TRACE.yaml format
555 
556Emitted when source has FR-XX (functional requirement) or UJ-XX (user journey) IDs. Maps source requirements to bigpowers epic/story structure and verification commands:
557 
558```yaml
559trace:
560  # Functional Requirements
561  - id: FR-001
562    type: functional_requirement
563    description: "User can register with email/password"
564    source_artifact: "prd.md"
565    epic: "e02-auth-ui"
566    story: "e02s01"
567    verify: "grep -q 'FR-001' specs/product/SCOPE_LATEST.yaml && echo OK"
568 
569  # User Journeys
570  - id: UJ-001
571    type: user_journey
572    description: "New user completes registration flow"
573    source_artifact: "epic-auth-ui.md"
574    epic: "e02-auth-ui"
575    story: "e02s01"
576    verify: "grep -q 'UJ-001' specs/epics/e02-auth-ui/epic.yaml && echo OK"
577
578metadata:
579  source_framework: "BMAD"
580  migrated_at: "2026-06-26T12:00:00Z"
581  total_requirements: 2
582  coverage: "All FR-XX and UJ-XX IDs from source mapped"
583```
584 
585**When source has no FR-XX/UJ-XX:** Skip REQUIREMENTS_TRACE.yaml. Add note to `state.yaml` handoff: "No FR-XX/UJ-XX IDs found — traceability file skipped".
586 
587**Existing trace file:** If REQUIREMENTS_TRACE.yaml exists, prompt user: "Overwrite? [yes / merge / skip]". Merge appends new entries; skip leaves existing file intact.
588 
589### `specs/state.yaml` template format
590 
591Generated during Step 4 of migration. Regenerate from scratch in bigpowers YAML format. The **handoff block is mandatory**:
592 
593```yaml
594active_flow: null
595active_epic_id: null
596active_story_id: null
597completed_epic: false
598
599epic_cycle:
600  current_step: null
601  next_skill: null
602  story_bcps: null
603  completed_steps: []
604  audit_result: null
605
606bug_cycle:
607  current_step: null
608  completed_steps: []
609
610release:
611  target_version: null
612  last_tag: null
613  last_publish: null
614  ci_verified: false
615
616metrics:
617  story_start: null
618  story_end: null
619  cycle_minutes: null
620  bcp_per_hour: null
621
622git:
623  branch: <current branch>
624  hash: <git rev-parse HEAD>
625  pushed: false
626
627handoff:
628  last_step_completed: "Migrated from <framework> on <date>"
629  open_decisions: []  # Empty if all decisions resolved during migration
630  required_reading:
631    - specs/product/VISION_LATEST.yaml
632    - specs/product/SCOPE_LATEST.yaml
633    - specs/tech-architecture/TECH_STACK_LATEST.md
634    - specs/release-plan.yaml
635  next_skill: survey-context
636
637two_pass_spec:  # Optional: only if user activates two-pass spec writing gate
638  journey_pass: pending
639  technical_pass: pending
640  approved_at: null
641```
642 
643---
644 
645## Reference block 1
646 
647```
648Detected: GSD
649Found:
650  ✓ .planning/ROADMAP.md
651  ✓ .planning/REQUIREMENTS.md  (12 REQ-XX items)
652  ✓ .planning/state.yaml
653  ✓ .planning/phases/01-auth/01-CONTEXT.md
654  ✗ .planning/METHODOLOGY.md  (not present)
655 
656Skipping:
657  .planning/phases/01-auth/01-01-SUMMARY.md  (execution record; archived only)
658 
659Proceed with migration? [yes / skip <artifact> / abort]
660```
661 
662---
663 
664## Reference block 2
665 
666```yaml
667# CORRECT — first-class id: field
668in_scope:
669  - id: REQ-001
670    description: "User can register with email/password"
671    source: "REQUIREMENTS.md"
672 
673# DEPRECATED — comment-only
674in_scope:
675  - "User can register with email/password"  # REQ-001
676```
677 
678---
679 
680## Reference block 3
681 
682```yaml
683trace:
684  - id: FR-001
685    type: functional_requirement
686    description: "User can register with email/password"
687    epic: e02-auth-ui
688    story: e02s01
689    verify: "grep -q 'FR-001' specs/product/SCOPE_LATEST.yaml && echo OK"
690  - id: UJ-001
691    type: user_journey
692    description: "New user completes registration flow"
693    epic: e02-auth-ui
694    story: e02s01
695```
696 
697---
698 
699## Reference block 4
700 
701```yaml
702active_flow: null
703active_epic_id: null
704active_story_id: null
705 
706# ... other state fields ...
707
708handoff:
709  last_step_completed: "Migrated from <framework> on <date>"
710  open_decisions:
711    - "decision text here"
712  required_reading:
713    - specs/product/VISION_LATEST.yaml
714    - specs/product/SCOPE_LATEST.yaml
715    - specs/tech-architecture/TECH_STACK_LATEST.md
716    - specs/release-plan.yaml
717  next_skill: survey-context
718```
719 
720---
721 
722## Reference block 5
723 
724```markdown
725# Migration Audit — <project-name> from <framework>
726 
727**Date:** <ISO 8601 timestamp>
728**Status:** Pass / Fail with findings
729 
730## Findings
731 
732### High Priority
733- Artifact: specs/epics/e02-auth-ui/epic.yaml
734  Finding: No verify: commands in story tasks
735  Recommendation: Add `verify:` to each task before develop-tdd
736 
737### Information
738- Count of TODO markers: 3 (normal for fresh migration)
739```
740 
741---
742 
743## Reference block 6
744 
745```
746Which lenses to include in specs/tech-architecture/METHODOLOGY_LATEST.md?
747 
748[x] Cost of Delay (CD3)           — Priority & trade-off assessment
749[ ] STRIDE                        — Security threat modeling
750[ ] F.I.R.S.T                     — Test quality principles
751[ ] Bayesian Updating            — Probabilistic decision-making
752[ ] OWASP Top 10                 — Web security framework
753```
754 
755---
756 
757### Step 7 — Post-migration: Optional two-pass spec writing gate
758 
759After Steps 1–6, offer the user an optional two-pass spec writing workflow (spec-kit learning):
760 
761Prompt: "Use two-pass spec writing (user journeys first, then technical)? [yes / no]"
762 
763If **yes**, initialize the gate in `specs/state.yaml`:
764 
765```yaml
766two_pass_spec:
767  journey_pass: pending
768  technical_pass: pending
769  approved_at: null
770```
771 
772The journey pass must be marked "complete" by the user (after stakeholder approval of user-journey specs) before the technical pass begins:
773 
774```yaml
775two_pass_spec:
776  journey_pass: complete
777  approved_at: "2026-06-26T12:00:00Z"
778  technical_pass: pending
779```
780 
781Inform the user: "Journey pass is pending. Run `elaborate-spec` for user journeys, get stakeholder approval, then update `two_pass_spec.journey_pass: complete` in state.yaml before proceeding to technical specs."
782 
783If **no**, skip the two-pass gate. Proceed directly to plan-work.
784 
785→ verify: `grep -q 'two_pass_spec:' specs/state.yaml && echo "two-pass gate initialized" || echo "two-pass gate not activated"`
786 
787 
788---
789 
790### Step 8 — Post-migration: Optional methodology doc template
791 
792After Steps 1–7, offer the user an optional analytical framework scaffold (GSD learning):
793 
794Prompt: "Create a methodology doc? [yes / no]"
795 
796If **yes**, present a checklist of analytical lenses:
797 
798```
799Which lenses to include in specs/tech-architecture/METHODOLOGY_LATEST.md?
800 
801[x] Cost of Delay (CD3)           — Priority & trade-off assessment
802[ ] STRIDE                        — Security threat modeling
803[ ] F.I.R.S.T                     — Test quality principles
804[ ] Bayesian Updating            — Probabilistic decision-making
805[ ] OWASP Top 10                 — Web security framework
806```
807 
808Copy the template from `migrate-spec/templates/METHODOLOGY_LATEST.md` to `specs/tech-architecture/METHODOLOGY_LATEST.md`.
809- Active lenses remain uncommented
810- Unselected lenses are left commented out
811- Populate `{{project_name}}` with the migrated project's name
812 
813If **no**, skip. Add note to handoff: "Methodology doc: skipped — can be added later via `cp migrate-spec/templates/METHODOLOGY_LATEST.md specs/tech-architecture/`"
814 
815→ verify: `test -f specs/tech-architecture/METHODOLOGY_LATEST.md && echo "methodology doc created" || echo "methodology doc skipped"`
816 
817---
818 
819 
820---
821 
822## Artifact Mapping Summary
823 
824Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE.md](./REFERENCE.md) (spec-kit, BMAD, learnings).
825 
826| Source | Target |
827|--------|--------|
828| GSD `ROADMAP.md` | `specs/release-plan.yaml + epic shards` |
829| GSD `REQUIREMENTS.md` | `specs/product/SCOPE_LATEST.yaml` |
830| GSD `CONTEXT.md` (phases) | `specs/tech-architecture/tech-stack.md` + `specs/adr/` |
831| GSD `PLAN.md` | `specs/epics/eNN-slug/epic.yaml` (tasks with verify in `-tasks.yaml`) |
832| GSD `METHODOLOGY.md` | `specs/tech-architecture/tech-stack.md` |
833| spec-kit `spec.md` | `specs/product/SCOPE_LATEST.yaml` + `specs/tech-architecture/tech-stack.md` |
834| spec-kit `plan.md` | `specs/tech-architecture/tech-stack.md` + `specs/release-plan.yaml` + `specs/epics/` |
835| spec-kit `tasks.md` | `specs/epics/ (see slice-tasks)` |
836| BMAD `prd.md` | `specs/product/SCOPE_LATEST.yaml` |
837| BMAD `architecture.md` | `specs/tech-architecture/tech-stack.md` + `specs/adr/` |
838| BMAD `epic-*.md` | `specs/release-plan.yaml + epic shards` |
839| BMAD `story-*.md` | `specs/epics/ (see slice-tasks)` |
840| BMAD `project-context.md` | `CLAUDE.md` (append project-specific section) |
841| BMAD `decision-log.md` | `specs/adr/` (one ADR per logged decision) |
842 
843---
844 
845 
846---
847 
848## Rules
849 
850- **Preserve source IDs** — REQ-XX, FR-XX, UJ-XX are emitted as first-class `id:` fields in bigpowers YAML targets (e.g., `in_scope` entries). Never silently renumber. See Step 3 ID Tracking subsection for details.
851- **Never merge contradictory docs** — if source has both `CONTEXT.md` and `architecture.md`, create sections in bigpowers `CONTEXT.md`; don't collapse them.
852- **ADRs are opt-in** — only create an ADR when: hard to reverse, surprising without context, result of a real trade-off. Lightweight decisions go to `specs/DECISION-LOG_LATEST.md`.
853- **state.yaml is always regenerated** — never migrate source STATE verbatim; bigpowers state.yaml needs its own format.
854- **specs/ is the only output location** — no files are created outside `specs/` and `CLAUDE.md`.
855 
856---
857 
858### Step 5 — Surface learnings (optional)
859 
860After migration, offer the user a brief analysis of what the source framework did that bigpowers doesn't have yet.
861 
862Use the learnings table from [REFERENCE.md](./REFERENCE.md#learnings-to-adopt). Present as checkboxes so the user can decide which to adopt.
863 
864→ verify: `grep -c "\- \[ \]" specs/state.yaml 2>/dev/null && echo "pending items recorded" || echo "no pending items in state.yaml"`
865 
866 
867---
868 
869### Step 6 — Adversarial review (optional)
870 
871Before the user runs `plan-work`, offer an optional lightweight audit of the migrated artifacts. This catches common migration errors early — incomplete specs, missing verification commands, unresolved decisions.
872 
873Prompt: "Run adversarial review of migrated artifacts? [yes / skip]"
874 
875If yes, perform these checks:
876 
8771. **Scan for incomplete markers** — Find TODO, FIXME, MISSING in specs/
8782. **Verify every epic has `verify:` commands** — Parse all `eNN-*/epic.yaml` files
8793. **Check state.yaml handoff** — Ensure `open_decisions` is documented (even if empty)
880 
881Collect findings and write to `specs/archive/MIGRATION-AUDIT.md`:
882 
883```markdown
884# Migration Audit — <project-name> from <framework>
885 
886**Date:** <ISO 8601 timestamp>
887**Status:** Pass / Fail with findings
888 
889 
890---
891 
892## Findings
893 
894### High Priority
895- Artifact: specs/epics/e02-auth-ui/epic.yaml
896  Finding: No verify: commands in story tasks
897  Recommendation: Add `verify:` to each task before develop-tdd
898 
899### Information
900- Count of TODO markers: 3 (normal for fresh migration)
901```
902 
903If findings exist, the handoff block should note: "Adversarial review: N findings — see `specs/archive/MIGRATION-AUDIT.md`"
904 
905If skip is chosen, add to handoff: "Adversarial review: skipped — review manually before plan-work"
906 
907→ verify: `test -f specs/archive/MIGRATION-AUDIT.md && echo "audit completed" || echo "audit skipped or not performed"`
908