feat: intelligent agent suggestion engine (v8.3.0) (#7)

Author: dmicheneau

.gitignore

@@ -33,5 +33,4 @@ node_modules/
 bun.lock
 
 # OpenCode working files
-.opencode/scratchpad.md
-.opencode/agents/.manifest-lock.json
+.opencode/*

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contribuer à OpenCode Agent Template
 
-Ce projet est un registre curé de **67 agents IA** pour [OpenCode](https://opencode.ai). Tous les agents sont manuellement évalués et maintenus — il n'y a pas de synchronisation automatique. Les scripts de sync existent encore comme outils de découverte, rien de plus.
+Ce projet est un registre curé de **69 agents IA** pour [OpenCode](https://opencode.ai). Tous les agents sont manuellement évalués et maintenus — il n'y a pas de synchronisation automatique. Les scripts de sync existent encore comme outils de découverte, rien de plus.
 
 ## Comment contribuer
 
@@ -25,7 +25,7 @@ Modifiez le prompt, ajustez les permissions, ou corrigez un problème. Consultez
 Deux sources d'inspiration :
 
 - **Upstream** : `python3 scripts/sync-agents.py --list --tier=extended` pour voir ce qui existe sur [aitmpl.com](https://www.aitmpl.com/agents)
-- **Observation** : vous identifiez un gap dans les 67 agents existants
+- **Observation** : vous identifiez un gap dans les 69 agents existants
 
 ### 2 — Évaluation
 

README.en.md

@@ -4,7 +4,7 @@
 
 [![CI](https://github.com/dmicheneau/opencode-template-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/dmicheneau/opencode-template-agent/actions/workflows/ci.yml)
 ![Agents](https://img.shields.io/badge/agents-69-blue)
-![Tests](https://img.shields.io/badge/tests-893%20passing-brightgreen)
+![Tests](https://img.shields.io/badge/tests-814%20passing-brightgreen)
 ![License](https://img.shields.io/badge/license-MIT-blue)
 ![Node](https://img.shields.io/badge/node-20%2B-green)
 ![npm](https://img.shields.io/npm/v/opencode-agents?label=npm&color=cb3837)
@@ -18,9 +18,12 @@ Each agent follows an expert 4-section format: identity, decisions, examples, qu
 ## 🚀 Quickstart
 
 ```bash
-# Interactive TUI (auto-detects TTY)
+# Interactive TUI with intelligent suggestions (auto-detects TTY)
 npx github:dmicheneau/opencode-template-agent
 
+# Detect stack and suggest relevant agents
+npx github:dmicheneau/opencode-template-agent install
+
 # Quick CLI — install a pack in one command
 npx github:dmicheneau/opencode-template-agent install --pack backend
 ```
@@ -42,6 +45,7 @@ npx github:dmicheneau/opencode-template-agent tui
 **What it does:**
 
 - Auto-detects TTY and launches the interactive interface
+- **Suggestion screen on startup**: if a stack is detected in the current project, the most relevant agents appear pre-selected — press `Space` to deselect, `Enter` to install, `B` to browse the full catalog
 - Browse categories with tabs (`←` `→` / `Tab`)
 - Navigate lists with `↑` `↓`
 - Select agents with `Space`, install with `Enter`
@@ -54,6 +58,9 @@ For automation or quick installation without a graphical interface.
 **Commands:**
 
 ```bash
+# Detect stack and suggest relevant agents
+npx github:dmicheneau/opencode-template-agent install
+
 # Install a specific agent
 npx github:dmicheneau/opencode-template-agent install typescript-pro
 
@@ -83,8 +90,8 @@ npx github:dmicheneau/opencode-template-agent search "machine learning"
 
 | Option | Description |
 |--------|-------------|
-| `--force` | Overwrite existing files |
-| `--dry-run` | Preview without writing to disk |
+| `--force` | Overwrite existing files; with `install` (no args), re-suggests already-installed agents |
+| `--dry-run` | Preview without writing to disk (also works with the auto-suggest flow) |
 
 > **Note:** `--pack` and `--category` are mutually exclusive.
 
@@ -488,7 +495,7 @@ git push --tags
 
 ## 🧪 Tests
 
-**893 tests** (560 JS + 23 plugin TS + 310 Python).
+**814 tests** (504 JS + 310 Python).
 
 ```bash
 # All JS tests (CLI + TUI)

README.md

@@ -4,7 +4,7 @@
 
 [![CI](https://github.com/dmicheneau/opencode-template-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/dmicheneau/opencode-template-agent/actions/workflows/ci.yml)
 ![Agents](https://img.shields.io/badge/agents-69-blue)
-![Tests](https://img.shields.io/badge/tests-893%20passing-brightgreen)
+![Tests](https://img.shields.io/badge/tests-814%20passing-brightgreen)
 ![License](https://img.shields.io/badge/license-MIT-blue)
 ![Node](https://img.shields.io/badge/node-20%2B-green)
 ![npm](https://img.shields.io/npm/v/opencode-agents?label=npm&color=cb3837)
@@ -18,9 +18,12 @@ Chaque agent suit un format expert à 4 sections : identité, décisions, exempl
 ## 🚀 Quickstart
 
 ```bash
-# TUI interactif (auto-détecte TTY)
+# TUI interactif avec suggestions intelligentes (auto-détecte TTY)
 npx github:dmicheneau/opencode-template-agent
 
+# Détecte la stack et suggère les agents adaptés
+npx github:dmicheneau/opencode-template-agent install
+
 # CLI rapide — installer un pack en une commande
 npx github:dmicheneau/opencode-template-agent install --pack backend
 ```
@@ -42,6 +45,7 @@ npx github:dmicheneau/opencode-template-agent tui
 **Ce que ça fait :**
 
 - Auto-détecte le TTY et lance l'interface interactive
+- **Écran de suggestions au démarrage** : si une stack est détectée dans le projet courant, les agents les plus pertinents apparaissent pré-sélectionnés — appuyez sur `Space` pour désélectionner, `Enter` pour installer, `B` pour parcourir tout le catalogue
 - Parcourir les catégories par onglets (`←` `→` / `Tab`)
 - Naviguer dans les listes avec `↑` `↓`
 - Sélectionner des agents avec `Space`, installer avec `Enter`
@@ -54,6 +58,9 @@ Pour l'automatisation ou une installation rapide sans interface graphique.
 **Commandes :**
 
 ```bash
+# Détecter la stack et suggérer les agents adaptés
+npx github:dmicheneau/opencode-template-agent install
+
 # Installer un agent spécifique
 npx github:dmicheneau/opencode-template-agent install typescript-pro
 
@@ -83,8 +90,8 @@ npx github:dmicheneau/opencode-template-agent search "machine learning"
 
 | Option | Description |
 |--------|-------------|
-| `--force` | Écraser les fichiers existants |
-| `--dry-run` | Aperçu sans écriture sur le disque |
+| `--force` | Écraser les fichiers existants ; avec `install` sans argument, re-propose les agents déjà installés |
+| `--dry-run` | Aperçu sans écriture sur le disque (fonctionne aussi avec la suggestion automatique) |
 
 > **Note :** `--pack` et `--category` sont mutuellement exclusifs.
 
@@ -488,7 +495,7 @@ git push --tags
 
 ## 🧪 Tests
 
-**893 tests** (560 JS + 23 plugin TS + 310 Python).
+**814 tests** (504 JS + 310 Python).
 
 ```bash
 # Tous les tests JS (CLI + TUI)

bin/cli.mjs

@@ -7,6 +7,8 @@
 
 import { VERSION } from '../src/meta.mjs';
 
+import { createInterface } from 'node:readline';
+
 import {
   getAgent,
   getCategory,
@@ -40,8 +42,11 @@ import {
   verifyLockIntegrity,
   rehashLock,
   bootstrapLock,
+  detectInstalledSet,
 } from '../src/lock.mjs';
 
+import { detectProjectProfile, scoreAgents } from '../src/recommender.mjs';
+
 import { parsePermissionFlags } from '../src/permissions/cli.mjs';
 import { resolvePermissions } from '../src/permissions/resolve.mjs';
 import { loadPreferences, savePreferences } from '../src/permissions/persistence.mjs';
@@ -366,17 +371,157 @@ async function cmdInstall(parsed) {
   // install <agent-name>
   const agentName = parsed.args[0];
   if (!agentName) {
-    errorMessage('Missing agent name. Usage: opencode-agents install <agent>');
-    console.error(`  Run ${cyan('opencode-agents list')} to see available agents.`);
-    console.error();
-    process.exit(1);
+    // No arguments at all — run the smart suggestion flow
+    const suggestedAgents = await runSuggestFlow(parsed, options, resolvedPerms);
+    if (suggestedAgents === null) {
+      console.log(`ℹ No agent suggestions available. Try ${cyan('opencode-agents list')} to browse all agents.`);
+      return;
+    }
+    return;
   }
 
   const agent = resolveAgentOrExit(agentName, 'install');
   const result = await installAgents([agent], { ...options, permissions: resolvedPerms });
   process.exit(result.failed > 0 ? 1 : 0);
 }
 
+// ─── Smart Suggestion Flow ──────────────────────────────────────────────────────
+
+/**
+ * Detect project profile, score agents, prompt user, and install suggestions.
+ * Returns the install result on success, or `null` to signal "fall through to help".
+ *
+ * @param {ParsedArgs} parsed
+ * @param {{ force: boolean, dryRun: boolean }} options
+ * @param {object|null} resolvedPerms
+ * @returns {Promise<null | object>}
+ */
+async function runSuggestFlow(parsed, options, resolvedPerms) {
+  const manifest = getManifest();
+
+  // 1. Detect project stack — bail gracefully on any error
+  let profile;
+  try {
+    profile = detectProjectProfile(process.cwd());
+  } catch {
+    return null;
+  }
+
+  // 2. Score agents
+  const installed = options.force ? new Set() : detectInstalledSet(manifest, process.cwd());
+  const suggestions = scoreAgents({ profile, installed, manifest });
+
+  // 3. No useful suggestions → fall through
+  const useful = suggestions.filter((s) => s.score >= 0.1);
+  if (useful.length === 0) return null;
+
+  const topN = useful.slice(0, 8);
+
+  // 4. Display detected stack
+  const stackItems = [
+    ...profile.languages,
+    ...profile.tools,
+    ...(profile.frameworks ?? []),
+  ].slice(0, 5);
+
+  console.log();
+  if (stackItems.length > 0) {
+    console.log(bold('Detected stack:') + '  ' + stackItems.map((s) => cyan(s)).join(dim(' · ')));
+    console.log();
+  }
+
+  // 5. Display suggestions
+  console.log(bold('Suggested agents for this project:'));
+  console.log();
+
+  const maxNameLen = topN.reduce((m, s) => Math.max(m, s.agent.name.length), 0);
+  const ANSI_OVERHEAD = cyan('').length;
+
+  topN.forEach((s, i) => {
+    const idx  = dim(String(i + 1).padStart(2) + '.');
+    const name = padRight(cyan(s.agent.name), maxNameLen + ANSI_OVERHEAD);
+    const pct  = bold(String(Math.round(s.score * 100)).padStart(3) + '%');
+    const desc = truncate(s.agent.description, 60);
+    const reasons = s.reasons.slice(0, 4).join(dim(' · '));
+
+    console.log(`  ${idx} ${name}  ${pct}  ${dim('—')} ${dim(desc)}`);
+    if (reasons) {
+      console.log(`      ${dim(reasons)}`);
+    }
+  });
+
+  console.log();
+
+  // 6. Prompt Y/n (auto-confirm when --force or non-TTY)
+  const autoConfirm = options.force || !process.stdin.isTTY;
+  let confirmed;
+
+  if (autoConfirm) {
+    confirmed = true;
+    if (options.dryRun) {
+      console.log(dim(`  (auto-confirmed — dry run)`));
+    } else if (!process.stdin.isTTY) {
+      console.log(dim(`  (auto-confirming in non-interactive mode)`));
+    }
+  } else {
+    process.stdout.write(`Install these ${topN.length} agents? [Y/n] `);
+    confirmed = await readYesNo();
+  }
+
+  if (!confirmed) {
+    console.log();
+    showHelp();
+    process.exit(0);
+  }
+
+  // 7. Install
+  console.log();
+  header(`Installing ${topN.length} suggested agent(s)...`);
+  const result = await installAgents(topN.map((s) => s.agent), { ...options, permissions: resolvedPerms });
+  process.exit(result.failed > 0 ? 1 : 0);
+  return result;
+}
+
+// ─── Suggestion flow helpers ────────────────────────────────────────────────────
+
+/**
+ * Read a single line from stdin, return true for Y/y/o/enter, false for N/n.
+ * @returns {Promise<boolean>}
+ */
+async function readYesNo() {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question('', (answer) => {
+      rl.close();
+      const a = answer.trim().toLowerCase();
+      resolve(a === '' || a === 'y' || a === 'o');
+    });
+  });
+}
+
+/**
+ * Pad a string (which may contain ANSI codes) to `width` visible chars.
+ * @param {string} s
+ * @param {number} width
+ * @returns {string}
+ */
+function padRight(s, width) {
+  // Strip ANSI to measure visible length
+  const visible = s.replace(/\x1b\[[0-9;]*m/g, '').length;
+  return s + ' '.repeat(Math.max(0, width - visible));
+}
+
+/**
+ * Truncate a plain string to `max` chars, appending '…' if cut.
+ * @param {string} s
+ * @param {number} max
+ * @returns {string}
+ */
+function truncate(s, max) {
+  if (s.length <= max) return s;
+  return s.slice(0, max - 1) + '…';
+}
+
 // ─── Command: uninstall ─────────────────────────────────────────────────────────
 
 /**

data/ecosystem-intent-tags.csv

@@ -0,0 +1,70 @@
+agent_name,ecosystem,intent,related_agents
+accessibility,web,audit,"ui-designer,react-specialist,nextjs-developer,screenshot-ui-analyzer"
+ai-engineer,ai,build,"ml-engineer,llm-architect,mlops-engineer,data-scientist"
+angular-architect,javascript,build,"typescript-pro,react-specialist,vue-expert,nextjs-developer"
+api-architect,web,design,"graphql-architect,database-architect,microservices-architect,documentation-engineer"
+api-documenter,web,document,"technical-writer,api-architect,documentation-engineer,diagram-architect"
+aws-specialist,cloud,deploy,"terraform-specialist,platform-engineer,kubernetes-specialist,ci-cd-engineer"
+business-analyst,web,plan,"product-manager,prd,project-manager,ux-researcher"
+ci-cd-engineer,devops,deploy,"docker-specialist,kubernetes-specialist,platform-engineer,sre-engineer"
+code-reviewer,web,review,"refactoring-specialist,test-automator,debugger,typescript-pro"
+compliance-auditor,security,audit,"security-auditor,security-engineer,penetration-tester,mcp-security-auditor"
+cpp-pro,web,build,"rust-pro,performance-engineer,debugger,refactoring-specialist"
+csharp-developer,dotnet,build,"java-architect,typescript-pro,database-architect,api-architect"
+data-analyst,data,research,"data-scientist,data-engineer,sql-pro,postgres-pro"
+data-engineer,data,build,"data-scientist,ml-engineer,postgres-pro,database-architect"
+data-scientist,data,research,"ml-engineer,data-engineer,ai-engineer,data-analyst"
+database-architect,data,design,"postgres-pro,sql-pro,api-architect,data-engineer"
+debugger,web,debug,"code-reviewer,performance-engineer,test-automator,refactoring-specialist"
+diagram-architect,web,document,"documentation-engineer,microservices-architect,api-architect,technical-writer"
+docker-specialist,devops,deploy,"kubernetes-specialist,ci-cd-engineer,platform-engineer,sre-engineer"
+documentation-engineer,web,document,"technical-writer,api-documenter,diagram-architect,api-architect"
+fullstack-developer,javascript,build,"typescript-pro,react-specialist,nextjs-developer,postgres-pro"
+golang-pro,go,build,"rust-pro,microservices-architect,kubernetes-specialist,docker-specialist"
+graphql-architect,web,design,"api-architect,database-architect,react-specialist,nextjs-developer"
+incident-responder,devops,debug,"sre-engineer,kubernetes-specialist,platform-engineer,docker-specialist"
+java-architect,jvm,build,"kotlin-specialist,microservices-architect,database-architect,api-architect"
+kotlin-specialist,jvm,build,"java-architect,mobile-developer,microservices-architect,api-architect"
+kubernetes-specialist,devops,deploy,"docker-specialist,platform-engineer,ci-cd-engineer,sre-engineer"
+legacy-modernizer,web,migrate,"refactoring-specialist,code-reviewer,typescript-pro,test-automator"
+linux-admin,devops,deploy,"docker-specialist,sre-engineer,kubernetes-specialist,platform-engineer"
+llm-architect,ai,design,"ai-engineer,prompt-engineer,ml-engineer,search-specialist"
+mcp-developer,mcp,build,"mcp-security-auditor,typescript-pro,api-architect"
+mcp-security-auditor,mcp,audit,"mcp-developer,security-auditor,compliance-auditor,security-engineer"
+microservices-architect,cloud,design,"api-architect,docker-specialist,kubernetes-specialist,database-architect"
+ml-engineer,ai,build,"data-scientist,mlops-engineer,ai-engineer,llm-architect"
+mlops-engineer,ai,deploy,"ml-engineer,docker-specialist,kubernetes-specialist,ai-engineer"
+mobile-developer,mobile,build,"react-specialist,swift-expert,kotlin-specialist,ui-designer"
+nextjs-developer,javascript,build,"react-specialist,typescript-pro,ui-designer,fullstack-developer"
+penetration-tester,security,audit,"security-auditor,compliance-auditor,security-engineer,mcp-security-auditor"
+performance-engineer,web,optimize,"debugger,code-reviewer,test-automator,refactoring-specialist"
+php-pro,php,build,"database-architect,api-architect,code-reviewer,refactoring-specialist"
+platform-engineer,devops,deploy,"kubernetes-specialist,docker-specialist,ci-cd-engineer,sre-engineer"
+postgres-pro,data,optimize,"database-architect,sql-pro,data-engineer,redis-specialist"
+prd,web,plan,"product-manager,business-analyst,project-manager,ux-researcher"
+product-manager,web,plan,"prd,business-analyst,ux-researcher,scrum-master"
+project-manager,web,plan,"product-manager,scrum-master,business-analyst,prd"
+prompt-engineer,ai,optimize,"llm-architect,ai-engineer,search-specialist"
+python-pro,python,build,"data-scientist,ai-engineer,data-engineer,api-architect"
+qa-expert,web,test,"test-automator,code-reviewer,debugger,performance-engineer"
+rails-expert,ruby,build,"database-architect,api-architect,code-reviewer,refactoring-specialist"
+react-specialist,javascript,build,"nextjs-developer,typescript-pro,ui-designer,angular-architect"
+redis-specialist,data,optimize,"postgres-pro,database-architect,performance-engineer,api-architect"
+refactoring-specialist,web,migrate,"code-reviewer,legacy-modernizer,test-automator,debugger"
+rust-pro,rust,build,"cpp-pro,golang-pro,performance-engineer,debugger"
+screenshot-ui-analyzer,web,review,"ui-designer,accessibility,react-specialist,ux-researcher"
+scrum-master,web,plan,"product-manager,project-manager,business-analyst,prd"
+search-specialist,ai,research,"data-analyst,llm-architect,prompt-engineer"
+security-auditor,security,audit,"penetration-tester,compliance-auditor,security-engineer,mcp-security-auditor"
+security-engineer,security,audit,"security-auditor,compliance-auditor,penetration-tester,ci-cd-engineer"
+smart-contract-auditor,security,audit,"security-auditor,compliance-auditor,penetration-tester"
+sql-pro,data,optimize,"postgres-pro,database-architect,data-engineer,data-analyst"
+sre-engineer,devops,deploy,"kubernetes-specialist,platform-engineer,incident-responder,docker-specialist"
+swift-expert,mobile,build,"mobile-developer,kotlin-specialist,ui-designer"
+technical-writer,web,document,"documentation-engineer,api-documenter,diagram-architect"
+terraform-specialist,devops,deploy,"aws-specialist,platform-engineer,kubernetes-specialist,ci-cd-engineer"
+test-automator,web,test,"qa-expert,code-reviewer,debugger,ci-cd-engineer"
+typescript-pro,javascript,build,"react-specialist,nextjs-developer,code-reviewer,refactoring-specialist"
+ui-designer,web,design,"accessibility,react-specialist,nextjs-developer,screenshot-ui-analyzer"
+ux-researcher,web,research,"product-manager,business-analyst,ui-designer,accessibility"
+vue-expert,javascript,build,"angular-architect,react-specialist,typescript-pro,nextjs-developer"