@gallopsystems/agent-skills 1.20.1 → 1.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gallopsystems/agent-skills",
-  "version": "1.20.1",
+  "version": "1.22.0",
   "description": "Gallop Systems agent skills, symlinked into .claude/skills (Claude Code) and .agents/skills (Codex) on install.",
   "license": "UNLICENSED",
   "repository": {

package/plugins/linear/skills/linear/SKILL.md

@@ -15,7 +15,9 @@ Invoke it as `node <skill>/bin/linear.mjs <command> [args] [--flags]`. Examples
 
 ### Check 1 — Workspace bootstrap config exists
 
-Before running any `linear.mjs` command, verify that the per-user workspace config exists at `~/.config/linctl/workspace.json` (override path with `$LINCTL_WORKSPACE_FILE`). This file holds the team UUID, the Linear member UUIDs that play the Frontend/PM and Backend roles, and the workflow-state and label UUIDs the CLI resolves symbolic names against. Without it, every command that needs the team, members, states, or labels will refuse to run.
+Before running any `linear.mjs` command, verify that the per-user workspace config exists at `~/.config/linctl/workspace.json` (override path with `$LINCTL_WORKSPACE_FILE`). This file holds **every team** in the workspace (each with its own UUID plus its workflow-state and label UUIDs — states differ per team), an optional `defaultTeam`, and the Linear member UUIDs that play the Frontend/PM and Backend roles. Without it, every command that needs the team, members, states, or labels will refuse to run.
+
+> **Multi-team workspaces:** `workspace.json` registers all teams, but `states`/`labels` are per-team (each team's `Todo` is a distinct UUID). Which team a command targets is resolved in this order: the **`--team <key|name|uuid>`** flag → the **`LINCTL_DEFAULT_TEAM`** env var (a per-repo default — set it via direnv/`.envrc` or your shell so every command in a repo targets that team) → the **`defaultTeam`** field in `workspace.json`. If none resolve, `--team` is **required** on team-scoped commands; workspace-wide commands (e.g. `list-initiatives`) work without a team. A legacy config (predating per-team support, i.e. with no `defaultTeam` key and top-level `states`/`labels`) still works — it falls back to the first registered team — but re-run `init` to migrate it to the per-team schema.
 
 ```bash
 [ -f "${LINCTL_WORKSPACE_FILE:-$HOME/.config/linctl/workspace.json}" ] && echo "ok" || echo "missing"
@@ -27,7 +29,7 @@ Before running any `linear.mjs` command, verify that the per-user workspace conf
 node linear.mjs init
 ```
 
-`init` calls Linear's GraphQL API, lists the workspace's members, and prompts the user to designate (1) the Frontend/PM lead and (2) the Backend lead by number. It then writes `~/.config/linctl/workspace.json`. The config is read fresh on every invocation — no re-sourcing needed.
+`init` calls Linear's GraphQL API, lists the workspace's members, and prompts the user to designate (1) the Frontend/PM lead and (2) the Backend lead by number, then (3) an optional default team key (blank = no default, so `--team` is required on each team-scoped call). It registers **all** teams with their per-team states/labels and writes `~/.config/linctl/workspace.json`. The config is read fresh on every invocation — no re-sourcing needed.
 
 ### Check 2 — Linear MCP server installed and authorized
 
@@ -187,6 +189,7 @@ node linear.mjs help        # full command list
 The CLI resolves friendly names against `workspace.json`, so you rarely need raw UUIDs:
 
 ```
+--team       ACME | "Acme Corp"  (team key or name)                          (or a UUID)
 --state      todo | backlog | "in progress" | "in review" | done | canceled   (or a UUID)
 --assignee   frontend | backend                                               (or a UUID)
 --labels     bug,frontend,feature  (comma-separated label names)              (or UUIDs)
@@ -194,13 +197,15 @@ The CLI resolves friendly names against `workspace.json`, so you rarely need raw
 --cycle      current  (the active cycle)                                      (or a UUID)
 ```
 
-Any value that's already a UUID is passed through untouched. Project and milestone IDs are still UUIDs (pass them with `--project` / `--milestone`).
+`--team` selects which team a team-scoped command runs against, and `--state`/`--labels` then resolve against **that team's** states and labels. When `--team` is omitted it falls back to `$LINCTL_DEFAULT_TEAM` (a per-repo default) and then to `workspace.json`'s `defaultTeam`; if none are set you'll get an error listing the registered team keys. Workspace-wide commands (initiatives) don't need a team. Any value that's already a UUID is passed through untouched. Project and milestone IDs are still UUIDs (pass them with `--project` / `--milestone`).
 
 ### Creating Issues
 
 > **Important:** When assigning an issue to a cycle, always set `--state todo`. Issues default to Backlog, which doesn't work with cycles — they must be in Todo status.
 >
 > **Required placement rule:** Never create an issue without both `--project` and `--milestone`. If the right project does not exist, create it first. If the project exists but the right milestone does not, create the milestone first. Do not leave issues unscoped or unmilestoned.
+>
+> **Confirm decisions with the requester — don't punt them into the issue.** When the person asking you to create the issue is right there in the conversation, ask the open decisions (scope, mechanism, data source, ownership, who/where it should land) *before* writing the issue — e.g. via a structured question prompt — and bake the confirmed answers into the body. Do **not** write an "Open questions" section full of decisions you could have just asked, and do **not** use that manufactured uncertainty as a rationale to leave the issue in Backlog or unassigned. Only genuinely external unknowns (something that needs a meeting, a client, or a spike to resolve) belong as open questions; everything the requester can answer on the spot should already be a confirmed decision with the issue placed and assigned accordingly.
 
 ```bash
 # --state todo is required when using --cycle

package/plugins/linear/skills/linear/bin/linear.mjs

@@ -73,39 +73,111 @@ function readMaybeFile(v, key) {
 // --- Workspace config ------------------------------------------------------
 
 /**
+ * @typedef {{ id: string, key: string, name: string, states?: Record<string, string>, labels?: Record<string, string> }} TeamEntry
  * @typedef {{
  *   teamId: string,
+ *   teams: TeamEntry[],
  *   members: { frontend?: string, backend?: string, frontendName?: string, backendName?: string },
  *   states: Record<string, string>,
  *   labels: Record<string, string>,
  * }} Config
  */
 
-/** @returns {Config | null} */
-function loadConfig() {
+/**
+ * Resolve which team a command runs against. Precedence: the `--team` flag
+ * (key, name, or UUID), then `$LINCTL_DEFAULT_TEAM` (a per-repo default, set via
+ * direnv or the shell), then the config's `defaultTeam`. A config that predates
+ * per-team support (no `defaultTeam` key at all) and no env override falls back
+ * to the first team for compatibility. Returns null only when there is genuinely
+ * no default and no `--team` — the caller defers the error until `cfg.teamId` is
+ * actually read.
+ * @param {TeamEntry[]} teams
+ * @param {string|undefined} ref
+ * @param {string|null|undefined} fileDefault
+ * @returns {TeamEntry | null}
+ */
+function selectTeam(teams, ref, fileDefault) {
+  /** @param {string} val */
+  const find = (val) => {
+    const v = String(val).toLowerCase();
+    return teams.find(
+      (t) => t.id === val || t.key?.toLowerCase() === v || t.name?.toLowerCase() === v,
+    );
+  };
+  if (ref) {
+    const t = find(ref);
+    if (!t) {
+      fail(`unknown team "${ref}". Registered: ${teams.map((x) => x.key).join(", ") || "(none)"}`);
+    }
+    return t ?? null;
+  }
+  const envDefault = process.env.LINCTL_DEFAULT_TEAM?.trim();
+  if (envDefault) {
+    const t = find(envDefault);
+    if (!t) {
+      fail(`LINCTL_DEFAULT_TEAM="${envDefault}" is not among the registered teams.`);
+    }
+    return t ?? null;
+  }
+  if (fileDefault) {
+    const t = find(fileDefault);
+    if (!t) fail(`configured defaultTeam "${fileDefault}" is not among the registered teams.`);
+    return t ?? null;
+  }
+  if (fileDefault === undefined) return teams[0] ?? null; // legacy config: no explicit default
+  return null; // defaultTeam === null and no env → no default; --team is required
+}
+
+/** @param {TeamEntry[]} teams */
+function teamSelectionError(teams) {
+  const keys = teams.map((t) => t.key).join(", ") || "(none registered)";
+  return (
+    `no team selected for this command.\n` +
+    `  Pass --team <key> (one of: ${keys}),\n` +
+    `  set LINCTL_DEFAULT_TEAM in your shell/repo (per-repo default),\n` +
+    `  or set "defaultTeam" in ${WORKSPACE_FILE}.`
+  );
+}
+
+/** @param {string} [teamRef] @returns {Config | null} */
+function loadConfig(teamRef) {
   if (!existsSync(WORKSPACE_FILE)) return null;
   const raw = JSON.parse(readFileSync(WORKSPACE_FILE, "utf8"));
+  /** @type {TeamEntry[]} */
   const teams = raw.teams ?? [];
   const roles = raw.roles ?? {};
-  return {
-    teamId: teams[0]?.id ?? "",
+  const sel = selectTeam(teams, teamRef, "defaultTeam" in raw ? raw.defaultTeam : undefined);
+  /** @type {Config} */
+  const cfg = {
+    // @ts-ignore — teamId is installed as a lazy getter below.
+    teams,
     members: {
       frontend: roles.frontend_lead?.id,
       backend: roles.backend_lead?.id,
       frontendName: roles.frontend_lead?.name,
       backendName: roles.backend_lead?.name,
     },
-    states: raw.states ?? {},
-    labels: raw.labels ?? {},
+    states: sel?.states ?? raw.states ?? {},
+    labels: sel?.labels ?? raw.labels ?? {},
   };
+  // Lazy: workspace-wide commands (e.g. list-initiatives) never read teamId, so
+  // they work without --team. Team-scoped commands trigger the error on access.
+  Object.defineProperty(cfg, "teamId", {
+    enumerable: true,
+    get() {
+      if (sel?.id) return sel.id;
+      return fail(teamSelectionError(teams));
+    },
+  });
+  return cfg;
 }
 
-/** @returns {Config} */
-function requireConfig() {
-  const cfg = loadConfig();
-  if (!cfg || !cfg.teamId) {
+/** @param {string} [teamRef] @returns {Config} */
+function requireConfig(teamRef) {
+  const cfg = loadConfig(teamRef);
+  if (!cfg) {
     fail(
-      `workspace config not found or incomplete at ${WORKSPACE_FILE}\n` +
+      `workspace config not found at ${WORKSPACE_FILE}\n` +
         `  Run \`node linear.mjs init\` to generate it.`,
     );
   }
@@ -970,12 +1042,46 @@ async function cmdApi(args, v, cfg) {
 
 // --- init (interactive workspace bootstrap) --------------------------------
 
+const WANTED_STATES = ["Backlog", "Todo", "In Progress", "In Review", "Done", "Canceled"];
+const WANTED_LABELS = ["discovery", "tech-debt", "backend", "frontend", "db", "bug", "feature", "improvement"];
+
+/** Filter a team's raw state nodes down to the canonical names we track.
+ * @param {Array<{id:string,name:string}>} nodes */
+function pickStates(nodes) {
+  /** @type {Record<string, string>} */
+  const states = {};
+  const lookup = new Map(nodes.map((s) => [s.name.toLowerCase(), s]));
+  for (const name of WANTED_STATES) {
+    const s = lookup.get(name.toLowerCase());
+    if (s) states[name] = s.id;
+  }
+  return states;
+}
+
+/** Filter a team's raw label nodes down to the canonical names we track.
+ * @param {Array<{id:string,name:string}>} nodes */
+function pickLabels(nodes) {
+  const norm = (s) => s.toLowerCase().replace(/-/g, " ").trim();
+  /** @type {Record<string, string>} */
+  const labels = {};
+  const lookup = new Map(nodes.map((l) => [norm(l.name), l]));
+  for (const name of WANTED_LABELS) {
+    const l = lookup.get(norm(name));
+    if (l) labels[name] = l.id;
+  }
+  return labels;
+}
+
 async function cmdInit() {
   if (!API_KEY) fail("LINEAR_API_KEY is not set. Set it first, then re-run `init`.");
 
   console.error("Fetching workspace data from Linear...");
+  // Pull each team's own states + labels — they differ per team (e.g. each
+  // team's "Todo" is a distinct workflow-state UUID).
   const bootstrap = await gql(
-    `{ teams(first: 50) { nodes { id key name parent { id } } }
+    `{ teams(first: 50) { nodes { id key name parent { id }
+         states { nodes { id name type } }
+         labels { nodes { id name } } } }
        users(first: 250) { nodes { id name email displayName } } }`,
   );
 
@@ -987,17 +1093,8 @@ async function cmdInit() {
     process.exit(1);
   }
 
-  // Prefer a parent team (no parent of its own) so states/labels come from the
-  // umbrella team rather than a sub-team.
-  const parents = teams.filter((t) => !t.parent);
-  const chosenTeam = parents[0] ?? teams[0];
-
-  const teamExtra = await gql(
-    `query TeamExtra($id: String!) {
-       team(id: $id) { states { nodes { id name type } } labels { nodes { id name } } }
-     }`,
-    { id: chosenTeam.id },
-  );
+  // Parent (umbrella) teams first so the list reads top-down.
+  const teamsSorted = [...teams].sort((a, b) => (a.parent ? 1 : 0) - (b.parent ? 1 : 0));
 
   // Filter out Linear's integration/bot users.
   const users = (bootstrap?.data?.users?.nodes ?? []).filter(
@@ -1014,6 +1111,10 @@ async function cmdInit() {
   const rl = createInterface({ input, output });
   const frontendIdx = await rl.question("Which member is the Frontend/PM lead? Enter number: ");
   const backendIdx = await rl.question("Which member is the Backend lead? Enter number: ");
+  console.error("\nTeams: " + teamsSorted.map((t) => t.key).join(", "));
+  const defaultTeamAns = (
+    await rl.question("Default team key (blank = none; --team required each call): ")
+  ).trim();
   rl.close();
 
   /** @param {string} idxStr */
@@ -1029,37 +1130,27 @@ async function cmdInit() {
   const frontend = pick(frontendIdx);
   const backend = pick(backendIdx);
 
-  const WANTED_STATES = ["Backlog", "Todo", "In Progress", "In Review", "Done", "Canceled"];
-  const WANTED_LABELS = ["discovery", "tech-debt", "backend", "frontend", "db", "bug", "feature", "improvement"];
-
-  const stateNodes = teamExtra?.data?.team?.states?.nodes ?? [];
-  const labelNodes = teamExtra?.data?.team?.labels?.nodes ?? [];
-
-  /** @type {Record<string, string>} */
-  const states = {};
-  const stateLookup = new Map(stateNodes.map((s) => [s.name.toLowerCase(), s]));
-  for (const name of WANTED_STATES) {
-    const s = stateLookup.get(name.toLowerCase());
-    if (s) states[name] = s.id;
-  }
-
-  const norm = (s) => s.toLowerCase().replace(/-/g, " ").trim();
-  /** @type {Record<string, string>} */
-  const labels = {};
-  const labelLookup = new Map(labelNodes.map((l) => [norm(l.name), l]));
-  for (const name of WANTED_LABELS) {
-    const l = labelLookup.get(norm(name));
-    if (l) labels[name] = l.id;
+  let defaultTeam = null;
+  if (defaultTeamAns) {
+    const match = teamsSorted.find(
+      (t) =>
+        t.key?.toLowerCase() === defaultTeamAns.toLowerCase() ||
+        t.name?.toLowerCase() === defaultTeamAns.toLowerCase(),
+    );
+    if (!match) fail(`"${defaultTeamAns}" is not one of the workspace teams.`);
+    defaultTeam = match.key;
   }
 
-  // Parent teams first so teams[0] is the umbrella team.
-  const teamsSorted = [...teams].sort((a, b) => (a.parent ? 1 : 0) - (b.parent ? 1 : 0));
-
   const cfg = {
-    teams: teamsSorted.map((t) => ({ id: t.id, key: t.key, name: t.name })),
+    teams: teamsSorted.map((t) => ({
+      id: t.id,
+      key: t.key,
+      name: t.name,
+      states: pickStates(t.states?.nodes ?? []),
+      labels: pickLabels(t.labels?.nodes ?? []),
+    })),
+    defaultTeam,
     roles: { frontend_lead: frontend, backend_lead: backend },
-    states,
-    labels,
   };
 
   mkdirSync(dirname(WORKSPACE_FILE), { recursive: true });
@@ -1119,6 +1210,13 @@ const USAGE = `Linear CLI — node linear.mjs <command> [args] [--flags]
 Setup:
   init                                   Interactive: fetch workspace, write ~/.config/linctl/workspace.json
 
+Team selection:
+  --team <key|name|uuid>                 Run a team-scoped command against this team
+                                         (e.g. --team ACME). Precedence: --team >
+                                         $LINCTL_DEFAULT_TEAM (per-repo default) >
+                                         workspace.json "defaultTeam". Workspace-wide
+                                         commands (initiatives) don't need a team.
+
 Issues:
   create-issue --title T [--description D|--description-file F] [--priority P]
                [--state S] [--assignee frontend|backend] [--labels a,b]
@@ -1187,6 +1285,7 @@ async function main() {
       priority: { type: "string" },
       state: { type: "string" },
       assignee: { type: "string" },
+      team: { type: "string" },
       labels: { type: "string" },
       estimate: { type: "string" },
       project: { type: "string" },
@@ -1221,7 +1320,7 @@ async function main() {
   const handler = COMMANDS[command];
   if (!handler) fail(`unknown command "${command}". Run \`node linear.mjs help\`.`);
 
-  const cfg = NO_CONFIG.has(command) ? /** @type {Config} */ ({}) : requireConfig();
+  const cfg = NO_CONFIG.has(command) ? /** @type {Config} */ ({}) : requireConfig(values.team);
   await handler(args, values, cfg);
 }