Update Branch Plan — AI-Powered Checkbox Updates

Analyze recent commits and conservatively update a branch plan's checkboxes and phase status — marking tasks complete only at ≥80% confidence. Any repo.

skillportablecrossworkflow

# Update Branch Plan — AI-Powered Checkbox Updates

Analyze recent commits and update a branch plan's checkboxes intelligently and conservatively. Repository-agnostic: it reads a markdown plan and matches commits to tasks; it never invents progress.

## Arguments
$ARGUMENTS

## Modes

| Mode | Usage | Behavior |
|---|---|---|
| **Default** | `update-branch-plan` | Analyze, propose, wait for approval |
| **Auto** | `--auto` | Non-interactive (used by `smart-commit`) |
| **Final** | `--final` | Branch completion — handle deferred tasks, add summary (used by `finish-branch`) |
| **Interactive** | `--interactive` | Manual task selection |

## Workflow

### Phase 1: Detect Branch, Base & Plan

```bash
BRANCH=$(git branch --show-current)
PLAN_FILE="Docs/branches/${BRANCH//\//-}.md"
[ -f "$PLAN_FILE" ] || { echo "No branch plan at $PLAN_FILE"; exit 0; }

# Base branch — auto-detect (used only as the fallback diff range below).
if git ls-remote --heads origin develop | grep -q .; then BASE_BRANCH=develop
else BASE_BRANCH=$(git remote show origin 2>/dev/null | sed -n 's/.*HEAD branch: //p'); BASE_BRANCH=${BASE_BRANCH:-main}; fi
```

### Phase 2: Gather Context

```bash
# Commits since the plan was last touched (else since the base branch)
LAST=$(git log -1 --format=%H -- "$PLAN_FILE" 2>/dev/null || echo "")
if [ -n "$LAST" ]; then
  COMMITS=$(git log "$LAST..HEAD" --pretty=format:"- %h %s")
  FILES=$(git diff --name-only "$LAST..HEAD")
else
  COMMITS=$(git log "$BASE_BRANCH..HEAD" --pretty=format:"- %h %s")
  FILES=$(git diff --name-only "$BASE_BRANCH..HEAD")
fi

UNCHECKED=$(grep -n '\- \[ \]' "$PLAN_FILE")
CHECKED=$(grep -n '\- \[x\]' "$PLAN_FILE")
```

### Phase 3: AI Analysis

**For matching logic, read [`progress-tracking.md`](progress-tracking.md).**

For each commit: match to plan tasks by keyword, file path, and semantic similarity; mark complete only at **≥80% confidence**; update phase status (⏳ → ✅) when all of a phase's tasks are checked; generate a one-line reason for every proposed change.

### Phase 4: Present Changes (unless `--auto`)

**For the output template, read [`plan-templates.md`](plan-templates.md).** Ask (Header "Apply updates"): **Apply all (Recommended)** / **Review individually** / **Skip**.

### Phase 5: Apply Updates

Use the Edit tool: replace `- [ ] Task` with `- [x] Task` for matched tasks; update phase emojis.

### Phase 6: Commit (in its own commit)

```bash
git add "$PLAN_FILE"
git commit -m "Docs: Update branch plan checkboxes

- Marked N tasks complete
- Updated M phase statuses"
```

## Integration

- **Called by `smart-commit`** (`--auto`) after creating commits.
- **Called by `finish-branch`** (`--final`) before archiving.
- Usable standalone for a manual progress sweep.

## Conservative Principles

- Mark complete only at **≥80% confidence**.
- Leave unchecked when ambiguous.
- Provide a reason for every change.
- Keep plan updates in **separate** commits.

## Supporting Files
- [`progress-tracking.md`](progress-tracking.md) — commit→task matching, confidence rules, interactive & final modes.
- [`plan-templates.md`](plan-templates.md) — proposed-changes output, completion summary, error messages.

How to use it

Comes with the ai-devkit plugin (install — two commands). Once installed, type this in any repo:

/update-branch-plan

This skill only runs when you ask for it by name — the agent never starts it on its own. That’s the Claude Code form — in Codex, type $update-branch-plan instead, or just name the skill in plain words.

What a run looks like:

your-repo — claude

> /update-branch-plan ⏺ Comparing recent commits against the branch plan…⏺ 2 tasks matched at ≥80% confidence → checked · 1 stays open ✓ Plan updated — phase 2 of 3 complete

That’s all you do — the agent runs the whole workflow itself. Curious, or want to audit it? The playbook it follows is collapsed under Under the hood below.

See it in action

Phase 2 · Checkout

Add payment-intent creationabc123 Feat

Handle 3-D Secure challengedef456 Feat

Add charge-flow tests9c2a1b Test

Under the hood — the playbook the agent follows nothing in here is for you to run

Everything in this section is read and executed by the agent when you invoke the skill. It’s published so you can audit it, learn from it, or adapt it — not because you need to follow it yourself.

Analyze recent commits and update a branch plan's checkboxes intelligently and conservatively. Repository-agnostic: it reads a markdown plan and matches commits to tasks; it never invents progress.

Arguments#

$ARGUMENTS

Modes#

Mode	Usage	Behavior
Default	`update-branch-plan`	Analyze, propose, wait for approval
Auto	`--auto`	Non-interactive (used by `smart-commit`)
Final	`--final`	Branch completion — handle deferred tasks, add summary (used by `finish-branch`)
Interactive	`--interactive`	Manual task selection

Workflow#

Phase 1: Detect Branch, Base & Plan#

BRANCH=$(git branch --show-current)
PLAN_FILE="Docs/branches/${BRANCH//\//-}.md"
[ -f "$PLAN_FILE" ] || { echo "No branch plan at $PLAN_FILE"; exit 0; }

# Base branch — auto-detect (used only as the fallback diff range below).
if git ls-remote --heads origin develop | grep -q .; then BASE_BRANCH=develop
else BASE_BRANCH=$(git remote show origin 2>/dev/null | sed -n 's/.*HEAD branch: //p'); BASE_BRANCH=${BASE_BRANCH:-main}; fi

Phase 2: Gather Context#

# Commits since the plan was last touched (else since the base branch)
LAST=$(git log -1 --format=%H -- "$PLAN_FILE" 2>/dev/null || echo "")
if [ -n "$LAST" ]; then
  COMMITS=$(git log "$LAST..HEAD" --pretty=format:"- %h %s")
  FILES=$(git diff --name-only "$LAST..HEAD")
else
  COMMITS=$(git log "$BASE_BRANCH..HEAD" --pretty=format:"- %h %s")
  FILES=$(git diff --name-only "$BASE_BRANCH..HEAD")
fi

UNCHECKED=$(grep -n '\- \[ \]' "$PLAN_FILE")
CHECKED=$(grep -n '\- \[x\]' "$PLAN_FILE")

Phase 3: AI Analysis#

For matching logic, read progress-tracking.md.

For each commit: match to plan tasks by keyword, file path, and semantic similarity; mark complete only at ≥80% confidence; update phase status (⏳ → ✅) when all of a phase's tasks are checked; generate a one-line reason for every proposed change.

Phase 4: Present Changes (unless `--auto`)#

For the output template, read plan-templates.md. Ask (Header "Apply updates"): Apply all (Recommended) / Review individually / Skip.

Phase 5: Apply Updates#

Use the Edit tool: replace - [ ] Task with - [x] Task for matched tasks; update phase emojis.

Phase 6: Commit (in its own commit)#

git add "$PLAN_FILE"
git commit -m "Docs: Update branch plan checkboxes

- Marked N tasks complete
- Updated M phase statuses"

Integration#

Called by smart-commit (--auto) after creating commits.
Called by finish-branch (--final) before archiving.
Usable standalone for a manual progress sweep.

Conservative Principles#

Mark complete only at ≥80% confidence.
Leave unchecked when ambiguous.
Provide a reason for every change.
Keep plan updates in separate commits.

Supporting Files#

progress-tracking.md — commit→task matching, confidence rules, interactive & final modes.
plan-templates.md — proposed-changes output, completion summary, error messages.

Adapt it to another stack ready-made prompt for Claude / Codex

Adapt to your platform

Copy this prompt into Claude or Codex, fill in your stack, and it will generate an adapted version for your project.

Port an agent skill (Claude Code / Codex SKILL.md format) to my project.

Below is "update-branch-plan" from ai-devkit (origin platform: cross, portability: portable).
What it does: Analyze recent commits and conservatively update a branch plan's checkboxes and phase status — marking tasks complete only at ≥80% confidence. Any repo.

Read it, then produce an equivalent SKILL.md (plus any scripts) for MY project:
<describe your stack, conventions, and repo here>

Keep the workflow's structure and intent. Replace platform-specific tooling and references per these notes:
Already generic — it operates on a markdown branch-plan doc (Docs/branches/<branch>.md, the convention issue-to-branch establishes) using checkbox/keyword matching. The only thing to localize is the base branch, which is auto-detected. Called automatically by smart-commit (--auto) and finish-branch (--final); usable standalone.

List what you changed and why.

--- SKILL.md ---
# Update Branch Plan — AI-Powered Checkbox Updates

Analyze recent commits and update a branch plan's checkboxes intelligently and conservatively. Repository-agnostic: it reads a markdown plan and matches commits to tasks; it never invents progress.

## Arguments
$ARGUMENTS

## Modes

| Mode | Usage | Behavior |
|---|---|---|
| **Default** | `update-branch-plan` | Analyze, propose, wait for approval |
| **Auto** | `--auto` | Non-interactive (used by `smart-commit`) |
| **Final** | `--final` | Branch completion — handle deferred tasks, add summary (used by `finish-branch`) |
| **Interactive** | `--interactive` | Manual task selection |

## Workflow

### Phase 1: Detect Branch, Base & Plan

```bash
BRANCH=$(git branch --show-current)
PLAN_FILE="Docs/branches/${BRANCH//\//-}.md"
[ -f "$PLAN_FILE" ] || { echo "No branch plan at $PLAN_FILE"; exit 0; }

# Base branch — auto-detect (used only as the fallback diff range below).
if git ls-remote --heads origin develop | grep -q .; then BASE_BRANCH=develop
else BASE_BRANCH=$(git remote show origin 2>/dev/null | sed -n 's/.*HEAD branch: //p'); BASE_BRANCH=${BASE_BRANCH:-main}; fi
```

### Phase 2: Gather Context

```bash
# Commits since the plan was last touched (else since the base branch)
LAST=$(git log -1 --format=%H -- "$PLAN_FILE" 2>/dev/null || echo "")
if [ -n "$LAST" ]; then
  COMMITS=$(git log "$LAST..HEAD" --pretty=format:"- %h %s")
  FILES=$(git diff --name-only "$LAST..HEAD")
else
  COMMITS=$(git log "$BASE_BRANCH..HEAD" --pretty=format:"- %h %s")
  FILES=$(git diff --name-only "$BASE_BRANCH..HEAD")
fi

UNCHECKED=$(grep -n '\- \[ \]' "$PLAN_FILE")
CHECKED=$(grep -n '\- \[x\]' "$PLAN_FILE")
```

### Phase 3: AI Analysis

**For matching logic, read [`progress-tracking.md`](progress-tracking.md).**

For each commit: match to plan tasks by keyword, file path, and semantic similarity; mark complete only at **≥80% confidence**; update phase status (⏳ → ✅) when all of a phase's tasks are checked; generate a one-line reason for every proposed change.

### Phase 4: Present Changes (unless `--auto`)

**For the output template, read [`plan-templates.md`](plan-templates.md).** Ask (Header "Apply updates"): **Apply all (Recommended)** / **Review individually** / **Skip**.

### Phase 5: Apply Updates

Use the Edit tool: replace `- [ ] Task` with `- [x] Task` for matched tasks; update phase emojis.

### Phase 6: Commit (in its own commit)

```bash
git add "$PLAN_FILE"
git commit -m "Docs: Update branch plan checkboxes

- Marked N tasks complete
- Updated M phase statuses"
```

## Integration

- **Called by `smart-commit`** (`--auto`) after creating commits.
- **Called by `finish-branch`** (`--final`) before archiving.
- Usable standalone for a manual progress sweep.

## Conservative Principles

- Mark complete only at **≥80% confidence**.
- Leave unchecked when ambiguous.
- Provide a reason for every change.
- Keep plan updates in **separate** commits.

## Supporting Files
- [`progress-tracking.md`](progress-tracking.md) — commit→task matching, confidence rules, interactive & final modes.
- [`plan-templates.md`](plan-templates.md) — proposed-changes output, completion summary, error messages.

How to use it

See it in action

Arguments#

Modes#

Workflow#

Phase 1: Detect Branch, Base & Plan#

Phase 2: Gather Context#

Phase 3: AI Analysis#

Phase 4: Present Changes (unless --auto)#

Phase 5: Apply Updates#

Phase 6: Commit (in its own commit)#

Integration#

Conservative Principles#

Supporting Files#

Adapt to your platform

Phase 4: Present Changes (unless `--auto`)#