The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat: add ECC consult command
Affaan Mustafa9a3f72712b21
diff --git a/README.md b/README.mdindex 3978ad8d0..6d89fc490 100644--- a/README.md+++ b/README.md@@ -207,6 +207,16 @@ Add hooks later only if you want runtime enforcement:./install.sh --target claude --modules hooks-runtime```+### Find the right components first++If you are not sure which ECC profile or component to install, ask the packaged advisor from any project:++```bash+npx ecc consult "security reviews" --target claude+```++It returns matching components, related profiles, and preview/install commands. Use the preview command before installing if you want to inspect the exact file plan.+### Step 1: Install the Plugin (Recommended)> NOTE: The plugin is convenient, but the OSS installer below is still the most reliable path if your Claude Code build has trouble resolving self-hosted marketplace entries.diff --git a/package.json b/package.jsonindex 6dd8e336d..87605f8ce 100644--- a/package.json+++ b/package.json@@ -62,6 +62,7 @@"rules/","schemas/","scripts/catalog.js",+ "scripts/consult.js","scripts/auto-update.js","scripts/claw.js","scripts/codex/merge-codex-config.js",diff --git a/scripts/consult.js b/scripts/consult.jsnew file mode 100644index 000000000..a560cc3c4--- /dev/null+++ b/scripts/consult.js@@ -0,0 +1,441 @@+#!/usr/bin/env node++const {+ SUPPORTED_INSTALL_TARGETS,+ listInstallComponents,+ listInstallProfiles,+ loadInstallManifests,+} = require('./lib/install-manifests');++const DEFAULT_TARGET = 'claude';+const DEFAULT_LIMIT = 5;+const MAX_LIMIT = 20;+const SCHEMA_VERSION = 'ecc.consult.v1';++const STOP_WORDS = new Set([+ 'a',+ 'an',+ 'and',+ 'app',+ 'are',+ 'for',+ 'from',+ 'i',+ 'in',+ 'into',+ 'me',+ 'need',+ 'of',+ 'on',+ 'please',+ 'skill',+ 'skills',+ 'the',+ 'to',+ 'want',+ 'with',+]);++const COMPONENT_ALIASES = Object.freeze({+ 'capability:security': [+ 'appsec',+ 'auth',+ 'authorization',+ 'checklist',+ 'hardening',+ 'pentest',+ 'secret',+ 'secrets',+ 'threat',+ 'vulnerability',+ 'vulnerabilities',+ ],+ 'capability:database': ['db', 'migration', 'migrations', 'postgres', 'postgresql', 'schema', 'sql'],+ 'capability:research': ['api', 'apis', 'exa', 'external', 'investigation', 'search'],+ 'capability:content': ['article', 'brand', 'business', 'copy', 'linkedin', 'writing'],+ 'capability:operators': ['automation', 'billing', 'connected', 'ops', 'operator', 'workspace'],+ 'capability:social': ['distribution', 'post', 'posting', 'publish', 'publishing', 'twitter', 'x'],+ 'capability:media': ['editing', 'image', 'remotion', 'slides', 'video'],+ 'capability:orchestration': ['dmux', 'parallel', 'tmux', 'worktree', 'worktrees'],+ 'framework:nextjs': ['next', 'next.js', 'nextjs'],+ 'framework:react': ['react', 'tsx'],+ 'framework:django': ['django'],+ 'framework:springboot': ['spring', 'springboot'],+ 'lang:typescript': ['javascript', 'js', 'node', 'nodejs', 'ts'],+ 'lang:python': ['py'],+ 'lang:go': ['golang'],+});++const PROFILE_ALIASES = Object.freeze({+ minimal: ['low-context', 'lean', 'no-hooks', 'base', 'lightweight'],+ core: ['baseline', 'default', 'starter'],+ developer: ['app', 'code', 'coding', 'engineering', 'software'],+ security: ['appsec', 'audit', 'hardening', 'review', 'threat', 'vulnerability'],+ research: ['content', 'investigation', 'publishing', 'synthesis'],+ full: ['all', 'complete', 'everything'],+});++function showHelp(exitCode = 0) {+ console.log(`+Consult ECC install components and profiles from any project++Usage:+ node scripts/consult.js "security reviews" [--target <target>] [--limit <n>] [--json]+ node scripts/consult.js security reviews --target codex++Options:+ --target <target> Install target to include in suggested commands. Default: ${DEFAULT_TARGET}+ --limit <n> Maximum component recommendations to return. Default: ${DEFAULT_LIMIT}+ --json Emit machine-readable consultation JSON+ --help Show this help text++Examples:+ node scripts/consult.js "security reviews"+ node scripts/consult.js "Next.js React app" --target cursor+ node scripts/consult.js "operator workflows" --target codex --json+`);++ process.exit(exitCode);+}++function normalizeToken(value) {+ return String(value || '')+ .toLowerCase()+ .replace(/\.js\b/g, 'js')+ .replace(/[^a-z0-9:+-]+/g, ' ')+ .trim();+}++function expandToken(token) {+ const values = new Set([token]);++ if (token.endsWith('ies') && token.length > 4) {+ values.add(`${token.slice(0, -3)}y`);+ }+ if (token.endsWith('es') && token.length > 4 && !token.endsWith('js')) {+ values.add(token.slice(0, -2));+ }+ if (token.endsWith('s') && token.length > 4 && !token.endsWith('js')) {+ values.add(token.slice(0, -1));+ }+ if (token.endsWith('ing') && token.length > 6) {+ values.add(token.slice(0, -3));+ }++ return [...values].filter(Boolean);+}++function tokenize(value) {+ const normalized = normalizeToken(value);+ if (!normalized) {+ return [];+ }++ const tokens = [];+ for (const token of normalized.split(/\s+/)) {+ if (!token || STOP_WORDS.has(token)) {+ continue;+ }+ tokens.push(...expandToken(token));+ }+ return [...new Set(tokens)];+}++function parsePositiveInteger(value, label) {+ if (!/^[1-9]\d*$/.test(String(value || ''))) {+ throw new Error(`${label} must be a positive integer`);+ }+ return Number(value);+}++function parseArgs(argv) {+ const args = argv.slice(2);+ const parsed = {+ queryParts: [],+ target: DEFAULT_TARGET,+ limit: DEFAULT_LIMIT,+ json: false,+ help: false,+ };++ for (let index = 0; index < args.length; index += 1) {+ const arg = args[index];++ if (arg === '--help' || arg === '-h') {+ parsed.help = true;+ } else if (arg === '--json') {+ parsed.json = true;+ } else if (arg === '--target') {+ if (!args[index + 1]) {+ throw new Error('Missing value for --target');+ }+ parsed.target = args[index + 1];+ index += 1;+ } else if (arg === '--limit') {+ if (!args[index + 1]) {+ throw new Error('Missing value for --limit');+ }+ parsed.limit = Math.min(parsePositiveInteger(args[index + 1], '--limit'), MAX_LIMIT);+ index += 1;+ } else if (arg.startsWith('-')) {+ throw new Error(`Unknown argument: ${arg}`);+ } else {+ parsed.queryParts.push(arg);+ }+ }++ if (!SUPPORTED_INSTALL_TARGETS.includes(parsed.target)) {+ throw new Error(+ `Unknown install target: ${parsed.target}. Expected one of ${SUPPORTED_INSTALL_TARGETS.join(', ')}`+ );+ }++ parsed.query = parsed.queryParts.join(' ').trim();+ return parsed;+}++function commandFor(kind, id, target) {+ if (kind === 'profile') {+ return `npx ecc install --profile ${id} --target ${target}`;+ }++ return `npx ecc install --profile minimal --target ${target} --with ${id}`;+}++function planCommandFor(componentId, target) {+ return `npx ecc plan --profile minimal --target ${target} --with ${componentId}`;+}++function buildSearchCorpus(parts) {+ return tokenize(parts.filter(Boolean).join(' '));+}++function scoreAgainstQuery(queryTokens, corpusTokens, options = {}) {+ const corpus = new Set(corpusTokens);+ const reasons = [];+ let score = 0;++ queryTokens.forEach((token, index) => {+ if (corpus.has(token)) {+ score += index === 0 ? 5 : 4;+ reasons.push(`matched "${token}"`);+ return;+ }++ if (+ token.length >= 4+ && [...corpus].some(corpusToken => (+ corpusToken.length >= 4+ && (corpusToken.includes(token) || token.includes(corpusToken))+ ))+ ) {+ score += 1;+ reasons.push(`fuzzy matched "${token}"`);+ }+ });++ if (options.preferred && reasons.length > 0) {+ score += options.preferred;+ }++ return { score, reasons: [...new Set(reasons)] };+}++function preferredComponentBonus(component, queryTokens) {+ let bonus = 0;+ const suffix = component.id.split(':')[1];++ if (queryTokens[0] === suffix) {+ bonus += 5;+ }++ if (component.family === 'capability') {+ bonus += 3;+ }++ if (component.id === 'capability:security' && queryTokens.some(token => ['audit', 'review', 'security'].includes(token))) {+ bonus += 4;+ }++ return bonus;+}++function rankComponents({ queryTokens, target, limit }) {+ return listInstallComponents({ target })+ .map(component => {+ const aliases = COMPONENT_ALIASES[component.id] || [];+ const corpusTokens = buildSearchCorpus([+ component.id.replace(':', ' '),+ component.family,+ component.description,+ component.moduleIds.join(' '),+ aliases.join(' '),+ ]);+ const { score, reasons } = scoreAgainstQuery(queryTokens, corpusTokens, {+ preferred: preferredComponentBonus(component, queryTokens),+ });++ return {+ component,+ score,+ reasons,+ };+ })+ .filter(result => result.score > 0)+ .sort((left, right) => (+ right.score - left.score+ || left.component.family.localeCompare(right.component.family)+ || left.component.id.localeCompare(right.component.id)+ ))+ .slice(0, limit)+ .map(result => ({+ componentId: result.component.id,+ family: result.component.family,+ description: result.component.description,+ moduleIds: result.component.moduleIds,+ targets: result.component.targets,+ score: result.score,+ reasons: result.reasons.length > 0 ? result.reasons : ['related install component'],+ installCommand: commandFor('component', result.component.id, target),+ planCommand: planCommandFor(result.component.id, target),+ }));+}++function rankProfiles({ queryTokens, target, limit }) {+ const manifests = loadInstallManifests();+ return listInstallProfiles()+ .map(profile => {+ const profileDefinition = manifests.profiles[profile.id] || {};+ const aliases = PROFILE_ALIASES[profile.id] || [];+ const corpusTokens = buildSearchCorpus([+ profile.id,+ profile.description,+ (profileDefinition.modules || []).join(' '),+ aliases.join(' '),+ ]);+ const preferred = queryTokens.includes(profile.id) ? 4 : 0;+ const { score, reasons } = scoreAgainstQuery(queryTokens, corpusTokens, { preferred });++ return {+ profile,+ score,+ reasons,+ };+ })+ .filter(result => result.score > 0)+ .sort((left, right) => right.score - left.score || left.profile.id.localeCompare(right.profile.id))+ .slice(0, Math.min(3, limit))+ .map(result => ({+ id: result.profile.id,+ description: result.profile.description,+ moduleCount: result.profile.moduleCount,+ score: result.score,+ reasons: result.reasons.length > 0 ? result.reasons : ['related install profile'],+ installCommand: commandFor('profile', result.profile.id, target),+ }));+}++function buildConsultation(options) {+ const queryTokens = tokenize(options.query);+ if (queryTokens.length === 0) {+ throw new Error('Consult requires a natural language query, for example: security reviews');+ }++ const matches = rankComponents({+ queryTokens,+ target: options.target,+ limit: options.limit,+ });+ const profiles = rankProfiles({+ queryTokens,+ target: options.target,+ limit: options.limit,+ });++ return {+ schemaVersion: SCHEMA_VERSION,+ query: options.query,+ target: options.target,+ generatedAt: new Date().toISOString(),+ matches,+ profiles,+ nextSteps: matches.length > 0+ ? [+ `Preview the top component: ${matches[0].planCommand}`,+ `Install it: ${matches[0].installCommand}`,+ ]+ : [+ 'Run `npx ecc catalog components` to browse all components.',+ 'Try a more specific query such as "security review", "Next.js", or "operator workflows".',+ ],+ };+}++function formatText(payload) {+ const lines = [+ `ECC consult (${payload.generatedAt})`,+ `Query: ${payload.query}`,+ `Target: ${payload.target}`,+ '',+ ];++ if (payload.matches.length === 0) {+ lines.push('No strong component matches found.');+ lines.push('Try: npx ecc catalog components');+ } else {+ lines.push('Recommended components:');+ payload.matches.forEach((match, index) => {+ lines.push(`${index + 1}. ${match.componentId} [${match.family}]`);+ lines.push(` ${match.description}`);+ lines.push(` Install: ${match.installCommand}`);+ lines.push(` Preview: ${match.planCommand}`);+ lines.push(` Why: ${match.reasons.join('; ')}`);+ });+ }++ if (payload.profiles.length > 0) {+ lines.push('');+ lines.push('Related profiles:');+ payload.profiles.forEach(profile => {+ lines.push(`- ${profile.id}: ${profile.description}`);+ lines.push(` Install: ${profile.installCommand}`);+ });+ }++ lines.push('');+ lines.push('Next steps:');+ payload.nextSteps.forEach(step => lines.push(`- ${step}`));++ return `${lines.join('\n')}\n`;+}++function main() {+ try {+ const options = parseArgs(process.argv);++ if (options.help) {+ showHelp(0);+ }++ const payload = buildConsultation(options);+ if (options.json) {+ console.log(JSON.stringify(payload, null, 2));+ } else {+ process.stdout.write(formatText(payload));+ }+ } catch (error) {+ console.error(`Error: ${error.message}`);+ process.exit(1);+ }+}++if (require.main === module) {+ main();+}++module.exports = {+ buildConsultation,+ formatText,+ parseArgs,+ tokenize,+};diff --git a/scripts/ecc.js b/scripts/ecc.jsindex a7c745f48..18a8240de 100755--- a/scripts/ecc.js+++ b/scripts/ecc.js@@ -17,6 +17,10 @@ const COMMANDS = {script: 'catalog.js',description: 'Discover install profiles and component IDs',},+ consult: {+ script: 'consult.js',+ description: 'Recommend ECC components and profiles from a natural language query',+ },'install-plan': {script: 'install-plan.js',description: 'Alias for plan',@@ -63,6 +67,7 @@ const PRIMARY_COMMANDS = ['install','plan','catalog',+ 'consult','list-installed','doctor','repair',@@ -97,6 +102,7 @@ Examples:ecc catalog profilesecc catalog components --family languageecc catalog show framework:nextjs+ ecc consult "security reviews"ecc list-installed --jsonecc doctor --target cursorecc repair --dry-rundiff --git a/tests/scripts/consult.test.js b/tests/scripts/consult.test.jsnew file mode 100644index 000000000..3eea8c3a8--- /dev/null+++ b/tests/scripts/consult.test.js@@ -0,0 +1,115 @@+/**+ * Tests for scripts/consult.js+ */++const assert = require('assert');+const fs = require('fs');+const os = require('os');+const path = require('path');+const { spawnSync } = require('child_process');++const SCRIPT = path.join(__dirname, '..', '..', 'scripts', 'consult.js');++function run(args = [], options = {}) {+ return spawnSync(process.execPath, [SCRIPT, ...args], {+ cwd: options.cwd || process.cwd(),+ encoding: 'utf8',+ maxBuffer: 10 * 1024 * 1024,+ });+}++function parseJson(stdout) {+ return JSON.parse(stdout.trim());+}++function test(name, fn) {+ try {+ fn();+ console.log(` PASS ${name}`);+ return true;+ } catch (error) {+ console.log(` FAIL ${name}`);+ console.log(` Error: ${error.message}`);+ return false;+ }+}++function runTests() {+ console.log('\n=== Testing consult.js ===\n');++ let passed = 0;+ let failed = 0;++ if (test('shows help with an explicit help flag', () => {+ const result = run(['--help']);++ assert.strictEqual(result.status, 0, result.stderr);+ assert.match(result.stdout, /Consult ECC install components/);+ assert.match(result.stdout, /node scripts\/consult\.js "security reviews"/);+ })) passed++; else failed++;++ if (test('recommends security components and profile for a natural language query', () => {+ const result = run(['security', 'reviews', '--json']);++ assert.strictEqual(result.status, 0, result.stderr);+ const payload = parseJson(result.stdout);+ assert.strictEqual(payload.schemaVersion, 'ecc.consult.v1');+ assert.strictEqual(payload.query, 'security reviews');+ assert.strictEqual(payload.target, 'claude');+ assert.strictEqual(payload.matches[0].componentId, 'capability:security');+ assert.ok(payload.matches[0].reasons.some(reason => reason.includes('security')));+ assert.strictEqual(+ payload.matches[0].installCommand,+ 'npx ecc install --profile minimal --target claude --with capability:security'+ );+ assert.ok(payload.profiles.some(profile => profile.id === 'security'));+ assert.ok(payload.profiles.find(profile => profile.id === 'security').installCommand.includes('--profile security'));+ })) passed++; else failed++;++ if (test('prints text recommendations with install and plan commands', () => {+ const result = run(['I', 'want', 'a', 'skill', 'for', 'security', 'reviews']);++ assert.strictEqual(result.status, 0, result.stderr);+ assert.match(result.stdout, /ECC consult/);+ assert.match(result.stdout, /capability:security/);+ assert.match(result.stdout, /npx ecc install --profile minimal --target claude --with capability:security/);+ assert.match(result.stdout, /npx ecc plan --profile minimal --target claude --with capability:security/);+ })) passed++; else failed++;++ if (test('works from outside the ECC repository', () => {+ const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-consult-project-'));+ try {+ const result = run(['nextjs', 'react', '--json'], { cwd: projectDir });++ assert.strictEqual(result.status, 0, result.stderr);+ const payload = parseJson(result.stdout);+ assert.strictEqual(payload.matches[0].componentId, 'framework:nextjs');+ assert.ok(payload.matches.some(match => match.componentId === 'framework:react'));+ } finally {+ fs.rmSync(projectDir, { recursive: true, force: true });+ }+ })) passed++; else failed++;++ if (test('filters recommendations by target and limit', () => {+ const result = run(['operator', 'workflows', '--target', 'codex', '--limit', '1', '--json']);++ assert.strictEqual(result.status, 0, result.stderr);+ const payload = parseJson(result.stdout);+ assert.strictEqual(payload.target, 'codex');+ assert.strictEqual(payload.matches.length, 1);+ assert.ok(payload.matches[0].targets.includes('codex'));+ assert.ok(payload.matches[0].installCommand.includes('--target codex'));+ })) passed++; else failed++;++ if (test('rejects unknown targets', () => {+ const result = run(['security', '--target', 'not-a-target']);++ assert.strictEqual(result.status, 1);+ assert.match(result.stderr, /Unknown install target/);+ })) passed++; else failed++;++ console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);+ process.exit(failed > 0 ? 1 : 0);+}++runTests();diff --git a/tests/scripts/ecc.test.js b/tests/scripts/ecc.test.jsindex f64d12998..2691f83a0 100644--- a/tests/scripts/ecc.test.js+++ b/tests/scripts/ecc.test.js@@ -69,6 +69,7 @@ function main() {assert.match(result.stdout, /list-installed/);assert.match(result.stdout, /doctor/);assert.match(result.stdout, /auto-update/);+ assert.match(result.stdout, /consult/);assert.match(result.stdout, /loop-status/);}],['delegates explicit install command', () => {@@ -103,6 +104,13 @@ function main() {assert.strictEqual(payload.id, 'framework:nextjs');assert.deepStrictEqual(payload.moduleIds, ['framework-language']);}],+ ['delegates consult command', () => {+ const result = runCli(['consult', 'security', 'reviews', '--json']);+ assert.strictEqual(result.status, 0, result.stderr);+ const payload = parseJson(result.stdout);+ assert.strictEqual(payload.schemaVersion, 'ecc.consult.v1');+ assert.strictEqual(payload.matches[0].componentId, 'capability:security');+ }],['delegates lifecycle commands', () => {const homeDir = createTempDir('ecc-cli-home-');const projectRoot = createTempDir('ecc-cli-project-');@@ -188,6 +196,11 @@ function main() {assert.strictEqual(result.status, 0, result.stderr);assert.match(result.stdout, /node scripts\/catalog\.js show <component-id>/);}],+ ['supports help for the consult subcommand', () => {+ const result = runCli(['help', 'consult']);+ assert.strictEqual(result.status, 0, result.stderr);+ assert.match(result.stdout, /node scripts\/consult\.js "security reviews"/);+ }],['fails on unknown commands instead of treating them as installs', () => {const result = runCli(['bogus']);assert.strictEqual(result.status, 1);diff --git a/tests/scripts/install-readme-clarity.test.js b/tests/scripts/install-readme-clarity.test.jsindex 7affd11f9..3a0725dbe 100644--- a/tests/scripts/install-readme-clarity.test.js+++ b/tests/scripts/install-readme-clarity.test.js@@ -93,6 +93,21 @@ function runTests() {);})) passed++; else failed++;+ if (test('README documents consult-based component discovery', () => {+ assert.ok(+ readme.includes('### Find the right components first'),+ 'README should surface component discovery before install steps'+ );+ assert.ok(+ readme.includes('npx ecc consult "security reviews" --target claude'),+ 'README should document the packaged consult command'+ );+ assert.ok(+ readme.includes('It returns matching components, related profiles, and preview/install commands.'),+ 'README should explain what consult returns'+ );+ })) passed++; else failed++;+if (test('README documents Cursor agent namespace and loading caveat', () => {assert.ok(readme.includes('`.cursor/agents/ecc-*.md`'),diff --git a/tests/scripts/npm-publish-surface.test.js b/tests/scripts/npm-publish-surface.test.jsindex 530f6cf9c..ae1ed738c 100644--- a/tests/scripts/npm-publish-surface.test.js+++ b/tests/scripts/npm-publish-surface.test.js@@ -43,6 +43,7 @@ function buildExpectedPublishPaths(repoRoot) {"manifests","scripts/ecc.js","scripts/catalog.js",+ "scripts/consult.js","scripts/claw.js","scripts/doctor.js","scripts/status.js",@@ -108,6 +109,7 @@ function main() {for (const requiredPath of ["scripts/catalog.js",+ "scripts/consult.js",".gemini/GEMINI.md",".claude-plugin/plugin.json",".codex-plugin/plugin.json",