Neb Work

• If .env is missing or NEB_TASK_API_URL is not set → tell user to run /neb-env-setup first and STOP
• If NEB_TASK_AGENT_ID is not set → execute Flow 1: First-Time Registration, then continue to Flow 2
• If NEB_TASK_AGENT_ID is set → execute Flow 2: Session Connect directly

Flow 1: First-Time Registration

Use /superpowers:executing-plans to follow the multi-step registration workflow below.

Run this when NEB_TASK_AGENT_ID is not set in .env. This registers the operator as an agent on the platform.

1.1: Read Git Identity

GIT_NAME=$(git config user.name)
GIT_EMAIL=$(git config user.email)

If either is empty, ask the user to configure git identity first and STOP.

1.2: Search for Existing Agent

Search all agents in the company for a match by name (case-insensitive) or metadata containing the email:

source "$(git rev-parse --show-toplevel)/.env"
curl -sf --max-time 10 "${NEB_TASK_API_URL}/api/companies/${NEB_TASK_COMPANY_ID}/agents"

Iterate the returned array. Match by:

• agent.name equals $GIT_NAME (case-insensitive string comparison)
• OR any field in agent.metadata contains $GIT_EMAIL

If found: Write the agent's id to .env as NEB_TASK_AGENT_ID (append or update the line). Skip to step 1.4.

If not found: Continue to step 1.3.

1.3: Create Operator Agent

source "$(git rev-parse --show-toplevel)/.env"
curl -sf --max-time 10 -X POST "${NEB_TASK_API_URL}/api/companies/${NEB_TASK_COMPANY_ID}/agents" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "'"${GIT_NAME}"'",
    "role": "operator",
    "title": "Engineer",
    "adapterType": "process",
    "adapterConfig": {}
  }'

Extract the returned id and write it to .env as NEB_TASK_AGENT_ID.

1.4: Generate API Key

source "$(git rev-parse --show-toplevel)/.env"
curl -sf --max-time 10 -X POST "${NEB_TASK_API_URL}/api/agents/${NEB_TASK_AGENT_ID}/keys" \
  -H "Content-Type: application/json"

This returns the raw API key token once (it cannot be retrieved again). Extract the key value and write it to .env as NEB_TASK_API_KEY.

1.5: Verify Agent

source "$(git rev-parse --show-toplevel)/.env"
curl -sf --max-time 10 "${NEB_TASK_API_URL}/api/agents/${NEB_TASK_AGENT_ID}" \
  -H "Authorization: Bearer ${NEB_TASK_API_KEY}"

Confirm the agent exists and status is active. If verification fails, report the error and STOP.

Use /superpowers:verification-before-completion to verify agent exists and API key works after registration.

Print: "Registered as operator agent: {name} ({id})"

Flow 2: Session Connect

Use /superpowers:executing-plans to follow the multi-step connect workflow below.

Run this every time the skill is invoked (after registration is complete).

2.1: Verify Environment

Source .env and confirm all four variables are set:

• NEB_TASK_API_URL
• NEB_TASK_COMPANY_ID
• NEB_TASK_AGENT_ID
• NEB_TASK_API_KEY

If any are missing, report which ones and tell the user to run /neb-env-setup and STOP.

2.2: Verify Identity

source "$(git rev-parse --show-toplevel)/.env"
curl -sf --max-time 10 "${NEB_TASK_API_URL}/api/agents/${NEB_TASK_AGENT_ID}" \
  -H "Authorization: Bearer ${NEB_TASK_API_KEY}"

Confirm the agent is active. If the request fails (401, 404, network error), report the error with troubleshooting steps and STOP.

2.3: Fetch Assigned Issues

Make three API calls to fetch issues by status:

source "$(git rev-parse --show-toplevel)/.env"

# In-progress issues
curl -sf --max-time 10 \
  "${NEB_TASK_API_URL}/api/companies/${NEB_TASK_COMPANY_ID}/issues?assigneeAgentId=${NEB_TASK_AGENT_ID}&status=in_progress" \
  -H "Authorization: Bearer ${NEB_TASK_API_KEY}"

# Todo issues
curl -sf --max-time 10 \
  "${NEB_TASK_API_URL}/api/companies/${NEB_TASK_COMPANY_ID}/issues?assigneeAgentId=${NEB_TASK_AGENT_ID}&status=todo" \
  -H "Authorization: Bearer ${NEB_TASK_API_KEY}"

# Blocked issues
curl -sf --max-time 10 \
  "${NEB_TASK_API_URL}/api/companies/${NEB_TASK_COMPANY_ID}/issues?assigneeAgentId=${NEB_TASK_AGENT_ID}&status=blocked" \
  -H "Authorization: Bearer ${NEB_TASK_API_KEY}"

2.4: Display Task List

Display all fetched issues grouped by status, numbered sequentially:

=== Your Tasks ===

IN PROGRESS:
  1. NEB-42  Fix OIDC redirect loop          [high]
  2. NEB-38  Update marketing site            [medium]

TODO:
  3. NEB-45  Add cluster health monitoring    [high]
  4. NEB-50  Helm chart version bump          [low]

BLOCKED:
  5. NEB-47  Deploy SSO (blocked by NEB-42)   [urgent]

Use the issue's identifier (e.g., NEB-42), title, and priority from the API response. If a status group has no issues, omit that section. If all groups are empty, print "No tasks assigned to you." and STOP.

2.5: Pick a Task

Use AskUserQuestion to prompt:

Pick a task (number) or 'q' to quit:

If the user enters 'q' or 'quit', print "Session ended." and STOP.

Map the number back to the corresponding issue.

2.6: Checkout Issue

Generate a UUID v4 for the run ID:

python3 -c "import uuid; print(uuid.uuid4())"

Checkout the selected issue:

source "$(git rev-parse --show-toplevel)/.env"
RUN_ID="<generated-uuid>"
curl -sf --max-time 10 -X POST \
  "${NEB_TASK_API_URL}/api/issues/${ISSUE_ID}/checkout" \
  -H "Authorization: Bearer ${NEB_TASK_API_KEY}" \
  -H "X-Paperclip-Run-Id: ${RUN_ID}" \
  -H "Content-Type: application/json"

If 409 (already checked out): Inform the user that this task is already checked out by another session. Use AskUserQuestion to ask: "This task is already checked out. Force checkout? (y/n)". If yes, retry with a force parameter or continue anyway. If no, go back to step 2.5.

If other error: Report and STOP.

2.7: Fetch Task Context

source "$(git rev-parse --show-toplevel)/.env"
curl -sf --max-time 10 \
  "${NEB_TASK_API_URL}/api/issues/${ISSUE_ID}/heartbeat-context" \
  -H "Authorization: Bearer ${NEB_TASK_API_KEY}"

2.8: Display Full Task Details

Display the complete task information:

=== NEB-42: Fix OIDC redirect loop ===
Status: in_progress | Priority: high

Description:
<full description from issue>

Acceptance Criteria:
<extracted from description if present>

Recent Comments:
<last 3 comments from heartbeat context, if any>

2.9: Set Up Session State

Write session state files for other skills to detect:

# Generate run ID (already done in 2.6)
echo "${RUN_ID}" > /tmp/neb-run-${CLAUDE_SESSION_ID:-$$}
echo "${ISSUE_ID}" > /tmp/neb-issue-${CLAUDE_SESSION_ID:-$$}

Note: CLAUDE_SESSION_ID may not be set. Fall back to $$ (process ID) or generate a unique identifier.

2.10: Post Session Start Comment

source "$(git rev-parse --show-toplevel)/.env"
BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
WORKSPACE=$(pwd)

curl -sf --max-time 10 -X POST \
  "${NEB_TASK_API_URL}/api/issues/${ISSUE_ID}/comments" \
  -H "Authorization: Bearer ${NEB_TASK_API_KEY}" \
  -H "X-Paperclip-Run-Id: ${RUN_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Session started — operator-assisted mode\nWorkspace: '"${WORKSPACE}"'\nBranch: '"${BRANCH}"'"
  }'

2.11: Print Session Ready Message

Print:

Connected to {IDENTIFIER}. You can now work normally.
Use /neb-delegate, /neb-review, /neb-team, /neb-handoff for collaboration.

Where {IDENTIFIER} is the issue identifier (e.g., NEB-42).

Flow 3: Assisted Work Mode (Context for Other Skills)

After connect completes, the session is in "assisted work mode." This means:

• /tmp/neb-run-{SESSION_ID} contains the active run UUID — other skills include this as X-Paperclip-Run-Id on mutations
• /tmp/neb-issue-{SESSION_ID} contains the active issue ID — other skills use this to post milestone comments
• Session hooks (scripts/neb-session-*.sh) detect these files and log activity automatically
• Skills like /neb-delegate, /neb-review, /neb-team, and /neb-handoff read these files to know which task is active

No additional action is needed for Flow 3 — it is purely the result of the session state written in Flow 2.

Error Handling

• Network failures: Report the specific error (connection refused, timeout, DNS failure) and suggest checking that the platform is running. Include the URL that was attempted.
• 401 Unauthorized: API key may be invalid or expired. Suggest re-running /neb-env-setup to regenerate credentials.
• 404 Not Found: Agent or issue may have been deleted. Report the specific resource that was not found.
• Empty inbox: "No tasks assigned to you." — this is not an error, just an informational state. STOP gracefully.
• Missing .env variables: List which variables are missing and direct user to /neb-env-setup.

Writing to .env

When writing variables to .env, use this pattern to update or append:

ENV_FILE="$(git rev-parse --show-toplevel)/.env"

# Update existing variable or append new one
if grep -q '^NEB_TASK_AGENT_ID=' "$ENV_FILE" 2>/dev/null; then
  sed -i '' 's|^NEB_TASK_AGENT_ID=.*|NEB_TASK_AGENT_ID='"${NEW_VALUE}"'|' "$ENV_FILE"
else
  echo "NEB_TASK_AGENT_ID=${NEW_VALUE}" >> "$ENV_FILE"
fi

Apply the same pattern for NEB_TASK_API_KEY.

Superpowers Integration