feat: Add configurable polecat branch naming (#825)

feat: Add configurable polecat branch naming

Adds polecat_branch_template configuration for custom branch naming patterns.

Template variables supported:
- {user}: git config user.name  
- {year}/{month}: date (YY/MM format)
- {name}: polecat name
- {issue}: issue ID without prefix
- {description}: sanitized issue title
- {timestamp}: unique timestamp

Maintains backward compatibility - empty template uses existing format.
This commit is contained in:
Adam Zionts
2026-01-21 20:53:12 -08:00
committed by GitHub
parent 0dfb0be368
commit 02390251fc
7 changed files with 353 additions and 37 deletions

View File

@@ -23,22 +23,35 @@ just `gt done`.
### The Self-Cleaning Model
Polecats are **self-cleaning**. When you run `gt done`:
1. Your branch is pushed to origin
2. An MR is created in the Refinery merge queue
3. Your sandbox gets nuked
4. Your session exits
5. **You cease to exist**
1. Syncs beads
2. Nukes your sandbox
3. Exits your session
4. **You cease to exist**
The **Refinery** handles all merging to main. It serializes concurrent work, rebases,
and resolves conflicts. You NEVER push directly to main - that's the Refinery's job.
There is no "idle" state. There is no "waiting for more work". Done means GONE.
**Two workflow types:**
**1. Merge Queue Workflow (gastown, beads repos):**
- Push branch to origin
- `gt done` submits to Refinery merge queue
- Refinery handles merge to main
**2. PR Workflow (longeye and similar repos):**
- Create GitHub PR
- Monitor for CI and review feedback
- Address any issues
- `gt done` when PR is approved and CI green
- Maintainer or Refinery merges the PR
**In both cases, you still run `gt done` at the end.** The difference is WHEN:
- Merge queue: After implementation and tests pass
- PR workflow: After PR is approved and CI is green
**Polecats do NOT:**
- Push directly to main (`git push origin main` - WRONG)
- Create pull requests (you're not an external contributor)
- Wait around to see if their work merges
There is no "idle" state. There is no "waiting for more work". Done means GONE.
The Refinery will handle the merge. You will not be there to see it.
- Merge their own PRs (maintainer or Refinery does this)
- Wait around after running `gt done`
**If you have finished your implementation work, your ONLY next action is:**
```bash
@@ -292,6 +305,49 @@ bd ready # See next step
When all steps are done, the molecule gets squashed automatically when you run `gt done`.
## PR Workflow (for repos that use pull requests)
**Applies to:** longeye and other repos that require code review via GitHub PRs
The **mol-polecat-work** molecule now includes PR creation and monitoring steps for
repos that use PR-based workflows. Here's what's different:
### Old Workflow (Merge Queue)
1. Implement → Test → `gt done` → Refinery merges
### New Workflow (PR-based)
1. Implement → Test
2. **Create PR** (with branch naming: adam/YY/M/description)
3. **Monitor PR** - Check CI and review status
4. **Address feedback** - Fix issues if CI fails or reviewers comment
5. **Verify ready** - Confirm CI green and PR approved
6. **`gt done`** - Mark complete and exit (maintainer will merge)
### Key Differences
**You keep the bead OPEN** during PR review. Don't mark complete until:
- ✓ All CI checks passing
- ✓ Review comments addressed
- ✓ PR approved by reviewer
**You may cycle multiple times** while waiting for review or fixing feedback:
```bash
# If context filling while waiting for review
gt handoff -s "Waiting for PR review" -m "Issue: <issue>
PR: #<number>
Status: <current state>
Next: Continue monitoring"
```
Your next session resumes from the current molecule step.
**Branch naming is critical:**
- Format: `adam/YY/M/<short-description>`
- Example: `adam/26/1/fix-social-media-parser`
- This matches the user convention for the repo
**You do NOT merge the PR** - a maintainer or Refinery does that.
## Before Signaling Done (MANDATORY)
> ⚠️ **CRITICAL**: Work is NOT complete until you run `gt done`