Merge pull request #578 from Oloodi/577-mobile-define-and-automate-release-and-tagging-strategy-for-client-staff-apps

Defined and automate release and tagging strategy for client staff apps

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,101 @@
+## 📋 Description
+
+<!-- Provide a clear and concise description of your changes -->
+
+
+---
+
+## 🎯 Type of Change
+
+<!-- Mark the relevant option with an "x" -->
+
+- [ ] 🐛 **Bug fix** (non-breaking change that fixes an issue)
+- [ ] ✨ **Feature** (non-breaking change that adds functionality)
+- [ ] 📝 **Documentation** (changes to docs, comments, or README)
+- [ ] 🔧 **Refactor** (code change that doesn't affect functionality)
+- [ ] ⚡ **Performance** (improvement in performance or optimization)
+- [ ] 🔐 **Security** (security fix or improvement)
+- [ ] 🎨 **Style** (formatting, linting, or minor code style changes)
+- [ ] 🏗️ **Architecture** (significant structural changes)
+
+---
+
+## 📦 Affected Areas
+
+<!-- Mark the relevant areas that were modified -->
+
+- [ ] 📱 **Mobile** (Flutter - Client/Worker app)
+- [ ] 🌐 **Web** (React Dashboard)
+- [ ] 🔌 **Backend** (APIs, Data Connect, Cloud Functions)
+- [ ] 🗄️ **Database** (Schema changes, migrations)
+- [ ] 🚀 **CI/CD** (GitHub Actions, deployment configs)
+- [ ] 📚 **Documentation** (Docs, onboarding guides)
+
+---
+
+## 🔗 Related Issues
+
+<!-- Link any related issues using #issue_number -->
+
+Closes #
+Related to #
+
+---
+
+## ✅ Testing
+
+<!-- Describe how you tested these changes -->
+
+**Test Details:**
+<!-- Provide specific test cases or scenarios -->
+
+
+---
+
+## 🔄 Breaking Changes
+
+<!-- Are there any breaking changes? If yes, describe them -->
+
+- [ ] No breaking changes
+- [ ] Yes, breaking changes:
+
+**Details:**
+<!-- Describe migration path or deprecation period if applicable -->
+
+
+---
+
+## 🎯 Checklist
+
+<!-- Complete this before requesting review -->
+
+- [ ] Code follows project style guidelines
+- [ ] Self-review completed
+- [ ] Comments added for complex logic
+- [ ] Documentation updated (if applicable)
+- [ ] No new console warnings/errors
+- [ ] Tests pass locally
+- [ ] Branch is up-to-date with `dev`
+- [ ] Commit messages are clear and descriptive
+- [ ] Sensitive data is not committed
+- [ ] Environment variables documented (if added)
+
+---
+
+## 📝 Additional Notes
+
+<!-- Any additional context, decisions, or considerations -->
+
+
+---
+
+## 🔍 Review Checklist for Maintainers
+
+- [ ] Code quality and readability
+- [ ] Design patterns follow project conventions
+- [ ] Test coverage is adequate
+- [ ] Performance implications reviewed
+- [ ] Security concerns addressed
+- [ ] Documentation is complete
+- [ ] Breaking changes properly communicated
+- [ ] Cross-platform compatibility (if applicable)

.github/scripts/create-release-summary.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# Generate release summary for GitHub Actions
+# Usage: ./create-release-summary.sh <app> <environment> <version> <tag_name>
+
+set -e
+
+APP=$1
+ENV=$2
+VERSION=$3
+TAG_NAME=$4
+
+if [ -z "$APP" ] || [ -z "$ENV" ] || [ -z "$VERSION" ] || [ -z "$TAG_NAME" ]; then
+  echo "❌ Error: Missing required parameters"
+  echo "Usage: ./create-release-summary.sh <app> <environment> <version> <tag_name>"
+  exit 1
+fi
+
+# Determine display names
+if [ "$APP" = "worker-mobile-app" ]; then
+  APP_DISPLAY="Worker Product"
+  APP_EMOJI="👷"
+else
+  APP_DISPLAY="Client Product"
+  APP_EMOJI="💼"
+fi
+
+ENV_UPPER=$(echo "$ENV" | tr '[:lower:]' '[:upper:]')
+RELEASE_NAME="Krow With Us - ${APP_DISPLAY} - ${ENV_UPPER} - v${VERSION}"
+
+# Environment emoji
+case "$ENV" in
+  dev)
+    ENV_EMOJI="🔧"
+    ;;
+  stage)
+    ENV_EMOJI="🎭"
+    ;;
+  prod)
+    ENV_EMOJI="🚀"
+    ;;
+  *)
+    ENV_EMOJI="📦"
+    ;;
+esac
+
+# Generate summary
+cat << EOF >> $GITHUB_STEP_SUMMARY
+## 🎉 Release Created Successfully
+
+### ${APP_EMOJI} Application Details
+- **App:** ${APP_DISPLAY}
+- **Environment:** ${ENV_EMOJI} ${ENV_UPPER}
+- **Version:** \`${VERSION}\`
+- **Tag:** \`${TAG_NAME}\`
+
+### 📦 Release Information
+**Release Name:** ${RELEASE_NAME}
+
+### ✅ Next Steps
+
+1. 🔍 **Verify** the tag and release on GitHub
+2. 🏗️ **Trigger** CodeMagic build (if configured)
+3. 📱 **Monitor** app store deployment
+4. 📚 **Update** project documentation if needed
+5. 🎯 **Communicate** release to stakeholders
+
+### 🔗 Quick Links
+- [View Tag](../../releases/tag/${TAG_NAME})
+- [Release Documentation](../../docs/release/MOBILE_RELEASE_PLAN.md)
+- [CHANGELOG](../../apps/mobile/apps/${APP}/CHANGELOG.md)
+EOF
+
+echo "✅ Summary generated successfully"

.github/scripts/extract-release-notes.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# Extract release notes from CHANGELOG for a specific version
+# Usage: ./extract-release-notes.sh <app> <version> <environment> <tag_name> <output_file>
+
+set -e
+
+APP=$1
+VERSION=$2
+ENV=$3
+TAG_NAME=$4
+OUTPUT_FILE=$5
+
+if [ -z "$APP" ] || [ -z "$VERSION" ] || [ -z "$ENV" ] || [ -z "$TAG_NAME" ] || [ -z "$OUTPUT_FILE" ]; then
+  echo "❌ Error: Missing required parameters"
+  echo "Usage: ./extract-release-notes.sh <app> <version> <environment> <tag_name> <output_file>"
+  exit 1
+fi
+
+# Determine CHANGELOG path and app name
+if [ "$APP" = "worker-mobile-app" ]; then
+  CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md"
+  APP_NAME="Staff Product (Worker)"
+else
+  CHANGELOG_PATH="apps/mobile/apps/client/CHANGELOG.md"
+  APP_NAME="Client Product"
+fi
+
+# Try to extract release notes for this version
+if [ -f "$CHANGELOG_PATH" ]; then
+  echo "📝 Found CHANGELOG at $CHANGELOG_PATH"
+  
+  # Extract section for this version
+  # Look for ## [VERSION] and collect until next ## [ or end of file
+  NOTES=$(awk "/## \[${VERSION}\]/,/^## \[/" "$CHANGELOG_PATH" | sed '1d;$d' | sed '/^$/d')
+  
+  if [ -z "$NOTES" ]; then
+    echo "⚠️ Warning: No CHANGELOG entry found for version $VERSION"
+    NOTES="Release $VERSION for $APP_NAME
+
+⚠️ No CHANGELOG entry found for this version. Please update the CHANGELOG manually.
+
+**Environment:** $ENV
+**Tag:** $TAG_NAME"
+  else
+    echo "✅ Extracted release notes for version $VERSION"
+    NOTES="# $APP_NAME - Release $VERSION
+
+$NOTES
+
+---
+
+**Environment:** $ENV
+**Tag:** $TAG_NAME"
+  fi
+else
+  echo "⚠️ Warning: CHANGELOG not found at $CHANGELOG_PATH"
+  NOTES="Release $VERSION for $APP_NAME
+
+**Environment:** $ENV
+**Tag:** $TAG_NAME"
+fi
+
+# Save to output file
+echo "$NOTES" > "$OUTPUT_FILE"
+echo "✅ Release notes saved to $OUTPUT_FILE"

.github/scripts/extract-version.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+# Extract version from version file for products
+# Usage: ./extract-version.sh <app>
+# app: worker-mobile-app or client-mobile-app
+
+set -e
+
+APP=$1
+
+if [ -z "$APP" ]; then
+  echo "❌ Error: App parameter required (worker-mobile-app or client-mobile-app)"
+  exit 1
+fi
+
+# Determine pubspec path
+if [ "$APP" = "worker-mobile-app" ]; then
+  PUBSPEC_PATH="apps/mobile/apps/staff/pubspec.yaml"
+  APP_NAME="Staff Product (Worker)"
+else
+  PUBSPEC_PATH="apps/mobile/apps/client/pubspec.yaml"
+  APP_NAME="Client Product"
+fi
+
+# Check if pubspec exists
+if [ ! -f "$PUBSPEC_PATH" ]; then
+  echo "❌ Error: pubspec.yaml not found at $PUBSPEC_PATH"
+  exit 1
+fi
+
+# Extract version (format: X.Y.Z+buildNumber)
+VERSION_LINE=$(grep "^version:" "$PUBSPEC_PATH")
+if [ -z "$VERSION_LINE" ]; then
+  echo "❌ Error: Could not find version in $PUBSPEC_PATH"
+  exit 1
+fi
+
+# Extract just the semantic version (before the +)
+VERSION=$(echo "$VERSION_LINE" | sed 's/version: *//' | sed 's/+.*//' | tr -d ' ')
+
+# Validate version format
+if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+  echo "❌ Error: Invalid version format in pubspec.yaml: $VERSION"
+  echo "Expected format: X.Y.Z (e.g., 0.1.0)"
+  exit 1
+fi
+
+echo "✅ Extracted version from $PUBSPEC_PATH: $VERSION"
+echo "$VERSION"

.github/scripts/generate-tag-name.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Generate tag name for product release
+# Usage: ./generate-tag-name.sh <app> <environment> <version>
+
+set -e
+
+APP=$1
+ENV=$2
+VERSION=$3
+
+if [ -z "$APP" ] || [ -z "$ENV" ] || [ -z "$VERSION" ]; then
+  echo "❌ Error: Missing required parameters"
+  echo "Usage: ./generate-tag-name.sh <app> <environment> <version>"
+  exit 1
+fi
+
+# Strip -mobile-app suffix from app name for cleaner tag names
+# worker-mobile-app -> worker, client-mobile-app -> client
+APP_TAG=$(echo "$APP" | sed 's/-mobile-app$//')
+
+TAG_NAME="krow-withus-${APP_TAG}-mobile/${ENV}-v${VERSION}"
+echo "$TAG_NAME"

.github/workflows/hotfix-branch-creation.yml

@@ -0,0 +1,331 @@
+name: 🚨 Product Hotfix
+
+on:
+  workflow_dispatch:
+    inputs:
+      app:
+        description: '📦 Product'
+        required: true
+        type: choice
+        options:
+          - worker-mobile-app
+          - client-mobile-app
+      tag:
+        description: '🏷️ Current Tag (e.g., krow-withus-worker-mobile/prod-v0.1.0 or dev/stage)'
+        required: true
+        type: string
+      issue_description:
+        description: '📝 Brief issue description'
+        required: true
+        type: string
+
+jobs:
+  create-hotfix-branch:
+    name: 🚨 Create Hotfix Branch
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      
+    steps:
+      - name: 📥 Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          
+      - name: 🔍 Validate tag exists
+        id: validate_tag
+        run: |
+          TAG="${{ github.event.inputs.tag }}"
+          
+          if ! git rev-parse "$TAG" >/dev/null 2>&1; then
+            echo "❌ Error: Tag '$TAG' does not exist"
+            echo "Available tags:"
+            git tag -l "krow-withus-*-mobile/*" | tail -20
+            exit 1
+          fi
+          
+          echo "✅ Tag exists: $TAG"
+          
+          # Extract version from tag
+          VERSION=$(echo "$TAG" | grep -oP 'v\K[0-9]+\.[0-9]+\.[0-9]+' || echo "")
+          if [ -z "$VERSION" ]; then
+            echo "❌ Error: Could not extract version from tag"
+            exit 1
+          fi
+          
+          echo "current_version=${VERSION}" >> $GITHUB_OUTPUT
+          echo "📌 Current version: $VERSION"
+          
+      - name: 🔢 Calculate hotfix version
+        id: hotfix_version
+        run: |
+          CURRENT="${{ steps.validate_tag.outputs.current_version }}"
+          
+          # Split version into parts
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
+          
+          # Increment PATCH version
+          NEW_PATCH=$((PATCH + 1))
+          HOTFIX_VERSION="${MAJOR}.${MINOR}.${NEW_PATCH}"
+          
+          echo "hotfix_version=${HOTFIX_VERSION}" >> $GITHUB_OUTPUT
+          echo "🆕 Hotfix version: $HOTFIX_VERSION"
+          
+      - name: 🌿 Generate branch name
+        id: branch
+        run: |
+          APP="${{ github.event.inputs.app }}"
+          VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}"
+          
+          # Strip -mobile-app suffix for cleaner branch names
+          APP_CLEAN=$(echo "$APP" | sed 's/-mobile-app$//')
+          
+          BRANCH_NAME="hotfix/krow-withus-${APP_CLEAN}-mobile-v${VERSION}"
+          echo "branch_name=${BRANCH_NAME}" >> $GITHUB_OUTPUT
+          echo "🌿 Branch to create: $BRANCH_NAME"
+          
+      - name: 🔍 Check if hotfix branch already exists
+        run: |
+          BRANCH="${{ steps.branch.outputs.branch_name }}"
+          
+          if git ls-remote --heads origin "$BRANCH" | grep -q "$BRANCH"; then
+            echo "❌ Error: Branch $BRANCH already exists"
+            exit 1
+          fi
+          
+          echo "✅ Branch does not exist, proceeding..."
+          
+      - name: 🌿 Create hotfix branch from tag
+        run: |
+          TAG="${{ github.event.inputs.tag }}"
+          BRANCH="${{ steps.branch.outputs.branch_name }}"
+          
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          
+          # Checkout the tag
+          git checkout "$TAG"
+          
+          # Create new branch
+          git checkout -b "$BRANCH"
+          
+          echo "✅ Created branch $BRANCH from tag $TAG"
+          
+      - name: 📝 Update version files
+        id: update_versions
+        run: |
+          APP="${{ github.event.inputs.app }}"
+          HOTFIX_VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}"
+          
+          if [ "$APP" = "worker-mobile-app" ]; then
+            PUBSPEC_PATH="apps/mobile/apps/staff/pubspec.yaml"
+            CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md"
+            APP_NAME="Staff Product"
+          else
+            PUBSPEC_PATH="apps/mobile/apps/client/pubspec.yaml"
+            CHANGELOG_PATH="apps/mobile/apps/client/CHANGELOG.md"
+            APP_NAME="Client Product"
+          fi
+          
+          # Update pubspec.yaml version
+          if [ -f "$PUBSPEC_PATH" ]; then
+            # Extract current version and build number
+            CURRENT_VERSION_LINE=$(grep "^version:" "$PUBSPEC_PATH")
+            CURRENT_BUILD=$(echo "$CURRENT_VERSION_LINE" | grep -oP '\+\K[0-9]+' || echo "1")
+            NEW_BUILD=$((CURRENT_BUILD + 1))
+            
+            # Update version line
+            sed -i "s/^version:.*/version: ${HOTFIX_VERSION}+${NEW_BUILD}/" "$PUBSPEC_PATH"
+            
+            echo "✅ Updated $PUBSPEC_PATH to ${HOTFIX_VERSION}+${NEW_BUILD}"
+            echo "updated_files=true" >> $GITHUB_OUTPUT
+          else
+            echo "⚠️ Warning: $PUBSPEC_PATH not found"
+            echo "updated_files=false" >> $GITHUB_OUTPUT
+          fi
+          
+      - name: 📋 Add CHANGELOG entry
+        run: |
+          APP="${{ github.event.inputs.app }}"
+          HOTFIX_VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}"
+          ISSUE="${{ github.event.inputs.issue_description }}"
+          
+          if [ "$APP" = "worker-mobile-app" ]; then
+            CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md"
+            APP_NAME="Staff Product"
+          else
+            CHANGELOG_PATH="apps/mobile/apps/client/CHANGELOG.md"
+            APP_NAME="Client Product"
+          fi
+          
+          if [ -f "$CHANGELOG_PATH" ]; then
+            DATE=$(date +%Y-%m-%d)
+            
+            # Create hotfix entry
+            HOTFIX_ENTRY="## [${HOTFIX_VERSION}] - ${DATE} - HOTFIX
+
+### Fixed
+- ${ISSUE}
+
+---
+
+"
+            
+            # Insert after the first line (title)
+            sed -i "1 a\\
+\\
+$HOTFIX_ENTRY" "$CHANGELOG_PATH"
+            
+            echo "✅ Added CHANGELOG entry for hotfix $HOTFIX_VERSION"
+          else
+            echo "⚠️ Warning: $CHANGELOG_PATH not found"
+          fi
+          
+      - name: 💾 Commit version changes
+        run: |
+          HOTFIX_VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}"
+          ISSUE="${{ github.event.inputs.issue_description }}"
+          
+          git add -A
+          git commit -m "chore: prepare hotfix v${HOTFIX_VERSION}
+
+HOTFIX: ${ISSUE}
+
+- Bump version to ${HOTFIX_VERSION}
+- Add CHANGELOG entry
+- Ready for bug fix commits
+
+From tag: ${{ github.event.inputs.tag }}"
+          
+          echo "✅ Committed version changes"
+          
+      - name: 🚀 Push hotfix branch
+        run: |
+          BRANCH="${{ steps.branch.outputs.branch_name }}"
+          
+          git push origin "$BRANCH"
+          
+          echo "✅ Pushed branch: $BRANCH"
+          
+      - name: 📄 Create Pull Request
+        id: create_pr
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          BRANCH="${{ steps.branch.outputs.branch_name }}"
+          HOTFIX_VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}"
+          ISSUE="${{ github.event.inputs.issue_description }}"
+          APP="${{ github.event.inputs.app }}"
+          
+          # Strip -mobile-app suffix for cleaner tag names
+          APP_CLEAN=$(echo "$APP" | sed 's/-mobile-app$//')
+          
+          if [ "$APP" = "worker-mobile-app" ]; then
+            APP_DISPLAY="Worker Product"
+          else
+            APP_DISPLAY="Client Product"
+          fi
+          
+          PR_TITLE="🚨 HOTFIX: ${APP_DISPLAY} v${HOTFIX_VERSION} - ${ISSUE}"
+          
+          PR_BODY="## 🚨 HOTFIX - URGENT FIX
+
+**App:** ${APP_DISPLAY}
+**Version:** ${HOTFIX_VERSION}
+**From:** \`${{ github.event.inputs.tag }}\`
+
+### Issue
+${ISSUE}
+
+### Impact
+<!-- Describe how many users are affected and severity -->
+
+### Solution
+<!-- Describe the fix (will be added as you commit fixes) -->
+
+### Testing
+<!-- Describe local verification -->
+
+---
+
+## ⚠️ Hotfix Process
+
+1. ✅ Hotfix branch created
+2. ⏳ **NEXT:** Make your bug fix commits to this branch
+3. ⏳ Test the fix locally
+4. ⏳ Request expedited review (< 15 minutes)
+5. ⏳ Merge to main and create production tag
+
+### To add your fix:
+\`\`\`bash
+git checkout $BRANCH
+# Make your changes
+git commit -m \"fix: [description]\"
+git push origin $BRANCH
+\`\`\`
+
+### After merging:
+\`\`\`bash
+# Tag and release
+git checkout main
+git pull origin main
+git tag -a krow-withus-${APP_CLEAN}-mobile/prod-v${HOTFIX_VERSION} -m \"HOTFIX: ${ISSUE}\"
+git push origin krow-withus-${APP_CLEAN}-mobile/prod-v${HOTFIX_VERSION}
+\`\`\`
+
+---
+
+**Ref:** [Hotfix Process Documentation](../docs/release/HOTFIX_PROCESS.md)"
+          
+          # Create PR
+          PR_URL=$(gh pr create \
+            --base main \
+            --head "$BRANCH" \
+            --title "$PR_TITLE" \
+            --body "$PR_BODY" \
+            --label "hotfix,urgent,production")
+          
+          echo "pr_url=${PR_URL}" >> $GITHUB_OUTPUT
+          echo "✅ Pull Request created: $PR_URL"
+          
+      - name: 📊 Hotfix Summary
+        run: |
+          # Strip -mobile-app suffix for cleaner tag names
+          APP_CLEAN=$(echo "${{ github.event.inputs.app }}" | sed 's/-mobile-app$//')
+          
+          echo "## 🚨 Hotfix Branch Created" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**App:** ${{ github.event.inputs.app }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Issue:** ${{ github.event.inputs.issue_description }}" >> $GITHUB_STEP_SUMMARY
+          echo "**From Tag:** \`${{ github.event.inputs.tag }}\`" >> $GITHUB_STEP_SUMMARY
+          echo "**Current Version:** ${{ steps.validate_tag.outputs.current_version }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Hotfix Version:** ${{ steps.hotfix_version.outputs.hotfix_version }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Branch:** \`${{ steps.branch.outputs.branch_name }}\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### 🔧 Next Steps" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "1. **Checkout the hotfix branch:**" >> $GITHUB_STEP_SUMMARY
+          echo "   \`\`\`bash" >> $GITHUB_STEP_SUMMARY
+          echo "   git fetch origin" >> $GITHUB_STEP_SUMMARY
+          echo "   git checkout ${{ steps.branch.outputs.branch_name }}" >> $GITHUB_STEP_SUMMARY
+          echo "   \`\`\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "2. **Make your bug fix(es)** - Keep changes minimal!" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "3. **Test locally** - Verify the fix works" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "4. **Request expedited review** - Target < 15 minutes" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "5. **Merge PR and create production tag:**" >> $GITHUB_STEP_SUMMARY
+          echo "   \`\`\`bash" >> $GITHUB_STEP_SUMMARY
+          echo "   git checkout main" >> $GITHUB_STEP_SUMMARY
+          echo "   git pull origin main" >> $GITHUB_STEP_SUMMARY
+          echo "   git tag -a krow-withus-${APP_CLEAN}-mobile/prod-v${{ steps.hotfix_version.outputs.hotfix_version }} -m \"HOTFIX: ${{ github.event.inputs.issue_description }}\"" >> $GITHUB_STEP_SUMMARY
+          echo "   git push origin krow-withus-${APP_CLEAN}-mobile/prod-v${{ steps.hotfix_version.outputs.hotfix_version }}" >> $GITHUB_STEP_SUMMARY
+          echo "   \`\`\`" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          
+          if [ -n "${{ steps.create_pr.outputs.pr_url }}" ]; then
+            echo "**Pull Request:** ${{ steps.create_pr.outputs.pr_url }}" >> $GITHUB_STEP_SUMMARY
+          fi

.github/workflows/product-release.yml

@@ -0,0 +1,145 @@
+name: <EFBFBD> Product Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      app:
+        description: '📦 Product'
+        required: true
+        type: choice
+        options:
+          - worker-mobile-app
+          - client-mobile-app
+      environment:
+        description: '🌍 Environment'
+        required: true
+        type: choice
+        options:
+          - dev
+          - stage
+          - prod
+      create_github_release:
+        description: '📦 Create GitHub Release'
+        required: true
+        type: boolean
+        default: true
+      prerelease:
+        description: '🔖 Mark as Pre-release'
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  validate-and-create-release:
+    name: 🚀 Create Product Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      
+    steps:
+      - name: 📥 Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          
+      - name: <EFBFBD> Make scripts executable
+        run: |
+          chmod +x .github/scripts/*.sh
+          echo "✅ Scripts are now executable"
+          
+      - name: 📖 Extract version from version file
+        id: version
+        run: |
+          VERSION=$(.github/scripts/extract-version.sh "${{ github.event.inputs.app }}")
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+          echo "📌 Extracted version: ${VERSION}"
+          
+      - name: 🏷️ Generate tag name
+        id: tag
+        run: |
+          TAG_NAME=$(.github/scripts/generate-tag-name.sh \
+            "${{ github.event.inputs.app }}" \
+            "${{ github.event.inputs.environment }}" \
+            "${{ steps.version.outputs.version }}")
+          echo "tag_name=${TAG_NAME}" >> $GITHUB_OUTPUT
+          echo "🎯 Tag to create: ${TAG_NAME}"
+          
+      - name: 🔍 Check if tag already exists
+        run: |
+          TAG_NAME="${{ steps.tag.outputs.tag_name }}"
+          if git rev-parse "$TAG_NAME" >/dev/null 2>&1; then
+            echo "❌ Error: Tag $TAG_NAME already exists"
+            echo "💡 Tip: Update the version in the version file before creating a new release"
+            exit 1
+          fi
+          echo "✅ Tag does not exist, proceeding..."
+          
+      - name: 📋 Extract release notes from CHANGELOG
+        id: release_notes
+        run: |
+          .github/scripts/extract-release-notes.sh \
+            "${{ github.event.inputs.app }}" \
+            "${{ steps.version.outputs.version }}" \
+            "${{ github.event.inputs.environment }}" \
+            "${{ steps.tag.outputs.tag_name }}" \
+            "/tmp/release_notes.md"
+          echo "notes_file=/tmp/release_notes.md" >> $GITHUB_OUTPUT
+          
+      - name: 🏷️ Create Git Tag
+        run: |
+          TAG_NAME="${{ steps.tag.outputs.tag_name }}"
+          APP="${{ github.event.inputs.app }}"
+          ENV="${{ github.event.inputs.environment }}"
+          VERSION="${{ steps.version.outputs.version }}"
+          
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          
+          git tag -a "$TAG_NAME" -m "🚀 Release ${APP} product ${VERSION} to ${ENV}"
+          git push origin "$TAG_NAME"
+          
+          echo "✅ Tag created and pushed: $TAG_NAME"
+          
+      - name: 📦 Create GitHub Release
+        if: ${{ github.event.inputs.create_github_release == 'true' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG_NAME="${{ steps.tag.outputs.tag_name }}"
+          APP="${{ github.event.inputs.app }}"
+          ENV="${{ github.event.inputs.environment }}"
+          VERSION="${{ steps.version.outputs.version }}"
+          
+          # Generate release title
+          if [ "$APP" = "worker-mobile-app" ]; then
+            APP_DISPLAY="Worker Mobile Application"
+          else
+            APP_DISPLAY="Client Mobile Application"
+          fi
+          
+          ENV_UPPER=$(echo "$ENV" | tr '[:lower:]' '[:upper:]')
+          RELEASE_NAME="Krow With Us - ${APP_DISPLAY} - ${ENV_UPPER} - v${VERSION}"
+          
+          echo "📦 Creating GitHub Release: $RELEASE_NAME"
+          
+          # Create release
+          if [ "${{ github.event.inputs.prerelease }}" = "true" ]; then
+            gh release create "$TAG_NAME" \
+              --title "$RELEASE_NAME" \
+              --notes-file "${{ steps.release_notes.outputs.notes_file }}" \
+              --prerelease
+            echo "🔖 Pre-release created successfully"
+          else
+            gh release create "$TAG_NAME" \
+              --title "$RELEASE_NAME" \
+              --notes-file "${{ steps.release_notes.outputs.notes_file }}"
+            echo "✅ Release created successfully"
+          fi
+          
+      - name: 📊 Generate Release Summary
+        run: |
+          .github/scripts/create-release-summary.sh \
+            "${{ github.event.inputs.app }}" \
+            "${{ github.event.inputs.environment }}" \
+            "${{ steps.version.outputs.version }}" \
+            "${{ steps.tag.outputs.tag_name }}"

apps/mobile/apps/client/CHANGELOG.md

@@ -0,0 +1,230 @@
+# Client Mobile App - Change Log
+
+## [0.0.1-M3] - Milestone 3 - 2026-02-15
+
+### Added - Authentication & Onboarding
+- Business email and password authentication
+- Client account registration
+- Business onboarding flow
+- Company information setup
+
+### Added - Home Dashboard
+- Welcome screen with business name
+- Coverage statistics for today:
+  - Coverage percentage
+  - Workers checked in vs needed
+  - Open positions count
+- Late workers alerts with visual indicators
+- Today's estimated labor cost
+- Upcoming shifts section
+- Quick action buttons:
+  - Create Order
+  - Hubs management
+
+### Added - Hub Management
+- Hubs page accessible from settings
+- Hub creation flow:
+  - Hub name input
+  - Address autocomplete with Google Maps Places API
+  - Hub creation confirmation
+- Hubs list view showing all created hubs
+- Hub card display with name, address, and tag ID
+
+### Added - Order Creation
+- Orders tab in bottom navigation
+- "+ Post" button to create new orders
+- Order type selection screen:
+  - One-Time orders (implemented)
+- One-Time Order creation form:
+  - Order name
+  - Date picker
+  - Hub selection
+  - Position management:
+    - Role selection
+    - Worker count
+    - Start/end time
+    - Shift duration calculation
+  - Cost estimation
+- Order creation confirmation
+
+### Added - Order Management
+- Orders list view with:
+  - Order cards showing date, location, time
+  - Worker count (filled/needed)
+  - Coverage percentage bar
+  - Status indicators (OPEN, FILLED, IN PROGRESS)
+- Order details view:
+  - Event name and location
+  - Roles and worker requirements
+  - Clock in/out times
+  - Estimated cost
+  - Coverage percentage
+  - Map integration with directions
+
+### Added - Coverage Monitoring
+- Coverage tab in bottom navigation
+- Real-time worker status dashboard:
+  - Checked In (green indicator)
+  - En Route (yellow indicator)
+  - Late (red indicator)
+  - Not Arrived status
+- Color-coded status badges
+- Worker information cards
+- Active shift monitoring
+
+### Added - Navigation
+- Bottom navigation bar with tabs:
+  - Coverage
+  - Billing
+  - Home
+  - Orders
+  - Reports
+- Settings menu accessible from home screen
+- Back navigation handling
+
+### Added - Settings
+- Settings page with options:
+  - Hubs management
+  - Profile editing
+  - Notifications preferences
+  - Log out
+
+### Technical Features
+- Firebase authentication integration
+- Data Connect backend integration
+- Google Maps Places API for address autocomplete
+- Real-time worker status tracking
+- Cost calculation engine
+- Coverage percentage calculations
+
+### Known Limitations
+- Orders require hub assignment
+- Currently supports one-time orders only
+- Order approval flow not yet implemented
+- RAPID, Recurring, and Permanent order types are placeholders
+
+---
+
+## [0.0.1-M4] - Milestone 4 - 2026-03-05
+
+### Added - Enhanced Authentication & Session Management
+- Authentication session persistence across app restarts
+- Automatic login with valid session tokens
+- Improved user experience with seamless session handling
+
+### Added - RAPID Order Creation (AI-Powered)
+- Voice input for order creation with audio recording
+- Text input for order description
+- Multi-platform audio recording support (iOS/Android)
+- AI transcription service for voice-to-text conversion
+- AI parsing to generate order drafts from natural language
+- Same-day order support for urgent coverage needs
+- Populated order form matching one-time order structure
+- Edit AI-generated order before submission
+- Quick order creation workflow
+- Audio file upload for transcription
+- RAPID order verification page with refinements
+- Hub and role matching for order creation
+
+### Added - Recurring Order Support
+- Recurring order creation flow
+- Schedule configuration interface
+- Recurring patterns (daily, weekly, custom)
+- Recurring order management
+
+### Added - Permanent Order Support
+- Permanent order creation flow
+- Long-term position setup
+- Permanent order management
+
+### Added - Enhanced Order Management
+- Hide edit icon for past or completed orders
+- Updated Reorder modal supporting all order types:
+  - One-Time reorder
+  - RAPID reorder
+  - Recurring reorder
+  - Permanent reorder
+- Reorder functionality with order type awareness
+- Hub manager assignment to orders
+- Cost center entity linking to hubs
+- Completion review UI with:
+  - Actions summary
+  - Amount display
+  - Info sections
+  - Worker listing
+- Invoice management improvements
+
+### Added - Comprehensive Reports System
+- Reports page with AI-powered insights
+- Three AI-generated insights on reports landing page
+- Six report types:
+  1. **Daily Ops Report**: Daily operational metrics and statistics
+  2. **Spend Report**: Labor cost analysis and spend tracking
+  3. **Coverage Report**: Shift coverage analytics and trends
+  4. **No-Show Report**: Worker attendance and no-show tracking
+  5. **Performance Report**: Worker performance metrics and ratings
+  6. *(Reserved for future report type)*
+
+### Added - Hub Management Enhancements
+- Dedicated hub details interface
+- Detailed hub information view
+- Hub editing page (separate interface)
+- Enhanced hub navigation
+
+### Added - Home Dashboard Enhancements
+- Reorder quick action button
+### Added - Home Dashboard Enhancements
+- Reorder quick action button for fast order duplication
+- Insights quick action button for AI analytics
+- Direct access to AI insights from home
+- Refactored home widgets with SectionLayout:
+  - Today's shifts section with titles
+  - Tomorrow's shifts section
+  - Coverage widget improvements
+  - Live activity widget enhancements
+  - Spending widget updates
+- Full-width dividers for better visual separation
+- Improved dashboard widget organization
+
+### Improved - User Experience
+- Better order type selection flow
+- Enhanced order creation UX across all types
+- Improved reports navigation
+- Better hub management interface
+- Bottom navigation bar show/hide based on route changes
+- Enhanced navigation robustness with error handling
+- Improved invoice page layout with reordered titles
+- Session management improvements with proper role validation
+- Enhanced settings page navigation flow
+- Better amount widget styling in completion review
+
+### Fixed
+- Client app crash issues resolved
+- Shift booking status inconsistencies fixed
+- Session navigation errors corrected
+- Formatting and code clarity improvements across codebase
+
+### Technical Features
+- Backend transaction support for order creation
+- Order validation (minimum hours check)
+- Shift creation validation
+- 24-hour cancellation policy enforcement
+- Enhanced backend reporting APIs
+- AI insights generation system
+- Core API integration:
+  - RAPID order transcription endpoints
+  - Order parsing services  
+  - File upload with signed URLs
+  - LLM services
+- ApiService with Dio for standardized API requests
+- DataConnectService integration across all repositories
+- Enhanced session management with SessionListener
+- Role-based session handling
+
+### Known Limitations
+- RAPID order parsing requires clear voice/text input
+- AI insights require sufficient historical data
+- Reports may have limited data in early usage
+- PDF export for reports not yet implemented
+
+---

apps/mobile/apps/client/pubspec.yaml

@@ -1,7 +1,7 @@
 name: krowwithus_client
 description: "KROW Client Application"
 publish_to: "none"
-version: 0.0.1-IlianaClientM3
+version: 0.0.1-m4
 resolution: workspace
 
 environment:

apps/mobile/apps/staff/CHANGELOG.md

@@ -0,0 +1,193 @@
+# Staff Mobile App - Change Log
+
+## [0.0.1-M3] - Milestone 3 - 2026-02-15
+
+### Added - Authentication & Onboarding
+- Phone number authentication with OTP verification
+- Staff onboarding flow with profile setup
+- Personal information collection (name, bio, languages)
+- Preferred work locations selection
+- Skills and industry selection
+
+### Added - Home Dashboard
+- Welcome screen with personalized greeting
+- Today's shifts section showing confirmed shifts
+- Tomorrow's shifts preview
+- Recommended shifts section based on profile
+- Quick action buttons (Find Shifts, Availability, Messages, Earnings)
+
+### Added - Shift Management
+- Find Shifts functionality to discover available work
+- Shift details view showing:
+  - Business name and location
+  - Hourly rate and estimated earnings
+  - Date, start time, end time
+  - Job requirements
+  - Map integration with directions
+- Shift booking/application process
+- Booking confirmation dialog
+- My Shifts view with week-by-week navigation
+- Color-coded shift status (Confirmed, Pending, Completed)
+
+### Added - Clock In/Out
+- Clock In page with slider interaction
+- Clock Out page with slider interaction
+- Automatic timestamp recording
+- Shift status updates upon clock in/out
+- Visual status indicators (green for checked in)
+
+### Added - Profile Management
+- Profile tab with personal information
+- Emergency Contact management:
+  - Contact name
+  - Relationship
+  - Phone number
+- Bank Account linking for direct deposit
+- Tax Forms section:
+  - W-4 form access
+  - I-9 form access
+- Time Card view:
+  - Historical shift records
+  - Hours worked tracking
+  - Earnings history
+
+### Added - Navigation
+- Bottom navigation bar with 5 tabs:
+  - Shifts
+  - Payments
+  - Home
+  - Clock In
+  - Profile
+- Tab bar hiding on specific pages
+
+### Technical Features
+- Firebase authentication integration
+- Data Connect backend integration
+- Google Maps integration for locations
+- Phone verification system
+- OTP code handling
+
+### Known Limitations
+- Newly created orders don't appear immediately in Find Shifts (requires vendor approval)
+- Limited to one-time order types in this milestone
+
+---
+
+## [0.0.1-M4] - Milestone 4 - 2026-03-05
+
+### Added - Enhanced Authentication & Session Management
+- Authentication session persistence across app restarts
+- Automatic login with valid session tokens
+- Improved user experience with seamless session handling
+
+### Added - Enhanced Shift Details
+- Google Maps location display in shift details view
+- Interactive map showing shift location
+- Directions integration
+- Shift requirements section showing:
+  - Required attire items (MUST HAVE)
+  - Preferred attire items (NICE TO HAVE)
+  - Other shift-specific requirements
+
+### Added - Attire Management
+- Dedicated Attire screen in profile
+- Camera and gallery support for attire photo capture
+- Local image preview before submission
+- Upload attire images for verification
+- MUST HAVE attire items list
+- NICE TO HAVE attire items list
+- Attire photo gallery in profile
+- Submit attire for review workflow
+- Attire verification status tracking (Pending, Approved, Rejected)
+- Attestation checkbox for attire accuracy confirmation
+- Filtered attire items based on requirements
+
+### Added - Documents & Certificates Management
+- Documents section in profile with verification status tracking
+- Upload documents (ID, licenses, etc.) with:
+  - Camera or gallery selection
+  - File type validation
+  - Upload progress tracking
+  - Verification metadata
+- Certificates management:
+  - Upload certificates with expiry dates
+  - Certificate number field
+  - Certificate type selection
+  - View existing certificates
+  - Delete certificates
+  - Verification status (Not Verified, Verified, Expired)
+- Mandatory document flagging
+- Document verification workflow
+
+### Added - Profile Enhancements
+- FAQ (Frequently Asked Questions) screen
+- Privacy and Security settings screen:
+  - Profile visibility toggle ("Hide account from business")
+  - Terms of Service document access
+  - Privacy Policy document access
+- Preferred locations management:
+  - Dedicated edit screen
+  - Location search functionality
+  - Display selected locations
+- Language selection interface:
+  - Spanish language support
+  - Success feedback on language change
+  - Persistent language preference
+- Benefits overview section:
+  - Benefits listing with circular progress indicators
+  - Benefits dashboard integration
+- Profile completion tracking for:
+  - Personal information
+  - Emergency contacts
+  - Experience
+  - Attire
+  - Documents
+  - Certificates
+
+### Added - Profile Completion Gating
+- Navigation restrictions for incomplete profiles
+- Only Home and Profile tabs accessible until profile is complete
+- Profile completion checklist
+- Guided onboarding completion flow
+
+### Improved - User Experience
+- Enhanced shift details UI with better information hierarchy
+- Improved profile section organization
+- Better navigation flow for profile completion
+- UiEmptyState widgets for better empty state handling:
+  - Bank account page empty state
+  - Home page when no shifts available
+- Improved onboarding flow with refactored experience and personal info pages
+- Enhanced emergency contact screen with info banner
+- Refactored profile header with profile level badge ("KROWER I")
+- Benefits card components with improved styling
+- Bottom navigation bar show/hide based on route
+- Tax forms page with progress overview
+- Improved notice and file type banners for uploads
+- Enhanced navigation robustness with proper error handling
+- Immediate ID token refresh after sign-in to prevent unauthenticated requests
+
+### Fixed
+- Profile completion status now updates correctly for emergency contacts
+- Session handling improved to prevent data loss
+- Navigation errors redirect to appropriate home page
+- Locale synchronization by reloading from persistent storage after change
+
+### Technical Features
+- Enhanced backend validation for shift acceptance
+- Overlapping shift prevention
+- Improved session management
+- Document upload and storage integration
+- Signed URL generation for file uploads
+- Camera and gallery native device access
+- File visibility controls (public/private)
+- Core API services integration (verification, file upload, LLM)
+- ApiService with Dio for standardized API requests
+- Device services abstraction layer
+
+### Known Limitations
+- Cannot accept overlapping shifts
+- Shifts require manual confirmation in some cases
+- Attire verification requires manual client approval
+
+---

apps/mobile/apps/staff/pubspec.yaml

@@ -1,7 +1,7 @@
 name: krowwithus_staff
 description: "KROW Staff Application"
 publish_to: 'none'
-version: 0.0.1-IlianaStaffM3
+version: 0.0.1-m4
 resolution: workspace
 
 environment:

docs/RELEASE/HOTFIX_PROCESS.md

@@ -0,0 +1,343 @@
+# Hotfix Process
+
+**For Emergency Production Fixes**
+
+---
+
+## 🚨 When to Hotfix
+
+Use hotfix when:
+- ✅ Critical bug in production affecting users
+- ✅ Data loss or security vulnerability
+- ✅ Service unavailable or major feature broken
+- ✅ Customer-blocking issue
+
+**Don't use hotfix for:**
+- ❌ Minor bugs (can wait for next release)
+- ❌ Feature requests
+- ❌ Nice-to-have improvements
+- ❌ Styling issues
+
+---
+
+## 🔄 Hotfix Process
+
+### Step 1: Assess & Declare Emergency
+
+```
+Issue: [Brief description]
+Severity: CRITICAL / HIGH / MEDIUM
+Product: [Staff Mobile / Client Mobile / Web / Backend]
+Environment: Production
+Impact: [How many users affected]
+```
+
+Once severity confirmed → Start hotfix immediately.
+
+---
+
+### Step 2: Create Hotfix Branch
+
+```bash
+# From production tag
+git checkout -b hotfix/krow-withus-worker-mobile-v0.1.1 \
+  krow-withus-worker-mobile/prod-v0.1.0
+
+# Verify you're on the right tag
+git log -1 --oneline
+```
+
+**Format**: `hotfix/<product>-v<PATCH+1>`
+
+---
+
+### Step 3: Fix the Bug
+
+```bash
+# Make your fix
+# Edit files, test locally
+
+# Commit with clear message
+git commit -m "fix: [issue description]
+
+HOTFIX for production
+Issue: [what happened]
+Solution: [what was fixed]
+Tested: [how was it tested locally]"
+```
+
+**Keep it minimal:**
+- Only fix the specific bug
+- Don't refactor or optimize
+- Don't add new features
+
+---
+
+### Step 4: Update Version
+
+Update PATCH version only (0.1.0 → 0.1.1):
+
+**For Mobile** (`apps/mobile/apps/*/pubspec.yaml`):
+```yaml
+# Old
+version: 0.1.0+5
+
+# New
+version: 0.1.1+6  # Only PATCH changed
+```
+
+**For Web** (`apps/web/package.json`):
+```json
+"version": "0.1.1"
+```
+
+**For Backend** (`backend/*/package.json`):
+```json
+"version": "0.1.1"
+```
+
+---
+
+### Step 5: Update CHANGELOG
+
+Add entry to **top** of appropriate CHANGELOG:
+
+```markdown
+| 2026-03-05 | 0.1.1 | HOTFIX: [Issue fixed] |
+
+(previous entries below...)
+```
+
+---
+
+### Step 6: Code Review (Expedited)
+
+```bash
+# Push hotfix branch
+git push origin hotfix/krow-withus-worker-mobile-v0.1.1
+
+# Create PR on GitHub with URGENT label
+gh pr create --title "HOTFIX: [Issue description]" \
+  --body "**URGENT PRODUCTION FIX**
+
+Issue: [What was broken]
+Impact: [Users affected]
+Solution: [What was fixed]
+Testing: [Local verification]"
+```
+
+**Get approval within 15 minutes if possible.**
+
+---
+
+### Step 7: Merge to Main
+
+```bash
+# Review complete - merge
+git checkout main
+git pull origin main
+git merge --ff-only hotfix/krow-withus-worker-mobile-v0.1.1
+git push origin main
+```
+
+---
+
+### Step 8: Create Production Tag
+
+```bash
+# Create tag from main
+git tag -a krow-withus-worker-mobile/prod-v0.1.1 \
+  -m "HOTFIX: [Issue fixed]"
+
+git push origin krow-withus-worker-mobile/prod-v0.1.1
+```
+
+---
+
+### Step 9: Deploy to Production
+
+```bash
+# Follow your deployment procedure
+# Higher priority than normal releases
+
+./scripts/deploy-mobile-production.sh krow-withus-worker-mobile/prod-v0.1.1
+```
+
+**Deployment time**: Within 30 minutes of approval
+
+---
+
+### Step 10: Verify & Monitor
+
+```bash
+# Smoke tests
+- App launches
+- Core features work
+- No new errors
+
+# Monitor for 2 hours
+- Watch error logs
+- Check user reports
+- Verify fix worked
+```
+
+---
+
+### Step 11: Communicate
+
+**Immediately after deployment:**
+
+```markdown
+🚨 PRODUCTION HOTFIX DEPLOYED
+
+Product: Worker Mobile
+Version: 0.1.1
+Issue: [Fixed issue]
+Impact: [Resolved for X users]
+Status: ✅ Deployed & verified
+
+No user action required.
+Service restored to normal.
+```
+
+**24 hours later:**
+
+```markdown
+✅ HOTFIX STATUS UPDATE
+
+Production hotfix v0.1.1 deployed 24 hours ago.
+Zero errors reported post-deployment.
+System stable.
+
+Thank you for your patience!
+```
+
+---
+
+## ⏱️ Timeline
+
+```
+T-0:    Issue detected & reported
+T+5min: Severity assessed, hotfix branch created
+T+15:   Fix implemented, code review started
+T+30:   Approved & merged, tag created
+T+45:   Deployed to production
+T+60:   Smoke tests pass, monitoring enabled
+T+120:  Declare emergency resolved, communicate
+T+1day: Follow-up communication
+```
+
+**Total time: 2-4 hours from detection to resolution**
+
+---
+
+## 🚫 Common Mistakes to Avoid
+
+❌ **Don't**:
+- Skip code review (even in emergency)
+- Add multiple unrelated fixes in one hotfix
+- Forget to update version number
+- Forget CHANGELOG entry
+- Deploy without testing
+- Forget to communicate with users
+
+✅ **Do**:
+- Keep hotfix minimal and focused
+- Test every fix locally first
+- Get at least one approval
+- Update all version files
+- Deploy immediately after approval
+- Monitor actively for 2+ hours
+
+---
+
+## 📋 Hotfix Checklist
+
+Copy for each emergency:
+
+```
+Hotfix: [Product] v[Old Version] → v[New Version]
+
+□ Severity assessed & documented
+□ Branch created from production tag
+□ Bug fixed & tested locally
+□ Version number updated (PATCH only)
+□ CHANGELOG entry added
+□ Commit message clear
+□ Code review requested (marked URGENT)
+□ Approval obtained
+□ Merged to main
+□ Production tag created
+□ Tag pushed to remote
+□ Deployed to production
+□ Smoke tests passed
+□ Error logs monitored (2+ hours)
+□ Users notified
+□ GitHub Release created
+□ Incident documented
+
+Total Time: ___ minutes
+```
+
+---
+
+## 🔍 Post-Incident
+
+After emergency is resolved:
+
+1. **Document what happened**
+   - Root cause analysis
+   - Why it wasn't caught before
+   - What testing was missed
+
+2. **Schedule postmortem** (within 24 hours)
+   - Review what went wrong
+   - Discuss prevention
+   - Update processes if needed
+
+3. **Plan prevention**
+   - Add test coverage
+   - Update CI/CD checks
+   - Improve monitoring
+
+4. **Communicate findings**
+   - Share with team
+   - Update documentation
+   - Prevent recurrence
+
+---
+
+## 📞 Emergency Contacts
+
+When issue detected:
+
+1. **Notify**: 
+   - Release Engineer
+   - DevOps
+   - Product Owner
+   - Affected Team
+
+2. **Communication Channel**:
+   - Slack: #emergency-releases
+   - Time-sensitive decisions on call
+
+3. **Decision Maker**:
+   - Product Owner approves rollback vs hotfix
+   - Release Engineer executes
+   - DevOps monitors infrastructure
+
+---
+
+## 🔗 Related
+
+- [OVERALL_RELEASE_PLAN.md](./OVERALL_RELEASE_PLAN.md) - Main release strategy
+- [MOBILE_RELEASE_PLAN.md](./MOBILE_RELEASE_PLAN.md) - Mobile-specific process
+- [../../CHANGELOG.md](../../CHANGELOG.md) - Version history
+
+---
+
+**Last Updated**: 2026-03-05  
+**Severity Levels**:
+- 🔴 CRITICAL: Service down, data loss, security (< 1 hour)
+- 🟠 HIGH: Major feature broken, workaround available (< 4 hours)
+- 🟡 MEDIUM: Minor feature affected (next release OK)

docs/RELEASE/MOBILE_RELEASE_PLAN.md

@@ -0,0 +1,564 @@
+# Mobile App Release Plan
+
+**For Staff Mobile & Client Mobile Apps**
+
+---
+
+## 📱 Overview
+
+This document covers release procedures for:
+
+- **Staff Mobile App** (aka "Worker Mobile") - `krow-withus-worker-mobile`
+- **Client Mobile App** - `krow-withus-client-mobile`
+
+Both apps:
+- Built with Flutter
+- Distributed to iOS & Android app stores
+- Maintain independent versions
+- Have independent CHANGELOGs
+- Share backend infrastructure
+
+---
+
+## 🏷️ Tag & Release Naming
+
+### Tag Format
+
+```
+krow-withus-<app>-mobile/<environment>-v<major>.<minor>.<patch>
+```
+
+### Examples
+
+**Staff Mobile (Worker Mobile)**
+```
+krow-withus-worker-mobile/dev-v0.1.0
+krow-withus-worker-mobile/stage-v0.2.0
+krow-withus-worker-mobile/prod-v1.0.0
+krow-withus-worker-mobile/prod-v1.0.1-hotfix.1
+```
+
+**Client Mobile**
+```
+krow-withus-client-mobile/dev-v0.1.0
+krow-withus-client-mobile/stage-v0.2.0
+krow-withus-client-mobile/prod-v1.0.0
+```
+
+### GitHub Release Names
+
+```
+Krow With Us - Worker Mobile - DEV - v0.1.0
+Krow With Us - Worker Mobile - STAGE - v0.2.0
+Krow With Us - Worker Mobile - PROD - v1.0.0
+
+Krow With Us - Client Mobile - DEV - v0.1.0
+Krow With Us - Client Mobile - STAGE - v0.2.0
+Krow With Us - Client Mobile - PROD - v1.0.0
+```
+
+---
+
+## 📝 CHANGELOG Management
+
+### Location
+
+Each app has its own CHANGELOG in the `apps/mobile/` directory structure:
+
+```
+apps/mobile/
+├── packages/
+│   ├── features/
+│   │   ├── staff/
+│   │   │   ├── authentication/CHANGELOG.md
+│   │   │   ├── home/CHANGELOG.md
+│   │   │   ├── payments/CHANGELOG.md
+│   │   │   ├── shifts/CHANGELOG.md
+│   │   │   └── ... (other staff features)
+│   │   └── client/
+│   │       ├── dashboard/CHANGELOG.md
+│   │       ├── orders/CHANGELOG.md
+│   │       └── ... (other client features)
+│   └── ... (other packages)
+├── apps/
+│   ├── staff_app/CHANGELOG.md              ← Staff app root
+│   └── client_app/CHANGELOG.md             ← Client app root
+└── CHANGELOG.md                            ← Consolidated (optional)
+```
+
+### App-Level CHANGELOG Format
+
+**File**: `apps/mobile/apps/staff_app/CHANGELOG.md`
+
+```markdown
+# Staff Mobile App - Change Log
+
+## [0.2.0] - 2026-03-15
+
+### Added
+- Feature X implementation
+- Feature Y enhancement
+- New UI component Z
+
+### Fixed
+- Bug fix for issue #123
+- Crash when loading payments
+
+### Changed
+- Updated design system
+- Improved performance
+
+### Deprecated
+- Removed old API endpoint
+
+## [0.1.0] - 2026-03-01
+
+### Added
+- Initial release
+- Authentication with phone & OTP
+- Shift browsing and booking
+- Clock in/out functionality
+- Payment history view
+```
+
+### Consolidated CHANGELOG (Optional)
+
+**File**: `apps/mobile/CHANGELOG.md` (at root of mobile folder)
+
+High-level overview of both apps:
+
+```markdown
+# Krow Workforce - Mobile Apps - Change Log
+
+## Staff Mobile v0.2.0 + Client Mobile v0.1.0 - 2026-03-15
+
+### Staff Mobile v0.2.0
+- Feature improvements
+- Bug fixes
+
+### Client Mobile v0.1.0
+- Initial release
+
+## Previous versions...
+```
+
+---
+
+## 📝 Version Files
+
+### Staff Mobile App
+
+**Primary Version File**: `apps/mobile/apps/staff_app/pubspec.yaml`
+
+```yaml
+name: staff_app
+description: "Krow With Us - Staff App"
+
+# Version format: MAJOR.MINOR.PATCH+BUILD_NUMBER
+version: 0.1.0+1
+
+environment:
+  sdk: '>=3.10.0 <4.0.0'
+  flutter: '>=3.38.0 <4.0.0'
+```
+
+**Rules**:
+- Update version before each release
+- Bump build number (+1) every build
+- SemVer only for version part (before +)
+
+### Client Mobile App
+
+**Primary Version File**: `apps/mobile/apps/client_app/pubspec.yaml`
+
+```yaml
+name: client_app
+description: "Krow With Us - Client App"
+
+version: 0.1.0+1
+
+environment:
+  sdk: '>=3.10.0 <4.0.0'
+  flutter: '>=3.38.0 <4.0.0'
+```
+
+---
+
+## 🚀 Release Workflow
+
+### Step 1: Create Release Branch
+
+```bash
+cd /Users/achintha/Documents/GitHub/krow-workforce
+
+# For Staff Mobile
+git checkout -b release/staff-mobile-v0.2.0
+
+# For Client Mobile
+git checkout -b release/client-mobile-v0.2.0
+```
+
+---
+
+### Step 2: Update Version Numbers
+
+#### Staff Mobile Example (v0.1.0 → v0.2.0)
+
+**File**: `apps/mobile/apps/staff_app/pubspec.yaml`
+
+```yaml
+# Old
+version: 0.1.0+5
+
+# New
+version: 0.2.0+6
+```
+
+#### Client Mobile Example (v0.1.0 → v0.2.0)
+
+**File**: `apps/mobile/apps/client_app/pubspec.yaml`
+
+```yaml
+# Old
+version: 0.1.0+3
+
+# New
+version: 0.2.0+4
+```
+
+---
+
+### Step 3: Update CHANGELOG
+
+**File**: `apps/mobile/apps/staff_app/CHANGELOG.md`
+
+Add entry at **top**:
+
+```markdown
+# Staff Mobile App - Change Log
+
+## [0.2.0] - 2026-03-05
+
+### Added
+- New shift details page with profile gating
+- Benefits overview section
+- Auto-match functionality
+
+### Fixed
+- Payment history display bug
+- Clock-in location verification
+
+### Changed
+- Updated design system components
+- Improved shift booking flow
+
+## [0.1.0] - 2026-02-15
+...
+```
+
+---
+
+### Step 4: Commit Changes
+
+```bash
+cd /Users/achintha/Documents/GitHub/krow-workforce
+
+# Stage changes
+git add apps/mobile/apps/staff_app/pubspec.yaml
+git add apps/mobile/apps/staff_app/CHANGELOG.md
+
+# Commit
+git commit -m "chore(staff-mobile): bump version to 0.2.0
+
+- Updated pubspec.yaml version: 0.1.0 → 0.2.0
+- Updated build number: 5 → 6
+- Updated CHANGELOG.md with v0.2.0 changes"
+```
+
+---
+
+### Step 5: Create Pull Request
+
+```bash
+# Push release branch
+git push origin release/staff-mobile-v0.2.0
+
+# Create PR (GitHub CLI)
+gh pr create \
+  --title "Release: Staff Mobile v0.2.0" \
+  --body "## Release: Staff Mobile v0.2.0
+
+### Changes
+- See CHANGELOG.md for full list
+
+### Testing
+- [ ] All tests passing
+- [ ] Manual testing complete
+- [ ] CodeMagic build successful
+
+### Checklist
+- [x] Version updated
+- [x] CHANGELOG updated
+- [x] Branch created from main
+- [ ] Approved by team lead"
+```
+
+---
+
+### Step 6: Merge to Main
+
+Once PR is approved:
+
+```bash
+# Switch to main
+git checkout main
+git pull origin main
+
+# Merge (fast-forward only)
+git merge --ff-only release/staff-mobile-v0.2.0
+
+# Push to remote
+git push origin main
+
+# Delete release branch
+git push origin --delete release/staff-mobile-v0.2.0
+```
+
+---
+
+### Step 7: Create Git Tag
+
+```bash
+# For DEV release
+git tag -a krow-withus-worker-mobile/dev-v0.2.0 \
+  -m "Staff Mobile v0.2.0 - Dev Release
+
+Features:
+- Shift details improvements
+- Benefits overview
+- Auto-match functionality
+
+Testing:
+- All unit tests passing
+- Manual QA on dev environment"
+
+# For STAGE release
+git tag -a krow-withus-worker-mobile/stage-v0.2.0 \
+  -m "Staff Mobile v0.2.0 - Stage Release"
+
+# For PROD release
+git tag -a krow-withus-worker-mobile/prod-v0.2.0 \
+  -m "Staff Mobile v0.2.0 - Production Release"
+```
+
+**Push tags**:
+
+```bash
+git push origin krow-withus-worker-mobile/dev-v0.2.0
+git push origin krow-withus-worker-mobile/stage-v0.2.0
+git push origin krow-withus-worker-mobile/prod-v0.2.0
+```
+
+---
+
+### Step 8: Create GitHub Release
+
+1. Go to: GitHub → Releases → Draft a new release
+2. Fill in:
+
+```
+Tag version: krow-withus-worker-mobile/dev-v0.2.0
+
+Release title:
+Krow With Us - Worker Mobile - DEV - v0.2.0
+
+Description:
+
+## 🎯 What's New in v0.2.0
+
+### ✨ Features
+- Shift details page with profile completion gating
+- Benefits overview with sick leave tracking
+- Auto-match shift recommendations
+
+### 🔧 Improvements
+- Faster payment history loading
+- Better shift booking UX
+- Improved clock-in reliability
+
+### 🐛 Bug Fixes
+- Fixed payment display date issue
+- Fixed location verification on iOS 15+
+- Fixed crash when no shifts available
+
+## 📦 Installation
+
+**iOS**: Download via TestFlight (internal) or App Store
+**Android**: Download via Play Store
+
+## 🔗 Dependencies
+
+Requires:
+- Backend API v0.1.0+
+- DataConnect schema v0.3.0+
+
+## ⚠️ Known Issues
+
+- Location permissions take 5-10 seconds on first install
+- Workaround: Grant permissions in Settings app
+
+## 📝 Notes for QA
+
+- Test on actual device, not emulator
+- Verify clock-in with GPS enabled
+- Test all payment history edge cases
+
+---
+
+Release Date: 2026-03-05
+Build Number: 6
+```
+
+3. **Optional**: Attach build artifacts (APK/AAB from CodeMagic)
+4. **Click**: "Publish release"
+
+---
+
+## 🔄 Deployment Flow
+
+### Dev Release → Staging
+
+After dev is tested:
+
+```bash
+# Create stage tag from same commit
+git tag -a krow-withus-worker-mobile/stage-v0.2.0 \
+  krow-withus-worker-mobile/dev-v0.2.0 \
+  -m "Staff Mobile v0.2.0 - Stage Release"
+
+git push origin krow-withus-worker-mobile/stage-v0.2.0
+
+# Deploy using CodeMagic or manual process
+```
+
+### Staging Release → Production
+
+After QA approval:
+
+```bash
+# Create prod tag from same commit
+git tag -a krow-withus-worker-mobile/prod-v0.2.0 \
+  krow-withus-worker-mobile/stage-v0.2.0 \
+  -m "Worker Mobile v0.2.0 - Production Release"
+
+git push origin krow-withus-worker-mobile/prod-v0.2.0
+
+# Deploy to production
+```
+
+---
+
+## 📱 App Store Distribution
+
+### iOS App Store
+
+**Version Name**: Match pubspec.yaml version (0.2.0)  
+**Build Number**: Match pubspec.yaml build number (+6)
+
+**Steps**:
+1. Ensure TestFlight build passed
+2. Submit to App Review
+3. Apple reviews (3-5 days)
+4. Release to users (can be phased)
+
+### Google Play Store
+
+**Version Name**: Match pubspec.yaml version (0.2.0)  
+**Version Code**: Match pubspec.yaml build number (6)
+
+**Steps**:
+1. Upload APK/AAB from CodeMagic
+2. Fill in release notes (from CHANGELOG)
+3. Submit for review
+4. Google reviews (hours to 24h)
+5. Release to users (can be phased, e.g., 10% then 100%)
+
+---
+
+## 🔧 Pre-Release Checklist
+
+Before creating tags:
+
+- [ ] All PRs merged to main
+- [ ] Code review complete
+- [ ] Tests passing (unit, widget, integration)
+- [ ] No lint/analysis errors: `flutter analyze`
+- [ ] Pubspec.yaml version updated
+- [ ] Build number incremented
+- [ ] CHANGELOG.md updated with date
+- [ ] Screenshots prepared (fresh)
+- [ ] Release notes drafted
+- [ ] No hardcoded strings (use translations)
+- [ ] No debug prints remaining
+- [ ] Performance acceptable (app launch < 3 seconds)
+- [ ] Screen lock/unlock works
+- [ ] Deep links tested
+- [ ] Notifications working
+- [ ] GPS/location working
+- [ ] Camera permissions working
+- [ ] All user-facing text reviewed
+
+---
+
+## 🎯 Release Cadence
+
+### Development Releases (dev)
+
+- **Frequency**: Weekly
+- **Day**: Monday 10:00 UTC
+- **Process**: Quick, test in dev only
+
+### Staging Releases (stage)
+
+- **Frequency**: Bi-weekly (on sprint/feature completion)
+- **Day**: Wednesday before production
+- **Process**: Full QA testing, 1 week in staging
+
+### Production Releases (prod)
+
+- **Frequency**: Monthly (end of sprint)
+- **Day**: Sunday/Monday morning (low traffic)
+- **Process**: Full validation, market distribution
+
+---
+
+## 🔗 Related
+
+- [OVERALL_RELEASE_PLAN.md](./OVERALL_RELEASE_PLAN.md) - General strategy
+- [HOTFIX_PROCESS.md](./HOTFIX_PROCESS.md) - Emergency procedures
+- [../../CHANGELOG.md](../../CHANGELOG.md) - Root-level history
+
+---
+
+## 📞 Common Questions
+
+**Q: What if I need to release just one app (not both)?**
+A: Completely fine! Each app is independent. Release when ready.
+
+**Q: Do I need to update the root CHANGELOG?**
+A: Optional. If you do, keep it high-level and reference app-specific CHANGELOGs.
+
+**Q: What about shared packages inside mobile/?**
+A: If shared package updated, mention in both app CHANGELOGs.
+
+**Q: How do I handle breaking changes?**
+A: MAJOR version bump (0.x → 1.x) and clearly document in CHANGELOG.
+
+**Q: Can I release dev and stage on different days?**
+A: Yes, no fixed schedule for dev/stage. Prod should be consistent (Sundays).
+
+---
+
+**Last Updated**: 2026-03-05  
+**Owner**: Mobile Engineering Team  
+**Status**: Active

docs/RELEASE/OVERALL_RELEASE_PLAN.md

@@ -0,0 +1,452 @@
+# KROW Workforce - Overall Release Plan
+
+**Document Version**: 1.0  
+**Created**: 2026-03-05  
+**Last Updated**: 2026-03-05  
+**Product Scope**: All products (Mobile, Web, Backend, Database)
+
+---
+
+## 📋 Overview
+
+This document outlines the release strategy for KROW Workforce monorepo containing 5 products:
+
+1. **Staff Mobile App** (Flutter - iOS/Android)
+2. **Client Mobile App** (Flutter - iOS/Android)
+3. **Web Dashboard** (React/Vite)
+4. **Backend Services** (Node.js - Command API, Core API)
+5. **Database** (Firebase Data Connect with PostgreSQL)
+
+---
+
+## 🔗 Versioning Strategy
+
+### Semantic Versioning (SemVer)
+
+All products use **Semantic Versioning 2.0.0**:
+
+```
+MAJOR.MINOR.PATCH-QUALIFIER
+0.1.0
+1.2.3-rc.1
+```
+
+- **MAJOR** (0→1): Breaking changes, major features
+- **MINOR** (1→2): Backward-compatible new features
+- **PATCH** (3→4): Bug fixes, minor improvements
+- **QUALIFIER** (optional): `-rc.1`, `-beta.1`, `-hotfix.1`
+
+### Version Independence
+
+Each product maintains **independent versioning**:
+- Products release on their own schedule
+- No requirement to synchronize versions
+- Can release major updates independently
+
+---
+
+## 🏷️ Git Tag Naming Convention
+
+### Standard Format
+
+```
+<product>/<environment>-v<major>.<minor>.<patch>
+```
+
+### Products & Environments
+
+| Product | Tag Prefix | Environments |
+|---------|-----------|---------------|
+| Staff Mobile | `krow-withus-worker-mobile` | dev, stage, prod |
+| Client Mobile | `krow-withus-client-mobile` | dev, stage, prod |
+| Web Dashboard | `web-dashboard` | dev, stage, prod |
+| Command API | `command-api` | dev, stage, prod |
+| Core API | `core-api` | dev, stage, prod |
+| DataConnect | `dataconnect` | stage, prod |
+
+### Environments
+
+- **dev**: Development releases (daily/weekly), unstable
+- **stage**: Staging releases (bi-weekly), pre-production testing
+- **prod**: Production releases (monthly), stable, customer-facing
+
+### Examples
+
+```
+krow-withus-worker-mobile/dev-v0.1.0
+krow-withus-client-mobile/stage-v0.2.0
+web-dashboard/prod-v1.0.0
+command-api/dev-v0.2.1
+core-api/prod-v0.1.0
+```
+
+---
+
+## 📅 Release Cadence
+
+### Development Releases (dev)
+
+- **Frequency**: Weekly or as-needed
+- **Scope**: Feature completions, bug fixes
+- **Duration**: Not guaranteed stable
+- **Deployment**: Dev environment only
+- **Who**: Development team
+
+### Staging Releases (stage)
+
+- **Frequency**: Bi-weekly (typically mid/end of sprint)
+- **Scope**: Sprint completion, feature milestones
+- **Duration**: 1-2 weeks stability expected
+- **Deployment**: Staging environment for QA
+- **Who**: QA team validates
+
+### Production Releases (prod)
+
+- **Frequency**: Monthly or sprint-based
+- **Scope**: Feature milestone completion, critical fixes
+- **Duration**: 4+ weeks standard support
+- **Deployment**: Production environment (customer-facing)
+- **Who**: Product owner approves, DevOps deploys
+
+---
+
+## 🔄 Product Dependency & Deployment Order
+
+### Critical Path (for synchronized releases)
+
+Deploy in this order:
+
+1. **DataConnect Schema** (if schema changed)
+   - Deploy schema changes first
+   - All APIs depend on schema availability
+
+2. **Backend Services** (parallel OK)
+   - Command API
+   - Core API
+   - Both can deploy simultaneously
+
+3. **Web Dashboard**
+   - Can deploy once backend ready
+   - Test API endpoints stable
+
+4. **Mobile Apps** (parallel OK)
+   - Staff Mobile
+   - Client Mobile
+   - Both can deploy simultaneously, independent of web
+
+### Independent Releases
+
+Products **can release independently** if:
+- No backend schema changes
+- No breaking API changes
+- No data migrations required
+
+Example: Staff Mobile can release UI improvements without web/backend changes.
+
+---
+
+## 📝 CHANGELOG Management
+
+### Location & Structure
+
+Each major product maintains its own CHANGELOG:
+
+```
+apps/mobile/packages/features/staff/*/CHANGELOG.md
+apps/mobile/packages/features/client/*/CHANGELOG.md
+apps/web/CHANGELOG.md
+backend/command-api/CHANGELOG.md
+backend/core-api/CHANGELOG.md
+CHANGELOG.md (root - high-level overview)
+```
+
+### Format
+
+```markdown
+| Date | Version | Change |
+|------|---------|--------|
+| 2026-03-05 | 0.1.0 | Initial release - [feature list] |
+```
+
+### What to Track
+
+- Features added
+- Bugs fixed
+- Breaking changes (clearly marked ⚠️)
+- Dependencies upgraded
+- Migration steps (if applicable)
+
+---
+
+## ✅ Release Checklist
+
+### Pre-Release (48 hours before)
+
+- [ ] All PRs merged to main
+- [ ] Code review complete
+- [ ] All tests passing (unit, integration, E2E)
+- [ ] No lint/type errors
+- [ ] Mobile builds succeed (CodeMagic)
+- [ ] Performance benchmarks acceptable
+- [ ] Security scan completed
+- [ ] CHANGELOG.md updated with all changes
+- [ ] Documentation updated
+- [ ] Team notified of pending release
+
+### Release Day
+
+- [ ] Update version numbers in all relevant files
+- [ ] Update CHANGELOG with date
+- [ ] Git commit: `git commit -m "chore: bump version to X.Y.Z"`
+- [ ] Git push changes to main
+- [ ] Create git tag: `git tag -a <product>/<env>-v<version> -m "Release message"`
+- [ ] Push tags: `git push origin <tag-name>`
+- [ ] Deploy to target environment
+- [ ] Smoke tests pass
+- [ ] Create GitHub Release page
+- [ ] Notify stakeholders
+
+### Post-Release (24 hours)
+
+- [ ] Monitor error logs
+- [ ] Verify all features work end-to-end
+- [ ] Performance is acceptable
+- [ ] No regressions reported
+- [ ] Users updated if needed
+- [ ] Document any issues
+
+---
+
+## 🔐 Protected Tags
+
+### Branch Protection Rules
+
+**Production tags require approval:**
+
+- Tag pattern: `*/prod-v*`
+- Require pull request review (1+ approval)
+- Require status checks to pass
+- Prevent force pushes
+- Disable deletions
+
+**Staging tags recommended:**
+
+- Tag pattern: `*/stage-v*`
+- Consider: Require at least 1 approval
+- Status checks should pass
+
+**Dev tags open:**
+
+- Tag pattern: `*/dev-v*`
+- No restrictions
+- Allow fast iteration
+
+---
+
+## 🚨 Rollback Procedures
+
+### For Production Issues
+
+**If critical issue detected:**
+
+1. **Identify** the product and issue
+2. **Assess** impact and severity
+3. **Decide** rollback vs hotfix
+   - Rollback: Undo entire release
+   - Hotfix: Fix and re-release (see HOTFIX_PROCESS.md)
+4. **Execute** rollback:
+   ```bash
+   # Revert commit
+   git revert <commit-hash> -m 1
+   git push origin main
+   
+   # Or switch traffic back to previous version
+   # (depends on deployment infrastructure)
+   ```
+5. **Communicate** with users
+6. **Plan** hotfix or next release
+
+### Time Windows
+
+- **Awareness**: 15-30 minutes (monitoring)
+- **Decision**: 15-30 minutes (severity assessment)
+- **Execution**: 15-60 minutes (rollback deployment)
+- **Verification**: 30-60 minutes (smoke tests)
+- **Communication**: Immediate + 24h updates
+
+**Total**: 2-4 hours from detection to stable state
+
+---
+
+## 📊 Release Templates & Tools
+
+### Git Commands
+
+```bash
+# Create tag
+git tag -a krow-withus-worker-mobile/dev-v0.1.0 \
+  -m "Staff Mobile v0.1.0 - Feature X"
+
+# Push tag
+git push origin krow-withus-worker-mobile/dev-v0.1.0
+
+# View tags for product
+git tag -l "krow-withus-worker-mobile/*" --sort=-version:refname
+
+# See what's in a tag
+git show krow-withus-worker-mobile/dev-v0.1.0
+
+# Delete tag (if mistake)
+git tag -d krow-withus-worker-mobile/dev-v0.1.0
+git push origin --delete krow-withus-worker-mobile/dev-v0.1.0
+```
+
+### GitHub Release Template
+
+```markdown
+# Krow With Us - Worker Mobile - DEV - v0.1.0
+
+**Release Date**: [Date]
+**Environment**: Development
+
+## What's New
+
+### ✨ Features
+- Feature 1 description
+- Feature 2 description
+
+### 🔧 Improvements
+- Improvement 1
+- Improvement 2
+
+### 🐛 Bug Fixes
+- Bug fix 1
+- Bug fix 2
+
+## Dependencies
+
+Requires:
+- Backend API v0.1.0 or higher
+- DataConnect schema v0.3.0 (if updated)
+
+## Installation
+
+[Download links & instructions]
+
+## Known Issues
+
+- Issue 1: [desc] (Workaround: ...)
+
+## Support
+
+contact: support@krow-workforce.com
+```
+
+---
+
+## 🔄 Hotfix Releases
+
+See [HOTFIX_PROCESS.md](./HOTFIX_PROCESS.md) for emergency procedures.
+
+Quick summary:
+1. Branch from production tag
+2. Fix the issue
+3. Bump PATCH version only
+4. Test and deploy immediately
+5. Create hotfix tag
+
+---
+
+## 📱 Mobile-Specific Release Process
+
+See [MOBILE_RELEASE_PLAN.md](./MOBILE_RELEASE_PLAN.md) for detailed mobile app process including:
+- Staff Mobile vs Client Mobile differences
+- Build number management
+- CodeMagic integration
+- App store distribution
+- CHANGELOG per app
+
+---
+
+## 🎯 Release Coordination
+
+### Single Product Release
+
+1. Update version files
+2. Update CHANGELOG
+3. Commit & push
+4. Create tag
+5. Deploy
+6. Create GitHub Release
+
+**Time**: 30-45 minutes (excluding testing)
+
+### Multi-Product Release (e.g., v1.0.0)
+
+**Pre-release phase** (1 week before):
+- Code freeze announced
+- QA testing begins
+- No new features merged
+
+**Release phase** (2-3 days):
+- Staging release (all products)
+- QA validation
+- Product owner sign-off
+
+**Production phase** (1 day):
+- Deploy in dependency order
+- Smoke tests each product
+- Monitor 24 hours
+- User communication
+
+**Time**: 5-7 days total, 4 hours active deployment
+
+---
+
+## 📞 Roles & Responsibilities
+
+| Role | Responsibility |
+|------|-----------------|
+| **Developer** | Keep code release-ready, update versions |
+| **QA** | Test staging releases, validate prod |
+| **Release Engineer** | Create tags, manage deployment, monitor |
+| **Product Owner** | Approve releases, communicate timeline |
+| **DevOps** | Infrastructure ready, deployment scripts |
+
+---
+
+## 📊 Success Metrics
+
+Track these per release:
+
+- **Lead Time**: Time from code commit to production
+- **Deployment Frequency**: How often you release
+- **Change Failure Rate**: % of releases needing rollback
+- **Time to Recovery**: Time to fix production issues
+- **User Adoption**: % of users on latest version
+
+---
+
+## 📚 Related Documentation
+
+- [MOBILE_RELEASE_PLAN.md](./MOBILE_RELEASE_PLAN.md) - Mobile app releases
+- [HOTFIX_PROCESS.md](./HOTFIX_PROCESS.md) - Emergency procedures
+- [../../RELEASE_STRATEGY.md](../../RELEASE_STRATEGY.md) - Original detailed guide
+- [../../CHANGELOG.md](../../CHANGELOG.md) - Root version history
+
+---
+
+## ✅ Implementation Status
+
+- ✅ Versioning strategy: SemVer
+- ✅ Environments: dev, stage, prod
+- ✅ Tag naming: Product-specific with brand prefix
+- ✅ Product dependencies: Defined
+- ✅ Release cadence: 3 levels
+- ⏳ GitHub Actions: To be set up
+- ⏳ Deployment automation: To be set up
+
+---
+
+**Next Step**: Review [MOBILE_RELEASE_PLAN.md](./MOBILE_RELEASE_PLAN.md) for app-specific process.
+