| name | artgraph-rename |
| description | Performs a safe rename / split / merge of requirement IDs across spec, code, tests, and lock. Use when the user asks to rename a REQ ID, split one ID into multiple, or merge multiple IDs into one. Make sure to use this skill whenever requirement IDs are being restructured. |
| allowed-tools | ["Bash(npx artgraph *)","Bash(npx --no-install artgraph *)","Bash(pnpm exec artgraph *)","Bash(bunx artgraph *)","Bash(bunx --no-install artgraph *)","Bash(deno run -A npm:artgraph/cli *)","Bash(artgraph *)","Bash(git status*)"] |
| user-invocable | true |
| disable-model-invocation | false |
Purpose
The agent runs artgraph rename (or its --split / --merge variants) to safely rewrite a requirement ID across spec lists/headings, @impl tags, test [ID] tags, frontmatter depends_on / derives_from, and .trace.lock. The operation is destructive and writes directly to tracked files — always run --dry-run first.
Exit code 1 does not always mean "it failed." rename also exits 1 on a
partial success: the rewrite is complete and correct, but some reference it
cannot reach was left behind (a task's requirement list — see step 3). Read
the output, not just the status, in both --dry-run and apply mode.
Preconditions
- Working tree must be committed —
artgraph rename writes directly to tracked files, and an uncommitted state makes the change irreversible.
- Target IDs must be in a form artgraph re-scans:
REQ-001, auth/FR-2, doc:xxx. Forms like REQ-COMBINED or REQ-001a are rejected.
Steps
1. Prerequisite check
See install-check for the standard pre-flight check. If artgraph is not installed, stop and invoke the artgraph-setup Skill instead.
<PM-exec> is the project's package runner: npx (npm), pnpm exec, bunx, or deno run -A npm:artgraph/cli. Substitute the one detected by _shared/package-manager.md (or written in .artgraph.json#packageManager).
2. Confirm git is clean
git status --porcelain
The output must be empty. If anything is listed, instruct the user to commit (or stash) before continuing — rename mutates tracked files in place and a dirty tree mixes manual edits with the rewrite.
3. Dry-run the rewrite
Pick the command shape that matches the user's intent and add --dry-run:
<PM-exec> rename --from REQ-001 --to REQ-100 --dry-run
<PM-exec> rename --split REQ-001 --into REQ-101 REQ-102 --dry-run
<PM-exec> rename --merge REQ-001 REQ-002 --into REQ-100 --dry-run
The dry-run prints the files, lines, and lock keys that will change. Show the diff summary to the user and get explicit confirmation before applying.
Check the exit code, and do not read it as pass/fail. --dry-run writes
nothing, yet it can still exit 1:
| exit | output | meaning | what to do |
|---|
| 0 | the preview | the rewrite reaches everything | proceed to step 4 |
| 1 | { "error": ... } (or an ERROR: line) | validation failed, nothing was previewed | fix the input; do NOT apply |
| 1 | the normal preview plus one or more WARNING: lines | partial success ahead — the rewrite is correct as far as it goes, but some references will be left pointing at the old ID | show the warnings to the user, then decide together whether to apply |
The last row is the one that trips scripts. The usual cause is a task's
requirement list (e.g. Kiro's _Requirements: 1.1, 2.3_ in tasks.md), which
rename does not rewrite; with --format json it appears as
warnings[].type === "unrewritten-task-requirement-ref" with the exact file
paths. Never treat --dry-run's exit code alone as "the rename is unsafe" —
distinguish the rows above by whether an error envelope or a preview was
printed.
4. Apply
Re-run the same command without --dry-run. The lock is auto-reconciled — contentHash, references, and specFile for the rewritten nodes are refreshed in .trace.lock.
The apply run exits 1 under the same partial-success condition as step 3,
after the files are already written. That is not a rollback signal: fix the
references the warning names by hand (renumber the task's requirement list to
match the new ID), then run <PM-exec> reconcile and continue.
5. Follow-up
For split and merge, additional manual work is required (new @impl assignments, scaffold TODO lines, leftover sub-bullets from old headings). See lifecycle-flows for the full handling.
For a plain rename, no follow-up edits are needed.
6. Re-check
<PM-exec> check
- rename and merge should pass immediately.
- split leaves the new IDs as
uncovered until @impl is added at the candidate files. Re-run <PM-exec> check after assigning the tags.
Output format
Pass --format json for scripted use; on error the payload is { "error": "..." }. See output schema for the success shape of artgraph rename.
