chore(release): 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

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:

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",

src/cli.ts

@@ -8,7 +8,9 @@ import { checkCommand } from './commands/check.js';
 import { configCommand } from './commands/config.js';
 import { initCommand } from './commands/init.js';
 import { integrationsCommand } from './commands/integrations.js';
+import { pauseCommand } from './commands/pause.js';
 import { planCommand } from './commands/plan.js';
+import { resumeCommand } from './commands/resume.js';
 import { runCommand } from './commands/run.js';
 import { setupCommand } from './commands/setup.js';
 import { skillCommand } from './commands/skill.js';
@@ -75,6 +77,10 @@ program
   .option('--no-track-cost', 'Disable cost tracking')
   .option('--circuit-breaker-failures <n>', 'Max consecutive failures before stopping (default: 3)')
   .option('--circuit-breaker-errors <n>', 'Max same error occurrences before stopping (default: 5)')
+  .option(
+    '--context-budget <n>',
+    'Max input tokens per iteration for smart context trimming (0 = unlimited)'
+  )
   // Figma integration options
   .option('--figma-mode <mode>', 'Figma mode: spec, tokens, components, assets, content')
   .option(
@@ -229,6 +235,8 @@ program
   .option('--validate', 'Run validation after each task', true)
   .option('--no-validate', 'Skip validation')
   .option('--max-iterations <n>', 'Max iterations per task (default: 15)')
+  .option('--batch', 'Use Anthropic Batch API for 50% cost reduction (no tool use)')
+  .option('--model <name>', 'Model to use in batch mode')
   .action(async (options) => {
     await autoCommand({
       source: options.source,
@@ -240,6 +248,30 @@ program
       agent: options.agent,
       validate: options.validate,
       maxIterations: options.maxIterations ? parseInt(options.maxIterations, 10) : undefined,
+      batch: options.batch,
+      model: options.model,
+    });
+  });
+
+// ralph-starter pause - Pause a running session
+program
+  .command('pause')
+  .description('Pause a running session for later resumption')
+  .option('--reason <text>', 'Reason for pausing the session')
+  .action(async (options) => {
+    await pauseCommand({
+      reason: options.reason,
+    });
+  });
+
+// ralph-starter resume - Resume a paused session
+program
+  .command('resume')
+  .description('Resume a paused session from where it left off')
+  .option('--force', 'Force resume even if session is not paused')
+  .action(async (options) => {
+    await resumeCommand({
+      force: options.force,
     });
   });