Skip to content

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

docs(ai-task): approved AI PRs merge in a clear order (#16758)

Hazem Adel49c1bb294602
diff --git a/.agents/skills/ai-task/SKILL.md b/.agents/skills/ai-task/SKILL.md
index 75f186081df..b4f49b41132 100644
--- a/.agents/skills/ai-task/SKILL.md
+++ b/.agents/skills/ai-task/SKILL.md
@@ -1,11 +1,11 @@
---
name: ai-task
-description: The AI team's one command for doing a task the team way, from ticket to merged PR. Use when an engineer on the AI team (chat, agents, MCP, AI providers) starts a task ("/ai-task AI-123", "start AI-123", "work on this bug"), turns a request or customer report into a ticket ("/ai-task customer says chat won't save"), triages or answers a bug or support question ("/ai-task triage ENG-456"), or is about to open or update a PR ("/ai-task ship"). Also lets support, admins and anyone outside the team report an AI bug or request ("/ai-task report ..."). Grills the user one question at a time ("/ai-task grill AI-123") until a ticket is solvable without asking anyone. Runs the team check-up ("/ai-task check", "check the AI roadmap", "how is activation", "weekly AI update"): activation and cost from production plus late, blocked or waiting work in Linear. It does the Linear, brain and PR paperwork so the user only answers what it can't work out.
+description: The AI team's one command for doing a task the team way, from ticket to merged PR. Use when an engineer on the AI team (chat, agents, MCP, AI providers) starts a task ("/ai-task AI-123", "start AI-123", "work on this bug"), turns a request or customer report into a ticket ("/ai-task customer says chat won't save"), triages or answers a bug or support question ("/ai-task triage ENG-456"), or is about to open or update a PR ("/ai-task ship"). Owns the merge queue: when a PR is approved it moves the ticket to Ready to merge and ranks it so the top merges first ("/ai-task queue", "what do I merge next", "my PR got approved"). Sets up new members ("set me up", "onboard me"): Linear MCP, personal Linear API key, repo. Also lets support, admins and anyone outside the team report an AI bug or request ("/ai-task report ..."). Grills the user one question at a time ("/ai-task grill AI-123") until a ticket is solvable without asking anyone. Runs the team check-up ("/ai-task check", "check the AI roadmap", "how is activation", "weekly AI update"): activation and cost from production plus late, blocked or waiting work in Linear. It does the Linear, brain and PR paperwork so the user only answers what it can't work out.
---
# AI task
-One command, six moments: **start**, **triage**, **ship**, **check**, **note** (AI team members) and **report** (anyone). Work out which one from what the user typed. If it's unclear, ask once.
+One command, seven moments: **start**, **triage**, **ship**, **queue**, **check**, **note** (AI team members) and **report** (anyone). Work out which one from what the user typed. If it's unclear, ask once.
Whenever a ticket is being created or is too thin to solve, run a **grill** (below) inside that moment.
@@ -26,7 +26,7 @@ Run these checks before anything else, silently when they pass. If one fails, sh
> You can still report anything you found: `/ai-task report <what happened>`.
> Joining the team? Ping the AI team lead.
-3. **Repo** (start, triage, ship and check). The current directory must be the activepieces repo (`git rev-parse --show-toplevel` with `brain/knowledge/` inside). If not, stop:
+3. **Repo** (start, triage, ship, queue and check). The current directory must be the activepieces repo (`git rev-parse --show-toplevel` with `brain/knowledge/` inside). If not, stop:
> **I need the activepieces repo for this one.**
> Open Claude Code inside your checkout and run `/ai-task` again.
@@ -42,9 +42,18 @@ Run these checks before anything else, silently when they pass. If one fails, sh
- **Queue or job failures** also need the DevOps box over SSH, which `/debug-failed-run` drives. Ask for the host once.
- **Rules for real data:** read only. Keep ClickHouse windows to 3 days or less. Copy only counts and ids into tickets, never customer content, emails or credentials.
+5. **Linear API key** (members). The Linear MCP can't set a card's position, so the queue order goes through `linear.mjs` with the member's personal key. Check it with `[ -n "$LINEAR_API_KEY" ]`, and never print the key. If it's missing, don't stop: show this once per session, before your answer:
+
+ > **One setup step left: your Linear API key.** I use it to keep the merge queue in order.
+ > In a terminal in the repo (any OS), run `node .agents/skills/ai-task/linear.mjs setup` and follow it. Then restart Claude Code. Don't paste the key here.
+
+ `setup` reads the key hidden, checks it with Linear, and saves it to `env` in `~/.claude/settings.json`, which Claude Code loads on every OS. It needs a real terminal, so not through `!`. A key pasted into the chat is leaked: don't use it, tell them to revoke it and run `setup` with a new one.
+
## Help (no arguments, "help", or "?")
-Run the requirement checks first, then show the card that fits.
+Run the requirement checks first, then show the card that fits. For a member, add one setup line under the card: `Setup: ✓ Linear MCP · ✓ API key · ✓ repo` (✗ on anything missing, with the card for it).
+
+**First run** (a member with no AI ticket assigned yet, or who says "set me up" / "onboard me"): walk the setup in order (Linear MCP, then the API key, then the repo), one card at a time, and finish with the "Start here" doc link and "Want to try it on one of your tickets from **Who's on what**?"
**Member card**
@@ -55,6 +64,7 @@ Run the requirement checks first, then show the card that fits.
> - `/ai-task grill AI-123` when a ticket is too vague
> - `/ai-task triage ENG-456` when a bug lands
> - `/ai-task ship` before you open a PR
+> - `/ai-task queue` to see what merges next
> - `/ai-task check` for the Thursday check-up
> - `/ai-task note AI-123 <text>` to save a decision on a ticket
> - `/ai-task report X` to file a bug for someone else
@@ -241,6 +251,18 @@ The cards below are examples of that voice, not forms to fill in word for word.
>
> **Want me to fix Greptile's comments?**
+**Queue**
+
+> **AI-41 merges next, then yours.**
+> 1. AI-41 · customer's flows broken · Ziyad
+> 2. AI-57 · yours · touches the chat prompt too
+> 3. AI-60 · Hazem
+>
+> Heads up: AI-41 also edits `chat-system-prompt.md`, so rebase after it lands.
+> AI-33 sat 6 days with conflicts, I'd send it back to In Review.
+>
+> **Save this order?**
+
## Team truth (read it, don't assume)
- **Team rules:** the Linear doc "Start here: how the AI team works" (team AI). It covers the templates, the work-in-progress limit, review time and rituals. If a rule there disagrees with this skill, the doc wins.
@@ -319,9 +341,36 @@ Run these checks and fix what you can, then show one short summary of what chang
- **When both pass:** mark it ready (`gh pr ready <n>`) and ask a reviewer from CODEOWNERS.
Ship card line: `✓ Greptile 5/5 · ✓ CI green`, or the blocker, for example `✗ Greptile 3/5: 2 findings`.
+11. **Approved?** If `gh pr view <n> --json reviewDecision` says `APPROVED`, don't merge yet. Run **Queue** below: it puts the ticket in Ready to merge and tells the user their place. Ship card line: `✓ Approved · #2 in queue, after AI-41`.
Ask before pushing, opening the PR, or posting to Linear or GitHub. Everything goes out under the user's name.
+## Queue: who merges next
+
+Approved PRs wait in **Ready to merge** (between In Review and Done), and the **Merge queue** view in team AI shows them as one list. **The top card merges first.** Nobody merges out of order, so two PRs that touch the same thing (the chat prompt, a tool description) never race each other.
+
+Runs on `/ai-task queue`, when Ship finds an approval, and inside Check.
+
+1. **Fill the column.** Linear moves a ticket here on its own when its PR is approved and green. Move in any AI ticket in In Review whose PR is approved and green but got missed. One that drops back to In Review on a new push re-enters when it's approved again.
+2. **Gather** for every ticket in Ready to merge:
+ - Linear: priority, labels, customer requests (`list_customer_needs`), `blocks` relations, when it entered the column (`stateHistory`);
+ - its PR: `gh pr view <n> --json number,author,files,additions,deletions,mergeable,reviewDecision,statusCheckRollup`.
+3. **Kick back first.** A card leaves the queue if its PR has conflicts, red CI, changes requested, or it's sat 5 working days without merging. Move it back to In Review with a one-line comment that says why and what unblocks it (mention the owner). A stale card at the bottom is worse than no card.
+4. **Rank the rest, top first.** One hard rule first: a PR always sits above every queued PR that needs it (`blocks`, or "merge after #n" in the PR), so the top card can always land. Then go down the list, and only use the next rule to break a tie:
+ 1. **Something's on fire:** the "Start here" urgent list (live automations broken with no workaround, data loss or wrong data, security, billing, many customers at once).
+ 2. **Customers waiting:** more customer requests first, then the one waiting longest.
+ 3. **Unblocks others:** it blocks a ticket outside the queue.
+ 4. **Linear priority.**
+ 5. **Smaller PR,** then **longest in the column.**
+5. **Find collisions.** Compare the queued PRs' `files`. Any overlap is a pair, and so is any two PRs touching the hot spots: `packages/server/api/src/assets/prompts/`, chat tool descriptions, the agent loop in `packages/server/worker/src/lib/execute/jobs/ee/agent/`. The higher one merges first and the lower one's owner rebases and re-runs CI right after. Put the pair on the card.
+6. **Show the queue card** and apply after one OK:
+ - state changes and kick-back comments through the Linear MCP;
+ - the order with `node .agents/skills/ai-task/linear.mjs order AI-41 AI-57 AI-60` (top first);
+ - no key: say where to drag each card in **Merge queue** ("drag AI-57 under AI-41").
+7. **Merging.** Only the owner of the top card merges, and only their own PR. Not on top? Wait, or ask in the channel. The one exception is an urgent fix (rule 4.1), which jumps the line and says so in the channel. After a merge, Linear moves it to Done; re-rank and tell the next owner if they need to rebase.
+
+Think the order is wrong? Say why in the ticket and re-run `/ai-task queue`, don't drag cards around it.
+
## Check: the team check-up (Thursday, or before a PM review)
`/ai-task check` (weekly) or `/ai-task check monthly`. Read only until the user approves a write. Any member can run it; the lead runs it every Thursday.
@@ -341,6 +390,7 @@ Ask before pushing, opening the PR, or posting to Linear or GitHub. Everything g
- **Late:** open issues past their due date. **Blocked:** an unfinished `blockedBy`.
- **Work in progress:** In Progress projects per lead, against the limit in "Start here". **Quiet:** In Progress projects with no update in 8 days.
- **Waiting:** AI PRs with no review after 1 working day, decisions past their decide-by date, and triage items older than 2 days.
+ - **Merge queue:** run Queue. Report its size, what's on top, any collision pairs, and cards to kick back.
- **Rituals:** repeating tickets skipped last time.
- **Habits:** AI PRs from the last 7 days without `Fixes AI-` or `Part of AI-` (use `gh pr list --state all --search "updated:>=<date>" --json number,author,body,files`), and new tickets missing their template's required parts. A nudge, not blame.
4. **Report** with the check card. Then offer the writes, and do only what the user picks:
@@ -368,5 +418,7 @@ Ask before pushing, opening the PR, or posting to Linear or GitHub. Everything g
- Move or close tickets the user didn't point at. Fix only what this task touches.
- Post security details publicly.
+- Merge a PR that isn't on top of the queue, unless it's urgent.
+- Reorder the queue or kick a card back without the user's OK.
- Run `git reset --hard`, `git checkout -- .` or `git clean`. Local env files must survive.
- Add process the "Start here" doc doesn't ask for.
diff --git a/.agents/skills/ai-task/linear.mjs b/.agents/skills/ai-task/linear.mjs
new file mode 100644
index 00000000000..785d9555a80
--- /dev/null
+++ b/.agents/skills/ai-task/linear.mjs
@@ -0,0 +1,105 @@
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+const SETTINGS_PATH = join(homedir(), '.claude', 'settings.json')
+const COMMANDS = { setup, order }
+
+const [command, ...args] = process.argv.slice(2)
+if (!COMMANDS[command]) {
+ fail('Usage: node linear.mjs setup | node linear.mjs order AI-41 AI-57 ...')
+}
+await COMMANDS[command](args)
+
+async function setup() {
+ if (!process.stdin.isTTY) {
+ fail('Run this in your own terminal (not inside Claude Code), so the key stays hidden.')
+ }
+ console.log('1. Open https://linear.app/settings/account/security')
+ console.log('2. New key, name it "Activepieces · <your name>\'s Claude (ai-task)", copy it')
+ const key = (await askHidden('3. Paste it here (hidden) and press Enter: ')).trim()
+ if (!key.startsWith('lin_api_')) {
+ fail('That doesn\'t look like a Linear key. It should start with lin_api_.')
+ }
+ const { viewer } = await linear({ key, query: '{ viewer { name } }' })
+ const settings = await readSettings()
+ await mkdir(dirname(SETTINGS_PATH), { recursive: true })
+ if (process.platform !== 'win32') {
+ await chmod(SETTINGS_PATH, 0o600).catch(() => undefined)
+ }
+ await writeFile(SETTINGS_PATH, JSON.stringify({ ...settings, env: { ...settings.env, LINEAR_API_KEY: key } }, null, 2) + '\n', { mode: 0o600 })
+ console.log(`\nSaved for ${viewer.name}. Restart Claude Code and you're set.`)
+}
+
+async function order(ids) {
+ const key = process.env.LINEAR_API_KEY
+ if (!key) {
+ fail('No LINEAR_API_KEY. Run: node .agents/skills/ai-task/linear.mjs setup')
+ }
+ if (ids.length === 0) {
+ fail('Give the ticket ids top first, e.g. order AI-41 AI-57')
+ }
+ const updates = ids.map((id, i) => `r${i}: issueUpdate(id: ${JSON.stringify(id)}, input: { sortOrder: ${(i + 1) * 1000} }) { success }`)
+ await linear({ key, query: `mutation { ${updates.join(' ')} }` })
+ console.log(`Ordered: ${ids.join(' > ')}`)
+}
+
+async function linear({ key, query }) {
+ const response = await fetch('https://api.linear.app/graphql', {
+ method: 'POST',
+ headers: { Authorization: key, 'Content-Type': 'application/json' },
+ body: JSON.stringify({ query }),
+ }).catch(() => fail('Couldn\'t reach Linear. Check your internet and try again.'))
+ const body = await response.json().catch(() => ({}))
+ if (!response.ok || !body.data || body.errors) {
+ fail(`Linear said no: ${body.errors?.[0]?.message ?? response.status}`)
+ }
+ return body.data
+}
+
+function askHidden(prompt) {
+ return new Promise((resolve) => {
+ process.stdout.write(prompt)
+ process.stdin.setRawMode(true)
+ process.stdin.resume()
+ process.stdin.setEncoding('utf8')
+ let value = ''
+ const onData = (chunk) => {
+ for (const char of chunk) {
+ if (char === '\u0003') {
+ process.stdout.write('\n')
+ process.exit(1)
+ }
+ if (char === '\r' || char === '\n') {
+ process.stdin.setRawMode(false)
+ process.stdin.pause()
+ process.stdin.off('data', onData)
+ process.stdout.write('\n')
+ resolve(value)
+ return
+ }
+ if (char === '\u007f' || char === '\b') {
+ value = value.slice(0, -1)
+ continue
+ }
+ value += char
+ }
+ }
+ process.stdin.on('data', onData)
+ })
+}
+
+async function readSettings() {
+ const raw = await readFile(SETTINGS_PATH, 'utf8').catch(() => '{}')
+ try {
+ return JSON.parse(raw)
+ }
+ catch {
+ fail(`${SETTINGS_PATH} isn't valid JSON, so I didn't touch it. Fix it and run this again.`)
+ }
+}
+
+function fail(message) {
+ console.error(`\n${message}`)
+ process.exit(1)
+}