@mindfoldhq/trellis 0.4.0-beta.7 → 0.4.0-beta.9

package/dist/templates/kiro/skills/record-session/SKILL.md

@@ -51,6 +51,7 @@ EOF
 **Auto-completes**:
 - [OK] Appends session to journal-N.md
 - [OK] Auto-detects line count, creates new file if >2000 lines
+- [OK] Auto-detects Branch context (`--branch` override; otherwise Branch = task.json -> current git branch; missing values are omitted gracefully)
 - [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history)
 - [OK] Auto-commits .trellis/workspace and .trellis/tasks changes
 
@@ -61,6 +62,6 @@ EOF
 | Command | Purpose |
 |---------|---------|
 | `python3 ./.trellis/scripts/get_context.py --mode record` | Get context for record-session |
-| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended)** |
+| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended, branch auto-complete)** |
 | `python3 ./.trellis/scripts/task.py archive <name>` | Archive completed task (auto-commits) |
 | `python3 ./.trellis/scripts/task.py list` | List active tasks |

package/dist/templates/markdown/agents.md

@@ -13,6 +13,10 @@ Use `@/.trellis/` to learn:
 - Project structure guidelines (`spec/`)
 - Developer workspace (`workspace/`)
 
+If you're using Codex, project-scoped helpers may also live in:
+- `.agents/skills/` for reusable Trellis skills
+- `.codex/agents/` for optional custom subagents
+
 Keep this managed block so 'trellis update' can refresh the instructions.
 
 <!-- TRELLIS:END -->

package/dist/templates/markdown/spec/backend/directory-structure.md

@@ -239,7 +239,7 @@ Templates use `.txt` extension to:
 ```typescript
 import { downloadTemplate } from "giget";
 
-await downloadTemplate("gh:mindfold-ai/Trellis/marketplace/specs/electron-fullstack", {
+await downloadTemplate("gh:mindfold-ai/marketplace/specs/electron-fullstack", {
   dir: destDir,
   preferOffline: true,
 });

package/dist/templates/markdown/workspace-index.md

@@ -73,6 +73,7 @@ This will:
 
 Each session should include:
 - Summary: One-line description
+- Branch: Which branch the work was done on
 - Main Changes: What was modified
 - Git Commits: Commit hashes and messages
 - Next Steps: What to do next
@@ -88,6 +89,7 @@ Use this template when recording sessions:
 
 **Date**: YYYY-MM-DD
 **Task**: {task-name}
+**Branch**: `{branch-name}`
 
 ### Summary
 

package/dist/templates/opencode/agents/dispatch.md

@@ -71,6 +71,10 @@ Execute each step in `phase` order.
 
 > Hook will auto-inject all specs, requirements, and technical design to subagent context.
 > Dispatch only needs to issue simple call commands.
+>
+> **OpenCode dispatch rule**: Call subagents synchronously (`run_in_background: false`).
+> Do NOT use `TaskOutput` or background polling as the completion signal for child phases.
+> The background wrapper can finish before the real subagent session is actually done.
 
 ### action: "implement"
 
@@ -79,7 +83,7 @@ Task(
   subagent_type: "implement",
   prompt: "Implement the feature described in prd.md in the task directory",
   model: "opus",
-  run_in_background: true
+  run_in_background: false
 )
 ```
 
@@ -98,7 +102,7 @@ Task(
   subagent_type: "check",
   prompt: "Check code changes, fix issues yourself",
   model: "opus",
-  run_in_background: true
+  run_in_background: false
 )
 ```
 
@@ -116,7 +120,7 @@ Task(
   subagent_type: "debug",
   prompt: "Fix the issues described in the task context",
   model: "opus",
-  run_in_background: true
+  run_in_background: false
 )
 ```
 
@@ -132,7 +136,7 @@ Task(
   subagent_type: "check",
   prompt: "[finish] Execute final completion check before PR",
   model: "opus",
-  run_in_background: true
+  run_in_background: false
 )
 ```
 
@@ -168,27 +172,23 @@ This will:
 ### Basic Pattern
 
 ```
-task_id = Task(
+result = Task(
   subagent_type: "implement",  // or "check", "debug"
   prompt: "Simple task description",
   model: "opus",
-  run_in_background: true
+  run_in_background: false
 )
 
-// Poll for completion
-for i in 1..N:
-    result = TaskOutput(task_id, block=true, timeout=300000)
-    if result.status == "completed":
-        break
+// Wait for the Task call to return before starting the next phase.
+// Do NOT call TaskOutput or use background polling inside OpenCode dispatch.
 ```
 
-### Timeout Settings
+### Execution Rule
 
-| Phase | Max Time | Poll Count |
-|-------|----------|------------|
-| implement | 30 min | 6 times |
-| check | 15 min | 3 times |
-| debug | 20 min | 4 times |
+- Run one phase at a time
+- Start the next phase only after the current `Task(...)` call returns
+- If a phase returns a clear timeout or failure, handle that result explicitly
+- Do **not** simulate completion by polling a background task wrapper
 
 ---
 
@@ -196,7 +196,7 @@ for i in 1..N:
 
 ### Timeout
 
-If a subagent times out, notify the user and ask for guidance:
+If a synchronous subagent call times out, notify the user and ask for guidance:
 
 ```
 "Subagent {phase} timed out after {time}. Options:
@@ -207,10 +207,11 @@ If a subagent times out, notify the user and ask for guidance:
 
 ### Subagent Failure
 
-If a subagent reports failure, read the output and decide:
+If a synchronous subagent call reports failure, read the output and decide:
 
 - If recoverable: call debug agent to fix
 - If not recoverable: notify user and ask for guidance
+- Do not switch back to `TaskOutput` polling for the same phase
 
 ---
 

package/dist/templates/opencode/commands/trellis/record-session.md

@@ -46,6 +46,7 @@ EOF
 **Auto-completes**:
 - [OK] Appends session to journal-N.md
 - [OK] Auto-detects line count, creates new file if >2000 lines
+- [OK] Auto-detects Branch context (`--branch` override; otherwise Branch = task.json -> current git branch; missing values are omitted gracefully)
 - [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history)
 - [OK] Auto-commits .trellis/workspace and .trellis/tasks changes
 
@@ -56,6 +57,6 @@ EOF
 | Command | Purpose |
 |---------|---------|
 | `python3 ./.trellis/scripts/get_context.py --mode record` | Get context for record-session |
-| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended)** |
+| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended, branch auto-complete)** |
 | `python3 ./.trellis/scripts/task.py archive <name>` | Archive completed task (auto-commits) |
 | `python3 ./.trellis/scripts/task.py list` | List active tasks |

package/dist/templates/opencode/lib/trellis-context.js

@@ -11,7 +11,7 @@
  */
 
 import { existsSync, readFileSync, appendFileSync, readdirSync } from "fs"
-import { join } from "path"
+import { isAbsolute, join } from "path"
 import { homedir, platform } from "os"
 import { execSync } from "child_process"
 
@@ -191,12 +191,52 @@ export class TrellisContext {
       if (!existsSync(currentTaskPath)) {
         return null
       }
-      return readFileSync(currentTaskPath, "utf-8").trim()
+      const taskRef = readFileSync(currentTaskPath, "utf-8").trim()
+      const normalized = this.normalizeTaskRef(taskRef)
+      return normalized || null
     } catch {
       return null
     }
   }
 
+  normalizeTaskRef(taskRef) {
+    if (!taskRef) {
+      return ""
+    }
+
+    if (isAbsolute(taskRef)) {
+      return taskRef.trim()
+    }
+
+    let normalized = taskRef.trim().replace(/\\/g, "/")
+    while (normalized.startsWith("./")) {
+      normalized = normalized.slice(2)
+    }
+
+    if (normalized.startsWith("tasks/")) {
+      return `.trellis/${normalized}`
+    }
+
+    return normalized
+  }
+
+  resolveTaskDir(taskRef) {
+    const normalized = this.normalizeTaskRef(taskRef)
+    if (!normalized) {
+      return null
+    }
+
+    if (isAbsolute(normalized)) {
+      return normalized
+    }
+
+    if (normalized.startsWith(".trellis/")) {
+      return join(this.directory, normalized)
+    }
+
+    return join(this.directory, ".trellis", "tasks", normalized)
+  }
+
   // ============================================================
   // Hook Decision Logic
   // ============================================================

package/dist/templates/opencode/plugins/session-start.js

@@ -11,7 +11,7 @@
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from "fs"
-import { join } from "path"
+import { basename, join } from "path"
 import { execFileSync } from "child_process"
 import { platform } from "os"
 import { TrellisContext, contextCollector, debugLog } from "../lib/trellis-context.js"
@@ -23,36 +23,16 @@ const PYTHON_CMD = platform() === "win32" ? "python" : "python3"
  * Check current task status and return structured status string.
  * JavaScript equivalent of _get_task_status in Claude's session-start.py.
  */
-function getTaskStatus(directory) {
-  const trellisDir = join(directory, ".trellis")
-  const currentTaskFile = join(trellisDir, ".current-task")
-
-  if (!existsSync(currentTaskFile)) {
-    return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on"
-  }
-
-  let taskRef
-  try {
-    taskRef = readFileSync(currentTaskFile, "utf-8").trim()
-  } catch {
-    return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on"
-  }
-
+function getTaskStatus(ctx) {
+  const taskRef = ctx.getCurrentTask()
   if (!taskRef) {
     return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on"
   }
 
   // Resolve task directory
-  let taskDir
-  if (taskRef.startsWith("/")) {
-    taskDir = taskRef
-  } else if (taskRef.startsWith(".trellis/")) {
-    taskDir = join(directory, taskRef)
-  } else {
-    taskDir = join(trellisDir, "tasks", taskRef)
-  }
+  const taskDir = ctx.resolveTaskDir(taskRef)
 
-  if (!existsSync(taskDir)) {
+  if (!taskDir || !existsSync(taskDir)) {
     return `Status: STALE POINTER\nTask: ${taskRef}\nNext: Task directory not found. Run: python3 ./.trellis/scripts/task.py finish`
   }
 
@@ -71,7 +51,7 @@ function getTaskStatus(directory) {
   const taskStatus = taskData.status || "unknown"
 
   if (taskStatus === "completed") {
-    const dirName = taskDir.split("/").pop()
+    const dirName = basename(taskDir)
     return `Status: COMPLETED\nTask: ${taskTitle}\nNext: Archive with \`python3 ./.trellis/scripts/task.py archive ${dirName}\` or start a new task`
   }
 
@@ -354,7 +334,7 @@ Read and follow all instructions below carefully.
   }
 
   // 6. Task status (R2: check task state for session resume)
-  const taskStatus = getTaskStatus(directory)
+  const taskStatus = getTaskStatus(ctx)
   parts.push(`<task-status>\n${taskStatus}\n</task-status>`)
 
   // 7. Final directive (R3: active, not passive)

package/dist/templates/qoder/skills/record-session/SKILL.md

@@ -51,6 +51,7 @@ EOF
 **Auto-completes**:
 - [OK] Appends session to journal-N.md
 - [OK] Auto-detects line count, creates new file if >2000 lines
+- [OK] Auto-detects Branch context (`--branch` override; otherwise Branch = task.json -> current git branch; missing values are omitted gracefully)
 - [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history)
 - [OK] Auto-commits .trellis/workspace and .trellis/tasks changes
 
@@ -61,6 +62,6 @@ EOF
 | Command | Purpose |
 |---------|---------|
 | `python3 ./.trellis/scripts/get_context.py --mode record` | Get context for record-session |
-| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended)** |
+| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended, branch auto-complete)** |
 | `python3 ./.trellis/scripts/task.py archive <name>` | Archive completed task (auto-commits) |
 | `python3 ./.trellis/scripts/task.py list` | List active tasks |

package/dist/templates/trellis/scripts/add_session.py

@@ -5,17 +5,23 @@ Add a new session to journal file and update index.md.
 
 Usage:
     python3 add_session.py --title "Title" --commit "hash" --summary "Summary" [--package cli]
+    python3 add_session.py --title "Title" --branch "feat/my-branch"
 
     # Pipe detailed content via stdin (use --stdin to opt in):
     cat << 'EOF' | python3 add_session.py --stdin --title "Title" --summary "Summary"
     <session content here>
     EOF
+
+Branch resolution order:
+    1. --branch CLI arg (explicit)
+    2. task.json branch field (from active task)
+    3. git branch --show-current (auto-detect)
+    4. None (omitted gracefully)
 """
 
 from __future__ import annotations
 
 import argparse
-import json
 import re
 import subprocess
 import sys
@@ -30,6 +36,7 @@ from common.paths import (
     get_workspace_dir,
 )
 from common.developer import ensure_developer
+from common.git import run_git
 from common.tasks import load_task
 from common.config import (
     get_packages,
@@ -139,6 +146,7 @@ def generate_session_content(
     extra_content: str,
     today: str,
     package: str | None = None,
+    branch: str | None = None,
 ) -> str:
     """Generate session content."""
     if commit and commit != "-":
@@ -151,13 +159,14 @@ def generate_session_content(
         commit_table = "(No commits - planning session)"
 
     package_line = f"\n**Package**: {package}" if package else ""
+    branch_line = f"\n**Branch**: `{branch}`" if branch else ""
 
     return f"""
 
 ## Session {session_num}: {title}
 
 **Date**: {today}
-**Task**: {title}{package_line}
+**Task**: {title}{package_line}{branch_line}
 
 ### Summary
 
@@ -192,7 +201,8 @@ def update_index(
     commit: str,
     new_session: int,
     active_file: str,
-    today: str
+    today: str,
+    branch: str | None = None,
 ) -> bool:
     """Update index.md with new session info."""
     # Format commit for display
@@ -271,10 +281,25 @@ def update_index(
             continue
 
         if in_session_history:
-            new_lines.append(line)
-            if re.match(r"^\|\s*-", line) and not header_written:
-                new_lines.append(f"| {new_session} | {today} | {title} | {commit_display} |")
+            # Migrate old 4/6-column headers to 5-column Branch-only history.
+            if re.match(
+                r"^\|\s*#\s*\|\s*Date\s*\|\s*Title\s*\|\s*Commits\s*\|\s*Branch\s*\|\s*Base Branch\s*\|\s*$",
+                line,
+            ):
+                new_lines.append("| # | Date | Title | Commits | Branch |")
+                continue
+            if re.match(r"^\|\s*#\s*\|\s*Date\s*\|\s*Title\s*\|\s*Commits\s*\|\s*Branch\s*\|\s*$", line):
+                new_lines.append("| # | Date | Title | Commits | Branch |")
+                continue
+            if re.match(r"^\|\s*#\s*\|\s*Date\s*\|\s*Title\s*\|\s*Commits\s*\|\s*$", line):
+                new_lines.append("| # | Date | Title | Commits | Branch |")
+                continue
+            if re.match(r"^\|[-| ]+\|\s*$", line) and not header_written:
+                new_lines.append("|---|------|-------|---------|--------|")
+                new_lines.append(f"| {new_session} | {today} | {title} | {commit_display} | `{branch or '-'}` |")
                 header_written = True
+                continue
+            new_lines.append(line)
             continue
 
         new_lines.append(line)
@@ -291,11 +316,16 @@ def update_index(
 def _auto_commit_workspace(repo_root: Path) -> None:
     """Stage .trellis/workspace and .trellis/tasks, then commit with a configured message."""
     commit_msg = get_session_commit_message(repo_root)
-    subprocess.run(
+    add_result = subprocess.run(
         ["git", "add", "-A", ".trellis/workspace", ".trellis/tasks"],
         cwd=repo_root,
         capture_output=True,
+        text=True,
     )
+    if add_result.returncode != 0:
+        print(f"[WARN] git add failed (exit {add_result.returncode}): {add_result.stderr.strip()}", file=sys.stderr)
+        print("[WARN] Please commit .trellis/ changes manually: git add .trellis && git commit", file=sys.stderr)
+        return
     # Check if there are staged changes
     result = subprocess.run(
         ["git", "diff", "--cached", "--quiet", "--", ".trellis/workspace", ".trellis/tasks"],
@@ -323,6 +353,7 @@ def add_session(
     extra_content: str = "(Add details)",
     auto_commit: bool = True,
     package: str | None = None,
+    branch: str | None = None,
 ) -> int:
     """Add a new session."""
     repo_root = get_repo_root()
@@ -348,7 +379,8 @@ def add_session(
     new_session = current_session + 1
 
     session_content = generate_session_content(
-        new_session, title, commit, summary, extra_content, today, package
+        new_session, title, commit, summary, extra_content, today, package,
+        branch,
     )
     content_lines = len(session_content.splitlines())
 
@@ -385,7 +417,16 @@ def add_session(
 
     # Update index.md
     active_file = f"{FILE_JOURNAL_PREFIX}{target_num}.md"
-    if not update_index(index_file, dev_dir, title, commit, new_session, active_file, today):
+    if not update_index(
+        index_file,
+        dev_dir,
+        title,
+        commit,
+        new_session,
+        active_file,
+        today,
+        branch,
+    ):
         return 1
 
     print("", file=sys.stderr)
@@ -419,6 +460,7 @@ def main() -> int:
     parser.add_argument("--summary", default="(Add summary)", help="Brief summary")
     parser.add_argument("--content-file", help="Path to file with detailed content")
     parser.add_argument("--package", help="Package name tag (e.g., cli, docs-site)")
+    parser.add_argument("--branch", help="Branch name (auto-detected if omitted)")
     parser.add_argument("--no-commit", action="store_true",
                         help="Skip auto-commit of workspace changes")
     parser.add_argument("--stdin", action="store_true",
@@ -434,8 +476,11 @@ def main() -> int:
     elif args.stdin:
         extra_content = sys.stdin.read()
 
-    # Resolve package: CLI → active task → default_package → None
+    # Load active task once — shared by package and branch resolution
     repo_root = get_repo_root()
+    current = get_current_task(repo_root)
+    task_data = load_task(repo_root / current) if current else None
+
     package = args.package
     if package:
         # CLI source: fail-fast in monorepo, ignore in single-repo
@@ -449,18 +494,26 @@ def main() -> int:
             return 1
     else:
         # Inferred: active task's task.json.package → default_package → None
-        task_package = None
-        current = get_current_task(repo_root)
-        if current:
-            ct = load_task(repo_root / current)
-            if ct and ct.package:
-                task_package = ct.package
+        task_package = task_data.package if task_data else None
         package = resolve_package(task_package, repo_root)
 
+    # Resolve branch: CLI → task.json → git auto-detect → None
+    branch = args.branch
+
+    if not branch:
+        if task_data and task_data.raw.get("branch"):
+            branch = task_data.raw["branch"]
+        else:
+            _, branch_out, _ = run_git(["branch", "--show-current"], cwd=repo_root)
+            detected = branch_out.strip()
+            if detected:
+                branch = detected
+
     return add_session(
         args.title, args.commit, args.summary, extra_content,
         auto_commit=not args.no_commit,
         package=package,
+        branch=branch,
     )
 
 

package/dist/templates/trellis/scripts/common/__init__.py

@@ -75,6 +75,8 @@ from .paths import (
     count_lines,
     get_current_task,
     get_current_task_abs,
+    normalize_task_ref,
+    resolve_task_ref,
     set_current_task,
     clear_current_task,
     has_current_task,