Agent: make the issue→PR orchestrator repo-independent and de-branded

[MateuszPaulski]

Make the autonomous issue→PR orchestrator (.claude/skills/airside-agent + the six
.claude/agents/airside-*.md subagents) generic — repo- and owner-independent, with the
GitHub command surface lifted out of the prose, the airside brand removed, and a clean seam
where a different tracker (Jira) could slot in later. Today the workflow only runs against the
one hardcoded repo, the runbook is hard to read, and GitHub is baked in everywhere.

Status: parking lot — dev-tooling cleanup, not product code. Deferred because the loop works
as-is for the single Airnauts/airside repo; this is about portability and maintainability, not a
missing capability. No ADR until committed (it would supersede the airside-agent design notes in
ADR-0042 / ADR-0043).

What's wrong today

• Repo/owner are hardcoded, not configured. SKILL.md §Config lists REPO =
  Airnauts/airside and OWNER = MateuszPaulski and literally says "Treat them as constants for
  now; they will move to the top of the file." They never moved — Airnauts/airside is inlined in
  ~40 gh api repos/Airnauts/airside/... / gh issue list --repo ... call sites across
  SKILL.md and all six agent files. You cannot point the loop at another repo without a
  find-replace.
• The airside brand is woven in (~53 places). The idempotency machinery is all branded: the
  issue markers <!-- airside-agent-state/-review/-spec/-note -->, the ack prefix
  🤖 airside-agent:, the top-level ack key <!-- airside-agent-ack:tl-<id> -->, the bot-comment
  disambiguation rule, the pickup label agent, and the skill + six subagent names
  (airside-builder, airside-reviewer, …). The user wants this de-branded to a product-neutral
  namespace.
• SKILL.md is hard to read. 545 lines / 32 KB of narrative algorithm with gh, gh api graphql, and jq snippets inlined throughout. The orchestration logic and the GitHub mechanics
  are tangled together in one file.
• GitHub is assumed end-to-end — gh CLI, GraphQL review threads, draft PRs, gh pr ready.
  There is no seam to target another service, even though Integrations: Jira is already a
  direction we're considering.
• Stale legacy references. .claude/agents/airside-triage.md:22,
  airside-spec-author.md:22, and airside-builder.md:31 still tell subagents to "ignore the dead
  link" to a now-removed docs/ideas.md / docs/issues.md. Those backlogs were retired (GitHub
  issues are now the sole backlog) — the agents shouldn't mention them at all.

Shape

1. One config block, referenced everywhere. Actually move REPO, OWNER, PICKUP_LABEL,
   BRANCH_PREFIX, REVIEW_CAP to the top of SKILL.md (as the §Config note already promises) and
   rewrite every call site to read repos/<REPO>/... / --repo <REPO> from it instead of the
   literal. The subagents take REPO/OWNER as inputs already (per the spawn contracts) — make
   them stop hardcoding it too.

2. Extract the GitHub command surface to its own reference file. Pull the inlined gh /
   gh api graphql / jq snippets out of the narrative into a single
   .claude/skills/airside-agent/references/github.md (or a set of named, copy-pasteable command
   recipes), keyed by orchestrator operation: scan, load-state, terminal-check,
   reconcile-artifacts, post-spec, post-review-note, CI-gate, promote, inline-threads,
   top-level-comments, ack/resolve. SKILL.md keeps the algorithm and links to the recipe by name.
   This is also the natural place the provider boundary will fall (see 4).

3. De-brand to a neutral namespace. Rename the skill, the six subagents, and every marker / ack
   prefix / disambiguation token from airside-* to a product-neutral name (candidates:
   task-agent, issue-agent, code-agent — pick one). This ripples to: the SKILL frontmatter
   name:, the /loop 5m /<name> target, the subagent_type registrations + fallback preamble
   paths .claude/agents/<name>-*.md, and the marker strings. The markers are persisted
   idempotency keys in live issues/PRs — any in-flight issue/PR carrying old airside-agent-*
   markers needs either a dual-read back-compat window or a clean cutover after in-flight work
   drains. There's prior art for a wide deprecate-with-pointer rename in ADR-0038
   (the comments→airside rebrand).

4. A tracker/VCS provider seam — design only, do not implement Jira now. Once the GitHub
   commands live behind the recipe boundary from (2), define the abstract operations the
   orchestrator actually needs — list actionable tasks, read/write structured task state, post a
   threaded comment, open/ready/merge a change request, read review threads — so GitHub is one
   implementation and a Jira tracker (+ a VCS host) could be another later. Keep this a documented
   interface in the skill, not new code; it ties into the existing Integrations: Jira direction.
   Switching providers is explicitly out of scope for this issue.

5. Delete the legacy doc mentions in the three agent files above — drop the "ignore the dead
   link to docs/ideas.md/docs/issues.md" sentences entirely.

Effort: medium — a doc/tooling refactor, no product source touched. Mostly editing
SKILL.md + the six .claude/agents/*.md, plus the agent-type registrations and the /loop
target name. Steps 1, 2, and 5 are low-risk and independently shippable; step 3 (rename) needs the
in-flight-marker migration handled; step 4 is a design write-up that unblocks a future Jira adapter.

[MateuszPaulski]

[MateuszPaulski]

Spec: Agent — make the issue→PR orchestrator repo-independent and de-branded (#63)

Problem

The airside-agent orchestrator (.claude/skills/airside-agent/SKILL.md + the six .claude/agents/airside-*.md subagents) only runs against the one hardcoded repo: Airnauts/airside is inlined at ~49 gh/gh api call sites, the airside brand is woven through the idempotency markers and subagent names, SKILL.md (610 lines) tangles the orchestration algorithm with inline gh/graphql/jq snippets, and three agent files still tell subagents to "ignore the dead link" to the retired docs/ideas.md/docs/issues.md. There is no seam where a different tracker (Jira) could slot in.

Approach

Deliver the low-risk, autonomously-mergeable parts of the issue now — issue steps 1 (configurable repo/owner), 2 (extract the GitHub command surface), 4 (provider-seam design), 5 (delete legacy doc mentions) — and carve the de-brand rename (step 3) into a follow-up issue the owner merges deliberately with the loop paused.

Why the split: steps 1/2/4/5 are pure content edits that keep the skill name and every persisted marker string identical, so the next tick just reads improved prose — zero live-state risk. The rename is a hard cutover on the running tool: /loop 5m /airside-agent and the subagent_type registrations resolve the skill/agents by name, so a merged rename breaks the next tick until the owner restarts with the new target — and the marker strings are live idempotency keys on 8 in-flight issues right now (#67, #53, #48, #31, #30, #17, #9, plus this one), which would be re-triaged/duplicated without a dual-read drain window. That coordination can't be a fire-and-forget autonomous merge. The issue's own risk-ordering already separates these ("1, 2, 5 independently shippable; step 3 needs the migration handled"). Rejected alternative: do the rename in this pass too — deferred to a follow-up because it needs an owner-run pause→merge→restart, not because it's hard.

Implementation plan

All changes are under .claude/ and docs/ — no product source.

1. Configurable repo/owner (issue step 1). In .claude/skills/airside-agent/SKILL.md:

   • Keep the existing §Config table (REPO, OWNER, PICKUP_LABEL, BRANCH_PREFIX, REVIEW_CAP) as the single source of these values; delete the "treat them as constants… they will move" note. Add OWNER_GRAPHQL/NAME_GRAPHQL guidance so the GraphQL -F o=… -F r=… split (currently -F o=Airnauts -F r=airside) is derived from REPO, not literal.
   • Rewrite every Airnauts/airside occurrence in the narrative to the placeholder form: --repo <REPO>, repos/<REPO>/..., and the issue/PR URLs in the §4 status table to https://github.com/<REPO>/.... agent/issue-<n> becomes <BRANCH_PREFIX><n>.
   • In each of the six .claude/agents/airside-*.md: change the Inputs line from REPO — `Airnauts/airside` to "REPO — the target repo, e.g. Airnauts/airside" and replace every literal --repo Airnauts/airside / repos/Airnauts/airside/... in their Steps with <REPO> read from the passed input. (The spawn contracts already pass REPO.)

2. Extract the GitHub command surface (issue step 2). Create .claude/skills/airside-agent/references/github.md — copy-pasteable gh/gh api graphql/jq recipes lifted verbatim (parameterised on <REPO>/<n>/<pr>) out of the SKILL.md narrative, keyed by orchestrator operation: scan, load-state, terminal-check, reconcile-artifacts, evaluate-approval, repair-labels, post-spec, post-review-note, post-review-report, ci-gate, promote, inline-threads, top-level-comments, ack-resolve, plus the gh gotchas block. SKILL.md keeps the algorithm and links each op to its recipe by name (e.g. "run the ci-gate recipe"), shrinking it substantially. Behaviour is byte-identical — this is a relocation, not a logic change. This is the boundary the provider seam (step 4) sits behind.

3. Provider-seam design, design-only (issue step 4). Create .claude/skills/airside-agent/references/providers.md defining the abstract operations the orchestrator actually needs — listActionableTasks, readTaskState / writeTaskState, postThreadedComment, openChangeRequest / readyChangeRequest / mergeChangeRequest, readReviewThreads / resolveReviewThread — with GitHub named as the one concrete implementation (each op cross-referenced to its github.md recipe) and a note that a Jira tracker + a VCS host would be a second implementation later. Documentation only; no code, no adapter, no provider switch. Ties into the existing Integrations: Jira direction. Add a one-line pointer from SKILL.md.

4. Delete legacy doc mentions (issue step 5). Remove the "Older issues may footer-link a now-removed docs/ideas.md/docs/issues.md entry; that backlog was retired — ignore the dead link…" sentences from .claude/agents/airside-triage.md, .claude/agents/airside-spec-author.md, and .claude/agents/airside-builder.md (drop them entirely; keep the surrounding "read the issue body in full" instruction).

5. ADR. Add ADR-0044 to docs/adr.md (newest-last), refining ADR-0042/0043: records the generalization (repo/owner from config), the references/github.md recipe extraction, and the design-only provider seam; explicitly notes the de-brand rename is deferred to a follow-up for the live-marker + /loop-target migration. Status: accepted.

6. File the follow-up for issue step 3 (the rename) via the filing-github-issues skill: neutral namespace (recommend task-agent — aligns with the frontmatter's "autonomous task orchestrator" and the provider framing; owner confirms the name), rename skill + six agents + subagent_type registrations + /loop target, and the migration: dual-read old airside-agent-* markers for one drain window while writing only new markers, plus the owner-coordinated pause loop → merge → restart with the new /loop target. Label agent.

Notes: PICKUP_LABEL (agent) and BRANCH_PREFIX (agent/) are already brand-neutral — make them config knobs referenced by name, do not rename them. Grep confirms filing-github-issues never references the agent label or airside-agent, so nothing strays.

Testing

No automated tests — this is a documentation/tooling refactor and pnpm lint (biome) does not cover markdown. Verify by:

• Hand-run one tick: /airside-agent. With REPO=Airnauts/airside in the config, the placeholder-substituted call sites must behave identically to today — confirm the tick reconciles the 8 live in-flight issues (Widget: unify the thread controller's four single-slot listeners into one event bus #67/Widget: page-level / unanchored comments (start a thread without a pin) #53/Integrations: GitHub Issues thread-action target (create a linked GitHub issue from a thread) #48/Widget: "what's new" changelog popup #31/Widget: "powered by Airside" mark linking to the repo #30/Real-time: live updates (SSE / WebSocket) #17/Widget: detail-view prev/next navigation #9 + Agent: make the issue→PR orchestrator repo-independent and de-branded #63) into the same phases/labels they hold now, with the (unchanged) airside-agent-* markers still parsing. No marker churn, no duplicate specs/PRs.
• Grep gate: no literal Airnauts/airside remains in SKILL.md or the six agent files outside the §Config table / illustrative "e.g." text; every op in the narrative links to a named github.md recipe.

Changeset

None (tooling/docs only — .claude/ + docs/; no publishable @airnauts/airside-* package touched).

Risks / open questions

• Rename in this pass? Recommended split: rename lands as a separate follow-up (see plan feat(notifier-email): email notifier with pluggable SMTP/Resend transports #6). If the owner instead wants it folded in now, add it as a final, separate commit carrying the dual-read marker migration, and be ready to pause loop → merge → /loop 5m /task-agent immediately after — otherwise the next tick breaks on the stale /loop target. Owner's call at /approve.
• Neutral name (task-agent recommended) is the owner's brand decision — confirm/override at approval; it only binds the follow-up.
• Recipe extraction fidelity: the risk is a transcription error in a jq/graphql snippet moved to github.md. Mitigated by lifting verbatim and the hand-run tick.

Out of scope

• The de-brand rename itself (issue step 3) — its own follow-up issue.
• Any actual Jira/other-provider implementation or a provider switch (step 4 is design-only per the issue).
• Renaming PICKUP_LABEL/BRANCH_PREFIX values or touching product code, packages, or CI.

---

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

[MateuszPaulski]

/revise one more review this against fable model, also we dont want to use airside-agent naming lets call it air-agent. Keep in midn that we want to keep docs minimal, user frendly, easy to read and understand and make changes

[MateuszPaulski]

🤖 airside-agent: 🔧 revision queued — re-speccing; a new spec version will follow.

[MateuszPaulski]

Spec: Agent — make the issue→PR orchestrator repo-independent and de-branded (#63)

Problem

The airside-agent orchestrator (.claude/skills/airside-agent/SKILL.md + the six .claude/agents/airside-*.md subagents) only runs against the one hardcoded repo: Airnauts/airside is inlined at every gh/gh api call site, the airside brand is woven through the idempotency markers and subagent names, SKILL.md (610 lines) tangles the orchestration algorithm with inline gh/graphql/jq snippets, and three agent files still tell subagents to "ignore the dead link" to the retired docs/ideas.md/docs/issues.md. There is no seam where a different tracker (Jira) could slot in.

Approach

Deliver the low-risk, autonomously-mergeable parts of the issue now — issue steps 1 (configurable repo/owner), 2 (extract the GitHub command surface), 4 (provider-seam design), 5 (delete legacy doc mentions) — and carve the de-brand rename (step 3) into a follow-up issue the owner merges deliberately with the loop paused.

Why the split: steps 1/2/4/5 are pure content edits that keep the skill name and every persisted marker string identical, so the next tick just reads improved prose — zero live-state risk. The rename is a hard cutover on the running tool: /loop 5m /airside-agent and the subagent_type registrations resolve the skill/agents by name, so a merged rename breaks the next tick until the owner restarts with the new target — and the marker strings are live idempotency keys on the issues currently carrying airside-agent-* markers (roughly a dozen open agent-labelled issues as of filing), which would be re-triaged/duplicated without a dual-read drain window. That coordination can't be a fire-and-forget autonomous merge. The issue's own risk-ordering already separates these ("1, 2, 5 independently shippable; step 3 needs the migration handled"). Rejected alternative: do the rename in this pass too — deferred to a follow-up because it needs an owner-run pause→merge→restart, not because it's hard.

Implementation plan

All changes are under .claude/ and docs/ — no product source.

Docs principle (applies to everything this spec produces). The prose docs — references/providers.md, the ADR entry, and the follow-up issue body — must stay short, skimmable, and easy to change: favour concise prose over exhaustive detail, lead with the one thing a reader needs, and don't restate what SKILL.md already says. Exception: the github.md recipes in plan #2 are lifted verbatim and complete — concision applies to how they're organized and headed, never to trimming a jq/graphql snippet (that would reintroduce the transcription risk this spec is trying to avoid).

1. Configurable repo/owner (issue step 1). In .claude/skills/airside-agent/SKILL.md:

   • Keep the existing §Config table (REPO, OWNER, PICKUP_LABEL, BRANCH_PREFIX, REVIEW_CAP) as the single source of these values; delete the "treat them as constants… they will move" note. Add OWNER_GRAPHQL/NAME_GRAPHQL guidance so the GraphQL -F o=… -F r=… split (currently -F o=Airnauts -F r=airside) is derived from REPO, not literal.
   • Rewrite every Airnauts/airside occurrence in the narrative to the placeholder form: --repo <REPO>, repos/<REPO>/..., and the issue/PR URLs in the §4 status table to https://github.com/<REPO>/.... agent/issue-<n> becomes <BRANCH_PREFIX><n>.
   • In each of the six .claude/agents/airside-*.md: change the Inputs line from REPO — `Airnauts/airside` to "REPO — the target repo, e.g. Airnauts/airside" and replace every literal --repo Airnauts/airside / repos/Airnauts/airside/... in their Steps with <REPO> read from the passed input. (The spawn contracts already pass REPO.)

2. Extract the GitHub command surface (issue step 2). Create .claude/skills/airside-agent/references/github.md — copy-pasteable gh/gh api graphql/jq recipes lifted verbatim (parameterised on <REPO>/<n>/<pr>) out of the SKILL.md narrative, keyed by orchestrator operation: scan, load-state, terminal-check, reconcile-artifacts, evaluate-approval, repair-labels, post-spec, post-review-note, post-review-report, ci-gate, promote, inline-threads, top-level-comments, ack-resolve, plus the gh gotchas block. SKILL.md keeps the algorithm and links each op to its recipe by name (e.g. "run the ci-gate recipe"), shrinking it substantially. Behaviour is byte-identical — this is a relocation, not a logic change; the snippets are moved whole. This is the boundary the provider seam (step 4) sits behind.

3. Provider-seam design, design-only (issue step 4). Create .claude/skills/airside-agent/references/providers.md — a short doc naming the abstract operations the orchestrator actually needs — listActionableTasks, readTaskState / writeTaskState, postThreadedComment, openChangeRequest / readyChangeRequest / mergeChangeRequest, readReviewThreads / resolveReviewThread — with GitHub as the one concrete implementation (each op cross-referenced to its github.md recipe) and a one-line note that a Jira tracker + a VCS host would be a second implementation later. Documentation only; no code, no adapter, no provider switch. Ties into the existing Integrations: Jira direction. Add a one-line pointer from SKILL.md.

4. Delete legacy doc mentions (issue step 5). Remove the "Older issues may footer-link a now-removed docs/ideas.md/docs/issues.md entry; that backlog was retired — ignore the dead link…" sentences from .claude/agents/airside-triage.md, .claude/agents/airside-spec-author.md, and .claude/agents/airside-builder.md (drop them entirely; keep the surrounding "read the issue body in full" instruction).

5. ADR. Add ADR-0044 to docs/adr.md (newest-last, kept concise), refining ADR-0042/0043: records the generalization (repo/owner from config), the references/github.md recipe extraction, and the design-only provider seam; notes the de-brand rename is deferred to a follow-up for the live-marker + /loop-target migration, and records the chosen neutral name air-agent so the decision is captured where the rationale lives. Status: accepted.

6. File the follow-up for issue step 3 (the rename) via the filing-github-issues skill. The neutral namespace is air-agent (decided by the owner). The follow-up covers: rename the skill to air-agent, rename the six agents into the air-* namespace (leave the exact per-agent filenames for the follow-up to settle — don't presume a scheme), update the subagent_type registrations and the /loop target to /loop 5m /air-agent, and the migration: dual-read the old airside-agent-* markers for one drain window while writing only the new air-agent-* markers, plus the owner-coordinated pause loop → merge → restart with the new /loop target. Label agent.

Notes: PICKUP_LABEL (agent) and BRANCH_PREFIX (agent/) are already brand-neutral — make them config knobs referenced by name, do not rename them. Grep confirms filing-github-issues never references the agent label or airside-agent, so nothing strays.

Testing

No automated tests — this is a documentation/tooling refactor and pnpm lint (biome) does not cover markdown. Verify by:

• Hand-run one tick: /airside-agent. With REPO=Airnauts/airside in the config, the placeholder-substituted call sites must behave identically to today — confirm the tick reconciles the live in-flight agent-labelled issues into the same phases/labels they hold now, with the (unchanged) airside-agent-* markers still parsing. No marker churn, no duplicate specs/PRs.
• Grep gate: no literal Airnauts/airside remains in SKILL.md or the six agent files outside the §Config table / illustrative "e.g." text; every op in the narrative links to a named github.md recipe; the github.md recipes match the pre-extraction snippets (diff-check the moved blocks).

Changeset

None (tooling/docs only — .claude/ + docs/; no publishable @airnauts/airside-* package touched).

Risks / open questions

• Rename in this pass? Recommended split: rename lands as a separate follow-up (see plan feat(notifier-email): email notifier with pluggable SMTP/Resend transports #6). If the owner instead wants it folded in now, add it as a final, separate commit carrying the dual-read marker migration, and be ready to pause loop → merge → /loop 5m /air-agent immediately after — otherwise the next tick breaks on the stale /loop target. Owner's call at /approve.
• Recipe extraction fidelity: the one real risk in this pass is a transcription error in a jq/graphql snippet moved to github.md. Mitigated by lifting verbatim (never trimmed for concision), the diff-check in Testing, and the hand-run tick.

Out of scope

• The de-brand rename itself (issue step 3) — its own follow-up issue, using the confirmed name air-agent.
• Any actual Jira/other-provider implementation or a provider switch (step 4 is design-only per the issue).
• Renaming PICKUP_LABEL/BRANCH_PREFIX values or touching product code, packages, or CI.

---

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

[MateuszPaulski]

🤖 airside-agent: applied your revisions (spec v2 — fable-model pass, air-agent naming, minimal-docs principle). Please re-/approve to build, or /revise <notes> again.