@brunosps00/dev-workflow 0.8.1 → 0.10.0

package/scaffold/skills/dw-execute-phase/references/plan-verification.md

@@ -0,0 +1,156 @@
+# Plan verification — the 6-dimension goal-backward analysis
+
+The `dw-plan-checker` agent verifies that a `tasks.md` will achieve the PRD goal BEFORE execution starts. This document details each dimension's checks, examples, and pass/fail criteria.
+
+## Why pre-execution verification
+
+Mid-execution discovery of plan flaws is expensive: context burned, partial commits to revert, deviation logs to resolve. Pre-execution verification catches the same flaws at zero implementation cost. The trade-off: 1-2 minutes of plan-checker time vs. potentially 30+ minutes of mid-execution rework.
+
+## The 6 dimensions
+
+### 1. Requirement Coverage
+
+**Goal:** every PRD requirement (RF-XX) has at least one task addressing it.
+
+**Steps:**
+1. Extract numbered requirements from `prd.md`. Pattern: `### RF-NN` or `**RF-NN:**` or numbered list under "Functional Requirements".
+2. Build `Set<RF>` of expected requirements.
+3. Scan `tasks.md` and `<NN>_task.md` files for `Closes RF-XX` / `RF: RF-XX` / `Requirement: RF-XX` markers.
+4. Compute `uncovered = expected - addressed`.
+
+**Pass:** `uncovered` is empty.
+**Revise:** uncovered non-empty AND fixable by adding tasks.
+**Block:** PRD has no numbered requirements (`expected` is empty) — verifying intent is impossible.
+
+**Common failures:**
+- Planner forgot a non-obvious requirement (e.g., audit logging) buried in PRD prose
+- Compound requirement ("user can sign up AND verify email") only addressed for one half
+- Requirement covered indirectly but no task explicitly marks the closure
+
+### 2. Task Completeness
+
+**Goal:** each task has all four parts: files, action, verification, done criteria.
+
+**Steps:**
+For each task in `tasks.md`:
+- Open `<NN>_task.md` (or inline section)
+- Check for required sections:
+  - `## Files` (or `Files to create/modify:`) — explicit paths
+  - `## Action` (or `Implement:`) — what to do, concrete
+  - `## Verification` (or `Verify:`) — how to know it worked (linter, tests, build, manual)
+  - `## Done` (or `Done when:`) — criteria for marking `[x]`
+
+**Pass:** all four sections present in every task.
+**Revise:** ≥1 task missing one section.
+
+**Common failures:**
+- "Files: TBD" or "Files: see techspec" — too vague
+- No verification → executor can't decide when to commit
+- Done criteria absent → executor commits but can't mark `[x]` confidently
+
+### 3. Dependency Soundness
+
+**Goal:** `Depends on:` graph is acyclic, references valid, waves are reasonable.
+
+**Steps:**
+1. Parse every task's `Depends on:` field (none / comma-separated task numbers).
+2. Build directed graph (node = task, edge = depends-on relation).
+3. Topological sort:
+   - Cycle → BLOCK with the cycle path
+   - Reference to non-existent task number → REVISE with the dangling ref
+4. Compute wave widths. Any wave > 8 tasks → REVISE (split with synthetic barrier).
+
+**Pass:** topological sort succeeds, all refs valid, waves ≤ 8 wide.
+
+**Common failures:**
+- Bidirectional dependency (`02 depends on 03; 03 depends on 02`) — likely planner confusion; needs re-think
+- Typo in `Depends on: 02` when the task is actually numbered `2.5` or `03`
+- 10 independent test files all in wave 1 → split into smaller waves
+
+### 4. Artifact Wiring
+
+**Goal:** every artifact produced by a task is consumed by a downstream task OR is a leaf deliverable referenced in PRD's user stories.
+
+**Steps:**
+1. For each task, identify what it PRODUCES:
+   - New files (from `Files: + src/foo.ts`)
+   - New exports (from `Implement: export function bar()`)
+   - New endpoints (from `Action: add POST /api/baz`)
+2. For each downstream task (later in topo order), identify what it CONSUMES:
+   - Imports (from `Files: src/quux.ts (modify) — imports bar`)
+   - References (from `Action: call /api/baz`)
+3. Cross-reference: every produced artifact should be either consumed downstream OR explicitly mentioned in PRD as a user-facing deliverable.
+
+**Pass:** zero orphan artifacts.
+**Revise:** ≥1 artifact created without consumer or PRD reference — likely incomplete plan.
+
+**Common failures:**
+- Task creates a service but no task wires it into the router
+- Task creates a migration file but no task runs it (`prisma migrate deploy`)
+- Task creates a config but no task reads it
+
+### 5. Context Budget
+
+**Goal:** the phase fits in a practical execution window.
+
+**Steps:**
+1. Count tasks. Practical limit: 12 tasks per phase before quality degrades.
+2. Estimate aggregate file changes: sum of files mentioned in `Files:` across all tasks. Limit: 30 files per phase.
+3. Check parallelism setup: are wave-1 tasks running in parallel? (frontmatter `parallel: true` or default).
+
+**Pass:** ≤12 tasks, ≤30 aggregate files, wave 1 has parallel execution if multi-task.
+
+**Revise:** > 12 tasks → suggest splitting into 2 phases. > 30 files → reduce scope or split.
+
+**Common failures:**
+- Mega-phase with 20 tasks because the planner couldn't decompose
+- Single-task waves where parallelism was forgotten
+
+### 6. Constraint Compliance
+
+**Goal:** tasks honor locked decisions and project conventions.
+
+**Steps:**
+1. Read `.dw/rules/index.md` and `.dw/rules/<module>.md` for relevant modules.
+2. Read `CONTEXT.md` if exists; extract `## Decisions` (LOCKED) section.
+3. Read `./CLAUDE.md` for project hard constraints.
+4. For each task, check if its `Action` or `Files` violate:
+   - A locked decision
+   - A project rule (forbidden pattern, mandated tool)
+   - A CLAUDE.md directive
+
+**Pass:** zero violations.
+**Block:** ≥1 hard violation. The plan must change before execution.
+
+**Common failures:**
+- Locked decision says "framework: Fastify" but task says "use Express"
+- Project rules forbid raw SQL; task uses `pg.query()` directly
+- CLAUDE.md says "no env files committed"; task adds `.env.production`
+
+## Verdict resolution
+
+After running all 6 dimensions:
+
+| Outcome | Verdict |
+|---------|---------|
+| All 6 PASS | PASS — proceed to execution |
+| Any REVISE, no BLOCK | REVISE — re-plan |
+| Any BLOCK | BLOCK — surface to user, no auto-replan |
+
+`PASS` is the only state that allows `/dw-execute-phase` to proceed.
+
+## Bounded revision loop
+
+The plan-checker is part of a bounded quality loop:
+
+1. `/dw-create-tasks` produces v1 of `tasks.md`
+2. `/dw-plan-checker` runs → REVISE
+3. `/dw-create-tasks --revise` produces v2 (consumes plan-checker's issues as input)
+4. `/dw-plan-checker` runs → PASS or REVISE again
+5. After 3 revisions without reaching PASS → escalate to user (something fundamental is wrong)
+
+The escalation cap prevents infinite loops where the planner can't satisfy the verifier. At 3 strikes, the user sees the diff between PRD and the failing tasks.md and decides next step.
+
+## Time budget
+
+Plan-checker target: 1-2 minutes. The 6 dimensions are mostly file reads and grep operations; no heavy analysis. If plan-checker exceeds 5 minutes, it's a sign the agent is over-thinking — bias toward issuing REVISE for ambiguous cases rather than analyzing them deeply.

package/scaffold/skills/dw-execute-phase/references/wave-coordination.md

@@ -0,0 +1,102 @@
+# Wave coordination — how the executor parallelizes tasks
+
+Tasks within a phase have dependencies. Some can run in parallel; others must wait. The executor groups tasks into **waves** and runs each wave as parallel subagent dispatches, with sequential ordering between waves.
+
+## Wave computation
+
+Input: `tasks.md` with each task carrying a `Depends on:` field (none, or comma-separated task numbers).
+
+Algorithm: topological sort.
+
+1. Build dependency graph: node per task, edge from each `Depends on:` to the dependent task.
+2. Cycle check: if a cycle exists → abort with `EXEC-FAILED: dependency cycle`.
+3. Wave assignment:
+   - Wave 1 = tasks with zero dependencies
+   - Wave N = tasks whose all dependencies are in waves 1..N-1
+4. Output: ordered list of waves, each wave a list of task numbers.
+
+## Example
+
+```
+tasks.md:
+- 01 Create user schema       Depends on: none
+- 02 Create user model        Depends on: 01
+- 03 Create order schema      Depends on: none
+- 04 Wire auth middleware     Depends on: 02
+- 05 Add login endpoint       Depends on: 04
+- 06 Add order endpoint       Depends on: 02, 03
+- 07 Wire validation rules    Depends on: 04, 06
+
+Computed waves:
+Wave 1: [01, 03]            (no deps; can run in parallel)
+Wave 2: [02]                (depends on 01)
+Wave 3: [04, 06]            (depend on wave 2)
+Wave 4: [05, 07]            (depend on wave 3)
+```
+
+## Parallel execution within a wave
+
+Within a wave, the executor dispatches tasks in parallel via subagent calls (one subagent per task). Each subagent:
+
+1. Reads its `<NN>_task.md`
+2. Implements
+3. Verifies (lint/tests/build)
+4. Commits atomically (per `atomic-commits.md`)
+5. Marks `[x]` in `tasks.md`
+6. Returns success or deviation status to the orchestrating executor
+
+The orchestrating executor:
+
+- Spawns N subagents in parallel (single message, N tool calls)
+- Waits for all to return
+- If all PASS → proceed to next wave
+- If ANY return deviation/blocked → resolve before next wave (see deviation rules in `agents/executor.md`)
+
+## Wave width limits
+
+Practical caps to keep context budget sane:
+
+- **Soft cap: 5 tasks per wave** — tested as the upper bound where parallel execution stays efficient
+- **Hard cap: 8 tasks per wave** — beyond this, the orchestrator's context fills with subagent results faster than tasks complete
+
+If a wave exceeds the hard cap, the planner should split: introduce a synthetic dependency to bisect the wave. Example: if Wave 3 has 10 independent tasks, force tasks 06-10 to depend on a "wave 3a barrier" so they go to Wave 3.5.
+
+The plan-checker (Dimension 5) flags wide waves before execution.
+
+## Cross-wave atomicity
+
+Each wave is a checkpoint:
+
+- After all tasks in a wave commit, run a `git status` check — should be clean (everything committed).
+- If any task in a wave failed permanently (Rule 3 deviation), abort BEFORE starting the next wave. Leave the partial work committed; surface to user via `EXEC-BLOCKED`.
+- Don't run waves N+1 with broken commits in wave N. The dependencies aren't satisfied.
+
+## Order within a wave
+
+Within a wave, order doesn't matter logically (no deps between same-wave tasks). But for **commit history readability**, the executor should commit in numeric order of task number (01 commit before 02 even if both are wave 1). The parallel subagent results may arrive out of order; the executor collects and commits sequentially.
+
+This means: subagents return their changes (files written, but NOT committed). The executor commits them in numeric order.
+
+(Alternative: subagents commit independently and accept commit interleaving. Pick this if commit-order doesn't matter for the project; the orchestrator sets a flag.)
+
+## When to NOT use waves
+
+Single-task changes (`/dw-quick`, `/dw-run-task`) bypass waves entirely. Waves are for `/dw-run-plan` and `/dw-execute-phase` — phase-scale execution.
+
+## Verification of wave structure (pre-execution)
+
+The plan-checker (Dimension 3 in `plan-checker.md`) verifies:
+- Topological sort succeeds (no cycles)
+- All `Depends on:` references point to existing tasks
+- No wave exceeds the hard cap (8 tasks)
+
+If these fail, plan-checker returns REVISE before any code is touched.
+
+## Resume after checkpoint
+
+If the executor checkpoints mid-phase, `active-session.md` records:
+- `last_completed_task`
+- `last_wave_completed`
+- `remaining_tasks`
+
+`/dw-resume` reads this, recomputes waves from `tasks.md`, skips already-committed tasks, and resumes from the wave containing `last_completed_task + 1`.

package/scaffold/skills/dw-git-discipline/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: dw-git-discipline
+description: Use when committing or opening a PR — applies trunk-based development, atomic commit discipline (one intent per commit, refactor separate from feature), conventional commit messages, and branch hygiene so history is bisectable and reviewable.
+---
+
+# Git Discipline
+
+> **Inspired by** [`addyosmani/agent-skills/git-workflow-and-versioning`](https://github.com/addyosmani/agent-skills/tree/main/git-workflow-and-versioning) (MIT). Trunk-based pattern, atomic commit principles, and branch-hygiene patterns adapted from Addy Osmani's work; specifics rewritten for dev-workflow's commit and PR commands.
+
+History is documentation. Bad commit hygiene corrupts the documentation; good hygiene makes future debugging cheap. This skill encodes the rules.
+
+## Three core principles
+
+### 1. One intent per commit
+
+A commit answers ONE question: "what did I change and why?" If your commit message has the word "and" connecting two unrelated changes — split it.
+
+Common splits:
+- Refactor + feature → two commits (refactor first, feature second).
+- Fix + style cleanup → two commits.
+- Type fix + behavior change → two commits.
+- Multiple bug fixes → one commit per bug.
+
+**Why this matters:** When something breaks 6 weeks later, `git bisect` returns the commit that introduced it. If that commit also did a rename, a refactor, and a feature, you've gained nothing. If it did one thing, you know what to revert.
+
+See `references/atomic-commits-discipline.md` for the discipline in detail.
+
+### 2. Trunk-based, short-lived branches
+
+Long-lived branches diverge from `main` and become merge nightmares. The discipline:
+
+- Branches live 1-3 days, max a week.
+- Daily merge or rebase from `main` to keep close to trunk.
+- Incomplete work behind feature flags, not behind a multi-week branch.
+- Small PRs (under ~400 lines diff). If bigger, ask: can this be split into independently-mergeable pieces?
+
+See `references/trunk-based-pattern.md` for when this bends and when it doesn't.
+
+### 3. Branch + commit message hygiene
+
+- **Branch names:** `feat/<scope>`, `fix/<scope>`, `refactor/<scope>`, `chore/<scope>`. Lowercase, kebab-case, ≤40 chars.
+- **Commit messages:** Conventional Commits (`type(scope): subject`) — `feat`, `fix`, `refactor`, `docs`, `chore`, `test`, `style`, `build`, `ci`, `perf`.
+- **Subject line:** ≤72 chars, imperative mood ("add" not "added"), no trailing period.
+- **Body (when needed):** explain WHY, not WHAT. The diff already shows what.
+- **Footer:** breaking-change marker, issue references, co-author lines.
+
+See `references/branch-hygiene.md` for naming conventions and rebase-vs-merge guidance.
+
+## What this skill enforces
+
+When wired into `/dw-commit`, every commit must:
+
+1. Have a single logical intent (one feature, one fix, one refactor — not mixed).
+2. Pass lint + tests + build BEFORE the commit is created.
+3. Use Conventional Commits format with correct type/scope.
+4. Have a body that explains WHY for non-trivial changes.
+5. NOT skip pre-commit hooks (`--no-verify` is forbidden unless user explicitly authorizes).
+6. NOT amend an already-pushed commit (history rewrites on shared branches break collaborators).
+
+When wired into `/dw-generate-pr`, every PR must:
+
+1. Have an explanatory description with summary + test plan, not just commit-list dump.
+2. Stay reasonably scoped (large PRs flagged with split suggestion).
+3. Have a branch that follows naming conventions.
+4. Reference an issue / PRD / spec when applicable.
+
+## Quick reference: when to do what
+
+| Situation | Action |
+|-----------|--------|
+| Mixed refactor + feature in working dir | Stage refactor → commit → stage feature → commit |
+| Pre-commit hook fails | Investigate. Fix root cause. NEVER `--no-verify` |
+| Want to "tidy up" before PR | `git rebase -i` BEFORE pushing — never after |
+| Already pushed and need to fix message | `git revert` + new commit. Don't force-push to shared. |
+| Branch is 5 days old, tons of conflicts | Rebase from main daily; don't let drift compound |
+| PR has 2,000 lines | Split. Identify natural seams: schema, backend, frontend, tests |
+| Stuck mid-merge with conflicts | Resolve, don't `git checkout --theirs` blindly. The conflict is information |
+
+## What this skill does NOT do
+
+- It does not push, force-push, or create branches without explicit user request.
+- It does not amend commits without explicit user request.
+- It does not collapse multiple commits via `git rebase -i` on already-pushed branches.
+- It does not enforce a specific commit count per PR — only that each commit is atomic.
+
+## Integration with dev-workflow commands
+
+- `/dw-commit` runs this skill — verifies lint/tests/build green, drafts a Conventional Commits message, splits commits if multi-intent detected.
+- `/dw-generate-pr` uses this skill to validate branch naming, PR body structure, and scope.
+- `/dw-run-task` and `/dw-run-plan` follow the atomic-commit discipline when their executor commits work — one task = one commit (or one logical sub-task).
+
+## Anti-patterns this skill prevents
+
+- "WIP" commits getting merged to `main` (pre-PR cleanup expected).
+- "Fix typo" follow-up commits that should have been amended in feature branch.
+- Commits with hooks bypassed (`--no-verify`) — root cause should be fixed instead.
+- Long-lived branches that drift from main.
+- PR descriptions that are just `git log` dumps.
+- Force-pushes to shared branches.
+- Commits that mix unrelated changes.
+
+## When discipline bends
+
+Real-world software can't always be perfect:
+
+- **Hotfix to production:** atomic still applies; hygiene bends only on subject-line conciseness if needed for clarity.
+- **Massive auto-generated change** (lockfile, codemod): one commit is fine; mark `chore(deps)` or `refactor(codemod)` clearly.
+- **Reverts:** use `git revert <sha>` (preserves history) over `git reset --hard` (rewrites history). Both create one commit; only revert is safe on shared branches.
+
+## Verification before committing
+
+- [ ] Lint passes
+- [ ] Tests pass
+- [ ] Build passes
+- [ ] One logical intent
+- [ ] Conventional Commits subject
+- [ ] Body explains WHY (when non-trivial)
+- [ ] No `--no-verify`
+- [ ] No amend of pushed commit
+- [ ] Branch name follows convention

package/scaffold/skills/dw-git-discipline/references/atomic-commits-discipline.md

@@ -0,0 +1,158 @@
+# Atomic commits — one intent per commit
+
+A commit is atomic if it represents exactly one logical change. Atomic commits are the foundation of `git bisect`, `git revert`, code review quality, and reading history six months later.
+
+## The single-intent rule
+
+If your commit message naturally contains "and" connecting two things — that's two commits.
+
+| Bad subject | Better |
+|-------------|--------|
+| `feat: add login form and fix navbar bug` | Two commits: `feat(login): add form`, `fix(nav): correct mobile menu` |
+| `refactor: extract user service and add caching` | Two commits: `refactor(user): extract service`, `feat(user): add result cache` |
+| `chore: update deps and reformat` | Two commits: `chore(deps): bump foo to 2.0`, `style: apply prettier sweep` |
+| `fix: handle null and add tests` | Two commits: `test(payment): cover null amount case`, `fix(payment): handle null amount` (or merge tests + fix when they're the same logical change — see below) |
+
+**Exception:** if you fix a bug AND add the regression test for it, those belong in ONE commit. The test proves the bug and proves the fix; separating them loses the link.
+
+## Refactor vs feature: always separate
+
+The most common atomicity violation: refactoring "while I'm in here" alongside a feature.
+
+Bad:
+```
+feat(orders): add bulk-order export AND extract OrderRepository
+```
+
+Good:
+```
+refactor(orders): extract OrderRepository (no behavior change)
+feat(orders): add bulk-order export endpoint
+```
+
+Why: when bulk-order export turns out to have a bug 2 months later, `git bisect` lands on the second commit. The first commit is a clean prior baseline you can compare against. If they were combined, the refactor's surface area dilutes the diagnosis.
+
+## Practical: how to make commits atomic
+
+When you find yourself with mixed changes in the working directory:
+
+```bash
+# 1. See what's changed
+git status
+git diff
+
+# 2. Stage just the refactor (no behavior change)
+git add -p   # interactive — pick hunks one by one
+# Or stage specific files:
+git add src/orders/repository.ts
+
+# 3. Verify what's staged matches one logical intent
+git diff --cached
+
+# 4. Commit
+git commit -m "refactor(orders): extract OrderRepository (no behavior change)"
+
+# 5. Stage the feature
+git add src/orders/bulk-export.ts src/orders/__tests__/bulk-export.test.ts
+
+# 6. Commit
+git commit -m "feat(orders): add bulk-order export endpoint"
+```
+
+`git add -p` is the workhorse for unmixing changes. Practice it.
+
+## Commit message structure
+
+Conventional Commits format:
+
+```
+type(scope): subject
+
+body — explains WHY, not what (the diff already shows what)
+
+Footer: BREAKING CHANGE, Refs, Co-Authored-By
+```
+
+**Type vocabulary:**
+
+| Type | Use for |
+|------|---------|
+| `feat` | New user-facing capability |
+| `fix` | Bug fix |
+| `refactor` | Code change with NO behavior change |
+| `perf` | Behavior unchanged but faster |
+| `docs` | Docs-only |
+| `test` | Test additions/changes only |
+| `style` | Formatting, no semantic change |
+| `chore` | Build, deps, config, no source change |
+| `ci` | CI pipeline changes only |
+| `build` | Build system changes |
+
+**Subject line rules:**
+- ≤72 chars
+- Imperative ("add" not "added", "fix" not "fixes")
+- No trailing period
+- Lowercase after the colon
+
+**Body rules:**
+- Wrap at 72-100 chars per line
+- Blank line between subject and body
+- WHY > WHAT
+- Reference issues, PRDs, ADRs when relevant
+
+## When to write a body
+
+You don't need a body for trivial changes. You need one when:
+
+- The reason for the change isn't obvious from the diff (e.g., a workaround for a bug in a dependency).
+- The change addresses an issue with non-obvious consequences (e.g., performance, security).
+- The change is a deliberate design choice over alternatives (briefly note the rejected option).
+- The change has a non-obvious blast radius.
+
+A good rule: if a future maintainer would say "huh, why?" reading the diff, write a body.
+
+## What goes in the footer
+
+- `BREAKING CHANGE: <explanation>` — for breaking-change commits.
+- `Refs #123` — issue reference.
+- `Co-Authored-By: Name <email>` — for pair work or AI assistance.
+
+## Bisect-friendly commits
+
+For `git bisect` to work, every commit must:
+- Build
+- Pass tests
+- Be a coherent state (not "WIP, half-implemented")
+
+If you can't bisect through your branch, the commits aren't atomic enough. Squash before merging is acceptable; intra-branch WIP commits get rebased away before push.
+
+## What to do with WIP / "save point" commits
+
+Local WIP is fine. Pushed WIP is not.
+
+Workflow:
+1. Make many small commits as you work (saves your progress).
+2. Before pushing OR before opening PR, `git rebase -i origin/main` to reorganize:
+   - Squash WIP commits into their logical parent.
+   - Drop accidental commits.
+   - Reorder so refactor comes before feature.
+   - Edit messages.
+3. Push the cleaned history.
+
+After pushing, no rewrites unless explicitly authorized — others may have pulled.
+
+## Common atomic-commit mistakes
+
+- **"Tiny extra fix" piggy-backed.** "While I was in there" → separate commit.
+- **Reformat sweep mixed with logic change.** Apply formatter as its own commit BEFORE making logic changes.
+- **Test fixture changes mixed with code changes.** If the fixture change is just to support the new code, fine — keep together. If the fixture was wrong before and you're fixing it, separate commit.
+- **Lockfile churn separate from intent.** Sometimes lockfile updates accompany intentional dep bumps; that's fine. But noisy lockfile changes from running `npm install` for unrelated reasons → revert.
+- **Generated file diffs mixed in.** Generated files (build artifacts, generated types) should regenerate from source automatically; don't commit them by hand alongside source changes if you can avoid it.
+
+## What atomic commits unlock
+
+- `git bisect` finds the exact commit that broke X — and that commit is small enough to inspect quickly.
+- `git revert <sha>` removes ONE feature without unwinding others.
+- Code review focuses: each commit reviewed in isolation makes a tight discussion possible.
+- Cherry-picking to other branches works cleanly when the change is one thing.
+- Commit messages become reliable changelog material.

package/scaffold/skills/dw-git-discipline/references/branch-hygiene.md

@@ -0,0 +1,150 @@
+# Branch hygiene — naming, lifetime, rebase vs merge
+
+Branches are conversations between developers. Names, lifetimes, and integration choices shape that conversation.
+
+## Branch naming conventions
+
+Format: `<type>/<scope>` or `<type>/<scope>-<short-description>`
+
+| Prefix | When |
+|--------|------|
+| `feat/` | New user-facing capability |
+| `fix/` | Bug fix |
+| `refactor/` | No behavior change, internal restructure |
+| `perf/` | Performance improvement |
+| `chore/` | Build, deps, config |
+| `docs/` | Documentation only |
+| `test/` | Test additions or fixes |
+| `experiment/` | Spike / exploration; usually NOT merged |
+| `hotfix/` | Urgent production fix |
+| `release/` | Release preparation (if your team uses release branches) |
+
+Rules:
+- Lowercase, kebab-case.
+- ≤40 characters total.
+- Match the prefix to the dominant change type if mixed.
+- Include a PRD/issue reference when one exists: `feat/prd-user-onboarding`, `fix/issue-1234-login-loop`.
+
+Examples:
+
+| Good | Bad |
+|------|-----|
+| `feat/user-onboarding` | `feature/UserOnboarding` (capitalized) |
+| `fix/login-redirect-loop` | `bug-fix-stuff` (no prefix, vague) |
+| `refactor/extract-user-service` | `mybranch` (meaningless) |
+| `chore/bump-react-19` | `update-deps-and-tests` (multi-intent in name) |
+
+## Branch lifetime
+
+| Branch type | Target lifetime |
+|-------------|-----------------|
+| `feat/` for normal feature | 1-3 days |
+| `fix/` for normal bug | hours to 1 day |
+| `hotfix/` | hours, ship same day |
+| `refactor/` for small refactor | hours to 1 day |
+| `refactor/` for major refactor | break into multiple `refactor/`+ branches, each 1-3 days |
+| `experiment/` | as long as needed, but NOT merged to main without conversion |
+| `release/` | until release ships |
+
+A branch older than a week is a smell. Either:
+- It's blocked on review (fix the review process).
+- It's too big (split it).
+- It should have been a feature flag on `main` (kill the branch, do it on main).
+
+## Daily integration with `main`
+
+While on a branch, integrate from `main` daily:
+
+```bash
+git fetch origin
+git rebase origin/main   # preferred for personal branches
+# OR
+git merge origin/main    # acceptable for shared branches
+```
+
+Why daily:
+- 1 day of drift = trivial conflicts.
+- 7 days of drift = cascading conflicts; same files changed on both sides multiple times.
+- Conflicts caught daily are individually small; conflicts caught at PR time are an avalanche.
+
+## Rebase vs merge
+
+| Situation | Choice |
+|-----------|--------|
+| Personal branch, never shared | Rebase. Linear history. |
+| Shared branch (others have pulled) | Merge. Rebase rewrites history; collaborators' branches diverge. |
+| Pulling latest `main` into your active feature branch | Rebase, IF nobody else has pulled your branch yet. |
+| Merging your feature into `main` via PR | Whatever the team standard is. Squash-merge is fine if commits weren't atomic; preserve commits if they were. |
+
+Rule of thumb: **rebase what's yours; merge what's shared.**
+
+## When NOT to force-push
+
+After a `git rebase`, the branch's history is rewritten — you must force-push to update the remote. This is FINE on a branch only YOU touch. It is BAD on shared branches because:
+
+- Collaborators have pulled the old history; their next pull will conflict in confusing ways.
+- Open PRs against the old SHAs may show garbled diffs.
+- Reviewers lose context if they linked to a specific SHA.
+
+Discipline:
+- `git push --force-with-lease` on personal branches: OK.
+- `git push --force` (without `with-lease`): never — too dangerous.
+- Force-push to `main` / `master` / `production` / shared release branches: only with explicit authorization, ideally never.
+
+## Cleanup: deleting merged branches
+
+After a branch merges:
+
+```bash
+# Delete locally
+git branch -d feat/user-onboarding
+
+# Delete remotely (most platforms auto-delete on PR merge)
+git push origin --delete feat/user-onboarding
+```
+
+A repo with hundreds of stale branches is noise. Most platforms (GitHub, GitLab) auto-delete on merge — enable that setting if you can.
+
+## Stale branch audit
+
+Once a quarter (or whenever the branch list gets noisy):
+
+```bash
+# List branches not merged to main, sorted by date
+git for-each-ref --sort=-committerdate refs/remotes/origin --format='%(committerdate:short) %(refname:short)' | head -50
+```
+
+Anything older than 60 days that hasn't merged: ask the owner — close, finish, or delete.
+
+## Hotfix branches
+
+When prod breaks and you need to ship fast:
+
+1. Branch from `main` (or the production tag, if you have one).
+2. Name: `hotfix/<short-description>` or `hotfix/<incident-id>`.
+3. Make ONE change. Atomic commit. No "while I'm here" piggybacks.
+4. PR to `main` (and to release branch if you have one) — fast review, fast merge, fast deploy.
+5. Verify in production.
+6. Add a regression test on `main` if hotfix didn't include one.
+
+Hotfix discipline matters because the temptation is to bundle other fixes — and hotfix bundles cause the next outage.
+
+## Stacked branches (advanced)
+
+Sometimes you must stack branches: feature B depends on feature A, A is in review.
+
+Options:
+
+1. **Wait for A to merge.** Best, when possible. Start B from updated `main`.
+2. **Stack:** branch B from A. PR B against A. When A merges, rebase B onto `main`, update PR target.
+3. **Feature flag both A and B on `main`.** A merges first behind flag, B merges next behind flag, both flip on together.
+
+Option 3 is the cleanest at scale. Stacking causes review and rebase pain.
+
+## Anti-patterns
+
+- Branch named `bruno-changes` — meaningless.
+- Branch lives 3 weeks "because we're discussing the design" — branch isn't where design happens. Keep designing in docs/PRDs; branch when you're ready to code.
+- `git pull` instead of `git pull --rebase` on a personal feature branch — creates merge commits in your history that you'll then need to clean up.
+- Force-pushing to fix "a typo in the commit message" on a shared branch — use `git revert` + new commit instead.
+- Multiple developers on the same branch without coordinating push order — non-fast-forward errors and conflicts. Pick one driver per branch or coordinate.