General Workflow

Git branching

• ALWAYS branch: git checkout -b feature/description or fix/description
• Use a descriptive title, not a code or vague slug. The branch name must read as a short phrase describing the actual intent/scope: feature/headless-storefront-specs, not feature/work, feature/wip, or an opaque auto-generated slug. Prefix with the type (feature/ fix/ docs/ refactor/ chore/), then a kebab-case description.
• Keep the name in sync with the work. When the intent or scope changes materially mid-branch, rename it: git branch -m <new-name>. If already pushed, update the remote (git push origin -u <new-name> then git push origin --delete <old-name>) and retitle any open PR to match. A stale branch name that no longer describes the work is a bug — fix it.
• NEVER commit directly to main
• Wait for user review before merging

Commit strategy

• Commits need a trigger first: either the user explicitly asks, or the user granted standing commit permission for the session. With neither, do NOT commit — leave the work uncommitted and say so at each checkpoint. (This trigger gates everything below.)
• Once triggered, one completed todo = one commit (multi-file is fine); never batch multiple todos into one commit, and commit only when that todo is actually done.
• At the start of multi-step work, proactively confirm the commit policy so the trigger is settled up front.

GitHub

• Default owner: Uplift-Duo-Co
• New repos: gh repo create Uplift-Duo-Co/<name> --private
• gh must be GitHub CLI (gh --version → gh version 2.x). The npm package gh (node-gh) shadows it on some machines; uninstall it (npm uninstall -g gh, or delete the orphaned shim under nvm) instead of working around it with an absolute path.

Merging

• Merge only on the user's explicit instruction ("merge it", "push this into main") — that instruction is the review. Until it comes the PR stays open; never merge on your own judgment, and never route around a blocked merge.
• Land PRs with a merge commit, never a squash — the per-todo commits and their quoted prompts are the history: gh pr merge <n> --merge --subject "🥳 Merge <what> (#<n>)". The PR body already carries every prompt in full.
• gh is the merge tool. Prefer the GitHub CLI over a GitHub MCP connector: it is already authenticated and scriptable, and a connector passes through the same permission layer, so it makes nothing smoother — it only adds an OAuth grant to keep alive.
• Make an approved merge deterministic. If the agent's permission layer still blocks gh pr merge after the user said merge, that is a config gap, not a judgment call: have the user allow-list git push, gh pr create and gh pr merge in the agent's permission settings. The rule above still decides when; the allow-list only removes the second-guessing.
• One worktree per session. Parallel sessions on one repo never switch branches under each other: git worktree add ../<repo>-<branch> -b <branch> origin/main. After the merge, fast-forward the main checkout, remove the worktree and delete the local branch.

Commit message format

[EMOJI] Brief summary (50 chars max)

👤 Human prompt: [The portion of the user's request this todo implements — verbatim excerpt]

🤖 === COMMIT SUMMARY ===
Foundation Model: [Actual model name — do not invent]
Estimated Token Cost: ~[X]K input tokens, ~[Y]K output tokens
Time Taken: ~[Z] minutes

=== [SECTION NAME] ===

[What changed and why]

TECHNICAL CHANGES:
- file/path: specific change

Emoji (subject line)

Use 🤖 before === COMMIT SUMMARY ===. Use 👤 before Human prompt: in the body.

Each todo commit quotes only the relevant portion of the human prompt. Copy, word-for-word, the part of the user's request that this todo and its code changes implement — an exact excerpt, never a paraphrase or summary. Truncate away the parts of the prompt that belong to other todos; if the whole prompt is about this todo, quote it whole.

The pull request description carries every prompt in full. The PR body must include ALL human prompts from the branch, complete with every word — full text, exactly as written, never truncated with "..."/"…", summarized, paraphrased, or missing lines. Multi-paragraph prompts go in whole. The per-todo excerpts in commits never substitute for this.

Example (bug fix)

😖 Fix dashboard CTA handler

👤 Human prompt: The log your first time button on the dashboard does not work.

🤖 === COMMIT SUMMARY ===
Foundation Model: Composer 2.5 (via Cursor)
Estimated Token Cost: ~3K input tokens, ~2K output tokens
Time Taken: ~10 minutes