@moreih29/nexus-core 0.15.2 → 0.16.1

package/dist/codex/dist/hooks/session-init.js

@@ -0,0 +1,37 @@
+// assets/hooks/session-init/handler.ts
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, basename } from "node:path";
+var handler = async (input) => {
+  if (input.hook_event_name !== "SessionStart")
+    return;
+  const safeSid = basename(input.session_id);
+  if (!safeSid || safeSid.startsWith(".") || safeSid.includes("/")) {
+    process.stderr.write(`[session-init] invalid session_id: ${input.session_id}
+`);
+    return;
+  }
+  const sessionDir = join(input.cwd, ".nexus/state", safeSid);
+  mkdirSync(sessionDir, { recursive: true });
+  writeFileSync(join(sessionDir, "agent-tracker.json"), "[]");
+  writeFileSync(join(sessionDir, "tool-log.jsonl"), "");
+};
+var handler_default = handler;
+
+// ../../../../../tmp/nexus-hook-entry-session-init-1776672660208/session-init-entry.ts
+import { readFileSync } from "node:fs";
+async function main() {
+  let raw = "";
+  try {
+    raw = readFileSync(0, "utf-8");
+  } catch {}
+  const input = raw ? JSON.parse(raw) : {};
+  const result = await handler_default(input);
+  if (result != null && result !== undefined) {
+    process.stdout.write(JSON.stringify(result));
+  }
+}
+main().then(() => process.exit(0), (err) => {
+  process.stderr.write(String(err?.stack ?? err) + `
+`);
+  process.exit(1);
+});

package/dist/codex/hooks/hooks.json

@@ -0,0 +1,28 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/hooks/session-init.js",
+        "timeout": 10
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/hooks/prompt-router.js",
+        "timeout": 10
+      }
+    ],
+    "SubagentStop": [
+      {
+        "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/hooks/agent-finalize.js",
+        "timeout": 10
+      }
+    ],
+    "SubagentStart": [
+      {
+        "command": "node ${CLAUDE_PLUGIN_ROOT}/dist/hooks/agent-bootstrap.js",
+        "timeout": 10
+      }
+    ]
+  }
+}

package/dist/codex/install/AGENTS.fragment.md

@@ -0,0 +1,60 @@
+<!-- nexus-core:lead:start -->
+# lead
+
+## 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 |
+
+<!-- nexus-core:lead:end -->

package/dist/codex/install/config.fragment.toml

@@ -0,0 +1,5 @@
+# Auto-generated by build-agents.ts — do not edit
+# Merge this fragment into your codex config.toml
+
+[mcp_servers.nx]
+command = "nexus-mcp"

package/dist/codex/install/install.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# Codex plugin installer — block-marker merge pattern.
+# nexus-core Model 2: wrapper owns integration seams.
+# Merges config.fragment.toml into ~/.codex/config.toml,
+# copies native agent TOMLs to ~/.codex/agents/,
+# and merges AGENTS.fragment.md into ~/.codex/AGENTS.md.
+set -euo pipefail
+
+PLUGIN_NAME="${PLUGIN_NAME:-codex-nexus}"
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+mkdir -p "$CODEX_HOME" "$CODEX_HOME/agents" "$CODEX_HOME/plugins"
+
+# 1. config.toml — block-marker merge
+MARKER_BEGIN="# BEGIN ${PLUGIN_NAME}"
+MARKER_END="# END ${PLUGIN_NAME}"
+CONFIG="$CODEX_HOME/config.toml"
+CONFIG_FRAGMENT="$SCRIPT_DIR/config.fragment.toml"
+
+touch "$CONFIG"
+if grep -q "${MARKER_BEGIN}" "$CONFIG" 2>/dev/null; then
+  sed -i.bak "/${MARKER_BEGIN}/,/${MARKER_END}/d" "$CONFIG"
+fi
+{
+  echo ""
+  echo "${MARKER_BEGIN}"
+  cat "$CONFIG_FRAGMENT"
+  echo "${MARKER_END}"
+} >> "$CONFIG"
+
+# 2. native agent TOMLs
+cp "$REPO_ROOT"/agents/*.toml "$CODEX_HOME/agents/" 2>/dev/null || true
+
+# 3. plugin body → ~/.codex/plugins/<name>/
+PLUGIN_DEST="$CODEX_HOME/plugins/${PLUGIN_NAME}"
+rm -rf "$PLUGIN_DEST"
+mkdir -p "$PLUGIN_DEST"
+cp -R "$REPO_ROOT"/plugin/. "$PLUGIN_DEST/"
+
+# 4. AGENTS.md — block-marker merge
+AGENTS_TARGET="$CODEX_HOME/AGENTS.md"
+AGENTS_FRAGMENT="$SCRIPT_DIR/AGENTS.fragment.md"
+FRAG_BEGIN="<!-- nexus-core:lead:start -->"
+FRAG_END="<!-- nexus-core:lead:end -->"
+
+if [ -f "$AGENTS_FRAGMENT" ]; then
+  touch "$AGENTS_TARGET"
+  if grep -q "${FRAG_BEGIN}" "$AGENTS_TARGET" 2>/dev/null; then
+    awk -v begin="${FRAG_BEGIN}" -v end="${FRAG_END}" '
+      $0 ~ begin { skip=1; next }
+      $0 ~ end { skip=0; next }
+      !skip { print }
+    ' "$AGENTS_TARGET" > "$AGENTS_TARGET.tmp" && mv "$AGENTS_TARGET.tmp" "$AGENTS_TARGET"
+  fi
+  cat "$AGENTS_FRAGMENT" >> "$AGENTS_TARGET"
+fi
+
+echo "Installed ${PLUGIN_NAME} → $CODEX_HOME"

package/dist/codex/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "codex-nexus",
+  "version": "0.13.0",
+  "description": "Nexus agent suite for Codex CLI",
+  "private": true,
+  "scripts": {
+    "sync": "bunx @moreih29/nexus-core sync --harness=codex --target=./",
+    "sync:dry": "bunx @moreih29/nexus-core sync --harness=codex --target=./ --dry-run",
+    "build": "bun run sync",
+    "validate": "bunx @moreih29/nexus-core validate",
+    "list": "bunx @moreih29/nexus-core list",
+    "install-plugin": "bash install/install.sh"
+  },
+  "devDependencies": {
+    "@moreih29/nexus-core": "^0.14.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/dist/codex/plugin/.codex-plugin/plugin.json

@@ -0,0 +1,57 @@
+{
+  "name": "codex-nexus",
+  "version": "0.13.0",
+  "description": "Nexus agent suite for Codex",
+  "agents": [
+    {
+      "id": "architect",
+      "config": "agents/architect.toml",
+      "prompt": "prompts/architect.md"
+    },
+    {
+      "id": "designer",
+      "config": "agents/designer.toml",
+      "prompt": "prompts/designer.md"
+    },
+    {
+      "id": "engineer",
+      "config": "agents/engineer.toml",
+      "prompt": "prompts/engineer.md"
+    },
+    {
+      "id": "lead",
+      "config": "agents/lead.toml",
+      "prompt": "prompts/lead.md"
+    },
+    {
+      "id": "postdoc",
+      "config": "agents/postdoc.toml",
+      "prompt": "prompts/postdoc.md"
+    },
+    {
+      "id": "researcher",
+      "config": "agents/researcher.toml",
+      "prompt": "prompts/researcher.md"
+    },
+    {
+      "id": "reviewer",
+      "config": "agents/reviewer.toml",
+      "prompt": "prompts/reviewer.md"
+    },
+    {
+      "id": "strategist",
+      "config": "agents/strategist.toml",
+      "prompt": "prompts/strategist.md"
+    },
+    {
+      "id": "tester",
+      "config": "agents/tester.toml",
+      "prompt": "prompts/tester.md"
+    },
+    {
+      "id": "writer",
+      "config": "agents/writer.toml",
+      "prompt": "prompts/writer.md"
+    }
+  ]
+}

package/dist/codex/plugin/skills/nx-init/SKILL.md

@@ -0,0 +1,189 @@
+---
+description: "Project onboarding — scan, mission, essentials, context generation"
+---
+## Role
+
+Scans the project and builds Nexus knowledge in the flat .nexus/ structure. On first run, performs a 5-step full onboarding sequence.
+
+## Constraints
+
+- NEVER modify source code. Slimming down the instruction file beyond the project section is not this skill's responsibility.
+- NEVER infer or guess information that cannot be confirmed from code — do not write it to context/.
+- NEVER store secrets (API keys, credentials, etc.) in knowledge files.
+- NEVER overwrite existing files without `--reset`. On resume, preserve existing files intact.
+- Project section in the instruction file MUST go through user confirmation before writing.
+- NEVER reference or create identity/, codebase/, reference/, or core/ paths.
+- Essentials section MUST NOT exceed 10 lines. If more items are needed, move lower-priority ones to .nexus/context/.
+
+## Guidelines
+
+## Trigger
+
+- Manual trigger — full onboarding (or resume). See harness docs: slash_command_display.
+- Manual trigger with `--reset` flag — back up existing `.nexus/` knowledge and re-onboard. See harness docs: slash_command_display.
+- Manual trigger with `--reset --cleanup` flags — show backup list + selective deletion. See harness docs: slash_command_display.
+
+---
+
+## Modes
+
+### First Run (no `.nexus/` flat structure)
+
+Automatically runs the 5-step full onboarding.
+
+Detection: `.nexus/context/`, `.nexus/memory/`, `.nexus/state/`, `.nexus/rules/` do not exist.
+
+### Resume (`.nexus/` partially exists)
+
+Check existing state and resume from the first incomplete step.
+
+### Reset (`--reset`)
+
+Back up existing `.nexus/` knowledge directories to `.nexus/bak.{timestamp}/`, then enter First Run.
+
+### Cleanup (`--reset --cleanup`)
+
+Show backup directory list, let user select backups to delete.
+
+---
+
+## Process
+
+### Phase 0: Mode Detection
+
+```
+IF --reset --cleanup flag:
+  Show list of .nexus/bak.*/ directories
+  Prompt user with options via `request_user_input({ prompt: "Select a backup to delete (or cancel)", options: [<backup list...>, {label: Cancel, description: "Exit without changes"}] })`.
+  Delete selected backup and exit
+
+ELSE IF --reset flag:
+  Move .nexus/{memory,context,state,rules}/ → .nexus/bak.{timestamp}/
+  Inform: "Existing knowledge has been backed up to .nexus/bak.{timestamp}/. Starting re-onboarding."
+  → Enter First Run
+
+ELSE IF .nexus/context/ exists:
+  → Enter Resume (check existing steps and resume)
+
+ELSE:
+  → Enter First Run (from Step 1)
+```
+
+---
+
+## Steps
+
+### Step 1: Project Scan
+
+Auto-detect code structure and tech stack. Create the flat `.nexus/` directory structure if it does not exist.
+
+Create directories (using shell command execution):
+- `.nexus/memory/`
+- `.nexus/context/`
+- `.nexus/state/`
+- `.nexus/rules/`
+
+Collected items:
+- **Directory structure**: top-level layout, major modules/packages
+- **Tech stack**: language, framework, runtime (package.json, Cargo.toml, pyproject.toml, go.mod, build.gradle, etc.)
+- **Build/test system**: scripts, CI configuration
+- **Existing docs**: CLAUDE.md, README.md, docs/, .cursorrules, etc.
+- **git context**: recent commits, branch structure, contributors
+
+Output: scan summary (language, framework, structure overview)
+
+For large projects (10+ top-level directories or 100+ files), consider spawning an Explore subagent for parallel scanning to reduce Lead context usage.
+
+### Step 2: Mission + Essentials (Interactive)
+
+Using the Step 1 scan results, draft a Mission statement (1–2 lines) and an Essentials list, then present both to the user for confirmation in a single pass.
+
+#### Essentials Guidelines
+
+Essentials are agent-critical facts — things an agent would get wrong if it didn't know them. Apply this judgment criterion: **"Would an agent produce wrong results without knowing this?"** Yes → Essentials. No → .nexus/context/.
+
+Draft from these five categories (include only what applies to this project):
+
+- **Tech stack** — runtime, language, package manager, core framework. Flag non-default tools (e.g. bun instead of npm, deno instead of node).
+- **Workflow** — build, test, deploy commands. Must-follow procedures such as required lint or type-check steps before committing.
+- **Constraints** — forbidden tools, patterns, or approaches. Directories or files that must not be modified.
+- **Domain** — target audience, required terminology or tone, compliance or regulatory constraints, methodology for research projects.
+- **Conventions** — naming, structure, or style that deviate from general defaults. Project-specific patterns an agent would not infer.
+
+Do not include items that are standard defaults for the detected tech stack. Do not exceed 10 lines total in the Essentials section.
+
+#### Draft Presentation
+
+Present the full draft to the user in this format:
+
+```
+The following will be added to the instruction file (see harness docs: instruction_file) (existing content will not be changed):
+
+<!-- PROJECT:START -->
+## {project-name}
+
+{mission 1-2 lines}
+
+### Essentials
+- {auto-detected item}
+- {auto-detected item}
+<!-- PROJECT:END -->
+
+Any changes?
+```
+
+Wait for the user to confirm or provide edits. Apply all changes in one pass — do not ask about Mission and Essentials separately.
+
+After confirmation, write the section into the instruction file inside markers using the harness's file-editing primitive. If the instruction file already contains `<!-- PROJECT:START -->` markers, replace the content between them. If the instruction file does not exist, create it with the markers.
+
+### Step 3: Context Knowledge Auto-Generation
+
+Analyze Step 1 scan results to generate context knowledge documents in `.nexus/context/`.
+
+Principles:
+- File names and content are decided freely based on project characteristics. No fixed templates.
+- Existing docs are information sources only — do not replicate their structure verbatim.
+- Do not guess content that cannot be confirmed from code.
+- Typically 1-3 files are sufficient. More files are not better.
+- **Generate abstract-level content only** — design patterns, architecture direction, module relationships, conventions. Do NOT include code-level details such as file listings, function signatures, or import maps. Those can be read directly from code.
+
+Generation targets (select and name based on what the project actually needs):
+- Development stack (languages, frameworks, runtimes, key dependencies, build/test/deploy workflow)
+- Design and architecture (module relationships, data flow, core entry points, conventions)
+- Implementation specifics (pipeline details, configuration patterns, file structure conventions, tool restrictions — anything too specific for the instruction file but not readable from code alone)
+
+Use the harness's file-creation primitive to create files at `.nexus/context/{chosen-name}.md`.
+
+For large projects, spawn Writer subagents per topic to generate context knowledge in parallel. Lead coordinates and reviews outputs.
+
+On completion: "context knowledge N files generated"
+
+### Step 4: Rules Initial Setup (Optional)
+
+Check whether team custom rules are needed.
+
+```
+request_user_input({ prompt: "Do you want to set up development rules now?", options: [{label: "Set up", description: "Coding conventions, test policy, commit rules, etc."}, {label: Skip, description: "Can be added later via [rule] tag"}] })
+```
+
+If "Set up": present a draft based on scan results → user confirms → save via the harness's file-creation primitive to `.nexus/rules/{topic}.md`.
+
+If "Skip": inform and proceed to Step 5.
+
+### Step 5: Completion Summary
+
+Output a summary of the onboarding results.
+
+```
+## Nexus Initialization Complete
+
+### Generated Files
+- instruction file: project section — mission and essentials (<!-- PROJECT:START/END -->)
+- .nexus/context/: {list of generated files}
+- .nexus/rules/: {generated files or "none (skipped)"}
+
+### Next Steps
+- [plan] — research, analyze, and plan before execution
+- [run] — execute from a plan
+- Manual re-run trigger with `--reset` flag — re-run onboarding (existing knowledge will be backed up). See harness docs: slash_command_display.
+```