claude-nexus 0.21.0 → 0.23.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.21.0",
+      "version": "0.23.0",
       "author": {
         "name": "kih"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-nexus",
-  "version": "0.21.0",
+  "version": "0.23.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 — architect, engineer, tester, researcher, and more. One tag triggers automatic orchestration of complex tasks across the right agents without manual coordination.
+Specialized subagents handle development and research systematically — architect, engineer, tester, researcher, and more. One tag triggers automatic orchestration of complex tasks across the right agents without manual coordination.
 
 ## Quick Start
 
@@ -27,7 +27,7 @@ Run `/claude-nexus:nx-init` — scans your project and auto-generates structured
 **3. Start using**
 
 - **Plan**: `[plan] How should we design the auth system?` — clarify intent and align before executing
-- **Run**: `[run] Implement login API` — agent team handles analysis through implementation
+- **Run**: `[run] Implement login API` — subagents handle analysis through implementation
 
 ## Usage
 
@@ -36,15 +36,15 @@ Tag your message to route it to the right workflow:
 | Tag | Action | Example |
 |-----|--------|---------|
 | `[plan]` | Pre-execution planning | `[plan] Discuss DB migration strategy` |
-| `[run]` | Execution (agent team) | `[run] Refactor payment module` |
-| `[d]` | Record a decision | `[d] Use PostgreSQL for primary storage` |
+| `[run]` | Execution (subagent composition) | `[run] Refactor payment module` |
+| `[d]` | Record a decision (within plan session) | `[d] Use PostgreSQL for primary storage` |
 | `[rule]` | Save a rule | `[rule] Always use bun instead of npm` |
 
-Typical flow: use `[plan]` to discuss and align → decide → use `[run]` to execute.
+Typical flow: `[plan]` to discuss and align → `[d]` to decide (within plan) → `[run]` to execute.
 
 ## Agents
 
-### How Team (4 agents)
+### How (4 agents)
 
 | Agent | Invocation | Role | Model |
 |-------|-----------|------|-------|
@@ -53,7 +53,7 @@ Typical flow: use `[plan]` to discuss and align → decide → use `[run]` to ex
 | **Postdoc** | `claude-nexus:postdoc` | Research methodology and evidence synthesis | opus |
 | **Strategist** | `claude-nexus:strategist` | Business strategy and competitive positioning | opus |
 
-### Do Team (3 agents)
+### Do (3 agents)
 
 | Agent | Invocation | Role | Model |
 |-------|-----------|------|-------|
@@ -61,7 +61,7 @@ Typical flow: use `[plan]` to discuss and align → decide → use `[run]` to ex
 | **Researcher** | `claude-nexus:researcher` | Web search, independent investigation | sonnet |
 | **Writer** | `claude-nexus:writer` | Technical writing and documentation | sonnet |
 
-### Check Team (2 agents)
+### Check (2 agents)
 
 | Agent | Invocation | Role | Model |
 |-------|-----------|------|-------|
@@ -85,17 +85,16 @@ Typical flow: use `[plan]` to discuss and align → decide → use `[run]` to ex
 
 Claude-callable tools exposed by the Nexus MCP server.
 
-### Core (15 tools)
+### Core (14 tools)
 
 | Tool | Purpose |
 |------|---------|
-| `nx_briefing` | Assemble role-specific briefing (core knowledge + rules) |
 | `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, plan) |
 | `nx_task_list/add/update/close` | Task management + history.json archiving |
-| `nx_artifact_write` | Save team artifacts (branch-isolated) |
-| `nx_plan_start` | Start plan session (topic + issues, team verification) |
+| `nx_artifact_write` | Save artifacts (branch-isolated) |
+| `nx_plan_start` | Start plan session (topic + issues + research summary) |
 | `nx_plan_status` | Query plan state |
 | `nx_plan_update` | Modify plan issues (add/remove/edit/reopen) |
 | `nx_plan_decide` | Record issue decision (plan.json) |
@@ -127,9 +126,13 @@ Nexus registers a single Gate module as a Claude Code hook.
 
 | Event | Role |
 |-------|------|
+| `SessionStart` | Initialize `.nexus/` structure, reset agent-tracker |
 | `UserPromptSubmit` | Tag detection → mode activation + TASK_PIPELINE injection + additionalContext guidance |
-| `PreToolUse` | Edit/Write: blocks when tasks.json missing. nx_plan_start: attendee team verification. Agent: team_name tracking |
+| `PreToolUse` | Edit/Write: blocks when incomplete tasks exist |
+| `SubagentStart` | Auto-inject role-filtered core knowledge index (lazy-read) |
+| `SubagentStop` | Record agent completion. Warn if owned tasks remain incomplete |
 | `Stop` | Blocks exit with pending tasks. Forces nx_task_close when all completed |
+| `PostCompact` | Snapshot session state (mode, plan, agent status) |
 
 </details>
 
@@ -154,17 +157,16 @@ Project knowledge and rules are stored under `.nexus/` and tracked by git.
 <details>
 <summary>Runtime State</summary>
 
-Runtime state is stored under `.nexus/` and is excluded from git.
+Runtime state is stored under `.nexus/state/` and is excluded from git. `history.json` is at `.nexus/` root and git-tracked.
 
 ```
 .nexus/
-├── branches/               ← Per-branch isolation
-│   └── {branch}/
-│       ├── tasks.json      ← Task list
-│       ├── meet.json       ← Meeting issue tracker
-│       ├── history.json    ← Cycle archive (created by nx_task_close)
-│       └── artifacts/      ← Team artifacts
-└── sync-state.json         ← Last sync commit
+├── history.json            ← Cycle archive (git-tracked, created by nx_task_close)
+└── state/                  ← Runtime state (git-ignored)
+    ├── tasks.json          ← Task list ([run] cycle)
+    ├── plan.json           ← Planning session ([plan] cycle)
+    ├── agent-tracker.json  ← Subagent lifecycle tracking
+    └── artifacts/          ← Artifacts
 ```
 
 </details>

package/README.md

@@ -29,15 +29,16 @@ claude plugin install claude-nexus@nexus
 **첫 사용**
 
 - **플랜**: `[plan] 인증 시스템 어떻게 설계하면 좋을까?`
-- **결정 기록**: `응 그 방향으로 [d]`
+- **결정 기록**: (plan 중) `응 그 방향으로 [d]`
+- **실행**: `[run] 로그인 API 구현`
 
 ## 사용법
 
 | 태그 | 동작 | 예시 |
 |------|------|------|
 | `[plan]` | 플랜 모드 활성화 | `[plan] DB 마이그레이션 전략 논의` |
-| `[d]` | 결정 기록 | `응 그 방향으로 [d]` |
-| `[run]` | 실행 (에이전트 팀) | `[run] 결제 모듈 리팩토링` |
+| `[d]` | 결정 기록 (plan 세션 내) | `응 그 방향으로 [d]` |
+| `[run]` | 실행 (서브에이전트 구성) | `[run] 결제 모듈 리팩토링` |
 | `[rule]` | 규칙 저장 | `[rule] npm 대신 bun 사용` |
 
 ## 에이전트
@@ -59,7 +60,7 @@ claude plugin install claude-nexus@nexus
 | 스킬 | 트리거 | 설명 |
 |------|--------|------|
 | **nx-plan** | `[plan]` | 구조화된 플랜. 요구사항 정리 → 결정 기록 |
-| **nx-run** | (기본 동작) | 동적 에이전트 구성 실행 |
+| **nx-run** | `[run]` | 동적 에이전트 구성 실행 |
 | **nx-init** | `/claude-nexus:nx-init` | 프로젝트 온보딩. 코드 스캔 → 지식 생성 |
 | **nx-setup** | `/claude-nexus:nx-setup` | 대화형 설정 |
 | **nx-sync** | `/claude-nexus:nx-sync` | 코어 지식 동기화. 소스 변경사항을 .nexus/core/ 문서에 반영 |
@@ -71,17 +72,16 @@ claude plugin install claude-nexus@nexus
 
 Claude가 직접 호출하는 도구입니다.
 
-### Core (15개)
+### Core (14개)
 
 | 도구 | 용도 |
 |------|------|
-| `nx_briefing` | 에이전트 역할별 브리핑 조립 (core knowledge + rules 기반) |
 | `nx_core_read/write` | 프로젝트 지식 관리 (`.nexus/core/`, git 추적) |
 | `nx_rules_read/write` | 팀 커스텀 규칙 관리 (`.nexus/rules/`, git 추적) |
 | `nx_context` | 현재 세션 상태 조회 (브랜치, 태스크, 플랜) |
 | `nx_task_list/add/update/close` | `.nexus/state/tasks.json` 기반 태스크 관리 + `.nexus/history.json` 아카이브 |
 | `nx_artifact_write` | 팀 산출물 저장 (`.nexus/state/artifacts/`) |
-| `nx_plan_start` | 플랜 세션 시작 (토픽 + 논점 등록, 참석자 팀 검증) |
+| `nx_plan_start` | 플랜 세션 시작 (토픽 + 논점 + 리서치 요약 등록) |
 | `nx_plan_status` | 플랜 상태 조회 |
 | `nx_plan_update` | 플랜 논점 수정 (add/remove/edit/reopen) |
 | `nx_plan_decide` | 논점 결정 처리 (plan.json) |
@@ -113,9 +113,13 @@ Gate 단일 모듈로 동작합니다.
 
 | 이벤트 | 역할 |
 |--------|------|
+| `SessionStart` | `.nexus/` 구조 초기화, agent-tracker 리셋 |
 | `UserPromptSubmit` | 태그 감지 → 모드 활성화 + TASK_PIPELINE 주입 + additionalContext 안내 |
-| `PreToolUse` | Edit/Write: tasks.json 없으면 차단. nx_plan_start: 참석자 팀 검증. Agent: team_name 트래킹 |
+| `PreToolUse` | Edit/Write: tasks.json 미완료 시 차단 |
+| `SubagentStart` | 에이전트 역할별 코어 지식 인덱스 자동 주입 (lazy-read) |
+| `SubagentStop` | 에이전트 완료 기록. 미완료 태스크 경고 |
 | `Stop` | pending 태스크 있으면 종료 차단. all completed면 nx_task_close 강제 |
+| `PostCompact` | 세션 상태 스냅샷 (모드, 플랜, 에이전트 현황) |
 
 </details>
 
@@ -128,7 +132,7 @@ Gate 단일 모듈로 동작합니다.
 - `rules/` — 팀 커스텀 규칙. git 추적.
 - `config.json` — Nexus 설정. git 추적.
 - `history.json` — 사이클 아카이브. git 추적.
-- `state/` — 런타임 상태 (tasks, meet 등). git 무시.
+- `state/` — 런타임 상태 (tasks, plan 등). git 무시.
 
 </details>
 
@@ -139,12 +143,10 @@ Gate 단일 모듈로 동작합니다.
 
 ```
 .nexus/state/
-├── tasks.json
-├── meet.json
-├── edit-tracker.json
-├── reopen-tracker.json
-├── agent-tracker.json
-└── artifacts/
+├── tasks.json          ← 태스크 목록 ([run] 사이클)
+├── plan.json           ← 플랜 세션 ([plan] 사이클)
+├── agent-tracker.json  ← 서브에이전트 라이프사이클
+└── artifacts/          ← 산출물
 ```
 
 </details>

package/VERSION

@@ -1 +1 @@
-0.21.0
+0.23.0

package/bridge/mcp-server.cjs

@@ -22255,9 +22255,11 @@ function registerPlanTools(server2) {
     "\uC548\uAC74 \uACB0\uC815 \uAE30\uB85D \u2014 [d] \uD0DC\uADF8\uB85C \uD2B8\uB9AC\uAC70",
     {
       issue_id: external_exports.number().describe("\uACB0\uC815\uD560 \uC548\uAC74 ID"),
-      summary: external_exports.string().describe("\uACB0\uC815 \uC694\uC57D")
+      summary: external_exports.string().describe("\uACB0\uC815 \uC694\uC57D"),
+      how_agents: external_exports.array(external_exports.string()).optional().describe('\uC774\uC288 \uBD84\uC11D\uC5D0 \uCC38\uC5EC\uD55C HOW \uC5D0\uC774\uC804\uD2B8 \uC774\uB984 \uBAA9\uB85D (\uC608: ["architect", "designer"])'),
+      how_summary: external_exports.record(external_exports.string(), external_exports.string()).optional().describe('\uC5D0\uC774\uC804\uD2B8\uBCC4 \uD575\uC2EC \uC758\uACAC \uC694\uC57D (\uC608: { "architect": "...", "designer": "..." })')
     },
-    async ({ issue_id, summary }) => {
+    async ({ issue_id, summary, how_agents, how_summary }) => {
       const data = await readPlan();
       if (!data) {
         return textResult({ error: "No active plan session" });
@@ -22268,6 +22270,8 @@ function registerPlanTools(server2) {
       }
       issue2.status = "decided";
       issue2.decision = summary;
+      if (how_agents !== void 0) issue2.how_agents = how_agents;
+      if (how_summary !== void 0) issue2.how_summary = how_summary;
       await writePlan(data);
       const allComplete = data.issues.every((i) => i.status === "decided");
       if (allComplete) {
@@ -22478,135 +22482,8 @@ function registerArtifactTools(server2) {
   );
 }
 
-// src/mcp/tools/briefing.ts
-var import_fs11 = require("fs");
-var import_promises7 = require("fs/promises");
-var import_path12 = require("path");
-var MATRIX = {
-  architect: { identity: "all", codebase: "all", reference: "all", memory: "all" },
-  postdoc: { identity: "all", codebase: "all", reference: "all", memory: "all" },
-  engineer: { identity: null, codebase: "all", reference: null, memory: "all" },
-  researcher: { identity: "all", codebase: null, reference: "all", memory: "all" },
-  tester: { identity: "all", codebase: "all", reference: null, memory: "all" },
-  designer: { identity: "all", codebase: "all", reference: "all", memory: "all" },
-  strategist: { identity: "all", codebase: "all", reference: "all", memory: "all" },
-  writer: { identity: null, codebase: "all", reference: null, memory: "all" },
-  reviewer: { identity: "all", codebase: "all", reference: null, memory: "all" }
-};
-function parseTags2(content) {
-  const match = content.match(/^<!--\s*tags:\s*(.+?)\s*-->/);
-  if (!match) return [];
-  return match[1].split(",").map((t) => t.trim()).filter(Boolean);
-}
-async function readLayerFiles(layer, hint) {
-  const layerDir = coreLayerDir(layer);
-  if (!(0, import_fs11.existsSync)(layerDir)) return [];
-  const files = (await (0, import_promises7.readdir)(layerDir)).filter((f) => f.endsWith(".md"));
-  const results = [];
-  for (const file of files) {
-    const filePath = (0, import_path12.join)(layerDir, file);
-    const content = await (0, import_promises7.readFile)(filePath, "utf-8");
-    results.push({ filename: file, content });
-  }
-  if (hint && results.length > 0) {
-    const hintLower = hint.toLowerCase();
-    const matched = results.filter(({ filename, content }) => {
-      const tags = parseTags2(content);
-      return tags.some((t) => t.toLowerCase().includes(hintLower)) || filename.toLowerCase().includes(hintLower);
-    });
-    if (matched.length > 0) return matched;
-  }
-  return results;
-}
-function registerBriefingTool(server2) {
-  server2.tool(
-    "nx_briefing",
-    "Assemble a role-specific briefing from the core knowledge store (identity, codebase, reference, memory layers) plus decisions and rules.",
-    {
-      role: external_exports.enum(["architect", "postdoc", "engineer", "researcher", "tester", "designer", "strategist", "writer", "reviewer"]).describe("Agent role"),
-      hint: external_exports.string().optional().describe("Relevant module/area hint for tag filtering")
-    },
-    async (params) => {
-      const role = params.role;
-      const hint = params.hint;
-      const matrix = MATRIX[role];
-      if (!matrix) {
-        return textResult({ error: `Unknown role: ${role}` });
-      }
-      const collectedFiles = [];
-      const sections = {};
-      for (const layer of LAYERS) {
-        const policy = matrix[layer];
-        if (policy === null) continue;
-        const files = await readLayerFiles(layer, hint);
-        sections[layer] = files;
-        for (const f of files) {
-          collectedFiles.push(`${layer}/${f.filename}`);
-        }
-      }
-      let decisionsSection = "";
-      const decisionsPath = (0, import_path12.join)(STATE_ROOT, "decisions.json");
-      if ((0, import_fs11.existsSync)(decisionsPath)) {
-        const raw = await (0, import_promises7.readFile)(decisionsPath, "utf-8");
-        decisionsSection = raw.trim();
-      }
-      let rulesSection = "";
-      const rulesDir = (0, import_path12.join)(NEXUS_ROOT, "rules");
-      if ((0, import_fs11.existsSync)(rulesDir)) {
-        const ruleFiles = (await (0, import_promises7.readdir)(rulesDir)).filter((f) => f.endsWith(".md"));
-        let parts = [];
-        for (const ruleFile of ruleFiles) {
-          const content = await (0, import_promises7.readFile)((0, import_path12.join)(rulesDir, ruleFile), "utf-8");
-          parts.push({ filename: ruleFile, content });
-        }
-        if (hint && parts.length > 0) {
-          const hintLower = hint.toLowerCase();
-          const matched = parts.filter(({ filename, content }) => {
-            const tags = parseTags2(content);
-            return tags.some((t) => t.toLowerCase().includes(hintLower)) || filename.toLowerCase().includes(hintLower);
-          });
-          if (matched.length > 0) parts = matched;
-        }
-        rulesSection = parts.map(({ filename, content }) => `### ${filename}
-${content.trim()}`).join("\n\n");
-      }
-      const lines = [];
-      lines.push(`<!-- briefing: role=${role}, hint=${hint ?? "null"}, files=[${collectedFiles.join(", ")}] -->`);
-      lines.push("");
-      if (decisionsSection) {
-        lines.push("## Decisions");
-        lines.push(decisionsSection);
-        lines.push("");
-      }
-      if (rulesSection) {
-        lines.push("## Rules");
-        lines.push(rulesSection);
-        lines.push("");
-      }
-      for (const layer of LAYERS) {
-        const policy = matrix[layer];
-        if (policy === null) continue;
-        const layerName = layer.charAt(0).toUpperCase() + layer.slice(1);
-        lines.push(`## ${layerName}`);
-        const files = sections[layer] ?? [];
-        if (files.length === 0) {
-          lines.push(`No ${layer} files.`);
-        } else {
-          for (const { filename, content } of files) {
-            lines.push(`### ${filename}`);
-            lines.push(content.trim());
-          }
-        }
-        lines.push("");
-      }
-      const markdown = lines.join("\n");
-      return { content: [{ type: "text", text: markdown }] };
-    }
-  );
-}
-
 // src/mcp/server.ts
-var import_path13 = require("path");
+var import_path12 = require("path");
 var server = new McpServer({
   name: "nx",
   version: getCurrentVersion() || "0.0.0"
@@ -22615,7 +22492,7 @@ registerCoreStore(server);
 registerMarkdownStore(server, {
   toolPrefix: "nx_rules",
   entityName: "name",
-  dirPath: (0, import_path13.join)(NEXUS_ROOT, "rules"),
+  dirPath: (0, import_path12.join)(NEXUS_ROOT, "rules"),
   pathFn: rulesPath,
   listKey: "rules",
   cache: false
@@ -22626,7 +22503,6 @@ registerAstTools(server);
 registerTaskTools(server);
 registerArtifactTools(server);
 registerPlanTools(server);
-registerBriefingTool(server);
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);