bigpowers 2.30.0 → 2.31.0

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.30.0",
+  "version": "2.31.0",
   "description": "70 skills — 61 agent skills for spec-driven, test-first software development by solo developers",
   "keywords": [
     "pi-package"

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

@@ -126,19 +126,38 @@ See [REFERENCE.md — REQUIREMENTS_TRACE.yaml format](./REFERENCE.md#requirement
 
 ### Step 4 — Generate state.yaml
 
-Always regenerate `specs/state.yaml` from scratch in bigpowers format (see REFERENCE.md for template):
+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:
 
-```markdown
-# Session State: <project name>
-## Current Milestone
-Migrated from <framework> on <date>. Next: review generated specs and run plan-work.
-## Pending Releases
-- [ ] Review migrated specs
-- [ ] Run elaborate-spec to validate scope
-- [ ] Run plan-work to produce first release plan
+```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
+```
+
+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
 ```
 
-→ verify: `[ -f specs/state.yaml ] && echo "ok" || echo "MISSING: specs/state.yaml not created"`
+→ 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)
 
@@ -450,7 +469,7 @@ Optional enhancements to offer the user after migration. Present as checkboxes.
 ### From GSD
 
 - [ ] **`specs/tech-architecture/METHODOLOGY_LATEST.md`** — Standing analytical lenses. Agents read before planning.
-- [ ] **`handoff` block in state.yaml** — Last skill, last step, required reading for next session.
+- [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
@@ -559,27 +578,49 @@ metadata:
 
 ### `specs/state.yaml` template format
 
-Generated during Step 4 of migration. Regenerate from scratch in bigpowers format:
-
-```markdown
-# Session State: <project name>
-
-## Current Milestone
-
-Migrated from <framework> on <date>. Next: review generated specs and run plan-work.
-
-## Git Metadata
-
-- **Branch**: <current branch>
-- **Hash**: <git rev-parse HEAD>
+Generated during Step 4 of migration. Regenerate from scratch in bigpowers YAML format. The **handoff block is mandatory**:
 
-## Completed Releases
-
-(none — migration starting point)
-
-## Pending Releases
+```yaml
+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
 
-- [ ] Review migrated specs
-- [ ] Run elaborate-spec to validate scope
-- [ ] Run plan-work to produce first release plan
+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
 ```

package/.pi/skills/migrate-spec/SKILL.md

@@ -128,19 +128,38 @@ See [REFERENCE.md — REQUIREMENTS_TRACE.yaml format](./REFERENCE.md#requirement
 
 ### Step 4 — Generate state.yaml
 
-Always regenerate `specs/state.yaml` from scratch in bigpowers format (see REFERENCE.md for template):
+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:
 
-```markdown
-# Session State: <project name>
-## Current Milestone
-Migrated from <framework> on <date>. Next: review generated specs and run plan-work.
-## Pending Releases
-- [ ] Review migrated specs
-- [ ] Run elaborate-spec to validate scope
-- [ ] Run plan-work to produce first release plan
+```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
+```
+
+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
 ```
 
-→ verify: `[ -f specs/state.yaml ] && echo "ok" || echo "MISSING: specs/state.yaml not created"`
+→ 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)
 
@@ -452,7 +471,7 @@ Optional enhancements to offer the user after migration. Present as checkboxes.
 ### From GSD
 
 - [ ] **`specs/tech-architecture/METHODOLOGY_LATEST.md`** — Standing analytical lenses. Agents read before planning.
-- [ ] **`handoff` block in state.yaml** — Last skill, last step, required reading for next session.
+- [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
@@ -561,27 +580,49 @@ metadata:
 
 ### `specs/state.yaml` template format
 
-Generated during Step 4 of migration. Regenerate from scratch in bigpowers format:
-
-```markdown
-# Session State: <project name>
-
-## Current Milestone
-
-Migrated from <framework> on <date>. Next: review generated specs and run plan-work.
-
-## Git Metadata
-
-- **Branch**: <current branch>
-- **Hash**: <git rev-parse HEAD>
+Generated during Step 4 of migration. Regenerate from scratch in bigpowers YAML format. The **handoff block is mandatory**:
 
-## Completed Releases
-
-(none — migration starting point)
-
-## Pending Releases
+```yaml
+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
 
-- [ ] Review migrated specs
-- [ ] Run elaborate-spec to validate scope
-- [ ] Run plan-work to produce first release plan
+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
 ```

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [2.31.0](https://github.com/danielvm-git/bigpowers/compare/v2.30.0...v2.31.0) (2026-06-26)
+
+
+### Features
+
+* **migrate-spec:** make handoff block mandatory in Step 4 output ([1f05663](https://github.com/danielvm-git/bigpowers/commit/1f0566320356d8de4d3c2775ddebc3b17cf27fe6))
+
 # [2.30.0](https://github.com/danielvm-git/bigpowers/compare/v2.29.0...v2.30.0) (2026-06-26)
 
 

package/COMMIT-MESSAGE.md

@@ -0,0 +1,34 @@
+# Proposed Commit Message
+
+## Type and Scope
+`feat(migrate-spec)` — Minor version bump
+
+## Title
+```
+feat(migrate-spec): make handoff block mandatory in Step 4 output
+```
+
+## Body
+```
+The handoff block (last_step_completed, open_decisions, required_reading,
+next_skill) is now a mandatory part of state.yaml generation, not optional.
+
+During real migrations, the handoff block proved immediately useful — the next
+agent reads it first to understand context, decisions, and required reading.
+Promoting it from optional to mandatory ensures every migration output includes
+this metadata.
+
+Changes:
+- SKILL.md Step 4: updated to mandate handoff block with YAML format example
+- REFERENCE.md: added complete state.yaml YAML template with handoff structure
+- Learnings table: marked handoff as adopted (from GSD learning set)
+```
+
+## Release Impact
+- **Bump Type:** `minor` (X.Y.z)
+- **Rationale:** New mandatory output structure in migrate-spec skill
+
+## Notes
+- Documentation-only change (no code changes)
+- All verify commands pass
+- Audit gate: PASS (10/10 items)

package/SKILL-INDEX.md

@@ -3,7 +3,7 @@
 > **DO NOT EDIT** — This file is auto-generated by `scripts/generate-skill-index.sh`.
 > Edit `SKILL.md` source files or `skills-lock.json` instead. Run `bash scripts/sync-skills.sh` to regenerate.
 
-**Generated:** 2026-06-26T22:23:41Z
+**Generated:** 2026-06-26T22:57:50Z
 **Skills:** 70
 
 ---

package/migrate-spec/REFERENCE.md

@@ -133,7 +133,7 @@ Optional enhancements to offer the user after migration. Present as checkboxes.
 ### From GSD
 
 - [ ] **`specs/tech-architecture/METHODOLOGY_LATEST.md`** — Standing analytical lenses. Agents read before planning.
-- [ ] **`handoff` block in state.yaml** — Last skill, last step, required reading for next session.
+- [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
@@ -242,27 +242,49 @@ metadata:
 
 ### `specs/state.yaml` template format
 
-Generated during Step 4 of migration. Regenerate from scratch in bigpowers format:
+Generated during Step 4 of migration. Regenerate from scratch in bigpowers YAML format. The **handoff block is mandatory**:
 
-```markdown
-# Session State: <project name>
-
-## Current Milestone
-
-Migrated from <framework> on <date>. Next: review generated specs and run plan-work.
-
-## Git Metadata
-
-- **Branch**: <current branch>
-- **Hash**: <git rev-parse HEAD>
-
-## Completed Releases
-
-(none — migration starting point)
-
-## Pending Releases
-
-- [ ] Review migrated specs
-- [ ] Run elaborate-spec to validate scope
-- [ ] Run plan-work to produce first release plan
+```yaml
+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
 ```

package/migrate-spec/SKILL.md

@@ -129,19 +129,38 @@ See [REFERENCE.md — REQUIREMENTS_TRACE.yaml format](./REFERENCE.md#requirement
 
 ### Step 4 — Generate state.yaml
 
-Always regenerate `specs/state.yaml` from scratch in bigpowers format (see REFERENCE.md for template):
-
-```markdown
-# Session State: <project name>
-## Current Milestone
-Migrated from <framework> on <date>. Next: review generated specs and run plan-work.
-## Pending Releases
-- [ ] Review migrated specs
-- [ ] Run elaborate-spec to validate scope
-- [ ] Run plan-work to produce first release plan
+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
+```
+
+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
 ```
 
-→ verify: `[ -f specs/state.yaml ] && echo "ok" || echo "MISSING: specs/state.yaml not created"`
+→ 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)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.30.0",
+  "version": "2.31.0",
   "description": "61 agent skills for spec-driven, test-first software development by solo developers",
   "main": "index.js",
   "scripts": {

package/skills-lock.json

@@ -163,7 +163,7 @@
     },
     "migrate-spec": {
       "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.",
-      "sha256": "72006537bb12ab1a",
+      "sha256": "897baa6f0f37ea68",
       "path": "migrate-spec/SKILL.md"
     },
     "model-domain": {