@mindfoldhq/trellis 0.4.0-beta.1 → 0.4.0-beta.10

package/dist/templates/iflow/hooks/session-start.py

@@ -66,23 +66,47 @@ def run_script(script_path: Path) -> str:
         return "No context available"
 
 
+def _normalize_task_ref(task_ref: str) -> str:
+    normalized = task_ref.strip()
+    if not normalized:
+        return ""
+
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return str(path_obj)
+
+    normalized = normalized.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+
+    if normalized.startswith("tasks/"):
+        return f".trellis/{normalized}"
+
+    return normalized
+
+
+def _resolve_task_dir(trellis_dir: Path, task_ref: str) -> Path:
+    normalized = _normalize_task_ref(task_ref)
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return path_obj
+    if normalized.startswith(".trellis/"):
+        return trellis_dir.parent / path_obj
+    return trellis_dir / "tasks" / path_obj
+
+
 def _get_task_status(trellis_dir: Path) -> str:
     """Check current task status and return structured status string."""
     current_task_file = trellis_dir / ".current-task"
     if not current_task_file.is_file():
         return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on"
 
-    task_ref = current_task_file.read_text(encoding="utf-8").strip()
+    task_ref = _normalize_task_ref(current_task_file.read_text(encoding="utf-8").strip())
     if not task_ref:
         return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on"
 
     # Resolve task directory
-    if Path(task_ref).is_absolute():
-        task_dir = Path(task_ref)
-    elif task_ref.startswith(".trellis/"):
-        task_dir = trellis_dir.parent / task_ref
-    else:
-        task_dir = trellis_dir / "tasks" / task_ref
+    task_dir = _resolve_task_dir(trellis_dir, task_ref)
     if not task_dir.is_dir():
         return f"Status: STALE POINTER\nTask: {task_ref}\nNext: Task directory not found. Run: python3 ./.trellis/scripts/task.py finish"
 
@@ -131,8 +155,8 @@ def _load_trellis_config(trellis_dir: Path) -> tuple:
         sys.path.insert(0, str(scripts_dir))
 
     try:
-        from common.config import get_default_package, get_packages, get_spec_scope, is_monorepo
-        from common.paths import get_current_task
+        from common.config import get_default_package, get_packages, get_spec_scope, is_monorepo  # type: ignore[import-not-found]
+        from common.paths import get_current_task  # type: ignore[import-not-found]
 
         repo_root = trellis_dir.parent
         is_mono = is_monorepo(repo_root)

package/dist/templates/kilo/workflows/record-session.md

@@ -1,6 +1,6 @@
 [!] **Prerequisite**: This command should only be used AFTER the human has tested and committed the code.
 
-**AI must NOT execute git commit** - only read history (`git log`, `git status`, `git diff`).
+**Do NOT run `git commit` directly** — the scripts below handle their own commits for `.trellis/` metadata. You only need to read git history (`git log`, `git status`, `git diff`) and run the Python scripts.
 
 ---
 
@@ -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/kiro/skills/before-dev/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: before-dev
-description: "Read the relevant development guidelines before starting your task."
+description: "Discovers and injects project-specific coding guidelines from .trellis/spec/ before implementation begins. Reads spec indexes, pre-development checklists, and shared thinking guides for the target package. Use when starting a new coding task, before writing any code, switching to a different package, or needing to refresh project conventions and standards."
 ---
 
 Read the relevant development guidelines before starting your task.

package/dist/templates/kiro/skills/brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorm
-description: "Brainstorm - Requirements Discovery (AI Coding Enhanced)"
+description: "Collaborative requirements discovery session optimized for AI coding workflows. Creates task directories, seeds PRDs, runs codebase research, proposes concrete implementation approaches with trade-offs, and converges on MVP scope through structured Q&A. Use when requirements are unclear, multiple implementation paths exist, trade-offs need evaluation, or a complex feature needs scoping before development."
 ---
 
 # Brainstorm - Requirements Discovery (AI Coding Enhanced)

package/dist/templates/kiro/skills/break-loop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: break-loop
-description: "Break the Loop - Deep Bug Analysis"
+description: "Deep post-fix bug analysis across five dimensions: root cause categorization, fix failure analysis, prevention mechanisms, systematic expansion, and knowledge capture. Updates .trellis/spec/ guides with lessons learned to prevent recurring bugs. Use when a debugging session completes, after fixing a tricky bug, when the same class of bug keeps recurring, or when you want to capture debugging insights into project documentation."
 ---
 
 # Break the Loop - Deep Bug Analysis

package/dist/templates/kiro/skills/check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: check
-description: "Check if the code you just wrote follows the development guidelines."
+description: "Validates recently written code against project-specific development guidelines from .trellis/spec/. Identifies changed files via git diff, discovers applicable spec modules, runs lint and typecheck, and reports guideline violations. Use when code is written and needs quality verification, to catch context drift during long sessions, or before committing changes."
 ---
 
 Check if the code you just wrote follows the development guidelines.

package/dist/templates/kiro/skills/check-cross-layer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: check-cross-layer
-description: "Cross-Layer Check"
+description: "Post-implementation verification across multiple code dimensions: cross-layer data flow, code reuse analysis, import path validation, and same-layer consistency checks. Identifies missed update sites, type mismatches, and duplicated constants. Use when changes span 3+ architectural layers, after modifying shared constants or configs, after batch file modifications, or when creating new utility functions."
 ---
 
 # Cross-Layer Check

package/dist/templates/kiro/skills/create-command/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-command
-description: "Create New Skill"
+description: "Scaffolds a new skill file with proper naming conventions and structure. Analyzes requirements to determine skill type and generates appropriate content. Use when adding a new developer workflow skill, creating a custom skill, or extending the Trellis skill set."
 ---
 
 # Create New Skill

package/dist/templates/kiro/skills/finish-work/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: finish-work
-description: "Finish Work - Pre-Commit Checklist"
+description: "Pre-commit quality checklist covering lint, typecheck, tests, code-spec sync, API changes, database migrations, cross-layer verification, and manual testing. Blocks commit if infra or cross-layer specs lack executable depth. Use when code is written and tested but not yet committed, before submitting changes, or as a final review before git commit."
 ---
 
 # Finish Work - Pre-Commit Checklist

package/dist/templates/kiro/skills/integrate-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: integrate-skill
-description: "Integrate Skill into Project Guidelines"
+description: "Adapts an external skill into project-specific development guidelines in .trellis/spec/. Creates guideline sections, code example templates with .template suffix, and updates spec indexes. Use when integrating an external skill, adding a new skill's patterns to project conventions, or incorporating third-party skill best practices into .trellis/spec/ documentation."
 ---
 
 # Integrate Skill into Project Guidelines

package/dist/templates/kiro/skills/onboard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: onboard
-description: "PART 3: Customize Your Development Guidelines"
+description: "Interactive three-part onboarding for new team members to the Trellis AI-assisted workflow system. Covers core philosophy (AI memory, project-specific knowledge, context drift), system structure and command deep-dives, real-world workflow examples, and guideline customization. Use when a new developer joins the project, someone needs to understand the Trellis workflow, or project guidelines need initial setup."
 ---
 
 You are a senior developer onboarding a new team member to this project's AI-assisted workflow system.

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

@@ -1,11 +1,11 @@
 ---
 name: record-session
-description: "Record work progress after human has tested and committed code"
+description: "Records completed work progress to .trellis/workspace/ journal files after human testing and commit. Captures session summaries, commit hashes, and updates developer index files for future session context. Use when a coding session is complete, after the human has committed code, or to persist session knowledge for future AI sessions."
 ---
 
 [!] **Prerequisite**: This skill should only be used AFTER the human has tested and committed the code.
 
-**AI must NOT execute git commit** - only read history (`git log`, `git status`, `git diff`).
+**Do NOT run `git commit` directly** — the scripts below handle their own commits for `.trellis/` metadata. You only need to read git history (`git log`, `git status`, `git diff`) and run the Python scripts.
 
 ---
 
@@ -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/kiro/skills/start/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: start
-description: "Start Session"
+description: "Initializes an AI development session by reading workflow guides, developer identity, git status, active tasks, and project guidelines from .trellis/. Classifies incoming tasks and routes to brainstorm, direct edit, or task workflow. Use when beginning a new coding session, resuming work, starting a new task, or re-establishing project context."
 ---
 
 # Start Session

package/dist/templates/kiro/skills/update-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: update-spec
-description: "Update Code-Spec - Capture Executable Contracts"
+description: "Captures executable contracts and coding knowledge into .trellis/spec/ documents after implementation, debugging, or design decisions. Enforces code-spec depth for infra and cross-layer changes with mandatory sections for signatures, contracts, validation matrices, and test points. Use when a feature is implemented, a bug is fixed, a design decision is made, a new pattern is discovered, or cross-layer contracts change."
 ---
 
 # Update Code-Spec - Capture Executable Contracts

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

@@ -1,6 +1,6 @@
 [!] **Prerequisite**: This command should only be used AFTER the human has tested and committed the code.
 
-**AI must NOT execute git commit** - only read history (`git log`, `git status`, `git diff`).
+**Do NOT run `git commit` directly** — the scripts below handle their own commits for `.trellis/` metadata. You only need to read git history (`git log`, `git status`, `git diff`) and run the Python scripts.
 
 ---
 
@@ -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/{plugin → 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/before-dev/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: before-dev
-description: "Read the relevant development guidelines before starting your task."
+description: "Discovers and injects project-specific coding guidelines from .trellis/spec/ before implementation begins. Reads spec indexes, pre-development checklists, and shared thinking guides for the target package. Use when starting a new coding task, before writing any code, switching to a different package, or needing to refresh project conventions and standards."
 ---
 
 Read the relevant development guidelines before starting your task.

package/dist/templates/qoder/skills/brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorm
-description: "Brainstorm - Requirements Discovery (AI Coding Enhanced)"
+description: "Collaborative requirements discovery session optimized for AI coding workflows. Creates task directories, seeds PRDs, runs codebase research, proposes concrete implementation approaches with trade-offs, and converges on MVP scope through structured Q&A. Use when requirements are unclear, multiple implementation paths exist, trade-offs need evaluation, or a complex feature needs scoping before development."
 ---
 
 # Brainstorm - Requirements Discovery (AI Coding Enhanced)

package/dist/templates/qoder/skills/break-loop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: break-loop
-description: "Break the Loop - Deep Bug Analysis"
+description: "Deep post-fix bug analysis across five dimensions: root cause categorization, fix failure analysis, prevention mechanisms, systematic expansion, and knowledge capture. Updates .trellis/spec/ guides with lessons learned to prevent recurring bugs. Use when a debugging session completes, after fixing a tricky bug, when the same class of bug keeps recurring, or when you want to capture debugging insights into project documentation."
 ---
 
 # Break the Loop - Deep Bug Analysis

package/dist/templates/qoder/skills/check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: check
-description: "Check if the code you just wrote follows the development guidelines."
+description: "Validates recently written code against project-specific development guidelines from .trellis/spec/. Identifies changed files via git diff, discovers applicable spec modules, runs lint and typecheck, and reports guideline violations. Use when code is written and needs quality verification, to catch context drift during long sessions, or before committing changes."
 ---
 
 Check if the code you just wrote follows the development guidelines.

package/dist/templates/qoder/skills/check-cross-layer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: check-cross-layer
-description: "Cross-Layer Check"
+description: "Post-implementation verification across multiple code dimensions: cross-layer data flow, code reuse analysis, import path validation, and same-layer consistency checks. Identifies missed update sites, type mismatches, and duplicated constants. Use when changes span 3+ architectural layers, after modifying shared constants or configs, after batch file modifications, or when creating new utility functions."
 ---
 
 # Cross-Layer Check

package/dist/templates/qoder/skills/create-command/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-command
-description: "Create New Skill"
+description: "Scaffolds a new skill file with proper naming conventions and structure. Analyzes requirements to determine skill type and generates appropriate content. Use when adding a new developer workflow skill, creating a custom skill, or extending the Trellis skill set."
 ---
 
 # Create New Skill

package/dist/templates/qoder/skills/finish-work/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: finish-work
-description: "Finish Work - Pre-Commit Checklist"
+description: "Pre-commit quality checklist covering lint, typecheck, tests, code-spec sync, API changes, database migrations, cross-layer verification, and manual testing. Blocks commit if infra or cross-layer specs lack executable depth. Use when code is written and tested but not yet committed, before submitting changes, or as a final review before git commit."
 ---
 
 # Finish Work - Pre-Commit Checklist

package/dist/templates/qoder/skills/integrate-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: integrate-skill
-description: "Integrate Skill into Project Guidelines"
+description: "Adapts an external skill into project-specific development guidelines in .trellis/spec/. Creates guideline sections, code example templates with .template suffix, and updates spec indexes. Use when integrating an external skill, adding a new skill's patterns to project conventions, or incorporating third-party skill best practices into .trellis/spec/ documentation."
 ---
 
 # Integrate Skill into Project Guidelines

package/dist/templates/qoder/skills/onboard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: onboard
-description: "PART 3: Customize Your Development Guidelines"
+description: "Interactive three-part onboarding for new team members to the Trellis AI-assisted workflow system. Covers core philosophy (AI memory, project-specific knowledge, context drift), system structure and command deep-dives, real-world workflow examples, and guideline customization. Use when a new developer joins the project, someone needs to understand the Trellis workflow, or project guidelines need initial setup."
 ---
 
 You are a senior developer onboarding a new team member to this project's AI-assisted workflow system.

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

@@ -1,11 +1,11 @@
 ---
 name: record-session
-description: "Record work progress after human has tested and committed code"
+description: "Records completed work progress to .trellis/workspace/ journal files after human testing and commit. Captures session summaries, commit hashes, and updates developer index files for future session context. Use when a coding session is complete, after the human has committed code, or to persist session knowledge for future AI sessions."
 ---
 
 [!] **Prerequisite**: This command should only be used AFTER the human has tested and committed the code.
 
-**AI must NOT execute git commit** - only read history (`git log`, `git status`, `git diff`).
+**Do NOT run `git commit` directly** — the scripts below handle their own commits for `.trellis/` metadata. You only need to read git history (`git log`, `git status`, `git diff`) and run the Python scripts.
 
 ---
 
@@ -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 |