@mindfoldhq/trellis 0.6.2 → 0.6.3

package/dist/templates/claude/hooks/statusline.py

@@ -0,0 +1,324 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Trellis StatusLine — project-level status display for Claude Code.
+
+Reads Claude Code session JSON from stdin + Trellis task data from filesystem.
+Outputs 1-2 lines:
+  With active task:  [P1] Task title (status)  +  info line
+  Without task:      info line only
+Info line: model · ctx% · branch · duration · developer · tasks · rate limits
+When COLUMNS (injected by Claude Code v2.1.153+) is too narrow for the info
+line, the rate-limit segments move to their own line via an explicit "\n".
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+# Fix: Windows Python defaults to GBK encoding, which corrupts UTF-8
+# characters like the middle dot (·). Wrap stdout/stderr with UTF-8.
+if sys.platform == "win32":
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if callable(reconfigure):
+            reconfigure(encoding="utf-8", errors="replace")
+
+
+def _read_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except (FileNotFoundError, PermissionError, OSError):
+        return ""
+
+
+def _read_json(path: Path) -> dict:
+    text = _read_text(path)
+    if not text:
+        return {}
+    try:
+        return json.loads(text)
+    except (json.JSONDecodeError, ValueError):
+        return {}
+
+
+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 _find_trellis_dir() -> Path | None:
+    """Walk up from cwd to find .trellis/ directory."""
+    current = Path.cwd()
+    for parent in [current, *current.parents]:
+        candidate = parent / ".trellis"
+        if candidate.is_dir():
+            return candidate
+    return None
+
+
+def _get_current_task(trellis_dir: Path) -> dict | None:
+    """Load current task info through Trellis' active task resolver."""
+    return _get_current_task_for_input(trellis_dir, {})
+
+
+def _get_current_task_for_input(trellis_dir: Path, cc_data: dict) -> dict | None:
+    """Load current task info for the Claude Code session JSON."""
+    scripts_dir = trellis_dir / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+    try:
+        from common.active_task import resolve_active_task  # type: ignore[import-not-found]
+    except Exception:
+        return None
+
+    active = resolve_active_task(trellis_dir.parent, cc_data, platform="claude")
+    if not active.task_path:
+        return None
+
+    task_path = _resolve_task_dir(trellis_dir, active.task_path)
+    if active.stale:
+        return {
+            "title": task_path.name,
+            "status": "stale",
+            "priority": "P?",
+            "source": active.source,
+        }
+
+    task_data = _read_json(task_path / "task.json")
+    if not task_data:
+        return None
+
+    return {
+        "title": task_data.get("title") or task_data.get("name") or "unknown",
+        "status": task_data.get("status", "unknown"),
+        "priority": task_data.get("priority", "P2"),
+        "source": active.source,
+    }
+
+
+def _count_active_tasks(trellis_dir: Path) -> int:
+    """Count non-archived task directories with valid task.json."""
+    tasks_dir = trellis_dir / "tasks"
+    if not tasks_dir.is_dir():
+        return 0
+    count = 0
+    for d in tasks_dir.iterdir():
+        if d.is_dir() and d.name != "archive" and (d / "task.json").is_file():
+            count += 1
+    return count
+
+
+def _get_developer(trellis_dir: Path) -> str:
+    content = _read_text(trellis_dir / ".developer")
+    if not content:
+        return "unknown"
+    for line in content.splitlines():
+        if line.startswith("name="):
+            return line[5:].strip()
+    return content.splitlines()[0].strip() or "unknown"
+
+
+def _get_git_branch() -> str:
+    try:
+        result = subprocess.run(
+            ["git", "branch", "--show-current"],
+            capture_output=True, text=True, timeout=3,
+        )
+        return result.stdout.strip() if result.returncode == 0 else ""
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return ""
+
+
+def _format_ctx_size(size: int) -> str:
+    if size >= 1_000_000:
+        return f"{size // 1_000_000}M"
+    if size >= 1_000:
+        return f"{size // 1_000}K"
+    return str(size)
+
+
+def _format_duration(ms: int) -> str:
+    secs = ms // 1000
+    hours, remainder = divmod(secs, 3600)
+    mins = remainder // 60
+    if hours > 0:
+        return f"{hours}h{mins}m"
+    return f"{mins}m"
+
+
+def _format_remaining(secs: int) -> str:
+    if secs <= 0:
+        return ""
+    days, remainder = divmod(secs, 86400)
+    hours, remainder = divmod(remainder, 3600)
+    mins = remainder // 60
+    if days > 0:
+        return f"{days}d{hours}h"
+    if hours > 0:
+        return f"{hours}h{mins}m"
+    return f"{mins}m"
+
+
+def _parse_resets_at(value: object) -> int:
+    """`resets_at` is epoch seconds (int/float, possibly stringified) or an
+    ISO-8601 timestamp depending on Claude Code version. Return epoch
+    seconds, or 0 when absent/unparseable (countdown is then omitted)."""
+    if isinstance(value, (int, float)):
+        return int(value)
+    if isinstance(value, str) and value:
+        try:
+            return int(float(value))
+        except ValueError:
+            pass
+        try:
+            parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+            return int(parsed.timestamp())
+        except ValueError:
+            pass
+    return 0
+
+
+def _rate_limit_part(label: str, window: dict, now: int) -> str:
+    try:
+        pct = int(float(window.get("used_percentage")))  # pyright: ignore[reportArgumentType]
+    except (TypeError, ValueError):
+        return ""
+    part = f"{label} {pct}%"
+    remaining = _format_remaining(_parse_resets_at(window.get("resets_at")) - now)
+    if remaining:
+        part += f" \033[90m(reset {remaining})\033[0m"
+    return part
+
+
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def _visible_len(s: str) -> int:
+    """Length of s with ANSI escape sequences stripped."""
+    return len(_ANSI_RE.sub("", s))
+
+
+def _terminal_width() -> int | None:
+    """Terminal width from the COLUMNS env var, or None.
+
+    The statusline stdin JSON has no width field and stdout is a pipe, so
+    the COLUMNS env var (injected by Claude Code v2.1.153+) is the only
+    width signal. Absent or malformed values return None."""
+    try:
+        width = int(os.environ.get("COLUMNS", ""))
+    except ValueError:
+        return None
+    return width if width > 0 else None
+
+
+def main() -> None:
+    # Read Claude Code session JSON from stdin
+    try:
+        cc_data = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, ValueError):
+        cc_data = {}
+
+    trellis_dir = _find_trellis_dir()
+    SEP = " \033[90m·\033[0m "
+
+    # --- Trellis data ---
+    task = _get_current_task_for_input(trellis_dir, cc_data) if trellis_dir else None
+    dev = _get_developer(trellis_dir) if trellis_dir else ""
+    task_count = _count_active_tasks(trellis_dir) if trellis_dir else 0
+
+    # --- CC session data ---
+    model = cc_data.get("model", {}).get("display_name", "?")
+    ctx_pct = int(cc_data.get("context_window", {}).get("used_percentage") or 0)
+    ctx_size = _format_ctx_size(cc_data.get("context_window", {}).get("context_window_size") or 0)
+    duration = _format_duration(cc_data.get("cost", {}).get("total_duration_ms") or 0)
+    branch = _get_git_branch()
+
+    # Avoid "Opus 4.6 (1M context) (1M)"
+    if re.search(r"\d+[KMG]\b", model, re.IGNORECASE):
+        model_label = model
+    else:
+        model_label = f"{model} ({ctx_size})"
+
+    # Context % with color
+    if ctx_pct >= 90:
+        ctx_color = "\033[31m"
+    elif ctx_pct >= 70:
+        ctx_color = "\033[33m"
+    else:
+        ctx_color = "\033[32m"
+
+    # Build info line: model · ctx · branch · duration · dev · tasks [· rate limits]
+    parts = [
+        model_label,
+        f"ctx {ctx_color}{ctx_pct}%\033[0m",
+    ]
+    if branch:
+        parts.append(f"\033[35m{branch}\033[0m")
+    parts.append(duration)
+    if dev:
+        parts.append(f"\033[32m{dev}\033[0m")
+    if task_count:
+        parts.append(f"{task_count} task(s)")
+
+    now = int(time.time())
+    rate_limits = cc_data.get("rate_limits", {})
+    rate_parts: list[str] = []
+    for label, key in (("5h", "five_hour"), ("7d", "seven_day")):
+        part = _rate_limit_part(label, rate_limits.get(key) or {}, now)
+        if part:
+            rate_parts.append(part)
+
+    info_line = SEP.join(parts + rate_parts)
+
+    # Output: task line (only if active) + info line
+    if task:
+        source = str(task.get("source") or "")
+        source_tag = "session" if source.startswith("session:") else source
+        source_suffix = f" \033[90m[{source_tag}]\033[0m" if source_tag else ""
+        print(f"\033[36m[{task['priority']}]\033[0m {task['title']} \033[33m({task['status']})\033[0m{source_suffix}")
+
+    # Claude Code's status-bar height counts only "\n" characters, so a
+    # visually wrapped long line misaligns rows. When the host provides a
+    # terminal width and the info line would overflow, split the rate-limit
+    # segments onto their own line with an explicit "\n" instead.
+    width = _terminal_width()
+    if width is not None and rate_parts and _visible_len(info_line) > width:
+        print(SEP.join(parts))
+        print(SEP.join(rate_parts))
+    else:
+        print(info_line)
+
+
+if __name__ == "__main__":
+    main()

package/dist/templates/claude/index.d.ts

@@ -4,9 +4,10 @@
  * Directory structure:
  *   claude/
  *   ├── agents/         # Sub-agent definitions
+ *   ├── hooks/          # Claude-only opt-in hooks (statusline.py)
  *   └── settings.json   # Settings configuration
  *
- * Hooks come from shared-hooks/ (unified with other platforms).
+ * Default hooks come from shared-hooks/ (unified with other platforms).
  */
 export declare const settingsTemplate: string;
 export interface AgentTemplate {
@@ -19,4 +20,12 @@ export interface SettingsTemplate {
 }
 export declare function getAllAgents(): AgentTemplate[];
 export declare function getSettingsTemplate(): SettingsTemplate;
+/**
+ * Opt-in statusLine hook, installed only via `trellis init --with-statusline`.
+ *
+ * Lives under claude/hooks/ (not shared-hooks/) because `statusLine` is a
+ * Claude-only event, and is intentionally NOT part of `collectTemplates` —
+ * `trellis update` must never force-install it on opted-out projects.
+ */
+export declare function getStatuslineHook(): string;
 //# sourceMappingURL=index.d.ts.map

package/dist/templates/claude/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/claude/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAqBH,eAAO,MAAM,gBAAgB,QAAgC,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,YAAY,IAAI,aAAa,EAAE,CAa9C;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,CAKtD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/claude/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAqBH,eAAO,MAAM,gBAAgB,QAAgC,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,YAAY,IAAI,aAAa,EAAE,CAa9C;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,CAKtD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C"}

package/dist/templates/claude/index.js

@@ -4,9 +4,10 @@
  * Directory structure:
  *   claude/
  *   ├── agents/         # Sub-agent definitions
+ *   ├── hooks/          # Claude-only opt-in hooks (statusline.py)
  *   └── settings.json   # Settings configuration
  *
- * Hooks come from shared-hooks/ (unified with other platforms).
+ * Default hooks come from shared-hooks/ (unified with other platforms).
  */
 import { readdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -43,4 +44,14 @@ export function getSettingsTemplate() {
         content: settingsTemplate,
     };
 }
+/**
+ * Opt-in statusLine hook, installed only via `trellis init --with-statusline`.
+ *
+ * Lives under claude/hooks/ (not shared-hooks/) because `statusLine` is a
+ * Claude-only event, and is intentionally NOT part of `collectTemplates` —
+ * `trellis update` must never force-install it on opted-out projects.
+ */
+export function getStatuslineHook() {
+    return readTemplate("hooks/statusline.py");
+}
 //# sourceMappingURL=index.js.map

package/dist/templates/claude/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/claude/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,SAAS,YAAY,CAAC,YAAoB;IACxC,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,SAAS,CAAC,GAAW;IAC5B,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC;AAY9D,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IAElC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACrC,MAAM,OAAO,GAAG,YAAY,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;YAC/C,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,UAAU,EAAE,eAAe;QAC3B,OAAO,EAAE,gBAAgB;KAC1B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/claude/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,SAAS,YAAY,CAAC,YAAoB;IACxC,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,SAAS,CAAC,GAAW;IAC5B,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC;AAY9D,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IAElC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACrC,MAAM,OAAO,GAAG,YAAY,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;YAC/C,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,UAAU,EAAE,eAAe;QAC3B,OAAO,EAAE,gBAAgB;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,YAAY,CAAC,qBAAqB,CAAC,CAAC;AAC7C,CAAC"}

package/dist/templates/common/bundled-skills/trellis-meta/SKILL.md

@@ -7,15 +7,15 @@ description: "Understand and customize the local Trellis architecture inside a u
 
 This skill is for local Trellis users who have already run `trellis init` in a project. After reading it, an AI should understand the Trellis architecture, operating model, and customization entry points inside that user project, then modify the generated `.trellis/` and platform directory files according to the user's request.
 
-Trellis v0.6 adds three architectural surfaces on top of the pre-v0.6 workflow / persistence / platform model. First, a multi-agent collaboration runtime: `trellis channel` coordinates multiple AI worker processes through project-scoped JSONL event logs at `~/.trellis/channels/<project>/<channel>/events.jsonl`, with worker OOM guard, forum/thread channels, durable idempotency keys, and bundled `.trellis/agents/{check,implement}.md` runtime definitions. Second, cross-session memory: `trellis mem list | search | context | extract | projects` reads raw Claude Code and Codex JSONL already on disk, slices by `--phase brainstorm|implement|all`, and never uploads anything. Third, a dual-package npm release: `@mindfoldhq/trellis` (CLI) and `@mindfoldhq/trellis-core` (SDK with `/channel`, `/task`, `/mem`, `/testing` subpaths) ship in lockstep on one version. Treat these as first-class customization surfaces alongside the per-platform integration files.
+Trellis v0.6 adds three architectural surfaces on top of the pre-v0.6 workflow / persistence / platform model. First, a multi-agent collaboration runtime: `trellis channel` coordinates multiple AI worker processes through project-scoped JSONL event logs at `~/.trellis/channels/<project>/<channel>/events.jsonl`, with worker OOM guard, forum/thread channels, durable idempotency keys, and bundled `.trellis/agents/{check,implement}.md` runtime definitions. Second, cross-session memory: `trellis mem list | search | context | extract | projects` reads raw Claude Code, Codex, and Pi Agent JSONL already on disk, slices by `--phase brainstorm|implement|all`, and never uploads anything. Third, a dual-package npm release: `@mindfoldhq/trellis` (CLI) and `@mindfoldhq/trellis-core` (SDK with `/channel`, `/task`, `/mem`, `/testing` subpaths) ship in lockstep on one version. Treat these as first-class customization surfaces alongside the per-platform integration files.
 
 The default operating scope is local files in the user project:
 
 - `.trellis/`: workflow, config, tasks, spec, workspace, scripts, bundled runtime agents, and runtime state.
-- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.windsurf/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills/<name>/SKILL.md`; subagent skills carry `runAs: subagent` frontmatter.
+- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.reasonix/`, `.kilocode/`, `.agent/`, `.devin/`, and similar directories. Pi additionally exposes a native `trellis_subagent` tool with `single` / `parallel` / `chain` dispatch modes, throttled progress cards, and `isTrellisAgent()` validation on top of the file layout. Reasonix stores both workflow skills and subagent skills as `.reasonix/skills/<name>/SKILL.md`; subagent skills carry `runAs: subagent` frontmatter.
 - Shared skill layer: `.agents/skills/`.
 - User-owned channel store outside the project tree: `~/.trellis/channels/<project>/<channel>/events.jsonl`.
-- Raw platform conversation logs queryable via `trellis mem`: `~/.claude/projects/` and `~/.codex/sessions/` (OpenCode adapter degraded for the v0.6 line).
+- Raw platform conversation logs queryable via `trellis mem`: `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/` (OpenCode adapter degraded for the v0.6 line).
 
 Do not assume the user has the Trellis source repository. Do not default to modifying the global npm install directory or `node_modules` — both `@mindfoldhq/trellis` and `@mindfoldhq/trellis-core` ship as published packages sharing one version and one git tag per release.
 
@@ -67,7 +67,7 @@ Do not assume the user has the Trellis source repository. Do not default to modi
 - `.trellis/config.yaml` is the project-level Trellis configuration entry point. It hosts task lifecycle hooks (`hooks.after_create` / `after_start` / `after_finish` / `after_archive`), journal shape (`session_commit_message` / `max_journal_lines` / `session_auto_commit`), channel worker guard (`channel.worker_guard.idle_timeout` / `max_live_workers`), Codex dispatch mode (`codex.dispatch_mode: inline | sub-agent`), and the spec registry block (`registry.spec.source` + `registry.spec.template`).
 - `.trellis/spec/` stores the user's project-specific coding conventions and design constraints. When `registry.spec` is set, files are refreshed by `trellis update`; local edits surface as "modified by user" conflicts in `.trellis/.template-hashes.json`.
 - `.trellis/tasks/` stores task PRDs, design notes, implement plans, research files, and JSONL context. Tasks form parent/child trees: `task.py create --parent <slug>`, `task.py add-subtask <parent> <child>`, `task.py remove-subtask <parent> <child>`, and `task.py list-context <task>`. `task.py create` rejects a slug already present in `.trellis/tasks/archive/**`.
-- `.trellis/workspace/` stores **deliberately written** developer journals. Raw cross-session dialogue is **not** stored here — it lives on disk under `~/.claude/projects/` and `~/.codex/sessions/` and is recovered via `trellis mem search|extract|context`. The bundled `trellis-session-insight` skill teaches when to reach for `mem`.
+- `.trellis/workspace/` stores **deliberately written** developer journals. Raw cross-session dialogue is **not** stored here — it lives on disk under `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/` and is recovered via `trellis mem search|extract|context`. The bundled `trellis-session-insight` skill teaches when to reach for `mem`.
 - `.trellis/agents/{check,implement}.md` are bundled, platform-agnostic channel runtime agent definitions loaded by `trellis channel spawn --agent <name>`. Editable; `trellis update` backfills missing ones. Editing the per-platform `trellis-implement.md` / `trellis-check.md` does **not** change channel-runtime worker behavior.
 - `~/.trellis/channels/<project>/<channel>/events.jsonl` is the channel runtime event log per project per channel. User-owned, file-locked sequence numbering, durable `idempotencyKey` support; never under `.trellis/`.
 - Bundled multi-file skills (`trellis-meta`, `trellis-spec-bootstrap`, `trellis-session-insight`, `trellis-channel`) are auto-dispatched to every platform skill root by `getBundledSkillTemplates()` in `packages/cli/src/templates/common/index.ts`. Dropping a new directory under `packages/cli/src/templates/common/bundled-skills/` (upstream) ships it to every platform on the next `trellis update`.

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/change-agents.md

@@ -24,6 +24,8 @@ When the user wants to change `trellis-research`, `trellis-implement`, or `trell
 | CodeBuddy | `.codebuddy/agents/trellis-*.md` |
 | Factory Droid | `.factory/droids/trellis-*.md` |
 | Pi Agent | `.pi/agents/trellis-*.md` |
+| Reasonix | `.reasonix/skills/trellis-*/SKILL.md` (subagent frontmatter) |
+| ZCode | `.zcode/cli/agents/trellis-*.md` |
 
 Use the actual paths in the user project as authoritative.
 

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/change-skills-or-commands.md

@@ -89,7 +89,8 @@ If a command only repeats workflow rules, prefer making it reference/read `.trel
 | Factory Droid | `.factory/skills/`, `.factory/commands/` |
 | Pi Agent | `.pi/skills/` |
 | Reasonix | `.reasonix/skills/` (no separate commands dir; slash commands built into the platform) |
-| Kilo / Antigravity / Windsurf | workflows + skills |
+| ZCode | `.agents/skills/`, `.zcode/commands/` |
+| Kilo / Antigravity / Devin | workflows + skills |
 
 Every directory above is a deploy target for the four bundled skills. Each platform receives a full copy on `trellis init` and refresh on `trellis update`; nothing has to be wired by hand.
 

package/dist/templates/common/bundled-skills/trellis-meta/references/customize-local/overview.md

@@ -17,7 +17,7 @@ This directory is for local AI working in a user project where Trellis was insta
 
 ## General Operation Order
 
-1. **Confirm platform and directories**: inspect which directories exist, such as `.claude/`, `.codex/`, `.cursor/`.
+1. **Confirm platform and directories**: inspect which directories exist, such as `.claude/`, `.codex/`, `.cursor/`, `.zcode/`.
 2. **Confirm the current active task**: run `python3 ./.trellis/scripts/task.py current --source`.
 3. **Read the local source of truth**: prefer `.trellis/workflow.md`, `.trellis/config.yaml`, and relevant platform files.
 4. **Modify narrowly**: edit only files related to the user's request.
@@ -32,7 +32,7 @@ This directory is for local AI working in a user project where Trellis was insta
 | Task material | `.trellis/tasks/<task>/` |
 | Project specs | `.trellis/spec/` |
 | Runtime scripts | `.trellis/scripts/` |
-| Platform integration | `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, and similar directories |
+| Platform integration | `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.zcode/`, and similar directories |
 | Shared skill | `.agents/skills/` |
 
 ## Things Not To Do By Default

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/bundled-skills.md

@@ -23,7 +23,7 @@ The set is discovered at runtime by listing directories under `templates/common/
 | Skill | Purpose |
 | --- | --- |
 | `trellis-meta` | This skill. Explains the local Trellis architecture and customization entry points to an AI working inside a user project. |
-| `trellis-session-insight` | Wraps the `trellis mem` CLI so an AI knows when and how to reach into past Claude Code / Codex conversation logs. |
+| `trellis-session-insight` | Wraps the `trellis mem` CLI so an AI knows when and how to reach into past Claude Code / Codex / Pi Agent conversation logs. |
 | `trellis-spec-bootstrap` | Platform-neutral workflow for creating or refreshing `.trellis/spec/` from the real codebase (with optional GitNexus / ABCoder integration). |
 | `trellis-channel` | Capability skill teaching an AI when to reach for `trellis channel` for multi-agent collaboration, forum/thread persistent boards, and dispatcher-wait patterns. |
 
@@ -45,7 +45,7 @@ Each platform configurator calls `writeSkills(<root>, <workflowSkills>, resolveB
 | Copilot | `.github/skills/<skill>/` | `configureCopilot` |
 | Droid | `.factory/skills/<skill>/` | `configureDroid` |
 | Antigravity | `.agent/skills/<skill>/` | `configureAntigravity` |
-| Windsurf | `.windsurf/skills/<skill>/` | `configureWindsurf` |
+| Devin | `.devin/skills/<skill>/` | `configureDevin` |
 | Kilo | `.kilocode/skills/<skill>/` | `configureKilo` |
 | OpenCode | (handled by `collectOpenCodeTemplates`) | Uses the same `resolveBundledSkills(ctx)` output |
 | Pi, Reasonix | (their own collectors) | Same `resolveBundledSkills(ctx)` output |
@@ -69,7 +69,7 @@ The mechanism that auto-dispatches bundled skills to platform skill roots lives
    - `writeSkills(skillsRoot, workflowSkills, bundledSkills)` writes both workflow skills and bundled skill files under `skillsRoot`.
    - `collectSkillTemplates(skillsRoot, workflowSkills, bundledSkills)` returns the same shape as a `Map<filePath, content>` for the update / hash pipeline.
 
-Every platform configurator that supports skills imports both helpers (see `claude.ts`, `cursor.ts`, `codex.ts`, `gemini.ts`, `kiro.ts`, `qoder.ts`, `codebuddy.ts`, `copilot.ts`, `droid.ts`, `antigravity.ts`, `windsurf.ts`, `kilo.ts`). The `index.ts` `PLATFORM_FUNCTIONS` registry also calls `resolveBundledSkills(ctx)` inside each `collectTemplates` closure so `trellis update` tracking stays consistent.
+Every platform configurator that supports skills imports both helpers (see `claude.ts`, `cursor.ts`, `codex.ts`, `gemini.ts`, `kiro.ts`, `qoder.ts`, `codebuddy.ts`, `copilot.ts`, `droid.ts`, `antigravity.ts`, `devin.ts`, `kilo.ts`). The `index.ts` `PLATFORM_FUNCTIONS` registry also calls `resolveBundledSkills(ctx)` inside each `collectTemplates` closure so `trellis update` tracking stays consistent.
 
 ## Adding a New Bundled Skill
 

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/generated-files.md

@@ -41,9 +41,9 @@ Different platforms generate different directories. Common categories:
 | --- | --- | --- |
 | hooks | `.claude/hooks/`, `.codex/hooks/`, `.cursor/hooks/` | Inject session context, workflow-state, and sub-agent context. |
 | settings | `.claude/settings.json`, `.codex/hooks.json`, `.qoder/settings.json` | Tell the platform when to run hooks or plugins. |
-| agents | `.claude/agents/`, `.codex/agents/`, `.kiro/agents/` | Define agents such as `trellis-research`, `trellis-implement`, and `trellis-check`. |
+| agents | `.claude/agents/`, `.codex/agents/`, `.kiro/agents/`, `.zcode/cli/agents/` | Define agents such as `trellis-research`, `trellis-implement`, and `trellis-check`. |
 | skills | `.claude/skills/`, `.agents/skills/`, `.qoder/skills/` | Skills that auto-trigger or can be read by AI. |
-| commands/prompts/workflows | `.cursor/commands/`, `.github/prompts/`, `.windsurf/workflows/` | Explicit user-invoked command or workflow entry points. |
+| commands/prompts/workflows | `.cursor/commands/`, `.github/prompts/`, `.devin/workflows/`, `.zcode/commands/` | Explicit user-invoked command or workflow entry points. |
 
 When modifying a platform directory, also confirm whether `.trellis/workflow.md` still describes the same flow.
 

package/dist/templates/common/bundled-skills/trellis-meta/references/local-architecture/overview.md

@@ -5,7 +5,7 @@
 Therefore, when an AI uses this skill, the default customization target is local files inside the user project:
 
 - `.trellis/`: workflow, tasks, specs, memory, scripts, and runtime state.
-- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.kilocode/`, `.agent/`, `.windsurf/`, and similar directories.
+- Platform directories: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.kilocode/`, `.agent/`, `.devin/`, `.reasonix/`, `.zcode/`, and similar directories.
 - Shared skill layer: `.agents/skills/`.
 
 Do not default to guiding the user to fork the Trellis CLI repository. Treat upstream source code as the operating target only when the user explicitly says they want to change Trellis upstream source, publish an npm package, or contribute a PR.

package/dist/templates/common/bundled-skills/trellis-meta/references/platform-files/agents.md

@@ -32,10 +32,12 @@ Agent files should not become generic chat prompts. They should define input sou
 | CodeBuddy | `.codebuddy/agents/trellis-*.md` |
 | Factory Droid | `.factory/droids/trellis-*.md` |
 | Pi Agent | `.pi/agents/trellis-*.md` |
+| Reasonix | `.reasonix/skills/trellis-*/SKILL.md` (subagent frontmatter) |
+| ZCode | `.zcode/cli/agents/trellis-*.md` |
 
 GitHub Copilot agent/prompt support is provided by a combination of directories such as `.github/agents/`, `.github/prompts/`, and `.github/skills/`; inspect the files actually generated in the user project.
 
-Main-session workflow platforms such as Kilo, Antigravity, and Windsurf may not have Trellis sub-agent files. They usually rely on workflows/skills to guide the main session.
+Main-session workflow platforms such as Kilo, Antigravity, and Devin may not have Trellis sub-agent files. They usually rely on workflows/skills to guide the main session.
 
 ## Two Context Loading Modes
 

package/dist/templates/common/bundled-skills/trellis-meta/references/platform-files/hooks-and-settings.md

@@ -28,6 +28,8 @@ Common files:
 | Factory Droid | `.factory/settings.json` |
 | Pi Agent | `.pi/settings.json`, `.pi/extensions/trellis/` |
 
+Reasonix and ZCode are pull-based platforms that do not use hooks or settings files; their agent files contain prelude instructions to read context after startup.
+
 Whether these files exist in a project depends on which `trellis init --<platform>` flags the user ran.
 
 ## Hook Script Types

package/dist/templates/common/bundled-skills/trellis-meta/references/platform-files/overview.md

@@ -5,7 +5,7 @@ Trellis connects the same local architecture to different AI tools. `.trellis/`
 When a local AI modifies Trellis, it should distinguish two file categories first:
 
 - **Shared files**: `.trellis/workflow.md`, `.trellis/tasks/`, `.trellis/spec/`, `.trellis/scripts/`.
-- **Platform files**: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.kilocode/`, `.agent/`, `.windsurf/`, and similar directories.
+- **Platform files**: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.kilocode/`, `.agent/`, `.devin/`, `.reasonix/`, `.zcode/`, and similar directories.
 
 Platform files do not store business state. They let the corresponding AI tool read Trellis state, call Trellis scripts, and load Trellis skills/agents/hooks.
 
@@ -17,7 +17,7 @@ Platform files do not store business state. They let the corresponding AI tool r
 | hooks/plugins/extensions | `.claude/hooks/`, `.opencode/plugins/`, `.pi/extensions/` | Inject context at session start, user input, agent startup, shell execution, and similar events. |
 | agents | `.claude/agents/`, `.codex/agents/`, `.kiro/agents/` | Define `trellis-research`, `trellis-implement`, and `trellis-check`. |
 | skills | `.claude/skills/`, `.agents/skills/`, `.qoder/skills/` | Capability descriptions that auto-trigger or can be read on demand. |
-| commands/prompts/workflows | `.cursor/commands/`, `.github/prompts/`, `.windsurf/workflows/` | Entry points explicitly invoked by the user. |
+| commands/prompts/workflows | `.cursor/commands/`, `.github/prompts/`, `.devin/workflows/` | Entry points explicitly invoked by the user. |
 
 ## Three Platform Integration Modes
 

package/dist/templates/common/bundled-skills/trellis-meta/references/platform-files/platform-map.md

@@ -14,13 +14,14 @@ This page lists common Trellis file locations in a user project by platform. Whe
 | Kiro | `--kiro` | `.kiro/` | `.kiro/skills/` | `.kiro/agents/` | `.kiro/hooks/` |
 | Gemini CLI | `--gemini` | `.gemini/` | `.agents/skills/` | `.gemini/agents/` | `.gemini/settings.json` + `.gemini/hooks/` |
 | Antigravity | `--antigravity` | `.agent/` | `.agent/skills/` | Usually none | `.agent/workflows/` |
-| Windsurf | `--windsurf` | `.windsurf/` | `.windsurf/skills/` | Usually none | `.windsurf/workflows/` |
+| Devin | `--devin` | `.devin/` | `.devin/skills/` | Usually none | `.devin/workflows/` |
 | Qoder | `--qoder` | `.qoder/` | `.qoder/skills/` | `.qoder/agents/` | `.qoder/hooks/` + `.qoder/settings.json` |
 | CodeBuddy | `--codebuddy` | `.codebuddy/` | `.codebuddy/skills/` | `.codebuddy/agents/` | `.codebuddy/hooks/` + `.codebuddy/settings.json` |
 | GitHub Copilot | `--copilot` | `.github/` | `.github/skills/` | `.github/agents/` | `.github/copilot/hooks/` + prompts |
 | Factory Droid | `--droid` | `.factory/` | `.factory/skills/` | `.factory/droids/` | `.factory/hooks/` + settings |
 | Pi Agent | `--pi` | `.pi/` | `.pi/skills/` | `.pi/agents/` | `.pi/extensions/trellis/` (native `trellis_subagent` tool) + `.pi/settings.json` |
 | Reasonix | `--reasonix` | `.reasonix/` | `.reasonix/skills/` | None — sub-agents are skills with `runAs: subagent` frontmatter | None |
+| ZCode | `--zcode` | `.zcode/` | `.agents/skills/` | `.zcode/cli/agents/` | pull-based prelude (no hooks) |
 
 ## Capability Groups
 
@@ -40,6 +41,7 @@ These platforms usually have `trellis-research`, `trellis-implement`, and `trell
 - Factory Droid
 - Pi Agent
 - Reasonix (delivered as skills with `runAs: subagent` under `.reasonix/skills/`, not as a separate `agents/` directory)
+- ZCode
 
 When changing implementation/check/research behavior, look for the corresponding platform agent files first.
 
@@ -57,7 +59,7 @@ These platforms rely more on workflows/skills to guide the main session:
 
 - Kilo
 - Antigravity
-- Windsurf
+- Devin
 
 When changing behavior, inspect workflows and skills first. Do not assume Trellis sub-agents exist.
 

package/dist/templates/common/bundled-skills/trellis-meta/references/platform-files/skills-and-commands.md

@@ -25,12 +25,14 @@ Trellis workflow skills usually share one semantic set: brainstorm, before-dev,
 | Kiro | `.kiro/skills/` |
 | Gemini CLI | `.agents/skills/`, `.gemini/commands/` |
 | Antigravity | `.agent/skills/`, `.agent/workflows/` |
-| Windsurf | `.windsurf/skills/`, `.windsurf/workflows/` |
+| Devin | `.devin/skills/`, `.devin/workflows/` |
 | Qoder | `.qoder/skills/`, `.qoder/commands/` |
 | CodeBuddy | `.codebuddy/skills/`, `.codebuddy/commands/` |
 | GitHub Copilot | `.github/skills/`, `.github/prompts/` |
 | Factory Droid | `.factory/skills/`, `.factory/commands/` |
 | Pi Agent | `.pi/skills/` |
+| Reasonix | `.reasonix/skills/` |
+| ZCode | `.agents/skills/`, `.zcode/commands/` |
 
 In a user project, use the files actually generated by init as authoritative.
 

package/dist/templates/common/bundled-skills/trellis-session-insight/SKILL.md

@@ -11,7 +11,7 @@ It is intentionally a **capability skill, not a workflow**. There is no fixed ou
 
 ## What `trellis mem` is
 
-A local CLI that indexes the user's past Claude Code and Codex conversation logs (the JSONL files each platform stores under `~/.claude/projects/` and `~/.codex/sessions/`) and lets you list, search, slice by Trellis task boundaries, and dump cleaned dialogue from them. OpenCode logs are not yet indexable (provider adapter pending) — when an OpenCode session is the obvious target, surface that limitation rather than guessing.
+A local CLI that indexes the user's past Claude Code, Codex, and Pi Agent conversation logs (the JSONL files each platform stores under `~/.claude/projects/`, `~/.codex/sessions/`, and `~/.pi/agent/sessions/`) and lets you list, search, slice by Trellis task boundaries, and dump cleaned dialogue from them. OpenCode logs are not yet indexable (provider adapter pending) — when an OpenCode session is the obvious target, surface that limitation rather than guessing.
 
 Nothing in `mem` is uploaded. All reads are local.
 
@@ -64,7 +64,7 @@ trellis mem extract <session-id> --grep "<keyword>"
 trellis mem context <session-id> --turns 3 --around 2
 
 # When you do not know the session id yet, start with list + filter.
-trellis mem list --task <task-dir>
+trellis mem list --cwd <project-path>
 trellis mem projects   # → list active project cwds, then narrow
 ```