plan-updater-skill

What I do

I provide automatic PLAN.md synchronization for any workflow that implements developer code:

1. Detect Branch Reference: Extract issue/ticket number from current branch name
2. Find PLAN File: Locate matching PLAN file in PLANS/ directory
3. Update Progress: Mark checkboxes as complete based on recent commits
4. Commit Changes: Commit with semantic message format
5. Graceful Skip: Skip silently when no PLAN file exists

When to use me

Use this skill when:

• Your subagent implements code changes (refactoring, testing, features)
• You're about to create a PR and want PLAN.md to reflect current state
• You've completed a significant milestone in development
• You want to maintain traceability between commits and plans

Trigger phrases:

• "update plan"
• "sync plan"
• "update PLAN.md"
• "mark plan progress"

Subagents That Should Use This Skill

Subagent	When to Invoke
pr-workflow-subagent	Before creating PR (step 3.5)
code-review-subagent	After completing refactoring
testing-subagent	After creating tests
ticket-plan-workflow-skill	After initial PLAN creation

Core Workflow

Step 1: Detect Branch Reference

Extract issue/ticket number from branch name:

Supported Branch Patterns:

• GIT-123 - GitHub issue (preferred)
• issue-123 - GitHub issue (legacy)
• 123 - GitHub issue (legacy)
• PROJECT-123 - JIRA ticket

BRANCH_NAME=$(git branch --show-current)

# GitHub pattern: GIT-123
if [[ "$BRANCH_NAME" =~ ^GIT-([0-9]+)$ ]]; then
  ISSUE_NUM="${BASH_REMATCH[1]}"
  PLAN_TYPE="github"
  PLAN_ID="$ISSUE_NUM"
fi

# Legacy GitHub pattern (backwards compatibility): issue-123 or 123
if [[ "$BRANCH_NAME" =~ ^issue-([0-9]+)$ ]] || [[ "$BRANCH_NAME" =~ ^([0-9]+)$ ]]; then
  ISSUE_NUM="${BASH_REMATCH[1]}"
  PLAN_TYPE="github"
  PLAN_ID="$ISSUE_NUM"
fi

Step 2: Find PLAN File

Locate the matching PLAN file:

# GitHub convention
GITHUB_PLAN="PLANS/PLAN-GIT-${ISSUE_NUM}.md"

# JIRA convention
JIRA_PLAN="PLANS/PLAN-${PLAN_ID}.md"

# Check which exists
if [ -f "$GITHUB_PLAN" ]; then
  PLAN_FILE="$GITHUB_PLAN"
elif [ -f "$JIRA_PLAN" ]; then
  PLAN_FILE="$JIRA_PLAN"
else
  echo "No PLAN file found for branch: $BRANCH_NAME"
  echo "Skipping PLAN.md update (graceful skip)"
  exit 0
fi

echo "Found PLAN file: $PLAN_FILE"