bigpowers 2.34.1 → 2.35.0

package/migrate-spec/SKILL.md

@@ -49,20 +49,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`
 
@@ -78,17 +65,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.
 
@@ -100,20 +77,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]"
 
@@ -131,168 +95,10 @@ 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`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bigpowers",
-  "version": "2.34.1",
-  "description": "61 agent skills for spec-driven, test-first software development by solo developers",
+  "version": "2.35.0",
+  "description": "70 agent skills for spec-driven, test-first software development by solo developers",
   "main": "index.js",
   "scripts": {
     "compliance": "bash scripts/audit-compliance.sh specs/verifications/features && bash scripts/validate-doctrine.sh",

package/publish-package/REFERENCE.md

@@ -0,0 +1,239 @@
+# Publish Package — Reference
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Verify prerequisites and show publish command without executing |
+| `--registry <type>` | Force registry type (skip auto-detection) |
+| `--otp <code>` | One-time password for npm 2FA |
+| `--no-verify` | Skip prerequisite checks (use with caution) |
+
+
+---
+
+## Examples
+
+### Publish an npm package
+
+```bash
+# Verify first
+publish-package --dry-run
+
+# Publish
+publish-package
+
+# Output:
+#   [npm] Publishing my-package v0.4.0...
+#   OK: npm publish confirmed (my-package@0.4.0 on registry)
+```
+
+### Publish a Rust crate
+
+```bash
+export CARGO_REGISTRY_TOKEN=<token>
+publish-package --dry-run
+publish-package
+```
+
+### Missing token scenario
+
+```bash
+$ publish-package
+FAIL: NPM_TOKEN not set. Set via: export NPM_TOKEN=<token> or add to .npmrc
+```
+
+
+---
+
+## Integration with release-branch
+
+When wired into `release-branch`, add a step after git push:
+
+```
+6a. Run publish-package to publish to package registries
+    → verify: publish-package --dry-run && publish-package
+```
+
+---
+
+## Reference block 1
+
+```bash
+# Check auth token exists
+if [ -z "${NPM_TOKEN:-}" ]; then
+  if [ ! -f ~/.npmrc ] || ! grep -q "_authToken" ~/.npmrc; then
+    echo "FAIL: NPM_TOKEN not set. Set via: export NPM_TOKEN=<token> or add //registry.npmjs.org/:_authToken=<token> to .npmrc"
+    exit 1
+  fi
+fi
+
+# Check version not already published
+PACKAGE_NAME=$(node -p "require('./package.json').name")
+CURRENT_VER=$(node -p "require('./package.json').version")
+if npm view "$PACKAGE_NAME@$CURRENT_VER" version 2>/dev/null; then
+  echo "FAIL: Version $CURRENT_VER already published for $PACKAGE_NAME. Bump version first."
+  exit 1
+fi
+
+# Check build artifacts are fresh
+if [ -d dist ] || [ -d lib ]; then
+  LATEST_BUILD=$(find dist lib 2>/dev/null -name "*.js" -o -name "*.cjs" -o -name "*.mjs" | xargs ls -t 2>/dev/null | head -1)
+  PACKAGE_MODIFIED=$(stat -f %m package.json 2>/dev/null || stat -c %Y package.json 2>/dev/null)
+  if [ -n "$LATEST_BUILD" ] && [ -n "$PACKAGE_MODIFIED" ]; then
+    BUILD_TIME=$(stat -f %m "$LATEST_BUILD" 2>/dev/null || stat -c %Y "$LATEST_BUILD" 2>/dev/null)
+    if [ "$BUILD_TIME" -lt "$PACKAGE_MODIFIED" ]; then
+      echo "WARNING: Build artifacts may be stale (package.json modified after last build). Run npm run build first."
+    fi
+  fi
+fi
+
+# Check CHANGELOG is updated
+if [ -f CHANGELOG.md ]; then
+  if ! grep -q "$CURRENT_VER" CHANGELOG.md 2>/dev/null; then
+    echo "WARNING: Version $CURRENT_VER not found in CHANGELOG.md. Update changelog before publish."
+  fi
+fi
+```
+
+---
+
+## Reference block 2
+
+```bash
+# Check auth token exists
+if [ -z "${CARGO_REGISTRY_TOKEN:-}" ]; then
+  if [ ! -f ~/.cargo/config.toml ] || ! grep -q "token" ~/.cargo/config.toml; then
+    echo "FAIL: CARGO_REGISTRY_TOKEN not set. Set via: export CARGO_REGISTRY_TOKEN=<token> or add to ~/.cargo/config.toml"
+    exit 1
+  fi
+fi
+
+# Check version not already published
+CRATE_NAME=$(grep '^name' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
+CURRENT_VER=$(grep '^version' Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
+if cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_VER\""; then
+  echo "FAIL: Version $CURRENT_VER already published for $CRATE_NAME. Bump version in Cargo.toml first."
+  exit 1
+fi
+```
+
+---
+
+## Reference block 3
+
+```bash
+# Check auth token exists
+if [ -z "${TWINE_PASSWORD:-}" ] && [ -z "${POETRY_PYPI_TOKEN_PYPI:-}" ]; then
+  if [ ! -f ~/.pypirc ]; then
+    echo "FAIL: PyPI token not configured. Set TWINE_PASSWORD or create ~/.pypirc"
+    exit 1
+  fi
+fi
+
+# Check for build artifacts
+if [ ! -d dist ] || [ -z "$(ls dist/*.whl 2>/dev/null)" ]; then
+  echo "WARNING: No .whl files found in dist/. Run: python -m build"
+fi
+```
+
+---
+
+## Reference block 4
+
+```bash
+# npm
+npm publish --access public
+
+# crates.io
+cargo publish
+
+# PyPI
+python -m twine upload dist/*  # or: poetry publish
+
+# Homebrew (opens PR, does not publish directly)
+brew bump-formula-pr --url=<tarball-url> <formula-name>
+```
+
+---
+
+## Reference block 5
+
+```bash
+# npm
+npm view "$PACKAGE_NAME" versions --json 2>/dev/null | grep -q "\"$CURRENT_VER\"" && echo "OK: npm publish confirmed"
+
+# crates.io
+cargo search "$CRATE_NAME" 2>/dev/null | grep -q "^${CRATE_NAME}.*\"$CURRENT_VER\"" && echo "OK: crates.io publish confirmed"
+
+# PyPI
+pip index versions "$PACKAGE_NAME" 2>/dev/null | grep -q "$CURRENT_VER" && echo "OK: PyPI publish confirmed"
+```
+
+---
+
+## Reference block 6
+
+```bash
+# Generic failure handler
+if [ $? -ne 0 ]; then
+  case "$REGISTRY" in
+    npm)
+      echo "FAIL: npm publish failed."
+      echo "  Common causes:"
+      echo "  - NPM_TOKEN not set in secrets: add to GitHub repo secrets"
+      echo "  - Version already published: bump version in package.json"
+      echo "  - Two-factor auth required: use --otp=<code> flag"
+      echo "  - Package scoped but not public: add --access public"
+      ;;
+    crates.io)
+      echo "FAIL: cargo publish failed."
+      echo "  Common causes:"
+      echo "  - CARGO_REGISTRY_TOKEN not configured: see ~/.cargo/config.toml"
+      echo "  - Version already published: bump version in Cargo.toml"
+      echo "  - Local changes not committed: cargo publish requires clean working tree"
+      ;;
+    pypi)
+      echo "FAIL: PyPI publish failed."
+      echo "  Common causes:"
+      echo "  - TWINE_PASSWORD not configured: set env var or ~/.pypirc"
+      echo "  - Build artifacts missing: run python -m build first"
+      echo "  - Version conflict: version already exists on PyPI"
+      ;;
+  esac
+  exit 1
+fi
+```
+
+---
+
+## Reference block 7
+
+```bash
+# Example output
+$ publish-package --dry-run
+
+[DRY-RUN] Detected package type: npm
+[DRY-RUN] Package: my-package v0.4.0
+[DRY-RUN] Checking NPM_TOKEN... OK
+[DRY-RUN] Checking version 0.4.0 not already published... OK
+[DRY-RUN] Checking build artifacts... WARNING: package.json modified after build
+[DRY-RUN] Checking CHANGELOG... OK
+[DRY-RUN] Would run: npm publish --access public
+[DRY-RUN] Exiting without publishing.
+```
+
+---
+
+## Reference block 8
+
+```bash
+# npm dry-run
+npm publish --access public --dry-run
+
+# crates.io dry-run (cargo does not have a publish dry-run; use --dry-run flag for validation only)
+cargo package --list 2>/dev/null
+
+# PyPI dry-run
+python -m twine upload --repository testpypi dist/*  # test.pypi.org
+```