@pennixrv/trellis 0.6.45 → 0.7.0-beta.5

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

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""
+Per-task workflow selection.
+
+Resolves which workflow markdown file consumers should read. A task may pin
+a workflow variant by storing `"workflow": "<id>"` in its task.json; the
+variant body lives at `.trellis/workflows/<id>.md` (user-managed library).
+
+Resolution precedence (single source of truth for all consumers), highest
+to lowest — each layer resolves an id to `.trellis/workflows/<id>.md` and
+falls through when unset, invalid, or pointing at a missing file:
+    1. Per-task pin  - active task's task.json `workflow` (session-bound,
+       explicit; a bad id or missing file warns once on stderr, then falls
+       through rather than aborting).
+    2. Personal      - `.developer` `workflow=<id>` (gitignored, per-developer;
+       outranks the team default). Silent on miss.
+    3. Team default  - config.yaml `default_workflow` (git-tracked, shared).
+       Silent on miss.
+    4. Global        - `.trellis/workflow.md`.
+With neither a per-task pin nor the personal/team keys set, this is identical
+to reading the global `.trellis/workflow.md`. Never raises.
+
+Provides:
+    workflow_md_for_task - Full precedence for an already-resolved task dir
+    resolve_workflow_md  - Session-aware wrapper via the active task resolver
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+from .paths import DIR_WORKFLOW, FILE_TASK_JSON
+
+# Workflow variant library directory under .trellis/ (plural on purpose:
+# `.trellis/workflow/` is reserved by the YAML-manifest migration).
+DIR_WORKFLOWS = "workflows"
+
+# Workflow ids must be plain slugs; anything else (path separators, dots)
+# is rejected so a task.json value can never escape .trellis/workflows/.
+WORKFLOW_ID_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def _global_workflow_md(repo_root: Path) -> Path:
+    return repo_root / DIR_WORKFLOW / "workflow.md"
+
+
+def _library_variant(repo_root: Path, workflow_id: str | None) -> Path | None:
+    """Map a workflow id to its library file if valid and present, else None.
+
+    Shared by every layer (per-task pin, personal, team). An id with path
+    separators/dots/blanks, or one whose `.trellis/workflows/<id>.md` file does
+    not exist, returns None so the caller falls through. Never raises.
+    """
+    if not isinstance(workflow_id, str) or not workflow_id:
+        return None
+    if not WORKFLOW_ID_RE.match(workflow_id):
+        return None
+    variant = repo_root / DIR_WORKFLOW / DIR_WORKFLOWS / f"{workflow_id}.md"
+    return variant if variant.is_file() else None
+
+
+def _developer_workflow_id(repo_root: Path) -> str | None:
+    """Personal override id from the gitignored .developer file (fail-open)."""
+    try:
+        from .paths import get_developer_workflow
+
+        return get_developer_workflow(repo_root)
+    except Exception:
+        return None
+
+
+def _config_default_id(repo_root: Path) -> str | None:
+    """Team-shared default id from config.yaml `default_workflow` (fail-open)."""
+    try:
+        from .config import get_default_workflow
+
+        return get_default_workflow(repo_root)
+    except Exception:
+        return None
+
+
+def _default_workflow_md(repo_root: Path) -> Path:
+    """Resolve the non-per-task default: personal -> team -> global.
+
+    Personal (`.developer` `workflow=`) outranks the team-shared
+    (config.yaml `default_workflow`) layer; both fall through to the global
+    `.trellis/workflow.md` when unset, invalid, or naming a missing file. These
+    layers are silent on miss (they are defaults, not an explicit per-task
+    choice — a per-turn warning would be noise).
+    """
+    for get_id in (_developer_workflow_id, _config_default_id):
+        variant = _library_variant(repo_root, get_id(repo_root))
+        if variant is not None:
+            return variant
+    return _global_workflow_md(repo_root)
+
+
+def _task_pin_variant(repo_root: Path, task_dir: Path | None) -> Path | None:
+    """Return the per-task pinned variant path, or None to fall through.
+
+    Emits a stderr warning on an invalid id or a missing variant file (an
+    explicit per-task choice that cannot be honored), then returns None so
+    resolution continues with the personal/team defaults. Never raises.
+    """
+    if task_dir is None:
+        return None
+
+    try:
+        raw = json.loads((task_dir / FILE_TASK_JSON).read_text(encoding="utf-8"))
+        if not isinstance(raw, dict):
+            return None
+
+        workflow_id = raw.get("workflow")
+        if not isinstance(workflow_id, str) or not workflow_id:
+            return None
+
+        if not WORKFLOW_ID_RE.match(workflow_id):
+            print(
+                f"Warning: task '{task_dir.name}' has invalid workflow id "
+                f"{workflow_id!r}; using default workflow resolution",
+                file=sys.stderr,
+            )
+            return None
+
+        variant = _library_variant(repo_root, workflow_id)
+        if variant is not None:
+            return variant
+
+        print(
+            f"Warning: task '{task_dir.name}' selects workflow '{workflow_id}' but "
+            f"{DIR_WORKFLOW}/{DIR_WORKFLOWS}/{workflow_id}.md is missing; "
+            f"using default workflow resolution",
+            file=sys.stderr,
+        )
+        return None
+    except Exception:
+        return None
+
+
+def workflow_md_for_task(repo_root: Path, task_dir: Path | None) -> Path:
+    """Return the workflow.md path for an already-resolved task dir (or None).
+
+    Applies the full precedence documented in the module docstring:
+    per-task pin -> personal (.developer) -> team (config.yaml) -> global.
+    Never raises; any failure falls through toward the global workflow path.
+    """
+    pin = _task_pin_variant(repo_root, task_dir)
+    if pin is not None:
+        return pin
+    return _default_workflow_md(repo_root)
+
+
+def resolve_workflow_md(
+    repo_root: Path,
+    input_data: dict | None = None,
+    platform: str | None = None,
+) -> Path:
+    """Resolve the session-aware active task, then apply the resolution rule.
+
+    ``input_data`` is the raw hook payload (session/conversation identity);
+    CLI callers may omit it — the active-task resolver then falls back to
+    environment context. Never raises; any failure resolves to the global
+    `.trellis/workflow.md`.
+    """
+    try:
+        from .active_task import resolve_active_task, resolve_task_ref
+
+        active = resolve_active_task(repo_root, input_data, platform)
+        task_dir: Path | None = None
+        if active.task_path:
+            task_dir = resolve_task_ref(active.task_path, repo_root)
+        return workflow_md_for_task(repo_root, task_dir)
+    except Exception:
+        return _global_workflow_md(repo_root)

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

@@ -12,6 +12,7 @@ Usage:
     python3 task.py current [--source] [--json] # Show active task
     python3 task.py ownership <operation> ...   # Manage formal handoff task ownership
     python3 task.py finish                      # Clear active task
+    python3 task.py workflow <id>|--clear       # Set/clear per-task workflow selection
     python3 task.py set-branch <dir> <branch>   # Set git branch
     python3 task.py set-base-branch <dir> <branch>  # Set PR target branch
     python3 task.py set-scope <dir> <scope>     # Set scope for PR title
@@ -51,11 +52,13 @@ from common.active_task import (
 from common.git import current_branch_name
 from common.io import (
     describe_json_read_failure,
+    read_json,
     read_json_checked,
     write_json,
 )
 from common.task_utils import resolve_task_dir, run_task_hooks
 from common.tasks import iter_active_tasks, children_progress
+from common.workflow_selection import WORKFLOW_ID_RE, workflow_md_for_task
 
 # Import command handlers from split modules (also re-exports for plan.py compatibility)
 from common.task_store import (
@@ -483,6 +486,72 @@ def cmd_ownership(args: argparse.Namespace) -> int:
         return 2
 
 
+# =============================================================================
+# Command: workflow
+# =============================================================================
+
+def cmd_workflow(args: argparse.Namespace) -> int:
+    """Set or clear the workflow selection on the current session's active task."""
+    repo_root = get_repo_root()
+
+    if args.clear and args.id:
+        print(colored("Error: pass either <id> or --clear, not both", Colors.RED))
+        return 1
+    if not args.clear and not args.id:
+        print(colored("Error: workflow id required (or --clear)", Colors.RED))
+        print("Usage: python3 task.py workflow <id> | --clear")
+        return 1
+
+    active = resolve_active_task(repo_root)
+    if not active.task_path:
+        print(colored("Error: No current task set", Colors.RED))
+        print("Hint: run task.py start <dir> first")
+        return 1
+
+    task_dir = repo_root / active.task_path
+    task_json_path = task_dir / FILE_TASK_JSON
+    if not task_json_path.is_file():
+        print(colored(f"Error: task.json not found at {task_dir}", Colors.RED))
+        return 1
+
+    data = read_json(task_json_path)
+    if not data:
+        print(colored(f"Error: failed to read {task_json_path}", Colors.RED))
+        return 1
+
+    if args.clear:
+        if data.pop("workflow", None) is None:
+            print(colored("No workflow selection set on this task", Colors.YELLOW))
+        else:
+            if not write_json(task_json_path, data):
+                print(colored("Error: failed to update task.json", Colors.RED))
+                return 1
+            print(colored("✓ Workflow selection cleared", Colors.GREEN))
+    else:
+        workflow_id = args.id
+        if not WORKFLOW_ID_RE.match(workflow_id):
+            print(colored(
+                f"Error: invalid workflow id '{workflow_id}' (allowed: letters, digits, '-', '_')",
+                Colors.RED,
+            ))
+            return 1
+        data["workflow"] = workflow_id
+        if not write_json(task_json_path, data):
+            print(colored("Error: failed to update task.json", Colors.RED))
+            return 1
+        print(colored(f"✓ Workflow set to: {workflow_id}", Colors.GREEN))
+
+    # workflow_md_for_task warns on stderr itself when the selected variant
+    # file is missing (it can be saved later via `trellis workflow --save`).
+    effective = workflow_md_for_task(repo_root, task_dir)
+    try:
+        effective_display = effective.relative_to(repo_root).as_posix()
+    except ValueError:
+        effective_display = str(effective)
+    print(f"Effective workflow: {effective_display}")
+    return 0
+
+
 # =============================================================================
 # Command: list
 # =============================================================================
@@ -665,12 +734,15 @@ Usage:
   python3 task.py create <title> --description <desc> --package <pkg>   Create task for a specific package
   python3 task.py create <title> --description <desc> --parent <dir>    Create task as child of parent
   python3 task.py create <title> --description <desc> --no-start        Create without making it active in this session
+  python3 task.py create <title> --description <desc> --workflow <id>   Create task pinned to a workflow variant
   python3 task.py add-context <dir> <jsonl> <path> [reason]  Add entry to jsonl
   python3 task.py validate <dir>                     Validate jsonl files
   python3 task.py list-context <dir>                 List jsonl entries
   python3 task.py start <dir>                        Set active task; records the checked-out branch when unset
   python3 task.py current [--source]                 Show active task
   python3 task.py finish                             Clear active task
+  python3 task.py workflow <id>                      Select workflow variant for active task
+  python3 task.py workflow --clear                   Clear selection (use default resolution)
   python3 task.py set-branch <dir> <branch>          Set git branch
   python3 task.py set-base-branch <dir> <branch>     Set PR target branch
   python3 task.py set-scope <dir> <scope>            Set scope for PR title
@@ -794,6 +866,10 @@ def main() -> int:
         action="store_true",
         help="Create the task without making it active in this session",
     )
+    p_create.add_argument(
+        "--workflow",
+        help="Workflow variant id for this task (.trellis/workflows/<id>.md)",
+    )
     p_create.add_argument(
         "--force",
         action="store_true",
@@ -889,6 +965,12 @@ def main() -> int:
     # finish
     subparsers.add_parser("finish", help="Clear active task")
 
+    # workflow
+    p_workflow = subparsers.add_parser("workflow", help="Set/clear per-task workflow selection")
+    p_workflow.add_argument("id", nargs="?", help="Workflow id (.trellis/workflows/<id>.md)")
+    p_workflow.add_argument("--clear", action="store_true",
+                            help="Remove the workflow selection (use default resolution)")
+
     # set-branch
     p_branch = subparsers.add_parser("set-branch", help="Set git branch")
     p_branch.add_argument("dir", help="Task directory")
@@ -969,6 +1051,7 @@ def main() -> int:
         "continuity": cmd_continuity,
         "ownership": cmd_ownership,
         "finish": cmd_finish,
+        "workflow": cmd_workflow,
         "set-branch": cmd_set_branch,
         "set-base-branch": cmd_set_base_branch,
         "set-scope": cmd_set_scope,

package/dist/templates/trellis/workflow.md

@@ -151,14 +151,14 @@ python3 ./.trellis/scripts/get_context.py --mode phase --step <X.Y>  # detailed
 ## Phase Index
 
 ```
-Phase 1: Plan    → classify, get task-creation consent, then write planning artifacts
+Phase 1: Plan    → classify, then create planning artifacts for work that needs a task
 Phase 2: Execute → implement only after task status is in_progress
 Phase 3: Finish  → verify, update spec, commit, and wrap up
 ```
 
 ### Request Triage
 
-- Simple conversation or small task: ask only whether this turn should create a Trellis task. If the user says no, skip Trellis for this session.
+- Direct small work: for a clearly bounded, single-surface operation with an immediate verification path, proceed without creating a Trellis task. Apply normal safety rules. If discovery expands the scope or reveals a design, ownership, release, or durable-record need, stop and create a task before continuing.
 - Complex task: ask whether you may create a Trellis task and enter planning. If the user says no, do not do broad inline implementation; explain, clarify scope, or suggest a smaller split.
 - User approval to create a task is not approval to start implementation. Planning still happens first.
 
@@ -187,8 +187,8 @@ Create new children with `task.py create "<title>" --slug <name> --parent <paren
 <!-- Per-turn breadcrumb: shown when there is no active task (before Phase 1) -->
 
 [workflow-state:no_task]
-No active task. First classify the current turn and ask for task-creation consent before creating any Trellis task.
-Simple conversation / small task: ask only whether this turn should create a Trellis task. If the user says no, skip Trellis for this session.
+No active task. First classify the current turn. Direct small work with a clear single owner and immediate verification may proceed without a Trellis task under normal safety rules.
+If scope expands or requires design, ownership, release, credentials, or a durable record, create a Trellis task before continuing.
 Complex task: ask the user if you can create a Trellis task and enter the planning phase. If the user says no, explain, clarify scope, or suggest a smaller split.
 [/workflow-state:no_task]
 
@@ -259,10 +259,11 @@ Inline mode: skip jsonl curation; Phase 2 reads artifacts/specs via `trellis-bef
      therefore must cover every required step from implementation through
      commit, including Phase 3.3 spec update and Phase 3.4 commit. -->
 
-Sub-agent dispatch protocol applies to all platforms and all sub-agents, including native Codex `SubagentStart` context injection with child-side pull fallback, class-2 Gemini/Qoder/Copilot/Reasonix/Trae/Grok/Kimi Code, hook-backed ZCode/Snow, and `trellis-research`: every dispatch prompt starts with `Active task: <task path from task.py current>` before role-specific instructions. On Grok Build, use `spawn_subagent` with `subagent_type` set to the Trellis agent name (e.g. `trellis-implement`). On Kimi Code, dispatch the built-in `coder` / `explore` sub-agent with the matching `.kimi-code/skills/trellis-<role>/SKILL.md` instructions.
+Sub-agent dispatch protocol applies to all platforms and all sub-agents, including native Codex `SubagentStart` context injection with child-side pull fallback, class-2 Gemini/Qoder/Copilot/Reasonix/Trae/Grok/Kimi Code/DeepSeek Harness, hook-backed ZCode/Snow, and `trellis-research`: every dispatch prompt starts with `Active task: <task path from task.py current>` before role-specific instructions. On Grok Build, use `spawn_subagent` with `subagent_type` set to the Trellis agent name (e.g. `trellis-implement`). On Kimi Code, dispatch the built-in `coder` / `explore` sub-agent with the matching `.kimi-code/skills/trellis-<role>/SKILL.md` instructions. On DeepSeek Harness, tell the child to load the matching `.dsh/skills/trellis-agent-<role>/SKILL.md` exactly once, then choose the synchronization path by capability. If the optional companion plugin exposes `trellis_wait`, dispatch `subagent` in its default continuable background mode, continue independent work, and call `trellis_wait` once per dependent child id when a dependent gate is next; each call returns only after DSH has queued that child's native settlement notice. Without `trellis_wait`, dispatch each child with `run_in_background: false` from the outset so no dependent gate can overtake it. Never simulate waiting with shell sleep, polling loops, `job_output`, repeated `list_agents`, or another long-running command, and never leave a background child without an event-driven wait path.
 
 [workflow-state:in_progress]
-Tools: `trellis-implement` / `trellis-research` are sub-agent types only (Task/Agent tool, NOT Skill; there is no skill by these names). `trellis-update-spec` is a skill. `trellis-check` exists as both; prefer the Agent form when verifying after code changes.
+Tools: `trellis-implement` / `trellis-research` name sub-agent roles dispatched through your platform's sub-agent mechanism, not skills the main session loads itself (on Claude Code: use the Task/Agent tool, never the Skill tool). `trellis-update-spec` is a skill. `trellis-check` exists as both; prefer the Agent/role form when verifying after code changes.
+On DeepSeek Harness, role instructions ship as collision-free `trellis-agent-implement` / `trellis-agent-check` / `trellis-agent-research` skills under `.dsh/skills/`. The main session must not load them itself: tell the child to load the matching role skill exactly once. If `trellis_wait` is available, use the default background mode, do independent work, then call `trellis_wait` once per dependent child id and consume each native settlement notice before entering the dependent gate. If it is unavailable, dispatch every child with `run_in_background: false` from the outset. Do not poll, sleep, or start a background child without an event-driven wait path.
 Flow: `trellis-implement` -> `trellis-check` -> `trellis-update-spec` -> commit (Phase 3.4) -> `/trellis:finish-work`.
 Use this block only when `codex.dispatch_mode: auto` is explicitly selected. Sub-agent self-exemption: if already running as `trellis-implement`, do NOT spawn another `trellis-implement` or `trellis-check`; if already running as `trellis-check`, do NOT spawn another `trellis-check` or `trellis-implement`. Dispatch is main session only.
 Dispatch prompt starts with `Active task: <task path from task.py current>`. Read context: jsonl entries -> `prd.md` -> `design.md if present` -> `implement.md if present`.
@@ -311,23 +312,23 @@ Code committed. Run `/trellis:finish-work`; if dirty, return to Phase 3.4 first.
 
 When a user request matches one of these intents inside an active task, route first, then load the detailed phase step if needed.
 
-[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
+[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
 - Planning or unclear requirements -> `trellis-brainstorm`.
 - Explicit eligible `analysis_only` -> complete evidence in planning, then commit artifacts and archive directly.
 - `in_progress` implementation/check -> dispatch `trellis-implement` / `trellis-check`.
 - Repeated debugging -> `trellis-break-loop`; spec updates -> `trellis-update-spec`.
 
-[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
+[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
-[codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
+[codex-inline, Kilo, Antigravity, Devin]
 
 - Planning or unclear requirements -> `trellis-brainstorm`.
 - Explicit eligible `analysis_only` -> complete evidence in planning, then commit artifacts and archive directly.
 - Before editing -> `trellis-before-dev`; after editing -> `trellis-check`.
 - Repeated debugging -> `trellis-break-loop`; spec updates -> `trellis-update-spec`.
 
-[/codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
+[/codex-inline, Kilo, Antigravity, Devin]
 
 ### Guardrails
 
@@ -349,7 +350,7 @@ python3 ./.trellis/scripts/get_context.py --mode phase --step <step>
 
 ## Phase 1: Plan
 
-Goal: classify the request, get task-creation consent when a task is needed, and produce the planning artifacts required before implementation.
+Goal: classify the request, perform only eligible direct small work without a task, and create planning artifacts when a task is needed.
 
 #### 1.0 Create task `[required · once]`
 
@@ -399,21 +400,22 @@ Return to this step whenever requirements change and revise the relevant artifac
 
 Research can happen at any time during requirement exploration. It isn't limited to local code — you can use any available tool (MCP servers, skills, web search, etc.) to look up external information, including third-party library docs, industry practices, API references, etc.
 
-[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
+[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
 Spawn the research sub-agent:
 
 - **Agent type**: `trellis-research`
 - **Task description**: Research <specific question>
 - **Key requirement**: Research output MUST be persisted to `{TASK_DIR}/research/`
+- **DeepSeek Harness**: tell the child to load `trellis-agent-research` exactly once. If `trellis_wait` is available, use the default continuable background mode, dispatch independent questions concurrently when useful, continue unrelated work, then call `trellis_wait` once per child id and consume each settlement notice before advancing. Without `trellis_wait`, dispatch each required child with `run_in_background: false`; do not poll or sleep.
 
-[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
+[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
-[codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
+[codex-inline, Kilo, Antigravity, Devin]
 
 Do the research in the main session directly and write findings into `{TASK_DIR}/research/`. `codex-inline` is the explicit mode that keeps work in the main session.
 
-[/codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
+[/codex-inline, Kilo, Antigravity, Devin]
 
 **Research artifact conventions**:
 - One file per research topic (e.g. `research/auth-library-comparison.md`)
@@ -428,7 +430,7 @@ Brainstorm and research can interleave freely — pause to research a technical
 
 Eligible analysis-only tasks skip this step because they never enter Phase 2 or dispatch implementation/check agents.
 
-[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
+[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
 Curate `implement.jsonl` and `check.jsonl` so the Phase 2 sub-agents get the right spec/research context. These files were seeded on `task create` with a single self-describing `_example` line; your job here is to fill in real entries.
 
@@ -473,13 +475,13 @@ Ready gate: both `implement.jsonl` and `check.jsonl` must contain at least one r
 
 Skip this step only when both files already have real curated entries.
 
-[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
+[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
-[codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
+[codex-inline, Kilo, Antigravity, Devin]
 
 Skip this step. Context is loaded directly by the `trellis-before-dev` skill in Phase 2.
 
-[/codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
+[/codex-inline, Kilo, Antigravity, Devin]
 
 #### 1.4 Activate task `[required · once]`
 
@@ -509,11 +511,11 @@ If `task.py start` errors with a session-identity message (no context key from h
 | `design.md` exists (complex tasks) | ✅ |
 | `implement.md` exists (complex tasks) | ✅ |
 
-[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
+[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
 | Change-bearing task: `implement.jsonl` and `check.jsonl` each contain at least one real curated entry (seed row does not count) | ✅ |
 
-[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
+[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
 ---
 
@@ -538,19 +540,20 @@ The platform hook/plugin auto-handles:
 
 [/Claude Code, Cursor, OpenCode, codex-sub-agent, CodeBuddy, Droid, Pi, ZCode, Snow, Oh My Pi]
 
-[Gemini, Qoder, Copilot, Reasonix, Trae, Grok, Kimi Code]
+[Gemini, Qoder, Copilot, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
 Spawn the implement sub-agent:
 
 - **Agent type**: `trellis-implement`
 - **Task description**: Implement the reviewed task artifacts, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
 - **Dispatch prompt guard**: The prompt MUST start with `Active task: <task path>`, then explicitly say the spawned agent is already `trellis-implement` and must implement directly without spawning another `trellis-implement` / `trellis-check`.
+- **DeepSeek Harness**: tell the child to load `trellis-agent-implement` exactly once. If `trellis_wait` is available, use the default background mode, continue independent work, then wait once for that child id and consume its successful native settlement notice before Phase 2.2. Without `trellis_wait`, dispatch that child with `run_in_background: false`. Do not poll or sleep.
 
 The pull-based sub-agent definition auto-handles the context load requirement:
 - Resolves the active task with `task.py current --source`, then reads `prd.md`, `design.md` if present, and `implement.md` if present
 - Reads `implement.jsonl` and requires the agent to load each referenced spec/research file before coding
 
-[/Gemini, Qoder, Copilot, Reasonix, Trae, Grok, Kimi Code]
+[/Gemini, Qoder, Copilot, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
 [Kiro]
 
@@ -566,7 +569,7 @@ The platform prelude auto-handles the context load requirement:
 
 [/Kiro]
 
-[codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
+[codex-inline, Kilo, Antigravity, Devin]
 
 1. Load the `trellis-before-dev` skill to read project guidelines
 2. Read `{TASK_DIR}/prd.md`, then `design.md` if present, then `implement.md` if present
@@ -574,27 +577,29 @@ The platform prelude auto-handles the context load requirement:
 4. Implement the code per reviewed artifacts
 5. Run project lint and type-check
 
-[/codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
+[/codex-inline, Kilo, Antigravity, Devin]
 
 #### 2.2 Quality check `[required · repeatable]`
 
-[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
+[Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
 Spawn the check sub-agent:
 
 - **Agent type**: `trellis-check`
 - **Task description**: Review all code changes against specs and task artifacts; fix any findings directly; ensure lint and type-check pass
 - **Dispatch prompt guard**: The prompt MUST start with `Active task: <task path>`, then tell the spawned agent it is already the `trellis-check` sub-agent and must review/fix directly, not spawn another `trellis-check` / `trellis-implement`.
+- **DeepSeek Harness**: tell the child to load `trellis-agent-check` exactly once. If `trellis_wait` is available, use the default background mode, continue independent work, then wait once for that child id and consume its successful native settlement notice before Phase 3. Without `trellis_wait`, dispatch that child with `run_in_background: false`. Do not poll or sleep.
 
 The check agent's job:
 - Review code changes against specs
 - Review code changes against `prd.md`, `design.md` if present, and `implement.md` if present
 - Auto-fix issues it finds
 - Run lint and typecheck to verify
+- A required check that cannot run, is skipped, or exits non-zero is blocked/failed, never passed. Do not weaken or rewrite acceptance criteria to advance the workflow.
 
-[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code]
+[/Claude Code, Cursor, OpenCode, codex-sub-agent, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Trae, Grok, Kimi Code, DeepSeek Harness]
 
-[codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
+[codex-inline, Kilo, Antigravity, Devin]
 
 Load the `trellis-check` skill and verify the code per its guidance:
 - Spec compliance
@@ -603,7 +608,7 @@ Load the `trellis-check` skill and verify the code per its guidance:
 
 If issues are found → fix → re-check, until green.
 
-[/codex-inline, Kilo, Antigravity, Devin, DeepSeek Harness]
+[/codex-inline, Kilo, Antigravity, Devin]
 
 **Final pass (before Phase 3.4 commit)**: the last 2.2 of a task must run full-scope, not just on the latest implement chunk. List all affected packages with `python3 ./.trellis/scripts/get_context.py --mode packages`, then load each package's spec index Quality Check section. This catches cross-layer / multi-package issues a mid-iteration local 2.2 cannot.
 
@@ -704,7 +709,7 @@ This section is for developers who want to modify the Trellis workflow itself. A
 ### Changing what a step means
 
 Edit the corresponding step's walkthrough body in the Phase 1 / 2 / 3 sections above. Critical invariants:
-- No active task must triage first and ask for task-creation consent before creating a Trellis task.
+- No active task must triage first; direct small work may proceed only when bounded, single-surface, and immediately verifiable, otherwise create a Trellis task first.
 - Planning must distinguish lightweight PRD-only tasks from complex tasks that require `prd.md`, `design.md`, and `implement.md` before start.
 - Every required execution path must keep the Phase 3.4 commit reminder reachable before `/trellis:finish-work`.
 

package/dist/types/ai-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-tools.d.ts","sourceRoot":"","sources":["../../src/types/ai-tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ai-tools.d.ts","sourceRoot":"","sources":["../../src/types/ai-tools.ts"],"names":[],"mappings":"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"}

package/dist/types/ai-tools.js

@@ -241,15 +241,30 @@ export const AI_TOOLS = {
             cliFlag: "droid",
         },
     },
+    /**
+     * DeepSeek Harness (dsh) — class-2 pull-based platform.
+     *
+     * DSH discovers skills from `<projectRoot>/.agents/skills/` (shared root,
+     * rank 200) and `<projectRoot>/.dsh/skills/` (DSH-private root, rank 100),
+     * plus user roots under `$DSH_HOME/skills` / `$DSH_AGENTS_HOME/skills`.
+     * SKILL.md frontmatter uses `name` (kebab-case) + `description`, matching
+     * Trellis's skill rendering. The model loads skills via the `skill` tool;
+     * users can load entry points by their `trellis-<name>` skill names. DSH
+     * surfaces that expose the slash pipeline may also accept `/trellis-<name>`.
+     *
+     * DSH injects project `AGENTS.md` at session start (workspace instructions)
+     * and supports isolated sub-agents through the `subagent` tool, so Trellis
+     * ships as class-2: workflow/bundled skills go to the shared `.agents/skills/`
+     * root via the neutral resolver (byte-identical to Codex/Gemini/Pi/Kimi
+     * writes), while DSH-private entry points (trellis-start / trellis-continue /
+     * trellis-finish-work) and collision-free role skills
+     * (trellis-agent-implement / trellis-agent-check / trellis-agent-research)
+     * live under `.dsh/skills/` with the pull-based prelude on implement/check.
+     *
+     * DSH has no project-level hooks/settings file Trellis may write, so
+     * hasHooks/hasPythonHooks stay false and no hook assets are emitted.
+     */
     dsh: {
-        // DeepSeek Harness (dsh) is a skills-first pull-based host: it reads
-        // `.agents/skills/` (agentskills.io, rank-200 project root) and its own
-        // `.dsh/skills/` (rank-100 project root) natively and the agent loads
-        // skills by name through its skill-loader tool. No session-start hook
-        // ships in the default web/headless profiles, so `hasHooks: false` and
-        // `trellis-start` stays as a user-invocable skill. Entry skills reference
-        // other skills by bare name (`trellis-<name>`), hence `cmdRefPrefix:
-        // "trellis-"`.
         name: "DeepSeek Harness (dsh)",
         templateDirs: ["common", "dsh"],
         configDir: ".dsh",
@@ -411,11 +426,9 @@ export const AI_TOOLS = {
      * `.kimi-code/skills/`.
      *
      * Kimi has no project-level hooks/settings file Trellis may write (hooks are
-     * user-level `~/.kimi-code/config.toml` only), so the Trellis agent prompts
-     * keep the pull-based prelude. They ship both as skills and as project-level
-     * custom sub-agent definitions under `.kimi-code/agents/` (Claude
-     * Code-compatible frontmatter), so the main session can dispatch
-     * `trellis-<name>` sub-agents directly.
+     * user-level `~/.kimi-code/config.toml` only) and no project-level custom
+     * sub-agent definitions (only the built-in coder/explore/plan sub-agents), so
+     * the Trellis agent prompts ship as skills with the pull-based prelude.
      */
     kimi: {
         name: "Kimi Code",