toga-ai 1.0.249 → 1.0.250

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.249",
+  "version": "1.0.250",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",

package/skills/plan-ticket/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: plan-ticket
+description: Build an implementation plan for a ClickUp ticket end-to-end. Invoke as `/plan-ticket <TICKET-ID>` (e.g. `/plan-ticket TRUE-79868`). Retrieves the full ticket from ClickUp, interrogates Talos (meeting-notes AI) and the local codebase for context, primes team framework knowledge by self-answering /kickoff from that gathered context, synthesizes a phased plan, saves it to test/@dave/approach/<TICKET>.md, shows a preview and iterates until you approve, then pushes the approved plan as formatted rich text to the ticket's Pseudocode field. Trigger on "/plan-ticket", "plan this ticket", "build a plan for <ticket>".
+---
+
+# plan-ticket — ticket → researched plan → ClickUp Pseudocode field
+
+Given a ClickUp ticket id, produce a grounded implementation plan and write it both to
+`test/@dave/approach/<TICKET>.md` and to the ticket's **📝 Pseudocode** custom field
+(rendered, not raw markdown).
+
+Helper scripts live in `scripts/` next to this file. They are run with `node`. All Talos
+auth is automatic — see **Token handling** below; the developer should never have to paste a
+token unless the 30-day refresh token has expired.
+
+Environment used: `CLICKUP_API_KEY`, `CLICKUP_TEAM_ID` (already in the session env). Talos
+tokens live in `~/.talos/credentials.json` (NOT in the repo).
+
+---
+
+## Step 0 — Resolve the ticket id
+
+The id is the argument after `/plan-ticket` (e.g. `TRUE-79868`). If none was given, ask for it.
+
+## Step 1 — Retrieve the full ticket from ClickUp
+
+```bash
+node ".claude/skills/plan-ticket/scripts/clickup.js" get <TICKET>
+```
+
+This prints JSON: `{name, status, description, pseudocodeFieldId, fields:{...non-empty custom fields...}}`.
+Read **all** of it — name, user story / description, and any populated custom fields (Application,
+Requirements, Epic, Acceptance criteria, etc.). These details drive both the Talos query and the
+codebase investigation. The **Application / Client** fields here also feed the self-answered
+kickoff in Step 4. Note `pseudocodeFieldId` for the push in Step 7.
+
+## Step 2 — Investigate the local codebase FIRST (before Talos)
+
+**Do the code recon before querying Talos.** Investigating first surfaces the *specific*
+unknowns — what already exists vs. what's build-from-scratch, FK topology, schema quirks,
+sibling/precedent plans in `test/@dave/approach/`, the exact reference handlers the ticket
+mirrors — which lets Step 3 ask Talos sharp, targeted questions ("a meeting discuss the DELETE
+policy for X, given Sales/Opportunities hold RESTRICT FKs?") instead of generic ones. A generic
+Talos query usually returns "no specific notes"; a code-informed one is far more likely to hit.
+
+Ground everything in the real code. Prefer the TOGA `planner` agent for non-trivial tickets (it
+reads deep docs in its own context and returns a phased plan); for small tickets, read the
+specific files directly. Open the actual classes, schema (`dbchanges2` / the live core2 reader),
+and reference handlers the ticket touches — do not guess paths. **Come out of this step with a
+concrete list of open questions / decisions to put to Talos.**
+
+## Step 3 — Interrogate Talos (meeting-notes AI), informed by the code findings
+
+Compose the question from the ticket details **plus the specific unknowns/decisions Step 2
+surfaced** — name the concrete choices you need ruled on (delete policy, scope boundaries,
+owners, deadlines) and the architecture you found, so Talos can confirm/deny against real
+meeting notes. Then:
+
+```bash
+node ".claude/skills/plan-ticket/scripts/talos.js" query "<your code-informed question>"
+```
+
+The helper auto-refreshes the access token, opens a thread against DevCore, auto-accepts the
+agent's plan-approval interrupt, and prints the assistant's answer. Capture what it finds
+(with the meeting/date citations it gives) — and note explicitly when it finds nothing specific.
+
+> Token handling: `talos.js` reads `~/.talos/credentials.json`, and if the cached access token
+> is missing/expiring it calls `POST {apiHost}/v2/auth/refresh` with the stored refresh token to
+> mint a new one (transactionId must be unique per call — the helper generates it). If the
+> **refresh** token itself has expired (~30 days), the helper prints clear instructions: the
+> developer logs in at `talos.togaiq.com`, grabs the `accessToken` + `refreshToken` from the
+> browser (DevTools → Application/Local Storage, or any `api.togaiq.com` request's
+> `Authorization` header), and runs `node scripts/talos.js set-tokens <access> <refresh>` once.
+> Never echo tokens into chat, memory, the KB, or any committed file.
+
+## Step 4 — Prime framework context via kickoff (self-answered from Steps 1–3)
+
+Now that you hold the ticket (Step 1), the code recon (Step 2), and the Talos findings
+(Step 3), invoke **`/kickoff`** to prime the team knowledge base — but **answer its interview
+yourself from what you just gathered** so it never stops to ask the developer. Steps 1–2
+already tell you everything kickoff's Step 2 interview needs:
+
+- **Framework (1.0 / 2.0 / both)** — from the repos the code sweep landed in (`worker/`,
+  `library/`, `toga/`, etc. → 1.0; `worker2/`, `api2/`, `_underscore/`, the React SPAs → 2.0)
+  plus the ticket's **Application** field.
+- **Layer (front / back / hybrid)** — from the repo types touched (React SPA → front-end;
+  PHP API/worker → back-end; both → hybrid).
+- **Repos** — the in-scope repos the Step 2 sweep identified.
+- **Client** — from the ticket's Application/Client field or ClickUp space; use
+  **"shared / internal"** when the ticket isn't client-specific.
+
+Invoke kickoff with these pre-filled as the trailing argument so its interview is satisfied and
+it goes straight to preflight + priming, e.g.:
+
+```
+/kickoff <framework> <layer>, repos: <repos>, client: <client> — <ticket title>
+```
+
+**Only stop to ask the developer if a gate answer is genuinely ambiguous** after all three
+inputs (e.g. the code spans both frameworks and neither ticket nor Talos says which is in
+scope). Otherwise let kickoff run unattended — it checks for harness updates, resolves the
+load-set, and returns the `context-primer` briefing.
+
+**Carry the primer briefing into synthesis.** The framework rules, gotchas, and client
+variations it surfaces directly inform the plan — fold them into the **Architecture decision**
+and **Risks/gotchas** sections in Step 5. This is the payoff of priming before synthesizing.
+
+> Ordering note: the code sweep (Step 2) intentionally runs *before* kickoff. Kickoff's gate
+> hook blocks reads until it primes, and doing the recon first is exactly what lets you
+> self-answer the interview here. Once kickoff's preflight runs, the gate releases and Step 5
+> synthesis can read freely.
+
+## Step 5 — Synthesize the plan and save it
+
+Write a phased plan to `test/@dave/approach/<TICKET>.md`. Structure: a **`# <TICKET> — <title>`
+heading**, then a **one-line bold header** (`**Repos:** … · **Framework:** … · **Client:** …`,
+plus a `· **Sibling/precedent:** <TICKET>` when one exists), then Summary · Meeting-notes
+context (Talos, with citations + an explicit "no notes found" note where true) · What already
+exists · Architecture decision · Phases (each: title, exact file paths, pseudocode) · Testing ·
+Risks/gotchas · Rollout/verification · Owners/open-questions to confirm · Key files. Run any
+relevant TOGA reviewers (php-reviewer/sql-reviewer) if code-shaped decisions warrant it.
+
+> **ANY SQL SHOWN IN THE PLAN'S PSEUDOCODE MUST ALREADY FOLLOW THE TEAM SQL FORMATTING
+> CONVENTIONS — NO ONE-LINE QUERIES, EVEN IN PSEUDOCODE.** WRITE EVERY QUERY MULTI-LINE:
+> KEYWORDS UPPERCASE, EACH CLAUSE ON ITS OWN LINE, TABLE/COLUMNS INDENTED ON THEIR OWN LINES,
+> NO `SELECT *`. THE PLAN IS THE TEMPLATE THE WORK-TICKET STEP COPIES FROM, SO A SLOPPY
+> ONE-LINER HERE BECOMES A STANDARDS VIOLATION IN THE SHIPPED CODE.
+
+**No point-in-time status.** Do not record what's currently deployed / Released / live (e.g. "the enqueuer is Released only on X today", "PR #123 is merged") — it's stale the moment it's written. Describe durable mechanisms, decisions, and required steps instead. (Matches the team rule against deployment status in docs.)
+
+**Length limit: keep the plan to ≤ 150 lines.** Be terse and high-signal — favor tight
+pseudocode and bullet lists over prose, fold related points into one line, and cut anything that
+doesn't change what the implementer does. If the content can't fit, trim the lowest-value detail
+(verbose rationale, repeated caveats) rather than dropping a section. After writing, verify with
+`wc -l test/@dave/approach/<TICKET>.md` and tighten if it's over.
+
+## Step 6 — Preview & approval loop (gate — do NOT push until approved)
+
+**The plan does NOT go to ClickUp automatically.** After writing the `.md`, present it to the
+developer for review and **wait for explicit approval** before Step 7.
+
+1. Show a **preview**: the full plan content (or, if long, the Summary + Architecture decision +
+   Phase titles + Owners/open-questions, with the rest available on request) so the developer can
+   judge it in-chat. Note the line count (must be ≤150).
+2. Prompt clearly: *"Approve this plan for the TRUE-XXXXX Pseudocode field, or tell me what to
+   change?"*
+3. **Iterate**: incorporate the developer's comments — edit `test/@dave/approach/<TICKET>.md`,
+   re-investigate (codebase or Talos) if a change needs grounding, re-check ≤150 lines, and show
+   the updated preview. Go back and forth until the developer explicitly approves.
+4. Only on explicit approval ("approved", "looks good", "ship it", etc.) proceed to Step 7. Do
+   **not** push on ambiguous replies — ask.
+
+## Step 7 — Push the approved plan to the Pseudocode field (rendered)
+
+Only after Step 6 approval. ClickUp custom text fields render formatting from a **Quill Delta**
+in `value_richtext`, not markdown in `value`. The helper converts the markdown and pushes both:
+
+```bash
+node ".claude/skills/plan-ticket/scripts/clickup.js" push <TICKET> "test/@dave/approach/<TICKET>.md"
+```
+
+It resolves the Pseudocode field id by name, converts markdown → Delta, and POSTs
+`{value:<plain>, value_richtext:<Delta JSON string>}`. Confirm it returns 200.
+
+**Overwrite guard.** `push` **refuses** (exit 2) if the Pseudocode field already has content, to
+avoid clobbering a manual/teammate edit — it prints the existing content. If that happens: show
+the existing content to the developer, confirm it's safe to replace, and only then re-run with
+`--force`:
+```bash
+node ".claude/skills/plan-ticket/scripts/clickup.js" push <TICKET> "test/@dave/approach/<TICKET>.md" --force
+```
+(A prior plan *we* wrote and the developer just re-approved is fine to replace — but still
+surface it so the developer knows what's being overwritten.)
+
+## Step 8 — Report
+
+Summarize: ticket title, what Talos surfaced (or didn't), the plan's key decisions + any
+owners/open questions to confirm, and the two outputs (the `.md` path + the Pseudocode field).
+Offer `/capture` if a durable KB-worthy finding emerged.
+
+---
+
+## Notes & reuse
+
+- The markdown→Quill-Delta conversion rules and the `value_richtext` mechanism are documented in
+  the team KB (`2.0/apps/worker2/features/clickup-richtext-api.md`) and personal memory
+  (`reference_clickup_richtext_field_delta`).
+- Talos is a LangGraph Agent Protocol server (`api.togaiq.com`); DevCore is the dev-team assistant
+  wired to the meeting-notes knowledge base. Other assistants (One/Sales/HR) are in
+  `credentials.json` under `assistants` if a different one is ever needed.
+- `talos.js query` accepts an optional 2nd arg = assistant key (default `devcore`).

package/skills/plan-ticket/scripts/clickup.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/*
+ * ClickUp helper for the plan-ticket skill.
+ *
+ * Usage:
+ *   node clickup.js get  <TASK>                 # print ticket details + pseudocodeFieldId as JSON
+ *   node clickup.js push <TASK> <md-path>       # convert markdown -> Quill Delta, push to Pseudocode field
+ *
+ * Env: CLICKUP_API_KEY, CLICKUP_TEAM_ID.
+ */
+const fs = require('fs');
+
+const KEY = process.env.CLICKUP_API_KEY;
+const TEAM = process.env.CLICKUP_TEAM_ID;
+const PSEUDOCODE_FIELD_NAME = 'Pseudocode'; // matched case-insensitively (field is "📝 Pseudocode")
+
+function taskUrl(task, suffix = '') {
+  return `https://api.clickup.com/api/v2/task/${task}${suffix}?custom_task_ids=true&team_id=${TEAM}`;
+}
+async function getTask(task) {
+  const r = await fetch(taskUrl(task), { headers: { Authorization: KEY } });
+  if (!r.ok) throw new Error('ClickUp get failed (' + r.status + '): ' + (await r.text()).slice(0, 300));
+  return r.json();
+}
+function findPseudocodeField(t) {
+  const fields = t.custom_fields || [];
+  const wanted = PSEUDOCODE_FIELD_NAME.toLowerCase();
+  // The target is the rich TEXT field named "📝 Pseudocode" — NOT "Pseudocode Required"
+  // (checkbox), "Pseudocode Review" (number), or "Pseudocode Reviewer" (users). So require
+  // a text field whose name contains "pseudocode".
+  return fields.find(f => f.type === 'text' && (f.name || '').toLowerCase().includes(wanted))
+    // fallback: exact name match ignoring emoji/whitespace
+    || fields.find(f => (f.name || '').toLowerCase().replace(/[^a-z]/g, '') === wanted);
+}
+
+/* ----------------------------------------------------------- markdown -> Quill Delta */
+function inline(text) {
+  const out = [];
+  let i = 0;
+  const push = (s, a) => { if (s) out.push(a ? { insert: s, attributes: a } : { insert: s }); };
+  while (i < text.length) {
+    const cands = [];
+    let p = text.indexOf('`', i); if (p !== -1) cands.push([p, 'code']);
+    p = text.indexOf('**', i); if (p !== -1) cands.push([p, 'bold']);
+    p = text.indexOf('[', i); if (p !== -1) cands.push([p, 'link']);
+    let it = -1;
+    for (let k = i; k < text.length; k++) { if (text[k] === '*' && text[k + 1] !== '*' && (k === 0 || text[k - 1] !== '*')) { it = k; break; } }
+    if (it !== -1) cands.push([it, 'italic']);
+    if (!cands.length) { push(text.slice(i)); break; }
+    cands.sort((a, b) => a[0] - b[0]);
+    const [pos, kind] = cands[0];
+    if (pos > i) push(text.slice(i, pos));
+    if (kind === 'code') { const e = text.indexOf('`', pos + 1); if (e === -1) { push(text.slice(pos)); break; } push(text.slice(pos + 1, e), { code: true }); i = e + 1; }
+    else if (kind === 'bold') { const e = text.indexOf('**', pos + 2); if (e === -1) { push(text.slice(pos)); break; } push(text.slice(pos + 2, e), { bold: true }); i = e + 2; }
+    else if (kind === 'italic') { const e = text.indexOf('*', pos + 1); if (e === -1) { push(text.slice(pos)); break; } push(text.slice(pos + 1, e), { italic: true }); i = e + 1; }
+    else { const m = /^\[([^\]]+)\]\(([^)]+)\)/.exec(text.slice(pos)); if (!m) { push(text.slice(pos, pos + 1)); i = pos + 1; } else { push(m[1], { link: m[2] }); i = pos + m[0].length; } }
+  }
+  return out;
+}
+function mdToDelta(md) {
+  md = md.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  const lines = md.split('\n');
+  const ops = [];
+  const pushInline = (t) => inline(t).forEach(o => ops.push(o));
+  const nl = (a) => ops.push(a ? { insert: '\n', attributes: a } : { insert: '\n' });
+  let i = 0;
+  while (i < lines.length) {
+    let line = lines[i];
+    if (/^```/.test(line)) { i++; while (i < lines.length && !/^```/.test(lines[i])) { ops.push({ insert: lines[i] }); nl({ 'code-block': true }); i++; } i++; continue; }
+    if (/^\s*\|/.test(line)) {
+      const rows = []; while (i < lines.length && /^\s*\|/.test(lines[i])) { rows.push(lines[i]); i++; }
+      const parsed = rows.map(r => r.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map(c => c.trim()))
+        .filter(cells => !cells.every(c => /^:?-{2,}:?$/.test(c) || c === ''));
+      parsed.forEach((cells, idx) => { const joined = cells.filter(c => c !== '').join('  —  '); pushInline(joined); nl(idx === 0 ? { bold: true } : { list: 'bullet' }); });
+      continue;
+    }
+    let m = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (m) { pushInline(m[2]); nl({ header: Math.min(m[1].length, 3) }); i++; continue; }
+    if (/^\s*([-*_])\1{2,}\s*$/.test(line)) { nl(); i++; continue; }
+    m = /^(\s*)(\d+)\.\s+(.*)$/.exec(line);
+    if (m) { const ind = Math.floor(m[1].length / 3); pushInline(m[3]); nl(ind > 0 ? { list: 'ordered', indent: ind } : { list: 'ordered' }); i++; continue; }
+    m = /^(\s*)[-*]\s+(.*)$/.exec(line);
+    if (m) { const ind = Math.floor(m[1].length / 2); pushInline(m[2]); nl(ind > 0 ? { list: 'bullet', indent: ind } : { list: 'bullet' }); i++; continue; }
+    m = /^>\s?(.*)$/.exec(line);
+    if (m) { pushInline(m[1]); nl({ blockquote: true }); i++; continue; }
+    if (line.trim() === '') { nl(); i++; continue; }
+    pushInline(line); nl(); i++;
+  }
+  const plain = ops.map(o => (typeof o.insert === 'string' ? o.insert : '')).join('');
+  return { delta: { ops }, plain };
+}
+
+async function push(task, mdPath, force) {
+  const t = await getTask(task);
+  const field = findPseudocodeField(t);
+  if (!field) throw new Error('No "Pseudocode" custom field found on ' + task);
+  // Overwrite guard: refuse to clobber an already-populated field unless --force.
+  const existing = (field.value != null && String(field.value).trim() !== '') ? String(field.value) : '';
+  if (existing && !force) {
+    console.error('REFUSING to overwrite: "' + field.name + '" already has content (' + existing.length + ' chars).');
+    console.error('--- current field content (first 500 chars) ---');
+    console.error(existing.slice(0, 500));
+    console.error('--- re-run with --force to replace ---');
+    process.exitCode = 2;
+    return;
+  }
+  const md = fs.readFileSync(mdPath, 'utf8');
+  const { delta, plain } = mdToDelta(md);
+  const url = `https://api.clickup.com/api/v2/task/${task}/field/${field.id}?custom_task_ids=true&team_id=${TEAM}`;
+  const body = JSON.stringify({ value: plain, value_richtext: JSON.stringify(delta) });
+  const r = await fetch(url, { method: 'POST', headers: { Authorization: KEY, 'Content-Type': 'application/json' }, body });
+  console.log('push ->', r.status, 'field', field.name, '(' + field.id + ')', 'ops', delta.ops.length, 'plain', plain.length);
+  if (!r.ok) { console.error(await r.text()); process.exitCode = 1; }
+}
+
+(async () => {
+  const argv = process.argv.slice(2);
+  const force = argv.includes('--force');
+  const [cmd, task, arg] = argv.filter(a => a !== '--force');
+  if (!KEY || !TEAM) { console.error('ERROR: CLICKUP_API_KEY / CLICKUP_TEAM_ID not set'); process.exit(1); }
+  try {
+    if (cmd === 'get') {
+      const t = await getTask(task);
+      const field = findPseudocodeField(t);
+      const fields = {};
+      (t.custom_fields || []).forEach(f => { if (f.value !== undefined && f.value !== null && f.value !== '') fields[f.name] = f.value; });
+      console.log(JSON.stringify({
+        id: t.id, custom_id: t.custom_id, name: t.name, status: t.status?.status,
+        description: t.description || t.text_content || '',
+        pseudocodeFieldId: field?.id || null,
+        url: t.url, fields,
+      }, null, 2));
+    } else if (cmd === 'push') {
+      if (!arg) throw new Error('Usage: push <TASK> <md-path> [--force]');
+      await push(task, arg, force);
+    } else {
+      console.log('commands: get <TASK> | push <TASK> <md-path> [--force]');
+    }
+  } catch (e) { console.error('ERROR:', e.message); process.exitCode = 1; }
+})();

package/skills/plan-ticket/scripts/talos.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+/*
+ * Talos (TOGa IQ) helper for the plan-ticket skill.
+ *
+ * Auth is automatic: reads ~/.talos/credentials.json and refreshes the short-lived (1h)
+ * access token from the stored 30-day refresh token via POST {apiHost}/v2/auth/refresh.
+ * The developer only ever pastes tokens once (set-tokens), and again only if the refresh
+ * token itself expires (~30 days).
+ *
+ * Usage:
+ *   node talos.js token                       # print a valid access token (refresh if needed)
+ *   node talos.js status                      # show token expiries
+ *   node talos.js set-tokens <access> <refresh>
+ *   node talos.js query "<question>" [assistantKey=devcore]
+ */
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const CRED_DIR = path.join(os.homedir(), '.talos');
+const CRED_PATH = path.join(CRED_DIR, 'credentials.json');
+
+function load() {
+  if (!fs.existsSync(CRED_PATH)) {
+    throw new Error(
+      'No Talos credentials at ' + CRED_PATH + '. Log in at talos.togaiq.com, copy the ' +
+      'accessToken + refreshToken (DevTools → Local Storage, or an api.togaiq.com request ' +
+      'Authorization header), then run: node talos.js set-tokens <access> <refresh>'
+    );
+  }
+  return JSON.parse(fs.readFileSync(CRED_PATH, 'utf8'));
+}
+function save(c) {
+  fs.mkdirSync(CRED_DIR, { recursive: true });
+  fs.writeFileSync(CRED_PATH, JSON.stringify(c, null, 2));
+}
+function jwtExp(jwt) {
+  try { return JSON.parse(Buffer.from(jwt.split('.')[1], 'base64').toString()).exp || 0; }
+  catch { return 0; }
+}
+function now() { return Math.floor(Date.now() / 1000); }
+
+async function refresh(c) {
+  if (!c.refreshToken) throw new Error('No refresh token stored — run set-tokens.');
+  if (c.refreshExp && c.refreshExp <= now()) {
+    throw new Error(
+      'Talos REFRESH token expired. Log in at talos.togaiq.com, grab a fresh accessToken + ' +
+      'refreshToken, and run: node talos.js set-tokens <access> <refresh>'
+    );
+  }
+  const host = c.apiHost || 'https://api-writer.togahub.com';
+  const tid = crypto.randomUUID();
+  const r = await fetch(`${host}/v2/auth/refresh?transactionId=${tid}`, {
+    method: 'POST',
+    headers: { 'Authorization': 'Bearer ' + c.refreshToken, 'Content-Type': 'application/json' },
+  });
+  const j = await r.json().catch(() => ({}));
+  if (!j.isSuccess || !j.data?.tokens?.access) {
+    throw new Error('Refresh failed (' + r.status + '): ' + JSON.stringify(j.messages || j).slice(0, 300) +
+      ' — if the refresh token is expired, run set-tokens with fresh values.');
+  }
+  c.accessToken = j.data.tokens.access;
+  c.accessExp = jwtExp(c.accessToken);
+  if (j.data.tokens.refresh) { c.refreshToken = j.data.tokens.refresh; c.refreshExp = jwtExp(c.refreshToken); }
+  save(c);
+  return c.accessToken;
+}
+
+async function getToken() {
+  const c = load();
+  // valid if present and not expiring within 120s
+  if (c.accessToken && c.accessExp && c.accessExp - now() > 120) return c.accessToken;
+  return refresh(c);
+}
+
+async function query(question, assistantKey) {
+  const c = load();
+  const token = await getToken();
+  const talos = c.talosHost || 'https://api.togaiq.com';
+  const assistants = c.assistants || {};
+  const assistant = assistants[assistantKey || 'devcore'] || assistants.devcore;
+  if (!assistant) throw new Error('No assistant id configured for "' + (assistantKey || 'devcore') + '"');
+  const H = () => ({ 'Authorization': 'Bearer ' + (c.accessToken || token), 'Content-Type': 'application/json' });
+
+  // create thread
+  let r = await fetch(`${talos}/threads`, { method: 'POST', headers: H(),
+    body: JSON.stringify({ metadata: { source: 'plan-ticket-skill' } }) });
+  if (r.status === 401) { await refresh(c); r = await fetch(`${talos}/threads`, { method: 'POST', headers: H(), body: JSON.stringify({ metadata: { source: 'plan-ticket-skill' } }) }); }
+  const th = await r.json();
+  const tid = th.thread_id;
+  if (!tid) throw new Error('Could not create thread: ' + JSON.stringify(th).slice(0, 300));
+
+  const extract = (j) => {
+    const msgs = j.messages || j.values?.messages;
+    if (Array.isArray(msgs)) {
+      const last = [...msgs].reverse().find(m => m.type === 'ai' || m.role === 'assistant');
+      if (last) return typeof last.content === 'string' ? last.content : JSON.stringify(last.content);
+    }
+    return null;
+  };
+  const isInterrupt = (j) => j.__interrupt__ || (Array.isArray(j.tasks) && j.tasks.some(t => t.interrupts?.length));
+
+  // initial run
+  let body = { assistant_id: assistant, input: { messages: [{ role: 'user', content: question }] } };
+  r = await fetch(`${talos}/threads/${tid}/runs/wait`, { method: 'POST', headers: H(), body: JSON.stringify(body) });
+  let j = await r.json().catch(() => ({}));
+
+  // auto-accept up to 5 plan-approval interrupts
+  for (let i = 0; i < 5 && isInterrupt(j); i++) {
+    body = { assistant_id: assistant, command: { resume: [{ type: 'accept', args: null }] } };
+    r = await fetch(`${talos}/threads/${tid}/runs/wait`, { method: 'POST', headers: H(), body: JSON.stringify(body) });
+    j = await r.json().catch(() => ({}));
+  }
+  const answer = extract(j);
+  return { thread_id: tid, answer: answer || JSON.stringify(j).slice(0, 1500) };
+}
+
+(async () => {
+  const [cmd, ...rest] = process.argv.slice(2);
+  try {
+    if (cmd === 'set-tokens') {
+      const [access, refreshTok] = rest;
+      if (!access || !refreshTok) throw new Error('Usage: set-tokens <access> <refresh>');
+      const c = fs.existsSync(CRED_PATH) ? JSON.parse(fs.readFileSync(CRED_PATH, 'utf8')) : {};
+      c.accessToken = access; c.accessExp = jwtExp(access);
+      c.refreshToken = refreshTok; c.refreshExp = jwtExp(refreshTok);
+      c.apiHost = c.apiHost || 'https://api-writer.togahub.com';
+      c.talosHost = c.talosHost || 'https://api.togaiq.com';
+      c.assistants = c.assistants || {
+        devcore: 'a5b1833d-b47c-5cb3-8cda-963f1cc74a33',
+        one: 'c6def0ad-659f-5aa8-b723-4a5a7d04578a',
+        sales: '842d173f-c084-583d-9eaf-ea692dd18356',
+        hr: 'eba7ca71-9b3f-52fe-b5bf-3ebd58aab720',
+      };
+      save(c);
+      console.log('Stored. accessExp', new Date(c.accessExp * 1000).toISOString(), 'refreshExp', new Date(c.refreshExp * 1000).toISOString());
+    } else if (cmd === 'status') {
+      const c = load();
+      console.log('access  exp:', c.accessExp ? new Date(c.accessExp * 1000).toISOString() : 'none', c.accessExp && c.accessExp > now() ? '(valid)' : '(expired/none)');
+      console.log('refresh exp:', c.refreshExp ? new Date(c.refreshExp * 1000).toISOString() : 'none', c.refreshExp && c.refreshExp > now() ? '(valid)' : '(EXPIRED — re-paste)');
+    } else if (cmd === 'token') {
+      console.log(await getToken());
+    } else if (cmd === 'query') {
+      const out = await query(rest[0], rest[1]);
+      console.log('THREAD:', out.thread_id);
+      console.log('=== TALOS ANSWER ===');
+      console.log(out.answer);
+    } else {
+      console.log('commands: token | status | set-tokens <access> <refresh> | query "<q>" [assistantKey]');
+    }
+  } catch (e) {
+    console.error('ERROR:', e.message);
+    process.exit(1);
+  }
+})();

package/skills/rework-ticket/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: rework-ticket
+description: Apply review feedback to an already-PR'd ClickUp ticket. Invoke as `/rework-ticket <TICKET-ID>` (e.g. `/rework-ticket TRUE-79162`) AFTER `/work-ticket` has opened PRs and a reviewer has left feedback. Finds the ticket's existing branches/PRs across the relevant repos, gathers every feedback source (ClickUp comments + GitHub PR reviews, inline review comments, and failing checks), primes framework context via /kickoff (self-answered), checks out each existing branch, implements the requested changes with TOGA reviewers, then pushes back to the SAME branch so the SAME PR updates — never opens a new PR. Replies on the ticket with what was addressed and stops; never changes ClickUp ticket status. Trigger on "/rework-ticket", "rework the ticket", "apply the PR feedback for <ticket>", "address review comments on <ticket>", "revise <ticket>".
+---
+
+# rework-ticket — gather feedback → revise the existing branch → push to the SAME PR
+
+The revision-loop companion to **`/work-ticket`**. Where `work-ticket` takes an approved plan and
+produces branches + PRs, `rework-ticket` takes the **feedback left on those PRs and the ticket** and
+revises the **existing** branches in place: it discovers the ticket's branches/PRs, reads every
+feedback channel, primes context, checks out each branch, implements the requested changes (with
+TOGA reviewers), and **pushes back to the same branch** so the **same PR** updates. It never opens a
+new PR and never changes ClickUp ticket status.
+
+It runs autonomously through the push, then **stops**. The developer re-requests review; moving the
+ticket forward is always a manual developer action.
+
+Helper scripts are reused from the sibling `plan-ticket` skill (`scripts/clickup.js`, `get` only).
+`gh` is already authenticated. Environment used: `CLICKUP_API_KEY`, `CLICKUP_TEAM_ID`.
+
+---
+
+## Step 0 — Resolve the ticket id
+
+The id is the argument after `/rework-ticket` (e.g. `TRUE-79162`). If none was given, ask for it.
+The **bare ticket id is the branch name** `work-ticket` used (`TRUE-79162`), so it is also the key
+for finding the branches and PRs to revise.
+
+## Step 1 — Load the ticket and discover its branches + PRs
+
+1. **Load the ticket** for title, status, url, and the internal `CU-<id>`:
+   ```bash
+   node ".claude/skills/plan-ticket/scripts/clickup.js" get <TICKET>
+   ```
+   Capture `name` (title), `url`, the internal `id` (the `CU-<id>` form), and — if present — the
+   **📝 Pseudocode** field, whose `Repos:` header lists the in-scope repos. The Pseudocode field is
+   the plan that the PRs implement; use its `Repos:` line as the candidate repo set.
+
+2. **Find the existing PRs/branches.** The authoritative list is usually the PR-links comment
+   `work-ticket` posted on the ticket (Step 1's comment fetch below will surface it). Confirm each by
+   asking GitHub directly — for every candidate repo from the `Repos:` header, list any PR whose head
+   branch is the bare ticket id:
+   ```bash
+   gh pr list --repo <owner/repo> --head <TICKET> --state all \
+     --json number,title,state,headRefName,url,isDraft
+   ```
+   Build a map `{repo, owner/repo, prNumber, branch:<TICKET>, repo-path}`. Resolve each repo's local
+   path from its `repo-path-<repo>` memory (never guess). A repo in the plan with **no** matching PR
+   is simply not in scope for this rework — note it, don't invent one.
+
+   > **The `test` repo has no PR** — `work-ticket` commits its harnesses straight to `master`
+   > ([[feedback_test_repo_commit_to_master]]). If feedback touches a `test/@dave` tool, revise it on
+   > `master` directly (commit + push to master), not via a branch/PR.
+
+## Step 2 — Gather EVERY feedback source (this is the heart of the skill)
+
+Do not act on a single channel — collect them all, then synthesize one concrete change-list. Read,
+in your own analysis (delegate the heavy reading to a subagent if it is large):
+
+1. **ClickUp comments** (the reliable channel — `work-ticket` always posts here):
+   ```bash
+   node -e 'const k=process.env.CLICKUP_API_KEY,t=process.env.CLICKUP_TEAM_ID;
+   fetch("https://api.clickup.com/api/v2/task/<TICKET>/comment?custom_task_ids=true&team_id="+t,
+    {headers:{Authorization:k}}).then(r=>r.json()).then(d=>console.log(JSON.stringify(
+      (d.comments||[]).map(c=>({by:c.user&&c.user.username,date:c.date,text:c.comment_text})),null,2)))'
+   ```
+   Read newest-last; the developer's review notes and any "please change X" land here.
+
+2. **GitHub PR feedback** — for each PR from Step 1, pull all three sub-channels:
+   ```bash
+   # PR-level reviews (APPROVED / CHANGES_REQUESTED + the review body) and top-level conversation
+   gh pr view <prNumber> --repo <owner/repo> \
+     --json title,body,state,reviewDecision,reviews,comments
+   # Inline code-review comments (path + line + body) -- the line-by-line asks
+   gh api repos/<owner/repo>/pulls/<prNumber>/comments \
+     --jq '.[] | {path, line, body, user: .user.login}'
+   # Failing CI/checks are also feedback to fix
+   gh pr checks <prNumber> --repo <owner/repo>
+   ```
+   Treat `reviewDecision: CHANGES_REQUESTED`, any unresolved inline comment, and any failing check as
+   a required change. A review thread phrased as a question is still a change request — address it in
+   code or answer it in your reply (Step 6).
+
+3. **Synthesize a change-list.** Produce a concrete, deduplicated list: for each item, the **repo +
+   file:line**, what is being asked, and how you will satisfy it. If two channels conflict, the most
+   recent **ClickUp comment from the developer wins** (it is the human decision); note the conflict.
+   If any feedback is genuinely ambiguous and changes what you build, ask the developer **once** (a
+   single `AskUserQuestion`) before editing — otherwise proceed.
+
+## Step 3 — Prime framework context via kickoff (self-answered)
+
+Same pattern as `work-ticket` Step 2: invoke **`/kickoff`** and answer its interview yourself from the
+plan's `Repos:` header (map repos → framework/layer/client), passing the change-list as the task:
+
+```
+/kickoff <framework> <layer>, repos: <repos>, client: <client> — rework <TICKET> <title>: <one-line change summary>
+```
+
+Carry the `context-primer` briefing into Step 5. Only stop to ask if a kickoff gate answer is
+genuinely ambiguous.
+
+## Step 4 — Check out each EXISTING branch (fetch first; do NOT create a new branch)
+
+For each repo in the Step 1 map, inside that repo's path:
+
+1. **Confirm a clean tree** — `git -C "<repo-path>" status --porcelain` should be empty (or contain
+   only files you are about to rework). Stop and surface anything unexpected rather than committing
+   over a stranger's uncommitted work.
+2. **Fetch and check out the ticket branch, then fast-forward to the PR head:**
+   ```bash
+   git -C "<repo-path>" fetch origin --quiet
+   git -C "<repo-path>" checkout TRUE-XXXX        # creates a local tracking branch from origin/TRUE-XXXX if needed
+   git -C "<repo-path>" pull --ff-only origin TRUE-XXXX
+   ```
+   This is the key difference from `work-ticket`: the branch **already exists on the remote** (it is
+   the open PR's head) — you must land your revisions **on that same branch**, not a fresh one. So you
+   check it out and pull the current PR head; you do **not** `checkout -b` and you do **not** re-base
+   it onto `origin/<default>` (that would rewrite the PR history). If `--ff-only` is rejected because
+   the remote branch moved in a way local can't fast-forward, stop and surface it — do not force
+   anything.
+   - For the **`test` repo**, there is no branch: `git checkout master && git pull --ff-only`.
+
+## Step 5 — Implement the change-list, then verify
+
+Apply the synthesized changes against the real files the feedback names. Drive non-trivial work as
+implement → verify with subagents so the conversation stays the conductor (same discipline as
+`work-ticket` Step 3):
+
+1. Make the edits the feedback requires — and **only** those (rework is scoped to the feedback; do not
+   re-architect untouched code).
+2. After each PHP file, run the TOGA reviewers (`php-reviewer`; `sql-reviewer` for SQL/schema;
+   `security-reviewer` when warranted) — **maker ≠ checker** — and loop until clean. Lint with the
+   right binary (`php -l`; 1.0 repos are PHP 7.2 → `C:\xampp7\php\php.exe -l`).
+3. Honor team rules throughout: parameterized queries only, no bare catch / `@`, named constants over
+   magic numbers, return-type declarations, no commented-out code, no secrets or absolute local paths.
+
+> **ALL SQL MUST FOLLOW THE TEAM SQL FORMATTING CONVENTIONS — NO EXCEPTIONS.** Every query is
+> multi-line: keywords uppercase, each clause and column on its own line, no `SELECT *`. Run
+> `sql-reviewer` on every file that contains SQL and fix formatting before committing.
+
+## Step 6 — Commit and push to the SAME branch (updates the SAME PR)
+
+For each reworked repo, inside its path:
+
+1. **Commit.** Stage only the files the feedback changed. Message format `type: short description`
+   (`feat`/`fix`/`refactor`/`docs`/`test`/`chore`, lowercase, present tense, ≤72 chars) — for a
+   rework, `fix:` or `refactor:` addressing the review is usual; reference what was addressed in the
+   body. **Pre-commit check:** `php -l` passes, no commented-out code, no credentials/local paths.
+2. **Push to the existing branch** — this updates the open PR in place; **do NOT open a new PR**:
+   ```bash
+   git -C "<repo-path>" push origin TRUE-XXXX
+   ```
+   **Never force-push** (per `git-workflow.md`) — a plain push appends commits the reviewer can see as
+   "changes since last review." For the `test` repo: `git push origin master`.
+
+Confirm with `gh pr view <prNumber> --repo <owner/repo> --json url,state` that the PR picked up the
+new commits (its head SHA advanced). Do **not** create a PR.
+
+## Step 6b — Reply on the ticket (and optionally the PR) — do NOT skip
+
+Post a ClickUp comment summarizing what was addressed, so the reviewer knows the rework landed
+(the same dependable channel `work-ticket` uses):
+
+```bash
+node -e 'const k=process.env.CLICKUP_API_KEY,t=process.env.CLICKUP_TEAM_ID;
+const body="Reworked TRUE-XXXX per review feedback:\n• <repo>: <what changed> (pushed to PR <url>)\n• ...";
+fetch("https://api.clickup.com/api/v2/task/TRUE-XXXX/comment?custom_task_ids=true&team_id="+t,
+ {method:"POST",headers:{Authorization:k,"Content-Type":"application/json"},
+  body:JSON.stringify({comment_text:body,notify_all:false})}).then(r=>r.text()).then(console.log)'
+```
+
+Optionally reply to specific inline review threads so each reviewer comment is visibly answered:
+`gh api repos/<owner/repo>/pulls/<prNumber>/comments/<commentId>/replies -f body="Done in <sha> — …"`
+(or a top-level `gh pr comment <prNumber> --repo <owner/repo> --body "Addressed: …"`).
+
+## Step 7 — Report & stop (do NOT touch ClickUp status)
+
+Summarize for the developer:
+- Ticket title and the repos that were reworked.
+- For each repo: the branch (`TRUE-XXXX`), the **PR url**, and the new commit(s) pushed.
+- The feedback items addressed (and any you answered in a reply rather than code), plus any conflict
+  you resolved by deferring to the latest developer comment.
+- Confirm the Step 6b comment was posted.
+- **Remind the developer the next step is theirs:** re-request review / re-approve, then **manually
+  move the ClickUp ticket forward** — this skill never changes ticket status.
+
+Offer `/capture` if a durable, KB-worthy finding emerged while reworking.
+
+---
+
+## Notes
+
+- **Same branch, same PR — always.** The defining rule: rework lands on the existing ticket branch and
+  updates the existing PR. Never `checkout -b`, never open a second PR, never force-push. (This is the
+  mirror image of `work-ticket`, which cuts a fresh branch from `origin/<default>`.)
+- **Feedback is multi-channel.** ClickUp comments + PR reviews + inline review comments + failing CI
+  checks are all feedback. Gather all of them before editing; the most recent developer ClickUp
+  comment breaks ties.
+- **Scope is the feedback, nothing more.** Do not refactor or "improve" code the review did not raise.
+- **Run AFTER `/work-ticket`.** This skill assumes branches/PRs already exist. If no PR matches the
+  ticket, stop and point the developer at `/work-ticket <TICKET>` first.
+- **Autonomy boundary:** autonomous through the push + ticket reply; stops there. Moving the ClickUp
+  ticket is always a manual developer action.

package/skills/work-ticket/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: work-ticket
+description: Work an APPROVED ClickUp ticket plan end-to-end. Invoke as `/work-ticket <TICKET-ID>` (e.g. `/work-ticket TRUE-79868`) AFTER `/plan-ticket` has pushed an approved plan to the ticket's Pseudocode field. Loads the plan from the ticket's Pseudocode field, primes framework context via /kickoff (self-answered), implements the plan phase-by-phase with TOGA reviewers, then per repo creates a bare ticket-ID branch, commits, pushes, opens a PR, and posts the PR links as a comment on the ticket. Stops after PRs are open for your review — never changes ClickUp ticket status. Trigger on "/work-ticket", "work the ticket", "execute the plan for <ticket>", "build and PR <ticket>", "ship <ticket>".
+---
+
+# work-ticket — approved plan → code → branch → commit → PR → ClickUp GitHub tab
+
+The downstream companion to **`/plan-ticket`**. Given a ticket whose plan has already been
+approved and pushed to its **📝 Pseudocode** field, this skill executes that plan: it primes
+context, writes the code, then for **each repo the plan touches** creates a branch named the
+**bare ticket id**, commits, pushes, opens a PR, and posts the PR links as a ticket comment.
+ClickUp's native GitHub integration *may* surface those PRs in the ticket's **GitHub tab** when
+the repo is connected in ClickUp's GitHub settings (see Step 5b — not guaranteed), because the
+ticket id is in the
+branch name (and PR title/body).
+
+It runs autonomously through **PR creation**, then **stops**. The developer reviews the PR(s);
+**moving the ClickUp ticket forward for approval is a manual step the developer does — this
+skill never changes ticket status.**
+
+Helper scripts are reused from the sibling `plan-ticket` skill (`scripts/clickup.js`). `gh` is
+already authenticated. Environment used: `CLICKUP_API_KEY`, `CLICKUP_TEAM_ID` (already in the
+session env).
+
+---
+
+## Step 0 — Resolve the ticket id
+
+The id is the argument after `/work-ticket` (e.g. `TRUE-79868`). If none was given, ask for it.
+
+## Step 1 — Load the approved plan from the ticket's Pseudocode field
+
+The **Pseudocode field is the source of truth** (not the local `test/@dave/approach/<TICKET>.md`,
+which may be stale or absent on this machine):
+
+```bash
+node ".claude/skills/plan-ticket/scripts/clickup.js" get <TICKET>
+```
+
+This prints JSON `{name, status, description, pseudocodeFieldId, url, fields:{...}}`. The
+approved plan is the value in `fields` whose key contains **"Pseudocode"** (case-insensitive)
+— that is the plain-text rendering of the plan pushed by `plan-ticket`.
+
+- **If the Pseudocode field is empty / absent** — there is no approved plan. **Stop** and tell
+  the developer to run `/plan-ticket <TICKET>` and approve it first. Do not invent a plan.
+- Parse the plan's one-line header `**Repos:** … · **Framework:** … · **Client:** …` and its
+  **Phases** (each carries exact file paths + pseudocode). Capture `name` (ticket title) for the
+  commit messages and PR titles, and the in-scope **repos**.
+
+## Step 2 — Prime framework context via kickoff (self-answered from the plan)
+
+Invoke **`/kickoff`** and **answer its interview yourself from the plan header** so it runs
+unattended (same pattern as `plan-ticket` Step 4):
+
+- **Framework / Layer / Repos / Client** — read directly from the plan's `**Repos:** …` header.
+  Map repos to framework (`worker/library/toga/…` → 1.0; `worker2/api2/_underscore/` + React
+  SPAs → 2.0) and layer (PHP API/worker → back-end; React SPA → front-end; both → hybrid).
+
+Pass them as the trailing argument so kickoff goes straight to preflight + priming:
+
+```
+/kickoff <framework> <layer>, repos: <repos>, client: <client> — execute <TICKET> <title>
+```
+
+Carry the `context-primer` briefing (framework rules, gotchas, client variations) into Step 3 —
+it directly informs how each phase is implemented. Only stop to ask the developer if a kickoff
+gate answer is genuinely ambiguous after reading the plan header.
+
+## Step 3 — Execute the plan, phase by phase
+
+Implement the plan against the **real repo paths** (resolve each from the `repo-path-<repo>`
+memory kickoff established; never guess paths). For non-trivial work drive it as implement →
+verify with subagents so the conversation stays the conductor:
+
+1. For each **phase** in the plan, an implementer subagent writes that phase's code at the
+   exact file paths the plan names. When phases span **independent repos**, give each
+   implementer **`isolation: worktree`** so they cannot collide on the same checkout.
+2. **Do NOT spawn the `php-reviewer` agent — the developer reviews PHP themselves on the PR.**
+   Still lint every PHP file with the right binary (`php -l`; 1.0 repos are PHP 7.2 →
+   `C:\xampp7\php\php.exe -l`), and still run `sql-reviewer` on files containing SQL and
+   `security-reviewer` only when genuinely warranted (raw SQL from untrusted input, outbound
+   writes, auth/credential handling). For ordinary PHP correctness/style, lint + the team rules
+   below are the bar — no PHP reviewer subagent.
+3. Honor the team rules throughout: parameterized queries only, no bare catch / `@`, named
+   constants over magic numbers, return-type declarations, no commented-out code, no secrets or
+   absolute local paths in any file that will be committed.
+
+> **ALL SQL MUST FOLLOW THE TEAM SQL FORMATTING CONVENTIONS — NO EXCEPTIONS, INCLUDING ONE-LINE
+> OR THROWAWAY QUERIES.** EVERY query (even a single-clause `DELETE`/`SELECT`, even inside a raw
+> `_Query`) IS WRITTEN MULTI-LINE: KEYWORDS UPPERCASE, EACH CLAUSE ON ITS OWN LINE, THE TABLE AND
+> EACH COLUMN INDENTED ON ITS OWN LINE, NO `SELECT *`. NEVER EMIT A COLLAPSED ONE-LINER LIKE
+> `new _Query('DELETE FROM X WHERE id = ' . $id, ...)`. RUN `sql-reviewer` ON EVERY FILE THAT
+> CONTAINS SQL AND FIX FORMATTING BEFORE COMMITTING.
+
+Do **not** push anything to a remote or open a PR until the code is implemented and clean.
+
+## Step 4 — Per repo: branch (bare ticket id), commit, push
+
+For **each repo in the plan's `Repos:` header** that has changes, run inside that repo's path:
+
+1. **Branch — bare ticket id, based on the CURRENT remote default.** This matches the team
+   convention (existing branches are `TRUE-79142`, `TRUE-77219`) and is exactly what ClickUp's
+   GitHub integration auto-links on. **The branch MUST be cut from freshly-fetched
+   `origin/<default>` — never from whatever local branch the repo happens to be sitting on.** A
+   working checkout is frequently parked on a *different, unmerged ticket's branch* (or a stale
+   local default); branching off that silently bases your PR on someone else's unmerged work and
+   produces a wrong, conflict-prone diff. So always **fetch first, then branch off the remote
+   default**, carrying your uncommitted Step 3 changes onto the new branch:
+   ```bash
+   # Resolve the repo's REAL default branch (e.g. _production for app repos, _main for dbchanges2)
+   DEFAULT=$(gh repo view <owner/repo> --json defaultBranchRef -q .defaultBranchRef.name)
+   git -C "<repo-path>" fetch origin --quiet
+   # Reuse an existing TRUE-XXXX branch if present; otherwise cut a fresh one from origin/<default>.
+   git -C "<repo-path>" rev-parse --verify TRUE-XXXX 2>/dev/null \
+     && git -C "<repo-path>" checkout TRUE-XXXX \
+     || git -C "<repo-path>" checkout -b TRUE-XXXX "origin/$DEFAULT"
+   ```
+   `git checkout -b … origin/$DEFAULT` keeps your uncommitted working-tree edits and re-bases them
+   onto the latest remote default in one step. **First confirm `git status` shows only the files
+   your plan changed** (no stray edits from a prior ticket) before branching. If the checkout is
+   refused because a file you edited also changed on the default, `git stash` → `checkout -b … origin/$DEFAULT`
+   → `git stash pop` and resolve. **Never branch off / commit to `_main`/`_production` directly**,
+   and **never force-push** (per `git-workflow.md`). If already on the `TRUE-XXXX` branch, still
+   `git fetch` and consider rebasing onto `origin/<default>` so the PR diff stays current.
+2. **Commit.** Stage only the files the plan changed. Message format `type: short description`
+   (`feat`/`fix`/`refactor`/`docs`/`test`/`chore`, lowercase, present tense, ≤72 chars). Add a
+   body paragraph for substantial changes. **Pre-commit check:** `php -l` passes on changed PHP,
+   no commented-out code, no credentials or local paths, branch name correct.
+3. **Push** the branch to origin: `git -C "<repo-path>" push -u origin <TICKET>`.
+
+Repeat for every in-scope repo — one branch per repo, all named the same bare ticket id.
+
+## Step 5 — Open a PR per repo (auto-links to the ClickUp GitHub tab)
+
+For each pushed repo, open a PR with `gh` from that repo's path:
+
+```bash
+gh pr create --repo <owner/repo> --base <DEFAULT-BRANCH> --head <TICKET> \
+  --title "<TICKET>" \
+  --body "<body>"
+```
+
+- **Title:** the **BARE TICKET ID ONLY** — e.g. `TRUE-79868`, nothing else. NO `[<repo>]` prefix,
+  NO description after it. The title must equal the branch name exactly (both the bare ticket id);
+  this is what ClickUp's GitHub integration matches on. (This intentionally overrides the
+  `[<repo>] <desc>` PR-title rule in `git-workflow.md` for ticket PRs.)
+- **Base branch:** resolve the repo's REAL default with
+  `gh repo view <owner/repo> --json defaultBranchRef -q .defaultBranchRef.name` — for
+  agilantsolutions app repos this is **`_production`**, NOT `_main` (`_main` is a disjoint orphan
+  and `gh pr create --base _main` fails "no history in common"). Never hardcode `_main`.
+- **Body must include the ticket id** — both the ticket url from Step 1's `url` AND the
+  **internal ClickUp id in `CU-<internalId>` form** (e.g. `CU-868k4mkku`). The internal id is the
+  `id` field from Step 1's `clickup.js get` JSON; ClickUp's GitHub integration matches the
+  internal `CU-<id>` token by default, whereas the bare custom id (`TRUE-79869`) only matches if
+  "allow custom task IDs in integrations" is enabled in the workspace. Include both. Also include,
+  per the PR-checklist rule: which repos/features are affected, how to test, and any migration
+  steps (DB schema, config, queue registration).
+- End the PR body with the standard footer:
+  `🤖 Generated with [Claude Code](https://claude.com/claude-code)`.
+
+### Step 5b — Post the PR links as a ClickUp comment (the RELIABLE link — do NOT skip)
+
+**The native GitHub↔ClickUp tab is NOT reliable in this workspace.** It only populates if each
+repo is connected under ClickUp → Settings → Integrations → GitHub (a one-time workspace OAuth
+setup that cannot be done from `gh`/code). When a repo is not connected, the bare-id branch +
+title + `CU-<id>` body produce **nothing** in the ticket's GitHub tab — this is exactly what
+happened to TRUE-79868/PR #89 and TRUE-79869/PRs #90+#639. Do not promise the GitHub tab will
+populate; treat it as best-effort that depends on a setting outside this skill.
+
+So **always post a comment** on the ticket with the PR links — this is the guaranteed-visible
+link. Use the ClickUp v2 API directly (the `clickup.js` helper only does `get`/`push`):
+
+```bash
+node -e 'const k=process.env.CLICKUP_API_KEY,t=process.env.CLICKUP_TEAM_ID;
+const body="PRs for <TICKET> (<title>):\n• <repo>: <pr-url>\n• ...";
+fetch("https://api.clickup.com/api/v2/task/<TICKET>/comment?custom_task_ids=true&team_id="+t,
+ {method:"POST",headers:{Authorization:k,"Content-Type":"application/json"},
+  body:JSON.stringify({comment_text:body,notify_all:false})}).then(r=>r.text()).then(console.log)'
+```
+
+(A comment does NOT populate the GitHub *tab* — it lands in the ticket's activity/comments —
+but it is the dependable way for the developer to reach the PRs from the ticket.)
+
+## Step 6 — Report & stop (do NOT touch ClickUp status)
+
+Summarize for the developer:
+- Ticket title and the repos that got changes.
+- For each repo: the branch name (`<TICKET>`) and the **PR url** `gh` returned.
+- Confirm the Step 5b comment was posted (the reliable link). State plainly that the GitHub
+  **tab** populates only if the repos are connected in ClickUp's GitHub integration settings —
+  do not claim it will appear automatically.
+- **Remind the developer the next step is theirs:** review/approve the PR(s), then **manually
+  move the ClickUp ticket forward** for approval — this skill intentionally does not change
+  ticket status.
+
+Offer `/capture` if a durable, KB-worthy finding emerged while implementing.
+
+---
+
+## Notes
+
+- **Source of truth is the Pseudocode field** (Step 1), because the local approach file may not
+  exist on the executing machine. If both exist and disagree, the field wins.
+- **Branch = bare ticket id**, one per repo (multi-repo plans get one branch + one PR each, all
+  linked to the same ticket). This intentionally overrides the generic `feature/<desc>` prefix
+  rule in `git-workflow.md` to match the team's actual convention.
+- **Linking is NOT automatic.** The native GitHub tab requires a per-repo connection in ClickUp's
+  GitHub integration settings (workspace OAuth, not doable from `gh`). The branch name + bare-id
+  PR title + `CU-<internalId>` in the body are necessary but **not sufficient** — if the repo
+  isn't connected, the tab stays empty. Step 5b's comment is the reliable link; always post it.
+- **Autonomy boundary:** autonomous through PR creation; stops there. Moving the ClickUp ticket
+  is always a manual developer action.
+- Run AFTER `/plan-ticket` has produced and the developer has approved a plan. This skill does
+  not plan — it executes an already-approved plan.