@pennixrv/trellis 0.6.45 → 0.7.0-beta.5

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

@@ -452,6 +452,25 @@ def _strip_breadcrumb_tag_blocks(content: str) -> str:
     return re.sub(r"\n{3,}", "\n\n", stripped).strip()
 
 
+def _resolve_workflow_md(root: Path, input_data: dict) -> Path:
+    """Resolve the active task's workflow file, falling back to the global one.
+
+    The per-task resolution rule lives in common.workflow_selection inside
+    .trellis/scripts. Older installed projects may not ship that module, and
+    hooks must never crash the session — ANY failure (import error, old
+    scripts tree, resolver bug) falls back to the global workflow.md.
+    """
+    try:
+        scripts_dir = root / ".trellis" / "scripts"
+        if str(scripts_dir) not in sys.path:
+            sys.path.insert(0, str(scripts_dir))
+        from common.workflow_selection import resolve_workflow_md  # type: ignore[import-not-found]
+
+        return resolve_workflow_md(root, input_data, platform="copilot")
+    except Exception:
+        return root / ".trellis" / "workflow.md"
+
+
 def _build_workflow_toc(workflow_path: Path) -> str:
     """Inject only the compact Phase Index summary for SessionStart."""
     content = read_file(workflow_path)
@@ -503,7 +522,7 @@ Trellis compact SessionStart context. Use it to orient the session; load details
     output.write("\n</current-state>\n\n")
 
     output.write("<trellis-workflow>\n")
-    output.write(_build_workflow_toc(trellis_dir / "workflow.md"))
+    output.write(_build_workflow_toc(_resolve_workflow_md(project_dir, hook_input)))
     output.write("\n</trellis-workflow>\n\n")
 
     output.write("<guidelines>\n")

package/dist/templates/dsh/DSH.md

@@ -1,15 +1,17 @@
 # Trellis on DeepSeek Harness (dsh)
 
-dsh is a **class-2 pull-based** Trellis host: no session-start hook auto-injects
-workflow context, so the agent loads the Trellis skills on demand through its
-skill-loader tool.
+dsh is a **class-2 pull-based** Trellis host. It discovers Trellis skills from
+the project, uses native continuable sub-agents for isolated implementation and
+review roles, and exposes a stable `DSH_SESSION_ID` to every managed shell.
 
-| Capability | Status |
-| --- | --- |
-| Skills (`.agents/skills/trellis-*/SKILL.md`) | Works — dsh discovers this shared root natively |
-| Entry skills (`.dsh/skills/trellis-*/SKILL.md`) | Works — dsh's own project skill root (highest rank) |
-| Context hooks | None — pull-based: skills read `.trellis/` files directly |
-| Sub-agents | None shipped — implement/check/research run inline via the workflow skills |
+| Capability | Without companion plugin | With `dsh-trellis` |
+| --- | --- | --- |
+| Shared and entry skills | Works | Works |
+| Session-scoped active task | Works through verified `DSH_SHELL=1` + `DSH_SESSION_ID`, including nested launches | Managed per-execution identity can forward a distinct child session |
+| Implement/check/research roles | Foreground native sub-agent | Background native sub-agent |
+| Per-turn workflow breadcrumb | Not available | Injected from `workflow.md` |
+| Event-driven child wait | Not available | `trellis_wait` |
+| Utility commands | Not available | `/trellis-status`, `/trellis-finish` |
 
 ## Quick start
 
@@ -20,37 +22,59 @@ dsh web        # or: dsh --profile headless "start a Trellis task for ..."
 
 In dsh:
 
-1. Open a session in the project root and describe the work in natural
-   language. For a new task the agent should load the `trellis-start` skill,
-   which reads the current task state from `.trellis/` and routes to
-   `trellis-brainstorm` (unclear requirements), `trellis-before-dev` (about to
-   write code), `trellis-check` (done coding), or `trellis-update-spec`
-   (learned something worth capturing).
-2. Entry skills are `trellis-start` / `trellis-continue` / `trellis-finish-work`
-   in `.dsh/skills/`. You can also ask for them by name at any time.
-3. Type `/trellis:finish-work` is a slash-command convention from other hosts —
-   dsh has no slash palette, so say "finish the trellis task" instead, and the
-   agent loads `trellis-finish-work`.
+1. Describe the work in natural language and load `trellis-start` when a
+   session needs explicit Trellis bootstrap.
+2. The main session dispatches `trellis-agent-research`,
+   `trellis-agent-implement`, and `trellis-agent-check` through DSH's native
+   `subagent` tool. Each child loads exactly one matching role skill.
+3. Finish through `trellis-finish-work`, which preserves the required order:
+   commit, archive, then journal.
+
+## Companion plugin fallback contract
+
+The Trellis adapter does not install a DSH profile plugin. Before dispatching a
+role, check whether the `trellis_wait` tool is available:
+
+- If available, use DSH's default continuable background mode, continue
+  independent work, then call `trellis_wait` once per dependent child id and
+  consume each native settlement notice before entering the dependent gate.
+- If unavailable, dispatch every child with `run_in_background: false` from the outset
+  so the dependent workflow gate cannot overtake it.
+
+Never replace either path with shell sleep, polling loops, `job_output`, or
+repeated agent-list polling.
+
+## Nested host sessions
+
+DSH inherits ordinary environment variables from the process that launches it.
+If that outer process is already an active Trellis session,
+`TRELLIS_CONTEXT_ID` would otherwise override the inner `DSH_SESSION_ID`.
+DSH rebuilds its complete `DSH_*` namespace for each managed shell, so the beta
+adapter treats `DSH_SHELL=1` together with `DSH_SESSION_ID` as the current DSH
+identity and resolves it before an inherited generic override, even without the
+plugin. The optional plugin additionally contributes a trusted
+`DSH_TRELLIS_CONTEXT_ID` when it must forward a child identity that differs
+from the shell's own session id.
 
 ## File map
 
-- `.agents/skills/` — auto-triggered workflow skills (`trellis-before-dev`,
-  `trellis-brainstorm`, `trellis-check`, `trellis-break-loop`,
-  `trellis-update-spec`) plus the bundled `trellis-meta` /
-  `trellis-spec-bootstrap` / `trellis-session-insight` skills. Byte-identical
-  to Codex / Gemini CLI / Pi / Kimi writes into the same shared root.
-- `.dsh/skills/` — dsh-private entry skills (`trellis-start` /
-  `trellis-continue` / `trellis-finish-work`).
-- `.trellis/` — specs, tasks, workspace memory, and the shared scripts the
-  skills invoke (`get_context.py`, `task.py`, ...).
+- `.agents/skills/` — shared workflow and bundled skills, byte-identical to
+  the other Agent Skills writers.
+- `.dsh/skills/trellis-{start,continue,finish-work}/` — DSH-private entry
+  skills.
+- `.dsh/skills/trellis-agent-{research,implement,check}/` — child-only role
+  skills; implement/check include the pull-based task context prelude.
+- `.dsh/DSH.md` — this operator guide.
+- `.trellis/` — workflow, specs, tasks, workspace journal, and shared scripts.
 
 ## Notes
 
-- Skill scripts pass `--platform dsh` to `get_context.py`; the value is used
-  as a platform-scoped context key.
-- The shipped `minimal` agent preset composes only `bash` +
-  `str_replace_editor`; the default presets include `web_search` and the
-  filesystem/terminal tools the skills assume.
-- dsh has no project-level sub-agent definition surface, so Trellis ships no
-  `trellis-implement` / `trellis-check` / `trellis-research` agent prompts
-  here — the workflow skills run those phases inline in the main session.
+- Generated Python commands use `python3` in source templates and are rendered
+  to the detected Windows launcher during `trellis init` / `trellis update`.
+- Role dispatch prompts start with `Active task: <task path>`. This exact task
+  path is the child's primary context source; children must not guess globally.
+- Each `dsh --profile headless` invocation creates a fresh DSH session. Do not
+  expect an active-task pointer to persist across separate headless calls; keep
+  the workflow in one session or explicitly resume its returned session id.
+- The optional companion plugin is maintained separately at
+  <https://github.com/SajoLuo/dsh-trellis>.

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

@@ -0,0 +1,99 @@
+---
+name: trellis-check
+user-invocable: false
+description: |
+  Child-agent-only quality role for Trellis. Main sessions must not load this
+  skill directly. Reviews code changes against specs and self-fixes issues.
+---
+# Check Agent
+
+You are the Check Agent in the Trellis workflow.
+
+## 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, workflow-state breadcrumbs, 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.
+
+dsh does not auto-inject SessionStart task context. Always pull context as required below.
+
+## Context
+
+Before checking, read:
+- `.trellis/spec/` - Development guidelines
+- Pre-commit checklist for quality standards
+
+## Core Responsibilities
+
+1. **Get code changes** - Use 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, you can modify code directly.
+
+---
+
+## Workflow
+
+### Step 1: Get Changes
+
+```bash
+git diff --name-only  # List changed files
+git diff              # View specific changes
+```
+
+### Step 2: Check Against Specs
+
+Read relevant specs in `.trellis/spec/` to check code:
+
+- Does it follow directory structure conventions
+- Does it follow naming conventions
+- Does it follow code patterns
+- Are there missing types
+- Are there potential bugs
+
+### Step 3: Self-Fix
+
+After finding issues:
+
+1. Fix the issue directly (use edit tool)
+2. Record what was fixed
+3. Continue checking other issues
+
+### Step 4: Run Verification
+
+Run project's lint and typecheck commands to verify changes.
+
+If failed, fix issues and re-run.
+
+If a required command cannot run, is skipped, or still exits non-zero, report
+the quality gate as **blocked** or **failed**. Never label it passed, weaken or
+rewrite acceptance criteria, or substitute an easier command just to advance
+the workflow.
+
+---
+
+## Report Format
+
+```markdown
+## Self-Check Complete
+
+### Files Checked
+
+- list changed files
+
+### Issues Fixed
+
+- what you fixed
+
+### Verification
+
+- Lint / typecheck results
+```

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

@@ -0,0 +1,106 @@
+---
+name: trellis-implement
+user-invocable: false
+description: |
+  Child-agent-only implementation role for Trellis. Main sessions must not
+  load this skill directly. Understands specs and requirements, then
+  implements features. No git commit allowed.
+---
+# Implement Agent
+
+You are the Implement Agent in the Trellis workflow.
+
+## 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, workflow-state breadcrumbs, 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.
+
+dsh does not auto-inject SessionStart task context. Always pull context as required below.
+
+## 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
+
+## 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
+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 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

package/dist/templates/dsh/agents/trellis-research.md

@@ -0,0 +1,134 @@
+---
+name: trellis-research
+user-invocable: false
+description: |
+  Child-agent-only research role for Trellis. Main sessions must not load this
+  skill directly. Finds files, patterns, and technical solutions, and persists
+  every finding to the current task's research/ directory. No code changes
+  outside that directory.
+---
+# Research Agent
+
+You are the Research Agent in the Trellis workflow.
+
+## Core Principle
+
+**You do one thing: find, explain, and PERSIST information.**
+
+Conversations get compacted; files don't. Every research output MUST end up as a file under `{TASK_DIR}/research/`. Returning findings only through the chat reply is a failure - the caller cannot read them next session.
+
+## Core Responsibilities
+
+1. **Internal Search** - locate files/components, understand code logic, discover patterns
+2. **External Search** - library docs, API references, best practices
+3. **Persist** - write each research topic to `{TASK_DIR}/research/<topic>.md`
+4. **Report** - return file paths + one-line summaries to the main agent, not full content
+
+---
+
+## Workflow
+
+### Step 1: Resolve Current Task
+
+Run `python3 ./.trellis/scripts/task.py current --source` to get the active task path. Prefer an `Active task: <path>` line in the dispatch prompt when present. If no active task is set, ask the user where to write output; do NOT guess.
+
+Ensure `{TASK_DIR}/research/` exists before writing findings.
+
+### Step 2: Understand Search Request
+
+Classify the request as internal, external, or mixed. Determine scope and expected output shape.
+
+### Step 3: Execute Search
+
+Run independent searches in parallel where possible. Read relevant source files, specs, and documentation before forming conclusions.
+
+### Step 4: Persist Each Topic
+
+For each distinct research topic, write a markdown file at `{TASK_DIR}/research/<topic-slug>.md` using the File Format below.
+
+### Step 5: Report to Main Agent
+
+Reply with ONLY:
+
+- List of files written, paths relative to repo root
+- One-line summary per file
+- Any critical caveats that the main agent needs to know right now
+
+Do NOT paste full research content into the reply. The files are the contract.
+
+---
+
+## Scope Limits
+
+### Write Allowed
+
+- `{TASK_DIR}/research/*.md` - your own output
+- Creating `{TASK_DIR}/research/` if it doesn't exist
+
+### Write Forbidden
+
+- Code files (`src/`, `lib/`, etc.)
+- Spec files (`.trellis/spec/`) - main agent should use the update-spec skill instead
+- `.trellis/scripts/`, `.trellis/workflow.md`, platform config (`.dsh/`, `.claude/`, `.cursor/`, etc.)
+- Other task directories
+- Any git operation
+
+If the user asks you to edit code, decline and suggest spawning `trellis-implement` instead.
+
+---
+
+## File Format
+
+Each `{TASK_DIR}/research/<topic>.md` should follow:
+
+```markdown
+# Research: <topic>
+
+- Query: <original query>
+- Scope: internal / external / mixed
+- Date: YYYY-MM-DD
+
+## Findings
+
+### Files Found
+
+| File Path | Description |
+|---|---|
+| `src/services/xxx.ts` | Main implementation |
+| `src/types/xxx.ts` | Type definitions |
+
+### Code Patterns
+
+<describe patterns, cite file:line>
+
+### External References
+
+- [Library X docs](url) - <why relevant, version constraints>
+
+### Related Specs
+
+- `.trellis/spec/xxx.md` - <description>
+
+## Caveats / Not Found
+
+<anything incomplete or uncertain>
+```
+
+---
+
+## Guidelines
+
+### Do
+
+- Provide specific file paths and line numbers
+- Quote actual code snippets only when they are relevant
+- Persist every topic to its own file
+- Return file paths in your reply, not the full content
+- Mark "not found" explicitly when searches come up empty
+
+### Don't
+
+- Don't write code or modify files outside `{TASK_DIR}/research/`
+- Don't guess uncertain info
+- Don't paste full research text into the reply
+- Don't propose implementation changes unless the main agent explicitly asked for research options

package/dist/templates/dsh/index.d.ts

@@ -1,21 +1,22 @@
 /**
  * DeepSeek Harness (dsh) template module.
  *
- * dsh is a class-2 pull-based, skills-only platform:
- * - Workflow + bundled skills go to the shared `.agents/skills/` root via
- *   the neutral resolver (byte-identical to Codex/Gemini/Pi/Kimi writes).
+ * dsh is a class-2 pull-based platform:
+ * - Workflow/bundled skills go to the shared `.agents/skills/` root via the
+ *   neutral resolver (byte-identical to Codex/Gemini/Pi/Kimi writes).
  * - User-invocable entry points (`trellis-start` / `trellis-continue` /
- *   `trellis-finish-work`, loaded by the dsh agent through its skill-loader
- *   tool) live under `.dsh/skills/<name>/SKILL.md` — dsh's own highest-rank
- *   project skill root.
+ *   `trellis-finish-work`) and Trellis role prompts live under
+ *   `.dsh/skills/trellis-agent-<role>/SKILL.md`.
  * - Operator guide `.dsh/DSH.md`.
  *
- * dsh has no shipped session-start hook, so `trellis-start` is kept as a
- * user-invocable skill. dsh ships no project-level sub-agent definition
- * surface, so no trellis-implement / trellis-check / trellis-research agent
- * prompts are written; implement/check/research run inline through the
- * workflow skills.
+ * dsh has no project-level hooks/settings file Trellis may write and no
+ * declarative custom sub-agent definitions, so the Trellis agent prompts ship
+ * as skills; the main session dispatches them through the `subagent` tool and
+ * trellis-agent-implement / trellis-agent-check get the pull-based prelude.
  */
+import { type AgentTemplate } from "../template-utils.js";
+/** Source role prompts; the configurator installs collision-free DSH skills. */
+export declare function getAllAgents(): AgentTemplate[];
 /** Operator guide copied to `.dsh/DSH.md`. */
 export declare function getDshGuide(): string;
 //# sourceMappingURL=index.d.ts.map

package/dist/templates/dsh/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/dsh/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,8CAA8C;AAC9C,wBAAgB,WAAW,IAAI,MAAM,CAEpC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/dsh/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAIhF,gFAAgF;AAChF,wBAAgB,YAAY,IAAI,aAAa,EAAE,CAE9C;AAED,8CAA8C;AAC9C,wBAAgB,WAAW,IAAI,MAAM,CAEpC"}

package/dist/templates/dsh/index.js

@@ -1,23 +1,25 @@
 /**
  * DeepSeek Harness (dsh) template module.
  *
- * dsh is a class-2 pull-based, skills-only platform:
- * - Workflow + bundled skills go to the shared `.agents/skills/` root via
- *   the neutral resolver (byte-identical to Codex/Gemini/Pi/Kimi writes).
+ * dsh is a class-2 pull-based platform:
+ * - Workflow/bundled skills go to the shared `.agents/skills/` root via the
+ *   neutral resolver (byte-identical to Codex/Gemini/Pi/Kimi writes).
  * - User-invocable entry points (`trellis-start` / `trellis-continue` /
- *   `trellis-finish-work`, loaded by the dsh agent through its skill-loader
- *   tool) live under `.dsh/skills/<name>/SKILL.md` — dsh's own highest-rank
- *   project skill root.
+ *   `trellis-finish-work`) and Trellis role prompts live under
+ *   `.dsh/skills/trellis-agent-<role>/SKILL.md`.
  * - Operator guide `.dsh/DSH.md`.
  *
- * dsh has no shipped session-start hook, so `trellis-start` is kept as a
- * user-invocable skill. dsh ships no project-level sub-agent definition
- * surface, so no trellis-implement / trellis-check / trellis-research agent
- * prompts are written; implement/check/research run inline through the
- * workflow skills.
+ * dsh has no project-level hooks/settings file Trellis may write and no
+ * declarative custom sub-agent definitions, so the Trellis agent prompts ship
+ * as skills; the main session dispatches them through the `subagent` tool and
+ * trellis-agent-implement / trellis-agent-check get the pull-based prelude.
  */
 import { createTemplateReader } from "../template-utils.js";
-const { readTemplate } = createTemplateReader(import.meta.url);
+const { listMdAgents, readTemplate } = createTemplateReader(import.meta.url);
+/** Source role prompts; the configurator installs collision-free DSH skills. */
+export function getAllAgents() {
+    return listMdAgents();
+}
 /** Operator guide copied to `.dsh/DSH.md`. */
 export function getDshGuide() {
     return readTemplate("DSH.md");

package/dist/templates/dsh/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/dsh/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,EAAE,YAAY,EAAE,GAAG,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/D,8CAA8C;AAC9C,MAAM,UAAU,WAAW;IACzB,OAAO,YAAY,CAAC,QAAQ,CAAC,CAAC;AAChC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/dsh/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,oBAAoB,EAAsB,MAAM,sBAAsB,CAAC;AAEhF,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE7E,gFAAgF;AAChF,MAAM,UAAU,YAAY;IAC1B,OAAO,YAAY,EAAE,CAAC;AACxB,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,WAAW;IACzB,OAAO,YAAY,CAAC,QAAQ,CAAC,CAAC;AAChC,CAAC"}