agent-proteus 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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.

package/README.md

@@ -0,0 +1,188 @@
+# 🔱 Proteus
+
+> Shape-shifting project intelligence for Claude Code
+
+Proteus analyzes your project and generates **project-specific agents** — specialized AI assistants that understand your codebase's language, framework, conventions, and rules.
+
+## Why Proteus?
+
+Claude Code works best with context. But generic agents don't know your project's:
+- Coding conventions and style
+- Directory structure
+- Testing patterns
+- Project-specific rules
+
+**Proteus transforms into your project**, creating personalized agents that already understand everything.
+
+## Installation
+
+```bash
+# Run directly with npx
+npx agent-proteus
+
+# Or install globally
+npm install -g agent-proteus
+```
+
+## Quick Start
+
+```bash
+# In your project directory
+proteus
+
+# Preview without saving
+proteus --dry-run
+
+# Specify output language
+proteus --lang ja
+```
+
+Proteus will:
+1. Analyze your project structure
+2. Read existing CLAUDE.md (if present) for rules
+3. Suggest project-specific agents using Claude Code
+4. Generate selected agents to `.claude/agents/`
+5. Optionally generate `/proteus` skill for easy routing
+
+## Generated Structure
+
+```
+.claude/
+├── agents/                    # Project-specific agents
+│   ├── rails-graphql-type-generator.md
+│   ├── rspec-request-spec-writer.md
+│   └── ...
+└── skills/
+    └── proteus/
+        └── SKILL.md           # Router skill for agents
+```
+
+## Commands
+
+```bash
+# Default: Analyze and generate agents
+proteus
+
+# Generate CLAUDE.md only
+proteus init
+
+# Update agent list in CLAUDE.md or agents.md
+proteus registry
+
+# Just analyze (no generation)
+proteus analyze
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <dir>` | Output directory (default: `.claude/agents`) |
+| `-l, --lang <code>` | Output language (en, ja, zh, ko, es, fr, de) |
+| `-d, --dry-run` | Preview without saving |
+| `-f, --force` | Skip confirmations |
+| `--include-claude-md` | Also generate CLAUDE.md if not exists |
+
+## How It Works
+
+```
+┌─────────────────────────────────────┐
+│  1. Analyze Project                 │
+│  - Language, framework, tools       │
+│  - Directory structure              │
+│  - Naming conventions               │
+└─────────────────────────────────────┘
+                ↓
+┌─────────────────────────────────────┐
+│  2. Read Existing Documents         │
+│  - CLAUDE.md (rules, conventions)   │
+│  - README.md (description)          │
+│  - Existing agents (avoids dupes)   │
+└─────────────────────────────────────┘
+                ↓
+┌─────────────────────────────────────┐
+│  3. Suggest Agents (via Claude)     │
+│  - Dynamic based on your stack      │
+│  - Considers existing coverage      │
+│  - Project-specific naming          │
+└─────────────────────────────────────┘
+                ↓
+┌─────────────────────────────────────┐
+│  4. Generate & Save                 │
+│  - Personalized agent definitions   │
+│  - /proteus skill for routing       │
+│  - Registry in CLAUDE.md            │
+└─────────────────────────────────────┘
+```
+
+## Smart Agent Suggestions
+
+Proteus adjusts suggestions based on existing coverage:
+
+| Existing Agents | Max Suggestions |
+|-----------------|-----------------|
+| 0 | 5 agents |
+| 1-2 | 3 agents |
+| 3-4 | 2 agents |
+| 5+ | 0-1 agents (if gaps exist) |
+
+## Supported Languages & Frameworks
+
+| Language | Frameworks |
+|----------|------------|
+| TypeScript/JavaScript | Next.js, React, Vue, Angular, Svelte, Express, Fastify, NestJS |
+| Go | Gin, Echo, Fiber |
+| Python | Django, Flask, FastAPI |
+| Ruby | Rails |
+| Rust | Actix, Axum |
+| Java | Spring |
+| PHP | Laravel |
+
+## Example: Rails Project
+
+```bash
+$ proteus
+
+🔱 PROTEUS - Shape-shifting project intelligence
+
+✓ Claude Code detected - using AI-powered generation
+✔ Output language: 日本語
+
+Tech Stack:
+  Language:    ruby
+  Framework:   rails
+  Testing:     rspec
+
+Recommended agents:
+  1. rails-graphql-type-generator
+  2. serializable-pattern-enforcer
+  3. rspec-request-spec-writer
+  ...
+
+✅ Created .claude/agents/rails-graphql-type-generator.md
+✅ Created .claude/skills/proteus/SKILL.md
+```
+
+## Using Generated Agents
+
+```bash
+# Use specific agent
+@rails-graphql-type-generator このResolverをレビューして
+
+# Use /proteus to auto-route
+/proteus テストを書いて  # → automatically uses rspec-request-spec-writer
+```
+
+## Contributing
+
+Contributions welcome! Please read our [Contributing Guide](CONTRIBUTING.md).
+
+## License
+
+MIT
+
+---
+
+<p align="center">
+  <i>Named after Proteus, the shape-shifting Greek sea god who could transform into anything — just like this tool transforms into your project.</i>
+</p>

package/dist/agent-registry-IWDWNZDN.js

@@ -0,0 +1,12 @@
+import {
+  generateAgentListSection,
+  scanExistingAgents,
+  shouldUpdateRegistry,
+  updateAgentRegistry
+} from "./chunk-XNEZQVEV.js";
+export {
+  generateAgentListSection,
+  scanExistingAgents,
+  shouldUpdateRegistry,
+  updateAgentRegistry
+};

package/dist/chunk-XNEZQVEV.js

@@ -0,0 +1,236 @@
+// src/agent-registry.ts
+import * as fs from "fs";
+import * as path from "path";
+var I18N = {
+  en: {
+    availableAgents: "Available Agents",
+    noAgentsConfigured: "No agents configured yet.",
+    agentHeader: "Agent",
+    descriptionHeader: "Description",
+    pathHeader: "Path",
+    agentsAvailable: (n) => `${n} agent(s) available`,
+    projectAgentsTitle: "Project Agents",
+    projectAgentsDescription: "This file lists all available Claude Code agents for this project."
+  },
+  ja: {
+    availableAgents: "\u5229\u7528\u53EF\u80FD\u306A\u30A8\u30FC\u30B8\u30A7\u30F3\u30C8",
+    noAgentsConfigured: "\u30A8\u30FC\u30B8\u30A7\u30F3\u30C8\u306F\u307E\u3060\u8A2D\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002",
+    agentHeader: "\u30A8\u30FC\u30B8\u30A7\u30F3\u30C8",
+    descriptionHeader: "\u8AAC\u660E",
+    pathHeader: "\u30D1\u30B9",
+    agentsAvailable: (n) => `${n}\u500B\u306E\u30A8\u30FC\u30B8\u30A7\u30F3\u30C8\u304C\u5229\u7528\u53EF\u80FD`,
+    projectAgentsTitle: "\u30D7\u30ED\u30B8\u30A7\u30AF\u30C8\u30A8\u30FC\u30B8\u30A7\u30F3\u30C8",
+    projectAgentsDescription: "\u3053\u306E\u30D5\u30A1\u30A4\u30EB\u306F\u3001\u3053\u306E\u30D7\u30ED\u30B8\u30A7\u30AF\u30C8\u3067\u5229\u7528\u53EF\u80FD\u306AClaude Code\u30A8\u30FC\u30B8\u30A7\u30F3\u30C8\u306E\u4E00\u89A7\u3067\u3059\u3002"
+  },
+  zh: {
+    availableAgents: "\u53EF\u7528\u4EE3\u7406",
+    noAgentsConfigured: "\u5C1A\u672A\u914D\u7F6E\u4EE3\u7406\u3002",
+    agentHeader: "\u4EE3\u7406",
+    descriptionHeader: "\u63CF\u8FF0",
+    pathHeader: "\u8DEF\u5F84",
+    agentsAvailable: (n) => `${n}\u4E2A\u4EE3\u7406\u53EF\u7528`,
+    projectAgentsTitle: "\u9879\u76EE\u4EE3\u7406",
+    projectAgentsDescription: "\u6B64\u6587\u4EF6\u5217\u51FA\u4E86\u6B64\u9879\u76EE\u6240\u6709\u53EF\u7528\u7684Claude Code\u4EE3\u7406\u3002"
+  },
+  ko: {
+    availableAgents: "\uC0AC\uC6A9 \uAC00\uB2A5\uD55C \uC5D0\uC774\uC804\uD2B8",
+    noAgentsConfigured: "\uC544\uC9C1 \uAD6C\uC131\uB41C \uC5D0\uC774\uC804\uD2B8\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.",
+    agentHeader: "\uC5D0\uC774\uC804\uD2B8",
+    descriptionHeader: "\uC124\uBA85",
+    pathHeader: "\uACBD\uB85C",
+    agentsAvailable: (n) => `${n}\uAC1C\uC758 \uC5D0\uC774\uC804\uD2B8 \uC0AC\uC6A9 \uAC00\uB2A5`,
+    projectAgentsTitle: "\uD504\uB85C\uC81D\uD2B8 \uC5D0\uC774\uC804\uD2B8",
+    projectAgentsDescription: "\uC774 \uD30C\uC77C\uC740 \uC774 \uD504\uB85C\uC81D\uD2B8\uC5D0\uC11C \uC0AC\uC6A9 \uAC00\uB2A5\uD55C Claude Code \uC5D0\uC774\uC804\uD2B8 \uBAA9\uB85D\uC785\uB2C8\uB2E4."
+  },
+  es: {
+    availableAgents: "Agentes Disponibles",
+    noAgentsConfigured: "No hay agentes configurados todav\xEDa.",
+    agentHeader: "Agente",
+    descriptionHeader: "Descripci\xF3n",
+    pathHeader: "Ruta",
+    agentsAvailable: (n) => `${n} agente(s) disponible(s)`,
+    projectAgentsTitle: "Agentes del Proyecto",
+    projectAgentsDescription: "Este archivo lista todos los agentes de Claude Code disponibles para este proyecto."
+  },
+  fr: {
+    availableAgents: "Agents Disponibles",
+    noAgentsConfigured: "Aucun agent configur\xE9 pour le moment.",
+    agentHeader: "Agent",
+    descriptionHeader: "Description",
+    pathHeader: "Chemin",
+    agentsAvailable: (n) => `${n} agent(s) disponible(s)`,
+    projectAgentsTitle: "Agents du Projet",
+    projectAgentsDescription: "Ce fichier liste tous les agents Claude Code disponibles pour ce projet."
+  },
+  de: {
+    availableAgents: "Verf\xFCgbare Agenten",
+    noAgentsConfigured: "Noch keine Agenten konfiguriert.",
+    agentHeader: "Agent",
+    descriptionHeader: "Beschreibung",
+    pathHeader: "Pfad",
+    agentsAvailable: (n) => `${n} Agent(en) verf\xFCgbar`,
+    projectAgentsTitle: "Projekt-Agenten",
+    projectAgentsDescription: "Diese Datei listet alle verf\xFCgbaren Claude Code Agenten f\xFCr dieses Projekt auf."
+  }
+};
+function scanExistingAgents(agentDir) {
+  const agents = [];
+  if (!fs.existsSync(agentDir)) {
+    return agents;
+  }
+  const files = fs.readdirSync(agentDir);
+  for (const file of files) {
+    if (!file.endsWith(".md") || file.startsWith("_") || file.toLowerCase() === "readme.md") {
+      continue;
+    }
+    const filePath = path.join(agentDir, file);
+    const content = fs.readFileSync(filePath, "utf-8");
+    const h1Match = content.match(/^#\s+(.+)$/m);
+    const name = h1Match ? h1Match[1].trim() : file.replace(".md", "");
+    const descMatch = content.match(/^#\s+.+\n+([^#\n].+)/m);
+    const description = descMatch ? descMatch[1].trim() : void 0;
+    agents.push({
+      name,
+      description,
+      path: file
+    });
+  }
+  return agents;
+}
+function generateAgentListSection(agents, agentDir, format = "table", lang = "en") {
+  const t = I18N[lang];
+  if (agents.length === 0) {
+    return `## ${t.availableAgents}
+
+${t.noAgentsConfigured}
+`;
+  }
+  const relativePath = agentDir.replace(/^\.\//, "");
+  if (format === "table") {
+    let section = `## ${t.availableAgents}
+
+`;
+    section += `| ${t.agentHeader} | ${t.descriptionHeader} | ${t.pathHeader} |
+`;
+    section += "|-------|-------------|------|\n";
+    for (const agent of agents) {
+      const desc = agent.description ? truncate(agent.description, 60) : "-";
+      section += `| ${agent.name} | ${desc} | \`${relativePath}/${agent.path}\` |
+`;
+    }
+    section += `
+*${t.agentsAvailable(agents.length)}*
+`;
+    return section;
+  } else {
+    let section = `## ${t.availableAgents}
+
+`;
+    for (const agent of agents) {
+      section += `### ${agent.name}
+`;
+      if (agent.description) {
+        section += `${agent.description}
+`;
+      }
+      section += `- **${t.pathHeader}**: \`${relativePath}/${agent.path}\`
+
+`;
+    }
+    return section;
+  }
+}
+function updateAgentRegistry(options, newAgents = []) {
+  const { projectPath, agentDir, format = "table", lang = "en" } = options;
+  const t = I18N[lang];
+  const existingAgents = scanExistingAgents(path.join(projectPath, agentDir));
+  const allAgents = [...existingAgents];
+  for (const newAgent of newAgents) {
+    const filename = `${newAgent.name}.md`;
+    if (!allAgents.some((a) => a.path === filename)) {
+      allAgents.push({
+        name: formatAgentName(newAgent.name),
+        description: newAgent.description,
+        path: filename
+      });
+    }
+  }
+  const agentSection = generateAgentListSection(allAgents, agentDir, format, lang);
+  const claudeMdPath = path.join(projectPath, "CLAUDE.md");
+  const agentsMdPath = path.join(projectPath, "agents.md");
+  if (fs.existsSync(claudeMdPath)) {
+    const result = updateFileWithAgentSection(claudeMdPath, agentSection, lang);
+    return {
+      file: "CLAUDE.md",
+      action: result.action,
+      agentCount: allAgents.length
+    };
+  }
+  if (fs.existsSync(agentsMdPath)) {
+    const result = updateFileWithAgentSection(agentsMdPath, agentSection, lang);
+    return {
+      file: "agents.md",
+      action: result.action,
+      agentCount: allAgents.length
+    };
+  }
+  const newContent = `# ${t.projectAgentsTitle}
+
+${t.projectAgentsDescription}
+
+${agentSection}`;
+  fs.writeFileSync(agentsMdPath, newContent, "utf-8");
+  return {
+    file: "agents.md",
+    action: "created",
+    agentCount: allAgents.length
+  };
+}
+function updateFileWithAgentSection(filePath, agentSection, lang) {
+  const content = fs.readFileSync(filePath, "utf-8");
+  const t = I18N[lang];
+  const allSectionHeaders = Object.values(I18N).map((i) => i.availableAgents).join("|");
+  const agentSectionPattern = new RegExp(`## (${allSectionHeaders})[\\s\\S]*?(?=\\n## |\\n# |$)`);
+  if (agentSectionPattern.test(content)) {
+    const newContent = content.replace(agentSectionPattern, agentSection.trim());
+    fs.writeFileSync(filePath, newContent, "utf-8");
+    return { action: "updated" };
+  } else {
+    const newContent = content.trimEnd() + "\n\n" + agentSection;
+    fs.writeFileSync(filePath, newContent, "utf-8");
+    return { action: "added-section" };
+  }
+}
+function formatAgentName(name) {
+  return name.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function truncate(str, maxLength) {
+  if (str.length <= maxLength) return str;
+  return str.slice(0, maxLength - 3) + "...";
+}
+function shouldUpdateRegistry(projectPath, agentDir, newAgentCount) {
+  const claudeMdPath = path.join(projectPath, "CLAUDE.md");
+  const agentsMdPath = path.join(projectPath, "agents.md");
+  if (!fs.existsSync(claudeMdPath) && !fs.existsSync(agentsMdPath)) {
+    return true;
+  }
+  const existingAgents = scanExistingAgents(path.join(projectPath, agentDir));
+  if (newAgentCount > 0) {
+    return true;
+  }
+  const registryPath = fs.existsSync(claudeMdPath) ? claudeMdPath : agentsMdPath;
+  const content = fs.readFileSync(registryPath, "utf-8");
+  const agentCountMatch = content.match(/\*(\d+)/);
+  if (agentCountMatch) {
+    const registeredCount = parseInt(agentCountMatch[1], 10);
+    return registeredCount !== existingAgents.length;
+  }
+  return true;
+}
+
+export {
+  scanExistingAgents,
+  generateAgentListSection,
+  updateAgentRegistry,
+  shouldUpdateRegistry
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node