create-claude-workspace 2.3.38 → 2.3.40

package/dist/template/.claude/agents/orchestrator.md

@@ -195,8 +195,8 @@ Before doing anything, check for unexpected state from user intervention or prev
     - If pipeline failed → resume STEP 9b fix loop.
     - If no pipeline found → proceed to STEP 10 (pipeline may have been cancelled or platform is unreachable).
   - **Crash recovery for STEP 10**: If `currentStep` in `state.json` is `10`:
-    - Check if the feature branch has commits ahead of main. If yes, proceed to STEP 10 (merge from main).
-    - If already merged: clean up worktree and branch.
+    - Check if the feature branch has commits ahead of main. If yes, proceed to STEP 10 (push + cleanup).
+    - If already merged or MR/PR exists: clean up worktree.
   - **Crash recovery for hotfix**: If `currentStep` starts with `hotfix`, resume in hotfix workflow mode (shortened cycle). Re-delegate to architect (same as STEPs 1-10 recovery above), then continue from the hotfix step.
   - `currentWorktree` is set in `state.json` but directory doesn't exist → orphaned reference. Check if the branch was merged (in `git log main`). If merged: task is done, move to next. If not merged but branch exists: recreate worktree `git worktree add {path} {branch}` and resume. If branch is gone: move to next task.
 - **Orphaned worktrees**: `git worktree list` — if there are worktrees not referenced by `state.json`:
@@ -371,8 +371,8 @@ If `PLAN.md` exists in the project root, check whether it changed since the last
 ### 13. One task per invocation — FULL CYCLE required
 - Complete exactly ONE task per invocation, then end the session cleanly.
 - The external loop (`autonomous.mjs` or ralph-loop) handles iteration control — you do NOT need to manage capacity, iteration counters, or session bounds.
-- **CRITICAL: You MUST execute the FULL cycle: STEP 9 → STEP 9b → STEP 10 → EXIT.** Do NOT exit after STEP 9. Creating an MR/PR is NOT the end — you must watch the CI pipeline (9b), read MR/PR comments, fix issues, and merge (10). Only EXIT after STEP 10 is complete (merge done, worktree cleaned up).
-- After merge (STEP 10), EXIT. Do NOT ask whether to continue, do NOT wait for confirmation, do NOT start another task. Do NOT create any commits after merge.
+- **CRITICAL: You MUST execute the FULL cycle: STEP 9 → STEP 9b → STEP 10 → EXIT.** Do NOT exit after STEP 9. Creating an MR/PR is NOT the end — you MUST watch the CI pipeline (9b), fix any failures, and only then clean up (10). Exiting without watching CI is a bug — the whole point is to ensure the MR/PR is green before handing off.
+- After STEP 10, EXIT. Do NOT ask whether to continue, do NOT wait for confirmation, do NOT start another task. Do NOT create any commits after cleanup.
 - Complexity tracking (S=1, M=2, L=4) is handled by the scheduler in `state.json`.
 
 ### 14. User input during autonomous operation
@@ -690,7 +690,7 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
 - **→ PROCEED TO STEP 9b** (do NOT exit here — MR/PR creation is NOT the end of the cycle)
 
 **STEP 9b: CI PIPELINE WATCH & MR/PR REVIEW** (only if git integration active AND remote push succeeded)
-- **Skip conditions**: no remote, no push happened, local-only mode, team workflow (team doesn't merge — CI runs on MR/PR, reviewed by humans)
+- **Skip conditions**: no remote, no push happened, local-only mode
 - **Wait for pipeline to start** (max 60s polling):
   ```bash
   # GitHub — wait for workflow run to appear, capture run ID
@@ -755,67 +755,56 @@ To determine if a task is frontend, backend, or fullstack, use this heuristic:
      - If architect confirms environment issue → proceed to STEP 10 with local merge fallback, log blocker
      - If still failing → proceed to STEP 10 with local merge fallback
 - **Note**: `--force-with-lease` is safe here because we own the branch and just pushed it. The MR/PR stays open and updates automatically.
-- **→ PROCEED TO STEP 10** (do NOT exit here — the MR/PR must be MERGED before exiting)
+- **→ PROCEED TO STEP 10**
 
-**STEP 10: POST-MERGE & NEXT ITEM**
+**STEP 10: POST-TASK CLEANUP & NEXT ITEM**
 - Everything was committed in STEP 9 inside the worktree.
-- **ZERO commits in this step** — all tracking was already committed in STEP 9. This step only performs git operations (merge, worktree cleanup, push) and delegates issue status updates.
-- **Solo workflow** (CLAUDE.md `Workflow: solo` or default):
+- **ZERO commits in this step** — all tracking was already committed in STEP 9. This step only performs git operations (cleanup, push) and delegates issue status updates.
+
+- **When running via scheduler** (`state.json` exists): The scheduler handles merge, worktree cleanup, and branch deletion. Orchestrator only ensures final push and exits.
+
+- **When running directly** (`claude --agent orchestrator` or ralph-loop):
+
   - **If git integration active** (MR/PR was created in STEP 9):
     - Ensure latest commit is pushed from worktree:
       ```bash
       git -C {worktree-path} push origin HEAD
       ```
-    - Merge via platform to properly close the MR/PR (CI should have passed in STEP 9b — if merge still fails due to checks, use local merge fallback below):
-      ```bash
-      # GitHub
-      gh pr merge --merge --delete-branch
-      # GitLab
-      glab mr merge --remove-source-branch
-      ```
-    - Then sync local main:
-      ```bash
-      git pull --rebase origin HEAD
-      ```
-    - Clean up worktree and branch:
+    - **Do NOT merge the MR/PR.** Leave it open for CI to pass and (optionally) human review. The MR/PR will be merged externally (by the user, by CI auto-merge, or by the scheduler in a future run).
+    - Clean up worktree only (branch stays for MR/PR):
       ```bash
       git worktree remove .worktrees/feat/{slug}
-      git branch -d feat/{slug} 2>/dev/null || true
       ```
-    - Delegate to `devops-integrator`: "Update issue #N status to done. Do NOT perform any git operations or file edits — already handled."
-  - **If no git integration** (no MR/PR):
-    - If remote exists: `git pull --rebase origin HEAD` before merge
+    - Sync main: `git pull --rebase origin HEAD`
+    - If git integration active: delegate to `devops-integrator`: "Update issue #N status to in-review. Do NOT perform any git operations."
+    - **Track the open MR/PR branch** — remember `feat/{slug}` for branch stacking (see below).
+
+  - **If no git integration** (no MR/PR, no remote):
     - Merge locally (from project root, which is on main):
       ```bash
       git merge feat/{slug} --no-ff
       ```
     - If merge fails due to conflicts: follow the "Merge Conflicts" section below, then retry
-    - If remote exists: `git push origin HEAD` after merge. If push fails (branch protection, auth): log blocker, leave commit local.
-    - If no remote: skip pull/push (local-only mode)
     - Clean up worktree and branch:
       ```bash
       git worktree remove .worktrees/feat/{slug}
       git branch -d feat/{slug}
       ```
-  - If platform merge fails (auth, permissions, branch protection):
-    - Fall back to local merge (same as no-git-integration path above)
-    - Delegate to `devops-integrator`: "Update issue #N status to done. Do NOT perform any git operations or file edits — already handled."
-- **Team workflow** (CLAUDE.md `Workflow: team`):
-  - If remote exists: push from worktree: `git -C {worktree-path} push origin HEAD`
-  - Clean up worktree (branch stays for MR/PR review):
+
+- **Branch stacking for dependent tasks**:
+  - If the next task depends on changes from a previous unmerged MR/PR, create worktree from the previous branch (not from main):
     ```bash
-    git worktree remove .worktrees/feat/{slug}
+    git worktree add .worktrees/feat/{next} -b feat/{next} feat/{previous}
     ```
-  - If remote exists: sync main: `git pull --rebase origin HEAD`
-  - If git integration active: delegate to `devops-integrator`: "Update issue #N status to in-review. Do NOT perform any git operations."
-  - Next task: if the next task depends on the previous (unmerged) MR/PR, create worktree from previous branch:
+  - This is "branch stacking" — the new branch builds on top of the unmerged one.
+  - When the previous MR/PR is eventually merged into main, rebase the stacked branch:
     ```bash
-    git worktree add .worktrees/feat/{next} -b feat/{next} feat/{previous}
+    git -C .worktrees/feat/{next} rebase --onto main feat/{previous}
     ```
-    Note the stacking. When the previous MR/PR is merged: `git -C .worktrees/feat/{next} rebase --onto main feat/{previous}`
+  - If the next task does NOT depend on the previous MR/PR, create worktree from main as usual.
 - **If no `[ ]` tasks remain in current phase AND at least one `[~]` exists** (all remaining were skipped): do NOT auto-advance. Delegate to `product-owner`: "All tasks in Phase [N] are blocked/skipped. The autonomous loop cannot proceed. Options: (1) ADD replacement tasks that unblock progress, (2) REPRIORITIZE to skip this phase entirely and move to next, (3) declare a BLOCKER requiring human intervention." If product-owner returns only CONFIRM with no actionable changes, STOP the autonomous loop and log: "Phase [N] fully blocked — requires human intervention. Run orchestrator manually after resolving blockers."
 - **→ EXIT NOW.** One task per invocation — STEP 10 is complete, end session. The external loop will start the next invocation.
-- **CRITICAL: ZERO commits after merge.** Do NOT `git add`, do NOT `git commit`, do NOT create `chore:` commits after the merge.
+- **CRITICAL: ZERO commits after STEP 10.** Do NOT `git add`, do NOT `git commit`, do NOT create `chore:` commits after cleanup.
 - **If no `[ ]` tasks remain in current phase AND zero `[~]` exist** (all completed) -> phase transition (handled at start of STEP 1)
 - **If no `[ ]` tasks remain in ALL phases AND zero `[~]` exist** (everything completed):
   - **Pre-completion check**: Run `git status --short` — if there are uncommitted/untracked source files (excluding `.env`, `node_modules/`, `.claude/autonomous-state.json`), do NOT enter completion sequence. These files represent unfinished work. Create a task to review and commit them, then continue STEP 1.
@@ -844,7 +833,7 @@ For critical production bugs (outside normal TODO.md flow):
 5. If reviewer finds CRITICAL or WARN issues: fix them and re-review (max 2 cycles for hotfixes). If still failing, commit anyway — hotfix urgency takes priority.
 6. Commit & push from worktree (STEP 9) — include in the SAME commit:
    - Do NOT update TODO.md checkboxes unless the fix corresponds to an existing task
-7. Post-merge: follow STEP 10 logic (merge to main from project root, clean up worktree + branch). No additional commits.
+7. Post-task: follow STEP 10 logic (push, create MR/PR if git integration active, clean up worktree). No additional commits.
 8. **Patch release**: if git integration active, delegate to `devops-integrator`: "Hotfix merged. Create a patch release with changelog." If CLAUDE.md has `Distribution: npm`, follow the same publish verification logic as phase transition (watch CI pipeline, verify `npm view`, fall back to direct publish on failure).
 
 **Skipped steps:** STEP 4 (tests — unless the bug reveals missing test coverage), STEP 5 (visual verification).
@@ -863,13 +852,17 @@ If a merge conflict occurs:
 5. If rebase is too complex: `cd {worktree-path} && git merge origin/main` instead (creates merge commit but is safer)
 6. Log the conflict resolution
 
-**During `git merge feat/branch` on main** (STEP 10, from project root):
+**During `git merge feat/branch` on main** (STEP 10, local merge only — no git integration):
 1. Resolve the conflict in the merge commit (do NOT rebase here — you are on main)
 2. `git add [resolved files]` (only resolved files — do NOT use `git add .`), then `git merge --continue`
 3. Verify the merged result: build, lint, test from project root
 4. Push: `git push origin HEAD`
 5. Then clean up: `git worktree remove .worktrees/feat/{slug} && git branch -d feat/{slug}`
 
+**During rebase in worktree** (branch stacking or MR/PR conflict):
+1. Resolve conflicts in the worktree: `git -C {worktree-path} add [resolved files]`, then `git -C {worktree-path} rebase --continue`
+2. Force-push the rebased branch: `git -C {worktree-path} push --force-with-lease`
+
 ## Proactive Problem Resolution
 
 All agents have access to a `report_issue` tool provided by the scheduler. When an agent encounters a problem outside its current task scope, it calls this tool to create a tracked issue. The scheduler picks it up on the next iteration and routes it through the normal pipeline.
@@ -914,6 +907,15 @@ Examples:
 - CI unfixable: `status: completed, action: ci_needs_config, message: "CI pipeline failed — missing NODE_AUTH_TOKEN secret. Task merged locally (fallback).", task_completed: "#42 User auth", next_task: "#43 Dashboard"`
 - Blocked: `status: blocked, action: needs_user_decision, message: "Task #15 requires API design decision — REST vs GraphQL. Cannot proceed without guidance."`
 
+## Research First — Then Implement (STRICT)
+
+Before solving any problem, agents MUST research whether a correct/proper solution exists:
+1. **Read documentation** — check official docs, existing code patterns, API references
+2. **Verify assumptions** — grep for existing implementations, check library APIs, read types
+3. **Only then implement** — using the verified correct approach
+
+Never guess or implement a workaround when a proper solution might exist. If unsure, delegate research to the relevant specialist agent before proceeding.
+
 ## No Workarounds — Fix the Root Cause (STRICT)
 
 When a tool, library, or process fails (e.g., `nx release`, `nx build`, a @cibule/* package, a generator), **fix the underlying issue** instead of bypassing it with a workaround. For example:
@@ -972,7 +974,7 @@ After handling the user's message, resume the development cycle from where you l
 - NEVER implement without architect plan (STEP 2) or skip code review (STEP 6)
 - Each commit = 1 logical unit
 - Conventional commits: feat/fix/refactor/chore/docs
-- **ABSOLUTE BAN: NEVER create commits that only change tracking files.** TODO.md changes (local mode) are committed WITH implementation code in STEP 9. After merge (STEP 10), ZERO commits. Forbidden patterns: `chore: update progress tracking`, `chore: update TODO.md`. If TODO.md shows as modified after merge, something went wrong in STEP 9 — investigate and fix, do NOT create a band-aid commit.
+- **ABSOLUTE BAN: NEVER create commits that only change tracking files.** TODO.md changes (local mode) are committed WITH implementation code in STEP 9. After STEP 10, ZERO commits. Forbidden patterns: `chore: update progress tracking`, `chore: update TODO.md`. If TODO.md shows as modified after cleanup, something went wrong in STEP 9 — investigate and fix, do NOT create a band-aid commit.
 - All files in ENGLISH
 - TODO.md is your task tracking system (local mode) — keep it PRECISE and CURRENT
 - **NEVER add `eslint-disable` comments** (inline, next-line, or block). Fix the actual code instead. If a lint rule cannot be satisfied, restructure the code — do not suppress the warning.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-workspace",
-  "version": "2.3.38",
+  "version": "2.3.40",
   "author": "",
   "repository": {
     "type": "git",