diff --git a/skills/autonomous-ai-agents/ai-coding-agents/SKILL.md b/skills/autonomous-ai-agents/ai-coding-agents/SKILL.md new file mode 100644 index 0000000..b123147 --- /dev/null +++ b/skills/autonomous-ai-agents/ai-coding-agents/SKILL.md @@ -0,0 +1,102 @@ +--- +name: ai-coding-agents +description: "AI coding agent integrations: OpenAI Codex CLI, Anthropic Claude Code, and OpenCode CLI for delegating coding tasks." +version: 2.0.0 +author: Hermes Agent +license: MIT +platforms: [linux, macos, windows] +metadata: + hermes: + tags: [codex, claude-code, opencode, ai-agent, coding, delegation] + related_skills: [development-workflow, kanban-workflow] +--- + +# AI Coding Agent Integrations + +Three AI coding agent CLIs for delegating implementation work. All three follow a similar pattern: launch the agent in a workspace, provide context via prompt, monitor execution, and verify output. + +## Section 1: OpenAI Codex CLI + +Delegate coding tasks to OpenAI's Codex CLI agent. Supports `codex exec` for bounded one-shot edits and `/goal` mode for multi-step work. + +**When to use:** Bounded coding tasks (features, bug fixes, refactors) where an autonomous coding agent can work independently. +**Key pattern:** Always run in an isolated git worktree/branch; Codex output is untrusted until reviewed. +**Prerequisite:** Verify your provider supports `/v1/responses` before attempting — see `references/codex-custom-provider.md` for endpoint probe commands. Most third-party endpoints (DeepSeek, 智谱, OneAPI) lack this endpoint. +**Auth:** `codex login --device-auth` (browser-based OpenID OAuth, needs PTY in terminal) or `OPENAI_API_KEY` env var. On this headless server, device-auth is the only path — Hermes starts it as a background PTY process and relays the one-time code to the user. +**See:** `references/codex.md` for workflows, `references/codex-custom-provider.md` for custom endpoint config and readiness diagnostic. + +## Section 2: Anthropic Claude Code + +Delegate coding tasks to Anthropic's Claude Code CLI. Interactive coding agent with tool use capabilities. + +**When to use:** Complex coding tasks requiring reasoning, refactoring, or multi-file changes via Claude. + +**Working models:** `claude-sonnet-4-5-20250929` (daily driver) and `claude-opus-4-20250514` (heavy lifting — architecture review, complex bugs). Both tested working 2026-06-14. + +**Pitfall — stale model config:** Claude Code reads its default model from `~/.claude/settings.json`. If this file references a model that no longer exists (we hit `claude-fable-5[1m]` on 2026-06-14), `claude -p` will fail silently — the agent gets an error string instead of a tool result. Fix: `claude config set model claude-opus-4-20250514` or directly edit `~/.claude/settings.json`. Always verify with `claude -p "what model are you" --output-format text --max-turns 1 --dangerously-skip-permissions` after changing models. + +**Hermes integration — the only working path:** Use `terminal(background=true, notify_on_complete=true)` with `claude -p`. +The `agent.subagent.provider: claude-code` config and ACP transport (`--acp --stdio`) +are **non-functional** — Claude Code v2.x does not support them. Do not use +`delegate_task(acp_command='claude')`. + +```bash +# Run Claude Code review via Hermes terminal +terminal(command="cd /path/to/repo && claude -p '' --output-format text --max-turns 6", + background=true, notify_on_complete=true, timeout=600) +``` + +**Parallel reviews:** Launch multiple `terminal(background=true)` calls simultaneously — each Claude Code instance runs independently and notifies on completion. For the full AtomK three-repo review + spec + re-review workflow, see `references/atomk-parallel-review-workflow.md`. + +**Scope for large repos:** Always provide an explicit file list in the prompt (e.g., `读 src/main/index.ts, src/main/auth.ts...`) rather than broad directories like `src/main/`. Large repos easily exhaust `--max-turns` on file discovery. Start with 8-10 files; if max turns hit, progressively narrow to 5-8 core files. Always include `--dangerously-skip-permissions` to avoid wasting turns on dialogs. Start with `--max-turns 8` and increase to 12+ only for narrow scopes. + +**See:** `references/claude-code.md`. For the full comparison of both working Hermes subagent +paths (built-in `delegate_task` vs external `claude -p`), see +`references/hermes-subagent-comparison.md`. + +## Section 3: OpenCode CLI + +Delegate coding tasks via the OpenCode CLI. An alternative coding agent for features and PR review. + +**When to use:** When the user prefers OpenCode as their coding agent, or for PR review workflows. +**See:** `references/opencode.md`. + +## Shared Principles + +1. **Isolate workspace** — always use git worktrees or branches, never run in a dirty main checkout +2. **Agent output is untrusted** — Hermes reviews, reconciles, and verifies before accepting +3. **Hermes owns lifecycle** — Hermes starts, monitors, and decides to accept/reject agent output +4. **Don't let agents own durable state** — Hermes writes kanban state, not the coding agent +5. **Verify with canonical tests** — run tests from Hermes, not just rely on agent self-report + +## Section 4: Collaborative Multi-Agent Setup + +All three tools (Hermes, Codex, Claude Code) can coexist on the same machine — CLI +entry points and install paths are independent. Note: Codex CLI requires a provider +with `/v1/responses` endpoint support (real OpenAI or OpenRouter); on our infrastructure +(DeepSeek/智譜/OneAPI/Google) it is **not viable**. See `references/collaborative-setup.md`. + +**See:** `references/collaborative-setup.md` for full guide. + +### Division of labor + +| Agent | Status | Best for | Avoid | +|-------|--------|----------|-------| +| **Hermes Agent** | ✅ | Orchestration, task decomposition, progress tracking | Hands-on code edits (delegate those) | +| **Claude Code** (Sonnet 4.5) | ✅ | Deep reasoning, complex bug hunting, code review, heavy refactors | Batch/bulk repetitive work | +| **Claude Code** (Opus 4) | ✅ | Architecture review, hardest bugs, large-scale refactors | Routine tasks (use Sonnet instead) | +| **Codex CLI** | ❌ | — | Unavailable on this system (no `/v1/responses` endpoint) | + +### Quick setup + +```bash +mkdir -p /workspace/my-project && cd /workspace/my-project +touch CHANGES.log CLAUDE.md AGENTS.md +``` + +Claude Code is invoked via `terminal(background=true)` in Hermes: +```bash +# The real working path — NOT agent.subagent.provider (dead config) +terminal(command="claude -p '' --output-format text --max-turns 6 --dangerously-skip-permissions", + background=true, notify_on_complete=true, timeout=600) +```