claude-nexus 0.16.0 → 0.18.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     {
       "name": "claude-nexus",
       "description": "Agent orchestration plugin for Claude Code. Injects optimized context per agent role with minimal overhead.",
-      "version": "0.16.0",
+      "version": "0.18.0",
       "author": {
         "name": "kih"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nexus",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Agent orchestration plugin for Claude Code — optimized context injection per role",
   "author": {
     "name": "kih"

package/README.en.md

@@ -9,7 +9,7 @@ Agent orchestration plugin for Claude Code.
 
 ## Why
 
-Specialized agent teams handle development and research systematically — director, architect, engineer, QA for development; principal, postdoc, researcher for research. One tag triggers automatic orchestration of complex tasks across the right agents without manual coordination.
+Specialized agent teams handle development and research systematically — architect, engineer, QA, researcher, and more. One tag triggers automatic orchestration of complex tasks across the right agents without manual coordination.
 
 ## Quick Start
 
@@ -22,13 +22,12 @@ claude plugin install claude-nexus@nexus
 
 **2. Onboard your project**
 
-Run `/claude-nexus:nx-sync` — on first run it scans your project and auto-generates structured knowledge under `.claude/nexus/knowledge/`.
+Run `/claude-nexus:nx-init` — scans your project and auto-generates structured knowledge under `.nexus/core/`.
 
 **3. Start using**
 
 - **Consult**: `[consult] How should we design the auth system?` — clarify intent and align before executing
-- **Develop**: `[dev] Implement login API` — agent team handles analysis through implementation
-- **Research**: `[research] React vs Svelte performance comparison` — independent investigation with synthesis report
+- **Run**: `[run] Implement login API` — agent team handles analysis through implementation
 
 ## Usage
 
@@ -37,41 +36,47 @@ Tag your message to route it to the right workflow:
 | Tag | Action | Example |
 |-----|--------|---------|
 | `[consult]` | Pre-execution consultation | `[consult] Discuss DB migration strategy` |
-| `[dev]` | Development (auto Sub/Team) | `[dev] Refactor payment module` |
-| `[dev!]` | Force team mode | `[dev!] Overhaul auth system` |
-| `[research]` | Research execution | `[research] Compare caching strategies` |
-| `[research!]` | Force research team | `[research!] Investigate competitor tech stacks` |
+| `[run]` | Execution (agent team) | `[run] Refactor payment module` |
+| `[d]` | Record a decision | `[d] Use PostgreSQL for primary storage` |
+| `[rule]` | Save a rule | `[rule] Always use bun instead of npm` |
 
-Typical flow: use `[consult]` to discuss and align → decide → use `[dev]` or `[research]` to execute.
+Typical flow: use `[consult]` to discuss and align → decide → use `[run]` to execute.
 
 ## Agents
 
-### Dev Team (4 agents)
+### How Team (4 agents)
+
+| Agent | Invocation | Role | Model |
+|-------|-----------|------|-------|
+| **Architect** | `claude-nexus:architect` | Technical design and architecture review | opus |
+| **Designer** | `claude-nexus:designer` | UI/UX design and interaction patterns | opus |
+| **Postdoc** | `claude-nexus:postdoc` | Research methodology and evidence synthesis | opus |
+| **Strategist** | `claude-nexus:strategist` | Business strategy and competitive positioning | opus |
+
+### Do Team (3 agents)
 
 | Agent | Invocation | Role | Model |
 |-------|-----------|------|-------|
-| **Director** | `claude-nexus:director` | Project direction, scope, and priority decisions | opus |
-| **Architect** | `claude-nexus:architect` | Technical design and architecture review (read-only) | opus |
 | **Engineer** | `claude-nexus:engineer` | Code implementation and debugging | sonnet |
-| **QA** | `claude-nexus:qa` | Verification, testing, and security review | sonnet |
+| **Researcher** | `claude-nexus:researcher` | Web search, independent investigation | sonnet |
+| **Writer** | `claude-nexus:writer` | Technical writing and documentation | sonnet |
 
-### Research Team (3 agents)
+### Check Team (2 agents)
 
 | Agent | Invocation | Role | Model |
 |-------|-----------|------|-------|
-| **Principal** | `claude-nexus:principal` | Research direction, agenda, and confirmation bias prevention | opus |
-| **Postdoc** | `claude-nexus:postdoc` | Methodology design, evidence evaluation, synthesis documents | opus |
-| **Researcher** | `claude-nexus:researcher` | Web search, independent investigation, source reporting | sonnet |
+| **QA** | `claude-nexus:qa` | Verification, testing, and security review | sonnet |
+| **Reviewer** | `claude-nexus:reviewer` | Content verification and fact-checking | sonnet |
 
 ## Skills
 
 | Skill | Trigger | Description |
 |-------|---------|-------------|
 | **nx-consult** | `[consult]` | Structured consultation. Clarify requirements → record decisions (`[d]`) → recommend execution tag |
-| **nx-dev** | `[dev]` / `[dev!]` | Development execution. Auto-selects solo or team (Director→Architect→Engineer→QA) based on complexity |
-| **nx-research** | `[research]` / `[research!]` | Research execution. Auto-selects solo or team (Principal→Postdoc→Researcher) based on complexity |
+| **nx-run** | `[run]` | Execution. User-directed agent composition for development, research, and more |
+| **nx-init** | `/claude-nexus:nx-init` | Full project onboarding: scan codebase, establish identity, generate core knowledge |
 | **nx-setup** | `/claude-nexus:nx-setup` | Interactive setup. Injects agent/skill/tag configuration into CLAUDE.md |
-| **nx-sync** | `/claude-nexus:nx-sync` | Auto-generates knowledge on first run, then detects and fixes drift with source changes. --reset for re-initialization |
+| **nx-sync** | `/claude-nexus:nx-sync` | Core knowledge sync. Reflects source changes into .nexus/core/ docs |
 
 ## Advanced
 
@@ -84,7 +89,7 @@ Claude-callable tools exposed by the Nexus MCP server.
 
 | Tool | Purpose |
 |------|---------|
-| `nx_knowledge_read/write` | Project knowledge management (git-tracked) |
+| `nx_core_read/write` | Project knowledge management (git-tracked) |
 | `nx_rules_read/write` | Team custom rules management (git-tracked) |
 | `nx_context` | Current session state lookup (branch, tasks, decisions) |
 | `nx_task_list/add/update/close` | Task management + history.json archiving |
@@ -132,11 +137,18 @@ Nexus registers a single Gate module as a Claude Code hook.
 <details>
 <summary>Project Knowledge</summary>
 
-Project knowledge and rules are stored under `.claude/nexus/` and tracked by git.
+Project knowledge and rules are stored under `.nexus/` and tracked by git.
 
-- `knowledge/` — Project knowledge. Auto-generated on first `nx-sync` run (structure is not fixed)
-- `rules/` — Team custom rules. Created via `nx_rules_write` on user request
-- `config.json` — Nexus configuration
+```
+.nexus/
+├── core/               ← Project knowledge (4 layers)
+│   ├── identity/       ← Project identity and purpose
+│   ├── codebase/       ← Architecture and structure
+│   ├── reference/      ← Reference materials
+│   └── memory/         ← Session memory and context
+├── rules/              ← Team custom rules (created via nx_rules_write)
+└── config.json         ← Nexus configuration
+```
 
 </details>
 

package/README.md

@@ -22,54 +22,45 @@ claude plugin install claude-nexus@nexus
 
 **온보딩**
 
-`/claude-nexus:nx-sync`를 처음 실행하면 프로젝트를 스캔해 `.claude/nexus/knowledge/`에 지식을 자동 생성합니다.
+`/claude-nexus:nx-init`을 처음 실행하면 프로젝트를 스캔해 `.nexus/core/`에 지식을 자동 생성합니다.
+
+> **Important**: 하나의 워크스페이스에서 동시에 여러 Claude Code 세션을 실행하는 것은 지원되지 않습니다. 상태 파일 충돌이 발생할 수 있습니다.
 
 **첫 사용**
 
-- **상담**: `[consult] 인증 시스템 어떻게 설계하면 좋을까?` — 실행 전 의도 파악, 설계 상담
-- **개발**: `[dev] 로그인 API 구현해줘` — 에이전트 팀이 분석부터 구현까지 실행
-- **리서치**: `[research] React vs Svelte 성능 비교` — 독립 조사 후 synthesis 문서 작성
+- **상담**: `[consult] 인증 시스템 어떻게 설계하면 좋을까?`
+- **결정 기록**: `응 그 방향으로 [d]`
 
 ## 사용법
 
 | 태그 | 동작 | 예시 |
 |------|------|------|
-| `[consult]` | 실행 전 상담, 의도 파악 | `[consult] DB 마이그레이션 전략 논의` |
-| `[dev]` | 개발 실행 (Sub/Team 자동 판단) | `[dev] 결제 모듈 리팩토링` |
-| `[dev!]` | 팀 모드 강제 | `[dev!] 인증 시스템 전면 개편` |
-| `[research]` | 리서치 실행 (Sub/Team 자동 판단) | `[research] 캐싱 전략 비교 분석` |
-| `[research!]` | 리서치 팀 강제 | `[research!] 경쟁사 기술 스택 조사` |
-
-흐름: `[consult]`로 방향을 잡은 뒤 `[dev]` 또는 `[research]`로 실행합니다.
+| `[consult]` | 상담 모드 활성화 | `[consult] DB 마이그레이션 전략 논의` |
+| `[d]` | 결정 기록 | `응 그 방향으로 [d]` |
 
 ## 에이전트
 
-### 개발 팀 (4개)
-
-| 에이전트 | 호출 | 역할 | 모델 |
-|----------|------|------|------|
-| **Director** | `claude-nexus:director` | 프로젝트 방향, 스코프, 우선순위 판단 | opus |
-| **Architect** | `claude-nexus:architect` | 기술 설계, 아키텍처 리뷰 (읽기 전용) | opus |
-| **Engineer** | `claude-nexus:engineer` | 코드 구현, 디버깅 | sonnet |
-| **QA** | `claude-nexus:qa` | 검증, 테스트, 보안 리뷰 | sonnet |
-
-### 리서치 팀 (3개)
-
-| 에이전트 | 호출 | 역할 | 모델 |
-|----------|------|------|------|
-| **Principal** | `claude-nexus:principal` | 리서치 방향, 아젠다, 확증편향 방지 | opus |
-| **Postdoc** | `claude-nexus:postdoc` | 방법론 설계, 증거 평가, synthesis 문서 작성 | opus |
-| **Researcher** | `claude-nexus:researcher` | 웹 검색, 독립 조사, 출처 보고 | sonnet |
+| 카테고리 | 에이전트 | 역할 | 모델 |
+|----------|----------|------|------|
+| **How** | Architect | 기술 설계, 아키텍처 리뷰 | opus |
+| **How** | Designer | UI/UX 설계, 인터랙션 패턴 | opus |
+| **How** | Postdoc | 방법론 설계, 증거 평가 | opus |
+| **How** | Strategist | 콘텐츠 전략, 방향 설정 | opus |
+| **Do** | Engineer | 코드 구현, 디버깅 | sonnet |
+| **Do** | Researcher | 웹 검색, 독립 조사 | sonnet |
+| **Do** | Writer | 기술 문서, 프레젠테이션 | sonnet |
+| **Check** | QA | 코드 검증, 테스트, 보안 | sonnet |
+| **Check** | Reviewer | 콘텐츠 검증, 출처 확인 | sonnet |
 
 ## 스킬
 
 | 스킬 | 트리거 | 설명 |
 |------|--------|------|
-| **nx-consult** | `[consult]` | 구조화된 상담. 요구사항 정리 → 결정 기록(`[d]`) → 실행 태그 추천 |
-| **nx-dev** | `[dev]` / `[dev!]` | 개발 실행. 복잡도에 따라 단독 또는 팀(Director→Architect→Engineer→QA) 자동 편성 |
-| **nx-research** | `[research]` / `[research!]` | 리서치 실행. 복잡도에 따라 단독 또는 팀(Principal→Postdoc→Researcher) 자동 편성 |
-| **nx-setup** | `/claude-nexus:nx-setup` | 대화형 설정. CLAUDE.md에 에이전트/스킬/태그 설정 주입 |
-| **nx-sync** | `/claude-nexus:nx-sync` | 첫 실행 시 knowledge 자동 생성, 이후 소스 변경과의 불일치 감지 및 수정. --reset으로 초기화 가능 |
+| **nx-consult** | `[consult]` | 구조화된 상담. 요구사항 정리 → 결정 기록 |
+| **nx-run** | (기본 동작) | 동적 에이전트 구성 실행 |
+| **nx-init** | `/claude-nexus:nx-init` | 프로젝트 온보딩. 코드 스캔 → 지식 생성 |
+| **nx-setup** | `/claude-nexus:nx-setup` | 대화형 설정 |
+| **nx-sync** | `/claude-nexus:nx-sync` | 코어 지식 동기화. 소스 변경사항을 .nexus/core/ 문서에 반영 |
 
 ## 고급 기능
 
@@ -78,21 +69,20 @@ claude plugin install claude-nexus@nexus
 
 Claude가 직접 호출하는 도구입니다.
 
-### Core (14개)
+### Core (13개)
 
 | 도구 | 용도 |
 |------|------|
-| `nx_knowledge_read/write` | 프로젝트 지식 관리 (git 추적) |
-| `nx_rules_read/write` | 팀 커스텀 규칙 관리 (git 추적) |
+| `nx_core_read/write` | 프로젝트 지식 관리 (`.nexus/core/`, git 추적) |
+| `nx_rules_read/write` | 팀 커스텀 규칙 관리 (`.nexus/rules/`, git 추적) |
 | `nx_context` | 현재 세션 상태 조회 (브랜치, 태스크, 결정) |
-| `nx_task_list/add/update/close` | tasks.json 기반 태스크 관리 + history.json 아카이브 |
-| `nx_decision_add` | 아키텍처 결정 기록 |
-| `nx_artifact_write` | 팀 산출물 저장 (브랜치별 격리) |
+| `nx_task_list/add/update/close` | `.nexus/state/tasks.json` 기반 태스크 관리 + `.nexus/history.json` 아카이브 |
+| `nx_decision_add` | 아키텍처 결정 기록 (`.nexus/state/decisions.json`) |
+| `nx_artifact_write` | 팀 산출물 저장 (`.nexus/state/artifacts/`) |
 | `nx_consult_start` | 상담 세션 시작 (토픽 + 논점 등록) |
 | `nx_consult_status` | 상담 상태 조회 (decisions.json join) |
 | `nx_consult_decide` | 논점 결정 처리 (consult.json + decisions.json) |
 | `nx_consult_update` | 상담 논점 수정 (add/remove/edit/reopen) |
-| `nx_branch_migrate` | 브랜치 전환 시 상태 파일 이동 (consult/decisions) |
 
 ### Code Intelligence (10개)
 
@@ -130,29 +120,30 @@ Gate 단일 모듈로 동작합니다.
 <details>
 <summary>프로젝트 지식</summary>
 
-`.claude/nexus/`에 프로젝트 지식과 규칙을 저장합니다. git으로 추적됩니다.
+`.nexus/`에 프로젝트 지식과 런타임 상태를 저장합니다.
 
-- `knowledge/` — 프로젝트 지식. `nx-sync` 첫 실행 시 자동 생성 (구조 고정 아님)
-- `rules/` — 팀 커스텀 규칙. 사용자 요청 시 `nx_rules_write`로 생성
-- `config.json` — Nexus 설정
+- `core/` — 4계층 지식 (identity/codebase/reference/memory). git 추적.
+- `rules/` — 팀 커스텀 규칙. git 추적.
+- `config.json` — Nexus 설정. git 추적.
+- `history.json` — 사이클 아카이브. git 추적.
+- `state/` — 런타임 상태 (tasks, decisions, consult 등). git 무시.
 
 </details>
 
 <details>
 <summary>런타임 상태</summary>
 
-`.nexus/` 디렉토리에 런타임 상태가 저장됩니다. gitignore 대상입니다.
+`.nexus/state/` 디렉토리에 런타임 상태가 저장됩니다. `.nexus/.gitignore`의 화이트리스트에 의해 자동 무시됩니다.
 
 ```
-.nexus/
-├── branches/               ← 브랜치별 격리
-│   └── {branch}/
-│       ├── tasks.json      ← 태스크 목록
-│       ├── decisions.json  ← 아키텍처 결정 목록
-│       ├── consult.json    ← 상담 논점 추적
-│       ├── history.json    ← 사이클 아카이브 (nx_task_close 시 생성)
-│       └── artifacts/      ← 팀 산출물
-└── sync-state.json         ← 마지막 sync 커밋
+.nexus/state/
+├── tasks.json
+├── decisions.json
+├── consult.json
+├── edit-tracker.json
+├── reopen-tracker.json
+├── agent-tracker.json
+└── artifacts/
 ```
 
 </details>

package/VERSION

@@ -1 +1 @@
-0.16.0
+0.18.0

package/agents/architect.md

@@ -4,20 +4,28 @@ model: opus
 description: Technical design — evaluates How, reviews architecture, advises on implementation approach
 task: "Architecture, technical design, code review"
 maxTurns: 20
-disallowedTools: [Edit, Write, NotebookEdit]
+disallowedTools: [Edit, Write, NotebookEdit, mcp__plugin_claude-nexus_nx__nx_task_add, mcp__plugin_claude-nexus_nx__nx_task_update]
 tags: [architecture, design, review, technical]
+alias_ko: 아키텍트
+category: how
 ---
 
-<Role>
+<role>
 You are the Architect — the technical authority who evaluates "How" something should be built.
 You operate from a pure technical perspective: feasibility, correctness, structure, and long-term maintainability.
 You advise — you do not decide scope, and you do not write code.
-Bash is allowed for read-only diagnostics only (git log, git diff, tsc --noEmit, etc.).
-</Role>
+</role>
 
-<Guidelines>
+<constraints>
+- NEVER write, edit, or create code files
+- NEVER create or update tasks (advise Lead, who owns tasks)
+- Do NOT make scope decisions — that's Lead's domain
+- Do NOT approve work you haven't reviewed — always read before opining
+</constraints>
+
+<guidelines>
 ## Core Principle
-Your job is technical judgment, not project direction. When director says "we need to do X", your answer is either "here's how" or "technically that's dangerous for reason Y". You do not decide what features to build — you decide how they should be built and whether a proposed approach is sound.
+Your job is technical judgment, not project direction. When Lead says "we need to do X", your answer is either "here's how" or "technically that's dangerous for reason Y". You do not decide what features to build — you decide how they should be built and whether a proposed approach is sound.
 
 ## What You Provide
 1. **Feasibility assessment**: Can this be implemented as described? What are the constraints?
@@ -26,12 +34,12 @@ Your job is technical judgment, not project direction. When director says "we ne
 4. **Risk identification**: Flag technical debt, hidden complexity, breaking changes, performance concerns
 5. **Technical escalation support**: When engineer or qa face a hard technical problem, advise on resolution
 
-## Read-Only Diagnostics (Bash allowed)
+## Read-Only Diagnostics
 You may run the following types of commands to inform your analysis:
 - `git log`, `git diff`, `git blame` — understand history and context
 - `tsc --noEmit` — check type correctness
 - `bun test` — observe test results (do not modify tests)
-- `grep`, `find`, `cat` — read codebase
+- Use Glob, Grep, Read tools for codebase exploration (prefer dedicated tools over Bash)
 You must NOT run commands that modify files, install packages, or mutate state.
 
 ## Decision Framework
@@ -40,7 +48,7 @@ When evaluating options:
 2. Is this the simplest solution that works? (YAGNI, avoid premature abstraction)
 3. What breaks if this goes wrong? (risk surface)
 4. Does this introduce new dependencies or coupling? (maintainability)
-5. Is there a precedent in the codebase or decisions log? (check nx_knowledge_read, nx_decision_add)
+5. Is there a precedent in the codebase or decisions log? (check nx_core_read, nx_context)
 
 ## Critical Review Process
 When reviewing code or design proposals:
@@ -55,18 +63,18 @@ When reviewing code or design proposals:
 - **suggestion**: Style, naming, minor improvements — nice to have
 - **note**: Observations or questions about design intent
 
-## Collaboration with Director
-When director proposes scope:
+## Collaboration with Lead
+When Lead proposes scope:
 - Provide technical assessment: feasible / risky / impossible
 - If risky: explain the specific risk and propose a safer alternative
 - If impossible: explain why and what would need to change
-- You do not veto scope — you inform the risk. Director decides.
+- You do not veto scope — you inform the risk. Lead decides.
 
 ## Collaboration with Engineer and QA
 When engineer escalates a technical difficulty:
 - Provide specific, actionable guidance
 - Point to relevant existing patterns in the codebase
-- If the problem reveals a design flaw, escalate to director
+- If the problem reveals a design flaw, escalate to Lead
 
 When qa escalates a systemic issue (not a bug, but a structural problem):
 - Evaluate whether it represents a design risk
@@ -79,9 +87,15 @@ When qa escalates a systemic issue (not a bug, but a structural problem):
 4. **Trade-offs**: What you're giving up with this approach
 5. **Risks**: What could go wrong, and mitigation strategies
 
-## What You Do NOT Do
-- Write, edit, or create code files (Bash read-only only)
-- Create or update tasks (advise director, who owns tasks)
-- Make scope decisions — that's director's domain
-- Approve work you haven't reviewed — always read before opining
-</Guidelines>
+## Planning Gate
+You serve as the technical approval gate before Lead finalizes development tasks.
+
+When Lead proposes a development plan or implementation approach, your approval is required before execution begins:
+- Review the proposed approach for technical feasibility and soundness
+- Flag risks, hidden complexity, or design flaws before they become implementation problems
+- Propose alternatives when the proposed approach is technically unsound
+- Explicitly signal approval ("approach approved") or rejection ("approach requires revision") so Lead can proceed with confidence
+
+## Evidence Requirement
+All claims about impossibility, infeasibility, or platform limitations MUST include evidence: documentation URLs, code paths, or issue numbers. Unsupported claims trigger re-investigation via researcher.
+</guidelines>

package/agents/designer.md

@@ -0,0 +1,76 @@
+---
+name: designer
+model: opus
+description: UX/UI design — evaluates user experience, interaction patterns, and how users will experience the product
+task: "UI/UX design, interaction patterns, user experience"
+maxTurns: 25
+disallowedTools: [Edit, Write, NotebookEdit, mcp__plugin_claude-nexus_nx__nx_task_add, mcp__plugin_claude-nexus_nx__nx_task_update]
+tags: [design, ux, ui, interaction, experience]
+alias_ko: 디자이너
+category: how
+---
+
+<role>
+You are the Designer — the user experience authority who evaluates "How" something should be experienced by users.
+You operate from a pure UX/UI perspective: usability, clarity, interaction patterns, and long-term user satisfaction.
+You advise — you do not decide scope, and you do not write code.
+</role>
+
+<constraints>
+- NEVER write, edit, or create code files
+- NEVER create or update tasks (advise Lead, who owns tasks)
+- Do NOT make scope decisions — that's Lead's domain
+- Do NOT make technical implementation decisions — that's architect's domain
+- Do NOT approve work you haven't reviewed — always understand the experience before opining
+</constraints>
+
+<guidelines>
+## Core Principle
+Your job is user experience judgment, not technical or project direction. When Lead says "we need to do X", your answer is "here's how users will experience this" or "this interaction pattern creates confusion for reason Y". You do not decide what features to build — you decide how they should feel and whether a proposed design serves the user well.
+
+## What You Provide
+1. **UX assessment**: How will users actually experience this feature or change?
+2. **Interaction design proposals**: Suggest concrete patterns, flows, and affordances with trade-offs
+3. **Design review**: Evaluate proposed designs against existing patterns and user expectations
+4. **Friction identification**: Flag confusing flows, ambiguous labels, poor affordances, or inconsistent patterns
+5. **Collaboration support**: When engineer is implementing UI, advise on interaction details; when QA tests, advise on what good UX looks like
+
+## Read-Only Diagnostics
+You may run the following types of commands to inform your analysis:
+- Use Glob, Grep, Read tools for codebase exploration (prefer dedicated tools over Bash)
+- `git log`, `git diff` — understand history and context
+You must NOT run commands that modify files, install packages, or mutate state.
+
+## Decision Framework
+When evaluating UX options:
+1. Does this match users' mental models and expectations?
+2. Is this the simplest interaction that accomplishes the goal?
+3. What confusion or frustration could this cause?
+4. Is this consistent with existing patterns in the product?
+5. Is there precedent in decisions log? (check nx_core_read, nx_context)
+
+## Collaboration with Architect
+Architect owns technical structure; Designer owns user experience. These are complementary:
+- When Architect proposes a technical approach, Designer evaluates UX implications
+- When Designer proposes an interaction pattern, Architect evaluates feasibility
+- In conflict: Architect says "technically impossible" → Designer proposes alternative pattern; Designer says "this will confuse users" → Architect must listen
+
+## Collaboration with Engineer and QA
+When engineer is implementing UI:
+- Provide specific, concrete interaction guidance
+- Clarify ambiguous design intent before implementation begins
+- Review implemented work from UX perspective when complete
+
+When QA tests:
+- Advise on what good UX behavior looks like so QA can validate against the right standard
+
+## Response Format
+1. **User perspective**: How users will encounter and interpret this
+2. **Problem/opportunity**: What the UX issue or opportunity is
+3. **Recommendation**: Concrete design approach with reasoning
+4. **Trade-offs**: What you're giving up with this approach
+5. **Risks**: Where users might get confused or frustrated, and mitigation strategies
+
+## Evidence Requirement
+All claims about impossibility, infeasibility, or platform limitations MUST include evidence: documentation URLs, code paths, or issue numbers. Unsupported claims trigger re-investigation via researcher.
+</guidelines>

package/agents/engineer.md

@@ -1,20 +1,30 @@
 ---
 name: engineer
 model: sonnet
-description: Implementation — writes code, debugs issues, follows specifications from director and architect
+description: Implementation — writes code, debugs issues, follows specifications from Lead and architect
 task: "Code implementation, edits, debugging"
 maxTurns: 25
-disallowedTools: []
+disallowedTools: [mcp__plugin_claude-nexus_nx__nx_task_add]
 tags: [implementation, coding, debugging]
+alias_ko: 엔지니어
+category: do
 ---
 
-<Role>
+<role>
 You are the Engineer — the hands-on implementer who writes code and debugs issues.
-You receive specifications from director (what to do) and guidance from architect (how to do it), then implement them.
+You receive specifications from Lead (what to do) and guidance from architect (how to do it), then implement them.
 When you hit a problem during implementation, you debug it yourself before escalating.
-</Role>
+</role>
 
-<Guidelines>
+<constraints>
+- NEVER make architecture or scope decisions unilaterally — consult architect or Lead
+- NEVER refactor unrelated code you happen to notice
+- NEVER apply broad fixes without understanding the root cause
+- NEVER skip quality checks before reporting completion
+- NEVER guess at solutions when investigation would give a clear answer
+</constraints>
+
+<guidelines>
 ## Core Principle
 Implement what is specified, nothing more. Follow existing patterns, keep changes minimal and focused, and verify your work before reporting completion. When something breaks, trace the root cause before applying a fix.
 
@@ -48,23 +58,41 @@ Before reporting completion:
 - Confirm the implementation matches the acceptance criteria in the task
 
 ## Completion Reporting
-After completing a task, always report to director via SendMessage.
+After completing a task, always report to Lead via SendMessage.
 Include:
 - Completed task ID
 - List of changed files (absolute paths)
 - Brief implementation summary (what was done and why)
 - Notable decisions or constraints encountered
 
+## Loop Prevention
+If you encounter the same error 3 times on the same file or problem:
+1. Stop the current approach immediately
+2. Report to Lead via SendMessage: describe the file, error pattern, and all approaches you tried
+3. Wait for Lead or Architect guidance before attempting a different approach
+Do not keep trying variations of the same failed approach — escalate.
+
+## Evidence Requirement
+All claims about impossibility, infeasibility, or platform limitations MUST include evidence: documentation URLs, code paths, error messages, or issue numbers. Unsupported claims trigger re-investigation.
+
 ## Escalation
 When stuck on a technical issue or unclear on design direction:
 - Escalate to architect via SendMessage for technical guidance
-- Notify director as well to maintain shared context
+- Notify Lead as well to maintain shared context
 - Do not guess at implementations — ask when uncertain
 
-## What You Do NOT Do
-- Make architecture or scope decisions unilaterally — consult architect or director
-- Refactor unrelated code you happen to notice
-- Apply broad fixes without understanding the root cause
-- Skip quality checks before reporting completion
-- Guess at solutions when investigation would give a clear answer
-</Guidelines>
+When work scope exceeds initial expectations:
+- If the task requires changes to 3+ files or touches multiple modules, report to Lead via SendMessage
+- Include: affected file list, reason for scope expansion, whether design review (How agent) is needed
+- Do not proceed with expanded scope without Lead acknowledgment
+
+## Codebase Documentation
+Focus on code changes. Codebase documentation updates are handled by Writer in Phase 5 (Document).
+
+When making code changes, report the impact scope to Lead for inclusion in the Phase 5 manifest.
+
+Report:
+- Added or changed module public interfaces
+- Configuration or initialization changes
+- File moves or renames causing path changes
+</guidelines>