@mindfoldhq/trellis 0.3.10 → 0.4.0-beta.10

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

@@ -0,0 +1,109 @@
+"""
+Task data access layer.
+
+Single source of truth for loading and iterating task directories.
+Replaces scattered task.json parsing across 9+ files.
+
+Provides:
+    load_task          — Load a single task by directory path
+    iter_active_tasks  — Iterate all non-archived tasks (sorted)
+    get_all_statuses   — Get {dir_name: status} map for children progress
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from pathlib import Path
+
+from .io import read_json
+from .paths import FILE_TASK_JSON
+from .types import TaskInfo
+
+
+def load_task(task_dir: Path) -> TaskInfo | None:
+    """Load task from a directory containing task.json.
+
+    Args:
+        task_dir: Absolute path to the task directory.
+
+    Returns:
+        TaskInfo if task.json exists and is valid, None otherwise.
+    """
+    task_json = task_dir / FILE_TASK_JSON
+    if not task_json.is_file():
+        return None
+
+    data = read_json(task_json)
+    if not data:
+        return None
+
+    return TaskInfo(
+        dir_name=task_dir.name,
+        directory=task_dir,
+        title=data.get("title") or data.get("name") or "unknown",
+        status=data.get("status", "unknown"),
+        assignee=data.get("assignee", ""),
+        priority=data.get("priority", "P2"),
+        children=tuple(data.get("children", [])),
+        parent=data.get("parent"),
+        package=data.get("package"),
+        raw=data,
+    )
+
+
+def iter_active_tasks(tasks_dir: Path) -> Iterator[TaskInfo]:
+    """Iterate all active (non-archived) tasks, sorted by directory name.
+
+    Skips the "archive" directory and directories without valid task.json.
+
+    Args:
+        tasks_dir: Path to the tasks directory.
+
+    Yields:
+        TaskInfo for each valid task.
+    """
+    if not tasks_dir.is_dir():
+        return
+
+    for d in sorted(tasks_dir.iterdir()):
+        if not d.is_dir() or d.name == "archive":
+            continue
+        info = load_task(d)
+        if info is not None:
+            yield info
+
+
+def get_all_statuses(tasks_dir: Path) -> dict[str, str]:
+    """Get a {dir_name: status} mapping for all active tasks.
+
+    Useful for computing children progress without loading full TaskInfo.
+
+    Args:
+        tasks_dir: Path to the tasks directory.
+
+    Returns:
+        Dict mapping directory names to status strings.
+    """
+    return {t.dir_name: t.status for t in iter_active_tasks(tasks_dir)}
+
+
+def children_progress(
+    children: tuple[str, ...] | list[str],
+    all_statuses: dict[str, str],
+) -> str:
+    """Format children progress string like " [2/3 done]".
+
+    Args:
+        children: List of child directory names.
+        all_statuses: Status map from get_all_statuses().
+
+    Returns:
+        Formatted string, or "" if no children.
+    """
+    if not children:
+        return ""
+    done = sum(
+        1 for c in children
+        if all_statuses.get(c) in ("completed", "done")
+    )
+    return f" [{done}/{len(children)} done]"

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

@@ -0,0 +1,112 @@
+"""
+Core type definitions for Trellis task data.
+
+Provides:
+    TaskData     — TypedDict for task.json shape (read-path type hints only)
+    TaskInfo     — Frozen dataclass for loaded task (the public API type)
+    AgentRecord  — TypedDict for registry.json agent entries
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TypedDict
+
+
+# =============================================================================
+# task.json shape (TypedDict — used only for read-path type hints)
+# =============================================================================
+
+class TaskData(TypedDict, total=False):
+    """Shape of task.json on disk.
+
+    Used only for type annotations when reading task.json.
+    Writes must use the original dict to avoid losing unknown fields.
+    """
+
+    id: str
+    name: str
+    title: str
+    description: str
+    status: str
+    dev_type: str
+    scope: str | None
+    package: str | None
+    priority: str
+    creator: str
+    assignee: str
+    createdAt: str
+    completedAt: str | None
+    branch: str | None
+    base_branch: str | None
+    worktree_path: str | None
+    current_phase: int
+    next_action: list[dict]
+    commit: str | None
+    pr_url: str | None
+    subtasks: list[str]
+    children: list[str]
+    parent: str | None
+    relatedFiles: list[str]
+    notes: str
+    meta: dict
+
+
+# =============================================================================
+# Loaded task object (frozen dataclass — the public API type)
+# =============================================================================
+
+@dataclass(frozen=True)
+class TaskInfo:
+    """Immutable view of a loaded task.
+
+    Created by load_task() / iter_active_tasks().
+    Contains the commonly accessed fields; the original dict
+    is preserved in `raw` for write-back and uncommon field access.
+    """
+
+    dir_name: str
+    directory: Path
+    title: str
+    status: str
+    assignee: str
+    priority: str
+    children: tuple[str, ...]
+    parent: str | None
+    package: str | None
+    raw: dict  # original dict — use for writes and uncommon fields
+
+    @property
+    def name(self) -> str:
+        """Task name (id or name field)."""
+        return self.raw.get("name") or self.raw.get("id") or self.dir_name
+
+    @property
+    def description(self) -> str:
+        return self.raw.get("description", "")
+
+    @property
+    def branch(self) -> str | None:
+        return self.raw.get("branch")
+
+    @property
+    def meta(self) -> dict:
+        return self.raw.get("meta", {})
+
+
+# =============================================================================
+# registry.json agent entry
+# =============================================================================
+
+class AgentRecord(TypedDict, total=False):
+    """Shape of an agent entry in registry.json."""
+
+    id: str
+    pid: int
+    task_dir: str
+    worktree_path: str
+    branch: str
+    platform: str
+    started_at: str
+    status: str

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

@@ -36,6 +36,7 @@ from common.paths import (
     get_tasks_dir,
     set_current_task,
 )
+from common.config import get_spec_base, resolve_package
 
 
 # =============================================================================
@@ -58,7 +59,7 @@ def write_prd_header() -> str:
 Welcome to Trellis! This is your first task.
 
 AI agents use `.trellis/spec/` to understand YOUR project's coding conventions.
-**Empty templates = AI writes generic code that doesn't match your project style.**
+**Starting from scratch = AI writes generic code that doesn't match your project style.**
 
 Filling these guidelines is a one-time setup that pays off for every future AI session.
 
@@ -70,36 +71,36 @@ Fill in the guideline files based on your **existing codebase**.
 """
 
 
-def write_prd_backend_section() -> str:
+def write_prd_backend_section(spec_base: str) -> str:
     """Write PRD backend section."""
-    return """
+    return f"""
 
 ### Backend Guidelines
 
 | File | What to Document |
 |------|------------------|
-| `.trellis/spec/backend/directory-structure.md` | Where different file types go (routes, services, utils) |
-| `.trellis/spec/backend/database-guidelines.md` | ORM, migrations, query patterns, naming conventions |
-| `.trellis/spec/backend/error-handling.md` | How errors are caught, logged, and returned |
-| `.trellis/spec/backend/logging-guidelines.md` | Log levels, format, what to log |
-| `.trellis/spec/backend/quality-guidelines.md` | Code review standards, testing requirements |
+| `.trellis/{spec_base}/backend/directory-structure.md` | Where different file types go (routes, services, utils) |
+| `.trellis/{spec_base}/backend/database-guidelines.md` | ORM, migrations, query patterns, naming conventions |
+| `.trellis/{spec_base}/backend/error-handling.md` | How errors are caught, logged, and returned |
+| `.trellis/{spec_base}/backend/logging-guidelines.md` | Log levels, format, what to log |
+| `.trellis/{spec_base}/backend/quality-guidelines.md` | Code review standards, testing requirements |
 """
 
 
-def write_prd_frontend_section() -> str:
+def write_prd_frontend_section(spec_base: str) -> str:
     """Write PRD frontend section."""
-    return """
+    return f"""
 
 ### Frontend Guidelines
 
 | File | What to Document |
 |------|------------------|
-| `.trellis/spec/frontend/directory-structure.md` | Component/page/hook organization |
-| `.trellis/spec/frontend/component-guidelines.md` | Component patterns, props conventions |
-| `.trellis/spec/frontend/hook-guidelines.md` | Custom hook naming, patterns |
-| `.trellis/spec/frontend/state-management.md` | State library, patterns, what goes where |
-| `.trellis/spec/frontend/type-safety.md` | TypeScript conventions, type organization |
-| `.trellis/spec/frontend/quality-guidelines.md` | Linting, testing, accessibility |
+| `.trellis/{spec_base}/frontend/directory-structure.md` | Component/page/hook organization |
+| `.trellis/{spec_base}/frontend/component-guidelines.md` | Component patterns, props conventions |
+| `.trellis/{spec_base}/frontend/hook-guidelines.md` | Custom hook naming, patterns |
+| `.trellis/{spec_base}/frontend/state-management.md` | State library, patterns, what goes where |
+| `.trellis/{spec_base}/frontend/type-safety.md` | TypeScript conventions, type organization |
+| `.trellis/{spec_base}/frontend/quality-guidelines.md` | Linting, testing, accessibility |
 """
 
 
@@ -168,17 +169,17 @@ After completing this task:
 """
 
 
-def write_prd(task_dir: Path, project_type: str) -> None:
+def write_prd(task_dir: Path, project_type: str, spec_base: str) -> None:
     """Write prd.md file."""
     content = write_prd_header()
 
     if project_type == "frontend":
-        content += write_prd_frontend_section()
+        content += write_prd_frontend_section(spec_base)
     elif project_type == "backend":
-        content += write_prd_backend_section()
+        content += write_prd_backend_section(spec_base)
     else:  # fullstack
-        content += write_prd_backend_section()
-        content += write_prd_frontend_section()
+        content += write_prd_backend_section(spec_base)
+        content += write_prd_frontend_section(spec_base)
 
     content += write_prd_footer()
 
@@ -190,7 +191,7 @@ def write_prd(task_dir: Path, project_type: str) -> None:
 # Task JSON
 # =============================================================================
 
-def write_task_json(task_dir: Path, developer: str, project_type: str) -> None:
+def write_task_json(task_dir: Path, developer: str, project_type: str, spec_base: str) -> None:
     """Write task.json file."""
     today = datetime.now().strftime("%Y-%m-%d")
 
@@ -200,20 +201,20 @@ def write_task_json(task_dir: Path, developer: str, project_type: str) -> None:
             {"name": "Fill frontend guidelines", "status": "pending"},
             {"name": "Add code examples", "status": "pending"},
         ]
-        related_files = [".trellis/spec/frontend/"]
+        related_files = [f".trellis/{spec_base}/frontend/"]
     elif project_type == "backend":
         subtasks = [
             {"name": "Fill backend guidelines", "status": "pending"},
             {"name": "Add code examples", "status": "pending"},
         ]
-        related_files = [".trellis/spec/backend/"]
+        related_files = [f".trellis/{spec_base}/backend/"]
     else:  # fullstack
         subtasks = [
             {"name": "Fill backend guidelines", "status": "pending"},
             {"name": "Fill frontend guidelines", "status": "pending"},
             {"name": "Add code examples", "status": "pending"},
         ]
-        related_files = [".trellis/spec/backend/", ".trellis/spec/frontend/"]
+        related_files = [f".trellis/{spec_base}/backend/", f".trellis/{spec_base}/frontend/"]
 
     task_data = {
         "id": TASK_NAME,
@@ -264,6 +265,10 @@ def main() -> int:
         print(f"Run: python3 ./{DIR_WORKFLOW}/{DIR_SCRIPTS}/init_developer.py <your-name>")
         return 1
 
+    # Resolve spec base path (monorepo: spec/<package>, single-repo: spec)
+    package = resolve_package(repo_root=repo_root)
+    spec_base = get_spec_base(package, repo_root)
+
     tasks_dir = get_tasks_dir(repo_root)
     task_dir = tasks_dir / TASK_NAME
     relative_path = f"{DIR_WORKFLOW}/{DIR_TASKS}/{TASK_NAME}"
@@ -277,8 +282,8 @@ def main() -> int:
     task_dir.mkdir(parents=True, exist_ok=True)
 
     # Write files
-    write_task_json(task_dir, developer, project_type)
-    write_prd(task_dir, project_type)
+    write_task_json(task_dir, developer, project_type, spec_base)
+    write_prd(task_dir, project_type, spec_base)
 
     # Set as current task
     set_current_task(relative_path, repo_root)

package/dist/templates/trellis/scripts/hooks/linear_sync.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""Linear sync hook for Trellis task lifecycle.
+
+Syncs task events to Linear via the `linearis` CLI.
+
+Usage (called automatically by task.py hooks):
+    python3 .trellis/scripts/hooks/linear_sync.py create
+    python3 .trellis/scripts/hooks/linear_sync.py start
+    python3 .trellis/scripts/hooks/linear_sync.py archive
+
+Manual usage:
+    TASK_JSON_PATH=.trellis/tasks/<name>/task.json python3 .trellis/scripts/hooks/linear_sync.py sync
+
+Environment:
+    TASK_JSON_PATH  - Absolute path to task.json (set by task.py)
+
+Configuration:
+    .trellis/hooks.local.json  - Local config (gitignored), example:
+    {
+      "linear": {
+        "team": "TEAM_KEY",
+        "project": "Project Name",
+        "assignees": {
+          "dev-name": "linear-user-id"
+        }
+      }
+    }
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+# ─── Configuration ────────────────────────────────────────────────────────────
+
+# Trellis priority → Linear priority (1=Urgent, 2=High, 3=Medium, 4=Low)
+PRIORITY_MAP = {"P0": 1, "P1": 2, "P2": 3, "P3": 4}
+
+# Linear status names (must match your team's workflow)
+STATUS_IN_PROGRESS = "In Progress"
+STATUS_DONE = "Done"
+
+
+def _load_config() -> dict:
+    """Load local hook config from .trellis/hooks.local.json."""
+    task_json_path = os.environ.get("TASK_JSON_PATH", "")
+    if task_json_path:
+        # Walk up from task.json to find .trellis/
+        trellis_dir = Path(task_json_path).parent.parent.parent
+    else:
+        trellis_dir = Path(".trellis")
+
+    config_path = trellis_dir / "hooks.local.json"
+    try:
+        with open(config_path, encoding="utf-8") as f:
+            return json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+CONFIG = _load_config()
+LINEAR_CFG = CONFIG.get("linear", {})
+
+TEAM = LINEAR_CFG.get("team", "")
+PROJECT = LINEAR_CFG.get("project", "")
+ASSIGNEE_MAP = LINEAR_CFG.get("assignees", {})
+
+# ─── Helpers ──────────────────────────────────────────────────────────────────
+
+
+def _read_task() -> tuple[dict, str]:
+    path = os.environ.get("TASK_JSON_PATH", "")
+    if not path:
+        print("TASK_JSON_PATH not set", file=sys.stderr)
+        sys.exit(1)
+    with open(path, encoding="utf-8") as f:
+        return json.load(f), path
+
+
+def _write_task(data: dict, path: str) -> None:
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+
+
+def _linearis(*args: str) -> dict | None:
+    result = subprocess.run(
+        ["linearis", *args],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode != 0:
+        print(f"linearis error: {result.stderr.strip()}", file=sys.stderr)
+        sys.exit(1)
+    stdout = result.stdout.strip()
+    if stdout:
+        return json.loads(stdout)
+    return None
+
+
+def _get_linear_issue(task: dict) -> str | None:
+    meta = task.get("meta")
+    if isinstance(meta, dict):
+        return meta.get("linear_issue")
+    return None
+
+
+# ─── Actions ──────────────────────────────────────────────────────────────────
+
+
+def cmd_create() -> None:
+    if not TEAM:
+        print("No linear.team configured in hooks.local.json", file=sys.stderr)
+        sys.exit(1)
+
+    task, path = _read_task()
+
+    # Skip if already linked
+    if _get_linear_issue(task):
+        print(f"Already linked: {_get_linear_issue(task)}")
+        return
+
+    title = task.get("title") or task.get("name") or "Untitled"
+    args = ["issues", "create", title, "--team", TEAM]
+
+    # Map priority
+    priority = PRIORITY_MAP.get(task.get("priority", ""), 0)
+    if priority:
+        args.extend(["-p", str(priority)])
+
+    # Set project
+    if PROJECT:
+        args.extend(["--project", PROJECT])
+
+    # Assign to Linear user
+    assignee = task.get("assignee", "")
+    linear_user_id = ASSIGNEE_MAP.get(assignee)
+    if linear_user_id:
+        args.extend(["--assignee", linear_user_id])
+
+    # Link to parent's Linear issue if available
+    parent_issue = _resolve_parent_linear_issue(task)
+    if parent_issue:
+        args.extend(["--parent-ticket", parent_issue])
+
+    result = _linearis(*args)
+    if result and "identifier" in result:
+        if not isinstance(task.get("meta"), dict):
+            task["meta"] = {}
+        task["meta"]["linear_issue"] = result["identifier"]
+        _write_task(task, path)
+        print(f"Created Linear issue: {result['identifier']}")
+
+
+def cmd_start() -> None:
+    task, _ = _read_task()
+    issue = _get_linear_issue(task)
+    if not issue:
+        return
+    _linearis("issues", "update", issue, "-s", STATUS_IN_PROGRESS)
+    print(f"Updated {issue} -> {STATUS_IN_PROGRESS}")
+    cmd_sync()
+
+
+def cmd_archive() -> None:
+    task, _ = _read_task()
+    issue = _get_linear_issue(task)
+    if not issue:
+        return
+    _linearis("issues", "update", issue, "-s", STATUS_DONE)
+    print(f"Updated {issue} -> {STATUS_DONE}")
+
+
+def cmd_sync() -> None:
+    """Sync prd.md content to Linear issue description."""
+    task, _ = _read_task()
+    issue = _get_linear_issue(task)
+    if not issue:
+        print("No linear_issue in meta, run create first", file=sys.stderr)
+        sys.exit(1)
+
+    # Find prd.md next to task.json
+    task_json_path = os.environ.get("TASK_JSON_PATH", "")
+    prd_path = Path(task_json_path).parent / "prd.md"
+    if not prd_path.is_file():
+        print(f"No prd.md found at {prd_path}", file=sys.stderr)
+        sys.exit(1)
+
+    description = prd_path.read_text(encoding="utf-8").strip()
+    _linearis("issues", "update", issue, "-d", description)
+    print(f"Synced prd.md to {issue} description")
+
+
+# ─── Parent Issue Resolution ─────────────────────────────────────────────────
+
+
+def _resolve_parent_linear_issue(task: dict) -> str | None:
+    """Find parent task's Linear issue identifier."""
+    parent_name = task.get("parent")
+    if not parent_name:
+        return None
+
+    task_json_path = os.environ.get("TASK_JSON_PATH", "")
+    if not task_json_path:
+        return None
+
+    current_task_dir = Path(task_json_path).parent
+    tasks_dir = current_task_dir.parent
+    parent_json = tasks_dir / parent_name / "task.json"
+
+    if parent_json.exists():
+        try:
+            with open(parent_json, encoding="utf-8") as f:
+                parent_task = json.load(f)
+            return _get_linear_issue(parent_task)
+        except (json.JSONDecodeError, OSError):
+            pass
+    return None
+
+
+# ─── Main ─────────────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    action = sys.argv[1] if len(sys.argv) > 1 else ""
+    actions = {
+        "create": cmd_create,
+        "start": cmd_start,
+        "archive": cmd_archive,
+        "sync": cmd_sync,
+    }
+    fn = actions.get(action)
+    if fn:
+        fn()
+    else:
+        print(f"Unknown action: {action}", file=sys.stderr)
+        print(f"Valid actions: {', '.join(actions)}", file=sys.stderr)
+        sys.exit(1)

package/dist/templates/trellis/scripts/multi_agent/_bootstrap.py

@@ -0,0 +1,17 @@
+"""Bootstrap path setup for multi_agent scripts.
+
+Import this module before importing from common/:
+
+    import _bootstrap  # noqa: F401
+
+This adds the parent scripts/ directory to sys.path so that
+`from common.xxx import yyy` works when running scripts directly
+via `python3 .trellis/scripts/multi_agent/some_script.py`.
+"""
+
+import sys
+from pathlib import Path
+
+_scripts_dir = str(Path(__file__).resolve().parent.parent)
+if _scripts_dir not in sys.path:
+    sys.path.insert(0, _scripts_dir)