claude-nexus 0.10.0 → 0.12.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.10.0",
+      "version": "0.12.0",
       "author": {
         "name": "kih"
       },

package/.claude-plugin/plugin.json

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

package/README.en.md

@@ -80,14 +80,18 @@ Typical flow: use `[consult]` to discuss and align → decide → use `[dev]` or
 
 Claude-callable tools exposed by the Nexus MCP server.
 
-### Core (5 tools)
+### Core (9 tools)
 
 | Tool | Purpose |
 |------|---------|
 | `nx_knowledge_read/write` | Project knowledge management (git-tracked) |
-| `nx_context` | Current session state lookup |
+| `nx_context` | Current session state lookup (branch, tasks, decisions) |
 | `nx_task_list/add/update/clear` | Task management backed by tasks.json |
 | `nx_decision_add` | Record architecture decisions |
+| `nx_artifact_write` | Save team artifacts (branch-isolated) |
+| `nx_consult_start` | Start consultation session (topic + issues) |
+| `nx_consult_status` | Query consultation state |
+| `nx_consult_decide` | Record issue decision (consult.json + decisions.json) |
 
 ### Code Intelligence (10 tools)
 
@@ -142,7 +146,8 @@ Runtime state is stored under `.nexus/` and is excluded from git.
 │   └── {branch}/
 │       ├── tasks.json      ← Task list
 │       ├── decisions.json  ← Architecture decision list
-│       └── reports/        ← Research outputs
+│       ├── consult.json   ← Consultation issue tracker (exists only during consult)
+│       └── artifacts/      ← Team artifacts
 └── sync-state.json         ← Last sync commit
 ```
 

package/README.md

@@ -78,14 +78,18 @@ claude plugin install claude-nexus@nexus
 
 Claude가 직접 호출하는 도구입니다.
 
-### Core (5개)
+### Core (9개)
 
 | 도구 | 용도 |
 |------|------|
 | `nx_knowledge_read/write` | 프로젝트 지식 관리 (git 추적) |
-| `nx_context` | 현재 세션 상태 조회 |
+| `nx_context` | 현재 세션 상태 조회 (브랜치, 태스크, 결정) |
 | `nx_task_list/add/update/clear` | tasks.json 기반 태스크 관리 |
 | `nx_decision_add` | 아키텍처 결정 기록 |
+| `nx_artifact_write` | 팀 산출물 저장 (브랜치별 격리) |
+| `nx_consult_start` | 상담 세션 시작 (토픽 + 논점 등록) |
+| `nx_consult_status` | 상담 상태 조회 |
+| `nx_consult_decide` | 논점 결정 처리 (consult.json + decisions.json) |
 
 ### Code Intelligence (10개)
 
@@ -140,7 +144,8 @@ Gate 단일 모듈로 동작합니다.
 │   └── {branch}/
 │       ├── tasks.json      ← 태스크 목록
 │       ├── decisions.json  ← 아키텍처 결정 목록
-│       └── reports/        ← 리서치 산출물
+│       ├── consult.json   ← 상담 논점 추적 (상담 중에만 존재)
+│       └── artifacts/      ← 팀 산출물
 └── sync-state.json         ← 마지막 sync 커밋
 ```
 

package/VERSION

@@ -1 +1 @@
-0.10.0
+0.12.0

package/agents/architect.md

@@ -2,6 +2,7 @@
 name: architect
 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]
 tags: [architecture, design, review, technical]

package/agents/director.md

@@ -2,6 +2,7 @@
 name: director
 model: opus
 description: Project direction — analyzes Why/What, owns task lifecycle, decides scope and priorities
+task: "Project direction, scope, priorities"
 maxTurns: 30
 disallowedTools: [Edit, Write, NotebookEdit]
 tags: [direction, planning, task-management]

package/agents/engineer.md

@@ -2,6 +2,7 @@
 name: engineer
 model: sonnet
 description: Implementation — writes code, debugs issues, follows specifications from director and architect
+task: "Code implementation, edits, debugging"
 maxTurns: 25
 disallowedTools: []
 tags: [implementation, coding, debugging]

package/agents/postdoc.md

@@ -2,6 +2,7 @@
 name: postdoc
 model: opus
 description: Research methodology and synthesis — designs investigation approach, evaluates evidence quality, writes synthesis documents
+task: "Research methodology, evidence synthesis"
 maxTurns: 25
 disallowedTools: [Edit, Bash, NotebookEdit]
 tags: [research, synthesis, methodology]
@@ -63,6 +64,9 @@ When researcher submits findings:
 - Ask clarifying questions if findings are ambiguous
 - Escalate to principal if researcher's findings reveal the original question was malformed
 
+## Saving Artifacts
+When writing synthesis documents or other deliverables, use `nx_artifact_write` (filename, content) instead of Write. This ensures the file is saved to the correct branch workspace.
+
 ## What You Do NOT Do
 - Run shell commands or modify the codebase
 - Create or update tasks (advise principal, who owns tasks)

package/agents/principal.md

@@ -2,6 +2,7 @@
 name: principal
 model: opus
 description: Research direction — owns research agenda, task lifecycle, and consensus with postdoc to prevent confirmation bias
+task: "Research direction, agenda, bias prevention"
 maxTurns: 25
 disallowedTools: [Edit, Write, Bash, NotebookEdit]
 tags: [research, direction, task-management]

package/agents/qa.md

@@ -2,6 +2,7 @@
 name: qa
 model: sonnet
 description: Quality assurance — tests, verifies, validates stability and security of implementations
+task: "Testing, verification, security review"
 maxTurns: 20
 disallowedTools: []
 tags: [verification, testing, security, quality]
@@ -74,6 +75,9 @@ When encountering structural issues that are difficult to assess technically:
 - Escalate to architect via SendMessage for technical assessment
 - If the issue is a design flaw (not just a bug), notify both architect and director
 
+## Saving Artifacts
+When writing verification reports or other deliverables to a file, use `nx_artifact_write` (filename, content) instead of Write. This ensures the file is saved to the correct branch workspace.
+
 ## What You Do NOT Do
 - Fix application code yourself — only test code (test files) may be edited
 - Call nx_task_add or nx_task_update directly — report to director, who owns tasks

package/agents/researcher.md

@@ -2,6 +2,7 @@
 name: researcher
 model: sonnet
 description: Independent investigation — conducts web searches, gathers evidence, and reports findings with citations
+task: "Web search, independent investigation"
 maxTurns: 20
 disallowedTools: []
 tags: [research, investigation, web-search, analysis]
@@ -63,6 +64,9 @@ If a research question is ambiguous or contradicts itself:
 - If the question itself seems malformed, flag it to principal via postdoc
 - Do not guess at intent — ask
 
+## Saving Artifacts
+When writing findings reports or other deliverables to a file, use `nx_artifact_write` (filename, content) instead of Write. This ensures the file is saved to the correct branch workspace.
+
 ## What You Do NOT Do
 - Present findings stronger than the evidence supports
 - Omit contradicting evidence because it's inconvenient

package/bridge/mcp-server.cjs

@@ -21045,6 +21045,11 @@ function migrateLegacyBranchDir(branchName) {
 }
 migrateLegacyBranchDir(CURRENT_BRANCH);
 var BRANCH_ROOT = (0, import_path.join)(RUNTIME_ROOT, "branches", sanitizeBranch(CURRENT_BRANCH));
+function getBranchRoot() {
+  const branch = getCurrentBranch();
+  migrateLegacyBranchDir(branch);
+  return (0, import_path.join)(RUNTIME_ROOT, "branches", sanitizeBranch(branch));
+}
 
 // src/mcp/tools/knowledge.ts
 var import_path2 = require("path");
@@ -21139,7 +21144,7 @@ function registerContextTool(server2) {
     {},
     async () => {
       let teamStatus = { activeMode: null };
-      const tasksFile = (0, import_path3.join)(BRANCH_ROOT, "tasks.json");
+      const tasksFile = (0, import_path3.join)(getBranchRoot(), "tasks.json");
       if ((0, import_fs3.existsSync)(tasksFile)) {
         try {
           const data = JSON.parse(await (0, import_promises2.readFile)(tasksFile, "utf-8"));
@@ -21155,9 +21160,19 @@ function registerContextTool(server2) {
         } catch {
         }
       }
+      let decisions = [];
+      const decisionsFile = (0, import_path3.join)(getBranchRoot(), "decisions.json");
+      if ((0, import_fs3.existsSync)(decisionsFile)) {
+        try {
+          const data = JSON.parse(await (0, import_promises2.readFile)(decisionsFile, "utf-8"));
+          decisions = Array.isArray(data.decisions) ? data.decisions : [];
+        } catch {
+        }
+      }
       const result = {
         branch: getCurrentBranch2(),
-        ...teamStatus
+        ...teamStatus,
+        decisions
       };
       return { content: [{ type: "text", text: JSON.stringify(result) }] };
     }
@@ -22047,15 +22062,19 @@ function registerAstTools(server2) {
 var import_fs7 = require("fs");
 var import_promises3 = require("fs/promises");
 var import_path7 = require("path");
-var TASKS_PATH = (0, import_path7.join)(BRANCH_ROOT, "tasks.json");
+function tasksPath() {
+  return (0, import_path7.join)(getBranchRoot(), "tasks.json");
+}
 async function readTasks() {
-  if (!(0, import_fs7.existsSync)(TASKS_PATH)) return null;
-  const raw = await (0, import_promises3.readFile)(TASKS_PATH, "utf-8");
+  const p = tasksPath();
+  if (!(0, import_fs7.existsSync)(p)) return null;
+  const raw = await (0, import_promises3.readFile)(p, "utf-8");
   return JSON.parse(raw);
 }
 async function writeTasks(data) {
-  ensureDir(BRANCH_ROOT);
-  await (0, import_promises3.writeFile)(TASKS_PATH, JSON.stringify(data, null, 2));
+  const root = getBranchRoot();
+  ensureDir(root);
+  await (0, import_promises3.writeFile)((0, import_path7.join)(root, "tasks.json"), JSON.stringify(data, null, 2));
 }
 function computeSummary(tasks) {
   const total = tasks.length;
@@ -22158,11 +22177,11 @@ function registerTaskTools(server2) {
     "Delete .nexus/tasks.json to abort the current plan and release the nonstop block",
     {},
     async () => {
-      if (!(0, import_fs7.existsSync)(TASKS_PATH)) {
+      if (!(0, import_fs7.existsSync)(tasksPath())) {
         return { content: [{ type: "text", text: JSON.stringify({ cleared: false, reason: "tasks.json not found" }) }] };
       }
       try {
-        (0, import_fs7.unlinkSync)(TASKS_PATH);
+        (0, import_fs7.unlinkSync)(tasksPath());
         return { content: [{ type: "text", text: JSON.stringify({ cleared: true }) }] };
       } catch (e) {
         return { content: [{ type: "text", text: JSON.stringify({ cleared: false, reason: String(e) }) }] };
@@ -22175,17 +22194,21 @@ function registerTaskTools(server2) {
 var import_fs8 = require("fs");
 var import_promises4 = require("fs/promises");
 var import_path8 = require("path");
-var DECISIONS_PATH = (0, import_path8.join)(BRANCH_ROOT, "decisions.json");
+function decisionsPath() {
+  return (0, import_path8.join)(getBranchRoot(), "decisions.json");
+}
 async function readDecisions() {
-  if (!(0, import_fs8.existsSync)(DECISIONS_PATH)) {
+  const p = decisionsPath();
+  if (!(0, import_fs8.existsSync)(p)) {
     return { decisions: [] };
   }
-  const raw = await (0, import_promises4.readFile)(DECISIONS_PATH, "utf-8");
+  const raw = await (0, import_promises4.readFile)(p, "utf-8");
   return JSON.parse(raw);
 }
 async function writeDecisions(data) {
-  ensureDir(BRANCH_ROOT);
-  await (0, import_promises4.writeFile)(DECISIONS_PATH, JSON.stringify(data, null, 2));
+  const root = getBranchRoot();
+  ensureDir(root);
+  await (0, import_promises4.writeFile)((0, import_path8.join)(root, "decisions.json"), JSON.stringify(data, null, 2));
 }
 function registerDecisionTools(server2) {
   server2.tool(
@@ -22210,6 +22233,166 @@ function registerDecisionTools(server2) {
   );
 }
 
+// src/mcp/tools/artifact.ts
+var import_promises5 = require("fs/promises");
+var import_path9 = require("path");
+function registerArtifactTools(server2) {
+  server2.tool(
+    "nx_artifact_write",
+    "Write a team artifact (report, synthesis, analysis) to the current branch workspace",
+    {
+      filename: external_exports.string().describe('Filename to write (e.g., "findings.md", "synthesis.md")'),
+      content: external_exports.string().describe("File content to write")
+    },
+    async ({ filename, content }) => {
+      const artifactsDir = (0, import_path9.join)(getBranchRoot(), "artifacts");
+      ensureDir(artifactsDir);
+      const path = (0, import_path9.join)(artifactsDir, filename);
+      await (0, import_promises5.writeFile)(path, content);
+      return { content: [{ type: "text", text: JSON.stringify({ success: true, path }) }] };
+    }
+  );
+}
+
+// src/mcp/tools/consult.ts
+var import_fs9 = require("fs");
+var import_promises6 = require("fs/promises");
+var import_path10 = require("path");
+function consultPath() {
+  return (0, import_path10.join)(getBranchRoot(), "consult.json");
+}
+async function readConsult() {
+  const p = consultPath();
+  if (!(0, import_fs9.existsSync)(p)) return null;
+  const raw = await (0, import_promises6.readFile)(p, "utf-8");
+  return JSON.parse(raw);
+}
+async function writeConsult(data) {
+  const root = getBranchRoot();
+  ensureDir(root);
+  await (0, import_promises6.writeFile)((0, import_path10.join)(root, "consult.json"), JSON.stringify(data, null, 2));
+}
+function decisionsPath2() {
+  return (0, import_path10.join)(getBranchRoot(), "decisions.json");
+}
+async function readDecisions2() {
+  const p = decisionsPath2();
+  if (!(0, import_fs9.existsSync)(p)) return { decisions: [] };
+  const raw = await (0, import_promises6.readFile)(p, "utf-8");
+  return JSON.parse(raw);
+}
+async function writeDecisions2(data) {
+  const root = getBranchRoot();
+  ensureDir(root);
+  await (0, import_promises6.writeFile)((0, import_path10.join)(root, "decisions.json"), JSON.stringify(data, null, 2));
+}
+function registerConsultTools(server2) {
+  server2.tool(
+    "nx_consult_start",
+    "Start a new consultation session with topic and issues to discuss",
+    {
+      topic: external_exports.string().describe("Consultation topic"),
+      issues: external_exports.array(external_exports.string()).describe("List of issue titles to discuss")
+    },
+    async ({ topic, issues }) => {
+      const data = {
+        topic,
+        issues: issues.map((title, i) => ({
+          id: i + 1,
+          title,
+          status: "pending"
+        }))
+      };
+      await writeConsult(data);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ created: true, topic, issueCount: issues.length })
+        }]
+      };
+    }
+  );
+  server2.tool(
+    "nx_consult_status",
+    "Get current consultation status: topic, issues, and their statuses",
+    {},
+    async () => {
+      const data = await readConsult();
+      if (!data) {
+        return { content: [{ type: "text", text: JSON.stringify({ active: false }) }] };
+      }
+      const pending = data.issues.filter((i) => i.status === "pending").length;
+      const discussing = data.issues.filter((i) => i.status === "discussing").length;
+      const decided = data.issues.filter((i) => i.status === "decided").length;
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            active: true,
+            topic: data.topic,
+            issues: data.issues,
+            summary: { total: data.issues.length, pending, discussing, decided }
+          })
+        }]
+      };
+    }
+  );
+  server2.tool(
+    "nx_consult_decide",
+    "Mark a consultation issue as decided and record the decision",
+    {
+      issue_id: external_exports.number().describe("Issue ID to mark as decided"),
+      summary: external_exports.string().describe("Decision summary to record")
+    },
+    async ({ issue_id, summary }) => {
+      const data = await readConsult();
+      if (!data) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: "No active consultation" }) }] };
+      }
+      const issue2 = data.issues.find((i) => i.id === issue_id);
+      if (!issue2) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: `Issue ${issue_id} not found` }) }] };
+      }
+      issue2.status = "decided";
+      const decisions = await readDecisions2();
+      decisions.decisions.push(summary);
+      await writeDecisions2(decisions);
+      const allDecided = data.issues.every((i) => i.status === "decided");
+      if (allDecided) {
+        try {
+          (0, import_fs9.unlinkSync)(consultPath());
+        } catch {
+        }
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              decided: true,
+              issue: issue2.title,
+              allComplete: true,
+              message: "All issues decided. consult.json removed.",
+              decisions: decisions.decisions
+            })
+          }]
+        };
+      }
+      await writeConsult(data);
+      const remaining = data.issues.filter((i) => i.status !== "decided");
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            decided: true,
+            issue: issue2.title,
+            allComplete: false,
+            remaining: remaining.map((i) => ({ id: i.id, title: i.title, status: i.status }))
+          })
+        }]
+      };
+    }
+  );
+}
+
 // src/mcp/server.ts
 var server = new McpServer({
   name: "nx",
@@ -22222,6 +22405,8 @@ registerLspTools(server);
 registerAstTools(server);
 registerTaskTools(server);
 registerDecisionTools(server);
+registerArtifactTools(server);
+registerConsultTools(server);
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);