| name | migrate-spec |
| model | sonnet |
| description | 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. |
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
- Run this skill from the root of the project being migrated (not the bigpowers repo itself).
- The skill auto-detects the source framework and presents its findings before transforming anything.
- 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 . 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: ls .planning/ 2>/dev/null && echo "GSD" || ls .specify/ 2>/dev/null && echo "spec-kit" || ls _bmad/ 2>/dev/null && echo "BMAD" || echo "BLOCKED: no known framework detected"
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: find . -maxdepth 4 \( -name "ROADMAP.md" -o -name "spec.md" -o -name "prd.md" -o -name "REQUIREMENTS.md" \) 2>/dev/null | grep -v ".git" | head -15
Step 3 — Transform (one artifact at a time, show diffs)
Apply the mapping from REFERENCE.md and REFERENCE-GSD.md. For each target file:
- Show what will be created or appended (title + first 20 lines).
- Ask: "Create this? [yes / edit / skip]"
- 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 diff --name-only HEAD -- specs/ 2>/dev/null | head -20
→ verify: ls specs/*.md 2>/dev/null | head -15
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 && grep -q 'last_step_completed' specs/state.yaml && echo "ok" || echo "MISSING or INCOMPLETE: handoff block"
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 sectiondecisions → scan each: if hard-to-reverse + surprising → specs/adr/NNNN-{slug}.md; if lightweight → specs/DECISION-LOG_LATEST.mdcanonical_refs → Reference links in TECH_STACKcode_context → Architecture sectiondeferred → 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–22 | Navigation |
| 24–62 | spec-kit → bigpowers Mapping |
| 64–130 | BMAD → bigpowers Mapping |
| 132–154 | Learnings to Adopt |
| 156–350 | Output Formats + state.yaml template |
| 352–620 | Reference blocks 1–2 + extended mappings |
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
From spec-kit
From BMAD
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
description: "Dashboard displays user profile"
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:
- 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"
- 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: []
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:
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
in_scope:
- id: REQ-001
description: "User can register with email/password"
source: "REQUIREMENTS.md"
in_scope:
- "User can register with email/password"
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
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:
- Scan for incomplete markers — Find TODO, FIXME, MISSING in specs/
- Verify every epic has
verify: commands — Parse all eNN-*/epic.yaml files
- 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"
