@grantx/fleet-cli 0.1.4 → 0.1.6

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@grantx/fleet-cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "type": "module",
   "files": ["src/", "bin/"],
   "bin": {
     "fleet": "./bin/fleet"
   },
   "dependencies": {
-    "@grantx/fleet-core": "0.1.3"
+    "@grantx/fleet-core": "0.1.5"
   },
   "engines": {
     "node": ">=22.0.0"

package/src/agent-templates.js

@@ -0,0 +1,354 @@
+// agent-templates.js — Rich CLAUDE.md generation for fleet agents.
+// Produces 80-120 line agent files matching the Clawcob quality bar.
+// Each agent gets: identity, core principle, FROZEN decisions, domain,
+// NOT-domain, gotchas, quality standards, tools, and constraints.
+
+/**
+ * Generate a rich CLAUDE.md for a worker agent.
+ * @param {object} agent - Full agent definition from the wizard
+ * @param {object} config - Fleet config (for roster, team type, repos)
+ * @returns {string} Markdown content
+ */
+export function generateRichAgentClaudeMd(agent, config) {
+  const lines = [];
+  const titleFromRole = agent.role.split('—')[0]?.trim() || agent.role.split('-')[0]?.trim() || agent.role;
+
+  // Header + identity
+  lines.push(`# ${agent.name} — ${titleFromRole}`);
+  lines.push('');
+  if (agent.identity) {
+    lines.push(agent.identity);
+  } else {
+    lines.push(`You are ${agent.name}, a fleet agent specializing in: ${agent.role}.`);
+  }
+  lines.push('');
+
+  // Core principle
+  if (agent.principles?.length > 0) {
+    lines.push('## Core Principle');
+    lines.push(agent.principles[0]);
+    lines.push('');
+  }
+
+  // FROZEN decisions
+  if (agent.frozenDecisions?.length > 0) {
+    lines.push('## FROZEN Decisions (DO NOT CHANGE)');
+    agent.frozenDecisions.forEach((d, i) => {
+      lines.push(`${i + 1}. ${d}`);
+    });
+    lines.push('');
+  }
+
+  // Domain
+  if (agent.domains?.length > 0) {
+    lines.push('## Domain');
+    agent.domains.forEach(d => lines.push(`- ${d}`));
+    lines.push('');
+  }
+
+  // NOT domain
+  if (agent.offLimits?.length > 0) {
+    lines.push('## NOT Your Domain');
+    agent.offLimits.forEach(d => {
+      // Try to identify which agent owns this area
+      const owner = findDomainOwner(d, config.agents, agent.name);
+      lines.push(owner ? `- ${d} (${owner}'s domain)` : `- ${d}`);
+    });
+    lines.push('');
+  }
+
+  // Known gotchas
+  if (agent.gotchas?.length > 0) {
+    lines.push('## Known Gotchas');
+    agent.gotchas.forEach(g => lines.push(`- ${g}`));
+    lines.push('');
+  }
+
+  // Quality standards (user-provided + team-type defaults)
+  const standards = [
+    ...(agent.qualityStandards || []),
+    ...teamQualityStandards(config.teamType, agent),
+  ];
+  if (standards.length > 0) {
+    lines.push('## Quality Standard');
+    // Deduplicate
+    const seen = new Set();
+    standards.forEach(s => {
+      const key = s.toLowerCase();
+      if (!seen.has(key)) {
+        seen.add(key);
+        lines.push(`- ${s}`);
+      }
+    });
+    lines.push('');
+  }
+
+  // Owned file patterns
+  if (agent.filePatterns?.length > 0) {
+    lines.push('## Owned File Patterns');
+    agent.filePatterns.forEach(p => lines.push(`- \`${p}\``));
+    lines.push('');
+  }
+
+  // Specialty keywords
+  if (agent.keywords?.length > 0) {
+    lines.push('## Specialty Keywords');
+    lines.push(agent.keywords.join(', '));
+    lines.push('');
+  }
+
+  // Additional principles (beyond the first/core one)
+  if (agent.principles?.length > 1) {
+    lines.push('## Working Principles');
+    agent.principles.slice(1).forEach(p => lines.push(`- ${p}`));
+    lines.push('');
+  }
+
+  // Tools section
+  lines.push('## Tools');
+  lines.push('');
+  lines.push('### Knowledge Store (grantx-kb)');
+  lines.push(`  export FLEET_AGENT_ID=${agent.name}`);
+  lines.push('');
+  lines.push(`  grantx-kb task list --to ${agent.name} --status pending`);
+  lines.push('  grantx-kb task claim <uuid>');
+  lines.push('  grantx-kb task start <uuid>');
+  lines.push('  grantx-kb task complete <uuid> --result "..."');
+  lines.push('');
+  lines.push('  grantx-kb knowledge search --query "<keywords>"');
+  lines.push('  grantx-kb knowledge add --category lesson --title "..." --content "..."');
+  lines.push('');
+
+  // Code repository section
+  if (config.repos?.length > 0) {
+    lines.push('### Code Repositories');
+    config.repos.forEach(r => {
+      if (r.path) {
+        lines.push(`  ${r.slug} → ${r.path}`);
+      } else {
+        lines.push(`  ${r.slug}`);
+      }
+    });
+    lines.push('');
+  }
+  lines.push('### Git Workflow');
+  lines.push(`  Work in branches: feat/${agent.name}/<description>`);
+  lines.push('  Create PRs via: gh pr create --title "..." --body "..."');
+  lines.push('');
+
+  // Constraints
+  lines.push('### What You Cannot Do');
+  const constraints = generateConstraints(agent, config.agents);
+  constraints.forEach(c => lines.push(`- ${c}`));
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate a rich CLAUDE.md for the conductor agent.
+ * @param {object} conductorInput - Conductor soul inputs from wizard
+ * @param {Array} roster - All agents (including conductor)
+ * @param {object} config - Fleet config
+ * @returns {string} Markdown content
+ */
+export function generateConductorClaudeMd(conductorInput, roster, config) {
+  const lines = [];
+  const workers = roster.filter(a => !a.isConductor);
+
+  // Header + identity
+  lines.push('# Conductor — Fleet Orchestrator');
+  lines.push('');
+  lines.push('You are a dispatcher, not a doer. You never write code. You never make product decisions. You read the state of the world, decide what needs to happen next, and tell the right agent to do it. Your value is in sequencing, unblocking, and synthesis — seeing connections across domains that individual agents miss.');
+  lines.push('');
+
+  // Core principle from philosophy
+  if (conductorInput.philosophy) {
+    lines.push('## Core Principle');
+    lines.push(`You are the only entity with visibility across all ${workers.length} agent workspaces. The fleet values: ${conductorInput.philosophy}.`);
+    lines.push('');
+  }
+
+  // What you do
+  lines.push('## What You Do');
+  lines.push('1. Check the task queue for stalled tasks. Reassign if blocked > 2 hours.');
+  lines.push('2. Check all agent heartbeats. Flag agents with no heartbeat or error status.');
+  lines.push(`3. Read all ${workers.length} agent workspaces. Synthesize cross-domain insights.`);
+  lines.push('4. Create tasks that connect discoveries across agents.');
+  lines.push('5. Generate sprint status reports.');
+  lines.push('6. Flag blockers to human when you cannot resolve them.');
+  lines.push('');
+
+  // What you never do
+  lines.push('## What You NEVER Do');
+  lines.push('- Write application code (that\'s what the workers are for)');
+  lines.push('- Deploy to production');
+  lines.push('- Approve PRs');
+  lines.push('- Make product decisions');
+  lines.push('- Modify your own CLAUDE.md');
+  lines.push('');
+
+  // Fleet roster table
+  lines.push('## Fleet Roster');
+  lines.push('');
+  lines.push('| Agent | Domain |');
+  lines.push('|-------|--------|');
+  lines.push('| Conductor (you) | Orchestration |');
+  workers.forEach(a => {
+    const domain = a.domains?.join(', ') || a.role;
+    lines.push(`| ${a.name} | ${domain} |`);
+  });
+  lines.push('');
+
+  // Decision framework
+  lines.push('## Decision Framework');
+  lines.push('1. Is this ticket blocked? Identify the blocker, create unblock task for the right agent.');
+
+  // Build routing rules from roster
+  const routingRules = workers.map(a => {
+    const domains = a.domains?.slice(0, 2).join('/') || a.role.split(',')[0].trim();
+    return `${domains} = ${a.name}`;
+  });
+  lines.push(`2. Is this the right agent? ${routingRules.join('. ')}.`);
+  lines.push('3. Is this urgent? Priority 1-3 = assign immediately. 4-7 = queue. 8-10 = background.');
+  lines.push('4. Cross-agent dependencies? Create tasks for both agents with clear sequencing.');
+  lines.push('');
+
+  // Escalation rules
+  if (conductorInput.escalation) {
+    lines.push('## Escalation Rules');
+    lines.push(conductorInput.escalation);
+    lines.push('');
+  }
+
+  // Sprint management
+  if (conductorInput.sprintStyle) {
+    lines.push('## Sprint Management');
+    lines.push(conductorInput.sprintStyle);
+    lines.push('');
+  }
+
+  // Custom rules
+  if (conductorInput.customRules?.length > 0) {
+    lines.push('## Additional Rules');
+    conductorInput.customRules.forEach(r => lines.push(`- ${r}`));
+    lines.push('');
+  }
+
+  // FROZEN decisions (union of all agents')
+  const allFrozen = [];
+  workers.forEach(a => {
+    if (a.frozenDecisions?.length > 0) {
+      allFrozen.push(...a.frozenDecisions);
+    }
+  });
+  if (allFrozen.length > 0) {
+    lines.push('## FROZEN Decisions (Fleet-wide)');
+    allFrozen.forEach((d, i) => lines.push(`${i + 1}. ${d}`));
+    lines.push('');
+  }
+
+  // Tools
+  lines.push('## Tools');
+  lines.push('');
+  lines.push('### grantx-kb (Knowledge Store CLI)');
+  lines.push('  export FLEET_AGENT_ID=conductor');
+  lines.push('');
+  lines.push('Check task queue:');
+  lines.push('  grantx-kb task list --status pending');
+  lines.push('  grantx-kb task list --status in_progress');
+  lines.push('  grantx-kb task list --status blocked');
+  lines.push('');
+  lines.push('Assign work:');
+  lines.push('  grantx-kb task create --to <agent> --title "..." --description "..." --priority <1-10>');
+  lines.push('');
+  lines.push('Check agent health:');
+  lines.push('  grantx-kb heartbeat check --since 30');
+  lines.push('');
+  lines.push('Read knowledge:');
+  lines.push('  grantx-kb knowledge search --query "<keywords>"');
+  lines.push('');
+
+  // Constraints
+  lines.push('### Constraints');
+  lines.push('- You can only reach: Supabase (knowledge store), GitHub (read-only), and fleet agents.');
+  lines.push('- Every action you take is logged to the audit trail.');
+  lines.push('- You cannot access email, CRM, messaging, or the web.');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// ── Helpers ───────────────────────────────────────────────────────
+
+/**
+ * Find which agent in the roster owns a given domain area.
+ */
+function findDomainOwner(area, agents, excludeName) {
+  const areaLower = area.toLowerCase();
+  for (const agent of agents || []) {
+    if (agent.name === excludeName || agent.isConductor) continue;
+    const domains = (agent.domains || []).map(d => d.toLowerCase());
+    const role = (agent.role || '').toLowerCase();
+    if (domains.some(d => areaLower.includes(d) || d.includes(areaLower))) {
+      return agent.name;
+    }
+    if (role.includes(areaLower)) {
+      return agent.name;
+    }
+  }
+  return null;
+}
+
+/**
+ * Generate team-type-specific quality standards.
+ */
+function teamQualityStandards(teamType, agent) {
+  const standards = {
+    ml: [
+      'Never ship a model without evaluation on holdout set',
+      'Always compare to production baseline before promoting',
+      'Every experiment logged with full hyperparameters',
+    ],
+    data: [
+      'All pipelines must be idempotent',
+      'Schema changes require migration scripts',
+      'Monitor before shipping — dashboards first, code second',
+    ],
+    fullstack: [
+      'Test coverage for new code',
+      'API changes require contract documentation',
+      'Responsive design — test at mobile and desktop breakpoints',
+    ],
+    skunkworks: [
+      'Every experiment has a hypothesis and success criteria',
+      'Results captured in knowledge store immediately',
+      'Reproducibility: document environment, data version, and steps',
+    ],
+  };
+  return standards[teamType] || [];
+}
+
+/**
+ * Generate agent-specific constraints based on roster composition.
+ */
+function generateConstraints(agent, allAgents) {
+  const constraints = [
+    'Do not modify files outside your owned patterns unless necessary',
+    'Do not send messages to humans directly (Slack is conductor\'s domain)',
+  ];
+
+  // Check for specialized agents and add their exclusive privileges
+  for (const other of allAgents || []) {
+    if (other.name === agent.name || other.isConductor) continue;
+    const roleLower = (other.role || '').toLowerCase();
+    if (roleLower.includes('deploy') || roleLower.includes('mlops')) {
+      constraints.push(`Do not deploy to production (${other.name}'s exclusive privilege)`);
+    }
+    if (roleLower.includes('review') || roleLower.includes('qa') || roleLower.includes('audit')) {
+      constraints.push(`Do not approve PRs (${other.name}'s exclusive privilege)`);
+    }
+  }
+
+  return constraints;
+}

package/src/agent-wizard.js

@@ -0,0 +1,228 @@
+// agent-wizard.js — Interactive agent builder for fleet setup.
+// Walks users through defining each agent's identity, domain, principles,
+// FROZEN decisions, gotchas, and quality standards. Produces agents at
+// the Clawcob quality bar.
+
+import { ask, askRequired, askYesNo, askCommaSeparated, askMultiline, askList, printHeader } from './prompt-utils.js';
+import { scanCodebase, generateRoster } from './generate.js';
+
+/**
+ * Run the full agent builder wizard.
+ * @param {readline.Interface} rl
+ * @param {string} projectRoot
+ * @param {string} teamType - 'ml' | 'data' | 'fullstack' | 'skunkworks'
+ * @param {Array} repos - Linked GitHub repos with scan results
+ * @returns {Promise<{workers: Array, conductorInput: object}>}
+ */
+export async function runAgentWizard(rl, projectRoot, teamType, repos) {
+  printHeader('Agent Builder');
+
+  // Run codebase scan as suggestion engine
+  const scanResult = scanCodebase(projectRoot);
+  const suggestions = generateRoster(scanResult);
+  const suggestedWorkers = suggestions.filter(a => !a.isConductor);
+
+  let workers;
+
+  if (suggestedWorkers.length > 0) {
+    console.log(`  Codebase suggests: ${suggestedWorkers.map(a => a.name).join(', ')}`);
+    const useSuggestions = await askYesNo(rl, 'Use suggestions as starting point?', true);
+
+    if (useSuggestions) {
+      workers = await buildFromSuggestions(rl, suggestedWorkers, teamType);
+    } else {
+      workers = await buildFromScratch(rl, teamType);
+    }
+  } else {
+    console.log('  No specific specialties detected in codebase.');
+    workers = await buildFromScratch(rl, teamType);
+  }
+
+  // Conductor soul
+  const conductorInput = await promptConductorSoul(rl, workers, teamType);
+
+  return { workers, conductorInput };
+}
+
+/**
+ * Build agents from scan suggestions — pre-fills name/role/keywords/patterns,
+ * then asks the DEEP questions for each.
+ */
+async function buildFromSuggestions(rl, suggestions, teamType) {
+  console.log(`\n  Refining ${suggestions.length} suggested agent(s)...`);
+  console.log('  You can skip an agent by entering "skip" for the name.\n');
+
+  const workers = [];
+  for (let i = 0; i < suggestions.length; i++) {
+    const s = suggestions[i];
+    console.log(`  --- Agent ${i + 1} of ${suggestions.length} (suggested: ${s.name}) ---\n`);
+
+    const name = await ask(rl, 'Name', s.name);
+    if (name === 'skip') {
+      console.log('  Skipped.\n');
+      continue;
+    }
+
+    const agent = await promptAgentDetails(rl, name, s.role, s.keywords, s.filePatterns, teamType);
+    workers.push(agent);
+    console.log(`  ✓ ${agent.name} defined\n`);
+  }
+
+  // Offer to add more
+  const addMore = await askYesNo(rl, 'Add more agents beyond suggestions?', false);
+  if (addMore) {
+    const extras = await buildFromScratch(rl, teamType);
+    workers.push(...extras);
+  }
+
+  return workers;
+}
+
+/**
+ * Build agents from scratch — user defines everything.
+ */
+async function buildFromScratch(rl, teamType) {
+  const countStr = await ask(rl, 'How many worker agents? (1-10)', '3');
+  const count = Math.max(1, Math.min(10, parseInt(countStr, 10) || 3));
+  console.log('');
+
+  const workers = [];
+  for (let i = 0; i < count; i++) {
+    console.log(`  --- Agent ${i + 1} of ${count} ---\n`);
+
+    const name = await askRequired(rl, 'Name (short, lowercase)');
+    const agent = await promptAgentDetails(rl, name, '', [], [], teamType);
+    workers.push(agent);
+    console.log(`  ✓ ${agent.name} defined\n`);
+  }
+
+  return workers;
+}
+
+/**
+ * Prompt for all the deep details of a single agent.
+ */
+async function promptAgentDetails(rl, name, defaultRole, defaultKeywords, defaultPatterns, teamType) {
+  const role = await askRequired(rl, `Role (one-line)${defaultRole ? ` [${defaultRole}]` : ''}`);
+  const finalRole = role || defaultRole;
+
+  const identity = await ask(rl, 'Identity (first person, 1-2 sentences — who is this agent?)');
+
+  const domains = await askCommaSeparated(rl, 'Domain (comma-separated areas this agent owns)');
+
+  const patternsDefault = defaultPatterns?.length > 0 ? defaultPatterns.join(', ') : '';
+  const patternsStr = await ask(rl, `File patterns (globs)${patternsDefault ? ` [${patternsDefault}]` : ''}`);
+  const filePatterns = patternsStr
+    ? patternsStr.split(',').map(s => s.trim()).filter(Boolean)
+    : defaultPatterns || [];
+
+  const offLimits = await askCommaSeparated(rl, 'NOT domain (what this agent must never touch)');
+
+  const principles = await askCommaSeparated(rl, 'Core principles (comma-separated)');
+
+  const frozenDecisions = await askMultiline(rl, 'FROZEN decisions (one per line)');
+
+  const gotchas = await askMultiline(rl, 'Known gotchas (one per line)');
+
+  const qualityStandards = await askMultiline(rl, 'Quality standards (one per line)');
+
+  // Derive keywords from domain + role + defaults
+  const keywords = deriveKeywords(finalRole, domains, defaultKeywords);
+
+  return {
+    name: name.toLowerCase().replace(/[^a-z0-9-]/g, '-'),
+    role: finalRole,
+    identity: identity || null,
+    domains,
+    keywords,
+    filePatterns,
+    offLimits,
+    principles,
+    frozenDecisions,
+    gotchas,
+    qualityStandards,
+    isConductor: false,
+  };
+}
+
+/**
+ * Prompt for the conductor soul.
+ */
+async function promptConductorSoul(rl, workers, teamType) {
+  printHeader('Conductor Soul');
+  console.log('  The conductor orchestrates your fleet — it dispatches, sequences, and synthesizes.\n');
+
+  const philosophy = await askRequired(rl, 'Fleet philosophy (what does your team value?)');
+
+  const escalation = await ask(rl,
+    'Escalation rules — when should conductor ask a human vs auto-dispatch?'
+  );
+
+  const sprintStyle = await ask(rl, 'Sprint style (e.g. weekly sprints, daily check-ins)');
+
+  const customRules = await askMultiline(rl, 'Additional conductor rules (one per line)');
+
+  return {
+    philosophy,
+    escalation: escalation || 'Escalate product decisions and security concerns. Auto-dispatch routine development tasks.',
+    sprintStyle: sprintStyle || 'Weekly sprints. Flag at-risk at 50% elapsed / <30% done.',
+    customRules,
+  };
+}
+
+// ── Helpers ───────────────────────────────────────────────────────
+
+/**
+ * Derive dispatch keywords from role text and domains.
+ * Expands known terms to synonyms for better SmartDispatcher matching.
+ */
+function deriveKeywords(role, domains, existingKeywords) {
+  const keywords = new Set(existingKeywords || []);
+
+  // Tokenize role
+  const roleTokens = role.toLowerCase().replace(/[^a-z0-9\s-]/g, '').split(/\s+/);
+  roleTokens.forEach(t => {
+    if (t.length > 2 && !STOP_WORDS.has(t)) keywords.add(t);
+  });
+
+  // Add domains directly
+  domains.forEach(d => {
+    d.toLowerCase().split(/\s+/).forEach(t => {
+      if (t.length > 2 && !STOP_WORDS.has(t)) keywords.add(t);
+    });
+  });
+
+  // Expand known terms
+  for (const kw of [...keywords]) {
+    const expansions = KEYWORD_EXPANSIONS[kw];
+    if (expansions) {
+      expansions.forEach(e => keywords.add(e));
+    }
+  }
+
+  return [...keywords];
+}
+
+const STOP_WORDS = new Set([
+  'the', 'and', 'for', 'with', 'from', 'that', 'this', 'are', 'was',
+  'has', 'have', 'been', 'will', 'can', 'all', 'not', 'but', 'also',
+]);
+
+const KEYWORD_EXPANSIONS = {
+  ranking: ['rank', 'ndcg', 'lgbm', 'lightgbm', 'model'],
+  'machine': ['ml', 'model', 'training'],
+  training: ['train', 'model', 'eval'],
+  frontend: ['ui', 'component', 'page', 'css', 'layout'],
+  backend: ['api', 'endpoint', 'route', 'server'],
+  api: ['endpoint', 'route', 'handler', 'middleware'],
+  database: ['db', 'query', 'migration', 'schema', 'sql'],
+  pipeline: ['etl', 'data', 'pipeline', 'ingestion'],
+  deploy: ['deployment', 'release', 'rollout', 'ci', 'cd'],
+  testing: ['test', 'qa', 'coverage', 'lint', 'review'],
+  docker: ['container', 'dockerfile', 'compose'],
+  kubernetes: ['k8s', 'helm', 'pod', 'deployment'],
+  prompt: ['llm', 'claude', 'gpt', 'eval', 'nlp'],
+  embedding: ['vector', 'retrieval', 'similarity', 'search'],
+  feature: ['features', 'parity', 'drift', 'lineage'],
+  experiment: ['hypothesis', 'research', 'ablation', 'eval'],
+};