---
phase: 06-developer-experience
plan: 06-01
type: execute
---

<objective>
Implement missing utility functions for project detection, directory management, and workflow saving.

Purpose: Provide essential helper functions that support local-first workflow management and intelligent project detection for the CLI.
Output: Complete set of utility functions in utils.py with comprehensive test coverage.
</objective>

<execution_context>
~/.claude/get-shit-done/workflows/execute-phase.md
./summary.md
~/.claude/get-shit-done/references/tdd.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@REQUIREMENTS.md (lines 661-753: Utility Functions specification)
@src/n8n_cli/utils.py (existing: sanitize_filename, find_workflow_file)
@pyproject.toml
</context>

<tasks>

<task type="auto" tdd="true">
  <name>Task 1: Implement project and directory utility functions</name>
  <files>src/n8n_cli/utils.py, tests/test_utils.py</files>
  <test-first>
    Test: detect_project_context() returns project from .n8n/config.json
    Test: detect_project_context() returns project from workflows/project-name/ path
    Test: detect_project_context() returns None when no context found
    Test: get_workflows_dir() returns Path("workflows")
    Test: get_project_dir("My Project") returns Path("workflows/my-project")
  </test-first>
  <action>
    Implement four utility functions following REQUIREMENTS.md specification (lines 705-738):

    1. detect_project_context() -> str | None:
       - Check .n8n/config.json for {"project": "name"}
       - Check if cwd contains "workflows" in path parts, return next part
       - Return None if no context found

    2. get_workflows_dir() -> Path:
       - Return Path("workflows")

    3. get_project_dir(project_name: str) -> Path:
       - Return Path("workflows") / sanitize_filename(project_name)

    4. Import json module for detect_project_context JSON parsing

    Follow existing code style: type hints, docstrings with Args/Returns/Examples sections.
  </action>
  <verify>pytest tests/test_utils.py -v passes all tests</verify>
  <done>All four utility functions implemented with passing tests covering normal and edge cases</done>
</task>

<task type="auto" tdd="true">
  <name>Task 2: Implement save_workflow utility function</name>
  <files>src/n8n_cli/utils.py, tests/test_utils.py</files>
  <test-first>
    Test: save_workflow(workflow, None) creates workflows/workflow-name.json
    Test: save_workflow(workflow, "My Project") creates workflows/my-project/workflow-name.json
    Test: save_workflow creates parent directories if they don't exist
    Test: save_workflow writes valid JSON with 2-space indentation
  </test-first>
  <action>
    Implement save_workflow(workflow: dict, project_name: str | None = None) -> Path following REQUIREMENTS.md spec (lines 740-753):

    - If project_name: use get_project_dir(project_name)
    - Else: use get_workflows_dir()
    - Create directory with parents=True, exist_ok=True
    - Generate filename from workflow["name"] using sanitize_filename()
    - Write JSON with indent=2 (standard Python JSON formatting)
    - Return Path to saved file

    Include comprehensive docstring with Args/Returns/Examples.
  </action>
  <verify>pytest tests/test_utils.py::test_save_workflow -v passes, ruff check passes</verify>
  <done>save_workflow function correctly saves workflows to appropriate directories with proper JSON formatting</done>
</task>

</tasks>

<verification>
Before declaring plan complete:
- [ ] pytest tests/test_utils.py passes with all new tests
- [ ] ruff check src/n8n_cli/utils.py passes
- [ ] mypy src/n8n_cli/utils.py passes
- [ ] All utility functions have comprehensive docstrings
- [ ] Test coverage for new functions >80%
</verification>

<success_criteria>

- detect_project_context() implemented with .n8n/config.json and path detection
- get_workflows_dir() and get_project_dir() implemented
- save_workflow() implemented with directory creation and JSON writing
- All functions have type hints and docstrings
- Comprehensive test suite covering normal and edge cases
- All tests passing
- No linting or type errors
  </success_criteria>

<output>
After completion, create `.planning/phases/06-developer-experience/06-01-SUMMARY.md`:

# Phase 6 Plan 1: Utility Functions Summary

**[Substantive one-liner - what shipped, not "phase complete"]**

## Accomplishments

- detect_project_context() for intelligent project detection
- Directory helper functions (get_workflows_dir, get_project_dir)
- save_workflow() for writing workflow JSON to appropriate locations
- Comprehensive test coverage for all utility functions

## Files Created/Modified

- `src/n8n_cli/utils.py` - Added 4 new utility functions
- `tests/test_utils.py` - Comprehensive tests for all utilities

## Decisions Made

[Document any implementation choices or deviations from spec]

## Issues Encountered

[Problems and resolutions, or "None"]

## Next Step

Ready for **06-02-PLAN.md (Progressive Verbosity Standardization)**.
</output>
