Development Workflow¶

This document describes the standard development workflow for the Rose project.

Setup and authorization¶

From the repository root, ./bootstrap.py downloads environment files and installs dependencies. Use --skip-env to keep existing environment files, or --force to recreate the Python virtual environment. Do not edit .env files by hand.

Agent work uses the current user-authorized scope: creating a commit does not implicitly authorize opening or merging a PR. When asked to push to an existing PR, keep its description aligned with the actual changes. Target develop, never main, for feature PRs. Use conventional commit messages.

After committing, verify the result and git status --short: a pre-commit formatter can rewrite files and abort even if the visible tail of the hook output looks green. Re-stage only the task's files and retry; preserve unrelated working-tree changes.

Workflow Overview¶

flowchart LR A[git-add-worktree] --> B[Develop & Commit] B --> C[Create PR] C --> D[rose-merge-branch]

Step 1: Create a Worktree¶

Use git-add-worktree to create an isolated workspace for your feature:

# From the main repository directory
git-add-worktree feature/my-feature

This creates a new directory at ../feature/my-feature with a fresh checkout.

Step 2: Develop¶

Work in the new worktree directory:

cd ../feature/my-feature

# Make changes and commit
git add .
git commit -m "feat: implement my feature"

Optional: isolated Supabase preview branch¶

If your work touches migrations, RLS, RPCs, or anything else that needs a real Postgres DB to test against, spin up a per-branch Supabase DB:

./bootstrap.py --branch

This creates an isolated Supabase Postgres branch keyed to the current git ref, wires its credentials into backend/.env.local and frontend/.env.local, then seeds synthetic data so the backoffice is immediately usable. The branch is auto-deleted when the PR closes.

See Supabase Preview Branches and Supabase Seeding for the full reference.

Step 3: Create a Pull Request¶

Push your branch and create a PR:

git push -u origin feature/my-feature
gh pr create --base develop

Step 4: Merge with rose-merge-branch¶

When ready to merge, use the CLI tool:

cd backend
poetry shell
rose-merge-branch

See CLI Merge Branch for detailed options and troubleshooting.

Why This Workflow?¶

Step	Benefit
git-add-worktree	Work on multiple features simultaneously without stashing
Create PR	Get code review and CI checks before merging
rose-merge-branch	Ensures tests pass and follows consistent merge process