reef-pulse

name	reef-pulse
description	Run the Moonjelly Reef pulse, an orchestrator to scan and dispatch all automated work on autopilot.

reef-pulse

Input

Nothing, or a specific issue-id to focus the pulse on a single issue.

ONLY_ISSUE_ID="{issue-id or -}" # "-" if nothing provided
SKILL_DIR="{base directory for this skill}" # e.g. "~/.claude/skills/reef-pulse"
LOCK_FILE=".agents/moonjelly-reef/pulse.lock"

Setup Guard

Read .agents/moonjelly-reef/config.md. If the file doesn't exist, stop and tell the diver: "🪼 reef-pulse requires setup. Run reef-scope first to configure the reef."

TRACKER_TYPE="{from .agents/moonjelly-reef/config.md tracker field}" # e.g. "local-tracker-committed"
TRACKER_BRANCH="{from .agents/moonjelly-reef/config.md tracker-branch field, or empty string if not set}"

If "$TRACKER_TYPE" != "local-tracker-committed", skip the rest of this section.

If "$TRACKER_BRANCH" is empty or missing from config, warn the user — do not continue:

⚠️ tracker-branch is not set in .agents/moonjelly-reef/config.md. Please add it, then try again.

CURRENT_BRANCH="$(git branch --show-current)"

If "$CURRENT_BRANCH" != "$TRACKER_BRANCH", warn the user — do not continue:

⚠️ Current branch is $CURRENT_BRANCH but the tracker branch is $TRACKER_BRANCH. Please run git checkout $TRACKER_BRANCH first, then try again.

./pull.sh --branch "$TRACKER_BRANCH"

Rules

Shell blocks are literal commands — execute them as written.

Tracker note:

• For local-tracker, run ./tracker.sh and ./merge.sh exactly as written.
• For GitHub, replace ./tracker.sh and ./merge.sh with gh
• For other trackers with MCP issue tools, replace ./tracker.sh issue with their MCP equivalent and ./tracker.sh pr and ./merge.sh pr with gh pr

AFK skill: this skill runs without human interaction. You are the orchestrator — scan, dispatch, and exit. You hold no state; labels are the state. When in doubt: check the labels, make your best judgment, move on. Never block waiting for human input.

0. Fetch context

If "$ONLY_ISSUE_ID" = "-", skip this step — the pulse-loop will scan all labels normally.

If $ONLY_ISSUE_ID is a specific ID, fetch that issue. The pulse-loop will process only this issue instead of scanning all labels:

./tracker.sh issue view "$ONLY_ISSUE_ID" --json body,title,labels

1. Session setup

Acquire lock

Check for an existing pulse.lock file.

If the pulse.lock file exists, another pulse may already be running (or a previous session crashed without cleaning up).

• If pulse.lock exists, read the start timestamp from it, calculate how long the existing pulse has been running, and report this to the diver: "The reef has been pulsing for {elapsed} ~~~ 🪸 🪸 🐠. There may be a lost diver. Pulse again to find them?" In interactive use, ask the diver. In cron/autopilot use, override automatically.
• If pulse.lock does not exist (or the diver chose to override), create it with a start timestamp (ISO 8601 UTC) and continue.

Print session header

RUN ONCE PER SESSION.

If this is the first iteration of the pulse (not a recursive call), print the session header:

┌─────────────────────────────────────────────────────────────┐
│  🪼  MOONJELLY REEF  ·  SESSION LOG                         │
└─────────────────────────────────────────────────────────────┘

Initialize the session bookkeeping variables:

PULSE_NR=1
AGENT_COUNT_SESSION=0
SESSION_START_TS="$(date +%s)"

2. Start pulse loop

After the session is initialized, read and follow pulse-loop.md from top to bottom for the first pulse-loop iteration.

3. Repeat pulse loop or finish

After each return from pulse-loop.md, decide whether to invoke another pulse-loop iteration or move to session completion.

If "$IS_SESSION_COMPLETE" = "false" and "$AGENT_COUNT_PULSE" -gt 0: the pulse dispatched automated work in this pulse-loop iteration. Re-run pulse-loop.md on the main session without asking confirmation. The loop stays on the main session, never as a sub-agent — this keeps the sequence strictly serial (scan, dispatch, wait, scan again) instead of spawning nested agents. Do NOT release the lock between pulse-loop iterations; the lock persists across the entire session. Re-running pulse-loop.md means following that file again from top to bottom using the updated shell variables already present in the same session.

If "$IS_SESSION_COMPLETE" = "true": no automated work was dispatched this iteration. The pulse has nothing left to do. Continue to step 4.

4. Session completion

RUN ONLY IF "$IS_SESSION_COMPLETE" = "true".

Print SESSION COMPLETE

Compute the final session duration from the session start timestamp:

SESSION_DURATION_SECS="$(( $(date +%s) - SESSION_START_TS ))"
SESSION_DURATION="{format SESSION_DURATION_SECS as XmYYs or HhMMmSSs}" # e.g. "17m00s"

Print the SESSION COMPLETE box with session stats:

┌─────────────────────────────────────────────────────────────┐
│  🪼 SESSION COMPLETE                                         │
│                                                              │
│  Duration    $SESSION_DURATION                               │
│  Pulses      $PULSE_NR                                       │
│  Agents      $AGENT_COUNT_SESSION  dispatches             │
│  To Land     #34  #53                                        │
│  Landed      #33  #52                                        │
│  Blocked     #56  #57                                        │
└─────────────────────────────────────────────────────────────┘

• To Land: issues that reached to-land during this session
• Landed: issues that reached landed during this session
• Blocked: issues that are blocked or have no actionable label

Print Lore

RUN ONLY IF "$AGENT_COUNT_SESSION" -gt 0.

prep:

SENTENCE_BALLPARK="$((PULSE_NR * 2))"

Dispatch a sub-agent:

Read and follow $SKILL_DIR/lore-writer.md.

SENTENCE_BALLPARK="$SENTENCE_BALLPARK"

The lore-writer sub-agent returns:

CHAPTER="{lore prose returned by the lore-writer sub-agent}" # e.g. "The tide shifted as three issues moved from implement to inspect..."

Print the chapter:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  $CHAPTER
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Print Next Up

Query for to-land and to-scope issues and say how many there are of those.

./tracker.sh issue list --json number,title,labels --limit 100 --search 'label:to-land OR label:to-scope'
X="{the amount of to-land issues}" # e.g. 3
Y="{the amount of to-scope issues}" # e.g. 2

Print:

The reef awaits new work. 🐚
You have $X open issues to land and $Y open issues to scope.
Run `reef-land` or `reef-scope` to start. 🤿

Release lock

To release the lock, delete the pulse.lock file.

Exit.