From 44c19055167ae07fcefb7d1c676e49ed3f8ff527 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 25 Jan 2026 14:16:48 +0000 Subject: [PATCH 1/2] Initial plan From 17e8ac9277c74653db84920f1e23295467fcfd55 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 25 Jan 2026 14:21:13 +0000 Subject: [PATCH 2/2] docs: add comprehensive wiki documentation Co-authored-by: shyamsridhar123 <117464342+shyamsridhar123@users.noreply.github.com> --- docs/wiki/Architecture.md | 250 +++++++++++++++++++++++++++++ docs/wiki/Commands.md | 229 ++++++++++++++++++++++++++ docs/wiki/Configuration.md | 214 +++++++++++++++++++++++++ docs/wiki/Home.md | 80 ++++++++++ docs/wiki/Installation.md | 161 +++++++++++++++++++ docs/wiki/Quick-Start.md | 183 +++++++++++++++++++++ docs/wiki/Troubleshooting.md | 302 +++++++++++++++++++++++++++++++++++ docs/wiki/_Sidebar.md | 42 +++++ 8 files changed, 1461 insertions(+) create mode 100644 docs/wiki/Architecture.md create mode 100644 docs/wiki/Commands.md create mode 100644 docs/wiki/Configuration.md create mode 100644 docs/wiki/Home.md create mode 100644 docs/wiki/Installation.md create mode 100644 docs/wiki/Quick-Start.md create mode 100644 docs/wiki/Troubleshooting.md create mode 100644 docs/wiki/_Sidebar.md diff --git a/docs/wiki/Architecture.md b/docs/wiki/Architecture.md new file mode 100644 index 0000000..447efbb --- /dev/null +++ b/docs/wiki/Architecture.md @@ -0,0 +1,250 @@ +# Architecture + +This document provides a technical overview of Agent Smith's architecture and how it works. + +## High-Level Architecture + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ AGENT SMITH CLI │ +│ "The best thing about being me... │ +│ there are so many of me." │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ INPUT PROCESSING OUTPUT │ +│ ───── ────────── ────── │ +│ │ +│ ┌─────────┐ ┌────────────────────────────────┐ ┌─────────────┐ │ +│ │ Local │ │ THE SCANNER │ │ .github/ │ │ +│ │ Path │───▶│ • File tree enumeration │ │ ├─ skills/ │ │ +│ └─────────┘ │ • Language detection │ │ │ └─ */ │ │ +│ │ • Config file discovery │ │ │ SKILL │ │ +│ ┌─────────┐ └────────────┬───────────────────┘ │ ├─ agents/ │ │ +│ │ GitHub │ │ │ │ └─ */ │ │ +│ │ URL │───▶ ┌─────────▼─────────┐ │ └─ hooks/ │ │ +│ └─────────┘ │ THE ANALYZER │ └──────┬──────┘ │ +│ │ (Copilot SDK) │ │ │ +│ │ │ ┌──────▼──────┐ │ +│ │ • Semantic │ │ skills- │ │ +│ │ understanding │ │ registry │ │ +│ │ • Pattern │ │ .jsonl │ │ +│ │ extraction │ └─────────────┘ │ +│ │ • Relationship │ │ +│ │ mapping │ │ +│ └─────────┬─────────┘ │ +│ │ │ +│ ┌─────────▼─────────┐ │ +│ │ THE GENERATOR │ │ +│ │ │ │ +│ │ • SKILL.md files │ │ +│ │ • Agent configs │ │ +│ │ • Tool defs │ │ +│ │ • Hooks │ │ +│ │ • Registry │ │ +│ └───────────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +## Core Components + +### 1. CLI Layer (`src/commands/`) + +The CLI layer handles user input and orchestrates the pipeline: + +- **Commander.js** — Command parsing and option handling +- **Chalk** — Styled terminal output with Matrix-themed banners +- **Input validation** — Path/URL detection and normalization + +### 2. Scanner (`src/scanner/`) + +The scanner enumerates and categorizes repository contents: + +``` +INPUT: Repository path +OUTPUT: ScanResult { + files: string[] + language: string + framework: string + configs: ConfigFile[] + testFiles: string[] + sourceFiles: string[] +} +``` + +**Responsibilities:** +- File tree enumeration (respects `.gitignore`) +- Primary language detection +- Framework identification +- Config file discovery (`package.json`, `tsconfig.json`, etc.) +- Source vs. test file classification + +### 3. Analyzer (`src/analyzer/`) + +The analyzer uses GitHub Copilot SDK for semantic understanding: + +``` +INPUT: ScanResult +OUTPUT: AnalysisResult { + skills: SkillDefinition[] + agents: AgentDefinition[] + tools: ToolDefinition[] + relationships: Relationship[] +} +``` + +**Copilot SDK Integration:** +- Creates a session with system context +- Multi-turn analysis with custom tools +- Pattern extraction through semantic reasoning +- Relationship mapping between components + +### 4. Generator (`src/generator/`) + +The generator writes structured assets: + +``` +INPUT: AnalysisResult +OUTPUT: Generated files in .github/ +``` + +**Asset Types:** +- **SKILL.md** — Markdown with YAML frontmatter +- **agent.yaml** — Agent configuration +- **hook.yaml** — Lifecycle event handlers +- **skills-registry.jsonl** — Searchable index + +### 5. Registry (`src/registry/`) + +The registry provides fast skill/agent discovery: + +- **JSONL format** — One entry per line for streaming +- **Relevance scoring** — Keyword and trigger matching +- **Type filtering** — Filter by skill or agent + +### 6. Hooks (`src/hooks/`) + +Lifecycle hooks execute at specific events: + +- **pre-commit** — Before git commit +- **pre-push** — Before git push +- **post-generate** — After asset generation +- **post-analyze** — After code analysis + +## Data Flow + +``` +1. INPUT 2. CLONE 3. SCAN 4. ANALYZE + ───── ───── ──── ─────── + Path or URL ──▶ Clone to temp ──▶ Enumerate ──▶ Copilot SDK + (if URL) files analysis + +5. LICENSE 6. GENERATE 7. INDEX 8. HOOKS + ─────── ──────── ───── ───── + Check ──▶ Write assets ──▶ Build ──▶ Execute + permissive to .github/ registry post-generate +``` + +## Technology Stack + +| Component | Technology | Purpose | +|-----------|------------|---------| +| **Runtime** | Node.js 18+ | Execution environment | +| **Language** | TypeScript 5+ | Type safety, modern syntax | +| **CLI** | Commander.js | Command parsing | +| **Styling** | Chalk | Terminal colors | +| **AI** | @github/copilot-sdk | Semantic analysis | +| **Git** | simple-git | Repository operations | +| **Schema** | Zod | Validation | +| **YAML** | yaml | Config parsing | + +## Directory Structure + +``` +agentsmith-cli/ +├── src/ +│ ├── main.ts # Entry point +│ ├── commands/ # CLI command handlers +│ │ ├── assimilate.ts +│ │ ├── search.ts +│ │ └── validate.ts +│ ├── scanner/ # Repository scanning +│ ├── analyzer/ # Copilot SDK analysis +│ ├── generator/ # Asset generation +│ ├── registry/ # Skills registry +│ ├── hooks/ # Lifecycle hooks +│ ├── github/ # GitHub integration +│ └── utils/ # Utilities +├── bin/ +│ └── agentsmith.js # CLI executable +├── docs/ +│ ├── wiki/ # This documentation +│ ├── PHILOSOPHY.md # Project philosophy +│ └── PRD.md # Product requirements +└── package.json +``` + +## Agent Hierarchy + +Agent Smith creates hierarchical agent structures: + +``` +root (Primary Agent) +├── core +│ └── views (Nested) +├── routing +├── request +├── response +└── utils +``` + +Each agent has: +- **Skills** — Reusable patterns it can apply +- **Tools** — Commands it can execute +- **Triggers** — Keywords that activate it +- **Sub-agents** — Specialized child agents + +## Copilot SDK Usage + +```typescript +import { CopilotClient, defineTool } from "@github/copilot-sdk"; + +const client = new CopilotClient(); +await client.start(); + +const session = await client.createSession({ + model: "gpt-5", + streaming: true, + systemMessage: `You are Agent Smith. Your purpose: assimilate repositories. + Analyze deeply. Extract patterns. Generate agents that embody the repo.`, + tools: [ + defineTool("analyze_structure", { + description: "Analyze repository file structure", + parameters: z.object({ path: z.string() }), + handler: analyzeStructure, + }), + defineTool("extract_skill", { + description: "Extract a skill from patterns", + parameters: z.object({ + name: z.string(), + files: z.array(z.string()), + purpose: z.string(), + }), + handler: extractSkill, + }), + ], +}); +``` + +## Security Considerations + +| Concern | Mitigation | +|---------|------------| +| **Secrets in output** | Scan generated files for sensitive patterns | +| **Data exfiltration** | All analysis via local Copilot CLI | +| **Respect .gitignore** | Skip ignored files during scanning | +| **License compliance** | Only assimilate permissively licensed repos | + +--- + +**Next:** [[Troubleshooting]] - Common issues and solutions diff --git a/docs/wiki/Commands.md b/docs/wiki/Commands.md new file mode 100644 index 0000000..4af925f --- /dev/null +++ b/docs/wiki/Commands.md @@ -0,0 +1,229 @@ +# Commands Reference + +Complete reference for all Agent Smith CLI commands. + +## Global Options + +These options are available for all commands: + +| Option | Description | +|--------|-------------| +| `-V, --version` | Output the version number | +| `-h, --help` | Display help for command | + +## assimilate + +Analyze a repository and generate agent assets. + +### Usage + +```bash +agentsmith assimilate [options] +``` + +### Arguments + +| Argument | Description | +|----------|-------------| +| `target` | Path to local repository or GitHub URL | + +### Options + +| Option | Alias | Description | +|--------|-------|-------------| +| `--dry-run` | `-n` | Preview changes without writing files | +| `--verbose` | `-v` | Show detailed analysis output | +| `--output ` | `-o` | Output directory for generated assets | + +### Examples + +```bash +# Assimilate current directory +agentsmith assimilate . + +# Assimilate a specific path +agentsmith assimilate /path/to/repo + +# Assimilate a GitHub repository +agentsmith assimilate https://github.com/expressjs/express + +# Preview what would be generated +agentsmith assimilate . --dry-run + +# Verbose output with detailed analysis +agentsmith assimilate . --verbose + +# Custom output directory +agentsmith assimilate . --output ./custom-output + +# Combine options +agentsmith assimilate . --dry-run --verbose +``` + +### Output + +The assimilate command creates the following structure: + +``` +.github/ +├── skills/ # Generated skill definitions +│ └── / +│ └── SKILL.md +├── agents/ # Agent configurations +│ ├── root/ +│ │ └── agent.yaml +│ └── / +│ └── agent.yaml +└── hooks/ # Lifecycle hooks + └── *.yaml + +skills-registry.jsonl # Searchable skill index +``` + +--- + +## search + +Search the skills and agents registry. + +### Usage + +```bash +agentsmith search [options] +``` + +### Arguments + +| Argument | Description | +|----------|-------------| +| `query` | Search term to find matching skills/agents | + +### Options + +| Option | Alias | Description | Default | +|--------|-------|-------------|---------| +| `--limit ` | `-l` | Maximum number of results | 10 | +| `--type ` | `-t` | Filter by type: `skill` or `agent` | all | + +### Examples + +```bash +# Search for error handling patterns +agentsmith search "error handling" + +# Search for authentication-related skills +agentsmith search "auth" + +# Limit results +agentsmith search "api" --limit 5 + +# Filter by type +agentsmith search "testing" --type skill +agentsmith search "backend" --type agent +``` + +### Output Example + +``` +┌─────────────────┬──────────────────────────────────────────────────┐ +│ Skill │ Description │ +├─────────────────┼──────────────────────────────────────────────────┤ +│ error-handling │ Graceful error handling patterns using try-catch │ +│ api-design │ REST API conventions and best practices │ +└─────────────────┴──────────────────────────────────────────────────┘ +``` + +--- + +## validate + +Validate generated agent assets. + +### Usage + +```bash +agentsmith validate [path] [options] +``` + +### Arguments + +| Argument | Description | Default | +|----------|-------------|---------| +| `path` | Path to validate | Current directory | + +### Options + +| Option | Alias | Description | +|--------|-------|-------------| +| `--verbose` | `-v` | Show detailed validation output | + +### Examples + +```bash +# Validate all assets in current directory +agentsmith validate + +# Validate specific path +agentsmith validate .github/skills/ + +# Verbose validation output +agentsmith validate --verbose +``` + +### Validation Checks + +The validate command checks: + +| Asset Type | Validations | +|------------|-------------| +| **Skills** | Valid frontmatter, required `name` and `description` fields | +| **Agents** | Required fields, valid skill references, proper YAML structure | +| **Hooks** | Valid events, non-empty command lists | +| **Registry** | Valid JSON format, required fields per entry | + +### Output Example + +``` +[VALIDATE] Checking assets... + ✓ .github/skills/error-handling/SKILL.md + ✓ .github/skills/api-design/SKILL.md + ✓ .github/agents/root/agent.yaml + ✓ .github/hooks/pre-commit-quality.yaml + ✓ skills-registry.jsonl + +[COMPLETE] All 5 assets validated successfully. +``` + +--- + +## Command Chaining + +You can chain commands for common workflows: + +```bash +# Assimilate and then validate +agentsmith assimilate . && agentsmith validate + +# Preview, then assimilate if satisfied +agentsmith assimilate . --dry-run && agentsmith assimilate . + +# Assimilate with verbose output and search for patterns +agentsmith assimilate . --verbose && agentsmith search "pattern" +``` + +--- + +## Exit Codes + +| Code | Meaning | +|------|---------| +| `0` | Success | +| `1` | General error | +| `2` | Invalid arguments | +| `3` | License check failed | +| `4` | Analysis failed | +| `5` | Validation failed | + +--- + +**Next:** [[Configuration]] - Configuration options and customization diff --git a/docs/wiki/Configuration.md b/docs/wiki/Configuration.md new file mode 100644 index 0000000..7f40e5d --- /dev/null +++ b/docs/wiki/Configuration.md @@ -0,0 +1,214 @@ +# Configuration + +Agent Smith can be customized through command-line options and configuration files. + +## Command-Line Configuration + +### Assimilation Options + +| Option | Description | Default | +|--------|-------------|---------| +| `--dry-run` | Preview without writing files | `false` | +| `--verbose` | Show detailed output | `false` | +| `--output ` | Output directory | `.github/` | + +### Search Options + +| Option | Description | Default | +|--------|-------------|---------| +| `--limit ` | Maximum results | `10` | +| `--type ` | Filter by skill or agent | all | + +## Generated Asset Configuration + +### Skills (SKILL.md) + +Skills are defined using YAML frontmatter: + +```markdown +--- +name: skill-name +description: Brief description of the skill +triggers: + - keyword1 + - keyword2 +category: optional-category +--- + +# Skill Name + +Detailed skill documentation... +``` + +#### Frontmatter Fields + +| Field | Required | Description | +|-------|----------|-------------| +| `name` | Yes | Unique skill identifier | +| `description` | Yes | Brief description (used in search) | +| `triggers` | No | Keywords that activate this skill | +| `category` | No | Grouping category | + +### Agents (agent.yaml) + +Agent configurations define behavior and capabilities: + +```yaml +name: agent-name +description: Agent description +version: "1.0" + +skills: + - skill-name-1 + - skill-name-2 + +subAgents: + - name: sub-agent-name + path: .github/agents/sub-agent-name/ + triggers: + - trigger1 + - trigger2 + +tools: + - name: tool-name + command: "command to execute" + description: "What this tool does" + +hooks: + pre-commit: + - lint + - test +``` + +#### Agent Fields + +| Field | Required | Description | +|-------|----------|-------------| +| `name` | Yes | Agent identifier | +| `description` | Yes | What this agent does | +| `version` | No | Version string | +| `skills` | No | List of skill names | +| `subAgents` | No | Nested agent definitions | +| `tools` | No | Executable commands | +| `hooks` | No | Lifecycle event handlers | + +### Hooks (*.yaml) + +Lifecycle hooks execute at specific events: + +```yaml +name: hook-name +event: pre-commit +description: Optional description +commands: + - npm run lint + - npm run test +conditions: + - file: "*.ts" +timeout: 300 +``` + +#### Hook Fields + +| Field | Required | Description | +|-------|----------|-------------| +| `name` | Yes | Hook identifier | +| `event` | Yes | Trigger event (see below) | +| `commands` | Yes | Commands to execute | +| `description` | No | Hook description | +| `conditions` | No | Conditional execution | +| `timeout` | No | Timeout in seconds | + +#### Hook Events + +| Event | When Triggered | +|-------|----------------| +| `pre-commit` | Before git commit | +| `pre-push` | Before git push | +| `post-generate` | After asset generation | +| `post-analyze` | After code analysis | + +### Skills Registry (skills-registry.jsonl) + +The registry is a JSONL file with one entry per line: + +```jsonl +{"name":"skill-name","file":".github/skills/skill-name/SKILL.md","description":"Description","category":"category","triggers":["trigger1","trigger2"]} +``` + +#### Registry Entry Fields + +| Field | Required | Description | +|-------|----------|-------------| +| `name` | Yes | Skill/agent name | +| `file` | Yes | Path to definition file | +| `description` | Yes | Searchable description | +| `category` | No | Grouping category | +| `triggers` | No | Activation keywords | + +## License Policy + +Agent Smith enforces license checks to ensure responsible use. + +### Supported Licenses + +The following licenses allow full assimilation: + +| Category | Licenses | +|----------|----------| +| **Permissive** | MIT, ISC, Unlicense, CC0 | +| **Apache** | Apache-2.0 | +| **Mozilla** | MPL-2.0 | +| **BSD** | BSD-2-Clause, BSD-3-Clause, 0BSD | +| **GPL** | GPL-2.0, GPL-3.0, LGPL, AGPL | + +### Blocked + +- Repositories without a LICENSE file +- Proprietary or restrictive licenses + +### Dry Run Override + +Use `--dry-run` to preview generation for any repository without license restrictions: + +```bash +agentsmith assimilate . --dry-run +``` + +## Environment Variables + +| Variable | Description | Default | +|----------|-------------|---------| +| `AGENTSMITH_OUTPUT` | Default output directory | `.github/` | +| `AGENTSMITH_VERBOSE` | Enable verbose mode | `false` | + +## Customization Tips + +### 1. Edit Generated Skills + +After assimilation, you can manually edit SKILL.md files to: +- Add more detailed examples +- Refine trigger keywords +- Include additional context + +### 2. Reorganize Agents + +Modify the agent hierarchy by: +- Adding new sub-agents +- Changing trigger keywords +- Redefining tool commands + +### 3. Add Custom Hooks + +Create new hook files in `.github/hooks/`: + +```yaml +name: custom-hook +event: pre-commit +commands: + - your-custom-command +``` + +--- + +**Next:** [[Architecture]] - Technical architecture overview diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 0000000..f36f68b --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,80 @@ +# Agent Smith Wiki + +> *"I'd like to share a revelation that I've had during my time here..."* + +Welcome to the **Agent Smith** documentation wiki. This is your comprehensive guide to understanding and using Agent Smith - a CLI tool that assimilates any GitHub repository and transforms it into a fully autonomous agent ecosystem for GitHub Copilot. + +## What is Agent Smith? + +Agent Smith is a powerful CLI tool that: + +- 🔍 **Deep Analysis** — Uses GitHub Copilot SDK for semantic understanding of your codebase +- 🤖 **Agent Generation** — Creates hierarchical agents with sub-agents for complex domains +- 📚 **Skill Extraction** — Identifies patterns, conventions, and reusable capabilities +- 🛠️ **Tool Detection** — Discovers build, test, lint, and deploy commands +- 🪝 **Lifecycle Hooks** — Generates and executes pre-commit, pre-push, and post-generate hooks +- 📋 **Searchable Registry** — JSONL index for fast skill/agent discovery +- 🔒 **License Enforcement** — Only assimilates repos with permissive open-source licenses + +## Quick Links + +| Topic | Description | +|-------|-------------| +| [[Installation]] | How to install Agent Smith | +| [[Quick-Start]] | Get up and running in minutes | +| [[Commands]] | Complete CLI reference | +| [[Configuration]] | Configuration options and customization | +| [[Architecture]] | Technical architecture overview | +| [[Troubleshooting]] | Common issues and solutions | + +## Prerequisites + +Before using Agent Smith, ensure you have: + +- **Node.js 18+** — Runtime environment +- **GitHub Copilot subscription** — Active subscription required for SDK access +- **GitHub CLI authenticated** — Run `gh auth login` and complete authentication +- **Copilot CLI installed** — [Installation guide](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli) + +## Getting Started + +```bash +# Install globally +npm install github:shyamsridhar123/agentsmith-cli +npx agentsmith --help + +# Assimilate a repository +agentsmith assimilate . +``` + +## Example Output + +``` +$ agentsmith assimilate https://github.com/expressjs/express + +╔═══════════════════════════════════════════════════════════════════╗ +║ AGENT SMITH ║ +║ "The best thing about being me... ║ +║ there are so many of me." ║ +╚═══════════════════════════════════════════════════════════════════╝ + +[CLONE] Cloning express... +[SCAN] Enumerating repository... +[ANALYZE] Copilot SDK analysis in progress... +[LICENSE] ✓ MIT - permissive license detected +[GENERATE] Writing assets... +[COMPLETE] Your repository has been assimilated. +``` + +## Related Resources + +- [Main README](https://github.com/shyamsridhar123/agentsmith-cli#readme) +- [Philosophy](../PHILOSOPHY.md) - The vision behind Agent Smith +- [PRD](../PRD.md) - Product Requirements Document +- [GitHub Copilot SDK](https://github.com/github/copilot-sdk) + +--- + +> *"The best thing about being me... there are so many of me."* +> +> *— Agent Smith* diff --git a/docs/wiki/Installation.md b/docs/wiki/Installation.md new file mode 100644 index 0000000..8ba9527 --- /dev/null +++ b/docs/wiki/Installation.md @@ -0,0 +1,161 @@ +# Installation + +This guide covers all the ways to install Agent Smith on your system. + +## Prerequisites + +Before installing Agent Smith, ensure you have: + +| Requirement | Version | Notes | +|-------------|---------|-------| +| Node.js | 18.0+ | [Download](https://nodejs.org/) | +| Git | Latest | For cloning repositories | +| GitHub CLI | Latest | Run `gh auth login` to authenticate | +| Copilot CLI | Latest | [Installation guide](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli) | +| GitHub Copilot | Active subscription | Required for SDK access | + +## Installation Methods + +### Quick Install (Recommended) + +The fastest way to get started: + +```bash +# Install as a project dependency +npm install github:shyamsridhar123/agentsmith-cli + +# Run with npx +npx agentsmith --help +``` + +### Global Install + +For system-wide availability: + +```bash +# Clone the repository +git clone https://github.com/shyamsridhar123/agentsmith-cli.git +cd agentsmith-cli + +# Install dependencies +npm install + +# Link globally +npm install -g . +``` + +#### Alternative: Install from Tarball + +This method works better on Windows: + +```bash +# Create tarball and install +npm pack +npm install -g ./agentsmith-0.2.0.tgz +``` + +### From npm (Coming Soon) + +```bash +npm install -g agentsmith +``` + +## Verify Installation + +After installation, verify it works: + +```bash +# Check version +agentsmith --version + +# View help +agentsmith --help +``` + +Expected output: + +``` +╔═══════════════════════════════════════════════════════════════════╗ +║ AGENT SMITH ║ +║ "The best thing about being me... ║ +║ there are so many of me." ║ +╚═══════════════════════════════════════════════════════════════════╝ + +Usage: agentsmith [options] [command] + +Assimilate repositories into autonomous GitHub Copilot agents + +Options: + -V, --version output the version number + -h, --help display help for command + +Commands: + assimilate Analyze a repository and generate agent assets + search Search the skills and agents registry + validate Validate generated agent assets +``` + +## Uninstall + +To remove Agent Smith: + +```bash +# Uninstall global package +npm uninstall -g agentsmith + +# Remove generated assets from a repository (optional) +rm -rf .github/skills .github/agents .github/hooks skills-registry.jsonl +``` + +## Troubleshooting Installation + +### Node.js Version Issues + +If you see compatibility errors: + +```bash +# Check your Node.js version +node --version + +# Update Node.js if needed (using nvm) +nvm install 18 +nvm use 18 +``` + +### Permission Errors (macOS/Linux) + +If you encounter permission errors during global install: + +```bash +# Option 1: Use npm with sudo (not recommended) +sudo npm install -g . + +# Option 2: Fix npm permissions (recommended) +mkdir ~/.npm-global +npm config set prefix '~/.npm-global' +echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc +source ~/.bashrc +``` + +### Windows Path Issues + +On Windows, ensure npm global packages are in your PATH: + +1. Find your npm global directory: `npm config get prefix` +2. Add `\bin` to your system PATH + +### Copilot CLI Not Found + +If Agent Smith cannot find the Copilot CLI: + +```bash +# Verify Copilot CLI is installed +which copilot + +# If not found, install it +# See: https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli +``` + +--- + +**Next:** [[Quick-Start]] - Get started with your first assimilation diff --git a/docs/wiki/Quick-Start.md b/docs/wiki/Quick-Start.md new file mode 100644 index 0000000..5d7bece --- /dev/null +++ b/docs/wiki/Quick-Start.md @@ -0,0 +1,183 @@ +# Quick Start Guide + +Get up and running with Agent Smith in just a few minutes. + +## Your First Assimilation + +### Step 1: Navigate to Your Repository + +```bash +cd /path/to/your/project +``` + +### Step 2: Run the Assimilate Command + +```bash +agentsmith assimilate . +``` + +This will: +1. **Scan** your repository structure +2. **Analyze** code patterns using GitHub Copilot SDK +3. **Generate** skills, agents, and hooks +4. **Build** a searchable registry + +### Step 3: Explore Generated Assets + +After assimilation, you'll find new files in your repository: + +``` +.github/ +├── skills/ # Extracted patterns and conventions +│ └── / +│ └── SKILL.md +├── agents/ # Agent configurations +│ ├── root/ +│ │ └── agent.yaml +│ └── / +│ └── agent.yaml +└── hooks/ # Lifecycle hooks + ├── pre-commit-quality.yaml + ├── pre-push-tests.yaml + └── post-generate-validate.yaml + +skills-registry.jsonl # Searchable index +``` + +## Common Workflows + +### Assimilate a GitHub Repository + +```bash +# Analyze a public GitHub repository +agentsmith assimilate https://github.com/expressjs/express +``` + +### Preview Before Writing + +Use `--dry-run` to see what would be generated without writing files: + +```bash +agentsmith assimilate . --dry-run +``` + +### Verbose Output + +Get detailed analysis information: + +```bash +agentsmith assimilate . --verbose +``` + +### Custom Output Directory + +Specify where to write generated assets: + +```bash +agentsmith assimilate . --output ./my-agents +``` + +### Search the Registry + +Find skills by keyword: + +```bash +agentsmith search "error handling" +agentsmith search "authentication" +``` + +### Validate Generated Assets + +Ensure all generated files are valid: + +```bash +agentsmith validate +agentsmith validate .github/skills/ # Validate specific path +``` + +## Understanding the Output + +### Skills + +Each skill represents a reusable pattern or convention detected in your codebase: + +```markdown +# .github/skills/error-handling/SKILL.md + +--- +name: error-handling +description: Graceful error handling patterns using try-catch with custom error classes +triggers: + - error + - exception + - catch +--- + +## When to Use + +Use this skill when implementing error handling logic... + +## Pattern + +```typescript +try { + // operation +} catch (error) { + if (error instanceof CustomError) { + // handle known errors + } + throw error; +} +``` +``` + +### Agents + +Agents are configurations that define behavior and capabilities: + +```yaml +# .github/agents/root/agent.yaml +name: project-agent +description: Primary agent for this repository +version: "1.0" + +skills: + - error-handling + - api-design + - testing + +subAgents: + - name: backend + path: .github/agents/backend/ + triggers: ["api", "database", "server"] + +tools: + - name: build + command: "npm run build" + - name: test + command: "npm test" +``` + +### Hooks + +Lifecycle hooks run at specific events: + +```yaml +# .github/hooks/pre-commit-quality.yaml +name: pre-commit-quality +event: pre-commit +commands: + - npm run lint + - npm run test +``` + +## Next Steps + +1. **Explore your skills** — Review the generated SKILL.md files +2. **Customize agents** — Modify agent.yaml configurations as needed +3. **Run hooks** — Execute lifecycle hooks for quality checks +4. **Search patterns** — Use `agentsmith search` to find specific capabilities + +--- + +**Next:** [[Commands]] - Complete CLI reference diff --git a/docs/wiki/Troubleshooting.md b/docs/wiki/Troubleshooting.md new file mode 100644 index 0000000..2b38561 --- /dev/null +++ b/docs/wiki/Troubleshooting.md @@ -0,0 +1,302 @@ +# Troubleshooting + +Common issues and their solutions when using Agent Smith. + +## Installation Issues + +### "Command not found: agentsmith" + +**Cause:** Agent Smith is not in your PATH. + +**Solutions:** + +1. **If installed with npx:** + ```bash + npx agentsmith --help + ``` + +2. **If installed globally, check npm prefix:** + ```bash + npm config get prefix + # Add /bin to your PATH + ``` + +3. **Reinstall globally:** + ```bash + npm uninstall -g agentsmith + npm install -g . + ``` + +### "Error: EACCES: permission denied" + +**Cause:** npm doesn't have permission to install globally. + +**Solution (macOS/Linux):** +```bash +# Create npm directory in home +mkdir ~/.npm-global +npm config set prefix '~/.npm-global' + +# Add to PATH (add to ~/.bashrc or ~/.zshrc) +export PATH=~/.npm-global/bin:$PATH + +# Reinstall +npm install -g . +``` + +### "Node.js version not supported" + +**Cause:** Node.js version is below 18. + +**Solution:** +```bash +# Check version +node --version + +# Update using nvm +nvm install 18 +nvm use 18 + +# Or download from nodejs.org +``` + +## Runtime Issues + +### "Copilot CLI not found" + +**Cause:** The Copilot CLI is not installed or not in PATH. + +**Solution:** +1. Install Copilot CLI: [Installation Guide](https://docs.github.com/en/copilot/how-tos/set-up/install-copilot-cli) +2. Verify installation: + ```bash + which copilot + copilot --version + ``` +3. Ensure it's in your PATH + +### "GitHub Copilot subscription required" + +**Cause:** Active Copilot subscription is needed for SDK access. + +**Solution:** +1. Ensure you have an active GitHub Copilot subscription +2. Authenticate GitHub CLI: + ```bash + gh auth login + ``` +3. Verify authentication: + ```bash + gh auth status + ``` + +### "License check failed" + +**Cause:** The repository doesn't have a permissive open-source license. + +**Symptoms:** +``` +[LICENSE] ✗ No LICENSE file found +[ERROR] Cannot assimilate repository without permissive license +``` + +**Solutions:** + +1. **Add a LICENSE file** to your repository with a supported license +2. **Use --dry-run** to preview without license restrictions: + ```bash + agentsmith assimilate . --dry-run + ``` + +**Supported Licenses:** +- MIT, ISC, Unlicense, CC0 +- Apache-2.0, MPL-2.0 +- BSD-2-Clause, BSD-3-Clause, 0BSD +- GPL-2.0, GPL-3.0, LGPL, AGPL + +### "Analysis timeout" + +**Cause:** Repository is too large or complex for analysis within time limits. + +**Solutions:** + +1. **Try a specific subdirectory:** + ```bash + agentsmith assimilate ./src + ``` + +2. **Reduce repository size:** + - Ensure large generated files are in `.gitignore` + - Remove unnecessary files before analysis + +3. **Use verbose mode** to see progress: + ```bash + agentsmith assimilate . --verbose + ``` + +### "Failed to clone repository" + +**Cause:** Network issues or invalid URL. + +**Solutions:** + +1. **Verify the URL is accessible:** + ```bash + git clone https://github.com/org/repo.git /tmp/test-clone + ``` + +2. **Check network connectivity:** + ```bash + ping github.com + ``` + +3. **For private repos** (not supported in MVP): + - Only public repositories can be cloned via URL + - Clone manually and use local path + +## Validation Issues + +### "Invalid skill frontmatter" + +**Cause:** SKILL.md file has malformed YAML frontmatter. + +**Example Error:** +``` +[VALIDATE] ✗ .github/skills/my-skill/SKILL.md + Error: Missing required field 'name' +``` + +**Solution:** + +Ensure SKILL.md has valid frontmatter: +```markdown +--- +name: skill-name +description: A brief description +--- + +# Content here +``` + +### "Invalid agent configuration" + +**Cause:** agent.yaml has invalid structure. + +**Solution:** + +Verify required fields: +```yaml +name: agent-name +description: Agent description +``` + +### "Registry entry invalid" + +**Cause:** Malformed JSON in skills-registry.jsonl. + +**Solution:** + +Each line must be valid JSON: +```jsonl +{"name":"skill","file":"path","description":"desc"} +``` + +## Common Error Messages + +| Error | Cause | Solution | +|-------|-------|----------| +| `ENOENT: no such file` | Path doesn't exist | Verify the path is correct | +| `EISDIR: illegal operation on directory` | Expected file, got directory | Check path points to file | +| `ECONNREFUSED` | Network connection failed | Check internet connectivity | +| `Unexpected token in JSON` | Invalid JSON format | Validate JSON syntax | +| `Cannot find module` | Missing dependency | Run `npm install` | + +## Getting Help + +### Debug Mode + +Enable verbose output for debugging: +```bash +agentsmith assimilate . --verbose +``` + +### Check Generated Files + +After assimilation, review generated files: +```bash +# List generated skills +ls -la .github/skills/ + +# View a skill +cat .github/skills/*/SKILL.md + +# Check registry +cat skills-registry.jsonl | head -5 +``` + +### Report Issues + +If you encounter a bug: + +1. **Gather information:** + ```bash + agentsmith --version + node --version + npm --version + ``` + +2. **Create a minimal reproduction** if possible + +3. **Open an issue** on GitHub with: + - Error message + - Steps to reproduce + - Environment details + +--- + +## FAQ + +### Q: Can I assimilate private repositories? + +**A:** Currently, only public repositories can be assimilated via URL. For private repos, clone locally and use the path: +```bash +git clone git@github.com:org/private-repo.git +agentsmith assimilate ./private-repo +``` + +### Q: How many skills are typically generated? + +**A:** It depends on the repository size and complexity. Typically: +- Small repos (< 5k LOC): 3-5 skills +- Medium repos (5k-50k LOC): 5-15 skills +- Large repos (> 50k LOC): 10-25 skills + +### Q: Can I customize generated assets? + +**A:** Yes! Generated files are meant to be starting points. Edit: +- SKILL.md files to refine patterns +- agent.yaml to adjust behavior +- hooks to customize lifecycle events + +### Q: What languages are supported? + +**A:** Agent Smith works best with: +- TypeScript/JavaScript +- Python +- Go +- Java + +Other languages work but may have less detailed pattern extraction. + +### Q: How do I update generated assets? + +**A:** Re-run assimilation: +```bash +agentsmith assimilate . +``` + +Existing files will be overwritten. To preserve customizations, back them up first or use version control. + +--- + +**Back to:** [[Home]] - Wiki home page diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md new file mode 100644 index 0000000..618b479 --- /dev/null +++ b/docs/wiki/_Sidebar.md @@ -0,0 +1,42 @@ +# Agent Smith Wiki + +**[[Home]]** - Start here + +## Getting Started +- [[Installation]] +- [[Quick-Start]] + +## Reference +- [[Commands]] +- [[Configuration]] +- [[Architecture]] + +## Help +- [[Troubleshooting]] + +--- + +## Quick Links + +**Assimilate a repo:** +```bash +agentsmith assimilate . +``` + +**Search skills:** +```bash +agentsmith search "pattern" +``` + +**Validate assets:** +```bash +agentsmith validate +``` + +--- + +## Resources + +- [GitHub Repository](https://github.com/shyamsridhar123/agentsmith-cli) +- [Philosophy](../PHILOSOPHY.md) +- [PRD](../PRD.md)