@pennyfarthing/core 10.4.0 → 11.0.0

package/pennyfarthing-dist/workflows/quick-spec/tech-spec-template.md

@@ -0,0 +1,74 @@
+---
+title: '{title}'
+slug: '{slug}'
+created: '{date}'
+status: 'in-progress'
+stepsCompleted: []
+tech_stack: []
+files_to_modify: []
+code_patterns: []
+test_patterns: []
+---
+
+# Tech-Spec: {title}
+
+**Created:** {date}
+
+## Overview
+
+### Problem Statement
+
+{problem_statement}
+
+### Solution
+
+{solution}
+
+### Scope
+
+**In Scope:**
+{in_scope}
+
+**Out of Scope:**
+{out_of_scope}
+
+## Context for Development
+
+### Codebase Patterns
+
+{codebase_patterns}
+
+### Files to Reference
+
+| File | Purpose |
+| ---- | ------- |
+
+{files_table}
+
+### Technical Decisions
+
+{technical_decisions}
+
+## Implementation Plan
+
+### Tasks
+
+{tasks}
+
+### Acceptance Criteria
+
+{acceptance_criteria}
+
+## Additional Context
+
+### Dependencies
+
+{dependencies}
+
+### Testing Strategy
+
+{testing_strategy}
+
+### Notes
+
+{notes}

package/pennyfarthing-dist/workflows/quick-spec/workflow.yaml

@@ -0,0 +1,35 @@
+# quick-spec Workflow - Adapted from BMAD format
+# Conversational spec engineering - ask questions, investigate code, produce implementation-ready tech-spec.
+#
+# Flow: Understand → Investigate → Generate → Review
+# Companion to quick-dev: spec first, then dev.
+
+workflow:
+  name: quick-spec
+  description: Conversational spec engineering - ask questions, investigate code, produce implementation-ready tech-spec.
+  version: "1.0.0"
+  type: stepped
+
+  # Step configuration
+  steps:
+    path: ./steps/
+    pattern: step-*.md
+
+  # Variables available in step files
+  variables:
+    project_root: .
+    planning_artifacts: sprint/planning/
+    implementation_artifacts: sprint/planning/
+    output_file: sprint/planning/tech-spec-wip.md
+    quick_dev_workflow: '{project_root}/.pennyfarthing/workflows/quick-dev/workflow.yaml'
+
+  # Output template
+  template: ./tech-spec-template.md
+
+  # Agent assignment
+  agent: architect
+
+  # Triggers - when to suggest this workflow
+  triggers:
+    types: [quick-spec, tech-spec, spec]
+    tags: [quick-spec, stepped]

package/pennyfarthing-dist/workflows/release/steps/step-01-preflight.md

@@ -55,21 +55,56 @@ CURRENT_VERSION=$(cat VERSION)
 echo "Current version: $CURRENT_VERSION"
 ```
 
+**Detect if current version is already a prerelease:**
+
+```bash
+if [[ "$CURRENT_VERSION" == *-* ]]; then
+    PRERELEASE_TAG="${CURRENT_VERSION#*-}"  # e.g., "alpha.0"
+    BASE_VERSION="${CURRENT_VERSION%%-*}"   # e.g., "10.4.0"
+    echo "Current version is a prerelease: $CURRENT_VERSION (base: $BASE_VERSION)"
+fi
+```
+
 Ask user: **What type of release?**
+
+**If current version is stable (no prerelease suffix):**
 - `patch` — bug fixes (x.y.Z)
 - `minor` — new features (x.Y.0)
 - `major` — breaking changes (X.0.0)
+- `prepatch` — prerelease for next patch (x.y.Z-alpha.0)
+- `preminor` — prerelease for next minor (x.Y.0-alpha.0)
+- `premajor` — prerelease for next major (X.0.0-alpha.0)
+
+**If current version is already a prerelease (e.g., 10.4.0-alpha.0):**
+- `prerelease` — bump prerelease number (x.y.z-alpha.N+1)
+- `promote` — promote to stable (x.y.z, dropping the prerelease suffix)
+- `graduate-beta` — graduate to beta (x.y.z-beta.0)
+- `graduate-rc` — graduate to release candidate (x.y.z-rc.0)
 
 Compute `NEW_VERSION` from bump type.
 
+**For prerelease bumps**, also ask: **Prerelease channel?** (default: `alpha`)
+- `alpha` — early testing, unstable
+- `beta` — feature-complete, testing
+- `rc` — release candidate, final testing
+
+Set `IS_PRERELEASE=true` and `PRERELEASE_CHANNEL` (alpha/beta/rc) for use in later steps.
+
 ### 1.4 Conflict Checks
 
 ```bash
-# Check npm
+# Check npm (prerelease uses dist-tag, but still check exact version)
 npm view @pennyfarthing/core@$NEW_VERSION version 2>/dev/null && echo "WARNING: $NEW_VERSION already on npm!"
 
 # Check git tags
 git tag -l "v$NEW_VERSION" | grep -q . && echo "WARNING: Tag v$NEW_VERSION already exists!"
+
+# For prereleases, check what's currently on the dist-tag
+if [[ "$IS_PRERELEASE" == "true" ]]; then
+    echo ""
+    echo "=== Current npm dist-tags ==="
+    npm view @pennyfarthing/core dist-tags 2>/dev/null || echo "(not yet published)"
+fi
 ```
 
 ### 1.5 Preview
@@ -85,16 +120,20 @@ git tag -l "v$NEW_VERSION" | grep -q . && echo "WARNING: Tag v$NEW_VERSION alrea
 | Tag not exists     | ✓/✗    |
 
 **Version:** {CURRENT_VERSION} → {NEW_VERSION}
+**Release type:** {stable | prerelease (alpha/beta/rc)}
 **Tag:** v{NEW_VERSION}
+**npm dist-tag:** {latest | alpha | beta | rc}
 
 **Files to modify:**
 - VERSION
 - package.json
 - packages/*/package.json (all workspace packages)
-- README.md
 - CHANGELOG.md
-- CLAUDE.md
 - package-lock.json (if present)
+{if stable: - README.md, - CLAUDE.md}
+
+**Steps that will be skipped for prerelease:**
+{if prerelease: Steps 4 (README), 5 (CLAUDE.md), 6 (Retro), 8 (Merge to main)}
 ```
 
 ---

package/pennyfarthing-dist/workflows/release/steps/step-02-bump.md

@@ -36,9 +36,10 @@ sed -i '' 's/"version": "{current_version}"/"version": "{new_version}"/' package
 
 ```bash
 # Bump all workspace packages (auto-discovered)
+# Regex handles both stable (x.y.z) and prerelease (x.y.z-tag.N) versions
 for PKG_JSON in packages/*/package.json; do
     if [[ -f "$PKG_JSON" ]]; then
-        sed -i '' -E 's/"version": "[0-9]+\.[0-9]+\.[0-9]+"/"version": "{new_version}"/' "$PKG_JSON"
+        sed -i '' -E 's/"version": "[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?"/"version": "{new_version}"/' "$PKG_JSON"
         echo "Updated $PKG_JSON"
     fi
 done
@@ -46,8 +47,12 @@ done
 
 ### 2.4 Update README.md
 
+**Skip for prerelease** — README should always reflect the latest stable version.
+
 ```bash
-sed -i '' 's/\*\*v{current_version}\*\*/\*\*v{new_version}\*\*/' README.md
+if [[ "$IS_PRERELEASE" != "true" ]]; then
+    sed -i '' 's/\*\*v{current_version}\*\*/\*\*v{new_version}\*\*/' README.md
+fi
 ```
 
 ### 2.5 Update package-lock.json
@@ -81,9 +86,11 @@ git diff --stat
 | `VERSION` | `{new_version}` |
 | `package.json` | `"version": "{new_version}"` |
 | `packages/*/package.json` | `"version": "{new_version}"` (all workspace packages) |
-| `README.md` | Badge updated |
+| `README.md` | Badge updated (stable only) |
 | `CHANGELOG.md` | New version header |
 
+**For prerelease:** README.md should NOT appear in the diff.
+
 ---
 
 <!-- GATE -->

package/pennyfarthing-dist/workflows/release/steps/step-03-changelog.md

@@ -18,7 +18,7 @@ Draft CHANGELOG.md section for the new version, ready for user review.
 
 ## Skill Reference
 
-This step follows the `/changelog` skill patterns. See `pennyfarthing-dist/skills/changelog/SKILL.md` for full reference on:
+This step follows the `/pf-changelog` skill patterns. See `pennyfarthing-dist/skills/changelog/SKILL.md` for full reference on:
 - Keep a Changelog format
 - Conventional commit parsing
 - Version bump decisions

package/pennyfarthing-dist/workflows/release/steps/step-07-commit.md

@@ -30,10 +30,15 @@ git checkout -b "$RELEASE_BRANCH"
 ### 7.2 Stage Files Explicitly
 
 ```bash
-# Root files
-git add VERSION package.json README.md CHANGELOG.md CLAUDE.md
+# Root files (always staged)
+git add VERSION package.json CHANGELOG.md
 [[ -f package-lock.json ]] && git add package-lock.json
 
+# Stable-only files (skip for prerelease)
+if [[ "$IS_PRERELEASE" != "true" ]]; then
+    git add README.md CLAUDE.md
+fi
+
 # All workspace packages (auto-discovered)
 for PKG_JSON in packages/*/package.json; do
     [[ -f "$PKG_JSON" ]] && git add "$PKG_JSON"
@@ -50,8 +55,12 @@ git diff --cached --name-only
 
 echo ""
 echo "=== Verification ==="
-# Check root files are staged
-for f in VERSION package.json README.md CHANGELOG.md CLAUDE.md; do
+# Check root files are staged (prerelease skips README.md and CLAUDE.md)
+ROOT_FILES="VERSION package.json CHANGELOG.md"
+if [[ "$IS_PRERELEASE" != "true" ]]; then
+    ROOT_FILES="$ROOT_FILES README.md CLAUDE.md"
+fi
+for f in $ROOT_FILES; do
     if git diff --cached --name-only | grep -q "^$f$"; then
         echo "  ✓ $f"
     else

package/pennyfarthing-dist/workflows/release/steps/step-08-merge.md

@@ -2,9 +2,18 @@
 
 <purpose>
 Merge develop into main and create the annotated release tag. This prepares everything for push — still local, still reversible.
+
+**For prerelease:** This step is SKIPPED. Alpha/beta/rc releases stay on develop and are tagged there. Main only receives stable releases.
 </purpose>
 
 <instructions>
+**If prerelease (`IS_PRERELEASE=true`):**
+1. Stay on develop (do NOT checkout main)
+2. Create annotated tag on develop with prerelease flag
+3. Show tag info
+4. Auto-continue to push step
+
+**If stable release:**
 1. Checkout main and pull latest
 2. Merge develop into main
 3. Create annotated tag
@@ -17,7 +26,19 @@ Merge summary and tag details. Everything is local — nothing has been pushed y
 
 ## Execution
 
-### 8.1 Update Main
+### 8.0 Prerelease Check
+
+```bash
+if [[ "$IS_PRERELEASE" == "true" ]]; then
+    echo "=== Prerelease — Skipping Merge to Main ==="
+    echo "Prerelease versions stay on develop. Main only receives stable releases."
+    echo ""
+fi
+```
+
+**If prerelease, skip to 8.3 (tag on develop).**
+
+### 8.1 Update Main (stable only)
 
 ```bash
 git checkout main
@@ -27,7 +48,7 @@ git pull origin main --ff-only || {
 }
 ```
 
-### 8.2 Merge Develop
+### 8.2 Merge Develop (stable only)
 
 ```bash
 git merge develop -m "Merge develop into main for release {new_version}"
@@ -49,9 +70,13 @@ echo "Branch: $(git branch --show-current)"
 echo "Tag: $(git tag -l 'v{new_version}')"
 echo "HEAD: $(git log --oneline -1)"
 echo ""
-echo "=== Branches Ahead of Remote ==="
-git log --oneline origin/main..main
-echo "---"
+if [[ "$IS_PRERELEASE" != "true" ]]; then
+    echo "=== Branches Ahead of Remote ==="
+    echo "main:"
+    git log --oneline origin/main..main
+    echo "---"
+fi
+echo "develop:"
 git log --oneline origin/develop..develop
 ```
 
@@ -60,6 +85,6 @@ Everything is local. The next step pushes to the remote — that's the point of
 ---
 
 **[C]** Continue to push
-**[A]** Abort (delete tag, reset main)
+**[A]** Abort (delete tag{if stable: , reset main})
 
 <!-- CYCLIST:CHOICES:C,A -->

package/pennyfarthing-dist/workflows/release/steps/step-09-push.md

@@ -31,11 +31,15 @@ echo "Pushing develop..."
 git push origin develop
 ```
 
-### 9.2 Push Main
+### 9.2 Push Main (stable only)
 
 ```bash
-echo "Pushing main..."
-git push origin main
+if [[ "$IS_PRERELEASE" != "true" ]]; then
+    echo "Pushing main..."
+    git push origin main
+else
+    echo "Skipping main push (prerelease stays on develop only)"
+fi
 ```
 
 ### 9.3 Push Tags
@@ -60,9 +64,11 @@ git ls-remote --tags origin | grep "v{new_version}"
 echo ""
 echo "Remote develop HEAD:"
 git log --oneline origin/develop -1
-echo ""
-echo "Remote main HEAD:"
-git log --oneline origin/main -1
+if [[ "$IS_PRERELEASE" != "true" ]]; then
+    echo ""
+    echo "Remote main HEAD:"
+    git log --oneline origin/main -1
+fi
 ```
 
 ---

package/pennyfarthing-dist/workflows/release/steps/step-10-publish.md

@@ -50,26 +50,41 @@ for PKG_JSON in package.json packages/*/package.json; do
 done
 ```
 
-### 10.3 Publish Root Package (Core)
+### 10.3 Determine npm Dist-Tag
+
+```bash
+if [[ "$IS_PRERELEASE" == "true" ]]; then
+    # Prerelease: publish under the prerelease channel tag (alpha, beta, rc)
+    # This prevents alpha versions from becoming the "latest" tag
+    NPM_TAG="--tag $PRERELEASE_CHANNEL"
+    echo "Publishing as prerelease with dist-tag: $PRERELEASE_CHANNEL"
+else
+    # Stable: publish as "latest" (npm default)
+    NPM_TAG=""
+    echo "Publishing as stable release (latest)"
+fi
+```
+
+### 10.4 Publish Root Package (Core)
 
 ```bash
 echo "Publishing @pennyfarthing/core@{new_version}..."
-npm publish --access public
+npm publish --access public $NPM_TAG
 ```
 
-### 10.4 Publish Workspace Packages
+### 10.5 Publish Workspace Packages
 
 ```bash
 for pkg_dir in packages/cyclist packages/shared packages/themes-*; do
     if [[ -f "$pkg_dir/package.json" ]]; then
         PKG_NAME=$(node -e "console.log(require('./$pkg_dir/package.json').name)")
         echo "Publishing $PKG_NAME@{new_version}..."
-        (cd "$pkg_dir" && npm publish --access public) || echo "WARNING: Failed to publish $PKG_NAME"
+        (cd "$pkg_dir" && npm publish --access public $NPM_TAG) || echo "WARNING: Failed to publish $PKG_NAME"
     fi
 done
 ```
 
-### 10.5 Verify Published
+### 10.6 Verify Published
 
 ```bash
 echo "=== Registry Verification ==="
@@ -81,6 +96,16 @@ for PKG_JSON in package.json packages/*/package.json; do
         && echo "  ✓ $PKG_NAME@{new_version}" \
         || echo "  ✗ $PKG_NAME@{new_version} NOT FOUND"
 done
+
+if [[ "$IS_PRERELEASE" == "true" ]]; then
+    echo ""
+    echo "=== Dist-Tag Verification ==="
+    echo "Checking that 'latest' still points to the stable release..."
+    npm view @pennyfarthing/core dist-tags 2>/dev/null
+    echo ""
+    echo "Users install stable: npm install @pennyfarthing/core"
+    echo "Users install alpha:  npm install @pennyfarthing/core@$PRERELEASE_CHANNEL"
+fi
 ```
 
 ---

package/pennyfarthing-dist/workflows/release/steps/step-11-finalize.md

@@ -22,9 +22,15 @@ Release summary with links to GitHub release, npm packages, and git tag.
 TAG="v{new_version}"
 TODAY=$(date +%Y-%m-%d)
 
+PRERELEASE_FLAG=""
+if [[ "$IS_PRERELEASE" == "true" ]]; then
+    PRERELEASE_FLAG="--prerelease"
+fi
+
 gh release create "$TAG" \
     --title "v{new_version}" \
     --notes "See [CHANGELOG.md](https://github.com/1898andCo/pennyfarthing/blob/main/CHANGELOG.md) for details." \
+    $PRERELEASE_FLAG \
     || echo "WARNING: GitHub release creation failed (may already exist)"
 ```
 
@@ -48,6 +54,8 @@ gh release view "v{new_version}" --json url --jq '.url' 2>/dev/null || echo "  N
 
 ### 11.3 Summary
 
+**For stable release:**
+
 ```
 ╔══════════════════════════════════════╗
 ║       Release {new_version} Complete       ║
@@ -64,6 +72,27 @@ gh release view "v{new_version}" --json url --jq '.url' 2>/dev/null || echo "  N
 ╚══════════════════════════════════════╝
 ```
 
+**For prerelease:**
+
+```
+╔══════════════════════════════════════════╗
+║  Prerelease {new_version} Complete            ║
+╠══════════════════════════════════════════╣
+║                                          ║
+║  Tag:       v{new_version}                    ║
+║  npm tag:   {prerelease_channel}              ║
+║  npm:       @pennyfarthing/core          ║
+║             @pennyfarthing/cyclist       ║
+║  GitHub:    (prerelease URL)             ║
+║                                          ║
+║  Branch pushed: develop (main unchanged) ║
+║  Current branch: develop                 ║
+║                                          ║
+║  Install: npm i @pennyfarthing/core@{channel} ║
+║                                          ║
+╚══════════════════════════════════════════╝
+```
+
 ---
 
 Release workflow complete. All systems updated.

package/pennyfarthing-dist/workflows/release.yaml

@@ -31,6 +31,13 @@ workflow:
     version_file: VERSION
     project_root: .
     packages: "core cyclist shared themes-comedy themes-literary themes-mythology-fantasy themes-prestige-tv themes-realistic themes-scifi themes-superheroes"
+    # Set during preflight based on user choice:
+    # IS_PRERELEASE: "true" | "false"
+    # PRERELEASE_CHANNEL: "alpha" | "beta" | "rc" (only when IS_PRERELEASE=true)
+    # These control conditional behavior in steps 2, 4, 5, 6, 7, 8, 9, 10, 11
+
+  # Steps skipped for prerelease
+  prerelease_skip_steps: [4, 5, 6, 8]  # README, CLAUDE.md, Retro, Merge to main
 
   # User approval gates
   gates: