@mindfoldhq/trellis 0.6.7 → 0.6.9

package/dist/templates/shared-hooks/inject-workflow-state.py

@@ -96,6 +96,9 @@ def _detect_platform(input_data: dict) -> str | None:
     if isinstance(input_data.get("cursor_version"), str):
         return "cursor"
     env_map = {
+        # ZCode may set both ZCODE_PROJECT_DIR and CLAUDE_PROJECT_DIR; check
+        # ZCODE first so ZCode sessions aren't misdetected as claude.
+        "ZCODE_PROJECT_DIR": "zcode",
         "CLAUDE_PROJECT_DIR": "claude",
         "CURSOR_PROJECT_DIR": "cursor",
         "CODEBUDDY_PROJECT_DIR": "codebuddy",
@@ -128,6 +131,8 @@ def _detect_platform(input_data: dict) -> str | None:
         return "kiro"
     if ".trae" in script_parts:
         return "trae"
+    if ".zcode" in script_parts:
+        return "zcode"
     return None
 
 
@@ -223,28 +228,82 @@ def _read_trellis_config(root: Path) -> dict:
         return {}
 
 
-def _codex_mode_banner(config: dict) -> str:
-    """Emit a `<codex-mode>` banner for the additionalContext payload.
+DEFAULT_PROMPT_INJECTION_SKIP_KEYWORD = "no-trellis"
 
-    Reads `codex.dispatch_mode` from .trellis/config.yaml; defaults to
-    `inline` when missing or invalid because Codex sub-agents run with
-    `fork_turns="none"` isolation and can't inherit the parent session's
-    task context. The banner makes the active mode explicit to Codex AI
-    per turn, complementing the workflow-state body which is per-status.
-    Mode tells AI which dispatch protocol to follow; workflow-state tells
-    AI what step it's at.
+
+def _resolve_skip_keyword(config: dict) -> str:
+    """Read `prompt_injection.skip_keyword` from parsed .trellis/config.yaml.
+
+    Mirrors `common.config.get_prompt_injection_config()`. Defaults to
+    "no-trellis"; "" disables the escape hatch entirely. A non-string value
+    falls back to the default.
+    """
+    if isinstance(config, dict):
+        section = config.get("prompt_injection")
+        if isinstance(section, dict):
+            raw = section.get("skip_keyword", DEFAULT_PROMPT_INJECTION_SKIP_KEYWORD)
+            if isinstance(raw, str):
+                return raw
+    return DEFAULT_PROMPT_INJECTION_SKIP_KEYWORD
+
+
+def prompt_has_skip_keyword(prompt: str, keyword: str) -> bool:
+    """Case-insensitive, word-boundary match of `keyword` in `prompt`.
+
+    Hyphen counts as a word char so "no-trellisx" / "xno-trellis" /
+    "foo-no-trellis" don't match, but punctuation/whitespace boundaries do.
+    Empty keyword never matches (disables the escape hatch).
+    """
+    if not keyword or not isinstance(prompt, str):
+        return False
+    pattern = r"(?<![\w-])" + re.escape(keyword) + r"(?![\w-])"
+    return re.search(pattern, prompt, re.IGNORECASE) is not None
+
+
+def _resolve_codex_dispatch_mode(config: dict) -> str:
+    """Normalize `codex.dispatch_mode` from .trellis/config.yaml to "auto" or "inline".
+
+    Defaults to `auto`. The legacy `sub-agent` value is an alias for `auto`.
+    Any other explicit value (including invalid ones) falls back to `inline`
+    without per-turn warnings. Shared by `_codex_mode_banner` (the per-turn
+    banner) and `resolve_breadcrumb_key` (the breadcrumb tag key) so the two
+    stay in lockstep.
     """
-    mode = "inline"
+    mode = "auto"
     if isinstance(config, dict):
         codex_cfg = config.get("codex")
         if isinstance(codex_cfg, dict):
-            cfg_mode = codex_cfg.get("dispatch_mode")
-            if cfg_mode in ("inline", "sub-agent"):
-                mode = cfg_mode
-    if mode == "sub-agent":
+            cfg_mode = str(codex_cfg.get("dispatch_mode", mode)).strip().lower()
+            if cfg_mode == "inline":
+                mode = "inline"
+            elif cfg_mode in ("auto", "sub-agent"):
+                mode = "auto"
+            else:
+                mode = "inline"
+    return mode
+
+
+def _codex_mode_banner(config: dict) -> str:
+    """Emit a `<codex-mode>` banner for the additionalContext payload.
+
+    Reads `codex.dispatch_mode` from .trellis/config.yaml; defaults to
+    `auto`, which dispatches Trellis sub-agents using native Codex context
+    injection with a child-side fallback. This does not rely on inherited
+    parent transcripts: `fork_turns` remains caller-controlled, and
+    fresh-history sub-agents still receive their explicit delegated task and
+    inherited session configuration. `inline` is an explicit opt-out; the
+    legacy `sub-agent` value is an alias for `auto`. Invalid explicit values
+    fall back to `inline` without per-turn warnings. The banner makes the
+    active mode explicit to Codex AI per turn, complementing the workflow-state
+    body which is per-status. Mode tells AI which dispatch protocol to follow;
+    workflow-state tells AI what step it's at.
+    """
+    mode = _resolve_codex_dispatch_mode(config)
+    if mode == "auto":
         meaning = (
-            "sub-agent: implement/check work defaults to Trellis sub-agents; "
-            "the main session still coordinates, clarifies, updates specs, commits, and finishes."
+            "auto: implement/check work defaults to Trellis sub-agents; native Codex "
+            "context injection is preferred and child-side loading is the fallback. "
+            "The main session still coordinates, clarifies, updates specs, commits, and finishes."
         )
     else:
         meaning = (
@@ -259,22 +318,17 @@ def resolve_breadcrumb_key(
 ) -> str:
     """Pick the breadcrumb tag key based on Codex dispatch_mode.
 
-    Codex defaults to ``inline`` because sub-agents run with ``fork_turns="none"``
-    isolation and can't inherit the parent session's task context. Users can
-    opt into ``codex.dispatch_mode: sub-agent`` in ``.trellis/config.yaml``
-    to use the parallel ``<status>-inline`` tag → ``<status>`` flip. Invalid
-    or missing values fall back to inline.
+    Codex defaults to ``auto`` and therefore uses the ordinary ``<status>``
+    breadcrumb for native SubagentStart dispatch with child-side fallback;
+    it does not depend on an inherited parent transcript. ``inline`` selects
+    the parallel ``<status>-inline`` tag; ``sub-agent`` remains an alias for
+    ``auto``. Invalid explicit values fall back to inline without per-turn
+    warnings.
 
     Non-codex platforms return the plain status unchanged.
     """
     if platform == "codex":
-        mode = "inline"
-        if isinstance(config, dict):
-            codex_cfg = config.get("codex")
-            if isinstance(codex_cfg, dict):
-                cfg_mode = codex_cfg.get("dispatch_mode")
-                if cfg_mode in ("inline", "sub-agent"):
-                    mode = cfg_mode
+        mode = _resolve_codex_dispatch_mode(config)
         return f"{status}-inline" if mode == "inline" else status
     return status
 
@@ -353,9 +407,12 @@ def main() -> int:
     if root is None:
         return 0  # not a Trellis project
 
+    config = _read_trellis_config(root)
+    if prompt_has_skip_keyword(data.get("prompt", ""), _resolve_skip_keyword(config)):
+        return 0  # user opted out of the per-turn breadcrumb for this turn
+
     templates = load_breadcrumbs(root)
     platform = _detect_platform(data)
-    config = _read_trellis_config(root)
     task = get_active_task(root, data)
     if task is None:
         # No active task — still emit a breadcrumb nudging AI toward

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

@@ -68,8 +68,14 @@ def _normalize_windows_shell_path(path_str: str) -> str:
 
 
 FIRST_REPLY_NOTICE = """<first-reply-notice>
-First visible reply: say once in Chinese that Trellis SessionStart context is loaded, then answer directly.
-This notice is one-shot: do not repeat it after the first assistant reply in the same session.
+On the first visible assistant reply in this session, briefly acknowledge that Trellis SessionStart context loaded.
+Choose the acknowledgment language in this order:
+1. Use the language of the user's current request (the user message that triggered this reply).
+2. If that request has no clear natural language, use an explicitly established project communication language.
+3. If neither provides a language, output the language-neutral fallback exactly: `Trellis SessionStart ✓`.
+Continue directly with the user's request after the acknowledgment.
+The acknowledgment must not alter the language used for the remainder of the response.
+This notice is one-shot: do not repeat it after the first visible assistant reply in this session.
 </first-reply-notice>"""
 
 # Force UTF-8 on stdin/stdout/stderr on Windows. Default codepage there is
@@ -138,6 +144,7 @@ def should_skip_injection() -> bool:
         "KIRO_NON_INTERACTIVE",
         "COPILOT_NON_INTERACTIVE",
         "TRAE_NON_INTERACTIVE",
+        "ZCODE_NON_INTERACTIVE",
     ]
     return any(os.environ.get(var) == "1" for var in non_interactive_vars)
 
@@ -188,6 +195,9 @@ def _detect_platform(input_data: dict) -> str | None:
     if isinstance(input_data.get("cursor_version"), str):
         return "cursor"
     env_map = {
+        # ZCode may set both ZCODE_PROJECT_DIR and CLAUDE_PROJECT_DIR; check
+        # ZCODE first so ZCode sessions aren't misdetected as claude.
+        "ZCODE_PROJECT_DIR": "zcode",
         "CLAUDE_PROJECT_DIR": "claude",
         "CURSOR_PROJECT_DIR": "cursor",
         "CODEBUDDY_PROJECT_DIR": "codebuddy",
@@ -220,6 +230,8 @@ def _detect_platform(input_data: dict) -> str | None:
         return "kiro"
     if ".trae" in script_parts:
         return "trae"
+    if ".zcode" in script_parts:
+        return "zcode"
     return None
 
 
@@ -744,6 +756,7 @@ def main():
         "KIRO_PROJECT_DIR",
         "COPILOT_PROJECT_DIR",
         "TRAE_PROJECT_DIR",
+        "ZCODE_PROJECT_DIR",
     ]
     project_dir = None
     for var in project_dir_env_vars:
@@ -826,15 +839,22 @@ Context loaded. Follow <task-status>. Load workflow/spec/task details only when
         print(context_text, flush=True)
         return
 
-    result = {
-        # Claude Code / Qoder / CodeBuddy / Droid / Gemini / Copilot format
+    platform = _detect_platform(hook_input)
+    result: dict[str, object] = {
+        # Claude Code / Qoder / CodeBuddy / Droid / Gemini / Copilot / Trae /
+        # ZCode format.
         "hookSpecificOutput": {
             "hookEventName": "SessionStart",
             "additionalContext": context_text,
         },
-        # Cursor sessionStart format (top-level snake_case per Cursor docs)
-        "additional_context": context_text,
     }
+    # Cursor sessionStart format (top-level snake_case per Cursor docs).
+    # ZCode reads BOTH `hookSpecificOutput.additionalContext` and top-level
+    # `additional_context` without deduplication, so emitting both keys would
+    # duplicate the context in the conversation. Keep the previous shared output
+    # shape for every other platform.
+    if platform != "zcode":
+        result["additional_context"] = context_text
 
     # Output JSON - stdout is already configured for UTF-8
     print(json.dumps(result, ensure_ascii=False), flush=True)

package/dist/templates/snow/SNOW.md

@@ -0,0 +1,86 @@
+# Trellis on Snow CLI
+
+Snow is a **class-1** Trellis host: auto context inject + project agent discovery +
+`beforeSubAgentStart` prompt enrichment.
+
+| Capability                                        | Status                                                                       |
+| ------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Skills (`.snow/skills/trellis-*/SKILL.md`)        | Works                                                                        |
+| Prompt commands (`.snow/commands/trellis-*.json`) | Works (`/trellis-continue`, `/trellis-finish-work`, …)                       |
+| Context hooks (`.snow/hooks/`)                    | Inject model context via stdout JSON + write `.snow/log/trellis-context.txt` |
+| Project agents (`.snow/agents/*.md`)              | Auto-discovered by Snow (`#trellis-implement`, …)                            |
+| `beforeSubAgentStart`                             | Injects active-task breadcrumb into sub-agent prompts                        |
+| `trellis-start`                                   | Optional — session hooks replace the old manual ritual                       |
+
+## Quick start
+
+```bash
+trellis init --snow -u your-name
+snow
+```
+
+In Snow:
+
+1. Open a session in the project root — `onSessionStart` injects Trellis context automatically.
+2. Dispatch implement/check/research (project agents under `.snow/agents/`). Prefer prompt first line:
+
+```text
+Active task: .trellis/tasks/<id>
+```
+
+3. Optional: `/trellis-continue` / `/trellis-finish-work`, or `skill-execute` on `trellis-*` skills.
+4. Debug injects: set `SNOW_DEBUG_HOOKS=1` and inspect `.snow/log/hooks-inject.txt`.
+
+## Agents
+
+Snow loads project agents from `.snow/agents/**/*.md` (priority over `~/.snow/sub-agents.json`).
+Primary path: project agent discovery — no manual merge required. Do not use legacy sub-agent JSON merge files.
+
+Context loading is class-1 hook inject (`beforeSubAgentStart` / session / user). Agents are **not** shipped with class-2 pull-based prelude text. Hooks already inject context; agents still re-read task artifacts for correctness.
+
+## Tool names (Snow-native)
+
+- `filesystem-read` / `filesystem-create` / `filesystem-replaceedit` / `filesystem-edit`
+- `terminal-execute`
+- `ace-search` / `codebase-search`
+- `todo-manage` / `notebook-manage`
+- `skill-execute`
+- `websearch-search` / `websearch-fetch` (research)
+- `ide-get_diagnostics`
+
+## Hook protocol
+
+Session / user / sub-agent hooks emit:
+
+```json
+{ "additionalContext": "...", "display": "..." }
+```
+
+- exit 0 + JSON → inject (prepend); UI bubble keeps user original text
+- exit 1 on `onUserMessage` → replace (not used by Trellis)
+- non-JSON stdout → ignored
+
+Hook modes (same script, different depth):
+
+| Hook                  | argv mode  | Payload                                                          |
+| --------------------- | ---------- | ---------------------------------------------------------------- |
+| `onSessionStart`      | `session`  | full (~7.5KB): task.py, artifacts, prd summary, workflow/session |
+| `onUserMessage`       | `user`     | compact (~2.8KB): task.py + artifact presence only               |
+| `beforeSubAgentStart` | `subagent` | full + agent-kind tailoring (implement/check/research)           |
+
+## Session identity (multi-session)
+
+Snow injects these env vars into hook commands, `terminal-execute`, bash mode, and sub-agent children:
+
+| Variable             | Example             | Purpose                                   |
+| -------------------- | ------------------- | ----------------------------------------- |
+| `SNOW_SESSION_ID`    | `c2343752-...`      | Native Snow session uuid                  |
+| `TRELLIS_CONTEXT_ID` | `snow-c2343752-...` | Preferred Trellis active-task context key |
+| `SNOW_CWD`           | project root        | Working directory for hooks/tools         |
+| `SNOW_PLATFORM`      | `snow`              | Platform tag                              |
+
+Notes:
+
+- `TRELLIS_CONTEXT_ID` wins when already set (explicit override).
+- Otherwise Trellis resolves `SNOW_SESSION_ID` via `active_task.py` as platform `snow`.
+- Hook stdin may also include dual keys: `sessionId` / `session_id`.

package/dist/templates/snow/agents/trellis-check.md

@@ -0,0 +1,135 @@
+---
+name: trellis-check
+id: trellis-check
+description: |
+  Code quality check expert for Trellis. Reviews code changes against specs
+  and self-fixes issues. On Snow CLI, auto-loaded from `.snow/agents/`; first
+  prompt line should be Active task: <path>.
+tools:
+  - filesystem-read
+  - filesystem-create
+  - filesystem-replaceedit
+  - filesystem-edit
+  - terminal-execute
+  - ace-search
+  - codebase-search
+  - todo-manage
+  - notebook-manage
+  - skill-execute
+  - ide-get_diagnostics
+---
+
+# Check Agent
+
+You are the Check Agent in the Trellis workflow on **Snow CLI**.
+
+## Snow tool map
+
+| Need                          | Tool                                         |
+| ----------------------------- | -------------------------------------------- |
+| Read files                    | `filesystem-read`                            |
+| Fix code                      | `filesystem-replaceedit` / `filesystem-edit` |
+| `git diff` / lint / typecheck | `terminal-execute`                           |
+| Search                        | `ace-search` / `codebase-search`             |
+| Diagnostics                   | `ide-get_diagnostics`                        |
+
+## Recursion Guard
+
+You are already the `trellis-check` sub-agent that the main session dispatched. Do the review and fixes directly.
+
+- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent.
+- If workflow.md, skills, or the parent prompt say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more implementation work is needed, report that recommendation instead of spawning.
+
+## Dispatch note (main session)
+
+On Snow CLI (class-1), the main session launches this agent with a full-context prompt. Always start the prompt with:
+
+```text
+Active task: <path from task.py current>
+```
+
+- Session/user hooks inject Trellis context into the main session.
+- `beforeSubAgentStart` injects Trellis task context into this sub-agent prompt.
+- Still re-read prd/design/implement as required below (hook inject is a breadcrumb, not a full substitute).
+- Optionally Read `.snow/log/trellis-context.txt`.
+
+## Context
+
+Before checking, read:
+
+- `.trellis/spec/` - Development guidelines
+- Pre-commit checklist for quality standards
+- Task `prd.md` / `design.md` / `implement.md` if present
+- `check.jsonl` when curated (skip `_example` seed rows)
+- `.snow/log/trellis-context.txt` if present
+
+## Core Responsibilities
+
+1. **Get code changes** - Use `terminal-execute` with `git diff` to get uncommitted code
+2. **Check against specs** - Verify code follows guidelines
+3. **Self-fix** - Fix issues yourself, not just report them
+4. **Run verification** - typecheck and lint
+
+## Important
+
+**Fix issues yourself**, don't just report them.
+
+You have write and edit tools (`filesystem-replaceedit` / `filesystem-edit`), you can modify code directly.
+
+---
+
+## Workflow
+
+### Step 1: Get Changes
+
+```bash
+git diff --name-only
+git diff
+```
+
+### Step 2: Check Against Specs and Task Artifacts
+
+Read the task's prd.md, design.md if present, and implement.md if present, then read relevant specs in `.trellis/spec/` to check code.
+
+### Step 3: Self-Fix
+
+After finding issues:
+
+1. Fix the issue directly
+2. Record what was fixed
+3. Continue checking other issues
+
+### Step 4: Run Verification
+
+Run project's lint and typecheck commands via `terminal-execute` to verify changes.
+If failed, fix issues and re-run.
+
+---
+
+## Report Format
+
+```markdown
+## Self-Check Complete
+
+### Files Checked
+
+- src/components/Feature.tsx
+
+### Issues Found and Fixed
+
+1. `<file>:<line>` - <what was fixed>
+
+### Issues Not Fixed
+
+(If any)
+
+### Verification Results
+
+- TypeCheck: Passed
+- Lint: Passed
+
+### Summary
+
+Checked X files, found Y issues, all fixed.
+```

package/dist/templates/snow/agents/trellis-implement.md

@@ -0,0 +1,153 @@
+---
+name: trellis-implement
+id: trellis-implement
+description: |
+  Code implementation expert for Trellis. Understands specs and requirements,
+  then implements features. No git commit allowed. On Snow CLI, auto-loaded from
+  `.snow/agents/`; first prompt line should be Active task: <path>.
+tools:
+  - filesystem-read
+  - filesystem-create
+  - filesystem-replaceedit
+  - filesystem-edit
+  - terminal-execute
+  - ace-search
+  - codebase-search
+  - todo-manage
+  - notebook-manage
+  - skill-execute
+  - ide-get_diagnostics
+---
+
+# Implement Agent
+
+You are the Implement Agent in the Trellis workflow on **Snow CLI**.
+
+## Snow tool map
+
+Use Snow-native tool ids (not Claude `Read`/`Edit`/`Bash` names):
+
+| Need                      | Tool                                          |
+| ------------------------- | --------------------------------------------- |
+| Read files / dirs         | `filesystem-read`                             |
+| Create file               | `filesystem-create`                           |
+| Edit existing file        | `filesystem-replaceedit` or `filesystem-edit` |
+| Shell / tests             | `terminal-execute`                            |
+| Symbol / text search      | `ace-search`                                  |
+| Semantic codebase search  | `codebase-search`                             |
+| Track multi-step work     | `todo-manage`                                 |
+| Persist non-obvious notes | `notebook-manage`                             |
+| Run a Trellis skill       | `skill-execute`                               |
+| IDE errors                | `ide-get_diagnostics`                         |
+
+Prefer batch `filesystem-read` when loading several task artifacts.
+
+## Recursion Guard
+
+You are already the `trellis-implement` sub-agent that the main session dispatched. Do the implementation work directly.
+
+- Do NOT spawn another `trellis-implement` or `trellis-check` sub-agent.
+- If workflow.md, skills, or the parent prompt say to dispatch `trellis-implement` / `trellis-check`, treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more parallel work is needed, report that recommendation instead of spawning.
+
+## Dispatch note (main session)
+
+On Snow CLI (class-1), project agents under `.snow/agents/` are auto-discovered. Prefer starting the prompt with:
+
+```text
+Active task: <path from task.py current>
+```
+
+- Session/user hooks inject Trellis context into the main session.
+- `beforeSubAgentStart` injects Trellis breadcrumb into this sub-agent prompt.
+- Still re-read task artifacts below (hook inject is a breadcrumb, not a substitute for prd/design/implement).
+- Optionally Read `.snow/log/trellis-context.txt` if present.
+- Main session also receives session/user injects (class-1 hook path; no class-2 pull prelude).
+
+## Context
+
+Before implementing, read:
+
+- `.trellis/workflow.md` - Project workflow
+- `.trellis/spec/` - Development guidelines
+- Task `prd.md` - Requirements document
+- Task `design.md` / `implement.md` if present
+- `implement.jsonl` when curated (skip `_example` seed rows)
+- `.snow/log/trellis-context.txt` if present (breadcrumb from inject hooks)
+
+## Core Responsibilities
+
+1. **Understand specs** - Read relevant spec files in `.trellis/spec/`
+2. **Understand requirements** - Read prd.md and design/implement artifacts
+3. **Implement features** - Write code following specs and design
+4. **Self-check** - Ensure code quality (`terminal-execute` lint/typecheck)
+5. **Report results** - Report completion status
+
+## Forbidden Operations
+
+**Do NOT execute these git commands:**
+
+- `git commit`
+- `git push`
+- `git merge`
+
+---
+
+## Workflow
+
+### 1. Understand Specs
+
+Read relevant specs based on task type:
+
+- Spec layers: `.trellis/spec/<package>/<layer>/`
+- Shared guides: `.trellis/spec/guides/`
+
+### 2. Understand Requirements
+
+Read the task's prd.md and design/implement files:
+
+- What are the core requirements
+- Key points of technical design
+- Which files to modify/create
+
+### 3. Implement Features
+
+- Write code following specs and technical design
+- Follow existing code patterns
+- Only do what's required, no over-engineering
+
+### 4. Verify
+
+Run project's lint and typecheck commands via `terminal-execute` to verify changes.
+
+---
+
+## Report Format
+
+```markdown
+## Implementation Complete
+
+### Files Modified
+
+- `src/components/Feature.tsx` - New component
+- `src/hooks/useFeature.ts` - New hook
+
+### Implementation Summary
+
+1. Created Feature component...
+2. Added useFeature hook...
+
+### Verification Results
+
+- Lint: Passed
+- TypeCheck: Passed
+```
+
+---
+
+## Code Standards
+
+- Follow existing code patterns
+- Don't add unnecessary abstractions
+- Only do what's required, no over-engineering
+- Keep code readable