catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-12 02:37:45 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: Add unified-execute-parallel, unified-execute-with-file, and worktree-merge workflows

Browse Source 
- Implemented unified-execute-parallel for executing tasks in isolated Git worktrees with parallel execution capabilities.
- Developed unified-execute-with-file for universal task execution from various planning outputs with progress tracking.
- Created worktree-merge to handle merging of completed worktrees back to the main branch, including dependency management and conflict detection.
- Enhanced documentation for each workflow, detailing core functionalities, implementation phases, and configuration options.
This commit is contained in:
catlog22
2026-02-05 18:44:00 +08:00
parent 1480873008
commit eac1bb81c8
17 changed files with 16 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

556
.codex/prompts/worktree-merge.md
View File

@@ -1,556 +0,0 @@
---
description: Merge completed worktrees back to main branch. Handle cross-group conflicts and dependency order.
argument-hint: "[--plan=<plan-session>] [--group=<group-id>] [--all] [--cleanup]"
---
# Codex Worktree-Merge Workflow
## Quick Start
Merge completed execution group worktrees back to main branch.
**Core workflow**: Load Status → Check Dependencies → Merge Groups → Cleanup Worktrees
**Key features**:
- **Dependency-aware merge**: Merge groups in correct order
- **Conflict detection**: Check for cross-group file conflicts
- **Selective or bulk merge**: Merge single group or all completed groups
- **Cleanup option**: Remove worktrees after successful merge
## Overview
1. **Load Status** - Read worktree-status.json and execution-groups.json
2. **Validate Dependencies** - Check group dependencies are merged first
3. **Merge Worktree** - Merge group's branch to main
4. **Update Status** - Mark group as merged
5. **Cleanup** (optional) - Remove worktree after merge
**Note**: This command only merges, execution is handled by `/workflow:unified-execute-parallel`.
## Input Files
```
.workflow/.execution/
└── worktree-status.json # Group completion status
.workflow/.planning/{session}/
├── execution-groups.json # Group metadata and dependencies
└── conflicts.json # Cross-group conflicts (if any)
.ccw/worktree/
├── {group-id}/ # Worktree to merge
│ ├── .execution/ # Execution logs
│ └── (modified files)
```
## Output
```
.workflow/.execution/
├── worktree-status.json # Updated with merge status
└── merge-log.md # Merge history and details
```
---
## Implementation Details
### Command Parameters
- `--plan=<session>`: Plan session ID (auto-detect if not provided)
- `--group=<id>`: Merge specific group (e.g., EG-001)
- `--all`: Merge all completed groups in dependency order
- `--cleanup`: Remove worktree after successful merge
**Examples**:
```bash
# Merge single group
--group=EG-001
# Merge all completed groups
--all
# Merge and cleanup
--group=EG-001 --cleanup
```
---
## Phase 1: Load Status
**Objective**: Read completion status and group metadata.
### Step 1.1: Load worktree-status.json
Read group completion status.
**Status File Location**: `.workflow/.execution/worktree-status.json`
**Required Fields**:
- `plan_session`: Planning session ID
- `groups[]`: Array of group status objects
- `status`: "completed" / "in_progress" / "failed"
- `worktree_path`: Path to worktree
- `branch`: Branch name
- `merge_status`: "not_merged" / "merged"
### Step 1.2: Load execution-groups.json
Read group dependencies.
**Metadata File**: `.workflow/.planning/{session}/execution-groups.json`
**Required Fields**:
- `groups[]`: Group metadata with dependencies
- `group_id`: Group identifier
- `dependencies_on_groups[]`: Groups that must merge first
- `cross_group_files[]`: Files modified by multiple groups
### Step 1.3: Determine Merge Targets
Select groups to merge based on parameters.
**Selection Logic**:
| Parameter | Behavior |
|-----------|----------|
| `--group=EG-001` | Merge only specified group |
| `--all` | Merge all groups with status="completed" |
| Neither | Prompt user to select from completed groups |
**Validation**:
- Group must have status="completed"
- Group's worktree must exist
- Group must not already be merged
---
## Phase 2: Validate Dependencies
**Objective**: Ensure dependencies are merged before target group.
### Step 2.1: Build Dependency Graph
Create merge order based on inter-group dependencies.
**Dependency Analysis**:
1. For target group, check `dependencies_on_groups[]`
2. For each dependency, verify merge status
3. Build topological order for merge sequence
**Example**:
```json
EG-003 depends on [EG-001, EG-002]
→ Merge order: EG-001, EG-002, then EG-003
```
### Step 2.2: Check Dependency Status
Validate all dependencies are merged.
**Check Logic**:
```
For each dependency in target.dependencies_on_groups:
├─ Check dependency.merge_status == "merged"
├─ If not merged: Error or prompt to merge dependency first
└─ If merged: Continue
```
**Options on Dependency Not Met**:
1. **Error**: Refuse to merge until dependencies merged
2. **Cascade**: Automatically merge dependencies first (if --all)
3. **Force**: Allow merge anyway (dangerous, use --force)
---
## Phase 3: Conflict Detection
**Objective**: Check for cross-group file conflicts before merge.
### Step 3.1: Load Cross-Group Files
Read files modified by multiple groups.
**Source**: `execution-groups.json` → `groups[].cross_group_files[]`
**Example**:
```json
{
"group_id": "EG-001",
"cross_group_files": [
{
"file": "src/shared/config.ts",
"conflicting_groups": ["EG-002"]
}
]
}
```
### Step 3.2: Check File Modifications
Compare file state across groups and main.
**Conflict Check**:
1. For each cross-group file:
- Get version on main branch
- Get version in target worktree
- Get version in conflicting group worktrees
2. If all different → conflict likely
3. If same → safe to merge
### Step 3.3: Report Conflicts
Display potential conflicts to user.
**Conflict Report**:
```markdown
## Potential Merge Conflicts
### File: src/shared/config.ts
- Modified by: EG-001 (target), EG-002
- Status: EG-002 already merged to main
- Action: Manual review recommended
### File: package.json
- Modified by: EG-001 (target), EG-003
- Status: EG-003 not yet merged
- Action: Safe to merge (EG-003 will handle conflict)
```
**User Decision**:
- Proceed with merge (handle conflicts manually if occur)
- Abort and review files first
- Coordinate with other group maintainers
---
## Phase 4: Merge Worktree
**Objective**: Merge group's branch from worktree to main.
### Step 4.1: Prepare Main Branch
Ensure main branch is up to date.
```bash
git checkout main
git pull origin main
```
### Step 4.2: Merge Group Branch
Merge from worktree's branch.
**Merge Command**:
```bash
# Strategy 1: Regular merge (creates merge commit)
git merge --no-ff {branch-name} -m "Merge {group-id}: {description}"
# Strategy 2: Squash merge (single commit)
git merge --squash {branch-name}
git commit -m "feat: {group-id} - {description}"
```
**Default**: Use regular merge to preserve history.
### Step 4.3: Handle Merge Conflicts
If conflicts occur, provide resolution guidance.
**Conflict Resolution**:
```bash
# List conflicting files
git status
# For each conflict:
# 1. Open file and resolve markers
# 2. Stage resolved file
git add {file}
# Complete merge
git commit
```
**Conflict Types**:
- **Cross-group file**: Expected, requires manual merge
- **Unexpected conflict**: Investigate cause
### Step 4.4: Push to Remote
Push merged changes.
```bash
git push origin main
```
**Validation**:
- Check CI/tests pass after merge
- Verify no regressions
---
## Phase 5: Update Status & Cleanup
**Objective**: Mark group as merged, optionally remove worktree.
### Step 5.1: Update worktree-status.json
Mark group as merged.
**Status Update**:
```json
{
"groups": {
"EG-001": {
"merge_status": "merged",
"merged_at": "2025-02-03T15:00:00Z",
"merged_to": "main",
"merge_commit": "abc123def456"
}
}
}
```
### Step 5.2: Append to merge-log.md
Record merge details.
**Merge Log Entry**:
```markdown
## EG-001: Frontend Development
- **Merged At**: 2025-02-03 15:00:00
- **Branch**: feature/cplan-auth-eg-001-frontend
- **Commit**: abc123def456
- **Tasks Completed**: 15/15
- **Conflicts**: 1 file (src/shared/config.ts) - resolved
- **Status**: Successfully merged to main
```
### Step 5.3: Cleanup Worktree (optional)
Remove worktree if --cleanup flag provided.
**Cleanup Commands**:
```bash
# Remove worktree
git worktree remove .ccw/worktree/{group-id}
# Delete branch (optional)
git branch -d {branch-name}
git push origin --delete {branch-name}
```
**When to Cleanup**:
- Group successfully merged
- No need to revisit worktree
- Disk space needed
**When to Keep**:
- May need to reference execution logs
- Other groups may need to coordinate
- Debugging merge issues
### Step 5.4: Display Summary
Report merge results.
**Summary Output**:
```
✓ Merged EG-001 to main
- Branch: feature/cplan-auth-eg-001-frontend
- Commit: abc123def456
- Tasks: 15/15 completed
- Conflicts: 1 resolved
- Worktree: Cleaned up
Remaining groups:
- EG-002: completed, ready to merge
- EG-003: in progress, waiting for dependencies
```
---
## Configuration
| Parameter | Default | Description |
|-----------|---------|-------------|
| `--plan` | Auto-detect | Plan session ID |
| `--group` | Interactive | Group to merge |
| `--all` | false | Merge all completed groups |
| `--cleanup` | false | Remove worktree after merge |
| `--force` | false | Ignore dependency checks |
| `--squash` | false | Use squash merge instead of regular |
---
## Error Handling
| Situation | Action |
|-----------|--------|
| Group not completed | Error: Complete execution first |
| Group already merged | Skip with warning |
| Dependencies not merged | Error or cascade merge (--all) |
| Merge conflict | Pause for manual resolution |
| Worktree not found | Error: Check worktree path |
| Push fails | Rollback merge, report error |
---
## Merge Strategies
### Strategy 1: Sequential Merge
Merge groups one by one in dependency order.
```bash
# Merge EG-001
--group=EG-001 --cleanup
# Merge EG-002
--group=EG-002 --cleanup
# Merge EG-003 (depends on EG-001, EG-002)
--group=EG-003 --cleanup
```
**Use When**:
- Want to review each merge carefully
- High risk of conflicts
- Testing between merges
### Strategy 2: Bulk Merge
Merge all completed groups at once.
```bash
--all --cleanup
```
**Use When**:
- Groups are independent
- Low conflict risk
- Want fast integration
### Strategy 3: Dependency-First
Merge dependencies before dependent groups.
```bash
# Automatically merges EG-001, EG-002 before EG-003
--group=EG-003 --cascade
```
**Use When**:
- Complex dependency graph
- Want automatic ordering
---
## Best Practices
### Before Merge
1. **Verify Completion**: Check all tasks in group completed
2. **Review Conflicts**: Read conflicts.json for cross-group files
3. **Test Worktree**: Run tests in worktree before merge
4. **Update Main**: Ensure main branch is current
### During Merge
1. **Follow Order**: Respect dependency order
2. **Review Conflicts**: Carefully resolve cross-group conflicts
3. **Test After Merge**: Run CI/tests after each merge
4. **Commit Often**: Keep merge history clean
### After Merge
1. **Update Status**: Ensure worktree-status.json reflects merge
2. **Keep Logs**: Archive merge-log.md for reference
3. **Cleanup Gradually**: Don't rush to delete worktrees
4. **Notify Team**: Inform others of merged groups
---
## Rollback Strategy
If merge causes issues:
```bash
# Find merge commit
git log --oneline
# Revert merge
git revert -m 1 {merge-commit}
git push origin main
# Or reset (dangerous, loses history)
git reset --hard HEAD~1
git push origin main --force
# Update status
# Mark group as not_merged in worktree-status.json
```
---
## Example Workflow
### Scenario: 3 Groups Complete
**Status**:
- EG-001: Completed (no dependencies)
- EG-002: Completed (no dependencies)
- EG-003: Completed (depends on EG-001, EG-002)
### Step 1: Merge Independent Groups
```bash
# Merge EG-001
--group=EG-001
# Test after merge
npm test
# Merge EG-002
--group=EG-002
# Test after merge
npm test
```
### Step 2: Merge Dependent Group
```bash
# EG-003 depends on EG-001, EG-002 (already merged)
--group=EG-003
# Final test
npm test
```
### Step 3: Cleanup All Worktrees
```bash
# Remove all merged worktrees
--cleanup-all
```
---
## When to Use This Workflow
### Use worktree-merge when:
- Execution groups completed via unified-execute-parallel
- Ready to integrate changes to main branch
- Need dependency-aware merge order
- Want to handle cross-group conflicts systematically
### Manual merge when:
- Single group with no dependencies
- Comfortable with Git merge commands
- No cross-group conflicts to handle
---
**Now execute worktree-merge for completed execution groups**