🔀 Development Workflow

📋 Universal Agent Workflow System

Established July 27, 2026

Applies to ALL coding agents across ALL repos (10 GitHub + 2 Azure DevOps).

🌿 Branching Rules

• Always branch from main as agent/<description>
• NEVER commit directly to main
• Use descriptive, kebab-case branch names

Examples

agent/add-convex-schema
agent/fix-login-flow
agent/redesign-header
agent/add-payment-webhook

🔄 Development Flow

Every feature or fix follows this 10-step flow:

Step Details

1. Branch from main: git checkout main && git pull && git checkout -b agent/<description>
2. Develop locally: Make changes, test iteratively
3. Run & screenshot: Start dev server, capture screenshots to test-screenshots/
4. Push branch: git push -u origin agent/<description>
5. Vercel preview: Auto-created on push — wait for deployment URL
6. Open PR: Use the PR template (auto-populates from .github/PULL_REQUEST_TEMPLATE.md)
7. Post to Discord: Share screenshots + preview link + PR link
8. Mike reviews: Address feedback if needed
9. Merge to main: Squash merge preferred
10. Prod deploy: Vercel production deploy + Convex auto-deploy (if configured)

📝 PR Template

Every GitHub repo has .github/PULL_REQUEST_TEMPLATE.md. PRs auto-populate with this template:

## Summary
<What does this PR do? Why is it needed?>

## Changes Made
- <Change 1>
- <Change 2>
- <Change 3>

## Testing Checklist
- [ ] Ran locally without errors
- [ ] All routes/pages load correctly
- [ ] No console errors
- [ ] Screenshots captured

## Screenshots
<Drag screenshots here or reference test-screenshots/ files>

## Preview URL
<Vercel preview URL from push deployment>

## Convex Note
<Any Convex schema/migration changes? "None" if not applicable>

📸 Screenshot Convention

• Save to test-screenshots/ in repo root
• Named: <feature>-<date>.png (e.g., login-page-2026-07-27.png)
• Committed to the branch — visible in PR file listing
• In .gitignore on main as a safety net (so screenshots never reach production)
• Auto-cleaned when branch is deleted after merge

# Example screenshot workflow
npm run dev -- --port 3456

# Capture screenshot
npx playwright-core screenshot --browser=chromium \
  --viewport-size=1400,900 --wait-for-timeout=3000 \
  "http://localhost:3456" ./test-screenshots/login-page-2026-07-27.png

# Commit to branch
git add test-screenshots/
git commit -m "feat: add login page screenshots"

⚡ Convex Auto-Deploy (GitHub Actions)

On merge to main, a GitHub Action automatically runs npx convex deploy.

How It Works

• Trigger: Push to main (i.e., PR merge)
• Action: npx convex deploy
• Requires: CONVEX_DEPLOY_KEY as a GitHub Actions secret

Configured Repos

# GitHub Action workflow (simplified)
name: Convex Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npx convex deploy
        env:
          CONVEX_DEPLOY_KEY: ${{ secrets.CONVEX_DEPLOY_KEY }}

🗺️ Where Applied

Workflow adoption status across all repos:

🔧 Scripts

apply-workflow-rules.ps1

PowerShell script to apply workflow rules across all repos.

scripts/apply-workflow-rules.ps1

• Adds AGENTS.md with workflow section
• Adds .github/PULL_REQUEST_TEMPLATE.md
• Adds test-screenshots/ to .gitignore
• Runs across all configured repos

set-github-secret.js

Node.js script to set GitHub Actions secrets via API (libsodium encryption).

scripts/set-github-secret.js <repo> <secret-name> <secret-value>

• Uses GitHub REST API + libsodium for encryption
• Used to set CONVEX_DEPLOY_KEY and other secrets
• Requires GITHUB_TOKEN in environment