From a71a04fb3bbfc4843a6841451a74c4eff816ae04 Mon Sep 17 00:00:00 2001 From: allanbrunoafya Date: Thu, 9 Apr 2026 13:22:09 -0300 Subject: [PATCH 1/6] feat: add territory-based parallel worktree split for independent task groups MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add opt-in parallel execution during plan→implement transition. When the plan contains disconnected task groups (no shared dependencies or files), the user is offered a choice: sequential (default) or parallel worktrees with territory-based file isolation. New skill: parallel-split - Builds territory map per task group (ownedFiles, forbidden, shared) - Creates git worktrees with afyapowers state pre-populated at implement phase - Generates PROMPT.md with territory protocol per worktree - Supports Warp, tmux, and manual terminal launch - Writes territory_map.json for merge orchestration Modified: next command (Step 5A) - Parses plan dependency graph to detect disconnected components - Presents choice only when 2+ independent groups exist - Falls through to normal flow when plan is fully connected Co-Authored-By: Claude Opus 4.6 (1M context) --- dist/claude/commands/next.md | 75 +++- dist/claude/skills/parallel-split/SKILL.md | 383 ++++++++++++++++++ .../parallel-split/territory-protocol.md | 66 +++ dist/cursor/commands/afyapowers-next.md | 75 +++- .../skills/afyapowers-parallel-split/SKILL.md | 383 ++++++++++++++++++ .../territory-protocol.md | 66 +++ dist/gemini/commands/next.md | 75 +++- dist/gemini/skills/parallel-split/SKILL.md | 383 ++++++++++++++++++ .../parallel-split/territory-protocol.md | 66 +++ dist/github-copilot/commands/next.md | 75 +++- .../skills/parallel-split/SKILL.md | 383 ++++++++++++++++++ .../parallel-split/territory-protocol.md | 66 +++ src/commands/next.md | 75 +++- src/skills/parallel-split/SKILL.md | 383 ++++++++++++++++++ src/skills/parallel-split/frontmatter.yaml | 9 + .../parallel-split/territory-protocol.md | 66 +++ 16 files changed, 2619 insertions(+), 10 deletions(-) create mode 100644 dist/claude/skills/parallel-split/SKILL.md create mode 100644 dist/claude/skills/parallel-split/territory-protocol.md create mode 100644 dist/cursor/skills/afyapowers-parallel-split/SKILL.md create mode 100644 dist/cursor/skills/afyapowers-parallel-split/territory-protocol.md create mode 100644 dist/gemini/skills/parallel-split/SKILL.md create mode 100644 dist/gemini/skills/parallel-split/territory-protocol.md create mode 100644 dist/github-copilot/skills/parallel-split/SKILL.md create mode 100644 dist/github-copilot/skills/parallel-split/territory-protocol.md create mode 100644 src/skills/parallel-split/SKILL.md create mode 100644 src/skills/parallel-split/frontmatter.yaml create mode 100644 src/skills/parallel-split/territory-protocol.md diff --git a/dist/claude/commands/next.md b/dist/claude/commands/next.md index 71d595c..c3f7716 100644 --- a/dist/claude/commands/next.md +++ b/dist/claude/commands/next.md @@ -52,15 +52,86 @@ Determine the next phase from the ordered list: design → plan → implement ## Step 5: Invoke Next Phase Skill -Tell the user which phase is starting, then invoke the appropriate skill: +Tell the user which phase is starting, then invoke the appropriate skill. + +**Special case: plan → implement transition** — Before invoking the implementing skill, run the Parallel Split Analysis (Step 5A). | Next Phase | Skill to Invoke | What It Does | |-----------|----------------|--------------| | plan | **writing-plans** skill | Break design into implementation tasks | -| implement | **implementing** skill | Execute tasks with TDD + subagents | +| implement | **(see Step 5A first)** → **implementing** skill | Execute tasks with TDD + subagents | | review | **reviewing** skill | 2-step code review (spec compliance + quality) | | complete | **completing** skill | Merge/PR/cleanup, produce completion summary | +### Step 5A: Parallel Split Analysis (plan → implement ONLY) + +**This step runs ONLY when transitioning from plan to implement.** For all other transitions, skip to Step 5B. + +1. Read the plan from `.afyapowers/features//artifacts/plan.md` +2. Parse all tasks: extract task numbers, `**Depends on:**` lines, and `**Files:**` sections +3. Build the dependency graph +4. Find **disconnected components** — groups of tasks with NO dependencies between them + +**How to find disconnected components:** +- Start with each task as its own group +- If Task A depends on Task B, merge their groups +- If Task A and Task B share files (overlap), merge their groups +- After processing all deps and overlaps, count remaining distinct groups + +5. **If only 1 group exists** (all tasks are connected): skip to Step 5B — no split possible. + +6. **If 2+ disconnected groups exist**, analyze each group: + - List tasks in the group + - Describe the group by its primary domain (infer from file paths and task names) + - List key files/directories the group touches + +7. **Present the choice to the user:** + +``` +Your plan has independent task groups with no dependencies between them: + + Group A (Tasks 1, 2, 5): + Files: + + Group B (Tasks 3, 4): + Files: + + Group C (Tasks 6, 7): + Files: + +How would you like to execute? + + 1) Sequential (default) — one agent implements all tasks using wave execution + 2) Parallel worktrees — creates worktrees with territory-based file isolation, + each runs the full afyapowers workflow (implement → review → complete) +``` + +8. **If user chooses 1 (Sequential):** proceed to Step 5B normally. + +9. **If user chooses 2 (Parallel):** + - Invoke `parallel-split` skill with: + - `feature_slug`: the active feature slug + - `plan_content`: full plan.md content + - `design_content`: full design.md content (read from artifacts) + - `task_groups`: the disconnected groups with task assignments + - `all_tasks`: parsed tasks with deps, files, status + - The parallel-split skill handles worktree creation, territory mapping, and terminal launch + - After the skill completes, tell the user: + "Parallel worktrees created. Each worktree will run implement → review → complete independently. + After all worktrees finish, merge them in order and run `/afyapowers:next` to proceed with the parent feature's review." + - **STOP** — do not invoke the implementing skill (worktree agents handle it) + +### Step 5B: Normal Phase Invocation + +Invoke the skill for the next phase: + +| Next Phase | Skill to Invoke | +|-----------|----------------| +| plan | **writing-plans** | +| implement | **implementing** | +| review | **reviewing** | +| complete | **completing** | + When the skill completes and produces its artifact: 1. Save the artifact to `.afyapowers/features//artifacts/` 2. Update `state.yaml` to add the artifact to the current phase's artifacts list diff --git a/dist/claude/skills/parallel-split/SKILL.md b/dist/claude/skills/parallel-split/SKILL.md new file mode 100644 index 0000000..b5df8d1 --- /dev/null +++ b/dist/claude/skills/parallel-split/SKILL.md @@ -0,0 +1,383 @@ +--- +name: afyapowers:parallel-split +description: "Split independent task groups into parallel worktrees with territory-based file isolation" +--- + +# Parallel Split — Territory-Based Worktree Parallelization + +Split a plan with independent task groups into N parallel git worktrees, each with its own territory (file ownership), plan subset, and afyapowers workflow. This enables multiple agents to implement different parts of a feature simultaneously without merge conflicts. + +**Invoked by:** `implementing` skill (when user chooses parallel execution) +**NOT a standalone command** — only triggered as a choice during the plan → implement transition. + +--- + +## Input + +This skill receives from the caller: + +- `feature_slug`: active feature directory name +- `plan_content`: full plan.md content +- `design_content`: full design.md content +- `task_groups`: array of disconnected task groups (computed by caller) +- `all_tasks`: parsed tasks with deps, files, status + +--- + +## Step 1: Build Territory Map + +For each task group, compute file ownership: + +### 1A. Collect files per group + +For each group, aggregate: +- `willCreate`: all files in `Create:` lines of the group's tasks +- `willModify`: all files in `Modify:` lines of the group's tasks +- `willTest`: all files in `Test:` lines of the group's tasks +- `willImport`: files referenced in task descriptions but not in Files: section + +### 1B. Assign territories + +For each group: + +- **ownedFiles**: `willCreate` + `willModify` + `willTest` that are NOT in any other group +- **ownedDirs**: directories where ALL files belong to this group +- **readOnlyFiles**: files this group imports that are owned by another group +- **forbiddenDirs**: directories owned entirely by other groups +- **sharedFiles**: files that appear in multiple groups, with strategies: + - `package.json`, `requirements.txt`, lock files → `deferred` + - Barrel exports (`index.ts`, `__init__.py`) → `deferred` + - Config files → `single_owner` (assign to group that modifies most) + - Entry points (`App.tsx`, `main.py`) → `single_owner` + +### 1C. Validate territory + +Check that: +1. Every `willCreate`/`willModify` file has exactly one owner (no double-ownership) +2. No file is both `ownedFiles` in one group and `ownedFiles` in another +3. Shared files have assigned strategies + +If validation fails, adjust by: +- Moving conflicting files to `deferred` strategy +- Assigning to the group whose tasks mention it most +- If truly inseparable, merge the two groups and reduce N + +### 1D. Determine merge order + +Analyze cross-group dependencies: +- If group B imports/uses files that group A creates → A merges before B +- If no cross-group dependencies → merge in any order (parallel merge) +- Generate ordered list: `["wt1", "wt3", "wt2"]` + +--- + +## Step 2: Create Git Worktrees + +For each task group: + +```bash +PROJECT_NAME=$(basename "$(pwd)") +FEATURE_SHORT=$(echo "{{feature_slug}}" | sed 's/^[0-9-]*//' | cut -c1-20) +BRANCH_NAME="${PROJECT_NAME}-${FEATURE_SHORT}-wt" +WT_PATH="../${PROJECT_NAME}-${FEATURE_SHORT}-wt" + +git worktree add -b "${BRANCH_NAME}" "${WT_PATH}" HEAD +``` + +--- + +## Step 3: Prepare Each Worktree + +For each worktree, do the following: + +### 3A. Create afyapowers feature state + +Create the feature directory structure in the worktree: + +```bash +WT="" +SLUG="-wt" + +mkdir -p "${WT}/.afyapowers/features/${SLUG}/artifacts" +echo "${SLUG}" > "${WT}/.afyapowers/features/active" +``` + +Write `state.yaml`: + +```yaml +feature: " (Group : )" +status: active +created_at: "" +current_phase: implement +phases: + design: + status: completed + started_at: "" + completed_at: "" + artifacts: [design.md] + plan: + status: completed + started_at: "" + completed_at: "" + artifacts: [plan.md] + implement: + status: in_progress + started_at: "" + completed_at: null + artifacts: [] + review: + status: pending + artifacts: [] + complete: + status: pending + artifacts: [] +``` + +Write `history.yaml` with initial events: + +```yaml +- event: feature_created + timestamp: "" + details: "Split from parent feature '' — Group " +- event: phase_started + timestamp: "" + phase: implement + details: "Parallel split — tasks: " +``` + +### 3B. Copy design.md + +Copy the parent feature's `design.md` to the worktree: + +```bash +cp ".afyapowers/features//artifacts/design.md" \ + "${WT}/.afyapowers/features/${SLUG}/artifacts/design.md" +``` + +### 3C. Generate subset plan.md + +Create a `plan.md` containing ONLY this group's tasks: + +1. Copy the plan header (Goal, Architecture, Tech Stack) +2. Include ONLY the `### Task N:` blocks assigned to this group +3. Renumber tasks sequentially (Task 1, Task 2, ...) for clarity +4. Update `**Depends on:**` references to use new task numbers +5. Preserve all step details, file lists, and Figma metadata + +Save to `${WT}/.afyapowers/features/${SLUG}/artifacts/plan.md` + +### 3D. Generate PROMPT.md with territory rules + +Read `skills/parallel-split/territory-protocol.md` as template. + +Replace placeholders: +- `{{WORKTREE_ID}}` → `wt` +- `{{OWNED_FILES}}` → list of ownedFiles + ownedDirs for this group +- `{{READ_ONLY_FILES}}` → list of readOnlyFiles +- `{{FORBIDDEN_DIRS}}` → list of forbiddenDirs +- `{{SHARED_FILES}}` → list with strategies +- `{{MERGE_ORDER}}` → merge order description + +Write to `${WT}/PROMPT.md`: + +```markdown +# Parallel Worktree wt — + +## Context + +You are implementing a subset of the feature "" in a parallel worktree. +This worktree handles tasks: +Focus area: + +## Active Feature + +Your afyapowers feature is ready at: +`.afyapowers/features//` + +The design and plan artifacts are pre-populated. You are starting at the **implement** phase. + +## Instructions + +1. Read PROMPT.md (this file) completely +2. Run the implement phase: the plan at `.afyapowers/features//artifacts/plan.md` has your tasks +3. Follow TDD and subagent-driven-development as usual +4. **Respect territory rules below** — do NOT edit files outside your territory +5. After implement: run `/afyapowers:next` to proceed to review +6. After review: run `/afyapowers:next` to proceed to complete +7. At complete phase: choose **"Keep as-is"** — do NOT merge or create PR +8. After completion, create `WORKTREE_COMPLETE.md` to signal you are done + + +``` + +### 3E. Provision MCP servers (Claude Code only) + +```bash +cd "${WT_ABS_PATH}" +claude mcp remove serena -s project 2>/dev/null +claude mcp remove sequential-thinking -s project 2>/dev/null +claude mcp add -s project serena -- uvx --from 'git+https://github.com/oraios/serena' serena start-mcp-server --context ide-assistant --project "${WT_ABS_PATH}" +claude mcp add -s project sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking +``` + +Copy settings if they exist: + +```bash +[ -f ".claude/settings.local.json" ] && mkdir -p "${WT}/.claude" && cp ".claude/settings.local.json" "${WT}/.claude/" +``` + +--- + +## Step 4: Write territory_map.json + +Write `territory_map.json` in the parent project root: + +```json +{ + "generated": "", + "source": "afyapowers-parallel-split", + "parentFeature": "", + "worktrees": [ + { + "id": "wt1", + "path": "", + "branch": "", + "featureSlug": "-wt1", + "tasks": [1, 2, 5], + "taskNames": ["Task 1: ...", "Task 2: ...", "Task 5: ..."], + "ownedFiles": [], + "ownedDirs": [], + "readOnlyFiles": [], + "forbiddenDirs": [], + "sharedFiles": [] + } + ], + "mergeOrder": ["wt1", "wt3", "wt2"], + "sharedFiles": [] +} +``` + +--- + +## Step 5: Update Parent Feature State + +In the parent project's `.afyapowers/features//`: + +1. Update `state.yaml`: set implement phase to `in_progress`, add note about parallel split +2. Append to `history.yaml`: + +```yaml +- event: parallel_split + timestamp: "" + details: "Split into parallel worktrees: " + territory_map: "territory_map.json" +``` + +--- + +## Step 6: Launch Terminals + +Detect available terminal multiplexer and launch: + +### 6A. Warp (default on macOS) + +Generate Warp Launch Configuration: + +```yaml +--- +name: afyapowers Parallel +windows: + - tabs: + - title: "afyapowers - Worktrees" + layout: + split_direction: vertical + panes: + - split_direction: horizontal + panes: + - cwd: "" + commands: + - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" + - cwd: "" + commands: + - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" +``` + +Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` + +Open: `open "warp://launch/afyapowers%20Parallel"` + +### 6B. tmux (fallback) + +```bash +SESSION="afyapowers-parallel" +tmux new-session -d -s "${SESSION}" -x 200 -y 50 +tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md...'" Enter +# Split + send-keys for each additional worktree +tmux select-layout -t "${SESSION}" tiled +tmux attach -t "${SESSION}" +``` + +### 6C. Manual (no multiplexer) + +Print commands for user to copy-paste: + +``` +Parallel split complete! Open one terminal per worktree: + + cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' + cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' +``` + +--- + +## Step 7: Display Summary + +``` +Parallel Split Complete + +Feature: +Worktrees: +Territory map: territory_map.json + + wt1 (Tasks ): + Owns: + Branch: + + wt2 (Tasks ): + Owns: + Branch: + +Merge order: wt1 → wt2 → wt3 +Shared files: (all deferred) + +Agents launched in . + +After all worktrees complete: + 1. Merge in order: git merge for each worktree + 2. Consolidate _deferred/ files + 3. Run full test suite + 4. Continue with /afyapowers:next in parent feature (review phase) +``` + +--- + +## CLEANUP + +After all worktrees complete and are merged: + +```bash +# Remove worktrees +git worktree list | grep "afyapowers.*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} + +# Clean up branches +git branch | grep "afyapowers.*wt" | xargs git branch -d + +# Remove territory map +rm territory_map.json + +# Clean up deferred files +rm -rf _deferred/ + +# Remove launch config +rm ~/.warp/launch_configurations/afyapowers-parallel.yaml 2>/dev/null +``` diff --git a/dist/claude/skills/parallel-split/territory-protocol.md b/dist/claude/skills/parallel-split/territory-protocol.md new file mode 100644 index 0000000..c492077 --- /dev/null +++ b/dist/claude/skills/parallel-split/territory-protocol.md @@ -0,0 +1,66 @@ +# Territory Protocol for Parallel Worktrees + +You are working in a **parallel worktree** with territory-based file isolation. Other agents are simultaneously working on other task groups in separate worktrees. To prevent merge conflicts, you MUST respect the territory rules below. + +--- + +## FILE OWNERSHIP RULES + +### Owned Files & Directories +{{OWNED_FILES}} + +You may freely create and edit these files. You may also create NEW files within your owned directories. + +### Read-Only Files +{{READ_ONLY_FILES}} + +You can IMPORT these files but MUST NOT modify them. They belong to another worktree or are shared infrastructure. + +### Forbidden Directories +{{FORBIDDEN_DIRS}} + +Do NOT touch any file in these directories. They are owned by other worktrees. + +### Shared Files +{{SHARED_FILES}} + +For each shared file, follow the strategy specified: + +- **deferred**: Do NOT edit this file directly. Create `_deferred/{{WORKTREE_ID}}/` with your additions. The merge step will consolidate. +- **append_only**: You may ADD new entries (dependencies, imports). Do NOT remove or modify existing entries. +- **single_owner (you own)**: Edit freely, but preserve exports that other worktrees depend on. +- **single_owner (other owns)**: Do NOT modify. If you need changes, document them in `_deferred/{{WORKTREE_ID}}/request.md`. + +--- + +## TERRITORY VIOLATION PROTOCOL + +If during implementation you realize you NEED to edit a file outside your territory: + +1. **Do NOT edit it** +2. Create `_deferred/{{WORKTREE_ID}}/territory-request.md` documenting what you need +3. Create a stub or workaround within your territory +4. Continue with implementation — the merge step will handle cross-territory needs +5. Note the territory limitation as a concern in your implementation + +--- + +## MERGE ORDER + +{{MERGE_ORDER}} + +Your worktree will be merged in the order specified above. If you depend on code from a worktree that merges before you, it will be available after their merge completes. + +--- + +## WORKFLOW + +You are running the afyapowers 5-phase workflow for your assigned tasks: + +1. Your plan.md has been pre-populated with your assigned tasks only +2. Run the implement phase: follow TDD, use subagent-driven-development for wave execution +3. After implementation: proceed to review phase (`/afyapowers:next`) +4. After review: proceed to complete phase (`/afyapowers:next`) +5. At completion: choose "Keep as-is" — the parent orchestrator handles merge + +**IMPORTANT:** Always respect territory rules during ALL phases (implement, review, complete). diff --git a/dist/cursor/commands/afyapowers-next.md b/dist/cursor/commands/afyapowers-next.md index b535c31..c4b7592 100644 --- a/dist/cursor/commands/afyapowers-next.md +++ b/dist/cursor/commands/afyapowers-next.md @@ -52,15 +52,86 @@ Determine the next phase from the ordered list: design → plan → implement ## Step 5: Invoke Next Phase Skill -Tell the user which phase is starting, then invoke the appropriate skill: +Tell the user which phase is starting, then invoke the appropriate skill. + +**Special case: plan → implement transition** — Before invoking the implementing skill, run the Parallel Split Analysis (Step 5A). | Next Phase | Skill to Invoke | What It Does | |-----------|----------------|--------------| | plan | **writing-plans** skill | Break design into implementation tasks | -| implement | **implementing** skill | Execute tasks with TDD + subagents | +| implement | **(see Step 5A first)** → **implementing** skill | Execute tasks with TDD + subagents | | review | **reviewing** skill | 2-step code review (spec compliance + quality) | | complete | **completing** skill | Merge/PR/cleanup, produce completion summary | +### Step 5A: Parallel Split Analysis (plan → implement ONLY) + +**This step runs ONLY when transitioning from plan to implement.** For all other transitions, skip to Step 5B. + +1. Read the plan from `.afyapowers/features//artifacts/plan.md` +2. Parse all tasks: extract task numbers, `**Depends on:**` lines, and `**Files:**` sections +3. Build the dependency graph +4. Find **disconnected components** — groups of tasks with NO dependencies between them + +**How to find disconnected components:** +- Start with each task as its own group +- If Task A depends on Task B, merge their groups +- If Task A and Task B share files (overlap), merge their groups +- After processing all deps and overlaps, count remaining distinct groups + +5. **If only 1 group exists** (all tasks are connected): skip to Step 5B — no split possible. + +6. **If 2+ disconnected groups exist**, analyze each group: + - List tasks in the group + - Describe the group by its primary domain (infer from file paths and task names) + - List key files/directories the group touches + +7. **Present the choice to the user:** + +``` +Your plan has independent task groups with no dependencies between them: + + Group A (Tasks 1, 2, 5): + Files: + + Group B (Tasks 3, 4): + Files: + + Group C (Tasks 6, 7): + Files: + +How would you like to execute? + + 1) Sequential (default) — one agent implements all tasks using wave execution + 2) Parallel worktrees — creates worktrees with territory-based file isolation, + each runs the full afyapowers workflow (implement → review → complete) +``` + +8. **If user chooses 1 (Sequential):** proceed to Step 5B normally. + +9. **If user chooses 2 (Parallel):** + - Invoke `parallel-split` skill with: + - `feature_slug`: the active feature slug + - `plan_content`: full plan.md content + - `design_content`: full design.md content (read from artifacts) + - `task_groups`: the disconnected groups with task assignments + - `all_tasks`: parsed tasks with deps, files, status + - The parallel-split skill handles worktree creation, territory mapping, and terminal launch + - After the skill completes, tell the user: + "Parallel worktrees created. Each worktree will run implement → review → complete independently. + After all worktrees finish, merge them in order and run `/afyapowers:next` to proceed with the parent feature's review." + - **STOP** — do not invoke the implementing skill (worktree agents handle it) + +### Step 5B: Normal Phase Invocation + +Invoke the skill for the next phase: + +| Next Phase | Skill to Invoke | +|-----------|----------------| +| plan | **writing-plans** | +| implement | **implementing** | +| review | **reviewing** | +| complete | **completing** | + When the skill completes and produces its artifact: 1. Save the artifact to `.afyapowers/features//artifacts/` 2. Update `state.yaml` to add the artifact to the current phase's artifacts list diff --git a/dist/cursor/skills/afyapowers-parallel-split/SKILL.md b/dist/cursor/skills/afyapowers-parallel-split/SKILL.md new file mode 100644 index 0000000..cd3a4c2 --- /dev/null +++ b/dist/cursor/skills/afyapowers-parallel-split/SKILL.md @@ -0,0 +1,383 @@ +--- +name: afyapowers-parallel-split +description: "Split independent task groups into parallel worktrees with territory-based file isolation" +--- + +# Parallel Split — Territory-Based Worktree Parallelization + +Split a plan with independent task groups into N parallel git worktrees, each with its own territory (file ownership), plan subset, and afyapowers workflow. This enables multiple agents to implement different parts of a feature simultaneously without merge conflicts. + +**Invoked by:** `implementing` skill (when user chooses parallel execution) +**NOT a standalone command** — only triggered as a choice during the plan → implement transition. + +--- + +## Input + +This skill receives from the caller: + +- `feature_slug`: active feature directory name +- `plan_content`: full plan.md content +- `design_content`: full design.md content +- `task_groups`: array of disconnected task groups (computed by caller) +- `all_tasks`: parsed tasks with deps, files, status + +--- + +## Step 1: Build Territory Map + +For each task group, compute file ownership: + +### 1A. Collect files per group + +For each group, aggregate: +- `willCreate`: all files in `Create:` lines of the group's tasks +- `willModify`: all files in `Modify:` lines of the group's tasks +- `willTest`: all files in `Test:` lines of the group's tasks +- `willImport`: files referenced in task descriptions but not in Files: section + +### 1B. Assign territories + +For each group: + +- **ownedFiles**: `willCreate` + `willModify` + `willTest` that are NOT in any other group +- **ownedDirs**: directories where ALL files belong to this group +- **readOnlyFiles**: files this group imports that are owned by another group +- **forbiddenDirs**: directories owned entirely by other groups +- **sharedFiles**: files that appear in multiple groups, with strategies: + - `package.json`, `requirements.txt`, lock files → `deferred` + - Barrel exports (`index.ts`, `__init__.py`) → `deferred` + - Config files → `single_owner` (assign to group that modifies most) + - Entry points (`App.tsx`, `main.py`) → `single_owner` + +### 1C. Validate territory + +Check that: +1. Every `willCreate`/`willModify` file has exactly one owner (no double-ownership) +2. No file is both `ownedFiles` in one group and `ownedFiles` in another +3. Shared files have assigned strategies + +If validation fails, adjust by: +- Moving conflicting files to `deferred` strategy +- Assigning to the group whose tasks mention it most +- If truly inseparable, merge the two groups and reduce N + +### 1D. Determine merge order + +Analyze cross-group dependencies: +- If group B imports/uses files that group A creates → A merges before B +- If no cross-group dependencies → merge in any order (parallel merge) +- Generate ordered list: `["wt1", "wt3", "wt2"]` + +--- + +## Step 2: Create Git Worktrees + +For each task group: + +```bash +PROJECT_NAME=$(basename "$(pwd)") +FEATURE_SHORT=$(echo "{{feature_slug}}" | sed 's/^[0-9-]*//' | cut -c1-20) +BRANCH_NAME="${PROJECT_NAME}-${FEATURE_SHORT}-wt" +WT_PATH="../${PROJECT_NAME}-${FEATURE_SHORT}-wt" + +git worktree add -b "${BRANCH_NAME}" "${WT_PATH}" HEAD +``` + +--- + +## Step 3: Prepare Each Worktree + +For each worktree, do the following: + +### 3A. Create afyapowers feature state + +Create the feature directory structure in the worktree: + +```bash +WT="" +SLUG="-wt" + +mkdir -p "${WT}/.afyapowers/features/${SLUG}/artifacts" +echo "${SLUG}" > "${WT}/.afyapowers/features/active" +``` + +Write `state.yaml`: + +```yaml +feature: " (Group : )" +status: active +created_at: "" +current_phase: implement +phases: + design: + status: completed + started_at: "" + completed_at: "" + artifacts: [design.md] + plan: + status: completed + started_at: "" + completed_at: "" + artifacts: [plan.md] + implement: + status: in_progress + started_at: "" + completed_at: null + artifacts: [] + review: + status: pending + artifacts: [] + complete: + status: pending + artifacts: [] +``` + +Write `history.yaml` with initial events: + +```yaml +- event: feature_created + timestamp: "" + details: "Split from parent feature '' — Group " +- event: phase_started + timestamp: "" + phase: implement + details: "Parallel split — tasks: " +``` + +### 3B. Copy design.md + +Copy the parent feature's `design.md` to the worktree: + +```bash +cp ".afyapowers/features//artifacts/design.md" \ + "${WT}/.afyapowers/features/${SLUG}/artifacts/design.md" +``` + +### 3C. Generate subset plan.md + +Create a `plan.md` containing ONLY this group's tasks: + +1. Copy the plan header (Goal, Architecture, Tech Stack) +2. Include ONLY the `### Task N:` blocks assigned to this group +3. Renumber tasks sequentially (Task 1, Task 2, ...) for clarity +4. Update `**Depends on:**` references to use new task numbers +5. Preserve all step details, file lists, and Figma metadata + +Save to `${WT}/.afyapowers/features/${SLUG}/artifacts/plan.md` + +### 3D. Generate PROMPT.md with territory rules + +Read `skills/parallel-split/territory-protocol.md` as template. + +Replace placeholders: +- `{{WORKTREE_ID}}` → `wt` +- `{{OWNED_FILES}}` → list of ownedFiles + ownedDirs for this group +- `{{READ_ONLY_FILES}}` → list of readOnlyFiles +- `{{FORBIDDEN_DIRS}}` → list of forbiddenDirs +- `{{SHARED_FILES}}` → list with strategies +- `{{MERGE_ORDER}}` → merge order description + +Write to `${WT}/PROMPT.md`: + +```markdown +# Parallel Worktree wt — + +## Context + +You are implementing a subset of the feature "" in a parallel worktree. +This worktree handles tasks: +Focus area: + +## Active Feature + +Your afyapowers feature is ready at: +`.afyapowers/features//` + +The design and plan artifacts are pre-populated. You are starting at the **implement** phase. + +## Instructions + +1. Read PROMPT.md (this file) completely +2. Run the implement phase: the plan at `.afyapowers/features//artifacts/plan.md` has your tasks +3. Follow TDD and subagent-driven-development as usual +4. **Respect territory rules below** — do NOT edit files outside your territory +5. After implement: run `/afyapowers:next` to proceed to review +6. After review: run `/afyapowers:next` to proceed to complete +7. At complete phase: choose **"Keep as-is"** — do NOT merge or create PR +8. After completion, create `WORKTREE_COMPLETE.md` to signal you are done + + +``` + +### 3E. Provision MCP servers (Claude Code only) + +```bash +cd "${WT_ABS_PATH}" +claude mcp remove serena -s project 2>/dev/null +claude mcp remove sequential-thinking -s project 2>/dev/null +claude mcp add -s project serena -- uvx --from 'git+https://github.com/oraios/serena' serena start-mcp-server --context ide-assistant --project "${WT_ABS_PATH}" +claude mcp add -s project sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking +``` + +Copy settings if they exist: + +```bash +[ -f ".claude/settings.local.json" ] && mkdir -p "${WT}/.claude" && cp ".claude/settings.local.json" "${WT}/.claude/" +``` + +--- + +## Step 4: Write territory_map.json + +Write `territory_map.json` in the parent project root: + +```json +{ + "generated": "", + "source": "afyapowers-parallel-split", + "parentFeature": "", + "worktrees": [ + { + "id": "wt1", + "path": "", + "branch": "", + "featureSlug": "-wt1", + "tasks": [1, 2, 5], + "taskNames": ["Task 1: ...", "Task 2: ...", "Task 5: ..."], + "ownedFiles": [], + "ownedDirs": [], + "readOnlyFiles": [], + "forbiddenDirs": [], + "sharedFiles": [] + } + ], + "mergeOrder": ["wt1", "wt3", "wt2"], + "sharedFiles": [] +} +``` + +--- + +## Step 5: Update Parent Feature State + +In the parent project's `.afyapowers/features//`: + +1. Update `state.yaml`: set implement phase to `in_progress`, add note about parallel split +2. Append to `history.yaml`: + +```yaml +- event: parallel_split + timestamp: "" + details: "Split into parallel worktrees: " + territory_map: "territory_map.json" +``` + +--- + +## Step 6: Launch Terminals + +Detect available terminal multiplexer and launch: + +### 6A. Warp (default on macOS) + +Generate Warp Launch Configuration: + +```yaml +--- +name: afyapowers Parallel +windows: + - tabs: + - title: "afyapowers - Worktrees" + layout: + split_direction: vertical + panes: + - split_direction: horizontal + panes: + - cwd: "" + commands: + - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" + - cwd: "" + commands: + - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" +``` + +Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` + +Open: `open "warp://launch/afyapowers%20Parallel"` + +### 6B. tmux (fallback) + +```bash +SESSION="afyapowers-parallel" +tmux new-session -d -s "${SESSION}" -x 200 -y 50 +tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md...'" Enter +# Split + send-keys for each additional worktree +tmux select-layout -t "${SESSION}" tiled +tmux attach -t "${SESSION}" +``` + +### 6C. Manual (no multiplexer) + +Print commands for user to copy-paste: + +``` +Parallel split complete! Open one terminal per worktree: + + cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' + cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' +``` + +--- + +## Step 7: Display Summary + +``` +Parallel Split Complete + +Feature: +Worktrees: +Territory map: territory_map.json + + wt1 (Tasks ): + Owns: + Branch: + + wt2 (Tasks ): + Owns: + Branch: + +Merge order: wt1 → wt2 → wt3 +Shared files: (all deferred) + +Agents launched in . + +After all worktrees complete: + 1. Merge in order: git merge for each worktree + 2. Consolidate _deferred/ files + 3. Run full test suite + 4. Continue with /afyapowers:next in parent feature (review phase) +``` + +--- + +## CLEANUP + +After all worktrees complete and are merged: + +```bash +# Remove worktrees +git worktree list | grep "afyapowers.*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} + +# Clean up branches +git branch | grep "afyapowers.*wt" | xargs git branch -d + +# Remove territory map +rm territory_map.json + +# Clean up deferred files +rm -rf _deferred/ + +# Remove launch config +rm ~/.warp/launch_configurations/afyapowers-parallel.yaml 2>/dev/null +``` diff --git a/dist/cursor/skills/afyapowers-parallel-split/territory-protocol.md b/dist/cursor/skills/afyapowers-parallel-split/territory-protocol.md new file mode 100644 index 0000000..c492077 --- /dev/null +++ b/dist/cursor/skills/afyapowers-parallel-split/territory-protocol.md @@ -0,0 +1,66 @@ +# Territory Protocol for Parallel Worktrees + +You are working in a **parallel worktree** with territory-based file isolation. Other agents are simultaneously working on other task groups in separate worktrees. To prevent merge conflicts, you MUST respect the territory rules below. + +--- + +## FILE OWNERSHIP RULES + +### Owned Files & Directories +{{OWNED_FILES}} + +You may freely create and edit these files. You may also create NEW files within your owned directories. + +### Read-Only Files +{{READ_ONLY_FILES}} + +You can IMPORT these files but MUST NOT modify them. They belong to another worktree or are shared infrastructure. + +### Forbidden Directories +{{FORBIDDEN_DIRS}} + +Do NOT touch any file in these directories. They are owned by other worktrees. + +### Shared Files +{{SHARED_FILES}} + +For each shared file, follow the strategy specified: + +- **deferred**: Do NOT edit this file directly. Create `_deferred/{{WORKTREE_ID}}/` with your additions. The merge step will consolidate. +- **append_only**: You may ADD new entries (dependencies, imports). Do NOT remove or modify existing entries. +- **single_owner (you own)**: Edit freely, but preserve exports that other worktrees depend on. +- **single_owner (other owns)**: Do NOT modify. If you need changes, document them in `_deferred/{{WORKTREE_ID}}/request.md`. + +--- + +## TERRITORY VIOLATION PROTOCOL + +If during implementation you realize you NEED to edit a file outside your territory: + +1. **Do NOT edit it** +2. Create `_deferred/{{WORKTREE_ID}}/territory-request.md` documenting what you need +3. Create a stub or workaround within your territory +4. Continue with implementation — the merge step will handle cross-territory needs +5. Note the territory limitation as a concern in your implementation + +--- + +## MERGE ORDER + +{{MERGE_ORDER}} + +Your worktree will be merged in the order specified above. If you depend on code from a worktree that merges before you, it will be available after their merge completes. + +--- + +## WORKFLOW + +You are running the afyapowers 5-phase workflow for your assigned tasks: + +1. Your plan.md has been pre-populated with your assigned tasks only +2. Run the implement phase: follow TDD, use subagent-driven-development for wave execution +3. After implementation: proceed to review phase (`/afyapowers:next`) +4. After review: proceed to complete phase (`/afyapowers:next`) +5. At completion: choose "Keep as-is" — the parent orchestrator handles merge + +**IMPORTANT:** Always respect territory rules during ALL phases (implement, review, complete). diff --git a/dist/gemini/commands/next.md b/dist/gemini/commands/next.md index 4461f40..6bb2148 100644 --- a/dist/gemini/commands/next.md +++ b/dist/gemini/commands/next.md @@ -48,15 +48,86 @@ Determine the next phase from the ordered list: design → plan → implement ## Step 5: Invoke Next Phase Skill -Tell the user which phase is starting, then invoke the appropriate skill: +Tell the user which phase is starting, then invoke the appropriate skill. + +**Special case: plan → implement transition** — Before invoking the implementing skill, run the Parallel Split Analysis (Step 5A). | Next Phase | Skill to Invoke | What It Does | |-----------|----------------|--------------| | plan | **writing-plans** skill | Break design into implementation tasks | -| implement | **implementing** skill | Execute tasks with TDD + subagents | +| implement | **(see Step 5A first)** → **implementing** skill | Execute tasks with TDD + subagents | | review | **reviewing** skill | 2-step code review (spec compliance + quality) | | complete | **completing** skill | Merge/PR/cleanup, produce completion summary | +### Step 5A: Parallel Split Analysis (plan → implement ONLY) + +**This step runs ONLY when transitioning from plan to implement.** For all other transitions, skip to Step 5B. + +1. Read the plan from `.afyapowers/features//artifacts/plan.md` +2. Parse all tasks: extract task numbers, `**Depends on:**` lines, and `**Files:**` sections +3. Build the dependency graph +4. Find **disconnected components** — groups of tasks with NO dependencies between them + +**How to find disconnected components:** +- Start with each task as its own group +- If Task A depends on Task B, merge their groups +- If Task A and Task B share files (overlap), merge their groups +- After processing all deps and overlaps, count remaining distinct groups + +5. **If only 1 group exists** (all tasks are connected): skip to Step 5B — no split possible. + +6. **If 2+ disconnected groups exist**, analyze each group: + - List tasks in the group + - Describe the group by its primary domain (infer from file paths and task names) + - List key files/directories the group touches + +7. **Present the choice to the user:** + +``` +Your plan has independent task groups with no dependencies between them: + + Group A (Tasks 1, 2, 5): + Files: + + Group B (Tasks 3, 4): + Files: + + Group C (Tasks 6, 7): + Files: + +How would you like to execute? + + 1) Sequential (default) — one agent implements all tasks using wave execution + 2) Parallel worktrees — creates worktrees with territory-based file isolation, + each runs the full afyapowers workflow (implement → review → complete) +``` + +8. **If user chooses 1 (Sequential):** proceed to Step 5B normally. + +9. **If user chooses 2 (Parallel):** + - Invoke `parallel-split` skill with: + - `feature_slug`: the active feature slug + - `plan_content`: full plan.md content + - `design_content`: full design.md content (read from artifacts) + - `task_groups`: the disconnected groups with task assignments + - `all_tasks`: parsed tasks with deps, files, status + - The parallel-split skill handles worktree creation, territory mapping, and terminal launch + - After the skill completes, tell the user: + "Parallel worktrees created. Each worktree will run implement → review → complete independently. + After all worktrees finish, merge them in order and run `/afyapowers:next` to proceed with the parent feature's review." + - **STOP** — do not invoke the implementing skill (worktree agents handle it) + +### Step 5B: Normal Phase Invocation + +Invoke the skill for the next phase: + +| Next Phase | Skill to Invoke | +|-----------|----------------| +| plan | **writing-plans** | +| implement | **implementing** | +| review | **reviewing** | +| complete | **completing** | + When the skill completes and produces its artifact: 1. Save the artifact to `.afyapowers/features//artifacts/` 2. Update `state.yaml` to add the artifact to the current phase's artifacts list diff --git a/dist/gemini/skills/parallel-split/SKILL.md b/dist/gemini/skills/parallel-split/SKILL.md new file mode 100644 index 0000000..b5a97ab --- /dev/null +++ b/dist/gemini/skills/parallel-split/SKILL.md @@ -0,0 +1,383 @@ +--- +name: parallel-split +description: "Split independent task groups into parallel worktrees with territory-based file isolation" +--- + +# Parallel Split — Territory-Based Worktree Parallelization + +Split a plan with independent task groups into N parallel git worktrees, each with its own territory (file ownership), plan subset, and afyapowers workflow. This enables multiple agents to implement different parts of a feature simultaneously without merge conflicts. + +**Invoked by:** `implementing` skill (when user chooses parallel execution) +**NOT a standalone command** — only triggered as a choice during the plan → implement transition. + +--- + +## Input + +This skill receives from the caller: + +- `feature_slug`: active feature directory name +- `plan_content`: full plan.md content +- `design_content`: full design.md content +- `task_groups`: array of disconnected task groups (computed by caller) +- `all_tasks`: parsed tasks with deps, files, status + +--- + +## Step 1: Build Territory Map + +For each task group, compute file ownership: + +### 1A. Collect files per group + +For each group, aggregate: +- `willCreate`: all files in `Create:` lines of the group's tasks +- `willModify`: all files in `Modify:` lines of the group's tasks +- `willTest`: all files in `Test:` lines of the group's tasks +- `willImport`: files referenced in task descriptions but not in Files: section + +### 1B. Assign territories + +For each group: + +- **ownedFiles**: `willCreate` + `willModify` + `willTest` that are NOT in any other group +- **ownedDirs**: directories where ALL files belong to this group +- **readOnlyFiles**: files this group imports that are owned by another group +- **forbiddenDirs**: directories owned entirely by other groups +- **sharedFiles**: files that appear in multiple groups, with strategies: + - `package.json`, `requirements.txt`, lock files → `deferred` + - Barrel exports (`index.ts`, `__init__.py`) → `deferred` + - Config files → `single_owner` (assign to group that modifies most) + - Entry points (`App.tsx`, `main.py`) → `single_owner` + +### 1C. Validate territory + +Check that: +1. Every `willCreate`/`willModify` file has exactly one owner (no double-ownership) +2. No file is both `ownedFiles` in one group and `ownedFiles` in another +3. Shared files have assigned strategies + +If validation fails, adjust by: +- Moving conflicting files to `deferred` strategy +- Assigning to the group whose tasks mention it most +- If truly inseparable, merge the two groups and reduce N + +### 1D. Determine merge order + +Analyze cross-group dependencies: +- If group B imports/uses files that group A creates → A merges before B +- If no cross-group dependencies → merge in any order (parallel merge) +- Generate ordered list: `["wt1", "wt3", "wt2"]` + +--- + +## Step 2: Create Git Worktrees + +For each task group: + +```bash +PROJECT_NAME=$(basename "$(pwd)") +FEATURE_SHORT=$(echo "{{feature_slug}}" | sed 's/^[0-9-]*//' | cut -c1-20) +BRANCH_NAME="${PROJECT_NAME}-${FEATURE_SHORT}-wt" +WT_PATH="../${PROJECT_NAME}-${FEATURE_SHORT}-wt" + +git worktree add -b "${BRANCH_NAME}" "${WT_PATH}" HEAD +``` + +--- + +## Step 3: Prepare Each Worktree + +For each worktree, do the following: + +### 3A. Create afyapowers feature state + +Create the feature directory structure in the worktree: + +```bash +WT="" +SLUG="-wt" + +mkdir -p "${WT}/.afyapowers/features/${SLUG}/artifacts" +echo "${SLUG}" > "${WT}/.afyapowers/features/active" +``` + +Write `state.yaml`: + +```yaml +feature: " (Group : )" +status: active +created_at: "" +current_phase: implement +phases: + design: + status: completed + started_at: "" + completed_at: "" + artifacts: [design.md] + plan: + status: completed + started_at: "" + completed_at: "" + artifacts: [plan.md] + implement: + status: in_progress + started_at: "" + completed_at: null + artifacts: [] + review: + status: pending + artifacts: [] + complete: + status: pending + artifacts: [] +``` + +Write `history.yaml` with initial events: + +```yaml +- event: feature_created + timestamp: "" + details: "Split from parent feature '' — Group " +- event: phase_started + timestamp: "" + phase: implement + details: "Parallel split — tasks: " +``` + +### 3B. Copy design.md + +Copy the parent feature's `design.md` to the worktree: + +```bash +cp ".afyapowers/features//artifacts/design.md" \ + "${WT}/.afyapowers/features/${SLUG}/artifacts/design.md" +``` + +### 3C. Generate subset plan.md + +Create a `plan.md` containing ONLY this group's tasks: + +1. Copy the plan header (Goal, Architecture, Tech Stack) +2. Include ONLY the `### Task N:` blocks assigned to this group +3. Renumber tasks sequentially (Task 1, Task 2, ...) for clarity +4. Update `**Depends on:**` references to use new task numbers +5. Preserve all step details, file lists, and Figma metadata + +Save to `${WT}/.afyapowers/features/${SLUG}/artifacts/plan.md` + +### 3D. Generate PROMPT.md with territory rules + +Read `skills/parallel-split/territory-protocol.md` as template. + +Replace placeholders: +- `{{WORKTREE_ID}}` → `wt` +- `{{OWNED_FILES}}` → list of ownedFiles + ownedDirs for this group +- `{{READ_ONLY_FILES}}` → list of readOnlyFiles +- `{{FORBIDDEN_DIRS}}` → list of forbiddenDirs +- `{{SHARED_FILES}}` → list with strategies +- `{{MERGE_ORDER}}` → merge order description + +Write to `${WT}/PROMPT.md`: + +```markdown +# Parallel Worktree wt — + +## Context + +You are implementing a subset of the feature "" in a parallel worktree. +This worktree handles tasks: +Focus area: + +## Active Feature + +Your afyapowers feature is ready at: +`.afyapowers/features//` + +The design and plan artifacts are pre-populated. You are starting at the **implement** phase. + +## Instructions + +1. Read PROMPT.md (this file) completely +2. Run the implement phase: the plan at `.afyapowers/features//artifacts/plan.md` has your tasks +3. Follow TDD and subagent-driven-development as usual +4. **Respect territory rules below** — do NOT edit files outside your territory +5. After implement: run `/afyapowers:next` to proceed to review +6. After review: run `/afyapowers:next` to proceed to complete +7. At complete phase: choose **"Keep as-is"** — do NOT merge or create PR +8. After completion, create `WORKTREE_COMPLETE.md` to signal you are done + + +``` + +### 3E. Provision MCP servers (Claude Code only) + +```bash +cd "${WT_ABS_PATH}" +claude mcp remove serena -s project 2>/dev/null +claude mcp remove sequential-thinking -s project 2>/dev/null +claude mcp add -s project serena -- uvx --from 'git+https://github.com/oraios/serena' serena start-mcp-server --context ide-assistant --project "${WT_ABS_PATH}" +claude mcp add -s project sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking +``` + +Copy settings if they exist: + +```bash +[ -f ".claude/settings.local.json" ] && mkdir -p "${WT}/.claude" && cp ".claude/settings.local.json" "${WT}/.claude/" +``` + +--- + +## Step 4: Write territory_map.json + +Write `territory_map.json` in the parent project root: + +```json +{ + "generated": "", + "source": "afyapowers-parallel-split", + "parentFeature": "", + "worktrees": [ + { + "id": "wt1", + "path": "", + "branch": "", + "featureSlug": "-wt1", + "tasks": [1, 2, 5], + "taskNames": ["Task 1: ...", "Task 2: ...", "Task 5: ..."], + "ownedFiles": [], + "ownedDirs": [], + "readOnlyFiles": [], + "forbiddenDirs": [], + "sharedFiles": [] + } + ], + "mergeOrder": ["wt1", "wt3", "wt2"], + "sharedFiles": [] +} +``` + +--- + +## Step 5: Update Parent Feature State + +In the parent project's `.afyapowers/features//`: + +1. Update `state.yaml`: set implement phase to `in_progress`, add note about parallel split +2. Append to `history.yaml`: + +```yaml +- event: parallel_split + timestamp: "" + details: "Split into parallel worktrees: " + territory_map: "territory_map.json" +``` + +--- + +## Step 6: Launch Terminals + +Detect available terminal multiplexer and launch: + +### 6A. Warp (default on macOS) + +Generate Warp Launch Configuration: + +```yaml +--- +name: afyapowers Parallel +windows: + - tabs: + - title: "afyapowers - Worktrees" + layout: + split_direction: vertical + panes: + - split_direction: horizontal + panes: + - cwd: "" + commands: + - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" + - cwd: "" + commands: + - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" +``` + +Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` + +Open: `open "warp://launch/afyapowers%20Parallel"` + +### 6B. tmux (fallback) + +```bash +SESSION="afyapowers-parallel" +tmux new-session -d -s "${SESSION}" -x 200 -y 50 +tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md...'" Enter +# Split + send-keys for each additional worktree +tmux select-layout -t "${SESSION}" tiled +tmux attach -t "${SESSION}" +``` + +### 6C. Manual (no multiplexer) + +Print commands for user to copy-paste: + +``` +Parallel split complete! Open one terminal per worktree: + + cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' + cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' +``` + +--- + +## Step 7: Display Summary + +``` +Parallel Split Complete + +Feature: +Worktrees: +Territory map: territory_map.json + + wt1 (Tasks ): + Owns: + Branch: + + wt2 (Tasks ): + Owns: + Branch: + +Merge order: wt1 → wt2 → wt3 +Shared files: (all deferred) + +Agents launched in . + +After all worktrees complete: + 1. Merge in order: git merge for each worktree + 2. Consolidate _deferred/ files + 3. Run full test suite + 4. Continue with /afyapowers:next in parent feature (review phase) +``` + +--- + +## CLEANUP + +After all worktrees complete and are merged: + +```bash +# Remove worktrees +git worktree list | grep "afyapowers.*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} + +# Clean up branches +git branch | grep "afyapowers.*wt" | xargs git branch -d + +# Remove territory map +rm territory_map.json + +# Clean up deferred files +rm -rf _deferred/ + +# Remove launch config +rm ~/.warp/launch_configurations/afyapowers-parallel.yaml 2>/dev/null +``` diff --git a/dist/gemini/skills/parallel-split/territory-protocol.md b/dist/gemini/skills/parallel-split/territory-protocol.md new file mode 100644 index 0000000..c492077 --- /dev/null +++ b/dist/gemini/skills/parallel-split/territory-protocol.md @@ -0,0 +1,66 @@ +# Territory Protocol for Parallel Worktrees + +You are working in a **parallel worktree** with territory-based file isolation. Other agents are simultaneously working on other task groups in separate worktrees. To prevent merge conflicts, you MUST respect the territory rules below. + +--- + +## FILE OWNERSHIP RULES + +### Owned Files & Directories +{{OWNED_FILES}} + +You may freely create and edit these files. You may also create NEW files within your owned directories. + +### Read-Only Files +{{READ_ONLY_FILES}} + +You can IMPORT these files but MUST NOT modify them. They belong to another worktree or are shared infrastructure. + +### Forbidden Directories +{{FORBIDDEN_DIRS}} + +Do NOT touch any file in these directories. They are owned by other worktrees. + +### Shared Files +{{SHARED_FILES}} + +For each shared file, follow the strategy specified: + +- **deferred**: Do NOT edit this file directly. Create `_deferred/{{WORKTREE_ID}}/` with your additions. The merge step will consolidate. +- **append_only**: You may ADD new entries (dependencies, imports). Do NOT remove or modify existing entries. +- **single_owner (you own)**: Edit freely, but preserve exports that other worktrees depend on. +- **single_owner (other owns)**: Do NOT modify. If you need changes, document them in `_deferred/{{WORKTREE_ID}}/request.md`. + +--- + +## TERRITORY VIOLATION PROTOCOL + +If during implementation you realize you NEED to edit a file outside your territory: + +1. **Do NOT edit it** +2. Create `_deferred/{{WORKTREE_ID}}/territory-request.md` documenting what you need +3. Create a stub or workaround within your territory +4. Continue with implementation — the merge step will handle cross-territory needs +5. Note the territory limitation as a concern in your implementation + +--- + +## MERGE ORDER + +{{MERGE_ORDER}} + +Your worktree will be merged in the order specified above. If you depend on code from a worktree that merges before you, it will be available after their merge completes. + +--- + +## WORKFLOW + +You are running the afyapowers 5-phase workflow for your assigned tasks: + +1. Your plan.md has been pre-populated with your assigned tasks only +2. Run the implement phase: follow TDD, use subagent-driven-development for wave execution +3. After implementation: proceed to review phase (`/afyapowers:next`) +4. After review: proceed to complete phase (`/afyapowers:next`) +5. At completion: choose "Keep as-is" — the parent orchestrator handles merge + +**IMPORTANT:** Always respect territory rules during ALL phases (implement, review, complete). diff --git a/dist/github-copilot/commands/next.md b/dist/github-copilot/commands/next.md index 5faf2d8..9b1dd80 100644 --- a/dist/github-copilot/commands/next.md +++ b/dist/github-copilot/commands/next.md @@ -52,15 +52,86 @@ Determine the next phase from the ordered list: design → plan → implement ## Step 5: Invoke Next Phase Skill -Tell the user which phase is starting, then invoke the appropriate skill: +Tell the user which phase is starting, then invoke the appropriate skill. + +**Special case: plan → implement transition** — Before invoking the implementing skill, run the Parallel Split Analysis (Step 5A). | Next Phase | Skill to Invoke | What It Does | |-----------|----------------|--------------| | plan | **writing-plans** skill | Break design into implementation tasks | -| implement | **implementing** skill | Execute tasks with TDD + subagents | +| implement | **(see Step 5A first)** → **implementing** skill | Execute tasks with TDD + subagents | | review | **reviewing** skill | 2-step code review (spec compliance + quality) | | complete | **completing** skill | Merge/PR/cleanup, produce completion summary | +### Step 5A: Parallel Split Analysis (plan → implement ONLY) + +**This step runs ONLY when transitioning from plan to implement.** For all other transitions, skip to Step 5B. + +1. Read the plan from `.afyapowers/features//artifacts/plan.md` +2. Parse all tasks: extract task numbers, `**Depends on:**` lines, and `**Files:**` sections +3. Build the dependency graph +4. Find **disconnected components** — groups of tasks with NO dependencies between them + +**How to find disconnected components:** +- Start with each task as its own group +- If Task A depends on Task B, merge their groups +- If Task A and Task B share files (overlap), merge their groups +- After processing all deps and overlaps, count remaining distinct groups + +5. **If only 1 group exists** (all tasks are connected): skip to Step 5B — no split possible. + +6. **If 2+ disconnected groups exist**, analyze each group: + - List tasks in the group + - Describe the group by its primary domain (infer from file paths and task names) + - List key files/directories the group touches + +7. **Present the choice to the user:** + +``` +Your plan has independent task groups with no dependencies between them: + + Group A (Tasks 1, 2, 5): + Files: + + Group B (Tasks 3, 4): + Files: + + Group C (Tasks 6, 7): + Files: + +How would you like to execute? + + 1) Sequential (default) — one agent implements all tasks using wave execution + 2) Parallel worktrees — creates worktrees with territory-based file isolation, + each runs the full afyapowers workflow (implement → review → complete) +``` + +8. **If user chooses 1 (Sequential):** proceed to Step 5B normally. + +9. **If user chooses 2 (Parallel):** + - Invoke `parallel-split` skill with: + - `feature_slug`: the active feature slug + - `plan_content`: full plan.md content + - `design_content`: full design.md content (read from artifacts) + - `task_groups`: the disconnected groups with task assignments + - `all_tasks`: parsed tasks with deps, files, status + - The parallel-split skill handles worktree creation, territory mapping, and terminal launch + - After the skill completes, tell the user: + "Parallel worktrees created. Each worktree will run implement → review → complete independently. + After all worktrees finish, merge them in order and run `/afyapowers:next` to proceed with the parent feature's review." + - **STOP** — do not invoke the implementing skill (worktree agents handle it) + +### Step 5B: Normal Phase Invocation + +Invoke the skill for the next phase: + +| Next Phase | Skill to Invoke | +|-----------|----------------| +| plan | **writing-plans** | +| implement | **implementing** | +| review | **reviewing** | +| complete | **completing** | + When the skill completes and produces its artifact: 1. Save the artifact to `.afyapowers/features//artifacts/` 2. Update `state.yaml` to add the artifact to the current phase's artifacts list diff --git a/dist/github-copilot/skills/parallel-split/SKILL.md b/dist/github-copilot/skills/parallel-split/SKILL.md new file mode 100644 index 0000000..b5a97ab --- /dev/null +++ b/dist/github-copilot/skills/parallel-split/SKILL.md @@ -0,0 +1,383 @@ +--- +name: parallel-split +description: "Split independent task groups into parallel worktrees with territory-based file isolation" +--- + +# Parallel Split — Territory-Based Worktree Parallelization + +Split a plan with independent task groups into N parallel git worktrees, each with its own territory (file ownership), plan subset, and afyapowers workflow. This enables multiple agents to implement different parts of a feature simultaneously without merge conflicts. + +**Invoked by:** `implementing` skill (when user chooses parallel execution) +**NOT a standalone command** — only triggered as a choice during the plan → implement transition. + +--- + +## Input + +This skill receives from the caller: + +- `feature_slug`: active feature directory name +- `plan_content`: full plan.md content +- `design_content`: full design.md content +- `task_groups`: array of disconnected task groups (computed by caller) +- `all_tasks`: parsed tasks with deps, files, status + +--- + +## Step 1: Build Territory Map + +For each task group, compute file ownership: + +### 1A. Collect files per group + +For each group, aggregate: +- `willCreate`: all files in `Create:` lines of the group's tasks +- `willModify`: all files in `Modify:` lines of the group's tasks +- `willTest`: all files in `Test:` lines of the group's tasks +- `willImport`: files referenced in task descriptions but not in Files: section + +### 1B. Assign territories + +For each group: + +- **ownedFiles**: `willCreate` + `willModify` + `willTest` that are NOT in any other group +- **ownedDirs**: directories where ALL files belong to this group +- **readOnlyFiles**: files this group imports that are owned by another group +- **forbiddenDirs**: directories owned entirely by other groups +- **sharedFiles**: files that appear in multiple groups, with strategies: + - `package.json`, `requirements.txt`, lock files → `deferred` + - Barrel exports (`index.ts`, `__init__.py`) → `deferred` + - Config files → `single_owner` (assign to group that modifies most) + - Entry points (`App.tsx`, `main.py`) → `single_owner` + +### 1C. Validate territory + +Check that: +1. Every `willCreate`/`willModify` file has exactly one owner (no double-ownership) +2. No file is both `ownedFiles` in one group and `ownedFiles` in another +3. Shared files have assigned strategies + +If validation fails, adjust by: +- Moving conflicting files to `deferred` strategy +- Assigning to the group whose tasks mention it most +- If truly inseparable, merge the two groups and reduce N + +### 1D. Determine merge order + +Analyze cross-group dependencies: +- If group B imports/uses files that group A creates → A merges before B +- If no cross-group dependencies → merge in any order (parallel merge) +- Generate ordered list: `["wt1", "wt3", "wt2"]` + +--- + +## Step 2: Create Git Worktrees + +For each task group: + +```bash +PROJECT_NAME=$(basename "$(pwd)") +FEATURE_SHORT=$(echo "{{feature_slug}}" | sed 's/^[0-9-]*//' | cut -c1-20) +BRANCH_NAME="${PROJECT_NAME}-${FEATURE_SHORT}-wt" +WT_PATH="../${PROJECT_NAME}-${FEATURE_SHORT}-wt" + +git worktree add -b "${BRANCH_NAME}" "${WT_PATH}" HEAD +``` + +--- + +## Step 3: Prepare Each Worktree + +For each worktree, do the following: + +### 3A. Create afyapowers feature state + +Create the feature directory structure in the worktree: + +```bash +WT="" +SLUG="-wt" + +mkdir -p "${WT}/.afyapowers/features/${SLUG}/artifacts" +echo "${SLUG}" > "${WT}/.afyapowers/features/active" +``` + +Write `state.yaml`: + +```yaml +feature: " (Group : )" +status: active +created_at: "" +current_phase: implement +phases: + design: + status: completed + started_at: "" + completed_at: "" + artifacts: [design.md] + plan: + status: completed + started_at: "" + completed_at: "" + artifacts: [plan.md] + implement: + status: in_progress + started_at: "" + completed_at: null + artifacts: [] + review: + status: pending + artifacts: [] + complete: + status: pending + artifacts: [] +``` + +Write `history.yaml` with initial events: + +```yaml +- event: feature_created + timestamp: "" + details: "Split from parent feature '' — Group " +- event: phase_started + timestamp: "" + phase: implement + details: "Parallel split — tasks: " +``` + +### 3B. Copy design.md + +Copy the parent feature's `design.md` to the worktree: + +```bash +cp ".afyapowers/features//artifacts/design.md" \ + "${WT}/.afyapowers/features/${SLUG}/artifacts/design.md" +``` + +### 3C. Generate subset plan.md + +Create a `plan.md` containing ONLY this group's tasks: + +1. Copy the plan header (Goal, Architecture, Tech Stack) +2. Include ONLY the `### Task N:` blocks assigned to this group +3. Renumber tasks sequentially (Task 1, Task 2, ...) for clarity +4. Update `**Depends on:**` references to use new task numbers +5. Preserve all step details, file lists, and Figma metadata + +Save to `${WT}/.afyapowers/features/${SLUG}/artifacts/plan.md` + +### 3D. Generate PROMPT.md with territory rules + +Read `skills/parallel-split/territory-protocol.md` as template. + +Replace placeholders: +- `{{WORKTREE_ID}}` → `wt` +- `{{OWNED_FILES}}` → list of ownedFiles + ownedDirs for this group +- `{{READ_ONLY_FILES}}` → list of readOnlyFiles +- `{{FORBIDDEN_DIRS}}` → list of forbiddenDirs +- `{{SHARED_FILES}}` → list with strategies +- `{{MERGE_ORDER}}` → merge order description + +Write to `${WT}/PROMPT.md`: + +```markdown +# Parallel Worktree wt — + +## Context + +You are implementing a subset of the feature "" in a parallel worktree. +This worktree handles tasks: +Focus area: + +## Active Feature + +Your afyapowers feature is ready at: +`.afyapowers/features//` + +The design and plan artifacts are pre-populated. You are starting at the **implement** phase. + +## Instructions + +1. Read PROMPT.md (this file) completely +2. Run the implement phase: the plan at `.afyapowers/features//artifacts/plan.md` has your tasks +3. Follow TDD and subagent-driven-development as usual +4. **Respect territory rules below** — do NOT edit files outside your territory +5. After implement: run `/afyapowers:next` to proceed to review +6. After review: run `/afyapowers:next` to proceed to complete +7. At complete phase: choose **"Keep as-is"** — do NOT merge or create PR +8. After completion, create `WORKTREE_COMPLETE.md` to signal you are done + + +``` + +### 3E. Provision MCP servers (Claude Code only) + +```bash +cd "${WT_ABS_PATH}" +claude mcp remove serena -s project 2>/dev/null +claude mcp remove sequential-thinking -s project 2>/dev/null +claude mcp add -s project serena -- uvx --from 'git+https://github.com/oraios/serena' serena start-mcp-server --context ide-assistant --project "${WT_ABS_PATH}" +claude mcp add -s project sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking +``` + +Copy settings if they exist: + +```bash +[ -f ".claude/settings.local.json" ] && mkdir -p "${WT}/.claude" && cp ".claude/settings.local.json" "${WT}/.claude/" +``` + +--- + +## Step 4: Write territory_map.json + +Write `territory_map.json` in the parent project root: + +```json +{ + "generated": "", + "source": "afyapowers-parallel-split", + "parentFeature": "", + "worktrees": [ + { + "id": "wt1", + "path": "", + "branch": "", + "featureSlug": "-wt1", + "tasks": [1, 2, 5], + "taskNames": ["Task 1: ...", "Task 2: ...", "Task 5: ..."], + "ownedFiles": [], + "ownedDirs": [], + "readOnlyFiles": [], + "forbiddenDirs": [], + "sharedFiles": [] + } + ], + "mergeOrder": ["wt1", "wt3", "wt2"], + "sharedFiles": [] +} +``` + +--- + +## Step 5: Update Parent Feature State + +In the parent project's `.afyapowers/features//`: + +1. Update `state.yaml`: set implement phase to `in_progress`, add note about parallel split +2. Append to `history.yaml`: + +```yaml +- event: parallel_split + timestamp: "" + details: "Split into parallel worktrees: " + territory_map: "territory_map.json" +``` + +--- + +## Step 6: Launch Terminals + +Detect available terminal multiplexer and launch: + +### 6A. Warp (default on macOS) + +Generate Warp Launch Configuration: + +```yaml +--- +name: afyapowers Parallel +windows: + - tabs: + - title: "afyapowers - Worktrees" + layout: + split_direction: vertical + panes: + - split_direction: horizontal + panes: + - cwd: "" + commands: + - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" + - cwd: "" + commands: + - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" +``` + +Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` + +Open: `open "warp://launch/afyapowers%20Parallel"` + +### 6B. tmux (fallback) + +```bash +SESSION="afyapowers-parallel" +tmux new-session -d -s "${SESSION}" -x 200 -y 50 +tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md...'" Enter +# Split + send-keys for each additional worktree +tmux select-layout -t "${SESSION}" tiled +tmux attach -t "${SESSION}" +``` + +### 6C. Manual (no multiplexer) + +Print commands for user to copy-paste: + +``` +Parallel split complete! Open one terminal per worktree: + + cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' + cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' +``` + +--- + +## Step 7: Display Summary + +``` +Parallel Split Complete + +Feature: +Worktrees: +Territory map: territory_map.json + + wt1 (Tasks ): + Owns: + Branch: + + wt2 (Tasks ): + Owns: + Branch: + +Merge order: wt1 → wt2 → wt3 +Shared files: (all deferred) + +Agents launched in . + +After all worktrees complete: + 1. Merge in order: git merge for each worktree + 2. Consolidate _deferred/ files + 3. Run full test suite + 4. Continue with /afyapowers:next in parent feature (review phase) +``` + +--- + +## CLEANUP + +After all worktrees complete and are merged: + +```bash +# Remove worktrees +git worktree list | grep "afyapowers.*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} + +# Clean up branches +git branch | grep "afyapowers.*wt" | xargs git branch -d + +# Remove territory map +rm territory_map.json + +# Clean up deferred files +rm -rf _deferred/ + +# Remove launch config +rm ~/.warp/launch_configurations/afyapowers-parallel.yaml 2>/dev/null +``` diff --git a/dist/github-copilot/skills/parallel-split/territory-protocol.md b/dist/github-copilot/skills/parallel-split/territory-protocol.md new file mode 100644 index 0000000..c492077 --- /dev/null +++ b/dist/github-copilot/skills/parallel-split/territory-protocol.md @@ -0,0 +1,66 @@ +# Territory Protocol for Parallel Worktrees + +You are working in a **parallel worktree** with territory-based file isolation. Other agents are simultaneously working on other task groups in separate worktrees. To prevent merge conflicts, you MUST respect the territory rules below. + +--- + +## FILE OWNERSHIP RULES + +### Owned Files & Directories +{{OWNED_FILES}} + +You may freely create and edit these files. You may also create NEW files within your owned directories. + +### Read-Only Files +{{READ_ONLY_FILES}} + +You can IMPORT these files but MUST NOT modify them. They belong to another worktree or are shared infrastructure. + +### Forbidden Directories +{{FORBIDDEN_DIRS}} + +Do NOT touch any file in these directories. They are owned by other worktrees. + +### Shared Files +{{SHARED_FILES}} + +For each shared file, follow the strategy specified: + +- **deferred**: Do NOT edit this file directly. Create `_deferred/{{WORKTREE_ID}}/` with your additions. The merge step will consolidate. +- **append_only**: You may ADD new entries (dependencies, imports). Do NOT remove or modify existing entries. +- **single_owner (you own)**: Edit freely, but preserve exports that other worktrees depend on. +- **single_owner (other owns)**: Do NOT modify. If you need changes, document them in `_deferred/{{WORKTREE_ID}}/request.md`. + +--- + +## TERRITORY VIOLATION PROTOCOL + +If during implementation you realize you NEED to edit a file outside your territory: + +1. **Do NOT edit it** +2. Create `_deferred/{{WORKTREE_ID}}/territory-request.md` documenting what you need +3. Create a stub or workaround within your territory +4. Continue with implementation — the merge step will handle cross-territory needs +5. Note the territory limitation as a concern in your implementation + +--- + +## MERGE ORDER + +{{MERGE_ORDER}} + +Your worktree will be merged in the order specified above. If you depend on code from a worktree that merges before you, it will be available after their merge completes. + +--- + +## WORKFLOW + +You are running the afyapowers 5-phase workflow for your assigned tasks: + +1. Your plan.md has been pre-populated with your assigned tasks only +2. Run the implement phase: follow TDD, use subagent-driven-development for wave execution +3. After implementation: proceed to review phase (`/afyapowers:next`) +4. After review: proceed to complete phase (`/afyapowers:next`) +5. At completion: choose "Keep as-is" — the parent orchestrator handles merge + +**IMPORTANT:** Always respect territory rules during ALL phases (implement, review, complete). diff --git a/src/commands/next.md b/src/commands/next.md index 4461f40..6bb2148 100644 --- a/src/commands/next.md +++ b/src/commands/next.md @@ -48,15 +48,86 @@ Determine the next phase from the ordered list: design → plan → implement ## Step 5: Invoke Next Phase Skill -Tell the user which phase is starting, then invoke the appropriate skill: +Tell the user which phase is starting, then invoke the appropriate skill. + +**Special case: plan → implement transition** — Before invoking the implementing skill, run the Parallel Split Analysis (Step 5A). | Next Phase | Skill to Invoke | What It Does | |-----------|----------------|--------------| | plan | **writing-plans** skill | Break design into implementation tasks | -| implement | **implementing** skill | Execute tasks with TDD + subagents | +| implement | **(see Step 5A first)** → **implementing** skill | Execute tasks with TDD + subagents | | review | **reviewing** skill | 2-step code review (spec compliance + quality) | | complete | **completing** skill | Merge/PR/cleanup, produce completion summary | +### Step 5A: Parallel Split Analysis (plan → implement ONLY) + +**This step runs ONLY when transitioning from plan to implement.** For all other transitions, skip to Step 5B. + +1. Read the plan from `.afyapowers/features//artifacts/plan.md` +2. Parse all tasks: extract task numbers, `**Depends on:**` lines, and `**Files:**` sections +3. Build the dependency graph +4. Find **disconnected components** — groups of tasks with NO dependencies between them + +**How to find disconnected components:** +- Start with each task as its own group +- If Task A depends on Task B, merge their groups +- If Task A and Task B share files (overlap), merge their groups +- After processing all deps and overlaps, count remaining distinct groups + +5. **If only 1 group exists** (all tasks are connected): skip to Step 5B — no split possible. + +6. **If 2+ disconnected groups exist**, analyze each group: + - List tasks in the group + - Describe the group by its primary domain (infer from file paths and task names) + - List key files/directories the group touches + +7. **Present the choice to the user:** + +``` +Your plan has independent task groups with no dependencies between them: + + Group A (Tasks 1, 2, 5): + Files: + + Group B (Tasks 3, 4): + Files: + + Group C (Tasks 6, 7): + Files: + +How would you like to execute? + + 1) Sequential (default) — one agent implements all tasks using wave execution + 2) Parallel worktrees — creates worktrees with territory-based file isolation, + each runs the full afyapowers workflow (implement → review → complete) +``` + +8. **If user chooses 1 (Sequential):** proceed to Step 5B normally. + +9. **If user chooses 2 (Parallel):** + - Invoke `parallel-split` skill with: + - `feature_slug`: the active feature slug + - `plan_content`: full plan.md content + - `design_content`: full design.md content (read from artifacts) + - `task_groups`: the disconnected groups with task assignments + - `all_tasks`: parsed tasks with deps, files, status + - The parallel-split skill handles worktree creation, territory mapping, and terminal launch + - After the skill completes, tell the user: + "Parallel worktrees created. Each worktree will run implement → review → complete independently. + After all worktrees finish, merge them in order and run `/afyapowers:next` to proceed with the parent feature's review." + - **STOP** — do not invoke the implementing skill (worktree agents handle it) + +### Step 5B: Normal Phase Invocation + +Invoke the skill for the next phase: + +| Next Phase | Skill to Invoke | +|-----------|----------------| +| plan | **writing-plans** | +| implement | **implementing** | +| review | **reviewing** | +| complete | **completing** | + When the skill completes and produces its artifact: 1. Save the artifact to `.afyapowers/features//artifacts/` 2. Update `state.yaml` to add the artifact to the current phase's artifacts list diff --git a/src/skills/parallel-split/SKILL.md b/src/skills/parallel-split/SKILL.md new file mode 100644 index 0000000..b5a97ab --- /dev/null +++ b/src/skills/parallel-split/SKILL.md @@ -0,0 +1,383 @@ +--- +name: parallel-split +description: "Split independent task groups into parallel worktrees with territory-based file isolation" +--- + +# Parallel Split — Territory-Based Worktree Parallelization + +Split a plan with independent task groups into N parallel git worktrees, each with its own territory (file ownership), plan subset, and afyapowers workflow. This enables multiple agents to implement different parts of a feature simultaneously without merge conflicts. + +**Invoked by:** `implementing` skill (when user chooses parallel execution) +**NOT a standalone command** — only triggered as a choice during the plan → implement transition. + +--- + +## Input + +This skill receives from the caller: + +- `feature_slug`: active feature directory name +- `plan_content`: full plan.md content +- `design_content`: full design.md content +- `task_groups`: array of disconnected task groups (computed by caller) +- `all_tasks`: parsed tasks with deps, files, status + +--- + +## Step 1: Build Territory Map + +For each task group, compute file ownership: + +### 1A. Collect files per group + +For each group, aggregate: +- `willCreate`: all files in `Create:` lines of the group's tasks +- `willModify`: all files in `Modify:` lines of the group's tasks +- `willTest`: all files in `Test:` lines of the group's tasks +- `willImport`: files referenced in task descriptions but not in Files: section + +### 1B. Assign territories + +For each group: + +- **ownedFiles**: `willCreate` + `willModify` + `willTest` that are NOT in any other group +- **ownedDirs**: directories where ALL files belong to this group +- **readOnlyFiles**: files this group imports that are owned by another group +- **forbiddenDirs**: directories owned entirely by other groups +- **sharedFiles**: files that appear in multiple groups, with strategies: + - `package.json`, `requirements.txt`, lock files → `deferred` + - Barrel exports (`index.ts`, `__init__.py`) → `deferred` + - Config files → `single_owner` (assign to group that modifies most) + - Entry points (`App.tsx`, `main.py`) → `single_owner` + +### 1C. Validate territory + +Check that: +1. Every `willCreate`/`willModify` file has exactly one owner (no double-ownership) +2. No file is both `ownedFiles` in one group and `ownedFiles` in another +3. Shared files have assigned strategies + +If validation fails, adjust by: +- Moving conflicting files to `deferred` strategy +- Assigning to the group whose tasks mention it most +- If truly inseparable, merge the two groups and reduce N + +### 1D. Determine merge order + +Analyze cross-group dependencies: +- If group B imports/uses files that group A creates → A merges before B +- If no cross-group dependencies → merge in any order (parallel merge) +- Generate ordered list: `["wt1", "wt3", "wt2"]` + +--- + +## Step 2: Create Git Worktrees + +For each task group: + +```bash +PROJECT_NAME=$(basename "$(pwd)") +FEATURE_SHORT=$(echo "{{feature_slug}}" | sed 's/^[0-9-]*//' | cut -c1-20) +BRANCH_NAME="${PROJECT_NAME}-${FEATURE_SHORT}-wt" +WT_PATH="../${PROJECT_NAME}-${FEATURE_SHORT}-wt" + +git worktree add -b "${BRANCH_NAME}" "${WT_PATH}" HEAD +``` + +--- + +## Step 3: Prepare Each Worktree + +For each worktree, do the following: + +### 3A. Create afyapowers feature state + +Create the feature directory structure in the worktree: + +```bash +WT="" +SLUG="-wt" + +mkdir -p "${WT}/.afyapowers/features/${SLUG}/artifacts" +echo "${SLUG}" > "${WT}/.afyapowers/features/active" +``` + +Write `state.yaml`: + +```yaml +feature: " (Group : )" +status: active +created_at: "" +current_phase: implement +phases: + design: + status: completed + started_at: "" + completed_at: "" + artifacts: [design.md] + plan: + status: completed + started_at: "" + completed_at: "" + artifacts: [plan.md] + implement: + status: in_progress + started_at: "" + completed_at: null + artifacts: [] + review: + status: pending + artifacts: [] + complete: + status: pending + artifacts: [] +``` + +Write `history.yaml` with initial events: + +```yaml +- event: feature_created + timestamp: "" + details: "Split from parent feature '' — Group " +- event: phase_started + timestamp: "" + phase: implement + details: "Parallel split — tasks: " +``` + +### 3B. Copy design.md + +Copy the parent feature's `design.md` to the worktree: + +```bash +cp ".afyapowers/features//artifacts/design.md" \ + "${WT}/.afyapowers/features/${SLUG}/artifacts/design.md" +``` + +### 3C. Generate subset plan.md + +Create a `plan.md` containing ONLY this group's tasks: + +1. Copy the plan header (Goal, Architecture, Tech Stack) +2. Include ONLY the `### Task N:` blocks assigned to this group +3. Renumber tasks sequentially (Task 1, Task 2, ...) for clarity +4. Update `**Depends on:**` references to use new task numbers +5. Preserve all step details, file lists, and Figma metadata + +Save to `${WT}/.afyapowers/features/${SLUG}/artifacts/plan.md` + +### 3D. Generate PROMPT.md with territory rules + +Read `skills/parallel-split/territory-protocol.md` as template. + +Replace placeholders: +- `{{WORKTREE_ID}}` → `wt` +- `{{OWNED_FILES}}` → list of ownedFiles + ownedDirs for this group +- `{{READ_ONLY_FILES}}` → list of readOnlyFiles +- `{{FORBIDDEN_DIRS}}` → list of forbiddenDirs +- `{{SHARED_FILES}}` → list with strategies +- `{{MERGE_ORDER}}` → merge order description + +Write to `${WT}/PROMPT.md`: + +```markdown +# Parallel Worktree wt — + +## Context + +You are implementing a subset of the feature "" in a parallel worktree. +This worktree handles tasks: +Focus area: + +## Active Feature + +Your afyapowers feature is ready at: +`.afyapowers/features//` + +The design and plan artifacts are pre-populated. You are starting at the **implement** phase. + +## Instructions + +1. Read PROMPT.md (this file) completely +2. Run the implement phase: the plan at `.afyapowers/features//artifacts/plan.md` has your tasks +3. Follow TDD and subagent-driven-development as usual +4. **Respect territory rules below** — do NOT edit files outside your territory +5. After implement: run `/afyapowers:next` to proceed to review +6. After review: run `/afyapowers:next` to proceed to complete +7. At complete phase: choose **"Keep as-is"** — do NOT merge or create PR +8. After completion, create `WORKTREE_COMPLETE.md` to signal you are done + + +``` + +### 3E. Provision MCP servers (Claude Code only) + +```bash +cd "${WT_ABS_PATH}" +claude mcp remove serena -s project 2>/dev/null +claude mcp remove sequential-thinking -s project 2>/dev/null +claude mcp add -s project serena -- uvx --from 'git+https://github.com/oraios/serena' serena start-mcp-server --context ide-assistant --project "${WT_ABS_PATH}" +claude mcp add -s project sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking +``` + +Copy settings if they exist: + +```bash +[ -f ".claude/settings.local.json" ] && mkdir -p "${WT}/.claude" && cp ".claude/settings.local.json" "${WT}/.claude/" +``` + +--- + +## Step 4: Write territory_map.json + +Write `territory_map.json` in the parent project root: + +```json +{ + "generated": "", + "source": "afyapowers-parallel-split", + "parentFeature": "", + "worktrees": [ + { + "id": "wt1", + "path": "", + "branch": "", + "featureSlug": "-wt1", + "tasks": [1, 2, 5], + "taskNames": ["Task 1: ...", "Task 2: ...", "Task 5: ..."], + "ownedFiles": [], + "ownedDirs": [], + "readOnlyFiles": [], + "forbiddenDirs": [], + "sharedFiles": [] + } + ], + "mergeOrder": ["wt1", "wt3", "wt2"], + "sharedFiles": [] +} +``` + +--- + +## Step 5: Update Parent Feature State + +In the parent project's `.afyapowers/features//`: + +1. Update `state.yaml`: set implement phase to `in_progress`, add note about parallel split +2. Append to `history.yaml`: + +```yaml +- event: parallel_split + timestamp: "" + details: "Split into parallel worktrees: " + territory_map: "territory_map.json" +``` + +--- + +## Step 6: Launch Terminals + +Detect available terminal multiplexer and launch: + +### 6A. Warp (default on macOS) + +Generate Warp Launch Configuration: + +```yaml +--- +name: afyapowers Parallel +windows: + - tabs: + - title: "afyapowers - Worktrees" + layout: + split_direction: vertical + panes: + - split_direction: horizontal + panes: + - cwd: "" + commands: + - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" + - cwd: "" + commands: + - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" +``` + +Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` + +Open: `open "warp://launch/afyapowers%20Parallel"` + +### 6B. tmux (fallback) + +```bash +SESSION="afyapowers-parallel" +tmux new-session -d -s "${SESSION}" -x 200 -y 50 +tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md...'" Enter +# Split + send-keys for each additional worktree +tmux select-layout -t "${SESSION}" tiled +tmux attach -t "${SESSION}" +``` + +### 6C. Manual (no multiplexer) + +Print commands for user to copy-paste: + +``` +Parallel split complete! Open one terminal per worktree: + + cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' + cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' +``` + +--- + +## Step 7: Display Summary + +``` +Parallel Split Complete + +Feature: +Worktrees: +Territory map: territory_map.json + + wt1 (Tasks ): + Owns: + Branch: + + wt2 (Tasks ): + Owns: + Branch: + +Merge order: wt1 → wt2 → wt3 +Shared files: (all deferred) + +Agents launched in . + +After all worktrees complete: + 1. Merge in order: git merge for each worktree + 2. Consolidate _deferred/ files + 3. Run full test suite + 4. Continue with /afyapowers:next in parent feature (review phase) +``` + +--- + +## CLEANUP + +After all worktrees complete and are merged: + +```bash +# Remove worktrees +git worktree list | grep "afyapowers.*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} + +# Clean up branches +git branch | grep "afyapowers.*wt" | xargs git branch -d + +# Remove territory map +rm territory_map.json + +# Clean up deferred files +rm -rf _deferred/ + +# Remove launch config +rm ~/.warp/launch_configurations/afyapowers-parallel.yaml 2>/dev/null +``` diff --git a/src/skills/parallel-split/frontmatter.yaml b/src/skills/parallel-split/frontmatter.yaml new file mode 100644 index 0000000..07fbca8 --- /dev/null +++ b/src/skills/parallel-split/frontmatter.yaml @@ -0,0 +1,9 @@ +claude: + name: afyapowers:parallel-split + description: "Split independent task groups into parallel worktrees with territory-based file isolation" +cursor: + name: afyapowers-parallel-split + description: "Split independent task groups into parallel worktrees with territory-based file isolation" +github-copilot: + name: parallel-split + description: "Split independent task groups into parallel worktrees with territory-based file isolation" diff --git a/src/skills/parallel-split/territory-protocol.md b/src/skills/parallel-split/territory-protocol.md new file mode 100644 index 0000000..c492077 --- /dev/null +++ b/src/skills/parallel-split/territory-protocol.md @@ -0,0 +1,66 @@ +# Territory Protocol for Parallel Worktrees + +You are working in a **parallel worktree** with territory-based file isolation. Other agents are simultaneously working on other task groups in separate worktrees. To prevent merge conflicts, you MUST respect the territory rules below. + +--- + +## FILE OWNERSHIP RULES + +### Owned Files & Directories +{{OWNED_FILES}} + +You may freely create and edit these files. You may also create NEW files within your owned directories. + +### Read-Only Files +{{READ_ONLY_FILES}} + +You can IMPORT these files but MUST NOT modify them. They belong to another worktree or are shared infrastructure. + +### Forbidden Directories +{{FORBIDDEN_DIRS}} + +Do NOT touch any file in these directories. They are owned by other worktrees. + +### Shared Files +{{SHARED_FILES}} + +For each shared file, follow the strategy specified: + +- **deferred**: Do NOT edit this file directly. Create `_deferred/{{WORKTREE_ID}}/` with your additions. The merge step will consolidate. +- **append_only**: You may ADD new entries (dependencies, imports). Do NOT remove or modify existing entries. +- **single_owner (you own)**: Edit freely, but preserve exports that other worktrees depend on. +- **single_owner (other owns)**: Do NOT modify. If you need changes, document them in `_deferred/{{WORKTREE_ID}}/request.md`. + +--- + +## TERRITORY VIOLATION PROTOCOL + +If during implementation you realize you NEED to edit a file outside your territory: + +1. **Do NOT edit it** +2. Create `_deferred/{{WORKTREE_ID}}/territory-request.md` documenting what you need +3. Create a stub or workaround within your territory +4. Continue with implementation — the merge step will handle cross-territory needs +5. Note the territory limitation as a concern in your implementation + +--- + +## MERGE ORDER + +{{MERGE_ORDER}} + +Your worktree will be merged in the order specified above. If you depend on code from a worktree that merges before you, it will be available after their merge completes. + +--- + +## WORKFLOW + +You are running the afyapowers 5-phase workflow for your assigned tasks: + +1. Your plan.md has been pre-populated with your assigned tasks only +2. Run the implement phase: follow TDD, use subagent-driven-development for wave execution +3. After implementation: proceed to review phase (`/afyapowers:next`) +4. After review: proceed to complete phase (`/afyapowers:next`) +5. At completion: choose "Keep as-is" — the parent orchestrator handles merge + +**IMPORTANT:** Always respect territory rules during ALL phases (implement, review, complete). From 10f37dbf6fd533245c51494bf0f74ccf846e5b65 Mon Sep 17 00:00:00 2001 From: allanbrunoafya Date: Thu, 9 Apr 2026 14:34:26 -0300 Subject: [PATCH 2/6] fix: redesign parallel-split to respect workflow architecture MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address all 4 review findings: 1. CRITICAL — Parent state path: Revert next.md to original. Worktrees now run ONLY implement phase, merge back into parent branch, and the parent continues with review→complete seeing the consolidated diff. 2. IMPORTANT — Partial review/complete: Removed review and complete from worktree PROMPT.md. Worktrees create WORKTREE_COMPLETE.md and stop. Parent handles unified review and completion after merge. 3. IMPORTANT — Chain architecture: Moved split choice from next command into implementing skill (between plan validation and SDD invocation). This respects the implementing→SDD chain without bypassing it. 4. IMPORTANT — history.yaml format: Fixed to append under `events:` root key matching the framework convention from new.md. Co-Authored-By: Claude Opus 4.6 (1M context) --- dist/claude/commands/next.md | 75 +----- dist/claude/skills/implementing/SKILL.md | 52 +++- dist/claude/skills/parallel-split/SKILL.md | 225 ++++++------------ .../parallel-split/territory-protocol.md | 29 +-- dist/cursor/commands/afyapowers-next.md | 75 +----- .../skills/afyapowers-implementing/SKILL.md | 52 +++- .../skills/afyapowers-parallel-split/SKILL.md | 225 ++++++------------ .../territory-protocol.md | 29 +-- dist/gemini/commands/next.md | 75 +----- dist/gemini/skills/implementing/SKILL.md | 52 +++- dist/gemini/skills/parallel-split/SKILL.md | 225 ++++++------------ .../parallel-split/territory-protocol.md | 29 +-- dist/github-copilot/commands/next.md | 75 +----- .../skills/implementing/SKILL.md | 52 +++- .../skills/parallel-split/SKILL.md | 225 ++++++------------ .../parallel-split/territory-protocol.md | 29 +-- src/commands/next.md | 75 +----- src/skills/implementing/SKILL.md | 52 +++- src/skills/parallel-split/SKILL.md | 225 ++++++------------ .../parallel-split/territory-protocol.md | 29 +-- 20 files changed, 665 insertions(+), 1240 deletions(-) diff --git a/dist/claude/commands/next.md b/dist/claude/commands/next.md index c3f7716..71d595c 100644 --- a/dist/claude/commands/next.md +++ b/dist/claude/commands/next.md @@ -52,86 +52,15 @@ Determine the next phase from the ordered list: design → plan → implement ## Step 5: Invoke Next Phase Skill -Tell the user which phase is starting, then invoke the appropriate skill. - -**Special case: plan → implement transition** — Before invoking the implementing skill, run the Parallel Split Analysis (Step 5A). +Tell the user which phase is starting, then invoke the appropriate skill: | Next Phase | Skill to Invoke | What It Does | |-----------|----------------|--------------| | plan | **writing-plans** skill | Break design into implementation tasks | -| implement | **(see Step 5A first)** → **implementing** skill | Execute tasks with TDD + subagents | +| implement | **implementing** skill | Execute tasks with TDD + subagents | | review | **reviewing** skill | 2-step code review (spec compliance + quality) | | complete | **completing** skill | Merge/PR/cleanup, produce completion summary | -### Step 5A: Parallel Split Analysis (plan → implement ONLY) - -**This step runs ONLY when transitioning from plan to implement.** For all other transitions, skip to Step 5B. - -1. Read the plan from `.afyapowers/features//artifacts/plan.md` -2. Parse all tasks: extract task numbers, `**Depends on:**` lines, and `**Files:**` sections -3. Build the dependency graph -4. Find **disconnected components** — groups of tasks with NO dependencies between them - -**How to find disconnected components:** -- Start with each task as its own group -- If Task A depends on Task B, merge their groups -- If Task A and Task B share files (overlap), merge their groups -- After processing all deps and overlaps, count remaining distinct groups - -5. **If only 1 group exists** (all tasks are connected): skip to Step 5B — no split possible. - -6. **If 2+ disconnected groups exist**, analyze each group: - - List tasks in the group - - Describe the group by its primary domain (infer from file paths and task names) - - List key files/directories the group touches - -7. **Present the choice to the user:** - -``` -Your plan has independent task groups with no dependencies between them: - - Group A (Tasks 1, 2, 5): - Files: - - Group B (Tasks 3, 4): - Files: - - Group C (Tasks 6, 7): - Files: - -How would you like to execute? - - 1) Sequential (default) — one agent implements all tasks using wave execution - 2) Parallel worktrees — creates worktrees with territory-based file isolation, - each runs the full afyapowers workflow (implement → review → complete) -``` - -8. **If user chooses 1 (Sequential):** proceed to Step 5B normally. - -9. **If user chooses 2 (Parallel):** - - Invoke `parallel-split` skill with: - - `feature_slug`: the active feature slug - - `plan_content`: full plan.md content - - `design_content`: full design.md content (read from artifacts) - - `task_groups`: the disconnected groups with task assignments - - `all_tasks`: parsed tasks with deps, files, status - - The parallel-split skill handles worktree creation, territory mapping, and terminal launch - - After the skill completes, tell the user: - "Parallel worktrees created. Each worktree will run implement → review → complete independently. - After all worktrees finish, merge them in order and run `/afyapowers:next` to proceed with the parent feature's review." - - **STOP** — do not invoke the implementing skill (worktree agents handle it) - -### Step 5B: Normal Phase Invocation - -Invoke the skill for the next phase: - -| Next Phase | Skill to Invoke | -|-----------|----------------| -| plan | **writing-plans** | -| implement | **implementing** | -| review | **reviewing** | -| complete | **completing** | - When the skill completes and produces its artifact: 1. Save the artifact to `.afyapowers/features//artifacts/` 2. Update `state.yaml` to add the artifact to the current phase's artifacts list diff --git a/dist/claude/skills/implementing/SKILL.md b/dist/claude/skills/implementing/SKILL.md index 44e9264..3a19932 100644 --- a/dist/claude/skills/implementing/SKILL.md +++ b/dist/claude/skills/implementing/SKILL.md @@ -23,7 +23,57 @@ Orchestrate plan execution by delegating to subagent-driven-development. - If all tasks are already complete, tell the user and suggest `/afyapowers:next` - If uncompleted tasks remain, proceed to execution -## Required Sub-Skills +## Parallel Split Analysis + +Before dispatching tasks, check if the plan can be split into independent parallel groups. + +### Detect disconnected components + +1. Parse all tasks from the plan: extract task numbers, `**Depends on:**` lines, and `**Files:**` sections +2. Build the dependency graph +3. Find **disconnected components** — groups of tasks with NO dependencies between them: + - Start with each task as its own group + - If Task A depends on Task B, merge their groups + - If Task A and Task B share files (from `**Files:**` sections), merge their groups + - After processing all deps and overlaps, count remaining distinct groups + +4. **If only 1 group** (all tasks are connected): proceed directly to the SDD invocation below. + +5. **If 2+ disconnected groups exist**, analyze each group: + - List tasks in the group + - Describe the group by its primary domain (infer from file paths and task names) + - List key files/directories the group touches + +6. **Present the choice to the user:** + +``` +Your plan has independent task groups with no dependencies between them: + + Group A (Tasks 1, 2, 5): + Files: + + Group B (Tasks 3, 4): + Files: + +How would you like to execute? + + 1) Sequential (default) — one agent implements all tasks using wave execution + 2) Parallel worktrees — creates worktrees with territory-based file isolation, + each implements its task group, then merges back for unified review +``` + +7. **If user chooses 1 (Sequential):** proceed to the SDD invocation below. + +8. **If user chooses 2 (Parallel):** + - Invoke `parallel-split` skill with: feature slug, plan content, design content, task groups, parsed tasks + - The parallel-split skill creates worktrees, each running ONLY the implement phase for its task group + - **After all worktrees complete and merge back:** + - Re-read the parent plan.md — verify all checkboxes are `[x]` (worktree merges update the parent plan) + - If some remain unchecked, report them to the user + - **Resume the parent flow at "After SDD Completes" below** (the parent continues with review → complete) + - **STOP here** — do not invoke SDD (the worktrees handled implementation) + +## Invoke Sub-Skill **REQUIRED:** Invoke `afyapowers:subagent-driven-development` via the Skill tool to execute all plan tasks. diff --git a/dist/claude/skills/parallel-split/SKILL.md b/dist/claude/skills/parallel-split/SKILL.md index b5df8d1..5963247 100644 --- a/dist/claude/skills/parallel-split/SKILL.md +++ b/dist/claude/skills/parallel-split/SKILL.md @@ -5,10 +5,12 @@ description: "Split independent task groups into parallel worktrees with territo # Parallel Split — Territory-Based Worktree Parallelization -Split a plan with independent task groups into N parallel git worktrees, each with its own territory (file ownership), plan subset, and afyapowers workflow. This enables multiple agents to implement different parts of a feature simultaneously without merge conflicts. +Split a plan with independent task groups into N parallel git worktrees. Each worktree implements its task group, then merges back so the parent feature continues with unified review and completion. **Invoked by:** `implementing` skill (when user chooses parallel execution) -**NOT a standalone command** — only triggered as a choice during the plan → implement transition. +**NOT a standalone command** — only triggered as a choice within the implementing phase. + +**Key constraint:** Worktrees run ONLY the implement phase. Review and complete happen on the parent branch after all worktrees merge back. This ensures review sees the consolidated diff and completion reflects the full feature. --- @@ -34,7 +36,6 @@ For each group, aggregate: - `willCreate`: all files in `Create:` lines of the group's tasks - `willModify`: all files in `Modify:` lines of the group's tasks - `willTest`: all files in `Test:` lines of the group's tasks -- `willImport`: files referenced in task descriptions but not in Files: section ### 1B. Assign territories @@ -54,8 +55,7 @@ For each group: Check that: 1. Every `willCreate`/`willModify` file has exactly one owner (no double-ownership) -2. No file is both `ownedFiles` in one group and `ownedFiles` in another -3. Shared files have assigned strategies +2. Shared files have assigned strategies If validation fails, adjust by: - Moving conflicting files to `deferred` strategy @@ -66,7 +66,7 @@ If validation fails, adjust by: Analyze cross-group dependencies: - If group B imports/uses files that group A creates → A merges before B -- If no cross-group dependencies → merge in any order (parallel merge) +- If no cross-group dependencies → merge in any order - Generate ordered list: `["wt1", "wt3", "wt2"]` --- @@ -88,97 +88,29 @@ git worktree add -b "${BRANCH_NAME}" "${WT_PATH}" HEAD ## Step 3: Prepare Each Worktree -For each worktree, do the following: - -### 3A. Create afyapowers feature state - -Create the feature directory structure in the worktree: - -```bash -WT="" -SLUG="-wt" - -mkdir -p "${WT}/.afyapowers/features/${SLUG}/artifacts" -echo "${SLUG}" > "${WT}/.afyapowers/features/active" -``` - -Write `state.yaml`: - -```yaml -feature: " (Group : )" -status: active -created_at: "" -current_phase: implement -phases: - design: - status: completed - started_at: "" - completed_at: "" - artifacts: [design.md] - plan: - status: completed - started_at: "" - completed_at: "" - artifacts: [plan.md] - implement: - status: in_progress - started_at: "" - completed_at: null - artifacts: [] - review: - status: pending - artifacts: [] - complete: - status: pending - artifacts: [] -``` - -Write `history.yaml` with initial events: - -```yaml -- event: feature_created - timestamp: "" - details: "Split from parent feature '' — Group " -- event: phase_started - timestamp: "" - phase: implement - details: "Parallel split — tasks: " -``` - -### 3B. Copy design.md - -Copy the parent feature's `design.md` to the worktree: - -```bash -cp ".afyapowers/features//artifacts/design.md" \ - "${WT}/.afyapowers/features/${SLUG}/artifacts/design.md" -``` - -### 3C. Generate subset plan.md +### 3A. Generate subset plan.md -Create a `plan.md` containing ONLY this group's tasks: +Create a `plan.md` in the worktree root containing ONLY this group's tasks: 1. Copy the plan header (Goal, Architecture, Tech Stack) 2. Include ONLY the `### Task N:` blocks assigned to this group -3. Renumber tasks sequentially (Task 1, Task 2, ...) for clarity -4. Update `**Depends on:**` references to use new task numbers +3. Preserve original task numbers (do NOT renumber — needed for merging checkboxes back) +4. Update `**Depends on:**` references: remove deps on tasks outside this group (they have no cross-group deps by definition) 5. Preserve all step details, file lists, and Figma metadata -Save to `${WT}/.afyapowers/features/${SLUG}/artifacts/plan.md` +Save to `${WT_PATH}/PLAN_SUBSET.md` -### 3D. Generate PROMPT.md with territory rules +### 3B. Copy design.md for context -Read `skills/parallel-split/territory-protocol.md` as template. +```bash +cp ".afyapowers/features//artifacts/design.md" "${WT_PATH}/DESIGN_CONTEXT.md" +``` + +### 3C. Generate PROMPT.md with territory rules -Replace placeholders: -- `{{WORKTREE_ID}}` → `wt` -- `{{OWNED_FILES}}` → list of ownedFiles + ownedDirs for this group -- `{{READ_ONLY_FILES}}` → list of readOnlyFiles -- `{{FORBIDDEN_DIRS}}` → list of forbiddenDirs -- `{{SHARED_FILES}}` → list with strategies -- `{{MERGE_ORDER}}` → merge order description +Read `skills/parallel-split/territory-protocol.md` as template. Replace placeholders with this group's territory data. -Write to `${WT}/PROMPT.md`: +Write to `${WT_PATH}/PROMPT.md`: ```markdown # Parallel Worktree wt — @@ -186,33 +118,33 @@ Write to `${WT}/PROMPT.md`: ## Context You are implementing a subset of the feature "" in a parallel worktree. -This worktree handles tasks: +This worktree handles tasks: Focus area: -## Active Feature - -Your afyapowers feature is ready at: -`.afyapowers/features//` +## Instructions -The design and plan artifacts are pre-populated. You are starting at the **implement** phase. +1. Read this file completely +2. Read `DESIGN_CONTEXT.md` for the full design spec +3. Read `PLAN_SUBSET.md` for your assigned tasks +4. Implement ALL tasks following TDD (test first → implement → refactor → commit) +5. For each completed task, mark its checkbox: `- [ ]` → `- [x]` in PLAN_SUBSET.md +6. **Respect territory rules below** — do NOT edit files outside your territory +7. After ALL tasks are complete: create `WORKTREE_COMPLETE.md` with a summary of what was done +8. Do NOT run /afyapowers:next — do NOT start review or complete phases -## Instructions +## IMPORTANT: Implement Only -1. Read PROMPT.md (this file) completely -2. Run the implement phase: the plan at `.afyapowers/features//artifacts/plan.md` has your tasks -3. Follow TDD and subagent-driven-development as usual -4. **Respect territory rules below** — do NOT edit files outside your territory -5. After implement: run `/afyapowers:next` to proceed to review -6. After review: run `/afyapowers:next` to proceed to complete -7. At complete phase: choose **"Keep as-is"** — do NOT merge or create PR -8. After completion, create `WORKTREE_COMPLETE.md` to signal you are done +This worktree handles ONLY the implement phase. Review and completion happen on +the parent branch after all worktrees merge back. When done, just create +WORKTREE_COMPLETE.md and stop. - + ``` -### 3E. Provision MCP servers (Claude Code only) +### 3D. Provision MCP servers (Claude Code only) ```bash +WT_ABS_PATH="$(cd "${WT_PATH}" && pwd)" cd "${WT_ABS_PATH}" claude mcp remove serena -s project 2>/dev/null claude mcp remove sequential-thinking -s project 2>/dev/null @@ -223,7 +155,7 @@ claude mcp add -s project sequential-thinking -- npx -y @modelcontextprotocol/se Copy settings if they exist: ```bash -[ -f ".claude/settings.local.json" ] && mkdir -p "${WT}/.claude" && cp ".claude/settings.local.json" "${WT}/.claude/" +[ -f ".claude/settings.local.json" ] && mkdir -p "${WT_PATH}/.claude" && cp ".claude/settings.local.json" "${WT_PATH}/.claude/" ``` --- @@ -242,7 +174,6 @@ Write `territory_map.json` in the parent project root: "id": "wt1", "path": "", "branch": "", - "featureSlug": "-wt1", "tasks": [1, 2, 5], "taskNames": ["Task 1: ...", "Task 2: ...", "Task 5: ..."], "ownedFiles": [], @@ -263,22 +194,20 @@ Write `territory_map.json` in the parent project root: In the parent project's `.afyapowers/features//`: -1. Update `state.yaml`: set implement phase to `in_progress`, add note about parallel split -2. Append to `history.yaml`: +Append to `history.yaml` under the `events:` key: ```yaml -- event: parallel_split - timestamp: "" - details: "Split into parallel worktrees: " - territory_map: "territory_map.json" + - timestamp: "" + event: parallel_split + phase: implement + details: "Split into parallel worktrees: " + command: parallel-split ``` --- ## Step 6: Launch Terminals -Detect available terminal multiplexer and launch: - ### 6A. Warp (default on macOS) Generate Warp Launch Configuration: @@ -296,14 +225,15 @@ windows: panes: - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" + - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" + - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" ``` -Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` +Where `` chains the `claude mcp remove` + `claude mcp add` commands from Step 3D. +Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` Open: `open "warp://launch/afyapowers%20Parallel"` ### 6B. tmux (fallback) @@ -311,7 +241,7 @@ Open: `open "warp://launch/afyapowers%20Parallel"` ```bash SESSION="afyapowers-parallel" tmux new-session -d -s "${SESSION}" -x 200 -y 50 -tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md...'" Enter +tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" Enter # Split + send-keys for each additional worktree tmux select-layout -t "${SESSION}" tiled tmux attach -t "${SESSION}" @@ -319,21 +249,14 @@ tmux attach -t "${SESSION}" ### 6C. Manual (no multiplexer) -Print commands for user to copy-paste: - -``` -Parallel split complete! Open one terminal per worktree: - - cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' - cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' -``` +Print commands for user to copy-paste. --- -## Step 7: Display Summary +## Step 7: Display Summary and Post-Merge Instructions ``` -Parallel Split Complete +Parallel Split — Implement Phase Feature: Worktrees: @@ -342,42 +265,36 @@ Territory map: territory_map.json wt1 (Tasks ): Owns: Branch: - + wt2 (Tasks ): Owns: Branch: Merge order: wt1 → wt2 → wt3 -Shared files: (all deferred) - -Agents launched in . - -After all worktrees complete: - 1. Merge in order: git merge for each worktree - 2. Consolidate _deferred/ files - 3. Run full test suite - 4. Continue with /afyapowers:next in parent feature (review phase) -``` +Shared files: (deferred) ---- +Agents launched. -## CLEANUP +After ALL worktrees create WORKTREE_COMPLETE.md: -After all worktrees complete and are merged: + 1. Merge in order: + git merge + git merge + ... -```bash -# Remove worktrees -git worktree list | grep "afyapowers.*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} + 2. Consolidate deferred files (if any in _deferred/) -# Clean up branches -git branch | grep "afyapowers.*wt" | xargs git branch -d + 3. Update plan.md checkboxes: + The merge brings in each worktree's PLAN_SUBSET.md changes. + Verify the parent plan.md has all tasks marked [x]. + If some checkboxes are still [ ], manually mark them based + on the worktree PLAN_SUBSET.md files. -# Remove territory map -rm territory_map.json + 4. Run /afyapowers:next to proceed to review (on the parent feature) -# Clean up deferred files -rm -rf _deferred/ - -# Remove launch config -rm ~/.warp/launch_configurations/afyapowers-parallel.yaml 2>/dev/null + 5. Clean up: + git worktree list | grep ".*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} + rm territory_map.json _deferred/ 2>/dev/null ``` + +**IMPORTANT:** After displaying the summary, the `implementing` skill will wait for the user to complete the merge steps and then resume at the "After SDD Completes" check (verifying all plan.md checkboxes are `[x]`). diff --git a/dist/claude/skills/parallel-split/territory-protocol.md b/dist/claude/skills/parallel-split/territory-protocol.md index c492077..b61d7dd 100644 --- a/dist/claude/skills/parallel-split/territory-protocol.md +++ b/dist/claude/skills/parallel-split/territory-protocol.md @@ -1,6 +1,6 @@ # Territory Protocol for Parallel Worktrees -You are working in a **parallel worktree** with territory-based file isolation. Other agents are simultaneously working on other task groups in separate worktrees. To prevent merge conflicts, you MUST respect the territory rules below. +You are working in a **parallel worktree** implementing a subset of tasks. Other agents are simultaneously working on other task groups in separate worktrees. To prevent merge conflicts, you MUST respect the territory rules below. --- @@ -40,27 +40,16 @@ If during implementation you realize you NEED to edit a file outside your territ 1. **Do NOT edit it** 2. Create `_deferred/{{WORKTREE_ID}}/territory-request.md` documenting what you need 3. Create a stub or workaround within your territory -4. Continue with implementation — the merge step will handle cross-territory needs -5. Note the territory limitation as a concern in your implementation +4. Continue with implementation --- -## MERGE ORDER +## SCOPE: IMPLEMENT ONLY -{{MERGE_ORDER}} +You are running ONLY the implement phase. Do NOT: +- Run `/afyapowers:next` +- Start review or complete phases +- Create review.md or completion.md +- Merge branches or create PRs -Your worktree will be merged in the order specified above. If you depend on code from a worktree that merges before you, it will be available after their merge completes. - ---- - -## WORKFLOW - -You are running the afyapowers 5-phase workflow for your assigned tasks: - -1. Your plan.md has been pre-populated with your assigned tasks only -2. Run the implement phase: follow TDD, use subagent-driven-development for wave execution -3. After implementation: proceed to review phase (`/afyapowers:next`) -4. After review: proceed to complete phase (`/afyapowers:next`) -5. At completion: choose "Keep as-is" — the parent orchestrator handles merge - -**IMPORTANT:** Always respect territory rules during ALL phases (implement, review, complete). +When all tasks are done, create `WORKTREE_COMPLETE.md` and stop. The parent branch handles review and completion after merge. diff --git a/dist/cursor/commands/afyapowers-next.md b/dist/cursor/commands/afyapowers-next.md index c4b7592..b535c31 100644 --- a/dist/cursor/commands/afyapowers-next.md +++ b/dist/cursor/commands/afyapowers-next.md @@ -52,86 +52,15 @@ Determine the next phase from the ordered list: design → plan → implement ## Step 5: Invoke Next Phase Skill -Tell the user which phase is starting, then invoke the appropriate skill. - -**Special case: plan → implement transition** — Before invoking the implementing skill, run the Parallel Split Analysis (Step 5A). +Tell the user which phase is starting, then invoke the appropriate skill: | Next Phase | Skill to Invoke | What It Does | |-----------|----------------|--------------| | plan | **writing-plans** skill | Break design into implementation tasks | -| implement | **(see Step 5A first)** → **implementing** skill | Execute tasks with TDD + subagents | +| implement | **implementing** skill | Execute tasks with TDD + subagents | | review | **reviewing** skill | 2-step code review (spec compliance + quality) | | complete | **completing** skill | Merge/PR/cleanup, produce completion summary | -### Step 5A: Parallel Split Analysis (plan → implement ONLY) - -**This step runs ONLY when transitioning from plan to implement.** For all other transitions, skip to Step 5B. - -1. Read the plan from `.afyapowers/features//artifacts/plan.md` -2. Parse all tasks: extract task numbers, `**Depends on:**` lines, and `**Files:**` sections -3. Build the dependency graph -4. Find **disconnected components** — groups of tasks with NO dependencies between them - -**How to find disconnected components:** -- Start with each task as its own group -- If Task A depends on Task B, merge their groups -- If Task A and Task B share files (overlap), merge their groups -- After processing all deps and overlaps, count remaining distinct groups - -5. **If only 1 group exists** (all tasks are connected): skip to Step 5B — no split possible. - -6. **If 2+ disconnected groups exist**, analyze each group: - - List tasks in the group - - Describe the group by its primary domain (infer from file paths and task names) - - List key files/directories the group touches - -7. **Present the choice to the user:** - -``` -Your plan has independent task groups with no dependencies between them: - - Group A (Tasks 1, 2, 5): - Files: - - Group B (Tasks 3, 4): - Files: - - Group C (Tasks 6, 7): - Files: - -How would you like to execute? - - 1) Sequential (default) — one agent implements all tasks using wave execution - 2) Parallel worktrees — creates worktrees with territory-based file isolation, - each runs the full afyapowers workflow (implement → review → complete) -``` - -8. **If user chooses 1 (Sequential):** proceed to Step 5B normally. - -9. **If user chooses 2 (Parallel):** - - Invoke `parallel-split` skill with: - - `feature_slug`: the active feature slug - - `plan_content`: full plan.md content - - `design_content`: full design.md content (read from artifacts) - - `task_groups`: the disconnected groups with task assignments - - `all_tasks`: parsed tasks with deps, files, status - - The parallel-split skill handles worktree creation, territory mapping, and terminal launch - - After the skill completes, tell the user: - "Parallel worktrees created. Each worktree will run implement → review → complete independently. - After all worktrees finish, merge them in order and run `/afyapowers:next` to proceed with the parent feature's review." - - **STOP** — do not invoke the implementing skill (worktree agents handle it) - -### Step 5B: Normal Phase Invocation - -Invoke the skill for the next phase: - -| Next Phase | Skill to Invoke | -|-----------|----------------| -| plan | **writing-plans** | -| implement | **implementing** | -| review | **reviewing** | -| complete | **completing** | - When the skill completes and produces its artifact: 1. Save the artifact to `.afyapowers/features//artifacts/` 2. Update `state.yaml` to add the artifact to the current phase's artifacts list diff --git a/dist/cursor/skills/afyapowers-implementing/SKILL.md b/dist/cursor/skills/afyapowers-implementing/SKILL.md index 40f8d00..a380621 100644 --- a/dist/cursor/skills/afyapowers-implementing/SKILL.md +++ b/dist/cursor/skills/afyapowers-implementing/SKILL.md @@ -23,7 +23,57 @@ Orchestrate plan execution by delegating to subagent-driven-development. - If all tasks are already complete, tell the user and suggest `/afyapowers:next` - If uncompleted tasks remain, proceed to execution -## Required Sub-Skills +## Parallel Split Analysis + +Before dispatching tasks, check if the plan can be split into independent parallel groups. + +### Detect disconnected components + +1. Parse all tasks from the plan: extract task numbers, `**Depends on:**` lines, and `**Files:**` sections +2. Build the dependency graph +3. Find **disconnected components** — groups of tasks with NO dependencies between them: + - Start with each task as its own group + - If Task A depends on Task B, merge their groups + - If Task A and Task B share files (from `**Files:**` sections), merge their groups + - After processing all deps and overlaps, count remaining distinct groups + +4. **If only 1 group** (all tasks are connected): proceed directly to the SDD invocation below. + +5. **If 2+ disconnected groups exist**, analyze each group: + - List tasks in the group + - Describe the group by its primary domain (infer from file paths and task names) + - List key files/directories the group touches + +6. **Present the choice to the user:** + +``` +Your plan has independent task groups with no dependencies between them: + + Group A (Tasks 1, 2, 5): + Files: + + Group B (Tasks 3, 4): + Files: + +How would you like to execute? + + 1) Sequential (default) — one agent implements all tasks using wave execution + 2) Parallel worktrees — creates worktrees with territory-based file isolation, + each implements its task group, then merges back for unified review +``` + +7. **If user chooses 1 (Sequential):** proceed to the SDD invocation below. + +8. **If user chooses 2 (Parallel):** + - Invoke `parallel-split` skill with: feature slug, plan content, design content, task groups, parsed tasks + - The parallel-split skill creates worktrees, each running ONLY the implement phase for its task group + - **After all worktrees complete and merge back:** + - Re-read the parent plan.md — verify all checkboxes are `[x]` (worktree merges update the parent plan) + - If some remain unchecked, report them to the user + - **Resume the parent flow at "After SDD Completes" below** (the parent continues with review → complete) + - **STOP here** — do not invoke SDD (the worktrees handled implementation) + +## Invoke Sub-Skill **REQUIRED:** Invoke `afyapowers:subagent-driven-development` via the Skill tool to execute all plan tasks. diff --git a/dist/cursor/skills/afyapowers-parallel-split/SKILL.md b/dist/cursor/skills/afyapowers-parallel-split/SKILL.md index cd3a4c2..01d6fe5 100644 --- a/dist/cursor/skills/afyapowers-parallel-split/SKILL.md +++ b/dist/cursor/skills/afyapowers-parallel-split/SKILL.md @@ -5,10 +5,12 @@ description: "Split independent task groups into parallel worktrees with territo # Parallel Split — Territory-Based Worktree Parallelization -Split a plan with independent task groups into N parallel git worktrees, each with its own territory (file ownership), plan subset, and afyapowers workflow. This enables multiple agents to implement different parts of a feature simultaneously without merge conflicts. +Split a plan with independent task groups into N parallel git worktrees. Each worktree implements its task group, then merges back so the parent feature continues with unified review and completion. **Invoked by:** `implementing` skill (when user chooses parallel execution) -**NOT a standalone command** — only triggered as a choice during the plan → implement transition. +**NOT a standalone command** — only triggered as a choice within the implementing phase. + +**Key constraint:** Worktrees run ONLY the implement phase. Review and complete happen on the parent branch after all worktrees merge back. This ensures review sees the consolidated diff and completion reflects the full feature. --- @@ -34,7 +36,6 @@ For each group, aggregate: - `willCreate`: all files in `Create:` lines of the group's tasks - `willModify`: all files in `Modify:` lines of the group's tasks - `willTest`: all files in `Test:` lines of the group's tasks -- `willImport`: files referenced in task descriptions but not in Files: section ### 1B. Assign territories @@ -54,8 +55,7 @@ For each group: Check that: 1. Every `willCreate`/`willModify` file has exactly one owner (no double-ownership) -2. No file is both `ownedFiles` in one group and `ownedFiles` in another -3. Shared files have assigned strategies +2. Shared files have assigned strategies If validation fails, adjust by: - Moving conflicting files to `deferred` strategy @@ -66,7 +66,7 @@ If validation fails, adjust by: Analyze cross-group dependencies: - If group B imports/uses files that group A creates → A merges before B -- If no cross-group dependencies → merge in any order (parallel merge) +- If no cross-group dependencies → merge in any order - Generate ordered list: `["wt1", "wt3", "wt2"]` --- @@ -88,97 +88,29 @@ git worktree add -b "${BRANCH_NAME}" "${WT_PATH}" HEAD ## Step 3: Prepare Each Worktree -For each worktree, do the following: - -### 3A. Create afyapowers feature state - -Create the feature directory structure in the worktree: - -```bash -WT="" -SLUG="-wt" - -mkdir -p "${WT}/.afyapowers/features/${SLUG}/artifacts" -echo "${SLUG}" > "${WT}/.afyapowers/features/active" -``` - -Write `state.yaml`: - -```yaml -feature: " (Group : )" -status: active -created_at: "" -current_phase: implement -phases: - design: - status: completed - started_at: "" - completed_at: "" - artifacts: [design.md] - plan: - status: completed - started_at: "" - completed_at: "" - artifacts: [plan.md] - implement: - status: in_progress - started_at: "" - completed_at: null - artifacts: [] - review: - status: pending - artifacts: [] - complete: - status: pending - artifacts: [] -``` - -Write `history.yaml` with initial events: - -```yaml -- event: feature_created - timestamp: "" - details: "Split from parent feature '' — Group " -- event: phase_started - timestamp: "" - phase: implement - details: "Parallel split — tasks: " -``` - -### 3B. Copy design.md - -Copy the parent feature's `design.md` to the worktree: - -```bash -cp ".afyapowers/features//artifacts/design.md" \ - "${WT}/.afyapowers/features/${SLUG}/artifacts/design.md" -``` - -### 3C. Generate subset plan.md +### 3A. Generate subset plan.md -Create a `plan.md` containing ONLY this group's tasks: +Create a `plan.md` in the worktree root containing ONLY this group's tasks: 1. Copy the plan header (Goal, Architecture, Tech Stack) 2. Include ONLY the `### Task N:` blocks assigned to this group -3. Renumber tasks sequentially (Task 1, Task 2, ...) for clarity -4. Update `**Depends on:**` references to use new task numbers +3. Preserve original task numbers (do NOT renumber — needed for merging checkboxes back) +4. Update `**Depends on:**` references: remove deps on tasks outside this group (they have no cross-group deps by definition) 5. Preserve all step details, file lists, and Figma metadata -Save to `${WT}/.afyapowers/features/${SLUG}/artifacts/plan.md` +Save to `${WT_PATH}/PLAN_SUBSET.md` -### 3D. Generate PROMPT.md with territory rules +### 3B. Copy design.md for context -Read `skills/parallel-split/territory-protocol.md` as template. +```bash +cp ".afyapowers/features//artifacts/design.md" "${WT_PATH}/DESIGN_CONTEXT.md" +``` + +### 3C. Generate PROMPT.md with territory rules -Replace placeholders: -- `{{WORKTREE_ID}}` → `wt` -- `{{OWNED_FILES}}` → list of ownedFiles + ownedDirs for this group -- `{{READ_ONLY_FILES}}` → list of readOnlyFiles -- `{{FORBIDDEN_DIRS}}` → list of forbiddenDirs -- `{{SHARED_FILES}}` → list with strategies -- `{{MERGE_ORDER}}` → merge order description +Read `skills/parallel-split/territory-protocol.md` as template. Replace placeholders with this group's territory data. -Write to `${WT}/PROMPT.md`: +Write to `${WT_PATH}/PROMPT.md`: ```markdown # Parallel Worktree wt — @@ -186,33 +118,33 @@ Write to `${WT}/PROMPT.md`: ## Context You are implementing a subset of the feature "" in a parallel worktree. -This worktree handles tasks: +This worktree handles tasks: Focus area: -## Active Feature - -Your afyapowers feature is ready at: -`.afyapowers/features//` +## Instructions -The design and plan artifacts are pre-populated. You are starting at the **implement** phase. +1. Read this file completely +2. Read `DESIGN_CONTEXT.md` for the full design spec +3. Read `PLAN_SUBSET.md` for your assigned tasks +4. Implement ALL tasks following TDD (test first → implement → refactor → commit) +5. For each completed task, mark its checkbox: `- [ ]` → `- [x]` in PLAN_SUBSET.md +6. **Respect territory rules below** — do NOT edit files outside your territory +7. After ALL tasks are complete: create `WORKTREE_COMPLETE.md` with a summary of what was done +8. Do NOT run /afyapowers:next — do NOT start review or complete phases -## Instructions +## IMPORTANT: Implement Only -1. Read PROMPT.md (this file) completely -2. Run the implement phase: the plan at `.afyapowers/features//artifacts/plan.md` has your tasks -3. Follow TDD and subagent-driven-development as usual -4. **Respect territory rules below** — do NOT edit files outside your territory -5. After implement: run `/afyapowers:next` to proceed to review -6. After review: run `/afyapowers:next` to proceed to complete -7. At complete phase: choose **"Keep as-is"** — do NOT merge or create PR -8. After completion, create `WORKTREE_COMPLETE.md` to signal you are done +This worktree handles ONLY the implement phase. Review and completion happen on +the parent branch after all worktrees merge back. When done, just create +WORKTREE_COMPLETE.md and stop. - + ``` -### 3E. Provision MCP servers (Claude Code only) +### 3D. Provision MCP servers (Claude Code only) ```bash +WT_ABS_PATH="$(cd "${WT_PATH}" && pwd)" cd "${WT_ABS_PATH}" claude mcp remove serena -s project 2>/dev/null claude mcp remove sequential-thinking -s project 2>/dev/null @@ -223,7 +155,7 @@ claude mcp add -s project sequential-thinking -- npx -y @modelcontextprotocol/se Copy settings if they exist: ```bash -[ -f ".claude/settings.local.json" ] && mkdir -p "${WT}/.claude" && cp ".claude/settings.local.json" "${WT}/.claude/" +[ -f ".claude/settings.local.json" ] && mkdir -p "${WT_PATH}/.claude" && cp ".claude/settings.local.json" "${WT_PATH}/.claude/" ``` --- @@ -242,7 +174,6 @@ Write `territory_map.json` in the parent project root: "id": "wt1", "path": "", "branch": "", - "featureSlug": "-wt1", "tasks": [1, 2, 5], "taskNames": ["Task 1: ...", "Task 2: ...", "Task 5: ..."], "ownedFiles": [], @@ -263,22 +194,20 @@ Write `territory_map.json` in the parent project root: In the parent project's `.afyapowers/features//`: -1. Update `state.yaml`: set implement phase to `in_progress`, add note about parallel split -2. Append to `history.yaml`: +Append to `history.yaml` under the `events:` key: ```yaml -- event: parallel_split - timestamp: "" - details: "Split into parallel worktrees: " - territory_map: "territory_map.json" + - timestamp: "" + event: parallel_split + phase: implement + details: "Split into parallel worktrees: " + command: parallel-split ``` --- ## Step 6: Launch Terminals -Detect available terminal multiplexer and launch: - ### 6A. Warp (default on macOS) Generate Warp Launch Configuration: @@ -296,14 +225,15 @@ windows: panes: - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" + - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" + - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" ``` -Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` +Where `` chains the `claude mcp remove` + `claude mcp add` commands from Step 3D. +Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` Open: `open "warp://launch/afyapowers%20Parallel"` ### 6B. tmux (fallback) @@ -311,7 +241,7 @@ Open: `open "warp://launch/afyapowers%20Parallel"` ```bash SESSION="afyapowers-parallel" tmux new-session -d -s "${SESSION}" -x 200 -y 50 -tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md...'" Enter +tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" Enter # Split + send-keys for each additional worktree tmux select-layout -t "${SESSION}" tiled tmux attach -t "${SESSION}" @@ -319,21 +249,14 @@ tmux attach -t "${SESSION}" ### 6C. Manual (no multiplexer) -Print commands for user to copy-paste: - -``` -Parallel split complete! Open one terminal per worktree: - - cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' - cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' -``` +Print commands for user to copy-paste. --- -## Step 7: Display Summary +## Step 7: Display Summary and Post-Merge Instructions ``` -Parallel Split Complete +Parallel Split — Implement Phase Feature: Worktrees: @@ -342,42 +265,36 @@ Territory map: territory_map.json wt1 (Tasks ): Owns: Branch: - + wt2 (Tasks ): Owns: Branch: Merge order: wt1 → wt2 → wt3 -Shared files: (all deferred) - -Agents launched in . - -After all worktrees complete: - 1. Merge in order: git merge for each worktree - 2. Consolidate _deferred/ files - 3. Run full test suite - 4. Continue with /afyapowers:next in parent feature (review phase) -``` +Shared files: (deferred) ---- +Agents launched. -## CLEANUP +After ALL worktrees create WORKTREE_COMPLETE.md: -After all worktrees complete and are merged: + 1. Merge in order: + git merge + git merge + ... -```bash -# Remove worktrees -git worktree list | grep "afyapowers.*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} + 2. Consolidate deferred files (if any in _deferred/) -# Clean up branches -git branch | grep "afyapowers.*wt" | xargs git branch -d + 3. Update plan.md checkboxes: + The merge brings in each worktree's PLAN_SUBSET.md changes. + Verify the parent plan.md has all tasks marked [x]. + If some checkboxes are still [ ], manually mark them based + on the worktree PLAN_SUBSET.md files. -# Remove territory map -rm territory_map.json + 4. Run /afyapowers:next to proceed to review (on the parent feature) -# Clean up deferred files -rm -rf _deferred/ - -# Remove launch config -rm ~/.warp/launch_configurations/afyapowers-parallel.yaml 2>/dev/null + 5. Clean up: + git worktree list | grep ".*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} + rm territory_map.json _deferred/ 2>/dev/null ``` + +**IMPORTANT:** After displaying the summary, the `implementing` skill will wait for the user to complete the merge steps and then resume at the "After SDD Completes" check (verifying all plan.md checkboxes are `[x]`). diff --git a/dist/cursor/skills/afyapowers-parallel-split/territory-protocol.md b/dist/cursor/skills/afyapowers-parallel-split/territory-protocol.md index c492077..b61d7dd 100644 --- a/dist/cursor/skills/afyapowers-parallel-split/territory-protocol.md +++ b/dist/cursor/skills/afyapowers-parallel-split/territory-protocol.md @@ -1,6 +1,6 @@ # Territory Protocol for Parallel Worktrees -You are working in a **parallel worktree** with territory-based file isolation. Other agents are simultaneously working on other task groups in separate worktrees. To prevent merge conflicts, you MUST respect the territory rules below. +You are working in a **parallel worktree** implementing a subset of tasks. Other agents are simultaneously working on other task groups in separate worktrees. To prevent merge conflicts, you MUST respect the territory rules below. --- @@ -40,27 +40,16 @@ If during implementation you realize you NEED to edit a file outside your territ 1. **Do NOT edit it** 2. Create `_deferred/{{WORKTREE_ID}}/territory-request.md` documenting what you need 3. Create a stub or workaround within your territory -4. Continue with implementation — the merge step will handle cross-territory needs -5. Note the territory limitation as a concern in your implementation +4. Continue with implementation --- -## MERGE ORDER +## SCOPE: IMPLEMENT ONLY -{{MERGE_ORDER}} +You are running ONLY the implement phase. Do NOT: +- Run `/afyapowers:next` +- Start review or complete phases +- Create review.md or completion.md +- Merge branches or create PRs -Your worktree will be merged in the order specified above. If you depend on code from a worktree that merges before you, it will be available after their merge completes. - ---- - -## WORKFLOW - -You are running the afyapowers 5-phase workflow for your assigned tasks: - -1. Your plan.md has been pre-populated with your assigned tasks only -2. Run the implement phase: follow TDD, use subagent-driven-development for wave execution -3. After implementation: proceed to review phase (`/afyapowers:next`) -4. After review: proceed to complete phase (`/afyapowers:next`) -5. At completion: choose "Keep as-is" — the parent orchestrator handles merge - -**IMPORTANT:** Always respect territory rules during ALL phases (implement, review, complete). +When all tasks are done, create `WORKTREE_COMPLETE.md` and stop. The parent branch handles review and completion after merge. diff --git a/dist/gemini/commands/next.md b/dist/gemini/commands/next.md index 6bb2148..4461f40 100644 --- a/dist/gemini/commands/next.md +++ b/dist/gemini/commands/next.md @@ -48,86 +48,15 @@ Determine the next phase from the ordered list: design → plan → implement ## Step 5: Invoke Next Phase Skill -Tell the user which phase is starting, then invoke the appropriate skill. - -**Special case: plan → implement transition** — Before invoking the implementing skill, run the Parallel Split Analysis (Step 5A). +Tell the user which phase is starting, then invoke the appropriate skill: | Next Phase | Skill to Invoke | What It Does | |-----------|----------------|--------------| | plan | **writing-plans** skill | Break design into implementation tasks | -| implement | **(see Step 5A first)** → **implementing** skill | Execute tasks with TDD + subagents | +| implement | **implementing** skill | Execute tasks with TDD + subagents | | review | **reviewing** skill | 2-step code review (spec compliance + quality) | | complete | **completing** skill | Merge/PR/cleanup, produce completion summary | -### Step 5A: Parallel Split Analysis (plan → implement ONLY) - -**This step runs ONLY when transitioning from plan to implement.** For all other transitions, skip to Step 5B. - -1. Read the plan from `.afyapowers/features//artifacts/plan.md` -2. Parse all tasks: extract task numbers, `**Depends on:**` lines, and `**Files:**` sections -3. Build the dependency graph -4. Find **disconnected components** — groups of tasks with NO dependencies between them - -**How to find disconnected components:** -- Start with each task as its own group -- If Task A depends on Task B, merge their groups -- If Task A and Task B share files (overlap), merge their groups -- After processing all deps and overlaps, count remaining distinct groups - -5. **If only 1 group exists** (all tasks are connected): skip to Step 5B — no split possible. - -6. **If 2+ disconnected groups exist**, analyze each group: - - List tasks in the group - - Describe the group by its primary domain (infer from file paths and task names) - - List key files/directories the group touches - -7. **Present the choice to the user:** - -``` -Your plan has independent task groups with no dependencies between them: - - Group A (Tasks 1, 2, 5): - Files: - - Group B (Tasks 3, 4): - Files: - - Group C (Tasks 6, 7): - Files: - -How would you like to execute? - - 1) Sequential (default) — one agent implements all tasks using wave execution - 2) Parallel worktrees — creates worktrees with territory-based file isolation, - each runs the full afyapowers workflow (implement → review → complete) -``` - -8. **If user chooses 1 (Sequential):** proceed to Step 5B normally. - -9. **If user chooses 2 (Parallel):** - - Invoke `parallel-split` skill with: - - `feature_slug`: the active feature slug - - `plan_content`: full plan.md content - - `design_content`: full design.md content (read from artifacts) - - `task_groups`: the disconnected groups with task assignments - - `all_tasks`: parsed tasks with deps, files, status - - The parallel-split skill handles worktree creation, territory mapping, and terminal launch - - After the skill completes, tell the user: - "Parallel worktrees created. Each worktree will run implement → review → complete independently. - After all worktrees finish, merge them in order and run `/afyapowers:next` to proceed with the parent feature's review." - - **STOP** — do not invoke the implementing skill (worktree agents handle it) - -### Step 5B: Normal Phase Invocation - -Invoke the skill for the next phase: - -| Next Phase | Skill to Invoke | -|-----------|----------------| -| plan | **writing-plans** | -| implement | **implementing** | -| review | **reviewing** | -| complete | **completing** | - When the skill completes and produces its artifact: 1. Save the artifact to `.afyapowers/features//artifacts/` 2. Update `state.yaml` to add the artifact to the current phase's artifacts list diff --git a/dist/gemini/skills/implementing/SKILL.md b/dist/gemini/skills/implementing/SKILL.md index 8c8b1db..a4fc93a 100644 --- a/dist/gemini/skills/implementing/SKILL.md +++ b/dist/gemini/skills/implementing/SKILL.md @@ -23,7 +23,57 @@ Orchestrate plan execution by delegating to subagent-driven-development. - If all tasks are already complete, tell the user and suggest `/afyapowers:next` - If uncompleted tasks remain, proceed to execution -## Required Sub-Skills +## Parallel Split Analysis + +Before dispatching tasks, check if the plan can be split into independent parallel groups. + +### Detect disconnected components + +1. Parse all tasks from the plan: extract task numbers, `**Depends on:**` lines, and `**Files:**` sections +2. Build the dependency graph +3. Find **disconnected components** — groups of tasks with NO dependencies between them: + - Start with each task as its own group + - If Task A depends on Task B, merge their groups + - If Task A and Task B share files (from `**Files:**` sections), merge their groups + - After processing all deps and overlaps, count remaining distinct groups + +4. **If only 1 group** (all tasks are connected): proceed directly to the SDD invocation below. + +5. **If 2+ disconnected groups exist**, analyze each group: + - List tasks in the group + - Describe the group by its primary domain (infer from file paths and task names) + - List key files/directories the group touches + +6. **Present the choice to the user:** + +``` +Your plan has independent task groups with no dependencies between them: + + Group A (Tasks 1, 2, 5): + Files: + + Group B (Tasks 3, 4): + Files: + +How would you like to execute? + + 1) Sequential (default) — one agent implements all tasks using wave execution + 2) Parallel worktrees — creates worktrees with territory-based file isolation, + each implements its task group, then merges back for unified review +``` + +7. **If user chooses 1 (Sequential):** proceed to the SDD invocation below. + +8. **If user chooses 2 (Parallel):** + - Invoke `parallel-split` skill with: feature slug, plan content, design content, task groups, parsed tasks + - The parallel-split skill creates worktrees, each running ONLY the implement phase for its task group + - **After all worktrees complete and merge back:** + - Re-read the parent plan.md — verify all checkboxes are `[x]` (worktree merges update the parent plan) + - If some remain unchecked, report them to the user + - **Resume the parent flow at "After SDD Completes" below** (the parent continues with review → complete) + - **STOP here** — do not invoke SDD (the worktrees handled implementation) + +## Invoke Sub-Skill **REQUIRED:** Invoke `afyapowers:subagent-driven-development` via the Skill tool to execute all plan tasks. diff --git a/dist/gemini/skills/parallel-split/SKILL.md b/dist/gemini/skills/parallel-split/SKILL.md index b5a97ab..a21a193 100644 --- a/dist/gemini/skills/parallel-split/SKILL.md +++ b/dist/gemini/skills/parallel-split/SKILL.md @@ -5,10 +5,12 @@ description: "Split independent task groups into parallel worktrees with territo # Parallel Split — Territory-Based Worktree Parallelization -Split a plan with independent task groups into N parallel git worktrees, each with its own territory (file ownership), plan subset, and afyapowers workflow. This enables multiple agents to implement different parts of a feature simultaneously without merge conflicts. +Split a plan with independent task groups into N parallel git worktrees. Each worktree implements its task group, then merges back so the parent feature continues with unified review and completion. **Invoked by:** `implementing` skill (when user chooses parallel execution) -**NOT a standalone command** — only triggered as a choice during the plan → implement transition. +**NOT a standalone command** — only triggered as a choice within the implementing phase. + +**Key constraint:** Worktrees run ONLY the implement phase. Review and complete happen on the parent branch after all worktrees merge back. This ensures review sees the consolidated diff and completion reflects the full feature. --- @@ -34,7 +36,6 @@ For each group, aggregate: - `willCreate`: all files in `Create:` lines of the group's tasks - `willModify`: all files in `Modify:` lines of the group's tasks - `willTest`: all files in `Test:` lines of the group's tasks -- `willImport`: files referenced in task descriptions but not in Files: section ### 1B. Assign territories @@ -54,8 +55,7 @@ For each group: Check that: 1. Every `willCreate`/`willModify` file has exactly one owner (no double-ownership) -2. No file is both `ownedFiles` in one group and `ownedFiles` in another -3. Shared files have assigned strategies +2. Shared files have assigned strategies If validation fails, adjust by: - Moving conflicting files to `deferred` strategy @@ -66,7 +66,7 @@ If validation fails, adjust by: Analyze cross-group dependencies: - If group B imports/uses files that group A creates → A merges before B -- If no cross-group dependencies → merge in any order (parallel merge) +- If no cross-group dependencies → merge in any order - Generate ordered list: `["wt1", "wt3", "wt2"]` --- @@ -88,97 +88,29 @@ git worktree add -b "${BRANCH_NAME}" "${WT_PATH}" HEAD ## Step 3: Prepare Each Worktree -For each worktree, do the following: - -### 3A. Create afyapowers feature state - -Create the feature directory structure in the worktree: - -```bash -WT="" -SLUG="-wt" - -mkdir -p "${WT}/.afyapowers/features/${SLUG}/artifacts" -echo "${SLUG}" > "${WT}/.afyapowers/features/active" -``` - -Write `state.yaml`: - -```yaml -feature: " (Group : )" -status: active -created_at: "" -current_phase: implement -phases: - design: - status: completed - started_at: "" - completed_at: "" - artifacts: [design.md] - plan: - status: completed - started_at: "" - completed_at: "" - artifacts: [plan.md] - implement: - status: in_progress - started_at: "" - completed_at: null - artifacts: [] - review: - status: pending - artifacts: [] - complete: - status: pending - artifacts: [] -``` - -Write `history.yaml` with initial events: - -```yaml -- event: feature_created - timestamp: "" - details: "Split from parent feature '' — Group " -- event: phase_started - timestamp: "" - phase: implement - details: "Parallel split — tasks: " -``` - -### 3B. Copy design.md - -Copy the parent feature's `design.md` to the worktree: - -```bash -cp ".afyapowers/features//artifacts/design.md" \ - "${WT}/.afyapowers/features/${SLUG}/artifacts/design.md" -``` - -### 3C. Generate subset plan.md +### 3A. Generate subset plan.md -Create a `plan.md` containing ONLY this group's tasks: +Create a `plan.md` in the worktree root containing ONLY this group's tasks: 1. Copy the plan header (Goal, Architecture, Tech Stack) 2. Include ONLY the `### Task N:` blocks assigned to this group -3. Renumber tasks sequentially (Task 1, Task 2, ...) for clarity -4. Update `**Depends on:**` references to use new task numbers +3. Preserve original task numbers (do NOT renumber — needed for merging checkboxes back) +4. Update `**Depends on:**` references: remove deps on tasks outside this group (they have no cross-group deps by definition) 5. Preserve all step details, file lists, and Figma metadata -Save to `${WT}/.afyapowers/features/${SLUG}/artifacts/plan.md` +Save to `${WT_PATH}/PLAN_SUBSET.md` -### 3D. Generate PROMPT.md with territory rules +### 3B. Copy design.md for context -Read `skills/parallel-split/territory-protocol.md` as template. +```bash +cp ".afyapowers/features//artifacts/design.md" "${WT_PATH}/DESIGN_CONTEXT.md" +``` + +### 3C. Generate PROMPT.md with territory rules -Replace placeholders: -- `{{WORKTREE_ID}}` → `wt` -- `{{OWNED_FILES}}` → list of ownedFiles + ownedDirs for this group -- `{{READ_ONLY_FILES}}` → list of readOnlyFiles -- `{{FORBIDDEN_DIRS}}` → list of forbiddenDirs -- `{{SHARED_FILES}}` → list with strategies -- `{{MERGE_ORDER}}` → merge order description +Read `skills/parallel-split/territory-protocol.md` as template. Replace placeholders with this group's territory data. -Write to `${WT}/PROMPT.md`: +Write to `${WT_PATH}/PROMPT.md`: ```markdown # Parallel Worktree wt — @@ -186,33 +118,33 @@ Write to `${WT}/PROMPT.md`: ## Context You are implementing a subset of the feature "" in a parallel worktree. -This worktree handles tasks: +This worktree handles tasks: Focus area: -## Active Feature - -Your afyapowers feature is ready at: -`.afyapowers/features//` +## Instructions -The design and plan artifacts are pre-populated. You are starting at the **implement** phase. +1. Read this file completely +2. Read `DESIGN_CONTEXT.md` for the full design spec +3. Read `PLAN_SUBSET.md` for your assigned tasks +4. Implement ALL tasks following TDD (test first → implement → refactor → commit) +5. For each completed task, mark its checkbox: `- [ ]` → `- [x]` in PLAN_SUBSET.md +6. **Respect territory rules below** — do NOT edit files outside your territory +7. After ALL tasks are complete: create `WORKTREE_COMPLETE.md` with a summary of what was done +8. Do NOT run /afyapowers:next — do NOT start review or complete phases -## Instructions +## IMPORTANT: Implement Only -1. Read PROMPT.md (this file) completely -2. Run the implement phase: the plan at `.afyapowers/features//artifacts/plan.md` has your tasks -3. Follow TDD and subagent-driven-development as usual -4. **Respect territory rules below** — do NOT edit files outside your territory -5. After implement: run `/afyapowers:next` to proceed to review -6. After review: run `/afyapowers:next` to proceed to complete -7. At complete phase: choose **"Keep as-is"** — do NOT merge or create PR -8. After completion, create `WORKTREE_COMPLETE.md` to signal you are done +This worktree handles ONLY the implement phase. Review and completion happen on +the parent branch after all worktrees merge back. When done, just create +WORKTREE_COMPLETE.md and stop. - + ``` -### 3E. Provision MCP servers (Claude Code only) +### 3D. Provision MCP servers (Claude Code only) ```bash +WT_ABS_PATH="$(cd "${WT_PATH}" && pwd)" cd "${WT_ABS_PATH}" claude mcp remove serena -s project 2>/dev/null claude mcp remove sequential-thinking -s project 2>/dev/null @@ -223,7 +155,7 @@ claude mcp add -s project sequential-thinking -- npx -y @modelcontextprotocol/se Copy settings if they exist: ```bash -[ -f ".claude/settings.local.json" ] && mkdir -p "${WT}/.claude" && cp ".claude/settings.local.json" "${WT}/.claude/" +[ -f ".claude/settings.local.json" ] && mkdir -p "${WT_PATH}/.claude" && cp ".claude/settings.local.json" "${WT_PATH}/.claude/" ``` --- @@ -242,7 +174,6 @@ Write `territory_map.json` in the parent project root: "id": "wt1", "path": "", "branch": "", - "featureSlug": "-wt1", "tasks": [1, 2, 5], "taskNames": ["Task 1: ...", "Task 2: ...", "Task 5: ..."], "ownedFiles": [], @@ -263,22 +194,20 @@ Write `territory_map.json` in the parent project root: In the parent project's `.afyapowers/features//`: -1. Update `state.yaml`: set implement phase to `in_progress`, add note about parallel split -2. Append to `history.yaml`: +Append to `history.yaml` under the `events:` key: ```yaml -- event: parallel_split - timestamp: "" - details: "Split into parallel worktrees: " - territory_map: "territory_map.json" + - timestamp: "" + event: parallel_split + phase: implement + details: "Split into parallel worktrees: " + command: parallel-split ``` --- ## Step 6: Launch Terminals -Detect available terminal multiplexer and launch: - ### 6A. Warp (default on macOS) Generate Warp Launch Configuration: @@ -296,14 +225,15 @@ windows: panes: - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" + - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" + - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" ``` -Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` +Where `` chains the `claude mcp remove` + `claude mcp add` commands from Step 3D. +Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` Open: `open "warp://launch/afyapowers%20Parallel"` ### 6B. tmux (fallback) @@ -311,7 +241,7 @@ Open: `open "warp://launch/afyapowers%20Parallel"` ```bash SESSION="afyapowers-parallel" tmux new-session -d -s "${SESSION}" -x 200 -y 50 -tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md...'" Enter +tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" Enter # Split + send-keys for each additional worktree tmux select-layout -t "${SESSION}" tiled tmux attach -t "${SESSION}" @@ -319,21 +249,14 @@ tmux attach -t "${SESSION}" ### 6C. Manual (no multiplexer) -Print commands for user to copy-paste: - -``` -Parallel split complete! Open one terminal per worktree: - - cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' - cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' -``` +Print commands for user to copy-paste. --- -## Step 7: Display Summary +## Step 7: Display Summary and Post-Merge Instructions ``` -Parallel Split Complete +Parallel Split — Implement Phase Feature: Worktrees: @@ -342,42 +265,36 @@ Territory map: territory_map.json wt1 (Tasks ): Owns: Branch: - + wt2 (Tasks ): Owns: Branch: Merge order: wt1 → wt2 → wt3 -Shared files: (all deferred) - -Agents launched in . - -After all worktrees complete: - 1. Merge in order: git merge for each worktree - 2. Consolidate _deferred/ files - 3. Run full test suite - 4. Continue with /afyapowers:next in parent feature (review phase) -``` +Shared files: (deferred) ---- +Agents launched. -## CLEANUP +After ALL worktrees create WORKTREE_COMPLETE.md: -After all worktrees complete and are merged: + 1. Merge in order: + git merge + git merge + ... -```bash -# Remove worktrees -git worktree list | grep "afyapowers.*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} + 2. Consolidate deferred files (if any in _deferred/) -# Clean up branches -git branch | grep "afyapowers.*wt" | xargs git branch -d + 3. Update plan.md checkboxes: + The merge brings in each worktree's PLAN_SUBSET.md changes. + Verify the parent plan.md has all tasks marked [x]. + If some checkboxes are still [ ], manually mark them based + on the worktree PLAN_SUBSET.md files. -# Remove territory map -rm territory_map.json + 4. Run /afyapowers:next to proceed to review (on the parent feature) -# Clean up deferred files -rm -rf _deferred/ - -# Remove launch config -rm ~/.warp/launch_configurations/afyapowers-parallel.yaml 2>/dev/null + 5. Clean up: + git worktree list | grep ".*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} + rm territory_map.json _deferred/ 2>/dev/null ``` + +**IMPORTANT:** After displaying the summary, the `implementing` skill will wait for the user to complete the merge steps and then resume at the "After SDD Completes" check (verifying all plan.md checkboxes are `[x]`). diff --git a/dist/gemini/skills/parallel-split/territory-protocol.md b/dist/gemini/skills/parallel-split/territory-protocol.md index c492077..b61d7dd 100644 --- a/dist/gemini/skills/parallel-split/territory-protocol.md +++ b/dist/gemini/skills/parallel-split/territory-protocol.md @@ -1,6 +1,6 @@ # Territory Protocol for Parallel Worktrees -You are working in a **parallel worktree** with territory-based file isolation. Other agents are simultaneously working on other task groups in separate worktrees. To prevent merge conflicts, you MUST respect the territory rules below. +You are working in a **parallel worktree** implementing a subset of tasks. Other agents are simultaneously working on other task groups in separate worktrees. To prevent merge conflicts, you MUST respect the territory rules below. --- @@ -40,27 +40,16 @@ If during implementation you realize you NEED to edit a file outside your territ 1. **Do NOT edit it** 2. Create `_deferred/{{WORKTREE_ID}}/territory-request.md` documenting what you need 3. Create a stub or workaround within your territory -4. Continue with implementation — the merge step will handle cross-territory needs -5. Note the territory limitation as a concern in your implementation +4. Continue with implementation --- -## MERGE ORDER +## SCOPE: IMPLEMENT ONLY -{{MERGE_ORDER}} +You are running ONLY the implement phase. Do NOT: +- Run `/afyapowers:next` +- Start review or complete phases +- Create review.md or completion.md +- Merge branches or create PRs -Your worktree will be merged in the order specified above. If you depend on code from a worktree that merges before you, it will be available after their merge completes. - ---- - -## WORKFLOW - -You are running the afyapowers 5-phase workflow for your assigned tasks: - -1. Your plan.md has been pre-populated with your assigned tasks only -2. Run the implement phase: follow TDD, use subagent-driven-development for wave execution -3. After implementation: proceed to review phase (`/afyapowers:next`) -4. After review: proceed to complete phase (`/afyapowers:next`) -5. At completion: choose "Keep as-is" — the parent orchestrator handles merge - -**IMPORTANT:** Always respect territory rules during ALL phases (implement, review, complete). +When all tasks are done, create `WORKTREE_COMPLETE.md` and stop. The parent branch handles review and completion after merge. diff --git a/dist/github-copilot/commands/next.md b/dist/github-copilot/commands/next.md index 9b1dd80..5faf2d8 100644 --- a/dist/github-copilot/commands/next.md +++ b/dist/github-copilot/commands/next.md @@ -52,86 +52,15 @@ Determine the next phase from the ordered list: design → plan → implement ## Step 5: Invoke Next Phase Skill -Tell the user which phase is starting, then invoke the appropriate skill. - -**Special case: plan → implement transition** — Before invoking the implementing skill, run the Parallel Split Analysis (Step 5A). +Tell the user which phase is starting, then invoke the appropriate skill: | Next Phase | Skill to Invoke | What It Does | |-----------|----------------|--------------| | plan | **writing-plans** skill | Break design into implementation tasks | -| implement | **(see Step 5A first)** → **implementing** skill | Execute tasks with TDD + subagents | +| implement | **implementing** skill | Execute tasks with TDD + subagents | | review | **reviewing** skill | 2-step code review (spec compliance + quality) | | complete | **completing** skill | Merge/PR/cleanup, produce completion summary | -### Step 5A: Parallel Split Analysis (plan → implement ONLY) - -**This step runs ONLY when transitioning from plan to implement.** For all other transitions, skip to Step 5B. - -1. Read the plan from `.afyapowers/features//artifacts/plan.md` -2. Parse all tasks: extract task numbers, `**Depends on:**` lines, and `**Files:**` sections -3. Build the dependency graph -4. Find **disconnected components** — groups of tasks with NO dependencies between them - -**How to find disconnected components:** -- Start with each task as its own group -- If Task A depends on Task B, merge their groups -- If Task A and Task B share files (overlap), merge their groups -- After processing all deps and overlaps, count remaining distinct groups - -5. **If only 1 group exists** (all tasks are connected): skip to Step 5B — no split possible. - -6. **If 2+ disconnected groups exist**, analyze each group: - - List tasks in the group - - Describe the group by its primary domain (infer from file paths and task names) - - List key files/directories the group touches - -7. **Present the choice to the user:** - -``` -Your plan has independent task groups with no dependencies between them: - - Group A (Tasks 1, 2, 5): - Files: - - Group B (Tasks 3, 4): - Files: - - Group C (Tasks 6, 7): - Files: - -How would you like to execute? - - 1) Sequential (default) — one agent implements all tasks using wave execution - 2) Parallel worktrees — creates worktrees with territory-based file isolation, - each runs the full afyapowers workflow (implement → review → complete) -``` - -8. **If user chooses 1 (Sequential):** proceed to Step 5B normally. - -9. **If user chooses 2 (Parallel):** - - Invoke `parallel-split` skill with: - - `feature_slug`: the active feature slug - - `plan_content`: full plan.md content - - `design_content`: full design.md content (read from artifacts) - - `task_groups`: the disconnected groups with task assignments - - `all_tasks`: parsed tasks with deps, files, status - - The parallel-split skill handles worktree creation, territory mapping, and terminal launch - - After the skill completes, tell the user: - "Parallel worktrees created. Each worktree will run implement → review → complete independently. - After all worktrees finish, merge them in order and run `/afyapowers:next` to proceed with the parent feature's review." - - **STOP** — do not invoke the implementing skill (worktree agents handle it) - -### Step 5B: Normal Phase Invocation - -Invoke the skill for the next phase: - -| Next Phase | Skill to Invoke | -|-----------|----------------| -| plan | **writing-plans** | -| implement | **implementing** | -| review | **reviewing** | -| complete | **completing** | - When the skill completes and produces its artifact: 1. Save the artifact to `.afyapowers/features//artifacts/` 2. Update `state.yaml` to add the artifact to the current phase's artifacts list diff --git a/dist/github-copilot/skills/implementing/SKILL.md b/dist/github-copilot/skills/implementing/SKILL.md index 8c8b1db..a4fc93a 100644 --- a/dist/github-copilot/skills/implementing/SKILL.md +++ b/dist/github-copilot/skills/implementing/SKILL.md @@ -23,7 +23,57 @@ Orchestrate plan execution by delegating to subagent-driven-development. - If all tasks are already complete, tell the user and suggest `/afyapowers:next` - If uncompleted tasks remain, proceed to execution -## Required Sub-Skills +## Parallel Split Analysis + +Before dispatching tasks, check if the plan can be split into independent parallel groups. + +### Detect disconnected components + +1. Parse all tasks from the plan: extract task numbers, `**Depends on:**` lines, and `**Files:**` sections +2. Build the dependency graph +3. Find **disconnected components** — groups of tasks with NO dependencies between them: + - Start with each task as its own group + - If Task A depends on Task B, merge their groups + - If Task A and Task B share files (from `**Files:**` sections), merge their groups + - After processing all deps and overlaps, count remaining distinct groups + +4. **If only 1 group** (all tasks are connected): proceed directly to the SDD invocation below. + +5. **If 2+ disconnected groups exist**, analyze each group: + - List tasks in the group + - Describe the group by its primary domain (infer from file paths and task names) + - List key files/directories the group touches + +6. **Present the choice to the user:** + +``` +Your plan has independent task groups with no dependencies between them: + + Group A (Tasks 1, 2, 5): + Files: + + Group B (Tasks 3, 4): + Files: + +How would you like to execute? + + 1) Sequential (default) — one agent implements all tasks using wave execution + 2) Parallel worktrees — creates worktrees with territory-based file isolation, + each implements its task group, then merges back for unified review +``` + +7. **If user chooses 1 (Sequential):** proceed to the SDD invocation below. + +8. **If user chooses 2 (Parallel):** + - Invoke `parallel-split` skill with: feature slug, plan content, design content, task groups, parsed tasks + - The parallel-split skill creates worktrees, each running ONLY the implement phase for its task group + - **After all worktrees complete and merge back:** + - Re-read the parent plan.md — verify all checkboxes are `[x]` (worktree merges update the parent plan) + - If some remain unchecked, report them to the user + - **Resume the parent flow at "After SDD Completes" below** (the parent continues with review → complete) + - **STOP here** — do not invoke SDD (the worktrees handled implementation) + +## Invoke Sub-Skill **REQUIRED:** Invoke `afyapowers:subagent-driven-development` via the Skill tool to execute all plan tasks. diff --git a/dist/github-copilot/skills/parallel-split/SKILL.md b/dist/github-copilot/skills/parallel-split/SKILL.md index b5a97ab..a21a193 100644 --- a/dist/github-copilot/skills/parallel-split/SKILL.md +++ b/dist/github-copilot/skills/parallel-split/SKILL.md @@ -5,10 +5,12 @@ description: "Split independent task groups into parallel worktrees with territo # Parallel Split — Territory-Based Worktree Parallelization -Split a plan with independent task groups into N parallel git worktrees, each with its own territory (file ownership), plan subset, and afyapowers workflow. This enables multiple agents to implement different parts of a feature simultaneously without merge conflicts. +Split a plan with independent task groups into N parallel git worktrees. Each worktree implements its task group, then merges back so the parent feature continues with unified review and completion. **Invoked by:** `implementing` skill (when user chooses parallel execution) -**NOT a standalone command** — only triggered as a choice during the plan → implement transition. +**NOT a standalone command** — only triggered as a choice within the implementing phase. + +**Key constraint:** Worktrees run ONLY the implement phase. Review and complete happen on the parent branch after all worktrees merge back. This ensures review sees the consolidated diff and completion reflects the full feature. --- @@ -34,7 +36,6 @@ For each group, aggregate: - `willCreate`: all files in `Create:` lines of the group's tasks - `willModify`: all files in `Modify:` lines of the group's tasks - `willTest`: all files in `Test:` lines of the group's tasks -- `willImport`: files referenced in task descriptions but not in Files: section ### 1B. Assign territories @@ -54,8 +55,7 @@ For each group: Check that: 1. Every `willCreate`/`willModify` file has exactly one owner (no double-ownership) -2. No file is both `ownedFiles` in one group and `ownedFiles` in another -3. Shared files have assigned strategies +2. Shared files have assigned strategies If validation fails, adjust by: - Moving conflicting files to `deferred` strategy @@ -66,7 +66,7 @@ If validation fails, adjust by: Analyze cross-group dependencies: - If group B imports/uses files that group A creates → A merges before B -- If no cross-group dependencies → merge in any order (parallel merge) +- If no cross-group dependencies → merge in any order - Generate ordered list: `["wt1", "wt3", "wt2"]` --- @@ -88,97 +88,29 @@ git worktree add -b "${BRANCH_NAME}" "${WT_PATH}" HEAD ## Step 3: Prepare Each Worktree -For each worktree, do the following: - -### 3A. Create afyapowers feature state - -Create the feature directory structure in the worktree: - -```bash -WT="" -SLUG="-wt" - -mkdir -p "${WT}/.afyapowers/features/${SLUG}/artifacts" -echo "${SLUG}" > "${WT}/.afyapowers/features/active" -``` - -Write `state.yaml`: - -```yaml -feature: " (Group : )" -status: active -created_at: "" -current_phase: implement -phases: - design: - status: completed - started_at: "" - completed_at: "" - artifacts: [design.md] - plan: - status: completed - started_at: "" - completed_at: "" - artifacts: [plan.md] - implement: - status: in_progress - started_at: "" - completed_at: null - artifacts: [] - review: - status: pending - artifacts: [] - complete: - status: pending - artifacts: [] -``` - -Write `history.yaml` with initial events: - -```yaml -- event: feature_created - timestamp: "" - details: "Split from parent feature '' — Group " -- event: phase_started - timestamp: "" - phase: implement - details: "Parallel split — tasks: " -``` - -### 3B. Copy design.md - -Copy the parent feature's `design.md` to the worktree: - -```bash -cp ".afyapowers/features//artifacts/design.md" \ - "${WT}/.afyapowers/features/${SLUG}/artifacts/design.md" -``` - -### 3C. Generate subset plan.md +### 3A. Generate subset plan.md -Create a `plan.md` containing ONLY this group's tasks: +Create a `plan.md` in the worktree root containing ONLY this group's tasks: 1. Copy the plan header (Goal, Architecture, Tech Stack) 2. Include ONLY the `### Task N:` blocks assigned to this group -3. Renumber tasks sequentially (Task 1, Task 2, ...) for clarity -4. Update `**Depends on:**` references to use new task numbers +3. Preserve original task numbers (do NOT renumber — needed for merging checkboxes back) +4. Update `**Depends on:**` references: remove deps on tasks outside this group (they have no cross-group deps by definition) 5. Preserve all step details, file lists, and Figma metadata -Save to `${WT}/.afyapowers/features/${SLUG}/artifacts/plan.md` +Save to `${WT_PATH}/PLAN_SUBSET.md` -### 3D. Generate PROMPT.md with territory rules +### 3B. Copy design.md for context -Read `skills/parallel-split/territory-protocol.md` as template. +```bash +cp ".afyapowers/features//artifacts/design.md" "${WT_PATH}/DESIGN_CONTEXT.md" +``` + +### 3C. Generate PROMPT.md with territory rules -Replace placeholders: -- `{{WORKTREE_ID}}` → `wt` -- `{{OWNED_FILES}}` → list of ownedFiles + ownedDirs for this group -- `{{READ_ONLY_FILES}}` → list of readOnlyFiles -- `{{FORBIDDEN_DIRS}}` → list of forbiddenDirs -- `{{SHARED_FILES}}` → list with strategies -- `{{MERGE_ORDER}}` → merge order description +Read `skills/parallel-split/territory-protocol.md` as template. Replace placeholders with this group's territory data. -Write to `${WT}/PROMPT.md`: +Write to `${WT_PATH}/PROMPT.md`: ```markdown # Parallel Worktree wt — @@ -186,33 +118,33 @@ Write to `${WT}/PROMPT.md`: ## Context You are implementing a subset of the feature "" in a parallel worktree. -This worktree handles tasks: +This worktree handles tasks: Focus area: -## Active Feature - -Your afyapowers feature is ready at: -`.afyapowers/features//` +## Instructions -The design and plan artifacts are pre-populated. You are starting at the **implement** phase. +1. Read this file completely +2. Read `DESIGN_CONTEXT.md` for the full design spec +3. Read `PLAN_SUBSET.md` for your assigned tasks +4. Implement ALL tasks following TDD (test first → implement → refactor → commit) +5. For each completed task, mark its checkbox: `- [ ]` → `- [x]` in PLAN_SUBSET.md +6. **Respect territory rules below** — do NOT edit files outside your territory +7. After ALL tasks are complete: create `WORKTREE_COMPLETE.md` with a summary of what was done +8. Do NOT run /afyapowers:next — do NOT start review or complete phases -## Instructions +## IMPORTANT: Implement Only -1. Read PROMPT.md (this file) completely -2. Run the implement phase: the plan at `.afyapowers/features//artifacts/plan.md` has your tasks -3. Follow TDD and subagent-driven-development as usual -4. **Respect territory rules below** — do NOT edit files outside your territory -5. After implement: run `/afyapowers:next` to proceed to review -6. After review: run `/afyapowers:next` to proceed to complete -7. At complete phase: choose **"Keep as-is"** — do NOT merge or create PR -8. After completion, create `WORKTREE_COMPLETE.md` to signal you are done +This worktree handles ONLY the implement phase. Review and completion happen on +the parent branch after all worktrees merge back. When done, just create +WORKTREE_COMPLETE.md and stop. - + ``` -### 3E. Provision MCP servers (Claude Code only) +### 3D. Provision MCP servers (Claude Code only) ```bash +WT_ABS_PATH="$(cd "${WT_PATH}" && pwd)" cd "${WT_ABS_PATH}" claude mcp remove serena -s project 2>/dev/null claude mcp remove sequential-thinking -s project 2>/dev/null @@ -223,7 +155,7 @@ claude mcp add -s project sequential-thinking -- npx -y @modelcontextprotocol/se Copy settings if they exist: ```bash -[ -f ".claude/settings.local.json" ] && mkdir -p "${WT}/.claude" && cp ".claude/settings.local.json" "${WT}/.claude/" +[ -f ".claude/settings.local.json" ] && mkdir -p "${WT_PATH}/.claude" && cp ".claude/settings.local.json" "${WT_PATH}/.claude/" ``` --- @@ -242,7 +174,6 @@ Write `territory_map.json` in the parent project root: "id": "wt1", "path": "", "branch": "", - "featureSlug": "-wt1", "tasks": [1, 2, 5], "taskNames": ["Task 1: ...", "Task 2: ...", "Task 5: ..."], "ownedFiles": [], @@ -263,22 +194,20 @@ Write `territory_map.json` in the parent project root: In the parent project's `.afyapowers/features//`: -1. Update `state.yaml`: set implement phase to `in_progress`, add note about parallel split -2. Append to `history.yaml`: +Append to `history.yaml` under the `events:` key: ```yaml -- event: parallel_split - timestamp: "" - details: "Split into parallel worktrees: " - territory_map: "territory_map.json" + - timestamp: "" + event: parallel_split + phase: implement + details: "Split into parallel worktrees: " + command: parallel-split ``` --- ## Step 6: Launch Terminals -Detect available terminal multiplexer and launch: - ### 6A. Warp (default on macOS) Generate Warp Launch Configuration: @@ -296,14 +225,15 @@ windows: panes: - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" + - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" + - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" ``` -Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` +Where `` chains the `claude mcp remove` + `claude mcp add` commands from Step 3D. +Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` Open: `open "warp://launch/afyapowers%20Parallel"` ### 6B. tmux (fallback) @@ -311,7 +241,7 @@ Open: `open "warp://launch/afyapowers%20Parallel"` ```bash SESSION="afyapowers-parallel" tmux new-session -d -s "${SESSION}" -x 200 -y 50 -tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md...'" Enter +tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" Enter # Split + send-keys for each additional worktree tmux select-layout -t "${SESSION}" tiled tmux attach -t "${SESSION}" @@ -319,21 +249,14 @@ tmux attach -t "${SESSION}" ### 6C. Manual (no multiplexer) -Print commands for user to copy-paste: - -``` -Parallel split complete! Open one terminal per worktree: - - cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' - cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' -``` +Print commands for user to copy-paste. --- -## Step 7: Display Summary +## Step 7: Display Summary and Post-Merge Instructions ``` -Parallel Split Complete +Parallel Split — Implement Phase Feature: Worktrees: @@ -342,42 +265,36 @@ Territory map: territory_map.json wt1 (Tasks ): Owns: Branch: - + wt2 (Tasks ): Owns: Branch: Merge order: wt1 → wt2 → wt3 -Shared files: (all deferred) - -Agents launched in . - -After all worktrees complete: - 1. Merge in order: git merge for each worktree - 2. Consolidate _deferred/ files - 3. Run full test suite - 4. Continue with /afyapowers:next in parent feature (review phase) -``` +Shared files: (deferred) ---- +Agents launched. -## CLEANUP +After ALL worktrees create WORKTREE_COMPLETE.md: -After all worktrees complete and are merged: + 1. Merge in order: + git merge + git merge + ... -```bash -# Remove worktrees -git worktree list | grep "afyapowers.*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} + 2. Consolidate deferred files (if any in _deferred/) -# Clean up branches -git branch | grep "afyapowers.*wt" | xargs git branch -d + 3. Update plan.md checkboxes: + The merge brings in each worktree's PLAN_SUBSET.md changes. + Verify the parent plan.md has all tasks marked [x]. + If some checkboxes are still [ ], manually mark them based + on the worktree PLAN_SUBSET.md files. -# Remove territory map -rm territory_map.json + 4. Run /afyapowers:next to proceed to review (on the parent feature) -# Clean up deferred files -rm -rf _deferred/ - -# Remove launch config -rm ~/.warp/launch_configurations/afyapowers-parallel.yaml 2>/dev/null + 5. Clean up: + git worktree list | grep ".*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} + rm territory_map.json _deferred/ 2>/dev/null ``` + +**IMPORTANT:** After displaying the summary, the `implementing` skill will wait for the user to complete the merge steps and then resume at the "After SDD Completes" check (verifying all plan.md checkboxes are `[x]`). diff --git a/dist/github-copilot/skills/parallel-split/territory-protocol.md b/dist/github-copilot/skills/parallel-split/territory-protocol.md index c492077..b61d7dd 100644 --- a/dist/github-copilot/skills/parallel-split/territory-protocol.md +++ b/dist/github-copilot/skills/parallel-split/territory-protocol.md @@ -1,6 +1,6 @@ # Territory Protocol for Parallel Worktrees -You are working in a **parallel worktree** with territory-based file isolation. Other agents are simultaneously working on other task groups in separate worktrees. To prevent merge conflicts, you MUST respect the territory rules below. +You are working in a **parallel worktree** implementing a subset of tasks. Other agents are simultaneously working on other task groups in separate worktrees. To prevent merge conflicts, you MUST respect the territory rules below. --- @@ -40,27 +40,16 @@ If during implementation you realize you NEED to edit a file outside your territ 1. **Do NOT edit it** 2. Create `_deferred/{{WORKTREE_ID}}/territory-request.md` documenting what you need 3. Create a stub or workaround within your territory -4. Continue with implementation — the merge step will handle cross-territory needs -5. Note the territory limitation as a concern in your implementation +4. Continue with implementation --- -## MERGE ORDER +## SCOPE: IMPLEMENT ONLY -{{MERGE_ORDER}} +You are running ONLY the implement phase. Do NOT: +- Run `/afyapowers:next` +- Start review or complete phases +- Create review.md or completion.md +- Merge branches or create PRs -Your worktree will be merged in the order specified above. If you depend on code from a worktree that merges before you, it will be available after their merge completes. - ---- - -## WORKFLOW - -You are running the afyapowers 5-phase workflow for your assigned tasks: - -1. Your plan.md has been pre-populated with your assigned tasks only -2. Run the implement phase: follow TDD, use subagent-driven-development for wave execution -3. After implementation: proceed to review phase (`/afyapowers:next`) -4. After review: proceed to complete phase (`/afyapowers:next`) -5. At completion: choose "Keep as-is" — the parent orchestrator handles merge - -**IMPORTANT:** Always respect territory rules during ALL phases (implement, review, complete). +When all tasks are done, create `WORKTREE_COMPLETE.md` and stop. The parent branch handles review and completion after merge. diff --git a/src/commands/next.md b/src/commands/next.md index 6bb2148..4461f40 100644 --- a/src/commands/next.md +++ b/src/commands/next.md @@ -48,86 +48,15 @@ Determine the next phase from the ordered list: design → plan → implement ## Step 5: Invoke Next Phase Skill -Tell the user which phase is starting, then invoke the appropriate skill. - -**Special case: plan → implement transition** — Before invoking the implementing skill, run the Parallel Split Analysis (Step 5A). +Tell the user which phase is starting, then invoke the appropriate skill: | Next Phase | Skill to Invoke | What It Does | |-----------|----------------|--------------| | plan | **writing-plans** skill | Break design into implementation tasks | -| implement | **(see Step 5A first)** → **implementing** skill | Execute tasks with TDD + subagents | +| implement | **implementing** skill | Execute tasks with TDD + subagents | | review | **reviewing** skill | 2-step code review (spec compliance + quality) | | complete | **completing** skill | Merge/PR/cleanup, produce completion summary | -### Step 5A: Parallel Split Analysis (plan → implement ONLY) - -**This step runs ONLY when transitioning from plan to implement.** For all other transitions, skip to Step 5B. - -1. Read the plan from `.afyapowers/features//artifacts/plan.md` -2. Parse all tasks: extract task numbers, `**Depends on:**` lines, and `**Files:**` sections -3. Build the dependency graph -4. Find **disconnected components** — groups of tasks with NO dependencies between them - -**How to find disconnected components:** -- Start with each task as its own group -- If Task A depends on Task B, merge their groups -- If Task A and Task B share files (overlap), merge their groups -- After processing all deps and overlaps, count remaining distinct groups - -5. **If only 1 group exists** (all tasks are connected): skip to Step 5B — no split possible. - -6. **If 2+ disconnected groups exist**, analyze each group: - - List tasks in the group - - Describe the group by its primary domain (infer from file paths and task names) - - List key files/directories the group touches - -7. **Present the choice to the user:** - -``` -Your plan has independent task groups with no dependencies between them: - - Group A (Tasks 1, 2, 5): - Files: - - Group B (Tasks 3, 4): - Files: - - Group C (Tasks 6, 7): - Files: - -How would you like to execute? - - 1) Sequential (default) — one agent implements all tasks using wave execution - 2) Parallel worktrees — creates worktrees with territory-based file isolation, - each runs the full afyapowers workflow (implement → review → complete) -``` - -8. **If user chooses 1 (Sequential):** proceed to Step 5B normally. - -9. **If user chooses 2 (Parallel):** - - Invoke `parallel-split` skill with: - - `feature_slug`: the active feature slug - - `plan_content`: full plan.md content - - `design_content`: full design.md content (read from artifacts) - - `task_groups`: the disconnected groups with task assignments - - `all_tasks`: parsed tasks with deps, files, status - - The parallel-split skill handles worktree creation, territory mapping, and terminal launch - - After the skill completes, tell the user: - "Parallel worktrees created. Each worktree will run implement → review → complete independently. - After all worktrees finish, merge them in order and run `/afyapowers:next` to proceed with the parent feature's review." - - **STOP** — do not invoke the implementing skill (worktree agents handle it) - -### Step 5B: Normal Phase Invocation - -Invoke the skill for the next phase: - -| Next Phase | Skill to Invoke | -|-----------|----------------| -| plan | **writing-plans** | -| implement | **implementing** | -| review | **reviewing** | -| complete | **completing** | - When the skill completes and produces its artifact: 1. Save the artifact to `.afyapowers/features//artifacts/` 2. Update `state.yaml` to add the artifact to the current phase's artifacts list diff --git a/src/skills/implementing/SKILL.md b/src/skills/implementing/SKILL.md index 8c8b1db..a4fc93a 100644 --- a/src/skills/implementing/SKILL.md +++ b/src/skills/implementing/SKILL.md @@ -23,7 +23,57 @@ Orchestrate plan execution by delegating to subagent-driven-development. - If all tasks are already complete, tell the user and suggest `/afyapowers:next` - If uncompleted tasks remain, proceed to execution -## Required Sub-Skills +## Parallel Split Analysis + +Before dispatching tasks, check if the plan can be split into independent parallel groups. + +### Detect disconnected components + +1. Parse all tasks from the plan: extract task numbers, `**Depends on:**` lines, and `**Files:**` sections +2. Build the dependency graph +3. Find **disconnected components** — groups of tasks with NO dependencies between them: + - Start with each task as its own group + - If Task A depends on Task B, merge their groups + - If Task A and Task B share files (from `**Files:**` sections), merge their groups + - After processing all deps and overlaps, count remaining distinct groups + +4. **If only 1 group** (all tasks are connected): proceed directly to the SDD invocation below. + +5. **If 2+ disconnected groups exist**, analyze each group: + - List tasks in the group + - Describe the group by its primary domain (infer from file paths and task names) + - List key files/directories the group touches + +6. **Present the choice to the user:** + +``` +Your plan has independent task groups with no dependencies between them: + + Group A (Tasks 1, 2, 5): + Files: + + Group B (Tasks 3, 4): + Files: + +How would you like to execute? + + 1) Sequential (default) — one agent implements all tasks using wave execution + 2) Parallel worktrees — creates worktrees with territory-based file isolation, + each implements its task group, then merges back for unified review +``` + +7. **If user chooses 1 (Sequential):** proceed to the SDD invocation below. + +8. **If user chooses 2 (Parallel):** + - Invoke `parallel-split` skill with: feature slug, plan content, design content, task groups, parsed tasks + - The parallel-split skill creates worktrees, each running ONLY the implement phase for its task group + - **After all worktrees complete and merge back:** + - Re-read the parent plan.md — verify all checkboxes are `[x]` (worktree merges update the parent plan) + - If some remain unchecked, report them to the user + - **Resume the parent flow at "After SDD Completes" below** (the parent continues with review → complete) + - **STOP here** — do not invoke SDD (the worktrees handled implementation) + +## Invoke Sub-Skill **REQUIRED:** Invoke `afyapowers:subagent-driven-development` via the Skill tool to execute all plan tasks. diff --git a/src/skills/parallel-split/SKILL.md b/src/skills/parallel-split/SKILL.md index b5a97ab..a21a193 100644 --- a/src/skills/parallel-split/SKILL.md +++ b/src/skills/parallel-split/SKILL.md @@ -5,10 +5,12 @@ description: "Split independent task groups into parallel worktrees with territo # Parallel Split — Territory-Based Worktree Parallelization -Split a plan with independent task groups into N parallel git worktrees, each with its own territory (file ownership), plan subset, and afyapowers workflow. This enables multiple agents to implement different parts of a feature simultaneously without merge conflicts. +Split a plan with independent task groups into N parallel git worktrees. Each worktree implements its task group, then merges back so the parent feature continues with unified review and completion. **Invoked by:** `implementing` skill (when user chooses parallel execution) -**NOT a standalone command** — only triggered as a choice during the plan → implement transition. +**NOT a standalone command** — only triggered as a choice within the implementing phase. + +**Key constraint:** Worktrees run ONLY the implement phase. Review and complete happen on the parent branch after all worktrees merge back. This ensures review sees the consolidated diff and completion reflects the full feature. --- @@ -34,7 +36,6 @@ For each group, aggregate: - `willCreate`: all files in `Create:` lines of the group's tasks - `willModify`: all files in `Modify:` lines of the group's tasks - `willTest`: all files in `Test:` lines of the group's tasks -- `willImport`: files referenced in task descriptions but not in Files: section ### 1B. Assign territories @@ -54,8 +55,7 @@ For each group: Check that: 1. Every `willCreate`/`willModify` file has exactly one owner (no double-ownership) -2. No file is both `ownedFiles` in one group and `ownedFiles` in another -3. Shared files have assigned strategies +2. Shared files have assigned strategies If validation fails, adjust by: - Moving conflicting files to `deferred` strategy @@ -66,7 +66,7 @@ If validation fails, adjust by: Analyze cross-group dependencies: - If group B imports/uses files that group A creates → A merges before B -- If no cross-group dependencies → merge in any order (parallel merge) +- If no cross-group dependencies → merge in any order - Generate ordered list: `["wt1", "wt3", "wt2"]` --- @@ -88,97 +88,29 @@ git worktree add -b "${BRANCH_NAME}" "${WT_PATH}" HEAD ## Step 3: Prepare Each Worktree -For each worktree, do the following: - -### 3A. Create afyapowers feature state - -Create the feature directory structure in the worktree: - -```bash -WT="" -SLUG="-wt" - -mkdir -p "${WT}/.afyapowers/features/${SLUG}/artifacts" -echo "${SLUG}" > "${WT}/.afyapowers/features/active" -``` - -Write `state.yaml`: - -```yaml -feature: " (Group : )" -status: active -created_at: "" -current_phase: implement -phases: - design: - status: completed - started_at: "" - completed_at: "" - artifacts: [design.md] - plan: - status: completed - started_at: "" - completed_at: "" - artifacts: [plan.md] - implement: - status: in_progress - started_at: "" - completed_at: null - artifacts: [] - review: - status: pending - artifacts: [] - complete: - status: pending - artifacts: [] -``` - -Write `history.yaml` with initial events: - -```yaml -- event: feature_created - timestamp: "" - details: "Split from parent feature '' — Group " -- event: phase_started - timestamp: "" - phase: implement - details: "Parallel split — tasks: " -``` - -### 3B. Copy design.md - -Copy the parent feature's `design.md` to the worktree: - -```bash -cp ".afyapowers/features//artifacts/design.md" \ - "${WT}/.afyapowers/features/${SLUG}/artifacts/design.md" -``` - -### 3C. Generate subset plan.md +### 3A. Generate subset plan.md -Create a `plan.md` containing ONLY this group's tasks: +Create a `plan.md` in the worktree root containing ONLY this group's tasks: 1. Copy the plan header (Goal, Architecture, Tech Stack) 2. Include ONLY the `### Task N:` blocks assigned to this group -3. Renumber tasks sequentially (Task 1, Task 2, ...) for clarity -4. Update `**Depends on:**` references to use new task numbers +3. Preserve original task numbers (do NOT renumber — needed for merging checkboxes back) +4. Update `**Depends on:**` references: remove deps on tasks outside this group (they have no cross-group deps by definition) 5. Preserve all step details, file lists, and Figma metadata -Save to `${WT}/.afyapowers/features/${SLUG}/artifacts/plan.md` +Save to `${WT_PATH}/PLAN_SUBSET.md` -### 3D. Generate PROMPT.md with territory rules +### 3B. Copy design.md for context -Read `skills/parallel-split/territory-protocol.md` as template. +```bash +cp ".afyapowers/features//artifacts/design.md" "${WT_PATH}/DESIGN_CONTEXT.md" +``` + +### 3C. Generate PROMPT.md with territory rules -Replace placeholders: -- `{{WORKTREE_ID}}` → `wt` -- `{{OWNED_FILES}}` → list of ownedFiles + ownedDirs for this group -- `{{READ_ONLY_FILES}}` → list of readOnlyFiles -- `{{FORBIDDEN_DIRS}}` → list of forbiddenDirs -- `{{SHARED_FILES}}` → list with strategies -- `{{MERGE_ORDER}}` → merge order description +Read `skills/parallel-split/territory-protocol.md` as template. Replace placeholders with this group's territory data. -Write to `${WT}/PROMPT.md`: +Write to `${WT_PATH}/PROMPT.md`: ```markdown # Parallel Worktree wt — @@ -186,33 +118,33 @@ Write to `${WT}/PROMPT.md`: ## Context You are implementing a subset of the feature "" in a parallel worktree. -This worktree handles tasks: +This worktree handles tasks: Focus area: -## Active Feature - -Your afyapowers feature is ready at: -`.afyapowers/features//` +## Instructions -The design and plan artifacts are pre-populated. You are starting at the **implement** phase. +1. Read this file completely +2. Read `DESIGN_CONTEXT.md` for the full design spec +3. Read `PLAN_SUBSET.md` for your assigned tasks +4. Implement ALL tasks following TDD (test first → implement → refactor → commit) +5. For each completed task, mark its checkbox: `- [ ]` → `- [x]` in PLAN_SUBSET.md +6. **Respect territory rules below** — do NOT edit files outside your territory +7. After ALL tasks are complete: create `WORKTREE_COMPLETE.md` with a summary of what was done +8. Do NOT run /afyapowers:next — do NOT start review or complete phases -## Instructions +## IMPORTANT: Implement Only -1. Read PROMPT.md (this file) completely -2. Run the implement phase: the plan at `.afyapowers/features//artifacts/plan.md` has your tasks -3. Follow TDD and subagent-driven-development as usual -4. **Respect territory rules below** — do NOT edit files outside your territory -5. After implement: run `/afyapowers:next` to proceed to review -6. After review: run `/afyapowers:next` to proceed to complete -7. At complete phase: choose **"Keep as-is"** — do NOT merge or create PR -8. After completion, create `WORKTREE_COMPLETE.md` to signal you are done +This worktree handles ONLY the implement phase. Review and completion happen on +the parent branch after all worktrees merge back. When done, just create +WORKTREE_COMPLETE.md and stop. - + ``` -### 3E. Provision MCP servers (Claude Code only) +### 3D. Provision MCP servers (Claude Code only) ```bash +WT_ABS_PATH="$(cd "${WT_PATH}" && pwd)" cd "${WT_ABS_PATH}" claude mcp remove serena -s project 2>/dev/null claude mcp remove sequential-thinking -s project 2>/dev/null @@ -223,7 +155,7 @@ claude mcp add -s project sequential-thinking -- npx -y @modelcontextprotocol/se Copy settings if they exist: ```bash -[ -f ".claude/settings.local.json" ] && mkdir -p "${WT}/.claude" && cp ".claude/settings.local.json" "${WT}/.claude/" +[ -f ".claude/settings.local.json" ] && mkdir -p "${WT_PATH}/.claude" && cp ".claude/settings.local.json" "${WT_PATH}/.claude/" ``` --- @@ -242,7 +174,6 @@ Write `territory_map.json` in the parent project root: "id": "wt1", "path": "", "branch": "", - "featureSlug": "-wt1", "tasks": [1, 2, 5], "taskNames": ["Task 1: ...", "Task 2: ...", "Task 5: ..."], "ownedFiles": [], @@ -263,22 +194,20 @@ Write `territory_map.json` in the parent project root: In the parent project's `.afyapowers/features//`: -1. Update `state.yaml`: set implement phase to `in_progress`, add note about parallel split -2. Append to `history.yaml`: +Append to `history.yaml` under the `events:` key: ```yaml -- event: parallel_split - timestamp: "" - details: "Split into parallel worktrees: " - territory_map: "territory_map.json" + - timestamp: "" + event: parallel_split + phase: implement + details: "Split into parallel worktrees: " + command: parallel-split ``` --- ## Step 6: Launch Terminals -Detect available terminal multiplexer and launch: - ### 6A. Warp (default on macOS) Generate Warp Launch Configuration: @@ -296,14 +225,15 @@ windows: panes: - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" + - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase. Respect territory rules.'" + - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" ``` -Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` +Where `` chains the `claude mcp remove` + `claude mcp add` commands from Step 3D. +Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` Open: `open "warp://launch/afyapowers%20Parallel"` ### 6B. tmux (fallback) @@ -311,7 +241,7 @@ Open: `open "warp://launch/afyapowers%20Parallel"` ```bash SESSION="afyapowers-parallel" tmux new-session -d -s "${SESSION}" -x 200 -y 50 -tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md...'" Enter +tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" Enter # Split + send-keys for each additional worktree tmux select-layout -t "${SESSION}" tiled tmux attach -t "${SESSION}" @@ -319,21 +249,14 @@ tmux attach -t "${SESSION}" ### 6C. Manual (no multiplexer) -Print commands for user to copy-paste: - -``` -Parallel split complete! Open one terminal per worktree: - - cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' - cd && claude 'Read PROMPT.md and execute the afyapowers workflow starting from implement phase.' -``` +Print commands for user to copy-paste. --- -## Step 7: Display Summary +## Step 7: Display Summary and Post-Merge Instructions ``` -Parallel Split Complete +Parallel Split — Implement Phase Feature: Worktrees: @@ -342,42 +265,36 @@ Territory map: territory_map.json wt1 (Tasks ): Owns: Branch: - + wt2 (Tasks ): Owns: Branch: Merge order: wt1 → wt2 → wt3 -Shared files: (all deferred) - -Agents launched in . - -After all worktrees complete: - 1. Merge in order: git merge for each worktree - 2. Consolidate _deferred/ files - 3. Run full test suite - 4. Continue with /afyapowers:next in parent feature (review phase) -``` +Shared files: (deferred) ---- +Agents launched. -## CLEANUP +After ALL worktrees create WORKTREE_COMPLETE.md: -After all worktrees complete and are merged: + 1. Merge in order: + git merge + git merge + ... -```bash -# Remove worktrees -git worktree list | grep "afyapowers.*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} + 2. Consolidate deferred files (if any in _deferred/) -# Clean up branches -git branch | grep "afyapowers.*wt" | xargs git branch -d + 3. Update plan.md checkboxes: + The merge brings in each worktree's PLAN_SUBSET.md changes. + Verify the parent plan.md has all tasks marked [x]. + If some checkboxes are still [ ], manually mark them based + on the worktree PLAN_SUBSET.md files. -# Remove territory map -rm territory_map.json + 4. Run /afyapowers:next to proceed to review (on the parent feature) -# Clean up deferred files -rm -rf _deferred/ - -# Remove launch config -rm ~/.warp/launch_configurations/afyapowers-parallel.yaml 2>/dev/null + 5. Clean up: + git worktree list | grep ".*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} + rm territory_map.json _deferred/ 2>/dev/null ``` + +**IMPORTANT:** After displaying the summary, the `implementing` skill will wait for the user to complete the merge steps and then resume at the "After SDD Completes" check (verifying all plan.md checkboxes are `[x]`). diff --git a/src/skills/parallel-split/territory-protocol.md b/src/skills/parallel-split/territory-protocol.md index c492077..b61d7dd 100644 --- a/src/skills/parallel-split/territory-protocol.md +++ b/src/skills/parallel-split/territory-protocol.md @@ -1,6 +1,6 @@ # Territory Protocol for Parallel Worktrees -You are working in a **parallel worktree** with territory-based file isolation. Other agents are simultaneously working on other task groups in separate worktrees. To prevent merge conflicts, you MUST respect the territory rules below. +You are working in a **parallel worktree** implementing a subset of tasks. Other agents are simultaneously working on other task groups in separate worktrees. To prevent merge conflicts, you MUST respect the territory rules below. --- @@ -40,27 +40,16 @@ If during implementation you realize you NEED to edit a file outside your territ 1. **Do NOT edit it** 2. Create `_deferred/{{WORKTREE_ID}}/territory-request.md` documenting what you need 3. Create a stub or workaround within your territory -4. Continue with implementation — the merge step will handle cross-territory needs -5. Note the territory limitation as a concern in your implementation +4. Continue with implementation --- -## MERGE ORDER +## SCOPE: IMPLEMENT ONLY -{{MERGE_ORDER}} +You are running ONLY the implement phase. Do NOT: +- Run `/afyapowers:next` +- Start review or complete phases +- Create review.md or completion.md +- Merge branches or create PRs -Your worktree will be merged in the order specified above. If you depend on code from a worktree that merges before you, it will be available after their merge completes. - ---- - -## WORKFLOW - -You are running the afyapowers 5-phase workflow for your assigned tasks: - -1. Your plan.md has been pre-populated with your assigned tasks only -2. Run the implement phase: follow TDD, use subagent-driven-development for wave execution -3. After implementation: proceed to review phase (`/afyapowers:next`) -4. After review: proceed to complete phase (`/afyapowers:next`) -5. At completion: choose "Keep as-is" — the parent orchestrator handles merge - -**IMPORTANT:** Always respect territory rules during ALL phases (implement, review, complete). +When all tasks are done, create `WORKTREE_COMPLETE.md` and stop. The parent branch handles review and completion after merge. From 19cf52bd778f040dc2f44a29e16cb8a9eff17930 Mon Sep 17 00:00:00 2001 From: allanbrunoafya Date: Thu, 9 Apr 2026 14:54:15 -0300 Subject: [PATCH 3/6] fix: canonical plan reconciliation and host-agnostic worktree setup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Worktrees now copy and update the canonical plan.md at .afyapowers/features//artifacts/plan.md so checkbox changes merge back cleanly into the parent branch - TASK_SCOPE.md is now a read-only scope summary, not the source of truth for task progress - Removed claude CLI coupling from parallel-split — MCP setup is optional and host-specific, not hardcoded - implementing skill clarifies post-merge path: if all [x] run /afyapowers:next, otherwise stay in implement Co-Authored-By: Claude Opus 4.6 (1M context) --- dist/claude/skills/implementing/SKILL.md | 10 +-- dist/claude/skills/parallel-split/SKILL.md | 90 ++++++++++++------- .../skills/afyapowers-implementing/SKILL.md | 10 +-- .../skills/afyapowers-parallel-split/SKILL.md | 90 ++++++++++++------- dist/gemini/skills/implementing/SKILL.md | 10 +-- dist/gemini/skills/parallel-split/SKILL.md | 90 ++++++++++++------- .../skills/implementing/SKILL.md | 10 +-- .../skills/parallel-split/SKILL.md | 90 ++++++++++++------- src/skills/implementing/SKILL.md | 10 +-- src/skills/parallel-split/SKILL.md | 90 ++++++++++++------- 10 files changed, 305 insertions(+), 195 deletions(-) diff --git a/dist/claude/skills/implementing/SKILL.md b/dist/claude/skills/implementing/SKILL.md index 3a19932..38eb367 100644 --- a/dist/claude/skills/implementing/SKILL.md +++ b/dist/claude/skills/implementing/SKILL.md @@ -67,11 +67,11 @@ How would you like to execute? 8. **If user chooses 2 (Parallel):** - Invoke `parallel-split` skill with: feature slug, plan content, design content, task groups, parsed tasks - The parallel-split skill creates worktrees, each running ONLY the implement phase for its task group - - **After all worktrees complete and merge back:** - - Re-read the parent plan.md — verify all checkboxes are `[x]` (worktree merges update the parent plan) - - If some remain unchecked, report them to the user - - **Resume the parent flow at "After SDD Completes" below** (the parent continues with review → complete) - - **STOP here** — do not invoke SDD (the worktrees handled implementation) + - Each worktree updates the canonical feature plan at `.afyapowers/features//artifacts/plan.md` in its own branch, but may only mark the tasks assigned to its group + - After all worktrees finish, merge them back into the parent branch and verify the parent plan has all tasks marked `[x]` + - If all tasks are `[x]`, the implement phase is complete: run `/afyapowers:next` on the parent feature to proceed to review + - If some tasks remain unchecked after the merge, stay in the implement phase and continue from the remaining tasks + - **STOP here** — do not invoke SDD in this run (the worktrees handled implementation) ## Invoke Sub-Skill diff --git a/dist/claude/skills/parallel-split/SKILL.md b/dist/claude/skills/parallel-split/SKILL.md index 5963247..0c85bb4 100644 --- a/dist/claude/skills/parallel-split/SKILL.md +++ b/dist/claude/skills/parallel-split/SKILL.md @@ -88,25 +88,38 @@ git worktree add -b "${BRANCH_NAME}" "${WT_PATH}" HEAD ## Step 3: Prepare Each Worktree -### 3A. Generate subset plan.md +### 3A. Copy canonical plan.md -Create a `plan.md` in the worktree root containing ONLY this group's tasks: +Copy the parent feature's canonical plan artifact into the worktree: + +```bash +mkdir -p "${WT_PATH}/.afyapowers/features//artifacts" +cp ".afyapowers/features//artifacts/plan.md" \ + "${WT_PATH}/.afyapowers/features//artifacts/plan.md" +``` + +This is the file that must be updated during implementation so checkbox changes merge back cleanly into the parent feature. + +### 3B. Generate task scope summary + +Create `TASK_SCOPE.md` in the worktree root containing ONLY this group's task blocks: 1. Copy the plan header (Goal, Architecture, Tech Stack) 2. Include ONLY the `### Task N:` blocks assigned to this group -3. Preserve original task numbers (do NOT renumber — needed for merging checkboxes back) -4. Update `**Depends on:**` references: remove deps on tasks outside this group (they have no cross-group deps by definition) -5. Preserve all step details, file lists, and Figma metadata +3. Preserve original task numbers (do NOT renumber) +4. Preserve all step details, file lists, and Figma metadata -Save to `${WT_PATH}/PLAN_SUBSET.md` +Save to `${WT_PATH}/TASK_SCOPE.md` -### 3B. Copy design.md for context +### 3C. Copy design.md for context ```bash +cp ".afyapowers/features//artifacts/design.md" \ + "${WT_PATH}/.afyapowers/features//artifacts/design.md" cp ".afyapowers/features//artifacts/design.md" "${WT_PATH}/DESIGN_CONTEXT.md" ``` -### 3C. Generate PROMPT.md with territory rules +### 3D. Generate PROMPT.md with territory rules Read `skills/parallel-split/territory-protocol.md` as template. Replace placeholders with this group's territory data. @@ -125,12 +138,14 @@ Focus area: 1. Read this file completely 2. Read `DESIGN_CONTEXT.md` for the full design spec -3. Read `PLAN_SUBSET.md` for your assigned tasks -4. Implement ALL tasks following TDD (test first → implement → refactor → commit) -5. For each completed task, mark its checkbox: `- [ ]` → `- [x]` in PLAN_SUBSET.md -6. **Respect territory rules below** — do NOT edit files outside your territory -7. After ALL tasks are complete: create `WORKTREE_COMPLETE.md` with a summary of what was done -8. Do NOT run /afyapowers:next — do NOT start review or complete phases +3. Read `TASK_SCOPE.md` for your assigned tasks +4. Read `.afyapowers/features//artifacts/plan.md` for the canonical feature plan +5. Implement ALL tasks following TDD (test first → implement → refactor → commit) +6. For each completed assigned task, mark its checkbox: `- [ ]` → `- [x]` in `.afyapowers/features//artifacts/plan.md` +7. Do NOT mark or edit tasks outside your assigned group +8. **Respect territory rules below** — do NOT edit files outside your territory +9. After ALL assigned tasks are complete: create `WORKTREE_COMPLETE.md` with a summary of what was done +10. Do NOT run /afyapowers:next — do NOT start review or complete phases ## IMPORTANT: Implement Only @@ -141,7 +156,14 @@ WORKTREE_COMPLETE.md and stop. ``` -### 3D. Provision MCP servers (Claude Code only) +### 3E. Host-Specific Setup + +Use the normal project or plugin setup for the host running in each worktree. + +- Claude Code: you may provision project MCP servers for each worktree if needed +- Other hosts: do not assume the `claude` CLI exists; use the host's normal setup flow instead + +Optional Claude Code setup example: ```bash WT_ABS_PATH="$(cd "${WT_PATH}" && pwd)" @@ -231,25 +253,23 @@ windows: - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" ``` -Where `` chains the `claude mcp remove` + `claude mcp add` commands from Step 3D. +Where `` chains the optional Claude Code setup commands from Step 3E. Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` Open: `open "warp://launch/afyapowers%20Parallel"` -### 6B. tmux (fallback) +### 6B. Generic Manual Launch -```bash -SESSION="afyapowers-parallel" -tmux new-session -d -s "${SESSION}" -x 200 -y 50 -tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" Enter -# Split + send-keys for each additional worktree -tmux select-layout -t "${SESSION}" tiled -tmux attach -t "${SESSION}" -``` +If automated launch is unavailable or you are using a non-Claude host, open one agent session per worktree manually and tell it to read `PROMPT.md`. + +Example: -### 6C. Manual (no multiplexer) +```text +cd && +cd && +``` -Print commands for user to copy-paste. +Use tmux, Warp, separate terminals, or separate IDE windows according to your host environment. --- @@ -284,17 +304,19 @@ After ALL worktrees create WORKTREE_COMPLETE.md: 2. Consolidate deferred files (if any in _deferred/) - 3. Update plan.md checkboxes: - The merge brings in each worktree's PLAN_SUBSET.md changes. - Verify the parent plan.md has all tasks marked [x]. - If some checkboxes are still [ ], manually mark them based - on the worktree PLAN_SUBSET.md files. + 3. Verify the canonical feature plan: + .afyapowers/features//artifacts/plan.md + Each worktree updated its assigned task checkboxes in that file. + After the merges, confirm every task is [x]. - 4. Run /afyapowers:next to proceed to review (on the parent feature) + 4. If every task is [x], run /afyapowers:next to proceed to review + If some tasks are still [ ], stay in implement and continue from there 5. Clean up: git worktree list | grep ".*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} rm territory_map.json _deferred/ 2>/dev/null ``` -**IMPORTANT:** After displaying the summary, the `implementing` skill will wait for the user to complete the merge steps and then resume at the "After SDD Completes" check (verifying all plan.md checkboxes are `[x]`). +**IMPORTANT:** This skill does not implicitly resume later. After merges are finished, continue from the parent feature: +- If the canonical plan is fully checked off, run `/afyapowers:next` +- If work remains, stay in implement and continue from the remaining unchecked tasks diff --git a/dist/cursor/skills/afyapowers-implementing/SKILL.md b/dist/cursor/skills/afyapowers-implementing/SKILL.md index a380621..df2fea8 100644 --- a/dist/cursor/skills/afyapowers-implementing/SKILL.md +++ b/dist/cursor/skills/afyapowers-implementing/SKILL.md @@ -67,11 +67,11 @@ How would you like to execute? 8. **If user chooses 2 (Parallel):** - Invoke `parallel-split` skill with: feature slug, plan content, design content, task groups, parsed tasks - The parallel-split skill creates worktrees, each running ONLY the implement phase for its task group - - **After all worktrees complete and merge back:** - - Re-read the parent plan.md — verify all checkboxes are `[x]` (worktree merges update the parent plan) - - If some remain unchecked, report them to the user - - **Resume the parent flow at "After SDD Completes" below** (the parent continues with review → complete) - - **STOP here** — do not invoke SDD (the worktrees handled implementation) + - Each worktree updates the canonical feature plan at `.afyapowers/features//artifacts/plan.md` in its own branch, but may only mark the tasks assigned to its group + - After all worktrees finish, merge them back into the parent branch and verify the parent plan has all tasks marked `[x]` + - If all tasks are `[x]`, the implement phase is complete: run `/afyapowers:next` on the parent feature to proceed to review + - If some tasks remain unchecked after the merge, stay in the implement phase and continue from the remaining tasks + - **STOP here** — do not invoke SDD in this run (the worktrees handled implementation) ## Invoke Sub-Skill diff --git a/dist/cursor/skills/afyapowers-parallel-split/SKILL.md b/dist/cursor/skills/afyapowers-parallel-split/SKILL.md index 01d6fe5..d3fabe7 100644 --- a/dist/cursor/skills/afyapowers-parallel-split/SKILL.md +++ b/dist/cursor/skills/afyapowers-parallel-split/SKILL.md @@ -88,25 +88,38 @@ git worktree add -b "${BRANCH_NAME}" "${WT_PATH}" HEAD ## Step 3: Prepare Each Worktree -### 3A. Generate subset plan.md +### 3A. Copy canonical plan.md -Create a `plan.md` in the worktree root containing ONLY this group's tasks: +Copy the parent feature's canonical plan artifact into the worktree: + +```bash +mkdir -p "${WT_PATH}/.afyapowers/features//artifacts" +cp ".afyapowers/features//artifacts/plan.md" \ + "${WT_PATH}/.afyapowers/features//artifacts/plan.md" +``` + +This is the file that must be updated during implementation so checkbox changes merge back cleanly into the parent feature. + +### 3B. Generate task scope summary + +Create `TASK_SCOPE.md` in the worktree root containing ONLY this group's task blocks: 1. Copy the plan header (Goal, Architecture, Tech Stack) 2. Include ONLY the `### Task N:` blocks assigned to this group -3. Preserve original task numbers (do NOT renumber — needed for merging checkboxes back) -4. Update `**Depends on:**` references: remove deps on tasks outside this group (they have no cross-group deps by definition) -5. Preserve all step details, file lists, and Figma metadata +3. Preserve original task numbers (do NOT renumber) +4. Preserve all step details, file lists, and Figma metadata -Save to `${WT_PATH}/PLAN_SUBSET.md` +Save to `${WT_PATH}/TASK_SCOPE.md` -### 3B. Copy design.md for context +### 3C. Copy design.md for context ```bash +cp ".afyapowers/features//artifacts/design.md" \ + "${WT_PATH}/.afyapowers/features//artifacts/design.md" cp ".afyapowers/features//artifacts/design.md" "${WT_PATH}/DESIGN_CONTEXT.md" ``` -### 3C. Generate PROMPT.md with territory rules +### 3D. Generate PROMPT.md with territory rules Read `skills/parallel-split/territory-protocol.md` as template. Replace placeholders with this group's territory data. @@ -125,12 +138,14 @@ Focus area: 1. Read this file completely 2. Read `DESIGN_CONTEXT.md` for the full design spec -3. Read `PLAN_SUBSET.md` for your assigned tasks -4. Implement ALL tasks following TDD (test first → implement → refactor → commit) -5. For each completed task, mark its checkbox: `- [ ]` → `- [x]` in PLAN_SUBSET.md -6. **Respect territory rules below** — do NOT edit files outside your territory -7. After ALL tasks are complete: create `WORKTREE_COMPLETE.md` with a summary of what was done -8. Do NOT run /afyapowers:next — do NOT start review or complete phases +3. Read `TASK_SCOPE.md` for your assigned tasks +4. Read `.afyapowers/features//artifacts/plan.md` for the canonical feature plan +5. Implement ALL tasks following TDD (test first → implement → refactor → commit) +6. For each completed assigned task, mark its checkbox: `- [ ]` → `- [x]` in `.afyapowers/features//artifacts/plan.md` +7. Do NOT mark or edit tasks outside your assigned group +8. **Respect territory rules below** — do NOT edit files outside your territory +9. After ALL assigned tasks are complete: create `WORKTREE_COMPLETE.md` with a summary of what was done +10. Do NOT run /afyapowers:next — do NOT start review or complete phases ## IMPORTANT: Implement Only @@ -141,7 +156,14 @@ WORKTREE_COMPLETE.md and stop. ``` -### 3D. Provision MCP servers (Claude Code only) +### 3E. Host-Specific Setup + +Use the normal project or plugin setup for the host running in each worktree. + +- Claude Code: you may provision project MCP servers for each worktree if needed +- Other hosts: do not assume the `claude` CLI exists; use the host's normal setup flow instead + +Optional Claude Code setup example: ```bash WT_ABS_PATH="$(cd "${WT_PATH}" && pwd)" @@ -231,25 +253,23 @@ windows: - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" ``` -Where `` chains the `claude mcp remove` + `claude mcp add` commands from Step 3D. +Where `` chains the optional Claude Code setup commands from Step 3E. Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` Open: `open "warp://launch/afyapowers%20Parallel"` -### 6B. tmux (fallback) +### 6B. Generic Manual Launch -```bash -SESSION="afyapowers-parallel" -tmux new-session -d -s "${SESSION}" -x 200 -y 50 -tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" Enter -# Split + send-keys for each additional worktree -tmux select-layout -t "${SESSION}" tiled -tmux attach -t "${SESSION}" -``` +If automated launch is unavailable or you are using a non-Claude host, open one agent session per worktree manually and tell it to read `PROMPT.md`. + +Example: -### 6C. Manual (no multiplexer) +```text +cd && +cd && +``` -Print commands for user to copy-paste. +Use tmux, Warp, separate terminals, or separate IDE windows according to your host environment. --- @@ -284,17 +304,19 @@ After ALL worktrees create WORKTREE_COMPLETE.md: 2. Consolidate deferred files (if any in _deferred/) - 3. Update plan.md checkboxes: - The merge brings in each worktree's PLAN_SUBSET.md changes. - Verify the parent plan.md has all tasks marked [x]. - If some checkboxes are still [ ], manually mark them based - on the worktree PLAN_SUBSET.md files. + 3. Verify the canonical feature plan: + .afyapowers/features//artifacts/plan.md + Each worktree updated its assigned task checkboxes in that file. + After the merges, confirm every task is [x]. - 4. Run /afyapowers:next to proceed to review (on the parent feature) + 4. If every task is [x], run /afyapowers:next to proceed to review + If some tasks are still [ ], stay in implement and continue from there 5. Clean up: git worktree list | grep ".*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} rm territory_map.json _deferred/ 2>/dev/null ``` -**IMPORTANT:** After displaying the summary, the `implementing` skill will wait for the user to complete the merge steps and then resume at the "After SDD Completes" check (verifying all plan.md checkboxes are `[x]`). +**IMPORTANT:** This skill does not implicitly resume later. After merges are finished, continue from the parent feature: +- If the canonical plan is fully checked off, run `/afyapowers:next` +- If work remains, stay in implement and continue from the remaining unchecked tasks diff --git a/dist/gemini/skills/implementing/SKILL.md b/dist/gemini/skills/implementing/SKILL.md index a4fc93a..457849d 100644 --- a/dist/gemini/skills/implementing/SKILL.md +++ b/dist/gemini/skills/implementing/SKILL.md @@ -67,11 +67,11 @@ How would you like to execute? 8. **If user chooses 2 (Parallel):** - Invoke `parallel-split` skill with: feature slug, plan content, design content, task groups, parsed tasks - The parallel-split skill creates worktrees, each running ONLY the implement phase for its task group - - **After all worktrees complete and merge back:** - - Re-read the parent plan.md — verify all checkboxes are `[x]` (worktree merges update the parent plan) - - If some remain unchecked, report them to the user - - **Resume the parent flow at "After SDD Completes" below** (the parent continues with review → complete) - - **STOP here** — do not invoke SDD (the worktrees handled implementation) + - Each worktree updates the canonical feature plan at `.afyapowers/features//artifacts/plan.md` in its own branch, but may only mark the tasks assigned to its group + - After all worktrees finish, merge them back into the parent branch and verify the parent plan has all tasks marked `[x]` + - If all tasks are `[x]`, the implement phase is complete: run `/afyapowers:next` on the parent feature to proceed to review + - If some tasks remain unchecked after the merge, stay in the implement phase and continue from the remaining tasks + - **STOP here** — do not invoke SDD in this run (the worktrees handled implementation) ## Invoke Sub-Skill diff --git a/dist/gemini/skills/parallel-split/SKILL.md b/dist/gemini/skills/parallel-split/SKILL.md index a21a193..38b9bef 100644 --- a/dist/gemini/skills/parallel-split/SKILL.md +++ b/dist/gemini/skills/parallel-split/SKILL.md @@ -88,25 +88,38 @@ git worktree add -b "${BRANCH_NAME}" "${WT_PATH}" HEAD ## Step 3: Prepare Each Worktree -### 3A. Generate subset plan.md +### 3A. Copy canonical plan.md -Create a `plan.md` in the worktree root containing ONLY this group's tasks: +Copy the parent feature's canonical plan artifact into the worktree: + +```bash +mkdir -p "${WT_PATH}/.afyapowers/features//artifacts" +cp ".afyapowers/features//artifacts/plan.md" \ + "${WT_PATH}/.afyapowers/features//artifacts/plan.md" +``` + +This is the file that must be updated during implementation so checkbox changes merge back cleanly into the parent feature. + +### 3B. Generate task scope summary + +Create `TASK_SCOPE.md` in the worktree root containing ONLY this group's task blocks: 1. Copy the plan header (Goal, Architecture, Tech Stack) 2. Include ONLY the `### Task N:` blocks assigned to this group -3. Preserve original task numbers (do NOT renumber — needed for merging checkboxes back) -4. Update `**Depends on:**` references: remove deps on tasks outside this group (they have no cross-group deps by definition) -5. Preserve all step details, file lists, and Figma metadata +3. Preserve original task numbers (do NOT renumber) +4. Preserve all step details, file lists, and Figma metadata -Save to `${WT_PATH}/PLAN_SUBSET.md` +Save to `${WT_PATH}/TASK_SCOPE.md` -### 3B. Copy design.md for context +### 3C. Copy design.md for context ```bash +cp ".afyapowers/features//artifacts/design.md" \ + "${WT_PATH}/.afyapowers/features//artifacts/design.md" cp ".afyapowers/features//artifacts/design.md" "${WT_PATH}/DESIGN_CONTEXT.md" ``` -### 3C. Generate PROMPT.md with territory rules +### 3D. Generate PROMPT.md with territory rules Read `skills/parallel-split/territory-protocol.md` as template. Replace placeholders with this group's territory data. @@ -125,12 +138,14 @@ Focus area: 1. Read this file completely 2. Read `DESIGN_CONTEXT.md` for the full design spec -3. Read `PLAN_SUBSET.md` for your assigned tasks -4. Implement ALL tasks following TDD (test first → implement → refactor → commit) -5. For each completed task, mark its checkbox: `- [ ]` → `- [x]` in PLAN_SUBSET.md -6. **Respect territory rules below** — do NOT edit files outside your territory -7. After ALL tasks are complete: create `WORKTREE_COMPLETE.md` with a summary of what was done -8. Do NOT run /afyapowers:next — do NOT start review or complete phases +3. Read `TASK_SCOPE.md` for your assigned tasks +4. Read `.afyapowers/features//artifacts/plan.md` for the canonical feature plan +5. Implement ALL tasks following TDD (test first → implement → refactor → commit) +6. For each completed assigned task, mark its checkbox: `- [ ]` → `- [x]` in `.afyapowers/features//artifacts/plan.md` +7. Do NOT mark or edit tasks outside your assigned group +8. **Respect territory rules below** — do NOT edit files outside your territory +9. After ALL assigned tasks are complete: create `WORKTREE_COMPLETE.md` with a summary of what was done +10. Do NOT run /afyapowers:next — do NOT start review or complete phases ## IMPORTANT: Implement Only @@ -141,7 +156,14 @@ WORKTREE_COMPLETE.md and stop. ``` -### 3D. Provision MCP servers (Claude Code only) +### 3E. Host-Specific Setup + +Use the normal project or plugin setup for the host running in each worktree. + +- Claude Code: you may provision project MCP servers for each worktree if needed +- Other hosts: do not assume the `claude` CLI exists; use the host's normal setup flow instead + +Optional Claude Code setup example: ```bash WT_ABS_PATH="$(cd "${WT_PATH}" && pwd)" @@ -231,25 +253,23 @@ windows: - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" ``` -Where `` chains the `claude mcp remove` + `claude mcp add` commands from Step 3D. +Where `` chains the optional Claude Code setup commands from Step 3E. Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` Open: `open "warp://launch/afyapowers%20Parallel"` -### 6B. tmux (fallback) +### 6B. Generic Manual Launch -```bash -SESSION="afyapowers-parallel" -tmux new-session -d -s "${SESSION}" -x 200 -y 50 -tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" Enter -# Split + send-keys for each additional worktree -tmux select-layout -t "${SESSION}" tiled -tmux attach -t "${SESSION}" -``` +If automated launch is unavailable or you are using a non-Claude host, open one agent session per worktree manually and tell it to read `PROMPT.md`. + +Example: -### 6C. Manual (no multiplexer) +```text +cd && +cd && +``` -Print commands for user to copy-paste. +Use tmux, Warp, separate terminals, or separate IDE windows according to your host environment. --- @@ -284,17 +304,19 @@ After ALL worktrees create WORKTREE_COMPLETE.md: 2. Consolidate deferred files (if any in _deferred/) - 3. Update plan.md checkboxes: - The merge brings in each worktree's PLAN_SUBSET.md changes. - Verify the parent plan.md has all tasks marked [x]. - If some checkboxes are still [ ], manually mark them based - on the worktree PLAN_SUBSET.md files. + 3. Verify the canonical feature plan: + .afyapowers/features//artifacts/plan.md + Each worktree updated its assigned task checkboxes in that file. + After the merges, confirm every task is [x]. - 4. Run /afyapowers:next to proceed to review (on the parent feature) + 4. If every task is [x], run /afyapowers:next to proceed to review + If some tasks are still [ ], stay in implement and continue from there 5. Clean up: git worktree list | grep ".*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} rm territory_map.json _deferred/ 2>/dev/null ``` -**IMPORTANT:** After displaying the summary, the `implementing` skill will wait for the user to complete the merge steps and then resume at the "After SDD Completes" check (verifying all plan.md checkboxes are `[x]`). +**IMPORTANT:** This skill does not implicitly resume later. After merges are finished, continue from the parent feature: +- If the canonical plan is fully checked off, run `/afyapowers:next` +- If work remains, stay in implement and continue from the remaining unchecked tasks diff --git a/dist/github-copilot/skills/implementing/SKILL.md b/dist/github-copilot/skills/implementing/SKILL.md index a4fc93a..457849d 100644 --- a/dist/github-copilot/skills/implementing/SKILL.md +++ b/dist/github-copilot/skills/implementing/SKILL.md @@ -67,11 +67,11 @@ How would you like to execute? 8. **If user chooses 2 (Parallel):** - Invoke `parallel-split` skill with: feature slug, plan content, design content, task groups, parsed tasks - The parallel-split skill creates worktrees, each running ONLY the implement phase for its task group - - **After all worktrees complete and merge back:** - - Re-read the parent plan.md — verify all checkboxes are `[x]` (worktree merges update the parent plan) - - If some remain unchecked, report them to the user - - **Resume the parent flow at "After SDD Completes" below** (the parent continues with review → complete) - - **STOP here** — do not invoke SDD (the worktrees handled implementation) + - Each worktree updates the canonical feature plan at `.afyapowers/features//artifacts/plan.md` in its own branch, but may only mark the tasks assigned to its group + - After all worktrees finish, merge them back into the parent branch and verify the parent plan has all tasks marked `[x]` + - If all tasks are `[x]`, the implement phase is complete: run `/afyapowers:next` on the parent feature to proceed to review + - If some tasks remain unchecked after the merge, stay in the implement phase and continue from the remaining tasks + - **STOP here** — do not invoke SDD in this run (the worktrees handled implementation) ## Invoke Sub-Skill diff --git a/dist/github-copilot/skills/parallel-split/SKILL.md b/dist/github-copilot/skills/parallel-split/SKILL.md index a21a193..38b9bef 100644 --- a/dist/github-copilot/skills/parallel-split/SKILL.md +++ b/dist/github-copilot/skills/parallel-split/SKILL.md @@ -88,25 +88,38 @@ git worktree add -b "${BRANCH_NAME}" "${WT_PATH}" HEAD ## Step 3: Prepare Each Worktree -### 3A. Generate subset plan.md +### 3A. Copy canonical plan.md -Create a `plan.md` in the worktree root containing ONLY this group's tasks: +Copy the parent feature's canonical plan artifact into the worktree: + +```bash +mkdir -p "${WT_PATH}/.afyapowers/features//artifacts" +cp ".afyapowers/features//artifacts/plan.md" \ + "${WT_PATH}/.afyapowers/features//artifacts/plan.md" +``` + +This is the file that must be updated during implementation so checkbox changes merge back cleanly into the parent feature. + +### 3B. Generate task scope summary + +Create `TASK_SCOPE.md` in the worktree root containing ONLY this group's task blocks: 1. Copy the plan header (Goal, Architecture, Tech Stack) 2. Include ONLY the `### Task N:` blocks assigned to this group -3. Preserve original task numbers (do NOT renumber — needed for merging checkboxes back) -4. Update `**Depends on:**` references: remove deps on tasks outside this group (they have no cross-group deps by definition) -5. Preserve all step details, file lists, and Figma metadata +3. Preserve original task numbers (do NOT renumber) +4. Preserve all step details, file lists, and Figma metadata -Save to `${WT_PATH}/PLAN_SUBSET.md` +Save to `${WT_PATH}/TASK_SCOPE.md` -### 3B. Copy design.md for context +### 3C. Copy design.md for context ```bash +cp ".afyapowers/features//artifacts/design.md" \ + "${WT_PATH}/.afyapowers/features//artifacts/design.md" cp ".afyapowers/features//artifacts/design.md" "${WT_PATH}/DESIGN_CONTEXT.md" ``` -### 3C. Generate PROMPT.md with territory rules +### 3D. Generate PROMPT.md with territory rules Read `skills/parallel-split/territory-protocol.md` as template. Replace placeholders with this group's territory data. @@ -125,12 +138,14 @@ Focus area: 1. Read this file completely 2. Read `DESIGN_CONTEXT.md` for the full design spec -3. Read `PLAN_SUBSET.md` for your assigned tasks -4. Implement ALL tasks following TDD (test first → implement → refactor → commit) -5. For each completed task, mark its checkbox: `- [ ]` → `- [x]` in PLAN_SUBSET.md -6. **Respect territory rules below** — do NOT edit files outside your territory -7. After ALL tasks are complete: create `WORKTREE_COMPLETE.md` with a summary of what was done -8. Do NOT run /afyapowers:next — do NOT start review or complete phases +3. Read `TASK_SCOPE.md` for your assigned tasks +4. Read `.afyapowers/features//artifacts/plan.md` for the canonical feature plan +5. Implement ALL tasks following TDD (test first → implement → refactor → commit) +6. For each completed assigned task, mark its checkbox: `- [ ]` → `- [x]` in `.afyapowers/features//artifacts/plan.md` +7. Do NOT mark or edit tasks outside your assigned group +8. **Respect territory rules below** — do NOT edit files outside your territory +9. After ALL assigned tasks are complete: create `WORKTREE_COMPLETE.md` with a summary of what was done +10. Do NOT run /afyapowers:next — do NOT start review or complete phases ## IMPORTANT: Implement Only @@ -141,7 +156,14 @@ WORKTREE_COMPLETE.md and stop. ``` -### 3D. Provision MCP servers (Claude Code only) +### 3E. Host-Specific Setup + +Use the normal project or plugin setup for the host running in each worktree. + +- Claude Code: you may provision project MCP servers for each worktree if needed +- Other hosts: do not assume the `claude` CLI exists; use the host's normal setup flow instead + +Optional Claude Code setup example: ```bash WT_ABS_PATH="$(cd "${WT_PATH}" && pwd)" @@ -231,25 +253,23 @@ windows: - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" ``` -Where `` chains the `claude mcp remove` + `claude mcp add` commands from Step 3D. +Where `` chains the optional Claude Code setup commands from Step 3E. Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` Open: `open "warp://launch/afyapowers%20Parallel"` -### 6B. tmux (fallback) +### 6B. Generic Manual Launch -```bash -SESSION="afyapowers-parallel" -tmux new-session -d -s "${SESSION}" -x 200 -y 50 -tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" Enter -# Split + send-keys for each additional worktree -tmux select-layout -t "${SESSION}" tiled -tmux attach -t "${SESSION}" -``` +If automated launch is unavailable or you are using a non-Claude host, open one agent session per worktree manually and tell it to read `PROMPT.md`. + +Example: -### 6C. Manual (no multiplexer) +```text +cd && +cd && +``` -Print commands for user to copy-paste. +Use tmux, Warp, separate terminals, or separate IDE windows according to your host environment. --- @@ -284,17 +304,19 @@ After ALL worktrees create WORKTREE_COMPLETE.md: 2. Consolidate deferred files (if any in _deferred/) - 3. Update plan.md checkboxes: - The merge brings in each worktree's PLAN_SUBSET.md changes. - Verify the parent plan.md has all tasks marked [x]. - If some checkboxes are still [ ], manually mark them based - on the worktree PLAN_SUBSET.md files. + 3. Verify the canonical feature plan: + .afyapowers/features//artifacts/plan.md + Each worktree updated its assigned task checkboxes in that file. + After the merges, confirm every task is [x]. - 4. Run /afyapowers:next to proceed to review (on the parent feature) + 4. If every task is [x], run /afyapowers:next to proceed to review + If some tasks are still [ ], stay in implement and continue from there 5. Clean up: git worktree list | grep ".*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} rm territory_map.json _deferred/ 2>/dev/null ``` -**IMPORTANT:** After displaying the summary, the `implementing` skill will wait for the user to complete the merge steps and then resume at the "After SDD Completes" check (verifying all plan.md checkboxes are `[x]`). +**IMPORTANT:** This skill does not implicitly resume later. After merges are finished, continue from the parent feature: +- If the canonical plan is fully checked off, run `/afyapowers:next` +- If work remains, stay in implement and continue from the remaining unchecked tasks diff --git a/src/skills/implementing/SKILL.md b/src/skills/implementing/SKILL.md index a4fc93a..457849d 100644 --- a/src/skills/implementing/SKILL.md +++ b/src/skills/implementing/SKILL.md @@ -67,11 +67,11 @@ How would you like to execute? 8. **If user chooses 2 (Parallel):** - Invoke `parallel-split` skill with: feature slug, plan content, design content, task groups, parsed tasks - The parallel-split skill creates worktrees, each running ONLY the implement phase for its task group - - **After all worktrees complete and merge back:** - - Re-read the parent plan.md — verify all checkboxes are `[x]` (worktree merges update the parent plan) - - If some remain unchecked, report them to the user - - **Resume the parent flow at "After SDD Completes" below** (the parent continues with review → complete) - - **STOP here** — do not invoke SDD (the worktrees handled implementation) + - Each worktree updates the canonical feature plan at `.afyapowers/features//artifacts/plan.md` in its own branch, but may only mark the tasks assigned to its group + - After all worktrees finish, merge them back into the parent branch and verify the parent plan has all tasks marked `[x]` + - If all tasks are `[x]`, the implement phase is complete: run `/afyapowers:next` on the parent feature to proceed to review + - If some tasks remain unchecked after the merge, stay in the implement phase and continue from the remaining tasks + - **STOP here** — do not invoke SDD in this run (the worktrees handled implementation) ## Invoke Sub-Skill diff --git a/src/skills/parallel-split/SKILL.md b/src/skills/parallel-split/SKILL.md index a21a193..38b9bef 100644 --- a/src/skills/parallel-split/SKILL.md +++ b/src/skills/parallel-split/SKILL.md @@ -88,25 +88,38 @@ git worktree add -b "${BRANCH_NAME}" "${WT_PATH}" HEAD ## Step 3: Prepare Each Worktree -### 3A. Generate subset plan.md +### 3A. Copy canonical plan.md -Create a `plan.md` in the worktree root containing ONLY this group's tasks: +Copy the parent feature's canonical plan artifact into the worktree: + +```bash +mkdir -p "${WT_PATH}/.afyapowers/features//artifacts" +cp ".afyapowers/features//artifacts/plan.md" \ + "${WT_PATH}/.afyapowers/features//artifacts/plan.md" +``` + +This is the file that must be updated during implementation so checkbox changes merge back cleanly into the parent feature. + +### 3B. Generate task scope summary + +Create `TASK_SCOPE.md` in the worktree root containing ONLY this group's task blocks: 1. Copy the plan header (Goal, Architecture, Tech Stack) 2. Include ONLY the `### Task N:` blocks assigned to this group -3. Preserve original task numbers (do NOT renumber — needed for merging checkboxes back) -4. Update `**Depends on:**` references: remove deps on tasks outside this group (they have no cross-group deps by definition) -5. Preserve all step details, file lists, and Figma metadata +3. Preserve original task numbers (do NOT renumber) +4. Preserve all step details, file lists, and Figma metadata -Save to `${WT_PATH}/PLAN_SUBSET.md` +Save to `${WT_PATH}/TASK_SCOPE.md` -### 3B. Copy design.md for context +### 3C. Copy design.md for context ```bash +cp ".afyapowers/features//artifacts/design.md" \ + "${WT_PATH}/.afyapowers/features//artifacts/design.md" cp ".afyapowers/features//artifacts/design.md" "${WT_PATH}/DESIGN_CONTEXT.md" ``` -### 3C. Generate PROMPT.md with territory rules +### 3D. Generate PROMPT.md with territory rules Read `skills/parallel-split/territory-protocol.md` as template. Replace placeholders with this group's territory data. @@ -125,12 +138,14 @@ Focus area: 1. Read this file completely 2. Read `DESIGN_CONTEXT.md` for the full design spec -3. Read `PLAN_SUBSET.md` for your assigned tasks -4. Implement ALL tasks following TDD (test first → implement → refactor → commit) -5. For each completed task, mark its checkbox: `- [ ]` → `- [x]` in PLAN_SUBSET.md -6. **Respect territory rules below** — do NOT edit files outside your territory -7. After ALL tasks are complete: create `WORKTREE_COMPLETE.md` with a summary of what was done -8. Do NOT run /afyapowers:next — do NOT start review or complete phases +3. Read `TASK_SCOPE.md` for your assigned tasks +4. Read `.afyapowers/features//artifacts/plan.md` for the canonical feature plan +5. Implement ALL tasks following TDD (test first → implement → refactor → commit) +6. For each completed assigned task, mark its checkbox: `- [ ]` → `- [x]` in `.afyapowers/features//artifacts/plan.md` +7. Do NOT mark or edit tasks outside your assigned group +8. **Respect territory rules below** — do NOT edit files outside your territory +9. After ALL assigned tasks are complete: create `WORKTREE_COMPLETE.md` with a summary of what was done +10. Do NOT run /afyapowers:next — do NOT start review or complete phases ## IMPORTANT: Implement Only @@ -141,7 +156,14 @@ WORKTREE_COMPLETE.md and stop. ``` -### 3D. Provision MCP servers (Claude Code only) +### 3E. Host-Specific Setup + +Use the normal project or plugin setup for the host running in each worktree. + +- Claude Code: you may provision project MCP servers for each worktree if needed +- Other hosts: do not assume the `claude` CLI exists; use the host's normal setup flow instead + +Optional Claude Code setup example: ```bash WT_ABS_PATH="$(cd "${WT_PATH}" && pwd)" @@ -231,25 +253,23 @@ windows: - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" ``` -Where `` chains the `claude mcp remove` + `claude mcp add` commands from Step 3D. +Where `` chains the optional Claude Code setup commands from Step 3E. Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` Open: `open "warp://launch/afyapowers%20Parallel"` -### 6B. tmux (fallback) +### 6B. Generic Manual Launch -```bash -SESSION="afyapowers-parallel" -tmux new-session -d -s "${SESSION}" -x 200 -y 50 -tmux send-keys -t "${SESSION}:0.0" "cd '' && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" Enter -# Split + send-keys for each additional worktree -tmux select-layout -t "${SESSION}" tiled -tmux attach -t "${SESSION}" -``` +If automated launch is unavailable or you are using a non-Claude host, open one agent session per worktree manually and tell it to read `PROMPT.md`. + +Example: -### 6C. Manual (no multiplexer) +```text +cd && +cd && +``` -Print commands for user to copy-paste. +Use tmux, Warp, separate terminals, or separate IDE windows according to your host environment. --- @@ -284,17 +304,19 @@ After ALL worktrees create WORKTREE_COMPLETE.md: 2. Consolidate deferred files (if any in _deferred/) - 3. Update plan.md checkboxes: - The merge brings in each worktree's PLAN_SUBSET.md changes. - Verify the parent plan.md has all tasks marked [x]. - If some checkboxes are still [ ], manually mark them based - on the worktree PLAN_SUBSET.md files. + 3. Verify the canonical feature plan: + .afyapowers/features//artifacts/plan.md + Each worktree updated its assigned task checkboxes in that file. + After the merges, confirm every task is [x]. - 4. Run /afyapowers:next to proceed to review (on the parent feature) + 4. If every task is [x], run /afyapowers:next to proceed to review + If some tasks are still [ ], stay in implement and continue from there 5. Clean up: git worktree list | grep ".*wt" | awk '{print $1}' | xargs -I {} git worktree remove {} rm territory_map.json _deferred/ 2>/dev/null ``` -**IMPORTANT:** After displaying the summary, the `implementing` skill will wait for the user to complete the merge steps and then resume at the "After SDD Completes" check (verifying all plan.md checkboxes are `[x]`). +**IMPORTANT:** This skill does not implicitly resume later. After merges are finished, continue from the parent feature: +- If the canonical plan is fully checked off, run `/afyapowers:next` +- If work remains, stay in implement and continue from the remaining unchecked tasks From 1d00da55d18d724850dfe9dce6cbd726e6d3d4c0 Mon Sep 17 00:00:00 2001 From: allanbrunoafya Date: Thu, 9 Apr 2026 15:05:43 -0300 Subject: [PATCH 4/6] fix: address 3 minor review findings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace hardcoded `claude` CLI in Warp launch config with placeholder for host-agnostic distribution - Document plan.md merge conflict resolution: preserve all valid [x] checkboxes from both sides when merging worktree branches - Clarify _deferred/ as temporary merge aid, not final product code — consolidate during parent merge then remove Co-Authored-By: Claude Opus 4.6 (1M context) --- dist/claude/skills/parallel-split/SKILL.md | 11 ++++++++--- .../skills/parallel-split/territory-protocol.md | 2 ++ dist/cursor/skills/afyapowers-parallel-split/SKILL.md | 11 ++++++++--- .../afyapowers-parallel-split/territory-protocol.md | 2 ++ dist/gemini/skills/parallel-split/SKILL.md | 11 ++++++++--- .../skills/parallel-split/territory-protocol.md | 2 ++ dist/github-copilot/skills/parallel-split/SKILL.md | 11 ++++++++--- .../skills/parallel-split/territory-protocol.md | 2 ++ src/skills/parallel-split/SKILL.md | 11 ++++++++--- src/skills/parallel-split/territory-protocol.md | 2 ++ 10 files changed, 50 insertions(+), 15 deletions(-) diff --git a/dist/claude/skills/parallel-split/SKILL.md b/dist/claude/skills/parallel-split/SKILL.md index 0c85bb4..a6a992b 100644 --- a/dist/claude/skills/parallel-split/SKILL.md +++ b/dist/claude/skills/parallel-split/SKILL.md @@ -247,13 +247,15 @@ windows: panes: - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" + - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" + - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" ``` -Where `` chains the optional Claude Code setup commands from Step 3E. +Where: +- `` chains the optional Claude Code setup commands from Step 3E +- `` is the command used by the host running in that worktree Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` Open: `open "warp://launch/afyapowers%20Parallel"` @@ -308,6 +310,9 @@ After ALL worktrees create WORKTREE_COMPLETE.md: .afyapowers/features//artifacts/plan.md Each worktree updated its assigned task checkboxes in that file. After the merges, confirm every task is [x]. + If git reports a conflict in plan.md because two worktrees marked different tasks, + keep both sets of checkbox updates. Resolve the conflict by preserving every [x] + that came from completed assigned tasks. 4. If every task is [x], run /afyapowers:next to proceed to review If some tasks are still [ ], stay in implement and continue from there diff --git a/dist/claude/skills/parallel-split/territory-protocol.md b/dist/claude/skills/parallel-split/territory-protocol.md index b61d7dd..04015fd 100644 --- a/dist/claude/skills/parallel-split/territory-protocol.md +++ b/dist/claude/skills/parallel-split/territory-protocol.md @@ -31,6 +31,8 @@ For each shared file, follow the strategy specified: - **single_owner (you own)**: Edit freely, but preserve exports that other worktrees depend on. - **single_owner (other owns)**: Do NOT modify. If you need changes, document them in `_deferred/{{WORKTREE_ID}}/request.md`. +`_deferred/` is a temporary merge aid. Do not treat it as final product code. Consolidate its contents during the parent-branch merge, then remove it unless the parent workflow explicitly decides to keep a note for follow-up. + --- ## TERRITORY VIOLATION PROTOCOL diff --git a/dist/cursor/skills/afyapowers-parallel-split/SKILL.md b/dist/cursor/skills/afyapowers-parallel-split/SKILL.md index d3fabe7..983f19b 100644 --- a/dist/cursor/skills/afyapowers-parallel-split/SKILL.md +++ b/dist/cursor/skills/afyapowers-parallel-split/SKILL.md @@ -247,13 +247,15 @@ windows: panes: - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" + - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" + - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" ``` -Where `` chains the optional Claude Code setup commands from Step 3E. +Where: +- `` chains the optional Claude Code setup commands from Step 3E +- `` is the command used by the host running in that worktree Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` Open: `open "warp://launch/afyapowers%20Parallel"` @@ -308,6 +310,9 @@ After ALL worktrees create WORKTREE_COMPLETE.md: .afyapowers/features//artifacts/plan.md Each worktree updated its assigned task checkboxes in that file. After the merges, confirm every task is [x]. + If git reports a conflict in plan.md because two worktrees marked different tasks, + keep both sets of checkbox updates. Resolve the conflict by preserving every [x] + that came from completed assigned tasks. 4. If every task is [x], run /afyapowers:next to proceed to review If some tasks are still [ ], stay in implement and continue from there diff --git a/dist/cursor/skills/afyapowers-parallel-split/territory-protocol.md b/dist/cursor/skills/afyapowers-parallel-split/territory-protocol.md index b61d7dd..04015fd 100644 --- a/dist/cursor/skills/afyapowers-parallel-split/territory-protocol.md +++ b/dist/cursor/skills/afyapowers-parallel-split/territory-protocol.md @@ -31,6 +31,8 @@ For each shared file, follow the strategy specified: - **single_owner (you own)**: Edit freely, but preserve exports that other worktrees depend on. - **single_owner (other owns)**: Do NOT modify. If you need changes, document them in `_deferred/{{WORKTREE_ID}}/request.md`. +`_deferred/` is a temporary merge aid. Do not treat it as final product code. Consolidate its contents during the parent-branch merge, then remove it unless the parent workflow explicitly decides to keep a note for follow-up. + --- ## TERRITORY VIOLATION PROTOCOL diff --git a/dist/gemini/skills/parallel-split/SKILL.md b/dist/gemini/skills/parallel-split/SKILL.md index 38b9bef..7fc8bce 100644 --- a/dist/gemini/skills/parallel-split/SKILL.md +++ b/dist/gemini/skills/parallel-split/SKILL.md @@ -247,13 +247,15 @@ windows: panes: - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" + - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" + - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" ``` -Where `` chains the optional Claude Code setup commands from Step 3E. +Where: +- `` chains the optional Claude Code setup commands from Step 3E +- `` is the command used by the host running in that worktree Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` Open: `open "warp://launch/afyapowers%20Parallel"` @@ -308,6 +310,9 @@ After ALL worktrees create WORKTREE_COMPLETE.md: .afyapowers/features//artifacts/plan.md Each worktree updated its assigned task checkboxes in that file. After the merges, confirm every task is [x]. + If git reports a conflict in plan.md because two worktrees marked different tasks, + keep both sets of checkbox updates. Resolve the conflict by preserving every [x] + that came from completed assigned tasks. 4. If every task is [x], run /afyapowers:next to proceed to review If some tasks are still [ ], stay in implement and continue from there diff --git a/dist/gemini/skills/parallel-split/territory-protocol.md b/dist/gemini/skills/parallel-split/territory-protocol.md index b61d7dd..04015fd 100644 --- a/dist/gemini/skills/parallel-split/territory-protocol.md +++ b/dist/gemini/skills/parallel-split/territory-protocol.md @@ -31,6 +31,8 @@ For each shared file, follow the strategy specified: - **single_owner (you own)**: Edit freely, but preserve exports that other worktrees depend on. - **single_owner (other owns)**: Do NOT modify. If you need changes, document them in `_deferred/{{WORKTREE_ID}}/request.md`. +`_deferred/` is a temporary merge aid. Do not treat it as final product code. Consolidate its contents during the parent-branch merge, then remove it unless the parent workflow explicitly decides to keep a note for follow-up. + --- ## TERRITORY VIOLATION PROTOCOL diff --git a/dist/github-copilot/skills/parallel-split/SKILL.md b/dist/github-copilot/skills/parallel-split/SKILL.md index 38b9bef..7fc8bce 100644 --- a/dist/github-copilot/skills/parallel-split/SKILL.md +++ b/dist/github-copilot/skills/parallel-split/SKILL.md @@ -247,13 +247,15 @@ windows: panes: - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" + - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" + - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" ``` -Where `` chains the optional Claude Code setup commands from Step 3E. +Where: +- `` chains the optional Claude Code setup commands from Step 3E +- `` is the command used by the host running in that worktree Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` Open: `open "warp://launch/afyapowers%20Parallel"` @@ -308,6 +310,9 @@ After ALL worktrees create WORKTREE_COMPLETE.md: .afyapowers/features//artifacts/plan.md Each worktree updated its assigned task checkboxes in that file. After the merges, confirm every task is [x]. + If git reports a conflict in plan.md because two worktrees marked different tasks, + keep both sets of checkbox updates. Resolve the conflict by preserving every [x] + that came from completed assigned tasks. 4. If every task is [x], run /afyapowers:next to proceed to review If some tasks are still [ ], stay in implement and continue from there diff --git a/dist/github-copilot/skills/parallel-split/territory-protocol.md b/dist/github-copilot/skills/parallel-split/territory-protocol.md index b61d7dd..04015fd 100644 --- a/dist/github-copilot/skills/parallel-split/territory-protocol.md +++ b/dist/github-copilot/skills/parallel-split/territory-protocol.md @@ -31,6 +31,8 @@ For each shared file, follow the strategy specified: - **single_owner (you own)**: Edit freely, but preserve exports that other worktrees depend on. - **single_owner (other owns)**: Do NOT modify. If you need changes, document them in `_deferred/{{WORKTREE_ID}}/request.md`. +`_deferred/` is a temporary merge aid. Do not treat it as final product code. Consolidate its contents during the parent-branch merge, then remove it unless the parent workflow explicitly decides to keep a note for follow-up. + --- ## TERRITORY VIOLATION PROTOCOL diff --git a/src/skills/parallel-split/SKILL.md b/src/skills/parallel-split/SKILL.md index 38b9bef..7fc8bce 100644 --- a/src/skills/parallel-split/SKILL.md +++ b/src/skills/parallel-split/SKILL.md @@ -247,13 +247,15 @@ windows: panes: - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" + - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" - cwd: "" commands: - - exec: " && claude 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" + - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" ``` -Where `` chains the optional Claude Code setup commands from Step 3E. +Where: +- `` chains the optional Claude Code setup commands from Step 3E +- `` is the command used by the host running in that worktree Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` Open: `open "warp://launch/afyapowers%20Parallel"` @@ -308,6 +310,9 @@ After ALL worktrees create WORKTREE_COMPLETE.md: .afyapowers/features//artifacts/plan.md Each worktree updated its assigned task checkboxes in that file. After the merges, confirm every task is [x]. + If git reports a conflict in plan.md because two worktrees marked different tasks, + keep both sets of checkbox updates. Resolve the conflict by preserving every [x] + that came from completed assigned tasks. 4. If every task is [x], run /afyapowers:next to proceed to review If some tasks are still [ ], stay in implement and continue from there diff --git a/src/skills/parallel-split/territory-protocol.md b/src/skills/parallel-split/territory-protocol.md index b61d7dd..04015fd 100644 --- a/src/skills/parallel-split/territory-protocol.md +++ b/src/skills/parallel-split/territory-protocol.md @@ -31,6 +31,8 @@ For each shared file, follow the strategy specified: - **single_owner (you own)**: Edit freely, but preserve exports that other worktrees depend on. - **single_owner (other owns)**: Do NOT modify. If you need changes, document them in `_deferred/{{WORKTREE_ID}}/request.md`. +`_deferred/` is a temporary merge aid. Do not treat it as final product code. Consolidate its contents during the parent-branch merge, then remove it unless the parent workflow explicitly decides to keep a note for follow-up. + --- ## TERRITORY VIOLATION PROTOCOL From da7264591578144773344f859bc02c64f30ea9a1 Mon Sep 17 00:00:00 2001 From: allanbrunoafya Date: Thu, 9 Apr 2026 16:15:12 -0300 Subject: [PATCH 5/6] docs(parallel-split): clarify host launch, merge reconciliation, and shared-file consolidation --- dist/claude/skills/parallel-split/SKILL.md | 9 ++++++++- dist/cursor/skills/afyapowers-parallel-split/SKILL.md | 9 ++++++++- dist/gemini/skills/parallel-split/SKILL.md | 9 ++++++++- dist/github-copilot/skills/parallel-split/SKILL.md | 9 ++++++++- src/skills/parallel-split/SKILL.md | 9 ++++++++- 5 files changed, 40 insertions(+), 5 deletions(-) diff --git a/dist/claude/skills/parallel-split/SKILL.md b/dist/claude/skills/parallel-split/SKILL.md index a6a992b..ac7941e 100644 --- a/dist/claude/skills/parallel-split/SKILL.md +++ b/dist/claude/skills/parallel-split/SKILL.md @@ -304,7 +304,14 @@ After ALL worktrees create WORKTREE_COMPLETE.md: git merge ... - 2. Consolidate deferred files (if any in _deferred/) + 2. Consolidate shared-file follow-up: + - For `_deferred/`, read each worktree contribution and fold the final content + into the real target files on the parent branch + - For `append_only` files, keep additive entries from every worktree + and resolve conflicts by preserving all valid additions + - For `single_owner` files, prefer the designated owner's version unless + the parent merge explicitly reconciles extra changes + - After consolidation, delete `_deferred/` if nothing still needs follow-up 3. Verify the canonical feature plan: .afyapowers/features//artifacts/plan.md diff --git a/dist/cursor/skills/afyapowers-parallel-split/SKILL.md b/dist/cursor/skills/afyapowers-parallel-split/SKILL.md index 983f19b..f383a79 100644 --- a/dist/cursor/skills/afyapowers-parallel-split/SKILL.md +++ b/dist/cursor/skills/afyapowers-parallel-split/SKILL.md @@ -304,7 +304,14 @@ After ALL worktrees create WORKTREE_COMPLETE.md: git merge ... - 2. Consolidate deferred files (if any in _deferred/) + 2. Consolidate shared-file follow-up: + - For `_deferred/`, read each worktree contribution and fold the final content + into the real target files on the parent branch + - For `append_only` files, keep additive entries from every worktree + and resolve conflicts by preserving all valid additions + - For `single_owner` files, prefer the designated owner's version unless + the parent merge explicitly reconciles extra changes + - After consolidation, delete `_deferred/` if nothing still needs follow-up 3. Verify the canonical feature plan: .afyapowers/features//artifacts/plan.md diff --git a/dist/gemini/skills/parallel-split/SKILL.md b/dist/gemini/skills/parallel-split/SKILL.md index 7fc8bce..2dd9aa7 100644 --- a/dist/gemini/skills/parallel-split/SKILL.md +++ b/dist/gemini/skills/parallel-split/SKILL.md @@ -304,7 +304,14 @@ After ALL worktrees create WORKTREE_COMPLETE.md: git merge ... - 2. Consolidate deferred files (if any in _deferred/) + 2. Consolidate shared-file follow-up: + - For `_deferred/`, read each worktree contribution and fold the final content + into the real target files on the parent branch + - For `append_only` files, keep additive entries from every worktree + and resolve conflicts by preserving all valid additions + - For `single_owner` files, prefer the designated owner's version unless + the parent merge explicitly reconciles extra changes + - After consolidation, delete `_deferred/` if nothing still needs follow-up 3. Verify the canonical feature plan: .afyapowers/features//artifacts/plan.md diff --git a/dist/github-copilot/skills/parallel-split/SKILL.md b/dist/github-copilot/skills/parallel-split/SKILL.md index 7fc8bce..2dd9aa7 100644 --- a/dist/github-copilot/skills/parallel-split/SKILL.md +++ b/dist/github-copilot/skills/parallel-split/SKILL.md @@ -304,7 +304,14 @@ After ALL worktrees create WORKTREE_COMPLETE.md: git merge ... - 2. Consolidate deferred files (if any in _deferred/) + 2. Consolidate shared-file follow-up: + - For `_deferred/`, read each worktree contribution and fold the final content + into the real target files on the parent branch + - For `append_only` files, keep additive entries from every worktree + and resolve conflicts by preserving all valid additions + - For `single_owner` files, prefer the designated owner's version unless + the parent merge explicitly reconciles extra changes + - After consolidation, delete `_deferred/` if nothing still needs follow-up 3. Verify the canonical feature plan: .afyapowers/features//artifacts/plan.md diff --git a/src/skills/parallel-split/SKILL.md b/src/skills/parallel-split/SKILL.md index 7fc8bce..2dd9aa7 100644 --- a/src/skills/parallel-split/SKILL.md +++ b/src/skills/parallel-split/SKILL.md @@ -304,7 +304,14 @@ After ALL worktrees create WORKTREE_COMPLETE.md: git merge ... - 2. Consolidate deferred files (if any in _deferred/) + 2. Consolidate shared-file follow-up: + - For `_deferred/`, read each worktree contribution and fold the final content + into the real target files on the parent branch + - For `append_only` files, keep additive entries from every worktree + and resolve conflicts by preserving all valid additions + - For `single_owner` files, prefer the designated owner's version unless + the parent merge explicitly reconciles extra changes + - After consolidation, delete `_deferred/` if nothing still needs follow-up 3. Verify the canonical feature plan: .afyapowers/features//artifacts/plan.md From fc9834bd8cd3c70af4c40991093e0c71c6b167b6 Mon Sep 17 00:00:00 2001 From: allanbrunoafya Date: Thu, 9 Apr 2026 17:03:23 -0300 Subject: [PATCH 6/6] docs(parallel-split): make worktree session launch explicit per host --- dist/claude/skills/parallel-split/SKILL.md | 75 +++++++++++-------- .../skills/afyapowers-parallel-split/SKILL.md | 74 ++++++++++-------- dist/gemini/skills/parallel-split/SKILL.md | 74 ++++++++++-------- .../skills/parallel-split/SKILL.md | 74 ++++++++++-------- src/skills/parallel-split/SKILL.md | 75 +++++++++++-------- 5 files changed, 217 insertions(+), 155 deletions(-) diff --git a/dist/claude/skills/parallel-split/SKILL.md b/dist/claude/skills/parallel-split/SKILL.md index ac7941e..f2a937e 100644 --- a/dist/claude/skills/parallel-split/SKILL.md +++ b/dist/claude/skills/parallel-split/SKILL.md @@ -228,50 +228,63 @@ Append to `history.yaml` under the `events:` key: --- -## Step 6: Launch Terminals +## Step 6: Launch Worktree Sessions -### 6A. Warp (default on macOS) +Launch one agent session per worktree using the host the user is already working in. -Generate Warp Launch Configuration: +### 6A. Cursor -```yaml ---- -name: afyapowers Parallel -windows: - - tabs: - - title: "afyapowers - Worktrees" - layout: - split_direction: vertical - panes: - - split_direction: horizontal - panes: - - cwd: "" - commands: - - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" - - cwd: "" - commands: - - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" +If the user is working in Cursor, including Cursor with a Claude-powered plugin: + +- Open a separate Cursor window or workspace for each worktree +- Do NOT reuse the same Cursor window for multiple worktrees +- In each window, confirm the opened folder is the correct worktree path +- Start the agent in that window +- Tell it to read `PROMPT.md` and execute only the assigned worktree scope + +Example: + +```text +Open in Cursor -> start agent -> "Read PROMPT.md" +Open in Cursor -> start agent -> "Read PROMPT.md" ``` -Where: -- `` chains the optional Claude Code setup commands from Step 3E -- `` is the command used by the host running in that worktree +### 6B. Claude Code -Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` -Open: `open "warp://launch/afyapowers%20Parallel"` +If the user is working in standalone Claude Code: -### 6B. Generic Manual Launch +- Open a separate terminal or Claude Code session for each worktree +- Do NOT reuse the same terminal session for multiple worktrees +- Run each session from the corresponding worktree directory +- Optionally apply the Claude Code setup from Step 3E before starting +- Tell each session to read `PROMPT.md` -If automated launch is unavailable or you are using a non-Claude host, open one agent session per worktree manually and tell it to read `PROMPT.md`. +Example: + +```text +cd && claude +cd && claude +``` + +### 6C. GitHub Copilot / Copilot CLI + +If the user is working through GitHub Copilot or Copilot CLI: + +- Open a separate terminal or agent session for each worktree +- Do NOT reuse the same terminal session for multiple worktrees +- Start each session from the correct worktree path +- Tell each session to read `PROMPT.md` Example: ```text -cd && -cd && +cd && +cd && ``` -Use tmux, Warp, separate terminals, or separate IDE windows according to your host environment. +### 6D. Optional Local Convenience Tools + +Terminal multiplexers or launchers such as tmux, Warp, or IDE tab groups may be used for convenience, but they are optional. They are not part of the architectural contract of this skill. --- @@ -295,7 +308,7 @@ Territory map: territory_map.json Merge order: wt1 → wt2 → wt3 Shared files: (deferred) -Agents launched. +Worktree sessions launched. After ALL worktrees create WORKTREE_COMPLETE.md: diff --git a/dist/cursor/skills/afyapowers-parallel-split/SKILL.md b/dist/cursor/skills/afyapowers-parallel-split/SKILL.md index f383a79..6e6cb80 100644 --- a/dist/cursor/skills/afyapowers-parallel-split/SKILL.md +++ b/dist/cursor/skills/afyapowers-parallel-split/SKILL.md @@ -228,50 +228,62 @@ Append to `history.yaml` under the `events:` key: --- -## Step 6: Launch Terminals +## Step 6: Launch Worktree Sessions -### 6A. Warp (default on macOS) +Launch one agent session per worktree using the host the user is already working in. -Generate Warp Launch Configuration: +### 6A. Cursor -```yaml ---- -name: afyapowers Parallel -windows: - - tabs: - - title: "afyapowers - Worktrees" - layout: - split_direction: vertical - panes: - - split_direction: horizontal - panes: - - cwd: "" - commands: - - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" - - cwd: "" - commands: - - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" +If the user is working in Cursor, including Cursor with a Claude-powered plugin: + +- Open a separate Cursor window or workspace for each worktree +- Do NOT reuse the same Cursor window for multiple worktrees +- In each window, confirm the opened folder is the correct worktree path +- Start the agent in that window +- Tell it to read `PROMPT.md` and execute only the assigned worktree scope + +Example: + +```text +Open in Cursor -> start agent -> "Read PROMPT.md" +Open in Cursor -> start agent -> "Read PROMPT.md" ``` -Where: -- `` chains the optional Claude Code setup commands from Step 3E -- `` is the command used by the host running in that worktree +### 6B. Claude Code -Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` -Open: `open "warp://launch/afyapowers%20Parallel"` +If the user is working in standalone Claude Code: -### 6B. Generic Manual Launch +- Open a separate terminal or Claude Code session for each worktree +- Do NOT reuse the same terminal session for multiple worktrees +- Run each session from the corresponding worktree directory +- Tell each session to read `PROMPT.md` -If automated launch is unavailable or you are using a non-Claude host, open one agent session per worktree manually and tell it to read `PROMPT.md`. +Example: + +```text +cd && claude +cd && claude +``` + +### 6C. GitHub Copilot / Copilot CLI + +If the user is working through GitHub Copilot or Copilot CLI: + +- Open a separate terminal or agent session for each worktree +- Do NOT reuse the same terminal session for multiple worktrees +- Start each session from the correct worktree path +- Tell each session to read `PROMPT.md` Example: ```text -cd && -cd && +cd && +cd && ``` -Use tmux, Warp, separate terminals, or separate IDE windows according to your host environment. +### 6D. Optional Local Convenience Tools + +Terminal multiplexers or launchers such as tmux, Warp, or IDE tab groups may be used for convenience, but they are optional. They are not part of the architectural contract of this skill. --- @@ -295,7 +307,7 @@ Territory map: territory_map.json Merge order: wt1 → wt2 → wt3 Shared files: (deferred) -Agents launched. +Worktree sessions launched. After ALL worktrees create WORKTREE_COMPLETE.md: diff --git a/dist/gemini/skills/parallel-split/SKILL.md b/dist/gemini/skills/parallel-split/SKILL.md index 2dd9aa7..30daceb 100644 --- a/dist/gemini/skills/parallel-split/SKILL.md +++ b/dist/gemini/skills/parallel-split/SKILL.md @@ -228,50 +228,62 @@ Append to `history.yaml` under the `events:` key: --- -## Step 6: Launch Terminals +## Step 6: Launch Worktree Sessions -### 6A. Warp (default on macOS) +Launch one agent session per worktree using the host the user is already working in. -Generate Warp Launch Configuration: +### 6A. Cursor -```yaml ---- -name: afyapowers Parallel -windows: - - tabs: - - title: "afyapowers - Worktrees" - layout: - split_direction: vertical - panes: - - split_direction: horizontal - panes: - - cwd: "" - commands: - - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" - - cwd: "" - commands: - - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" +If the user is working in Cursor, including Cursor with a Claude-powered plugin: + +- Open a separate Cursor window or workspace for each worktree +- Do NOT reuse the same Cursor window for multiple worktrees +- In each window, confirm the opened folder is the correct worktree path +- Start the agent in that window +- Tell it to read `PROMPT.md` and execute only the assigned worktree scope + +Example: + +```text +Open in Cursor -> start agent -> "Read PROMPT.md" +Open in Cursor -> start agent -> "Read PROMPT.md" ``` -Where: -- `` chains the optional Claude Code setup commands from Step 3E -- `` is the command used by the host running in that worktree +### 6B. Claude Code -Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` -Open: `open "warp://launch/afyapowers%20Parallel"` +If the user is working in standalone Claude Code: -### 6B. Generic Manual Launch +- Open a separate terminal or Claude Code session for each worktree +- Do NOT reuse the same terminal session for multiple worktrees +- Run each session from the corresponding worktree directory +- Tell each session to read `PROMPT.md` -If automated launch is unavailable or you are using a non-Claude host, open one agent session per worktree manually and tell it to read `PROMPT.md`. +Example: + +```text +cd && claude +cd && claude +``` + +### 6C. GitHub Copilot / Copilot CLI + +If the user is working through GitHub Copilot or Copilot CLI: + +- Open a separate terminal or agent session for each worktree +- Do NOT reuse the same terminal session for multiple worktrees +- Start each session from the correct worktree path +- Tell each session to read `PROMPT.md` Example: ```text -cd && -cd && +cd && +cd && ``` -Use tmux, Warp, separate terminals, or separate IDE windows according to your host environment. +### 6D. Optional Local Convenience Tools + +Terminal multiplexers or launchers such as tmux, Warp, or IDE tab groups may be used for convenience, but they are optional. They are not part of the architectural contract of this skill. --- @@ -295,7 +307,7 @@ Territory map: territory_map.json Merge order: wt1 → wt2 → wt3 Shared files: (deferred) -Agents launched. +Worktree sessions launched. After ALL worktrees create WORKTREE_COMPLETE.md: diff --git a/dist/github-copilot/skills/parallel-split/SKILL.md b/dist/github-copilot/skills/parallel-split/SKILL.md index 2dd9aa7..30daceb 100644 --- a/dist/github-copilot/skills/parallel-split/SKILL.md +++ b/dist/github-copilot/skills/parallel-split/SKILL.md @@ -228,50 +228,62 @@ Append to `history.yaml` under the `events:` key: --- -## Step 6: Launch Terminals +## Step 6: Launch Worktree Sessions -### 6A. Warp (default on macOS) +Launch one agent session per worktree using the host the user is already working in. -Generate Warp Launch Configuration: +### 6A. Cursor -```yaml ---- -name: afyapowers Parallel -windows: - - tabs: - - title: "afyapowers - Worktrees" - layout: - split_direction: vertical - panes: - - split_direction: horizontal - panes: - - cwd: "" - commands: - - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" - - cwd: "" - commands: - - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" +If the user is working in Cursor, including Cursor with a Claude-powered plugin: + +- Open a separate Cursor window or workspace for each worktree +- Do NOT reuse the same Cursor window for multiple worktrees +- In each window, confirm the opened folder is the correct worktree path +- Start the agent in that window +- Tell it to read `PROMPT.md` and execute only the assigned worktree scope + +Example: + +```text +Open in Cursor -> start agent -> "Read PROMPT.md" +Open in Cursor -> start agent -> "Read PROMPT.md" ``` -Where: -- `` chains the optional Claude Code setup commands from Step 3E -- `` is the command used by the host running in that worktree +### 6B. Claude Code -Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` -Open: `open "warp://launch/afyapowers%20Parallel"` +If the user is working in standalone Claude Code: -### 6B. Generic Manual Launch +- Open a separate terminal or Claude Code session for each worktree +- Do NOT reuse the same terminal session for multiple worktrees +- Run each session from the corresponding worktree directory +- Tell each session to read `PROMPT.md` -If automated launch is unavailable or you are using a non-Claude host, open one agent session per worktree manually and tell it to read `PROMPT.md`. +Example: + +```text +cd && claude +cd && claude +``` + +### 6C. GitHub Copilot / Copilot CLI + +If the user is working through GitHub Copilot or Copilot CLI: + +- Open a separate terminal or agent session for each worktree +- Do NOT reuse the same terminal session for multiple worktrees +- Start each session from the correct worktree path +- Tell each session to read `PROMPT.md` Example: ```text -cd && -cd && +cd && +cd && ``` -Use tmux, Warp, separate terminals, or separate IDE windows according to your host environment. +### 6D. Optional Local Convenience Tools + +Terminal multiplexers or launchers such as tmux, Warp, or IDE tab groups may be used for convenience, but they are optional. They are not part of the architectural contract of this skill. --- @@ -295,7 +307,7 @@ Territory map: territory_map.json Merge order: wt1 → wt2 → wt3 Shared files: (deferred) -Agents launched. +Worktree sessions launched. After ALL worktrees create WORKTREE_COMPLETE.md: diff --git a/src/skills/parallel-split/SKILL.md b/src/skills/parallel-split/SKILL.md index 2dd9aa7..f87917b 100644 --- a/src/skills/parallel-split/SKILL.md +++ b/src/skills/parallel-split/SKILL.md @@ -228,50 +228,63 @@ Append to `history.yaml` under the `events:` key: --- -## Step 6: Launch Terminals +## Step 6: Launch Worktree Sessions -### 6A. Warp (default on macOS) +Launch one agent session per worktree using the host the user is already working in. -Generate Warp Launch Configuration: +### 6A. Cursor -```yaml ---- -name: afyapowers Parallel -windows: - - tabs: - - title: "afyapowers - Worktrees" - layout: - split_direction: vertical - panes: - - split_direction: horizontal - panes: - - cwd: "" - commands: - - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" - - cwd: "" - commands: - - exec: " && 'Read PROMPT.md and implement all assigned tasks following TDD. Create WORKTREE_COMPLETE.md when done.'" +If the user is working in Cursor, including Cursor with a Claude-powered plugin: + +- Open a separate Cursor window or workspace for each worktree +- Do NOT reuse the same Cursor window for multiple worktrees +- In each window, confirm the opened folder is the correct worktree path +- Start the agent in that window +- Tell it to read `PROMPT.md` and execute only the assigned worktree scope + +Example: + +```text +Open in Cursor -> start agent -> "Read PROMPT.md" +Open in Cursor -> start agent -> "Read PROMPT.md" ``` -Where: -- `` chains the optional Claude Code setup commands from Step 3E -- `` is the command used by the host running in that worktree +### 6B. Claude Code -Write to `~/.warp/launch_configurations/afyapowers-parallel.yaml` -Open: `open "warp://launch/afyapowers%20Parallel"` +If the user is working in standalone Claude Code: -### 6B. Generic Manual Launch +- Open a separate terminal or Claude Code session for each worktree +- Do NOT reuse the same terminal session for multiple worktrees +- Run each session from the corresponding worktree directory +- Optionally apply the Claude Code setup from Step 3E before starting +- Tell each session to read `PROMPT.md` -If automated launch is unavailable or you are using a non-Claude host, open one agent session per worktree manually and tell it to read `PROMPT.md`. +Example: + +```text +cd && claude +cd && claude +``` + +### 6C. GitHub Copilot / Copilot CLI + +If the user is working through GitHub Copilot or Copilot CLI: + +- Open a separate terminal or agent session for each worktree +- Do NOT reuse the same terminal session for multiple worktrees +- Start each session from the correct worktree path +- Tell each session to read `PROMPT.md` Example: ```text -cd && -cd && +cd && +cd && ``` -Use tmux, Warp, separate terminals, or separate IDE windows according to your host environment. +### 6D. Optional Local Convenience Tools + +Terminal multiplexers or launchers such as tmux, Warp, or IDE tab groups may be used for convenience, but they are optional. They are not part of the architectural contract of this skill. --- @@ -295,7 +308,7 @@ Territory map: territory_map.json Merge order: wt1 → wt2 → wt3 Shared files: (deferred) -Agents launched. +Worktree sessions launched. After ALL worktrees create WORKTREE_COMPLETE.md: