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

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

@@ -0,0 +1,79 @@
+# Agents
+
+Trellis agent files define specialized roles. Common Trellis agents in a user project are:
+
+- `trellis-research`
+- `trellis-implement`
+- `trellis-check`
+
+File locations and formats differ by platform, but responsibility boundaries should stay consistent.
+
+## Agent Responsibilities
+
+| Agent | Responsibility |
+| --- | --- |
+| `trellis-research` | Investigate the question and write findings into the current task's `research/`. |
+| `trellis-implement` | Implement against `prd.md`, `info.md`, `implement.jsonl`, and related spec/research. |
+| `trellis-check` | Review changes, fix discovered issues, and run necessary checks. |
+
+Agent files should not become generic chat prompts. They should define input sources, write boundaries, whether code may be changed, and how results are reported.
+
+## Common Paths
+
+| Platform | Agent path |
+| --- | --- |
+| Claude Code | `.claude/agents/trellis-*.md` |
+| Cursor | `.cursor/agents/trellis-*.md` |
+| OpenCode | `.opencode/agents/trellis-*.md` |
+| Codex | `.codex/agents/trellis-*.toml` |
+| Kiro | `.kiro/agents/trellis-*.json` |
+| Gemini CLI | `.gemini/agents/trellis-*.md` |
+| Qoder | `.qoder/agents/trellis-*.md` |
+| CodeBuddy | `.codebuddy/agents/trellis-*.md` |
+| Factory Droid | `.factory/droids/trellis-*.md` |
+| Pi Agent | `.pi/agents/trellis-*.md` |
+
+GitHub Copilot agent/prompt support is provided by a combination of directories such as `.github/agents/`, `.github/prompts/`, and `.github/skills/`; inspect the files actually generated in the user project.
+
+Main-session workflow platforms such as Kilo, Antigravity, and Windsurf may not have Trellis sub-agent files. They usually rely on workflows/skills to guide the main session.
+
+## Two Context Loading Modes
+
+### hook push
+
+The platform hook injects task context before the agent starts. The agent file itself can focus more on responsibilities and boundaries.
+
+Common on platforms that support agent hooks.
+
+### agent pull
+
+The agent file instructs the agent to read after startup:
+
+- `python3 ./.trellis/scripts/task.py current --source`
+- current task `prd.md`
+- `info.md`
+- `implement.jsonl` or `check.jsonl`
+- spec/research files referenced by JSONL
+
+This mode fits platforms whose hooks cannot reliably rewrite sub-agent prompts.
+
+## Local Change Scenarios
+
+| User need | Edit location |
+| --- | --- |
+| Implement agent must follow extra restrictions | The platform's `trellis-implement` agent file. |
+| Check agent must run project-specific commands | `trellis-check` agent file, and `.trellis/spec/` if needed. |
+| Research agent must output a fixed format | `trellis-research` agent file. |
+| Agent cannot read task context | Agent prelude or `inject-subagent-context` hook. |
+| Add a project-specific agent | Platform agent directory + related workflow/command/skill entry point. |
+
+## Modification Principles
+
+1. **Keep responsibilities single-purpose**. Do not mix research, implement, and check responsibilities into one agent.
+2. **Specify the read order**. Agents must know to start from the active task and then find the PRD and JSONL.
+3. **Specify write boundaries**. Research usually only writes `research/`; implement can write code; check can fix issues.
+4. **Keep semantics synchronized in multi-platform projects**. If the user configured Claude, Codex, and Cursor together, decide whether changes to one platform's agent also need to be applied to others.
+
+## Do Not Default To Editing Upstream Templates
+
+Local AI should default to modifying platform agent files inside the user project. Discuss upstream template source only when the user explicitly wants to contribute the change back to Trellis.

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

@@ -0,0 +1,69 @@
+# Hooks And Settings
+
+Hooks/settings are the entry layer that connects a platform to Trellis. They decide which scripts, plugins, or extensions a platform runs for which events.
+
+## Settings Responsibilities
+
+settings/config files usually register:
+
+- session-start hook: injects a Trellis overview when a new session starts or context resets.
+- workflow-state hook: injects the next-action hint for the current state on each user input.
+- sub-agent context hook: injects task context when implementation/check/research agents start.
+- shell/session bridge: lets shell commands see the same Trellis session identity.
+- platform plugin or extension entry points.
+
+Common files:
+
+| Platform | settings/config |
+| --- | --- |
+| Claude Code | `.claude/settings.json` |
+| Cursor | `.cursor/hooks.json` |
+| Codex | `.codex/hooks.json`, `.codex/config.toml` |
+| OpenCode | `.opencode/package.json`, `.opencode/plugins/*` |
+| Kiro | `.kiro/hooks/` + platform config |
+| Gemini CLI | `.gemini/settings.json` |
+| Qoder | `.qoder/settings.json` |
+| CodeBuddy | `.codebuddy/settings.json` |
+| GitHub Copilot | `.github/copilot/hooks.json` |
+| Factory Droid | `.factory/settings.json` |
+| Pi Agent | `.pi/settings.json`, `.pi/extensions/trellis/` |
+
+Whether these files exist in a project depends on which `trellis init --<platform>` flags the user ran.
+
+## Hook Script Types
+
+| Script | Purpose |
+| --- | --- |
+| `session-start.py` | Generates session-start context. |
+| `inject-workflow-state.py` | Injects the next-action hint based on active task status. |
+| `inject-subagent-context.py` | Injects PRD, JSONL context, and related spec/research into sub-agents. |
+| `inject-shell-session-context.py` | Lets shell commands inherit Trellis session identity. |
+
+Not every platform has every hook. Do not copy files from another platform just because a platform lacks a hook; first confirm whether that platform supports the corresponding event.
+
+## Local Change Scenarios
+
+| User need | Edit location |
+| --- | --- |
+| AI should see more/less context in a new session | Platform `session-start` hook. |
+| Per-turn hint policy should change | State blocks in `.trellis/workflow.md` + `inject-workflow-state` hook. |
+| Sub-agent cannot read PRD/spec | `inject-subagent-context` hook or agent prelude. |
+| `task.py current` in shell has no active task | Shell/session bridge hook or platform environment variable configuration. |
+| Disable an automatic injection | The corresponding hook registration in settings/config. |
+
+## Modification Principles
+
+1. **Settings wire things up; hooks define behavior**. If only the hook changes, the platform may never call it. If only settings change, behavior may not change.
+2. **Confirm platform event names first**. Different platforms use different names for SessionStart, UserPromptSubmit, AgentSpawn, shell execution, and similar events.
+3. **Hooks read local `.trellis/`, not upstream source**. `.trellis/scripts/` and `.trellis/workflow.md` in the user project are the default targets.
+4. **Errors must be visible**. Hook failures should tell the user what was not injected instead of silently leaving the AI without context.
+
+## Troubleshooting Path
+
+If the user says "AI did not read Trellis state":
+
+1. Check whether the platform settings register the hook.
+2. Check whether the hook file exists.
+3. Manually run the `.trellis/scripts/get_context.py` or `task.py current --source` command that the hook depends on.
+4. Check whether active task state exists in `.trellis/.runtime/sessions/`.
+5. Check whether the platform shell passes session identity.

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

@@ -0,0 +1,59 @@
+# Platform Files Overview
+
+Trellis connects the same local architecture to different AI tools. `.trellis/` stores the shared runtime; platform directories store adapter files that define how each AI tool enters Trellis.
+
+When a local AI modifies Trellis, it should distinguish two file categories first:
+
+- **Shared files**: `.trellis/workflow.md`, `.trellis/tasks/`, `.trellis/spec/`, `.trellis/scripts/`.
+- **Platform files**: `.claude/`, `.codex/`, `.cursor/`, `.opencode/`, `.kiro/`, `.gemini/`, `.qoder/`, `.codebuddy/`, `.github/`, `.factory/`, `.pi/`, `.kilocode/`, `.agent/`, `.windsurf/`, and similar directories.
+
+Platform files do not store business state. They let the corresponding AI tool read Trellis state, call Trellis scripts, and load Trellis skills/agents/hooks.
+
+## Platform File Categories
+
+| Category | Common paths | Purpose |
+| --- | --- | --- |
+| settings/config | `.claude/settings.json`, `.codex/hooks.json`, `.qoder/settings.json` | Register hooks, plugins, extensions, or platform behavior. |
+| hooks/plugins/extensions | `.claude/hooks/`, `.opencode/plugins/`, `.pi/extensions/` | Inject context at session start, user input, agent startup, shell execution, and similar events. |
+| agents | `.claude/agents/`, `.codex/agents/`, `.kiro/agents/` | Define `trellis-research`, `trellis-implement`, and `trellis-check`. |
+| skills | `.claude/skills/`, `.agents/skills/`, `.qoder/skills/` | Capability descriptions that auto-trigger or can be read on demand. |
+| commands/prompts/workflows | `.cursor/commands/`, `.github/prompts/`, `.windsurf/workflows/` | Entry points explicitly invoked by the user. |
+
+## Three Platform Integration Modes
+
+### 1. Hook / Extension Driven
+
+These platforms can trigger scripts or plugins on specific events and actively inject Trellis context into AI.
+
+Common capabilities:
+
+- session-start injection of a `.trellis/` overview.
+- workflow-state hints for each user turn.
+- PRD/spec/research injection when sub-agents start.
+- Shell commands inheriting session identity.
+
+To change "when the AI knows what," inspect hooks/plugins/extensions and settings first.
+
+### 2. Agent Prelude / Pull-Based
+
+Some platforms cannot reliably let hooks rewrite sub-agent prompts, so the agent file itself instructs the agent to read the active task, PRD, and JSONL context after startup.
+
+To change how sub-agents load context, inspect the agent files themselves.
+
+### 3. Main-Session Workflow
+
+Some platforms do not have Trellis sub-agent or hook capabilities. They rely on workflows/skills/commands to guide the main-session AI to read files, run scripts, and move tasks forward.
+
+To change behavior, inspect platform workflows/skills/commands and `.trellis/workflow.md`.
+
+## Local Modification Order
+
+When the user asks to customize behavior for a platform, the AI should inspect files in this order:
+
+1. Read `.trellis/workflow.md` to confirm the shared flow.
+2. Read the target platform's settings/config to see which hooks/agents/skills/commands are registered.
+3. Read the target platform's agents/skills/commands/hooks.
+4. Modify the local file closest to the user's need.
+5. If the change affects the shared flow, synchronize `.trellis/workflow.md` or `.trellis/spec/`.
+
+Do not modify only platform files and forget the shared workflow. Do not modify only `.trellis/workflow.md` and forget that platform entry points may still contain old descriptions.

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

@@ -0,0 +1,74 @@
+# Platform File Map
+
+This page lists common Trellis file locations in a user project by platform. Whether a platform directory exists in an actual project depends on which `trellis init --<platform>` commands the user ran.
+
+## Matrix
+
+| Platform | CLI flag | Main directory | Skill directory | Agent directory | Hooks/extensions |
+| --- | --- | --- | --- | --- | --- |
+| Claude Code | `--claude` | `.claude/` | `.claude/skills/` | `.claude/agents/` | `.claude/hooks/` + `.claude/settings.json` |
+| Cursor | `--cursor` | `.cursor/` | `.cursor/skills/` | `.cursor/agents/` | `.cursor/hooks.json` + `.cursor/hooks/` |
+| OpenCode | `--opencode` | `.opencode/` | `.opencode/skills/` | `.opencode/agents/` | `.opencode/plugins/` |
+| Codex | `--codex` | `.codex/` | `.agents/skills/` | `.codex/agents/` | `.codex/hooks/` + `.codex/hooks.json` |
+| Kilo | `--kilo` | `.kilocode/` | `.kilocode/skills/` | Usually none | `.kilocode/workflows/` |
+| Kiro | `--kiro` | `.kiro/` | `.kiro/skills/` | `.kiro/agents/` | `.kiro/hooks/` |
+| Gemini CLI | `--gemini` | `.gemini/` | `.gemini/skills/` | `.gemini/agents/` | `.gemini/settings.json` + `.gemini/hooks/` |
+| Antigravity | `--antigravity` | `.agent/` | `.agent/skills/` | Usually none | `.agent/workflows/` |
+| Windsurf | `--windsurf` | `.windsurf/` | `.windsurf/skills/` | Usually none | `.windsurf/workflows/` |
+| Qoder | `--qoder` | `.qoder/` | `.qoder/skills/` | `.qoder/agents/` | `.qoder/hooks/` + `.qoder/settings.json` |
+| CodeBuddy | `--codebuddy` | `.codebuddy/` | `.codebuddy/skills/` | `.codebuddy/agents/` | `.codebuddy/hooks/` + `.codebuddy/settings.json` |
+| GitHub Copilot | `--copilot` | `.github/` | `.github/skills/` | `.github/agents/` | `.github/copilot/hooks/` + prompts |
+| Factory Droid | `--droid` | `.factory/` | `.factory/skills/` | `.factory/droids/` | `.factory/hooks/` + settings |
+| Pi Agent | `--pi` | `.pi/` | `.pi/skills/` | `.pi/agents/` | `.pi/extensions/trellis/` + `.pi/settings.json` |
+
+## Capability Groups
+
+### Trellis Sub-Agent Support
+
+These platforms usually have `trellis-research`, `trellis-implement`, and `trellis-check` files:
+
+- Claude Code
+- Cursor
+- OpenCode
+- Codex
+- Kiro
+- Gemini CLI
+- Qoder
+- CodeBuddy
+- GitHub Copilot
+- Factory Droid
+- Pi Agent
+
+When changing implementation/check/research behavior, look for the corresponding platform agent files first.
+
+### Main-Session Workflow Platforms
+
+These platforms rely more on workflows/skills to guide the main session:
+
+- Kilo
+- Antigravity
+- Windsurf
+
+When changing behavior, inspect workflows and skills first. Do not assume Trellis sub-agents exist.
+
+### Shared `.agents/skills/`
+
+Codex writes the shared `.agents/skills/` layer. Some tools that support agentskills.io can also read this directory. If the user wants multiple compatible tools to share one skill, consider `.agents/skills/` first, but do not assume every platform reads it.
+
+## Decision Rules When Modifying Platform Files
+
+1. User specified a platform: modify only that platform directory unless shared workflow/spec files must also change.
+2. User says "all platforms should do this": synchronize equivalent entry points platform by platform; do not modify only one directory.
+3. User only says "my AI": inspect the configuration directories that actually exist in the project and infer the current AI platform.
+4. User wants project rules: prefer `.trellis/spec/` or a project-local skill.
+5. User wants Trellis behavior: edit `.trellis/workflow.md` plus platform hooks/agents/skills/commands.
+
+## When Paths Differ
+
+Platform ecosystems change, and user projects may already be customized. If this table disagrees with local files, use the actual settings/config in the user project as authoritative:
+
+- Check the hook that settings registers.
+- Check the script that a command/prompt/workflow points to.
+- Judge behavior by the read rules currently written in the agent file.
+
+Do not delete a custom file just because it is not listed in this path table.

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/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/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 -->