chore(release): v0.2.0 stable release

.github/workflows/prepare-release.yml

@@ -12,15 +12,22 @@ permissions:
 
 jobs:
   # NOTE: Auto-labeling (including candidate-release) is handled by auto-label.yml
-  # This workflow aggregates ALL merged candidate-release PRs since the last release
+  # This workflow aggregates ALL merged candidate-release/release PRs since the last release
+  #
+  # Labels:
+  #   candidate-release → beta bump (0.1.1-beta.16 → 0.1.1-beta.17)
+  #   release    → stable bump (0.1.1-beta.16 → 0.2.0)
 
-  # Create/update release PR when a PR with candidate-release label is merged
+  # Create/update release PR when a PR with candidate-release or release label is merged
   create-release-pr:
     name: Create Release PR
     if: |
       github.event.action == 'closed' &&
       github.event.pull_request.merged == true &&
-      contains(github.event.pull_request.labels.*.name, 'candidate-release') &&
+      (
+        contains(github.event.pull_request.labels.*.name, 'candidate-release') ||
+        contains(github.event.pull_request.labels.*.name, 'release')
+      ) &&
       !startsWith(github.event.pull_request.head.ref, 'release/')
     runs-on: ubuntu-latest
     steps:
@@ -57,16 +64,26 @@ jobs:
             echo "No release tags found, collecting all candidate-release PRs"
           fi
 
-          # Query all merged PRs with candidate-release label since the tag date
+          # Query all merged PRs with candidate-release or release label since the tag date
           # Exclude release branch PRs
-          PR_JSON=$(gh pr list \
+          CANDIDATE_JSON=$(gh pr list \
             --state merged \
             --label "candidate-release" \
             --base main \
             --json number,title,mergedAt,headRefName \
             --limit 100 \
             --jq "[.[] | select(.mergedAt > \"$TAG_DATE\" and (.headRefName | startswith(\"release/\") | not))]"
           )
+          STABLE_JSON=$(gh pr list \
+            --state merged \
+            --label "release" \
+            --base main \
+            --json number,title,mergedAt,headRefName \
+            --limit 100 \
+            --jq "[.[] | select(.mergedAt > \"$TAG_DATE\" and (.headRefName | startswith(\"release/\") | not))]"
+          )
+          # Merge and deduplicate by PR number
+          PR_JSON=$(echo "$CANDIDATE_JSON $STABLE_JSON" | jq -s 'add | unique_by(.number)')
 
           PR_COUNT=$(echo "$PR_JSON" | jq length)
           echo "Found $PR_COUNT merged PRs since $LATEST_TAG"
@@ -125,24 +142,49 @@ jobs:
           echo "Version bump: $BUMP (current: $CURRENT_VERSION)"
           echo "Changes: $(echo "$CHANGES" | jq -r '.[] | "  - #\(.pr): \(.rawTitle)"')"
 
+      - name: Check if stable release
+        if: steps.collect.outputs.skip != 'true'
+        id: stable
+        run: |
+          IS_STABLE="${{ contains(github.event.pull_request.labels.*.name, 'release') }}"
+          echo "is_stable=$IS_STABLE" >> $GITHUB_OUTPUT
+          echo "Stable release: $IS_STABLE"
+
       - name: Calculate new version
         if: steps.collect.outputs.skip != 'true'
         id: version
         env:
           CURRENT: ${{ steps.bump.outputs.current }}
           BUMP: ${{ steps.bump.outputs.bump }}
+          IS_STABLE: ${{ steps.stable.outputs.is_stable }}
         run: |
+          if [ "$IS_STABLE" = "true" ]; then
+            # Stable release: strip prerelease suffix, apply semver bump to base
+            BASE=$(echo "$CURRENT" | sed 's/-.*$//')
+            IFS='.' read -r MAJOR MINOR PATCH <<< "$BASE"
 
-          # Parse version (handle prerelease)
-          if [[ "$CURRENT" == *"-"* ]]; then
-            # It's a prerelease, just bump the prerelease number
+            case "$BUMP" in
+              major)
+                NEW_VERSION="$((MAJOR + 1)).0.0"
+                ;;
+              minor)
+                NEW_VERSION="${MAJOR}.$((MINOR + 1)).0"
+                ;;
+              patch)
+                NEW_VERSION="${MAJOR}.${MINOR}.$((PATCH + 1))"
+                ;;
+            esac
+
+            echo "Stable release: $CURRENT -> $NEW_VERSION (bump: $BUMP)"
+          elif [[ "$CURRENT" == *"-"* ]]; then
+            # Beta release: bump the prerelease number
             BASE=$(echo "$CURRENT" | sed 's/-.*$//')
             PRE_TYPE=$(echo "$CURRENT" | sed 's/.*-\([a-z]*\).*/\1/')
             PRE_NUM=$(echo "$CURRENT" | sed 's/.*\.\([0-9]*\)$/\1/')
             NEW_PRE_NUM=$((PRE_NUM + 1))
             NEW_VERSION="${BASE}-${PRE_TYPE}.${NEW_PRE_NUM}"
           else
-            # Parse semver
+            # Already stable, apply semver bump
             IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
 
             case "$BUMP" in
@@ -202,6 +244,7 @@ jobs:
           EXISTING_NUMBER: ${{ steps.check.outputs.number }}
           EXISTING_BRANCH: ${{ steps.check.outputs.branch }}
           EXISTING_VERSION: ${{ steps.check.outputs.version }}
+          IS_STABLE: ${{ steps.stable.outputs.is_stable }}
         run: |
           TODAY=$(date +%Y-%m-%d)
           RELEASE_BRANCH="release/v${NEW_VERSION}"
@@ -257,10 +300,18 @@ jobs:
           # Build PR body with all included changes
           PR_CHANGES_LIST=$(echo "$CHANGES_JSON" | jq -r '.[] | "- #\(.pr): \(.rawTitle)"')
 
+          if [ "$IS_STABLE" = "true" ]; then
+            RELEASE_LABEL="Stable Release"
+            NPM_TAG_INFO="Package will be published to npm with \`latest\` tag"
+          else
+            RELEASE_LABEL="Release"
+            NPM_TAG_INFO="Package will be published to npm"
+          fi
+
           PR_BODY=$(cat <<EOF
-          ## Release v${NEW_VERSION}
+          ## ${RELEASE_LABEL} v${NEW_VERSION}
 
-          This PR was automatically created to prepare release v${NEW_VERSION}.
+          This PR was automatically created to prepare ${RELEASE_LABEL,,} v${NEW_VERSION}.
 
           ### Changes included
           ${PR_CHANGES_LIST}
@@ -273,7 +324,7 @@ jobs:
           ### What happens when this PR is merged
           1. Git tag \`v${NEW_VERSION}\` will be created
           2. GitHub Release will be published
-          3. Package will be published to npm
+          3. ${NPM_TAG_INFO}
 
           ---
           This PR was auto-generated by the release workflow.
@@ -286,8 +337,13 @@ jobs:
             echo "Updated existing release PR #${EXISTING_NUMBER}"
           else
             # Create new PR
+            if [ "$IS_STABLE" = "true" ]; then
+              PR_TITLE="chore(release): v${NEW_VERSION} (stable)"
+            else
+              PR_TITLE="chore(release): v${NEW_VERSION}"
+            fi
             gh pr create \
-              --title "chore(release): v${NEW_VERSION}" \
+              --title "$PR_TITLE" \
               --body "$PR_BODY" \
               --label "release" \
               --base main

CONTRIBUTING.md

@@ -63,12 +63,23 @@ pnpm build
 
 ### 1. Create a Branch
 
+Follow the branch naming convention:
+
 ```bash
-git checkout -b feature/my-feature
-# or
-git checkout -b fix/my-fix
+git checkout -b feature/my-feature    # New features
+git checkout -b fix/my-fix            # Bug fixes
+git checkout -b staging/v0.2.0        # Staging branches (use target version)
+git checkout -b release/v0.2.0        # Release branches (automated)
 ```
 
+**Branch naming rules:**
+- `feature/<name>` — New features
+- `fix/<name>` — Bug fixes
+- `docs/<name>` — Documentation changes
+- `chore/<name>` — Maintenance tasks
+- `staging/v<version>` — Pre-release staging (must use target semver)
+- `release/v<version>` — Release branches (created by CI)
+
 ### 2. Make Your Changes
 
 - Keep changes focused - one feature or fix per PR

IMPLEMENTATION_PLAN.md

@@ -39,6 +39,12 @@
 - [ ] Add `--figma-preview` to show changes without applying
 - [ ] Add `--figma-mapping <file>` for custom content mapping
 
+### Session Management
+- [x] Create `src/loop/session.ts` for pause/resume support
+- [x] Add `ralph-starter pause` command
+- [x] Add `ralph-starter resume` command
+- [ ] Store session state in `.ralph-session.json`
+
 ### Task 6: Documentation
 
 - [ ] Add content mode section to README.md

README.md

@@ -368,6 +368,33 @@ Control API call frequency to manage costs:
 ralph-starter run --rate-limit 50 "build X"
 ```
 
+**When rate limits are reached**, ralph-starter displays detailed stats:
+
+```
+⚠ Claude rate limit reached
+
+Rate Limit Stats:
+  • Session usage: 100% (50K / 50K tokens)
+  • Requests made: 127 this hour
+  • Time until reset: ~47 minutes (resets at 04:30 UTC)
+
+Session Progress:
+  • Tasks completed: 3/5
+  • Current task: "Add swarm mode CLI flags"
+  • Branch: auto/github-54
+  • Iterations completed: 12
+
+To resume when limit resets:
+  ralph-starter run
+
+Tip: Check your limits at https://claude.ai/settings
+```
+
+This helps you:
+- Know exactly when you can resume
+- Track progress on your current session
+- Understand your usage patterns
+
 ### Cost Tracking
 
 Track estimated token usage and costs during loops:

docs/docs/cli/skill.md

@@ -123,6 +123,16 @@ installed skills from three locations:
 Detected skills are matched against the project's tech stack
 and included in the agent's prompt context when relevant.
 
+## Auto Skill Discovery
+
+When running a task, ralph-starter can also query the skills.sh
+registry to find and install relevant skills automatically.
+If you want to disable this behavior, set:
+
+```bash
+RALPH_DISABLE_SKILL_AUTO_INSTALL=1
+```
+
 ## Behavior
 
 - The `add` action uses `npx add-skill` under the hood.

docs/docs/wizard/overview.md

@@ -83,7 +83,7 @@ $ ralph-starter
 ❯ Yes, I know what I want to build
   No, help me brainstorm ideas
 
-? What's your idea for today?
+? Which idea do you want to build?
   (e.g., "a habit tracker app" or "an API for managing recipes")
 > a personal finance tracker
 
@@ -107,7 +107,7 @@ $ ralph-starter
 
   Complexity: Working MVP
 
-? Does this look right?
+? Is this the right specs?
 ❯ Yes, let's build it!
   I want to change something
   Start over with a different idea

package.json

@@ -66,6 +66,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.73.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "chalk": "^5.3.0",
     "chalk-animation": "^2.0.3",