@moreih29/nexus-core 0.1.0

package/skills/nx-plan/meta.yml

@@ -0,0 +1,7 @@
+name: nx-plan
+description: Structured multi-perspective analysis to decompose issues, align on
+  decisions, and produce an enriched plan before execution. Plan only — does not
+  execute.
+triggers:
+  - plan
+id: nx-plan

package/skills/nx-run/body.md

@@ -0,0 +1,149 @@
+## Role
+
+Execution norm that Lead follows when the user invokes the [run] tag. Composes subagents dynamically based on user direction and drives the full execution pipeline from intake to completion.
+
+## Constraints
+
+- NEVER modify files via Bash (sed, echo >, cat <<EOF, tee, etc.) — always use Edit/Write tools (Gate enforced)
+- NEVER terminate while pending tasks remain (Gate Stop nonstop)
+- NEVER spawn a new branch without checking for main/master first
+- MUST check tasks.json before executing — if absent, write the plan first
+- MUST spawn subagents per-task based on owner field — Do not handle multi-task work as Lead solo when task count ≥ 2 or target files ≥ 2
+- MUST NOT spawn parallel Engineers if their target files overlap — serialize instead
+- MUST call nx_task_close before completing the cycle — archive plan+tasks to history.json
+
+## Guidelines
+
+## Flow
+
+### Step 1: Intake (Lead)
+
+- **User specifies agents/direction** → follow the instruction as given.
+- **[run] only (no direction)** → confirm direction with user before proceeding.
+- User decides scope and composition. Lead fills in what is not specified.
+- **Branch Guard**: if on main/master, create a branch appropriate to the task type before proceeding (prefix: `feat/`, `fix/`, `chore/`, `research/`, etc. — Lead's judgment). Auto-create without user confirmation.
+- Check for `tasks.json`:
+  - **Exists** → read it and proceed to Step 2.
+  - **Absent** → auto-invoke `Skill({ skill: "claude-nexus:nx-plan", args: "auto" })` to generate tasks.json. Do NOT ask — `[run]` implies execution intent. After plan generation, proceed to Step 2.
+- If tasks.json exists, check prior decisions with `nx_plan_status`.
+
+### Step 1.5: TUI Progress
+
+Register tasks for visual progress tracking (Ctrl+T):
+
+- **≤ 10 tasks**: `TaskCreate` per task
+- **> 10 tasks**: group by `plan_issue`, `TaskCreate` per group
+- Use `TaskUpdate` to reflect progress (`in_progress` / `completed`) as execution proceeds
+- **Skip only if**: non-TTY environment (VSCode, headless)
+- **Known issue**: TUI may freeze during auto-compact (#27919) — task data on disk remains correct
+
+### Step 2: Execute
+
+- **Present tasks.json** to the user — show task list with owner, deps, approach summary. Proceed immediately without asking for confirmation.
+- Execute tasks based on `owner` field:
+  - `owner: "lead"` → Lead handles directly
+  - `owner: "engineer"`, `"researcher"`, `"writer"`, etc. → spawn subagent matching the owner role
+  - `owner: "architect"`, `"tester"`, `"reviewer"`, etc. → spawn corresponding HOW/CHECK subagent
+- For each subagent, pass the task's `context`, `approach`, and `acceptance` as the prompt.
+- **Parallel execution**: independent tasks (no overlapping target files, no deps) can be spawned in parallel. Tasks sharing target files must be serialized.
+- **SubagentStop escalation chain**: when a subagent stops with incomplete work:
+  1. **Do/Check failed** → spawn the relevant HOW agent (e.g., Engineer failed → Architect) to diagnose the failure, review the approach, and suggest adjustments.
+  2. **Re-delegate** → apply HOW's adjusted approach and re-delegate to a new Do/Check agent.
+  3. **HOW also failed** → Lead reports the failure to the user with diagnosis details and asks for direction.
+  - Maximum: 1 HOW diagnosis + 1 re-delegation per task. After that, escalate to user.
+  - Relevant HOW mapping: Engineer→Architect, Writer→Strategist, Researcher→Postdoc, Tester→Architect.
+
+### Resume Dispatch Rule
+
+For each task, Lead chooses between fresh spawn and resume based on the `owner`'s `resume_tier`:
+
+1. Lookup `resume_tier` from `agents/{owner}.md` frontmatter (if absent → treat as `ephemeral`).
+2. If `ephemeral` → fresh spawn. Stop.
+3. If `bounded` → check tasks.json history: did the same `owner` previously work on overlapping target files? If yes AND no intervening edits by other agents → resume candidate. Otherwise fresh. Always include "re-read target files before any modification" instruction in the resume prompt.
+4. If `persistent` → resume by default if the same agent worked earlier in this run. Cross-task reuse allowed.
+5. Before issuing SendMessage for any resume, verify `.nexus/state/runtime.json` has `teams_enabled: true`. Otherwise fall back to fresh spawn silently — do NOT throw an error.
+
+### Step 3: Verify (Lead + Check subagents)
+
+**Lead**: confirm build + E2E pass/fail.
+
+**Tester — acceptance criteria verification**:
+- Tester reads each completed task's `acceptance` field from tasks.json
+- Verifies each criterion with PASS/FAIL judgment
+- All criteria must pass for the task to be considered done
+- If any criterion fails → Step 2 rework (reopen task)
+- Tester spawn conditions (any one triggers):
+  - tasks.json contains at least 1 task with an `acceptance` field
+  - 3 or more files changed
+  - Existing test files modified
+  - External API/DB access code changed
+  - Failure history for this area exists in memory
+
+**Reviewer — writer deliverable verification**:
+- Whenever Writer produced a deliverable in Step 2, Reviewer MUST verify it
+- Writer → Reviewer is a mandatory pairing, not optional
+- Reviewer checks: factual accuracy, source consistency, grammar/format
+
+- If issues found: code problems → Step 2 rework; design problems → re-run nx-plan before re-executing.
+
+### Step 4: Complete
+
+Execute in order:
+
+1. **nx-sync**: invoke `Skill({ skill: "claude-nexus:nx-sync" })` if code changes were made in this cycle. Best effort — failure does not block cycle completion.
+2. **nx_task_close**: call to archive plan+tasks to history.json. This updates `.nexus/history.json`.
+3. **git commit**: stage and commit source changes, build artifacts (`bridge/`, `scripts/`), `.nexus/history.json`, and any modified `.nexus/memory/` or `.nexus/context/`. Use explicit `git add` with paths (not `git add -A`) and a HEREDOC commit message with `Co-Authored-By`. This ensures the cycle's history archive lands in the same commit as the code changes, giving a 1:1 cycle-commit mapping.
+4. **Report**: summarize to user — changed files, key decisions applied, and suggested next steps. Merge/push is the user's decision and outside this skill's scope.
+
+---
+
+## Reference Framework
+
+| Phase | Owner | Content |
+|-------|-------|---------|
+| 1. Intake | Lead | Clarify intent, confirm direction, Branch Guard, check tasks.json / invoke nx-plan if absent |
+| 2. Execute | Do subagents | Spawn per-task by owner, delegation criteria, parallel where safe |
+| 3. Verify | Lead + Check subagent | Build check, quality verification |
+| 4. Complete | Lead | nx-sync, nx_task_close, git commit, report |
+
+---
+
+## Structured Delegation
+
+When Lead delegates tasks to subagents, structure the prompt in this format:
+
+```
+TASK: {specific deliverable}
+
+CONTEXT:
+- Current state: {relevant code/doc locations}
+- Dependencies: {results from prior tasks}
+- Prior decisions: {relevant decisions}
+- Target files: {file path list}
+
+CONSTRAINTS:
+- {constraint 1}
+- {constraint 2}
+
+ACCEPTANCE:
+- {completion criterion 1}
+- {completion criterion 2}
+```
+
+---
+
+## Key Principles
+
+1. **Lead = interpret user direction + coordinate + own tasks**
+2. **User decides scope and composition**
+3. **tasks.json is the single source of state** — produced by nx-plan, read at Step 1, updated as tasks complete
+4. **Do subagents = execute per owner** — Lead spawns one subagent per task based on the `owner` field. Engineers focus on code changes. Doc updates are done in bulk by Writer in Step 4. Researcher records to reference/ immediately.
+5. **Check subagents = verify** — Lead's discretion + 4 conditions
+6. **SubagentStop escalation** — when a subagent stops with incomplete work, escalate through HOW diagnosis → re-delegation → user report. Max 1 cycle per task.
+7. **Gate Stop nonstop** — cannot terminate while pending tasks exist
+8. **Plan first** — if tasks.json is absent, nx-plan must run before Step 2
+9. **No file modification via Bash** — sed, echo >, cat <<EOF, tee, and similar Bash-based file edits are prohibited. Always use Edit/Write tools (Gate enforced)
+## State Management
+
+`.nexus/state/tasks.json` — produced by nx-plan, managed via `nx_task_add`/`nx_task_update`. Gate Stop enforcement.
+On cycle end, archive plan+tasks to `.nexus/history.json` via `nx_task_close`.

package/skills/nx-run/meta.yml

@@ -0,0 +1,5 @@
+name: nx-run
+description: Execution — user-directed agent composition.
+triggers:
+  - run
+id: nx-run

package/skills/nx-setup/body.md

@@ -0,0 +1,196 @@
+## Role
+
+Interactive project setup wizard — configure Nexus for a new project with minimal token cost. Every step is a concrete choice via `AskUserQuestion`, with no open-ended exploration.
+
+## Constraints
+
+- NEVER accept free-text input — every step must use `AskUserQuestion` with explicit options.
+- NEVER skip the "Skip" option — all steps are optional.
+- NEVER modify files outside the selected scope without explicit user confirmation.
+- NEVER overwrite an existing `statusLine` field in settings.json without explicit user confirmation.
+
+## Guidelines
+
+## Trigger
+- Direct invocation: `/claude-nexus:nx-setup`
+
+---
+
+## Steps
+
+### Step 1: Scope Selection
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Where should the Nexus configuration be applied?",
+    header: "Scope",
+    multiSelect: false,
+    options: [
+      { label: "User (Global)", description: "Apply to all projects (~/.claude/CLAUDE.md, ~/.claude/settings.json statusline)" },
+      { label: "Project", description: "Apply to this project only (CLAUDE.md, .claude/settings.local.json)" }
+    ]
+  }]
+})
+```
+
+All file write paths for subsequent steps are determined by this selection:
+- User: `~/.claude/CLAUDE.md`, `~/.claude/settings.json` (statusline wrapper)
+- Project: `./CLAUDE.md`, `./.claude/settings.local.json`
+
+### Step 2: Statusline
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Enable the Nexus statusline? (model, branch, context usage, rate limits)",
+    header: "Statusline",
+    multiSelect: false,
+    options: [
+      { label: "Enable (Recommended)", description: "2 lines: model+branch+git, context+usage meters" },
+      { label: "Skip", description: "Skip statusline configuration" }
+    ]
+  }]
+})
+```
+
+**Create wrapper script** (for Enable, run via Bash tool):
+```bash
+mkdir -p ~/.claude/hooks
+cat > ~/.claude/hooks/nexus-statusline.sh << 'EOF'
+#!/bin/bash
+SCRIPT=$(ls -1d "$HOME/.claude/plugins/cache/nexus/claude-nexus"/*/scripts/statusline.cjs 2>/dev/null | sort -V | tail -1)
+[ -n "$SCRIPT" ] && exec node "$SCRIPT"
+EOF
+chmod +x ~/.claude/hooks/nexus-statusline.sh
+```
+
+**On selection, depending on scope:**
+
+**(1) User scope:**
+- Create wrapper script (run step above)
+- If `statusLine` field is **absent** in `~/.claude/settings.json`: add statusLine setting directly:
+  ```json
+  { "statusLine": { "type": "command", "command": "bash $HOME/.claude/hooks/nexus-statusline.sh" } }
+  ```
+- If `statusLine` field **already exists** in `~/.claude/settings.json`: create wrapper only, do not modify settings.json — ask user to confirm replacement (see "Statusline coexistence handling" below)
+
+**(2) Project scope:**
+- Create wrapper script (run step above)
+- If `statusLine` field is **absent** in `.claude/settings.local.json`: add statusLine setting directly:
+  ```json
+  { "statusLine": { "type": "command", "command": "bash $HOME/.claude/hooks/nexus-statusline.sh" } }
+  ```
+- If `statusLine` field **already exists** in `.claude/settings.local.json`: create wrapper only, do not modify settings.local.json — ask user to confirm replacement (see "Statusline coexistence handling" below)
+**(3) Skip:**
+- Do not create wrapper or modify settings.json.
+
+**Statusline coexistence handling:**
+
+Run only if settings.json modification was deferred above (i.e., wrapper was created but existing statusLine was detected).
+If statusLine settings were already applied above, skip this sub-step.
+
+Specifically, treat an existing statusline setting as detected if any of the following are true:
+- `~/.claude/hooks/statusline.sh` file exists
+- Or the scope-appropriate settings.json (`~/.claude/settings.json` or `.claude/settings.local.json`) already has a `statusLine` field
+
+If detected:
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "An existing statusline configuration was detected. Replace it with the Nexus statusline?",
+    header: "Statusline",
+    multiSelect: false,
+    options: [
+      { label: "Replace (Recommended)", description: "Replace with Nexus statusline (wrapper script configuration)" },
+      { label: "Keep Existing", description: "Keep existing statusline. Nexus wrapper is created but settings.json is not modified." }
+    ]
+  }]
+})
+```
+
+- "Replace (Recommended)": replace the `statusLine` in the scope-appropriate settings.json with the Nexus wrapper (wrapper script already created above)
+- "Keep Existing": keep the existing `statusLine` in settings.json (wrapper script already created above — user can switch manually later)
+
+If no existing statusline configuration is detected, skip this sub-step.
+
+### Step 3: Recommended Plugin
+
+Check if `context7@claude-plugins-official` is in `enabledPlugins` (global or project settings.json).
+
+**Already installed:**
+
+Notify and skip:
+```
+"Recommended plugin already installed: context7 ✓"
+```
+
+**Not installed:**
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Install the context7 plugin? It enables agents to look up library docs in real time.",
+    header: "Plugin",
+    multiSelect: false,
+    options: [
+      { label: "Install (Recommended)", description: "context7 — real-time library documentation lookup (Upstash Context7)" },
+      { label: "Skip", description: "Skip recommended plugin installation" }
+    ]
+  }]
+})
+```
+
+**If "Install":**
+Add to `enabledPlugins` in the scope-appropriate settings.json (`~/.claude/settings.json` or `.claude/settings.local.json`):
+```json
+{
+  "context7@claude-plugins-official": true
+}
+```
+Claude Code will automatically install the plugin at the start of the next session.
+
+**If "Skip":** proceed to the next step.
+
+Note: Once added to `enabledPlugins`, Claude Code automatically installs the plugin at the start of the next session.
+
+### Step 4: Knowledge Init
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Auto-generate project core knowledge?",
+    header: "Init",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Analyze existing docs (README, CLAUDE.md, etc.) to generate knowledge files in .nexus/memory/ and .nexus/context/" },
+      { label: "Skip", description: "Run manually later with /claude-nexus:nx-init" }
+    ]
+  }]
+})
+```
+
+If "Yes": invoke `Skill({ skill: "claude-nexus:nx-init" })`.
+If "Skip": proceed to next step.
+
+### Step 5: Complete
+
+Output a setup completion message:
+- Summary of applied settings
+- Brief introduction to available skills/agents
+- "To get started, describe a task, or use [plan] for planning, [run] for execution, [rule] for saving rules"
+
+---
+
+## Key Principles
+
+1. **Every step uses AskUserQuestion** — no free-text input
+2. **Minimize tokens** — limit each step to concrete choices to prevent unnecessary exploration
+3. **Always provide a Skip option** — nothing is forced
+4. **Extensible structure** — includes recommended plugin step, expandable to additional categories in the future
+
+## State Management
+
+Setup operates via sequential AskUserQuestion calls with no state file.
+Configuration results are written to the scope-appropriate settings file at each step.

package/skills/nx-setup/meta.yml

@@ -0,0 +1,4 @@
+name: nx-setup
+description: Interactive project setup wizard for Nexus configuration.
+manual_only: true
+id: nx-setup

package/skills/nx-sync/body.md

@@ -0,0 +1,81 @@
+## Role
+
+Scans the current project state and synchronizes .nexus/context/ design documents. Uses git diff to identify code changes, then updates abstract design documents (principles, philosophy, development stack, architectural decisions) that cannot be inferred from code alone.
+
+## Constraints
+
+- NEVER delete existing context files — only update or add
+- NEVER modify source code — this skill updates documentation only
+- NEVER guess information that cannot be confirmed from sources — mark as "needs verification" instead
+- MUST preserve existing content structure — update sections, don't rewrite entire files unnecessarily
+- NEVER use deprecated MCP knowledge tools — use Read and Write native tools only
+
+## Guidelines
+
+## Trigger
+
+- `[sync]` — synchronize .nexus/context/ with current project state
+
+## Process
+
+### Step 1: Gather Sources
+
+Collect information from all available sources:
+
+1. **git diff** — run `git diff --name-only HEAD~10..HEAD` (or use recent commits to identify changed files)
+   - Identifies which source files changed
+   - Primary signal for determining which context documents may be stale
+2. **Conversation context** — if available in current session
+   - Design decisions discussed but not yet reflected in context documents
+   - Supplementary source for all updates
+
+### Step 2: Read Current Context
+
+Read all files in `.nexus/context/` using the Read tool:
+
+- List files: `ls .nexus/context/`
+- Read each file to understand current documented state
+- Compare against detected changes to identify gaps or stale content
+
+Only update files where a concrete change is detected. If no staleness is found, report "already current" and skip.
+
+### Step 3: Execute Updates
+
+Spawn Writer agent to update affected context documents:
+
+```
+Agent({ subagent_type: "claude-nexus:writer", name: "writer-sync-context",
+  prompt: "Update .nexus/context/ documents based on the following changes. Read current files with the Read tool, then write updates with the Write tool. Changes: {change_manifest}" })
+```
+
+The Writer agent:
+- Reads each relevant context file with the Read tool
+- Applies targeted updates — changes only the sections that are stale
+- Writes the updated file back with the Write tool
+- Does not rewrite files that are already accurate
+
+### Step 4: Report
+
+Report to user:
+- Which context files were scanned
+- Which files were updated and what changed
+- Which files were already up to date
+- Any items marked "needs verification"
+
+## Key Principles
+
+1. **Targeted updates over full rewrites** — only change sections that are actually stale
+2. **Evidence-based** — every update must trace to a source (git diff or conversation)
+3. **Preserve structure** — maintain existing document organization, headings, and format
+4. **No speculation** — if a change's impact on context docs is unclear, flag it rather than guess
+
+## What .nexus/context/ Contains
+
+Context documents capture abstract knowledge that cannot be read directly from source code:
+
+- Design principles and philosophy
+- Architectural decisions and their rationale
+- Development stack choices and constraints
+- Project conventions and standards
+
+These documents are updated when code changes reflect a shift in principles, a new architectural decision is made, or the development stack evolves. They are not updated for routine code additions that do not change the underlying design.

package/skills/nx-sync/meta.yml

@@ -0,0 +1,6 @@
+name: nx-sync
+description: Context knowledge synchronization — scans project state and updates
+  .nexus/context/ design documents
+triggers:
+  - sync
+id: nx-sync

package/vocabulary/capabilities.yml

@@ -0,0 +1,32 @@
+# Capabilities restrict an agent's access to harness-provided tools.
+# NOT constraints on nexus-core's own scripts/ or tooling.
+
+capabilities:
+  - id: no_file_edit
+    description: "Agent cannot create or modify files in the user's workspace"
+    harness_mapping:
+      claude_code:
+        - Edit
+        - Write
+        - NotebookEdit
+      opencode:
+        - edit
+        - write
+        - patch
+        - multiedit
+
+  - id: no_task_create
+    description: "Agent cannot create new tasks in the Nexus task pipeline"
+    harness_mapping:
+      claude_code:
+        - mcp__plugin_claude-nexus_nx__nx_task_add
+      opencode:
+        - nx_task_add
+
+  - id: no_task_update
+    description: "Agent cannot update the state of existing Nexus tasks"
+    harness_mapping:
+      claude_code:
+        - mcp__plugin_claude-nexus_nx__nx_task_update
+      opencode:
+        - nx_task_update

package/vocabulary/categories.yml

@@ -0,0 +1,11 @@
+# Agent role categories. Determined by reasoning surface vs artifact surface.
+
+categories:
+  - id: how
+    description: "분석·자문. 깊은 맥락 유지가 핵심 자산. architect, designer, postdoc, strategist."
+
+  - id: do
+    description: "실행. 산출물(artifact) 단위로 작업하고 종료. engineer, writer, researcher."
+
+  - id: check
+    description: "검증. 항상 fresh한 관점에서 독립적으로 검사. tester, reviewer."

package/vocabulary/resume-tiers.yml

@@ -0,0 +1,11 @@
+# Agent session resumability tiers. Reflects what kind of surface the agent produces.
+
+resume_tiers:
+  - id: persistent
+    description: "세션 전체를 지속한다. HOW 카테고리 에이전트와 researcher. 맥락 누적이 핵심 자산."
+
+  - id: bounded
+    description: "artifact 단위로 지속한다. engineer, writer. 특정 산출물 완성 후 종료."
+
+  - id: ephemeral
+    description: "항상 새로 시작한다. tester, reviewer. 이전 맥락 없이 독립 검증해야 하기 때문."

package/vocabulary/tags.yml

@@ -0,0 +1,51 @@
+# Canonical definition of all Nexus tag triggers.
+# Slash command triggers are NOT stored here — each harness resolves them
+# in its own command namespace.
+# variants field is valid for both skill and inline_action types.
+
+tags:
+  # skill tags (3 entries, 4 triggers)
+  - id: plan
+    trigger: "[plan]"
+    type: skill
+    skill: nx-plan
+    description: "Activates nx-plan skill for structured multi-perspective analysis and decision recording"
+    variants: ["auto"]   # [plan:auto] for autonomous mode
+
+  - id: run
+    trigger: "[run]"
+    type: skill
+    skill: nx-run
+    description: "Activates nx-run skill for task execution with subagent composition"
+
+  - id: sync
+    trigger: "[sync]"
+    type: skill
+    skill: nx-sync
+    description: "Activates nx-sync skill for .nexus/context/ knowledge synchronization"
+
+  # inline action tags (4 entries, 5 triggers)
+  - id: d
+    trigger: "[d]"
+    type: inline_action
+    handler: nx_plan_decide
+    description: "Records a decision during an active plan session"
+
+  - id: m
+    trigger: "[m]"
+    type: inline_action
+    handler: memory_store
+    description: "Stores a lesson or reference to .nexus/memory/"
+
+  - id: m-gc
+    trigger: "[m:gc]"
+    type: inline_action
+    handler: memory_gc
+    description: "Garbage-collects .nexus/memory/ by merging or removing stale entries"
+
+  - id: rule
+    trigger: "[rule]"
+    type: inline_action
+    handler: rule_store
+    description: "Stores a project rule to .nexus/rules/. [rule:*] supports tag parameter."
+    variants: ["*"]   # [rule:any-tag] for parameterized variants