@moreih29/nexus-core 0.15.2 → 0.16.0

package/dist/claude/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-1776671215218/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/claude/hooks/hooks.json

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

package/dist/claude/settings.json

@@ -0,0 +1,3 @@
+{
+  "agent": "lead"
+}

package/dist/claude/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 `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 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.
+
+```
+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 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.
+```

package/dist/claude/skills/nx-plan/SKILL.md

@@ -0,0 +1,353 @@
+---
+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 `Skill({ command: "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 | `Agent({ subagent_type: "explore", prompt: "<file/code search task>" })` for codebase exploration |
+| External research needed | `Agent({ subagent_type: "researcher", prompt: "<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.