github/spec-kit · error · ValueError

Run this command from the Spec Kit repository root.

Error message

Run this command from the Spec Kit repository root.

What it means

scaffold_integration is a maintainer tool: it generates files under src/specify_cli/integrations/ and tests/integrations/ inside the Spec Kit source repository itself. Before writing, it verifies the layout with _is_spec_kit_repo_root(project_root) and refuses otherwise. This error means the supplied project root does not look like the Spec Kit repo checkout.

Source

Thrown at src/specify_cli/integration_scaffold.py:220

def scaffold_integration(
    project_root: Path,
    key: str,
    integration_type: str,
) -> IntegrationScaffoldResult:
    """Create a minimal built-in integration package and test skeleton."""
    clean_key = _clean_key(key)
    normalized_type = integration_type.strip().lower()
    if normalized_type not in _TEMPLATES:
        supported = ", ".join(supported_integration_scaffold_types())
        raise ValueError(
            f"Unsupported integration type '{normalized_type}'. Use one of: {supported}."
        )

    integrations_root = project_root / "src" / "specify_cli" / "integrations"
    tests_root = project_root / "tests" / "integrations"
    if not _is_spec_kit_repo_root(project_root):
        raise ValueError("Run this command from the Spec Kit repository root.")

    package_name = _package_name(clean_key)
    class_name = _class_name(clean_key)
    integration_dir = integrations_root / package_name
    integration_file = integration_dir / "__init__.py"
    test_file = tests_root / f"test_integration_{package_name}.py"

    for target in (integration_file, test_file):
        _assert_safe_scaffold_target(project_root, target)

    existing = [path for path in (integration_file, test_file) if path.exists()]
    if existing:
        labels = ", ".join(path.relative_to(project_root).as_posix() for path in existing)
        raise FileExistsError(f"Refusing to overwrite existing scaffold file(s): {labels}")

    created_integration_dir = not integration_dir.exists()
    try:
        integration_dir.mkdir(exist_ok=True)

View on GitHub (pinned to bf88c9f9a8)

Solutions

1. Clone github/spec-kit (or your fork), and run the scaffold command from that repository root.
2. If adding a personal integration to an existing project, write the integration package by hand under src/specify_cli/integrations/ following AGENTS.md's Quickstart, instead of scaffolding outside the repo.
3. Verify the root with a quick check: `ls src/specify_cli/integrations tests/integrations` succeeds only in the real repo.

Example fix

# before (inside a user project)
$ cd ~/my-app && specify ... scaffold my-agent markdown
# after (inside the spec-kit clone)
$ cd ~/src/spec-kit && # run scaffold here

from pathlib import Path

def is_spec_kit_repo(root: Path) -> bool:
    return (root / "src" / "specify_cli" / "integrations").is_dir() and \
           (root / "tests" / "integrations").is_dir()

When it happens

Trigger: Calling scaffold_integration with a user project directory (a project created by `specify init`) instead of a clone of the spec-kit repository; running from a random directory where the src/specify_cli package layout is absent.

Common situations: Users running the scaffold command inside their own app project, expecting it to add a custom integration there (it cannot — it only generates files in the Spec Kit source tree); wrong cwd when invoking the CLI.

Related errors

• Unsupported integration type '{normalized_type}'. Use one of
• Refusing to scaffold outside the repository root: {target}
• specify event ${{command}} (${{event}}) failed: ${{(e as Err
• errors.join('; ')
• Error: --number requires a value

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