oh-my-customcode 0.81.0 → 0.83.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -235,7 +235,7 @@ Key rules: R010 (orchestrator never writes files), R009 (parallel execution mand
235
235
 
236
236
  ---
237
237
 
238
- ### Guides (33)
238
+ ### Guides (36)
239
239
 
240
240
  Reference documentation covering best practices, architecture decisions, and integration patterns. Located in `guides/` at project root, covering topics from agent design to CI/CD to observability.
241
241
 
@@ -292,7 +292,7 @@ your-project/
292
292
  │ ├── specs/ # Extracted canonical specs
293
293
  │ ├── contexts/ # 4 shared context files
294
294
  │ └── ontology/ # Knowledge graph for RAG
295
- └── guides/ # 33 reference documents
295
+ └── guides/ # 36 reference documents
296
296
  ```
297
297
 
298
298
  ---
package/dist/cli/index.js CHANGED
@@ -2301,7 +2301,7 @@ var init_package = __esm(() => {
2301
2301
  workspaces: [
2302
2302
  "packages/*"
2303
2303
  ],
2304
- version: "0.81.0",
2304
+ version: "0.83.0",
2305
2305
  description: "Batteries-included agent harness for Claude Code",
2306
2306
  type: "module",
2307
2307
  bin: {
@@ -28047,7 +28047,8 @@ async function installSettingsLocal(targetDir, result) {
28047
28047
  statusLine: {
28048
28048
  type: "command",
28049
28049
  command: ".claude/statusline.sh",
28050
- padding: 0
28050
+ padding: 0,
28051
+ refreshInterval: 10
28051
28052
  }
28052
28053
  };
28053
28054
  if (await fileExists(settingsPath)) {
package/dist/index.js CHANGED
@@ -1654,7 +1654,8 @@ async function installSettingsLocal(targetDir, result) {
1654
1654
  statusLine: {
1655
1655
  type: "command",
1656
1656
  command: ".claude/statusline.sh",
1657
- padding: 0
1657
+ padding: 0,
1658
+ refreshInterval: 10
1658
1659
  }
1659
1660
  };
1660
1661
  if (await fileExists(settingsPath)) {
@@ -1973,7 +1974,7 @@ var package_default = {
1973
1974
  workspaces: [
1974
1975
  "packages/*"
1975
1976
  ],
1976
- version: "0.81.0",
1977
+ version: "0.83.0",
1977
1978
  description: "Batteries-included agent harness for Claude Code",
1978
1979
  type: "module",
1979
1980
  bin: {
package/package.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "workspaces": [
4
4
  "packages/*"
5
5
  ],
6
- "version": "0.81.0",
6
+ "version": "0.83.0",
7
7
  "description": "Batteries-included agent harness for Claude Code",
8
8
  "type": "module",
9
9
  "bin": {
@@ -165,6 +165,16 @@
165
165
  }
166
166
  ],
167
167
  "description": "Lightweight project profile staleness check for adaptive harness (#831)"
168
+ },
169
+ {
170
+ "matcher": "*",
171
+ "hooks": [
172
+ {
173
+ "type": "command",
174
+ "command": "bash .claude/hooks/scripts/session-autofix.sh"
175
+ }
176
+ ],
177
+ "description": "Auto-detect and fix previous session issues at start (#838)"
168
178
  }
169
179
  ],
170
180
  "UserPromptSubmit": [
@@ -177,6 +187,16 @@
177
187
  }
178
188
  ],
179
189
  "description": "Advisory pre-processing of user input — skill matching hints and intent analysis"
190
+ },
191
+ {
192
+ "matcher": "*",
193
+ "hooks": [
194
+ {
195
+ "type": "prompt",
196
+ "command": "bash .claude/hooks/scripts/session-autofix-prompt.sh"
197
+ }
198
+ ],
199
+ "description": "Inject session auto-fix findings into first user prompt (#838)"
180
200
  }
181
201
  ],
182
202
  "SubagentStart": [
@@ -0,0 +1,34 @@
1
+ #!/bin/bash
2
+ # Session Auto-Fix Prompt — UserPromptSubmit prompt hook (#838)
3
+ # One-shot: reads SessionStart findings and injects into first user prompt.
4
+ # Protocol: stdout text -> injected into model context
5
+
6
+ FIXES_FILE="/tmp/.claude-session-fixes-${PPID}"
7
+
8
+ # Only fire if findings exist (one-shot)
9
+ if [ ! -f "$FIXES_FILE" ]; then
10
+ exit 0
11
+ fi
12
+
13
+ # Read and remove (one-shot: prevent repeated injection)
14
+ FINDINGS=$(cat "$FIXES_FILE")
15
+ rm -f "$FIXES_FILE"
16
+
17
+ ISSUE_COUNT=$(echo "$FINDINGS" | jq -r '.issue_count // 0' 2>/dev/null)
18
+
19
+ if [ "$ISSUE_COUNT" -gt 0 ]; then
20
+ echo "[Session Auto-Fix] Previous session left ${ISSUE_COUNT} issue(s):"
21
+ echo "$FINDINGS" | jq -r '.issues[]' 2>/dev/null | while IFS= read -r issue; do
22
+ type="${issue%%:*}"
23
+ msg="${issue#*:}"
24
+ echo " - [${type}] ${msg}"
25
+ done
26
+ FIX_COUNT=$(echo "$FINDINGS" | jq -r '.fix_count // 0' 2>/dev/null)
27
+ if [ "$FIX_COUNT" -gt 0 ]; then
28
+ echo "Auto-fixed: ${FIX_COUNT} item(s)."
29
+ fi
30
+ echo ""
31
+ echo "Consider addressing remaining issues before starting new work."
32
+ fi
33
+
34
+ exit 0
@@ -0,0 +1,146 @@
1
+ #!/bin/bash
2
+ # Session Auto-Fix — SessionStart command hook (#838)
3
+ # Detects previous session issues: uncommitted changes, template sync,
4
+ # CLAUDE.md counts, gitignore blocking, wiki staleness, broken skill refs.
5
+ # Protocol: stdin JSON -> stdout pass-through, exit 0 always
6
+ # Time budget: <3s
7
+
8
+ input=$(cat)
9
+ FIXES_FILE="/tmp/.claude-session-fixes-${PPID}"
10
+ LOG_DIR=".claude/outputs/session-fixes"
11
+ ISSUES=()
12
+ FIXES=()
13
+ ISSUE_COUNT=0
14
+ FIX_COUNT=0
15
+
16
+ # Utility: add issue
17
+ add_issue() {
18
+ ISSUES+=("$1")
19
+ ISSUE_COUNT=$((ISSUE_COUNT + 1))
20
+ }
21
+
22
+ add_fix() {
23
+ FIXES+=("$1")
24
+ FIX_COUNT=$((FIX_COUNT + 1))
25
+ }
26
+
27
+ # ─── Check 1: Uncommitted changes ───
28
+ uncommitted=$(git status --porcelain 2>/dev/null | head -20)
29
+ if [ -n "$uncommitted" ]; then
30
+ count=$(echo "$uncommitted" | wc -l | tr -d ' ')
31
+ add_issue "uncommitted:${count} uncommitted changes detected"
32
+ fi
33
+
34
+ # ─── Check 2: Template sync (lightweight count comparison) ───
35
+ if [ -d "templates/.claude/agents" ] && [ -d ".claude/agents" ]; then
36
+ src_agents=$(ls .claude/agents/*.md 2>/dev/null | wc -l | tr -d ' ')
37
+ tpl_agents=$(ls templates/.claude/agents/*.md 2>/dev/null | wc -l | tr -d ' ')
38
+ if [ "$src_agents" != "$tpl_agents" ]; then
39
+ add_issue "template-sync:Agent count mismatch (source:${src_agents} vs template:${tpl_agents})"
40
+ fi
41
+
42
+ src_skills=$(find .claude/skills -name "SKILL.md" 2>/dev/null | wc -l | tr -d ' ')
43
+ tpl_skills=$(find templates/.claude/skills -name "SKILL.md" 2>/dev/null | wc -l | tr -d ' ')
44
+ if [ "$src_skills" != "$tpl_skills" ]; then
45
+ add_issue "template-sync:Skill count mismatch (source:${src_skills} vs template:${tpl_skills})"
46
+ fi
47
+
48
+ src_rules=$(ls .claude/rules/*.md 2>/dev/null | wc -l | tr -d ' ')
49
+ tpl_rules=$(ls templates/.claude/rules/*.md 2>/dev/null | wc -l | tr -d ' ')
50
+ if [ "$src_rules" != "$tpl_rules" ]; then
51
+ add_issue "template-sync:Rule count mismatch (source:${src_rules} vs template:${tpl_rules})"
52
+ fi
53
+
54
+ src_guides=$(find guides -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l | tr -d ' ')
55
+ tpl_guides=$(find templates/guides -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l | tr -d ' ')
56
+ if [ "$src_guides" != "$tpl_guides" ]; then
57
+ add_issue "template-sync:Guide count mismatch (source:${src_guides} vs template:${tpl_guides})"
58
+ fi
59
+ fi
60
+
61
+ # ─── Check 3: CLAUDE.md count validation ───
62
+ if [ -f "CLAUDE.md" ]; then
63
+ actual_agents=$(ls .claude/agents/*.md 2>/dev/null | wc -l | tr -d ' ')
64
+ doc_agents=$(grep -oE '[0-9]+ 파일\)' CLAUDE.md | head -1 | grep -oE '[0-9]+' || echo "0")
65
+ if [ "$actual_agents" != "$doc_agents" ] && [ "$doc_agents" != "0" ]; then
66
+ add_issue "claude-md:Agent count in CLAUDE.md ($doc_agents) != actual ($actual_agents)"
67
+ fi
68
+ fi
69
+
70
+ # ─── Check 4: Gitignore blocking new .claude/ files ───
71
+ new_files=$(git ls-files --others --exclude-standard .claude/ 2>/dev/null | head -5)
72
+ ignored_new=""
73
+ if [ -n "$new_files" ]; then
74
+ while IFS= read -r f; do
75
+ if git check-ignore --quiet "$f" 2>/dev/null; then
76
+ ignored_new="${ignored_new}${f}\n"
77
+ fi
78
+ done <<< "$new_files"
79
+ fi
80
+ if [ -n "$ignored_new" ]; then
81
+ add_issue "gitignore:New .claude/ files blocked by .gitignore"
82
+ fi
83
+
84
+ # ─── Check 5: Wiki staleness (lightweight) ───
85
+ if [ -d "wiki" ]; then
86
+ missing_wiki=0
87
+ for agent in .claude/agents/*.md; do
88
+ name=$(basename "$agent" .md)
89
+ if [ ! -f "wiki/agents/${name}.md" ]; then
90
+ missing_wiki=$((missing_wiki + 1))
91
+ fi
92
+ done
93
+ if [ "$missing_wiki" -gt 0 ]; then
94
+ add_issue "wiki-stale:${missing_wiki} agent(s) missing wiki pages"
95
+ fi
96
+ fi
97
+
98
+ # ─── Check 6: Broken skill references (lightweight) ───
99
+ broken_refs=0
100
+ for agent in .claude/agents/*.md; do
101
+ skills_line=$(grep -E '^skills:' "$agent" 2>/dev/null | head -1)
102
+ if [ -n "$skills_line" ]; then
103
+ skills=$(echo "$skills_line" | sed 's/skills: *\[//;s/\]//;s/,/ /g;s/"//g' | tr -d "'")
104
+ for skill in $skills; do
105
+ skill=$(echo "$skill" | tr -d ' ')
106
+ if [ -n "$skill" ] && [ ! -f ".claude/skills/${skill}/SKILL.md" ]; then
107
+ broken_refs=$((broken_refs + 1))
108
+ fi
109
+ done
110
+ fi
111
+ done
112
+ if [ "$broken_refs" -gt 0 ]; then
113
+ add_issue "broken-refs:${broken_refs} broken skill reference(s) in agent frontmatter"
114
+ fi
115
+
116
+ # ─── Report ───
117
+ if [ "$ISSUE_COUNT" -gt 0 ]; then
118
+ echo "[Session Auto-Fix] ${ISSUE_COUNT} issue(s) detected:" >&2
119
+ for issue in "${ISSUES[@]}"; do
120
+ type="${issue%%:*}"
121
+ msg="${issue#*:}"
122
+ echo " ⚠ [${type}] ${msg}" >&2
123
+ done
124
+ if [ "$FIX_COUNT" -gt 0 ]; then
125
+ echo "[Session Auto-Fix] Auto-fixed ${FIX_COUNT} item(s):" >&2
126
+ for fix in "${FIXES[@]}"; do
127
+ echo " ✓ ${fix}" >&2
128
+ done
129
+ fi
130
+ fi
131
+
132
+ # ─── Write findings for prompt hook ───
133
+ if command -v jq >/dev/null 2>&1; then
134
+ issues_json=$(printf '%s\n' "${ISSUES[@]}" | jq -R . | jq -s .)
135
+ fixes_json=$(printf '%s\n' "${FIXES[@]}" | jq -R . | jq -s .)
136
+ echo "{\"issue_count\":${ISSUE_COUNT},\"fix_count\":${FIX_COUNT},\"issues\":${issues_json},\"fixes\":${fixes_json}}" > "$FIXES_FILE"
137
+ else
138
+ echo "{\"issue_count\":${ISSUE_COUNT},\"fix_count\":${FIX_COUNT}}" > "$FIXES_FILE"
139
+ fi
140
+
141
+ # ─── JSONL log ───
142
+ mkdir -p "$LOG_DIR" 2>/dev/null
143
+ echo "{\"date\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"issue_count\":${ISSUE_COUNT},\"fix_count\":${FIX_COUNT}}" >> "${LOG_DIR}/$(date +%Y-%m-%d).jsonl" 2>/dev/null
144
+
145
+ echo "$input"
146
+ exit 0
@@ -161,7 +161,7 @@ project/
161
161
  | +-- rules/ # 전역 규칙 (R000-R022)
162
162
  | +-- hooks/ # 훅 스크립트 (보안, 검증, HUD)
163
163
  | +-- contexts/ # 컨텍스트 파일 (ecomode)
164
- +-- guides/ # 레퍼런스 문서 (33 토픽)
164
+ +-- guides/ # 레퍼런스 문서 (36 토픽)
165
165
  ```
166
166
 
167
167
  ## 오케스트레이션
@@ -0,0 +1,110 @@
1
+ # Agent Definition Quality Standards
2
+
3
+ ## Overview
4
+
5
+ Quality criteria for `.claude/agents/*.md` files. Adapted from ETH Zurich research on LLM-generated agent configurations, modified to fit oh-my-customcode's "create, connect, use" philosophy.
6
+
7
+ ## Core Principle: LLM Generation + Human Verification
8
+
9
+ > ETH Zurich finding: Purely LLM-generated AGENTS.md files perform worse than human-crafted ones.
10
+ >
11
+ > oh-my-customcode adaptation: LLM generation is the core workflow (via mgr-creator), but **verification is mandatory**. The creation tool generates; the verification process validates.
12
+
13
+ | Approach | Status |
14
+ |----------|--------|
15
+ | Pure LLM generation without review | Not recommended |
16
+ | LLM generation + mgr-sauron verification | Required (current workflow) |
17
+ | Human-crafted from scratch | Acceptable but not required |
18
+
19
+ ## Four-Section Structure
20
+
21
+ Every agent file SHOULD contain these conceptual sections:
22
+
23
+ ### 1. STYLE — How the agent communicates
24
+
25
+ ```yaml
26
+ # In frontmatter or body
27
+ # - Output format preferences
28
+ # - Verbosity level (maps to effort: low/medium/high)
29
+ # - Language conventions
30
+ ```
31
+
32
+ ### 2. GOTCHAS — Known pitfalls and edge cases
33
+
34
+ ```markdown
35
+ ## Known Issues
36
+ - This agent cannot handle files larger than X
37
+ - Requires MCP server Y to be running
38
+ - Output format changes when ecomode is active
39
+ ```
40
+
41
+ ### 3. ARCH_DECISIONS — Why this agent exists this way
42
+
43
+ ```markdown
44
+ ## Design Decisions
45
+ - Uses sonnet (not opus) because task complexity is moderate
46
+ - Skills X and Y are included because they cover the primary workflow
47
+ - Memory scope is project (not user) because knowledge is repo-specific
48
+ ```
49
+
50
+ ### 4. TEST_STRATEGY — How to verify the agent works
51
+
52
+ ```markdown
53
+ ## Verification
54
+ - Run with sample input: `Agent(subagent_type: "this-agent", prompt: "test task")`
55
+ - Expected: output matches format X
56
+ - Edge case: empty input should return guidance, not error
57
+ ```
58
+
59
+ ## Frontmatter Quality Checklist
60
+
61
+ | Field | Required | Quality Check |
62
+ |-------|----------|---------------|
63
+ | `name` | Yes | Matches filename (kebab-case) |
64
+ | `description` | Yes | One line, specific (not generic "handles X") |
65
+ | `model` | Yes | Justified by task complexity |
66
+ | `tools` | Yes | Minimal set needed (no unnecessary tools) |
67
+ | `skills` | No | Referenced skills must exist |
68
+ | `domain` | No | Matches actual specialization |
69
+ | `limitations` | No | Honest about what agent cannot do |
70
+
71
+ ## Anti-Patterns
72
+
73
+ | Anti-Pattern | Problem | Fix |
74
+ |-------------|---------|-----|
75
+ | Kitchen-sink tools | `tools: [Read, Write, Edit, Bash, Agent, ...]` | Minimal tool set for the role |
76
+ | Vague description | "Handles various tasks" | Specific: "Reviews Go code for idiomatic patterns" |
77
+ | Copy-paste body | Duplicates guide content | Reference guide, don't copy |
78
+ | Missing limitations | Sets unrealistic expectations | Declare what agent cannot do |
79
+ | Orphaned skill refs | References non-existent skills | mgr-supplier audit catches this |
80
+ | Excessive instructions | 500+ line body with detailed how-to | Move details to skills, keep agent body focused |
81
+
82
+ ## Verification Workflow
83
+
84
+ ```
85
+ mgr-creator generates agent
86
+ → mgr-sauron verifies (R017)
87
+ → Frontmatter valid?
88
+ → Skills exist?
89
+ → Tools minimal?
90
+ → Description specific?
91
+ → Human reviews (optional but recommended for complex agents)
92
+ → Agent deployed
93
+ ```
94
+
95
+ ## Quality Metrics
96
+
97
+ | Metric | Target |
98
+ |--------|--------|
99
+ | Body length | 50-200 lines (excluding frontmatter) |
100
+ | Tool count | 3-8 (role-appropriate) |
101
+ | Skill references | All resolvable |
102
+ | Description length | 10-80 characters |
103
+ | Limitations declared | At least 1 for complex agents |
104
+
105
+ ## Related
106
+
107
+ - R006 — Agent design rules (frontmatter format, separation of concerns)
108
+ - R017 — Sync verification (mgr-sauron validation)
109
+ - `mgr-creator` — Agent creation workflow
110
+ - `mgr-supplier` — Dependency audit
@@ -244,3 +244,22 @@ guides:
244
244
  path: ./web-scraping/
245
245
  source:
246
246
  type: internal
247
+
248
+ # Agent Operations
249
+ - name: worktree-lifecycle
250
+ description: Worktree lifecycle automation aliases (agent-spin/merge/clean) for AI agent workflows
251
+ path: ./worktree-lifecycle/
252
+ source:
253
+ type: internal
254
+
255
+ - name: multi-model-routing
256
+ description: Role-based model selection strategy for AI agent workflows
257
+ path: ./multi-model-routing/
258
+ source:
259
+ type: internal
260
+
261
+ - name: agents-md-quality
262
+ description: Agent definition quality standards adapted from ETH Zurich research
263
+ path: ./agents-md-quality/
264
+ source:
265
+ type: internal
@@ -0,0 +1,101 @@
1
+ # Multi-Model Routing
2
+
3
+ ## Overview
4
+
5
+ Role-based model selection strategy for AI agent workflows. Consolidates model routing conventions from R006 (agent design), R008 (tool identification), and agent frontmatter into a single reference.
6
+
7
+ ## Model Aliases
8
+
9
+ | Alias | Full ID | Cost | Speed | Use Case |
10
+ |-------|---------|------|-------|----------|
11
+ | `haiku` | claude-haiku-4-5 | $ | Fast | Search, simple edits, file discovery |
12
+ | `sonnet` | claude-sonnet-4-6 | $$ | Moderate | Code generation, general tasks (default) |
13
+ | `opus` | claude-opus-4-6 | $$$ | Slower | Complex reasoning, architecture, planning |
14
+ | `opusplan` | claude-opus-4-6 + plan mode | $$$ | Slower | Architecture with approval gates |
15
+
16
+ Extended context: `[1m]` suffix enables 1M token context (e.g., `claude-opus-4-6[1m]`).
17
+
18
+ ## Role-Based Routing Table
19
+
20
+ | Role | Recommended Model | Rationale |
21
+ |------|------------------|-----------|
22
+ | Code search / file discovery | haiku | Fast, cheap, sufficient for retrieval |
23
+ | Code review | sonnet | Needs understanding, not deep reasoning |
24
+ | Code generation | sonnet | Good balance of quality and speed |
25
+ | Bug fix (simple) | sonnet | Pattern recognition sufficient |
26
+ | Bug fix (complex) | opus | Needs deep reasoning across modules |
27
+ | Architecture design | opus / opusplan | Requires holistic thinking |
28
+ | Test generation | sonnet | Template-driven, moderate complexity |
29
+ | Documentation | sonnet | Straightforward generation |
30
+ | Release verification | opus | Cross-cutting validation |
31
+ | Orchestration | opus | Routing decisions need broad context |
32
+
33
+ ## Cost-Quality Tradeoff Matrix
34
+
35
+ ```
36
+ Quality ▲
37
+ │ ┌─────────┐
38
+ │ │ opus │ Complex reasoning
39
+ │ └────┬────┘
40
+ │ │
41
+ │ ┌────┴────┐
42
+ │ │ sonnet │ General purpose (default)
43
+ │ └────┬────┘
44
+ │ │
45
+ │ ┌────┴────┐
46
+ │ │ haiku │ Retrieval, simple tasks
47
+ │ └─────────┘
48
+ └──────────────────────► Cost
49
+ ```
50
+
51
+ ## MODEL_ROUTING.md Convention
52
+
53
+ Projects can declare a `MODEL_ROUTING.md` file to override default routing:
54
+
55
+ ```markdown
56
+ # Model Routing
57
+
58
+ | Agent Pattern | Model | Override Reason |
59
+ |---------------|-------|-----------------|
60
+ | lang-*-expert | sonnet | Default sufficient for code generation |
61
+ | mgr-sauron | opus | Verification requires deep analysis |
62
+ | Explore | haiku | Search-only, no generation needed |
63
+ ```
64
+
65
+ Place in project root or `.claude/` directory.
66
+
67
+ ## Agent Frontmatter Integration
68
+
69
+ ```yaml
70
+ # .claude/agents/example.md
71
+ name: example-agent
72
+ model: sonnet # Use alias from table above
73
+ ```
74
+
75
+ The `model` field in agent frontmatter sets the default. The Agent tool's `model` parameter overrides at spawn time.
76
+
77
+ ## Escalation Pattern
78
+
79
+ When a task fails at a lower model tier, escalate:
80
+
81
+ ```
82
+ haiku → sonnet → opus
83
+ ```
84
+
85
+ Configuration in agent frontmatter:
86
+ ```yaml
87
+ escalation:
88
+ enabled: true
89
+ path: haiku → sonnet → opus
90
+ threshold: 2 # failures before escalation advisory
91
+ ```
92
+
93
+ ## Fast Mode Interaction
94
+
95
+ Fast Mode (`/fast` toggle) uses the same model with faster output (~2.5x). It does NOT change the model — it reduces reasoning depth while maintaining the configured model tier.
96
+
97
+ ## Related
98
+
99
+ - R006 — Agent design rules (model aliases, frontmatter format)
100
+ - R008 — Tool identification (model in agent:model format)
101
+ - `guides/skill-bundle-design/` — Skill architecture patterns
@@ -0,0 +1,104 @@
1
+ # Worktree Lifecycle Automation
2
+
3
+ ## Overview
4
+
5
+ Three shell aliases for managing git worktree lifecycle in AI agent workflows: **spin** (create), **merge** (integrate), **clean** (remove). Builds on basic worktree knowledge from `guides/git-worktree-workflow/`.
6
+
7
+ ## Aliases
8
+
9
+ ### agent-spin — Create worktree for agent work
10
+
11
+ ```bash
12
+ agent-spin() {
13
+ local branch="$1"
14
+ local base="${2:-develop}"
15
+ local repo_name=$(basename "$(git rev-parse --show-toplevel)")
16
+ local worktree_dir="../${repo_name}-${branch}"
17
+
18
+ git fetch origin "$base"
19
+ git worktree add -b "$branch" "$worktree_dir" "origin/$base"
20
+ echo "Worktree ready: $worktree_dir (branch: $branch, base: $base)"
21
+ }
22
+ ```
23
+
24
+ **Usage**: `agent-spin feature/session-autofix develop`
25
+
26
+ ### agent-merge — Integrate worktree branch
27
+
28
+ ```bash
29
+ agent-merge() {
30
+ local branch="$1"
31
+ local target="${2:-develop}"
32
+ local repo_name=$(basename "$(git rev-parse --show-toplevel)")
33
+ local worktree_dir="../${repo_name}-${branch}"
34
+
35
+ # Switch to main worktree
36
+ cd "$(git worktree list | head -1 | awk '{print $1}')"
37
+
38
+ git checkout "$target"
39
+ git merge --no-ff "$branch" -m "Merge branch '$branch' into $target"
40
+
41
+ echo "Merged $branch into $target"
42
+ }
43
+ ```
44
+
45
+ **Usage**: `agent-merge feature/session-autofix develop`
46
+
47
+ ### agent-clean — Remove worktree and branch
48
+
49
+ ```bash
50
+ agent-clean() {
51
+ local branch="$1"
52
+ local repo_name=$(basename "$(git rev-parse --show-toplevel)")
53
+ local worktree_dir="../${repo_name}-${branch}"
54
+
55
+ git worktree remove "$worktree_dir" --force
56
+ git branch -d "$branch"
57
+
58
+ echo "Cleaned: worktree $worktree_dir, branch $branch"
59
+ }
60
+ ```
61
+
62
+ **Usage**: `agent-clean feature/session-autofix`
63
+
64
+ ## Setup
65
+
66
+ Add to `~/.zshrc` or `~/.bashrc`:
67
+
68
+ ```bash
69
+ # Agent worktree lifecycle
70
+ source ~/dotfiles/agent-worktree.sh # or inline the functions above
71
+ ```
72
+
73
+ ## Claude Code Integration
74
+
75
+ Claude Code's `EnterWorktree` / `ExitWorktree` tools provide built-in worktree support for subagents. The aliases above complement this for manual or hook-driven workflows.
76
+
77
+ | Method | Use Case |
78
+ |--------|----------|
79
+ | `EnterWorktree` tool | Agent-managed isolation (automatic) |
80
+ | `agent-spin` alias | Manual or hook-triggered worktree creation |
81
+ | Agent frontmatter `isolation: worktree` | Declarative per-agent isolation |
82
+
83
+ ## Lifecycle Flow
84
+
85
+ ```
86
+ agent-spin feature/x develop
87
+ └── Work in isolated worktree
88
+ └── Tests pass
89
+ └── agent-merge feature/x develop
90
+ └── agent-clean feature/x
91
+ ```
92
+
93
+ ## Best Practices
94
+
95
+ - Always base worktrees on `origin/develop` (not local) to avoid stale base
96
+ - Run tests in the worktree before merge
97
+ - Clean up worktrees promptly — orphaned worktrees accumulate disk usage
98
+ - For CI-driven flows, `agent-clean` should be in the finally/cleanup step
99
+
100
+ ## Related
101
+
102
+ - `guides/git-worktree-workflow/` — Basic worktree commands and directory structure
103
+ - R006 `isolation: worktree` — Agent frontmatter isolation setting
104
+ - Claude Code `EnterWorktree` / `ExitWorktree` — Built-in tool support
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "0.81.0",
2
+ "version": "0.83.0",
3
3
  "lastUpdated": "2026-04-12T00:00:00.000Z",
4
4
  "components": [
5
5
  {
@@ -24,7 +24,7 @@
24
24
  "name": "guides",
25
25
  "path": "guides",
26
26
  "description": "Reference documentation",
27
- "files": 33
27
+ "files": 36
28
28
  },
29
29
  {
30
30
  "name": "hooks",