[Bug]: opencode integration dispatch fails — uses unsupported `-p` flag instead of `run` subcommand

[markuswondrak]

Bug Description

When dispatching workflow commands via the opencode integration, OpencodeIntegration inherits build_exec_args() from MarkdownIntegration, which generates ["opencode", "-p", "/speckit.specify ..."]. The opencode CLI does not support the -p short flag — it uses --prompt (long form only) for prompt input, and the intended headless dispatch mode is opencode run [message..].

When opencode receives the unrecognized -p flag, it prints its full help text and exits — the workflow step sees exit code 0 but no actual output, causing the step to fail silently.

Steps to Reproduce

1. Initialize a project with opencode: specify init --ai opencode
2. Run a workflow: specify workflow run speckit --input spec="build a login page" --input integration=opencode
3. Observe: opencode prints its CLI help text instead of executing the /speckit.specify command
4. The workflow step fails with empty stdout/stderr and exit_code: 0 (help exits successfully)

Expected Behavior

The workflow should dispatch opencode run "/speckit.specify build a login page" which:

• Uses the run subcommand (headless/batch mode, not interactive TUI)
• Processes the slash-command from .opencode/command/speckit.specify.md
• Runs to completion and exits with the appropriate exit code

Actual Behavior

The inherited build_exec_args() generates ["opencode", "-p", "/speckit.specify build a login page"]. Since -p is not a valid opencode flag, opencode prints its help text and exits — no command is executed.

Environment

• Specify CLI Version: 0.8.3.dev0
• AI Agent: opencode
• Operating System: Linux x86_64
• Python: 3.12.3

Error Output

$ specify workflow run speckit \
    --input spec="$(cat ./01_chat_mvp.md)" \
    --input integration=opencode

Running workflow: Full SDD Cycle (speckit)
Version: 1.0.0

  ▸  speckit.specify …

[opencode prints full CLI help text — same output as `opencode --help`]

Root Cause

Code location: src/specify_cli/integrations/opencode/__init__.py (21 lines)

OpencodeIntegration does NOT override build_exec_args(). It inherits from MarkdownIntegration which hardcodes -p:

# src/specify_cli/integrations/base.py, lines 833-847
class MarkdownIntegration(IntegrationBase):
    def build_exec_args(self, prompt, *, model=None, output_json=True):
        if not self.config or not self.config.get("requires_cli"):
            return None
        args = [self.key, "-p", prompt]     # ← "-p" invalid for opencode
        if model:
            args.extend(["--model", model])  # ← opencode uses "-m"
        if output_json:
            args.extend(["--output-format", "json"])  # ← not supported
        return args

Other integrations with non-standard CLI dispatch DO override build_exec_args() — e.g., CopilotIntegration (copilot/__init__.py line 127). OpencodeIntegration should do the same.

Proposed Fix

Override build_exec_args() in OpencodeIntegration:

def build_exec_args(self, prompt, *, model=None, output_json=True):
    """Build CLI args for opencode headless dispatch via ``run`` subcommand."""
    args = [self.key, "run", prompt]
    if model:
        args.extend(["-m", model])
    return args

Key changes:

1. Replace -p flag with run subcommand (opencode headless/batch mode)
2. Use -m instead of --model (matches opencode actual flag)
3. Drop --output-format json (not supported by opencode)

Additional Context

The "auto" integration resolution (which reads .specify/integration.json) works correctly — when a project is initialized with --ai opencode, the engine correctly resolves the integration key to "opencode". The bug is solely in the CLI argument construction.

A full forensic analysis with evidence chain is documented in the repo.

[markuswondrak]

Scope extends beyond opencode — systematic build_exec_args() audit

While investigating this bug, I audited all 28 integrations and found that the root cause is not specific to opencode — it's a systematic architectural weakness in how build_exec_args() is inherited.

Current state

Only 4 out of 15 CLI-capable integrations have verified, correct build_exec_args() implementations:

Integration	Base class	CLI invocation	Status
Claude	SkillsIntegration	claude -p "prompt" --model X --output-format json	✅ Verified (-p is documented)
Gemini	TomlIntegration	gemini -p "prompt" -m X --output-format json	✅ Verified (-p and -m are documented)
Codex	SkillsIntegration	codex exec "prompt" --model X --json	✅ Custom override with exec subcommand
Copilot	IntegrationBase	copilot -p "prompt" --agent X --yolo --model X --output-format json	✅ Custom override with dynamic --yolo

The remaining 11 integrations with requires_cli: True all inherit build_exec_args() from their base class without verification that the CLI actually supports the generated flags:

Integration	Inherited invocation	Risk
OpenCode	opencode -p "prompt" --model X --output-format json	❌ Confirmed broken — should be opencode run "prompt" -m X
Amp	amp -p "prompt" --model X --output-format json	⚠️ Unverified
Auggie	auggie -p "prompt" --model X --output-format json	⚠️ Unverified
CodeBuddy	codebuddy -p "prompt" --model X --output-format json	⚠️ Unverified
Forge	forge -p "prompt" --model X --output-format json	⚠️ Unverified
iFlow	iflow -p "prompt" --model X --output-format json	⚠️ Unverified
Junie	junie -p "prompt" --model X --output-format json	⚠️ Unverified
Kiro CLI	kiro-cli -p "prompt" --model X --output-format json	⚠️ Unverified
Pi	pi -p "prompt" --model X --output-format json	⚠️ Unverified
QoderCLI	qodercli -p "prompt" --model X --output-format json	⚠️ Unverified
Qwen	qwen -p "prompt" --model X --output-format json	⚠️ Unverified

Additionally, 3 SkillsIntegration-based CLIs (Kimi, Shai, Vibe) and 1 TomlIntegration-based CLI (Tabnine) inherit the same -p pattern without verification.

There's also a data inconsistency: Goose has requires_cli: True but inherits from YamlIntegration, which doesn't override build_exec_args() — so it returns None, meaning CLI dispatch silently fails despite claiming CLI support.

Root cause

MarkdownIntegration.build_exec_args() hardcodes three assumptions that don't hold for all CLIs:

1. Prompt mechanism: -p flag (works for Claude/Gemini) vs. run/exec subcommand (opencode/codex) vs. other formats
2. Model flag: --model long form (most) vs. -m short form (Gemini, opencode) vs. not supported
3. JSON output: --output-format json (most) vs. --json (Codex) vs. -f json (opencode) vs. not supported

Every deviation requires a full method override, which is easy to forget (as the opencode bug shows).

Proposed fix: Declarative batch-mode attributes

Instead of requiring each integration to override build_exec_args(), introduce class-level attributes on IntegrationBase that make the common variations declarative:

class IntegrationBase(ABC):
    exec_mode: str = "flag"           # "flag" | "subcommand" | "none"
    exec_prompt_flag: str = "-p"      # flag used when exec_mode="flag"
    exec_subcommand: str = ""          # subcommand when exec_mode="subcommand"
    exec_model_flag: str = "--model"   # "--model" or "-m"
    exec_json_args: tuple[str, ...] = ("--output-format", "json")  # or ("--json",) or ()

Then build_exec_args() on IntegrationBase uses these attributes, and most integrations need zero method overrides:

# OpencodeIntegration — just attributes, no method override
class OpencodeIntegration(MarkdownIntegration):
    key = "opencode"
    exec_mode = "subcommand"
    exec_subcommand = "run"
    exec_model_flag = "-m"
    exec_json_args = ()
    ...

# CodexIntegration — just attributes, no method override
class CodexIntegration(SkillsIntegration):
    key = "codex"
    exec_mode = "subcommand"
    exec_subcommand = "exec"
    exec_json_args = ("--json",)
    ...

Complex cases like Copilot (dynamic --yolo flag) still override build_exec_args() directly.

This makes CLI invocation patterns visible at a glance in the integration class, eliminates an entire class of bugs, and reduces boilerplate from ~15 lines per override to ~4 lines of attributes.

I have a detailed implementation plan ready — happy to submit a PR that fixes the opencode bug and introduces the declarative architecture in one go, or as separate PRs if preferred.

[markuswondrak]

Created new issue for that: #2416