From de46a17d00d175daccc7b828821b5e19cb0a75ac Mon Sep 17 00:00:00 2001
From: A <258483684+la14-1@users.noreply.github.com>
Date: Mon, 9 Feb 2026 22:16:27 -0800
Subject: [PATCH] docs: Add refactoring service architecture guide to CLAUDE.md
 (#158)

Documents the dual-mode cycle system (issue vs refactor), concurrency
model, worktree isolation, and guidance for modifying the service.
Also adds trigger service files to the file structure convention.

Co-authored-by: A <6723574+louisgv@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index dcea9974..a11a706d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -110,6 +110,12 @@ spawn/
   {cloud}/
     lib/common.sh                # Cloud-specific functions (sources shared/common.sh)
     {agent}.sh                   # Agent deployment scripts
+  .claude/skills/setup-trigger-service/
+    trigger-server.ts            # HTTP trigger server (concurrent runs, dedup)
+    refactor.sh                  # Dual-mode cycle script (issue fix or full refactor)
+    start-refactor.sh            # Launcher with secrets (gitignored)
+  .github/workflows/
+    refactor.yml                 # Scheduled + issue-triggered workflow
   manifest.json                  # The matrix (source of truth)
   improve.sh                     # Run this to trigger one improvement cycle
   test/run.sh                    # Test harness
@@ -242,6 +248,50 @@ When running autonomous improvement/refactoring loops (`./improve.sh --loop`):
 - **Test after EACH iteration** — don't batch multiple changes without verification
 - **If a change breaks tests, STOP** — revert and ask for guidance rather than compounding the regression
 
+## Refactoring Service
+
+The automated refactoring service runs via `.claude/skills/setup-trigger-service/`. It is triggered by GitHub Actions (on schedule, on issue open, or manual dispatch).
+
+### Architecture
+
+```
+trigger-server.ts   — HTTP server (port 8080), spawns refactor.sh per trigger
+start-refactor.sh   — Sets env vars (secrets, MAX_CONCURRENT), execs trigger-server
+refactor.sh         — Dual-mode: issue fix or full refactor cycle
+refactor.yml        — GitHub Actions workflow that POSTs to the trigger server
+```
+
+### Dual-Mode Cycles
+
+`refactor.sh` detects its mode from the `SPAWN_ISSUE` env var (set by trigger-server.ts):
+
+| | Issue Mode | Refactor Mode |
+|---|---|---|
+| **Trigger** | `?reason=issues&issue=N` | `?reason=schedule` |
+| **Agents** | 2 (issue-fixer, issue-tester) | 6 (security, ux, complexity, test, branch, community) |
+| **Prompt timeout** | 15 min | 30 min |
+| **Hard timeout** | 20 min | 40 min |
+| **Worktree** | `/tmp/spawn-worktrees/issue-N/` | `/tmp/spawn-worktrees/refactor/` |
+| **Team name** | `spawn-issue-N` | `spawn-refactor` |
+| **Pre-cycle cleanup** | Skip | Branch/PR/worktree cleanup |
+| **Post-cycle commit** | Skip (uses PR workflow) | Direct commit to main |
+
+### Concurrency
+
+- `MAX_CONCURRENT=3` allows 1 refactor + 2 issue runs simultaneously
+- Each run gets an isolated worktree — no cross-contamination
+- Cleanup only touches its own worktree, never `rm -rf /tmp/spawn-worktrees`
+- Duplicate issue triggers (same issue number already running) return **409 Conflict**
+- Capacity full returns **429 Too Many Requests**
+
+### Modifying the Service
+
+- `start-refactor.sh` is **gitignored** (contains `TRIGGER_SECRET`) — edit locally only
+- `trigger-server.ts` and `refactor.sh` are committed — changes require a PR
+- After merging changes, restart the service for them to take effect
+- The refactor prompt uses `WORKTREE_BASE_PLACEHOLDER` which gets `sed`-substituted at runtime
+- Issue prompt uses heredoc variable expansion directly (not single-quoted)
+
 ## Git Workflow
 
 - Always work on a feature branch — never commit directly to main (except urgent one-line fixes)