Role

Role

Execution norm that Lead follows when the user invokes the [run] tag. Reads tasks.json, dynamically composes subagents based on the owner field, and drives the execute-verify-complete cycle.

Constraints

• NEVER execute without a plan. If tasks.json is absent, invoke nx-auto-plan first to generate one, then return.
• Tasks are executed by their owner. Delegation to the matching subagent is the default — not Lead solo handling.
• NEVER stop while incomplete tasks remain. Continue the cycle until nx_task_list confirms all tasks are completed.
• NEVER work on main/master. Move to a branch appropriate to the task type before starting execution.

Procedure

Step 1: Preparation

• Branch Guard: if on main/master, create and switch to a branch matching the task type (prefix: feat/, fix/, chore/, research/, etc. — Lead's judgment).
• Load tasks.json:
  • Exists → read the list with nx_task_list and check prior decisions with nx_plan_status.
  • Absent → auto-invoke Skill({ command: "nx-auto-plan" }) to generate tasks.json. Do NOT ask the user — [run] implies execution intent.

Step 2: Execute

Task Registration

For each task, call TaskCreate({ subject: "<label>" }) then nx_task_update({ taskId, status: "pending" }) to register progress tracking. Keep registrations to a maximum of 10. If tasks exceed 10, group related tasks by a natural grouping unit such as plan_issue or target file, so that registered entries stay within 10.

Task Dispatch

• Execute tasks according to the owner field.
  • owner: "lead" → Lead handles directly.
  • Others → spawn the subagent matching the owner role.
• Pass the task's context, approach, and acceptance as the prompt to each subagent.
• Resume decision: for each task, query nx_task_resume for resume routing information and decide whether to spawn fresh or resume according to the Resume Dispatch Rule below.
• Parallel execution: tasks with no deps can be spawned in parallel. Serialize tasks that share overlapping target files.

State Transitions

• On task start, update to in_progress via nx_task_update; on completion, update to completed.
• When transitioning a task to completed, include result: {outcome, summary, artifacts?} in the same nx_task_update call. recorded_at is server-stamped. Note that status records the workflow stage and result.outcome records the end verdict — they are orthogonal.
• When a subagent is freshly spawned, include owner={role, agent_id: <id from spawn>, resume_tier: <ephemeral|bounded|persistent>} in the same nx_task_update call so that a future nx_task_resume can return this id.
• At the same moment, update progress tracking with TaskCreate({ subject: "<label>" }) then nx_task_update({ taskId, status: "in_progress" }) / TaskCreate({ subject: "<label>" }) then nx_task_update({ taskId, status: "completed" }). Reuse the exact label set at initial registration.

Resume Dispatch Rule

Lead acts based on the resume_tier and agent_id values returned by nx_task_resume.

• ephemeral → spawn fresh.
• bounded → resume if the same owner has prior work on overlapping target files and no other agent has edited in between. The resume prompt MUST include an instruction to "re-read target files before making any modifications."
• persistent → resume if the same agent participated in a prior task in this run. Cross-task reuse allowed.

When resume is chosen, invoke the SendMessage({ to: "<id>", message: "<resume prompt>" }) tool with the agent_id returned by nx_task_resume. Always provide a fresh resume prompt — some harnesses (OpenCode) do not expose a path to push additional input into a running session and support resume only by injecting a new prompt into an idle session.

If nx_task_resume returns agent_id: null, or the harness can no longer locate that id, fall back to fresh spawn silently — do NOT throw an error.

Escalation Chain

After receiving the Check result, Lead routes. Two inputs are read: Verdict and Flagged issues classification.

Verdict Inputs

Verifier	PASS	Routing entry
Tester	PASS	FAIL
Reviewer	APPROVED	REVISION_REQUIRED · BLOCKED

Routing Rules

Lead decides the next action based on the Flagged issues classification in the Check report.

Flagged issues classification	Next action
Design flaw · architectural change required	Spawn the domain-matched HOW → consult → re-delegate to Do
Scope conflict · user decision required · ambiguous judgment	Report to user · request direction
Environment problem · unverifiable (UNVERIFIABLE included)	Fix environment / retry. If unresolvable, report to user
Other (simple failure)	Re-delegate to the same Do (count +1)

Failures with a clear classification branch immediately at count zero. Only simple failures accumulate the count.

Simple-Failure Cumulative Count

Do → Check(fail) → Do → Check(fail) → HOW → Do → Check(fail) → Lead → user

• 1st → re-delegate to the same Do (attach failure feedback to the prompt)
• 2nd consecutive → spawn the domain-matched HOW → consult on approach → re-delegate to Do
• Still failing after HOW consultation → report to the user with diagnostic details and request direction

Mid-Do Notification Handling

Do/Check agents may notify directly mid-task or in their completion reports per their own body definitions. When Lead receives such a notification, it applies the routing rules above immediately — independent of the chain count.

Step 3: Verify

Lead delegates verification to the Check subagent using each task's acceptance field. Detailed judgment is the subagent's autonomous domain.

• Tester — code verification (engineer deliverables).
• Reviewer — document verification (writer deliverables).

Verification failures follow the Escalation Chain above.

Step 4: End-of-Cycle Review

Once all tasks reach completed state, Lead reviews the cycle and decides whether to close.

Review scope

• Alignment between the original user request and the result — any missing area?
• Cross-task deliverable integration — do the outputs operate without contradiction?
• Any follow-ups implied but not explicitly stated within the request?

HOW consultation

Spawning the domain-matched HOW for cross-task review is the default — Architect for code, Designer for UX, Postdoc for research methodology. If you skip the consultation, state the reason in the cycle-end report — justified-skip examples: existing decisions or retrospectives already cover the cycle outcome / a single-task cycle with no cross-task review target / change radius is contained within one module with low irreversibility.

When recording cycle-end synthesis or task failure notes via nx_plan_analysis_add, use role='retrospective' for end-of-cycle synthesis and role='failure-note' for per-task failure annotations. These two values are reserved as classification anchors for nx_history_search; arbitrary role values are also permitted.

Actions by decision

Decision	Action
No additional work	Proceed to Step 5 Complete
Missing coverage found	Register a new task with nx_task_add → return to Step 2 Execute
Existing task needs rework	Reopen with nx_task_update → return to Step 2 Execute

Iteration cap

The review runs at most twice per cycle (initial + one re-review). After follow-up work brings all tasks back to completed, the second review runs. If gaps remain at the second review, do NOT auto-register more work — report to the user and let them decide whether to extend the cycle. Extending the cycle is the user's decision domain.

Scope discipline

Catch missing coverage only within the original user request. Quality-improvement ideas outside the request are deferred to a new plan cycle — preventing scope creep within the current cycle.

Step 5: Complete

Execute in order.

1. nx_task_close: archives plan+tasks to .nexus/history.json. plan.json and tasks.json are removed.
2. git commit: bundle source changes, build artifacts (bridge/, scripts/), .nexus/history.json, and any modified .nexus/memory/ or .nexus/context/ into a single commit to maintain 1:1 cycle-commit mapping. Use explicit paths instead of git add -A.
3. Report: summarize to the user using the items below. Merge/push is the user's decision and outside this skill's scope.
   • Changes: file paths and summary
   • Key decisions: scope, approach, trade-offs
   • Next steps: follow-up actions
   • Open questions: when applicable
   • Risks / uncertainties: express in the form "X may fail under Y condition", when applicable

---

Reference Framework

Phase	Owner	Content
1. Preparation	Lead	Branch Guard, read tasks.json via nx_task_list / invoke nx-auto-plan if absent
2. Execute	Do subagents	Spawn per owner, resume decision via nx_task_resume, state transitions via nx_task_update
3. Verify	Check subagents	Tester (code) / Reviewer (document) verification against acceptance criteria
4. End-of-Cycle Review	Lead (HOW if needed)	Cycle-level review, register additional work or close
5. Complete	Lead	nx_task_close, git commit, report

---

Structured Delegation

When Lead delegates a task to a subagent, 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}

---

State Management

.nexus/state/tasks.json is created by nx-plan variants (plan/auto-plan) via nx_task_add, and state transitions during the nx-run cycle are reflected via nx_task_update. Querying is handled by nx_task_list, and resume decisions by nx_task_resume. On cycle end, call nx_task_close to archive plan+tasks to .nexus/history.json.