From 2b104dc021c08c9e5dc7f8b9f21d24a64522e8c7 Mon Sep 17 00:00:00 2001 From: yusyus Date: Wed, 4 Feb 2026 20:52:46 +0300 Subject: [PATCH] docs: Add multi-agent support documentation Update documentation for PR #270 multi-agent enhancement feature: - CHANGELOG.md: Add comprehensive section for multi-agent support - README.md: Update LOCAL Enhancement section with agent options - ENHANCEMENT_MODES.md: Add multi-agent guide with security details Includes: - Agent selection (claude, codex, copilot, opencode, custom) - CLI flags and environment variables - Security validation details - Agent aliases and normalization - Usage examples for all modes Co-Authored-By: Claude Sonnet 4.5 --- CHANGELOG.md | 25 +++++++ README.md | 20 +++++- docs/features/ENHANCEMENT_MODES.md | 109 ++++++++++++++++++++++++++++- 3 files changed, 149 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index feae51d..0310016 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added +#### Multi-Agent Support for Local Enhancement (NEW) +- **Multiple Coding Agent Support**: Choose your preferred local coding agent for SKILL.md enhancement + - **Claude Code** (default): Claude Code CLI with `--dangerously-skip-permissions` + - **Codex CLI**: OpenAI Codex CLI with `--full-auto` and `--skip-git-repo-check` + - **Copilot CLI**: GitHub Copilot CLI (`gh copilot chat`) + - **OpenCode CLI**: OpenCode CLI + - **Custom agents**: Use any CLI tool with `--agent custom --agent-cmd "command {prompt_file}"` +- **CLI Arguments**: New flags for agent selection + - `--agent`: Choose agent (claude, codex, copilot, opencode, custom) + - `--agent-cmd`: Override command template for custom agents +- **Environment Variables**: CI/CD friendly configuration + - `SKILL_SEEKER_AGENT`: Default agent to use + - `SKILL_SEEKER_AGENT_CMD`: Default command template for custom agents +- **Security First**: Custom command validation + - Blocks dangerous shell characters (`;`, `&`, `|`, `$`, `` ` ``, `\n`, `\r`) + - Validates executable exists in PATH + - Safe parsing with `shlex.split()` +- **Dual Input Modes**: Supports both file-based and stdin-based agents + - File-based: Uses `{prompt_file}` placeholder (Claude, custom agents) + - Stdin-based: Pipes prompt via stdin (Codex CLI) +- **Backward Compatible**: Claude Code remains the default, no breaking changes +- **Comprehensive Tests**: 13 new tests covering all agent types and security validation +- **Agent Normalization**: Smart alias handling (e.g., "claude-code" → "claude") +- **Credit**: Contributed by @rovo79 (Robert Dean) via PR #270 + #### C3.10: Signal Flow Analysis for Godot Projects (NEW) - **Complete Signal Flow Analysis System**: Analyze event-driven architectures in Godot game projects - Signal declaration extraction (`signal` keyword detection) diff --git a/README.md b/README.md index 5fc6b53..34155fa 100644 --- a/README.md +++ b/README.md @@ -1560,8 +1560,24 @@ skill-seekers enhance output/react/ - **Quality:** Transforms 75-line templates into 500+ line comprehensive guides **LOCAL Enhancement (Recommended):** -- Uses your Claude Code Max plan (no API costs) -- Opens new terminal with Claude Code +- Uses your local coding agent (no API costs) +- **Multiple Agent Support:** + - Claude Code (default) - Your Claude Code Max plan + - Codex CLI - OpenAI Codex CLI + - Copilot CLI - GitHub Copilot CLI + - OpenCode CLI - OpenCode CLI + - Custom agents - Use any CLI tool +- Choose agent with `--agent` flag: + ```bash + skill-seekers enhance output/react/ --agent codex + skill-seekers enhance output/react/ --agent copilot + skill-seekers enhance output/react/ --agent custom --agent-cmd "my-agent {prompt_file}" + ``` +- Environment variables for CI/CD: + ```bash + export SKILL_SEEKER_AGENT=codex + export SKILL_SEEKER_AGENT_CMD="my-agent {prompt_file}" + ``` - Analyzes reference files automatically - Takes 30-60 seconds - Quality: 9/10 (comparable to API version) diff --git a/docs/features/ENHANCEMENT_MODES.md b/docs/features/ENHANCEMENT_MODES.md index 1b2db7f..e2587ff 100644 --- a/docs/features/ENHANCEMENT_MODES.md +++ b/docs/features/ENHANCEMENT_MODES.md @@ -11,6 +11,98 @@ Skill Seekers supports **4 enhancement modes** for different use cases: 3. **Daemon** - Fully detached process, continues after parent exits 4. **Terminal** - Opens new terminal window (interactive) +## Multi-Agent Support (NEW) + +All enhancement modes now support **multiple local coding agents**: + +### Supported Agents + +| Agent | Display Name | Default | Notes | +|-------|--------------|---------|-------| +| **claude** | Claude Code | ✅ Yes | Your Claude Code Max plan (no API costs) | +| **codex** | OpenAI Codex CLI | No | Uses `codex exec --full-auto` | +| **copilot** | GitHub Copilot CLI | No | Uses `gh copilot chat` | +| **opencode** | OpenCode CLI | No | Uses `opencode` command | +| **custom** | Custom CLI Agent | No | Use any CLI tool with `--agent-cmd` | + +### Agent Selection + +**CLI Flags:** +```bash +# Use Codex CLI +skill-seekers enhance output/react/ --agent codex + +# Use Copilot CLI +skill-seekers enhance output/react/ --agent copilot + +# Use OpenCode CLI +skill-seekers enhance output/react/ --agent opencode + +# Custom agent with file input +skill-seekers enhance output/react/ --agent custom --agent-cmd "my-agent --prompt {prompt_file}" + +# Custom agent with stdin input +skill-seekers enhance output/react/ --agent custom --agent-cmd "my-agent --enhance" +``` + +**Environment Variables (CI/CD):** +```bash +# Set default agent +export SKILL_SEEKER_AGENT=codex +skill-seekers enhance output/react/ + +# Set custom command template +export SKILL_SEEKER_AGENT=custom +export SKILL_SEEKER_AGENT_CMD="my-agent {prompt_file}" +skill-seekers enhance output/react/ +``` + +### Agent Command Templates + +**File-based agents** (use `{prompt_file}` placeholder): +```bash +--agent-cmd "my-agent --input {prompt_file}" +--agent-cmd "my-agent < {prompt_file}" +``` + +**Stdin-based agents** (no placeholder): +```bash +--agent-cmd "my-agent --enhance" +``` + +### Security + +Custom commands are validated for security: +- ✅ Blocks dangerous shell characters: `;`, `&`, `|`, `$`, `` ` ``, `\n`, `\r` +- ✅ Validates executable exists in PATH +- ✅ Safe parsing with `shlex.split()` + +**Example rejection:** +```bash +# This will fail with security error: +skill-seekers enhance . --agent custom --agent-cmd "evil; rm -rf /" +# Error: Custom command contains dangerous shell characters +``` + +### Agent Aliases + +Agent names are normalized with smart alias support: +```bash +# All resolve to "claude" +--agent claude +--agent claude-code +--agent claude_code +--agent CLAUDE + +# All resolve to "codex" +--agent codex +--agent codex-cli + +# All resolve to "copilot" +--agent copilot +--agent copilot-cli +``` + ## Mode Comparison | Feature | Headless | Background | Daemon | Terminal | @@ -28,18 +120,25 @@ Skill Seekers supports **4 enhancement modes** for different use cases: **When to use**: CI/CD pipelines, automation scripts, when you want to wait for completion ```bash -# Basic usage - waits until done +# Basic usage - waits until done (uses Claude Code by default) skill-seekers enhance output/react/ +# Use different agent +skill-seekers enhance output/react/ --agent codex +skill-seekers enhance output/react/ --agent copilot + # With custom timeout skill-seekers enhance output/react/ --timeout 1200 # Force mode - no confirmations skill-seekers enhance output/react/ --force + +# Combine agent + force mode +skill-seekers enhance output/react/ --agent codex --force ``` **Behavior**: -- Runs `claude` CLI directly +- Runs selected coding agent CLI directly (default: Claude Code) - **BLOCKS** until enhancement completes - Shows progress output - Returns exit code: 0 = success, 1 = failure @@ -49,9 +148,13 @@ skill-seekers enhance output/react/ --force **When to use**: When you want to continue working while enhancement runs ```bash -# Start enhancement in background +# Start enhancement in background (default agent: Claude Code) skill-seekers enhance output/react/ --background +# Start with different agent +skill-seekers enhance output/react/ --background --agent codex +skill-seekers enhance output/react/ --background --agent copilot + # Returns immediately with status file created # ✅ Background enhancement started! # 📊 Status file: output/react/.enhancement_status.json