@mindfoldhq/trellis 0.3.5 → 0.3.7

package/dist/templates/markdown/spec/backend/script-conventions.md

@@ -23,8 +23,11 @@ All workflow scripts are written in **Python 3.10+** for cross-platform compatib
 │   ├── task_utils.py     # Task helper functions
 │   ├── phase.py          # Multi-agent phase tracking
 │   ├── registry.py       # Agent registry management
-│   ├── worktree.py       # Git worktree utilities
+│   ├── config.py         # Config reader (config.yaml, hooks)
+│   ├── worktree.py       # Git worktree utilities + YAML parser
 │   └── git_context.py    # Git/session context
+├── hooks/                # Lifecycle hook scripts (project-specific)
+│   └── linear_sync.py    # Example: sync tasks to Linear
 ├── multi_agent/          # Multi-agent pipeline scripts
 │   ├── __init__.py
 │   ├── start.py          # Start worktree agent
@@ -81,10 +84,19 @@ Task Management Script.
 
 Usage:
     python3 task.py create "<title>" [--slug <name>]
-    python3 task.py list [--mine] [--status <status>]
+    python3 task.py init-context <dir> <dev_type>
+    python3 task.py add-context <dir> <file> <reason>
+    python3 task.py validate <dir>
+    python3 task.py list-context <dir>
     python3 task.py start <dir>
     python3 task.py finish
+    python3 task.py set-branch <dir> <branch>
+    python3 task.py set-base-branch <dir> <branch>
+    python3 task.py set-scope <dir> <scope>
+    python3 task.py create-pr [dir] [--dry-run]
     python3 task.py archive <task-name>
+    python3 task.py list [--mine] [--status <status>]
+    python3 task.py list-archive [YYYY-MM]
 """
 
 from __future__ import annotations
@@ -202,11 +214,13 @@ def run_command(
 
 ## Cross-Platform Compatibility
 
-### CRITICAL: Windows stdout Encoding
+### CRITICAL: Windows stdio Encoding (stdout + stdin)
 
-On Windows, Python's stdout defaults to the system code page (e.g., GBK/CP936 in China, CP1252 in Western locales). This causes `UnicodeEncodeError` when printing non-ASCII characters.
+On Windows, Python's stdout AND stdin default to the system code page (e.g., GBK/CP936 in China, CP1252 in Western locales). This causes:
+- `UnicodeEncodeError` when **printing** non-ASCII characters (stdout)
+- `UnicodeDecodeError` when **reading piped** UTF-8 content (stdin), e.g. Chinese text via `cat << EOF | python3 script.py`
 
-**The Problem Chain**:
+**The Problem Chain (stdout)**:
 
 ```
 Windows code page = GBK (936)
@@ -220,60 +234,64 @@ json.dumps(ensure_ascii=False) → print()
 GBK cannot encode \ufffd → UnicodeEncodeError: 'gbk' codec can't encode character
 ```
 
-**Root Cause**: Even if you set `PYTHONIOENCODING` in subprocess calls, the **parent process's stdout** still uses the system code page. The error occurs when `print()` tries to write to stdout.
-
----
+**The Problem Chain (stdin)**:
 
-#### GOOD: Use `sys.stdout.reconfigure()` (Python 3.7+)
+```
+AI agent pipes UTF-8 content via heredoc: cat << 'EOF' | python3 add_session.py ...
+    ↓
+Python stdin defaults to GBK encoding (PowerShell default code page)
+    ↓
+sys.stdin.read() decodes bytes as GBK, not UTF-8
+    ↓
+Chinese text garbled or UnicodeDecodeError
+```
 
-```python
-import sys
+**Root Cause**: Even if you set `PYTHONIOENCODING` in subprocess calls, the **parent process's stdio** still uses the system code page.
 
-# MUST be at the top of the script, before any print() calls
-if sys.platform == "win32":
-    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
-    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
-```
+---
 
-**Why this works**: `reconfigure()` modifies the existing stream **in-place**, changing its encoding settings directly. This affects all subsequent writes to stdout.
+#### GOOD: Centralize encoding fix in `common/__init__.py`
 
-**Best Practice**: Add this to `common/__init__.py` so all scripts that `from common import ...` automatically get the fix:
+All stdio encoding is handled in one place. Scripts that `from common import ...` automatically get the fix:
 
 ```python
 # common/__init__.py
+import io
 import sys
 
-if sys.platform == "win32":
-    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
-    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+def _configure_stream(stream):
+    """Configure a stream for UTF-8 encoding on Windows."""
+    if hasattr(stream, "reconfigure"):
+        stream.reconfigure(encoding="utf-8", errors="replace")
+        return stream
+    elif hasattr(stream, "detach"):
+        return io.TextIOWrapper(stream.detach(), encoding="utf-8", errors="replace")
+    return stream
 
-# ... rest of exports
+if sys.platform == "win32":
+    sys.stdout = _configure_stream(sys.stdout)
+    sys.stderr = _configure_stream(sys.stderr)
+    sys.stdin = _configure_stream(sys.stdin)    # Don't forget stdin!
 ```
 
 ---
 
-#### BAD: Do NOT use `io.TextIOWrapper`
+#### DON'T: Inline encoding code in individual scripts
 
 ```python
-# BAD - This does NOT reliably fix the encoding issue!
+# BAD - Duplicated in every script, easy to forget stdin
 import sys
-import io
-
 if sys.platform == "win32":
-    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    # Forgot stdin! Piped Chinese text will break.
 ```
 
-**Why this fails**:
+**Why this is bad**:
+1. **Easy to forget streams**: stdout was fixed but stdin was missed in multiple scripts, causing real user bugs
+2. **Duplicated code**: Same logic copy-pasted across `add_session.py`, `git_context.py`, etc.
+3. **Inconsistent coverage**: Some scripts fix stdout only, others fix stdout+stderr, none fixed stdin
 
-1. **Creates a new wrapper, doesn't fix the underlying issue**: `TextIOWrapper` wraps `sys.stdout.buffer`, but the original stdout object and its encoding settings may still interfere in some code paths.
-
-2. **Loses original stdout properties**: The new wrapper may not preserve all attributes of the original `sys.stdout` (like `isatty()`, line buffering behavior).
-
-3. **Race condition with buffering**: If any output was buffered before the replacement, it may still be encoded with the old encoding.
-
-4. **Not idempotent**: Calling this multiple times creates nested wrappers, while `reconfigure()` is safe to call multiple times.
-
-**Real-world failure case**: Users reported that `io.TextIOWrapper` did not fix the `UnicodeEncodeError` on Windows, while `sys.stdout.reconfigure()` worked immediately.
+**Real-world failure**: Users on Windows reported garbled Chinese text when using `cat << EOF | python3 add_session.py`. Root cause: stdin was never reconfigured to UTF-8.
 
 ---
 
@@ -281,7 +299,8 @@ if sys.platform == "win32":
 
 | Method | Works? | Reason |
 |--------|--------|--------|
-| `sys.stdout.reconfigure(encoding="utf-8")` | ✅ Yes | Modifies stream in-place |
+| `common/__init__.py` centralized fix | ✅ Yes | All streams, all scripts, one place |
+| `sys.stdout.reconfigure(encoding="utf-8")` | ⚠️ Partial | Only stdout; easy to forget stdin/stderr |
 | `io.TextIOWrapper(sys.stdout.buffer, ...)` | ❌ No | Creates wrapper, doesn't fix underlying encoding |
 | `PYTHONIOENCODING=utf-8` env var | ⚠️ Partial | Only works if set **before** Python starts |
 
@@ -320,6 +339,169 @@ path = ".trellis/scripts/task.py"
 
 ---
 
+## Task Lifecycle Hooks
+
+### Scope / Trigger
+
+Task lifecycle events (`after_create`, `after_start`, `after_finish`, `after_archive`) execute user-defined shell commands configured in `config.yaml`.
+
+### Signatures
+
+```python
+# config.py — read hook commands from config
+def get_hooks(event: str, repo_root: Path | None = None) -> list[str]
+
+# task.py — execute hooks (never blocks main operation)
+def _run_hooks(event: str, task_json_path: Path, repo_root: Path) -> None
+```
+
+### Contracts
+
+**Config format** (`config.yaml`):
+```yaml
+hooks:
+  after_create:
+    - "python3 .trellis/scripts/hooks/my_hook.py create"
+  after_start:
+    - "python3 .trellis/scripts/hooks/my_hook.py start"
+  after_archive:
+    - "python3 .trellis/scripts/hooks/my_hook.py archive"
+```
+
+**Environment variables passed to hooks**:
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `TASK_JSON_PATH` | Absolute path string | Path to the task's `task.json` |
+
+- `cwd` is set to `repo_root`
+- Hooks inherit the parent process environment + `TASK_JSON_PATH`
+
+### Subprocess Execution
+
+```python
+import os
+import subprocess
+
+env = {**os.environ, "TASK_JSON_PATH": str(task_json_path)}
+
+result = subprocess.run(
+    cmd,
+    shell=True,
+    cwd=repo_root,
+    env=env,
+    capture_output=True,
+    text=True,
+    encoding="utf-8",    # REQUIRED: cross-platform
+    errors="replace",    # REQUIRED: cross-platform
+)
+```
+
+### Validation & Error Matrix
+
+| Condition | Behavior |
+|-----------|----------|
+| No `hooks` key in config | No-op (empty list) |
+| `hooks` is not a dict | No-op (empty list) |
+| Event key missing | No-op (empty list) |
+| Hook command exits non-zero | `[WARN]` to stderr, continues to next hook |
+| Hook command throws exception | `[WARN]` to stderr, continues to next hook |
+| `linearis` not installed | Hook fails with warning, task operation succeeds |
+
+### Wrong vs Correct
+
+#### Wrong — blocking on hook failure
+```python
+result = subprocess.run(cmd, shell=True, check=True)  # Raises on failure!
+```
+
+#### Correct — warn and continue
+```python
+try:
+    result = subprocess.run(cmd, shell=True, ...)
+    if result.returncode != 0:
+        print(f"[WARN] Hook failed: {cmd}", file=sys.stderr)
+except Exception as e:
+    print(f"[WARN] Hook error: {cmd} — {e}", file=sys.stderr)
+```
+
+### Hook Script Pattern
+
+Hook scripts that need project-specific config (API keys, user IDs) should:
+1. Store config in a **gitignored** local file (e.g., `.trellis/hooks.local.json`)
+2. Read config at startup, fail with clear message if missing
+3. Keep the script itself committable (no hardcoded secrets)
+
+```python
+# .trellis/scripts/hooks/my_hook.py — committable, no secrets
+CONFIG = _load_config()  # reads from .trellis/hooks.local.json (gitignored)
+TEAM = CONFIG.get("linear", {}).get("team", "")
+```
+
+---
+
+## Auto-Commit Pattern
+
+Scripts that modify `.trellis/` tracked files should auto-commit their changes to keep the workspace clean. Use a `--no-commit` flag for opt-out.
+
+### Convention: Auto-Commit After Mutation
+
+```python
+def _auto_commit(scope: str, message: str, repo_root: Path) -> None:
+    """Stage and commit changes in a specific .trellis/ subdirectory."""
+    subprocess.run(["git", "add", "-A", scope], cwd=repo_root, capture_output=True)
+    # Check if there are staged changes
+    result = subprocess.run(
+        ["git", "diff", "--cached", "--quiet", "--", scope],
+        cwd=repo_root,
+    )
+    if result.returncode == 0:
+        print("[OK] No changes to commit.", file=sys.stderr)
+        return
+    commit_result = subprocess.run(
+        ["git", "commit", "-m", message],
+        cwd=repo_root, capture_output=True, text=True,
+    )
+    if commit_result.returncode == 0:
+        print(f"[OK] Auto-committed: {message}", file=sys.stderr)
+    else:
+        print(f"[WARN] Auto-commit failed: {commit_result.stderr.strip()}", file=sys.stderr)
+```
+
+**Scripts using this pattern**:
+- `add_session.py` — commits `.trellis/workspace` + `.trellis/tasks` after recording a session
+- `task.py archive` — commits `.trellis/tasks` after archiving a task
+
+**Always add `--no-commit` flag** for scripts that auto-commit, so users can opt out.
+
+---
+
+## CLI Mode Extension Pattern
+
+### Design Decision: `--mode` for Context-Dependent Output
+
+When a script needs different output for different use cases, use `--mode` (not separate scripts or additional flags).
+
+**Example**: `get_context.py` serves two modes:
+- `--mode default` — full session context (DEVELOPER, GIT STATUS, RECENT COMMITS, CURRENT TASK, ACTIVE TASKS, MY TASKS, JOURNAL, PATHS)
+- `--mode record` — focused output for record-session (MY ACTIVE TASKS first with emphasis, GIT STATUS, RECENT COMMITS, CURRENT TASK)
+
+```python
+parser.add_argument(
+    "--mode", "-m",
+    choices=["default", "record"],
+    default="default",
+    help="Output mode: default (full context) or record (for record-session)",
+)
+```
+
+**When to add a new mode** (not a new script):
+- Output is a subset/reordering of the same data
+- The underlying data sources are shared
+- The difference is in presentation, not in data fetching
+
+---
+
 ## Error Handling
 
 ### Exit Codes

package/dist/templates/opencode/commands/trellis/brainstorm.md

@@ -387,6 +387,19 @@ Here's my understanding of the complete requirements:
 Does this look correct? If yes, I'll proceed with implementation.
 ```
 
+### Subtask Decomposition (Complex Tasks)
+
+For complex tasks with multiple independent work items, create subtasks:
+
+```bash
+# Create child tasks
+CHILD1=$(python3 ./.trellis/scripts/task.py create "Child task 1" --slug child1 --parent "$TASK_DIR")
+CHILD2=$(python3 ./.trellis/scripts/task.py create "Child task 2" --slug child2 --parent "$TASK_DIR")
+
+# Or link existing tasks
+python3 ./.trellis/scripts/task.py add-subtask "$TASK_DIR" "$CHILD_DIR"
+```
+
 ---
 
 ## PRD Target Structure (final)

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

@@ -12,7 +12,10 @@
 python3 ./.trellis/scripts/get_context.py --mode record
 ```
 
-[!] If MY ACTIVE TASKS shows any completed tasks, archive them FIRST:
+[!] Archive tasks whose work is **actually done** — judge by work status, not the `status` field in task.json:
+- Code committed? → Archive it (don't wait for PR)
+- All acceptance criteria met? → Archive it
+- Don't skip archiving just because `status` still says `planning` or `in_progress`
 
 ```bash
 python3 ./.trellis/scripts/task.py archive <task-name>

package/dist/templates/opencode/commands/trellis/start.md

@@ -45,6 +45,10 @@ cat .trellis/spec/backend/index.md   # Backend guidelines
 cat .trellis/spec/guides/index.md    # Thinking guides
 ```
 
+> **Important**: The index files are navigation — they list the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`).
+> At this step, just read the indexes to understand what's available.
+> When you start actual development, you MUST go back and read the specific guideline files relevant to your task, as listed in the index's Pre-Development Checklist.
+
 ### Step 4: Report and Ask
 
 Report what you learned and ask: "What would you like to work on?"
@@ -82,7 +86,7 @@ For questions or trivial fixes, work directly:
 
 ## Complex Task - Brainstorm First
 
-For complex or vague tasks, use the brainstorm process to clarify requirements.
+For complex or vague tasks, **automatically start the brainstorm process** — do NOT skip directly to implementation.
 
 See `/trellis:brainstorm` for the full process. Summary:
 
@@ -93,6 +97,10 @@ See `/trellis:brainstorm` for the full process. Summary:
 5. **Confirm final requirements** - Get explicit approval
 6. **Proceed to Task Workflow** - With clear requirements in PRD
 
+> **Subtask Decomposition**: If brainstorm reveals multiple independent work items,
+> consider creating subtasks using `--parent` flag or `add-subtask` command.
+> See `/trellis:brainstorm` Step 8 for details.
+
 ---
 
 ## Task Workflow (Development Tasks)

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

@@ -10,10 +10,97 @@
  * - Otherwise, this plugin handles injection
  */
 
-import { existsSync } from "fs"
+import { existsSync, readFileSync, readdirSync, statSync } from "fs"
 import { join } from "path"
 import { TrellisContext, contextCollector, debugLog } from "../lib/trellis-context.js"
 
+
+/**
+ * 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"
+  }
+
+  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)
+  }
+
+  if (!existsSync(taskDir)) {
+    return `Status: STALE POINTER\nTask: ${taskRef}\nNext: Task directory not found. Run: python3 ./.trellis/scripts/task.py finish`
+  }
+
+  // Read task.json
+  let taskData = {}
+  const taskJsonPath = join(taskDir, "task.json")
+  if (existsSync(taskJsonPath)) {
+    try {
+      taskData = JSON.parse(readFileSync(taskJsonPath, "utf-8"))
+    } catch {
+      // Ignore parse errors
+    }
+  }
+
+  const taskTitle = taskData.title || taskRef
+  const taskStatus = taskData.status || "unknown"
+
+  if (taskStatus === "completed") {
+    const dirName = taskDir.split("/").pop()
+    return `Status: COMPLETED\nTask: ${taskTitle}\nNext: Archive with \`python3 ./.trellis/scripts/task.py archive ${dirName}\` or start a new task`
+  }
+
+  // Check if context is configured (jsonl files exist and non-empty)
+  let hasContext = false
+  for (const jsonlName of ["implement.jsonl", "check.jsonl", "spec.jsonl"]) {
+    const jsonlPath = join(taskDir, jsonlName)
+    if (existsSync(jsonlPath)) {
+      try {
+        const st = statSync(jsonlPath)
+        if (st.size > 0) {
+          hasContext = true
+          break
+        }
+      } catch {
+        // Ignore stat errors
+      }
+    }
+  }
+
+  const hasPrd = existsSync(join(taskDir, "prd.md"))
+
+  if (!hasPrd) {
+    return `Status: NOT READY\nTask: ${taskTitle}\nMissing: prd.md not created\nNext: Write PRD, then research → init-context → start`
+  }
+
+  if (!hasContext) {
+    return `Status: NOT READY\nTask: ${taskTitle}\nMissing: Context not configured (no jsonl files)\nNext: Complete Phase 2 (research → init-context → start) before implementing`
+  }
+
+  return `Status: READY\nTask: ${taskTitle}\nNext: Continue with implement or check`
+}
+
 /**
  * Build session context for injection
  */
@@ -50,20 +137,60 @@ Read and follow all instructions below carefully.
     parts.push("</workflow>")
   }
 
-  // 4. Guidelines Index
+  // 4. Guidelines Index (dynamic discovery, matching Claude's session-start.py)
   parts.push("<guidelines>")
-
-  parts.push("## Frontend")
-  const frontendIndex = ctx.readProjectFile(".trellis/spec/frontend/index.md")
-  parts.push(frontendIndex || "Not configured")
-
-  parts.push("\n## Backend")
-  const backendIndex = ctx.readProjectFile(".trellis/spec/backend/index.md")
-  parts.push(backendIndex || "Not configured")
-
-  parts.push("\n## Guides")
-  const guidesIndex = ctx.readProjectFile(".trellis/spec/guides/index.md")
-  parts.push(guidesIndex || "Not configured")
+  parts.push("**Note**: The guidelines below are index files — they list available guideline documents and their locations.")
+  parts.push("During actual development, you MUST read the specific guideline files listed in each index's Pre-Development Checklist.\n")
+
+  const specDir = join(directory, ".trellis", "spec")
+  if (existsSync(specDir)) {
+    try {
+      const subs = readdirSync(specDir).filter(name => {
+        if (name.startsWith(".")) return false
+        try {
+          return statSync(join(specDir, name)).isDirectory()
+        } catch {
+          return false
+        }
+      }).sort()
+
+      for (const sub of subs) {
+        const indexFile = join(specDir, sub, "index.md")
+        if (existsSync(indexFile)) {
+          // Flat spec dir: spec/<layer>/index.md
+          const content = ctx.readFile(indexFile)
+          if (content) {
+            parts.push(`## ${sub}\n${content}\n`)
+          }
+        } else {
+          // Nested package dirs (monorepo): spec/<pkg>/<layer>/index.md
+          try {
+            const nested = readdirSync(join(specDir, sub)).filter(name => {
+              try {
+                return statSync(join(specDir, sub, name)).isDirectory()
+              } catch {
+                return false
+              }
+            }).sort()
+
+            for (const layer of nested) {
+              const nestedIndex = join(specDir, sub, layer, "index.md")
+              if (existsSync(nestedIndex)) {
+                const content = ctx.readFile(nestedIndex)
+                if (content) {
+                  parts.push(`## ${sub}/${layer}\n${content}\n`)
+                }
+              }
+            }
+          } catch {
+            // Ignore directory read errors
+          }
+        }
+      }
+    } catch {
+      // Ignore spec directory read errors
+    }
+  }
 
   parts.push("</guidelines>")
 
@@ -78,9 +205,15 @@ Read and follow all instructions below carefully.
     parts.push("</instructions>")
   }
 
-  // 6. Final directive
+  // 6. Task status (R2: check task state for session resume)
+  const taskStatus = getTaskStatus(directory)
+  parts.push(`<task-status>\n${taskStatus}\n</task-status>`)
+
+  // 7. Final directive (R3: active, not passive)
   parts.push(`<ready>
-Context loaded. Wait for user's first message, then follow <instructions> to handle their request.
+Context loaded. Steps 1-3 (workflow, context, guidelines) are already injected above — do NOT re-read them.
+Start from Step 4. Wait for user's first message, then follow <instructions> to handle their request.
+If there is an active task, ask whether to continue it.
 </ready>`)
 
   return parts.join("\n\n")

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

@@ -392,6 +392,19 @@ Here's my understanding of the complete requirements:
 Does this look correct? If yes, I'll proceed with implementation.
 ```
 
+### Subtask Decomposition (Complex Tasks)
+
+For complex tasks with multiple independent work items, create subtasks:
+
+```bash
+# Create child tasks
+CHILD1=$(python3 ./.trellis/scripts/task.py create "Child task 1" --slug child1 --parent "$TASK_DIR")
+CHILD2=$(python3 ./.trellis/scripts/task.py create "Child task 2" --slug child2 --parent "$TASK_DIR")
+
+# Or link existing tasks
+python3 ./.trellis/scripts/task.py add-subtask "$TASK_DIR" "$CHILD_DIR"
+```
+
 ---
 
 ## PRD Target Structure (final)

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

@@ -17,7 +17,10 @@ description: "Record work progress after human has tested and committed code"
 python3 ./.trellis/scripts/get_context.py --mode record
 ```
 
-[!] If MY ACTIVE TASKS shows any completed tasks, archive them FIRST:
+[!] Archive tasks whose work is **actually done** — judge by work status, not the `status` field in task.json:
+- Code committed? → Archive it (don't wait for PR)
+- All acceptance criteria met? → Archive it
+- Don't skip archiving just because `status` still says `planning` or `in_progress`
 
 ```bash
 python3 ./.trellis/scripts/task.py archive <task-name>