Uh oh!
There was an error while loading. Please reload this page.
docs: staging environment design + implementation plan - #246
Conversation
Design spec and task-by-task plan for an admin-only, fully-hosted staging environment (Cloudflare Workers frontend + Railway backend + dedicated Supabase project). Includes a psycopg migration runner to close#197, idempotency fix for #196, trunk-based deploy model, and Cloudflare Access gating. Links the data-integrity / index / bug backlog the environment de-risks. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Warning Review limit reached
More reviews will be available in 59 minutes and 20 seconds. Learn how PR review limits work. Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file). ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits. 🚦 How do rate limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (3)
📝 WalkthroughWalkthroughTwo new documentation files are added: a design spec ( ChangesStaging Environment Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related issues
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Deploying with |
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ❌ Deployment failed View logs | frontend | 06766b8 | Jun 22 2026, 03:56 AM |
There was a problem hiding this comment.
🧹 Nitpick comments (3)
docs/superpowers/plans/2026-06-21-staging-environment.md (2)
270-276: 🧹 Nitpick | 🔵 Trivial | 💤 Low valueMinor: Improve the CLI output message grammar.
Line 274's message construction results in "Applied 5 migration(s):" (with a trailing colon) before listing migrations, which is grammatically awkward. Consider simplifying to match typical CLI patterns:
🔧 Suggested revision
- verb = "Baselined" if baseline else "Applied"- print(f"{verb} {len(handled)} migration(s):" if handled else "No pending migrations.")- for name in handled:- print(f" - {name}")+ if handled:+ verb = "Baselined" if baseline else "Applied"+ print(f"{verb} {len(handled)} migration(s).")+ for name in handled:+ print(f" - {name}")+ else:+ print("No pending migrations.")This separates the summary line from the list and removes the trailing colon.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/superpowers/plans/2026-06-21-staging-environment.md` around lines 270 - 276, The print statement that constructs the migration summary message has a grammatically awkward trailing colon in the output when migrations are handled. Modify the conditional print statement to remove the trailing colon from the migration count message, ensuring the summary line is cleanly separated from the list of migration names that follows on subsequent lines.
31-38: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick winAdd explicit step to update
.env.example.The file structure lists
backend/.env.exampleas modified (to documentSUPABASE_DB_URLandAPP_ENV=staging), but no task explicitly covers this update. Consider adding a step in Task 1 (psycopg dependency) or creating a standalone "documentation" sub-task to ensure this is not overlooked.💡 Suggested addition to Task 1, Step 3 (before commit)
-[ ]**Step 2.5: Update `.env.example`** (if not already documented) Run: `grep -q "SUPABASE_DB_URL" backend/.env.example || echo "SUPABASE_DB_URL=postgresql://..." >> backend/.env.example` Ensure the file documents both `SUPABASE_DB_URL` (for migration runner) and `APP_ENV=staging` as examples.Then update the existing Step 3 commit message to reference
.env.example:git add backend/requirements.txt backend/.env.example git commit -m "build: add psycopg dependency + document SUPABASE_DB_URL in .env.example (`#197`)"🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/superpowers/plans/2026-06-21-staging-environment.md` around lines 31 - 38, The staging environment plan lists backend/.env.example as a modified file in the file structure section but does not include an explicit task step that covers updating it with the new SUPABASE_DB_URL and APP_ENV=staging documentation. Add a new sub-task step (such as Step 2.5 under Task 1) that explicitly instructs to update backend/.env.example to document both SUPABASE_DB_URL (for the migration runner) and APP_ENV=staging (for the application environment), and update the commit message in the subsequent step to include this file in the git add and commit commands.docs/superpowers/specs/2026-06-21-staging-environment-design.md (1)
212-221: 🧹 Nitpick | 🔵 Trivial | 💤 Low valueVary sentence structure in the phases list to improve readability.
Lines 216–221 have repetitive sentence beginnings ("Phase X"), which LanguageTool flagged. While this structure is functional, consider alternating phrasing to improve prose flow. For example:
- "Phase 0 — migration runner + ordered/idempotent migrations" (current)
- "Bring the migration runner and ordered/idempotent migrations online (Phase 0)" (alternative)
This is a low-priority style suggestion; the current form is acceptable for a checklist-style outline.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/superpowers/specs/2026-06-21-staging-environment-design.md` around lines 212 - 221, The phases list in the Build phases section (Phase 0 through Phase 7) has repetitive sentence structure where every item begins with "**Phase X** —" which reduces readability. To fix this, vary the phrasing of some items by restructuring them with different sentence beginnings while preserving the phase numbers and core content. For example, some items could reorder the phase reference to the end in parentheses (like "Set up X (Phase Y)"), while others could keep the original format, creating an alternating pattern that improves prose flow without losing the checklist clarity or changing the actual deliverables described in each phase.Source: Linters/SAST tools
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Nitpick comments:
In `@docs/superpowers/plans/2026-06-21-staging-environment.md`:
- Around line 270-276: The print statement that constructs the migration summary
message has a grammatically awkward trailing colon in the output when migrations
are handled. Modify the conditional print statement to remove the trailing colon
from the migration count message, ensuring the summary line is cleanly separated
from the list of migration names that follows on subsequent lines.
- Around line 31-38: The staging environment plan lists backend/.env.example as
a modified file in the file structure section but does not include an explicit
task step that covers updating it with the new SUPABASE_DB_URL and
APP_ENV=staging documentation. Add a new sub-task step (such as Step 2.5 under
Task 1) that explicitly instructs to update backend/.env.example to document
both SUPABASE_DB_URL (for the migration runner) and APP_ENV=staging (for the
application environment), and update the commit message in the subsequent step
to include this file in the git add and commit commands.
In `@docs/superpowers/specs/2026-06-21-staging-environment-design.md`:
- Around line 212-221: The phases list in the Build phases section (Phase 0
through Phase 7) has repetitive sentence structure where every item begins with
"**Phase X** —" which reduces readability. To fix this, vary the phrasing of
some items by restructuring them with different sentence beginnings while
preserving the phase numbers and core content. For example, some items could
reorder the phase reference to the end in parentheses (like "Set up X (Phase
Y)"), while others could keep the original format, creating an alternating
pattern that improves prose flow without losing the checklist clarity or
changing the actual deliverables described in each phase.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: f8b34cd0-702f-473a-981d-26c4f89dfb86
📒 Files selected for processing (2)
docs/superpowers/plans/2026-06-21-staging-environment.mddocs/superpowers/specs/2026-06-21-staging-environment-design.md
Deploying with |
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs | frontend-staging | 7fe5c14 | Commit Preview URL Branch Preview URL | Jun 24 2026, 02:34 PM |
What
Adds the design spec and a task-by-task implementation plan for an admin-only, fully-hosted staging environment — a parallel mini-prod (Cloudflare Workers frontend + Railway backend + a dedicated Supabase project) where DB migrations and bugfixes can be verified before reaching prod.
Docs only — no code/behavior changes. This PR is the planning artifact; implementation lands in follow-up PRs per the plan's tasks (which is itself a first exercise of the trunk-based workflow the plan defines).
docs/superpowers/specs/2026-06-21-staging-environment-design.mddocs/superpowers/plans/2026-06-21-staging-environment.mdKey decisions captured
maincontinuously deploys to staging; aproductionbranch (fast-forwarded from a verifiedmaincommit) deploys to prod.mainvia its own PR): a ~50-line psycopg-basedbackend/db/migrate.pyover the Supabase direct connection, with aschema_migrationstracking table and orderedmigrations/dir. Also makesmigration_cosmetics.sqlidempotent (migration_cosmetics.sql adds FK constraints non-idempotently — re-run fails #196).noindex; admin email allowlist; service token on the Worker→backend hop.Backlog this environment de-risks
Migration plumbing (#197, #196); data-integrity migrations (#195, #181, #180, #179); index additions (#178, #177, #176, #161, #160); backend bugs (#158, #168); frontend bugs (#191, #186, #185, #184, #183, #166, #165, #164); prerequisite #163 (dep pinning, tracked separately).
Notes / open questions
--baselinerun (documented in the plan).🤖 Generated with Claude Code
Summary by CodeRabbit