@jahanxu/trellis 0.4.2 → 0.5.0

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

@@ -21,6 +21,7 @@ Context Source: .trellis/.current-task points to task directory
 - info.md         - Technical design
 - codex-review-output.txt - Code Review results
 """
+from __future__ import annotations
 
 # IMPORTANT: Suppress all warnings FIRST
 import warnings
@@ -30,7 +31,6 @@ import json
 import os
 import sys
 from pathlib import Path
-from typing import Optional, List, Tuple
 
 # IMPORTANT: Force stdout to use UTF-8 on Windows
 # This fixes UnicodeEncodeError when outputting non-ASCII characters
@@ -70,7 +70,7 @@ AGENTS_REQUIRE_TASK = (AGENT_IMPLEMENT, AGENT_CHECK, AGENT_DEBUG)
 AGENTS_ALL = (AGENT_IMPLEMENT, AGENT_CHECK, AGENT_DEBUG, AGENT_RESEARCH)
 
 
-def find_repo_root(start_path: str) -> Optional[str]:
+def find_repo_root(start_path: str) -> str | None:
     """
     Find git repo root from start_path upwards
 
@@ -85,7 +85,7 @@ def find_repo_root(start_path: str) -> Optional[str]:
     return None
 
 
-def get_current_task(repo_root: str) -> Optional[str]:
+def get_current_task(repo_root: str) -> str | None:
     """
     Read current task directory path from .trellis/.current-task
 
@@ -162,7 +162,7 @@ def update_current_phase(repo_root: str, task_dir: str, subagent_type: str) -> N
         pass
 
 
-def read_file_content(base_path: str, file_path: str) -> Optional[str]:
+def read_file_content(base_path: str, file_path: str) -> str | None:
     """Read file content, return None if file doesn't exist"""
     full_path = os.path.join(base_path, file_path)
     if os.path.exists(full_path) and os.path.isfile(full_path):
@@ -265,58 +265,6 @@ def read_jsonl_entries(base_path: str, jsonl_path: str) -> list[tuple[str, str]]
     return results
 
 
-def read_source_json(repo_root: str, task_dir: str) -> Optional[dict]:
-    """
-    Read source.json from task directory (三角色协作上游引用)
-
-    Returns:
-        source.json data or None if not exists
-    """
-    source_json_path = os.path.join(repo_root, task_dir, "source.json")
-    if not os.path.exists(source_json_path):
-        return None
-
-    try:
-        with open(source_json_path, "r", encoding="utf-8") as f:
-            return json.load(f)
-    except Exception:
-        return None
-
-
-def inject_upstream_context(repo_root: str, task_dir: str) -> list[tuple[str, str]]:
-    """
-    Inject upstream outputs for three-role collaboration
-
-    Reads source.json and injects:
-    1. Upstream HANDOFF document
-    2. Upstream deliverables (requirements/prototypes)
-
-    Returns:
-        [(path, content), ...]
-    """
-    source_data = read_source_json(repo_root, task_dir)
-    if not source_data or "based_on" not in source_data:
-        return []
-
-    results = []
-    based_on = source_data["based_on"]
-
-    # 1. Inject upstream HANDOFF document
-    handoff_doc = based_on.get("handoff_doc")
-    if handoff_doc:
-        handoff_content = read_file_content(repo_root, handoff_doc)
-        if handoff_content:
-            results.append((handoff_doc, handoff_content))
-
-    # 2. Inject upstream deliverables directory (all .md files)
-    upstream_path = based_on.get("path")
-    if upstream_path:
-        upstream_contents = read_directory_contents(repo_root, upstream_path)
-        results.extend(upstream_contents)
-
-    return results
-
-
 def get_agent_context(repo_root: str, task_dir: str, agent_type: str) -> str:
     """
     Get complete context for specified agent
@@ -346,9 +294,8 @@ def get_implement_context(repo_root: str, task_dir: str) -> str:
 
     Read order:
     1. All files in implement.jsonl (dev specs)
-    2. Upstream outputs (HANDOFF + deliverables, if three-role collaboration)
-    3. prd.md (requirements)
-    4. info.md (technical design)
+    2. prd.md (requirements)
+    3. info.md (technical design)
     """
     context_parts = []
 
@@ -357,19 +304,12 @@ def get_implement_context(repo_root: str, task_dir: str) -> str:
     if base_context:
         context_parts.append(base_context)
 
-    # 2. Inject upstream outputs (三角色协作)
-    upstream_entries = inject_upstream_context(repo_root, task_dir)
-    if upstream_entries:
-        context_parts.append("=== Upstream Outputs (三角色协作上游产出) ===")
-        for file_path, content in upstream_entries:
-            context_parts.append(f"=== {file_path} ===\n{content}")
-
-    # 3. Requirements document
+    # 2. Requirements document
     prd_content = read_file_content(repo_root, f"{task_dir}/prd.md")
     if prd_content:
         context_parts.append(f"=== {task_dir}/prd.md (Requirements) ===\n{prd_content}")
 
-    # 4. Technical design
+    # 3. Technical design
     info_content = read_file_content(repo_root, f"{task_dir}/info.md")
     if info_content:
         context_parts.append(
@@ -385,8 +325,7 @@ def get_check_context(repo_root: str, task_dir: str) -> str:
 
     Read order:
     1. All files in check.jsonl (check specs + dev specs)
-    2. Upstream outputs (HANDOFF + deliverables, if three-role collaboration)
-    3. prd.md (for understanding task intent)
+    2. prd.md (for understanding task intent)
     """
     context_parts = []
 
@@ -414,14 +353,7 @@ def get_check_context(repo_root: str, task_dir: str) -> str:
         for file_path, content in spec_entries:
             context_parts.append(f"=== {file_path} (Dev spec) ===\n{content}")
 
-    # 2. Inject upstream outputs (三角色协作)
-    upstream_entries = inject_upstream_context(repo_root, task_dir)
-    if upstream_entries:
-        context_parts.append("=== Upstream Outputs (三角色协作上游产出) ===")
-        for file_path, content in upstream_entries:
-            context_parts.append(f"=== {file_path} ===\n{content}")
-
-    # 3. Requirements document (for understanding task intent)
+    # 2. Requirements document (for understanding task intent)
     prd_content = read_file_content(repo_root, f"{task_dir}/prd.md")
     if prd_content:
         context_parts.append(
@@ -438,9 +370,8 @@ def get_finish_context(repo_root: str, task_dir: str) -> str:
     Read order:
     1. All files in finish.jsonl (if exists)
     2. Fallback to finish-work.md only (lightweight final check)
-    3. Upstream outputs (HANDOFF + deliverables, if three-role collaboration)
-    4. update-spec.md (for active spec sync)
-    5. prd.md (for verifying requirements are met)
+    3. update-spec.md (for active spec sync)
+    4. prd.md (for verifying requirements are met)
     """
     context_parts = []
 
@@ -460,14 +391,7 @@ def get_finish_context(repo_root: str, task_dir: str) -> str:
                 f"=== .claude/commands/trellis/finish-work.md (Finish checklist) ===\n{finish_work}"
             )
 
-    # 2. Inject upstream outputs (三角色协作)
-    upstream_entries = inject_upstream_context(repo_root, task_dir)
-    if upstream_entries:
-        context_parts.append("=== Upstream Outputs (三角色协作上游产出) ===")
-        for file_path, content in upstream_entries:
-            context_parts.append(f"=== {file_path} ===\n{content}")
-
-    # 3. Spec update process (for active spec sync)
+    # 2. Spec update process (for active spec sync)
     update_spec = read_file_content(
         repo_root, ".claude/commands/trellis/update-spec.md"
     )
@@ -476,7 +400,7 @@ def get_finish_context(repo_root: str, task_dir: str) -> str:
             f"=== .claude/commands/trellis/update-spec.md (Spec update process) ===\n{update_spec}"
         )
 
-    # 4. Requirements document (for verifying requirements are met)
+    # 3. Requirements document (for verifying requirements are met)
     prd_content = read_file_content(repo_root, f"{task_dir}/prd.md")
     if prd_content:
         context_parts.append(
@@ -492,8 +416,7 @@ def get_debug_context(repo_root: str, task_dir: str) -> str:
 
     Read order:
     1. All files in debug.jsonl (specs needed for fixing)
-    2. Upstream outputs (HANDOFF + deliverables, if three-role collaboration)
-    3. codex-review-output.txt (Codex Review results)
+    2. codex-review-output.txt (Codex Review results)
     """
     context_parts = []
 
@@ -519,14 +442,7 @@ def get_debug_context(repo_root: str, task_dir: str) -> str:
             if content:
                 context_parts.append(f"=== {file_path} ({description}) ===\n{content}")
 
-    # 2. Inject upstream outputs (三角色协作)
-    upstream_entries = inject_upstream_context(repo_root, task_dir)
-    if upstream_entries:
-        context_parts.append("=== Upstream Outputs (三角色协作上游产出) ===")
-        for file_path, content in upstream_entries:
-            context_parts.append(f"=== {file_path} ===\n{content}")
-
-    # 3. Codex review output (if exists)
+    # 2. Codex review output (if exists)
     codex_output = read_file_content(repo_root, f"{task_dir}/codex-review-output.txt")
     if codex_output:
         context_parts.append(
@@ -678,7 +594,7 @@ Dev specs and Codex Review results:
 - Report which issues were fixed and which files were modified"""
 
 
-def get_research_context(repo_root: str, task_dir: Optional[str]) -> str:
+def get_research_context(repo_root: str, task_dir: str | None) -> str:
     """
     Context for Research Agent
 

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

@@ -17,6 +17,7 @@ State file: .trellis/.ralph-state.json
 - Tracks current iteration count per session
 - Resets when task changes
 """
+from __future__ import annotations
 
 # IMPORTANT: Suppress all warnings FIRST
 import warnings

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

@@ -3,6 +3,7 @@
 """
 Session Start Hook - Inject structured context
 """
+from __future__ import annotations
 
 # IMPORTANT: Suppress all warnings FIRST
 import warnings
@@ -65,30 +66,167 @@ def run_script(script_path: Path) -> str:
         return "No context available"
 
 
-def run_script_with_args(script_path: Path, args: list[str]) -> str:
-    """Run script with additional arguments"""
+def detect_role(trellis_dir: Path) -> str | None:
+    """Detect role from developer name ({role}-{name} convention)."""
+    dev_file = trellis_dir / ".developer"
+    if not dev_file.is_file():
+        return None
     try:
-        if script_path.suffix == ".py":
-            env = os.environ.copy()
-            env["PYTHONIOENCODING"] = "utf-8"
-            cmd = [sys.executable, "-W", "ignore", str(script_path)] + args
-        else:
-            env = os.environ
-            cmd = [str(script_path)] + args
+        content = dev_file.read_text(encoding="utf-8")
+        for line in content.splitlines():
+            if line.startswith("name="):
+                name = line.split("=", 1)[1].strip()
+                # Parse role from {role}-{name} pattern
+                if "-" in name:
+                    role = name.split("-", 1)[0]
+                    if role in ("pm", "designer", "frontend", "frontend-impl"):
+                        return role
+    except (OSError, IOError):
+        pass
+    return None
+
+
+def inject_upstream_context(trellis_dir: Path, project_dir: Path, output: StringIO) -> None:
+    """Inject upstream context when source.json exists in current task."""
+    current_task_file = trellis_dir / ".current-task"
+    if not current_task_file.is_file():
+        return
 
-        result = subprocess.run(
-            cmd,
-            capture_output=True,
-            text=True,
-            encoding="utf-8",
-            errors="replace",
-            timeout=5,
-            cwd=script_path.parent.parent.parent,
-            env=env,
-        )
-        return result.stdout if result.returncode == 0 else "No available tasks"
-    except (subprocess.TimeoutExpired, FileNotFoundError, PermissionError):
-        return "No available tasks"
+    try:
+        task_rel = current_task_file.read_text(encoding="utf-8").strip()
+    except (OSError, IOError):
+        return
+
+    if not task_rel:
+        return
+
+    task_dir = project_dir / task_rel
+    source_file = task_dir / "source.json"
+    if not source_file.is_file():
+        return
+
+    try:
+        source = json.loads(source_file.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return
+
+    based_on = source.get("based_on")
+    if not based_on:
+        return
+
+    output.write("<upstream-context>\n")
+    output.write("## Based on Upstream Deliverable\n")
+    output.write(f"- Type: {based_on.get('type', '?')}\n")
+    output.write(f"- ID: {based_on.get('id', '?')}\n")
+    output.write(f"- Path: {based_on.get('path', '?')}\n\n")
+
+    # Read HANDOFF document
+    handoff_path = project_dir / based_on.get("handoff_doc", "")
+    if handoff_path.is_file():
+        output.write("### Handoff Document\n")
+        handoff_content = read_file(handoff_path)
+        if len(handoff_content) > 3000:
+            handoff_content = handoff_content[:3000] + "\n... (truncated)"
+        output.write(handoff_content)
+        output.write("\n\n")
+
+    # Read upstream deliverable files
+    source_path = project_dir / based_on.get("path", "")
+    if source_path.is_dir():
+        output.write("### Upstream Deliverable Files\n")
+        total_size = 0
+        text_exts = {".md", ".txt", ".tsx", ".ts", ".jsx", ".js", ".vue", ".css", ".json", ".yaml", ".yml", ".html"}
+        for fpath in sorted(source_path.rglob("*")):
+            if not fpath.is_file():
+                continue
+            if fpath.name == "HANDOFF.md":
+                continue
+            if fpath.suffix not in text_exts:
+                continue
+            if total_size >= 50000:
+                output.write("\n(total size cap reached, remaining files omitted)\n")
+                break
+            try:
+                content = fpath.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                continue
+            rel = fpath.relative_to(source_path)
+            output.write(f"\n#### {rel}\n")
+            ext = fpath.suffix[1:] if fpath.suffix else ""
+            if len(content) > 3000:
+                content = content[:3000] + "\n... (truncated)"
+            output.write(f"```{ext}\n{content}\n```\n")
+            total_size += len(content)
+
+    output.write("</upstream-context>\n\n")
+
+
+def inject_pool_summary(trellis_dir: Path, output: StringIO) -> None:
+    """Inject available tasks summary from pool files."""
+    pool_dir = trellis_dir / "pool"
+    if not pool_dir.is_dir():
+        return
+
+    pool_files = sorted(pool_dir.glob("*.json"))
+    if not pool_files:
+        return
+
+    has_available = False
+    pool_output = StringIO()
+
+    for pool_file in pool_files:
+        try:
+            data = json.loads(pool_file.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            continue
+
+        available = [
+            i for i in data.get("available", [])
+            if i.get("status") == "available"
+        ]
+        if not available:
+            continue
+
+        has_available = True
+        pool_name = pool_file.stem
+        pool_output.write(f"## Available in {pool_name} ({len(available)})\n")
+        for item in available:
+            completed_by = item.get("completed_by", "?")
+            completed_at = item.get("completed_at", "?")
+            pool_output.write(
+                f"- {item.get('id', '?')}: {item.get('title', '?')} "
+                f"(by {completed_by}, {completed_at})\n"
+            )
+        pool_output.write("\n")
+
+    if has_available:
+        output.write("<available-tasks>\n")
+        output.write(pool_output.getvalue())
+        output.write("Use `/trellis:pick-task <pool> <id>` to start working on an available item.\n")
+        output.write("</available-tasks>\n\n")
+
+
+def inject_role_guidelines(trellis_dir: Path, role: str | None, output: StringIO) -> None:
+    """Inject role-specific guidelines if role is detected."""
+    if not role:
+        return
+
+    role_dir_map = {
+        "pm": "pm",
+        "designer": "designer",
+        "frontend": "frontend-impl",
+        "frontend-impl": "frontend-impl",
+    }
+
+    role_dir = role_dir_map.get(role)
+    if not role_dir:
+        return
+
+    role_index = trellis_dir / "spec" / "roles" / role_dir / "index.md"
+    if role_index.is_file():
+        output.write(f"## Role: {role}\n")
+        output.write(read_file(role_index))
+        output.write("\n\n")
 
 
 def main():
@@ -113,38 +251,6 @@ Read and follow all instructions below carefully.
     output.write(run_script(context_script))
     output.write("\n</current-state>\n\n")
 
-    output.write("<task-pools>\n")
-    pool_script = trellis_dir / "scripts" / "pool.py"
-    developer_script = trellis_dir / "scripts" / "get_developer.py"
-
-    # Get current developer role
-    developer_output = run_script(developer_script).strip()
-    if developer_output and developer_output != "No context available":
-        role = developer_output.split('-')[0] if '-' in developer_output else ""
-        output.write(f"## Current Role: {role}\n\n")
-
-        # Show available task pools based on role
-        if role == "designer":
-            output.write("### Available Requirements (from PM)\n")
-            requirements_output = run_script_with_args(
-                pool_script, ["list", "requirements", "--status", "available"]
-            )
-            output.write(requirements_output)
-            output.write("\n\nUse: `/trellis:pick-task requirements <task-id>` to start\n")
-        elif role == "frontend":
-            output.write("### Available Prototypes (from Designer)\n")
-            prototypes_output = run_script_with_args(
-                pool_script, ["list", "prototypes", "--status", "available"]
-            )
-            output.write(prototypes_output)
-            output.write("\n\nUse: `/trellis:pick-task prototypes <task-id>` to start\n")
-        elif role == "pm":
-            output.write("### PM Role (Pipeline Starting Point)\n")
-            output.write("PM creates tasks directly, not from pool.\n\n")
-            output.write("Use: `python3 .trellis/scripts/task.py create \"<title>\"` to start\n")
-
-    output.write("\n</task-pools>\n\n")
-
     output.write("<workflow>\n")
     workflow_content = read_file(trellis_dir / "workflow.md", "No workflow.md found")
     output.write(workflow_content)
@@ -152,6 +258,10 @@ Read and follow all instructions below carefully.
 
     output.write("<guidelines>\n")
 
+    # Detect role and inject role-specific guidelines
+    role = detect_role(trellis_dir)
+    inject_role_guidelines(trellis_dir, role, output)
+
     output.write("## Frontend\n")
     frontend_index = read_file(
         trellis_dir / "spec" / "frontend" / "index.md", "Not configured"
@@ -174,6 +284,12 @@ Read and follow all instructions below carefully.
 
     output.write("\n</guidelines>\n\n")
 
+    # Inject upstream context (from source.json in current task)
+    inject_upstream_context(trellis_dir, project_dir, output)
+
+    # Inject pool summary (available tasks)
+    inject_pool_summary(trellis_dir, output)
+
     output.write("<instructions>\n")
     start_md = read_file(
         claude_dir / "commands" / "trellis" / "start.md", "No start.md found"

package/dist/templates/iflow/commands/trellis/handoff.md

@@ -0,0 +1,148 @@
+# Handoff - Complete Task and Add to Pool
+
+Complete the current task, generate a HANDOFF.md document, and add the deliverable to the appropriate pool.
+
+---
+
+## Prerequisites
+
+- Must have a current task set (`.trellis/.current-task`)
+- Task must have deliverable files in the output directory
+
+---
+
+## Process `[AI]`
+
+### Step 1: Read Current Task
+
+```bash
+python3 ./.trellis/scripts/get_context.py
+```
+
+Read the task's `task.json` to get:
+- `output_dir`: where deliverables are stored
+- `role`: which role completed this task
+- `title`: task title
+- `slug`: task slug / deliverable ID
+
+If no current task is set, inform the user and stop.
+
+### Step 2: Check Deliverables
+
+Verify that the output directory exists and contains files:
+
+```bash
+ls -la <output_dir>/
+```
+
+If empty or missing, warn the user:
+> "The output directory `<output_dir>` appears empty. Would you like to continue anyway?"
+
+### Step 3: Generate HANDOFF.md
+
+Analyze all files in the output directory and generate a `HANDOFF.md` document.
+
+**For PM role (requirements pool):**
+
+```markdown
+# {Title} - Requirements Handoff
+
+## Task Info
+- **Feature ID**: {slug}
+- **Title**: {title}
+- **Completed by**: {developer}
+- **Completed at**: {timestamp}
+
+## Core Requirements
+(AI-generated summary of PRD key points, 2-3 paragraphs)
+
+## Deliverable Files
+- `prd.md` - Product requirements document
+- (list all files)
+
+## Key Design Points
+1. (extracted from PRD)
+2. ...
+
+## Special Notes for Downstream
+- (important details the Designer should know)
+- (constraints, edge cases, specific UI requirements)
+
+## Related Resources
+- (links if any)
+```
+
+**For Designer role (prototypes pool):**
+
+```markdown
+# {Title} - Prototype Handoff
+
+## Task Info
+- **Feature ID**: {slug}
+- **Based on**: {source requirement}
+- **Completed by**: {developer}
+- **Completed at**: {timestamp}
+
+## Design Notes
+(AI-generated summary of design approach, 2-3 paragraphs)
+
+## Deliverable Files
+- (list all component files)
+
+## Component Structure
+(component tree overview)
+
+## Mock Data Notes
+Current mock data used:
+```typescript
+// Document all mock data and their locations
+// Include file name and line numbers
+```
+
+## Logic for Frontend to Implement
+1. Replace mock login handler with real API call (file:line)
+2. Add error handling for network failures
+3. Implement loading state management
+4. ...
+
+## Special Notes for Downstream
+- (interactions to preserve)
+- (SDK dependencies)
+- (form validation already implemented)
+```
+
+Write the generated HANDOFF.md to `<output_dir>/HANDOFF.md`.
+
+### Step 4: Ask for Handoff Message (Optional)
+
+Ask the user:
+> "Any additional notes for the downstream role? (Press Enter to skip)"
+
+If provided, append to the Special Notes section.
+
+### Step 5: Add to Pool
+
+Determine the target pool based on role:
+- `pm` -> `requirements`
+- `designer` -> `prototypes`
+- `frontend-impl` or `frontend` -> `implementations`
+
+```bash
+python3 ./.trellis/scripts/pool.py add <pool> <slug> "<title>" <output_dir>
+```
+
+### Step 6: Report
+
+Output a summary:
+```
+Handoff complete!
+- Deliverable: <slug>
+- Pool: <pool>
+- HANDOFF.md: <output_dir>/HANDOFF.md
+- Status: available
+
+Next: The downstream role can pick this up with:
+  /trellis:pick-task <pool> <slug>
+```
+
+Remind the user to commit and push so the downstream role can access the deliverables.