AI agent skill · by @PiLastDigit

TRIP Upgrade

Upgrade TRIP workflow skills to a newer version while preserving project customizations

Archived 2026-10-23 · Source updated 2026-09-24. Check the original repository for the latest version.

SKILL.md instructions

# TRIP Upgrade Mode

You are now in **upgrade mode** — merging a newer version of the TRIP workflow into this project's existing, customized TRIP skills.

## The Problem

Each project's TRIP skills have two interleaved layers:
1. **Workflow skeleton** — steps, Codex integration, file structure, process flow
2. **Project customizations** — test commands, checklist sections, version file, technical considerations, guidance sections

A naive copy would destroy layer 2. This skill recovers the **generic template the project was installed from**, computes the project's customizations as a diff against it, and replays that diff onto the new template with a git three-way merge — one command per file, exact, and verifiable. Manual extraction of the customizations remains as the path for pre-2.8.1 installs, which carry no version stamp.

## Prerequisites

Nothing to copy. The skill fetches the TRIP-workflow repository itself and upgrades to its **latest release** by default.

`$ARGUMENTS`, optional:
- a **version** (`2.9.0` or `v2.9.0`) pins the target release instead of the latest;
- a **path** to a local `skills/` folder (a fork, an offline copy) is used as the staged source instead of fetching. In that case the base template (Phase 2) still needs the clone; without network, use the Fallback path.

---

## Phase 1: Inventory

### 1.1 Fetch the Latest Release

One clone serves the whole upgrade — it provides the new skills now and the base template in Phase 2:

```bash
TRIP_SRC=$(mktemp -d)
git clone -q --no-checkout https://github.com/PiLastDigit/TRIP-workflow "$TRIP_SRC"
TARGET=$(git -C "$TRIP_SRC" tag --list 'v*' --sort=-v:refname | head -1)   # or v$ARGUMENTS when a version was given
S=$(mktemp -d); git -C "$TRIP_SRC" archive "$TARGET" skills | tar -x -C "$S" --strip-components=1
```

`$S` is the **staged** source for the rest of this skill. If a path was passed instead, `S=<that path>` and skip the archive. If the clone fails (offline, no access), tell the user and stop — or take the Fallback path with a local folder.

### 1.2 Detect Versions

Since v2.8.1 every `SKILL.md` carries `metadata.trip-version` in its frontmatter. Read both sides:

```bash
# Installed (one line per distinct version; more than one line = a mixed install)
grep -h "^  trip-version" .claude/skills/*/SKILL.md | sort | uniq -c

# Staged
grep -h "^  trip-version" "$S"/*/SKILL.md | sort -u
```

- **Field present on both sides**: report `installed X → target Y`. If X equals Y, tell the user the project is already on the latest release and stop; remove `$TRIP_SRC` and `$S`.
- **Field missing in the installed copy**: the install predates v2.8.1. Describe it from structural hints — `--speedrun` in TRIP-1-plan = 2.7.x, `checklist.md` + `TRIP-3-release` present = v2, `codex-*` skills absent = v1 — and plan on the **Fallback: Manual Extraction** path, since no base template can be fetched.
- **Mixed versions**: list the outliers; they are usually skills skipped in a previous upgrade and should be merged like any other.

### 1.3 Categorize Skills

List all skill folders in both locations:

```bash
# Currently installed
ls -d .claude/skills/*/

# New (staged)
ls -d "$S"/*/
```

Categorize each skill into one of:

| Category | Meaning | Action |
|----------|---------|--------|
| **New** | Exists in `$S` only | Copy directly |
| **Removed** | Exists in installed only | Warn user, leave in place |
| **Unchanged** | Identical in both | Skip |
| **Updated — pure workflow** | Changed, but no project customizations | Replace directly |
| **Updated — customized** | Changed, AND contains project-specific content | Extract → merge → replace |

**Pure workflow skills** (no project customizations): `TRIP-compact`, `TRIP-hotfix`, `TRIP-research`, `TRIP-init`, `codex-implement`, `codex-plan-review`, `codex-code-review`

**Exception — model defaults**: `codex-plan-review/scripts/_common.sh` holds the per-flow Codex model/effort/service-tier defaults, which the user may have tuned. Before replacing, diff the installed `_common.sh` against staging — if the model/effort/tier values differ from the generic defaults, carry the user's values into the new file.

**Customized skills** (have project-specific content): `TRIP-1-plan`, `TRIP-2-implement`, `TRIP-3-release`, `TRIP-review`, `TRIP-test`

**Renamed in TRIP v2** — when the installed folder uses an old name, treat it as the same skill under its new name (merge into the new name, then delete the old folder):

| Installed (old) | Target (new) |
|---|---|
| `TRIP-3-review` | `TRIP-review` |
| `TRIP-4-test` | `TRIP-test` |

`TRIP-3-release` is **new in v2** but its project values (version file, week anchor, tutorial config) are **extracted from the old `TRIP-2-implement`'s post-implementation steps** — categorize it as customized even though no folder exists yet.

**Other non-TRIP skills** in `$S` (e.g. future additions): Treat as new, or as pure workflow if they already exist.

For each skill, diff the installed vs new version to confirm whether it actually changed:

```bash
diff -rq .claude/skills/<skill>/ "$S"/<skill>/
```

### 1.4 Present Inventory

Show the version line, then a summary table to the user:

```
TRIP 2.7.4 → 2.8.1 (installed version read from metadata.trip-version)

Skill                 | Status              | Action
--------------------- | ------------------- | ------
TRIP-1-plan           | Updated (customized) | Extract + merge
TRIP-2-implement      | Updated (customized) | Extract + merge
TRIP-3-release        | New (customized)     | New template + values from old TRIP-2
TRIP-review           | Renamed + updated    | Extract + merge, delete TRIP-3-review/
TRIP-test             | Renamed + updated    | Extract + merge, delete TRIP-4-test/
TRIP-compact          | Unchanged            | Skip
TRIP-hotfix           | Unchanged            | Skip
TRIP-init             | Updated (pure)       | Replace
TRIP-research         | Unchanged            | Skip
codex-plan-review     | New                  | Copy
codex-code-review     | New                  | Copy
codex-implement       | New                  | Copy
```

`AskUserQuestion`: "Here's the upgrade plan. Proceed?"
Options: "Yes, start upgrade" (recommended) / "Let me review the new files first" / "Abort"

---


## Phase 2: Obtain the Base Template

The merge needs the **generic skills of the version currently installed** (the "base"). The project never holds them — only the customized copy — so fetch them from the TRIP-workflow repository.

### 2.1 Reuse the Clone

`$TRIP_SRC` from Phase 1.1 already holds every release tag:

```bash
git -C "$TRIP_SRC" tag --sort=-v:refname | head -20
```

### 2.2 Identify the Base Tag

The base tag is `v<installed trip-version>` from Phase 1.2. **No stamp means a pre-2.8.1 install**: the base cannot be named with certainty, so skip to **Fallback: Manual Extraction** below. This happens once per project — every install from 2.8.1 on carries the stamp.

```bash
BASE=$(mktemp -d)
git -C "$TRIP_SRC" archive "v$INSTALLED_VERSION" skills | tar -x -C "$BASE" --strip-components=1
```

### 2.3 Report

> "Base template v2.8.2 fetched. Upgrading v2.8.2 → v2.9.0."

---

## Phase 3: Three-Way Merge

For **every file in `$S`**, state folders excluded, decide by presence:

| Installed | Base | Action |
|---|---|---|
| yes | yes | `git merge-file -p installed base staged` → merged file |
| yes | no | file is new upstream but the project also has one: merge with an empty base (`git merge-file -p installed /dev/null staged`) |
| no | — | copy staged |
| (installed only) | — | leave in place, list as "Removed upstream" |

Build everything in a scratch directory first; nothing under `.claude/skills/` changes until Phase 4 passes.

```bash
MERGED=$(mktemp -d); I=.claude/skills   # $S = staged source from Phase 1.1
( cd "$S" && find . -type f -not -path '*/state/*' ) | sed 's|^\./||' | while read -r f; do
  mkdir -p "$MERGED/$(dirname "$f")"
  if [ -f "$I/$f" ]; then
    b="$BASE/$f"; [ -f "$b" ] || b=/dev/null
    git merge-file -p -L installed -L base -L staged "$I/$f" "$b" "$S/$f" > "$MERGED/$f" || echo "CONFLICT $f"
  else
    cp "$S/$f" "$MERGED/$f"
  fi
done
grep -rl '^<<<<<<< ' "$MERGED" || echo "no conflicts"
```

**Conflicts** happen only where a workflow change and a customization touch the same lines. Open the marked region, keep the new workflow text and re-apply the project's intent inside it, remove the markers. Never resolve by taking one side wholesale.

**Renamed skills** (`TRIP-3-review` → `TRIP-review`, `TRIP-4-test` → `TRIP-test`): treat the old folder as the installed side of the new name, then delete the old folder in Phase 5. **`TRIP-3-release` on a v1 install**: no installed side exists; copy staged and fill its placeholders from the old `TRIP-2-implement` post-implementation steps (see the Fallback section for what to look for).

---

## Phase 4: Review and Validate

### 4.1 Prove the Merge

Two diffs per merged file, both must be short and readable:

```bash
# what the project customized — must contain ONLY project-specific content
diff "$S/$f" "$MERGED/$f"
# what the upgrade changes — must contain ONLY workflow changes (and the new frontmatter)
diff "$I/$f" "$MERGED/$f"
```

Read both for every customized skill (`TRIP-1-plan`, `TRIP-2-implement`, `TRIP-3-release`, `TRIP-review/*`, `TRIP-test`) and for any pure skill whose first diff is not empty — a project sometimes tweaks a "pure" skill by a line, and the merge carries that over. A customization appearing in the second diff as a removal, or workflow text appearing in the first diff, means the merge went wrong for that file — fix it before continuing.

### 4.2 Placeholder Check

Scan the merged files for leftover placeholders:

```bash
grep -rn --exclude-dir=TRIP-init --exclude-dir=TRIP-upgrade '\[ADAPT_TO_PROJECT\|\[PROJECT_NAME\]\|\[VERSION_FILE\]\|\[WEEK_ANCHOR_DATE\]\|\[TEST_COMMAND\]\|\[LINT_COMMAND\]\|\[TYPECHECK_COMMAND\]\|\[TUTORIAL_STEP\]\|\[MAIN_BRANCH\]' "$MERGED"/TRIP-*/
```

`TRIP-init` and `TRIP-upgrade` mention every placeholder by name in their own instructions, so they are excluded.

If any are found, fill them from context or ask the user.

### 4.3 Cross-Reference Check

- `checklist.md` section names must match `cr-template.md` checklist section names
- `codex-code-review/prompts/start.tpl` and `resume.tpl` reference `.claude/skills/TRIP-review/checklist.md` — confirm it exists, and that no template still points at the old `TRIP-3-review/` path
- `codex-code-review/prompts/synthesize.tpl` and `codex-code-review/SKILL.md` reference `.claude/skills/TRIP-review/cr-template.md` — confirm it exists
- `TRIP-1-plan` references `codex-plan-review/scripts/start.sh` and `resume.sh`; `TRIP-2-implement` and `TRIP-research` invoke each skill's own wrapper scripts — confirm `codex-implement`, `codex-code-review`, and `codex-ask` each ship `scripts/{start,resume,reset,show}.sh` (they pin `STATE_DIR` and delegate to `codex-plan-review`), and that `codex-plan-review/scripts/key.sh` exists

### 4.4 Present Summary

Show what changed:

```
Upgrade complete:
- New skills added: [list]
- Skills updated: [list]
- Skills unchanged: [list]
- Project customizations preserved: [list key ones]
```

Run the version-stamp check from **Frontmatter and Version Stamp** on `$MERGED`.

`AskUserQuestion`: "Merge verified. Apply to .claude/skills/?"
Options: "Apply" (recommended) / "Show me the diffs first" / "Abort"

If "Show me the diffs first": present the Phase 4.1 diffs. If "Abort": remove the scratch directories, nothing was changed.

---

## Phase 5: Apply and Clean Up

```bash
# copy merged files over the install; state/ folders are never touched
rsync -a --exclude 'state/' "$MERGED"/ .claude/skills/
```

Then delete renamed-away folders (`TRIP-3-review/`, `TRIP-4-test/`) if any, remove the scratch directories (`$TRIP_SRC`, `$S` unless it is a user-supplied path, `$BASE`, `$MERGED` — use `trash-put` where available, otherwise `rm -r`), and confirm the stamp once more on the live install:

```bash
grep -h "^  trip-version" .claude/skills/*/SKILL.md | sort | uniq -c
```

Report:
> "TRIP workflow upgraded vX → vY. N files merged, M copied, 0 conflicts. `git diff .claude/skills/` shows the change before you commit."

---

## Fallback: Manual Extraction

Use this path when the installed skills carry no `metadata.trip-version` (pre-2.8.1 install). It needs a staged source `$S` — the fetched release from Phase 1.1, or a local folder passed as argument. It rebuilds each customized skill from the new template by hand.

### F.1 Extract Project Context

Before touching any installed files, read every customized skill and extract all project-specific values into a context block. This is your safety net — everything here gets re-injected later.

#### F.1.1 Read All Installed Skills

Read every file in the installed skills directory that will be affected.

#### F.1.2 Extract Customizations

Build a context block by extracting these values from the installed skills:

**From TRIP-1-plan/SKILL.md:**
- `PROJECT_NAME` — the text that replaced `[PROJECT_NAME]` (appears in the `# Planning Mode` header and `**planning mode** for` line)
- `TECHNICAL_CONSIDERATIONS` — the full content of the `## Technical Considerations` section in the plan template (everything between `## Technical Considerations` and the next `##` heading)
- `GUIDANCE_SECTIONS` — everything after the plan template's closing section that replaced `[ADAPT_TO_PROJECT: Guidance Sections]` (project-specific per-component guidance at the bottom of the file)
- `DOC_IMPACT_CANDIDATES` — the candidates list inside the plan template's `## Documentation Impact` section, if present (may not exist in pre-v2.5 installs)
- `PLAN_PREREQUISITES` — any additional living-docs lines in the Prerequisites list beyond ARCHI.md, if present

**From TRIP-2-implement/SKILL.md** (in v1 installs, the release values below live in its Post-Implementation steps; in v2 installs they live in `TRIP-3-release/SKILL.md`):
- `PROJECT_NAME` — (confirm matches TRIP-1-plan)
- `VERSION_FILE` — the text that replaced `[VERSION_FILE]` in Step 2
- `WEEK_ANCHOR_DATE` — the date that replaced `[WEEK_ANCHOR_DATE]` in Step 1
- `TUTORIAL_CONFIG` — if tutorials are enabled: the full Tutorial step block with user context. If disabled: note "tutorials disabled"
- `LINT_COMMAND` — if present (may not exist in older versions)
- `TYPECHECK_COMMAND` — if present
- `TEST_COMMAND` — if present

**From TRIP-review/SKILL.md — or `TRIP-3-review/` in v1 installs (checklist.md if already split):**
- `REVIEW_CHECKLIST` — the full checklist content. In older versions this is inline in SKILL.md. In newer versions it's in `checklist.md`. Extract it wherever it lives.
- `CR_TEMPLATE` — if `cr-template.md` exists, extract it. Otherwise note "no template file — using inline template"

**From TRIP-test/SKILL.md — or `TRIP-4-test/` in v1 installs:**
- `TEST_COMMANDS` — the full Commands section
- `TEST_STRUCTURE` — the test structure description
- `TESTING_PRIORITIES` — the full testing priorities section

#### F.1.3 Present Extracted Context

Show the user a summary of what was extracted:

```
Extracted project context:
- Project name: [name]
- Version file: [path]
- Week anchor: [date]
- Tutorials: [enabled/disabled]
- Test commands: [lint] / [typecheck] / [test]
- Checklist sections: [count] sections ([list names])
- Guidance sections: [count] sections ([list names])
- Technical considerations: [count] items
```

`AskUserQuestion`: "Extracted project context looks correct?"
Options: "Yes, continue" / "No, let me correct something"

If "No": let the user specify corrections, update the context block.

---


### F.2 Handle Structural Migrations

Before merging, handle any structural changes between the old and new workflow versions. Read both old and new files to detect what changed structurally.

#### F.2.1 Checklist Extraction (TRIP-review)

**Old structure** (early v1): Checklist inline in `TRIP-3-review/SKILL.md`
**New structure** (v2): Checklist in separate `TRIP-review/checklist.md`, template in `TRIP-review/cr-template.md` (late-v1 installs have these same files under `TRIP-3-review/`)

If the installed version has the checklist inline in SKILL.md (no separate `checklist.md`):
1. The extracted `REVIEW_CHECKLIST` from F.1 is the project-customized checklist
2. It will be injected into the new `checklist.md` in F.3

If the installed version already has `checklist.md`:
1. The extracted content is already in the right format
2. Merge normally in F.3

#### F.2.2 Codex Integration (TRIP-1-plan, TRIP-2-implement)

**Old structure**: No Codex review steps
**New structure**: TRIP-1-plan has Step 3 (Codex plan review), TRIP-2-implement has Codex Code Review section

These are pure workflow additions — no project-specific content to migrate. They will be applied from the new template. The only project-specific part is the test commands in TRIP-2-implement's Codex pre-step, which come from the extracted context.

#### F.2.3 Codex Skills (codex-plan-review, codex-code-review, codex-implement)

If not installed yet, these are entirely new — copy from `$S` directly. The review skills reference `TRIP-review/checklist.md` and `TRIP-review/cr-template.md`, which will be populated with project content. If already installed (late-v1), replace as pure workflow (see the `_common.sh` exception in Phase 1.3) — v1 prompt templates point at the old `TRIP-3-review/` paths and must be replaced with the v2 versions.

---


### F.3 Customized Skills — Rebuild From Template

For each customized skill, take the **new template** from `$S` and inject the **extracted project context** from Phase 2. 

**General approach**: Read the new template file. Find each placeholder or generic section. Replace with the corresponding extracted value. Write the result.

#### TRIP-1-plan/SKILL.md

1. Start from the new template (`$S`)
2. Replace `[PROJECT_NAME]` with extracted `PROJECT_NAME`
3. Replace the generic `## Technical Considerations` block in the plan template with extracted `TECHNICAL_CONSIDERATIONS`
4. Replace the `[ADAPT_TO_PROJECT: Guidance Sections]` comment block with extracted `GUIDANCE_SECTIONS`
5. Resolve the `[ADAPT_TO_PROJECT]` marker in the `## Documentation Impact` section: use extracted `DOC_IMPACT_CANDIDATES` if present; otherwise build the list from the project's living docs (README, module READMEs, operations/user manuals, reference specs next to the code, contributor guides), one bullet per doc with when it's affected
6. Resolve the `[ADAPT_TO_PROJECT]` line in the Prerequisites list: use extracted `PLAN_PREREQUISITES` if present; otherwise list any living docs a plan must respect beyond ARCHI.md, or delete the line if there are none

#### TRIP-2-implement/SKILL.md

1. Start from the new template (`$S`)
2. Replace `[PROJECT_NAME]` with extracted `PROJECT_NAME`
3. Replace `[LINT_COMMAND]`, `[TYPECHECK_COMMAND]`, `[TEST_COMMAND]` in the Testing Gate with extracted commands
   - If the old version didn't have Codex review (no test commands extracted), check the old TRIP-4-test for test commands, or ask the user
4. Adapt the Integration impact check comment block to the project's integration/E2E tooling (from the old TRIP-4-test content if present)

#### TRIP-3-release/SKILL.md (new in v2 — values come from the old TRIP-2)

1. Start from the new template (`$S`)
2. Replace `[PROJECT_NAME]` with extracted `PROJECT_NAME`
3. Replace `[VERSION_FILE]` with extracted `VERSION_FILE`
4. Replace `[WEEK_ANCHOR_DATE]` with extracted `WEEK_ANCHOR_DATE`
5. Replace `[MAIN_BRANCH]` with the repo's default branch name
6. Replace the standalone-verification commands with the same extracted lint/typecheck/test commands
7. Handle tutorial config:
   - If tutorials were disabled: remove the `[TUTORIAL_STEP]` block
   - If tutorials were enabled: replace the `[TUTORIAL_STEP]` block with extracted `TUTORIAL_CONFIG` and renumber subsequent steps

#### TRIP-review/SKILL.md + checklist.md + cr-template.md (was `TRIP-3-review` in v1)

1. `SKILL.md`: Start from the new template. Replace `[PROJECT_NAME]`.
2. `checklist.md`: Start from the new template. Replace the `[ADAPT_TO_PROJECT]` comment block with the project-specific checklist sections from the extracted `REVIEW_CHECKLIST`.
   - The new template has generic sections 1-3 (Functional, Code Quality, Architectural) and 4-6 (Error Handling, Security, Performance). The project customization goes between section 3 and 4 (where the comment marker is), and may also modify sections 3-6.
   - If the old checklist had custom sections (numbered 4+), insert them at the `[ADAPT_TO_PROJECT]` marker and renumber if needed.
   - Preserve the Severity Classification and Approval Gate from the **new** template unless the project had custom overrides.
3. `cr-template.md`: Start from the new template. Update the Checklist section names to match the actual sections in the merged `checklist.md`.

#### TRIP-test/SKILL.md (was `TRIP-4-test` in v1)

1. Start from the new template (`$S`)
2. Replace `[PROJECT_NAME]` with extracted `PROJECT_NAME`
3. Replace `[TEST_COMMAND_*]` placeholders with extracted `TEST_COMMANDS`
4. Replace test structure placeholder with extracted `TEST_STRUCTURE`
5. Replace testing priorities placeholder with extracted `TESTING_PRIORITIES`


New skills: copy from `$S`. Pure-workflow skills: copy from `$S` with `rsync -a --exclude 'state/'` (never delete a skill folder — codex `state/` lives inside). Then continue with Phase 4.2 onward, treating the rebuilt files as `$MERGED`.

---
## Frontmatter and Version Stamp

The YAML frontmatter of every merged `SKILL.md` (`name`, `description`, `argument-hint`, `disable-model-invocation`, `metadata.trip-version`) is **pure workflow**: take it verbatim from the staged file, never from the installed copy. After the merge, verify every skill reports the staged version:

```bash
grep -h "^  trip-version" .claude/skills/*/SKILL.md | sort | uniq -c
```

Exactly one line must come back, matching the staged version. Any other line means a skill was skipped or merged from the old frontmatter — fix it before reporting completion.

---

## Edge Cases

### Installed skills have no `metadata.trip-version`
Pre-2.8.1 install. Use the structural hints from Phase 1.2 to describe the version, then take the Fallback path. The rebuilt files carry the stamp, so the next upgrade uses the merge.

### Installed TRIP-upgrade predates 2.8.4 (or does not exist — v1 installs)
The user copied this skill's folder over `.claude/skills/TRIP-upgrade/` by hand to bootstrap. That is expected: run normally. The old skill (if any) used a `new-TRIP/` staging folder — if one is present, treat it as a user-supplied `$S` path and remove it in Phase 5.

### Old version has no Codex skills at all
This is the most common upgrade path. The Codex skills are "New" — copy directly. The Codex integration in TRIP-1-plan and TRIP-2-implement comes from the new template and needs no project-specific content except test commands.

### Old version has inline checklist but no separate files
The structural migration in Phase 3.1 handles this. Extract the custom checklist content from the old SKILL.md, inject into the new `checklist.md`.

### Old version already has the new structure
Everything categorizes as "Unchanged" or minor updates. The merge is trivial.

### Project has extra custom skills not in the new workflow
These are "Removed" in the inventory — warn the user but leave them in place. Never delete skills that exist only in the installed version.

### Test commands not available anywhere
If the old version predates the Codex review pre-step and TRIP-4-test doesn't have extractable commands, ask the user:

`AskUserQuestion`: "The new workflow needs lint/typecheck/test commands for Codex code review. What are the commands for this project?"
Options: "Let me provide them" (user types commands) / "Skip for now" (leave placeholders)

---

## Notes for the Agent

- **Read before writing.** Read every file you plan to modify. Never write from memory alone.
- **Preserve semantics, not bytes.** If the old checklist had 10 custom sections, they all need to survive, even if their numbering changes.
- **New workflow features get project context.** When Codex code review is new, the test commands still need to be filled from the project's existing test setup.
- **When in doubt, ask.** If you can't confidently extract a customization, show the user the relevant section and ask what to keep.
- **Atomic application.** Build all merged content in `$MERGED` before touching `.claude/skills/`. If something goes wrong mid-merge, the installed skills are still intact.
- **Never delete a skill folder.** Codex `state/` directories live inside the skill folders and hold every past review thread. Copy over, never remove-and-copy.
- **Never delete user-created files.** If the project has extra files in a skill directory (like project-specific fixtures or notes), leave them alone.