diff --git a/plugins/compound-engineering/commands/workflows/work.md b/plugins/compound-engineering/commands/workflows/work.md index 1884645..d404ffc 100644 --- a/plugins/compound-engineering/commands/workflows/work.md +++ b/plugins/compound-engineering/commands/workflows/work.md @@ -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 + + # 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)