@mindfoldhq/trellis 0.5.0-beta.16 → 0.5.0-beta.18

package/dist/templates/common/bundled-skills/trellis-meta/references/platform-files/skills-and-commands.md

@@ -0,0 +1,83 @@
+# Skills, Commands, Prompts, And Workflows
+
+Skills and commands are textual entry points for user interaction with Trellis. Different platforms use different names, but their core purpose is the same: tell the AI how to enter the Trellis flow when the user expresses a certain intent.
+
+## Conceptual Differences
+
+| Type | Trigger mode | Best for |
+| --- | --- | --- |
+| skill | AI auto-match or explicit user mention | Long-term capabilities, workflow rules, modification guides. |
+| command | Explicit user invocation | Clear operation entry points such as continue and finish-work. |
+| prompt | Explicit user invocation or platform selection | Similar to command, but in a platform prompt format. |
+| workflow | Explicit user selection or platform auto-match | Guides the main session when no sub-agent/hook exists. |
+
+Trellis workflow skills usually share one semantic set: brainstorm, before-dev, check, update-spec, break-loop. Multi-file built-in skills such as `trellis-meta` use layered references.
+
+## Common Paths
+
+| Platform | Common entries |
+| --- | --- |
+| Claude Code | `.claude/skills/`, `.claude/commands/` |
+| Cursor | `.cursor/skills/`, `.cursor/commands/` |
+| OpenCode | `.opencode/skills/`, `.opencode/commands/` |
+| Codex | `.agents/skills/`, `.codex/skills/` |
+| Kilo | `.kilocode/skills/`, `.kilocode/workflows/` |
+| Kiro | `.kiro/skills/` |
+| Gemini CLI | `.gemini/skills/`, `.gemini/commands/` |
+| Antigravity | `.agent/skills/`, `.agent/workflows/` |
+| Windsurf | `.windsurf/skills/`, `.windsurf/workflows/` |
+| Qoder | `.qoder/skills/`, `.qoder/commands/` |
+| CodeBuddy | `.codebuddy/skills/`, `.codebuddy/commands/` |
+| GitHub Copilot | `.github/skills/`, `.github/prompts/` |
+| Factory Droid | `.factory/skills/`, `.factory/commands/` |
+| Pi Agent | `.pi/skills/` |
+
+In a user project, use the files actually generated by init as authoritative.
+
+## Skill Structure
+
+A common skill is a directory:
+
+```text
+trellis-meta/
+├── SKILL.md
+└── references/
+```
+
+`SKILL.md` should tell the AI:
+
+- When to use this skill.
+- Which reference to read first for the current task.
+- What not to do.
+
+References hold longer explanations so the entry file does not contain everything.
+
+## Command/Prompt/Workflow Structure
+
+Commands, prompts, and workflows are usually single files. Their content should include:
+
+- When to use it.
+- Which `.trellis/` files to read.
+- Which scripts to run.
+- How to report after completion.
+
+They should not store task state; task state belongs in `.trellis/tasks/` and `.trellis/.runtime/`.
+
+## Local Change Scenarios
+
+| User need | Edit location |
+| --- | --- |
+| Change AI auto-trigger rules | The corresponding skill's frontmatter description. |
+| Change user command behavior | The corresponding command/prompt/workflow file. |
+| Add a project-local skill | Platform skill directory, or shared `.agents/skills/`. |
+| Let multiple platforms share one capability | Write equivalent skills in each platform skill directory, or use the `.agents/skills/` shared layer on platforms that support it. |
+| Change finish/continue entry points | Platform commands/prompts/workflows. |
+
+## Modification Principles
+
+1. **Keep entry files short; references carry long content**. This matters especially for multi-file skills like `trellis-meta`.
+2. **Make trigger descriptions specific**. A description that is too broad can mis-trigger; one that is too narrow may not trigger.
+3. **Keep the same semantics consistent across platforms**. File formats can differ, but behavior descriptions should match.
+4. **Put project-specific capabilities in local skills**. Do not put team-private flows into public `trellis-meta`.
+
+If the user only wants local AI to know one more project rule, usually create a project-local skill or update `.trellis/spec/` instead of changing a Trellis built-in workflow skill.

package/dist/templates/common/commands/finish-work.md

@@ -1,28 +1,48 @@
 # Finish Work
 
-Wrap up the current session.
+Wrap up the current session: archive the active task (and any other completed-but-unarchived tasks the user wants to clean up) and record the session journal. Code commits are NOT done here — those happen in workflow Phase 3.4 before you invoke this command.
 
-## Step 1: Quality Gate
+## Step 1: Survey current state
 
-`trellis-check` should have already run in Phase 3. If not, trigger it now and do not proceed until lint, type-check, tests, and spec compliance pass.
+```bash
+{{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode record
+```
+
+This prints:
+
+- **My active tasks** — review whether any besides the current one are actually done (code merged, AC met) and should be archived this round.
+- **Git status** — quick visual on what's dirty.
+- **Recent commits** — you'll need their hashes in Step 4 for `--commit`.
 
-## Step 2: Remind User to Commit
+If `--mode record` surfaces other completed tasks not tied to the current session, surface them to the user with a one-shot confirmation: "These N tasks look done — archive them too in this round? [y/N]". Default is no; the current active task is always archived in Step 3 regardless.
 
-If there are uncommitted changes:
+## Step 2: Sanity check — working tree must be clean
 
-> "Please review the changes and commit when ready."
+Run:
+
+```bash
+git status --porcelain
+```
 
-Do NOT run `git commit` — the human commits after testing.
+Filter out paths under `.trellis/workspace/` and `.trellis/tasks/` — those are managed by `add_session.py` and `task.py archive` auto-commits and will appear dirty as part of this skill's own work.
 
-## Step 3: Record Session (after commit)
+If anything else is dirty (any path outside those two prefixes), **stop and bail out** with:
 
-Archive finished tasks (judge by work status, not the `status` field):
+> "Working tree has uncommitted code changes. Return to workflow Phase 3.4 to commit them before running `{{CMD_REF:finish-work}}`."
+
+Do NOT run `git commit` here. Do NOT prompt the user to commit. The user goes back to Phase 3.4 and the AI drives the batched commit there.
+
+## Step 3: Archive task(s)
 
 ```bash
 {{PYTHON_CMD}} ./.trellis/scripts/task.py archive <task-name>
 ```
 
-Append a session entry (auto-handles journal rotation, line count, index update):
+At minimum: the current active task (if any). Plus any extra tasks the user confirmed in Step 1. Each archive produces a `chore(task): archive ...` commit via the script's auto-commit.
+
+If there is no active task and the user did not confirm any cleanup archives, skip this step.
+
+## Step 4: Record session journal
 
 ```bash
 {{PYTHON_CMD}} ./.trellis/scripts/add_session.py \
@@ -30,3 +50,7 @@ Append a session entry (auto-handles journal rotation, line count, index update)
   --commit "hash1,hash2" \
   --summary "Brief summary"
 ```
+
+Use the work-commit hashes produced in Phase 3.4 (visible in Step 1's `Recent commits` list, or via `git log --oneline`) for `--commit`. Do not include the archive commit hashes from Step 3. This produces a `chore: record journal` commit.
+
+Final git log order: `<work commits from 3.4>` → `chore(task): archive ...` (one or more) → `chore: record journal`.

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

@@ -6,8 +6,9 @@
  *
  * Directory structure:
  *   common/
- *   ├── commands/    # Templates that stay as slash commands (start, finish-work)
- *   └── skills/      # Templates that become auto-triggered skills
+ *   ├── commands/        # Templates that stay as slash commands
+ *   ├── skills/          # Single-file templates that become auto-triggered skills
+ *   └── bundled-skills/  # Multi-file built-in skills with references/assets
  */
 export interface CommonTemplate {
     /** Template name without extension (e.g., "start", "before-dev") */
@@ -15,6 +16,18 @@ export interface CommonTemplate {
     /** Raw content with {{placeholders}} — must be resolved before writing */
     content: string;
 }
+export interface CommonBundledSkillFile {
+    /** POSIX path relative to the skill directory, e.g. "references/core.md" */
+    relativePath: string;
+    /** Raw content with {{placeholders}} — must be resolved before writing */
+    content: string;
+}
+export interface CommonBundledSkill {
+    /** Skill directory name, e.g. "trellis-meta" */
+    name: string;
+    /** Files that must be written under the skill directory */
+    files: CommonBundledSkillFile[];
+}
 /**
  * Get all command templates (stay as slash commands on all platforms).
  * Results are cached after first call.
@@ -25,4 +38,11 @@ export declare function getCommandTemplates(): CommonTemplate[];
  * Results are cached after first call.
  */
 export declare function getSkillTemplates(): CommonTemplate[];
+/**
+ * Get all multi-file built-in skills.
+ *
+ * These are copied as complete skill directories so references and assets stay
+ * lazy-loadable instead of being flattened into one oversized SKILL.md.
+ */
+export declare function getBundledSkillTemplates(): CommonBundledSkill[];
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/common/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAuBH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,EAAE,CAMtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,EAAE,CAMpD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/common/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAuBH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,KAAK,EAAE,sBAAsB,EAAE,CAAC;CACjC;AAOD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,EAAE,CAMtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,EAAE,CAMpD;AAuCD;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,kBAAkB,EAAE,CAM/D"}

package/dist/templates/common/index.js

@@ -6,11 +6,12 @@
  *
  * Directory structure:
  *   common/
- *   ├── commands/    # Templates that stay as slash commands (start, finish-work)
- *   └── skills/      # Templates that become auto-triggered skills
+ *   ├── commands/        # Templates that stay as slash commands
+ *   ├── skills/          # Single-file templates that become auto-triggered skills
+ *   └── bundled-skills/  # Multi-file built-in skills with references/assets
  */
-import { readdirSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -30,6 +31,7 @@ function listMarkdownFiles(dir) {
 // Cached results — files don't change during a CLI run
 let cachedCommands;
 let cachedSkills;
+let cachedBundledSkills;
 /**
  * Get all command templates (stay as slash commands on all platforms).
  * Results are cached after first call.
@@ -52,4 +54,51 @@ export function getSkillTemplates() {
     }));
     return cachedSkills;
 }
+function listDirectories(dir) {
+    try {
+        return readdirSync(join(__dirname, dir))
+            .filter((entry) => statSync(join(__dirname, dir, entry)).isDirectory())
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function toPosixRelativePath(root, filePath) {
+    return relative(root, filePath).split(sep).join("/");
+}
+function listBundledSkillFiles(skillDir) {
+    const root = join(__dirname, "bundled-skills", skillDir);
+    const files = [];
+    function walk(dir) {
+        for (const entry of readdirSync(dir)) {
+            const fullPath = join(dir, entry);
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                walk(fullPath);
+            }
+            else {
+                files.push({
+                    relativePath: toPosixRelativePath(root, fullPath),
+                    content: readFileSync(fullPath, "utf-8"),
+                });
+            }
+        }
+    }
+    walk(root);
+    return files.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+}
+/**
+ * Get all multi-file built-in skills.
+ *
+ * These are copied as complete skill directories so references and assets stay
+ * lazy-loadable instead of being flattened into one oversized SKILL.md.
+ */
+export function getBundledSkillTemplates() {
+    cachedBundledSkills ??= listDirectories("bundled-skills").map((name) => ({
+        name,
+        files: listBundledSkillFiles(name),
+    }));
+    return cachedBundledSkills;
+}
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/common/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,SAAS,YAAY,CAAC,YAAoB;IACxC,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,iBAAiB,CAAC,GAAW;IACpC,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;aACrC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;aAChC,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AASD,uDAAuD;AACvD,IAAI,cAA4C,CAAC;AACjD,IAAI,YAA0C,CAAC;AAE/C;;;GAGG;AACH,MAAM,UAAU,mBAAmB;IACjC,cAAc,KAAK,iBAAiB,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC9D,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;QAC/B,OAAO,EAAE,YAAY,CAAC,YAAY,IAAI,EAAE,CAAC;KAC1C,CAAC,CAAC,CAAC;IACJ,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,YAAY,KAAK,iBAAiB,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1D,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;QAC/B,OAAO,EAAE,YAAY,CAAC,UAAU,IAAI,EAAE,CAAC;KACxC,CAAC,CAAC,CAAC;IACJ,OAAO,YAAY,CAAC;AACtB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/common/index.ts"],"names":[],"mappings":"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"}

package/dist/templates/common/skills/brainstorm.md

@@ -57,6 +57,9 @@ Before any Q&A, ensure a task exists. If none exists, create one immediately.
 TASK_DIR=$(python3 ./.trellis/scripts/task.py create "brainstorm: <short goal>" --slug <auto>)
 ```
 
+Use a slug without a date prefix. `task.py create` adds the `MM-DD-`
+directory prefix automatically.
+
 Create/seed `prd.md` immediately with what you know:
 
 ```markdown

package/dist/templates/copilot/prompts/finish-work.prompt.md

@@ -1,157 +1,89 @@
 ---
-description: "Trellis Copilot prompt: Finish Work - Pre-Commit Checklist"
+description: "Trellis Copilot prompt: Finish Work — survey + archive task + record session journal"
 ---
 
-# Finish Work - Pre-Commit Checklist
+# Finish Work
 
-Before submitting or committing, use this checklist to ensure work completeness.
+Wrap up the current session: archive the active task (and any other completed-but-unarchived tasks the user wants to clean up) and record the session journal. Code commits are NOT done here — those happen in workflow Phase 3.4 before you invoke this prompt.
 
-**Timing**: After code is written and tested, before commit
+**Timing**: After Phase 3.4 (Commit changes) — when the working tree is already clean.
 
 ---
 
-## Checklist
-
-### 1. Code Quality
+## Step 1: Survey current state
 
 ```bash
-# Must pass
-pnpm lint
-pnpm type-check
-pnpm test
+python3 ./.trellis/scripts/get_context.py --mode record
 ```
 
-- [ ] `pnpm lint` passes with 0 errors?
-- [ ] `pnpm type-check` passes with no type errors?
-- [ ] Tests pass?
-- [ ] No `console.log` statements (use logger)?
-- [ ] No non-null assertions (the `x!` operator)?
-- [ ] No `any` types?
-
-### 1.5. Test Coverage
-
-Check if your change needs new or updated tests (see `.trellis/spec/unit-test/conventions.md`):
-
-- [ ] New pure function �?unit test added?
-- [ ] Bug fix �?regression test added in `test/regression.test.ts`?
-- [ ] Changed init/update behavior �?integration test added/updated?
-- [ ] No logic change (text/data only) �?no test needed
-
-### 2. Code-Spec Sync
-
-**Code-Spec Docs**:
-- [ ] Does `.trellis/spec/backend/` need updates?
-  - New patterns, new modules, new conventions
-- [ ] Does `.trellis/spec/frontend/` need updates?
-  - New components, new hooks, new patterns
-- [ ] Does `.trellis/spec/guides/` need updates?
-  - New cross-layer flows, lessons from bugs
-
-**Key Question**: 
-> "If I fixed a bug or discovered something non-obvious, should I document it so future me (or others) won't hit the same issue?"
-
-If YES -> Update the relevant code-spec doc.
-
-### 2.5. Code-Spec Hard Block (Infra/Cross-Layer)
-
-If this change touches infra or cross-layer contracts, this is a blocking checklist:
-
-- [ ] Spec content is executable (real signatures/contracts), not principle-only text
-- [ ] Includes file path + command/API name + payload field names
-- [ ] Includes validation and error matrix
-- [ ] Includes Good/Base/Bad cases
-- [ ] Includes required tests and assertion points
+This prints:
 
-**Block Rule**:
-In pipeline mode, the finish agent will automatically detect and execute spec updates when gaps are found.
-If running this checklist manually, ensure spec sync is complete before committing �?run `/` if needed.
+- **My active tasks** — review whether any besides the current one are actually done (code merged, AC met) and should be archived this round.
+- **Git status** — quick visual on what's dirty.
+- **Recent commits** — you'll need their hashes in Step 4 for `--commit`.
 
-### 3. API Changes
+If `--mode record` surfaces other completed tasks not tied to the current session, surface them to the user with a one-shot confirmation: "These N tasks look done — archive them too in this round? [y/N]". Default is no; the current active task is always archived in Step 3 regardless.
 
-If you modified API endpoints:
+## Step 2: Sanity check — working tree must be clean
 
-- [ ] Input schema updated?
-- [ ] Output schema updated?
-- [ ] API documentation updated?
-- [ ] Client code updated to match?
+Run:
 
-### 4. Database Changes
+```bash
+git status --porcelain
+```
 
-If you modified database schema:
+Filter out paths under `.trellis/workspace/` and `.trellis/tasks/` — those are managed by `add_session.py` and `task.py archive` auto-commits and will appear dirty as part of this prompt's own work.
 
-- [ ] Migration file created?
-- [ ] Schema file updated?
-- [ ] Related queries updated?
-- [ ] Seed data updated (if applicable)?
+If anything else is dirty (any path outside those two prefixes), **stop and bail out** with:
 
-### 5. Cross-Layer Verification
+> "Working tree has uncommitted code changes. Return to workflow Phase 3.4 to commit them before running `/finish-work`."
 
-If the change spans multiple layers:
+Do NOT run `git commit` here. Do NOT prompt the user to commit. The user goes back to Phase 3.4 and the AI drives the batched commit there.
 
-- [ ] Data flows correctly through all layers?
-- [ ] Error handling works at each boundary?
-- [ ] Types are consistent across layers?
-- [ ] Loading states handled?
+## Step 3: Archive task(s)
 
-### 6. Manual Testing
+```bash
+python3 ./.trellis/scripts/task.py archive <task-name>
+```
 
-- [ ] Feature works in browser/app?
-- [ ] Edge cases tested?
-- [ ] Error states tested?
-- [ ] Works after page refresh?
+At minimum: the current active task (if any). Plus any extra tasks the user confirmed in Step 1. Each archive produces a `chore(task): archive ...` commit via the script's auto-commit.
 
----
+If there is no active task and the user did not confirm any cleanup archives, skip this step.
 
-## Quick Check Flow
+## Step 4: Record session journal
 
 ```bash
-# 1. Code checks
-pnpm lint && pnpm type-check
-
-# 2. View changes
-git status
-git diff --name-only
-
-# 3. Based on changed files, check relevant items above
+python3 ./.trellis/scripts/add_session.py \
+  --title "Session Title" \
+  --commit "hash1,hash2" \
+  --summary "Brief summary"
 ```
 
----
-
-## Common Oversights
+Use the work-commit hashes produced in Phase 3.4 (visible in Step 1's `Recent commits` list, or via `git log --oneline`) for `--commit`. Do not include the archive commit hashes from Step 3. This produces a `chore: record journal` commit.
 
-| Oversight | Consequence | Check |
-|-----------|-------------|-------|
-| Code-spec docs not updated | Others don't know the change | Check .trellis/spec/ |
-| Spec text is abstract only | Easy regressions in infra/cross-layer changes | Require signature/contract/matrix/cases/tests |
-| Migration not created | Schema out of sync | Check db/migrations/ |
-| Types not synced | Runtime errors | Check shared types |
-| Tests not updated | False confidence | Run full test suite |
-| Console.log left in | Noisy production logs | Search for console.log |
+Final git log order: `<work commits from 3.4>` → `chore(task): archive ...` (one or more) → `chore: record journal`.
 
 ---
 
 ## Relationship to Other Commands
 
 ```
-Development Flow:
-  Write code -> Test -> / -> git commit -> /
-                          |                              |
-                   Ensure completeness              Record progress
-                   
+Development Flow (workflow.md Phase 3):
+  3.1 Quality verification
+  3.2 Debug retrospective (on demand)
+  3.3 Spec update
+  3.4 Commit changes  -> AI drafts batched commits, user confirms
+  3.5 Wrap-up         -> /finish-work (this prompt: survey + archive + journal)
+
 Debug Flow:
-  Hit bug -> Fix -> / -> Knowledge capture
-                       |
-                  Deep analysis
+  Hit bug -> Fix -> /break-loop -> Knowledge capture
 ```
 
-- `/` - Check work completeness (this command)
-- `/` - Record session and commits
-- `/` - Deep analysis after debugging
+- `/finish-work` — survey + archive + record session (this prompt)
+- `/break-loop` — deep analysis after debugging
 
 ---
 
 ## Core Principle
 
-> **Delivery includes not just code, but also documentation, verification, and knowledge capture.**
-
-Complete work = Code + Docs + Tests + Verification
+> **Finish-work is pure bookkeeping.** Code is already committed before this runs. If the working tree is dirty, this prompt refuses to proceed.

package/dist/templates/markdown/agents.md

@@ -16,6 +16,14 @@ If you're using Codex or another agent-capable tool, additional project-scoped h
 - `.agents/skills/` — reusable Trellis skills
 - `.codex/agents/` — optional custom subagents
 
+## Subagents
+
+- ALWAYS wait for all subagents to complete before yielding.
+- Spawn subagents automatically when:
+  - Parallelizable work (e.g., install + verify, npm test + typecheck, multiple tasks from plan)
+  - Long-running or blocking tasks where a worker can run independently.
+  - Isolation for risky changes or checks
+
 Managed by Trellis. Edits outside this block are preserved; edits inside may be overwritten by a future `trellis update`.
 
 <!-- TRELLIS:END -->

package/dist/templates/opencode/plugins/inject-subagent-context.js

@@ -1,3 +1,4 @@
+/* global process */
 /**
  * Trellis Context Injection Plugin
  *
@@ -259,6 +260,19 @@ function shellQuote(value) {
   return `'${String(value).replace(/'/g, "'\\''")}'`
 }
 
+function powershellQuote(value) {
+  return `'${String(value).replace(/'/g, "''")}'`
+}
+
+function buildTrellisContextPrefix(contextKey, hostPlatform = process.platform) {
+  if (hostPlatform === "win32") {
+    // OpenCode's Windows Bash tool runs through PowerShell, not a POSIX shell.
+    return `$env:TRELLIS_CONTEXT_ID = ${powershellQuote(contextKey)}; `
+  }
+
+  return `export TRELLIS_CONTEXT_ID=${shellQuote(contextKey)}; `
+}
+
 function getBashCommandKey(args) {
   if (!args || typeof args !== "object") return null
   if (typeof args.command === "string") return "command"
@@ -271,7 +285,8 @@ function commandStartsWithTrellisContext(command) {
   return (
     /^TRELLIS_CONTEXT_ID\s*=/.test(firstCommand) ||
     /^export\s+TRELLIS_CONTEXT_ID\s*=/.test(firstCommand) ||
-    /^env\s+(?:[^\s=]+\s+)*TRELLIS_CONTEXT_ID\s*=/.test(firstCommand)
+    /^env\s+(?:[^\s=]+\s+)*TRELLIS_CONTEXT_ID\s*=/.test(firstCommand) ||
+    /^\$env:TRELLIS_CONTEXT_ID\s*=/i.test(firstCommand)
   )
 }
 
@@ -279,7 +294,7 @@ function commandStartsWithTrellisContext(command) {
  * OpenCode TUI may not expose OPENCODE_RUN_ID to Bash. The plugin hook still
  * receives session identity, so inject it into Bash commands before execution.
  */
-function injectTrellisContextIntoBash(ctx, input, output) {
+function injectTrellisContextIntoBash(ctx, input, output, hostPlatform) {
   const args = output?.args
   const commandKey = getBashCommandKey(args)
   if (!commandKey) return false
@@ -291,7 +306,7 @@ function injectTrellisContextIntoBash(ctx, input, output) {
   const contextKey = ctx.getContextKey(input)
   if (!contextKey) return false
 
-  args[commandKey] = `export TRELLIS_CONTEXT_ID=${shellQuote(contextKey)}; ${command}`
+  args[commandKey] = `${buildTrellisContextPrefix(contextKey, hostPlatform)}${command}`
   return true
 }
 
@@ -300,7 +315,7 @@ function injectTrellisContextIntoBash(ctx, input, output) {
 // (packages/opencode/src/plugin/index.ts — `for ([_, fn] of Object.entries(mod)) await fn(input)`);
 // the previous `{ id, server }` object shape failed with
 // `TypeError: fn is not a function` in 1.2.x.
-export default async ({ directory }) => {
+export default async ({ directory, platform: hostPlatform = process.platform }) => {
   const ctx = new TrellisContext(directory)
   debugLog("inject", "Plugin loaded, directory:", directory)
 
@@ -311,7 +326,7 @@ export default async ({ directory }) => {
 
           const toolName = input?.tool?.toLowerCase()
           if (toolName === "bash") {
-            if (injectTrellisContextIntoBash(ctx, input, output)) {
+            if (injectTrellisContextIntoBash(ctx, input, output, hostPlatform)) {
               debugLog("inject", "Injected TRELLIS_CONTEXT_ID into Bash command")
             }
             return

package/dist/templates/opencode/plugins/inject-workflow-state.js

@@ -81,7 +81,12 @@ const FALLBACK_BREADCRUMBS = {
     "Per-turn only; does not carry forward; do NOT invent an override the " +
     "user did not say.",
   completed:
-    "User commits changes; then run task.py archive.",
+    "Code committed via Phase 3.4; run `/trellis:finish-work` to wrap up " +
+    "(archive task + record session).\n" +
+    "If you reach this state with uncommitted code, return to Phase 3.4 " +
+    "first — `/finish-work` refuses to run on a dirty working tree.\n" +
+    "`task.py archive` deletes runtime session files that point at the " +
+    "archived task.",
 }
 
 /**