1 +#
Shame Command Implementation Plan 3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Rename `/review` to `/shame` and replace typed targets with inferred targets, `@` paths, and argument completion.
7 +**Architecture:** Keep the extension in one implementation file. Parse flags and tokens first, then resolve tokens asynchronously against the filesystem, GitHub PR syntax, and Git refs in that order; keep completion synchronous and side-effect-free using Node filesystem APIs plus a bounded Git ref query.
9 +**Tech Stack:** TypeScript, Node 26 standard library, Pi extension API, Vitest, Pi test harness
13 +**Phase:** Single-plan implementation
17 +###
Task 1: Rename the extension 21 +- Rename: `extensions/review/` → `extensions/shame/`
22 +- Modify: `extensions/shame/package.json`
23 +- Modify: `extensions/shame/index.ts`
24 +- Modify: `extensions/shame/__tests__/harness.test.ts`
25 +- Modify: `README.md`
26 +- Modify: `CHANGELOG.md`
27 +- Modify: `package-lock.json`
29 +- [ ] **Step 1: Rename the directory and package**
34 +mv extensions/review extensions/shame
37 +Change the package name in `extensions/shame/package.json`:
40 +"name":
"@bugabinga/pi-ext-shame" 43 +Rename the exported extension function and command registration in `extensions/shame/index.ts`:
46 +export default function shameExtension(pi
: ExtensionAPI) {
47 + pi.
registerCommand(
"shame", {
49 + "Shame code. Usage: /shame [@path ...|#pr|pr-url|git-ref] [--extra <focus>]",
52 +- [ ] **Step 2: Rename test imports and the load test**
54 +Use these names in `extensions/shame/__tests__/harness.test.ts`:
57 +import shameExtension, { __test }
from "../index";
59 +describe(
"shame extension", ()
=> {
60 + it(
"loads in real Pi extension runtime",
async ()
=> {
61 + t
= await createTestSession({ extensionFactories: [shameExtension] });
62 + expect(t.session.extensionRunner.extensions).
toHaveLength(
1);
67 +- [ ] **Step 3: Update repository metadata**
69 +Replace the root README row with:
72 +| `shame` | Hostile agent code review for Pi. | [README](extensions/shame/README.md) |
75 +Replace the review changelog entry with one sentence describing `/shame`, inferred targets, `@` paths, and completion.
76 +Update `extensions/shame/README.md` to show only the approved interface from `docs/super/specs/2026-07-11-shame-command-design.md`.
77 +Regenerate workspace lock entries:
80 +npm install --package-lock-only --ignore-scripts
83 +Expected: `package-lock.json` contains `extensions/shame` and `@bugabinga/pi-ext-shame`, with no review workspace entry.
85 +- [ ] **Step 4: Run the renamed harness test**
90 +mise run test
-- extensions/shame/__tests__/harness.test.ts
93 +Expected: all existing parser and extension-load assertions pass, and no import path references `extensions/review`.
95 +- [ ] **Step 5: Commit the rename**
98 +git add CHANGELOG.md README.md package-lock.json extensions/review extensions/shame
99 +git commit -m
"refactor(shame): rename review extension" 102 +###
Task 2: Infer review targets 106 +- Modify: `extensions/shame/index.ts`
107 +- Modify: `extensions/shame/__tests__/harness.test.ts`
109 +- [ ] **Step 1: Replace parser tests with failing inferred-target tests**
111 +Expose `parseInput` and `resolveTarget` through `__test`.
112 +Add tests using a temporary Git repository created inside the harness cwd:
115 +it(
"parses @ paths and extra focus", ()
=> {
116 + expect(__test.
parseInput(
'@src @test --extra "focus auth"')).
toEqual({
117 + tokens: [
"@src",
"@test"],
118 + extra:
"focus auth",
122 +it(
"recognizes PR shorthand and URLs", ()
=> {
123 + expect(__test.
pullRequestRef(
"#123")).
toBe(
"123");
125 + __test.
pullRequestRef(
"https://github.com/acme/app/pull/42"),
126 + ).
toBe(
"https://github.com/acme/app/pull/42");
130 +Add async resolver assertions for `@src`, multiple paths, a plain existing path, a local branch, a commit SHA, a missing path, and mixed path/ref tokens.
131 +Use `pi.exec("git", ["init", "-b", "trunk"])`, configure a local test identity, create one commit, and create branch `feature`.
133 +- [ ] **Step 2: Run tests to verify failure**
138 +mise run test
-- extensions/shame/__tests__/harness.test.ts
141 +Expected: FAIL because `parseInput`, `pullRequestRef`, and `resolveTarget` do not exist.
143 +- [ ] **Step 3: Implement flag parsing and target resolution**
145 +Replace `ParsedReviewArgs` with:
148 +type ParsedInput = {
155 +Implement these functions in `extensions/shame/index.ts`:
158 +function parseInput(input
: string)
: ParsedInput;
159 +function pullRequestRef(token
: string)
: string | null;
160 +async function resolveTarget(
164 +)
: Promise<{ target
?: ReviewTarget; error
?: string }>;
167 +`parseInput` retains the existing quote-aware tokenizer and removes `--extra`/`-e` plus its value.
168 +`pullRequestRef` accepts `#` followed only by digits and `https://github.com/<owner>/<repo>/pull/<number>` URLs.
169 +`resolveTarget` performs exactly this sequence:
171 +1. Empty tokens return `smartTarget(pi)`.
172 +2. Strip one leading `@`; if any original token starts with `@` or any resulting token exists under `cwd`, require every token to exist and return one folder target containing normalized repo-relative paths.
173 +3. One PR token returns a PR target.
174 +4. One token matching `refs/heads/<token>` or `refs/remotes/<token>` through `git show-ref --verify` returns a branch target.
175 +5. One token accepted by `git rev-parse --verify <token>^{commit}` returns a commit target.
176 +6. Multiple non-path tokens return `Cannot mix paths and Git refs in one review`.
177 +7. One unresolved token returns `Cannot resolve "<token>". Try /shame @<path>, #123, a PR URL, branch, or commit`.
179 +Add an `execOk` helper that checks `pi.exec(...).code === 0`; do not parse localized Git stderr.
180 +Paths outside `cwd` after `path.resolve` must be rejected.
182 +Update the command handler:
185 +const parsed
= parseInput(args);
186 +if (parsed.error)
return ctx.ui.
notify(parsed.error,
"error");
187 +const resolved
= await resolveTarget(pi, ctx.cwd, parsed.tokens);
188 +if (
!resolved.
target) {
189 + ctx.ui.
notify(resolved.error
?? "Cannot resolve review target",
"error");
192 +const target
= resolved.
target;
195 +Keep prompt generation unchanged except `/review` wording becomes `/shame` where user-visible.
197 +- [ ] **Step 4: Run resolver tests**
202 +mise run test
-- extensions/shame/__tests__/harness.test.ts
205 +Expected: all inferred-target and existing prompt/load tests pass.
207 +- [ ] **Step 5: Commit inference**
210 +git add extensions/shame/index.ts extensions/shame/__tests__/harness.test.ts
211 +git commit -m
"feat(shame): infer review targets" 214 +###
Task 3: Add argument completion 218 +- Modify: `extensions/shame/index.ts`
219 +- Modify: `extensions/shame/__tests__/harness.test.ts`
221 +- [ ] **Step 1: Add failing completion tests**
223 +Create `src/`, `src/nested/`, and a local `feature` branch in the harness cwd.
224 +Fetch the command from the loaded extension and assert:
227 +const command
= t.session.extensionRunner.extensions[
0].commands.
get(
"shame");
228 +expect(command.
getArgumentCompletions(
"@sr")).
toContainEqual({
232 +expect(command.
getArgumentCompletions(
"@src/ @te")).
toContainEqual({
233 + value:
"@src/ @test/",
236 +expect(command.
getArgumentCompletions(
"fea")).
toContainEqual({
242 +Also assert suggestions for empty input include `--extra` and `#123` examples.
244 +- [ ] **Step 2: Run tests to verify failure**
249 +mise run test
-- extensions/shame/__tests__/harness.test.ts
252 +Expected: FAIL because `/shame` has no `getArgumentCompletions`.
254 +- [ ] **Step 3: Implement completion**
256 +Track the active cwd from `session_start` and initialize it to `process.cwd()`.
257 +Add `completeArguments(cwd, argumentText)` using `readdirSync(..., { withFileTypes: true })` for the active `@` token and `execFileSync("git", ["for-each-ref", "--format=%(refname:short)", "refs/heads", "refs/remotes"], { cwd, encoding: "utf8" })` for branch names.
258 +Catch filesystem/Git failures and return only applicable static suggestions.
259 +Filter control characters from values and labels.
260 +Preserve the prefix before the active whitespace-delimited token because Pi replaces the full argument string.
261 +Append `/` to directories.
265 +getArgumentCompletions(argumentText) {
266 + return completeArguments(cwd, argumentText);
270 +Do not walk the repository recursively; list only the active directory.
272 +- [ ] **Step 4: Run focused tests and formatting**
277 +mise run test
-- extensions/shame/__tests__/harness.test.ts
279 +mise run test
-- extensions/shame/__tests__/harness.test.ts
282 +Expected: all commands exit 0 and formatting leaves the focused test green.
284 +- [ ] **Step 5: Commit completion**
287 +git add extensions/shame/index.ts extensions/shame/__tests__/harness.test.ts
288 +git commit -m
"feat(shame): complete paths and branches" 291 +###
Task 4: Verify release readiness 295 +- Verify: all modified files
297 +- [ ] **Step 1: Search for stale names**
302 +rg -n
'extensions/review|pi-ext-review|/review|`review` extension' . --glob
'!docs/super/specs/**' --glob
'!docs/super/plans/**' 305 +Expected: no stale extension or command references.
307 +- [ ] **Step 2: Run the release gate**
315 +Expected: lint, all tests, and static extension checks pass.
317 +- [ ] **Step 3: Inspect final state**
322 +git status --short --branch
323 +git log -4 --oneline
326 +Expected: clean worktree with the rename, inference, and completion commits above the design/plan commits.