oh-my-customcode 0.50.0 → 0.51.1

package/README.md

@@ -13,7 +13,7 @@
 
 **[한국어 문서 (Korean)](./README_ko.md)**
 
-45 agents. 90 skills. 21 rules. One command.
+45 agents. 91 skills. 21 rules. One command.
 
 ```bash
 npm install -g oh-my-customcode && cd your-project && omcustom init
@@ -138,7 +138,7 @@ Each agent declares its tools, model, memory scope, and limitations in YAML fron
 
 ---
 
-### Skills (90)
+### Skills (91)
 
 | Category | Count | Includes |
 |----------|-------|----------|
@@ -228,7 +228,7 @@ Key rules: R010 (orchestrator never writes files), R009 (parallel execution mand
 
 ---
 
-### Guides (29)
+### Guides (30)
 
 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.
 
@@ -274,14 +274,14 @@ your-project/
 ├── CLAUDE.md                   # Entry point
 ├── .claude/
 │   ├── agents/                 # 45 agent definitions
-│   ├── skills/                 # 90 skill modules
+│   ├── skills/                 # 91 skill modules
 │   ├── rules/                  # 21 governance rules (R000-R021)
 │   ├── hooks/                  # 15 lifecycle hook scripts
 │   ├── schemas/                # Tool input validation schemas
 │   ├── specs/                  # Extracted canonical specs
 │   ├── contexts/               # 4 shared context files
 │   └── ontology/               # Knowledge graph for RAG
-└── guides/                     # 29 reference documents
+└── guides/                     # 30 reference documents
 ```
 
 ---

package/dist/cli/index.js

@@ -9323,7 +9323,7 @@ var init_package = __esm(() => {
   package_default = {
     name: "oh-my-customcode",
     workspaces: ["packages/*"],
-    version: "0.50.0",
+    version: "0.51.1",
     description: "Batteries-included agent harness for Claude Code",
     type: "module",
     bin: {

package/dist/index.js

@@ -1668,7 +1668,7 @@ import { join as join6 } from "node:path";
 var package_default = {
   name: "oh-my-customcode",
   workspaces: ["packages/*"],
-  version: "0.50.0",
+  version: "0.51.1",
   description: "Batteries-included agent harness for Claude Code",
   type: "module",
   bin: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "oh-my-customcode",
   "workspaces": ["packages/*"],
-  "version": "0.50.0",
+  "version": "0.51.1",
   "description": "Batteries-included agent harness for Claude Code",
   "type": "module",
   "bin": {

package/templates/.claude/skills/scout/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: scout
+description: Analyze external URL to evaluate fit with oh-my-customcode project and auto-create GitHub issue with verdict
+scope: core
+version: 1.0.0
+user-invocable: true
+argument-hint: "<url>"
+---
+
+# /scout — External Link Analysis
+
+Analyze an external URL (tech blog, tool, library, methodology) to evaluate its fit with the oh-my-customcode project and auto-create a GitHub issue with a structured verdict.
+
+## Usage
+
+```
+/scout <url>
+/scout https://news.hada.io/topic?id=27673
+/scout https://github.com/user/repo
+```
+
+## Verdict Taxonomy
+
+| Verdict | Meaning | Label | Follow-up |
+|---------|---------|-------|-----------|
+| **INTERNALIZE** | Aligns with project philosophy; should become a skill/agent/guide | `scout:internalize` + `P1`/`P2`/`P3` | `/research` or direct implementation |
+| **INTEGRATE** | Useful but best kept as external dependency | `scout:integrate` + `P2`/`P3` | Plugin/MCP integration review |
+| **SKIP** | Irrelevant or duplicates existing functionality | `scout:skip` | Issue created then closed |
+
+## Pre-flight Guards
+
+### Guard 1: URL Validity (GATE)
+
+Before any work, validate the URL:
+
+```bash
+# Check URL is syntactically valid
+echo "$URL" | grep -qE '^https?://'
+```
+
+If invalid: `[Pre-flight] GATE: Invalid or unreachable URL. Please check and retry.` — abort.
+
+### Guard 2: Duplicate Scout (WARN)
+
+Search existing GitHub issues for prior scout reports on the same URL domain:
+
+```bash
+DOMAIN=$(echo "$URL" | sed 's|https\?://||' | cut -d'/' -f1)
+gh issue list --state all --label "scout:internalize,scout:integrate,scout:skip" \
+  --json number,title,body --jq ".[] | select(.body | contains(\"$DOMAIN\"))" 2>/dev/null
+```
+
+If found: `[Pre-flight] WARN: Similar URL already scouted in issue #N. Proceed anyway? [Y/n]`
+
+## Display Format
+
+Before execution, show the plan:
+
+```
+[Scout] {url}
+├── Phase 1: Fetch & Summarize
+├── Phase 2: Load Project Philosophy
+├── Phase 3: Fit Analysis (sonnet)
+└── Phase 4: Issue Creation
+
+Estimated: ~1 min | Cost: ~$0.5-1.5
+Execute? [Y/n]
+```
+
+## Workflow
+
+### Phase 1: Fetch & Summarize
+
+1. `WebFetch(url)` — retrieve page content
+2. Extract core information:
+   - Title and purpose
+   - Key technology / methodology
+   - Approach and principles
+3. If fetch fails — report error, abort
+
+### Phase 2: Load Project Philosophy
+
+1. `Read(CLAUDE.md)` — extract architecture philosophy:
+   - Compilation metaphor (source -> build -> artifact)
+   - Separation of concerns (R006)
+   - Dynamic agent creation ("no expert? create one")
+   - Skill/agent/guide/rule structure
+2. `Read(README.md)` — extract project overview and component inventory
+3. `Glob(.claude/skills/*/SKILL.md)` — list existing skills for overlap detection
+
+### Phase 3: Fit Analysis
+
+Spawn 1 sonnet agent with the following analysis prompt.
+
+**Inputs**:
+- Fetched content summary (Phase 1)
+- Project philosophy context (Phase 2)
+- Existing skill list (Phase 2)
+
+**Analysis dimensions**:
+
+| Dimension | Question |
+|-----------|----------|
+| Philosophy alignment | Does it match the compilation metaphor, separation of concerns, "create experts on demand"? |
+| Technical fit | Does it complement or overlap with existing skills/agents/guides? |
+| Integration effort | How much work to internalize vs. use externally? |
+| Value proposition | What concrete benefit does it bring to the project? |
+
+**Agent prompt template**:
+
+```
+You are a project fit analyst. Given:
+
+1. External content summary:
+{phase1_summary}
+
+2. Project philosophy:
+{phase2_philosophy}
+
+3. Existing skills ({skill_count} total):
+{skill_list}
+
+Analyze the external content against the project philosophy across 4 dimensions:
+- Philosophy alignment
+- Technical fit (overlap with existing skills?)
+- Integration effort (XS/S/M/L)
+- Value proposition
+
+Return a structured verdict:
+- verdict: INTERNALIZE | INTEGRATE | SKIP
+- priority: P1 | P2 | P3
+- rationale: 2-3 sentences
+- philosophy_table: criterion/fit/rationale for each dimension
+- recommendation: specific integration plan or skip reason
+- next_steps: 2-3 actionable items
+- escalation: true/false (INTERNALIZE + M/L effort = true)
+```
+
+**Output**: Structured verdict with rationale.
+
+### Phase 4: Issue Creation
+
+1. Ensure scout labels exist (defensive, idempotent):
+```bash
+gh label create "scout:internalize" --color "0E8A16" --description "Scout: should be internalized" 2>/dev/null || true
+gh label create "scout:integrate" --color "1D76DB" --description "Scout: keep as external" 2>/dev/null || true
+gh label create "scout:skip" --color "D4C5F9" --description "Scout: skip" 2>/dev/null || true
+```
+
+2. Create GitHub issue:
+```bash
+gh issue create \
+  --title "[scout:{verdict}] {content_title}" \
+  --label "scout:{verdict},P{n}" \
+  --body "{issue_body}"
+```
+
+3. If verdict is `SKIP`: auto-close the issue:
+```bash
+gh issue close {number} -c "Auto-closed: scout verdict is SKIP"
+```
+
+### Issue Body Template
+
+```markdown
+## Scout Report: {title}
+
+**Source**: {url}
+**Verdict**: {INTERNALIZE / INTEGRATE / SKIP}
+**Priority**: {P1 / P2 / P3}
+
+## Summary
+{2-3 sentence summary of the external content}
+
+## Philosophy Alignment
+| Criterion | Fit | Rationale |
+|-----------|-----|-----------|
+| Compilation metaphor | {check/cross} | {explanation} |
+| Separation of concerns (R006) | {check/cross} | {explanation} |
+| Dynamic agent creation | {check/cross} | {explanation} |
+| Existing skill overlap | {check/cross} | {overlapping skills list} |
+
+## Recommendation
+{Specific integration plan — which skill/agent/guide to create, or why to skip}
+
+## Next Steps
+- [ ] {follow-up action 1}
+- [ ] {follow-up action 2}
+
+---
+Generated by `/scout`
+```
+
+## Escalation
+
+When verdict is `INTERNALIZE` and integration effort is M or L:
+
+```
+[Advisory] Deep analysis recommended.
+└── Consider running: /research {url}
+```
+
+## Result Display
+
+```
+[Scout Complete] {title}
+├── Verdict: {INTERNALIZE / INTEGRATE / SKIP}
+├── Priority: {P1 / P2 / P3}
+├── Issue: #{number}
+└── Escalation: {/research recommended | none}
+```
+
+## Model Selection
+
+| Phase | Model | Rationale |
+|-------|-------|-----------|
+| Phase 1 (Fetch) | orchestrator | Simple WebFetch, no agent needed |
+| Phase 2 (Load) | orchestrator | Simple Read/Glob, no agent needed |
+| Phase 3 (Analysis) | sonnet | Balanced reasoning for fit analysis |
+| Phase 4 (Issue) | orchestrator | gh issue create via Bash |
+
+## Integration
+
+| Rule | How |
+|------|-----|
+| R009 | Single agent in Phase 3 — no parallelism needed |
+| R010 | Orchestrator manages phases 1/2/4; analysis delegated to sonnet agent in Phase 3 |
+| R015 | Display scout plan before execution (Display Format section) |
+
+## When NOT to Use
+
+| Scenario | Better Alternative |
+|----------|--------------------|
+| Deep multi-source research | `/research <url>` |
+| Internal project analysis | `/omcustom:analysis` |
+| Known tool evaluation | Direct agent conversation |
+| Bulk URL analysis (5+) | `/research` with URL list |
+
+## Differences from /research
+
+| Aspect | /scout | /research |
+|--------|--------|-----------|
+| Purpose | Quick fit evaluation | Deep multi-dimensional analysis |
+| Teams | 1 agent | 10 teams |
+| Cost | ~$0.5-1.5 | ~$8-15 |
+| Duration | 1-2 min | 10-20 min |
+| Output | Issue with verdict | Full report with ADOPT/ADAPT/AVOID |
+| When | First contact with new link | Deep dive after scout recommends |

package/templates/CLAUDE.md

@@ -119,6 +119,7 @@ oh-my-customcode로 구동됩니다.
 | `/optimize-bundle` | 번들 크기 최적화 |
 | `/optimize-report` | 최적화 리포트 생성 |
 | `/research` | 10-team 병렬 딥 분석 및 교차 검증 |
+| `/scout` | 외부 URL 분석 및 프로젝트 적합성 평가 |
 | `/deep-plan` | 연구 검증 기반 계획 수립 (research → plan → verify) |
 | `/deep-verify` | 다중 관점 릴리즈 품질 검증 |
 | `/omcustom:sauron-watch` | 전체 R017 검증 |
@@ -135,11 +136,11 @@ project/
 +-- CLAUDE.md                    # 진입점
 +-- .claude/
 |   +-- agents/                  # 서브에이전트 정의 (45 파일)
-|   +-- skills/                  # 스킬 (90 디렉토리)
+|   +-- skills/                  # 스킬 (91 디렉토리)
 |   +-- rules/                   # 전역 규칙 (R000-R021)
 |   +-- hooks/                   # 훅 스크립트 (보안, 검증, HUD)
 |   +-- contexts/                # 컨텍스트 파일 (ecomode)
-+-- guides/                      # 레퍼런스 문서 (29 토픽)
++-- guides/                      # 레퍼런스 문서 (30 토픽)
 ```
 
 ## 오케스트레이션

package/templates/guides/drizzle-orm/README.md

@@ -0,0 +1,69 @@
+# Drizzle ORM: sql Template Literal Pitfalls
+
+## The Bug: Column References in Subqueries
+
+When using Drizzle ORM's `sql` template literals, `${table.column}` generates a **bare column name without the table qualifier**. This causes silent semantic errors inside aliased subqueries.
+
+### Symptom
+
+```typescript
+// Code
+sql`SELECT ${agentInvocations.errorSummary} as sub_es
+    FROM ${agentInvocations} AS ai2
+    WHERE ai2.agent_type = ${agentInvocations.agentType}`
+
+// Generated SQL (WRONG)
+SELECT "error_summary" as sub_es
+FROM "agent_invocations" AS ai2
+WHERE ai2.agent_type = "agent_type"  -- "agent_type" becomes a literal string, always true!
+```
+
+`${agentInvocations.agentType}` expands to the **quoted column name** `"agent_type"` — not the value of the column. The `WHERE` clause compares `ai2.agent_type = "agent_type"`, which SQLite treats as a string literal match — always true for rows where `agent_type` equals the string `"agent_type"`.
+
+### Why Reviewers Miss It
+
+- The code *looks* correct — you see `agentInvocations.agentType` and assume it's a column reference.
+- Drizzle's `${table.column}` syntax works fine in top-level queries where table context is unambiguous.
+- The bug only manifests inside subqueries with table aliases (`AS ai2`) — normal queries pass.
+- No compile-time error; the SQL executes but returns wrong results.
+
+## The Fix: Raw SQL for Subquery Internal References
+
+Use raw SQL strings for column references *inside* aliased subqueries. Reserve `${table.column}` only for Drizzle's top-level query builder where it resolves correctly.
+
+```typescript
+// CORRECT: raw SQL column references inside aliased subquery
+sql`SELECT ai2.error_summary as sub_es
+    FROM ${agentInvocations} AS ai2
+    WHERE ai2.agent_type = ${agentInvocations}.agent_type`
+```
+
+Note: `${agentInvocations}` (the table object itself) still correctly expands to the table name and is safe to use for the `FROM` clause. Only *column* references inside subqueries must be written as raw SQL.
+
+## Decision Table
+
+| Context | Pattern | Safe? |
+|---------|---------|-------|
+| Top-level `FROM` clause | `${table}` | ✅ Yes |
+| Top-level `WHERE` with parameterized value | `${value}` | ✅ Yes (auto-parameterized) |
+| Top-level `SELECT` column | `${table.column}` | ✅ Yes |
+| Inside aliased subquery `SELECT` | `${table.column}` | ❌ No — bare column name |
+| Inside aliased subquery `WHERE` comparison | `${table.column}` | ❌ No — string literal, not column ref |
+| Inside aliased subquery (fixed) | `alias.column_name` | ✅ Yes |
+
+## Verification
+
+Use `.toSQL()` to inspect generated SQL before running:
+
+```typescript
+const query = sql`SELECT ${agentInvocations.errorSummary} as sub_es
+    FROM ${agentInvocations} AS ai2
+    WHERE ai2.agent_type = ${agentInvocations.agentType}`
+
+console.log(query.toSQL())
+// Reveals the bare column names — catches the bug before runtime
+```
+
+## Key Takeaway
+
+> **`${table.column}` in Drizzle's `sql` template generates a bare column identifier, not a qualified reference.** Inside aliased subqueries, this breaks table-qualified comparisons. Always use raw `alias.column_name` strings inside subquery bodies.

package/templates/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.50.0",
+  "version": "0.51.1",
   "lastUpdated": "2026-03-16T00:00:00.000Z",
   "components": [
     {
@@ -18,13 +18,13 @@
       "name": "skills",
       "path": ".claude/skills",
       "description": "Reusable skill modules (includes slash commands)",
-      "files": 90
+      "files": 91
     },
     {
       "name": "guides",
       "path": "guides",
       "description": "Reference documentation",
-      "files": 29
+      "files": 30
     },
     {
       "name": "hooks",