itdove/devaiflow#665: Clarify default-branch behavior for daf git new

devflow/cli/main.py

@@ -1610,7 +1610,10 @@ def git_open(ctx: click.Context, issue_key: str, repository: Optional[str], head
 @click.option("--goal-file", help="Explicit file path or URL for goal input (mutually exclusive with --goal)")
 @click.option("--name", help="Session name (auto-generated from goal if not provided)")
 @click.option("--path", help="Project path (bypasses interactive selection)")
-@click.option("--branch", help="Git branch name (bypasses interactive creation prompt)")
+@click.option(
+    "--branch",
+    help="Branch name to record in session metadata; it is not created or checked out",
+)
 @click.option("--parent", help="Parent issue key (owner/repo#123 or #123)")
 @workspace_option()
 @click.option("--projects", help="Comma-separated list of repository names for multi-project sessions (requires --workspace)")
@@ -1621,10 +1624,16 @@ def git_open(ctx: click.Context, issue_key: str, repository: Optional[str], head
 @click.option("--headless", is_flag=True, help="Run agent in headless mode (no interactive UI, exits after completion)")
 @click.option("--auto-approve", is_flag=True, help="Auto-approve all agent tool permissions (file edits, commands)")
 def git_new(ctx: click.Context, issue_type: Optional[str], goal: Optional[str], goal_file: Optional[str], name: str, path: str, branch: str, parent: Optional[str], workspace: str, projects: str, temp_clone: bool, repository: Optional[str], model_profile: str, model: str, headless: bool, auto_approve: bool) -> None:
-    """Create GitHub/GitLab issue with analysis-only session.
+    """Create a GitHub/GitLab issue with an analysis-only session.
+
+    This command does not create or select a working branch and does not show
+    the development branch picker. For a development session that should select
+    a starting branch, including the repository default, use ``daf new`` or
+    ``daf open`` instead. A supplied ``--branch`` is only recorded in session
+    metadata; it is not created or checked out.
 
     Creates a session with session_type="ticket_creation" that:
-    - Skips branch creation automatically
+    - Skips branch creation and checkout automatically
     - Provides analysis-only constraints in the initial prompt
     - Persists the session type for reopening
 

devflow/cli_skills/daf-git/SKILL.md

@@ -189,6 +189,12 @@ daf git new task --goal "Refactor auth module" --parent "#123"
 
 **Purpose:** Analyze the codebase to create a well-informed issue
 
+**Branch behavior:** `daf git new` is an analysis-only issue-creation workflow;
+it does not create or select a working branch or show the development branch
+picker. A supplied `--branch` is recorded only as session metadata and is not
+created or checked out. For development work that should select a starting
+branch, including the repository default, use `daf new` or `daf open` instead.
+
 **Template injection:** The prompt automatically includes issue body templates from config,
 repo `.github/ISSUE_TEMPLATE/` directory, or built-in defaults. Use them to structure
 well-formed issues with acceptance criteria.

devflow/cli_skills/daf-workflow/SKILL.md

@@ -278,6 +278,12 @@ conversation. Do not delete local work to resolve retention/recovery warnings.
 
 Analysis-only session for creating a GitHub/GitLab issue.
 
+This workflow does not create or select a working branch and does not show the
+development branch picker. A supplied `--branch` is recorded only in session
+metadata; it is not created or checked out. For development work that should
+select a starting branch, including the repository default, use `daf new` or
+`daf open` instead.
+
 **Temp directory session** — sync before analysis (see Step 5).
 
 **CRITICAL CONSTRAINTS:**

docs/workflows/github-gitlab-integration.md

@@ -140,6 +140,13 @@ daf git new --goal "Add user authentication to API"
 3. Claude helps you understand implementation complexity
 4. You create a detailed issue with accurate acceptance criteria
 
+This is an issue-creation workflow, not a development branch setup. The
+`daf git new` command does not create or select a working branch and does not
+show the development branch picker. A supplied `--branch` is recorded only in
+session metadata; it is not created or checked out. For development work that
+should select a starting branch, including the repository default, use `daf new`
+or `daf open` instead.
+
 **Inside Claude session:**
 
 ```bash

tests/test_git_issue_creation_guidance.py

@@ -2,20 +2,39 @@
 
 from pathlib import Path
 
+from click.testing import CliRunner
+
+from devflow.cli.main import cli
+
 SOURCE_ROOT = Path(__file__).parents[1] / "devflow"
 GIT_SKILL = SOURCE_ROOT / "cli_skills" / "daf-git" / "SKILL.md"
 CLI_SKILL = SOURCE_ROOT / "cli_skills" / "daf-cli" / "SKILL.md"
 WORKFLOW_SKILL = SOURCE_ROOT / "cli_skills" / "daf-workflow" / "SKILL.md"
 
 
+def test_git_new_help_explains_branch_behavior(temp_daf_home):
+    """The command help distinguishes issue creation from development branch setup."""
+    result = CliRunner().invoke(cli, ["git", "new", "--help"])
+
+    assert result.exit_code == 0
+    output = " ".join(result.output.split())
+    assert "does not create or select a working branch" in output
+    assert "does not show the development branch picker" in output
+    assert "daf new" in output
+    assert "daf open" in output
+    assert "record in session metadata" in output
+
+
 def test_git_skill_does_not_describe_jira_linking_for_git_issues():
     """The GitHub/GitLab skill must document the supported post-creation flow."""
-    content = GIT_SKILL.read_text(encoding="utf-8")
+    content = " ".join(GIT_SKILL.read_text(encoding="utf-8").split())
 
     assert "daf link" not in content
     assert "issue URL and key" in content
     assert "supported" in content
     assert "daf open <session-name>" in content
+    assert "development branch picker" in content
+    assert "daf new" in content
 
 
 def test_cli_skill_keeps_jira_linking_separate_from_git_issue_creation():
@@ -29,11 +48,14 @@ def test_cli_skill_keeps_jira_linking_separate_from_git_issue_creation():
 
 def test_workflow_skill_documents_git_issue_session_behavior():
     """The workflow skill must not promise an unsupported automatic rename."""
-    content = WORKFLOW_SKILL.read_text(encoding="utf-8")
+    content = " ".join(WORKFLOW_SKILL.read_text(encoding="utf-8").split())
     start = content.index("## GitHub/GitLab Issue Creation")
     end = content.index("## JIRA Ticket Creation", start)
     section = content[start:end]
 
     assert "issue URL and key" in section
     assert "daf open <session-name>" in section
     assert "automatically renamed" not in section
+    assert "does not create or select a working branch" in section
+    assert "daf new" in section
+    assert "daf open" in section