Development Workflow

Branch Strategy

Deployment Branches (Auto-triggered)

These branches trigger deployments when pushed to:

Local Development

Pre-commit Hooks

Husky runs automatically on commit:

• Biome lint and format on staged files
• TypeScript type checking on affected packages

Commands

# Start development servers
./start-dev.sh --apps frontend,backend --packages db,api
 
# Run all checks locally
pnpm lint && pnpm typecheck && pnpm test
 
# Run specific test file
pnpm vite:test --run path/to/test.spec.ts

Opening a Pull Request

When your feature or fix is ready, use the /open-pr Claude command to create a well-structured pull request.

# In Claude Code, type:
/open-pr

The command automatically:

1. Analyzes the diff between your branch and develop
2. Identifies affected packages and the type of changes
3. Generates a comprehensive PR description (summary, rationale, technical details, testing instructions, impact analysis)
4. Creates the PR via GitHub CLI (gh pr create)

PR Title Conventions

PR titles follow the conventional commits format:

Examples:

• fix(frontend): resolve issue with user preferences not saving
• feat(api): add AI-powered search functionality
• refactor(db): optimize inventory query performance

Changeset Reminder

Before or after opening your PR, generate a changeset with the /write-changeset command. This creates a versioning entry in .changeset/ describing what changed and the appropriate version bump (patch, minor, or major).

/write-changeset

Pull Request Checks

When you open a PR against develop, GitHub Actions runs these checks automatically:

pnpm turbo run lint --affected

pnpm turbo run typecheck --affected

pnpm turbo run test --affected

pnpm depcheck && pnpm check:packages

Code Review Workflow

After your PR is created, CodeRabbit (our automated code review bot) will analyze it and post review comments. Here’s the full review cycle:

/pr-review-analysis 2159

/pr-review-resolve

Claude-Assisted Development

We use Claude Code extensively throughout our development workflow. Claude commands (invoked by typing /command-name in Claude Code) automate repetitive tasks and enforce project conventions.

Key Workflows

Feature ideation pipeline:

/refine-idea → /create-prd → /create-plan

Takes a feature from rough idea to a structured implementation plan with specs saved in specs/{feature-name}/.

PR review pipeline:

/open-pr → wait for review → /pr-review-analysis → /pr-review-resolve

Creates the PR, triages review comments, and resolves them — all from Claude Code.

Parallel development:

/worktree {feature-name} → work in separate directory → /worktree-cleanup {feature-name}

Spin up isolated git worktrees for parallel Claude Code sessions on different features.

See the full Claude Commands Reference for all available commands.

Deployment

Manual Deployment

Use the deploy script to deploy any branch to staging or production:

# Deploy develop branch to production
./scripts/deploy.sh prod develop
 
# Deploy develop branch to staging
./scripts/deploy.sh staging develop
 
# Deploy a feature branch to staging for testing
./scripts/deploy.sh staging feature/my-feature

The script handles:

1. Frontend deployment (pushes to vercel-prod or vercel-staging)
2. Backend deployment (pushes to ecs-prod-backend or ecs-staging-backend)
3. Admin deployment (pushes to admin-prod or admin-staging)
4. Trigger.dev tasks deployment

Automatic Deployments

Versioning with Changesets

We use Changesets  for versioning:

1. Add a changeset when making notable changes (use /write-changeset in Claude Code or manually):

   pnpm changeset

2. Changesets bot creates a “Release” PR that:

   • Bumps versions in package.json files
   • Updates CHANGELOG.md files
   • Creates git tags on merge

3. Git tags trigger deployment workflows for the tagged packages.

Infrastructure