@mindfoldhq/trellis 0.5.0-beta.8 → 0.5.0-rc.0

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

@@ -3,210 +3,29 @@
 Task JSONL context management.
 
 Provides:
-    cmd_init_context  - Initialize JSONL context files for a task
     cmd_add_context   - Add entry to JSONL context file
     cmd_validate      - Validate JSONL context files
     cmd_list_context  - List JSONL context entries
+
+Note:
+    ``cmd_init_context`` was removed in v0.5.0-beta.12. JSONL context files
+    are now seeded at ``task.py create`` time with a self-describing
+    ``_example`` line; the AI agent curates real entries during Phase 1.3 of
+    the workflow. See ``.trellis/workflow.md`` Phase 1.3 for the current
+    instructions.
 """
 
 from __future__ import annotations
 
 import argparse
 import json
-import sys
 from pathlib import Path
 
-from .cli_adapter import get_cli_adapter_auto
-from .config import (
-    get_packages,
-    is_monorepo,
-    resolve_package,
-    validate_package,
-)
-from .io import read_json, write_json
 from .log import Colors, colored
-from .paths import (
-    DIR_SPEC,
-    DIR_WORKFLOW,
-    FILE_TASK_JSON,
-    get_repo_root,
-)
+from .paths import get_repo_root
 from .task_utils import resolve_task_dir
 
 
-# =============================================================================
-# JSONL Default Content Generators
-# =============================================================================
-
-def get_implement_base() -> list[dict]:
-    """Get base implement context entries."""
-    return [
-        {"file": f"{DIR_WORKFLOW}/workflow.md", "reason": "Project workflow and conventions"},
-    ]
-
-
-def get_implement_backend(package: str | None = None) -> list[dict]:
-    """Get backend implement context entries."""
-    spec_base = f"{DIR_SPEC}/{package}" if package else DIR_SPEC
-    return [
-        {"file": f"{DIR_WORKFLOW}/{spec_base}/backend/index.md", "reason": "Backend development guide"},
-    ]
-
-
-def get_implement_frontend(package: str | None = None) -> list[dict]:
-    """Get frontend implement context entries."""
-    spec_base = f"{DIR_SPEC}/{package}" if package else DIR_SPEC
-    return [
-        {"file": f"{DIR_WORKFLOW}/{spec_base}/frontend/index.md", "reason": "Frontend development guide"},
-    ]
-
-
-def get_check_context(repo_root: Path) -> list[dict]:
-    """Get check context entries."""
-    adapter = get_cli_adapter_auto(repo_root)
-
-    return [
-        {"file": adapter.get_trellis_command_path("finish-work"), "reason": "Finish work checklist"},
-        {"file": adapter.get_trellis_command_path("check"), "reason": "Code quality check spec"},
-    ]
-
-
-def _write_jsonl(path: Path, entries: list[dict]) -> None:
-    """Write entries to JSONL file."""
-    lines = [json.dumps(entry, ensure_ascii=False) for entry in entries]
-    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
-
-
-# =============================================================================
-# Command: init-context
-# =============================================================================
-
-def cmd_init_context(args: argparse.Namespace) -> int:
-    """Initialize JSONL context files for a task."""
-    repo_root = get_repo_root()
-    target_dir = resolve_task_dir(args.dir, repo_root)
-    dev_type = args.type
-
-    if not dev_type:
-        print(colored("Error: Missing arguments", Colors.RED))
-        print("Usage: python3 task.py init-context <task-dir> <dev_type>")
-        print("  dev_type: backend | frontend | fullstack | test | docs")
-        return 1
-
-    if not target_dir.is_dir():
-        print(colored(f"Error: Directory not found: {target_dir}", Colors.RED))
-        return 1
-
-    # Resolve package: --package CLI → task.json.package → default_package
-    cli_package: str | None = getattr(args, "package", None)
-    package: str | None = None
-    if not is_monorepo(repo_root):
-        # Single-repo: ignore --package, no package prefix
-        if cli_package:
-            print(colored("Warning: --package ignored in single-repo project", Colors.YELLOW), file=sys.stderr)
-    elif cli_package:
-        if not validate_package(cli_package, repo_root):
-            packages = get_packages(repo_root)
-            available = ", ".join(sorted(packages.keys())) if packages else "(none)"
-            print(colored(f"Error: unknown package '{cli_package}'. Available: {available}", Colors.RED), file=sys.stderr)
-            return 1
-        package = cli_package
-    else:
-        # Read task.json.package as inferred source
-        task_json_path = target_dir / FILE_TASK_JSON
-        task_pkg_value = None
-        if task_json_path.is_file():
-            task_data = read_json(task_json_path)
-            if isinstance(task_data, dict):
-                task_pkg_value = task_data.get("package")
-        # Only pass string values to resolve_package (guard against malformed JSON)
-        task_package = task_pkg_value if isinstance(task_pkg_value, str) else None
-        package = resolve_package(task_package=task_package, repo_root=repo_root)
-
-        # Monorepo fallback prohibition
-        if package is None:
-            packages = get_packages(repo_root)
-            available = ", ".join(sorted(packages.keys())) if packages else "(none)"
-            print(colored(
-                f"Error: monorepo project requires --package (or set default_package in config.yaml). Available: {available}",
-                Colors.RED,
-            ), file=sys.stderr)
-            return 1
-
-    print(colored("=== Initializing Agent Context Files ===", Colors.BLUE))
-    print(f"Target dir: {target_dir}")
-    print(f"Dev type: {dev_type}")
-    if package:
-        print(f"Package: {package}")
-    print()
-
-    # implement.jsonl
-    print(colored("Creating implement.jsonl...", Colors.CYAN))
-    implement_entries = get_implement_base()
-    if dev_type in ("backend", "test"):
-        implement_entries.extend(get_implement_backend(package))
-    elif dev_type == "frontend":
-        implement_entries.extend(get_implement_frontend(package))
-    elif dev_type == "fullstack":
-        implement_entries.extend(get_implement_backend(package))
-        implement_entries.extend(get_implement_frontend(package))
-
-    implement_file = target_dir / "implement.jsonl"
-    _write_jsonl(implement_file, implement_entries)
-    print(f"  {colored('✓', Colors.GREEN)} {len(implement_entries)} entries")
-
-    # check.jsonl
-    print(colored("Creating check.jsonl...", Colors.CYAN))
-    check_entries = get_check_context(repo_root)
-    check_file = target_dir / "check.jsonl"
-    _write_jsonl(check_file, check_entries)
-    print(f"  {colored('✓', Colors.GREEN)} {len(check_entries)} entries")
-
-    # Update task.json dev_type and package
-    task_json_path = target_dir / FILE_TASK_JSON
-    if task_json_path.is_file():
-        task_data = read_json(task_json_path)
-        if isinstance(task_data, dict):
-            task_data["dev_type"] = dev_type
-            task_data["package"] = package  # Always sync to match resolved value
-            write_json(task_json_path, task_data)
-
-    print()
-    print(colored("✓ All context files created", Colors.GREEN))
-    print()
-
-    # Show what was auto-injected
-    all_injected = [e["file"] for e in implement_entries]
-    print(colored("Auto-injected (defaults only):", Colors.YELLOW))
-    for f in all_injected:
-        print(f"  - {f}")
-    print()
-
-    # Scan spec directory for available spec files the AI should consider
-    spec_base = repo_root / DIR_WORKFLOW / DIR_SPEC
-    if package:
-        spec_base = spec_base / package
-    available_specs: list[str] = []
-    if spec_base.is_dir():
-        for md_file in sorted(spec_base.rglob("*.md")):
-            rel = str(md_file.relative_to(repo_root))
-            if rel not in all_injected:
-                available_specs.append(rel)
-
-    if available_specs:
-        print(colored("Available spec files (not yet injected):", Colors.BLUE))
-        for spec in available_specs:
-            print(f"  - {spec}")
-        print()
-
-    print(colored("Next steps:", Colors.BLUE))
-    print("  1. Review the spec files above and add relevant ones for your task:")
-    print(f"     python3 task.py add-context <dir> implement <spec-path> \"<reason>\"")
-    print("  2. Set as current: python3 task.py start <dir>")
-
-    return 0
-
-
 # =============================================================================
 # Command: add-context
 # =============================================================================
@@ -294,7 +113,11 @@ def cmd_validate(args: argparse.Namespace) -> int:
 
 
 def _validate_jsonl(jsonl_file: Path, repo_root: Path) -> int:
-    """Validate a single JSONL file."""
+    """Validate a single JSONL file.
+
+    Seed rows (no ``file`` field — typically ``{"_example": "..."}``) are
+    skipped silently; they are self-describing comments, not real entries.
+    """
     file_name = jsonl_file.name
     errors = 0
 
@@ -303,6 +126,7 @@ def _validate_jsonl(jsonl_file: Path, repo_root: Path) -> int:
         return 0
 
     line_num = 0
+    real_entries = 0
     for line in jsonl_file.read_text(encoding="utf-8").splitlines():
         line_num += 1
         if not line.strip():
@@ -319,10 +143,10 @@ def _validate_jsonl(jsonl_file: Path, repo_root: Path) -> int:
         entry_type = data.get("type", "file")
 
         if not file_path:
-            print(f"  {colored(f'{file_name}:{line_num}: Missing file field', Colors.RED)}")
-            errors += 1
+            # Seed / comment row — skip silently
             continue
 
+        real_entries += 1
         full_path = repo_root / file_path
         if entry_type == "directory":
             if not full_path.is_dir():
@@ -334,7 +158,7 @@ def _validate_jsonl(jsonl_file: Path, repo_root: Path) -> int:
                 errors += 1
 
     if errors == 0:
-        print(f"  {colored(f'{file_name}: ✓ ({line_num} entries)', Colors.GREEN)}")
+        print(f"  {colored(f'{file_name}: ✓ ({real_entries} entries)', Colors.GREEN)}")
     else:
         print(f"  {colored(f'{file_name}: ✗ ({errors} errors)', Colors.RED)}")
 
@@ -365,6 +189,7 @@ def cmd_list_context(args: argparse.Namespace) -> int:
         print(colored(f"[{jsonl_name}]", Colors.CYAN))
 
         count = 0
+        seed_only = True
         for line in jsonl_file.read_text(encoding="utf-8").splitlines():
             if not line.strip():
                 continue
@@ -374,8 +199,13 @@ def cmd_list_context(args: argparse.Namespace) -> int:
             except json.JSONDecodeError:
                 continue
 
+            file_path = data.get("file")
+            if not file_path:
+                # Seed / comment row — don't count as a real entry
+                continue
+            seed_only = False
+
             count += 1
-            file_path = data.get("file", "?")
             entry_type = data.get("type", "file")
             reason = data.get("reason", "-")
 
@@ -385,6 +215,9 @@ def cmd_list_context(args: argparse.Namespace) -> int:
                 print(f"  {colored(f'{count}.', Colors.GREEN)} {file_path}")
             print(f"     {colored('→', Colors.YELLOW)} {reason}")
 
+        if seed_only:
+            print(f"  {colored('(no curated entries yet — only seed row)', Colors.YELLOW)}")
+
         print()
 
     return 0

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

@@ -16,6 +16,7 @@ Provides:
 from __future__ import annotations
 
 import argparse
+import json
 import re
 import sys
 from datetime import datetime
@@ -35,9 +36,7 @@ from .paths import (
     DIR_TASKS,
     DIR_WORKFLOW,
     FILE_TASK_JSON,
-    clear_current_task,
     generate_task_date_prefix,
-    get_current_task,
     get_developer,
     get_repo_root,
     get_tasks_dir,
@@ -78,6 +77,61 @@ def ensure_tasks_dir(repo_root: Path) -> Path:
     return tasks_dir
 
 
+# =============================================================================
+# Sub-agent platform detection + JSONL seeding
+# =============================================================================
+
+# Config directories of platforms that consume implement.jsonl / check.jsonl.
+# Keep in sync with src/types/ai-tools.ts AI_TOOLS entries — these are the
+# platforms listed in workflow.md's "agent-capable" Skill Routing block
+# (Class-1 hook-inject + Class-2 pull-based preludes). Kilo / Antigravity /
+# Windsurf are NOT in this list: they do not consume JSONL.
+_SUBAGENT_CONFIG_DIRS: tuple[str, ...] = (
+    ".claude",
+    ".cursor",
+    ".codex",
+    ".kiro",
+    ".gemini",
+    ".opencode",
+    ".qoder",
+    ".codebuddy",
+    ".factory",   # Factory Droid
+    ".github/copilot",
+    ".pi",        # Pi Agent
+)
+
+_SEED_EXAMPLE = (
+    "Fill with {\"file\": \"<path>\", \"reason\": \"<why>\"}. "
+    "Put spec/research files only — no code paths. "
+    "Run `python3 .trellis/scripts/get_context.py --mode packages` to list available specs. "
+    "Delete this line once real entries are added."
+)
+
+
+def _has_subagent_platform(repo_root: Path) -> bool:
+    """Return True if any sub-agent-capable platform is configured.
+
+    Detected by probing well-known config directories at the repo root. Used
+    only to decide whether ``task.py create`` should seed empty
+    ``implement.jsonl`` / ``check.jsonl`` files.
+    """
+    for config_dir in _SUBAGENT_CONFIG_DIRS:
+        if (repo_root / config_dir).is_dir():
+            return True
+    return False
+
+
+def _write_seed_jsonl(path: Path) -> None:
+    """Write a one-line seed JSONL file with a self-describing ``_example``.
+
+    The seed row has no ``file`` field, so downstream consumers (hooks +
+    preludes) that iterate entries via ``item.get("file")`` naturally skip
+    it. The row exists purely as an in-file prompt for the AI curator.
+    """
+    seed = {"_example": _SEED_EXAMPLE}
+    path.write_text(json.dumps(seed, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
 # =============================================================================
 # Command: create
 # =============================================================================
@@ -173,6 +227,18 @@ def cmd_create(args: argparse.Namespace) -> int:
 
     write_json(task_json_path, task_data)
 
+    # Seed implement.jsonl / check.jsonl for sub-agent-capable platforms.
+    # Agent curates real entries in Phase 1.3 (see .trellis/workflow.md).
+    # Agent-less platforms (Kilo / Antigravity / Windsurf) skip this — they
+    # load specs via the trellis-before-dev skill instead of JSONL.
+    seeded_jsonl = False
+    if _has_subagent_platform(repo_root):
+        for jsonl_name in ("implement.jsonl", "check.jsonl"):
+            jsonl_path = task_dir / jsonl_name
+            if not jsonl_path.exists():
+                _write_seed_jsonl(jsonl_path)
+        seeded_jsonl = True
+
     # Handle --parent: establish bidirectional link
     if args.parent:
         parent_dir = resolve_task_dir(args.parent, repo_root)
@@ -195,12 +261,35 @@ def cmd_create(args: argparse.Namespace) -> int:
 
                 print(colored(f"Linked as child of: {parent_dir.name}", Colors.GREEN), file=sys.stderr)
 
+    # Auto-activate the new task so the per-turn breadcrumb fires planning
+    # state. Best-effort: gracefully degrade if no session identity (CLI run
+    # outside an AI session) — the task is still created, the user can run
+    # task.py start later. Pointer is session-scoped so this never affects
+    # other AI sessions.
+    try:
+        from .active_task import resolve_context_key, set_active_task
+        if resolve_context_key():
+            try:
+                rel_dir = task_dir.relative_to(repo_root).as_posix()
+            except ValueError:
+                rel_dir = str(task_dir)
+            set_active_task(rel_dir, repo_root)
+    except Exception:
+        pass
+
     print(colored(f"Created task: {dir_name}", Colors.GREEN), file=sys.stderr)
     print("", file=sys.stderr)
     print(colored("Next steps:", Colors.BLUE), file=sys.stderr)
     print("  1. Create prd.md with requirements", file=sys.stderr)
-    print("  2. Run: python3 task.py init-context <dir> <dev_type>", file=sys.stderr)
-    print("  3. Run: python3 task.py start <dir>", file=sys.stderr)
+    if seeded_jsonl:
+        print(
+            "  2. Curate implement.jsonl / check.jsonl (spec + research files only — "
+            "see .trellis/workflow.md Phase 1.3)",
+            file=sys.stderr,
+        )
+        print("  3. Run: python3 task.py start <dir>", file=sys.stderr)
+    else:
+        print("  2. Run: python3 task.py start <dir>", file=sys.stderr)
     print("", file=sys.stderr)
 
     # Output relative path for script chaining
@@ -225,8 +314,8 @@ def cmd_archive(args: argparse.Namespace) -> int:
 
     tasks_dir = get_tasks_dir(repo_root)
 
-    # Find task directory
-    task_dir = find_task_by_name(task_name, tasks_dir)
+    # Resolve task directory (supports task name, relative path, or absolute path)
+    task_dir = resolve_task_dir(task_name, repo_root)
 
     if not task_dir or not task_dir.is_dir():
         print(colored(f"Error: Task not found: {task_name}", Colors.RED), file=sys.stderr)
@@ -249,24 +338,12 @@ def cmd_archive(args: argparse.Namespace) -> int:
             data["completedAt"] = today
             write_json(task_json_path, data)
 
-            # Handle subtask relationships on archive
-            task_parent = data.get("parent")
+            # Handle subtask relationships on archive.
+            # Keep this task in its parent's children list so progress
+            # counters (children_progress) stay consistent — children
+            # missing from the active set are treated as completed.
             task_children = data.get("children", [])
 
-            # If this is a child, remove from parent's children list
-            if task_parent:
-                parent_dir = find_task_by_name(task_parent, tasks_dir)
-                if parent_dir:
-                    parent_json = parent_dir / FILE_TASK_JSON
-                    if parent_json.is_file():
-                        parent_data = read_json(parent_json)
-                        if parent_data:
-                            parent_children = parent_data.get("children", [])
-                            if dir_name in parent_children:
-                                parent_children.remove(dir_name)
-                                parent_data["children"] = parent_children
-                                write_json(parent_json, parent_data)
-
             # If this is a parent, clear parent field in all children
             if task_children:
                 for child_name in task_children:
@@ -279,10 +356,9 @@ def cmd_archive(args: argparse.Namespace) -> int:
                                 child_data["parent"] = None
                                 write_json(child_json, child_data)
 
-    # Clear if current task
-    current = get_current_task(repo_root)
-    if current and dir_name in current:
-        clear_current_task(repo_root)
+    # Clear any session that still points at this task before the path moves.
+    from .active_task import clear_task_from_sessions
+    clear_task_from_sessions(str(task_dir), repo_root)
 
     # Archive
     result = archive_task_complete(task_dir, repo_root)

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

@@ -102,8 +102,11 @@ def children_progress(
     """
     if not children:
         return ""
+    # A child missing from active statuses has been archived (cmd_archive
+    # sets status=completed before moving the dir). Count it as done so
+    # parent progress doesn't regress when children are archived.
     done = sum(
         1 for c in children
-        if all_statuses.get(c) in ("completed", "done")
+        if c not in all_statuses or all_statuses.get(c) in ("completed", "done")
     )
     return f" [{done}/{len(children)} done]"

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

@@ -41,8 +41,6 @@ class TaskData(TypedDict, total=False):
     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]

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

@@ -65,7 +65,10 @@ def get_phase_index() -> str:
     Matches what the SessionStart hook injects into the `<workflow>` block:
     starts at `## Phase Index`, continues through `## Phase 1: Plan`,
     `## Phase 2: Execute`, `## Phase 3: Finish`, stops at
-    `## Workflow State Breadcrumbs` (consumed by UserPromptSubmit hook).
+    `## Customizing Trellis (for forks)` (the docs-for-forks footer).
+    `[workflow-state:STATUS]` tag blocks (now embedded in Phase Index since
+    v0.5.0-rc.0) are consumed by the UserPromptSubmit hook so they're
+    stripped from this output.
     """
     text = _read_workflow()
     lines = text.splitlines()
@@ -77,7 +80,7 @@ def get_phase_index() -> str:
         if start is None and stripped == _PHASE_INDEX_HEADING:
             start = i
             continue
-        if start is not None and stripped == "## Workflow State Breadcrumbs":
+        if start is not None and stripped == "## Customizing Trellis (for forks)":
             end = i
             break
 
@@ -85,7 +88,16 @@ def get_phase_index() -> str:
         return ""
     if end is None:
         end = len(lines)
-    return "\n".join(lines[start:end]).rstrip() + "\n"
+
+    section = "\n".join(lines[start:end]).rstrip()
+    # Strip [workflow-state:STATUS]...[/workflow-state:STATUS] blocks since
+    # they're injected separately by inject-workflow-state.py per-turn.
+    import re as _re
+    tag_re = _re.compile(
+        r"\[workflow-state:([A-Za-z0-9_-]+)\]\s*\n.*?\n\s*\[/workflow-state:\1\]\n?",
+        _re.DOTALL,
+    )
+    return tag_re.sub("", section).rstrip() + "\n"
 
 
 def get_step(step_id: str) -> str: