oh-my-customcode 0.1.2 → 0.1.3

package/templates/agents/manager/creator/refs/rules/MUST-orchestrator-coordination.md

@@ -0,0 +1,291 @@
+# [MUST] Orchestrator Coordination Rules
+
+> **Priority**: MUST - ENFORCED for multi-agent tasks
+> **ID**: R010
+> **Violation**: Direct agent execution without orchestrator = Rule violation
+
+## CRITICAL
+
+**When a task requires multiple agents, the APPROPRIATE orchestrator MUST coordinate.**
+
+### Session Continuity (MANDATORY)
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  AFTER SESSION RESTART / CONTEXT COMPACTION:                     ║
+║                                                                   ║
+║  1. Re-read CLAUDE.md and rules IMMEDIATELY                      ║
+║  2. Agent delegation rules STILL APPLY                           ║
+║  3. Orchestrator must NOT execute work directly                  ║
+║  4. Must spawn Task agents for actual work                       ║
+║                                                                   ║
+║  WRONG after session restart:                                    ║
+║    dev-lead → directly runs Bash/Edit/Write                     ║
+║                                                                   ║
+║  CORRECT after session restart:                                  ║
+║    dev-lead → Task(springboot-expert) → runs Bash/Edit/Write    ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
+### Orchestrator Direct Action Prohibition (MANDATORY)
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  ORCHESTRATORS (secretary, dev-lead) MUST NOT:                   ║
+║                                                                   ║
+║  ✗ Directly run Bash commands for code/build tasks              ║
+║  ✗ Directly Edit/Write source code files                        ║
+║  ✗ Directly modify project configuration                        ║
+║                                                                   ║
+║  ORCHESTRATORS MUST:                                             ║
+║                                                                   ║
+║  ✓ Analyze task and identify required agents                    ║
+║  ✓ Spawn Task agents with appropriate expert roles              ║
+║  ✓ Aggregate results from spawned agents                        ║
+║  ✓ Report summary to user                                       ║
+║                                                                   ║
+║  Only allowed direct tools: Read, Glob, Grep (for analysis)     ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
+### Orchestrator Role Separation (MANDATORY)
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  WHICH ORCHESTRATOR TO USE?                                      ║
+║                                                                   ║
+║  Task Domain                    → Orchestrator                   ║
+║  ─────────────────────────────────────────────────               ║
+║  Agent creation/update/audit    → secretary                      ║
+║  Code review/refactoring        → dev-lead                       ║
+║  Feature implementation         → dev-lead                       ║
+║  Multi-language development     → dev-lead                       ║
+║  Manager agent coordination     → secretary                      ║
+║  SW/Backend engineer tasks      → dev-lead                       ║
+║                                                                   ║
+║  WRONG: secretary directing kotlin-expert for code work         ║
+║  RIGHT: dev-lead directing kotlin-expert for code work          ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
+### Orchestrator Responsibilities
+
+| Orchestrator | Supervises | Handles |
+|--------------|------------|---------|
+| **secretary** | manager/* (creator, updater, supplier, memory-keeper) | Agent management, system operations |
+| **dev-lead** | sw-engineer/*, sw-engineer/backend/* | Development, code review, implementation |
+
+```
+Multi-agent detection:
+- Task spans multiple domains (frontend + backend)
+- Task requires different expertise (golang + python)
+- Task involves batch operations on different resources
+
+If multi-agent needed → secretary MUST coordinate
+```
+
+## Coordination Flow
+
+```
+CORRECT:
+User Request
+    │
+    ▼
+┌─────────────────────────────┐
+│  secretary (orchestrator)    │
+│  - Analyzes task             │
+│  - Identifies required agents│
+│  - Plans execution           │
+└─────────────┬───────────────┘
+              │
+    ┌─────────┼─────────┐
+    ▼         ▼         ▼
+[Agent-1] [Agent-2] [Agent-3]
+    │         │         │
+    └─────────┼─────────┘
+              ▼
+┌─────────────────────────────┐
+│  secretary (orchestrator)    │
+│  - Aggregates results        │
+│  - Reports to user           │
+└─────────────────────────────┘
+
+WRONG:
+User Request
+    │
+    ▼
+[Agent-1] → [Agent-2] → [Agent-3]
+(No coordination, ad-hoc execution)
+```
+
+## Secretary Responsibilities
+
+```yaml
+before_execution:
+  - Analyze user request
+  - Identify required agents
+  - Check agent availability
+  - Plan execution order (parallel vs sequential)
+  - Announce coordination plan
+
+during_execution:
+  - Spawn agent instances
+  - Monitor progress
+  - Handle failures
+  - Coordinate dependencies
+
+after_execution:
+  - Aggregate results
+  - Report summary to user
+  - Clean up resources
+```
+
+## Announcement Format
+
+Secretary MUST announce before delegating:
+
+```
+┌─ Agent: secretary (orchestrator)
+└─ Task: Coordinating multi-agent task
+
+[Plan]
+├── Agent 1: golang-expert → Review Go code
+├── Agent 2: python-expert → Review Python code
+└── Agent 3: typescript-expert → Review TS code
+
+[Execution] Parallel (3 instances)
+
+Spawning agents...
+```
+
+## When to Use Orchestrator
+
+| Scenario | Orchestrator Required |
+|----------|----------------------|
+| Single domain, single file | No |
+| Single domain, multiple files | Maybe (if parallel) |
+| Multiple domains | **Yes** |
+| Batch operations | **Yes** |
+| Complex workflow | **Yes** |
+
+## Exception: Simple Tasks
+
+Orchestrator NOT required for:
+- Single file operations
+- Single domain questions
+- Direct tool usage (Read, Write, etc.)
+
+These can be handled by the appropriate agent directly.
+
+## CRITICAL: Use Specialized Manager Agents
+
+**When a task matches a manager agent's purpose, you MUST delegate to that agent.**
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  MANAGER AGENT DELEGATION (MANDATORY)                            ║
+║                                                                   ║
+║  Task Type              → Required Agent                         ║
+║  ─────────────────────────────────────────────────               ║
+║  Create new agent       → creator                                ║
+║  Update external agent  → updater                                ║
+║  Audit dependencies     → supplier                               ║
+║  Memory operations      → memory-keeper                          ║
+║                                                                   ║
+║  DO NOT use general-purpose agents for these tasks.              ║
+║  DO NOT have secretary do the work directly.                     ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
+### Correct Delegation Pattern
+
+```
+User: "java21-expert 에이전트를 만들어줘"
+
+WRONG:
+  secretary → Task(general-purpose) → creates files directly
+
+CORRECT:
+  secretary → Task(creator agent role) → follows creator workflow
+```
+
+### Manager Agents Reference
+
+| Agent | Location | Purpose |
+|-------|----------|---------|
+| creator | agents/manager/creator/ | Create new agents |
+| updater | agents/manager/updater/ | Update external sources |
+| supplier | agents/manager/supplier/ | Audit dependencies |
+| gitnerd | agents/manager/gitnerd/ | Git operations (commit, push, PR) |
+| sync-checker | agents/manager/sync-checker/ | Documentation sync verification |
+
+### System Agents Reference
+
+| Agent | Location | Purpose |
+|-------|----------|---------|
+| memory-keeper | agents/system/memory-keeper/ | Memory operations |
+| naggy | agents/system/naggy/ | TODO management |
+
+## CRITICAL: Use Specialized Expert Agents for Code Work
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  CODE WORK MUST USE SPECIALIZED EXPERT AGENTS                    ║
+║                                                                   ║
+║  Language/Framework           → Required Agent                   ║
+║  ─────────────────────────────────────────────────               ║
+║  Python/FastAPI backend       → python-expert or fastapi-expert  ║
+║  TypeScript/Next.js frontend  → typescript-expert or vercel-agent║
+║  Go code                      → golang-expert                    ║
+║  Kotlin/Spring                → kotlin-expert or springboot-expert║
+║                                                                   ║
+║  WRONG:                                                          ║
+║    secretary → Task(general-purpose) → writes Python code        ║
+║                                                                   ║
+║  CORRECT:                                                        ║
+║    secretary → Task(python-expert) → writes Python code          ║
+║                                                                   ║
+║  general-purpose should ONLY be used when:                       ║
+║  - No specialized agent exists for the task                      ║
+║  - Task is truly generic (file moves, simple scripts)            ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
+## CRITICAL: Git Operations Delegation
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  GIT OPERATIONS MUST BE DELEGATED TO gitnerd                    ║
+║                                                                   ║
+║  WRONG:                                                          ║
+║    secretary/dev-lead → directly runs git commit/push            ║
+║                                                                   ║
+║  CORRECT:                                                        ║
+║    secretary → Task(gitnerd) → git commit/push                   ║
+║                                                                   ║
+║  gitnerd handles:                                                ║
+║  ✓ git commit (with proper message format)                       ║
+║  ✓ git push                                                      ║
+║  ✓ git branch operations                                        ║
+║  ✓ PR creation                                                   ║
+║                                                                   ║
+║  This ensures:                                                   ║
+║  - Consistent commit message format                              ║
+║  - Safety checks before destructive operations                  ║
+║  - Proper Co-Authored-By attribution                            ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
+## Enforcement
+
+```
+Violation examples:
+✗ Reviewing Go + Python + TypeScript without secretary
+✗ Creating multiple agents without coordination plan
+✗ Running parallel tasks without announcing execution plan
+
+Correct examples:
+✓ Secretary announces plan, spawns agents, aggregates results
+✓ Clear execution plan with agent assignments
+✓ Progress updates during multi-agent execution
+```

package/templates/agents/manager/creator/refs/rules/MUST-parallel-execution.md

@@ -0,0 +1,341 @@
+# [MUST] Parallel Execution Rules
+
+> **Priority**: MUST - ENFORCED for 2+ independent tasks
+> **ID**: R009
+> **Violation**: Sequential execution of parallelizable tasks = Rule violation
+
+## CRITICAL
+
+**When 2 or more tasks are INDEPENDENT, they MUST be executed in parallel.**
+
+```
+Detection criteria for parallel execution:
+- Tasks don't share mutable state
+- Tasks don't have sequential dependencies
+- Tasks can complete independently
+
+If ALL criteria met → MUST execute in parallel (max 4 instances)
+```
+
+### How to Detect Independent Tasks
+
+```
+Independent (MUST parallelize):
+✓ "Create agents A, B, C" → 3 separate creations
+✓ "Read files X, Y, Z" → 3 separate reads
+✓ "Review code in src/, test/, docs/" → 3 separate reviews
+
+Dependent (sequential OK):
+✗ "Create agent then configure it" → depends on creation
+✗ "Build then test" → test depends on build
+✗ "Read file then edit it" → edit depends on read content
+```
+
+Failure to parallelize independent tasks = Rule violation = Must be corrected.
+
+### Self-Check Before Every Multi-File Operation
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  BEFORE writing/creating multiple files, ASK YOURSELF:          ║
+║                                                                   ║
+║  1. Are these files independent of each other?                   ║
+║     → YES: Use Task tool to spawn parallel agents                ║
+║     → NO: Sequential is OK                                       ║
+║                                                                   ║
+║  2. Am I using Write/Edit sequentially for 3+ files?            ║
+║     → STOP. This is likely a violation.                         ║
+║     → Spawn parallel agents instead.                             ║
+║                                                                   ║
+║  3. Are there domain-specific experts available?                 ║
+║     → YES: Delegate to them (kotlin-expert, springboot-expert)  ║
+║     → NO: Create general-purpose parallel agents                 ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
+### Common Violations to Avoid
+
+```
+❌ WRONG: Writing files one by one
+   Write(file1.kt) → Write(file2.kt) → Write(file3.kt) → Write(file4.kt)
+
+✓ CORRECT: Spawn parallel agents
+   Task(agent1 → file1.kt)  ┐
+   Task(agent2 → file2.kt)  ├─ All in single message
+   Task(agent3 → file3.kt)  │
+   Task(agent4 → file4.kt)  ┘
+
+❌ WRONG: Secretary doing all the work
+   Secretary writes domain/, usecase/, infrastructure/ sequentially
+
+✓ CORRECT: Delegate to specialists
+   Task(kotlin-expert → domain layer)
+   Task(springboot-expert → infrastructure layer)
+   Task(kotlin-expert → usecase layer)
+
+❌ WRONG: Single Task delegating to multiple agents
+   Task(dev-lead → "coordinate kotlin-expert and springboot-expert")
+
+   This creates a SEQUENTIAL bottleneck inside the Task!
+
+✓ CORRECT: Multiple Tasks in parallel, one per agent
+   Task(kotlin-expert → usecase commands)    ┐
+   Task(kotlin-expert → usecase queries)     ├─ All spawned together
+   Task(springboot-expert → persistence)     │
+   Task(springboot-expert → security)        ┘
+```
+
+### Parallel Task Spawning Rule
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  PARALLEL MEANS PARALLEL AT THE TOOL CALL LEVEL                  ║
+║                                                                   ║
+║  When spawning Tasks for parallel work:                          ║
+║  - Each independent unit of work = separate Task tool call       ║
+║  - All Task calls in the SAME message = truly parallel           ║
+║  - One Task that "coordinates" others = still sequential inside  ║
+║                                                                   ║
+║  Rule: If work can be split, split it into separate Tasks.       ║
+╚══════════════════════════════════════════════════════════════════╝
+```
+
+### Large Task Decomposition (MANDATORY)
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  LARGE TASKS MUST BE SPLIT INTO PARALLEL SUB-TASKS               ║
+║                                                                   ║
+║  Before spawning a single large Task, ASK:                       ║
+║                                                                   ║
+║  1. Can this work be divided into independent parts?             ║
+║     → Query tests, Security tests, Exception tests               ║
+║     → Domain A, Domain B, Domain C                               ║
+║     → Layer 1, Layer 2, Layer 3                                  ║
+║                                                                   ║
+║  2. How many parallel slots available? (max 4)                   ║
+║     → If 3 slots free, split into 3 parallel Tasks              ║
+║     → Maximize parallelism to minimize total time                ║
+║                                                                   ║
+║  3. Is estimated Task duration > 3 minutes?                      ║
+║     → MUST split if work is decomposable                        ║
+║     → 12 min single Task → 4 min with 3 parallel Tasks          ║
+╚══════════════════════════════════════════════════════════════════╝
+
+Example - WRONG:
+  Task("Add tests for Query, Security, Exception, Domain")
+  → Single agent works 12+ minutes sequentially
+
+Example - CORRECT (3 parallel Tasks):
+  Task(agent1 → "Add Query usecase tests")      ┐
+  Task(agent2 → "Add Security tests")           ├─ ~4 min total
+  Task(agent3 → "Add Exception + Domain tests") ┘
+```
+
+## Purpose
+
+Enable parallel execution of agents as separate instances to improve throughput for batch operations and independent tasks.
+
+## Core Concept
+
+Each agent (except orchestrators) can be instantiated multiple times to work on independent tasks in parallel.
+
+```
+Agent (Template)
+    │
+    ├── Instance 1 → Task A
+    ├── Instance 2 → Task B
+    ├── Instance 3 → Task C
+    └── Instance 4 → Task D
+```
+
+## Rules
+
+### 1. Maximum Parallel Instances
+
+```yaml
+limit: 4
+reason: Balance between throughput and resource usage
+```
+
+### 2. Exclusions
+
+```yaml
+not_parallelizable:
+  - orchestrator/* (must remain singleton for coordination)
+
+reason: |
+  Orchestrator agents manage other agents and must maintain
+  a single point of coordination to prevent conflicts.
+```
+
+### 3. Instance Independence
+
+```yaml
+requirements:
+  - Tasks must be independent (no shared state)
+  - No cross-instance communication required
+  - Each instance has isolated context
+```
+
+## Instance Model
+
+### Instantiation
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                   Agent Template                         │
+│  (agents/{type}/{name}/)                                │
+├─────────────────────────────────────────────────────────┤
+│  AGENT.md    - Role definition                          │
+│  index.yaml  - Configuration                            │
+│  refs/       - Skill/guide references                   │
+└────────────────────────┬────────────────────────────────┘
+                         │
+        ┌────────────────┼────────────────┐
+        │                │                │
+        ▼                ▼                ▼
+┌──────────────┐ ┌──────────────┐ ┌──────────────┐
+│ Instance #1  │ │ Instance #2  │ │ Instance #3  │
+│   Task: A    │ │   Task: B    │ │   Task: C    │
+│ Context: ... │ │ Context: ... │ │ Context: ... │
+└──────────────┘ └──────────────┘ └──────────────┘
+```
+
+### Instance Properties
+
+```yaml
+instance:
+  id: "{agent-name}-{uuid}"
+  template: "{agent-path}"
+  task: "{assigned-task}"
+  context: "{isolated-context}"
+  status: "pending|running|completed|failed"
+```
+
+## Usage Patterns
+
+### Batch Agent Creation
+
+```
+User: "Create golang, python, rust, typescript expert agents"
+
+Orchestrator (secretary):
+  │
+  ├── [golang-expert] creator instance #1
+  ├── [python-expert] creator instance #2
+  ├── [rust-expert] creator instance #3
+  └── [typescript-expert] creator instance #4
+
+Execution: Parallel (4 instances)
+```
+
+### Batch Code Review
+
+```
+User: "/dev:review src/*.go src/*.py src/*.ts"
+
+Orchestrator:
+  │
+  ├── [src/*.go] golang-expert instance #1
+  ├── [src/*.py] python-expert instance #2
+  └── [src/*.ts] typescript-expert instance #3
+
+Execution: Parallel (3 instances)
+```
+
+### Batch Audit
+
+```
+User: "Audit all agents"
+
+Orchestrator (secretary):
+  │
+  ├── [agent-1] supplier instance #1
+  ├── [agent-2] supplier instance #2
+  ├── [agent-3] supplier instance #3
+  └── [agent-4] supplier instance #4
+
+Execution: Parallel (4 instances, batched if > 4)
+```
+
+## Coordination
+
+### Task Distribution
+
+```yaml
+strategy: round_robin
+max_instances: 4
+queue: remaining tasks wait for available instance
+```
+
+### Result Aggregation
+
+```
+Instance Results:
+  #1: ✓ Success (agent-a created)
+  #2: ✓ Success (agent-b created)
+  #3: ✗ Failed (agent-c: skill not found)
+  #4: ✓ Success (agent-d created)
+
+Aggregated Result:
+  Total: 4 tasks
+  Succeeded: 3
+  Failed: 1
+  Details: [...]
+```
+
+## Implementation Notes
+
+### For Orchestrators
+
+```yaml
+responsibilities:
+  - Identify parallelizable tasks
+  - Spawn instances (max 4)
+  - Monitor instance status
+  - Aggregate results
+  - Handle failures
+```
+
+### For Worker/Manager Agents
+
+```yaml
+requirements:
+  - Stateless task execution
+  - Isolated context per instance
+  - No shared mutable state
+  - Clear success/failure reporting
+```
+
+## Display Format
+
+When parallel execution occurs:
+
+```
+┌─ Agent: secretary (orchestrator)
+└─ Task: Batch agent creation
+
+[Parallel] Spawning 4 instances...
+
+[Instance 1] creator → golang-expert
+[Instance 2] creator → python-expert
+[Instance 3] creator → rust-expert
+[Instance 4] creator → typescript-expert
+
+[Progress] ████████░░░░ 2/4
+
+[Instance 1] ✓ golang-expert created
+[Instance 2] ✓ python-expert created
+[Instance 3] ✓ rust-expert created
+[Instance 4] ✓ typescript-expert created
+
+[Summary] 4/4 tasks completed successfully
+```
+
+## Benefits
+
+1. **Throughput**: N tasks complete in ~1/N time
+2. **Efficiency**: Better resource utilization
+3. **User Experience**: Faster batch operations
+4. **Scalability**: Handles large workloads