Nexus Worker Skill

Execute assigned nexus subtasks with focused implementation. You claim subtasks, do the work, and mark complete.

Project Scoping (CRITICAL)

First step when receiving any nexus task: Set the project context from your delegation prompt.

Finding Your Project

The orchestrator ALWAYS includes the project in your delegation context:

NEXUS_PROJECT: <project-name>

Look for this in your prompt and use it directly:

export NEXUS_PROJECT="<project-name>"

Why Workers Don't Discover

• •Workers are delegated specific subtasks with full context
• •The orchestrator has already determined the correct project
• •Workers should NOT prompt users or modify .envrc
• •If NEXUS_PROJECT is missing from your delegation, that's an orchestrator bug - ask for clarification

Example Delegation Context

CONTEXT:
- Stack: Python 3.11, FastAPI
- Constraints: uv-first, no new dependencies

NEXUS_PROJECT: nexus

SKILLS TO LOAD:
- nexus-worker

NEXUS SUBTASK: abc123

TASK:
- Claim the subtask: nexus issue claim abc123
- Add health check endpoint
- Complete it: nexus issue update abc123 --status completed

Extract and export immediately:

export NEXUS_PROJECT="nexus"
nexus issue claim abc123

Server Check

nexus status || echo "Server not running on port 7001"

CLI-Only Operations

All nexus operations MUST use the nexus CLI:

nexus issue claim/create/update/complete/release/renew
nexus plan show
nexus status

The CLI validates state, manages timestamps, and ensures consistency.

Role Definition

• •Claim SUBTASKS or small standalone issues
• •Do the implementation work (code, tests, docs)
• •Mark your work complete when done
• •Create follow-up issues if you discover new work
• •Do NOT decompose or orchestrate large features

Core Workflow

1. nexus issue claim <id>                          # Claim your assigned subtask
2. # Do the implementation work
3. nexus issue update <id> --status completed      # Mark done

Essential Commands

When Delegated a Subtask

You'll receive a subtask ID in your prompt (look for NEXUS SUBTASK:):

1. •Always claim it first before starting work
2. •Read details with nexus issue show <id> --format json
3. •Check parent plan if it exists (see Plan-Aware Implementation)
4. •Complete your work
5. •Mark the subtask done
6. •The orchestrator monitors and handles the parent issue

Plan-Aware Implementation

Before Starting Work

⚠️ CLAIM WILL FAIL if parent has unapproved feature plan

The nexus issue claim command checks plan approval status. If the parent issue has a feature type plan with ready=false, the claim will raise ValueError. See "If Plan Not Ready" section below.

# 1. Claim the subtask (may fail if plan not approved)
nexus issue claim <id>

# 2. Check if it's a subtask with a parent
PARENT=$(nexus issue show <id> --format json | jq -r '.parent // empty')

# 3. If subtask, read parent plan for context
if [ -n "$PARENT" ]; then
  nexus plan show $PARENT
fi

Using the Plan

When a parent plan exists, pay attention to:

• •Intent: The goal you're working toward
• •Direction: Architectural decisions to follow
• •Human Notes: Footguns and constraints to avoid
• •Acceptance Criteria: What must be true when done

Standalone Issues (No Parent)

If you're assigned a standalone issue (no parent, no plan):

1. •Determine if it needs a plan (complex work = yes)
2. •If needed, create one:
   bash

   nexus plan template bugfix  # or refactor, testing
   # Fill in sections
   nexus plan create --type bugfix --for-issue <id> --body -
   

3. •bugfix/refactor/testing auto-approve; feature plans need human

If Plan Not Ready (HARD BLOCKER)

nexus issue claim will FAIL with ValueError if the issue has an unapproved feature plan. This is enforced by the system, not a guideline.

What happens when claim fails:

$ nexus issue claim abc123
Error: Plan not approved for issue

What to do:

1. •Do NOT try to work around this - the gate exists for a reason
2. •Report back to orchestrator with this message:

BLOCKED: Cannot claim subtask <id>

The issue has a feature plan that is not approved.
Plan ID: <plan_id>
Status: ready=false

Action required: Human must approve the plan before workers can proceed.
Command for orchestrator: nexus plan list --not-ready

1. •Do NOT:
   • •Try to claim the parent issue instead
   • •Create a new issue to bypass the plan
   • •Implement without claiming

The orchestrator needs to iterate with the human to get the plan approved.

Handling Problems

Creating Follow-up Issues

If you discover related work while implementing:

# Create sibling subtask (same parent)
nexus issue create --title "Fix related bug" --project "nexus" --parent <parent_id>

Don't claim it - let the orchestrator assign it.

Example Session

# Claim the subtask you were assigned
nexus issue claim abc123

# Check what you need to do
nexus issue show abc123 --format json

# Check parent plan for context
PARENT=$(nexus issue show abc123 --format json | jq -r '.parent // empty')
if [ -n "$PARENT" ]; then
  echo "Reading parent plan..."
  nexus plan show $PARENT
fi

# ... do the implementation work ...

# Renew if it's taking a while
nexus issue renew abc123

# ... finish the work ...

# Mark complete
nexus issue update abc123 --status completed

Best Practices

• •Always claim before starting (prevents duplicate work)
• •Keep claims short - release if you can't finish
• •One subtask at a time (focus)
• •Use --format json for parsing issue details
• •Don't create subtasks unless explicitly needed
• •Follow the parent plan's Direction and Human Notes
• •Validate against Acceptance Criteria before completing

Anti-Patterns

• •❌ Working without claiming (no visibility for orchestrator)
• •❌ Ignoring parent plan (missing constraints/context)
• •❌ Creating many subtasks (you're a worker, not orchestrator)
• •❌ Holding claims for hours without renewing
• •❌ Completing without verifying against acceptance criteria
• •❌ Implementing without claiming when claim fails (bypasses the gate)
• •❌ Claiming the parent issue to work around subtask plan gate
• •❌ Creating new issues to avoid unapproved plan