migrate-spec

<!-- story: e25s01 --> <!-- story: e25s02 --> <!-- story: e25s03 --> <!-- story: e25s04 --> <!-- story: e25s05 --> <!-- story: e25s06 -->

Migrate Spec

Transform 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.

Quick start

1. Run this skill from the root of the project being migrated (not the bigpowers repo itself).
2. The skill auto-detects the source framework and presents its findings before transforming anything.
3. All output goes to specs/ at the project root.

---

Red flags — stop and ask

Before proceeding, check for these rationalization traps:

• 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?"
• Wrong trigger — user said "migrate my code" or "migrate the database", not "migrate my specs". Confirm before running.
• 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?"
• 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?"

If any red flag fires: surface it, wait for explicit user confirmation before continuing.

---

Process

Step 1 — Detect the source framework

Scan for the fingerprints below. Stop at first match; if multiple match, list them and ask the user which is primary.

Framework	Fingerprints (any one is sufficient)
GSD	.planning/ directory; .planning/ROADMAP.md; .planning/REQUIREMENTS.md with REQ- IDs
spec-kit	.specify/ directory; spec.md + plan.md at root; .github/skills/speckit-*/SKILL.md
BMAD	_bmad/ directory; _bmad-output/ directory; prd.md with FR- IDs; epic-*.md or story-*.md

If none found: ask the user which framework before proceeding.

→ verify: test -d specs && test -f specs/state.yaml

Step 2 — Inventory the source artifacts

List every artifact found matching the detected framework. Present the list to the user:

See REFERENCE.md — Detected: GSD...

→ verify: test -d specs && test -w specs

Step 3 — Transform (one artifact at a time, show diffs)

Apply the mapping from REFERENCE.md and REFERENCE-GSD.md. For each target file:

1. Show what will be created or appended (title + first 20 lines).
2. Ask: "Create this? [yes / edit / skip]"
3. On yes: write to specs/.

ID Tracking (REQ-XX, FR-XX, UJ-XX)

When source artifacts contain IDs (REQ-XX, FR-XX, UJ-XX), emit them as first-class YAML fields in in_scope entries, not YAML comments:

See REFERENCE.md — # CORRECT — first-class id: field...

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.

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.

See REFERENCE.md — in_scope format with ID tracking for examples.

Traceability Output (FR-XX, UJ-XX)

When source has FR-XX or UJ-XX IDs, emit specs/product/REQUIREMENTS_TRACE.yaml for end-to-end requirement traceability:

See REFERENCE.md — trace:...

Existing trace file: If REQUIREMENTS_TRACE.yaml already exists, prompt: "REQUIREMENTS_TRACE.yaml exists. [overwrite / merge / skip]"

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".

See REFERENCE.md — REQUIREMENTS_TRACE.yaml format for the complete schema.

HARD GATE — Never overwrite an existing specs/ file without explicit user confirmation. Merge into it if it exists; don't clobber.

→ verify: git rev-parse --git-dir >/dev/null 2>&1 && test -d specs

→ verify: test -d specs && [ "$(ls specs/*.md specs/*.yaml 2>/dev/null | wc -l | tr -d " ")" -gt 0 ]

Step 4 — Generate state.yaml

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

See REFERENCE.md — active_flow: null...

If no open decisions were found during migration, the open_decisions list may be empty with an explanatory comment:

See REFERENCE.md — handoff:...

→ verify: grep -q handoff: specs/state.yaml

---

migrate-spec Reference — GSD

Full artifact transformation rules for migrating GSD projects to bigpowers YAML layout.

See REFERENCE.md for spec-kit, BMAD, learnings, and ADR/DECISION-LOG formats.

---

Artifact Locations

GSD stores everything under .planning/ at the project root.

.planning/
├── ROADMAP.md
├── STATE.md
├── REQUIREMENTS.md
├── METHODOLOGY.md
├── HANDOFF.json
├── .continue-here.md
└── phases/
    └── XX-name/
        ├── XX-CONTEXT.md
        ├── XX-YY-PLAN.md
        ├── XX-YY-SUMMARY.md
        └── XX-DISCUSSION-LOG.md
    spikes/
        └── SPIKE-NNN/README.md

---

Transformation Rules

.planning/ROADMAP.md → specs/release-plan.yaml + specs/epics/eNN-*.yaml

GSD ROADMAP has: milestone name, phases, success criteria per phase, plan count.

Transform:

• Each GSD phase → one epic entry in release-plan.yaml (id, title, wsjf, file)
• Phase detail → matching specs/epics/eNN-slug.yaml (stories, tasks, verify)
• Completed phases → done in execution-status.yaml; active → in_progress

---

.planning/REQUIREMENTS.md → specs/product/SCOPE_LATEST.yaml

GSD REQUIREMENTS has: REQ-XX IDs, Validated/Active/Out-of-Scope categories, traceability.

Transform:

• Preserve REQ-XX IDs as first-class id: fields in in_scope entries (see REFERENCE.md — ID tracking format)
• Validated requirements → in_scope entries with id:, description:, source: fields
• Out-of-Scope → out_of_scope entries (preserve IDs if present)
• Active (in-progress) → in_scope with status note

---

.planning/phases/XX-name/XX-CONTEXT.md → specs/tech-architecture/TECH_STACK_LATEST.md + specs/adr/

GSD CONTEXT.md has 6 sections: domain, decisions, canonical_refs, code_context, specifics, deferred.

Transform:

• domain → plans/TECH_STACK_LATEST.md Domain section
• decisions → scan each: if hard-to-reverse + surprising → specs/adr/NNNN-{slug}.md; if lightweight → specs/DECISION-LOG_LATEST.md
• canonical_refs → Reference links in TECH_STACK
• code_context → Architecture section
• deferred → SCOPE_LATEST.yaml out_of_scope (with "(deferred from GSD)" note)

---

.planning/phases/XX-name/XX-YY-PLAN.md → specs/epics/eNN-*.yaml tasks

GSD PLAN has: frontmatter (depends-on, verify), objective, typed tasks, success criteria, output spec.

Transform:

• Preserve task structure as tasks[] in epic shard
• Keep verify: <command> lines
• Map GSD depends-on to task depends-on notes
• SUMMARY.md (execution record) → skip or append to specs/archive/

---

.planning/METHODOLOGY.md → specs/tech-architecture/METHODOLOGY_LATEST.md

GSD METHODOLOGY.md is a standing reference for analytical lenses (Bayesian updating, STRIDE, cost-of-delay).

Transform:

• Copy each lens as a section in specs/tech-architecture/METHODOLOGY_LATEST.md
• Note: "These lenses should inform plan-work and audit-code sessions."

---

.planning/HANDOFF.json + .continue-here.md → specs/state.yaml handoff

GSD HANDOFF has: current phase, last plan, blocking reason, required reading list.

Transform — populate handoff in state.yaml:

handoff:
  last_step_completed: "<phase/plan from HANDOFF>"
  open_decisions:
    - "<blocking reason if any>"
  required_reading:
    - "<required_reading list>"
  next_skill: survey-context

---

.planning/spikes/SPIKE-NNN/README.md → specs/archive/spikes/SPIKE-{name}.md

GSD spike README has: YAML frontmatter (verdict, validates, related), methodology, findings, recommendation.

Transform:

• Flatten directory into specs/archive/spikes/SPIKE-{name}.md
• Preserve frontmatter as YAML block at top
• Keep verdict prominently: **Verdict:** ADOPTED / REJECTED / DEFERRED

---

Skip List

These GSD artifacts are not migrated — they are execution records, not planning inputs:

Artifact	Reason
.planning/phases/XX/XX-YY-SUMMARY.md	Execution log; no bigpowers equivalent
.planning/phases/XX/XX-DISCUSSION-LOG.md	Audit trail only; not consumed by agents
.planning/USER-PROFILE.md	User calibration; bigpowers has no profile system
.planning/sketches/	Visual exploration; not spec artifacts

---

Migrate Spec — Reference

Navigation

Lines	Section
1	Title
3–68	Navigation
69–70	spec-kit → bigpowers Mapping
71–84	Artifact Locations
85–94	spec.md → specs/product/SCOPE_LATEST.yaml + specs/tech-architecture/TECH_STACK_LATEST.md
95–105	plan.md → specs/tech-architecture/TECH_STACK_LATEST.md + specs/release-plan.yaml + specs/epics/
106–114	tasks.md → specs/epics/ (via slice-tasks)
115–120	.specify/ state
121–122	BMAD → bigpowers Mapping
123–141	Artifact Locations
142–148	product-brief.md / prfaq-{project}.md → specs/product/VISION_LATEST.yaml
149–160	prd.md → specs/product/SCOPE_LATEST.yaml + GLOSSARY_LATEST.yaml
161–167	addendum.md + decision-log.md → specs/adr/ + specs/DECISION-LOG_LATEST.md
168–174	architecture.md → specs/tech-architecture/TECH_STACK_LATEST.md + specs/adr/
175–178	epic-*.md → specs/release-plan.yaml + specs/epics/eNN-*.yaml
179–182	story-*.md → specs/epics/ stories
183–188	project-context.md → CLAUDE.md
189–192	Learnings to Adopt
193–198	From GSD
199–204	From spec-kit
205–212	From BMAD
213–214	Output Formats
215–224	ADR format (bigpowers)
225–227	Context
228–230	Decision
231–234	Consequences
235–246	DECISION-LOG.md format
247–257	MIGRATION-AUDIT.md format
258–264	Summary
265–274	High Priority Findings
275–278	Information
279–285	Next Steps
286–306	in_scope format with ID tracking
307–341	REQUIREMENTS_TRACE.yaml format
342–397	specs/state.yaml template format
398–416	Reference block 1
417–432	Reference block 2
433–451	Reference block 3
452–474	Reference block 4
475–482	Reference block 5
483–484	Findings
485–489	High Priority
490–495	Information
496–509	Reference block 6
510–542	Step 7 — Post-migration: Optional two-pass spec writing gate
543–574	Step 8 — Post-migration: Optional methodology doc template
575–600	Artifact Mapping Summary
601–610	Rules
611–621	Step 5 — Surface learnings (optional)
622–644	Step 6 — Adversarial review (optional)
645–646	Findings
647–651	High Priority
652–660	Information

migrate-spec Reference — spec-kit, BMAD, Learnings

Transformation rules for spec-kit and BMAD projects, plus learnings to adopt and output formats.

See REFERENCE-GSD.md for full GSD → bigpowers YAML mapping.

---

spec-kit → bigpowers Mapping

Artifact Locations

project-root/
├── spec.md         ← user journeys, success criteria, scope
├── plan.md         ← technology, architecture, constraints
├── tasks.md        ← atomic task list
└── .specify/
    ├── workflow-catalogs.yml
    └── workflows/runs/<id>/
        ├── state.json
        └── log.jsonl

spec.md → specs/product/SCOPE_LATEST.yaml + specs/tech-architecture/TECH_STACK_LATEST.md

spec-kit spec.md focuses on: who uses it, user journeys, success criteria, what's in/out of scope.

Transform:

• User journeys → SCOPE_LATEST.yaml success criteria / in_scope entries
• In/out of scope → in_scope / out_of_scope sections
• Domain terms / glossary → requirements/GLOSSARY_LATEST.yaml
• Problem statement / vision → requirements/VISION_LATEST.yaml

plan.md → specs/tech-architecture/TECH_STACK_LATEST.md + specs/release-plan.yaml + specs/epics/

spec-kit plan.md covers: technology stack, architectural patterns, implementation constraints.

Transform:

• Technology decisions → plans/TECH_STACK_LATEST.md Technology section
• Architecture patterns → Architecture section
• Hard decisions with trade-offs → specs/adr/NNNN-{slug}.md
• Phased approach / milestones → release-plan.yaml epic entries
• Implementation steps → epics/eNN-*.yaml task list with verify:

tasks.md → specs/epics/ (via slice-tasks)

spec-kit tasks are atomic, verifiable in isolation — same principle as bigpowers verify: mandate.

Transform:

• Copy tasks into epic shard tasks[]; preserve task numbers
• Add verify: line if spec-kit task has an acceptance criterion
• Group into epics matching release-plan.yaml entries

.specify/ state

Discard — workflow engine state; not meaningful in the bigpowers skill model.

---

BMAD → bigpowers Mapping

Artifact Locations

project-root/
├── _bmad/bmm/config.yaml
├── _bmad-output/
│   ├── product-brief.md
│   ├── prfaq-{project}.md
│   ├── prd.md
│   ├── addendum.md
│   ├── decision-log.md
│   ├── ux-spec.md
│   └── architecture.md
├── project-context.md
└── docs/
    ├── epic-{slug}.md
    └── story-{slug}.md

product-brief.md / prfaq-{project}.md → specs/product/VISION_LATEST.yaml

Transform:

• Vision + core value → VISION_LATEST.yaml north_star / success_criteria
• Target users → notes in VISION or SCOPE
• prfaq customer FAQ → can inform success criteria in SCOPE

prd.md → specs/product/SCOPE_LATEST.yaml + GLOSSARY_LATEST.yaml

BMAD prd.md has: Glossary, FR-XX functional requirements, UJ-XX user journeys, NFRs, assumptions.

Transform:

• Glossary → GLOSSARY_LATEST.yaml
• FR-XX items → in_scope with IDs preserved
• UJ-XX user journeys → success criteria
• NFRs → constraints section
• [ASSUMPTION: ...] inline tags → collected in scope YAML
• Out-of-scope features → out_of_scope

addendum.md + decision-log.md → specs/adr/ + specs/DECISION-LOG_LATEST.md

Transform:

• Hard, irreversible, surprising decisions → individual specs/adr/NNNN-{slug}.md
• Lightweight decisions → specs/DECISION-LOG_LATEST.md (date | decision | rationale)
• addendum.md change signals → note in SCOPE_LATEST.yaml metadata

architecture.md → specs/tech-architecture/TECH_STACK_LATEST.md + specs/adr/

Transform:

• ADR sections → individual specs/adr/NNNN-{slug}.md files
• System overview / data models → TECH_STACK Architecture section
• API contracts → keep at docs/api.md or similar; link from TECH_STACK

epic-*.md → specs/release-plan.yaml + specs/epics/eNN-*.yaml

Each epic → one release-plan entry + one epic shard. Acceptance criteria → story tasks with verify:.

story-*.md → specs/epics/ stories

Each story → one story entry in epic shard. Acceptance criteria → verify: lines.

project-context.md → CLAUDE.md

Add a "## Project Context" section to CLAUDE.md. Copy tech stack, coding rules, preferences verbatim.

---

Learnings to Adopt

Optional enhancements to offer the user after migration. Present as checkboxes.

From GSD

• [x] specs/tech-architecture/METHODOLOGY_LATEST.md — Standing analytical lenses. Agents read before planning. (adopted: optional Step 8 template scaffold)
• [x] handoff block in state.yaml — Last skill, last step, required reading for next session. (adopted: mandatory in Step 4 output)
• [x] ID tracking in SCOPE_LATEST.yaml — FR/UJ IDs for spec → plan → verification traceability. (adopted in Step 3 transform)

From spec-kit

• [x] Two-pass spec writing — User-journey pass first, then technical-decisions pass. (adopted: optional post-migration gate)
• [ ] Explicit inter-phase gate — "Approve to proceed?" at end of elaborate-spec.
• [ ] Epic task isolation — Each task completable in isolation; depends-on explicit in epic YAML.

From BMAD

• [x] FR-XX + UJ-XX in SCOPE_LATEST.yaml — Rigorous traceability. (adopted: REQUIREMENTS_TRACE.yaml emitted on migration)
• [ ] specs/DECISION-LOG_LATEST.md — Lightweight decisions below ADR threshold.
• [x] Adversarial review pass — Critique epic shard before develop-tdd. (adopted: optional Step 6 in migration)

---

Output Formats

ADR format (bigpowers)

Use model-domain/ADR-FORMAT.md. Only create when all three apply: hard to reverse, surprising without context, result of a real trade-off.

# ADR-NNNN: {Title}

**Status:** Accepted
**Date:** YYYY-MM-DD

## Context
[What situation forced this decision?]

## Decision
[What was decided?]

## Consequences
[What becomes easier or harder?]

DECISION-LOG.md format

For lightweight decisions that don't warrant a full ADR:

# Decision Log

| Date | Decision | Rationale | Alternatives |
|------|----------|-----------|--------------|
| 2026-05-19 | Use Postgres | Existing ops expertise | SQLite (limited), DynamoDB (no local dev) |

MIGRATION-AUDIT.md format

Post-migration adversarial review report. Written to specs/archive/MIGRATION-AUDIT.md when Step 6 runs:

# Migration Audit — <project-name>

**Source Framework:** <GSD|spec-kit|BMAD>  
**Date:** <ISO 8601>  
**Status:** <Pass|Findings|Critical>

## Summary

- TODO markers: N
- FIXME markers: N
- MISSING markers: N
- Epics without verify: N

## High Priority Findings

- **Artifact:** specs/epics/e02-auth-ui/epic.yaml
  **Issue:** Story e02s01 has no verify: commands in tasks
  **Recommendation:** Add runnable verify command before develop-tdd

- **Artifact:** specs/state.yaml
  **Issue:** open_decisions list empty without comment explanation
  **Recommendation:** Add # comment if all decisions were resolved during migration

## Information

- Artifact specs/epics/e01-auth/epic.yaml contains TODO: "Define Neon Auth client URL injection" (normal for fresh migration)

## Next Steps

1. Address high-priority findings before plan-work
2. Run bash scripts/audit-compliance.sh to enforce code quality gates
3. Begin develop-tdd on highest-WSJF epic

in_scope format with ID tracking

Source IDs (REQ-XX, FR-XX, UJ-XX) are emitted as first-class YAML fields:

in_scope:
  - id: REQ-001
    description: "User can register with email and password"
    source: "REQUIREMENTS.md"
  - id: FR-015
    description: "Auth service must support OAuth2 token flow"
    source: "prd.md"
  - id: REQ-AUTO-002  # auto-generated when source had no ID
    description: "Dashboard displays user profile"
    # auto-generated: true  (optional comment for tracking)

When source has no IDs: If the user opts in, auto-generated IDs follow the REQ-{NNN} format with an optional # auto-generated comment.

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.

REQUIREMENTS_TRACE.yaml format

Emitted when source has FR-XX (functional requirement) or UJ-XX (user journey) IDs. Maps source requirements to bigpowers epic/story structure and verification commands:

trace:
  # Functional Requirements
  - id: FR-001
    type: functional_requirement
    description: "User can register with email/password"
    source_artifact: "prd.md"
    epic: "e02-auth-ui"
    story: "e02s01"
    verify: "grep -q 'FR-001' specs/product/SCOPE_LATEST.yaml && echo OK"

  # User Journeys
  - id: UJ-001
    type: user_journey
    description: "New user completes registration flow"
    source_artifact: "epic-auth-ui.md"
    epic: "e02-auth-ui"
    story: "e02s01"
    verify: "grep -q 'UJ-001' specs/epics/e02-auth-ui/epic.yaml && echo OK"

metadata:
  source_framework: "BMAD"
  migrated_at: "2026-06-26T12:00:00Z"
  total_requirements: 2
  coverage: "All FR-XX and UJ-XX IDs from source mapped"

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".

Existing trace file: If REQUIREMENTS_TRACE.yaml exists, prompt user: "Overwrite? [yes / merge / skip]". Merge appends new entries; skip leaves existing file intact.

specs/state.yaml template format

Generated during Step 4 of migration. Regenerate from scratch in bigpowers YAML format. The handoff block is mandatory:

active_flow: null
active_epic_id: null
active_story_id: null
completed_epic: false

epic_cycle:
  current_step: null
  next_skill: null
  story_bcps: null
  completed_steps: []
  audit_result: null

bug_cycle:
  current_step: null
  completed_steps: []

release:
  target_version: null
  last_tag: null
  last_publish: null
  ci_verified: false

metrics:
  story_start: null
  story_end: null
  cycle_minutes: null
  bcp_per_hour: null

git:
  branch: <current branch>
  hash: <git rev-parse HEAD>
  pushed: false

handoff:
  last_step_completed: "Migrated from <framework> on <date>"
  open_decisions: []  # Empty if all decisions resolved during migration
  required_reading:
    - specs/product/VISION_LATEST.yaml
    - specs/product/SCOPE_LATEST.yaml
    - specs/tech-architecture/TECH_STACK_LATEST.md
    - specs/release-plan.yaml
  next_skill: survey-context

two_pass_spec:  # Optional: only if user activates two-pass spec writing gate
  journey_pass: pending
  technical_pass: pending
  approved_at: null

---

Reference block 1

Detected: GSD
Found:
  ✓ .planning/ROADMAP.md
  ✓ .planning/REQUIREMENTS.md  (12 REQ-XX items)
  ✓ .planning/state.yaml
  ✓ .planning/phases/01-auth/01-CONTEXT.md
  ✗ .planning/METHODOLOGY.md  (not present)

Skipping:
  .planning/phases/01-auth/01-01-SUMMARY.md  (execution record; archived only)

Proceed with migration? [yes / skip <artifact> / abort]

---

Reference block 2

# CORRECT — first-class id: field
in_scope:
  - id: REQ-001
    description: "User can register with email/password"
    source: "REQUIREMENTS.md"

# DEPRECATED — comment-only
in_scope:
  - "User can register with email/password"  # REQ-001

---

Reference block 3

trace:
  - id: FR-001
    type: functional_requirement
    description: "User can register with email/password"
    epic: e02-auth-ui
    story: e02s01
    verify: "grep -q 'FR-001' specs/product/SCOPE_LATEST.yaml && echo OK"
  - id: UJ-001
    type: user_journey
    description: "New user completes registration flow"
    epic: e02-auth-ui
    story: e02s01

---

Reference block 4

active_flow: null
active_epic_id: null
active_story_id: null

# ... other state fields ...

handoff:
  last_step_completed: "Migrated from <framework> on <date>"
  open_decisions:
    - "decision text here"
  required_reading:
    - specs/product/VISION_LATEST.yaml
    - specs/product/SCOPE_LATEST.yaml
    - specs/tech-architecture/TECH_STACK_LATEST.md
    - specs/release-plan.yaml
  next_skill: survey-context

---

Reference block 5

# Migration Audit — <project-name> from <framework>

**Date:** <ISO 8601 timestamp>
**Status:** Pass / Fail with findings

## Findings

### High Priority
- Artifact: specs/epics/e02-auth-ui/epic.yaml
  Finding: No verify: commands in story tasks
  Recommendation: Add `verify:` to each task before develop-tdd

### Information
- Count of TODO markers: 3 (normal for fresh migration)

---

Reference block 6

Which lenses to include in specs/tech-architecture/METHODOLOGY_LATEST.md?

[x] Cost of Delay (CD3)           — Priority & trade-off assessment
[ ] STRIDE                        — Security threat modeling
[ ] F.I.R.S.T                     — Test quality principles
[ ] Bayesian Updating            — Probabilistic decision-making
[ ] OWASP Top 10                 — Web security framework

---

Step 7 — Post-migration: Optional two-pass spec writing gate

After Steps 1–6, offer the user an optional two-pass spec writing workflow (spec-kit learning):

Prompt: "Use two-pass spec writing (user journeys first, then technical)? [yes / no]"

If yes, initialize the gate in specs/state.yaml:

two_pass_spec:
  journey_pass: pending
  technical_pass: pending
  approved_at: null

The journey pass must be marked "complete" by the user (after stakeholder approval of user-journey specs) before the technical pass begins:

two_pass_spec:
  journey_pass: complete
  approved_at: "2026-06-26T12:00:00Z"
  technical_pass: pending

Inform 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."

If no, skip the two-pass gate. Proceed directly to plan-work.

→ verify: grep -q 'two_pass_spec:' specs/state.yaml && echo "two-pass gate initialized" || echo "two-pass gate not activated"

---

Step 8 — Post-migration: Optional methodology doc template

After Steps 1–7, offer the user an optional analytical framework scaffold (GSD learning):

Prompt: "Create a methodology doc? [yes / no]"

If yes, present a checklist of analytical lenses:

Which lenses to include in specs/tech-architecture/METHODOLOGY_LATEST.md?

[x] Cost of Delay (CD3)           — Priority & trade-off assessment
[ ] STRIDE                        — Security threat modeling
[ ] F.I.R.S.T                     — Test quality principles
[ ] Bayesian Updating            — Probabilistic decision-making
[ ] OWASP Top 10                 — Web security framework

Copy the template from migrate-spec/templates/METHODOLOGY_LATEST.md to specs/tech-architecture/METHODOLOGY_LATEST.md.

• Active lenses remain uncommented
• Unselected lenses are left commented out
• Populate {{project_name}} with the migrated project's name

If no, skip. Add note to handoff: "Methodology doc: skipped — can be added later via cp migrate-spec/templates/METHODOLOGY_LATEST.md specs/tech-architecture/"

→ verify: test -f specs/tech-architecture/METHODOLOGY_LATEST.md && echo "methodology doc created" || echo "methodology doc skipped"

---

---

Artifact Mapping Summary

Full mapping tables: REFERENCE-GSD.md (GSD) · REFERENCE.md (spec-kit, BMAD, learnings).

Source	Target
GSD ROADMAP.md	specs/release-plan.yaml + epic shards
GSD REQUIREMENTS.md	specs/product/SCOPE_LATEST.yaml
GSD CONTEXT.md (phases)	specs/tech-architecture/tech-stack.md + specs/adr/
GSD PLAN.md	specs/epics/eNN-slug/epic.yaml (tasks with verify in -tasks.yaml)
GSD METHODOLOGY.md	specs/tech-architecture/tech-stack.md
spec-kit spec.md	specs/product/SCOPE_LATEST.yaml + specs/tech-architecture/tech-stack.md
spec-kit plan.md	specs/tech-architecture/tech-stack.md + specs/release-plan.yaml + specs/epics/
spec-kit tasks.md	specs/epics/ (see slice-tasks)
BMAD prd.md	specs/product/SCOPE_LATEST.yaml
BMAD architecture.md	specs/tech-architecture/tech-stack.md + specs/adr/
BMAD epic-*.md	specs/release-plan.yaml + epic shards
BMAD story-*.md	specs/epics/ (see slice-tasks)
BMAD project-context.md	CLAUDE.md (append project-specific section)
BMAD decision-log.md	specs/adr/ (one ADR per logged decision)

---

---

Rules

• 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.
• Never merge contradictory docs — if source has both CONTEXT.md and architecture.md, create sections in bigpowers CONTEXT.md; don't collapse them.
• 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.
• state.yaml is always regenerated — never migrate source STATE verbatim; bigpowers state.yaml needs its own format.
• specs/ is the only output location — no files are created outside specs/ and CLAUDE.md.

---

Step 5 — Surface learnings (optional)

After migration, offer the user a brief analysis of what the source framework did that bigpowers doesn't have yet.

Use the learnings table from REFERENCE.md. Present as checkboxes so the user can decide which to adopt.

→ verify: grep -c "\- \[ \]" specs/state.yaml 2>/dev/null && echo "pending items recorded" || echo "no pending items in state.yaml"

---

Step 6 — Adversarial review (optional)

Before 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.

Prompt: "Run adversarial review of migrated artifacts? [yes / skip]"

If yes, perform these checks:

1. Scan for incomplete markers — Find TODO, FIXME, MISSING in specs/
2. Verify every epic has verify: commands — Parse all eNN-*/epic.yaml files
3. Check state.yaml handoff — Ensure open_decisions is documented (even if empty)

Collect findings and write to specs/archive/MIGRATION-AUDIT.md:

# Migration Audit — <project-name> from <framework>

**Date:** <ISO 8601 timestamp>
**Status:** Pass / Fail with findings


---

## Findings

### High Priority
- Artifact: specs/epics/e02-auth-ui/epic.yaml
  Finding: No verify: commands in story tasks
  Recommendation: Add `verify:` to each task before develop-tdd

### Information
- Count of TODO markers: 3 (normal for fresh migration)

If findings exist, the handoff block should note: "Adversarial review: N findings — see specs/archive/MIGRATION-AUDIT.md"

If skip is chosen, add to handoff: "Adversarial review: skipped — review manually before plan-work"

→ verify: test -f specs/archive/MIGRATION-AUDIT.md && echo "audit completed" || echo "audit skipped or not performed"