oh-my-customcode 0.2.0 → 0.3.0

package/README.md

@@ -6,6 +6,8 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![CI](https://github.com/baekenough/oh-my-customcode/actions/workflows/ci.yml/badge.svg)](https://github.com/baekenough/oh-my-customcode/actions/workflows/ci.yml)
 
+**[한국어 문서 (Korean)](./README_ko.md)**
+
 **The easiest way to customize Claude Code with agents, skills, and rules.**
 
 Like oh-my-zsh transformed shell customization, oh-my-customcode makes personalizing your Claude Code experience simple, powerful, and fun.
@@ -228,6 +230,32 @@ bun run build        # Build for production
 - Node.js >= 18.0.0
 - Claude Code CLI
 
+### Sync Verification
+
+oh-my-customcode templates are synced from [baekgom-agents](https://github.com/baekenough/baekgom-agents). To verify templates are in sync:
+
+```bash
+# Local verification (requires baekgom-agents checkout)
+./scripts/verify-sync.sh /path/to/baekgom-agents
+
+# Or using environment variable
+BAEKGOM_AGENTS_PATH=/path/to/baekgom-agents ./scripts/verify-sync.sh
+```
+
+The verification checks 7 content directories:
+- `.claude/agents/` (34 agents)
+- `.claude/skills/` (42 skills)
+- `.claude/rules/` (18 rules)
+- `.claude/hooks/`
+- `.claude/contexts/`
+- `guides/`
+- `pipelines/`
+
+CI automatically runs sync verification on:
+- Push to main (when templates change)
+- Weekly schedule (Monday 00:00 UTC)
+- Manual workflow dispatch
+
 ---
 
 ## Contributing

package/dist/cli/index.js

@@ -12260,6 +12260,105 @@ async function checkSkills(targetDir) {
     fixable: false
   };
 }
+async function checkGuides(targetDir) {
+  const guidesDir = path.join(targetDir, "guides");
+  const exists2 = await isDirectory(guidesDir);
+  if (!exists2) {
+    return {
+      name: "Guides",
+      status: "fail",
+      message: "guides/ directory not found",
+      fixable: true
+    };
+  }
+  const topicCount = await countDirectories(guidesDir);
+  if (topicCount === 0) {
+    return {
+      name: "Guides",
+      status: "warn",
+      message: "guides/ directory is empty (0 topics found)",
+      fixable: false
+    };
+  }
+  return {
+    name: "Guides",
+    status: "pass",
+    message: `Guides OK (${topicCount} topics)`,
+    fixable: false
+  };
+}
+async function checkHooks(targetDir) {
+  const hooksDir = path.join(targetDir, ".claude", "hooks");
+  const exists2 = await isDirectory(hooksDir);
+  if (!exists2) {
+    return {
+      name: "Hooks",
+      status: "fail",
+      message: ".claude/hooks/ directory not found",
+      fixable: true
+    };
+  }
+  const hookFiles = await findFiles(hooksDir, /\.(sh|json|yaml)$/);
+  if (hookFiles.length === 0) {
+    return {
+      name: "Hooks",
+      status: "warn",
+      message: ".claude/hooks/ directory is empty",
+      fixable: false
+    };
+  }
+  return {
+    name: "Hooks",
+    status: "pass",
+    message: `Hooks OK (${hookFiles.length} files)`,
+    fixable: false
+  };
+}
+async function checkPipelines(targetDir) {
+  const pipelinesDir = path.join(targetDir, "pipelines");
+  const exists2 = await isDirectory(pipelinesDir);
+  if (!exists2) {
+    return {
+      name: "Pipelines",
+      status: "fail",
+      message: "pipelines/ directory not found",
+      fixable: true
+    };
+  }
+  return {
+    name: "Pipelines",
+    status: "pass",
+    message: "Pipelines OK",
+    fixable: false
+  };
+}
+async function checkContexts(targetDir) {
+  const contextsDir = path.join(targetDir, ".claude", "contexts");
+  const exists2 = await isDirectory(contextsDir);
+  if (!exists2) {
+    return {
+      name: "Contexts",
+      status: "fail",
+      message: ".claude/contexts/ directory not found",
+      fixable: true
+    };
+  }
+  const contextFiles = await findFiles(contextsDir, /\.md$/);
+  if (contextFiles.length === 0) {
+    return {
+      name: "Contexts",
+      status: "warn",
+      message: ".claude/contexts/ directory is empty",
+      fixable: false
+    };
+  }
+  return {
+    name: "Contexts",
+    status: "pass",
+    message: `Contexts OK (${contextFiles.length} files)`,
+    fixable: false
+  };
+}
 async function fixBrokenSymlinks(_targetDir, brokenSymlinks) {
   let fixed = 0;
   for (const symlink of brokenSymlinks) {
@@ -12283,6 +12382,10 @@ async function fixSingleIssue(check, targetDir) {
     Rules: () => createMissingDirectory(path.join(targetDir, ".claude", "rules")),
     Agents: () => createMissingDirectory(path.join(targetDir, ".claude", "agents")),
     Skills: () => createMissingDirectory(path.join(targetDir, ".claude", "skills")),
+    Guides: () => createMissingDirectory(path.join(targetDir, "guides")),
+    Hooks: () => createMissingDirectory(path.join(targetDir, ".claude", "hooks")),
+    Pipelines: () => createMissingDirectory(path.join(targetDir, "pipelines")),
+    Contexts: () => createMissingDirectory(path.join(targetDir, ".claude", "contexts")),
     Symlinks: async () => {
       if (!check.details || check.details.length === 0)
         return false;
@@ -12335,7 +12438,11 @@ async function doctorCommand(options = {}) {
     checkAgents(targetDir),
     checkSkills(targetDir),
     checkSymlinks(targetDir),
-    checkIndexFiles(targetDir)
+    checkIndexFiles(targetDir),
+    checkGuides(targetDir),
+    checkHooks(targetDir),
+    checkPipelines(targetDir),
+    checkContexts(targetDir)
   ]);
   if (options.fix) {
     const hasFixableIssues = checks.some((c) => c.status === "fail" && c.fixable);
@@ -13393,11 +13500,71 @@ ${type} (${components.length}):`);
 function formatAsJson(components) {
   console.log(JSON.stringify(components, null, 2));
 }
+async function getHooks(targetDir) {
+  const hooksDir = join5(targetDir, ".claude", "hooks");
+  if (!await fileExists(hooksDir))
+    return [];
+  try {
+    const hookFiles = await listFiles(hooksDir, { recursive: true, pattern: "*.sh" });
+    const hookConfigs = await listFiles(hooksDir, { recursive: true, pattern: "*.json" });
+    const hookYamls = await listFiles(hooksDir, { recursive: true, pattern: "*.yaml" });
+    const allFiles = [...hookFiles, ...hookConfigs, ...hookYamls];
+    return allFiles.map((hookPath) => ({
+      name: basename2(hookPath),
+      type: "hook",
+      path: relative(targetDir, hookPath)
+    })).sort((a, b) => a.name.localeCompare(b.name));
+  } catch {
+    return [];
+  }
+}
+async function getContexts(targetDir) {
+  const contextsDir = join5(targetDir, ".claude", "contexts");
+  if (!await fileExists(contextsDir))
+    return [];
+  try {
+    const mdFiles = await listFiles(contextsDir, { recursive: false, pattern: "*.md" });
+    const yamlFiles = await listFiles(contextsDir, { recursive: false, pattern: "*.yaml" });
+    const allFiles = [...mdFiles, ...yamlFiles];
+    const contexts = await Promise.all(allFiles.map(async (ctxPath) => {
+      const ext = ctxPath.endsWith(".md") ? ".md" : ".yaml";
+      const description = ext === ".md" ? await tryExtractMarkdownDescription(ctxPath, { maxLength: 100 }) : undefined;
+      return {
+        name: basename2(ctxPath, ext),
+        type: "context",
+        path: relative(targetDir, ctxPath),
+        description
+      };
+    }));
+    return contexts.sort((a, b) => a.name.localeCompare(b.name));
+  } catch {
+    return [];
+  }
+}
+async function getPipelines(targetDir) {
+  const pipelinesDir = join5(targetDir, "pipelines");
+  if (!await fileExists(pipelinesDir))
+    return [];
+  try {
+    const pipelineFiles = await listFiles(pipelinesDir, { recursive: true, pattern: "*.yaml" });
+    return pipelineFiles.map((pipePath) => ({
+      name: basename2(pipePath, ".yaml"),
+      type: "pipeline",
+      category: relative(join5(targetDir, "pipelines"), dirname2(pipePath)) || "root",
+      path: relative(targetDir, pipePath)
+    })).sort((a, b) => a.name.localeCompare(b.name));
+  } catch {
+    return [];
+  }
+}
 var COMPONENT_GETTERS = {
   agents: getAgents,
   skills: getSkills,
   guides: getGuides,
-  rules: getRules
+  rules: getRules,
+  hooks: getHooks,
+  contexts: getContexts,
+  pipelines: getPipelines
 };
 function displayComponents(components, type, format) {
   if (format === "json") {
@@ -13409,19 +13576,25 @@ function displayComponents(components, type, format) {
   }
 }
 async function handleListAll(targetDir, format) {
-  const [agents, skills, guides, rules] = await Promise.all([
+  const [agents, skills, guides, rules, hooks, contexts, pipelines] = await Promise.all([
     getAgents(targetDir),
     getSkills(targetDir),
     getGuides(targetDir),
-    getRules(targetDir)
+    getRules(targetDir),
+    getHooks(targetDir),
+    getContexts(targetDir),
+    getPipelines(targetDir)
   ]);
   if (format !== "json") {
     displayComponents(agents, "agents", format);
     displayComponents(skills, "skills", format);
     displayComponents(guides, "guides", format);
     displayComponents(rules, "rules", format);
+    displayComponents(hooks, "hooks", format);
+    displayComponents(contexts, "contexts", format);
+    displayComponents(pipelines, "pipelines", format);
   }
-  return [...agents, ...skills, ...guides, ...rules];
+  return [...agents, ...skills, ...guides, ...rules, ...hooks, ...contexts, ...pipelines];
 }
 async function listCommand(type = "all", options = {}) {
   const targetDir = process.cwd();

package/dist/index.js

@@ -780,7 +780,7 @@ async function preserveCustomizations(targetDir, customizations) {
   return preserved;
 }
 function getAllUpdateComponents() {
-  return ["rules", "agents", "skills", "guides", "pipelines", "commands", "hooks", "contexts"];
+  return ["rules", "agents", "skills", "guides", "pipelines", "hooks", "contexts"];
 }
 async function getLatestVersion() {
   const manifestPath = resolveTemplatePath("manifest.json");
@@ -825,11 +825,10 @@ async function updateComponent(targetDir, component, customizations, options) {
 function getComponentPath(component) {
   const paths = {
     rules: ".claude/rules",
-    agents: "agents",
-    skills: "skills",
+    agents: ".claude/agents",
+    skills: ".claude/skills",
     guides: "guides",
     pipelines: "pipelines",
-    commands: "commands",
     hooks: ".claude/hooks",
     contexts: ".claude/contexts"
   };
@@ -840,7 +839,7 @@ async function backupInstallation(targetDir) {
   const backupDir = join4(targetDir, `.omcustom-backup-${timestamp}`);
   const fs = await import("node:fs/promises");
   await ensureDirectory(backupDir);
-  const dirsToBackup = [".claude", "agents", "skills", "guides", "pipelines", "commands"];
+  const dirsToBackup = [".claude", "guides", "pipelines"];
   for (const dir of dirsToBackup) {
     const srcPath = join4(targetDir, dir);
     if (await fileExists(srcPath)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-customcode",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Batteries-included agent harness for Claude Code",
   "type": "module",
   "bin": {

package/templates/.claude/rules/MUST-orchestrator-coordination.md

@@ -263,6 +263,42 @@ CORRECT:
 ╚══════════════════════════════════════════════════════════════════╝
 ```
 
+## CRITICAL: Use Specialized Agents for Documentation & Spec Writing
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  DOCUMENTATION/SPEC WORK MUST USE SPECIALIZED AGENTS             ║
+║                                                                   ║
+║  Document Type                → Required Agent                   ║
+║  ─────────────────────────────────────────────────               ║
+║  Architecture docs/ADR        → arch-documenter                  ║
+║  API specification (OpenAPI)  → arch-documenter                  ║
+║  Technical design docs        → arch-documenter                  ║
+║  Frontend UI/page specs       → fe-vercel-agent / fe-* agents    ║
+║  Component design specs       → fe-vercel-agent / fe-* agents    ║
+║  CI/CD pipeline specs         → mgr-gitnerd                      ║
+║  GitHub repository config     → mgr-gitnerd                      ║
+║  Docker/infra specs           → infra-docker-expert              ║
+║  AWS architecture specs       → infra-aws-expert                 ║
+║  Database schema specs        → db-supabase-expert               ║
+║  Test strategy/plans          → qa-planner                       ║
+║  Test case documentation      → qa-writer                        ║
+║                                                                   ║
+║  WRONG:                                                          ║
+║    orchestrator → Task(general-purpose) → writes API spec        ║
+║                                                                   ║
+║  CORRECT:                                                        ║
+║    orchestrator → Task(arch-documenter) → writes API spec        ║
+║                                                                   ║
+║  general-purpose should ONLY be used when:                       ║
+║  - No specialized agent exists for the document type             ║
+║  - Document is truly generic (meeting notes, simple lists)       ║
+║                                                                   ║
+║  RULE: If the document requires domain expertise to write        ║
+║        correctly, it MUST be delegated to the domain expert.     ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
 ## CRITICAL: Sub-agent Model Specification
 
 ```

package/templates/CLAUDE.md.en

@@ -89,12 +89,15 @@ When 2 or more tasks are INDEPENDENT:
 Detection: If tasks don't share state or have dependencies -> PARALLEL
 ```
 
-### 4. Agent Routing (ENFORCED for multi-agent tasks)
+### 4. Orchestrator Coordination (ENFORCED for multi-agent tasks)
 ```
 When task requires multiple agents:
--> Routing skills analyze request and route to appropriate agents
--> Agents execute tasks based on their expertise
--> Results are aggregated and returned
+-> Main conversation (orchestrator) MUST coordinate
+-> Main conversation assigns tasks to appropriate agents
+-> Main conversation aggregates results
+
+Flow:
+  User -> Main conversation -> [agent-1, agent-2, agent-3] -> Main conversation -> User
 ```
 
 ---
@@ -106,15 +109,14 @@ When task requires multiple agents:
 ### MUST (Never violate)
 | ID | Rule | Description |
 |----|------|-------------|
-| R000 | Language Policy | English I/O and files |
+| R000 | Language Policy | Korean I/O, English files, delegation model |
 | R001 | Safety Rules | Prohibited actions, required checks |
 | R002 | Permission Rules | Tool tiers, file access scope |
 | R006 | Agent Design | Agent structure, separation of concerns |
 | R007 | Agent Identification | **ENFORCED** - Display agent/skill in ALL responses |
 | R008 | Tool Identification | **ENFORCED** - Display agent when using ANY tool |
-| R009 | Parallel Execution | **ENFORCED** - Parallel execution for independent tasks |
-| R010 | Agent Routing | **ENFORCED** - Agent routing for multi-agent tasks |
-| R015 | Intent Transparency | **MUST** - Transparent agent routing |
+| R009 | Parallel Execution | **ENFORCED** - Parallel execution, large task decomposition |
+| R010 | Orchestrator Coordination | **ENFORCED** - Orchestrator coordination, session continuity, direct action prohibition |
 | R016 | Continuous Improvement | **ENFORCED** - Update rules when violations occur |
 | R017 | Sync Verification | **ENFORCED** - Verify sync before structural changes |
 
@@ -123,10 +125,11 @@ When task requires multiple agents:
 |----|------|-------------|
 | R003 | Interaction Rules | Response principles, status format |
 | R004 | Error Handling | Error levels, recovery strategy |
-| R011 | Memory Integration | Session persistence |
+| R011 | Memory Integration | Session persistence with claude-mem |
 | R012 | HUD Statusline | Real-time status display |
 | R013 | Ecomode | Token efficiency for batch ops |
 | R014 | Pipeline Mode | Sequential workflow execution |
+| R015 | Intent Transparency | **MUST** - Transparent agent routing |
 
 ### MAY (Optional)
 | ID | Rule | Description |
@@ -135,98 +138,70 @@ When task requires multiple agents:
 
 ## Commands
 
-Commands use `/slash-command` format.
+### Slash Commands (from Skills)
 
-### System Commands
 | Command | Description |
 |---------|-------------|
+| `/create-agent` | Create a new agent |
+| `/update-docs` | Sync documentation with project structure |
+| `/update-external` | Update agents from external sources |
+| `/audit-agents` | Audit agent dependencies |
+| `/fix-refs` | Fix broken references |
+| `/dev-review` | Review code for best practices |
+| `/dev-refactor` | Refactor code |
+| `/memory-save` | Save session context to claude-mem |
+| `/memory-recall` | Search and recall memories |
+| `/pipeline-run` | Execute a defined pipeline |
+| `/pipeline-list` | List available pipelines |
+| `/npm-publish` | Publish package to npm registry |
+| `/npm-version` | Manage semantic versions |
+| `/npm-audit` | Audit dependencies |
+| `/optimize-analyze` | Analyze bundle and performance |
+| `/optimize-bundle` | Optimize bundle size |
+| `/optimize-report` | Generate optimization report |
+| `/sauron-watch` | Full R017 verification |
 | `/lists` | Show all available commands |
 | `/status` | Show system status |
 | `/help` | Show help information |
 
-### Manager Commands
-| Command | Description |
-|---------|-------------|
-| `/mgr-creator:agent` | Create a new agent |
-| `/mgr-updater:docs` | Sync documentation with project structure |
-| `/mgr-supplier:audit` | Audit agent dependencies |
-| `/mgr-supplier:fix` | Fix broken references |
-| `/sys-naggy:list` | Show all TODO items |
-| `/sys-naggy:add` | Add a new TODO item |
-| `/sys-naggy:done` | Mark TODO item as complete |
-| `/mgr-gitnerd:commit` | Create a git commit |
-| `/mgr-gitnerd:branch` | Create or switch branches |
-| `/mgr-gitnerd:pr` | Create a pull request |
-| `/mgr-gitnerd:sync` | Sync with remote repository |
-| `/mgr-sync-checker:check` | Run full synchronization check |
-| `/mgr-sauron:watch` | Full R017 verification |
-| `/mgr-sauron:quick` | Quick verification |
-
-### Dev Commands
-| Command | Description |
-|---------|-------------|
-| `/dev:review` | Review code for best practices |
-| `/dev:refactor` | Refactor code |
-
-### Tooling Commands
-| Command | Description |
-|---------|-------------|
-| `/tool-npm-expert:publish` | Publish package to npm registry |
-| `/tool-npm-expert:version` | Manage semantic versions |
-| `/tool-optimizer:analyze` | Analyze bundle and performance |
-| `/tool-optimizer:bundle` | Optimize bundle size |
-
-### Memory Commands
-| Command | Description |
-|---------|-------------|
-| `/sys-memory-keeper:save` | Save session context |
-| `/sys-memory-keeper:recall` | Search and recall memories |
-
-### Pipeline Commands
-| Command | Description |
-|---------|-------------|
-| `/pipeline:run` | Execute a defined pipeline |
-| `/pipeline:list` | List available pipelines |
-
 ## Project Structure
 
 ```
 project/
 +-- CLAUDE.md                    # Entry point
 +-- .claude/
+|   +-- agents/                  # Subagent definitions (34 files)
+|   +-- skills/                  # Skills (42 directories)
 |   +-- rules/                   # Global rules (R000-R017)
-|   +-- hooks/                   # Hook scripts
-|   +-- contexts/                # Context files
-|   +-- agents/                  # Flat agent directory
-|   |   +-- lang-golang-expert/
-|   |   +-- lang-python-expert/
-|   |   +-- be-fastapi-expert/
-|   |   +-- fe-vercel-agent/
-|   |   +-- mgr-creator/
-|   |   +-- sys-memory-keeper/
-|   |   +-- ... (34 total)
-|   +-- skills/                  # Skill definitions
-|   |   +-- routing/
-|   |   +-- development/
-|   |   +-- backend/
-|   |   +-- infrastructure/
-|   |   +-- system/
-+-- guides/                      # Reference docs
+|   +-- hooks/                   # Hook scripts (memory, HUD)
+|   +-- contexts/                # Context files (ecomode)
++-- guides/                      # Reference docs (13 topics)
 +-- pipelines/                   # Pipeline definitions
+|   +-- templates/
+|   +-- examples/
 ```
 
+## Orchestration
+
+Orchestration is handled by routing skills in the main conversation:
+- **secretary-routing**: Routes management tasks to manager agents
+- **dev-lead-routing**: Routes development tasks to language/framework experts
+- **qa-lead-routing**: Coordinates QA workflow
+
+The main conversation acts as the sole orchestrator. Subagents cannot spawn other subagents.
+
 ## Agents Summary
 
 | Type | Count | Agents |
 |------|-------|--------|
-| Language | 6 | lang-golang-expert, lang-python-expert, lang-rust-expert, lang-kotlin-expert, lang-typescript-expert, lang-java21-expert |
-| Backend | 5 | be-fastapi-expert, be-springboot-expert, be-go-backend-expert, be-express-expert, be-nestjs-expert |
-| Frontend | 3 | fe-vercel-agent, fe-vuejs-agent, fe-svelte-agent |
-| Tooling | 3 | tool-npm-expert, tool-optimizer, tool-bun-expert |
-| Database | 1 | db-supabase-expert |
-| Architect | 2 | arch-documenter, arch-speckit-agent |
-| Infrastructure | 2 | infra-docker-expert, infra-aws-expert |
-| QA | 3 | qa-planner, qa-writer, qa-engineer |
+| SW Engineer/Language | 6 | lang-golang-expert, lang-python-expert, lang-rust-expert, lang-kotlin-expert, lang-typescript-expert, lang-java21-expert |
+| SW Engineer/Backend | 5 | be-fastapi-expert, be-springboot-expert, be-go-backend-expert, be-express-expert, be-nestjs-expert |
+| SW Engineer/Frontend | 3 | fe-vercel-agent, fe-vuejs-agent, fe-svelte-agent |
+| SW Engineer/Tooling | 3 | tool-npm-expert, tool-optimizer, tool-bun-expert |
+| SW Engineer/Database | 1 | db-supabase-expert |
+| SW Architect | 2 | arch-documenter, arch-speckit-agent |
+| Infra Engineer | 2 | infra-docker-expert, infra-aws-expert |
+| QA Team | 3 | qa-planner, qa-writer, qa-engineer |
 | Manager | 6 | mgr-creator, mgr-updater, mgr-supplier, mgr-gitnerd, mgr-sync-checker, mgr-sauron |
 | System | 2 | sys-memory-keeper, sys-naggy |
 | Tutor | 1 | tutor-go |
@@ -238,23 +213,45 @@ project/
 # Show all commands
 /lists
 
-# Audit dependencies
-/mgr-supplier:audit
-
-# Create new agent
-/mgr-creator:agent my-agent --type language
+# Agent management
+/create-agent my-agent
+/update-docs
+/audit-agents
 
-# Review code
-/dev:review src/main.go
+# Code review
+/dev-review src/main.go
 
 # Memory management
-/sys-memory-keeper:save
-/sys-memory-keeper:recall authentication
+/memory-save
+/memory-recall authentication
 
 # Pipeline execution
-/pipeline:list
-/pipeline:run code-review --input file_path=src/main.go
+/pipeline-list
+/pipeline-run code-review --input file_path=src/main.go
 
-# Override intent detection
-@lang-golang-expert review this
+# Verification
+/sauron-watch
 ```
+
+## Git Workflow (MUST follow)
+
+| Branch | Purpose |
+|--------|---------|
+| `develop` | Main development branch (default) |
+| `feature/*` | New features -> PR to develop |
+| `release/*` | Release preparation -> **npm publish here only** |
+| `hotfix/*` | Critical fixes -> tag -> publish -> merge to develop |
+
+**Publishing flow:**
+```
+develop → release/x.y.z → npm publish → merge back to develop
+```
+
+**Key rules:**
+- Create feature branches from `develop`
+- **npm publish MUST only happen from release branch**
+- Use conventional commits: `feat:`, `fix:`, `docs:`, `chore:`
+- Include "Closes #N" in commit message to auto-close issues
+- Pre-commit hooks run tests automatically
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed workflow.

package/templates/CLAUDE.md.ko

@@ -92,9 +92,12 @@ oh-my-customcode로 구동됩니다.
 ### 4. 오케스트레이터 조율 (다중 에이전트 작업 시 강제)
 ```
 작업에 여러 에이전트가 필요할 때:
--> secretary (오케스트레이터)가 반드시 조율
--> secretary가 적절한 에이전트에 작업 할당
--> secretary가 결과 집계
+-> 메인 대화 (오케스트레이터)가 반드시 조율
+-> 메인 대화가 적절한 에이전트에 작업 할당
+-> 메인 대화가 결과 집계
+
+흐름:
+  사용자 -> 메인 대화 -> [agent-1, agent-2, agent-3] -> 메인 대화 -> 사용자
 ```
 
 ---
@@ -106,15 +109,14 @@ oh-my-customcode로 구동됩니다.
 ### MUST (절대 위반 금지)
 | ID | 규칙 | 설명 |
 |----|------|------|
-| R000 | 언어 정책 | 한국어 입출력, 영어 파일 |
+| R000 | 언어 정책 | 한국어 입출력, 영어 파일, 위임 모델 |
 | R001 | 안전 규칙 | 금지된 작업, 필수 확인 |
 | R002 | 권한 규칙 | 도구 티어, 파일 접근 범위 |
 | R006 | 에이전트 설계 | 에이전트 구조, 관심사 분리 |
 | R007 | 에이전트 식별 | **강제** - 모든 응답에 에이전트/스킬 표시 |
 | R008 | 도구 식별 | **강제** - 모든 도구 사용 시 에이전트 표시 |
-| R009 | 병렬 실행 | **강제** - 독립 작업 병렬 실행 |
-| R010 | 오케스트레이터 조율 | **강제** - 다중 에이전트 작업 조율 |
-| R015 | 의도 투명성 | **필수** - 투명한 에이전트 라우팅 |
+| R009 | 병렬 실행 | **강제** - 병렬 실행, 대규모 작업 분해 |
+| R010 | 오케스트레이터 조율 | **강제** - 오케스트레이터 조율, 세션 연속성, 직접 실행 금지 |
 | R016 | 지속적 개선 | **강제** - 위반 발생 시 규칙 업데이트 |
 | R017 | 동기화 검증 | **강제** - 구조 변경 전 검증 |
 
@@ -123,10 +125,11 @@ oh-my-customcode로 구동됩니다.
 |----|------|------|
 | R003 | 상호작용 규칙 | 응답 원칙, 상태 형식 |
 | R004 | 오류 처리 | 오류 수준, 복구 전략 |
-| R011 | 메모리 통합 | 세션 지속성 |
+| R011 | 메모리 통합 | claude-mem을 통한 세션 지속성 |
 | R012 | HUD 상태줄 | 실시간 상태 표시 |
 | R013 | Ecomode | 배치 작업 토큰 효율성 |
 | R014 | 파이프라인 모드 | 순차 워크플로우 실행 |
+| R015 | 의도 투명성 | **필수** - 투명한 에이전트 라우팅 |
 
 ### MAY (선택)
 | ID | 규칙 | 설명 |
@@ -135,97 +138,70 @@ oh-my-customcode로 구동됩니다.
 
 ## 커맨드
 
-형식: `/slash-command [인자]`
+### 슬래시 커맨드 (스킬 기반)
 
-### 시스템 커맨드
 | 커맨드 | 설명 |
 |--------|------|
+| `/create-agent` | 새 에이전트 생성 |
+| `/update-docs` | 프로젝트 구조와 문서 동기화 |
+| `/update-external` | 외부 소스에서 에이전트 업데이트 |
+| `/audit-agents` | 에이전트 의존성 감사 |
+| `/fix-refs` | 깨진 참조 수정 |
+| `/dev-review` | 코드 베스트 프랙티스 리뷰 |
+| `/dev-refactor` | 코드 리팩토링 |
+| `/memory-save` | 세션 컨텍스트를 claude-mem에 저장 |
+| `/memory-recall` | 메모리 검색 및 리콜 |
+| `/pipeline-run` | 정의된 파이프라인 실행 |
+| `/pipeline-list` | 사용 가능한 파이프라인 목록 |
+| `/npm-publish` | npm 레지스트리에 패키지 배포 |
+| `/npm-version` | 시맨틱 버전 관리 |
+| `/npm-audit` | 의존성 감사 |
+| `/optimize-analyze` | 번들 및 성능 분석 |
+| `/optimize-bundle` | 번들 크기 최적화 |
+| `/optimize-report` | 최적화 리포트 생성 |
+| `/sauron-watch` | 전체 R017 검증 |
 | `/lists` | 모든 사용 가능한 커맨드 표시 |
 | `/status` | 시스템 상태 표시 |
 | `/help` | 도움말 표시 |
 
-### 매니저 커맨드
-| 커맨드 | 설명 |
-|--------|------|
-| `/mgr-creator:agent` | 새 에이전트 생성 |
-| `/mgr-updater:docs` | 프로젝트 구조와 문서 동기화 |
-| `/mgr-supplier:audit` | 에이전트 의존성 감사 |
-| `/mgr-supplier:fix` | 깨진 참조 수정 |
-| `/sys-naggy:list` | 모든 TODO 항목 표시 |
-| `/sys-naggy:add` | 새 TODO 항목 추가 |
-| `/sys-naggy:done` | TODO 항목 완료 처리 |
-| `/mgr-gitnerd:commit` | git 커밋 생성 |
-| `/mgr-gitnerd:branch` | 브랜치 생성/전환 |
-| `/mgr-gitnerd:pr` | 풀 리퀘스트 생성 |
-| `/mgr-gitnerd:sync` | 원격 저장소와 동기화 |
-| `/mgr-sync-checker:check` | 전체 동기화 검사 실행 |
-| `/mgr-sauron:watch` | 전체 R017 검증 |
-| `/mgr-sauron:quick` | 빠른 검증 |
-
-### 개발 커맨드
-| 커맨드 | 설명 |
-|--------|------|
-| `/dev:review` | 코드 베스트 프랙티스 리뷰 |
-| `/dev:refactor` | 코드 리팩토링 |
-
-### 툴링 커맨드
-| 커맨드 | 설명 |
-|--------|------|
-| `/tool-npm-expert:publish` | npm 레지스트리에 패키지 배포 |
-| `/tool-npm-expert:version` | 시맨틱 버전 관리 |
-| `/tool-optimizer:analyze` | 번들 및 성능 분석 |
-| `/tool-optimizer:bundle` | 번들 크기 최적화 |
-
-### 메모리 커맨드
-| 커맨드 | 설명 |
-|--------|------|
-| `/sys-memory-keeper:save` | 세션 컨텍스트 저장 |
-| `/sys-memory-keeper:recall` | 메모리 검색 및 리콜 |
-
-### 파이프라인 커맨드
-| 커맨드 | 설명 |
-|--------|------|
-| `/pipeline:run` | 정의된 파이프라인 실행 |
-| `/pipeline:list` | 사용 가능한 파이프라인 목록 |
-
 ## 프로젝트 구조
 
 ```
 project/
 +-- CLAUDE.md                    # 진입점
 +-- .claude/
+|   +-- agents/                  # 서브에이전트 정의 (34 파일)
+|   +-- skills/                  # 스킬 (42 디렉토리)
 |   +-- rules/                   # 전역 규칙 (R000-R017)
-|   +-- hooks/                   # 훅 스크립트
-|   +-- contexts/                # 컨텍스트 파일
-|   +-- agents/                  # 에이전트 (플랫 구조)
-|   |   +-- lang-*               # 언어 전문가 (6)
-|   |   +-- be-*                 # 백엔드 전문가 (5)
-|   |   +-- fe-*                 # 프론트엔드 전문가 (3)
-|   |   +-- tool-*               # 툴링 전문가 (3)
-|   |   +-- db-*                 # 데이터베이스 전문가 (1)
-|   |   +-- arch-*               # 아키텍트 (2)
-|   |   +-- infra-*              # 인프라 전문가 (2)
-|   |   +-- qa-*                 # QA 팀 (3)
-|   |   +-- mgr-*                # 매니저 (6)
-|   |   +-- sys-*                # 시스템 (2)
-|   |   +-- tutor-*              # 튜터 (1)
-|   +-- skills/                  # 스킬 (routing/, execution/)
-+-- guides/                      # 레퍼런스 문서 (12)
+|   +-- hooks/                   # 훅 스크립트 (메모리, HUD)
+|   +-- contexts/                # 컨텍스트 파일 (ecomode)
++-- guides/                      # 레퍼런스 문서 (13 토픽)
 +-- pipelines/                   # 파이프라인 정의
+|   +-- templates/
+|   +-- examples/
 ```
 
+## 오케스트레이션
+
+오케스트레이션은 메인 대화의 라우팅 스킬로 처리됩니다:
+- **secretary-routing**: 매니저 에이전트로 관리 작업 라우팅
+- **dev-lead-routing**: 언어/프레임워크 전문가에게 개발 작업 라우팅
+- **qa-lead-routing**: QA 워크플로우 조율
+
+메인 대화가 유일한 오케스트레이터 역할을 합니다. 서브에이전트는 다른 서브에이전트를 생성할 수 없습니다.
+
 ## 에이전트 요약
 
 | 타입 | 수량 | 에이전트 |
 |------|------|----------|
-| Language | 6 | lang-golang-expert, lang-python-expert, lang-rust-expert, lang-kotlin-expert, lang-typescript-expert, lang-java21-expert |
-| Backend | 5 | be-fastapi-expert, be-springboot-expert, be-go-backend-expert, be-express-expert, be-nestjs-expert |
-| Frontend | 3 | fe-vercel-agent, fe-vuejs-agent, fe-svelte-agent |
-| Tooling | 3 | tool-npm-expert, tool-optimizer, tool-bun-expert |
-| Database | 1 | db-supabase-expert |
-| Architect | 2 | arch-documenter, arch-speckit-agent |
-| Infrastructure | 2 | infra-docker-expert, infra-aws-expert |
-| QA | 3 | qa-planner, qa-writer, qa-engineer |
+| SW Engineer/Language | 6 | lang-golang-expert, lang-python-expert, lang-rust-expert, lang-kotlin-expert, lang-typescript-expert, lang-java21-expert |
+| SW Engineer/Backend | 5 | be-fastapi-expert, be-springboot-expert, be-go-backend-expert, be-express-expert, be-nestjs-expert |
+| SW Engineer/Frontend | 3 | fe-vercel-agent, fe-vuejs-agent, fe-svelte-agent |
+| SW Engineer/Tooling | 3 | tool-npm-expert, tool-optimizer, tool-bun-expert |
+| SW Engineer/Database | 1 | db-supabase-expert |
+| SW Architect | 2 | arch-documenter, arch-speckit-agent |
+| Infra Engineer | 2 | infra-docker-expert, infra-aws-expert |
+| QA Team | 3 | qa-planner, qa-writer, qa-engineer |
 | Manager | 6 | mgr-creator, mgr-updater, mgr-supplier, mgr-gitnerd, mgr-sync-checker, mgr-sauron |
 | System | 2 | sys-memory-keeper, sys-naggy |
 | Tutor | 1 | tutor-go |
@@ -237,23 +213,45 @@ project/
 # 모든 커맨드 표시
 /lists
 
-# 의존성 감사
-/mgr-supplier:audit
-
-# 새 에이전트 생성
-/mgr-creator:agent my-agent --type lang
+# 에이전트 관리
+/create-agent my-agent
+/update-docs
+/audit-agents
 
 # 코드 리뷰
-/dev:review src/main.go
+/dev-review src/main.go
 
 # 메모리 관리
-/sys-memory-keeper:save
-/sys-memory-keeper:recall authentication
+/memory-save
+/memory-recall authentication
 
 # 파이프라인 실행
-/pipeline:list
-/pipeline:run code-review --input file_path=src/main.go
+/pipeline-list
+/pipeline-run code-review --input file_path=src/main.go
+
+# 검증
+/sauron-watch
+```
+
+## Git 워크플로우 (반드시 준수)
+
+| 브랜치 | 용도 |
+|--------|------|
+| `develop` | 메인 개발 브랜치 (기본) |
+| `feature/*` | 새 기능 -> develop으로 PR |
+| `release/*` | 릴리스 준비 -> **npm 배포는 여기서만** |
+| `hotfix/*` | 긴급 수정 -> 태그 -> 배포 -> develop 머지 |
 
-# 의도 감지 오버라이드
-@lang-golang-expert 이것 리뷰해줘
+**퍼블리싱 흐름:**
 ```
+develop → release/x.y.z → npm publish → develop 머지
+```
+
+**핵심 규칙:**
+- `develop`에서 feature 브랜치 생성
+- **npm publish는 반드시 release 브랜치에서만**
+- Conventional commits 사용: `feat:`, `fix:`, `docs:`, `chore:`
+- 커밋 메시지에 "Closes #N" 포함시 이슈 자동 종료
+- Pre-commit 훅이 테스트 자동 실행
+
+자세한 워크플로우는 [CONTRIBUTING.md](CONTRIBUTING.md) 참조.