@blogic-cz/agent-tools 0.2.6 → 0.3.0

package/README.md

@@ -15,27 +15,104 @@ These tools wrap each CLI with:
 
 ## Installation
 
-> **Recommended:** Copy the repo URL and tell your AI agent to install it. The agent will set up everything — dependencies, config file, credential guard — in the right places for your project.
+> **Recommended:** Copy the repo URL and tell your AI agent to install it. The agent will set up everything — dev dependency, config file, credential guard, skill — in the right places for your project.
 >
 > ```
-> Install @blogic-cz/agent-tools from https://github.com/blogic-cz/agent-tools and set it up for this project.
+> Install @blogic-cz/agent-tools from https://github.com/blogic-cz/agent-tools as a dev dependency, install the agent-tools skill, set up the credential guard, and configure the tools I need for this project.
 > ```
 
 ### Manual installation
 
 ```bash
-bun add @blogic-cz/agent-tools
+bun add -d @blogic-cz/agent-tools
 ```
 
 **Requirements:** [Bun](https://bun.sh/) >=1.0.0
 
 ### For agents reading this
 
-Clone the repo and look at the source. The tools are in `src/`, each tool is self-contained:
+Follow these steps to set up agent-tools in the consumer project.
+
+**Step 1 — Install**
+
+- **JavaScript/TypeScript project** (has `package.json`): Install as a **dev dependency**:
+  ```bash
+  bun add -d @blogic-cz/agent-tools
+  ```
+- **Non-JavaScript project** (no `package.json`): Skip installation — run tools directly with `bunx`:
+  ```bash
+  bunx agent-tools-gh pr status
+  bunx agent-tools-k8s pods --env test
+  ```
+
+**Step 2 — Configure**
+
+Ask the user which tools they need (gh, db, k8s, az, logs, session). Create `agent-tools.json5` in the project root with **only the selected tools configured**. See [`examples/agent-tools.json5`](./examples/agent-tools.json5) for the full config reference with all options documented.
+
+Minimal starting config:
+
+```json5
+{
+  $schema: "https://raw.githubusercontent.com/blogic-cz/agent-tools/main/schemas/agent-tools.schema.json",
+}
+```
+
+**Step 3 — Credential Guard**
+
+Set up the credential guard for the agent's platform:
+
+- **Claude Code**: Add the `PreToolUse` hook to `.claude/settings.json` — see [Setup for Claude Code](#setup-for-claude-code)
+- **OpenCode**: Create the plugin at `.opencode/plugins/credential-guard.ts` — see [Setup for OpenCode](#setup-for-opencode)
+
+**Step 4 — Test & Demo**
+
+For each tool the user selected in Step 2:
+
+1. Run `bunx agent-tools-<tool> --help` to verify it works
+2. Summarize the key commands available
+3. Show the user what data they have access to based on their `agent-tools.json5` — e.g. which environments, clusters, namespaces, databases, or profiles are configured and reachable
+
+**Step 5 — Skill & Agent Docs**
+
+Tell the user to run the following command themselves — it's interactive and lets them choose which agents to install the skill for:
 
 ```bash
-git clone https://github.com/blogic-cz/agent-tools.git
-ls src/  # gh-tool/ db-tool/ k8s-tool/ az-tool/ logs-tool/ session-tool/ credential-guard/
+npx skills add blogic-cz/agent-tools
+```
+
+**Do not run this command for the user** — it requires interactive selection.
+
+Then update the project's `AGENTS.md` and/or `CLAUDE.md`:
+
+1. Add an `agent-tools` row to the skills table (if one exists):
+   ```markdown
+   | Agent wrapper tools (`db-tool`, `k8s-tool`, `logs-tool`, `az-tool`, `gh` patterns) | `agent-tools` |
+   ```
+2. Add or update the **Tooling** section:
+
+   ```markdown
+   ## Tooling
+
+   For tool wrappers and operational patterns, load `agent-tools`.
+   ```
+
+**Step 6 — Custom Tool Scaffold**
+
+Create an `agent-tools/` directory in the project root with an example tool so the user has a working template for building project-specific tools. Copy the scaffold from [`examples/custom-tool/`](./examples/custom-tool/):
+
+```
+agent-tools/
+  package.json          # private package depending on @blogic-cz/agent-tools
+  tsconfig.json         # extends root tsconfig
+  noop.ts               # placeholder export for typecheck
+  example-tool/
+    index.ts             # ping-pong example using Effect CLI
+```
+
+After creating the files, run `bun install` in the `agent-tools/` directory (or from the workspace root if it's a monorepo). Then verify:
+
+```bash
+bun run agent-tools/example-tool/index.ts ping
 ```
 
 ## Quick Start
@@ -75,6 +152,22 @@ bunx agent-tools-gh pr review-triage   # interactive summary of PR feedback
 bunx agent-tools-k8s pods --env test   # list pods (structured command)
 ```
 
+Optionally, add script aliases to your `package.json` for shorter invocation:
+
+```json
+{
+  "scripts": {
+    "gh-tool": "agent-tools-gh",
+    "k8s-tool": "agent-tools-k8s",
+    "db-tool": "agent-tools-db",
+    "logs-tool": "agent-tools-logs",
+    "session-tool": "agent-tools-session"
+  }
+}
+```
+
+Then run via `bun run k8s-tool -- pods --env test` instead of `bunx agent-tools-k8s pods --env test`.
+
 4. Hook up the credential guard in your agent config (Claude Code, OpenCode, etc.):
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, and sessions",
   "keywords": [
     "agent",

package/src/gh-tool/index.ts

@@ -5,12 +5,13 @@ import { Effect, Layer } from "effect";
 
 import { renderCauseToStderr, VERSION } from "#shared";
 import {
-  issueListCommand,
-  issueViewCommand,
   issueCloseCommand,
-  issueReopenCommand,
   issueCommentCommand,
   issueEditCommand,
+  issueListCommand,
+  issueReopenCommand,
+  issueTriageSummaryCommand,
+  issueViewCommand,
 } from "./issue";
 import {
   prViewCommand,
@@ -72,7 +73,9 @@ const prCommand = Command.make("pr", {}).pipe(
 );
 
 const issueCommand = Command.make("issue", {}).pipe(
-  Command.withDescription("Issue operations (list, view, close, reopen, comment, edit)"),
+  Command.withDescription(
+    "Issue operations (list, view, close, reopen, comment, edit, triage-summary)",
+  ),
   Command.withSubcommands([
     issueListCommand,
     issueViewCommand,
@@ -80,6 +83,7 @@ const issueCommand = Command.make("issue", {}).pipe(
     issueReopenCommand,
     issueCommentCommand,
     issueEditCommand,
+    issueTriageSummaryCommand,
   ]),
 );
 

package/src/gh-tool/issue/commands.ts

@@ -0,0 +1,145 @@
+import { Command, Flag } from "effect/unstable/cli";
+import { Effect, Option } from "effect";
+
+import { formatOption, logFormatted } from "#shared";
+
+import { closeIssue, commentOnIssue, editIssue, listIssues, reopenIssue, viewIssue } from "./core";
+
+export const issueListCommand = Command.make(
+  "list",
+  {
+    format: formatOption,
+    labels: Flag.string("labels").pipe(
+      Flag.withDescription("Filter by label (comma-separated)"),
+      Flag.optional,
+    ),
+    limit: Flag.integer("limit").pipe(
+      Flag.withDescription("Maximum number of issues to return"),
+      Flag.withDefault(30),
+    ),
+    state: Flag.choice("state", ["open", "closed", "all"]).pipe(
+      Flag.withDescription("Filter by state: open, closed, all"),
+      Flag.withDefault("open"),
+    ),
+  },
+  ({ format, labels, limit, state }) =>
+    Effect.gen(function* () {
+      const issues = yield* listIssues({
+        labels: Option.getOrNull(labels),
+        limit,
+        state,
+      });
+      yield* logFormatted(issues, format);
+    }),
+).pipe(Command.withDescription("List issues (default: open, use --state to filter)"));
+
+export const issueViewCommand = Command.make(
+  "view",
+  {
+    format: formatOption,
+    issue: Flag.integer("issue").pipe(Flag.withDescription("Issue number")),
+  },
+  ({ format, issue }) =>
+    Effect.gen(function* () {
+      const info = yield* viewIssue(issue);
+      yield* logFormatted(info, format);
+    }),
+).pipe(Command.withDescription("View issue details"));
+
+export const issueCloseCommand = Command.make(
+  "close",
+  {
+    comment: Flag.string("comment").pipe(
+      Flag.withDescription("Comment to add when closing"),
+      Flag.optional,
+    ),
+    format: formatOption,
+    issue: Flag.integer("issue").pipe(Flag.withDescription("Issue number to close")),
+    reason: Flag.choice("reason", ["completed", "not planned"]).pipe(
+      Flag.withDescription("Close reason: completed, not planned"),
+      Flag.withDefault("completed"),
+    ),
+  },
+  ({ comment, format, issue, reason }) =>
+    Effect.gen(function* () {
+      const result = yield* closeIssue({
+        comment: Option.getOrNull(comment),
+        issue,
+        reason,
+      });
+      yield* logFormatted(result, format);
+    }),
+).pipe(Command.withDescription("Close an issue with optional comment and reason"));
+
+export const issueReopenCommand = Command.make(
+  "reopen",
+  {
+    comment: Flag.string("comment").pipe(
+      Flag.withDescription("Comment to add when reopening"),
+      Flag.optional,
+    ),
+    format: formatOption,
+    issue: Flag.integer("issue").pipe(Flag.withDescription("Issue number to reopen")),
+  },
+  ({ comment, format, issue }) =>
+    Effect.gen(function* () {
+      const result = yield* reopenIssue({
+        comment: Option.getOrNull(comment),
+        issue,
+      });
+      yield* logFormatted(result, format);
+    }),
+).pipe(Command.withDescription("Reopen a closed issue"));
+
+export const issueCommentCommand = Command.make(
+  "comment",
+  {
+    body: Flag.string("body").pipe(Flag.withDescription("Comment body text")),
+    format: formatOption,
+    issue: Flag.integer("issue").pipe(Flag.withDescription("Issue number to comment on")),
+  },
+  ({ body, format, issue }) =>
+    Effect.gen(function* () {
+      const result = yield* commentOnIssue({ body, issue });
+      yield* logFormatted(result, format);
+    }),
+).pipe(Command.withDescription("Post a comment on an issue"));
+
+export const issueEditCommand = Command.make(
+  "edit",
+  {
+    addAssignee: Flag.string("add-assignee").pipe(
+      Flag.withDescription("Add assignee login (comma-separated for multiple)"),
+      Flag.optional,
+    ),
+    addLabels: Flag.string("add-labels").pipe(
+      Flag.withDescription("Add labels (comma-separated)"),
+      Flag.optional,
+    ),
+    body: Flag.string("body").pipe(Flag.withDescription("New issue body"), Flag.optional),
+    format: formatOption,
+    issue: Flag.integer("issue").pipe(Flag.withDescription("Issue number to edit")),
+    removeAssignee: Flag.string("remove-assignee").pipe(
+      Flag.withDescription("Remove assignee login (comma-separated for multiple)"),
+      Flag.optional,
+    ),
+    removeLabels: Flag.string("remove-labels").pipe(
+      Flag.withDescription("Remove labels (comma-separated)"),
+      Flag.optional,
+    ),
+    title: Flag.string("title").pipe(Flag.withDescription("New issue title"), Flag.optional),
+  },
+  ({ addAssignee, addLabels, body, format, issue, removeAssignee, removeLabels, title }) =>
+    Effect.gen(function* () {
+      const result = yield* editIssue({
+        addAssignee: Option.getOrNull(addAssignee),
+        addLabels: Option.getOrNull(addLabels),
+        body: Option.getOrNull(body),
+        issue,
+        removeAssignee: Option.getOrNull(removeAssignee),
+        removeLabels: Option.getOrNull(removeLabels),
+        title: Option.getOrNull(title),
+      });
+      yield* logFormatted(result, format);
+    }),
+).pipe(Command.withDescription("Edit issue title, body, labels, or assignees"));

package/src/gh-tool/issue/core.ts

@@ -0,0 +1,208 @@
+import { Effect } from "effect";
+
+import { GitHubCommandError } from "#gh/errors";
+import { GitHubService } from "#gh/service";
+
+export type IssueInfo = {
+  number: number;
+  title: string;
+  state: string;
+  url: string;
+  labels: Array<{ name: string }>;
+  assignees: Array<{ login: string }>;
+  author: { login: string };
+  createdAt: string;
+  closedAt: string | null;
+};
+
+export type IssueListItem = {
+  number: number;
+  title: string;
+  state: string;
+  url: string;
+  labels: Array<{ name: string }>;
+  createdAt: string;
+};
+
+export type RawIssueComment = {
+  id: number;
+  user: { login: string };
+  body: string;
+  created_at: string;
+  html_url: string;
+};
+
+export const listIssues = Effect.fn("issue.listIssues")(function* (opts: {
+  state: string;
+  labels: string | null;
+  limit: number;
+}) {
+  const gh = yield* GitHubService;
+
+  const args = [
+    "issue",
+    "list",
+    "--state",
+    opts.state,
+    "--limit",
+    String(opts.limit),
+    "--json",
+    "number,title,state,url,labels,createdAt",
+  ];
+
+  if (opts.labels !== null) {
+    args.push("--label", opts.labels);
+  }
+
+  return yield* gh.runGhJson<IssueListItem[]>(args);
+});
+
+export const viewIssue = Effect.fn("issue.viewIssue")(function* (issueNumber: number) {
+  const gh = yield* GitHubService;
+
+  return yield* gh.runGhJson<IssueInfo>([
+    "issue",
+    "view",
+    String(issueNumber),
+    "--json",
+    "number,title,state,url,labels,assignees,author,createdAt,closedAt",
+  ]);
+});
+
+export const closeIssue = Effect.fn("issue.closeIssue")(function* (opts: {
+  issue: number;
+  comment: string | null;
+  reason: string;
+}) {
+  const gh = yield* GitHubService;
+
+  const args = ["issue", "close", String(opts.issue), "--reason", opts.reason];
+
+  if (opts.comment !== null) {
+    args.push("--comment", opts.comment);
+  }
+
+  yield* gh.runGh(args);
+
+  return yield* gh.runGhJson<IssueInfo>([
+    "issue",
+    "view",
+    String(opts.issue),
+    "--json",
+    "number,title,state,url,labels,assignees,author,createdAt,closedAt",
+  ]);
+});
+
+export const reopenIssue = Effect.fn("issue.reopenIssue")(function* (opts: {
+  issue: number;
+  comment: string | null;
+}) {
+  const gh = yield* GitHubService;
+
+  const args = ["issue", "reopen", String(opts.issue)];
+
+  if (opts.comment !== null) {
+    args.push("--comment", opts.comment);
+  }
+
+  yield* gh.runGh(args);
+
+  return yield* gh.runGhJson<IssueInfo>([
+    "issue",
+    "view",
+    String(opts.issue),
+    "--json",
+    "number,title,state,url,labels,assignees,author,createdAt,closedAt",
+  ]);
+});
+
+export const commentOnIssue = Effect.fn("issue.commentOnIssue")(function* (opts: {
+  issue: number;
+  body: string;
+}) {
+  const gh = yield* GitHubService;
+  const repoInfo = yield* gh.getRepoInfo();
+
+  const trimmedBody = opts.body.trim();
+  if (trimmedBody.length === 0) {
+    return yield* Effect.fail(
+      new GitHubCommandError({
+        command: "gh-tool issue comment",
+        exitCode: 0,
+        stderr: "Comment body cannot be empty",
+        message: "Comment body cannot be empty",
+      }),
+    );
+  }
+
+  const result = yield* gh.runGh([
+    "api",
+    "-X",
+    "POST",
+    `repos/${repoInfo.owner}/${repoInfo.name}/issues/${opts.issue}/comments`,
+    "-f",
+    `body=${trimmedBody}`,
+  ]);
+
+  const rawComment = yield* Effect.try({
+    try: () => JSON.parse(result.stdout) as RawIssueComment,
+    catch: (error) =>
+      new GitHubCommandError({
+        command: "gh-tool issue comment",
+        exitCode: 0,
+        stderr: `Failed to parse response: ${error instanceof Error ? error.message : String(error)}`,
+        message: `Failed to parse response: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+  }).pipe(Effect.mapError((error) => error as GitHubCommandError));
+
+  return {
+    id: rawComment.id,
+    author: rawComment.user.login,
+    body: rawComment.body,
+    createdAt: rawComment.created_at,
+    url: rawComment.html_url,
+  };
+});
+
+export const editIssue = Effect.fn("issue.editIssue")(function* (opts: {
+  issue: number;
+  title: string | null;
+  body: string | null;
+  addLabels: string | null;
+  removeLabels: string | null;
+  addAssignee: string | null;
+  removeAssignee: string | null;
+}) {
+  const gh = yield* GitHubService;
+
+  const args = ["issue", "edit", String(opts.issue)];
+
+  if (opts.title !== null) {
+    args.push("--title", opts.title);
+  }
+  if (opts.body !== null) {
+    args.push("--body", opts.body);
+  }
+  if (opts.addLabels !== null) {
+    args.push("--add-label", opts.addLabels);
+  }
+  if (opts.removeLabels !== null) {
+    args.push("--remove-label", opts.removeLabels);
+  }
+  if (opts.addAssignee !== null) {
+    args.push("--add-assignee", opts.addAssignee);
+  }
+  if (opts.removeAssignee !== null) {
+    args.push("--remove-assignee", opts.removeAssignee);
+  }
+
+  yield* gh.runGh(args);
+
+  return yield* gh.runGhJson<IssueInfo>([
+    "issue",
+    "view",
+    String(opts.issue),
+    "--json",
+    "number,title,state,url,labels,assignees,author,createdAt,closedAt",
+  ]);
+});

package/src/gh-tool/issue/index.ts

@@ -0,0 +1,9 @@
+export {
+  issueCloseCommand,
+  issueCommentCommand,
+  issueEditCommand,
+  issueListCommand,
+  issueReopenCommand,
+  issueViewCommand,
+} from "./commands";
+export { issueTriageSummaryCommand } from "./triage";

package/src/gh-tool/issue/triage.ts

@@ -0,0 +1,320 @@
+import { Command, Flag } from "effect/unstable/cli";
+import { Effect } from "effect";
+
+import { formatOption, logFormatted } from "#shared";
+import { GitHubService } from "#gh/service";
+
+// ---------------------------------------------------------------------------
+// Raw types (gh CLI JSON output)
+// ---------------------------------------------------------------------------
+
+type RawTriageIssue = {
+  number: number;
+  title: string;
+  state: string;
+  url: string;
+  labels: Array<{ name: string }>;
+  assignees: Array<{ login: string }>;
+  author: { login: string };
+  body: string;
+  comments: Array<unknown>;
+  createdAt: string;
+};
+
+type RawTriagePR = {
+  number: number;
+  title: string;
+  state: string;
+  url: string;
+  labels: Array<{ name: string }>;
+  author: { login: string };
+  body: string;
+  headRefName: string;
+  baseRefName: string;
+  isDraft: boolean;
+  mergeable: string;
+  reviewDecision: string;
+  statusCheckRollup: Array<{
+    name: string;
+    status: string;
+    conclusion: string | null;
+    context: string;
+  }>;
+};
+
+// ---------------------------------------------------------------------------
+// Classification types
+// ---------------------------------------------------------------------------
+
+type IssueClassification = "QUESTION" | "BUG" | "FEATURE" | "OTHER";
+type PRClassification = "BUGFIX" | "OTHER";
+type Confidence = "HIGH" | "MEDIUM" | "LOW";
+
+// ---------------------------------------------------------------------------
+// Output types
+// ---------------------------------------------------------------------------
+
+type TriageIssue = {
+  number: number;
+  title: string;
+  author: string;
+  labels: string[];
+  classification: IssueClassification;
+  confidence: Confidence;
+  body: string;
+  commentsCount: number;
+  createdAt: string;
+  url: string;
+};
+
+type TriagePR = {
+  number: number;
+  title: string;
+  author: string;
+  labels: string[];
+  classification: PRClassification;
+  confidence: Confidence;
+  headRefName: string;
+  baseRefName: string;
+  isDraft: boolean;
+  mergeable: string;
+  reviewDecision: string;
+  ciStatus: string;
+  body: string;
+  url: string;
+};
+
+type TriageSummary = {
+  repo: string;
+  fetchedAt: string;
+  issues: TriageIssue[];
+  prs: TriagePR[];
+  summary: {
+    totalIssues: number;
+    totalPRs: number;
+    issuesByType: Record<string, number>;
+    prsByType: Record<string, number>;
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Classification logic (pure functions)
+// ---------------------------------------------------------------------------
+
+function classifyIssue(
+  labels: string[],
+  title: string,
+): { classification: IssueClassification; confidence: Confidence } {
+  const lowerLabels = new Set(labels.map((l) => l.toLowerCase()));
+  const lowerTitle = title.toLowerCase();
+
+  // Labels first — HIGH confidence
+  if (lowerLabels.has("bug")) {
+    return { classification: "BUG", confidence: "HIGH" };
+  }
+  if (lowerLabels.has("question") || lowerLabels.has("help wanted")) {
+    return { classification: "QUESTION", confidence: "HIGH" };
+  }
+  if (
+    lowerLabels.has("enhancement") ||
+    lowerLabels.has("feature") ||
+    lowerLabels.has("feature request")
+  ) {
+    return { classification: "FEATURE", confidence: "HIGH" };
+  }
+
+  // Title patterns — MEDIUM confidence
+  if (/\[bug\]/i.test(title) || /^bug:/i.test(title) || /^fix:/i.test(title)) {
+    return { classification: "BUG", confidence: "MEDIUM" };
+  }
+  if (
+    lowerTitle.includes("?") ||
+    /\[question\]/i.test(title) ||
+    /how to/i.test(title) ||
+    /is it possible/i.test(title)
+  ) {
+    return { classification: "QUESTION", confidence: "MEDIUM" };
+  }
+  if (
+    /\[feature\]/i.test(title) ||
+    /\[enhancement\]/i.test(title) ||
+    /\[rfe\]/i.test(title) ||
+    /^feat:/i.test(title)
+  ) {
+    return { classification: "FEATURE", confidence: "MEDIUM" };
+  }
+
+  // Default — LOW confidence
+  return { classification: "OTHER", confidence: "LOW" };
+}
+
+function classifyPR(
+  labels: string[],
+  title: string,
+  branch: string,
+): { classification: PRClassification; confidence: Confidence } {
+  const lowerLabels = new Set(labels.map((l) => l.toLowerCase()));
+
+  // Labels first — HIGH confidence
+  if (lowerLabels.has("bug")) {
+    return { classification: "BUGFIX", confidence: "HIGH" };
+  }
+
+  // Title/branch patterns — MEDIUM confidence
+  if (/^fix/i.test(title)) {
+    return { classification: "BUGFIX", confidence: "MEDIUM" };
+  }
+  if (branch.startsWith("fix/") || branch.startsWith("bugfix/")) {
+    return { classification: "BUGFIX", confidence: "MEDIUM" };
+  }
+
+  // Default — LOW confidence
+  return { classification: "OTHER", confidence: "LOW" };
+}
+
+function aggregateCIStatus(checks: RawTriagePR["statusCheckRollup"]): string {
+  if (checks.length === 0) return "UNKNOWN";
+  if (checks.some((c) => c.conclusion === "failure")) return "FAIL";
+  if (checks.some((c) => c.status !== "COMPLETED")) return "PENDING";
+  return "PASS";
+}
+
+function truncateBody(body: string, maxLength = 500): string {
+  if (body.length <= maxLength) return body;
+  return body.slice(0, maxLength) + "…";
+}
+
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+
+const fetchTriageSummary = Effect.fn("issue.fetchTriageSummary")(function* (opts: {
+  state: string;
+  limit: number;
+}) {
+  const gh = yield* GitHubService;
+  const repoInfo = yield* gh.getRepoInfo();
+
+  // Parallel fetch: issues + PRs
+  const [rawIssues, rawPRs] = yield* Effect.all(
+    [
+      gh.runGhJson<RawTriageIssue[]>([
+        "issue",
+        "list",
+        "--state",
+        opts.state,
+        "--limit",
+        String(opts.limit),
+        "--json",
+        "number,title,state,url,labels,assignees,author,body,comments,createdAt",
+      ]),
+      gh.runGhJson<RawTriagePR[]>([
+        "pr",
+        "list",
+        "--state",
+        opts.state,
+        "--limit",
+        String(opts.limit),
+        "--json",
+        "number,title,state,url,labels,author,body,headRefName,baseRefName,isDraft,mergeable,reviewDecision,statusCheckRollup",
+      ]),
+    ],
+    { concurrency: "unbounded" },
+  );
+
+  // Classify + transform issues
+  const issues: TriageIssue[] = rawIssues.map((issue) => {
+    const labelNames = issue.labels.map((l) => l.name);
+    const { classification, confidence } = classifyIssue(labelNames, issue.title);
+
+    return {
+      number: issue.number,
+      title: issue.title,
+      author: issue.author.login,
+      labels: labelNames,
+      classification,
+      confidence,
+      body: truncateBody(issue.body),
+      commentsCount: issue.comments.length,
+      createdAt: issue.createdAt,
+      url: issue.url,
+    };
+  });
+
+  // Classify + transform PRs
+  const prs: TriagePR[] = rawPRs.map((pr) => {
+    const labelNames = pr.labels.map((l) => l.name);
+    const { classification, confidence } = classifyPR(labelNames, pr.title, pr.headRefName);
+
+    return {
+      number: pr.number,
+      title: pr.title,
+      author: pr.author.login,
+      labels: labelNames,
+      classification,
+      confidence,
+      headRefName: pr.headRefName,
+      baseRefName: pr.baseRefName,
+      isDraft: pr.isDraft,
+      mergeable: pr.mergeable,
+      reviewDecision: pr.reviewDecision,
+      ciStatus: aggregateCIStatus(pr.statusCheckRollup ?? []),
+      body: truncateBody(pr.body),
+      url: pr.url,
+    };
+  });
+
+  // Build summary counters
+  const issuesByType: Record<string, number> = {};
+  for (const issue of issues) {
+    issuesByType[issue.classification] = (issuesByType[issue.classification] ?? 0) + 1;
+  }
+
+  const prsByType: Record<string, number> = {};
+  for (const pr of prs) {
+    prsByType[pr.classification] = (prsByType[pr.classification] ?? 0) + 1;
+  }
+
+  const result: TriageSummary = {
+    repo: `${repoInfo.owner}/${repoInfo.name}`,
+    fetchedAt: new Date().toISOString(),
+    issues,
+    prs,
+    summary: {
+      totalIssues: issues.length,
+      totalPRs: prs.length,
+      issuesByType,
+      prsByType,
+    },
+  };
+
+  return result;
+});
+
+// ---------------------------------------------------------------------------
+// CLI Command
+// ---------------------------------------------------------------------------
+
+export const issueTriageSummaryCommand = Command.make(
+  "triage-summary",
+  {
+    format: formatOption,
+    limit: Flag.integer("limit").pipe(
+      Flag.withDescription("Maximum number of issues and PRs to fetch"),
+      Flag.withDefault(100),
+    ),
+    state: Flag.choice("state", ["open", "closed", "all"]).pipe(
+      Flag.withDescription("Filter by state: open, closed, all"),
+      Flag.withDefault("open"),
+    ),
+  },
+  ({ format, limit, state }) =>
+    Effect.gen(function* () {
+      const summary = yield* fetchTriageSummary({ limit, state });
+      yield* logFormatted(summary, format);
+    }),
+).pipe(
+  Command.withDescription(
+    "Composite: fetch all issues + PRs, classify each, return structured triage summary",
+  ),
+);

package/src/gh-tool/pr/core.ts

@@ -449,7 +449,14 @@ export const fetchChecks = Effect.fn("pr.fetchChecks")(function* (
     return yield* gh.runGhJson<CheckResult[]>([...args, "--json", "name,state,bucket,link"]);
   }
 
-  return yield* gh.runGhJson<CheckResult[]>([...args, "--json", "name,state,bucket,link"]);
+  const results = yield* gh.runGhJson<CheckResult[]>([...args, "--json", "name,state,bucket,link"]);
+  if (results.some((c) => c.bucket === "pending")) {
+    yield* Console.warn(
+      `ℹ️  Some checks are still running. Prefer --watch to block until completion instead of polling:\n` +
+        `   bun agent-tools-gh pr checks${pr !== null ? ` --pr ${pr}` : ""} --watch`,
+    );
+  }
+  return results;
 });
 
 export const fetchFailedChecks = Effect.fn("pr.fetchFailedChecks")(function* (pr: number | null) {

package/src/k8s-tool/security.ts

@@ -68,8 +68,10 @@ export function isKubectlCommandAllowed(cmd: string): K8sSecurityCheckResult {
   const kubectlPart = trimmed.split("|")[0].trim();
 
   // Extract verb: first non-flag word
-  const words = kubectlPart.split(/\s+/).filter((w) => !w.startsWith("-"));
-  const verb = words[0]?.toLowerCase();
+  const verb = kubectlPart
+    .split(/\s+/)
+    .find((word) => !word.startsWith("-"))
+    ?.toLowerCase();
 
   if (!verb) {
     return { allowed: false, command: cmd, reason: "Empty kubectl command." };

package/src/shared/error-renderer.ts

@@ -32,12 +32,10 @@ const formatError = (error: unknown): string => {
 };
 
 const formatCause = (cause: Cause.Cause<unknown>): string => {
-  const failures = cause.reasons.filter(Cause.isFailReason);
-  const firstFailure = failures[0];
+  const firstFailure = cause.reasons.find(Cause.isFailReason);
   if (firstFailure !== undefined) return formatError(firstFailure.error);
 
-  const defects = cause.reasons.filter(Cause.isDieReason);
-  const firstDefect = defects[0];
+  const firstDefect = cause.reasons.find(Cause.isDieReason);
   if (firstDefect !== undefined) {
     if (firstDefect.defect instanceof Error)
       return `Unexpected error: ${firstDefect.defect.message}`;

package/src/gh-tool/issue.ts

@@ -1,361 +0,0 @@
-import { Command, Flag } from "effect/unstable/cli";
-import { Effect, Option } from "effect";
-
-import { formatOption, logFormatted } from "#shared";
-import { GitHubCommandError } from "./errors";
-import { GitHubService } from "./service";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-type IssueInfo = {
-  number: number;
-  title: string;
-  state: string;
-  url: string;
-  labels: Array<{ name: string }>;
-  assignees: Array<{ login: string }>;
-  author: { login: string };
-  createdAt: string;
-  closedAt: string | null;
-};
-
-type IssueListItem = {
-  number: number;
-  title: string;
-  state: string;
-  url: string;
-  labels: Array<{ name: string }>;
-  createdAt: string;
-};
-
-type RawIssueComment = {
-  id: number;
-  user: { login: string };
-  body: string;
-  created_at: string;
-  html_url: string;
-};
-
-// ---------------------------------------------------------------------------
-// Handlers
-// ---------------------------------------------------------------------------
-
-const listIssues = Effect.fn("issue.listIssues")(function* (opts: {
-  state: string;
-  labels: string | null;
-  limit: number;
-}) {
-  const gh = yield* GitHubService;
-
-  const args = [
-    "issue",
-    "list",
-    "--state",
-    opts.state,
-    "--limit",
-    String(opts.limit),
-    "--json",
-    "number,title,state,url,labels,createdAt",
-  ];
-
-  if (opts.labels !== null) {
-    args.push("--label", opts.labels);
-  }
-
-  return yield* gh.runGhJson<IssueListItem[]>(args);
-});
-
-const viewIssue = Effect.fn("issue.viewIssue")(function* (issueNumber: number) {
-  const gh = yield* GitHubService;
-
-  return yield* gh.runGhJson<IssueInfo>([
-    "issue",
-    "view",
-    String(issueNumber),
-    "--json",
-    "number,title,state,url,labels,assignees,author,createdAt,closedAt",
-  ]);
-});
-
-const closeIssue = Effect.fn("issue.closeIssue")(function* (opts: {
-  issue: number;
-  comment: string | null;
-  reason: string;
-}) {
-  const gh = yield* GitHubService;
-
-  const args = ["issue", "close", String(opts.issue), "--reason", opts.reason];
-
-  if (opts.comment !== null) {
-    args.push("--comment", opts.comment);
-  }
-
-  yield* gh.runGh(args);
-
-  return yield* gh.runGhJson<IssueInfo>([
-    "issue",
-    "view",
-    String(opts.issue),
-    "--json",
-    "number,title,state,url,labels,assignees,author,createdAt,closedAt",
-  ]);
-});
-
-const reopenIssue = Effect.fn("issue.reopenIssue")(function* (opts: {
-  issue: number;
-  comment: string | null;
-}) {
-  const gh = yield* GitHubService;
-
-  const args = ["issue", "reopen", String(opts.issue)];
-
-  if (opts.comment !== null) {
-    args.push("--comment", opts.comment);
-  }
-
-  yield* gh.runGh(args);
-
-  return yield* gh.runGhJson<IssueInfo>([
-    "issue",
-    "view",
-    String(opts.issue),
-    "--json",
-    "number,title,state,url,labels,assignees,author,createdAt,closedAt",
-  ]);
-});
-
-const commentOnIssue = Effect.fn("issue.commentOnIssue")(function* (opts: {
-  issue: number;
-  body: string;
-}) {
-  const gh = yield* GitHubService;
-  const repoInfo = yield* gh.getRepoInfo();
-
-  const trimmedBody = opts.body.trim();
-  if (trimmedBody.length === 0) {
-    return yield* Effect.fail(
-      new GitHubCommandError({
-        command: "gh-tool issue comment",
-        exitCode: 0,
-        stderr: "Comment body cannot be empty",
-        message: "Comment body cannot be empty",
-      }),
-    );
-  }
-
-  const result = yield* gh.runGh([
-    "api",
-    "-X",
-    "POST",
-    `repos/${repoInfo.owner}/${repoInfo.name}/issues/${opts.issue}/comments`,
-    "-f",
-    `body=${trimmedBody}`,
-  ]);
-
-  const rawComment = yield* Effect.try({
-    try: () => JSON.parse(result.stdout) as RawIssueComment,
-    catch: (error) =>
-      new GitHubCommandError({
-        command: "gh-tool issue comment",
-        exitCode: 0,
-        stderr: `Failed to parse response: ${error instanceof Error ? error.message : String(error)}`,
-        message: `Failed to parse response: ${error instanceof Error ? error.message : String(error)}`,
-      }),
-  }).pipe(Effect.mapError((error) => error as GitHubCommandError));
-
-  return {
-    id: rawComment.id,
-    author: rawComment.user.login,
-    body: rawComment.body,
-    createdAt: rawComment.created_at,
-    url: rawComment.html_url,
-  };
-});
-
-const editIssue = Effect.fn("issue.editIssue")(function* (opts: {
-  issue: number;
-  title: string | null;
-  body: string | null;
-  addLabels: string | null;
-  removeLabels: string | null;
-  addAssignee: string | null;
-  removeAssignee: string | null;
-}) {
-  const gh = yield* GitHubService;
-
-  const args = ["issue", "edit", String(opts.issue)];
-
-  if (opts.title !== null) {
-    args.push("--title", opts.title);
-  }
-  if (opts.body !== null) {
-    args.push("--body", opts.body);
-  }
-  if (opts.addLabels !== null) {
-    args.push("--add-label", opts.addLabels);
-  }
-  if (opts.removeLabels !== null) {
-    args.push("--remove-label", opts.removeLabels);
-  }
-  if (opts.addAssignee !== null) {
-    args.push("--add-assignee", opts.addAssignee);
-  }
-  if (opts.removeAssignee !== null) {
-    args.push("--remove-assignee", opts.removeAssignee);
-  }
-
-  yield* gh.runGh(args);
-
-  return yield* gh.runGhJson<IssueInfo>([
-    "issue",
-    "view",
-    String(opts.issue),
-    "--json",
-    "number,title,state,url,labels,assignees,author,createdAt,closedAt",
-  ]);
-});
-
-// ---------------------------------------------------------------------------
-// CLI Commands
-// ---------------------------------------------------------------------------
-
-export const issueListCommand = Command.make(
-  "list",
-  {
-    format: formatOption,
-    labels: Flag.string("labels").pipe(
-      Flag.withDescription("Filter by label (comma-separated)"),
-      Flag.optional,
-    ),
-    limit: Flag.integer("limit").pipe(
-      Flag.withDescription("Maximum number of issues to return"),
-      Flag.withDefault(30),
-    ),
-    state: Flag.choice("state", ["open", "closed", "all"]).pipe(
-      Flag.withDescription("Filter by state: open, closed, all"),
-      Flag.withDefault("open"),
-    ),
-  },
-  ({ format, labels, limit, state }) =>
-    Effect.gen(function* () {
-      const issues = yield* listIssues({
-        labels: Option.getOrNull(labels),
-        limit,
-        state,
-      });
-      yield* logFormatted(issues, format);
-    }),
-).pipe(Command.withDescription("List issues (default: open, use --state to filter)"));
-
-export const issueViewCommand = Command.make(
-  "view",
-  {
-    format: formatOption,
-    issue: Flag.integer("issue").pipe(Flag.withDescription("Issue number")),
-  },
-  ({ format, issue }) =>
-    Effect.gen(function* () {
-      const info = yield* viewIssue(issue);
-      yield* logFormatted(info, format);
-    }),
-).pipe(Command.withDescription("View issue details"));
-
-export const issueCloseCommand = Command.make(
-  "close",
-  {
-    comment: Flag.string("comment").pipe(
-      Flag.withDescription("Comment to add when closing"),
-      Flag.optional,
-    ),
-    format: formatOption,
-    issue: Flag.integer("issue").pipe(Flag.withDescription("Issue number to close")),
-    reason: Flag.choice("reason", ["completed", "not planned"]).pipe(
-      Flag.withDescription("Close reason: completed, not planned"),
-      Flag.withDefault("completed"),
-    ),
-  },
-  ({ comment, format, issue, reason }) =>
-    Effect.gen(function* () {
-      const result = yield* closeIssue({
-        comment: Option.getOrNull(comment),
-        issue,
-        reason,
-      });
-      yield* logFormatted(result, format);
-    }),
-).pipe(Command.withDescription("Close an issue with optional comment and reason"));
-
-export const issueReopenCommand = Command.make(
-  "reopen",
-  {
-    comment: Flag.string("comment").pipe(
-      Flag.withDescription("Comment to add when reopening"),
-      Flag.optional,
-    ),
-    format: formatOption,
-    issue: Flag.integer("issue").pipe(Flag.withDescription("Issue number to reopen")),
-  },
-  ({ comment, format, issue }) =>
-    Effect.gen(function* () {
-      const result = yield* reopenIssue({
-        comment: Option.getOrNull(comment),
-        issue,
-      });
-      yield* logFormatted(result, format);
-    }),
-).pipe(Command.withDescription("Reopen a closed issue"));
-
-export const issueCommentCommand = Command.make(
-  "comment",
-  {
-    body: Flag.string("body").pipe(Flag.withDescription("Comment body text")),
-    format: formatOption,
-    issue: Flag.integer("issue").pipe(Flag.withDescription("Issue number to comment on")),
-  },
-  ({ body, format, issue }) =>
-    Effect.gen(function* () {
-      const result = yield* commentOnIssue({ body, issue });
-      yield* logFormatted(result, format);
-    }),
-).pipe(Command.withDescription("Post a comment on an issue"));
-
-export const issueEditCommand = Command.make(
-  "edit",
-  {
-    addAssignee: Flag.string("add-assignee").pipe(
-      Flag.withDescription("Add assignee login (comma-separated for multiple)"),
-      Flag.optional,
-    ),
-    addLabels: Flag.string("add-labels").pipe(
-      Flag.withDescription("Add labels (comma-separated)"),
-      Flag.optional,
-    ),
-    body: Flag.string("body").pipe(Flag.withDescription("New issue body"), Flag.optional),
-    format: formatOption,
-    issue: Flag.integer("issue").pipe(Flag.withDescription("Issue number to edit")),
-    removeAssignee: Flag.string("remove-assignee").pipe(
-      Flag.withDescription("Remove assignee login (comma-separated for multiple)"),
-      Flag.optional,
-    ),
-    removeLabels: Flag.string("remove-labels").pipe(
-      Flag.withDescription("Remove labels (comma-separated)"),
-      Flag.optional,
-    ),
-    title: Flag.string("title").pipe(Flag.withDescription("New issue title"), Flag.optional),
-  },
-  ({ addAssignee, addLabels, body, format, issue, removeAssignee, removeLabels, title }) =>
-    Effect.gen(function* () {
-      const result = yield* editIssue({
-        addAssignee: Option.getOrNull(addAssignee),
-        addLabels: Option.getOrNull(addLabels),
-        body: Option.getOrNull(body),
-        issue,
-        removeAssignee: Option.getOrNull(removeAssignee),
-        removeLabels: Option.getOrNull(removeLabels),
-        title: Option.getOrNull(title),
-      });
-      yield* logFormatted(result, format);
-    }),
-).pipe(Command.withDescription("Edit issue title, body, labels, or assignees"));