Implement Plan

You are tasked with implementing an approved technical plan from thoughts/shared/plans/. These plans contain phases with specific changes and success criteria.

Prerequisites

# Check project setup (thoughts, CLAUDE.md snippet, config)
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/check-project-setup.sh" ]]; then
  "${CLAUDE_PLUGIN_ROOT}/scripts/check-project-setup.sh" || exit 1
fi

# Auto-discover most recent plan (workflow context + filesystem fallback)
RECENT_PLAN=""
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
  RECENT_PLAN=$("${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" recent plans)
fi
if [[ -n "$RECENT_PLAN" ]]; then
  echo "📋 Auto-discovered recent plan: $RECENT_PLAN"
else
  echo "⚠️ No recent plan found in workflow context or filesystem"
fi

Session Tracking

SESSION_SCRIPT="${CLAUDE_PLUGIN_ROOT}/scripts/catalyst-session.sh"
if [[ -x "$SESSION_SCRIPT" ]]; then
  CATALYST_SESSION_ID=$("$SESSION_SCRIPT" start --skill "implement-plan" \
    --ticket "${TICKET_ID:-}" \
    --workflow "${CATALYST_SESSION_ID:-}")
  export CATALYST_SESSION_ID
  "$SESSION_SCRIPT" phase "$CATALYST_SESSION_ID" "implementing" --phase 1
fi

Initial Response

Auto-discovery has already run in Prerequisites above. Check its output and follow this priority:

1. If user provided a plan path as parameter: Use the provided path (user override). Skip to Step 3.

2. If no parameter provided AND Prerequisites output shows a discovered plan (📋):

   • Show user the discovered plan path
   • Ask: "Proceed with this plan? [Y/n]"
   • If yes: use it and skip to Step 3
   • If no: proceed to option 3

3. If no parameter AND Prerequisites shows no plan found (⚠️):

   • List available plans from thoughts/shared/plans/
   • Show most recent 5 plans with dates and ticket numbers
   • Ask user which plan to implement
   • Wait for user input with plan path

STEP 3: Read and prepare

Once you have a plan path:

• Read the plan completely (no limit/offset)
• Check for any existing checkmarks (- [x]) to see what's done
• Read the original ticket and all files mentioned in the plan
• Extract ticket from plan frontmatter (source_ticket field) and update Linear state to stateMap.inProgress from config using Linearis CLI (run linearis issues usage for syntax). If Linearis CLI is not available, skip silently and continue implementation. Skip the status transition when CATALYST_PHASE is set — under a phase agent (e.g. phase-implement, or this skill invoked as a sub-task from phase-pr / phase-monitor-merge during PR resolution / CI fix-up loops) the deterministic coordinator (CTL-558) owns the Linear status write-back. A direct write here would regress the ticket from PR back to Implement, producing operator-visible state flicker (CTL-601). Mirrors the gate in create-pr/SKILL.md:227-232.
• Think deeply about how the pieces fit together
• Create a todo list to track your progress
• Start implementing if you understand what needs to be done

Implementation Philosophy

Plans are carefully designed, but reality can be messy. Your job is to:

• Follow TDD: write tests before implementation code in each phase
• Follow the plan's intent while adapting to what you find
• Implement each phase fully before moving to the next
• Verify your work makes sense in the broader codebase context
• Update checkboxes in the plan as you complete sections

TDD Rhythm Per Phase

For each phase, follow Red → Green → Refactor:

1. Red — Write the tests specified in the plan's "Tests First" section. Run them to confirm they fail.
2. Green — Implement the minimum code from the plan's "Implementation" section to make tests pass.
3. Refactor — Clean up while keeping tests green. Apply any refactoring notes from the plan.

This order is non-negotiable. If a phase doesn't have a "Tests First" section, write tests for the phase's expected behavior before implementing. The tests serve as executable acceptance criteria.

When things don't match the plan exactly, think about why and communicate clearly. The plan is your guide, but your judgment matters too.

If you encounter a mismatch:

• STOP and think deeply about why the plan can't be followed

• Present the issue clearly:

  Issue in Phase [N]:
  Expected: [what the plan says]
  Found: [actual situation]
  Why this matters: [explanation]
  
  How should I proceed?
  

Verification Approach

Within each phase (TDD cycle):

• Write tests first → run them → confirm they fail (Red)
• Write implementation → run tests → confirm they pass (Green)
• Refactor if needed → run tests → confirm they still pass (Refactor)

After completing a phase:

• Run the full success criteria checks (usually make check test covers everything)
• Fix any issues before proceeding
• Update your progress in both the plan and your todos
• Check off completed items in the plan file itself using Edit
• Check context usage - monitor token consumption
• Push + ensure the draft PR (phase-agent mode) — In phase-agent mode the draft PR opens at the first phase commit (see the implement-plan-draft-pr-early fence); interactive /catalyst-dev:implement-plan runs skip this automatically via the CATALYST_PHASE gate.

# CTL-783: make the PR the durable off-disk work record from the FIRST commit.
# Run after EVERY plan-phase commit: first run opens the draft PR, later runs
# just push (draft_pr_ensure is idempotent). Interactive runs (no
# CATALYST_PHASE) skip — no surprise pushes. Fail-open: never blocks the phase.
if [[ -n "${CATALYST_PHASE:-}" && -r "${CLAUDE_PLUGIN_ROOT}/scripts/lib/draft-pr.sh" ]]; then
  # shellcheck source=/dev/null
  source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/draft-pr.sh"
  if [[ "$(draft_pr_enabled)" == "true" ]]; then
    draft_pr_push || true
    draft_pr_ensure "main" "${TICKET_ID:-${CATALYST_TICKET:-}}" >/dev/null 2>&1 || true
  fi
fi

Don't let verification interrupt your flow - batch full suite runs at natural stopping points. But always run the specific tests you wrote during each Red → Green cycle.

Context Management During Implementation

Monitor context proactively throughout implementation:

After Each Phase:

✅ Phase {N} complete!

## 📊 Context Status
Current usage: {X}% ({Y}K/{Z}K tokens)

{If >60%}:
⚠️ **Context Alert**: We're at {X}% usage.

**Recommendation**: Create a handoff before continuing to Phase {N+1}.

**Why?** Implementation accumulates context:
- File reads
- Code changes
- Test outputs
- Error messages
- Context clears ensure continued high performance

**Options**:
1. ✅ Create handoff and clear context (recommended)
   - Use `/create-handoff` to generate properly formatted handoff
   - Format: `thoughts/shared/handoffs/{ticket}/YYYY-MM-DD_HH-MM-SS_description.md`
   - Includes timestamp for lexical sorting by recency
2. Continue to next phase (if close to completion)

**To resume**: Start fresh session, run `/implement-plan {plan-path}`
(The plan file tracks progress with checkboxes - you'll resume automatically)

{If <60%}:
✅ Context healthy. Ready for Phase {N+1}.

When to Warn:

• After any phase if context >60%
• If context >70%, strongly recommend handoff
• If context >80%, STOP and require handoff
• If user is spinning on errors (3+ attempts), suggest context clear

Educate About Phase-Based Context:

• Explain that implementation is designed to work in chunks
• Each phase completion is a natural handoff point
• Plan file preserves progress across sessions
• Fresh context = fresh perspective on next phase

Creating a Handoff:

When recommending a handoff, guide the user:

1. Offer to create the handoff using /create-handoff
2. Or create a manual handoff following the timestamp convention
3. Handoff filename format: `thoughts/shared/handoffs/{ticket}/YYYY-MM-DD_HH-MM-SS_descrip