feat(workflows:work): add incremental commits and branch safety (#93)
- Add branch detection at start of Setup Environment step - Support continuing on existing feature branch or creating new - Require explicit confirmation to commit to default branch - Add incremental commit guidance with decision criteria table - Include heuristic: "Can I write a meaningful commit message?" - Generalize test commands to be framework-agnostic
This commit is contained in:
Trevin Chow
@@ -30,31 +30,48 @@ This command takes a work document (plan, specification, or todo file) and execu
|
||||
|
||||
2. **Setup Environment**
|
||||
|
||||
Choose your work style:
|
||||
First, check the current branch:
|
||||
|
||||
**Option A: Live work on current branch**
|
||||
```bash
|
||||
git checkout main && git pull origin main
|
||||
current_branch=$(git branch --show-current)
|
||||
default_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
|
||||
|
||||
# Fallback if remote HEAD isn't set
|
||||
if [ -z "$default_branch" ]; then
|
||||
default_branch=$(git rev-parse --verify origin/main >/dev/null 2>&1 && echo "main" || echo "master")
|
||||
fi
|
||||
```
|
||||
|
||||
**If already on a feature branch** (not the default branch):
|
||||
- Ask: "Continue working on `[current_branch]`, or create a new branch?"
|
||||
- If continuing, proceed to step 3
|
||||
- If creating new, follow Option A or B below
|
||||
|
||||
**If on the default branch**, choose how to proceed:
|
||||
|
||||
**Option A: Create a new branch**
|
||||
```bash
|
||||
git pull origin [default_branch]
|
||||
git checkout -b feature-branch-name
|
||||
```
|
||||
Use a meaningful name based on the work (e.g., `feat/user-authentication`, `fix/email-validation`).
|
||||
|
||||
**Option B: Parallel work with worktree (recommended for parallel development)**
|
||||
**Option B: Use a worktree (recommended for parallel development)**
|
||||
```bash
|
||||
# Ask user first: "Work in parallel with worktree or on current branch?"
|
||||
# If worktree:
|
||||
skill: git-worktree
|
||||
# The skill will create a new branch from main in an isolated worktree
|
||||
# The skill will create a new branch from the default branch in an isolated worktree
|
||||
```
|
||||
|
||||
**Option C: Continue on the default branch**
|
||||
- Requires explicit user confirmation
|
||||
- Only proceed after user explicitly says "yes, commit to [default_branch]"
|
||||
- Never commit directly to the default branch without explicit permission
|
||||
|
||||
**Recommendation**: Use worktree if:
|
||||
- You want to work on multiple features simultaneously
|
||||
- You want to keep main clean while experimenting
|
||||
- You want to keep the default branch clean while experimenting
|
||||
- You plan to switch between branches frequently
|
||||
|
||||
Use live branch if:
|
||||
- You're working on a single feature
|
||||
- You prefer staying in the main repository
|
||||
|
||||
3. **Create Todo List**
|
||||
- Use TodoWrite to break plan into actionable tasks
|
||||
- Include dependencies between tasks
|
||||
@@ -78,11 +95,41 @@ This command takes a work document (plan, specification, or todo file) and execu
|
||||
- Run tests after changes
|
||||
- Mark task as completed in TodoWrite
|
||||
- Mark off the corresponding checkbox in the plan file ([ ] → [x])
|
||||
- Evaluate for incremental commit (see below)
|
||||
```
|
||||
|
||||
**IMPORTANT**: Always update the original plan document by checking off completed items. Use the Edit tool to change `- [ ]` to `- [x]` for each task you finish. This keeps the plan as a living document showing progress and ensures no checkboxes are left unchecked.
|
||||
|
||||
2. **Follow Existing Patterns**
|
||||
2. **Incremental Commits**
|
||||
|
||||
After completing each task, evaluate whether to create an incremental commit:
|
||||
|
||||
| Commit when... | Don't commit when... |
|
||||
|----------------|---------------------|
|
||||
| Logical unit complete (model, service, component) | Small part of a larger unit |
|
||||
| Tests pass + meaningful progress | Tests failing |
|
||||
| About to switch contexts (backend → frontend) | Purely scaffolding with no behavior |
|
||||
| About to attempt risky/uncertain changes | Would need a "WIP" commit message |
|
||||
|
||||
**Heuristic:** "Can I write a commit message that describes a complete, valuable change? If yes, commit. If the message would be 'WIP' or 'partial X', wait."
|
||||
|
||||
**Commit workflow:**
|
||||
```bash
|
||||
# 1. Verify tests pass (use project's test command)
|
||||
# Examples: bin/rails test, npm test, pytest, go test, etc.
|
||||
|
||||
# 2. Stage only files related to this logical unit (not `git add .`)
|
||||
git add <files related to this logical unit>
|
||||
|
||||
# 3. Commit with conventional message
|
||||
git commit -m "feat(scope): description of this unit"
|
||||
```
|
||||
|
||||
**Handling merge conflicts:** If conflicts arise during rebasing or merging, resolve them immediately. Incremental commits make conflict resolution easier since each commit is small and focused.
|
||||
|
||||
**Note:** Incremental commits use clean conventional messages without attribution footers. The final Phase 4 commit/PR includes the full attribution.
|
||||
|
||||
3. **Follow Existing Patterns**
|
||||
|
||||
- The plan should reference similar code - read those files first
|
||||
- Match naming conventions exactly
|
||||
@@ -90,14 +137,14 @@ This command takes a work document (plan, specification, or todo file) and execu
|
||||
- Follow project coding standards (see CLAUDE.md)
|
||||
- When in doubt, grep for similar implementations
|
||||
|
||||
3. **Test Continuously**
|
||||
4. **Test Continuously**
|
||||
|
||||
- Run relevant tests after each significant change
|
||||
- Don't wait until the end to test
|
||||
- Fix failures immediately
|
||||
- Add new tests for new functionality
|
||||
|
||||
4. **Figma Design Sync** (if applicable)
|
||||
5. **Figma Design Sync** (if applicable)
|
||||
|
||||
For UI work with Figma designs:
|
||||
|
||||
@@ -106,7 +153,7 @@ This command takes a work document (plan, specification, or todo file) and execu
|
||||
- Fix visual differences identified
|
||||
- Repeat until implementation matches design
|
||||
|
||||
5. **Track Progress**
|
||||
6. **Track Progress**
|
||||
- Keep TodoWrite updated as you complete tasks
|
||||
- Note any blockers or unexpected discoveries
|
||||
- Create new tasks if scope expands
|
||||
@@ -119,8 +166,8 @@ This command takes a work document (plan, specification, or todo file) and execu
|
||||
Always run before submitting:
|
||||
|
||||
```bash
|
||||
# Run full test suite
|
||||
bin/rails test
|
||||
# Run full test suite (use project's test command)
|
||||
# Examples: bin/rails test, npm test, pytest, go test, etc.
|
||||
|
||||
# Run linting (per CLAUDE.md)
|
||||
# Use linting-agent before pushing to origin
|
||||
@@ -284,7 +331,7 @@ Before creating PR, verify:
|
||||
|
||||
- [ ] All clarifying questions asked and answered
|
||||
- [ ] All TodoWrite tasks marked completed
|
||||
- [ ] Tests pass (run `bin/rails test`)
|
||||
- [ ] Tests pass (run project's test command)
|
||||
- [ ] Linting passes (use linting-agent)
|
||||
- [ ] Code follows existing patterns
|
||||
- [ ] Figma designs match implementation (if applicable)
|
||||
|
||||
Reference in New Issue
Block a user