@blulotus/trellis 0.7.0 → 0.7.1

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

@@ -4,23 +4,23 @@
 Task Management Script.
 
 Usage:
-    python3 task.py create "<title>" [--slug <name>] [--assignee <dev>] [--priority P0|P1|P2|P3] [--parent <dir>] [--package <pkg>] [--no-start]
-    python3 task.py add-context <dir> <file> <path> [reason] # Add jsonl entry
-    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
-    python3 task.py current [--source] [--json] # Show active task
-    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
-    python3 task.py set-meta <dir> <key> <value>  # Set a task metadata key
-    python3 task.py archive <task-dir>          # Archive completed task
-    python3 task.py list                        # List active tasks
-    python3 task.py list-archive [month]        # List archived tasks
-    python3 task.py add-subtask <parent-dir> <child-dir>     # Link child to parent
-    python3 task.py remove-subtask <parent-dir> <child-dir>  # Unlink child from parent
+    python task.py create "<title>" [--slug <name>] [--assignee <dev>] [--priority P0|P1|P2|P3] [--parent <dir>] [--package <pkg>] [--no-start]
+    python task.py add-context <dir> <file> <path> [reason] # Add jsonl entry
+    python task.py validate <dir>              # Validate jsonl files
+    python task.py list-context <dir>          # List jsonl entries
+    python task.py start <dir>                 # Set active task
+    python task.py current [--source] [--json] # Show active task
+    python task.py finish                      # Clear active task
+    python task.py workflow <id>|--clear       # Set/clear per-task workflow selection
+    python task.py set-branch <dir> <branch>   # Set git branch
+    python task.py set-base-branch <dir> <branch>  # Set PR target branch
+    python task.py set-scope <dir> <scope>     # Set scope for PR title
+    python task.py set-meta <dir> <key> <value>  # Set a task metadata key
+    python task.py archive <task-dir>          # Archive completed task
+    python task.py list                        # List active tasks
+    python task.py list-archive [month]        # List archived tasks
+    python task.py add-subtask <parent-dir> <child-dir>     # Link child to parent
+    python task.py remove-subtask <parent-dir> <child-dir>  # Unlink child from parent
 """
 
 from __future__ import annotations
@@ -41,6 +41,7 @@ from common.paths import (
 )
 from common.active_task import (
     clear_active_task,
+    mark_session_engaged,
     resolve_active_task,
     resolve_context_key,
     set_active_task,
@@ -69,9 +70,36 @@ from common.task_context import (
 
 
 # =============================================================================
-# Command: start / finish
+# Command: engage / start / finish
 # =============================================================================
 
+def cmd_engage(args: argparse.Namespace) -> int:
+    """Opt this session into the Trellis workflow."""
+    repo_root = get_repo_root()
+    context_key = mark_session_engaged(repo_root)
+
+    if context_key:
+        print(colored(f"✓ Trellis engaged for this session: {context_key}", Colors.GREEN))
+        return 0
+
+    # Unlike `start`, engage has no useful degraded mode: without a persisted
+    # flag both context-injection hooks stay silent for the whole session, so
+    # every later phase would run without the per-turn breadcrumb that enforces
+    # the planning and commit gates. Fail loudly instead of half-working.
+    print(colored("Error: cannot engage — no session identity available", Colors.RED))
+    print(colored(
+        "The engaged flag is keyed by session, so without an identity the "
+        "context-injection hooks cannot tell this session opted in.",
+        Colors.YELLOW,
+    ))
+    print(colored(
+        "Hint: run inside an AI session whose hooks are active, or set "
+        "TRELLIS_CONTEXT_ID before running task.py engage.",
+        Colors.YELLOW,
+    ))
+    return 1
+
+
 def cmd_start(args: argparse.Namespace) -> int:
     """Set active task."""
     repo_root = get_repo_root()
@@ -229,7 +257,7 @@ def cmd_workflow(args: argparse.Namespace) -> int:
         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")
+        print("Usage: python task.py workflow <id> | --clear")
         return 1
 
     active = resolve_active_task(repo_root)
@@ -456,28 +484,29 @@ def show_usage() -> None:
     print("""Task Management Script
 
 Usage:
-  python3 task.py create <title>                     Create new task directory
-  python3 task.py create <title> --package <pkg>     Create task for a specific package
-  python3 task.py create <title> --parent <dir>      Create task as child of parent
-  python3 task.py create <title> --no-start          Create without making it active in this session
-  python3 task.py create <title> --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
-  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
-  python3 task.py set-meta <dir> <key> <value>       Set/overwrite a task metadata key
-  python3 task.py archive <task-dir>                 Archive completed task
-  python3 task.py add-subtask <parent> <child>       Link child task to parent
-  python3 task.py remove-subtask <parent> <child>    Unlink child from parent
-  python3 task.py list [--mine] [--status <status>] [--json]  List tasks
-  python3 task.py list-archive [YYYY-MM]             List archived tasks
+  python task.py create <title>                     Create new task directory
+  python task.py create <title> --package <pkg>     Create task for a specific package
+  python task.py create <title> --parent <dir>      Create task as child of parent
+  python task.py create <title> --no-start          Create without making it active in this session
+  python task.py create <title> --workflow <id>     Create task pinned to a workflow variant
+  python task.py add-context <dir> <jsonl> <path> [reason]  Add entry to jsonl
+  python task.py validate <dir>                     Validate jsonl files
+  python task.py list-context <dir>                 List jsonl entries
+  python task.py engage                             Opt this session into the Trellis workflow
+  python task.py start <dir>                        Set active task
+  python task.py current [--source]                 Show active task
+  python task.py finish                             Clear active task
+  python task.py workflow <id>                      Select workflow variant for active task
+  python task.py workflow --clear                   Clear selection (use default resolution)
+  python task.py set-branch <dir> <branch>          Set git branch
+  python task.py set-base-branch <dir> <branch>     Set PR target branch
+  python task.py set-scope <dir> <scope>            Set scope for PR title
+  python task.py set-meta <dir> <key> <value>       Set/overwrite a task metadata key
+  python task.py archive <task-dir>                 Archive completed task
+  python task.py add-subtask <parent> <child>       Link child task to parent
+  python task.py remove-subtask <parent> <child>    Unlink child from parent
+  python task.py list [--mine] [--status <status>] [--json]  List tasks
+  python task.py list-archive [YYYY-MM]             List archived tasks
 
 Monorepo options:
   --package <pkg>      Package name (validated against config.yaml packages)
@@ -488,21 +517,21 @@ List options:
   --json               Output machine-readable JSON (also available on `current`)
 
 Examples:
-  python3 task.py create "Add login feature" --slug add-login
-  python3 task.py create "Add login feature" --slug add-login --package cli
-  python3 task.py create "Add login feature" --meta linear=ENG-123 --meta epic=auth
-  python3 task.py create "Child task" --slug child --parent .trellis/tasks/01-21-parent
-  python3 task.py add-context <dir> implement .trellis/spec/cli/backend/auth.md "Auth guidelines"
-  python3 task.py set-branch <dir> task/add-login
-  python3 task.py start .trellis/tasks/01-21-add-login
-  python3 task.py current --source
-  python3 task.py finish
-  python3 task.py archive add-login
-  python3 task.py add-subtask parent-task child-task  # Link existing tasks
-  python3 task.py remove-subtask parent-task child-task
-  python3 task.py list                               # List all active tasks
-  python3 task.py list --mine                        # List my tasks only
-  python3 task.py list --mine --status in_progress   # List my in-progress tasks
+  python task.py create "Add login feature" --slug add-login
+  python task.py create "Add login feature" --slug add-login --package cli
+  python task.py create "Add login feature" --meta linear=ENG-123 --meta epic=auth
+  python task.py create "Child task" --slug child --parent .trellis/tasks/01-21-parent
+  python task.py add-context <dir> implement .trellis/spec/cli/backend/auth.md "Auth guidelines"
+  python task.py set-branch <dir> task/add-login
+  python task.py start .trellis/tasks/01-21-add-login
+  python task.py current --source
+  python task.py finish
+  python task.py archive add-login
+  python task.py add-subtask parent-task child-task  # Link existing tasks
+  python task.py remove-subtask parent-task child-task
+  python task.py list                               # List all active tasks
+  python task.py list --mine                        # List my tasks only
+  python task.py list --mine --status in_progress   # List my in-progress tasks
 """)
 
 
@@ -533,7 +562,7 @@ def main() -> int:
         )
         print("See .trellis/workflow.md planning artifact guidance or run:", file=sys.stderr)
         print(
-            "  python3 ./.trellis/scripts/get_context.py --mode phase --step 1",
+            "  python ./.trellis/scripts/get_context.py --mode phase --step 1",
             file=sys.stderr,
         )
         print(
@@ -591,6 +620,9 @@ def main() -> int:
     p_listctx = subparsers.add_parser("list-context", help="List context entries")
     p_listctx.add_argument("dir", help="Task directory")
 
+    # engage
+    subparsers.add_parser("engage", help="Opt this session into the Trellis workflow")
+
     # start
     p_start = subparsers.add_parser("start", help="Set active task")
     p_start.add_argument("dir", help="Task directory")
@@ -668,6 +700,7 @@ def main() -> int:
         "add-context": cmd_add_context,
         "validate": cmd_validate,
         "list-context": cmd_list_context,
+        "engage": cmd_engage,
         "start": cmd_start,
         "current": cmd_current,
         "finish": cmd_finish,

package/dist/templates/trellis/workflow.md

@@ -102,9 +102,13 @@ python3 ./.trellis/scripts/get_context.py --mode phase --step <X.Y>  # detailed
   The [workflow-state:STATUS] blocks embedded in the ## Phase Index section
   below are the SINGLE source of truth for the per-turn `<workflow-state>`
   breadcrumb that every supported AI platform's UserPromptSubmit hook
-  reads. inject-workflow-state.py (Python platforms) and
-  inject-workflow-state.js (OpenCode plugin) only parse them — there is no
-  fallback dict baked into the scripts after v0.5.0-rc.0.
+  reads. inject-workflow-state.py only parses them — there is no fallback
+  dict baked into the script after v0.5.0-rc.0.
+
+  The breadcrumb is opt-in: inject-workflow-state.py emits nothing until the
+  session runs `task.py engage` via `trellis-start` / `trellis-continue` /
+  `trellis-finish-work`. Every block below therefore speaks only to sessions
+  that asked for Trellis.
 
   STATUS charset: [A-Za-z0-9_-]+. When the hook can't find a tag, it
   degrades to a generic "Refer to workflow.md for current step." line —
@@ -118,7 +122,8 @@ python3 ./.trellis/scripts/get_context.py --mode phase --step <X.Y>  # detailed
     skip and Phase 3.4 commit skip both manifested via this gap).
 
   TAG ↔ PHASE scoping:
-    [workflow-state:no_task]      → no active task; before Phase 1
+    [workflow-state:no_task]      → engaged with no active task: before
+                                    Phase 1, or after task.py finish/archive
     [workflow-state:planning]     → all of Phase 1 (status='planning')
     [workflow-state:planning-inline] → Codex inline variant of Phase 1
     [workflow-state:in_progress]  → Phase 2 + Phase 3.2-3.4
@@ -151,8 +156,9 @@ Phase 3: Finish  → verify, commit, and wrap up
 
 ### Request Triage
 
-- Do not ask whether to create a Trellis task. With no active task, work inline.
-- Create a task only when the user explicitly asks for one. The user owns the complexity judgment; do not offer, suggest, or infer it.
+- Trellis is opt-in per session. Until the user invokes `trellis-start`, `trellis-continue` or `trellis-finish-work`, no Trellis context is injected and there is nothing to route — work inline.
+- Do not ask whether to create a Trellis task, and do not offer, suggest, or infer that a request warrants one. The user owns that judgment and expresses it by invoking `trellis-start`.
+- An in-flight task from another session is not this session's task. Only `trellis-continue` adopts it.
 - Creating a task is not approval to start implementation. Planning still happens first, and every task gets the full artifact set.
 
 ### Planning Artifacts
@@ -188,17 +194,20 @@ Use child tasks for deliverables that can be planned, implemented, checked, and
 
 Create new children with `task.py create "<title>" --slug <name> --parent <parent-dir>`. Link existing tasks with `task.py add-subtask <parent> <child>`, and unlink mistakes with `task.py remove-subtask <parent> <child>`.
 
-<!-- Per-turn breadcrumb: shown when there is no active task (before Phase 1) -->
+<!-- Per-turn breadcrumb: shown in an engaged session that has no active task —
+     either `trellis-start` has not created one yet, or `task.py finish` /
+     archive cleared the pointer mid-session. An unengaged session gets no
+     breadcrumb at all, so this block never speaks for one. -->
 
 [workflow-state:no_task]
 No active task. Work inline; create a Trellis task only when the user explicitly asks for one.
 [/workflow-state:no_task]
 
 ### Phase 1: Plan
-- 1.0 Create task `[required · once]` (only on explicit user request)
+- 1.0 Create task `[required · once]` (only on explicit user request, i.e. `trellis-start`)
 - 1.1 Requirement exploration `[required · repeatable]` (`prd.md`, `design.md`, `implement.md` — all three)
 - 1.2 Research `[optional · repeatable]` (required for `kind=bug`: this is where the repro is built)
-- 1.3 Configure context `[required · once]` — Claude Code, Cursor, OpenCode, Codex, Kiro, Gemini, Qoder, CodeBuddy, Copilot, Droid, Pi, Oh My Pi, ZCode, Snow, Reasonix, Grok, Kimi Code (sub-agent-dispatch platforms only; inline platforms skip)
+- 1.3 Configure context `[required · once]` — Claude Code, Codex (sub-agent-dispatch platforms only; inline platforms skip)
 - 1.4 Activate task `[required · once]` (review gate + red-evidence gate, then `task.py start`; status → in_progress)
 - 1.5 Completion criteria
 
@@ -237,11 +246,10 @@ 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/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.
+Sub-agent dispatch protocol applies to all platforms and all sub-agents, including native Codex `SubagentStart` context injection with child-side pull fallback and `trellis-research`: every dispatch prompt starts with `Active task: <task path from task.py current>` before role-specific instructions.
 
 [workflow-state:in_progress]
 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` -> commit (Phase 3.4) -> `/trellis:finish-work`. Spec update (3.3) is on demand — run it when the user asks, not as part of the default flow.
 Red before green: work the `implement.md` slice checklist one slice at a time — test at a seam confirmed in `design.md`, run it, paste the redacted red output into that slice entry, then write the minimum code to pass. No horizontal slicing, no tautological assertions, no refactoring inside a red-green cycle. `kind=chore` and repos with no runnable harness must state that in the slice entry instead of skipping silently. Load the `trellis-tdd` skill for the full contract.
 Main-session default: dispatch implement/check sub-agents. 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.
@@ -292,23 +300,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, DeepSeek Harness]
+[Claude Code, codex-sub-agent]
 
 - Planning or unclear requirements -> `trellis-brainstorm`.
 - `in_progress` implementation/check -> dispatch `trellis-implement` / `trellis-check`.
 - Writing a failing test, or reproducing a reported bug -> `trellis-tdd`.
 - 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, DeepSeek Harness]
+[/Claude Code, codex-sub-agent]
 
-[codex-inline, Kilo, Antigravity, Devin]
+[codex-inline]
 
 - Planning or unclear requirements -> `trellis-brainstorm`.
 - Before editing -> `trellis-before-dev`; after editing -> `trellis-check`.
 - Writing a failing test, or reproducing a reported bug -> `trellis-tdd`.
 - Repeated debugging -> `trellis-break-loop`; spec updates -> `trellis-update-spec`.
 
-[/codex-inline, Kilo, Antigravity, Devin]
+[/codex-inline]
 
 ### Guardrails
 
@@ -336,7 +344,7 @@ Goal: turn an explicitly requested task into the planning artifacts and red evid
 
 #### 1.0 Create task `[required · once]`
 
-Create the task directory only when the user explicitly asked for a task. Do not ask whether to create one, and do not create one on your own initiative. The command sets status to `planning`, writes `task.json`, creates a default `prd.md`, and auto-targets the new task when session identity is available:
+Create the task directory only when the user explicitly asked for a task — in practice, when they invoked `trellis-start`, which owns this step. Do not ask whether to create one, and do not create one on your own initiative. The command sets status to `planning`, writes `task.json`, creates a default `prd.md`, and auto-targets the new task when session identity is available:
 
 ```bash
 python3 ./.trellis/scripts/task.py create "<task title>" --slug <name> --meta kind=<bug|feature|chore>
@@ -380,22 +388,21 @@ 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, DeepSeek Harness]
+[Claude Code, codex-sub-agent]
 
 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, DeepSeek Harness]
+[/Claude Code, codex-sub-agent]
 
-[codex-inline, Kilo, Antigravity, Devin]
+[codex-inline]
 
 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]
+[/codex-inline]
 
 **Research artifact conventions**:
 - One file per research topic (e.g. `research/auth-library-comparison.md`)
@@ -421,7 +428,7 @@ Brainstorm and research can interleave freely — pause to research a technical
 
 #### 1.3 Configure context `[required · once]`
 
-[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]
+[Claude Code, codex-sub-agent]
 
 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.
 
@@ -466,13 +473,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, DeepSeek Harness]
+[/Claude Code, codex-sub-agent]
 
-[codex-inline, Kilo, Antigravity, Devin]
+[codex-inline]
 
 Skip this step. Context is loaded directly by the `trellis-before-dev` skill in Phase 2.
 
-[/codex-inline, Kilo, Antigravity, Devin]
+[/codex-inline]
 
 #### 1.4 Activate task `[required · once]`
 
@@ -506,11 +513,11 @@ If `task.py start` errors with a session-identity message (no context key from h
 | User confirms task should enter implementation | ✅ |
 | `task.py start` has been run (status = in_progress) | ✅ |
 
-[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]
+[Claude Code, codex-sub-agent]
 
 | `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, DeepSeek Harness]
+[/Claude Code, codex-sub-agent]
 
 ---
 
@@ -533,7 +540,7 @@ For `meta.kind=bug`, the slice-1 test is the minimised reproduction from `resear
 
 `meta.kind=chore` is exempt. A repo with no runnable harness is also exempt, but the slice entry must say so and why — never skip the cycle silently. Load the `trellis-tdd` skill for the full contract.
 
-[Claude Code, Cursor, OpenCode, codex-sub-agent, CodeBuddy, Droid, Pi, ZCode, Snow, Oh My Pi]
+[Claude Code, codex-sub-agent]
 
 Spawn the implement sub-agent:
 
@@ -546,38 +553,9 @@ The platform hook/plugin auto-handles:
 - Injects `prd.md`, `design.md` if present, and `implement.md` if present
 - For Codex, `SubagentStart` supplies native context injection; the agent profile keeps child-side loading as the fallback
 
-[/Claude Code, Cursor, OpenCode, codex-sub-agent, CodeBuddy, Droid, Pi, ZCode, Snow, Oh My Pi]
-
-[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 one `implement.md` slice at a time, red before green at the seams confirmed in `design.md`, 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, DeepSeek Harness]
-
-[Kiro]
-
-Spawn the implement sub-agent:
-
-- **Agent type**: `trellis-implement`
-- **Task description**: Implement the reviewed task artifacts one `implement.md` slice at a time, red before green at the seams confirmed in `design.md`, consulting materials under `{TASK_DIR}/research/`; finish by running project lint and type-check
-- **Dispatch prompt guard**: Tell the spawned agent it is already the `trellis-implement` sub-agent and must implement directly, not spawn another `trellis-implement` / `trellis-check`.
-
-The platform prelude auto-handles the context load requirement:
-- Reads `implement.jsonl` and injects referenced spec/research files into the agent prompt
-- Injects `prd.md`, `design.md` if present, and `implement.md` if present
-
-[/Kiro]
+[/Claude Code, codex-sub-agent]
 
-[codex-inline, Kilo, Antigravity, Devin]
+[codex-inline]
 
 1. Load the `trellis-before-dev` skill to read project guidelines
 2. Read `{TASK_DIR}/prd.md`, then `design.md`, then `implement.md`
@@ -585,18 +563,17 @@ The platform prelude auto-handles the context load requirement:
 4. Load the `trellis-tdd` skill and walk the `implement.md` slice checklist red-before-green, one slice at a time
 5. Run project lint and type-check
 
-[/codex-inline, Kilo, Antigravity, Devin]
+[/codex-inline]
 
 #### 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, DeepSeek Harness]
+[Claude Code, codex-sub-agent]
 
 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
@@ -606,9 +583,9 @@ The check agent's job:
 - 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, DeepSeek Harness]
+[/Claude Code, codex-sub-agent]
 
-[codex-inline, Kilo, Antigravity, Devin]
+[codex-inline]
 
 Load the `trellis-check` skill and verify the code per its guidance:
 - Spec compliance
@@ -617,7 +594,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]
+[/codex-inline]
 
 **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.
 
@@ -718,6 +695,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:
+- Trellis is opt-in per session: both injection hooks stay silent until an entry point runs `task.py engage`. Never move a required step's only enforcement out of the per-turn breadcrumb.
 - With no active task, never ask whether to create one. A task is created only on the user's explicit request.
 - Every task carries `prd.md`, `design.md`, and `implement.md` before start. There is no PRD-only tier.
 - `meta.kind` is never guessed, and the red-evidence gate for that kind must be satisfied — or its impossibility written down — before `task.py start`.
@@ -727,7 +705,7 @@ All tag blocks live in the `## Phase Index` section above, immediately after eac
 
 | Scope | Corresponding tag |
 |---|---|
-| No active task (before Phase 1) | `[workflow-state:no_task]` (after the Phase Index ASCII art) |
+| Engaged, no active task (before Phase 1, or after archive) | `[workflow-state:no_task]` (after the Phase Index ASCII art) |
 | All of Phase 1 (task created → ready for implementation) | `[workflow-state:planning]` (after Phase 1 summary) |
 | Codex inline Phase 1 | `[workflow-state:planning-inline]` |
 | Phase 2 + Phase 3.2–3.4 (implementation + check + wrap-up) | `[workflow-state:in_progress]` (after Phase 2 summary) |

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

@@ -6,33 +6,33 @@
 /**
  * Supported AI coding tools
  */
-export type AITool = "claude-code" | "cursor" | "opencode" | "codex" | "kilo" | "kiro" | "gemini" | "antigravity" | "devin" | "qoder" | "codebuddy" | "copilot" | "droid" | "dsh" | "pi" | "reasonix" | "zcode" | "trae" | "omp" | "grok" | "kimi" | "snow";
+export type AITool = "claude-code" | "codex";
 /**
  * Template directory categories
  */
-export type TemplateDir = "common" | "claude" | "cursor" | "opencode" | "codex" | "kilo" | "kiro" | "gemini" | "antigravity" | "devin" | "qoder" | "codebuddy" | "copilot" | "droid" | "dsh" | "pi" | "reasonix" | "zcode" | "trae" | "omp" | "grok" | "kimi" | "snow";
+export type TemplateDir = "common" | "claude" | "codex";
 /**
- * CLI flag names for platform selection (e.g., --claude, --cursor, --kilo, --kiro, --gemini, --antigravity)
+ * CLI flag names for platform selection (`--claude`, `--codex`).
  * Must match keys in InitOptions (src/commands/init.ts)
  */
-export type CliFlag = "claude" | "cursor" | "opencode" | "codex" | "kilo" | "kiro" | "gemini" | "antigravity" | "devin" | "qoder" | "codebuddy" | "copilot" | "droid" | "dsh" | "pi" | "reasonix" | "zcode" | "trae" | "omp" | "grok" | "kimi" | "snow";
+export type CliFlag = "claude" | "codex";
 /**
  * Template context for placeholder resolution.
  * Controls how common templates are rendered per platform.
  */
 export interface TemplateContext {
     /** Prefix for cross-referencing other commands/skills */
-    cmdRefPrefix: "/trellis:" | "/trellis-" | "$" | "/" | "/skill trellis-" | "/skill:trellis-" | "trellis-";
+    cmdRefPrefix: "/trellis:" | "$";
     /** Description of AI executor actions shown in role tables */
-    executorAI: "Bash scripts or Task calls" | "Bash scripts or tool calls" | "Bash scripts or Agent calls" | "Bash scripts or file reads";
+    executorAI: "Bash scripts or Task calls" | "Bash scripts or tool calls";
     /** Label for user-invocable actions */
-    userActionLabel: "Slash commands" | "Skills" | "Workflows" | "Prompts" | "Commands";
+    userActionLabel: "Slash commands" | "Skills";
     /** Platform supports spawning sub-agents with isolated context */
     agentCapable: boolean;
     /** Platform has hook system (SessionStart, PreToolUse) */
     hasHooks: boolean;
     /**
-     * CLI flag value for this platform (e.g. "claude", "codex", "kiro").
+     * CLI flag value for this platform ("claude", "codex").
      * Substituted into template commands via {{CLI_FLAG}} so rendered skill /
      * command files can pass `--platform <flag>` to scripts that need to know
      * the invoking platform, removing the need to re-detect at runtime.
@@ -57,7 +57,7 @@ export interface AIToolConfig {
      * to the platform's managed paths automatically.
      */
     supportsAgentSkills?: boolean;
-    /** Additional managed paths beyond configDir (e.g., .github/hooks for Copilot) */
+    /** Additional managed paths beyond configDir (e.g., .codex/skills) */
     extraManagedPaths?: string[];
     /** CLI flag name for --flag options (e.g., "claude" for --claude) */
     cliFlag: CliFlag;
@@ -73,7 +73,7 @@ export interface AIToolConfig {
  * This is the single source of truth for platform data.
  *
  * When adding a new platform, add an entry here and create:
- * 1. src/configurators/{platform}.ts — configure function
+ * 1. src/configurators/{platform}.ts — collect{Platform}Templates()
  * 2. src/templates/{platform}/ — template files
  * 3. Register in src/configurators/index.ts — PLATFORM_FUNCTIONS
  * 4. Add CLI flag in src/cli/index.ts

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":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,MAAM,MAAM,GACd,aAAa,GACb,QAAQ,GACR,UAAU,GACV,OAAO,GACP,MAAM,GACN,MAAM,GACN,QAAQ,GACR,aAAa,GACb,OAAO,GACP,OAAO,GACP,WAAW,GACX,SAAS,GACT,OAAO,GACP,KAAK,GACL,IAAI,GACJ,UAAU,GACV,OAAO,GACP,MAAM,GACN,KAAK,GACL,MAAM,GACN,MAAM,GACN,MAAM,CAAC;AAEX;;GAEG;AACH,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,OAAO,GACP,MAAM,GACN,MAAM,GACN,QAAQ,GACR,aAAa,GACb,OAAO,GACP,OAAO,GACP,WAAW,GACX,SAAS,GACT,OAAO,GACP,KAAK,GACL,IAAI,GACJ,UAAU,GACV,OAAO,GACP,MAAM,GACN,KAAK,GACL,MAAM,GACN,MAAM,GACN,MAAM,CAAC;AAEX;;;GAGG;AACH,MAAM,MAAM,OAAO,GACf,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,OAAO,GACP,MAAM,GACN,MAAM,GACN,QAAQ,GACR,aAAa,GACb,OAAO,GACP,OAAO,GACP,WAAW,GACX,SAAS,GACT,OAAO,GACP,KAAK,GACL,IAAI,GACJ,UAAU,GACV,OAAO,GACP,MAAM,GACN,KAAK,GACL,MAAM,GACN,MAAM,GACN,MAAM,CAAC;AAEX;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,YAAY,EACR,WAAW,GACX,WAAW,GACX,GAAG,GACH,GAAG,GACH,iBAAiB,GACjB,iBAAiB,GACjB,UAAU,CAAC;IACf,8DAA8D;IAC9D,UAAU,EACN,4BAA4B,GAC5B,4BAA4B,GAC5B,6BAA6B,GAC7B,4BAA4B,CAAC;IACjC,uCAAuC;IACvC,eAAe,EACX,gBAAgB,GAChB,QAAQ,GACR,WAAW,GACX,SAAS,GACT,UAAU,CAAC;IACf,kEAAkE;IAClE,YAAY,EAAE,OAAO,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,kFAAkF;IAClF,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,cAAc,EAAE,OAAO,CAAC;IACxB,+EAA+E;IAC/E,cAAc,EAAE,OAAO,CAAC;IACxB,sEAAsE;IACtE,eAAe,EAAE,eAAe,CAAC;CAClC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAidjD,CAAC;AAEF;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAExD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAUtD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAE3D"}
+{"version":3,"file":"ai-tools.d.ts","sourceRoot":"","sources":["../../src/types/ai-tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,aAAa,GAAG,OAAO,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;AAExD;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEzC;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,YAAY,EAAE,WAAW,GAAG,GAAG,CAAC;IAChC,8DAA8D;IAC9D,UAAU,EAAE,4BAA4B,GAAG,4BAA4B,CAAC;IACxE,uCAAuC;IACvC,eAAe,EAAE,gBAAgB,GAAG,QAAQ,CAAC;IAC7C,kEAAkE;IAClE,YAAY,EAAE,OAAO,CAAC;IACtB,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AACD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,YAAY,EAAE,WAAW,EAAE,CAAC;IAC5B,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,cAAc,EAAE,OAAO,CAAC;IACxB,+EAA+E;IAC/E,cAAc,EAAE,OAAO,CAAC;IACxB,sEAAsE;IACtE,eAAe,EAAE,eAAe,CAAC;CAClC;AACD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAkCjD,CAAC;AACF;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAExD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAUtD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAE3D"}