.gemini/commands/ship.toml references non-existent .gemini/agents/ directory

[wi5nuu]

Description

The .gemini/commands/ship.toml file references a .gemini/agents/ directory on lines 10 and 25, but this directory does not exist in the repository. The actual agent definitions are located in the repository root under agents/.

As a result, the /ship command in Gemini CLI cannot correctly resolve the code-reviewer, security-auditor, and test-engineer subagents because the documented path .gemini/agents/ does not exist.

Evidence

1. The .gemini/agents/ directory does not exist

$ git ls-tree -r HEAD --name-only .gemini/

.gemini/commands/build.toml
.gemini/commands/code-simplify.toml
.gemini/commands/planning.toml
.gemini/commands/review.toml
.gemini/commands/ship.toml
.gemini/commands/spec.toml
.gemini/commands/test.toml
.gemini/commands/webperf.toml

Only .gemini/commands/ exists. There is no agents/ subdirectory inside .gemini/.

2. The agent files exist at the repository root

$ ls agents/

README.md
code-reviewer.md
security-auditor.md
test-engineer.md
web-performance-auditor.md

3. .gitignore does not exclude .gemini/agents/

.DS_Store
node_modules/
.env
.env.*
*.log
.claude/.simplify-ignore-cache/
.claude/sdd-cache/

There is no ignore rule that would hide a .gemini/agents/ directory.

4. The working tree is clean

$ git status .gemini/

nothing to commit, working tree clean

This confirms there are no hidden or untracked files under .gemini/.

5. Direct comparison with the Antigravity version

.gemini/commands/ship.toml (Gemini CLI) – line 10

Spawn three subagents concurrently. Gemini CLI exposes each custom subagent in .gemini/agents/ as a tool

.gemini/commands/ship.toml (Gemini CLI) – line 25

If you've defined your own code-reviewer, security-auditor, or test-engineer in .gemini/agents/

commands/ship.toml (Antigravity) – line 10

Spawn three subagents concurrently. The CLI exposes each custom subagent in agents/ as a tool

commands/ship.toml (Antigravity) – line 25

If you've defined your own code-reviewer, security-auditor, or test-engineer in agents/

The Antigravity version correctly references agents/, while the Gemini CLI version incorrectly references .gemini/agents/.

Impact

Gemini CLI users running /ship are instructed to locate subagents in .gemini/agents/, a directory that does not exist in this repository. As a result, the parallel fan-out orchestration involving code-reviewer, security-auditor, and test-engineer cannot locate the documented agent definitions.

Proposed Fix

Update .gemini/commands/ship.toml to reference agents/ instead of .gemini/agents/, matching the Antigravity implementation.

- subagent in `.gemini/agents/` as a tool
+ subagent in `agents/` as a tool

- in `.gemini/agents/` or `~/.gemini/agents/`, those take precedence
+ in `agents/` or your global configuration, those take precedence

[nucliweb]

After investigating, the reference to .gemini/agents/ in ship.toml is correct, reflecting Gemini CLI's official convention for project-level custom subagents, not a path in this repo.

Each tool has its own runtime directory for custom agents:

Tool	Custom agents directory
Gemini CLI	.gemini/agents/ (project) · ~/.gemini/agents/ (user)
Cursor	.cursor/agents/ (project) · ~/.cursor/agents/ (user)
GitHub Copilot	.github/agents/ (org) · ~/.github/agents/ (user)
Claude Code	.claude/agents/ (project) · ~/.claude/agents/ (user)

The agents/ directory at the repo root is the source location where agent definitions are maintained for development. When deploying to a specific tool, users copy them to the appropriate tool-specific directory, following the same pattern used for skills (skills/*/SKILL.md goes to .cursor/rules/, .gemini/skills/, etc.).

The Antigravity version using agents/ is a different tool with a different convention, not the reference implementation for Gemini CLI.

That said, there is a real documentation gap: gemini-cli-setup.md doesn't explain that users need to copy files from agents/ to .gemini/agents/ in their project for /ship to use parallel fan-out. The command has a graceful fallback to sequential execution, but that's not documented in the setup guide.

Closing this as not a bug, but the documentation gap in gemini-cli-setup.md would be worth a separate issue or PR.