@moreih29/nexus-core 0.1.0

package/schema/skill.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "skill.schema.json",
+  "title": "Nexus Skill meta.yml",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "name", "description"],
+  "properties": {
+    "id": { "$ref": "common.schema.json#/$defs/id" },
+    "name": { "type": "string", "minLength": 1 },
+    "description": { "$ref": "common.schema.json#/$defs/description" },
+    "triggers": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "common.schema.json#/$defs/id" }
+    },
+    "alias_ko": { "type": "string" },
+    "manual_only": { "type": "boolean", "default": false }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "manual_only": { "const": true } },
+        "required": ["manual_only"]
+      },
+      "then": {},
+      "else": {
+        "properties": {
+          "triggers": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "$ref": "common.schema.json#/$defs/id" }
+          }
+        },
+        "required": ["triggers"]
+      }
+    }
+  ]
+}

package/schema/vocabulary.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "vocabulary.schema.json",
+  "title": "Nexus Vocabulary files",
+  "$defs": {
+    "capabilityEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "description", "harness_mapping"],
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/id" },
+        "description": { "$ref": "common.schema.json#/$defs/description" },
+        "harness_mapping": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["claude_code", "opencode"],
+          "properties": {
+            "claude_code": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+            "opencode": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+          }
+        }
+      }
+    },
+    "capabilityFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["capabilities"],
+      "properties": {
+        "capabilities": { "type": "array", "items": { "$ref": "#/$defs/capabilityEntry" } }
+      }
+    },
+    "simpleEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "description"],
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/id" },
+        "description": { "$ref": "common.schema.json#/$defs/description" }
+      }
+    },
+    "categoryFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["categories"],
+      "properties": {
+        "categories": { "type": "array", "items": { "$ref": "#/$defs/simpleEntry" } }
+      }
+    },
+    "resumeTierFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["resume_tiers"],
+      "properties": {
+        "resume_tiers": { "type": "array", "items": { "$ref": "#/$defs/simpleEntry" } }
+      }
+    },
+    "tagEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "trigger", "type", "description"],
+      "properties": {
+        "id": { "$ref": "common.schema.json#/$defs/id" },
+        "trigger": { "type": "string", "minLength": 1 },
+        "type": { "type": "string", "enum": ["skill", "inline_action"] },
+        "description": { "$ref": "common.schema.json#/$defs/description" },
+        "skill": { "$ref": "common.schema.json#/$defs/id" },
+        "handler": { "type": "string", "minLength": 1 },
+        "variants": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      },
+      "if": {
+        "properties": { "type": { "const": "skill" } },
+        "required": ["type"]
+      },
+      "then": {
+        "properties": { "skill": {} },
+        "required": ["skill"]
+      },
+      "else": {
+        "properties": { "handler": {} },
+        "required": ["handler"]
+      }
+    },
+    "tagFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tags"],
+      "properties": {
+        "tags": { "type": "array", "items": { "$ref": "#/$defs/tagEntry" } }
+      }
+    }
+  }
+}

package/skills/nx-init/body.md

@@ -0,0 +1,199 @@
+## 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 CLAUDE.md 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.
+- Project section in CLAUDE.md 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
+
+- `/claude-nexus:nx-init` — full onboarding (or resume)
+- `/claude-nexus:nx-init --reset` — back up existing `.nexus/` knowledge and re-onboard
+- `/claude-nexus:nx-init --reset --cleanup` — show backup list + selective deletion
+
+---
+
+## 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
+  AskUserQuestion({
+    questions: [{
+      question: "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 Bash mkdir):
+- `.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 CLAUDE.md (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 CLAUDE.md inside markers using the Edit tool. If CLAUDE.md already contains `<!-- PROJECT:START -->` markers, replace the content between them. If CLAUDE.md 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 CLAUDE.md but not readable from code alone)
+
+Use the Write tool 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.
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "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 Write tool 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
+- CLAUDE.md: 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
+- /claude-nexus:nx-init --reset — re-run onboarding (existing knowledge will be backed up)
+```

package/skills/nx-init/meta.yml

@@ -0,0 +1,4 @@
+name: nx-init
+description: Project onboarding — scan, mission, essentials, context generation
+manual_only: true
+id: nx-init

package/skills/nx-plan/body.md

@@ -0,0 +1,336 @@
+## 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 TeamCreate. SendMessage 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. SendMessage to a `name` (running teammate communication) 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 Agent tool
+- Continuing conversation without a tag → continue existing session
+
+---
+
+## Auto Mode (`[plan:auto]`)
+
+When triggered with `[plan:auto]` or invoked via `Skill({ args: "auto" })`, 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 `AskUserQuestion` 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 Glob/Read 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 Explore agent (`subagent_type: "Explore"`) for file/code search |
+| External research needed | Spawn Researcher agent (`subagent_type: "claude-nexus:researcher"`) 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 Agent tool 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 Agent tool. 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 `.nexus/state/runtime.json` shows `teams_enabled: false`, 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:
+
+   | Task 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 |
+
+   **Verification task auto-pairing** — create separate verification tasks:
+   - Task with `owner: "engineer"` + `acceptance` field → pair a **tester** task (verify acceptance criteria)
+   - Task with `owner: "writer"` → pair a **reviewer** task (verify deliverable)
+   - Paired verification tasks are linked via `deps` to the original task
+4. **Write 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
+- **Read**: `nx_plan_status()` — check current issue state + decisions
+- **Update**: `nx_plan_update(action, ...)` — add/remove/edit/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.