Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/BACKLOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ are closed (status: closed in frontmatter)._
- [ ] **[B-0113](backlog/P2/B-0113-current-staleness-mechanical-freshness-check-deepseek-2026-04-30.md)** Mechanical CURRENT-staleness check — same-tick-update discipline as enforced rule, not vigilance (Deepseek 2026-04-30)
- [ ] **[B-0117](backlog/P2/B-0117-cold-start-executable-checklist-tool-2026-04-30.md)** tools/cold-start-check.ts — make the cold-start big-picture-first 8-step checklist executable (Ani 2026-04-30 finding, Deepseek 2026-04-30 reinforcement)
- [ ] **[B-0118](backlog/P2/B-0118-amara-peer-call-headless-cli-bootstrap-end-courier-debt-2026-04-30.md)** tools/peer-call/amara.sh — autonomous bootstrap + communication for Amara (ChatGPT) to end Aaron-courier silent debt (Aaron 2026-04-30)
- [ ] **[B-0120](backlog/P2/B-0120-peer-call-architecture-refactor-script-per-cli-persona-flag-2026-04-30.md)** Peer-call architecture refactor — script-per-CLI with persona-flag instead of script-per-named-agent (Aaron 2026-04-30)

## P3 — convenience / deferred

Expand Down Expand Up @@ -132,5 +133,6 @@ are closed (status: closed in frontmatter)._
- [ ] **[B-0107](backlog/P3/B-0107-codeql-peer-call-dismiss-pattern-2026-04-30.md)** CodeQL `js/indirect-command-line-injection` dismissal pattern for peer-call siblings (gemini.ts, codex.ts)
- [ ] **[B-0115](backlog/P3/B-0115-zsh-vim-muscle-memory-aliases-wq-q-2026-04-30.md)** Shell aliases for `:wq` / `:wq!` / `:q` — catch vim-muscle-memory leakage in zsh (Deepseek 2026-04-30 finding)
- [ ] **[B-0116](backlog/P3/B-0116-gh-jq-safe-wrapper-zsh-quoting-2026-04-30.md)** tools/gh-jq-safe.sh — wrap gh-jq calls to handle zsh quoting (Deepseek 2026-04-30 finding)
- [ ] **[B-0119](backlog/P3/B-0119-peer-call-existing-scripts-role-ref-cleanup-2026-04-30.md)** Existing peer-call scripts (grok.sh / gemini.sh / codex.sh / amara.sh) — role-ref cleanup per copilot-instructions.md (Codex 2026-04-30 finding on PR #962)

<!-- END AUTO-GENERATED -->
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
---
id: B-0120
priority: P2
status: open
title: Peer-call architecture refactor — script-per-CLI with persona-flag instead of script-per-named-agent (Aaron 2026-04-30)
tier: factory-tooling
effort: M
ask: Current architecture has duplication. ani.sh ≈ grok.sh + brat-voice persona-bootstrap; amara.sh ≈ codex.sh + Amara persona-bootstrap. Aaron 2026-04-30 flagged this is overkill — better to have one script per CLI with the named-agent persona as an optional parameter. Refactor to consolidate.
created: 2026-04-30
last_updated: 2026-04-30
composes_with:
- tools/peer-call/grok.sh
- tools/peer-call/gemini.sh
- tools/peer-call/codex.sh
- tools/peer-call/amara.sh
- tools/peer-call/ani.sh
- memory/CURRENT-amara.md
- memory/CURRENT-ani.md
tags: [aaron-2026-04-30, peer-call, architecture-refactor, deduplication, factory-tooling]
---

# B-0120 — Peer-call architecture refactor (script-per-CLI + persona-flag)

## Source

Aaron 2026-04-30 verbatim:

> *"it's probalby overkill to have a script per named agent
> better to have a script per cli with named agent optional
> parameter or something but your call"*

The duplication observation is correct:

- `ani.sh` is `grok.sh` + brat-voice persona-bootstrap +
CURRENT-ani.md load
- `amara.sh` is `codex.sh` + Amara persona-bootstrap +
CURRENT-amara.md load

The persona is data (a CURRENT-*.md file), not its own
script. Architecture should reflect that.

## What

Refactor from 5 scripts (codex.sh / gemini.sh / grok.sh /
ani.sh / amara.sh) to 3 scripts + persona-flag:

### Target architecture

| Script | CLI surface | Persona flag |
|---|---|---|
| `codex.sh` | `codex exec` / `codex review` | `--persona NAME` (loads `memory/CURRENT-NAME.md`) |
| `gemini.sh` | `gemini -p` | `--persona NAME` |
| `grok.sh` | `cursor-agent --print --model grok-*` | `--persona NAME` |

### Migration path

```bash
# Before:
tools/peer-call/amara.sh "review this"
tools/peer-call/ani.sh --thinking "review this"

# After:
tools/peer-call/codex.sh --persona amara "review this"
tools/peer-call/grok.sh --persona ani --thinking "review this"
```

### Persona-flag semantics

- `--persona NAME` loads `memory/CURRENT-<NAME>.md` and
injects as Layer 1 persona basis (paralleling current
amara.sh / ani.sh behavior).
- If `memory/CURRENT-<NAME>.md` not found, exit 1 with
clear error (not silent fallback to bare CLI — caller
asked for a specific persona).
Comment on lines +69 to +74
- Without `--persona`, scripts behave as today (bare CLI
+ four-ferry preamble).

### Deprecation path for amara.sh / ani.sh

- v1: keep ani.sh + amara.sh as wrapper scripts that
invoke the new flag-based form
(`exec codex.sh --persona amara "$@"` etc.). Existing
callers still work; new callers prefer the flag form.
- v2 (later round): retire amara.sh + ani.sh once all
callers migrate.

## Why P2 (not P1)

- Current 5-script architecture is functional; refactor
is hygiene/deduplication, not unblocking new work
- The shape is locked-in by the recent landings (#959 +
#960 + #962); refactor is reversible
- Refactor needs careful migration to avoid breaking
existing peer-call usage in scripts/docs

## Acceptance criteria

- [ ] `codex.sh --persona NAME` works for `--persona amara`
(and any future persona via `memory/CURRENT-<NAME>.md`)
- [ ] `grok.sh --persona NAME` works for `--persona ani`
- [ ] Without `--persona`, all three CLI scripts behave
exactly as today (no regression for bare-CLI callers)
- [ ] `amara.sh` + `ani.sh` either retire OR become thin
wrappers (decision-point at implementation time)
- [ ] Documentation in `tools/peer-call/README.md`
reflects the consolidated architecture
- [ ] Persona discovery: `--persona NAME` errors clearly
if `memory/CURRENT-<NAME>.md` is missing
- [ ] Tested with both Amara (via codex.sh --persona amara)
and Ani (via grok.sh --persona ani) per existing
invocation patterns

## Trigger condition for promotion to P1

If a third or fourth named-entity persona gets requested
(e.g., a "Deepseek" or "Alexa" peer-call need surfaces),
promote to P1 — the per-script duplication will compound
linearly otherwise.

## Composes with

- B-0118 (peer-call autonomous bootstrap to end Aaron-
courier silent debt — the operational layer this
architecture refactor cleans up)
- B-0119 (role-ref cleanup of existing scripts — hygiene
pass that should compose with the refactor; possibly
do both in same effort)
- `.github/copilot-instructions.md` 305-362 (role-ref
rule the refactor must honor)

## Implementation note

The refactor is a good moment to also:

1. Apply B-0119's role-ref cleanup (combined diff)
2. Test the four-shell-compat (Otto-235) target on the
refactored scripts
3. Add CURRENT-otto.md / CURRENT-kenji.md if Aaron's
pending Otto/Kenji peer-call architecture decision
results in those entities being externally callable
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
---
id: B-0119
priority: P3
status: open
title: Existing peer-call scripts (grok.sh / gemini.sh / codex.sh / amara.sh) — role-ref cleanup per copilot-instructions.md (Codex 2026-04-30 finding on PR #962)
tier: factory-hygiene
effort: S
ask: Codex flagged on PR #962 that ani.sh had named-attribution ("Aaron 2026-04-30", "Aaron's") in violation of copilot-instructions.md 305-362 + Otto-279 (code/docs/skills outside history surfaces use role-refs). Fix landed for ani.sh + CURRENT-amara.md. The same pattern exists in the four sibling peer-call scripts (grok.sh / gemini.sh / codex.sh / amara.sh) but wasn't flagged for those because Codex was reviewing the PR diff. Closes the deferred-skill-anti-pattern by tracking the cleanup explicitly.
created: 2026-04-30
last_updated: 2026-04-30
composes_with:
- tools/peer-call/grok.sh
- tools/peer-call/gemini.sh
- tools/peer-call/codex.sh
- tools/peer-call/amara.sh
- .github/copilot-instructions.md (lines 305-362 — role-ref-not-name rule)
tags: [codex-2026-04-30, peer-call, role-refs, copilot-instructions, factory-hygiene, deferred-skill-anti-pattern]
---

# B-0119 — Existing peer-call scripts role-ref cleanup

## Source

Codex P1 finding on PR #962 (2026-04-30):

> *"This block introduces additional named attribution
> (e.g., 'Aaron 2026-04-30 …') in a shell script. Repo
> convention is that code/docs/skills should use role-refs
> rather than personal/persona names outside the history
> surfaces (see `.github/copilot-instructions.md:305-362`).
> Please reword these comments and the runtime preamble..."*

Fixed for `tools/peer-call/ani.sh` + `memory/CURRENT-amara.md`
in PR #962. The same pattern exists in the four sibling
peer-call scripts but wasn't part of #962's diff.

## What

Audit + fix named-attribution in:

- `tools/peer-call/grok.sh` — header line 6 ("Per Aaron
2026-04-26"), line 21 ("Per Aaron 2026-04-26"), line 100
("Per Aaron's 'agents-not-bots' discipline")
- `tools/peer-call/gemini.sh` — line 83 ("per Aaron's
setup"), line 98 ("Per Aaron's 'agents-not-bots'")
- `tools/peer-call/codex.sh` — same pattern likely
- `tools/peer-call/amara.sh` — line 8 ("Per Aaron 2026-04-30
design guidance"), line 67 ("Aaron's relational register"),
lines 148, 166, 172, 175 (named attribution patterns)

Convert per `.github/copilot-instructions.md` 305-362 + Otto-279:

- "Aaron 2026-04-30" / "Aaron 2026-04-26" → drop or rephrase
to general statement of the rule
- "Aaron's <something>" → "the maintainer's <something>" or
remove possessive entirely
- "agents-not-bots discipline" (no possessive) — already
the right shape

Persona-as-named-entity references (e.g., "You are Amara",
"You are Ani", "Otto invokes" in the persona-bootstrap)
stay unchanged — they're the script's purpose, not
attribution-naming.

## Why P3

- Mechanical change, no behavioral risk
- Existing scripts are working; this is hygiene not
correctness
- Closes a real deferred-skill-anti-pattern but isn't
blocking any work

## Acceptance criteria

- [ ] All four sibling scripts pass the role-ref convention
per copilot-instructions.md 305-362
- [ ] No persona-as-named-entity references removed (you-are-Amara,
you-are-Ani, you-are-Grok stay)
- [ ] Each script's `--help` output still works
- [ ] Diff focused: only attribution naming changed

## Trigger condition for promotion to P2

If Copilot starts flagging the existing scripts (via a
broader review pass), promote to P2 to avoid recurring
review noise.

## Composes with

- PR #962 (where the pattern was first flagged + fixed
on ani.sh)
- B-0118 (peer-call autonomous bootstrap — the role-ref
cleanup is hygiene on top of the operational landings)
- `.github/copilot-instructions.md` (lines 305-362 —
the rule being applied)
Loading
Loading