oh-my-customcode 0.81.0 → 0.82.0

package/README.md

@@ -235,7 +235,7 @@ Key rules: R010 (orchestrator never writes files), R009 (parallel execution mand
 
 ---
 
-### Guides (33)
+### Guides (36)
 
 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.
 
@@ -292,7 +292,7 @@ your-project/
 │   ├── specs/                  # Extracted canonical specs
 │   ├── contexts/               # 4 shared context files
 │   └── ontology/               # Knowledge graph for RAG
-└── guides/                     # 33 reference documents
+└── guides/                     # 36 reference documents
 ```
 
 ---

package/dist/cli/index.js

@@ -2301,7 +2301,7 @@ var init_package = __esm(() => {
     workspaces: [
       "packages/*"
     ],
-    version: "0.81.0",
+    version: "0.82.0",
     description: "Batteries-included agent harness for Claude Code",
     type: "module",
     bin: {
@@ -28047,7 +28047,8 @@ async function installSettingsLocal(targetDir, result) {
     statusLine: {
       type: "command",
       command: ".claude/statusline.sh",
-      padding: 0
+      padding: 0,
+      refreshInterval: 10
     }
   };
   if (await fileExists(settingsPath)) {

package/dist/index.js

@@ -1654,7 +1654,8 @@ async function installSettingsLocal(targetDir, result) {
     statusLine: {
       type: "command",
       command: ".claude/statusline.sh",
-      padding: 0
+      padding: 0,
+      refreshInterval: 10
     }
   };
   if (await fileExists(settingsPath)) {
@@ -1973,7 +1974,7 @@ var package_default = {
   workspaces: [
     "packages/*"
   ],
-  version: "0.81.0",
+  version: "0.82.0",
   description: "Batteries-included agent harness for Claude Code",
   type: "module",
   bin: {

package/package.json

@@ -3,7 +3,7 @@
   "workspaces": [
     "packages/*"
   ],
-  "version": "0.81.0",
+  "version": "0.82.0",
   "description": "Batteries-included agent harness for Claude Code",
   "type": "module",
   "bin": {

package/templates/CLAUDE.md

@@ -161,7 +161,7 @@ project/
 |   +-- rules/                   # 전역 규칙 (R000-R022)
 |   +-- hooks/                   # 훅 스크립트 (보안, 검증, HUD)
 |   +-- contexts/                # 컨텍스트 파일 (ecomode)
-+-- guides/                      # 레퍼런스 문서 (33 토픽)
++-- guides/                      # 레퍼런스 문서 (36 토픽)
 ```
 
 ## 오케스트레이션

package/templates/guides/agents-md-quality/README.md

@@ -0,0 +1,110 @@
+# Agent Definition Quality Standards
+
+## Overview
+
+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.
+
+## Core Principle: LLM Generation + Human Verification
+
+> ETH Zurich finding: Purely LLM-generated AGENTS.md files perform worse than human-crafted ones.
+>
+> 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.
+
+| Approach | Status |
+|----------|--------|
+| Pure LLM generation without review | Not recommended |
+| LLM generation + mgr-sauron verification | Required (current workflow) |
+| Human-crafted from scratch | Acceptable but not required |
+
+## Four-Section Structure
+
+Every agent file SHOULD contain these conceptual sections:
+
+### 1. STYLE — How the agent communicates
+
+```yaml
+# In frontmatter or body
+# - Output format preferences
+# - Verbosity level (maps to effort: low/medium/high)
+# - Language conventions
+```
+
+### 2. GOTCHAS — Known pitfalls and edge cases
+
+```markdown
+## Known Issues
+- This agent cannot handle files larger than X
+- Requires MCP server Y to be running
+- Output format changes when ecomode is active
+```
+
+### 3. ARCH_DECISIONS — Why this agent exists this way
+
+```markdown
+## Design Decisions
+- Uses sonnet (not opus) because task complexity is moderate
+- Skills X and Y are included because they cover the primary workflow
+- Memory scope is project (not user) because knowledge is repo-specific
+```
+
+### 4. TEST_STRATEGY — How to verify the agent works
+
+```markdown
+## Verification
+- Run with sample input: `Agent(subagent_type: "this-agent", prompt: "test task")`
+- Expected: output matches format X
+- Edge case: empty input should return guidance, not error
+```
+
+## Frontmatter Quality Checklist
+
+| Field | Required | Quality Check |
+|-------|----------|---------------|
+| `name` | Yes | Matches filename (kebab-case) |
+| `description` | Yes | One line, specific (not generic "handles X") |
+| `model` | Yes | Justified by task complexity |
+| `tools` | Yes | Minimal set needed (no unnecessary tools) |
+| `skills` | No | Referenced skills must exist |
+| `domain` | No | Matches actual specialization |
+| `limitations` | No | Honest about what agent cannot do |
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|-------------|---------|-----|
+| Kitchen-sink tools | `tools: [Read, Write, Edit, Bash, Agent, ...]` | Minimal tool set for the role |
+| Vague description | "Handles various tasks" | Specific: "Reviews Go code for idiomatic patterns" |
+| Copy-paste body | Duplicates guide content | Reference guide, don't copy |
+| Missing limitations | Sets unrealistic expectations | Declare what agent cannot do |
+| Orphaned skill refs | References non-existent skills | mgr-supplier audit catches this |
+| Excessive instructions | 500+ line body with detailed how-to | Move details to skills, keep agent body focused |
+
+## Verification Workflow
+
+```
+mgr-creator generates agent
+  → mgr-sauron verifies (R017)
+    → Frontmatter valid?
+    → Skills exist?
+    → Tools minimal?
+    → Description specific?
+  → Human reviews (optional but recommended for complex agents)
+  → Agent deployed
+```
+
+## Quality Metrics
+
+| Metric | Target |
+|--------|--------|
+| Body length | 50-200 lines (excluding frontmatter) |
+| Tool count | 3-8 (role-appropriate) |
+| Skill references | All resolvable |
+| Description length | 10-80 characters |
+| Limitations declared | At least 1 for complex agents |
+
+## Related
+
+- R006 — Agent design rules (frontmatter format, separation of concerns)
+- R017 — Sync verification (mgr-sauron validation)
+- `mgr-creator` — Agent creation workflow
+- `mgr-supplier` — Dependency audit

package/templates/guides/index.yaml

@@ -244,3 +244,22 @@ guides:
     path: ./web-scraping/
     source:
       type: internal
+
+  # Agent Operations
+  - name: worktree-lifecycle
+    description: Worktree lifecycle automation aliases (agent-spin/merge/clean) for AI agent workflows
+    path: ./worktree-lifecycle/
+    source:
+      type: internal
+
+  - name: multi-model-routing
+    description: Role-based model selection strategy for AI agent workflows
+    path: ./multi-model-routing/
+    source:
+      type: internal
+
+  - name: agents-md-quality
+    description: Agent definition quality standards adapted from ETH Zurich research
+    path: ./agents-md-quality/
+    source:
+      type: internal

package/templates/guides/multi-model-routing/README.md

@@ -0,0 +1,101 @@
+# Multi-Model Routing
+
+## Overview
+
+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.
+
+## Model Aliases
+
+| Alias | Full ID | Cost | Speed | Use Case |
+|-------|---------|------|-------|----------|
+| `haiku` | claude-haiku-4-5 | $ | Fast | Search, simple edits, file discovery |
+| `sonnet` | claude-sonnet-4-6 | $$ | Moderate | Code generation, general tasks (default) |
+| `opus` | claude-opus-4-6 | $$$ | Slower | Complex reasoning, architecture, planning |
+| `opusplan` | claude-opus-4-6 + plan mode | $$$ | Slower | Architecture with approval gates |
+
+Extended context: `[1m]` suffix enables 1M token context (e.g., `claude-opus-4-6[1m]`).
+
+## Role-Based Routing Table
+
+| Role | Recommended Model | Rationale |
+|------|------------------|-----------|
+| Code search / file discovery | haiku | Fast, cheap, sufficient for retrieval |
+| Code review | sonnet | Needs understanding, not deep reasoning |
+| Code generation | sonnet | Good balance of quality and speed |
+| Bug fix (simple) | sonnet | Pattern recognition sufficient |
+| Bug fix (complex) | opus | Needs deep reasoning across modules |
+| Architecture design | opus / opusplan | Requires holistic thinking |
+| Test generation | sonnet | Template-driven, moderate complexity |
+| Documentation | sonnet | Straightforward generation |
+| Release verification | opus | Cross-cutting validation |
+| Orchestration | opus | Routing decisions need broad context |
+
+## Cost-Quality Tradeoff Matrix
+
+```
+Quality ▲
+        │  ┌─────────┐
+        │  │  opus    │ Complex reasoning
+        │  └────┬────┘
+        │       │
+        │  ┌────┴────┐
+        │  │ sonnet   │ General purpose (default)
+        │  └────┬────┘
+        │       │
+        │  ┌────┴────┐
+        │  │  haiku   │ Retrieval, simple tasks
+        │  └─────────┘
+        └──────────────────────► Cost
+```
+
+## MODEL_ROUTING.md Convention
+
+Projects can declare a `MODEL_ROUTING.md` file to override default routing:
+
+```markdown
+# Model Routing
+
+| Agent Pattern | Model | Override Reason |
+|---------------|-------|-----------------|
+| lang-*-expert | sonnet | Default sufficient for code generation |
+| mgr-sauron | opus | Verification requires deep analysis |
+| Explore | haiku | Search-only, no generation needed |
+```
+
+Place in project root or `.claude/` directory.
+
+## Agent Frontmatter Integration
+
+```yaml
+# .claude/agents/example.md
+name: example-agent
+model: sonnet  # Use alias from table above
+```
+
+The `model` field in agent frontmatter sets the default. The Agent tool's `model` parameter overrides at spawn time.
+
+## Escalation Pattern
+
+When a task fails at a lower model tier, escalate:
+
+```
+haiku → sonnet → opus
+```
+
+Configuration in agent frontmatter:
+```yaml
+escalation:
+  enabled: true
+  path: haiku → sonnet → opus
+  threshold: 2  # failures before escalation advisory
+```
+
+## Fast Mode Interaction
+
+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.
+
+## Related
+
+- R006 — Agent design rules (model aliases, frontmatter format)
+- R008 — Tool identification (model in agent:model format)
+- `guides/skill-bundle-design/` — Skill architecture patterns

package/templates/guides/worktree-lifecycle/README.md

@@ -0,0 +1,104 @@
+# Worktree Lifecycle Automation
+
+## Overview
+
+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/`.
+
+## Aliases
+
+### agent-spin — Create worktree for agent work
+
+```bash
+agent-spin() {
+  local branch="$1"
+  local base="${2:-develop}"
+  local repo_name=$(basename "$(git rev-parse --show-toplevel)")
+  local worktree_dir="../${repo_name}-${branch}"
+
+  git fetch origin "$base"
+  git worktree add -b "$branch" "$worktree_dir" "origin/$base"
+  echo "Worktree ready: $worktree_dir (branch: $branch, base: $base)"
+}
+```
+
+**Usage**: `agent-spin feature/session-autofix develop`
+
+### agent-merge — Integrate worktree branch
+
+```bash
+agent-merge() {
+  local branch="$1"
+  local target="${2:-develop}"
+  local repo_name=$(basename "$(git rev-parse --show-toplevel)")
+  local worktree_dir="../${repo_name}-${branch}"
+
+  # Switch to main worktree
+  cd "$(git worktree list | head -1 | awk '{print $1}')"
+
+  git checkout "$target"
+  git merge --no-ff "$branch" -m "Merge branch '$branch' into $target"
+
+  echo "Merged $branch into $target"
+}
+```
+
+**Usage**: `agent-merge feature/session-autofix develop`
+
+### agent-clean — Remove worktree and branch
+
+```bash
+agent-clean() {
+  local branch="$1"
+  local repo_name=$(basename "$(git rev-parse --show-toplevel)")
+  local worktree_dir="../${repo_name}-${branch}"
+
+  git worktree remove "$worktree_dir" --force
+  git branch -d "$branch"
+
+  echo "Cleaned: worktree $worktree_dir, branch $branch"
+}
+```
+
+**Usage**: `agent-clean feature/session-autofix`
+
+## Setup
+
+Add to `~/.zshrc` or `~/.bashrc`:
+
+```bash
+# Agent worktree lifecycle
+source ~/dotfiles/agent-worktree.sh  # or inline the functions above
+```
+
+## Claude Code Integration
+
+Claude Code's `EnterWorktree` / `ExitWorktree` tools provide built-in worktree support for subagents. The aliases above complement this for manual or hook-driven workflows.
+
+| Method | Use Case |
+|--------|----------|
+| `EnterWorktree` tool | Agent-managed isolation (automatic) |
+| `agent-spin` alias | Manual or hook-triggered worktree creation |
+| Agent frontmatter `isolation: worktree` | Declarative per-agent isolation |
+
+## Lifecycle Flow
+
+```
+agent-spin feature/x develop
+  └── Work in isolated worktree
+      └── Tests pass
+          └── agent-merge feature/x develop
+              └── agent-clean feature/x
+```
+
+## Best Practices
+
+- Always base worktrees on `origin/develop` (not local) to avoid stale base
+- Run tests in the worktree before merge
+- Clean up worktrees promptly — orphaned worktrees accumulate disk usage
+- For CI-driven flows, `agent-clean` should be in the finally/cleanup step
+
+## Related
+
+- `guides/git-worktree-workflow/` — Basic worktree commands and directory structure
+- R006 `isolation: worktree` — Agent frontmatter isolation setting
+- Claude Code `EnterWorktree` / `ExitWorktree` — Built-in tool support

package/templates/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.81.0",
+  "version": "0.82.0",
   "lastUpdated": "2026-04-12T00:00:00.000Z",
   "components": [
     {
@@ -24,7 +24,7 @@
       "name": "guides",
       "path": "guides",
       "description": "Reference documentation",
-      "files": 33
+      "files": 36
     },
     {
       "name": "hooks",