# 🎨 Emoji Naming Convention
**Version:** 1.0.0
**Status:** ACTIVE
**Approved By:** Felipe (2025-10-21)

---

## 🎯 Mission

**Universal visual language across all systems:**
- GitHub issues = same emoji as Forge tasks = same emoji as Agent sessions
- Instant recognition without reading title
- Same language everywhere: Genie ↔ Forge ↔ GitHub

---

## 📋 Standard Format

```
[<emoji>] <Type>: <Title> (#GitHubIssue)
```

**Brackets provide:**
- Structure for extraction/parsing
- Visual framing that makes emojis pop
- Clear boundaries between emoji and text

**Examples:**
```
[🐛] Bug: Forge executor hardcodes base_branch (#154)
[💭] Wish: MCP Server Authentication (#152)
[📚] Learn: Task Naming Convention Standardization (#157)
[⚙️] Forge: Drop-in replacement executor (#143)
[🤖] implementor: background
```

---

## 🎨 Work Type Emojis

### Core Work Types

| Emoji | Type | When To Use |
|-------|------|-------------|
| 🐛 | Bug | Something broken, needs fixing |
| 💭 | Wish | Discovery/planning for new features |
| 📚 | Learn | Research, investigation, knowledge capture |
| ⚙️ | Forge | Implementation of approved work |
| ✅ | Review | Quality assurance, validation |
| 🔨 | Refactor | Code improvement without new features |
| 📖 | Docs | Writing/updating documentation |
| 🧹 | Chore | Maintenance, dependencies, housekeeping |

---

## 🧞 Agent Emojis

### Core Orchestrators

| Emoji | Agent | Usage |
|-------|-------|-------|
| 🧞 | Genie | Main orchestrator |
| 💭 | Wish | Wish dance orchestrator |
| ⚙️ | Forge | Task breakdown |
| ✅ | Review | Quality validation |

### Specialist Agents

| Emoji | Agent | Usage |
|-------|-------|-------|
| 🤖 | Implementor | Code implementation (robot) |
| 🤖 | Tests | Test writing (robot) |
| 🤖 | Polish | Code polishing (robot) |
| 🤖 | Refactor | Code refactoring (robot) |
| 🚀 | Release | Release management |
| ✍️ | Prompt | Instruction writing |
| 🔧 | Git | GitHub operations |
| 📝 | Commit | Commit crafting |
| 🔍 | Debug | Debugging |
| 🏗️ | Install | Installation |

**Note:** 🤖 Robot emoji for all execution agents (they do the work)

### Thinking Modes

| Emoji | Agent | Usage |
|-------|-------|-------|
| 🧠 | Analyze | Deep analysis |
| 🎯 | Plan | Strategic planning |
| 🤔 | Socratic | Questioning/learning |
| 🔬 | Deep-Dive | Detailed investigation |
| 🎓 | Explore | Codebase exploration |

---

## 🎯 Usage Guidelines

### When Creating Forge Tasks

**Format:**
```typescript
await mcp__automagik_forge__create_task({
  project_id: projectId,
  title: "[🐛] Bug: Clear description of the bug (#GitHubIssueNumber)",
  description: "Full context here..."
});
```

**Rules:**
1. **Choose ONE emoji** from work type table
2. **Wrap in brackets:** `[🐛]` not `🐛`
3. **Match work type:** Bug=🐛, Wish=💭, Learn=📚, Forge=⚙️, etc.
4. **Include GitHub issue:** `(#NNN)` at end of title
5. **Keep title ≤ 80 characters** including emoji and brackets

### When Creating GitHub Issues

**Format:**
```bash
gh issue create \
  --title "[🐛] Bug: Clear description of the bug" \
  --body "Full description..." \
  --label "type:bug,area:forge"
```

**After creation, update Forge task to include issue number:**
```typescript
await mcp__automagik_forge__update_task({
  task_id: taskId,
  title: "[🐛] Bug: Clear description (#157)"  // Add issue number
});
```

### When Starting Agent Sessions

**Format:**
```typescript
await mcp__genie__run({
  agent: "implementor",
  name: "[🤖] implementor: fix-forge-base-branch",
  prompt: "Fix base branch hardcoding..."
});
```

**Pattern:** `[<emoji>] <Agent>: <brief-description>`

**Note:** Agent session names are auto-generated by forge-executor.ts with correct emoji

---

## 📋 Decision Tree

**"Which emoji should I use?"**

### For Tasks
1. **Is it broken?** → [🐛] Bug
2. **New feature (planning)?** → [💭] Wish
3. **New feature (implementing)?** → [⚙️] Forge
4. **Research/investigation?** → [📚] Learn
5. **Quality check?** → [✅] Review
6. **Clean up code?** → [🔨] Refactor
7. **Write docs?** → [📖] Docs
8. **Maintenance?** → [🧹] Chore

### For Agent Sessions
1. **Which agent am I starting?**
2. **Find agent in emoji table**
3. **Use that emoji in brackets**

Example: Starting implementor → [🤖] implementor

---

## ✅ Examples by Scenario

### Bug Fix Workflow
```
GitHub: [🐛] Bug: Forge executor hardcodes base_branch
Forge:  [🐛] Bug: Forge executor hardcodes base_branch (#154)
Agent:  [🤖] implementor: fix-forge-base-branch-hardcoding
```

### Wish Workflow
```
GitHub: [💭] Wish: MCP Server Authentication
Forge:  [💭] Wish: MCP Server Authentication (#152)
Agent:  [💭] wish: mcp-auth-discovery
        [⚙️] forge: mcp-auth-execution-plan
        [🤖] implementor: mcp-auth-endpoints
        [✅] review: mcp-auth-validation
```

### Learn Task
```
GitHub: [📚] Learn: Task Naming Convention Standardization
Forge:  [📚] Learn: Task Naming Convention Standardization (#157)
Forge:  [🧹] Chore: Unified Emoji Naming Convention (updated from Learn to Chore per Felipe)
```

---

## 🚫 Common Mistakes

### ❌ Wrong Format
```
Bad:  Task 1: Forge Project Auto-Sync
Bad:  🧹 Chore: Missing brackets
Good: [🧹] Chore: Forge Project Auto-Sync on MCP Startup
```

### ❌ Missing Issue Reference
```
Bad:  [🐛] Bug: Forge executor hardcodes base_branch
Good: [🐛] Bug: Forge executor hardcodes base_branch (#154)
```

### ❌ Wrong Emoji
```
Bad:  [🐛] Bug: Add new authentication feature  (not a bug!)
Good: [💭] Wish: MCP Server Authentication
```

### ❌ Multiple Emojis
```
Bad:  [🐛💭] Bug Wish: Something confusing
Good: [🐛] Bug: Clear single-purpose title
```

---

## 🎨 Emoji Quick Reference (Copy-Paste)

```
Work Types:
[🐛] Bug          [💭] Wish         [📚] Learn        [⚙️] Forge
[✅] Review       [🔨] Refactor     [📖] Docs         [🧹] Chore

Execution Agents (Robots):
[🤖] implementor  [🤖] tests        [🤖] polish       [🤖] refactor

Core Agents:
[🧞] genie        [🔧] git          [🚀] release      [📝] commit
[✍️] prompt       [🔍] debug        [🏗️] install

Thinking:
[🧠] analyze      [🎯] plan         [🤔] socratic     [🔬] deep-dive
[🎓] explore
```

---

## 📚 Implementation Checklist

**When creating Forge tasks:**
- [ ] Choose emoji from work type table
- [ ] Format: `[<emoji>] <Type>: <Title> (#Issue)`
- [ ] Wrap emoji in brackets: `[🐛]` not `🐛`
- [ ] Verify title ≤ 80 characters (including brackets)
- [ ] Include GitHub issue number
- [ ] Same emoji across all systems

**When creating GitHub issues:**
- [ ] Choose emoji from work type table
- [ ] Format: `[<emoji>] <Type>: <Title>`
- [ ] Wrap emoji in brackets
- [ ] Add appropriate labels
- [ ] Update Forge task with issue number after creation

**When starting agent sessions:**
- [ ] Choose emoji from agent table
- [ ] Format: `[<emoji>] <agent>: <description>`
- [ ] Use robot emoji [🤖] for execution agents
- [ ] Keep description brief and clear
- [ ] Auto-generated by forge-executor.ts

---

## 🔗 Related Documentation

- **Full Spec:** `.genie/reports/emoji-naming-standard.md` - Complete taxonomy
- **Proposals:** `.genie/reports/task-naming-5-proposals.md` - How we chose emoji format
- **Mapping:** `.genie/reports/task-rename-mapping.md` - Before/after examples

---

## ✨ Benefits

**Why emojis?**
1. ⚡ **60,000x faster** visual recognition than text
2. 🎨 **Universal** - works across all platforms (GitHub, Forge, CLI)
3. 🔍 **Scannable** - find tasks by visual shape, not reading
4. 🌍 **Language-agnostic** - same meaning globally
5. 🎯 **Consistent** - one language everywhere

**Impact:**
- Faster kanban scanning
- Instant task type recognition
- Unified developer experience
- Reduced cognitive load

---

**Remember:** Same emoji = same meaning = same language everywhere 🎯