1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
|
#+TITLE: Rename an .ai Artifact
#+AUTHOR: Craig Jennings & Claude
#+DATE: 2026-05-31
* Summary
Rename a workflow or a script that lives in the =.ai/= tree, without leaving the canonical copy, the mirror copy, the INDEX, or any reference behind. The work is mechanical and easy to do incompletely by hand — a missed reference or a forgotten mirror copy is the classic failure. The =rename-ai-artifact.sh= script does it the same way every time, so reach for the script rather than renaming files by hand.
Quick contract — what it does:
- Moves the artifact in both =claude-templates/.ai/= (canonical) and =.ai/= (mirror), in lockstep.
- Rewrites every reference to the artifact's stem, repo-wide, on a token boundary so renaming =foo= can't corrupt =foobar= or =foo-bar=.
- Rewrites the underscore module-name variant too — a hyphenated script imported as =foo_bar= via importlib, not just the =foo-bar.py= path.
- Leaves =sessions/= (both trees) untouched — archived session records are history.
- Runs =workflow-integrity.py= and =sync-check.sh= afterward to prove no drift.
* Execution
Run once per file. For a family (a workflow plus its helper scripts), run it once per artifact; order doesn't matter because reference matching is token-bounded.
#+begin_example
scripts/rename-ai-artifact.sh OLD-BASENAME NEW-BASENAME
# examples
scripts/rename-ai-artifact.sh old-workflow.org new-workflow.org
scripts/rename-ai-artifact.sh old-helper.py new-helper.py
#+end_example
After the last file in a family is renamed, review =git status= and the diff, then commit through the normal publish flow.
* Reference
** When to use
Any time an =.ai/= workflow or script changes name. Also the right tool when only the *concept* is being renamed and you want every trigger phrase, =file:= link, and prose mention updated to match.
** What it will not do
- It won't touch =sessions/= records (history stays accurate to when it was written).
- It won't rename across directories — the artifact keeps its home directory; only the basename changes.
- It renames one artifact per call and refuses if the source is missing or the target name already exists.
** If a verify step reports drift
The script still completes the rename, then warns. Read the =workflow-integrity= / =sync-check= output, fix by hand (usually a stale INDEX row the stem rewrite didn't reach because the row used different wording), and re-run the checks before committing.
|
