@tacuchi/agent-factory 0.1.0

package/LICENSE

@@ -0,0 +1,37 @@
+MIT License
+
+Copyright (c) 2026 tacuchi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Acknowledgments
+
+This project was inspired in part by claude-code-templates
+(https://github.com/davila7/claude-code-templates) by Daniel Ávila,
+licensed under the MIT License. Specifically, the following concepts were
+studied as reference:
+
+- Stack detection patterns (detectProject utility)
+- YAML frontmatter format for Claude Code agent definitions
+- CLI structure using commander + inquirer + chalk + ora
+
+All code in agent-factory is original work. No source code was copied
+from claude-code-templates.

package/README.md

@@ -0,0 +1,142 @@
+# 🏭 agent-factory
+
+CLI to create AI agents for **Claude Code**, **Codex**, **Gemini CLI** and more.
+
+Analyzes your repository's tech stack and generates role-based agents ready to use.
+
+## Install
+
+```bash
+npm install -g agent-factory
+```
+
+Or run directly:
+
+```bash
+npx agent-factory <command>
+```
+
+## Commands
+
+### `detect <path>`
+
+Detect the technology stack of a repository.
+
+```bash
+agent-factory detect ./my-project
+agent-factory detect ./my-project --json    # Pure JSON output
+```
+
+### `init <path>`
+
+Analyze a repository and generate suggested agents automatically.
+
+```bash
+agent-factory init ./my-project
+agent-factory init ./my-project -y                        # Skip confirmations
+agent-factory init ./my-project --output ./workspace -y   # Write agents elsewhere
+```
+
+### `create`
+
+Create a single agent interactively or with flags.
+
+```bash
+agent-factory create
+agent-factory create -n api-expert -r specialist -s ./my-project -y
+```
+
+### `list [path]`
+
+List existing agents in a directory.
+
+```bash
+agent-factory list
+agent-factory list ./my-project --json   # JSON output
+```
+
+## Global flags
+
+| Flag | Description |
+|------|-------------|
+| `-q, --quiet` | Suppress all visual output (banners, spinners, logs). Useful for programmatic/SKILL usage. |
+| `-V, --version` | Show version |
+| `-h, --help` | Show help |
+
+## Supported stacks
+
+**Languages & frameworks:** JavaScript/TypeScript (Angular, React, Vue, Next.js, Svelte, Nuxt, Node.js), Java (Spring Boot — Maven & Gradle), Kotlin, Python (Django, FastAPI, Flask), Go, Rust, Dart/Flutter, .NET, Ruby on Rails.
+
+**Supplementary:** Docker, SCSS, Tailwind CSS, Bootstrap, Angular Material.
+
+## Agent roles
+
+| Role | Purpose |
+|------|---------|
+| **specialist** | Deep knowledge of the detected stack, implements features and fixes |
+| **coordinator** | Orchestrates tasks across the project, manages cross-cutting concerns |
+| **reviewer** | Code review focused on quality, patterns and best practices |
+| **architect** | System design, architecture decisions and technical strategy |
+
+## Output
+
+Agents are written in dual format:
+
+- `.claude/agents/<name>.md` — YAML frontmatter format for Claude Code
+- `.agents/<name>.md` — Plain markdown, compatible with other AI tools
+
+## Programmatic usage (SKILL-friendly)
+
+Designed to be invoked by AI agents via SKILLs:
+
+```bash
+# Silent detection, JSON output
+agent-factory detect ./repo --json
+
+# Silent init, separate output directory
+agent-factory -q init ./repo --output ./workspace -y
+
+# List agents as JSON
+agent-factory list ./workspace --json
+```
+
+## Project structure
+
+```
+agent-factory/
+├── bin/agent-factory.js        # CLI entry point
+├── src/
+│   ├── commands/
+│   │   ├── detect.js           # Stack detection command
+│   │   ├── create.js           # Interactive agent creation
+│   │   ├── init.js             # Auto-suggest and generate agents
+│   │   └── list.js             # List and validate existing agents
+│   ├── core/
+│   │   ├── stack-detector.js   # Technology stack analysis
+│   │   ├── template-engine.js  # Template rendering with Handlebars-like syntax
+│   │   ├── agent-writer.js     # Writes agents to dual formats
+│   │   └── agent-validator.js  # Validates agent file structure
+│   └── utils/
+│       ├── logger.js           # Colored output, spinners, quiet mode
+│       └── prompts.js          # Inquirer prompt builders
+└── templates/
+    └── roles/                  # Agent role templates
+        ├── specialist.md.tmpl
+        ├── coordinator.md.tmpl
+        ├── reviewer.md.tmpl
+        └── architect.md.tmpl
+```
+
+## Inspiration & acknowledgments
+
+This project was built from scratch as an original work. The concept and architecture were inspired in part by [claude-code-templates](https://github.com/davila7/claude-code-templates) by Daniel Ávila, from which the following ideas were studied as reference:
+
+- Stack detection patterns
+- YAML frontmatter format for Claude Code agents
+- CLI tooling choices (commander, inquirer, chalk, ora)
+
+No source code was copied. All implementation is original.
+
+## License
+
+[MIT](LICENSE)

package/bin/agent-factory.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const { banner, setQuiet } = require('../src/utils/logger');
+const pkg = require('../package.json');
+
+program
+  .name('agent-factory')
+  .description('CLI to create AI agents for Claude Code, Codex, Gemini CLI and more')
+  .version(pkg.version)
+  .option('-q, --quiet', 'Suppress banner and visual output (for programmatic use)')
+  .hook('preAction', (thisCommand, actionCommand) => {
+    const globalOpts = thisCommand.opts();
+    const subOpts = actionCommand.opts();
+    if (globalOpts.quiet || subOpts.json) {
+      setQuiet(true);
+    } else {
+      banner(pkg.version);
+    }
+  });
+
+program
+  .command('detect <path>')
+  .description('Detect technology stack of a repository')
+  .option('-v, --verbose', 'Show detailed detection info')
+  .option('--json', 'Output as JSON (implies --quiet)')
+  .action(async (repoPath, options) => {
+    const { runDetect } = require('../src/commands/detect');
+    await runDetect(repoPath, options);
+  });
+
+program
+  .command('create')
+  .description('Create an AI agent (interactive or with flags)')
+  .option('-n, --name <name>', 'Agent name (kebab-case)')
+  .option('-r, --role <role>', 'Agent role: specialist, coordinator, reviewer, architect')
+  .option('-m, --model <model>', 'Model: opus, sonnet, haiku', 'sonnet')
+  .option('-s, --scope <path>', 'Repository path (for stack detection)')
+  .option('-o, --output <path>', 'Output directory (default: current dir)')
+  .option('-t, --target <target>', 'Target: claude, codex, all', 'all')
+  .option('--tools <tools>', 'Comma-separated tools: Read,Write,Edit,Bash')
+  .option('-y, --yes', 'Skip confirmations')
+  .action(async (options) => {
+    const { runCreate } = require('../src/commands/create');
+    await runCreate(options);
+  });
+
+program
+  .command('init <path>')
+  .description('Analyze repository and suggest agents')
+  .option('-o, --output <path>', 'Output directory (default: same as repo path)')
+  .option('-t, --target <target>', 'Target: claude, codex, all', 'all')
+  .option('-m, --model <model>', 'Model for generated agents', 'sonnet')
+  .option('-y, --yes', 'Skip confirmations')
+  .action(async (repoPath, options) => {
+    const { runInit } = require('../src/commands/init');
+    await runInit(repoPath, options);
+  });
+
+program
+  .command('list [path]')
+  .description('List existing agents in a directory')
+  .option('-v, --verbose', 'Show validation details')
+  .option('--json', 'Output as JSON (implies --quiet)')
+  .action(async (dirPath, options) => {
+    const { runList } = require('../src/commands/list');
+    await runList(dirPath || process.cwd(), options);
+  });
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,45 @@
+{
+"name": "@tacuchi/agent-factory",
+  "version": "0.1.0",
+  "description": "CLI to create AI agents for Claude Code, Codex, Gemini CLI and more",
+  "bin": {
+    "agent-factory": "bin/agent-factory.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "test": "node --test tests/",
+    "start": "node bin/agent-factory.js"
+  },
+  "keywords": [
+    "claude-code",
+    "agents",
+    "codex",
+    "gemini",
+    "ai",
+    "cli",
+    "agent-factory"
+  ],
+  "author": "tacuchi",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tacuchi/agent-factory"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^8.2.6",
+    "js-yaml": "^4.1.0",
+    "ora": "^5.4.1"
+  }
+}

package/src/commands/create.js

@@ -0,0 +1,99 @@
+const path = require('path');
+const { detect } = require('../core/stack-detector');
+const { renderFile } = require('../core/template-engine');
+const { writeAgent, buildDescription, TOOLS_BY_ROLE } = require('../core/agent-writer');
+const { AgentValidator } = require('../core/agent-validator');
+const { log, spinner } = require('../utils/logger');
+const { askCreateOptions, confirmGeneration } = require('../utils/prompts');
+
+async function runCreate(options = {}) {
+  const isInteractive = !options.name;
+  const config = isInteractive ? await askCreateOptions() : normalizeFlags(options);
+
+  const { name, role, model, scope, output, target, tools } = config;
+
+  const spin = spinner('Generating agent...').start();
+
+  let stackResult = { primaryTech: 'Generic', framework: '', verifyCommands: '', stackParts: [], stackCsv: 'Generic' };
+  if (scope) {
+    stackResult = await detect(scope);
+  }
+
+  const templateData = {
+    name,
+    primary_tech: stackResult.primaryTech,
+    framework: stackResult.framework,
+    scope: scope || '.',
+    stack_list: stackResult.stackParts.length > 0
+      ? stackResult.stackParts.map((p) => `- ${p}`).join('\n')
+      : `- ${stackResult.primaryTech}`,
+    verify_cmds: stackResult.verifyCommands || 'N/A',
+    stack_csv: stackResult.stackCsv,
+  };
+
+  const templateFile = `${role}.md.tmpl`;
+  let body;
+  try {
+    body = await renderFile(templateFile, templateData);
+  } catch {
+    spin.fail(`Template not found: ${templateFile}`);
+    process.exit(1);
+  }
+
+  spin.succeed('Agent generated');
+
+  const outputDir = output || process.cwd();
+  const targetDirs = [];
+  if (target === 'claude' || target === 'all') targetDirs.push('.claude/agents/');
+  if (target === 'codex' || target === 'all') targetDirs.push('.agents/');
+
+  if (!options.yes && isInteractive) {
+    const confirmed = await confirmGeneration(name, targetDirs);
+    if (!confirmed) {
+      log.warn('Cancelled');
+      return;
+    }
+  }
+
+  const resolvedTools = tools || TOOLS_BY_ROLE[role] || 'Read, Write, Edit, Bash';
+  const results = await writeAgent({
+    name,
+    role,
+    model,
+    tools: resolvedTools,
+    body,
+    outputDir,
+    target,
+  });
+
+  const validator = new AgentValidator();
+  if (results.claude) {
+    const fs = require('fs-extra');
+    const content = await fs.readFile(results.claude, 'utf8');
+    const validation = validator.validate(content, `${name}.md`);
+    if (validation.valid) {
+      log.success(`Claude: ${results.claude} (score: ${validation.score}/100)`);
+    } else {
+      log.warn(`Claude: ${results.claude} (score: ${validation.score}/100, ${validation.errorCount} errors)`);
+    }
+  }
+
+  if (results.codex) {
+    log.success(`Codex:  ${results.codex}`);
+  }
+}
+
+function normalizeFlags(options) {
+  return {
+    name: options.name,
+    role: options.role || 'specialist',
+    model: options.model || 'sonnet',
+    scope: options.scope ? path.resolve(options.scope) : '',
+    output: options.output ? path.resolve(options.output) : process.cwd(),
+    target: options.target || 'all',
+    tools: options.tools || '',
+    yes: options.yes || false,
+  };
+}
+
+module.exports = { runCreate };

package/src/commands/detect.js

@@ -0,0 +1,56 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { detect, deriveAlias } = require('../core/stack-detector');
+const { log, spinner, chalk } = require('../utils/logger');
+
+async function runDetect(repoPath, options = {}) {
+  const abs = path.resolve(repoPath);
+
+  if (!(await fs.pathExists(abs))) {
+    if (options.json) {
+      console.log(JSON.stringify({ error: `Path does not exist: ${abs}` }));
+      process.exit(1);
+    }
+    log.error(`Path does not exist: ${abs}`);
+    process.exit(1);
+  }
+
+  const spin = spinner('Detecting stack...').start();
+  const result = await detect(abs);
+  spin.succeed('Detection complete');
+
+  if (options.json) {
+    console.log(JSON.stringify({ alias: deriveAlias(abs), ...result }));
+    return result;
+  }
+
+  console.log('');
+  log.label('  Path', abs);
+  log.label('  Alias', deriveAlias(abs));
+  log.label('  Primary', result.primaryTech);
+
+  if (result.framework) {
+    log.label('  Framework', result.framework);
+  }
+
+  if (result.stackParts.length > 0) {
+    log.label('  Stack', result.stackCsv);
+  }
+
+  if (result.verifyCommands) {
+    log.label('  Verify', result.verifyCommands);
+  }
+
+  if (options.verbose && result.stackParts.length > 0) {
+    console.log('');
+    log.muted('  Stack parts:');
+    result.stackParts.forEach((part) => {
+      console.log(chalk.gray('    •'), part);
+    });
+  }
+
+  console.log('');
+  return result;
+}
+
+module.exports = { runDetect };

package/src/commands/init.js

@@ -0,0 +1,115 @@
+const path = require('path');
+const fs = require('fs-extra');
+const { detect, deriveAlias } = require('../core/stack-detector');
+const { renderFile } = require('../core/template-engine');
+const { writeAgent, TOOLS_BY_ROLE } = require('../core/agent-writer');
+const { AgentValidator } = require('../core/agent-validator');
+const { log, spinner, chalk } = require('../utils/logger');
+const { askInitAgents } = require('../utils/prompts');
+
+async function runInit(repoPath, options = {}) {
+  const abs = path.resolve(repoPath);
+
+  if (!(await fs.pathExists(abs))) {
+    log.error(`Path does not exist: ${abs}`);
+    process.exit(1);
+  }
+
+  const spin = spinner('Analyzing repository...').start();
+  const stackResult = await detect(abs);
+  const alias = deriveAlias(abs);
+  spin.succeed(`Detected: ${stackResult.primaryTech}${stackResult.framework ? ` / ${stackResult.framework}` : ''}`);
+
+  const suggestions = buildSuggestions(alias, stackResult, abs);
+
+  log.info(`Suggested agents for ${chalk.white(alias)}:`);
+  suggestions.forEach((s) => {
+    log.muted(`  • ${s.name} (${s.role}) — ${s.description}`);
+  });
+
+  let selected = suggestions;
+  if (!options.yes) {
+    selected = await askInitAgents(suggestions);
+    if (selected.length === 0) {
+      log.warn('No agents selected');
+      return;
+    }
+  }
+
+  const target = options.target || 'all';
+  const model = options.model || 'sonnet';
+  const outputDir = options.output ? path.resolve(options.output) : abs;
+  const validator = new AgentValidator();
+
+  for (const agent of selected) {
+    const templateData = {
+      name: agent.name,
+      primary_tech: stackResult.primaryTech,
+      framework: stackResult.framework,
+      scope: abs,
+      stack_list: stackResult.stackParts.length > 0
+        ? stackResult.stackParts.map((p) => `- ${p}`).join('\n')
+        : `- ${stackResult.primaryTech}`,
+      verify_cmds: stackResult.verifyCommands || 'N/A',
+      stack_csv: stackResult.stackCsv,
+    };
+
+    let body;
+    try {
+      body = await renderFile(`${agent.role}.md.tmpl`, templateData);
+    } catch {
+      log.warn(`Template not found for role: ${agent.role}, skipping`);
+      continue;
+    }
+
+    const results = await writeAgent({
+      name: agent.name,
+      role: agent.role,
+      model,
+      tools: TOOLS_BY_ROLE[agent.role],
+      body,
+      outputDir,
+      target,
+    });
+
+    if (results.claude) {
+      const content = await fs.readFile(results.claude, 'utf8');
+      const validation = validator.validate(content, `${agent.name}.md`);
+      log.success(`${agent.name} → .claude/agents/ (score: ${validation.score}/100)`);
+    }
+    if (results.codex) {
+      log.success(`${agent.name} → .agents/`);
+    }
+  }
+
+  log.success(`${selected.length} agent(s) generated in ${outputDir}`);
+}
+
+function buildSuggestions(alias, stackResult, repoPath) {
+  const suggestions = [];
+  const tech = stackResult.framework || stackResult.primaryTech;
+
+  suggestions.push({
+    name: `repo-${alias}`,
+    role: 'specialist',
+    description: `${tech} specialist for ${alias}`,
+  });
+
+  suggestions.push({
+    name: `${alias}-reviewer`,
+    role: 'reviewer',
+    description: `Code reviewer for ${tech}`,
+  });
+
+  if (stackResult.stackParts.length >= 3) {
+    suggestions.push({
+      name: `${alias}-architect`,
+      role: 'architect',
+      description: `Architecture advisor for ${tech}`,
+    });
+  }
+
+  return suggestions;
+}
+
+module.exports = { runInit };

package/src/commands/list.js

@@ -0,0 +1,117 @@
+const path = require('path');
+const fs = require('fs-extra');
+const yaml = require('js-yaml');
+const { AgentValidator } = require('../core/agent-validator');
+const { log, chalk } = require('../utils/logger');
+
+async function runList(dirPath, options = {}) {
+  const abs = path.resolve(dirPath);
+  const agents = [];
+
+  const claudeDir = path.join(abs, '.claude', 'agents');
+  const codexDir = path.join(abs, '.agents');
+
+  if (await fs.pathExists(claudeDir)) {
+    const files = (await fs.readdir(claudeDir)).filter((f) => f.endsWith('.md'));
+    for (const file of files) {
+      const content = await fs.readFile(path.join(claudeDir, file), 'utf8');
+      agents.push({ file, source: '.claude/agents', content, format: 'claude' });
+    }
+  }
+
+  if (await fs.pathExists(codexDir)) {
+    const files = (await fs.readdir(codexDir)).filter((f) => f.endsWith('.md'));
+    for (const file of files) {
+      const existing = agents.find((a) => a.file === file);
+      if (existing) {
+        existing.codexToo = true;
+        continue;
+      }
+      const content = await fs.readFile(path.join(codexDir, file), 'utf8');
+      agents.push({ file, source: '.agents', content, format: 'codex' });
+    }
+  }
+
+  if (agents.length === 0) {
+    if (options.json) {
+      console.log(JSON.stringify([]));
+      return;
+    }
+    log.warn(`No agents found in ${abs}`);
+    log.muted('  Run "agent-factory init <path>" or "agent-factory create" to generate agents.');
+    return;
+  }
+
+  const validator = new AgentValidator();
+
+  if (options.json) {
+    const jsonResult = agents.map((agent) => {
+      const fm = extractFrontmatter(agent.content);
+      const validation = validator.validate(agent.content, agent.file);
+      return {
+        name: fm?.name || agent.file.replace('.md', ''),
+        model: fm?.model || null,
+        source: agent.codexToo ? 'both' : agent.source,
+        score: validation.score,
+        valid: validation.valid,
+      };
+    });
+    console.log(JSON.stringify(jsonResult));
+    return;
+  }
+
+  console.log('');
+  log.info(`${agents.length} agent(s) found in ${chalk.white(abs)}`);
+  console.log('');
+
+  const header = padRow('Name', 'Model', 'Source', 'Score');
+  console.log(chalk.gray(header));
+  console.log(chalk.gray('─'.repeat(header.length)));
+
+  for (const agent of agents) {
+    const fm = extractFrontmatter(agent.content);
+    const name = fm?.name || agent.file.replace('.md', '');
+    const model = fm?.model || '—';
+    const source = agent.codexToo ? 'both' : agent.source;
+
+    const validation = validator.validate(agent.content, agent.file);
+    const scoreStr = `${validation.score}/100`;
+    const scoreColor = validation.score >= 90 ? '#10B981' : validation.score >= 70 ? '#F59E0B' : '#EF4444';
+
+    console.log(
+      padRow(
+        chalk.white(name),
+        chalk.gray(model),
+        chalk.gray(source),
+        chalk.hex(scoreColor)(scoreStr)
+      )
+    );
+
+    if (options.verbose) {
+      if (validation.errorCount > 0) {
+        validation.errors.forEach((e) => console.log(chalk.red(`    ✗ ${e.message}`)));
+      }
+      if (validation.warningCount > 0) {
+        validation.warnings.forEach((w) => console.log(chalk.yellow(`    ⚠ ${w.message}`)));
+      }
+    }
+  }
+
+  console.log('');
+}
+
+function padRow(name, model, source, score) {
+  return `  ${name.padEnd(30)} ${model.padEnd(10)} ${source.padEnd(18)} ${score}`;
+}
+
+function extractFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  try {
+    return yaml.load(match[1]);
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { runList };