bigpowers 2.34.1 → 2.34.2

package/.pi/prompts/migrate-spec.md

@@ -46,20 +46,7 @@ If none found: ask the user which framework before proceeding.
 
 List every artifact found matching the detected framework. Present the list to the user:
 
-```
-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]
-```
+See [REFERENCE.md](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`
 
@@ -75,17 +62,7 @@ Apply the mapping from [REFERENCE.md](./REFERENCE.md) and [REFERENCE-GSD.md](./R
 
 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:
 
-```yaml
-# 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
-```
+See [REFERENCE.md](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.
 
@@ -97,20 +74,7 @@ See [REFERENCE.md — in_scope format with ID tracking](./REFERENCE.md#in_scope-
 
 When source has FR-XX or UJ-XX IDs, emit `specs/product/REQUIREMENTS_TRACE.yaml` for end-to-end requirement traceability:
 
-```yaml
-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
-```
+See [REFERENCE.md](REFERENCE.md) — `trace:...`
 
 **Existing trace file:** If `REQUIREMENTS_TRACE.yaml` already exists, prompt: "REQUIREMENTS_TRACE.yaml exists. [overwrite / merge / skip]"
 
@@ -128,170 +92,14 @@ See [REFERENCE.md — REQUIREMENTS_TRACE.yaml format](./REFERENCE.md#requirement
 
 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:
 
-```yaml
-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
-```
+See [REFERENCE.md](REFERENCE.md) — `active_flow: null...`
 
 If no open decisions were found during migration, the `open_decisions` list may be empty with an explanatory comment:
 
-```yaml
-handoff:
-  last_step_completed: "..."
-  open_decisions: []  # None — all decisions resolved during migration
-  required_reading: [...]
-  next_skill: survey-context
-```
+See [REFERENCE.md](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"`
 
-### 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](./REFERENCE.md#learnings-to-adopt). 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`:
-
-```markdown
-# 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"`
-
-### 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`:
-
-```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:
-
-```yaml
-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](./REFERENCE-GSD.md) (GSD) · [REFERENCE.md](./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.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`.
-
 ---
 
 # migrate-spec Reference — GSD
@@ -428,6 +236,8 @@ These GSD artifacts are not migrated — they are execution records, not plannin
 
 ---
 
+# Migrate Spec — Reference
+
 # migrate-spec Reference — spec-kit, BMAD, Learnings
 
 Transformation rules for spec-kit and BMAD projects, plus learnings to adopt and output formats.
@@ -762,3 +572,269 @@ two_pass_spec:  # Optional: only if user activates two-pass spec writing gate
   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
+
+```yaml
+# 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
+
+```yaml
+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
+
+```yaml
+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
+
+```markdown
+# 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`:
+
+```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:
+
+```yaml
+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](./REFERENCE-GSD.md) (GSD) · [REFERENCE.md](./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.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](./REFERENCE.md#learnings-to-adopt). 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`:
+
+```markdown
+# 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"`