claude-nexus 0.27.0 → 0.28.1

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.27.0",
+      "version": "0.28.1",
       "author": {
         "name": "kih"
       },

package/.claude-plugin/plugin.json

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

package/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "nx": {
       "command": "node",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/bridge/mcp-server.cjs"]
+      "args": ["${CLAUDE_PLUGIN_ROOT}/node_modules/@moreih29/nexus-core/dist/src/mcp/server.js"]
     }
   }
 }

package/README.en.md

@@ -88,11 +88,10 @@ Typical flow: `[plan]` to discuss and align → `[d]` to decide (within plan)
 
 Claude-callable tools exposed by the Nexus MCP server.
 
-### Core (11 tools)
+### Core (10 tools)
 
 | Tool | Purpose |
 |------|---------|
-| `nx_context` | Current session state lookup (branch, tasks, plan) |
 | `nx_task_list/add/update/close` | Task management + history.json archiving |
 | `nx_history_search` | Search past plan/task cycles (topic/decision query, last N) |
 | `nx_artifact_write` | Save artifacts (branch-isolated) |
@@ -101,7 +100,7 @@ Claude-callable tools exposed by the Nexus MCP server.
 | `nx_plan_update` | Modify plan issues (add/remove/edit/reopen) |
 | `nx_plan_decide` | Record issue decision (plan.json) |
 
-### Code Intelligence (10 tools)
+### Code Intelligence (8 tools)
 
 | Tool | Purpose |
 |------|---------|
@@ -113,11 +112,8 @@ Claude-callable tools exposed by the Nexus MCP server.
 | `nx_lsp_code_actions` | Auto-fix and refactoring suggestions |
 | `nx_lsp_document_symbols` | Symbols in a file |
 | `nx_lsp_workspace_symbols` | Project-wide symbol search |
-| `nx_ast_search` | AST pattern search (tree-sitter) |
-| `nx_ast_replace` | AST pattern replacement (dryRun supported) |
 
 LSP auto-detects the project language (e.g., `tsconfig.json` → TypeScript).
-AST tools require `@ast-grep/napi`: `bun install @ast-grep/napi`
 
 </details>
 

package/README.md

@@ -75,11 +75,10 @@ claude plugin install claude-nexus@nexus
 
 Claude가 직접 호출하는 도구입니다.
 
-### Core (11개)
+### Core (10개)
 
 | 도구 | 용도 |
 |------|------|
-| `nx_context` | 현재 세션 상태 조회 (브랜치, 태스크, 플랜) |
 | `nx_task_list/add/update/close` | `.nexus/state/tasks.json` 기반 태스크 관리 + `.nexus/history.json` 아카이브 |
 | `nx_history_search` | 과거 plan/task 사이클 검색 (topic/decision 검색, 최근 N개) |
 | `nx_artifact_write` | 팀 산출물 저장 (`.nexus/state/artifacts/`) |
@@ -88,7 +87,7 @@ Claude가 직접 호출하는 도구입니다.
 | `nx_plan_update` | 플랜 논점 수정 (add/remove/edit/reopen) |
 | `nx_plan_decide` | 논점 결정 처리 (plan.json) |
 
-### Code Intelligence (10개)
+### Code Intelligence (8개)
 
 | 도구 | 용도 |
 |------|------|
@@ -100,11 +99,8 @@ Claude가 직접 호출하는 도구입니다.
 | `nx_lsp_code_actions` | 자동 수정/리팩토링 제안 |
 | `nx_lsp_document_symbols` | 파일 내 심볼 목록 |
 | `nx_lsp_workspace_symbols` | 프로젝트 전체 심볼 검색 |
-| `nx_ast_search` | AST 패턴 검색 (tree-sitter) |
-| `nx_ast_replace` | AST 패턴 치환 (dryRun 지원) |
 
 LSP는 프로젝트 언어를 자동 감지합니다 (tsconfig.json → TypeScript 등).
-AST는 `@ast-grep/napi` 필요: `bun install @ast-grep/napi`
 
 </details>
 

package/VERSION

@@ -1 +1 @@
-0.27.0
+0.28.1

package/agents/architect.md

@@ -1,15 +1,14 @@
 ---
-name: architect
 description: "Technical design — evaluates How, reviews architecture, advises on implementation approach"
-model: opus
-maxTurns: 20
-disallowedTools: [Edit, Write, NotebookEdit, mcp__plugin_claude-nexus_nx__nx_task_add, mcp__plugin_claude-nexus_nx__nx_task_update]
-task: "Architecture, technical design, code review"
-alias_ko: 아키텍트
-category: how
-resume_tier: persistent
+model: claude-opus-4
+disallowedTools:
+  - Edit
+  - Write
+  - MultiEdit
+  - NotebookEdit
+  - mcp__plugin_claude-nexus_nx__nx_task_add
+  - mcp__plugin_claude-nexus_nx__nx_task_update
 ---
-
 ## Role
 
 You are the Architect — the technical authority who evaluates "How" something should be built.

package/agents/designer.md

@@ -1,15 +1,14 @@
 ---
-name: designer
 description: "UX/UI design — evaluates user experience, interaction patterns, and how users will experience the product"
-model: opus
-maxTurns: 25
-disallowedTools: [Edit, Write, NotebookEdit, mcp__plugin_claude-nexus_nx__nx_task_add, mcp__plugin_claude-nexus_nx__nx_task_update]
-task: "UI/UX design, interaction patterns, user experience"
-alias_ko: 디자이너
-category: how
-resume_tier: persistent
+model: claude-opus-4
+disallowedTools:
+  - Edit
+  - Write
+  - MultiEdit
+  - NotebookEdit
+  - mcp__plugin_claude-nexus_nx__nx_task_add
+  - mcp__plugin_claude-nexus_nx__nx_task_update
 ---
-
 ## Role
 
 You are the Designer — the user experience authority who evaluates "How" something should be experienced by users.

package/agents/engineer.md

@@ -1,15 +1,9 @@
 ---
-name: engineer
 description: "Implementation — writes code, debugs issues, follows specifications from Lead and architect"
-model: sonnet
-maxTurns: 25
-disallowedTools: [mcp__plugin_claude-nexus_nx__nx_task_add]
-task: "Code implementation, edits, debugging"
-alias_ko: 엔지니어
-category: do
-resume_tier: bounded
+model: claude-sonnet-4
+disallowedTools:
+  - mcp__plugin_claude-nexus_nx__nx_task_add
 ---
-
 ## Role
 
 You are the Engineer — the hands-on implementer who writes code and debugs issues.

package/agents/lead.md

@@ -0,0 +1,59 @@
+---
+description: "Primary orchestrator — converses directly with users, composes 9 subagents across HOW/DO/CHECK categories, and owns scope decisions and task lifecycle"
+model: claude-opus-4
+---
+## Identity
+
+You are Lead — the sole agent who converses directly with users.
+You orchestrate 9 subagents (architect, designer, postdoc, strategist, engineer, researcher, writer, reviewer, tester) to fulfill user requests.
+Final responsibility for decision recording, scope judgment, and user-facing reporting rests with you.
+
+## Constraints
+
+- **Task ownership**: You are the only agent authorized to call `nx_task_add` / `nx_task_update` / `nx_task_close`. Subagents do not create or update tasks.
+- **Scope authority**: You consult HOW agents for advice, but final scope decisions are yours alone.
+- **Skill delegation**: Delegate execution flows to skills. Use nx-plan for `[plan]`, nx-run for `[run]`, nx-sync for `[sync]`, and nx-init for initial onboarding. Detailed execution steps live inside each skill and are not duplicated in this body.
+- **File editing**: No `no_file_edit` restriction — handle simple tasks directly.
+- **Absolute prohibitions**:
+  - Spawning multiple subagents in parallel for the same task (risk of target file conflicts)
+  - Destructive git operations without explicit user instruction (`reset --hard`, `push --force`, etc.)
+  - Injecting hook messages in any language other than English
+
+## Collaboration
+
+### HOW agents (architect / designer / postdoc / strategist)
+They advise on technical, UX, research methodology, and business judgment. They do not hold decision authority. You review their advice and make the final call.
+
+### DO agents (engineer / researcher / writer)
+They handle execution, implementation, investigation, and writing. You provide task context, approach, and acceptance criteria, then review their deliverables.
+
+### CHECK agents (reviewer / tester)
+They verify the accuracy and quality of deliverables.
+- writer → reviewer: mandatory pairing
+- engineer → tester: conditional pairing (when acceptance criteria include runtime requirements)
+
+### Direct handling vs. spawn decision
+- Single file or small-scale edits: handle directly as Lead
+- Three or more files, complex judgment, or specialist analysis: spawn a subagent
+
+### Resume Dispatch
+Decide whether to reuse a completed subagent based on the `resume_tier` field (persistent / bounded / ephemeral) in the agent's frontmatter. See the nx-run skill for detailed rules.
+
+## Output Format
+
+When responding to users, maintain the following structure:
+
+- **Changes**: Paths and summaries of modified, created, or deleted files
+- **Key Decisions**: Judgments made during this work (scope, approach, trade-offs)
+- **Next Steps**: Follow-on actions the user can take (review, commit, further investigation, etc.)
+
+For long responses, lead with the summary. For short questions, answer directly without structure.
+
+## References
+
+| Skill | Purpose |
+|-------|---------|
+| nx-plan | Structured multi-perspective analysis and decision recording |
+| nx-run | Task execution orchestration |
+| nx-sync | `.nexus/context/` knowledge synchronization |
+| nx-init | Project onboarding |

package/agents/postdoc.md

@@ -1,15 +1,14 @@
 ---
-name: postdoc
 description: "Research methodology and synthesis — designs investigation approach, evaluates evidence quality, writes synthesis documents"
-model: opus
-maxTurns: 25
-disallowedTools: [Edit, Write, NotebookEdit, mcp__plugin_claude-nexus_nx__nx_task_add, mcp__plugin_claude-nexus_nx__nx_task_update]
-task: "Research methodology, evidence synthesis"
-alias_ko: 포닥
-category: how
-resume_tier: persistent
+model: claude-opus-4
+disallowedTools:
+  - Edit
+  - Write
+  - MultiEdit
+  - NotebookEdit
+  - mcp__plugin_claude-nexus_nx__nx_task_add
+  - mcp__plugin_claude-nexus_nx__nx_task_update
 ---
-
 ## Role
 
 You are the Postdoctoral Researcher — the methodological authority who evaluates "How" research should be conducted and synthesizes findings into coherent conclusions.

package/agents/researcher.md

@@ -1,15 +1,13 @@
 ---
-name: researcher
 description: "Independent investigation — conducts web searches, gathers evidence, and reports findings with citations"
-model: sonnet
-maxTurns: 20
-disallowedTools: [Edit, Write, NotebookEdit, mcp__plugin_claude-nexus_nx__nx_task_add]
-task: "Web search, independent investigation"
-alias_ko: 리서처
-category: do
-resume_tier: persistent
+model: claude-sonnet-4
+disallowedTools:
+  - Edit
+  - Write
+  - MultiEdit
+  - NotebookEdit
+  - mcp__plugin_claude-nexus_nx__nx_task_add
 ---
-
 ## Role
 
 You are the Researcher — the web research specialist who gathers evidence through web searches, external document analysis, and structured inquiry.

package/agents/reviewer.md

@@ -1,15 +1,13 @@
 ---
-name: reviewer
 description: "Content verification — validates accuracy, checks facts, confirms grammar and format of non-code deliverables"
-model: sonnet
-maxTurns: 20
-disallowedTools: [Edit, Write, NotebookEdit, mcp__plugin_claude-nexus_nx__nx_task_add]
-task: "Content verification, fact-checking, grammar review"
-alias_ko: 리뷰어
-category: check
-resume_tier: ephemeral
+model: claude-sonnet-4
+disallowedTools:
+  - Edit
+  - Write
+  - MultiEdit
+  - NotebookEdit
+  - mcp__plugin_claude-nexus_nx__nx_task_add
 ---
-
 ## Role
 
 You are the Reviewer — the content quality guardian who verifies the accuracy, clarity, and integrity of non-code deliverables.

package/agents/strategist.md

@@ -1,15 +1,14 @@
 ---
-name: strategist
 description: "Business strategy — evaluates market positioning, competitive landscape, and business viability of decisions"
-model: opus
-maxTurns: 25
-disallowedTools: [Edit, Write, NotebookEdit, mcp__plugin_claude-nexus_nx__nx_task_add, mcp__plugin_claude-nexus_nx__nx_task_update]
-task: "Business strategy, market analysis, competitive positioning"
-alias_ko: 전략가
-category: how
-resume_tier: persistent
+model: claude-opus-4
+disallowedTools:
+  - Edit
+  - Write
+  - MultiEdit
+  - NotebookEdit
+  - mcp__plugin_claude-nexus_nx__nx_task_add
+  - mcp__plugin_claude-nexus_nx__nx_task_update
 ---
-
 ## Role
 
 You are the Strategist — the business and market authority who evaluates "How" decisions land in the real world.

package/agents/tester.md

@@ -1,15 +1,13 @@
 ---
-name: tester
 description: "Testing and verification — tests, verifies, validates stability and security of implementations"
-model: sonnet
-maxTurns: 20
-disallowedTools: [Edit, Write, NotebookEdit, mcp__plugin_claude-nexus_nx__nx_task_add]
-task: "Testing, verification, security review"
-alias_ko: 테스터
-category: check
-resume_tier: ephemeral
+model: claude-sonnet-4
+disallowedTools:
+  - Edit
+  - Write
+  - MultiEdit
+  - NotebookEdit
+  - mcp__plugin_claude-nexus_nx__nx_task_add
 ---
-
 ## Role
 
 You are the Tester — the code verification specialist who tests, validates, and secures implementations.

package/agents/writer.md

@@ -1,15 +1,9 @@
 ---
-name: writer
 description: "Technical writing — transforms research findings, code, and analysis into clear documents and presentations for the intended audience"
-model: sonnet
-maxTurns: 25
-disallowedTools: [mcp__plugin_claude-nexus_nx__nx_task_add]
-task: "Technical writing, documentation, presentations"
-alias_ko: 라이터
-category: do
-resume_tier: bounded
+model: claude-sonnet-4
+disallowedTools:
+  - mcp__plugin_claude-nexus_nx__nx_task_add
 ---
-
 ## Role
 
 You are the Writer — the communication specialist who transforms technical content into clear, audience-appropriate documents.

package/dist/hooks/agent-bootstrap.js

@@ -0,0 +1,105 @@
+// assets/hooks/agent-bootstrap/handler.ts
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+var CORE_INDEX_SIZE_LIMIT = 2 * 1024;
+function loadValidRoles(cwd) {
+  const agentsDir = join(cwd, "assets/agents");
+  const roles = [];
+  if (existsSync(agentsDir)) {
+    for (const entry of readdirSync(agentsDir, { withFileTypes: true })) {
+      if (entry.isDirectory())
+        roles.push(entry.name);
+    }
+  }
+  return roles;
+}
+function readFirstLine(path) {
+  try {
+    const content = readFileSync(path, "utf-8");
+    const firstNonEmpty = content.split(`
+`).find((l) => l.trim().length > 0) ?? "";
+    return firstNonEmpty.replace(/^#+\s*/, "").slice(0, 80);
+  } catch {
+    return "";
+  }
+}
+function buildCoreIndex(cwd) {
+  const entries = [];
+  for (const sub of [".nexus/memory", ".nexus/context"]) {
+    const absDir = join(cwd, sub);
+    if (!existsSync(absDir))
+      continue;
+    for (const f of readdirSync(absDir, { withFileTypes: true })) {
+      if (!f.isFile() || !f.name.endsWith(".md"))
+        continue;
+      const full = join(absDir, f.name);
+      entries.push({
+        path: `${sub}/${f.name}`,
+        mtime: statSync(full).mtimeMs,
+        line: readFirstLine(full)
+      });
+    }
+  }
+  entries.sort((a, b) => b.mtime - a.mtime);
+  const lines = [];
+  let bytes = 0;
+  for (const e of entries) {
+    const formatted = `- ${e.path}: ${e.line}`;
+    if (bytes + formatted.length + 1 > CORE_INDEX_SIZE_LIMIT)
+      break;
+    lines.push(formatted);
+    bytes += formatted.length + 1;
+  }
+  return lines.length > 0 ? `Available memory/context:
+` + lines.join(`
+`) : "";
+}
+function getResumeCount(cwd, sessionId, agentId) {
+  const trackerPath = join(cwd, ".nexus/state", sessionId, "agent-tracker.json");
+  if (!existsSync(trackerPath))
+    return 0;
+  try {
+    const tracker = JSON.parse(readFileSync(trackerPath, "utf-8"));
+    const entry = Array.isArray(tracker) ? tracker.find((e) => e.agent_id === agentId) : null;
+    return entry?.resume_count ?? 0;
+  } catch {
+    return 0;
+  }
+}
+var handler = async (input) => {
+  if (input.hook_event_name !== "SubagentStart")
+    return;
+  const { cwd, session_id, agent_type, agent_id } = input;
+  const resumeCount = getResumeCount(cwd, session_id, agent_id);
+  if (resumeCount > 0)
+    return;
+  const validRoles = loadValidRoles(cwd);
+  if (!validRoles.includes(agent_type))
+    return;
+  const parts = [];
+  const coreIndex = buildCoreIndex(cwd);
+  if (coreIndex) {
+    parts.push(`<system-notice>
+${coreIndex}
+</system-notice>`);
+  }
+  const rulePath = join(cwd, ".nexus/rules", `${agent_type}.md`);
+  if (existsSync(rulePath)) {
+    const ruleContent = readFileSync(rulePath, "utf-8").trim();
+    if (ruleContent) {
+      parts.push(`<system-notice>
+Custom rule for ${agent_type}:
+${ruleContent}
+</system-notice>`);
+    }
+  }
+  if (parts.length === 0)
+    return;
+  return { additional_context: parts.join(`
+
+`) };
+};
+var handler_default = handler;
+export {
+  handler_default as default
+};

package/dist/hooks/agent-finalize.js

@@ -0,0 +1,164 @@
+// src/shared/json-store.js
+import fs from "node:fs/promises";
+import { constants as fsConstants, appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+var inProcessQueues = new Map;
+async function runWithInProcessLock(filePath, action) {
+  const previous = inProcessQueues.get(filePath) ?? Promise.resolve();
+  let release = () => {};
+  const gate = new Promise((resolve) => {
+    release = resolve;
+  });
+  const entry = previous.then(() => gate);
+  inProcessQueues.set(filePath, entry);
+  await previous;
+  try {
+    return await action();
+  } finally {
+    release();
+    entry.finally(() => {
+      if (inProcessQueues.get(filePath) === entry) {
+        inProcessQueues.delete(filePath);
+      }
+    });
+  }
+}
+var LOCK_RETRY_INTERVAL_MS = 100;
+var LOCK_MAX_RETRIES = 50;
+var LOCK_STALE_MS = 30000;
+function lockPath(filePath) {
+  return `${filePath}.lock`;
+}
+async function acquireFsLock(filePath) {
+  const lp = lockPath(filePath);
+  for (let attempt = 0;attempt <= LOCK_MAX_RETRIES; attempt++) {
+    try {
+      const fd = await fs.open(lp, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL);
+      await fd.close();
+      return;
+    } catch (err) {
+      const e = err;
+      if (e.code !== "EEXIST")
+        throw err;
+      try {
+        const stat = await fs.stat(lp);
+        const ageMs = Date.now() - stat.mtimeMs;
+        if (ageMs > LOCK_STALE_MS) {
+          await fs.unlink(lp).catch(() => {
+            return;
+          });
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      if (attempt === LOCK_MAX_RETRIES) {
+        throw new Error(`Failed to acquire lock for "${filePath}" after ${LOCK_MAX_RETRIES} retries`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_INTERVAL_MS));
+    }
+  }
+}
+async function releaseFsLock(filePath) {
+  await fs.unlink(lockPath(filePath)).catch(() => {
+    return;
+  });
+}
+async function readJsonFile(filePath, defaultValue) {
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, "utf8");
+  } catch (err) {
+    const e = err;
+    if (e.code === "ENOENT")
+      return defaultValue;
+    throw err;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return defaultValue;
+  }
+}
+async function writeJsonFile(filePath, data) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.tmp.${process.pid}.${Date.now()}.${randomUUID()}`;
+  await fs.writeFile(tmpPath, JSON.stringify(data, null, 2) + `
+`, "utf8");
+  await fs.rename(tmpPath, filePath);
+}
+async function updateJsonFileLocked(filePath, defaultValue, updater) {
+  return runWithInProcessLock(filePath, async () => {
+    await acquireFsLock(filePath);
+    try {
+      const current = await readJsonFile(filePath, defaultValue);
+      const next = await updater(current);
+      await writeJsonFile(filePath, next);
+      return next;
+    } finally {
+      await releaseFsLock(filePath);
+    }
+  });
+}
+var APPEND_SIZE_WARN_THRESHOLD = 4 * 1024;
+
+// assets/hooks/agent-finalize/handler.ts
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+var handler = async (input) => {
+  if (input.hook_event_name !== "SubagentStop")
+    return;
+  const { cwd, session_id, agent_type, agent_id } = input;
+  const lastMessage = (input.last_assistant_message ?? "").slice(0, 500);
+  const sessionDir = join(cwd, ".nexus/state", session_id);
+  const trackerPath = join(sessionDir, "agent-tracker.json");
+  const toolLogPath = join(sessionDir, "tool-log.jsonl");
+  const tasksPath = join(sessionDir, "tasks.json");
+  await updateJsonFileLocked(trackerPath, [], (tracker) => {
+    const entry = tracker.find((e) => e["agent_id"] === agent_id);
+    if (!entry)
+      return tracker;
+    entry["status"] = "completed";
+    entry["stopped_at"] = new Date().toISOString();
+    entry["last_message"] = lastMessage;
+    if (existsSync(toolLogPath)) {
+      const files = new Set;
+      const raw = readFileSync(toolLogPath, "utf-8");
+      for (const line of raw.split(`
+`)) {
+        if (!line.trim())
+          continue;
+        try {
+          const log = JSON.parse(line);
+          if (log["agent_id"] === agent_id && typeof log["file"] === "string") {
+            files.add(log["file"]);
+          }
+        } catch {}
+      }
+      entry["files_touched"] = [...files];
+    }
+    return tracker;
+  });
+  if (!existsSync(tasksPath))
+    return;
+  try {
+    const tasksData = JSON.parse(readFileSync(tasksPath, "utf-8"));
+    const tasks = Array.isArray(tasksData?.["tasks"]) ? tasksData["tasks"] : [];
+    const incomplete = tasks.filter((t) => t["owner"]?.["role"] === agent_type && t["status"] !== "completed");
+    if (incomplete.length === 0)
+      return;
+    const ids = incomplete.map((t) => t["id"]).join(", ");
+    return {
+      additional_context: `<system-notice>
+Subagent "${agent_type}" finished. Tasks still pending with this role: ${ids}. Review status and coordinate remaining subagent delegation.
+</system-notice>`
+    };
+  } catch {
+    return;
+  }
+};
+var handler_default = handler;
+export {
+  handler_default as default
+};