Agent: rename the orchestrator to the neutral air-agent namespace

[MateuszPaulski]

De-brand the issue→PR orchestrator from the airside-* namespace to the neutral air-agent name (owner-decided — recorded in ADR-0048). This is issue step 3 of #63, deliberately split out: it is a hard cutover on the running tool — /loop 5m /airside-agent and the subagent_type registrations resolve the skill/agents by name, and the airside-agent-* markers are persisted idempotency keys on live issues/PRs — so it needs an owner-coordinated pause → merge → restart, not a fire-and-forget autonomous merge.

Status: parking lot — owner-coordinated merge with the loop paused (see Migration below).

Shape:

• Rename the skill .claude/skills/airside-agent/ → air-agent: the frontmatter name:, the /loop 5m /air-agent target, and the file mode's invocation (/air-agent file <description>).
• Rename the six subagents .claude/agents/airside-*.md into the air-* namespace — settle the exact per-agent filenames as part of this issue (no scheme is presumed here); update every subagent_type registration and fallback preamble path in SKILL.md's spawn contracts.
• Rename the persisted marker strings and prefixes: <!-- airside-agent-state/-review/-review-report:<sha>/-spec v<n>/-note -->, the ack prefix 🤖 airside-agent:, and the top-level ack key <!-- airside-agent-ack:tl-<id> --> → their air-agent forms; the bot-comment disambiguation rule must match the new tokens (and the old ones during the drain window).
• Also sweep references/github.md (the recipes carry the marker strings), scripts/tick-scan.sh comments, the fixer's Airside-Agent-Fix / Airside-Agent-Conflicts commit trailers, and the visible "airside-agent" wording in notes/reports.
• Do not rename PICKUP_LABEL (agent) or BRANCH_PREFIX (agent/issue-) — already brand-neutral config knobs (Agent: make the issue→PR orchestrator repo-independent and de-branded #63).

Migration (the reason this is its own issue):

1. Dual-read, new-write: for one drain window, read/match both the old airside-agent-* and new air-agent-* markers everywhere (state, spec, review, acks, bot-comment rule) while writing only the new ones — otherwise every in-flight agent-labelled issue gets re-triaged/duplicated.
2. Cutover: owner pauses the loop → merges → restarts with /loop 5m /air-agent (the old target dangles after the rename).
3. Drop the dual-read once in-flight issues have drained. Prior art for a wide deprecate-with-pointer rename: ADR-0038.

Context: #63 / ADR-0048 (records the decision and the chosen name).

[MateuszPaulski]

[MateuszPaulski]

Spec: Agent: rename the orchestrator to the neutral air-agent namespace

Depends on PR #73 (agent/issue-63) merging first. All paths and line references below are as of that branch (config placeholders, references/github.md, references/providers.md, scripts/tick-scan.sh, file mode, conflicts op). Build this on top of the post-#73 main; if #73 hasn't merged yet, this issue is not actionable.

Problem

The orchestrator carries the product brand: the skill .claude/skills/airside-agent/, six .claude/agents/airside-*.md subagents, and the persisted airside-agent-* markers/prefixes on live issues and PRs. ADR-0050 records the owner-decided neutral name air-agent; this issue executes the rename with a migration that doesn't re-triage or duplicate in-flight work.

Approach

A single-PR rename with a dual-read / new-write drain window: every read-side marker match accepts both the old airside-agent-* and new air-agent-* tokens (each dual-match line tagged DRAIN(#72) so cleanup is one grep), while every write emits only the new tokens. This works cleanly because air-agent is not a substring of airside-agent (and vice versa) — the two token families never cross-match. State comments are edited in place each tick, so old-marker state comments migrate to the new marker naturally on first refresh; spec/review/ack comments are append-only, so dual-read covers them until their issues drain.

Alternative rejected: a one-shot migration script that rewrites all old markers on live issues at cutover — more moving parts, mutates history-bearing comments (spec comments are the SPEC_AT command anchor; rewriting one would resurrect already-handled /revise//approve commands), and the drain window costs almost nothing.

Subagent filename scheme (settled here): plain air-* — a 1:1 swap of the airside- prefix:

Old file / subagent_type	New file / subagent_type
airside-triage	air-triage
airside-spec-author	air-spec-author
airside-spec-reviser	air-spec-reviser
airside-builder	air-builder
airside-reviewer	air-reviewer
airside-fixer	air-fixer

Rationale: matches the issue's own "air-* namespace" wording, keeps names short, and keeps subagent_type == filename stem. (Rejected: air-agent-builder etc. — longer, and the six agents are already grouped by living in this repo's .claude/agents/.)

Marker/token mapping (write-side, new-only):

Old	New
<!-- airside-agent-state {json} -->	<!-- air-agent-state {json} -->
<!-- airside-agent-review {json} -->	<!-- air-agent-review {json} -->
<!-- airside-agent-review-report:<sha> -->	<!-- air-agent-review-report:<sha> -->
<!-- airside-agent-spec v<n> -->	<!-- air-agent-spec v<n> -->
<!-- airside-agent-note -->	<!-- air-agent-note -->
<!-- airside-agent-ack:tl-<id> -->	<!-- air-agent-ack:tl-<id> -->
🤖 airside-agent: (ack prefix)	🤖 air-agent:
Airside-Agent-Fix: true (fixer trailer)	Air-Agent-Fix: true
Airside-Agent-Conflicts: true (conflicts trailer)	Air-Agent-Conflicts: true

Unchanged by design: PICKUP_LABEL (agent), BRANCH_PREFIX (agent/issue-), all state:* label names, and every historical mention in docs/adr.md (decided history is never rewritten — ADR-0042/0043/0050 keep the old name).

Implementation plan

1. Rename the skill directory — git mv .claude/skills/airside-agent .claude/skills/air-agent (SKILL.md, references/github.md, references/providers.md, scripts/tick-scan.sh move with it).
2. .claude/skills/air-agent/SKILL.md — frontmatter name: air-agent; description + title; /loop 5m /air-agent; /air-agent file <description>; the §1 script path .claude/skills/air-agent/scripts/tick-scan.sh; the marker list (§"The issue markers") rewritten to the new tokens; the bot-comment rule becomes: a comment is the bot's iff its body contains <!-- air-agent OR 🤖 air-agent — or, during the drain window, <!-- airside-agent OR 🤖 airside-agent (tag the old pair DRAIN(#72)); the six spawn contracts' subagent_type values and fallback preamble paths (.claude/agents/air-*.md); the conflicts-op one-attempt guard reads either trailer (DRAIN(#72)); visible strings ("no actionable air-agent tasks", the revising ack line 🤖 air-agent: 🔧 revision queued …). Add a short "Drain window (issue Agent: rename the orchestrator to the neutral air-agent namespace #72)" paragraph under the marker section: dual-read old+new, write new-only, cleanup = the follow-up issue below.
3. git mv the six agent files to .claude/agents/air-*.md per the table; in each: frontmatter name:, description ("air-agent orchestrator"), heading, marker references (builder reads the highest-version air-agent-spec — dual-match, DRAIN(#72), since an approved-but-unbuilt spec may carry the old marker), the builder's PR footer 🤖 Draft opened by air-agent — automated build of #<n>., the fixer's two commit trailers (write new), temp-file names (/tmp/air-agent-pr-<ISSUE>.md, cosmetic). Leave the product-brand references alone: "the airside way", @airnauts/airside-*, Airnauts/airside config examples — those name the repo/packages, not the agent.
4. .claude/skills/air-agent/references/github.md — all 13 occurrences: write recipes (post-state, post-spec, post-review-note, post-review-report, ack-resolve) emit new tokens only; read recipes dual-match with a # DRAIN(#72) comment on each:
   • load-state: select(.body|contains("air-agent-state") or contains("airside-agent-state"))
   • evaluate-approval SPEC_AT: max created_at over comments matching either spec marker (spec version numbering continues across markers — a post-rename revision of an old-marker v1 posts <!-- air-agent-spec v2 -->; "highest version" spans both).
   • review-note read: either review marker; review-report idempotency guard: either …-review-report:<HEAD> form.
   • acked-ids set: collect ids from both …-ack:tl-<id> forms.
5. scripts/tick-scan.sh — header comment only (it returns raw comments; marker matching lives in the recipes/SKILL). No functional change.
6. docs/adr.md — one new ADR, newest-last, next free number at merge time (the issue says ADR-0048 but the decision landed as ADR-0050 — verify against merged main, per the Agent: make the issue→PR orchestrator repo-independent and de-branded (#63) #73 numbering lesson). Status: accepted; records the executed cutover: the air-* filename scheme, the token mapping, dual-read/new-write with DRAIN(#72) tags, and the owner-coordinated pause→merge→restart. References ADR-0050 (decision) and ADR-0038 (prior deprecate-with-pointer rename art).
7. File the cleanup follow-up issue (at PR time, without the agent label): "drop the Agent: rename the orchestrator to the neutral air-agent namespace #72 dual-read" — grep DRAIN(#72), delete the old-token halves, once every issue/PR that predates the cutover is terminal (list the then-open agent-labelled issues in its body).
8. Cutover runbook (put it verbatim in the PR description — these are owner/post-merge actions, not code):
   1. Owner pauses the loop (stop /loop).
   2. Merge the PR.
   3. One-time label-description sweep (descriptions aren't touched by the preflight --force upsert): gh label edit agent --repo Airnauts/airside --description "Pick up this issue for the air-agent automation", and same for the state:* labels whose descriptions say "airside-agent".
   4. Hand-run one tick (/air-agent) in a fresh session (a live session may still have the old subagent_types registered) and check the end-of-tick table matches pre-pause state — no re-triage, no duplicate spec.
   5. Restart with /loop 5m /air-agent.

Testing

No product code — verification is grep gates plus the live hand-run tick:

• Grep gate: after the sweep, grep -rn "airside-agent\|airside-triage\|airside-builder\|airside-reviewer\|airside-fixer\|airside-spec\|Airside-Agent" .claude/ returns only lines tagged DRAIN(#72) (the deliberate dual-reads). docs/adr.md is exempt (history).
• Inverse gate: every DRAIN(#72) line contains an old token — so the cleanup issue is exactly grep -rn "DRAIN(#72)" .claude/.
• bash -n .claude/skills/air-agent/scripts/tick-scan.sh + one live run against Airnauts/airside (read-only) — output parity with a pre-rename run.
• pnpm lint green (biome; wide renames broke CI once before — ADR-0038 lesson).
• The post-merge hand-run tick (cutover step 4) is the real end-to-end proof: existing old-marker state/spec comments are adopted, not re-created.

Changeset

None — .claude/ + docs/ only; no publishable package touched.

Risks / open questions

• Filename scheme is proposed as plain air-* — confirm at /approve (say /approve use air-agent-* filenames to override; it's a mechanical change to steps 2–3).
• This PR must not be auto-driven to merge: it renames the running tool. The loop never merges PRs anyway, but the owner should pause the loop before merging (cutover step 1), since a tick that runs mid-rename-merge is fine (pre-merge files) but a tick after merge under the old /airside-agent target dangles.
• An old-marker spec in awaiting-approval at cutover: /approve still lands because SPEC_AT dual-reads the old spec marker — covered, but worth eyeballing on the hand-run tick.
• Old-token drain is unbounded if a pre-cutover issue lingers in blocked — acceptable; the cleanup issue simply waits.

Out of scope

• Renaming PICKUP_LABEL, BRANCH_PREFIX, or state:* label names (already neutral).
• Rewriting docs/adr.md history or old GitHub comments/commits (old markers/trailers stay as posted).
• De-branding the product-facing text in the agents ("the airside way", @airnauts/airside-* rules) — that's repo-specific builder guidance, a Agent: make the issue→PR orchestrator repo-independent and de-branded #63-lineage generalization concern, not this rename.
• Dropping the dual-read — the filed follow-up issue.

---

🤖 Reply /approve to build, /revise <notes> to change it, or /stop to cancel.