@mindfoldhq/trellis 0.3.10 → 0.4.0-beta.10

package/dist/templates/claude/hooks/inject-subagent-context.py

@@ -99,7 +99,14 @@ def get_current_task(repo_root: str) -> str | None:
     try:
         with open(current_task_file, "r", encoding="utf-8") as f:
             content = f.read().strip()
-            return content if content else None
+            if not content:
+                return None
+            normalized = content.replace("\\", "/")
+            while normalized.startswith("./"):
+                normalized = normalized[2:]
+            if normalized.startswith("tasks/"):
+                normalized = f".trellis/{normalized}"
+            return normalized
     except Exception:
         return None
 
@@ -339,8 +346,7 @@ def get_check_context(repo_root: str, task_dir: str) -> str:
         check_files = [
             (".claude/commands/trellis/finish-work.md", "Finish work checklist"),
             (".claude/commands/trellis/check-cross-layer.md", "Cross-layer check spec"),
-            (".claude/commands/trellis/check-backend.md", "Backend check spec"),
-            (".claude/commands/trellis/check-frontend.md", "Frontend check spec"),
+            (".claude/commands/trellis/check.md", "Code quality check spec"),
         ]
         for file_path, description in check_files:
             content = read_file_content(repo_root, file_path)
@@ -432,8 +438,7 @@ def get_debug_context(repo_root: str, task_dir: str) -> str:
             context_parts.append(f"=== {file_path} (Dev spec) ===\n{content}")
 
         check_files = [
-            (".claude/commands/trellis/check-backend.md", "Backend check spec"),
-            (".claude/commands/trellis/check-frontend.md", "Frontend check spec"),
+            (".claude/commands/trellis/check.md", "Code quality check spec"),
             (".claude/commands/trellis/check-cross-layer.md", "Cross-layer check spec"),
         ]
         for file_path, description in check_files:
@@ -603,24 +608,34 @@ def get_research_context(repo_root: str, task_dir: str | None) -> str:
     """
     context_parts = []
 
-    # 1. Project structure overview (uses constants for paths)
+    # 1. Project structure overview (dynamically discover spec directories)
     spec_path = f"{DIR_WORKFLOW}/{DIR_SPEC}"
+    spec_root = Path(repo_root) / DIR_WORKFLOW / DIR_SPEC
+
+    # Build spec tree dynamically
+    tree_lines = [f"{spec_path}/"]
+    if spec_root.is_dir():
+        pkg_dirs = sorted(d for d in spec_root.iterdir() if d.is_dir())
+        for i, pkg_dir in enumerate(pkg_dirs):
+            is_last = i == len(pkg_dirs) - 1
+            prefix = "└── " if is_last else "├── "
+            layers = sorted(d.name for d in pkg_dir.iterdir() if d.is_dir())
+            layer_info = f" ({', '.join(layers)})" if layers else ""
+            tree_lines.append(f"{prefix}{pkg_dir.name}/{layer_info}")
+
+    spec_tree = "\n".join(tree_lines)
+
     project_structure = f"""## Project Spec Directory Structure
 
 ```
-{spec_path}/
-├── shared/      # Cross-project common specs (TypeScript, code quality, git)
-├── frontend/    # Frontend standards
-├── backend/     # Backend standards
-└── guides/      # Thinking guides (cross-layer, code reuse, etc.)
-
-{DIR_WORKFLOW}/big-question/  # Known issues and pitfalls
+{spec_tree}
 ```
 
+To get structured package info, run: `python3 ./{DIR_WORKFLOW}/scripts/get_context.py --mode packages`
+
 ## Search Tips
 
 - Spec files: `{spec_path}/**/*.md`
-- Known issues: `{DIR_WORKFLOW}/big-question/`
 - Code search: Use Glob and Grep tools
 - Tech solutions: Use mcp__exa__web_search_exa or mcp__exa__get_code_context_exa"""
 

package/dist/templates/claude/hooks/ralph-loop.py

@@ -72,7 +72,14 @@ def get_current_task(repo_root: str) -> str | None:
     try:
         with open(current_task_file, "r", encoding="utf-8") as f:
             content = f.read().strip()
-            return content if content else None
+            if not content:
+                return None
+            normalized = content.replace("\\", "/")
+            while normalized.startswith("./"):
+                normalized = normalized[2:]
+            if normalized.startswith("tasks/"):
+                normalized = f".trellis/{normalized}"
+            return normalized
     except Exception:
         return None
 
@@ -258,17 +265,18 @@ def main():
         sys.exit(0)
 
     # Get subagent info
-    subagent_type = input_data.get("subagent_type", "")
-    agent_output = input_data.get("agent_output", "")
-    original_prompt = input_data.get("prompt", "")
+    # Field names per Claude Code SubagentStop event schema:
+    #   agent_type, last_assistant_message, agent_id, agent_transcript_path, cwd
+    # The event does NOT carry a `prompt` field, so finish-phase detection
+    # based on a `[finish]` marker in the user prompt is no longer possible
+    # here; finish-phase skip logic should be reintroduced via task.json
+    # state (e.g. current_phase) in a follow-up.
+    agent_type = input_data.get("agent_type", "")
+    last_assistant_message = input_data.get("last_assistant_message", "")
     cwd = input_data.get("cwd", os.getcwd())
 
     # Only control check agent
-    if subagent_type != TARGET_AGENT:
-        sys.exit(0)
-
-    # Skip Ralph Loop for finish phase (already verified in check phase)
-    if "[finish]" in original_prompt.lower():
+    if agent_type != TARGET_AGENT:
         sys.exit(0)
 
     # Find repo root
@@ -350,7 +358,7 @@ def main():
     else:
         # No verify commands, fall back to completion markers
         markers = get_completion_markers(repo_root, task_dir)
-        all_complete, missing = check_completion(agent_output, markers)
+        all_complete, missing = check_completion(last_assistant_message, markers)
 
         if all_complete:
             # All checks complete, allow stop

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

@@ -65,23 +65,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"
 
@@ -119,6 +143,151 @@ def _get_task_status(trellis_dir: Path) -> str:
     return f"Status: READY\nTask: {task_title}\nNext: Continue with implement or check"
 
 
+def _load_trellis_config(trellis_dir: Path) -> tuple:
+    """Load Trellis config for session-start decisions.
+
+    Returns:
+        (is_mono, packages_dict, spec_scope, task_pkg, default_pkg)
+    """
+    scripts_dir = trellis_dir / "scripts"
+    if str(scripts_dir) not in sys.path:
+        sys.path.insert(0, str(scripts_dir))
+
+    try:
+        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)
+        packages = get_packages(repo_root) or {}
+        scope = get_spec_scope(repo_root)
+
+        # Get active task's package
+        task_pkg = None
+        current = get_current_task(repo_root)
+        if current:
+            task_json = repo_root / current / "task.json"
+            if task_json.is_file():
+                try:
+                    data = json.loads(task_json.read_text(encoding="utf-8"))
+                    if isinstance(data, dict):
+                        tp = data.get("package")
+                        if isinstance(tp, str) and tp:
+                            task_pkg = tp
+                except (json.JSONDecodeError, OSError):
+                    pass
+
+        default_pkg = get_default_package(repo_root)
+        return is_mono, packages, scope, task_pkg, default_pkg
+    except Exception:
+        return False, {}, None, None, None
+
+
+def _check_legacy_spec(trellis_dir: Path, is_mono: bool, packages: dict) -> str | None:
+    """Check for legacy spec directory structure in monorepo.
+
+    Returns warning message if legacy structure detected, None otherwise.
+    """
+    if not is_mono or not packages:
+        return None
+
+    spec_dir = trellis_dir / "spec"
+    if not spec_dir.is_dir():
+        return None
+
+    # Check for legacy flat spec dirs (spec/backend/, spec/frontend/ with index.md)
+    has_legacy = False
+    for legacy_name in ("backend", "frontend"):
+        legacy_dir = spec_dir / legacy_name
+        if legacy_dir.is_dir() and (legacy_dir / "index.md").is_file():
+            has_legacy = True
+            break
+
+    if not has_legacy:
+        return None
+
+    # Check which packages are missing spec/<pkg>/ directory
+    missing = [
+        name for name in sorted(packages.keys())
+        if not (spec_dir / name).is_dir()
+    ]
+
+    if not missing:
+        return None  # All packages have spec dirs
+
+    if len(missing) == len(packages):
+        return (
+            f"[!] Legacy spec structure detected: found `spec/backend/` or `spec/frontend/` "
+            f"but no package-scoped `spec/<package>/` directories.\n"
+            f"Monorepo packages: {', '.join(sorted(packages.keys()))}\n"
+            f"Please reorganize: `spec/backend/` -> `spec/<package>/backend/`"
+        )
+    return (
+        f"[!] Partial spec migration detected: packages {', '.join(missing)} "
+        f"still missing `spec/<pkg>/` directory.\n"
+        f"Please complete migration for all packages."
+    )
+
+
+def _resolve_spec_scope(
+    is_mono: bool,
+    packages: dict,
+    scope,
+    task_pkg: str | None,
+    default_pkg: str | None,
+) -> set | None:
+    """Resolve which packages should have their specs injected.
+
+    Returns:
+        Set of package names to include, or None for full scan.
+    """
+    if not is_mono or not packages:
+        return None  # Single-repo: full scan
+
+    if scope is None:
+        return None  # No scope configured: full scan
+
+    if isinstance(scope, str) and scope == "active_task":
+        if task_pkg and task_pkg in packages:
+            return {task_pkg}
+        if default_pkg and default_pkg in packages:
+            return {default_pkg}
+        return None  # Fallback to full scan
+
+    if isinstance(scope, list):
+        valid = set()
+        for entry in scope:
+            if entry in packages:
+                valid.add(entry)
+            else:
+                print(
+                    f"Warning: spec_scope contains unknown package: {entry}, ignoring",
+                    file=sys.stderr,
+                )
+
+        if valid:
+            # Warn if active task is out of scope
+            if task_pkg and task_pkg not in valid:
+                print(
+                    f"Warning: active task package '{task_pkg}' is out of configured spec_scope",
+                    file=sys.stderr,
+                )
+            return valid
+
+        # All entries invalid: fallback chain
+        print(
+            "Warning: all spec_scope entries invalid, falling back to task/default/full",
+            file=sys.stderr,
+        )
+        if task_pkg and task_pkg in packages:
+            return {task_pkg}
+        if default_pkg and default_pkg in packages:
+            return {default_pkg}
+        return None  # Full scan
+
+    return None  # Unknown scope type: full scan
+
+
 def main():
     if should_skip_injection():
         sys.exit(0)
@@ -127,6 +296,10 @@ def main():
     trellis_dir = project_dir / ".trellis"
     claude_dir = project_dir / ".claude"
 
+    # Load config for scope filtering and legacy detection
+    is_mono, packages, scope_config, task_pkg, default_pkg = _load_trellis_config(trellis_dir)
+    allowed_pkgs = _resolve_spec_scope(is_mono, packages, scope_config, task_pkg, default_pkg)
+
     output = StringIO()
 
     output.write("""<session-context>
@@ -136,6 +309,11 @@ Read and follow all instructions below carefully.
 
 """)
 
+    # Legacy migration warning
+    legacy_warning = _check_legacy_spec(trellis_dir, is_mono, packages)
+    if legacy_warning:
+        output.write(f"<migration-warning>\n{legacy_warning}\n</migration-warning>\n\n")
+
     output.write("<current-state>\n")
     context_script = trellis_dir / "scripts" / "get_context.py"
     output.write(run_script(context_script))
@@ -155,13 +333,27 @@ Read and follow all instructions below carefully.
         for sub in sorted(spec_dir.iterdir()):
             if not sub.is_dir() or sub.name.startswith("."):
                 continue
+
+            # Always include guides/ regardless of scope
+            if sub.name == "guides":
+                index_file = sub / "index.md"
+                if index_file.is_file():
+                    output.write(f"## {sub.name}\n")
+                    output.write(read_file(index_file))
+                    output.write("\n\n")
+                continue
+
             index_file = sub / "index.md"
             if index_file.is_file():
+                # Flat spec dir (single-repo layer like spec/backend/)
                 output.write(f"## {sub.name}\n")
                 output.write(read_file(index_file))
                 output.write("\n\n")
             else:
-                # Check for nested package dirs (monorepo: spec/<pkg>/<layer>/index.md)
+                # Nested package dirs (monorepo: spec/<pkg>/<layer>/index.md)
+                # Apply scope filter
+                if allowed_pkgs is not None and sub.name not in allowed_pkgs:
+                    continue
                 for nested in sorted(sub.iterdir()):
                     if not nested.is_dir():
                         continue
@@ -180,7 +372,7 @@ Read and follow all instructions below carefully.
     output.write(start_md)
     output.write("\n</instructions>\n\n")
 
-    # R2: Check task status and inject structured tag
+    # Check task status and inject structured tag
     task_status = _get_task_status(trellis_dir)
     output.write(f"<task-status>\n{task_status}\n</task-status>\n\n")
 

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

@@ -0,0 +1,211 @@
+#!/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
+"""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+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. Returns dict with title/status/priority or None."""
+    task_ref = _normalize_task_ref(_read_text(trellis_dir / ".current-task"))
+    if not task_ref:
+        return None
+
+    # Resolve task directory
+    task_path = _resolve_task_dir(trellis_dir, task_ref)
+    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"),
+    }
+
+
+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 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(trellis_dir) 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)")
+
+    five_hr = cc_data.get("rate_limits", {}).get("five_hour", {}).get("used_percentage")
+    if five_hr is not None:
+        parts.append(f"5h {int(five_hr)}%")
+    seven_day = cc_data.get("rate_limits", {}).get("seven_day", {}).get("used_percentage")
+    if seven_day is not None:
+        parts.append(f"7d {int(seven_day)}%")
+
+    info_line = SEP.join(parts)
+
+    # Output: task line (only if active) + info line
+    if task:
+        print(f"\033[36m[{task['priority']}]\033[0m {task['title']} \033[33m({task['status']})\033[0m")
+    print(info_line)
+
+
+if __name__ == "__main__":
+    main()

package/dist/templates/claude/settings.json

@@ -1,4 +1,8 @@
 {
+  "statusLine": {
+    "type": "command",
+    "command": "{{PYTHON_CMD}} .claude/hooks/statusline.py"
+  },
   "hooks": {
     "SessionStart": [
       {

package/dist/templates/codebuddy/commands/trellis/before-dev.md

@@ -0,0 +1,29 @@
+Read the relevant development guidelines before starting your task.
+
+Execute these steps:
+
+1. **Discover packages and their spec layers**:
+   ```bash
+   python3 ./.trellis/scripts/get_context.py --mode packages
+   ```
+
+2. **Identify which specs apply** to your task based on:
+   - Which package you're modifying (e.g., `cli/`, `docs-site/`)
+   - What type of work (backend, frontend, unit-test, docs, etc.)
+
+3. **Read the spec index** for each relevant module:
+   ```bash
+   cat .trellis/spec/<package>/<layer>/index.md
+   ```
+   Follow the **"Pre-Development Checklist"** section in the index.
+
+4. **Read the specific guideline files** listed in the Pre-Development Checklist that are relevant to your task. The index is NOT the goal — it points you to the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). Read those files to understand the coding standards and patterns.
+
+5. **Always read shared guides**:
+   ```bash
+   cat .trellis/spec/guides/index.md
+   ```
+
+6. Understand the coding standards and patterns you need to follow, then proceed with your development plan.
+
+This step is **mandatory** before writing any code.