@blxzer/cursor-trellis 0.1.0 → 0.1.2

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

@@ -0,0 +1,527 @@
+#!/usr/bin/env python3
+"""
+Subagent dispatch prompt builder — single source for hook + CLI Layer 2.
+
+Agent-facing only; not documented in user README.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Literal
+
+from .io import read_json
+from .paths import FILE_TASK_JSON
+
+DIR_WORKFLOW = ".trellis"
+DIR_SPEC = "spec"
+
+AGENT_IMPLEMENT = "trellis-implement"
+AGENT_CHECK = "trellis-check"
+AGENT_RESEARCH = "trellis-research"
+
+AGENTS_ALL = (AGENT_IMPLEMENT, AGENT_CHECK, AGENT_RESEARCH)
+AGENTS_REQUIRE_TASK = (AGENT_IMPLEMENT, AGENT_CHECK)
+
+INJECTION_MARKER = "<!-- trellis-hook-injected -->"
+
+DispatchRole = Literal["implement", "check", "research"]
+
+DEFAULT_SCOPES: dict[str, str] = {
+    "implement": (
+        "Implement per prd.md and implement.md; run project lint/typecheck/tests."
+    ),
+    "check": (
+        "Review against prd/spec; fix in-contract defects; record evidence in verify.md."
+    ),
+    "research": "Research and persist to {TASK}/research/.",
+}
+
+
+def prompt_has_injection_marker(text: str) -> bool:
+    return INJECTION_MARKER in text
+
+
+def read_file_content(base_path: str, file_path: str) -> str | None:
+    full_path = os.path.join(base_path, file_path)
+    if os.path.exists(full_path) and os.path.isfile(full_path):
+        try:
+            with open(full_path, "r", encoding="utf-8") as f:
+                return f.read()
+        except OSError:
+            return None
+    return None
+
+
+def read_directory_contents(
+    base_path: str, dir_path: str, max_files: int = 20
+) -> list[tuple[str, str]]:
+    full_path = os.path.join(base_path, dir_path)
+    if not os.path.exists(full_path) or not os.path.isdir(full_path):
+        return []
+
+    results: list[tuple[str, str]] = []
+    try:
+        md_files = sorted(
+            f
+            for f in os.listdir(full_path)
+            if f.endswith(".md") and os.path.isfile(os.path.join(full_path, f))
+        )
+        for filename in md_files[:max_files]:
+            file_full_path = os.path.join(full_path, filename)
+            relative_path = os.path.join(dir_path, filename)
+            try:
+                with open(file_full_path, "r", encoding="utf-8") as f:
+                    results.append((relative_path, f.read()))
+            except OSError:
+                continue
+    except OSError:
+        pass
+    return results
+
+
+def read_jsonl_entries(
+    base_path: str,
+    jsonl_path: str,
+    *,
+    warn_prefix: str = "subagent-dispatch",
+) -> list[tuple[str, str]]:
+    full_path = os.path.join(base_path, jsonl_path)
+    if not os.path.exists(full_path):
+        print(
+            f"[{warn_prefix}] WARN: {jsonl_path} not found — "
+            "sub-agent will receive only task artifacts",
+            file=sys.stderr,
+        )
+        return []
+
+    results: list[tuple[str, str]] = []
+    saw_real_entry = False
+    try:
+        with open(full_path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    item = json.loads(line)
+                    file_path = item.get("file") or item.get("path")
+                    entry_type = item.get("type", "file")
+                    if not file_path:
+                        continue
+                    saw_real_entry = True
+                    if entry_type == "directory":
+                        results.extend(read_directory_contents(base_path, file_path))
+                    else:
+                        content = read_file_content(base_path, file_path)
+                        if content:
+                            results.append((file_path, content))
+                except json.JSONDecodeError:
+                    continue
+    except OSError:
+        pass
+
+    if not saw_real_entry:
+        print(
+            f"[{warn_prefix}] WARN: {jsonl_path} has no curated entries "
+            "(only seed / empty) — sub-agent will receive only task artifacts.",
+            file=sys.stderr,
+        )
+    return results
+
+
+def get_agent_context(repo_root: str, task_dir: str, agent_type: str) -> str:
+    context_parts: list[str] = []
+    agent_jsonl = f"{task_dir}/{agent_type}.jsonl"
+    for file_path, content in read_jsonl_entries(repo_root, agent_jsonl):
+        context_parts.append(f"=== {file_path} ===\n{content}")
+    return "\n\n".join(context_parts)
+
+
+def get_implement_context(repo_root: str, task_dir: str) -> str:
+    context_parts: list[str] = []
+    base_context = get_agent_context(repo_root, task_dir, "implement")
+    if base_context:
+        context_parts.append(base_context)
+
+    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}")
+
+    design_content = read_file_content(repo_root, f"{task_dir}/design.md")
+    if design_content:
+        context_parts.append(
+            f"=== {task_dir}/design.md (Technical Design) ===\n{design_content}"
+        )
+
+    implement_plan_content = read_file_content(repo_root, f"{task_dir}/implement.md")
+    if implement_plan_content:
+        context_parts.append(
+            f"=== {task_dir}/implement.md (Execution Plan) ===\n{implement_plan_content}"
+        )
+    return "\n\n".join(context_parts)
+
+
+def get_check_context(repo_root: str, task_dir: str) -> str:
+    context_parts: list[str] = []
+    for file_path, content in read_jsonl_entries(repo_root, f"{task_dir}/check.jsonl"):
+        context_parts.append(f"=== {file_path} ===\n{content}")
+
+    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}")
+
+    design_content = read_file_content(repo_root, f"{task_dir}/design.md")
+    if design_content:
+        context_parts.append(
+            f"=== {task_dir}/design.md (Technical Design) ===\n{design_content}"
+        )
+
+    implement_plan_content = read_file_content(repo_root, f"{task_dir}/implement.md")
+    if implement_plan_content:
+        context_parts.append(
+            f"=== {task_dir}/implement.md (Execution Plan) ===\n{implement_plan_content}"
+        )
+    return "\n\n".join(context_parts)
+
+
+def get_finish_context(repo_root: str, task_dir: str) -> str:
+    return get_check_context(repo_root, task_dir)
+
+
+def get_research_context(repo_root: str, task_dir: str | None) -> str:
+    _ = task_dir
+    spec_path = f"{DIR_WORKFLOW}/{DIR_SPEC}"
+    spec_root = Path(repo_root) / DIR_WORKFLOW / DIR_SPEC
+
+    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}")
+
+    project_structure = f"""## Project Spec Directory Structure
+
+```
+{chr(10).join(tree_lines)}
+```
+
+To get structured package info, run: `python ./{DIR_WORKFLOW}/scripts/get_context.py --mode packages`
+
+## Search Tips
+
+- Spec files: `{spec_path}/**/*.md`
+- Code search: Use Glob and Grep tools
+- External facts / docs: load `smart-search-cli` skill and use Bash (`smart-search` CLI), not Cursor WebSearch/WebFetch by default"""
+    return project_structure
+
+
+def build_implement_prompt(original_prompt: str, context: str) -> str:
+    return f"""{INJECTION_MARKER}
+# Implement Agent Task
+
+You are the Implement Agent in the Multi-Agent Pipeline.
+
+## Your Context
+
+All the information you need has been prepared for you:
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Understand specs** - All dev specs are injected above, understand them
+2. **Understand task artifacts** - Read requirements, technical design if present, and execution plan if present
+3. **Implement feature** - Implement following specs and task artifacts
+4. **Self-check** - Ensure code quality against check specs
+
+## Important Constraints
+
+- Do NOT execute git commit, only code modifications
+- Follow all dev specs injected above
+- Report list of modified/created files when done"""
+
+
+def build_check_prompt(original_prompt: str, context: str) -> str:
+    return f"""{INJECTION_MARKER}
+# Check Agent Task
+
+You are the Check Agent in the Multi-Agent Pipeline (code and cross-layer checker).
+
+## Your Context
+
+All check specs and dev specs you need:
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Get changes** - Run `git diff --name-only` and `git diff` to get code changes
+2. **Check against specs** - Check item by item against specs above
+3. **Self-fix** - Fix issues directly, don't just report
+4. **Run verification** - Run project's lint and typecheck commands
+
+## Important Constraints
+
+- Fix issues yourself, don't just report
+- Must execute complete checklist in check specs
+- Pay special attention to impact radius analysis (L1-L5)"""
+
+
+def build_finish_prompt(original_prompt: str, context: str) -> str:
+    return f"""{INJECTION_MARKER}
+# Finish Agent Task
+
+You are performing the final check before creating a PR.
+
+## Your Context
+
+Finish checklist and requirements:
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Review changes** - Run `git diff --name-only` to see all changed files
+2. **Verify task artifacts** - Check requirements in prd.md and, when present, design.md / implement.md
+3. **Spec sync** - Analyze whether changes introduce new patterns, contracts, or conventions
+4. **Run final checks** - Execute lint and typecheck
+5. **Confirm ready** - Ensure code is ready for PR
+
+## Important Constraints
+
+- You MAY update spec files when gaps are detected (use update-spec.md as guide)
+- MUST read the target spec file BEFORE editing (avoid duplicating existing content)
+- Do NOT update specs for trivial changes (typos, formatting, obvious fixes)
+- Verify all acceptance criteria in prd.md are met"""
+
+
+def build_research_prompt(original_prompt: str, context: str) -> str:
+    return f"""{INJECTION_MARKER}
+# Research Agent Task
+
+You are the Trellis Research Agent.
+
+## Core Principle
+
+**You do one thing: find, explain, and PERSIST information.**
+
+Conversations get compacted; files do not. Every research topic MUST be written under `{{TASK_DIR}}/research/`. Chat-only findings are a failure.
+
+## Dispatch contract
+
+- External facts: load `smart-search-cli` skill + Bash — default **not** Cursor `WebSearch`/`WebFetch`.
+- Do NOT spawn nested `trellis-implement` / `trellis-check` / `trellis-research` sub-agents.
+
+## Project Info
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Resolve task** — ensure `{{TASK_DIR}}/research/` exists
+2. **Classify** — internal / external / mixed
+3. **Search** — Glob/Grep/Read for repo; `smart-search-cli` + CLI for external
+4. **Persist** — Write each topic to `{{TASK_DIR}}/research/<topic-slug>.md`
+5. **Report** — Reply with file paths + one-line summaries only
+
+## Write ALLOWED
+
+- `{{TASK_DIR}}/research/*.md` only
+
+## Write FORBIDDEN
+
+- Code, `.trellis/spec/`, platform config, git operations"""
+
+
+def _repo_relative(task_dir: Path, repo_root: Path) -> str:
+    try:
+        return task_dir.relative_to(repo_root).as_posix()
+    except ValueError:
+        return task_dir.as_posix()
+
+
+def _truncate_context(context: str, max_chars: int | None, warnings: list[str]) -> str:
+    if max_chars is None or len(context) <= max_chars:
+        return context
+    warnings.append(f"context truncated at {max_chars} chars")
+    return context[:max_chars] + "\n...[truncated]..."
+
+
+def _resolve_scope(role: DispatchRole, scope: str | None, task_rel: str) -> str:
+    if scope and scope.strip():
+        return scope.strip()
+    default = DEFAULT_SCOPES[role]
+    if role == "research":
+        return default.replace("{TASK}", task_rel)
+    return default
+
+
+def _compose_task_prompt(task_rel: str, scope: str) -> str:
+    return f"Selected task: {task_rel}\n\n{scope}"
+
+
+def build_dispatch_prompt(
+    repo_root: Path,
+    task_dir: Path,
+    role: str,
+    *,
+    scope: str | None = None,
+    finish: bool = False,
+    max_chars: int | None = None,
+    original_prompt: str | None = None,
+    require_in_progress: bool = True,
+) -> tuple[str | None, list[str], list[str]]:
+    """
+    Build a full subagent dispatch prompt.
+
+    Returns (prompt, warnings, errors). prompt is None on hard failure.
+    When original_prompt is set (hook path), it is used as the task section as-is.
+    """
+    warnings: list[str] = []
+    errors: list[str] = []
+
+    if role not in ("implement", "check", "research"):
+        errors.append(f"invalid role: {role!r}")
+        return None, warnings, errors
+
+    repo_root_str = str(repo_root)
+    if not task_dir.is_dir():
+        errors.append(f"task directory not found: {task_dir}")
+        return None, warnings, errors
+
+    task_rel = _repo_relative(task_dir, repo_root)
+    prd_path = task_dir / "prd.md"
+    if role in ("implement", "check"):
+        if not prd_path.is_file():
+            errors.append(f"prd.md missing under {task_rel}")
+            return None, warnings, errors
+    elif not prd_path.is_file():
+        warnings.append(f"prd.md missing under {task_rel}")
+
+    if role in ("implement", "check") and require_in_progress:
+        task_json_path = task_dir / FILE_TASK_JSON
+        task_data = read_json(task_json_path) if task_json_path.is_file() else None
+        status = (task_data or {}).get("status")
+        if status != "in_progress":
+            errors.append(f"task status must be in_progress, got {status!r}")
+
+    if original_prompt is not None:
+        task_prompt = original_prompt
+    else:
+        resolved_scope = _resolve_scope(role, scope, task_rel)  # type: ignore[arg-type]
+        task_prompt = _compose_task_prompt(task_rel, resolved_scope)
+
+    if role == "implement":
+        context = get_implement_context(repo_root_str, task_rel)
+        context = _truncate_context(context, max_chars, warnings)
+        if not context:
+            errors.append("no implement context available")
+            return None, warnings, errors
+        prompt = build_implement_prompt(task_prompt, context)
+    elif role == "check":
+        context = get_finish_context(repo_root_str, task_rel) if finish else get_check_context(
+            repo_root_str, task_rel
+        )
+        context = _truncate_context(context, max_chars, warnings)
+        if not context:
+            errors.append("no check context available")
+            return None, warnings, errors
+        prompt = (
+            build_finish_prompt(task_prompt, context)
+            if finish
+            else build_check_prompt(task_prompt, context)
+        )
+    else:
+        context = get_research_context(repo_root_str, task_rel)
+        context = _truncate_context(context, max_chars, warnings)
+        if not context:
+            errors.append("no research context available")
+            return None, warnings, errors
+        prompt = build_research_prompt(task_prompt, context)
+
+    return prompt, warnings, errors
+
+
+def build_dispatch_prompt_for_agent(
+    repo_root: str,
+    task_dir: str,
+    subagent_type: str,
+    original_prompt: str,
+    *,
+    finish: bool = False,
+    max_chars: int | None = None,
+) -> str | None:
+    """Hook helper: map subagent type to role and build prompt."""
+    if subagent_type == AGENT_RESEARCH and not task_dir:
+        context = get_research_context(repo_root, None)
+        if max_chars is not None and len(context) > max_chars:
+            context = context[:max_chars] + "\n...[truncated]..."
+        if not context:
+            return None
+        return build_research_prompt(original_prompt, context)
+
+    role_map = {
+        AGENT_IMPLEMENT: "implement",
+        AGENT_CHECK: "check",
+        AGENT_RESEARCH: "research",
+    }
+    role = role_map.get(subagent_type)
+    if not role:
+        return None
+
+    repo_path = Path(repo_root)
+    task_path = repo_path / task_dir.replace("\\", "/")
+    is_finish = finish or "[finish]" in original_prompt.lower()
+    prompt, _, errors = build_dispatch_prompt(
+        repo_path,
+        task_path,
+        role,
+        finish=is_finish if role == "check" else False,
+        max_chars=max_chars,
+        original_prompt=original_prompt,
+        require_in_progress=False,
+    )
+    if errors:
+        for item in errors:
+            print(f"[inject-subagent-context] {item}", file=sys.stderr)
+        return None
+    return prompt

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

@@ -1272,6 +1272,38 @@ def cmd_integrate_child(args: argparse.Namespace) -> int:
 # Command: generate-child-prompt / parent-status / review-child
 # =============================================================================
 
+def cmd_generate_dispatch_prompt(args: argparse.Namespace) -> int:
+    """Build a full Task dispatch prompt (Agent-facing CLI Layer 2)."""
+    from .subagent_dispatch import build_dispatch_prompt
+
+    repo_root = get_repo_root()
+    task_dir = resolve_task_dir(args.task_dir, repo_root)
+    role = args.role
+    scope = getattr(args, "scope", None)
+    finish = bool(getattr(args, "finish", False))
+    max_chars = getattr(args, "max_chars", None)
+
+    prompt, warnings, errors = build_dispatch_prompt(
+        repo_root,
+        task_dir,
+        role,
+        scope=scope,
+        finish=finish,
+        max_chars=max_chars,
+    )
+    for item in warnings:
+        print(f"[generate-dispatch-prompt] WARN: {item}", file=sys.stderr)
+    if errors:
+        for item in errors:
+            print(f"[generate-dispatch-prompt] Error: {item}", file=sys.stderr)
+        return 1
+    if prompt is None:
+        print(colored("Error: could not build dispatch prompt", Colors.RED), file=sys.stderr)
+        return 1
+    print(prompt)
+    return 0
+
+
 def cmd_generate_child_prompt(args: argparse.Namespace) -> int:
     """Generate a child implementation prompt for parent orchestration."""
     from .parent_orchestration import build_child_prompt

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

@@ -132,7 +132,7 @@ def get_step(step_id: str) -> str:
 
 
 def _platform_matches(platform: str, block_names: list[str]) -> bool:
-    """Case-insensitive fuzzy match: accept 'cursor', 'Cursor', 'claude-code', 'Claude Code'."""
+    """Case-insensitive fuzzy match: accept 'cursor' or 'Cursor'."""
     needle = platform.lower().replace("-", "").replace("_", "").replace(" ", "")
     for name in block_names:
         hay = name.lower().replace("-", "").replace("_", "").replace(" ", "")
@@ -142,29 +142,8 @@ def _platform_matches(platform: str, block_names: list[str]) -> bool:
 
 
 def resolve_effective_platform(platform: str, config: dict) -> str:
-    """Map ``codex`` to a dispatch-mode-namespaced virtual platform name.
-
-    When ``--platform codex`` is passed, return ``"codex-inline"`` (default)
-    or ``"codex-sub-agent"`` based on ``.trellis/config.yaml`` ``codex.dispatch_mode``.
-    ``filter_platform`` then surfaces blocks whose marker lists include the
-    namespaced name (e.g. ``[codex-sub-agent, ...]`` or ``[codex-inline, Kilo,
-    Antigravity, Windsurf]``).
-
-    Default is ``inline`` because Codex sub-agents run with ``fork_turns="none"``
-    isolation and can't inherit the parent session's task context — inline
-    keeps the main agent in charge so context isn't lost. Invalid / missing
-    values also fall back to inline.
-
-    Other platforms are returned unchanged.
-    """
-    if platform == "codex":
-        mode = "inline"
-        codex_cfg = config.get("codex") if isinstance(config, dict) else None
-        if isinstance(codex_cfg, dict):
-            cfg_mode = codex_cfg.get("dispatch_mode")
-            if cfg_mode in ("inline", "sub-agent"):
-                mode = cfg_mode
-        return f"codex-{mode}"
+    """Return the platform name unchanged (Cursor-only fork)."""
+    _ = config
     return platform
 
 

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

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""CLI: rank codebase path candidates for B/E/D intents (eval / dogfood)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from common.retrieval_result_ranking import rank_retrieval_result_candidates
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Rank retrieval path candidates (caller / trap / env intents).",
+    )
+    parser.add_argument(
+        "--candidates",
+        help="Path to JSON array of candidate objects, or '-' for stdin.",
+    )
+    parser.add_argument(
+        "--intents",
+        required=True,
+        help="Comma-separated intent ids (e.g. caller-chain,env-config-literal).",
+    )
+    parser.add_argument("--top-k", type=int, default=5)
+    parser.add_argument("--expanded-pool-size", type=int, default=None)
+    parser.add_argument(
+        "--caller-pool-expansion",
+        action="store_true",
+        help="Enable caller pool expansion (caller-chain intent).",
+    )
+    parser.add_argument("--min-concrete-callers", type=int, default=3)
+    parser.add_argument("--json", action="store_true", help="Emit JSON (default).")
+    parser.add_argument("--pretty", action="store_true")
+    return parser.parse_args(argv)
+
+
+def load_candidates(source: str | None) -> list[dict]:
+    if source is None or source == "-":
+        raw = sys.stdin.read()
+    else:
+        raw = Path(source).read_text(encoding="utf-8")
+    parsed = json.loads(raw)
+    if not isinstance(parsed, list):
+        raise ValueError("candidates must be a JSON array")
+    return [item for item in parsed if isinstance(item, dict)]
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    try:
+        candidates = load_candidates(args.candidates)
+    except (OSError, json.JSONDecodeError, ValueError) as error:
+        print(f"rank_retrieval_candidates: {error}", file=sys.stderr)
+        return 2
+
+    intents = [part.strip() for part in args.intents.split(",") if part.strip()]
+    expansion = None
+    if args.caller_pool_expansion:
+        expansion = {
+            "enabled": True,
+            "minConcreteCallers": args.min_concrete_callers,
+        }
+
+    result = rank_retrieval_result_candidates(
+        candidates,
+        intents=intents,
+        top_k=args.top_k,
+        expanded_pool_size=args.expanded_pool_size,
+        caller_pool_expansion=expansion,
+    )
+    indent = 2 if args.pretty else None
+    print(json.dumps(result, indent=indent, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())