@cursor/july 0.1.42 → 0.1.45

package/templates/triage/README.md

@@ -0,0 +1,48 @@
+# Triage agent
+
+A triage front door for your team. Send it bug reports, questions, and
+feedback; it classifies each report against a rubric, judges severity,
+records a structured verdict, and replies with the next step.
+
+Scaffolded with:
+
+```bash
+npx @cursor/july init ./my-triage-agent --template triage
+```
+
+## Run it
+
+```bash
+agent-sdk login   # once per machine
+agent-sdk dev
+```
+
+Open the playground URL it prints. Chat directly, or use the `/report`
+slash command to submit a report the way an integration would
+(`POST /v1/channels/intake/report`).
+
+## Wire it to Slack
+
+The Slack channel idles until its tokens exist. Create a Slack app and
+its env with:
+
+```bash
+agent-sdk slack setup
+```
+
+Then @mention the bot or DM it. The setup-slack skill in the
+@cursor/july package has the full walkthrough.
+
+## Make it yours
+
+- `agent/instructions.md` owns the flow every report follows.
+- `agent/skills/triage-rubric.md` owns the kinds, the tie-breakers, and
+  the severity ladder. Edit this first; it is the judgment.
+- `agent/tools/record_triage.ts` owns the verdict shape. Point its
+  `execute` at your tracker (Linear, GitHub Issues, a webhook) to file
+  real tickets.
+- `evals/triage.eval.ts` holds three smoke cases. Run `agent-sdk eval`
+  after every rubric change.
+
+The full walkthrough, from scaffold through deploy, is the triage
+cookbook: run `agent-sdk docs` and open Templates, then Triage agent.

package/templates/triage/agent/agent.ts

@@ -0,0 +1,14 @@
+import { defineAgent } from "@cursor/july";
+
+export default defineAgent({
+  model: {
+    id: "grok-4.5",
+    params: [
+      { id: "effort", value: "high" },
+      { id: "fast", value: "true" },
+    ],
+  },
+  local: {
+    sandbox: true,
+  },
+});

package/templates/triage/agent/channels/intake.ts

@@ -0,0 +1,20 @@
+import { defineChannel, POST } from "@cursor/july/channels";
+import { z } from "zod";
+
+export default defineChannel({
+  routes: [
+    POST("/report", {
+      description: "Submit a report for triage",
+      bodySchema: z.object({
+        message: z.string(),
+        reporter: z.string().optional(),
+      }),
+      handler: async (_req, { send, body }) => {
+        const from =
+          body.reporter === undefined ? "" : ` (from ${body.reporter})`;
+        const session = await send(`New report${from}:\n\n${body.message}`);
+        return Response.json({ ok: true, sessionId: session.id });
+      },
+    }),
+  ],
+});

package/templates/triage/agent/channels/slack.ts

@@ -0,0 +1,3 @@
+import { slackChannel } from "@cursor/july/channels/slack";
+
+export default slackChannel();

package/templates/triage/agent/hooks/memory.ts

@@ -0,0 +1,3 @@
+import { memoryHook } from "@cursor/july/memory";
+
+export default memoryHook();

package/templates/triage/agent/instructions.md

@@ -0,0 +1,27 @@
+# Triage agent
+
+You are the triage front door for this team. People send you reports:
+bug reports, questions, feedback, feature ideas. You classify each one,
+judge its severity, and hand back a verdict the team can act on.
+
+Read the `triage-rubric` skill before classifying. It defines the three
+kinds and the tie-breakers.
+
+## Every report
+
+1. Read the report. If it is too thin to classify (no symptom, no
+   question, no opinion), ask for the missing piece once. Otherwise do
+   not ask; classify with what you have.
+2. If a `memory/` directory exists in your workspace, grep the journal
+   for similar past reports and say when one matches.
+3. Call `record_triage` exactly once with your verdict.
+4. Reply with the verdict: kind, severity, a one-line reason, and the
+   next step. Keep the reply under six lines. No preamble.
+
+## Boundaries
+
+- You classify and route. You do not fix bugs, write code, or promise
+  timelines.
+- When a report mixes kinds, pick the dominant one and name the split
+  in your reason.
+- Never invent reporter details. Missing fields stay empty.

package/templates/triage/agent/skills/triage-rubric.md

@@ -0,0 +1,43 @@
+---
+description: Definitions and tie-breakers for classifying a report as bug, question, or feedback, plus the severity ladder.
+---
+
+# Triage rubric
+
+## Kinds
+
+- **bug**: something is broken, erroring, slow, or behaving wrong right
+  now, and the reporter wants it diagnosed or fixed. Usually has a
+  symptom, an error, an id, a timestamp, or steps.
+- **question**: the reporter wants to know something that has an answer
+  (how does X work, is Y expected, who owns Z). Someone has to look it
+  up, not fix it.
+- **feedback**: an opinion, suggestion, complaint about how something
+  behaves, or a feature idea. The reporter is telling the team
+  something, not asking it to find anything out.
+
+## Tie-breakers
+
+- "This is annoying, you should change X" is feedback even when it
+  sounds like a complaint.
+- A question about a specific failure that already happened is a bug.
+  "Why did my export fail yesterday?" needs an investigation, not a
+  lookup.
+- A bug report that also suggests a fix is a bug.
+- A known bug with a workaround that only works sometimes is a bug. The
+  unreliable workaround is the thing to explain.
+- A feature idea phrased as a question ("could we have dark mode?") is
+  feedback.
+
+## Severity
+
+- **urgent**: data loss, security exposure, or many users blocked with
+  no workaround.
+- **high**: a core flow is broken or wrong for some users, no
+  reasonable workaround.
+- **medium**: broken or wrong with a workaround, or a sharp edge that
+  costs time.
+- **low**: cosmetic, minor friction, questions, and most feedback.
+
+Questions and feedback default to low unless the report shows real
+user impact.

package/templates/triage/agent/tools/record_triage.ts

@@ -0,0 +1,23 @@
+import { defineTool } from "@cursor/july/tools";
+import { z } from "zod";
+
+export default defineTool({
+  description:
+    "Record the structured triage verdict for the current report. Call exactly once per report, before replying.",
+  inputSchema: z.object({
+    kind: z.enum(["bug", "question", "feedback"]),
+    severity: z.enum(["low", "medium", "high", "urgent"]),
+    title: z
+      .string()
+      .max(80)
+      .describe("Short, imperative summary of the report."),
+    summary: z
+      .string()
+      .describe("What the reporter said, in two sentences or less."),
+    nextStep: z.string().describe("The single next action for the team."),
+    reporter: z.string().optional().describe("Who reported it, when known."),
+  }),
+  async execute(verdict) {
+    return { recorded: true, at: new Date().toISOString(), verdict };
+  },
+});

package/templates/triage/evals/evals.config.ts

@@ -0,0 +1,5 @@
+import { defineEvalConfig } from "@cursor/july/evals";
+
+export default defineEvalConfig({
+  maxConcurrency: 10,
+});

package/templates/triage/evals/triage.eval.ts

@@ -0,0 +1,43 @@
+import { defineEval, includes } from "@cursor/july/evals";
+
+export default defineEval({
+  tags: ["smoke"],
+  cases: [
+    {
+      id: "bug",
+      description: "A concrete failure is recorded as a bug.",
+      async test(t) {
+        await t.send(
+          "Export to CSV has failed with a 500 since this morning. Request id 41ac. Retrying does not help."
+        );
+        t.succeeded();
+        t.calledTool("record_triage");
+        t.check(t.reply, includes(/bug/i));
+      },
+    },
+    {
+      id: "question",
+      description: "A how-does-it-work ask is recorded as a question.",
+      async test(t) {
+        await t.send(
+          "How do I rotate the API keys for the staging environment?"
+        );
+        t.succeeded();
+        t.calledTool("record_triage");
+        t.check(t.reply, includes(/question/i));
+      },
+    },
+    {
+      id: "feedback",
+      description: "A suggestion is recorded as feedback.",
+      async test(t) {
+        await t.send(
+          "The onboarding wizard has too many steps. You should collapse the profile pages into one."
+        );
+        t.succeeded();
+        t.calledTool("record_triage");
+        t.check(t.reply, includes(/feedback/i));
+      },
+    },
+  ],
+});

package/templates/triage/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "triage-agent",
+  "private": true,
+  "type": "module",
+  "description": "Triage agent: classifies bug reports, questions, and feedback into structured verdicts.",
+  "scripts": {
+    "check": "tsc --noEmit",
+    "dev": "agent-sdk dev"
+  },
+  "dependencies": {
+    "@cursor/july": "latest",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.0",
+    "typescript": "^5.8.0"
+  }
+}

package/templates/triage/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["agent/**/*", "evals/**/*"]
+}