github/spec-kit · error · ValueError

--commands-dir is required for the generic integration

Error message

--commands-dir is required for the generic integration

What it means

Raised by GenericIntegration._resolve_commands_dir() (src/specify_cli/integrations/generic/__init__.py:83) when neither parsed_options ("commands_dir") nor raw_options contains a usable --commands-dir value. The generic integration is stateless — its output directory is not in config — so the caller must supply --commands-dir at call time; token parsing finds no '--commands-dir' or '--commands-dir=' token with a non-empty value and raises ValueError.

Source

Thrown at src/specify_cli/integrations/generic/__init__.py:83

        if commands_dir and (not isinstance(commands_dir, str) or commands_dir.strip()):
            return commands_dir

        # Fall back to raw_options (--integration-options="--commands-dir ...")
        raw = opts.get("raw_options")
        if raw:
            import shlex
            tokens = shlex.split(raw)
            for i, token in enumerate(tokens):
                if token == "--commands-dir" and i + 1 < len(tokens):
                    candidate = tokens[i + 1]
                    if candidate.strip():
                        return candidate
                if token.startswith("--commands-dir="):
                    candidate = token.split("=", 1)[1]
                    if candidate.strip():
                        return candidate

        raise ValueError(
            "--commands-dir is required for the generic integration"
        )

    def commands_dest(self, project_root: Path) -> Path:
        """Not supported for GenericIntegration — use setup() directly.

        GenericIntegration is stateless; the output directory comes from
        ``parsed_options`` or ``raw_options`` at call time, not from
        instance state.
        """
        raise ValueError(
            "GenericIntegration.commands_dest() cannot be called directly; "
            "the output directory is resolved from parsed_options in setup()"
        )

    def setup(
        self,
        project_root: Path,

View on GitHub (pinned to bf88c9f9a8)

Solutions

Pass commands_dir in parsed_options: setup(root, manifest, parsed_options={"commands_dir": "myagent/commands"}).
Or include --integration-options="--commands-dir myagent/commands" on the specify CLI.
Ensure the value is non-empty after shlex.split if passed via raw_options.
Check for the '=' form being given a blank value.

Example fix

# before
GenericIntegration().setup(project_root, manifest, parsed_options={})

# after
GenericIntegration().setup(
    project_root, manifest, parsed_options={"commands_dir": ".myagent/commands"}
)

Defensive patterns

Strategy: validation

Validate before calling

opts = parsed_options or {}
if not opts.get("commands_dir"):
    raise SystemExit(
        "generic integration requires --commands-dir "
        "(or parsed_options['commands_dir'])"
    )

Type guard

def has_commands_dir(parsed_options: dict | None, raw_options: str | None) -> bool:
    if parsed_options and str(parsed_options.get("commands_dir", "")).strip():
        return True
    if raw_options and "--commands-dir" in raw_options:
        import shlex
        for i, t in enumerate(shlex.split(raw_options)):
            if t == "--commands-dir" and i + 1 < len(shlex.split(raw_options)):
                return True
            if t.startswith("--commands-dir=") and t.split("=", 1)[1].strip():
                return True
    return False

Try / catch

try:
    integration.setup(root, manifest, parsed_options=opts)
except ValueError as e:
    if "--commands-dir is required" in str(e):
        opts = {**(opts or {}), "commands_dir": ".agent/commands"}
        integration.setup(root, manifest, parsed_options=opts)
    else:
        raise

Prevention

Always pass commands_dir in parsed_options when driving the generic integration programmatically.
On the CLI, use --integration-options="--commands-dir <dir>" with a non-empty value.
Check the option string with shlex.split mentally — quoting errors make it parse empty.

When it happens

Trigger: Calling GenericIntegration().setup(project_root, manifest) with parsed_options lacking 'commands_dir' and raw_options lacking '--commands-dir <dir>' or '--commands-dir=<dir>'; or passing an empty value ('--commands-dir=' with blank string).

Common situations: Using the generic integration programmatically and forgetting the option; passing the flag via a different options string that shlex splits unexpectedly; quoting issues where '--commands-dir=' receives an empty value; CLI invocation missing --integration-options.

Related errors

AI-assisted analysis of github/spec-kit@bf88c9f9a8 (2026-08-14). Data as JSON: /api/errors/1ddbcd0fcb0a1c10. Report an issue: GitHub.