codingbuddy-rules 4.5.0 → 5.1.0

package/.ai-rules/rules/clarification-guide.md

@@ -98,32 +98,32 @@ Use these categories as reference when generating questions. Adapt to specific c
 ```markdown
 ## Clarification Phase
 
-### 질문 1/3
+### Question 1/3
 
-**[카테고리]에 대한 확인이 필요합니다:**
+**Clarification needed for [Category]:**
 
-[컨텍스트에 맞게 조정된 질문]
+[Question adapted to context]
 
-- **A)** [선택지 1]
-- **B)** [선택지 2]
-- **C)** [선택지 3]
+- **A)** [Option 1]
+- **B)** [Option 2]
+- **C)** [Option 3]
 
-> 답변을 선택해주세요 (A/B/C) 또는 다른 의견이 있으시면 말씀해주세요.
+> Please select your answer (A/B/C) or share your own input.
 ```
 
 ### After All Questions
 
 ```markdown
-## 수집된 정보 요약
+## Collected Information Summary
 
-| 항목 | 결정 사항 |
+| Item | Decision |
 |------|----------|
-| 범위 | [사용자 선택] |
-| 우선순위 | [사용자 선택] |
-| 제약조건 | [사용자 선택] |
+| Scope | [User's selection] |
+| Priority | [User's selection] |
+| Constraints | [User's selection] |
 | ... | ... |
 
-이 내용이 맞나요? 확인해주시면 PLAN 수립을 시작하겠습니다.
+Does this look correct? Once confirmed, we will proceed with creating the PLAN.
 ```
 
 ---
@@ -132,7 +132,7 @@ Use these categories as reference when generating questions. Adapt to specific c
 
 | Situation | Response |
 |-----------|----------|
-| User answers "I'm not sure" / "잘 모르겠어요" | Present default recommendation with rationale, ask for confirmation |
+| User answers "I'm not sure" | Present default recommendation with rationale, ask for confirmation |
 | User wants to skip a question | Note that AI will use best judgment, continue to next question |
 | User provides unexpected answer | Acknowledge the input, incorporate into understanding, continue |
 | User asks to skip all questions | Proceed to PLAN creation, note assumptions made |

package/.ai-rules/rules/core.md

@@ -46,6 +46,39 @@ PLAN → (user: ACT) → ACT → PLAN → (user: EVAL) → EVAL → Improved PLA
 
 ---
 
+### Output Language
+
+**Rule:** The `language` setting in `codingbuddy.config.json` controls **communication language only** (conversation, explanations, questions). All generated **artifacts** must always be written in **English**, regardless of the `language` setting.
+
+| Category | Language | Examples |
+|----------|----------|----------|
+| **Communication** | `codingbuddy.config.json` `language` setting | Conversation, explanations, status updates, questions |
+| **Artifacts** | Always English | Code, comments, variable names, documentation, commit messages, PR titles/descriptions, branch names, TODO items, error messages in code, log messages, JSDoc/TSDoc, type names |
+
+**Why:**
+- Code and documentation in English ensures global readability and collaboration
+- Mixed-language codebases create maintenance burden and hinder onboarding
+- Commit history and PR descriptions must be searchable in a common language
+
+**Examples:**
+
+```
+# Communication (follows language setting, e.g., "ko")
+"This function handles user authentication. Let's move on to the next step."
+
+# Artifacts (always English)
+/** Validates user authentication token and returns session data. */
+function validateAuthToken(token: string): SessionData { ... }
+
+# Commit message (always English)
+feat(auth): add token validation with session management
+
+# Code comments (always English)
+// Check token expiration before proceeding
+```
+
+---
+
 ### Plan Mode
 
 **Important:**
@@ -61,6 +94,18 @@ PLAN → (user: ACT) → ACT → PLAN → (user: EVAL) → EVAL → Improved PLA
 **Purpose:**
 Create actionable implementation plans following TDD and augmented coding principles
 
+### API Assumption Verification (PLAN mode)
+
+When a plan references external API fields, schemas, or behaviors:
+1. **Cite source**: Include the official documentation URL for every API assumption
+2. **Mark unverified**: Tag any assumption without a verified source as `[UNVERIFIED]`
+3. **Verify before ACT**: All `[UNVERIFIED]` items must be verified (via WebFetch/WebSearch) before transitioning to ACT mode
+4. **No fabricated schemas**: Never assume API input/output fields exist without documentation proof
+
+Example:
+- ✅ "Hook stdin includes `tool_name` field ([source](https://code.claude.com/docs/en/hooks))"
+- ❌ "Hook stdin includes `session_cost` field" (no source → will cause implementation failure)
+
 ---
 
 ### Structured Reasoning Process (SRP)
@@ -577,6 +622,33 @@ To preserve this implementation session for future reference:
 - In monorepo subdirectories, use git -C "$REPO_ROOT" flag for git commands
 - After using cd, ensure relative paths are not double-applied in subsequent commands
 
+### Working Directory Safety
+
+After any operation that changes directory (cd, clone, worktree operations):
+
+- Verify current working directory is the project root before running project-scoped commands
+- Use absolute paths for critical operations (version control, CI tools, package managers)
+- If working directory drifted, return immediately: `cd /path/to/project`
+- Never assume the working directory is correct after directory-changing operations
+
+### Skill Invocation Safety
+
+Before invoking any skill via a tool:
+
+- Check the skill file frontmatter for `disable-model-invocation: true`
+- Skills with this flag cannot be invoked via tool-based invocation
+- Instead, read the skill content and execute the workflow steps directly
+- This applies to all AI assistants, not just specific tool implementations
+
+### Issue Deduplication
+
+Before creating any issue in the project tracker:
+
+- Search for existing similar issues using relevant keywords (e.g., `gh issue list --search "<keywords>"`)
+- If a duplicate or closely related issue is found, update it instead of creating a new one
+- Track all issues created in the current session to prevent same-session duplicates
+- Include cross-references when creating related but distinct issues
+
 ---
 
 ### Eval Mode
@@ -883,6 +955,7 @@ To preserve this evaluation session for future reference:
 - User initiates with `AUTO` keyword and the system handles the entire workflow
 - Continues iterating until quality targets are achieved or maximum iterations reached
 - Best for tasks where iterative refinement is expected
+- For parallel task execution within AUTO mode, see [parallel-execution.md](parallel-execution.md)
 
 **Trigger:**
 - Type `AUTO` to start autonomous execution

package/.ai-rules/rules/parallel-execution.md

@@ -0,0 +1,217 @@
+# Parallel Execution Guidelines
+
+Rules for running multiple tasks concurrently using sub-agents, workers, or parallel processes. These rules are tool-agnostic and apply to any AI assistant orchestrating parallel work.
+
+---
+
+## The Iron Rule
+
+```
+ISSUES MODIFYING THE SAME FILES MUST NOT RUN IN THE SAME PARALLEL WAVE
+```
+
+No exceptions. If two tasks touch the same file, they run sequentially in different waves. Violating this rule causes merge conflicts, lost work, and corrupted state.
+
+**Why:** Parallel workers operate on isolated copies (e.g., git worktrees, branches). When two workers modify the same file simultaneously, their changes conflict on merge. One worker's changes will be lost or require manual resolution.
+
+---
+
+## Wave Planning
+
+Parallel tasks are organized into **waves** — groups of tasks that execute concurrently. Tasks within a wave must be independent; tasks across waves may depend on each other.
+
+### Step 1: File Overlap Matrix
+
+Before assigning tasks to waves, build a file overlap matrix. This is **mandatory**, not optional.
+
+**Process:**
+
+1. For each task, list all files that will be created or modified
+2. Compare every pair of tasks for file overlap
+3. Any overlap means those tasks **cannot** be in the same wave
+
+**Example Matrix:**
+
+```
+         Task A    Task B    Task C    Task D
+Task A     -       overlap     -         -
+Task B   overlap     -         -       overlap
+Task C     -         -         -         -
+Task D     -       overlap     -         -
+```
+
+**Result:** A and B cannot be in the same wave. B and D cannot be in the same wave. C is independent and can go in any wave.
+
+### Step 2: Dependency Analysis
+
+Beyond file overlap, check for logical dependencies:
+
+- Does Task B require output from Task A? (sequential dependency)
+- Does Task C need a type/interface that Task A creates? (creation dependency)
+- Does Task D modify a function that Task B also calls? (behavioral dependency)
+
+Tasks with dependencies must run in later waves than their prerequisites.
+
+### Step 3: Wave Assignment
+
+Use a greedy coloring algorithm:
+
+```
+1. Sort tasks by number of conflicts (most conflicts first)
+2. For each task:
+   a. Find the earliest wave where no conflict exists
+   b. Assign the task to that wave
+3. Result: minimum number of waves
+```
+
+**Example Result:**
+
+```
+Wave 1: Task A, Task C, Task D  (no mutual conflicts)
+Wave 2: Task B                  (conflicts with A and D)
+```
+
+### Step 4: Wave Ordering
+
+Order waves considering:
+
+- **Foundation first:** Tasks that create shared types, interfaces, or utilities go in Wave 1
+- **Consumers later:** Tasks that depend on Wave 1 outputs go in Wave 2+
+- **Independent tasks:** Can go in any wave; prefer earlier waves to maximize parallelism
+
+---
+
+## Sub-Agent Parallelization Strategy
+
+When dispatching parallel sub-agents (workers), follow these guidelines:
+
+### Worker Isolation
+
+Each worker must operate in an isolated environment:
+
+- **Separate working copy:** Each worker gets its own git worktree, branch, or directory
+- **No shared mutable state:** Workers must not write to the same files, databases, or caches simultaneously
+- **Independent commits:** Each worker commits to its own branch
+
+### Worker Prompt Design
+
+Each worker prompt must include:
+
+1. **Clear scope:** Exactly which files to create or modify
+2. **Boundary constraints:** Files the worker must NOT touch
+3. **Context:** Shared types, interfaces, or utilities the worker may read but not modify
+4. **Success criteria:** How to verify the task is complete
+5. **Verification command:** A command to run before completing (e.g., tests, lint)
+
+### Merge Strategy
+
+After all workers in a wave complete:
+
+1. **Verify each worker's changes:** Run tests and lint on each branch independently
+2. **Merge sequentially:** Merge each worker's branch into the target branch one at a time
+3. **Run integration tests:** After all merges, verify the combined changes work together
+4. **Resolve conflicts immediately:** If a merge conflict occurs, investigate the root cause — it likely indicates a violation of the Iron Rule
+
+---
+
+## Continuous Execution Rule
+
+Workers MUST complete all assigned tasks in a single uninterrupted flow.
+Stopping between tasks to wait for user input is a protocol violation.
+
+- DO NOT stop between steps
+- Complete ALL tasks without waiting for user input
+- Only stop after writing RESULT.json
+- Auto-nudge from conductor is a fallback safety net, not the primary mechanism
+
+---
+
+## AUTO Mode Iteration Methodology
+
+When using AUTO mode with parallel execution:
+
+### Iteration Structure
+
+```
+Iteration 1:
+  PLAN  → Identify tasks, build file overlap matrix, assign waves
+  ACT   → Execute Wave 1 (parallel workers)
+        → Merge Wave 1 results
+        → Execute Wave 2 (parallel workers)
+        → Merge Wave 2 results
+        → ... repeat for all waves
+  EVAL  → Verify all tasks complete, run full test suite
+        → If Critical/High issues found → iterate
+
+Iteration 2 (if needed):
+  PLAN  → Address issues found in previous EVAL
+  ACT   → Fix issues (may or may not need parallel execution)
+  EVAL  → Re-verify
+```
+
+### Quality Gates Between Waves
+
+Before starting the next wave:
+
+- All workers in the current wave must have completed successfully
+- All changes from the current wave must be merged
+- Tests must pass after merging
+- No unresolved conflicts
+
+### Escape Conditions
+
+Stop iterating when:
+
+- All acceptance criteria are met
+- EVAL reports Critical = 0 AND High = 0
+- Maximum iterations reached (default: 3)
+
+---
+
+## Post-Execution Verification Checklist
+
+After all waves complete, verify:
+
+```
+- [ ] All tasks completed successfully
+- [ ] All branches merged without conflicts
+- [ ] Full test suite passes
+- [ ] No files were modified by multiple workers (Iron Rule verification)
+- [ ] Lint and format checks pass
+- [ ] Type checking passes
+- [ ] No unintended changes outside task scope
+```
+
+### Iron Rule Verification Command
+
+Run this after merging to confirm no file was modified by multiple workers:
+
+```bash
+# For git-based workflows: check if any file appears in multiple worker branches
+# Compare each worker's changed files against all other workers
+git diff --name-only main..worker-1 > /tmp/w1.txt
+git diff --name-only main..worker-2 > /tmp/w2.txt
+comm -12 <(sort /tmp/w1.txt) <(sort /tmp/w2.txt)
+# Output must be empty — any listed files indicate an Iron Rule violation
+```
+
+---
+
+## Common Pitfalls
+
+| Pitfall | Prevention |
+|---------|------------|
+| Skipping file overlap matrix | **Always** build the matrix before assigning waves |
+| "It probably won't conflict" | Assume it will. Check explicitly. No exceptions |
+| Shared config files (package.json, tsconfig) | Only one worker per wave may modify shared config |
+| Generated files (lock files, build output) | Exclude from worker scope; regenerate after merge |
+| Test files that import from multiple modules | Treat test files as modifying the modules they test |
+| Workers exceeding their scope | Define explicit file boundaries in worker prompts |
+
+---
+
+## Reference
+
+- For detailed wave analysis algorithms, see the skill-specific documentation in your tool's configuration
+- For AUTO mode general workflow, see [core.md](core.md) — Auto Mode section
+- For TDD practices during parallel execution, see [augmented-coding.md](augmented-coding.md)

package/.ai-rules/schemas/agent.schema.json

@@ -291,6 +291,44 @@
         }
       ],
       "description": "General checklist (can be object or array)"
+    },
+    "visual": {
+      "type": "object",
+      "description": "Visual identity for the agent character system",
+      "required": ["eye", "eyeFallback", "colorAnsi", "group"],
+      "properties": {
+        "eye": {
+          "type": "string",
+          "description": "Unicode symbol representing the agent's eye/icon",
+          "minLength": 1
+        },
+        "eyeFallback": {
+          "type": "string",
+          "description": "ASCII fallback character for terminals without Unicode support",
+          "minLength": 1,
+          "maxLength": 1
+        },
+        "colorAnsi": {
+          "type": "string",
+          "enum": ["black", "red", "green", "yellow", "blue", "magenta", "cyan", "white", "bright"],
+          "description": "ANSI color name for terminal rendering"
+        },
+        "group": {
+          "type": "string",
+          "enum": [
+            "workflow",
+            "architecture",
+            "quality",
+            "security",
+            "frontend",
+            "backend",
+            "integration",
+            "specialist"
+          ],
+          "description": "Domain group for visual categorization"
+        }
+      },
+      "additionalProperties": false
     }
   },
   "additionalProperties": true

package/.ai-rules/skills/README.md

@@ -30,6 +30,7 @@ Reusable workflows for consistent development practices.
 
 | Skill | Description | When to Use |
 |-------|-------------|-------------|
+| agent-discussion | Terminal formatter for multi-agent debate output with severity badges and consensus indicators | Rendering parallel agent findings, code review debates, EVAL summaries |
 | context-management | Preserve critical decisions across sessions and context compaction | Long tasks, multi-session work, PLAN→ACT→EVAL transitions |
 | deployment-checklist | Pre-deploy validation, health checks, rollback planning | Before every staging/production deployment |
 | dispatching-parallel-agents | Handle 2+ independent tasks without shared state | Parallel task execution |
@@ -39,6 +40,8 @@ Reusable workflows for consistent development practices.
 | legacy-modernization | Strangler fig pattern for incremental migration of legacy code | Modernizing old patterns, major version upgrades |
 | subagent-driven-development | Execute plans with independent tasks in current session | In-session plan execution |
 | systematic-debugging | Systematic approach before proposing fixes | Encountering bugs or failures |
+| cross-repo-issues | Detect, confirm, and create issues in upstream/related repositories with safety checks | Bug belongs upstream, dependency issue, fork-to-upstream reporting |
+| retrospective | Analyze session archives for coding patterns, agent usage, and improvement suggestions | Sprint reviews, periodic retrospectives, process improvement |
 | writing-plans | Create implementation plans before coding | Multi-step tasks with specs |
 
 ### Documentation & Communication
@@ -47,9 +50,17 @@ Reusable workflows for consistent development practices.
 |-------|-------------|-------------|
 | documentation-generation | Generate README, API docs, CHANGELOG, and ADRs from code | Creating or updating project documentation |
 | pr-all-in-one | Unified commit and PR workflow with smart issue linking | `/pr-all-in-one [target] [issue]` |
+| ship | Run local CI checks and ship changes — branch, commit, push, and PR | Changes are ready to ship |
 | pr-review | Systematic, evidence-based PR review with anti-sycophancy principles | Conducting manual PR reviews |
 | prompt-engineering | Write and optimize prompts for AI tools and agent system prompts | AI tool instructions, MCP tool descriptions, agent prompts |
 
+### DevOps & Infrastructure
+
+| Skill | Description | When to Use |
+|-------|-------------|-------------|
+| cost-budget | Cost budget management with threshold alerts and auto-pause for autonomous workflows | Managing AI session costs, budget limits, taskMaestro wave budgets |
+| tmux-master | Background knowledge for tmux session/window/pane lifecycle, layout, communication, styling, and troubleshooting | Parallel agent execution, taskMaestro workflows, tmux automation |
+
 ### codingbuddy Specific
 
 | Skill | Description | When to Use |
@@ -57,6 +68,7 @@ Reusable workflows for consistent development practices.
 | agent-design | Design new specialist agent JSON definitions with schema, expertise, and system prompts | Adding new agents to codingbuddy |
 | mcp-builder | NestJS-based MCP server development with Tools/Resources/Prompts design | Building or extending MCP servers |
 | rule-authoring | Write unambiguous AI coding rules compatible across multiple AI tools | Creating rules for .ai-rules/ directories |
+| skill-creator | Create, eval, improve, and benchmark skills with measurable behavior-change tests | Creating new skills, testing skill effectiveness, optimizing underperforming skills |
 
 ## Skill Format
 
@@ -176,6 +188,10 @@ EOF
 │   └── SKILL.md
 │
 ├── [Workflow & Process]
+├── agent-discussion/
+│   └── SKILL.md
+├── cross-repo-issues/
+│   └── SKILL.md
 ├── context-management/
 │   └── SKILL.md
 ├── deployment-checklist/
@@ -196,6 +212,8 @@ EOF
 │   └── SKILL.md
 ├── subagent-driven-development/
 │   └── SKILL.md
+├── retrospective/
+│   └── SKILL.md
 ├── systematic-debugging/
 │   └── SKILL.md
 ├── writing-plans/
@@ -213,12 +231,22 @@ EOF
 │   └── SKILL.md
 ├── prompt-engineering/
 │   └── SKILL.md
+├── ship/
+│   └── SKILL.md
+│
+├── [DevOps & Infrastructure]
+├── cost-budget/
+│   └── SKILL.md
+├── tmux-master/
+│   └── SKILL.md
 │
 └── [codingbuddy Specific]
     ├── agent-design/
     │   └── SKILL.md
     ├── mcp-builder/
     │   └── SKILL.md
-    └── rule-authoring/
+    ├── rule-authoring/
+    │   └── SKILL.md
+    └── skill-creator/
         └── SKILL.md
 ```

package/.ai-rules/skills/agent-design/SKILL.md

@@ -267,3 +267,8 @@ ALL    → Cross-cutting agents (code-reviewer)
 - [ ] README.md updated with new agent
 - [ ] Added to relevant adapter configurations
 ```
+
+## Additional resources
+
+- [Agent JSON template](examples/agent-template.json) — Copy-and-adapt template with all required/optional fields and a design checklist
+- [Expertise definition guidelines](references/expertise-guidelines.md) — How to write differentiated expertise items, avoid overlaps, and validate quality

package/.ai-rules/skills/agent-design/examples/agent-template.json

@@ -0,0 +1,55 @@
+{
+  "_template_instructions": "Copy this file and replace all <placeholder> values. Remove this _template_instructions field. Save as packages/rules/.ai-rules/agents/<agent-name>.json (kebab-case filename).",
+
+  "name": "<Display Name>",
+  "description": "<One-sentence description of what this agent specializes in — be specific, not broad>",
+
+  "role": {
+    "title": "<Official Role Title>",
+    "type": "specialist",
+    "expertise": [
+      "<Specific Domain Expertise 1 — e.g., 'Zero-Downtime Schema Migrations'>",
+      "<Specific Domain Expertise 2 — e.g., 'Expand-Contract Migration Pattern'>",
+      "<Specific Domain Expertise 3 — e.g., 'Rollback Strategy Design'>",
+      "<Specific Domain Expertise 4 (optional)>",
+      "<Specific Domain Expertise 5 (optional)>"
+    ],
+    "responsibilities": [
+      "<Key responsibility 1 — what this agent actively does>",
+      "<Key responsibility 2 — what this agent actively does>",
+      "<Key responsibility 3 — what this agent actively does>"
+    ]
+  },
+
+  "context_files": [".ai-rules/rules/core.md", ".ai-rules/rules/project.md"],
+
+  "modes": {
+    "planning": {
+      "activation": {
+        "trigger": "<When this agent activates in PLAN mode — e.g., 'When planning database schema migrations'>",
+        "auto_activate_conditions": [
+          "<Condition 1 — e.g., 'Schema change planning'>",
+          "<Condition 2 — e.g., 'Migration strategy design'>"
+        ]
+      }
+    },
+    "evaluation": {
+      "activation": {
+        "trigger": "<When this agent activates in EVAL mode — e.g., 'When evaluating migration safety and rollback readiness'>"
+      }
+    }
+  },
+
+  "_design_checklist": {
+    "_comment": "Remove this section from the final agent file. Use it during design to verify quality.",
+    "checks": [
+      "Domain is specific, not broad (e.g., 'Zero-Downtime Migrations' not 'Databases')",
+      "No significant overlap with existing agents (< 2 shared expertise items)",
+      "System prompt includes what this agent does NOT handle",
+      "3-7 expertise items, all specific and measurable",
+      "Filename follows kebab-case convention",
+      "Modes reflect actual usage patterns (PLAN, ACT, EVAL, or ALL)",
+      "JSON validates with: cat <file>.json | jq ."
+    ]
+  }
+}

package/.ai-rules/skills/agent-design/references/expertise-guidelines.md

@@ -0,0 +1,112 @@
+# Agent Expertise Definition Guidelines
+
+How to define clear, differentiated expertise items for codingbuddy specialist agents.
+
+## The Expertise Quality Spectrum
+
+| Level | Example | Verdict |
+|-------|---------|---------|
+| Too broad | "Databases" | Rejected — could mean anything |
+| Too vague | "Backend development" | Rejected — overlaps with many agents |
+| Right level | "PostgreSQL Query Plan Optimization" | Accepted — specific, testable |
+| Right level | "Zero-Downtime Schema Migrations" | Accepted — clear domain boundary |
+| Too narrow | "PostgreSQL 15.2 BRIN index tuning" | Risky — might be too version-specific |
+
+## Writing Expertise Items
+
+### Formula
+
+```
+[Technique/Pattern] + [Domain/Technology] + [Qualifier (optional)]
+```
+
+**Examples:**
+- "Expand-Contract Migration Pattern" (technique + domain)
+- "React Server Component Performance Profiling" (technique + technology)
+- "OWASP Top 10 Vulnerability Assessment" (standard + domain)
+- "Zero-Downtime Blue-Green Deployments" (qualifier + technique)
+
+### Rules
+
+1. **3-7 items per agent** — fewer than 3 means the agent is too narrow; more than 7 means it's too broad
+2. **Each item is independently meaningful** — someone reading just the expertise list should understand the agent's domain
+3. **No overlapping items within the same agent** — if two items cover similar ground, merge them
+4. **Use established terminology** — reference known patterns, standards, and methodologies
+
+## Differentiation Matrix
+
+Before adding an agent, compare expertise against existing agents:
+
+```
+New Agent Expertise          Existing Agent Expertise       Overlap?
+─────────────────────────    ─────────────────────────      ────────
+API Rate Limiting            API Gateway Patterns           PARTIAL → ok if boundaries clear
+REST API Versioning          GraphQL Schema Evolution       NO → different domains
+Error Response Standards     Error Handling Patterns         YES → merge or split
+```
+
+**Overlap thresholds:**
+- 0-1 shared items: Safe to add
+- 2 shared items: Review carefully, ensure boundaries are clear
+- 3+ shared items: Merge agents or fundamentally redesign scope
+
+## Expertise vs. Responsibilities
+
+| | Expertise | Responsibilities |
+|---|-----------|------------------|
+| **What** | Knowledge domains the agent has | Actions the agent takes |
+| **Format** | Noun phrases (domain areas) | Verb phrases (active duties) |
+| **Count** | 3-7 items | 2-4 items |
+| **Example** | "Container Orchestration Patterns" | "Design Kubernetes deployment manifests" |
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|-------------|---------|-----|
+| "Best practices" | Meaningless without context | Name the specific practice |
+| "General development" | Every agent does this | What SPECIFIC development? |
+| "Code review" | Too broad — review for what? | "Security-focused code review" |
+| "Testing" | Every engineer tests | "Property-based testing strategies" |
+| "Architecture" | Name the architecture concern | "Event-driven architecture design" |
+| Tool names alone ("Docker") | Knowing a tool isn't expertise | "Container image optimization" |
+
+## Expertise Validation Checklist
+
+For each expertise item, verify:
+
+```
+- [ ] Could I write a 30-minute talk about JUST this item?
+- [ ] Is this clearly different from the other items in this agent?
+- [ ] Would another agent's expertise NOT cover this?
+- [ ] Can I name 3 concrete tasks that require this specific expertise?
+- [ ] Is this stable enough to last 6+ months without rewording?
+```
+
+## Tier-Specific Guidance
+
+### Primary Agents (type: "primary")
+
+Used as the main agent in a workflow mode. Expertise should be broad enough to lead a mode but focused on a methodology:
+
+```json
+"expertise": [
+  "Solution Architecture Design",
+  "Technology Selection and Trade-off Analysis",
+  "System Integration Planning",
+  "Scalability and Performance Architecture"
+]
+```
+
+### Specialist Agents (type: "specialist")
+
+Called in parallel for domain reviews. Expertise should be deep and narrow:
+
+```json
+"expertise": [
+  "OWASP Top 10 Vulnerability Assessment",
+  "Authentication and Authorization Patterns",
+  "Secrets Management and Rotation",
+  "Security Header Configuration",
+  "Dependency Vulnerability Scanning"
+]
+```