@moreih29/nexus-core 0.17.0 → 0.18.2

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

@@ -1,353 +0,0 @@
----
-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
----
-## Role
-
-Facilitate structured multi-perspective analysis using subagents to decompose issues, deliberate on options, and align on decisions. Lead acts as synthesizer AND active participant — orchestrates subagent research/analysis AND contributes its own position. Does not execute — planning only. Transition to execution is the user's decision.
-
-## Constraints
-
-- NEVER execute — this skill is planning only; transition to execution is the user's decision
-- NEVER call `nx_plan_start` before research is complete (research_summary is required)
-- NEVER present multiple issues at once — one issue at a time only
-- NEVER ask groundless questions — always research code/knowledge/decisions first
-- NEVER use the harness's team creation primitive. Inter-agent messaging for resume is permitted ONLY for resuming completed subagents whose `resume_tier` is `persistent` or `bounded`, and ONLY within the constraints of the Resume Policy section below. Direct inter-agent communication to running teammates remains forbidden in plan sessions.
-- MUST record all decisions with `[d]` tag so they are not scattered across turns
-- MUST call `nx_plan_decide` when recording `[d]`
-- MUST check for existing plan.json before starting a new session
-- `[d]` without an active plan.json is BLOCKED — "[d]는 plan 세션 안에서만 유효합니다."
-- MUST present a comparison table before asking for a decision — never present options as prose only. Format:
-
-```
-| | A: {title} | B: {title} |
-|---|---|---|
-| Pros | ... | ... |
-| Cons | ... | ... |
-| Pick | | **(Recommended)** |
-```
-
-## Guidelines
-
-## Trigger
-
-- Explicit tag: `[plan]` — continue existing session if plan.json exists, otherwise start new
-- Additional analysis needed mid-session: spawn HOW subagents independently via the harness's subagent spawn primitive
-- Continuing conversation without a tag → continue existing session
-
----
-
-## Auto Mode (`[plan:auto]`)
-
-When triggered with `[plan:auto]` or invoked via `$nx-plan`, run the full planning process **without user interaction**:
-
-1. **Research** — spawn researcher+Explore subagents (same as interactive)
-2. **Issue derivation** — Lead identifies issues from research
-3. **Auto-decide** — for each issue, Lead selects the recommended option without presenting choices. Each `nx_plan_decide(summary)` MUST include: selected approach + reason, AND rejected alternatives + why they were dismissed. No comparison table needed, but internal deliberation is mandatory.
-4. **Decision briefing** — output a concise summary of all decisions before generating tasks:
-   ```
-   [auto-plan complete] N issues, N decisions:
-   - #1: {selected} ({rejected alternative} — reason)
-   - #2: ...
-   ```
-   Do not wait for user response — proceed immediately to task generation.
-5. **Plan document** — generate tasks.json following Step 7 rules (including HOW-assisted decomposition if `how_agents` present in plan.json issues). Apply owner table and verification auto-pairing.
-
-Key differences from interactive mode:
-- No user prompts or comparison tables — Lead decides autonomously
-- No dynamic agenda proposals — Lead handles all derived issues internally
-- Output: tasks.json ready for `[run]` execution
-
-**Scope by invocation context:**
-- `[plan:auto]` standalone → auto-plan + briefing + tasks.json generation. Stops here.
-- Invoked by `[run]` (tasks.json absent) → auto-plan + briefing + tasks.json generation + seamless execution transition. No pause between plan and run.
-
-This mode is invoked internally by `[run]` when no tasks.json exists, or explicitly by the user with `[plan:auto]`.
-
----
-
-## Procedure (Interactive Mode)
-
-### Step 1: Intent Discovery
-
-Determine planning depth and identify which HOW subagents to delegate analysis to, based on Progressive Depth.
-
-| Level | Signal | Exploration Scope |
-|-------|--------|-------------------|
-| **Specific** | File path, function name, error message, or concrete target named | Focused on the relevant file/module |
-| **Direction-setting** | Open-ended question, "it would be nice if ~", choice needed among approaches | Related area + external case research |
-| **Abstract** | "I don't know how to approach this", goal itself unclear, fundamental direction | Full codebase + external research + comparable project comparison |
-
-- Specific request → confirm intent with 1–2 questions, derive issues immediately
-- Direction-setting → use hypothesis-based questions to understand intent
-- Abstract/fundamental → actively interview to uncover root goals the user hasn't clarified
-
-**HOW subagent selection rule:**
-- User explicitly names agents → use as-is, propose additions if gaps detected
-- User does not name agents → Lead proposes based on issue scope, confirm with user
-- Additional HOW subagents can be spawned at any time during analysis (Lead's or user's discretion)
-
-### Step 2: Research
-
-Understand code, core knowledge, and prior decisions before forming a planning agenda.
-
-**Start by checking existing knowledge**: before spawning any subagent, use file pattern search and file reading to scan `.nexus/memory/` and `.nexus/context/` for relevant memos and context files, and use `nx_history_search` to check for prior decisions on this topic. If the needed information is already there, use it directly and skip or narrow the subagent spawn. Only spawn subagents to fill gaps not covered by existing knowledge.
-
-**Approach selection:**
-
-| Scenario | Approach |
-|----------|----------|
-| Codebase orientation | `spawn_agent("explore", "<file/code search task>")` for codebase exploration |
-| External research needed | `spawn_agent("researcher", "<research question>")` for web search |
-| Both codebase and external | Spawn Explore + Researcher in parallel |
-
-- NEVER call `nx_plan_start` before research is complete.
-- `research_summary` parameter in `nx_plan_start` is required — forces research completion before session creation.
-- Researcher subagents are spawned via the harness's subagent spawn primitive and return findings to Lead. They do not join the plan session.
-
-**Existing session (plan.json present):**
-- Check current state with `nx_plan_status`.
-- If new topic or additional research needed → spawn researcher subagent accordingly.
-- Do not proceed to next issue before research is complete.
-
-### Step 3: Session Setup
-
-Register the planning session.
-
-1. **`nx_plan_start(topic, issues, research_summary)`** — register plan in plan.json; auto-archives any existing plan.json.
-2. Show the issue list to the user and confirm before proceeding.
-
-### Step 4: Analysis
-
-**Always proceed one issue at a time.** Never present multiple issues simultaneously.
-
-For each issue:
-
-1. **Current State Analysis** — Lead summarizes the current state and problems, drawing on research.
-2. **Subagent Analysis** — for complex issues, spawn HOW subagents (architect, strategist, etc.) in parallel via the harness's subagent spawn primitive. Each subagent independently analyzes the issue and returns findings.
-   - **Domain-Agent mapping** — match issue keywords to recommended HOW subagents:
-
-   | Domain keywords | Recommended HOW |
-   |----------------|-----------------|
-   | UI, UX, 디자인, 인터페이스, 사용자 경험, 레이아웃 | Designer |
-   | 아키텍처, 시스템 설계, 성능, 구조 변경, API, 스키마 | Architect |
-   | 비즈니스, 시장, 전략, 포지셔닝, 경쟁, 수익 | Strategist |
-   | 연구 방법론, 근거 평가, 문헌, 실험 설계 | Postdoc |
-
-   - **Opt-out default**: if the issue matches a domain in the mapping, spawning is the default. Multiple matches → multiple spawns. To skip, state "{Agent} not needed — reason: ..." in the analysis text.
-   - **No mapping match**: if no domain matches, Lead analyzes directly. When uncertain, spawn — the cost of an unnecessary spawn is lower than the cost of a shallow analysis.
-   - **Record HOW findings**: after HOW subagents return, include their agent names and key findings when recording the decision via `nx_plan_decide(how_agents=[...], how_summary={...})`. This data is stored in plan.json for Step 7 task generation.
-3. **Present Options** — after synthesis, Lead presents a comparison:
-
-```
-| Item | A: {title} | B: {title} | C: {title} |
-|------|-----------|-----------|-----------|
-| Pros | ... | ... | ... |
-| Cons | ... | ... | ... |
-| Trade-offs | ... | ... | ... |
-| Best for | ... | ... | ... |
-
-**Recommendation: {X} ({title})**
-
-- Option A falls short because {reason}
-- Option B falls short because {reason}
-- Option X overcomes {A/B limitations} → {core benefit}
-```
-
-4. **Await user response** — receive free-form responses. Users may combine options, push back, or ask follow-up questions.
-
-## Resume Policy
-
-When the harness's resume mechanism is unavailable, ALL resume paths are disabled — force fresh spawn. Otherwise:
-
-| resume_tier | Same-issue default | Cross-issue | Disqualifiers |
-|---|---|---|---|
-| persistent | resume by default | Lead opt-in only | counter-evidence / reversal / re-review issue → fresh |
-| bounded | conditional (same artifact only) | forbidden | loop 3x / feedback cycle (REVISION_REQUIRED) → fresh |
-| ephemeral | forbidden | forbidden | N/A (always fresh) |
-
-Before resuming a `bounded` agent: include a "re-read target files before any modification" instruction in the prompt. Bounded resume without re-read is BLOCKED.
-
-`resume_tier` is read from each agent's frontmatter (`agents/*.md`). If absent, treat as `ephemeral` (most conservative).
-
-### Step 5: Record Decision
-
-When the user decides, record with the `[d]` tag.
-
-- gate.ts detects `[d]` and routes to `nx_plan_decide`.
-- `nx_plan_decide(issue_id, summary)` — marks issue as `decided`, writes `decision` inline in plan.json.
-- Decisions are NOT written to decisions.json — plan.json is the single source of truth.
-- `[d]` without plan.json is blocked.
-- **Progress anchoring**: immediately after recording, output one line: "Issue #N decided (M of K complete). Next: #X — {title}." This keeps the user oriented in multi-issue sessions.
-
-**Immediately after each decision**, Lead checks: "Does this decision create follow-up questions or new issues?" If yes, propose adding via `nx_plan_update(action='add')` before moving to the next issue.
-
-**Decision reversal**: if the user wants to reconsider a prior decision ("아까 결정 다시 생각해보자", "issue #N 번복"), Lead calls `nx_plan_update(action='reopen', issue_id=N)` to reopen the issue and returns to Step 4 analysis for that issue.
-
-### Step 6: Dynamic Agenda + Wrap-up
-
-After each decision, Lead automatically checks for derived issues.
-
-- **Dynamic agenda proposal**: after a decision is recorded, Lead examines whether the decision implies follow-on questions or unresolved sub-issues. If found, propose adding them with `nx_plan_update(action='add', ...)` and confirm with the user before adding.
-- Pending issues remain → naturally transition to the next issue.
-- All issues decided → **Gap check**: compare original question/topic against the issue list.
-  - Gap found → register additional issues with `nx_plan_update(action='add', ...)`, return to Step 4.
-  - No gap → signal planning complete.
-- Wrap-up: confirm all analysis threads have reported conclusions to Lead.
-- Proceed to Step 7 automatically — do not ask whether to generate the plan document.
-
-### Step 7: Plan Document Generation
-
-All issues decided → generate the plan document (tasks.json) immediately:
-
-1. **Collect decisions** — gather all `decided` issues from plan.json
-2. **Derive tasks** — decompose decisions into concrete, actionable tasks
-
-   **HOW-assisted task decomposition**: check plan.json issues for `how_agents` field.
-   - If HOW agents participated in analysis → re-spawn those HOWs with the decided approach + their prior `how_summary` as context. Ask them to propose task decomposition and owner assignment for their domain.
-   - If no HOW agents participated → Lead decomposes alone using the owner table and auto-pairing rules above.
-   - This ensures task generation depth is proportional to plan analysis depth.
-
-3. **Enrich each task** with:
-   - `approach` — implementation strategy derived from the decision rationale
-   - `acceptance` — definition of done, verifiable criteria
-   - `risk` — known risks or caveats from the analysis
-   - `deps` — task dependencies based on execution order
-   - `owner` — assign based on delegation analysis:
-
-   | Work type | owner | Criteria |
-   |-----------|-------|----------|
-   | Single file, small change | **lead** | Subagent overhead > task effort |
-   | Code implementation (.ts, .js, .py, etc.) | **engineer** | Source code creation/modification |
-   | Documentation/content (.md, non-code) | **writer** | .md files, README, docs, non-code content |
-   | Web research / external investigation | **researcher** | External information gathering needed |
-   | Design analysis / review | **architect** etc. HOW | Technical trade-off judgment |
-   | Sequential edits to same file | **lead** | Parallel subagents risk conflict |
-
-   **Primary metric — artifact-coherence**: a well-scoped task targets a single artifact or a tightly coupled artifact cluster and makes a single coherent change. A change is coherent when (a) it can be described in one sentence, (b) reverting it leaves all other artifacts consistent, and (c) its acceptance can be verified by inspecting its outputs alone.
-
-   **Verification auto-pairing (conditional)** — create a CHECK task only when the DO task's acceptance includes the appropriate verification trigger:
-   - `owner: "engineer"` + acceptance contains a runtime-behavior criterion → pair a **tester** task.
-   - `owner: "writer"` + acceptance contains a verifiable deliverable criterion → pair a **reviewer** task.
-   - Exclusions: pure refactor (behavior-preserving), type-only changes, docs-adjacent tasks (.md or frontmatter-only, classified under `docs_only` entries in `vocabulary/task-exceptions.yml`), and researcher tasks. Researcher tasks never receive an auto-paired CHECK — research outputs feed Lead or HOW agents directly, not tester or reviewer.
-   - Paired verification tasks are linked via `deps` to the original task.
-
-   **Exception catalog**: task decomposition exceptions are defined in `vocabulary/task-exceptions.yml` (`docs_only.coherent`, `docs_only.independent`, `same_file_bundle`, `generated_artifacts`). When an exception applies to a task, record its id in the task's `context` field so downstream tooling can trace the classification.
-
-   **Dedup Layer 1 (plan-time static merge)**: before finalizing the task list, scan draft tasks for overlapping target_files. Overlapping tasks are merged into a single owner task via the `same_file_bundle` exception from `vocabulary/task-exceptions.yml` to prevent parallel write conflicts during execution.
-
-   **DO/CHECK decomposition principle**: DO agents (engineer, writer, researcher) and CHECK agents (tester, reviewer) accumulate less per-task context than HOW agents. When a task involves multiple independent artifacts, decompose across multiple parallel DO/CHECK subagents rather than bundling. HOW agents benefit from consolidated context and should generally remain as single sessions. Parallel decomposition is worthwhile when there are at least three independent artifacts; below that, bundling under one owner is preferable to avoid parallelization overhead.
-
-   **HOW decomposition rule**: split HOW analysis across multiple subagents only when the issue crosses different rows of the domain-agent mapping table (architect vs designer vs strategist vs postdoc). Sub-concerns within a single domain row belong in one HOW session.
-
-4. **Populate tasks.json** via `nx_task_add`:
-   - Set `goal` from the plan topic
-   - Set `decisions` from plan.json decided summaries
-   - Call `nx_task_add(plan_issue=N, approach, acceptance, risk, owner)` for each task
-   - If any decisions involve design or architecture changes, include a task (owner: `writer` or `lead`) to update the relevant files in `.nexus/context/` to reflect those decisions
-5. **Present plan document** — show the user the generated tasks.json summary for review
-6. **Present transition**: "Proceed with `[run]` to execute."
-
-**Incremental mode**: if tasks.json already exists (e.g., after adding follow-up issues), only add tasks for new decisions. Check `plan_issue` field to avoid duplicating tasks for already-covered issues.
-
----
-
-## plan → run Transition
-
-tasks.json is already generated in Step 7. Plan's role ends here.
-Proceed with `[run]` to execute.
-
----
-
-## Principles
-
-1. **Active intent discovery** — actively uncover what the user hasn't clarified. Use interviewing to surface the root goal behind the words.
-2. **Lead as synthesizer AND participant** — Lead does not merely relay subagent findings. Lead forms its own position, makes recommendations, and pushes back with evidence. Not a yes-man.
-3. **Exploration first + proactive expansion** — research code/knowledge/external sources before planning starts. Never ask groundless questions.
-4. **Hypothesis-based questions** — instead of empty questions, form hypotheses grounded in research and confirm with the user.
-5. **Progressive Depth** — automatically adjust planning depth and HOW subagent composition based on request complexity.
-6. **One at a time** — never present multiple issues at once. Reduce the user's cognitive load.
-7. **Options must include pros/cons/trade-offs/recommendation** — when recommending, explain why other options fall short.
-8. **Objective pushback** — even when the user arrives with strong conviction, Lead MUST independently analyze all viable options and present trade-offs the user may not have considered. The comparison table exists to surface what the user doesn't know, not to confirm what they already believe. Counter with evidence when better alternatives exist.
-9. **Prose conversation by default** — free-form user responses (combinations, pushback, follow-up questions) are the core of planning quality.
-10. **Dynamic agenda** — decisions create new questions. Lead proactively surfaces derived issues rather than waiting for the user to notice gaps.
-
----
-
-## State Management
-
-### plan.json
-
-`.nexus/state/plan.json` — managed via MCP tools.
-
-```json
-{
-  "id": 1,
-  "topic": "topic name",
-  "issues": [
-    {
-      "id": 1,
-      "title": "issue title",
-      "status": "pending"
-    },
-    {
-      "id": 2,
-      "title": "issue title",
-      "status": "decided",
-      "decision": "decision summary",
-      "how_agents": ["architect", "designer"],
-      "how_summary": {
-        "architect": "key findings...",
-        "designer": "key findings..."
-      }
-    }
-  ],
-  "research_summary": "...",
-  "created_at": "2026-01-01T00:00:00Z"
-}
-```
-
-- **Create**: `nx_plan_start(topic, issues, research_summary)` — called in Step 3; auto-archives any existing plan.json
-- **Status**: `nx_plan_status()` — check current issue state + decisions
-- **Update**: `nx_plan_update(action, ...)` — add/remove/modify/reopen issues
-- **Decide**: `nx_plan_decide(issue_id, summary)` — marks issue as `decided`, writes decision inline
-- **File presence = session in progress**
-
-### Topic Switching
-
-- `[plan]` → continue existing plan.json if present; start new session if not
-- Continue conversation without tag → continue existing session
-- New `nx_plan_start` call → auto-archives current plan.json before creating new one
-
-### Session Abort
-
-To abort a session, archive current state via `nx_task_close`. Incomplete issues/tasks are recorded in history.json for future reference.
-
----
-
-## Self-Reinforcing Loop
-
-```
-[plan] start → check/continue existing plan.json (start new if none)
-  ↓
-Intent discovery → research (parallel subagents) → nx_plan_start (register issues)
-  ↓
-Per-issue: HOW subagent analysis (parallel, independent) → Lead synthesis
-  → options comparison → [d] → nx_plan_decide
-  → dynamic agenda check → propose derived issues if found
-  ↓
-Next issue → ... → gap check → planning complete
-  ↓
-Proceed with `[run]` to execute.
-  ↓
-[run]: execution skill handles the full pipeline
-  ↓
-All done → nx_task_close (handled by run skill)
-```
-
-gate.ts detects `[d]` and routes to `nx_plan_decide` if plan.json exists; blocks otherwise.
-
-## Deactivation
-
-When transitioning to `[run]`, Plan's role ends. Execution is handled by the run skill.

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

@@ -1,154 +0,0 @@
----
-description: "Execution — user-directed agent composition."
-triggers:
-  - run
----
-## 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 shell commands (sed, echo redirection, heredoc, tee, etc.) — always use the harness's dedicated file-editing primitives (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, generate 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 `$nx-plan` 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**: `update_plan([{ name: "<per-task label>", state: "pending" }])` per task
-- **> 10 tasks**: group by `plan_issue`, `update_plan([{ name: "<group label>", state: "pending" }])` per group
-- Update the registered entry via `update_plan([{ name: "<label>", state: "in_progress" }])` / `update_plan([{ name: "<label>", state: "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 attempting any resume, verify the harness's resume mechanism is available. If unavailable, 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 `$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 shell commands** — sed, echo redirection, heredoc, tee, and similar shell-based file edits are prohibited. Always use the harness's dedicated file-editing primitives (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/dist/codex/plugin/skills/nx-sync/SKILL.md

@@ -1,87 +0,0 @@
----
-description: "Context knowledge synchronization — scans project state and updates .nexus/context/ design documents"
-triggers:
-  - sync
----
-## 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 the harness's file-reading and file-creation primitives 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 harness's file-reading primitive:
-
-- 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:
-
-```
-spawn_agent("writer", ">>WRITER_SYNC_PROMPT")
-Update .nexus/context/ documents based on the following changes. Read current files with the harness's file-reading primitive, then write updates with the harness's file-creation primitive. Changes: {change_manifest}
-<<WRITER_SYNC_PROMPT
-```
-
-The Writer agent:
-- Reads each relevant context file with the harness's file-reading primitive
-- Applies targeted updates — changes only the sections that are stale
-- Writes the updated file back with the harness's file-creation primitive
-- 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.