Handle standalone workflow path edge cases

Author: Copilot

docs/reference/workflows.md

@@ -20,7 +20,7 @@ Example:
 specify workflow run speckit -i spec="Build a kanban board with drag-and-drop task management" -i scope=full
 ```
 
-> **Note:** All workflow commands require a project already initialized with `specify init`.
+> **Note:** Most workflow commands require a project already initialized with `specify init`. The exception is `specify workflow run <local-file.yml|yaml>`, which can run outside a project; in that case, run state is stored under the current directory's `.specify/workflows/runs/<run_id>/`.
 
 ## Resume a Workflow
 

src/specify_cli/__init__.py

@@ -2727,8 +2727,8 @@ def workflow_run(
     """Run a workflow from an installed ID or local YAML path."""
     from .workflows.engine import WorkflowEngine
 
-    source_path = Path(source)
-    is_file_source = source_path.suffix in (".yml", ".yaml") and source_path.exists()
+    source_path = Path(source).expanduser()
+    is_file_source = source_path.suffix.lower() in (".yml", ".yaml") and source_path.exists()
 
     if is_file_source:
         # When running a YAML file directly, use cwd as project root
@@ -2741,7 +2741,7 @@ def workflow_run(
     engine.on_step_start = lambda sid, label: console.print(f"  \u25b8 [{sid}] {label} \u2026")
 
     try:
-        definition = engine.load_workflow(source)
+        definition = engine.load_workflow(source_path if is_file_source else source)
     except FileNotFoundError:
         console.print(f"[red]Error:[/red] Workflow not found: {source}")
         raise typer.Exit(1)

src/specify_cli/workflows/engine.py

@@ -403,10 +403,10 @@ def load_workflow(self, source: str | Path) -> WorkflowDefinition:
         ValueError:
             If the workflow YAML is invalid.
         """
-        path = Path(source)
+        path = Path(source).expanduser()
 
         # Try as a direct file path first
-        if path.suffix in (".yml", ".yaml") and path.exists():
+        if path.suffix.lower() in (".yml", ".yaml") and path.exists():
             return WorkflowDefinition.from_yaml(path)
 
         # Try as an installed workflow ID

tests/test_workflow_run_without_project.py

@@ -46,6 +46,49 @@ def test_workflow_run_yaml_without_project(self, tmp_path):
         assert result.exit_code == 0, f"workflow run failed: {result.output}"
         assert "completed" in result.output
         assert (tmp_path / "marker.txt").exists()
+        assert (tmp_path / ".specify" / "workflows" / "runs").is_dir()
+
+    def test_workflow_run_yaml_with_tilde_and_uppercase_suffix(self, tmp_path, monkeypatch):
+        """Running ~/file.YML should work without a .specify/ directory."""
+        from typer.testing import CliRunner
+        from specify_cli import app
+
+        runner = CliRunner()
+
+        home_dir = tmp_path / "home"
+        home_dir.mkdir()
+        monkeypatch.setenv("HOME", str(home_dir))
+
+        workflow_file = home_dir / "test-workflow.YML"
+        workflow_content = {
+            "schema_version": "1.0",
+            "workflow": {
+                "id": "standalone-test-uppercase",
+                "name": "Standalone Test Uppercase",
+                "version": "1.0.0",
+                "description": "A workflow that runs from ~/ with an uppercase suffix",
+            },
+            "steps": [
+                {
+                    "id": "create-marker",
+                    "type": "shell",
+                    "run": "echo done > marker.txt",
+                },
+            ],
+        }
+        workflow_file.write_text(yaml.dump(workflow_content), encoding="utf-8")
+
+        old_cwd = os.getcwd()
+        try:
+            os.chdir(tmp_path)
+            result = runner.invoke(app, [
+                "workflow", "run", "~/test-workflow.YML",
+            ], catch_exceptions=False)
+        finally:
+            os.chdir(old_cwd)
+        assert result.exit_code == 0, f"workflow run failed: {result.output}"
+        assert "Status: completed" in result.output
+        assert (tmp_path / "marker.txt").exists()
 
     def test_workflow_run_id_still_requires_project(self, tmp_path):
         """Running a workflow by ID should still require a .specify/ directory."""
@@ -117,4 +160,5 @@ def test_workflow_run_failing_yaml_without_project(self, tmp_path):
             ], catch_exceptions=False)
         finally:
             os.chdir(old_cwd)
-        assert "failed" in result.output.lower()
+        assert result.exit_code == 0, f"workflow run failed unexpectedly: {result.output}"
+        assert "Status: failed" in result.output