Agents Guide
SpecSoloist uses native subagents — agent definitions for Claude Code and Gemini CLI — to perform multi-step, tool-using compilation tasks. This is the default mode for most commands.
What Are Native Subagents?
Native subagents are Markdown files that define an agent's role, tools, and behaviour:
- Claude Code:
.claude/agents/directory - Gemini CLI:
.gemini/agents/directory
When you run sp conduct, sp compose, sp fix, or sp respec, SpecSoloist detects which CLI is installed (Claude preferred) and delegates the task to the appropriate agent.
Available Agents
| Agent | Role |
|---|---|
| compose | Draft architecture and specs from natural language |
| conductor | Orchestrate builds, resolve dependencies, spawn soloists |
| soloist | Compile a single spec into working code and tests |
| respec | Reverse-engineer existing code into specs |
| fix | Analyze test failures, patch code, re-test |
Each agent exists in three forms:
| Form | Location | Format | Used by |
|---|---|---|---|
| Skill | src/specsoloist/skills/sp-<name>/SKILL.md |
agentskills | Any agent framework |
| Claude agent | .claude/agents/<name>.md |
Claude Code | Claude Code |
| Gemini agent | .gemini/agents/<name>.md |
Gemini CLI | Gemini CLI |
Skills vs Native Agents
Skills are the cross-platform source of truth for what an agent should do. Native agent files (.claude/agents/, .gemini/agents/) express the same behavior with platform-specific wrappers — different tool names, and Gemini adds max_turns.
They cannot be mechanically unified because tool names differ per platform:
| Action | Claude Code | Gemini CLI |
|---|---|---|
| Read a file | Read |
read_file |
| Write a file | Write |
write_file |
| Run a shell command | Bash |
run_shell_command |
| Spawn a subagent | Task (subagent_type: <name>) |
platform-specific |
When you change agent behavior, update all three: the skill and both native agent files. See CONTRIBUTING.md in the repository root for the full sync checklist.
How sp Commands Use Agents
sp conduct src/
└── Conductor agent
├── Reads all *.spec.md files
├── Resolves dependency order
└── Spawns soloist agents per spec (parallel)
├── soloist: config
├── soloist: resolver
└── soloist: parser ...
sp compose "build a todo app with auth"
└── Compose agent
├── Drafts architecture
└── Writes spec files to src/
sp fix mymodule
└── Fix agent
├── Reads failing tests
├── Patches implementation
└── Re-runs tests (up to 3 retries)
sp respec src/mymodule.py
└── Respec agent
├── Reads existing code
└── Writes spec to src/mymodule.spec.md
Usage with Claude Code
# Default: delegates to Claude agent
sp conduct src/
# Fully automated (no permission prompts) — for CI or quine runs
sp conduct score/ --auto-accept
# Override model
sp conduct src/ --model claude-haiku-4-5-20251001
!!! warning "Running sp conduct inside a Claude Code session"
sp conduct (agent mode) spawns a new Claude Code subprocess. This is blocked when
you are already inside an active Claude Code session — the subprocess cannot start.
**The right approach from within Claude Code:** use the `Agent` tool to spawn the
`conductor` agent directly. No subprocess needed — you *are* the runtime.
Alternatively, use `sp conduct --no-agent`, which uses direct LLM API calls and
works from within a Claude Code session (requires `ANTHROPIC_API_KEY` or `GEMINI_API_KEY`).
Usage with Gemini CLI
If claude is not installed but gemini is, SpecSoloist automatically falls back to Gemini:
--no-agent Fallback
Pass --no-agent to skip the agent entirely and use direct LLM API calls. This is faster for simple single-spec compilation but loses the multi-step reasoning and tool-use capabilities:
Note: --no-agent requires an API key (GEMINI_API_KEY or ANTHROPIC_API_KEY).
The Quine
sp conduct score/ --auto-accept runs the quine — it uses the conductor agent to regenerate SpecSoloist's own source code from its own specs. This validates that all specs are complete and correct.
Output goes to build/quine/. Run the generated tests with: