Loading
Also from Kynth Studios
Also from Kynth Studios
Also from Kynth Studios
1234567# story: e25s018# story: e25s029# story: e25s0310# story: e25s0411# story: e25s0512# story: e25s061314# Migrate Spec1516Transform 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.1718## Quick start19201. Run this skill from the root of the project being migrated (not the bigpowers repo itself).212. The skill auto-detects the source framework and presents its findings before transforming anything.223. All output goes to `specs/` at the project root.2324---2526## Red flags — stop and ask2728Before proceeding, check for these rationalization traps:2930- **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?"31- **Wrong trigger** — user said "migrate my code" or "migrate the database", not "migrate my specs". Confirm before running.32- **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?"33- **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?"3435If any red flag fires: surface it, wait for explicit user confirmation before continuing.3637---3839## Process4041### Step 1 — Detect the source framework4243Scan for the fingerprints below. Stop at first match; if multiple match, list them and ask the user which is primary.4445| Framework | Fingerprints (any one is sufficient) |46|-----------|--------------------------------------|47| **GSD** | `.planning/` directory; `.planning/ROADMAP.md`; `.planning/REQUIREMENTS.md` with `REQ-` IDs |48| **spec-kit** | `.specify/` directory; `spec.md` + `plan.md` at root; `.github/skills/speckit-*/SKILL.md` |49| **BMAD** | `_bmad/` directory; `_bmad-output/` directory; `prd.md` with `FR-` IDs; `epic-*.md` or `story-*.md` |5051If none found: ask the user which framework before proceeding.5253→ verify: `test -d specs && test -f specs/state.yaml`5455### Step 2 — Inventory the source artifacts5657List every artifact found matching the detected framework. Present the list to the user:5859See [REFERENCE.md](REFERENCE.md) — `Detected: GSD...`6061→ verify: `test -d specs && test -w specs`6263### Step 3 — Transform (one artifact at a time, show diffs)6465Apply the mapping from [REFERENCE.md](./REFERENCE.md) and [REFERENCE-GSD.md](./REFERENCE-GSD.md). For each target file:66671. Show what will be created or appended (title + first 20 lines).682. Ask: "Create this? [yes / edit / skip]"693. On yes: write to `specs/`.7071#### ID Tracking (REQ-XX, FR-XX, UJ-XX)7273When source artifacts contain IDs (REQ-XX, FR-XX, UJ-XX), emit them as **first-class YAML fields** in `in_scope` entries, not YAML comments:7475See [REFERENCE.md](REFERENCE.md) — `# CORRECT — first-class id: field...`7677**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.7879**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`.8081See [REFERENCE.md — in_scope format with ID tracking](./REFERENCE.md#in_scope-format-with-id-tracking) for examples.8283#### Traceability Output (FR-XX, UJ-XX)8485When source has FR-XX or UJ-XX IDs, emit `specs/product/REQUIREMENTS_TRACE.yaml` for end-to-end requirement traceability:8687See [REFERENCE.md](REFERENCE.md) — `trace:...`8889**Existing trace file:** If `REQUIREMENTS_TRACE.yaml` already exists, prompt: "REQUIREMENTS_TRACE.yaml exists. [overwrite / merge / skip]"9091**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".9293See [REFERENCE.md — REQUIREMENTS_TRACE.yaml format](./REFERENCE.md#requirements_traceyaml-format) for the complete schema.9495> **HARD GATE** — Never overwrite an existing `specs/` file without explicit user confirmation. Merge into it if it exists; don't clobber.96>97> → verify: `git rev-parse --git-dir >/dev/null 2>&1 && test -d specs`9899→ verify: `test -d specs && [ "$(ls specs/*.md specs/*.yaml 2>/dev/null | wc -l | tr -d " ")" -gt 0 ]`100101### Step 4 — Generate state.yaml102103Always 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:104105See [REFERENCE.md](REFERENCE.md) — `active_flow: null...`106107If no open decisions were found during migration, the `open_decisions` list may be empty with an explanatory comment:108109See [REFERENCE.md](REFERENCE.md) — `handoff:...`110111→ verify: `grep -q handoff: specs/state.yaml`112113---114115# migrate-spec Reference — GSD116117Full artifact transformation rules for migrating GSD projects to bigpowers YAML layout.118119See [REFERENCE.md](./REFERENCE.md) for spec-kit, BMAD, learnings, and ADR/DECISION-LOG formats.120121---122123## Artifact Locations124125GSD stores everything under `.planning/` at the project root.126127```128.planning/129├── ROADMAP.md130├── STATE.md131├── REQUIREMENTS.md132├── METHODOLOGY.md133├── HANDOFF.json134├── .continue-here.md135└── phases/136 └── XX-name/137 ├── XX-CONTEXT.md138 ├── XX-YY-PLAN.md139 ├── XX-YY-SUMMARY.md140 └── XX-DISCUSSION-LOG.md141 spikes/142 └── SPIKE-NNN/README.md143```144145---146147## Transformation Rules148149### `.planning/ROADMAP.md` → `specs/release-plan.yaml` + `specs/epics/eNN-*.yaml`150151GSD ROADMAP has: milestone name, phases, success criteria per phase, plan count.152153Transform:154- Each GSD phase → one epic entry in `release-plan.yaml` (`id`, `title`, `wsjf`, `file`)155- Phase detail → matching `specs/epics/eNN-slug.yaml` (stories, tasks, `verify`)156- Completed phases → `done` in `execution-status.yaml`; active → `in_progress`157158---159160### `.planning/REQUIREMENTS.md` → `specs/product/SCOPE_LATEST.yaml`161162GSD REQUIREMENTS has: REQ-XX IDs, Validated/Active/Out-of-Scope categories, traceability.163164Transform:165- 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))166- Validated requirements → `in_scope` entries with `id:`, `description:`, `source:` fields167- Out-of-Scope → `out_of_scope` entries (preserve IDs if present)168- Active (in-progress) → `in_scope` with status note169170---171172### `.planning/phases/XX-name/XX-CONTEXT.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/adr/`173174GSD CONTEXT.md has 6 sections: domain, decisions, canonical_refs, code_context, specifics, deferred.175176Transform:177- `domain` → `plans/TECH_STACK_LATEST.md` Domain section178- `decisions` → scan each: if hard-to-reverse + surprising → `specs/adr/NNNN-{slug}.md`; if lightweight → `specs/DECISION-LOG_LATEST.md`179- `canonical_refs` → Reference links in TECH_STACK180- `code_context` → Architecture section181- `deferred` → `SCOPE_LATEST.yaml` `out_of_scope` (with "(deferred from GSD)" note)182183---184185### `.planning/phases/XX-name/XX-YY-PLAN.md` → `specs/epics/eNN-*.yaml` tasks186187GSD PLAN has: frontmatter (depends-on, verify), objective, typed tasks, success criteria, output spec.188189Transform:190- Preserve task structure as `tasks[]` in epic shard191- Keep `verify: <command>` lines192- Map GSD `depends-on` to task `depends-on` notes193- SUMMARY.md (execution record) → skip or append to `specs/archive/`194195---196197### `.planning/METHODOLOGY.md` → `specs/tech-architecture/METHODOLOGY_LATEST.md`198199GSD METHODOLOGY.md is a standing reference for analytical lenses (Bayesian updating, STRIDE, cost-of-delay).200201Transform:202- Copy each lens as a section in `specs/tech-architecture/METHODOLOGY_LATEST.md`203- Note: "These lenses should inform `plan-work` and `audit-code` sessions."204205---206207### `.planning/HANDOFF.json` + `.continue-here.md` → `specs/state.yaml` `handoff`208209GSD HANDOFF has: current phase, last plan, blocking reason, required reading list.210211Transform — populate `handoff` in `state.yaml`:212213```yaml214handoff:215 last_step_completed: "<phase/plan from HANDOFF>"216 open_decisions:217 - "<blocking reason if any>"218 required_reading:219 - "<required_reading list>"220 next_skill: survey-context221```222223---224225### `.planning/spikes/SPIKE-NNN/README.md` → `specs/archive/spikes/SPIKE-{name}.md`226227GSD spike README has: YAML frontmatter (verdict, validates, related), methodology, findings, recommendation.228229Transform:230- Flatten directory into `specs/archive/spikes/SPIKE-{name}.md`231- Preserve frontmatter as YAML block at top232- Keep verdict prominently: `**Verdict:** ADOPTED / REJECTED / DEFERRED`233234---235236## Skip List237238These GSD artifacts are not migrated — they are execution records, not planning inputs:239240| Artifact | Reason |241|----------|--------|242| `.planning/phases/XX/XX-YY-SUMMARY.md` | Execution log; no bigpowers equivalent |243| `.planning/phases/XX/XX-DISCUSSION-LOG.md` | Audit trail only; not consumed by agents |244| `.planning/USER-PROFILE.md` | User calibration; bigpowers has no profile system |245| `.planning/sketches/` | Visual exploration; not spec artifacts |246247---248249# Migrate Spec — Reference250251## Navigation252253| Lines | Section |254|-------|---------|255| 1 | Title |256| 3–68 | Navigation |257| 69–70 | spec-kit → bigpowers Mapping |258| 71–84 | Artifact Locations |259| 85–94 | `spec.md` → `specs/product/SCOPE_LATEST.yaml` + `specs/tech-architecture/TECH_STACK_LATEST.md` |260| 95–105 | `plan.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/release-plan.yaml` + `specs/epics/` |261| 106–114 | `tasks.md` → `specs/epics/` (via slice-tasks) |262| 115–120 | `.specify/` state |263| 121–122 | BMAD → bigpowers Mapping |264| 123–141 | Artifact Locations |265| 142–148 | `product-brief.md` / `prfaq-{project}.md` → `specs/product/VISION_LATEST.yaml` |266| 149–160 | `prd.md` → `specs/product/SCOPE_LATEST.yaml` + `GLOSSARY_LATEST.yaml` |267| 161–167 | `addendum.md` + `decision-log.md` → `specs/adr/` + `specs/DECISION-LOG_LATEST.md` |268| 168–174 | `architecture.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/adr/` |269| 175–178 | `epic-*.md` → `specs/release-plan.yaml` + `specs/epics/eNN-*.yaml` |270| 179–182 | `story-*.md` → `specs/epics/` stories |271| 183–188 | `project-context.md` → `CLAUDE.md` |272| 189–192 | Learnings to Adopt |273| 193–198 | From GSD |274| 199–204 | From spec-kit |275| 205–212 | From BMAD |276| 213–214 | Output Formats |277| 215–224 | ADR format (bigpowers) |278| 225–227 | Context |279| 228–230 | Decision |280| 231–234 | Consequences |281| 235–246 | DECISION-LOG.md format |282| 247–257 | MIGRATION-AUDIT.md format |283| 258–264 | Summary |284| 265–274 | High Priority Findings |285| 275–278 | Information |286| 279–285 | Next Steps |287| 286–306 | in_scope format with ID tracking |288| 307–341 | REQUIREMENTS_TRACE.yaml format |289| 342–397 | `specs/state.yaml` template format |290| 398–416 | Reference block 1 |291| 417–432 | Reference block 2 |292| 433–451 | Reference block 3 |293| 452–474 | Reference block 4 |294| 475–482 | Reference block 5 |295| 483–484 | Findings |296| 485–489 | High Priority |297| 490–495 | Information |298| 496–509 | Reference block 6 |299| 510–542 | Step 7 — Post-migration: Optional two-pass spec writing gate |300| 543–574 | Step 8 — Post-migration: Optional methodology doc template |301| 575–600 | Artifact Mapping Summary |302| 601–610 | Rules |303| 611–621 | Step 5 — Surface learnings (optional) |304| 622–644 | Step 6 — Adversarial review (optional) |305| 645–646 | Findings |306| 647–651 | High Priority |307| 652–660 | Information |308309# migrate-spec Reference — spec-kit, BMAD, Learnings310311Transformation rules for spec-kit and BMAD projects, plus learnings to adopt and output formats.312313See [REFERENCE-GSD.md](./REFERENCE-GSD.md) for full GSD → bigpowers YAML mapping.314315---316317## spec-kit → bigpowers Mapping318319### Artifact Locations320321```322project-root/323├── spec.md ← user journeys, success criteria, scope324├── plan.md ← technology, architecture, constraints325├── tasks.md ← atomic task list326└── .specify/327 ├── workflow-catalogs.yml328 └── workflows/runs/<id>/329 ├── state.json330 └── log.jsonl331```332333### `spec.md` → `specs/product/SCOPE_LATEST.yaml` + `specs/tech-architecture/TECH_STACK_LATEST.md`334335spec-kit `spec.md` focuses on: who uses it, user journeys, success criteria, what's in/out of scope.336337Transform:338- User journeys → `SCOPE_LATEST.yaml` success criteria / `in_scope` entries339- In/out of scope → `in_scope` / `out_of_scope` sections340- Domain terms / glossary → `requirements/GLOSSARY_LATEST.yaml`341- Problem statement / vision → `requirements/VISION_LATEST.yaml`342343### `plan.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/release-plan.yaml` + `specs/epics/`344345spec-kit `plan.md` covers: technology stack, architectural patterns, implementation constraints.346347Transform:348- Technology decisions → `plans/TECH_STACK_LATEST.md` Technology section349- Architecture patterns → Architecture section350- Hard decisions with trade-offs → `specs/adr/NNNN-{slug}.md`351- Phased approach / milestones → `release-plan.yaml` epic entries352- Implementation steps → `epics/eNN-*.yaml` task list with `verify:`353354### `tasks.md` → `specs/epics/` (via slice-tasks)355356spec-kit tasks are atomic, verifiable in isolation — same principle as bigpowers `verify:` mandate.357358Transform:359- Copy tasks into epic shard `tasks[]`; preserve task numbers360- Add `verify:` line if spec-kit task has an acceptance criterion361- Group into epics matching `release-plan.yaml` entries362363### `.specify/` state364365Discard — workflow engine state; not meaningful in the bigpowers skill model.366367---368369## BMAD → bigpowers Mapping370371### Artifact Locations372373```374project-root/375├── _bmad/bmm/config.yaml376├── _bmad-output/377│ ├── product-brief.md378│ ├── prfaq-{project}.md379│ ├── prd.md380│ ├── addendum.md381│ ├── decision-log.md382│ ├── ux-spec.md383│ └── architecture.md384├── project-context.md385└── docs/386 ├── epic-{slug}.md387 └── story-{slug}.md388```389390### `product-brief.md` / `prfaq-{project}.md` → `specs/product/VISION_LATEST.yaml`391392Transform:393- Vision + core value → `VISION_LATEST.yaml` north_star / success_criteria394- Target users → notes in VISION or SCOPE395- prfaq customer FAQ → can inform success criteria in SCOPE396397### `prd.md` → `specs/product/SCOPE_LATEST.yaml` + `GLOSSARY_LATEST.yaml`398399BMAD `prd.md` has: Glossary, FR-XX functional requirements, UJ-XX user journeys, NFRs, assumptions.400401Transform:402- Glossary → `GLOSSARY_LATEST.yaml`403- FR-XX items → `in_scope` with IDs preserved404- UJ-XX user journeys → success criteria405- NFRs → `constraints` section406- `[ASSUMPTION: ...]` inline tags → collected in scope YAML407- Out-of-scope features → `out_of_scope`408409### `addendum.md` + `decision-log.md` → `specs/adr/` + `specs/DECISION-LOG_LATEST.md`410411Transform:412- Hard, irreversible, surprising decisions → individual `specs/adr/NNNN-{slug}.md`413- Lightweight decisions → `specs/DECISION-LOG_LATEST.md` (date | decision | rationale)414- `addendum.md` change signals → note in `SCOPE_LATEST.yaml` metadata415416### `architecture.md` → `specs/tech-architecture/TECH_STACK_LATEST.md` + `specs/adr/`417418Transform:419- ADR sections → individual `specs/adr/NNNN-{slug}.md` files420- System overview / data models → TECH_STACK Architecture section421- API contracts → keep at `docs/api.md` or similar; link from TECH_STACK422423### `epic-*.md` → `specs/release-plan.yaml` + `specs/epics/eNN-*.yaml`424425Each epic → one release-plan entry + one epic shard. Acceptance criteria → story tasks with `verify:`.426427### `story-*.md` → `specs/epics/` stories428429Each story → one story entry in epic shard. Acceptance criteria → `verify:` lines.430431### `project-context.md` → `CLAUDE.md`432433Add a "## Project Context" section to `CLAUDE.md`. Copy tech stack, coding rules, preferences verbatim.434435---436437## Learnings to Adopt438439Optional enhancements to offer the user after migration. Present as checkboxes.440441### From GSD442443- [x] **`specs/tech-architecture/METHODOLOGY_LATEST.md`** — Standing analytical lenses. Agents read before planning. (adopted: optional Step 8 template scaffold)444- [x] **`handoff` block in state.yaml** — Last skill, last step, required reading for next session. (adopted: mandatory in Step 4 output)445- [x] **ID tracking in SCOPE_LATEST.yaml** — FR/UJ IDs for spec → plan → verification traceability. (adopted in Step 3 transform)446447### From spec-kit448449- [x] **Two-pass spec writing** — User-journey pass first, then technical-decisions pass. (adopted: optional post-migration gate)450- [ ] **Explicit inter-phase gate** — "Approve to proceed?" at end of `elaborate-spec`.451- [ ] **Epic task isolation** — Each task completable in isolation; `depends-on` explicit in epic YAML.452453### From BMAD454455- [x] **FR-XX + UJ-XX in SCOPE_LATEST.yaml** — Rigorous traceability. (adopted: REQUIREMENTS_TRACE.yaml emitted on migration)456- [ ] **`specs/DECISION-LOG_LATEST.md`** — Lightweight decisions below ADR threshold.457- [x] **Adversarial review pass** — Critique epic shard before `develop-tdd`. (adopted: optional Step 6 in migration)458459---460461## Output Formats462463### ADR format (bigpowers)464465Use `model-domain/ADR-FORMAT.md`. Only create when all three apply: hard to reverse, surprising without context, result of a real trade-off.466467```markdown468# ADR-NNNN: {Title}469470**Status:** Accepted471**Date:** YYYY-MM-DD472473## Context474[What situation forced this decision?]475476## Decision477[What was decided?]478479## Consequences480[What becomes easier or harder?]481```482483### DECISION-LOG.md format484485For lightweight decisions that don't warrant a full ADR:486487```markdown488# Decision Log489490| Date | Decision | Rationale | Alternatives |491|------|----------|-----------|--------------|492| 2026-05-19 | Use Postgres | Existing ops expertise | SQLite (limited), DynamoDB (no local dev) |493```494495### MIGRATION-AUDIT.md format496497Post-migration adversarial review report. Written to `specs/archive/MIGRATION-AUDIT.md` when Step 6 runs:498499```markdown500# Migration Audit — <project-name>501502**Source Framework:** <GSD|spec-kit|BMAD>503**Date:** <ISO 8601>504**Status:** <Pass|Findings|Critical>505506## Summary507508- TODO markers: N509- FIXME markers: N510- MISSING markers: N511- Epics without verify: N512513## High Priority Findings514515- **Artifact:** specs/epics/e02-auth-ui/epic.yaml516 **Issue:** Story e02s01 has no verify: commands in tasks517 **Recommendation:** Add runnable verify command before develop-tdd518519- **Artifact:** specs/state.yaml520 **Issue:** open_decisions list empty without comment explanation521 **Recommendation:** Add # comment if all decisions were resolved during migration522523## Information524525- Artifact specs/epics/e01-auth/epic.yaml contains TODO: "Define Neon Auth client URL injection" (normal for fresh migration)526527## Next Steps5285291. Address high-priority findings before plan-work5302. Run bash scripts/audit-compliance.sh to enforce code quality gates5313. Begin develop-tdd on highest-WSJF epic532```533534### in_scope format with ID tracking535536Source IDs (REQ-XX, FR-XX, UJ-XX) are emitted as first-class YAML fields:537538```yaml539in_scope:540 - id: REQ-001541 description: "User can register with email and password"542 source: "REQUIREMENTS.md"543 - id: FR-015544 description: "Auth service must support OAuth2 token flow"545 source: "prd.md"546 - id: REQ-AUTO-002 # auto-generated when source had no ID547 description: "Dashboard displays user profile"548 # auto-generated: true (optional comment for tracking)549```550551**When source has no IDs:** If the user opts in, auto-generated IDs follow the `REQ-{NNN}` format with an optional `# auto-generated` comment.552553**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.554555### REQUIREMENTS_TRACE.yaml format556557Emitted when source has FR-XX (functional requirement) or UJ-XX (user journey) IDs. Maps source requirements to bigpowers epic/story structure and verification commands:558559```yaml560trace:561 # Functional Requirements562 - id: FR-001563 type: functional_requirement564 description: "User can register with email/password"565 source_artifact: "prd.md"566 epic: "e02-auth-ui"567 story: "e02s01"568 verify: "grep -q 'FR-001' specs/product/SCOPE_LATEST.yaml && echo OK"569570 # User Journeys571 - id: UJ-001572 type: user_journey573 description: "New user completes registration flow"574 source_artifact: "epic-auth-ui.md"575 epic: "e02-auth-ui"576 story: "e02s01"577 verify: "grep -q 'UJ-001' specs/epics/e02-auth-ui/epic.yaml && echo OK"578579metadata:580 source_framework: "BMAD"581 migrated_at: "2026-06-26T12:00:00Z"582 total_requirements: 2583 coverage: "All FR-XX and UJ-XX IDs from source mapped"584```585586**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".587588**Existing trace file:** If REQUIREMENTS_TRACE.yaml exists, prompt user: "Overwrite? [yes / merge / skip]". Merge appends new entries; skip leaves existing file intact.589590### `specs/state.yaml` template format591592Generated during Step 4 of migration. Regenerate from scratch in bigpowers YAML format. The **handoff block is mandatory**:593594```yaml595active_flow: null596active_epic_id: null597active_story_id: null598completed_epic: false599600epic_cycle:601 current_step: null602 next_skill: null603 story_bcps: null604 completed_steps: []605 audit_result: null606607bug_cycle:608 current_step: null609 completed_steps: []610611release:612 target_version: null613 last_tag: null614 last_publish: null615 ci_verified: false616617metrics:618 story_start: null619 story_end: null620 cycle_minutes: null621 bcp_per_hour: null622623git:624 branch: <current branch>625 hash: <git rev-parse HEAD>626 pushed: false627628handoff:629 last_step_completed: "Migrated from <framework> on <date>"630 open_decisions: [] # Empty if all decisions resolved during migration631 required_reading:632 - specs/product/VISION_LATEST.yaml633 - specs/product/SCOPE_LATEST.yaml634 - specs/tech-architecture/TECH_STACK_LATEST.md635 - specs/release-plan.yaml636 next_skill: survey-context637638two_pass_spec: # Optional: only if user activates two-pass spec writing gate639 journey_pass: pending640 technical_pass: pending641 approved_at: null642```643644---645646## Reference block 1647648```649Detected: GSD650Found:651 ✓ .planning/ROADMAP.md652 ✓ .planning/REQUIREMENTS.md (12 REQ-XX items)653 ✓ .planning/state.yaml654 ✓ .planning/phases/01-auth/01-CONTEXT.md655 ✗ .planning/METHODOLOGY.md (not present)656657Skipping:658 .planning/phases/01-auth/01-01-SUMMARY.md (execution record; archived only)659660Proceed with migration? [yes / skip <artifact> / abort]661```662663---664665## Reference block 2666667```yaml668# CORRECT — first-class id: field669in_scope:670 - id: REQ-001671 description: "User can register with email/password"672 source: "REQUIREMENTS.md"673674# DEPRECATED — comment-only675in_scope:676 - "User can register with email/password" # REQ-001677```678679---680681## Reference block 3682683```yaml684trace:685 - id: FR-001686 type: functional_requirement687 description: "User can register with email/password"688 epic: e02-auth-ui689 story: e02s01690 verify: "grep -q 'FR-001' specs/product/SCOPE_LATEST.yaml && echo OK"691 - id: UJ-001692 type: user_journey693 description: "New user completes registration flow"694 epic: e02-auth-ui695 story: e02s01696```697698---699700## Reference block 4701702```yaml703active_flow: null704active_epic_id: null705active_story_id: null706707# ... other state fields ...708709handoff:710 last_step_completed: "Migrated from <framework> on <date>"711 open_decisions:712 - "decision text here"713 required_reading:714 - specs/product/VISION_LATEST.yaml715 - specs/product/SCOPE_LATEST.yaml716 - specs/tech-architecture/TECH_STACK_LATEST.md717 - specs/release-plan.yaml718 next_skill: survey-context719```720721---722723## Reference block 5724725```markdown726# Migration Audit — <project-name> from <framework>727728**Date:** <ISO 8601 timestamp>729**Status:** Pass / Fail with findings730731## Findings732733### High Priority734- Artifact: specs/epics/e02-auth-ui/epic.yaml735 Finding: No verify: commands in story tasks736 Recommendation: Add `verify:` to each task before develop-tdd737738### Information739- Count of TODO markers: 3 (normal for fresh migration)740```741742---743744## Reference block 6745746```747Which lenses to include in specs/tech-architecture/METHODOLOGY_LATEST.md?748749[x] Cost of Delay (CD3) — Priority & trade-off assessment750[ ] STRIDE — Security threat modeling751[ ] F.I.R.S.T — Test quality principles752[ ] Bayesian Updating — Probabilistic decision-making753[ ] OWASP Top 10 — Web security framework754```755756---757758### Step 7 — Post-migration: Optional two-pass spec writing gate759760After Steps 1–6, offer the user an optional two-pass spec writing workflow (spec-kit learning):761762Prompt: "Use two-pass spec writing (user journeys first, then technical)? [yes / no]"763764If **yes**, initialize the gate in `specs/state.yaml`:765766```yaml767two_pass_spec:768 journey_pass: pending769 technical_pass: pending770 approved_at: null771```772773The journey pass must be marked "complete" by the user (after stakeholder approval of user-journey specs) before the technical pass begins:774775```yaml776two_pass_spec:777 journey_pass: complete778 approved_at: "2026-06-26T12:00:00Z"779 technical_pass: pending780```781782Inform 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."783784If **no**, skip the two-pass gate. Proceed directly to plan-work.785786→ verify: `grep -q 'two_pass_spec:' specs/state.yaml && echo "two-pass gate initialized" || echo "two-pass gate not activated"`787788789---790791### Step 8 — Post-migration: Optional methodology doc template792793After Steps 1–7, offer the user an optional analytical framework scaffold (GSD learning):794795Prompt: "Create a methodology doc? [yes / no]"796797If **yes**, present a checklist of analytical lenses:798799```800Which lenses to include in specs/tech-architecture/METHODOLOGY_LATEST.md?801802[x] Cost of Delay (CD3) — Priority & trade-off assessment803[ ] STRIDE — Security threat modeling804[ ] F.I.R.S.T — Test quality principles805[ ] Bayesian Updating — Probabilistic decision-making806[ ] OWASP Top 10 — Web security framework807```808809Copy the template from `migrate-spec/templates/METHODOLOGY_LATEST.md` to `specs/tech-architecture/METHODOLOGY_LATEST.md`.810- Active lenses remain uncommented811- Unselected lenses are left commented out812- Populate `{{project_name}}` with the migrated project's name813814If **no**, skip. Add note to handoff: "Methodology doc: skipped — can be added later via `cp migrate-spec/templates/METHODOLOGY_LATEST.md specs/tech-architecture/`"815816→ verify: `test -f specs/tech-architecture/METHODOLOGY_LATEST.md && echo "methodology doc created" || echo "methodology doc skipped"`817818---819820821---822823## Artifact Mapping Summary824825Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE.md](./REFERENCE.md) (spec-kit, BMAD, learnings).826827| Source | Target |828|--------|--------|829| GSD `ROADMAP.md` | `specs/release-plan.yaml + epic shards` |830| GSD `REQUIREMENTS.md` | `specs/product/SCOPE_LATEST.yaml` |831| GSD `CONTEXT.md` (phases) | `specs/tech-architecture/tech-stack.md` + `specs/adr/` |832| GSD `PLAN.md` | `specs/epics/eNN-slug/epic.yaml` (tasks with verify in `-tasks.yaml`) |833| GSD `METHODOLOGY.md` | `specs/tech-architecture/tech-stack.md` |834| spec-kit `spec.md` | `specs/product/SCOPE_LATEST.yaml` + `specs/tech-architecture/tech-stack.md` |835| spec-kit `plan.md` | `specs/tech-architecture/tech-stack.md` + `specs/release-plan.yaml` + `specs/epics/` |836| spec-kit `tasks.md` | `specs/epics/ (see slice-tasks)` |837| BMAD `prd.md` | `specs/product/SCOPE_LATEST.yaml` |838| BMAD `architecture.md` | `specs/tech-architecture/tech-stack.md` + `specs/adr/` |839| BMAD `epic-*.md` | `specs/release-plan.yaml + epic shards` |840| BMAD `story-*.md` | `specs/epics/ (see slice-tasks)` |841| BMAD `project-context.md` | `CLAUDE.md` (append project-specific section) |842| BMAD `decision-log.md` | `specs/adr/` (one ADR per logged decision) |843844---845846847---848849## Rules850851- **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.852- **Never merge contradictory docs** — if source has both `CONTEXT.md` and `architecture.md`, create sections in bigpowers `CONTEXT.md`; don't collapse them.853- **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`.854- **state.yaml is always regenerated** — never migrate source STATE verbatim; bigpowers state.yaml needs its own format.855- **specs/ is the only output location** — no files are created outside `specs/` and `CLAUDE.md`.856857---858859### Step 5 — Surface learnings (optional)860861After migration, offer the user a brief analysis of what the source framework did that bigpowers doesn't have yet.862863Use the learnings table from [REFERENCE.md](./REFERENCE.md#learnings-to-adopt). Present as checkboxes so the user can decide which to adopt.864865→ verify: `grep -c "\- \[ \]" specs/state.yaml 2>/dev/null && echo "pending items recorded" || echo "no pending items in state.yaml"`866867868---869870### Step 6 — Adversarial review (optional)871872Before 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.873874Prompt: "Run adversarial review of migrated artifacts? [yes / skip]"875876If yes, perform these checks:8778781. **Scan for incomplete markers** — Find TODO, FIXME, MISSING in specs/8792. **Verify every epic has `verify:` commands** — Parse all `eNN-*/epic.yaml` files8803. **Check state.yaml handoff** — Ensure `open_decisions` is documented (even if empty)881882Collect findings and write to `specs/archive/MIGRATION-AUDIT.md`:883884```markdown885# Migration Audit — <project-name> from <framework>886887**Date:** <ISO 8601 timestamp>888**Status:** Pass / Fail with findings889890891---892893## Findings894895### High Priority896- Artifact: specs/epics/e02-auth-ui/epic.yaml897 Finding: No verify: commands in story tasks898 Recommendation: Add `verify:` to each task before develop-tdd899900### Information901- Count of TODO markers: 3 (normal for fresh migration)902```903904If findings exist, the handoff block should note: "Adversarial review: N findings — see `specs/archive/MIGRATION-AUDIT.md`"905906If skip is chosen, add to handoff: "Adversarial review: skipped — review manually before plan-work"907908→ verify: `test -f specs/archive/MIGRATION-AUDIT.md && echo "audit completed" || echo "audit skipped or not performed"`909
One repository carrying more than one format is the comparison this product exists for: does anyone actually write different content in each file, or is one a copy of the other?
| Repository | Format | Stack | Covers | Score | Changed |
|---|---|---|---|---|---|
| danielvm-git/bigpowers.cursor/rules/simple-english.mdc · 139 | Cursor rules | styletypesgitdatabase+6 | 47/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/assess-impact.mdc · 139 | Cursor rules | testtesting-strategydeployment | 66/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/audit-plan.mdc · 139 | Cursor rules | buildteststylegit | 74/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/build-epic.mdc · 139 | Cursor rules | buildgit | 58/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/change-request.mdc · 139 | Cursor rules | no sections | 48/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/commit-message.mdc · 139 | Cursor rules | lint-formatstyletypesgit+3 | 82/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/compose-workflow.mdc · 139 | Cursor rules | styledo-notagent-behaviour | 65/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/context7-mcp.mdc · 139 | Cursor rules | style | 54/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/deepen-architecture.mdc · 139 | Cursor rules | testtesting-strategydo-not | 57/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/define-language.mdc · 139 | Cursor rules | lint-formatdo-not | 65/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/define-success.mdc · 139 | Cursor rules | no sections | 4/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/delegate-task.mdc · 139 | Cursor rules | git | 62/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/deploy.mdc · 139 | Cursor rules | setupbuildtestdeployment | 77/100 | 14 days ago | |
| danielvm-git/bigpowers.windsurf/rules/verify-work.md · 139 | Windsurf rules | buildtestlint-formatagent-behaviour | 74/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/develop-tdd.mdc · 139 | Cursor rules | teststylearchtesting-strategy+5 | 85/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/diagnose-root.mdc · 139 | Cursor rules | no sections | 39/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/diagnose-stall.mdc · 139 | Cursor rules | no sections | 44/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/dispatch-agents.mdc · 139 | Cursor rules | git | 54/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/edit-document.mdc · 139 | Cursor rules | no sections | 39/100 | 14 days ago | |
| danielvm-git/bigpowers.cursor/rules/elaborate-spec.mdc · 139 | Cursor rules | test | 58/100 | 14 days ago |
Same format, overlapping stack, ranked by quality.
| Repository | Format | Stack | Covers | Score | Changed |
|---|---|---|---|---|---|
| danielvm-git/bigpowers.windsurf/rules/organize-workspace.md · 139 | Windsurf rules | buildstylegitdeployment+2 | 89/100 | 14 days ago | |
| danielvm-git/bigpowers.windsurf/rules/guard-git.md · 139 | Windsurf rules | stylearchgitsecurity+2 | 89/100 | 14 days ago | |
| danielvm-git/bigpowers.windsurf/rules/quick-fix.md · 139 | Windsurf rules | teststylegitdeployment+1 | 85/100 | 14 days ago | |
| danielvm-git/bigpowers.windsurf/rules/develop-tdd.md · 139 | Windsurf rules | teststylearchtesting-strategy+5 | 85/100 | 14 days ago | |
| danielvm-git/bigpowers.windsurf/rules/extract-design.md · 139 | Windsurf rules | lint-formatstyledependenciesui | 82/100 | 14 days ago | |
| danielvm-git/bigpowers.windsurf/rules/commit-message.md · 139 | Windsurf rules | lint-formatstyletypesgit+3 | 82/100 | 14 days ago | |
| danielvm-git/bigpowers.windsurf/rules/session-state.md · 139 | Windsurf rules | lint-formatstyleagent-behaviour | 82/100 | 14 days ago | |
| danielvm-git/bigpowers.windsurf/rules/setup-environment.md · 139 | Windsurf rules | setupstylesecuritydo-not+1 | 81/100 | 14 days ago |
A badge carrying the measured quality of the strongest agent config file in this repository, out of 100. It reads from this index every time somebody loads your page, so it changes when the measurement changes and there is nothing to keep up to date. Free, no account, and the value is not something you or we can set by hand.
[](https://rulestack.kynth.studio/configs/danielvm-git-bigpowers-windsurf-rules-migrate-spec)Would rather not hotlink us? Every badge is also served in shields.io’s endpoint schema, so shields renders the image and your readers never talk to our domain:
Published by Toolproof, the masthead over this index and eight others. The method behind the number is at toolproof.kynth.studio/methodology, and the whole thing is readable as JSON with no key at /api.