phase-implement

phase-implement

Phase-agent that owns the implementation half of the legacy oneshot cycle — this is the biggest single cost line of a worker run, which is why it leaves -p for --bg first (plan §Initiative 1 Phase 3 rationale). The skill body is intentionally thin: the canonical /catalyst-dev:implement-plan skill already handles TDD rhythm, quality gates, agent-team mode, and findings collection — phase-implement adds only the phase-agent envelope (signal file, comms channel, /goal cap, terminal emit) around it.

Prerequisites

• CATALYST_ORCHESTRATOR_DIR, CATALYST_ORCHESTRATOR_ID, CATALYST_PHASE=implement,

CATALYST_TICKET set by [[phase-agent-dispatch]].

• An approved plan exists at thoughts/shared/plans/<date>-<ticket-lowercase>.md — the dispatcher's

prior-artifact gate already validates this; this skill re-reads the file.

• Current working directory is the ticket's worktree (orchestrator's Phase 2 provisioning).

Prelude (template — copy verbatim into the running session)

set -euo pipefail

: "${CATALYST_ORCHESTRATOR_DIR:?required (set by phase-agent-dispatch)}"
: "${CATALYST_ORCHESTRATOR_ID:?required}"
: "${CATALYST_PHASE:?required}"
: "${CATALYST_TICKET:?required}"

ORCH_DIR="$CATALYST_ORCHESTRATOR_DIR"
ORCH_ID="$CATALYST_ORCHESTRATOR_ID"
PHASE="$CATALYST_PHASE"
TICKET="$CATALYST_TICKET"
CHANNEL="${ORCH_ID}"

# CTL-484: continuation-worker orientation. Set by orchestrate-revive's
# continuation branch when this skill is resumed via `claude --bg --resume`
# after a previous session hit its /goal turn cap. Read the handoff doc and
# trust its summary instead of re-walking the plan from scratch.
if [[ "${CATALYST_IS_CONTINUATION:-}" == "true" ]]; then
  CONT_HANDOFF="${CATALYST_HANDOFF_PATH:-}"
  CONT_N="${CATALYST_CONTINUATION_COUNT:-?}"
  if [[ -n "$CONT_HANDOFF" && -f "$CONT_HANDOFF" ]]; then
    echo "phase-implement: continuation #${CONT_N} — resuming from ${CONT_HANDOFF}"
    echo "phase-implement: reading handoff (do NOT re-read full plan from scratch)"
    cat "$CONT_HANDOFF"
  else
    echo "warn: CATALYST_IS_CONTINUATION=true but handoff path missing or unreadable" >&2
  fi
fi

SIGNAL_FILE="${ORCH_DIR}/workers/${TICKET}/phase-${PHASE}.json"
[[ -f "$SIGNAL_FILE" ]] || { echo "phase-${PHASE}: signal file missing" >&2; exit 1; }

PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
[[ -n "$PLUGIN_ROOT" ]] || PLUGIN_ROOT="$(dirname "$(dirname "$(dirname "$(realpath "${BASH_SOURCE[0]:-$0}" 2>/dev/null || echo .)")")")"

# 0. Codified bg_job_id yield (CTL-615). If the signal file's bg_job_id
#    names a DIFFERENT live bg job, we are a redispatch duplicate of a
#    still-running canonical worker. Bow out without touching the signal,
#    without emitting any phase event. Encodes operator memories
#    #43/#44/#49/#50 — the playbook is now code. phase-implement carries
#    the highest blast radius (commits land here), so it gets the gate
#    even though the template inheritance also provides it.
YIELD_CHECK="${PLUGIN_ROOT}/scripts/phase-agent-yield-check.sh"
if [[ -x "$YIELD_CHECK" ]] && bash "$YIELD_CHECK" \
     --signal "$SIGNAL_FILE" \
     --phase "$PHASE" \
     --worker-dir "$(dirname "$SIGNAL_FILE")"; then
  echo "phase-${PHASE}: yielding to canonical worker (CTL-615)" >&2
  exit 0
fi

# 1. Join the shared comms channel (best-effort).
COMMS="${PLUGIN_ROOT}/scripts/catalyst-comms"
[[ -x "$COMMS" ]] || COMMS="$(command -v catalyst-comms 2>/dev/null || true)"
if [[ -n "$COMMS" && -x "$COMMS" ]]; then
  "$COMMS" join "$CHANNEL" --as "$TICKET" \
    --capabilities "phase-implement: ${TICKET}" \
    --orch "$ORCH_ID" --parent orchestrator --ttl 3600 >/dev/null 2>&1 || true
  "$COMMS" send "$CHANNEL" "phase-implement started" --as "$TICKET" --type info \
    --orch "$ORCH_ID" >/dev/null 2>&1 || true
fi

# 2. Start a catalyst-session for cost/token instrumentation.
SESSION_SCRIPT="${PLUGIN_ROOT}/scripts/catalyst-session.sh"
if [[ -x "$SESSION_SCRIPT" ]]; then
  CATALYST_SESSION_ID=$("$SESSION_SCRIPT" start \
    --skill "phase-implement" \
    --ticket "$TICKET" \
    --workflow "${CATALYST_SESSION_ID:-}")
  export CATALYST_SESSION_ID
fi

# 3. Mark the signal file as running + persist catalystSessionId (CTL-496:
#    orchestrate-roll-usage --phase reads this to attribute cost).
TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
TMP="${SIGNAL_FILE}.tmp.$$"
jq --arg ts "$TS" --arg sid "${CATALYST_SESSION_ID:-}" '
  .status = "running"
  | .updatedAt = $ts
  | if $sid != "" then .catalystSessionId = $sid else . end
' "$SIGNAL_FILE" > "$TMP" \
  && mv "$TMP" "$SIGNAL_FILE"

# CTL-587: test-kill after-prelude. Exits AFTER the signal is flipped to
# running (so classifyWorker sees a non-terminal worker) but BEFORE any
# commit work, so reclaimDeadWorkIfPossible's implement-probe returns false
# on the next staleness tick and the revive path engages. Mode suffix
# `${PHASE}:after-prelude` keeps the env var phase-agnostic — only the
# matching phase aborts.
if [[ "${CATALYST_TEST_KILL_PHASE:-}" == "${PHASE}:after-prelude" ]]; then
  echo "[CTL-587 test-kill] aborting after prelude" >&2
  exit 137
fi

# 4. Locate the approved plan. The dispatcher already validated this glob;
#    we re-resolve to capture the actual filename for the delegated skill.
TICKET_LC="$(printf '%s' "$TICKET" | tr '[:upper:]' '[:lower:]')"
shopt -s nullglob
PLAN_MATCHES=( thoughts/shared/plans/*-"${TICKET_LC}".md )
shopt -u nullglob
[[ ${#PLAN_MATCHES[@]} -gt 0 ]] || { echo "no plan found for ${TICKET} under thoughts/shared/plans/" >&2; exit 1; }
PLAN_PATH="${PLAN_MATCHES[0]}"
echo "phase-implement: plan = ${PLAN_PATH}"

# 5. Linear status is written by the coordinator (CTL-558): the execution-core
#    scheduler / orchestrate-phase-advance applies the `Implement` state when
#    it commits the implement-phase transition. The phase agent no longer
#    transitions Linear itself.

/goal condition

Transcript-evaluable so a /goal evaluator (which only sees Claude's text output, not the filesystem) can decide pass/fail from what the agent prints. Plan §"Per-phase /goal conditions":

/goal "I have run /catalyst-dev:implement-plan on ${PLAN_PATH} to completion
       AND `git diff <base>..HEAD` on this branch is non-empty AND the targeted
       tests pass (I have printed the test command + `exit 0` to my transcript);
       (Linear status is written by the coordinator — CTL-558 — not this agent.)"

Phase-specific work

1. Invoke the canonical implementation skill via the Task tool. It owns TDD, quality gates,

agent-team mode (--team), findings collection, and the per-phase commit cadence:

`` Use the Task tool to launch /catalyst-dev:implement-plan on PLAN_PATH. Pass through any --team flag if the caller set CATALYST_IMPLEMENT_TEAM=1 in the env. Wait for completion and surface its stdout summary. ``

The canonical skill is responsible for committing each plan phase as a discrete commit AND for running the post-implementation quality gates (/validate-type-safety, /security-review, code-reviewer agent, pr-test-analyzer agent). phase-implement does NOT add commits or gates of its own. If implement-plan exits with errors, the failure-handling block below runs.

1. After the delegated skill returns, print a one-line summary to stdout so the /goal evaluator

has signal that the work landed:

``bash git diff --stat "$(git merge-base HEAD main)..HEAD" # base depends on the # worktree's tracking ``

1. When the broader plan's Phase 4 (CTL-450) introduces dedicated phase-verify and phase-review

agents, this skill will pass --skip-quality-gates to implement-plan so those concerns move into their own phase agents (plan §"Phase agents wrap canonical skills"). For the MVP this skill runs the gates inline via implement-plan because no phase-verify exists yet — the cutover is a one-line change to the Task invocation when that phase lands.