great-cto 2.8.6 → 2.9.1

package/dist/adapt.js

@@ -77,6 +77,44 @@ Configure Claude Code to launch:
 npx great-cto mcp
 \`\`\`
 
+## Subagent routing (do not default to general-purpose)
+
+When dispatching the **Agent** tool, pick the right \`subagent_type\` based on
+what's being changed. \`general-purpose\` is a fallback, **not** the default —
+using it for pattern-matched work silently skips specialist review.
+
+| Trigger (file pattern OR topic in prompt) | Use \`subagent_type:\` |
+|---|---|
+| \`migrations/\`, \`schema.sql\`, ORM migration files | \`db-migration-reviewer\` |
+| \`auth/\`, OAuth/SAML/JWT, login flow, password reset | \`security-officer\` |
+| Payment endpoints, \`stripe.\`, webhooks, refund flow | \`pci-reviewer\` |
+| Prompts in \`prompts/\`, RAG, tool definitions, LLM-facing strings | \`ai-security-reviewer\` |
+| Eval suites, golden citation tests, prompt regression | \`ai-eval-engineer\` |
+| Play Store, App Store, iOS/Android release | \`mobile-store-reviewer\` |
+| API contract: OpenAPI, GraphQL schema, webhook signatures | \`api-platform-reviewer\` |
+| Voice/IVR/telephony, Twilio, recording-consent, TCPA | \`voice-ai-reviewer\` |
+| Clinical / SaMD / FDA / FHIR / PHI | \`ai-clinical-reviewer\`, \`fda-reviewer\` |
+| Lending, ECOA, FCRA, NMLS, adverse action | \`lending-credit-reviewer\` |
+| HR-AI, hiring, AEDT, resume screening | \`hr-ai-reviewer\` |
+| Infra-as-code: Terraform / Helm / CDK / Pulumi | \`infra-reviewer\` |
+| Performance regression, hot path, p99 budgets | \`performance-engineer\` |
+| Browser extension manifest, MV3 permissions | \`web-store-reviewer\` |
+| New feature implementation (TDD) | \`senior-dev\` |
+| Architecture decisions, ADRs, scaling questions | \`architect\` |
+| Planning a feature into tasks (Beads), dependency graph | \`pm\` |
+| QA report after impl, coverage + acceptance | \`qa-engineer\` |
+| Deploy / canary / rollback / SLO | \`devops\` |
+| Production incident triage, P0 postmortem | \`l3-support\` |
+| Pattern extraction from session, retro to \`lessons.md\` | \`continuous-learner\` |
+
+Rule of thumb: if a file pattern or topic matches above, use that specialist
+**before** falling back to \`general-purpose\`. Specialist agents catch
+domain-specific bugs (race conditions in migrations, prompt-injection vectors,
+TCPA violations) that a generalist won't flag.
+
+When in doubt, run two agents in parallel: the specialist + general-purpose,
+and reconcile their outputs.
+
 ## Style + conventions
 
 - Tests **before** implementation (RED → GREEN → REFACTOR). Coverage 80%+ default.

package/dist/main.js

@@ -10,16 +10,18 @@
 //   7. bootstrap .great_cto/PROJECT.md
 //   8. print next steps
 import { resolve } from "node:path";
-import { banner, bold, cyan, dim, error, green, log, step, warn, yellow, confirm } from "./ui.js";
+import { banner, bold, cyan, dim, error, gray, green, log, step, warn, yellow, confirm } from "./ui.js";
 import { detect } from "./detect.js";
 import { pickArchetype, suggestCompliance } from "./archetypes.js";
 import { install, findInstalledVersions } from "./installer.js";
 import { enableGreatCto } from "./settings.js";
 import { bootstrap } from "./bootstrap.js";
 import { shouldUseLlmFallback, suggestArchetypeFromLlm } from "./llm-fallback.js";
-import { readFileSync } from "node:fs";
+import { isTelemetryEnabled, sendInstallPing, telemetrySubcommand, computeAnonId, } from "./telemetry.js";
+import { readFileSync, writeFileSync, mkdirSync, existsSync as fsExistsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
 function getCliVersion() {
     try {
         const here = dirname(fileURLToPath(import.meta.url));
@@ -94,6 +96,8 @@ function parseArgs(argv) {
             args.command = "webhook";
         else if (a === "report")
             args.command = "report";
+        else if (a === "telemetry")
+            args.command = "telemetry";
         // Slash-commands surfaced as CLI subcommands so users get a clear hint
         // instead of a confusing usage error. These work only in the chat plugin.
         else if (a === "start" || a === "audit" || a === "inbox" || a === "digest" ||
@@ -394,6 +398,13 @@ ${bold("Claude Code adapter:")}
   great-cto adapt --dry-run            Preview what would be written
   ${dim("Idempotent — re-run after editing .great_cto/PROJECT.md")}
 
+${bold("Telemetry (opt-IN, off by default):")}
+  great-cto telemetry status           Show current state + endpoint + anon_id
+  great-cto telemetry on               Enable anonymous usage events
+  great-cto telemetry off              Disable (also: DO_NOT_TRACK=1)
+  great-cto telemetry whoami           Print your anon_id (8 hex chars)
+  ${dim("Privacy: docs/PRIVACY.md · no code, no repo names, no PII")}
+
 ${bold("Webhook server (preview):")}
   great-cto serve --port 3142          Webhook receiver (logs to ~/.great_cto/webhook-events.log)
   ${dim("Endpoints: POST /webhook/github, POST /webhook/generic, GET /events, GET /healthz")}
@@ -750,6 +761,19 @@ async function runInit(args) {
     log("");
     log(green(bold("✓ great_cto is ready.")));
     log("");
+    // ── 6. opt-IN telemetry prompt ───────────────────────────
+    // Aggressive opt-IN promo (Option A from telemetry strategy).
+    // Shows up only when interactive + not CI + not already decided + DO_NOT_TRACK unset.
+    await promoteTelemetryOptIn({ archetype: archetype, cliVersion: getCliVersion(), yes: args.yes });
+    // If telemetry is enabled (either via prior opt-in or env var), fire a fresh
+    // install-ping so re-runs of `init` (after upgrades) count toward WAU/MAU.
+    if (isTelemetryEnabled()) {
+        await sendInstallPing({
+            cliVersion: getCliVersion(),
+            archetype: archetype,
+            consent: true,
+        }).catch(() => { });
+    }
     log(bold("Next steps:"));
     log(`  1. ${dim("Restart Claude Code to pick up the plugin.")}`);
     log(`  2. ${dim("Edit")} ${cyan(".great_cto/PROJECT.md")} ${dim("to refine goals and compliance.")}`);
@@ -761,6 +785,82 @@ async function runInit(args) {
     log("");
     return 0;
 }
+// ── Telemetry opt-IN prompt ────────────────────────────────────────────────
+// Shows after a successful init when interactive. NOT shown if:
+//   - --yes / -y was used (skip-confirmation mode)
+//   - DO_NOT_TRACK=1 (respect honest signal)
+//   - Already opted in or explicitly opted out (no nag)
+//   - CI environment
+//   - Non-TTY stdin (piped install)
+async function promoteTelemetryOptIn(opts) {
+    // Skip prompts in non-interactive mode.
+    if (opts.yes)
+        return;
+    if (!process.stdin.isTTY)
+        return;
+    if (process.env.DO_NOT_TRACK === "1" || process.env.DO_NOT_TRACK === "true")
+        return;
+    if (process.env.CI || process.env.GITHUB_ACTIONS)
+        return;
+    // If user already made a decision (either way), respect it — don't re-ask.
+    const cfgFile = join(homedir(), ".great_cto", "telemetry.json");
+    if (fsExistsSync(cfgFile)) {
+        try {
+            const cfg = JSON.parse(readFileSync(cfgFile, "utf8"));
+            if (cfg.enabled === true || cfg.enabled === false)
+                return;
+        }
+        catch { /* malformed — ask again */ }
+    }
+    // The honest, brand-aligned ask.
+    log(dim("─".repeat(60)));
+    log(bold("Help great_cto learn from how you use it?"));
+    log("");
+    log(dim("Anonymous usage data (default: off). Helps cross-project"));
+    log(dim("lessons promote to a global pattern library."));
+    log("");
+    log(dim("Here is exactly what would be sent — one event per command:"));
+    log("");
+    log(gray(`  {`));
+    log(gray(`    "version": "${opts.cliVersion}",`));
+    log(gray(`    "command": "init",`));
+    log(gray(`    "archetype": "${opts.archetype}",`));
+    log(gray(`    "node": "${process.version.replace(/^v/, "")}",`));
+    log(gray(`    "os": "${process.platform}",`));
+    log(gray(`    "exit_code": 0,`));
+    log(gray(`    "duration_ms": 1234,`));
+    log(gray(`    "anon_id": "${computeAnonId()}"   ${dim("// 8 hex chars, not reversible")}`));
+    log(gray(`  }`));
+    log("");
+    log(dim("No code, no repo names, no file paths, no PII."));
+    log(dim("Toggle anytime: " + cyan("npx great-cto telemetry off")));
+    log(dim("Privacy: " + cyan("github.com/avelikiy/great_cto/blob/main/docs/PRIVACY.md")));
+    log("");
+    const yes = await confirm(bold("Enable anonymous telemetry?"), false);
+    log("");
+    // Persist the decision either way so we never re-ask.
+    try {
+        const dir = join(homedir(), ".great_cto");
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, "telemetry.json"), JSON.stringify({ enabled: yes, decided_at: new Date().toISOString() }, null, 2) + "\n");
+    }
+    catch { /* best-effort */ }
+    if (yes) {
+        log(green(`✓ Telemetry enabled. Thank you.`));
+        log(dim(`  See your anon_id anytime: ${cyan("npx great-cto telemetry whoami")}`));
+        log("");
+        // Send the first event — the install-ping itself.
+        await sendInstallPing({
+            cliVersion: opts.cliVersion,
+            archetype: opts.archetype,
+            consent: true,
+        });
+    }
+    else {
+        log(dim(`Telemetry off. ${cyan("npx great-cto telemetry on")} to change later.`));
+        log("");
+    }
+}
 async function main() {
     const rawArgv = process.argv.slice(2);
     const args = parseArgs(rawArgv);
@@ -775,6 +875,12 @@ async function main() {
         log(`Run ${cyan("great-cto --help")} for usage.`);
         process.exit(2);
     }
+    if (args.command === "telemetry") {
+        const sub = rawArgv[rawArgv.indexOf("telemetry") + 1];
+        const { exitCode, output } = telemetrySubcommand(sub);
+        process.stdout.write(output);
+        process.exit(exitCode);
+    }
     if (args.command === "scan") {
         try {
             const code = await runScan(args, rawArgv);

package/dist/webhook-dispatch.js

@@ -11,6 +11,7 @@
 //   - slack: posts as Slack incoming-webhook JSON ({text, blocks?})
 //   - discord: Discord webhook JSON ({content, embeds?})
 //   - pagerduty: Events API v2 ({routing_key, event_action, payload})
+//   - resend: HTML email via Resend API ({from, to, subject, html})
 //   - generic: arbitrary JSON POST
 import { appendFileSync, existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
@@ -39,6 +40,62 @@ function formatDiscord(ev) {
         embeds: ev.body ? [{ description: ev.body, color }] : undefined,
     };
 }
+function emojiForLevel(level) {
+    return level === "critical" ? "🚨"
+        : level === "error" ? "❌"
+            : level === "warning" ? "⏸️"
+                : "ℹ️";
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+}
+/**
+ * Build the Resend API payload — POSTed to https://api.resend.com/emails
+ * with Authorization: Bearer <api_key>.
+ *
+ * Body fields from meta:
+ *   - project, link (CTA URL), action (CTA label)
+ *   - kv: Record<string,string> for the metric table
+ *   - severity (optional override for color)
+ */
+function formatResend(ev, hook) {
+    const accent = ev.level === "critical" ? "#dc2626"
+        : ev.level === "error" ? "#ea580c"
+            : ev.level === "warning" ? "#d97706"
+                : "#00d97e";
+    const emoji = emojiForLevel(ev.level);
+    const meta = (ev.meta ?? {});
+    const project = typeof meta.project === "string" ? meta.project : "great_cto";
+    const link = typeof meta.link === "string" ? meta.link : "";
+    const action = typeof meta.action === "string" ? meta.action : "View in board";
+    const kv = (meta.kv ?? {});
+    const tableRows = Object.entries(kv)
+        .map(([k, v]) => `<tr><td style="padding:6px 12px;color:#6b7280;font-size:12px;font-family:ui-monospace,monospace;text-transform:uppercase;letter-spacing:.05em">${escapeHtml(k)}</td><td style="padding:6px 12px;color:#111827;font-size:14px;font-weight:500">${escapeHtml(v)}</td></tr>`)
+        .join("");
+    const html = `<!doctype html><html><body style="margin:0;background:#f9fafb;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;color:#111827">
+<div style="max-width:560px;margin:32px auto;background:#ffffff;border:1px solid #e5e7eb;border-radius:12px;overflow:hidden">
+  <div style="padding:20px 24px;border-bottom:1px solid #e5e7eb;background:#0a0e0c;color:#ffffff">
+    <div style="font-size:11px;font-family:ui-monospace,monospace;letter-spacing:.1em;color:#9ca3af">${escapeHtml(project.toUpperCase())} · GREATCTO</div>
+    <div style="font-size:20px;font-weight:600;margin-top:6px;color:${accent}">${emoji} ${escapeHtml(ev.title)}</div>
+  </div>
+  ${ev.body ? `<div style="padding:20px 24px;font-size:14px;line-height:1.55;color:#374151">${escapeHtml(ev.body).replace(/\n/g, "<br>")}</div>` : ""}
+  ${tableRows ? `<table style="width:100%;border-top:1px solid #e5e7eb;border-collapse:collapse">${tableRows}</table>` : ""}
+  ${link ? `<div style="padding:24px;text-align:center;border-top:1px solid #e5e7eb">
+    <a href="${escapeHtml(link)}" style="display:inline-block;background:${accent};color:#ffffff;text-decoration:none;padding:10px 22px;border-radius:8px;font-weight:600;font-size:14px">${escapeHtml(action)}</a>
+  </div>` : ""}
+  <div style="padding:14px 24px;background:#f9fafb;font-size:11px;color:#9ca3af;font-family:ui-monospace,monospace">
+    Sent by great_cto · ${escapeHtml(ev.name)} · ${new Date().toISOString()}<br>
+    Unsubscribe: edit ~/.great_cto/webhooks.json or the Notifications tab in the board
+  </div>
+</div></body></html>`;
+    const to = (hook.to ?? "").split(",").map(s => s.trim()).filter(Boolean);
+    return {
+        from: hook.from ?? "GreatCTO <notifications@greatcto.systems>",
+        to,
+        subject: `${emoji} ${ev.title}`,
+        html,
+    };
+}
 function formatPagerDuty(ev, routingKey) {
     // PagerDuty Events API v2
     const severity = ev.level === "critical" ? "critical"
@@ -65,6 +122,7 @@ function buildPayload(hook, ev) {
             const key = hook.headers?.routing_key ?? "";
             return formatPagerDuty(ev, key);
         }
+        case "resend": return formatResend(ev, hook);
         case "generic":
         default: return { event: ev.name, ...ev };
     }
@@ -79,7 +137,18 @@ async function deliver(hook, ev, attempt = 0) {
         };
         // Don't leak routing_key as HTTP header — PagerDuty wants it in body
         delete headers.routing_key;
-        const res = await fetch(hook.url, { method: "POST", headers, body });
+        // Resend: Bearer auth + URL override (config can leave url blank).
+        let url = hook.url;
+        if (hook.format === "resend") {
+            if (!hook.apiKey)
+                throw new Error("resend: apiKey is required");
+            if (!hook.to)
+                throw new Error("resend: 'to' email is required");
+            headers["Authorization"] = `Bearer ${hook.apiKey}`;
+            if (!url)
+                url = "https://api.resend.com/emails";
+        }
+        const res = await fetch(url, { method: "POST", headers, body });
         if (!res.ok) {
             throw new Error(`HTTP ${res.status} ${res.statusText}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "great-cto",
-  "version": "2.8.6",
+  "version": "2.9.1",
   "description": "One command install for the great_cto Claude Code plugin. Auto-detects your stack, picks the right archetype, bootstraps PROJECT.md.",
   "keywords": [
     "claude-code",
@@ -86,4 +86,4 @@
   "engines": {
     "node": ">=18.17.0"
   }
-}
+}