steerdev 1.0.35__tar.gz → 1.0.37__tar.gz

{steerdev-1.0.35 → steerdev-1.0.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steerdev
-Version: 1.0.35
+Version: 1.0.37
 Summary: Backend task runner for steerdev.com - orchestrates CLI coding agents with activity reporting
 Project-URL: Homepage, https://github.com/pentoai/steerdev-agent
 Project-URL: Repository, https://github.com/pentoai/steerdev-agent

{steerdev-1.0.35 → steerdev-1.0.37}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "steerdev"
-version = "1.0.35"
+version = "1.0.37"
 description = "Backend task runner for steerdev.com - orchestrates CLI coding agents with activity reporting"
 readme = "README.md"
 authors = [

{steerdev-1.0.35 → steerdev-1.0.37}/src/steerdev_agent/cli.py

@@ -1145,40 +1145,83 @@ git_app = typer.Typer(
 app.add_typer(git_app)
 
 
+def _slugify(text: str, max_length: int = 48) -> str:
+    """Convert text to a git-safe branch slug.
+
+    Lowercases, replaces non-alphanumeric chars with hyphens, collapses
+    consecutive hyphens, and trims to max_length.
+    """
+    import re
+
+    slug = text.lower().strip()
+    slug = re.sub(r"[^a-z0-9]+", "-", slug)
+    slug = slug.strip("-")
+    # Trim to max_length without cutting mid-word
+    if len(slug) > max_length:
+        slug = slug[:max_length].rsplit("-", 1)[0]
+    return slug
+
+
 @git_app.command("branch")
 def git_branch(
     task_id: Annotated[
         str | None,
-        typer.Argument(help="Task ID to create branch for (uses first 8 chars)"),
+        typer.Argument(help="Task ID to create branch for"),
     ] = None,
     name: Annotated[
         str | None,
-        typer.Option("--name", "-n", help="Custom branch name suffix"),
+        typer.Option(
+            "--name",
+            "-n",
+            help="Custom branch name slug (overrides auto-slug)",
+        ),
     ] = None,
 ) -> None:
     """Create a task branch with steerdev naming convention.
 
-    Creates a branch named `task/<task-id-short>` or `task/<task-id-short>-<name>`.
-    Uses the first 8 characters of the task ID for the branch name.
+    Fetches the task from the API to resolve the external ticket identifier
+    (e.g. Linear ID) and auto-generates a descriptive branch name.
+
+    Branch naming priority:
+      1. External ticket ID + slug:  task/<LINEAR-ID>-<slug>
+      2. External ticket ID only:    task/<LINEAR-ID>
+      3. Fallback (no ticket ID):    task/<short-uuid>[-<slug>]
 
     Example:
         steerdev git branch abc12345-...
-        # Creates: task/abc12345
+        # Fetches task, finds Linear ID "PROJ-123", title "Add user auth"
+        # Creates: task/PROJ-123-add-user-auth
+
+        steerdev git branch abc12345-... --name custom-slug
+        # Creates: task/PROJ-123-custom-slug
 
-        steerdev git branch abc12345-... --name auth-flow
-        # Creates: task/abc12345-auth-flow
+        # If no Linear ID exists, falls back to short UUID:
+        # Creates: task/abc12345-add-user-auth
     """
     import subprocess
 
+    from steerdev_agent.api.tasks import TasksClient
+
     if not task_id:
         console.print("[red]Error: Task ID is required[/red]")
         raise typer.Exit(1)
 
-    # Use first 8 chars of task ID
-    short_id = task_id[:8]
-    branch_name = f"task/{short_id}"
-    if name:
-        branch_name = f"task/{short_id}-{name}"
+    # Fetch task to get external identifier and title
+    linear_id: str | None = None
+    task_title: str | None = None
+    with TasksClient() as client:
+        if client.check_api_key():
+            task = client.get_task(task_id)
+            if task:
+                linear_id = task.get("linear_identifier")
+                task_title = task.get("title")
+
+    # Build branch name: prefer external ticket ID over internal UUID
+    prefix = linear_id or task_id[:8]
+
+    # Determine the slug: explicit --name, or auto-generated from title
+    slug = name or (_slugify(task_title) if task_title else None)
+    branch_name = f"task/{prefix}-{slug}" if slug else f"task/{prefix}"
 
     try:
         # Check if branch already exists
@@ -1200,7 +1243,7 @@ def git_branch(
                 Panel(
                     f"[bold green]Branch created[/bold green]\n\n"
                     f"Branch: {branch_name}\n"
-                    f"Task ID: {task_id}",
+                    f"Task ID: {task_id}" + (f"\nLinear ID: {linear_id}" if linear_id else ""),
                     title="Success",
                     border_style="green",
                 )

{steerdev-1.0.35 → steerdev-1.0.37}/src/steerdev_agent/prompt/builder.py

@@ -38,6 +38,9 @@ class TaskContext(BaseModel):
     status: str = Field(default="unstarted", description="Task status")
     priority: int = Field(default=3, description="Task priority (1=urgent, 4=low)")
     working_directory: str | None = Field(default=None, description="Task working directory")
+    linear_identifier: str | None = Field(
+        default=None, description="External ticket ID (e.g. Linear PROJ-123)"
+    )
     spec: str | None = Field(default=None, description="Technical specification")
     metadata: dict[str, Any] | None = Field(default=None, description="Additional metadata")
     wave: WaveContext | None = Field(
@@ -181,6 +184,7 @@ class PromptBuilder:
             priority=task.priority,
             status=task.status,
             working_directory=working_dir,
+            linear_identifier=task.linear_identifier,
         )
 
         # Add spec if present

{steerdev-1.0.35 → steerdev-1.0.37}/src/steerdev_agent/prompt/templates.py

@@ -22,6 +22,7 @@ class PromptTemplates:
 
 **Title:** {title}
 **ID:** {task_id}
+**Ticket:** {ticket_id}
 **Priority:** {priority}
 **Status:** {status}
 
@@ -299,6 +300,7 @@ Include what you accomplished, key decisions, files changed, and anything the ne
         priority: int = 3,
         status: str = "unstarted",
         working_directory: str = ".",
+        linear_identifier: str | None = None,
     ) -> str:
         """Format task information.
 
@@ -309,6 +311,7 @@ Include what you accomplished, key decisions, files changed, and anything the ne
             priority: Task priority (1-4).
             status: Task status.
             working_directory: Working directory.
+            linear_identifier: External ticket ID (e.g. Linear PROJ-123).
 
         Returns:
             Formatted task information.
@@ -319,6 +322,7 @@ Include what you accomplished, key decisions, files changed, and anything the ne
         return cls.TASK_PROMPT.format(
             title=title,
             task_id=task_id,
+            ticket_id=linear_identifier or "N/A",
             priority=priority_display,
             status=status,
             prompt=prompt,

{steerdev-1.0.35 → steerdev-1.0.37}/src/steerdev_agent/runner.py

@@ -489,6 +489,7 @@ class Runner:
                 status=task.get("status", "unstarted"),
                 priority=task.get("priority", 3),
                 working_directory=task.get("working_directory"),
+                linear_identifier=task.get("linear_identifier"),
                 wave=wave_context,
             ),
         )

{steerdev-1.0.35 → steerdev-1.0.37}/src/steerdev_agent/setup/templates/skills/steerdev-merge-into-canal-skill/SKILL.md

@@ -1,5 +1,7 @@
 # Merge Into Canal Skill
 
+> **IMPORTANT: This skill is opt-in only.** Only use it when the `--canals` flag was explicitly passed to `steerdev run` or `steerdev agent`. If you are unsure whether canals are enabled, use `steerdev-wave-tasks-merge-skill` or `steerdev-single-task-merge-skill` instead.
+
 Use this skill when a workflow phase tells you to merge the **current task branch or wave branch into a canal**.
 
 ## When to Use

{steerdev-1.0.35 → steerdev-1.0.37}/src/steerdev_agent/setup/templates/skills/steerdev-single-task-merge-skill/SKILL.md

@@ -6,7 +6,7 @@ Use this skill when a workflow phase tells you to complete **one task on one bra
 
 - The workflow prompt explicitly references `single-task-merge`
 - `--no-waves` is active, or no wave context is present
-- `--no-canals` is active
+- Canals are not explicitly enabled for this project (canal mode requires `--canals` flag and explicit setup)
 
 ## Expected Outcome
 
@@ -45,6 +45,11 @@ Before creating your task branch, ensure you're starting from an up-to-date defa
 steerdev git branch TASK_ID [--name NAME]
 ```
 
+This fetches the task from the API and builds the branch name automatically:
+- If the task has an external ticket ID (e.g. Linear `PROJ-123`): `task/PROJ-123-<slug-from-title>`
+- If no external ID exists: `task/<short-uuid>-<slug-from-title>`
+- Use `--name` to override the auto-generated slug
+
 3. Implement the requested changes
 4. Commit with a conventional commit message that explains why the change exists
 5. Push the current branch:
@@ -62,9 +67,20 @@ steerdev git pr --title "TITLE" --task-id TASK_ID [--body "BODY"]
 7. Update the task result with the PR URL
 8. Log completion in the root `docs/` progress files
 
+## Branch Naming Convention
+
+Branch names should link to the external ticket tracker (e.g. Linear) for traceability on GitHub:
+
+| Has External ID? | Format | Example |
+|---|---|---|
+| Yes | `task/<TICKET-ID>-<slug>` | `task/PROJ-123-add-user-auth` |
+| No  | `task/<short-uuid>-<slug>` | `task/abc12345-add-user-auth` |
+
+**Why this matters:** GitHub integrations (Linear, Jira, etc.) match ticket IDs in branch names to link PRs/branches back to issues. Using internal UUIDs breaks this linkage.
+
 ## Conventions
 
-- Branch naming should follow `task/<short-task-id>` unless the workflow prompt says otherwise
+- Always use `steerdev git branch` to create branches (it resolves the external ticket ID automatically)
 - Create exactly one PR for the task
 - Include the PR URL in the task result summary
 
@@ -73,10 +89,12 @@ steerdev git pr --title "TITLE" --task-id TASK_ID [--body "BODY"]
 ```bash
 steerdev tasks update abc12345... --status started
 steerdev git branch abc12345...
+# → Creates: task/PROJ-123-add-user-authentication (if Linear ID exists)
+# → Creates: task/abc12345-add-user-authentication (fallback)
 # ... implement changes ...
 git add .
 git commit -m "feat: add user authentication"
 git push -u origin HEAD
-steerdev git pr --title "Add user authentication" --task-id abc12345...
+steerdev git pr --title "PROJ-123: Add user authentication" --task-id abc12345...
 steerdev tasks update abc12345... --result "PR: https://github.com/org/repo/pull/42"
 ```

{steerdev-1.0.35 → steerdev-1.0.37}/src/steerdev_agent/setup/templates/skills/steerdev-task-management-skill/SKILL.md

@@ -120,7 +120,11 @@ Create a new task for discovered work items.
 4. Implement the requested change.
 5. Verify web/UI changes visually with `agent-browser`.
 6. Add task comments when useful for blockers, handoffs, or status notes.
-7. Update the task result and status when the active workflow reaches completion.
+7. Merge and create a PR using the appropriate merge skill:
+   - **Wave tasks** (task has wave context): use `steerdev-wave-tasks-merge-skill`
+   - **Standalone tasks** (no wave context): use `steerdev-single-task-merge-skill`
+   - **Canal merge** (`steerdev-merge-into-canal-skill`): only when `--canals` was explicitly passed — do NOT use this by default
+8. Update the task result and status when the active workflow reaches completion.
 
 **IMPORTANT**: Always write progress logs. See the **steerdev-progress-logging-skill** for details.
 

{steerdev-1.0.35 → steerdev-1.0.37}/src/steerdev_agent/setup/templates/skills/steerdev-wave-tasks-merge-skill/SKILL.md

@@ -6,7 +6,7 @@ Use this skill when a workflow phase tells you to complete **multiple related ta
 
 - The workflow prompt explicitly references `wave-tasks-merge`
 - `--waves` is active and wave context is present
-- `--no-canals` is active
+- Canals are not explicitly enabled for this project (canal mode requires `--canals` flag and explicit setup)
 
 ## Expected Outcome
 
@@ -40,7 +40,15 @@ git checkout -b wave/<wave-number>
 2. For each task in the wave:
 - Mark the task `started`
 - Implement the requested change
-- Commit with a task-prefixed conventional commit, such as `[task:<id>] feat: ...`
+- Commit with a task-prefixed conventional commit. **Use the external ticket ID when available** (e.g. Linear ID), falling back to the internal short ID:
+
+```bash
+# With external ticket ID (preferred):
+git commit -m "[PROJ-123] feat: add user endpoint"
+
+# Fallback (no external ID):
+git commit -m "[task:abc12345] feat: add user endpoint"
+```
 
 3. After the wave work is ready for review, push the shared branch:
 
@@ -57,26 +65,40 @@ steerdev git pr --title "Wave <N>: <description>" --body "..."
 5. Update all related tasks with the shared PR URL
 6. Log progress and completion in the root `docs/` progress files
 
+## Commit Prefix Convention
+
+Use external ticket IDs in commits so GitHub integrations can link commits to issues:
+
+| Has External ID? | Commit Prefix | Example |
+|---|---|---|
+| Yes | `[<TICKET-ID>]` | `[PROJ-123] feat: add user endpoint` |
+| No  | `[task:<short-uuid>]` | `[task:abc12345] feat: add user endpoint` |
+
+Run `steerdev tasks get TASK_ID` to find the task's `linear_identifier` before committing.
+
 ## Conventions
 
 - Use one branch per wave: `wave/<wave-number>`
 - Do not create per-task PRs inside the wave
-- Keep commits traceable by including `[task:<id>]` in each task-specific commit
+- Keep commits traceable by including the external ticket ID (or internal ID fallback) in each commit
 - Include the shared PR URL in every related task result
 
 ## Example
 
 ```bash
 git checkout -b wave/3
+
 steerdev tasks update task-aaa... --status started
+# Check: steerdev tasks get task-aaa... → Linear ID: PROJ-123
 # ... implement task 1 ...
 git add .
-git commit -m "[task:task-aaa] feat: add user endpoint"
+git commit -m "[PROJ-123] feat: add user endpoint"
 
 steerdev tasks update task-bbb... --status started
+# Check: steerdev tasks get task-bbb... → Linear ID: PROJ-124
 # ... implement task 2 ...
 git add .
-git commit -m "[task:task-bbb] fix: validate email format"
+git commit -m "[PROJ-124] fix: validate email format"
 
 git push -u origin HEAD
 steerdev git pr --title "Wave 3: User management improvements" --body "..."