diff --git a/dist/claude/skills/implementing/SKILL.md b/dist/claude/skills/implementing/SKILL.md index b79bef6..3cdda52 100644 --- a/dist/claude/skills/implementing/SKILL.md +++ b/dist/claude/skills/implementing/SKILL.md @@ -30,7 +30,57 @@ Otherwise (direct invocation): - 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 + - 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 **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 new file mode 100644 index 0000000..f2a937e --- /dev/null +++ b/dist/claude/skills/parallel-split/SKILL.md @@ -0,0 +1,347 @@ +--- +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 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 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. + +--- + +## 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 + +### 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. 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 +- 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 + +### 3A. Copy canonical plan.md + +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) +4. Preserve all step details, file lists, and Figma metadata + +Save to `${WT_PATH}/TASK_SCOPE.md` + +### 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" +``` + +### 3D. Generate PROMPT.md with territory rules + +Read `skills/parallel-split/territory-protocol.md` as template. Replace placeholders with this group's territory data. + +Write to `${WT_PATH}/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: + +## Instructions + +1. Read this file completely +2. Read `DESIGN_CONTEXT.md` for the full design spec +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 + +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. 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)" +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_PATH}/.claude" && cp ".claude/settings.local.json" "${WT_PATH}/.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": "", + "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//`: + +Append to `history.yaml` under the `events:` key: + +```yaml + - timestamp: "" + event: parallel_split + phase: implement + details: "Split into parallel worktrees: " + command: parallel-split +``` + +--- + +## Step 6: Launch Worktree Sessions + +Launch one agent session per worktree using the host the user is already working in. + +### 6A. Cursor + +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" +``` + +### 6B. Claude Code + +If the user is working in standalone Claude Code: + +- 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` + +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 && +``` + +### 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. + +--- + +## Step 7: Display Summary and Post-Merge Instructions + +``` +Parallel Split — Implement Phase + +Feature: +Worktrees: +Territory map: territory_map.json + + wt1 (Tasks ): + Owns: + Branch: + + wt2 (Tasks ): + Owns: + Branch: + +Merge order: wt1 → wt2 → wt3 +Shared files: (deferred) + +Worktree sessions launched. + +After ALL worktrees create WORKTREE_COMPLETE.md: + + 1. Merge in order: + git merge + git merge + ... + + 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 + 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 + + 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:** 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/claude/skills/parallel-split/territory-protocol.md b/dist/claude/skills/parallel-split/territory-protocol.md new file mode 100644 index 0000000..04015fd --- /dev/null +++ b/dist/claude/skills/parallel-split/territory-protocol.md @@ -0,0 +1,57 @@ +# Territory Protocol for Parallel Worktrees + +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. + +--- + +## 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`. + +`_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 + +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 + +--- + +## SCOPE: IMPLEMENT ONLY + +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 + +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/skills/afyapowers-implementing/SKILL.md b/dist/cursor/skills/afyapowers-implementing/SKILL.md index 79f7e49..d7fc33b 100644 --- a/dist/cursor/skills/afyapowers-implementing/SKILL.md +++ b/dist/cursor/skills/afyapowers-implementing/SKILL.md @@ -29,7 +29,57 @@ Otherwise (direct invocation): - 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 + - 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 **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 new file mode 100644 index 0000000..6e6cb80 --- /dev/null +++ b/dist/cursor/skills/afyapowers-parallel-split/SKILL.md @@ -0,0 +1,346 @@ +--- +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 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 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. + +--- + +## 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 + +### 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. 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 +- 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 + +### 3A. Copy canonical plan.md + +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) +4. Preserve all step details, file lists, and Figma metadata + +Save to `${WT_PATH}/TASK_SCOPE.md` + +### 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" +``` + +### 3D. Generate PROMPT.md with territory rules + +Read `skills/parallel-split/territory-protocol.md` as template. Replace placeholders with this group's territory data. + +Write to `${WT_PATH}/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: + +## Instructions + +1. Read this file completely +2. Read `DESIGN_CONTEXT.md` for the full design spec +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 + +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. 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)" +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_PATH}/.claude" && cp ".claude/settings.local.json" "${WT_PATH}/.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": "", + "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//`: + +Append to `history.yaml` under the `events:` key: + +```yaml + - timestamp: "" + event: parallel_split + phase: implement + details: "Split into parallel worktrees: " + command: parallel-split +``` + +--- + +## Step 6: Launch Worktree Sessions + +Launch one agent session per worktree using the host the user is already working in. + +### 6A. Cursor + +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" +``` + +### 6B. Claude Code + +If the user is working in standalone Claude Code: + +- 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` + +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 && +``` + +### 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. + +--- + +## Step 7: Display Summary and Post-Merge Instructions + +``` +Parallel Split — Implement Phase + +Feature: +Worktrees: +Territory map: territory_map.json + + wt1 (Tasks ): + Owns: + Branch: + + wt2 (Tasks ): + Owns: + Branch: + +Merge order: wt1 → wt2 → wt3 +Shared files: (deferred) + +Worktree sessions launched. + +After ALL worktrees create WORKTREE_COMPLETE.md: + + 1. Merge in order: + git merge + git merge + ... + + 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 + 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 + + 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:** 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-parallel-split/territory-protocol.md b/dist/cursor/skills/afyapowers-parallel-split/territory-protocol.md new file mode 100644 index 0000000..04015fd --- /dev/null +++ b/dist/cursor/skills/afyapowers-parallel-split/territory-protocol.md @@ -0,0 +1,57 @@ +# Territory Protocol for Parallel Worktrees + +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. + +--- + +## 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`. + +`_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 + +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 + +--- + +## SCOPE: IMPLEMENT ONLY + +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 + +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/skills/implementing/SKILL.md b/dist/gemini/skills/implementing/SKILL.md index 8b1c910..73018b7 100644 --- a/dist/gemini/skills/implementing/SKILL.md +++ b/dist/gemini/skills/implementing/SKILL.md @@ -24,7 +24,57 @@ Otherwise (direct invocation): - 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 + - 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 **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 new file mode 100644 index 0000000..30daceb --- /dev/null +++ b/dist/gemini/skills/parallel-split/SKILL.md @@ -0,0 +1,346 @@ +--- +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 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 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. + +--- + +## 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 + +### 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. 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 +- 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 + +### 3A. Copy canonical plan.md + +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) +4. Preserve all step details, file lists, and Figma metadata + +Save to `${WT_PATH}/TASK_SCOPE.md` + +### 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" +``` + +### 3D. Generate PROMPT.md with territory rules + +Read `skills/parallel-split/territory-protocol.md` as template. Replace placeholders with this group's territory data. + +Write to `${WT_PATH}/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: + +## Instructions + +1. Read this file completely +2. Read `DESIGN_CONTEXT.md` for the full design spec +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 + +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. 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)" +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_PATH}/.claude" && cp ".claude/settings.local.json" "${WT_PATH}/.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": "", + "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//`: + +Append to `history.yaml` under the `events:` key: + +```yaml + - timestamp: "" + event: parallel_split + phase: implement + details: "Split into parallel worktrees: " + command: parallel-split +``` + +--- + +## Step 6: Launch Worktree Sessions + +Launch one agent session per worktree using the host the user is already working in. + +### 6A. Cursor + +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" +``` + +### 6B. Claude Code + +If the user is working in standalone Claude Code: + +- 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` + +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 && +``` + +### 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. + +--- + +## Step 7: Display Summary and Post-Merge Instructions + +``` +Parallel Split — Implement Phase + +Feature: +Worktrees: +Territory map: territory_map.json + + wt1 (Tasks ): + Owns: + Branch: + + wt2 (Tasks ): + Owns: + Branch: + +Merge order: wt1 → wt2 → wt3 +Shared files: (deferred) + +Worktree sessions launched. + +After ALL worktrees create WORKTREE_COMPLETE.md: + + 1. Merge in order: + git merge + git merge + ... + + 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 + 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 + + 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:** 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/parallel-split/territory-protocol.md b/dist/gemini/skills/parallel-split/territory-protocol.md new file mode 100644 index 0000000..04015fd --- /dev/null +++ b/dist/gemini/skills/parallel-split/territory-protocol.md @@ -0,0 +1,57 @@ +# Territory Protocol for Parallel Worktrees + +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. + +--- + +## 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`. + +`_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 + +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 + +--- + +## SCOPE: IMPLEMENT ONLY + +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 + +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/skills/implementing/SKILL.md b/dist/github-copilot/skills/implementing/SKILL.md index 84f91af..e5b873c 100644 --- a/dist/github-copilot/skills/implementing/SKILL.md +++ b/dist/github-copilot/skills/implementing/SKILL.md @@ -28,7 +28,57 @@ Otherwise (direct invocation): - 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 + - 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 **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 new file mode 100644 index 0000000..30daceb --- /dev/null +++ b/dist/github-copilot/skills/parallel-split/SKILL.md @@ -0,0 +1,346 @@ +--- +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 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 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. + +--- + +## 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 + +### 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. 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 +- 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 + +### 3A. Copy canonical plan.md + +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) +4. Preserve all step details, file lists, and Figma metadata + +Save to `${WT_PATH}/TASK_SCOPE.md` + +### 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" +``` + +### 3D. Generate PROMPT.md with territory rules + +Read `skills/parallel-split/territory-protocol.md` as template. Replace placeholders with this group's territory data. + +Write to `${WT_PATH}/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: + +## Instructions + +1. Read this file completely +2. Read `DESIGN_CONTEXT.md` for the full design spec +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 + +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. 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)" +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_PATH}/.claude" && cp ".claude/settings.local.json" "${WT_PATH}/.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": "", + "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//`: + +Append to `history.yaml` under the `events:` key: + +```yaml + - timestamp: "" + event: parallel_split + phase: implement + details: "Split into parallel worktrees: " + command: parallel-split +``` + +--- + +## Step 6: Launch Worktree Sessions + +Launch one agent session per worktree using the host the user is already working in. + +### 6A. Cursor + +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" +``` + +### 6B. Claude Code + +If the user is working in standalone Claude Code: + +- 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` + +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 && +``` + +### 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. + +--- + +## Step 7: Display Summary and Post-Merge Instructions + +``` +Parallel Split — Implement Phase + +Feature: +Worktrees: +Territory map: territory_map.json + + wt1 (Tasks ): + Owns: + Branch: + + wt2 (Tasks ): + Owns: + Branch: + +Merge order: wt1 → wt2 → wt3 +Shared files: (deferred) + +Worktree sessions launched. + +After ALL worktrees create WORKTREE_COMPLETE.md: + + 1. Merge in order: + git merge + git merge + ... + + 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 + 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 + + 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:** 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/parallel-split/territory-protocol.md b/dist/github-copilot/skills/parallel-split/territory-protocol.md new file mode 100644 index 0000000..04015fd --- /dev/null +++ b/dist/github-copilot/skills/parallel-split/territory-protocol.md @@ -0,0 +1,57 @@ +# Territory Protocol for Parallel Worktrees + +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. + +--- + +## 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`. + +`_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 + +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 + +--- + +## SCOPE: IMPLEMENT ONLY + +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 + +When all tasks are done, create `WORKTREE_COMPLETE.md` and stop. The parent branch handles review and completion after merge. diff --git a/src/skills/implementing/SKILL.md b/src/skills/implementing/SKILL.md index 435fe42..e11b300 100644 --- a/src/skills/implementing/SKILL.md +++ b/src/skills/implementing/SKILL.md @@ -38,7 +38,57 @@ Otherwise (direct invocation): - 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 + - 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 **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 new file mode 100644 index 0000000..f87917b --- /dev/null +++ b/src/skills/parallel-split/SKILL.md @@ -0,0 +1,347 @@ +--- +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 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 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. + +--- + +## 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 + +### 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. 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 +- 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 + +### 3A. Copy canonical plan.md + +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) +4. Preserve all step details, file lists, and Figma metadata + +Save to `${WT_PATH}/TASK_SCOPE.md` + +### 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" +``` + +### 3D. Generate PROMPT.md with territory rules + +Read `skills/parallel-split/territory-protocol.md` as template. Replace placeholders with this group's territory data. + +Write to `${WT_PATH}/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: + +## Instructions + +1. Read this file completely +2. Read `DESIGN_CONTEXT.md` for the full design spec +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 + +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. 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)" +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_PATH}/.claude" && cp ".claude/settings.local.json" "${WT_PATH}/.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": "", + "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//`: + +Append to `history.yaml` under the `events:` key: + +```yaml + - timestamp: "" + event: parallel_split + phase: implement + details: "Split into parallel worktrees: " + command: parallel-split +``` + +--- + +## Step 6: Launch Worktree Sessions + +Launch one agent session per worktree using the host the user is already working in. + +### 6A. Cursor + +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" +``` + +### 6B. Claude Code + +If the user is working in standalone Claude Code: + +- 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` + +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 && +``` + +### 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. + +--- + +## Step 7: Display Summary and Post-Merge Instructions + +``` +Parallel Split — Implement Phase + +Feature: +Worktrees: +Territory map: territory_map.json + + wt1 (Tasks ): + Owns: + Branch: + + wt2 (Tasks ): + Owns: + Branch: + +Merge order: wt1 → wt2 → wt3 +Shared files: (deferred) + +Worktree sessions launched. + +After ALL worktrees create WORKTREE_COMPLETE.md: + + 1. Merge in order: + git merge + git merge + ... + + 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 + 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 + + 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:** 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/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..04015fd --- /dev/null +++ b/src/skills/parallel-split/territory-protocol.md @@ -0,0 +1,57 @@ +# Territory Protocol for Parallel Worktrees + +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. + +--- + +## 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`. + +`_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 + +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 + +--- + +## SCOPE: IMPLEMENT ONLY + +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 + +When all tasks are done, create `WORKTREE_COMPLETE.md` and stop. The parent branch handles review and completion after merge.