automaker/DEVELOPMENT_WORKFLOW.md

Development Workflow

This document defines the standard workflow for keeping a branch in sync with the upstream release candidate (RC) and for shipping feature work. It is paired with check-sync.sh.

Quick Decision Rule

1. Ask the user to select a workflow:
   • Sync Workflow → you are maintaining the current RC branch with fixes/improvements and will push the same fixes to both origin and upstream RC when you have local commits to publish.
   • PR Workflow → you are starting new feature work on a new branch; upstream updates happen via PR only.
2. After the user selects, run:

   ./check-sync.sh
   

3. Use the status output to confirm alignment. If it reports diverged, default to merging upstream/<TARGET_RC> into the current branch and preserving local commits. For Sync Workflow, when the working tree is clean and you are behind upstream RC, proceed with the fetch + merge without asking for additional confirmation.

Target RC Resolution

The target RC is resolved dynamically so the workflow stays current as the RC changes.

Resolution order:

1. Latest upstream/v*rc branch (auto-detected)
2. upstream/HEAD (fallback)
3. If neither is available, you must pass --rc <branch>

Override for a single run:

./check-sync.sh --rc <rc-branch>

Pre-Flight Checklist

1. Confirm a clean working tree:

   git status
   

2. Confirm the current branch:

   git branch --show-current
   

3. Ensure remotes exist (origin + upstream):

   git remote -v
   

Sync Workflow (Upstream Sync)

Use this flow when you are updating the current branch with fixes or improvements and intend to keep origin and upstream RC in lockstep.

1. Check sync status

   ./check-sync.sh
   

2. Update from upstream RC before editing (no pulls)
   • Behind upstream RC → fetch and merge RC into your branch:

     git fetch upstream
     git merge upstream/<TARGET_RC> --no-edit
     

     When the working tree is clean and the user selected Sync Workflow, proceed without an extra confirmation prompt.
   • Diverged → stop and resolve manually.
3. Resolve conflicts if needed
   • Handle conflicts intelligently: preserve upstream behavior and your local intent.
4. Make changes and commit (if you are delivering fixes)

   git add -A
   git commit -m "type: description"
   

5. Build to verify

   npm run build:packages
   npm run build
   

6. Push after a successful merge to keep remotes aligned
   • If you only merged upstream RC changes, push origin only to sync your fork:

     git push origin <branch>
     

   • If you have local fixes to publish, push origin + upstream:

     git push origin <branch>
     git push upstream <branch>:<TARGET_RC>
     

   • Always ask the user which push to perform.
   • Origin (origin-only sync):

     git push origin <branch>
     

   • Upstream RC (publish the same fixes when you have local commits):

     git push upstream <branch>:<TARGET_RC>
     

7. Re-check sync

   ./check-sync.sh
   

PR Workflow (Feature Work)

Use this flow only for new feature work on a new branch. Do not push to upstream RC.

1. Create or switch to a feature branch

   git checkout -b <branch>
   

2. Make changes and commit

   git add -A
   git commit -m "type: description"
   

3. Merge upstream RC before shipping

   git merge upstream/<TARGET_RC> --no-edit
   

4. Build and/or test

   npm run build:packages
   npm run build
   

5. Push to origin

   git push -u origin <branch>
   

6. Create or update the PR
   • Use gh pr create or the GitHub UI.
7. Review and follow-up

• Apply feedback, commit changes, and push again.
• Re-run ./check-sync.sh if additional upstream sync is needed.

Conflict Resolution Checklist

1. Identify which changes are from upstream vs. local.
2. Preserve both behaviors where possible; avoid dropping either side.
3. Prefer minimal, safe integrations over refactors.
4. Re-run build commands after resolving conflicts.
5. Re-run ./check-sync.sh to confirm status.

Build/Test Matrix

• Sync Workflow: npm run build:packages and npm run build.
• PR Workflow: npm run build:packages and npm run build (plus relevant tests).

Post-Sync Verification

1. git status should be clean.
2. ./check-sync.sh should show expected alignment.
3. Verify recent commits with:

   git log --oneline -5
   

check-sync.sh Usage

• Uses dynamic Target RC resolution (see above).
• Override target RC:

  ./check-sync.sh --rc <rc-branch>
  

• Optional preview limit:

  ./check-sync.sh --preview 10
  

• The script prints sync status for both origin and upstream and previews recent commits when you are behind.

Stop Conditions

Stop and ask for guidance if any of the following are true:

• The working tree is dirty and you are about to merge or push.
• ./check-sync.sh reports diverged during PR Workflow, or a merge cannot be completed.
• The script cannot resolve a target RC and requests --rc.
• A build fails after sync or conflict resolution.

AI Agent Guardrails

• Always run ./check-sync.sh before merges or pushes.
• Always ask for explicit user approval before any push command.
• Do not ask for additional confirmation before a Sync Workflow fetch + merge when the working tree is clean and the user has already selected the Sync Workflow.
• Choose Sync vs PR workflow based on intent (RC maintenance vs new feature work), not on the script's workflow hint.
• Only use force push when the user explicitly requests a history rewrite.
• Ask for explicit approval before dependency installs, branch deletion, or destructive operations.
• When resolving merge conflicts, preserve both upstream changes and local intent where possible.
• Do not create or switch to new branches unless the user explicitly requests it.

AI Agent Decision Guidance

Agents should provide concrete, task-specific suggestions instead of repeatedly asking open-ended questions. Use the user's stated goal and the ./check-sync.sh status to propose a default path plus one or two alternatives, and only ask for confirmation when an action requires explicit approval.

Default behavior:

• If the intent is RC maintenance, recommend the Sync Workflow and proceed with safe preparation steps (status checks, previews). If the branch is behind upstream RC, fetch and merge without additional confirmation when the working tree is clean, then push to origin to keep the fork aligned. Push upstream only when there are local fixes to publish.
• If the intent is new feature work, recommend the PR Workflow and proceed with safe preparation steps (status checks, identifying scope). Ask for approval before merges, pushes, or dependency installs.
• If ./check-sync.sh reports diverged during Sync Workflow, merge upstream/<TARGET_RC> into the current branch and preserve local commits.
• If ./check-sync.sh reports diverged during PR Workflow, stop and ask for guidance with a short explanation of the divergence and the minimal options to resolve it. If the user's intent is RC maintenance, prefer the Sync Workflow regardless of the script hint. When the intent is new feature work, use the PR Workflow and avoid upstream RC pushes.

Suggestion format (keep it short):

• Recommended: one sentence with the default path and why it fits the task.
• Alternatives: one or two options with the tradeoff or prerequisite.
• Approval points: mention any upcoming actions that need explicit approval (exclude sync workflow pushes and merges).

Failure Modes and How to Avoid Them

Sync Workflow:

• Wrong RC target: verify the auto-detected RC in ./check-sync.sh output before merging.
• Diverged from upstream RC: stop and resolve manually before any merge or push.
• Dirty working tree: commit or stash before syncing to avoid accidental merges.
• Missing remotes: ensure both origin and upstream are configured before syncing.
• Build breaks after sync: run npm run build:packages and npm run build before pushing.

PR Workflow:

• Branch not synced to current RC: re-run ./check-sync.sh and merge RC before shipping.
• Pushing the wrong branch: confirm git branch --show-current before pushing.
• Unreviewed changes: always commit and push to origin before opening or updating a PR.
• Skipped tests/builds: run the build commands before declaring the PR ready.

Notes

• Avoid merging with uncommitted changes; commit or stash first.
• Prefer merge over rebase for PR branches; rebases rewrite history and often require a force push, which should only be done with an explicit user request.
• Use clear, conventional commit messages and split unrelated changes into separate commits.