@mindfoldhq/trellis 0.4.0 → 0.5.0-beta.10

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

@@ -125,30 +125,48 @@ def _get_task_status(trellis_dir: Path) -> str:
     return f"Status: READY\nTask: {task_title}\nNext: Continue with implement or check"
 
 
-def _build_workflow_toc(workflow_path: Path) -> str:
-    """Build a compact section index for workflow.md (lazy-load the full file on demand).
+def _extract_range(content: str, start_header: str, end_header: str) -> str:
+    """Extract lines starting at `## start_header` up to (but excluding) `## end_header`."""
+    lines = content.splitlines()
+    start: "int | None" = None
+    end: int = len(lines)
+    start_match = f"## {start_header}"
+    end_match = f"## {end_header}"
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if start is None and stripped == start_match:
+            start = i
+            continue
+        if start is not None and stripped == end_match:
+            end = i
+            break
+    if start is None:
+        return ""
+    return "\n".join(lines[start:end]).rstrip()
 
-    Replaces full-file injection to keep additionalContext payload small.
-    The full file is accessible via: Read tool on .trellis/workflow.md
-    """
+
+def _build_workflow_toc(workflow_path: Path) -> str:
+    """Inject workflow guide: TOC + Phase Index + Phase 1/2/3 step details."""
     content = read_file(workflow_path)
     if not content:
         return "No workflow.md found"
 
-    toc_lines = [
+    out_lines = [
         "# Development Workflow — Section Index",
         "Full guide: .trellis/workflow.md  (read on demand)",
         "",
+        "## Table of Contents",
     ]
     for line in content.splitlines():
         if line.startswith("## "):
-            toc_lines.append(line)
+            out_lines.append(line)
+    out_lines += ["", "---", ""]
 
-    toc_lines += [
-        "",
-        "To read a section: use the Read tool on .trellis/workflow.md",
-    ]
-    return "\n".join(toc_lines)
+    phases = _extract_range(content, "Phase Index", "Workflow State Breadcrumbs")
+    if phases:
+        out_lines.append(phases)
+
+    return "\n".join(out_lines).rstrip()
 
 
 def main() -> None:
@@ -183,38 +201,56 @@ Read and follow all instructions below carefully.
     output.write("\n</workflow>\n\n")
 
     output.write("<guidelines>\n")
-    output.write("**Note**: The guidelines below are index files — they list available guideline documents and their locations.\n")
-    output.write("During actual development, you MUST read the specific guideline files listed in each index's Pre-Development Checklist.\n\n")
-
+    output.write(
+        "Project spec indexes are listed by path below. Each index contains a "
+        "**Pre-Development Checklist** listing the specific guideline files to "
+        "read before coding.\n\n"
+        "- If you're spawning an implement/check sub-agent, context is injected "
+        "automatically via `{task}/implement.jsonl` / `check.jsonl`. You do NOT "
+        "need to read these indexes yourself.\n"
+        "- If you're editing code directly in the main session, Read the relevant "
+        "index(es) on-demand and follow their Pre-Dev Checklist.\n\n"
+    )
+
+    # guides/ inlined (cross-package thinking, broadly useful)
+    guides_index = trellis_dir / "spec" / "guides" / "index.md"
+    if guides_index.is_file():
+        output.write("## guides (inlined — cross-package thinking guides)\n")
+        output.write(read_file(guides_index))
+        output.write("\n\n")
+
+    # Other indexes — paths only
+    paths: list[str] = []
     spec_dir = trellis_dir / "spec"
     if spec_dir.is_dir():
         for sub in sorted(spec_dir.iterdir()):
             if not sub.is_dir() or sub.name.startswith("."):
                 continue
-
             if sub.name == "guides":
-                index_file = sub / "index.md"
-                if index_file.is_file():
-                    output.write(f"## {sub.name}\n")
-                    output.write(read_file(index_file))
-                    output.write("\n\n")
                 continue
-
             index_file = sub / "index.md"
             if index_file.is_file():
-                output.write(f"## {sub.name}\n")
-                output.write(read_file(index_file))
-                output.write("\n\n")
+                paths.append(f".trellis/spec/{sub.name}/index.md")
             else:
                 for nested in sorted(sub.iterdir()):
                     if not nested.is_dir():
                         continue
                     nested_index = nested / "index.md"
                     if nested_index.is_file():
-                        output.write(f"## {sub.name}/{nested.name}\n")
-                        output.write(read_file(nested_index))
-                        output.write("\n\n")
-
+                        paths.append(
+                            f".trellis/spec/{sub.name}/{nested.name}/index.md"
+                        )
+
+    if paths:
+        output.write("## Available spec indexes (read on demand)\n")
+        for p in paths:
+            output.write(f"- {p}\n")
+        output.write("\n")
+
+    output.write(
+        "Discover more via: "
+        "`python3 ./.trellis/scripts/get_context.py --mode packages`\n"
+    )
     output.write("</guidelines>\n\n")
 
     task_status = _get_task_status(trellis_dir)

package/dist/templates/codex/hooks.json

@@ -11,6 +11,17 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "{{PYTHON_CMD}} .codex/hooks/inject-workflow-state.py",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   }
 }

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

@@ -24,7 +24,6 @@ export interface ConfigTemplate {
     targetPath: string;
     content: string;
 }
-export declare function getAllSkills(): SkillTemplate[];
 export declare function getAllAgents(): AgentTemplate[];
 /**
  * Get Codex-specific skills (installed to .codex/skills/, not shared .agents/skills/).

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/codex/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAgCH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,YAAY,IAAI,aAAa,EAAE,CAS9C;AAED,wBAAgB,YAAY,IAAI,aAAa,EAAE,CAc9C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,aAAa,EAAE,CASnD;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,WAAW,IAAI,YAAY,EAAE,CAW5C;AAED,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAKlD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/codex/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAgCH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,wBAAgB,YAAY,IAAI,aAAa,EAAE,CAc9C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,aAAa,EAAE,CASnD;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,WAAW,IAAI,YAAY,EAAE,CAW5C;AAED,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED,wBAAgB,iBAAiB,IAAI,cAAc,CAKlD"}

package/dist/templates/codex/index.js

@@ -39,14 +39,7 @@ function listFiles(dir) {
         return [];
     }
 }
-export function getAllSkills() {
-    const skills = [];
-    for (const name of listDirectories("skills")) {
-        const content = readTemplate(`skills/${name}/SKILL.md`);
-        skills.push({ name, content });
-    }
-    return skills;
-}
+// Shared skills are now sourced from common/ templates (see templates/common/index.ts)
 export function getAllAgents() {
     const agents = [];
     for (const file of listFiles("agents")) {

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/codex/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/codex/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;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,eAAe,CAAC,GAAW;IAClC,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;aAC9D,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;aACtC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;aAC1B,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAC,GAAW;IAC5B,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAiBD,uFAAuF;AAEvF,MAAM,UAAU,YAAY;IAC1B,MAAM,MAAM,GAAoB,EAAE,CAAC;IAEnC,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,SAAS;QACX,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACvC,MAAM,OAAO,GAAG,YAAY,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC;QAC/C,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,MAAM,GAAoB,EAAE,CAAC;IAEnC,KAAK,MAAM,IAAI,IAAI,eAAe,CAAC,cAAc,CAAC,EAAE,CAAC;QACnD,MAAM,OAAO,GAAG,YAAY,CAAC,gBAAgB,IAAI,WAAW,CAAC,CAAC;QAC9D,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAOD,MAAM,UAAU,WAAW;IACzB,MAAM,KAAK,GAAmB,EAAE,CAAC;IAEjC,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,SAAS;QACX,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,SAAS,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,YAAY,CAAC,YAAY,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,UAAU,EAAE,aAAa;QACzB,OAAO,EAAE,YAAY,CAAC,aAAa,CAAC;KACrC,CAAC;AACJ,CAAC"}

package/dist/templates/codex/skills/start/SKILL.md

@@ -247,7 +247,7 @@ Use this output format:
 Initialize default context:
 
 ```bash
-python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type>
+python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type> --platform {{CLI_FLAG}}
 # type: backend | frontend | fullstack
 ```
 

package/dist/templates/common/commands/continue.md

@@ -0,0 +1,51 @@
+# Continue Current Task
+
+Resume work on the current task — pick up at the right phase/step in `.trellis/workflow.md`.
+
+---
+
+## Step 1: Load Current Context
+
+```bash
+{{PYTHON_CMD}} ./.trellis/scripts/get_context.py
+```
+
+Confirms: current task, git state, recent commits.
+
+## Step 2: Load the Phase Index
+
+```bash
+{{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase
+```
+
+Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
+
+## Step 3: Decide Where You Are
+
+Compare the task's `prd.md` + recent activity against the Phase Index:
+
+- No `prd.md` yet, or requirements unclear → **Phase 1: Plan** (start at step 1.0/1.1)
+- `prd.md` exists + context configured, but code not written → **Phase 2: Execute** (step 2.1)
+- Code written, pending final quality gate → **Phase 3: Finish** (step 3.1)
+
+Phase rules (full detail in `.trellis/workflow.md`):
+
+1. Run steps **in order** within a phase — `[required]` steps must not be skipped
+2. `[once]` steps are already done if the output exists (e.g., `prd.md`, `implement.jsonl`) — skip them
+3. You may go back to an earlier phase if discoveries require it
+
+## Step 4: Load the Specific Step
+
+Once you know which step to resume at:
+
+```bash
+{{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase --step <X.X> --platform {{CLI_FLAG}}
+```
+
+Follow the loaded instructions. After each `[required]` step completes, move to the next.
+
+---
+
+## Reference
+
+Full workflow, skill routing table, and the DO-NOT-skip table live in `.trellis/workflow.md`. This command is only an entry point — the canonical guidance is there.

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

@@ -0,0 +1,32 @@
+# Finish Work
+
+Wrap up the current session.
+
+## Step 1: Quality Gate
+
+`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.
+
+## Step 2: Remind User to Commit
+
+If there are uncommitted changes:
+
+> "Please review the changes and commit when ready."
+
+Do NOT run `git commit` — the human commits after testing.
+
+## Step 3: Record Session (after commit)
+
+Archive finished tasks (judge by work status, not the `status` field):
+
+```bash
+{{PYTHON_CMD}} ./.trellis/scripts/task.py archive <task-name>
+```
+
+Append a session entry (auto-handles journal rotation, line count, index update):
+
+```bash
+{{PYTHON_CMD}} ./.trellis/scripts/add_session.py \
+  --title "Session Title" \
+  --commit "hash1,hash2" \
+  --summary "Brief summary"
+```

package/dist/templates/common/commands/start.md

@@ -0,0 +1,56 @@
+# Start Session
+
+Initialize a Trellis-managed development session. This platform has no session-start hook, so manually load the equivalent context by following these steps (each one mirrors a section the hook would otherwise inject).
+
+---
+
+## Step 1: Current state
+Identity, git status, current task, active tasks, journal location.
+
+```bash
+{{PYTHON_CMD}} ./.trellis/scripts/get_context.py
+```
+
+## Step 2: Workflow overview
+Phase Index + skill routing table + DO-NOT-skip rules.
+
+```bash
+{{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase
+```
+
+Full guide in `.trellis/workflow.md` (read on demand).
+
+## Step 3: Guideline indexes
+Discover packages + spec layers, then read each relevant index file.
+
+```bash
+{{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode packages
+cat .trellis/spec/guides/index.md
+cat .trellis/spec/<package>/<layer>/index.md   # for each relevant layer
+```
+
+Index files list the specific guideline docs to read when you actually start coding.
+
+## Step 4: Decide next action
+From Step 1 you know the current task. Check the task directory:
+
+- **Active task + `prd.md` exists** → Phase 2 step 2.1. Load the step detail:
+  ```bash
+  {{PYTHON_CMD}} ./.trellis/scripts/get_context.py --mode phase --step 2.1 --platform {{CLI_FLAG}}
+  ```
+- **Active task + no `prd.md`** → Phase 1.1. Load the `trellis-brainstorm` skill.
+- **No active task** → when the user describes multi-step work, load the `trellis-brainstorm` skill to clarify requirements, then create a task via `task.py create`. For simple one-off questions or trivial edits, skip this and just answer directly — no task needed.
+
+---
+
+## Skill routing (quick reference)
+
+| User intent | Skill |
+|---|---|
+| New feature / unclear requirements | `trellis-brainstorm` |
+| About to write code | `trellis-before-dev` |
+| Done coding / quality check | `trellis-check` |
+| Stuck / fixed same bug multiple times | `trellis-break-loop` |
+| Learned something worth capturing | `trellis-update-spec` |
+
+Full rules + anti-rationalization table in `.trellis/workflow.md`.

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

@@ -0,0 +1,28 @@
+/**
+ * Common templates — single source of truth for all platforms.
+ *
+ * These templates contain {{placeholders}} that are resolved per-platform
+ * by resolvePlaceholders() in configurators/shared.ts.
+ *
+ * Directory structure:
+ *   common/
+ *   ├── commands/    # Templates that stay as slash commands (start, finish-work)
+ *   └── skills/      # Templates that become auto-triggered skills
+ */
+export interface CommonTemplate {
+    /** Template name without extension (e.g., "start", "before-dev") */
+    name: string;
+    /** Raw content with {{placeholders}} — must be resolved before writing */
+    content: string;
+}
+/**
+ * Get all command templates (stay as slash commands on all platforms).
+ * Results are cached after first call.
+ */
+export declare function getCommandTemplates(): CommonTemplate[];
+/**
+ * Get all skill templates (become auto-triggered skills on supporting platforms).
+ * Results are cached after first call.
+ */
+export declare function getSkillTemplates(): CommonTemplate[];
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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"}

package/dist/templates/common/index.js

@@ -0,0 +1,55 @@
+/**
+ * Common templates — single source of truth for all platforms.
+ *
+ * These templates contain {{placeholders}} that are resolved per-platform
+ * by resolvePlaceholders() in configurators/shared.ts.
+ *
+ * Directory structure:
+ *   common/
+ *   ├── commands/    # Templates that stay as slash commands (start, finish-work)
+ *   └── skills/      # Templates that become auto-triggered skills
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+function readTemplate(relativePath) {
+    return readFileSync(join(__dirname, relativePath), "utf-8");
+}
+function listMarkdownFiles(dir) {
+    try {
+        return readdirSync(join(__dirname, dir))
+            .filter((f) => f.endsWith(".md"))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+// Cached results — files don't change during a CLI run
+let cachedCommands;
+let cachedSkills;
+/**
+ * Get all command templates (stay as slash commands on all platforms).
+ * Results are cached after first call.
+ */
+export function getCommandTemplates() {
+    cachedCommands ??= listMarkdownFiles("commands").map((file) => ({
+        name: file.replace(/\.md$/, ""),
+        content: readTemplate(`commands/${file}`),
+    }));
+    return cachedCommands;
+}
+/**
+ * Get all skill templates (become auto-triggered skills on supporting platforms).
+ * Results are cached after first call.
+ */
+export function getSkillTemplates() {
+    cachedSkills ??= listMarkdownFiles("skills").map((file) => ({
+        name: file.replace(/\.md$/, ""),
+        content: readTemplate(`skills/${file}`),
+    }));
+    return cachedSkills;
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +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"}

package/dist/templates/{droid/commands/trellis → common/skills}/brainstorm.md

@@ -1,7 +1,3 @@
----
-description: Collaborative requirements discovery before implementation
----
-
 # Brainstorm - Requirements Discovery (AI Coding Enhanced)
 
 Guide AI through collaborative requirements discovery **before implementation**, optimized for AI coding workflows:
@@ -15,7 +11,7 @@ Guide AI through collaborative requirements discovery **before implementation**,
 
 ## When to Use
 
-Triggered from `/trellis-start` when the user describes a development task, especially when:
+Triggered from {{CMD_REF:start}} when the user describes a development task, especially when:
 
 * requirements are unclear or evolving
 * there are multiple valid implementation paths
@@ -188,18 +184,61 @@ Examples:
 * The user asks for "best practice", "how others do it", "recommendation"
 * The user can't reasonably enumerate options
 
-### Research steps
+### Delegate to `trellis-research` sub-agent (don't research inline)
+
+For each research topic, **spawn a `trellis-research` sub-agent via the Task tool** — don't do WebFetch / WebSearch / `gh api` inline in the main conversation.
+
+Why:
+- The sub-agent has its own context window → doesn't pollute brainstorm context with raw tool output
+- It persists findings to `{TASK_DIR}/research/<topic>.md` (the contract — see `workflow.md` Phase 1.2)
+- It returns only `{file path, one-line summary}` to the main agent
+- Independent topics can be **parallelized** — spawn multiple sub-agents in one tool call
+
+Agent type: `trellis-research`
+Task description template: "Research <specific question>; persist findings to `{TASK_DIR}/research/<topic-slug>.md`."
+
+❌ Bad (what you must NOT do):
+```
+Main agent: WebFetch(url-A) → WebFetch(url-B) → Bash(gh api ...)
+          → WebSearch(q1) → WebSearch(q2) → ... (10+ inline calls)
+          → Write(research/topic.md)
+```
+→ Pollutes main context with raw HTML/JSON, burns tokens.
+
+✅ Good:
+```
+Main agent: Task(subagent_type="trellis-research",
+                 prompt="Research topic A; persist to research/topic-a.md")
+          + Task(subagent_type="trellis-research",
+                 prompt="Research topic B; persist to research/topic-b.md")
+          + Task(subagent_type="trellis-research",
+                 prompt="Research topic C; persist to research/topic-c.md")
+→ Reads research/topic-{a,b,c}.md after they finish.
+```
+
+### Research steps (to pass into each sub-agent prompt)
+
+Each `trellis-research` sub-agent should:
 
-1. Identify 2–4 comparable tools/patterns
+1. Identify 2–4 comparable tools/patterns for its topic
 2. Summarize common conventions and why they exist
 3. Map conventions onto our repo constraints
-4. Produce **2–3 feasible approaches** for our project
+4. Write findings to `{TASK_DIR}/research/<topic>.md`
+
+Main agent then reads the persisted files and produces **2–3 feasible approaches** in PRD.
 
 ### Research output format (PRD)
 
-Add a section in PRD (either within Technical Notes or as its own):
+The PRD itself should only reference the persisted research files, not duplicate their content. Add a `## Research References` section pointing at `research/*.md`.
+
+Optionally, add a convergence section with feasible approaches derived from the research:
 
 ```markdown
+## Research References
+
+* [`research/<topic-a>.md`](research/<topic-a>.md) — <one-line takeaway>
+* [`research/<topic-b>.md`](research/<topic-b>.md) — <one-line takeaway>
+
 ## Research Notes
 
 ### What similar tools do
@@ -486,6 +525,6 @@ The task directory and PRD already exist from brainstorm, so Phase 1 of the Task
 
 | Command | When to Use |
 |---------|-------------|
-| `/trellis-start` | Entry point that triggers brainstorm |
-| `/trellis-finish-work` | After implementation is complete |
-| `/trellis-update-spec` | If new patterns emerge during work |
+| `{{CMD_REF:start}}` | Entry point that triggers brainstorm |
+| `{{CMD_REF:finish-work}}` | After implementation is complete |
+| `{{CMD_REF:update-spec}}` | If new patterns emerge during work |

package/dist/templates/{iflow/commands/trellis → common/skills}/break-loop.md

@@ -1,6 +1,6 @@
 # Break the Loop - Deep Bug Analysis
 
-When debug is complete, use this command for deep analysis to break the "fix bug -> forget -> repeat" cycle.
+When debug is complete, use this for deep analysis to break the "fix bug -> forget -> repeat" cycle.
 
 ---
 
@@ -37,7 +37,7 @@ What mechanisms would prevent this from happening again?
 |------|-------------|---------|
 | **Documentation** | Write it down so people know | Update thinking guide |
 | **Architecture** | Make the error impossible structurally | Type-safe wrappers |
-| **Compile-time** | TypeScript strict, no any | Signature change causes compile error |
+| **Compile-time** | Strict type checking, no escape hatches | Signature change causes compile error |
 | **Runtime** | Monitoring, alerts, scans | Detect orphan entities |
 | **Test Coverage** | E2E tests, integration tests | Verify full flow |
 | **Code Review** | Checklist, PR template | "Did you check X?" |
@@ -56,10 +56,10 @@ What broader problems does this bug reveal?
 Solidify insights into the system:
 
 - [ ] Update `.trellis/spec/guides/` thinking guides
-- [ ] Update `.trellis/spec/backend/` or `frontend/` docs
+- [ ] Update relevant `.trellis/spec/` docs
 - [ ] Create issue record (if applicable)
 - [ ] Create feature ticket for root fix
-- [ ] Update check commands if needed
+- [ ] Update check guidelines if needed
 
 ---
 

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

@@ -0,0 +1,87 @@
+# Code Quality Check
+
+Comprehensive quality verification for recently written code. Combines spec compliance, cross-layer safety, and pre-commit checks.
+
+---
+
+## Step 1: Identify What Changed
+
+```bash
+git diff --name-only HEAD
+git status
+```
+
+## Step 2: Read Applicable Specs
+
+```bash
+python3 ./.trellis/scripts/get_context.py --mode packages
+```
+
+For each changed package/layer, read the spec index and follow its **Quality Check** section:
+
+```bash
+cat .trellis/spec/<package>/<layer>/index.md
+```
+
+Read the specific guideline files referenced — the index is a pointer, not the goal.
+
+## Step 3: Run Project Checks
+
+Run the project's lint, type-check, and test commands. Fix any failures before proceeding.
+
+## Step 4: Review Against Checklist
+
+### Code Quality
+
+- [ ] Linter passes?
+- [ ] Type checker passes (if applicable)?
+- [ ] Tests pass?
+- [ ] No debug logging left in?
+- [ ] No suppressed warnings or type-safety bypasses?
+
+### Test Coverage
+
+- [ ] New function → unit test added?
+- [ ] Bug fix → regression test added?
+- [ ] Changed behavior → existing tests updated?
+
+### Spec Sync
+
+- [ ] Does `.trellis/spec/` need updates? (new patterns, conventions, lessons learned)
+
+> "If I fixed a bug or discovered something non-obvious, should I document it so future me won't hit the same issue?" → If YES, update the relevant spec doc.
+
+## Step 5: Cross-Layer Dimensions (if applicable)
+
+Skip this step if your change is confined to a single layer.
+
+### A. Data Flow (changes touch 3+ layers)
+
+- [ ] Read flow traces correctly: Storage → Service → API → UI
+- [ ] Write flow traces correctly: UI → API → Service → Storage
+- [ ] Types/schemas correctly passed between layers?
+- [ ] Errors properly propagated to caller?
+
+### B. Code Reuse (modifying constants, creating utilities)
+
+- [ ] Searched for existing similar code before creating new?
+  ```bash
+  grep -r "pattern" src/
+  ```
+- [ ] If 2+ places define same value → extracted to shared constant?
+- [ ] After batch modification, all occurrences updated?
+
+### C. Import/Dependency (creating new files)
+
+- [ ] Correct import paths (relative vs absolute)?
+- [ ] No circular dependencies?
+
+### D. Same-Layer Consistency
+
+- [ ] Other places using the same concept are consistent?
+
+---
+
+## Step 6: Report and Fix
+
+Report violations found and fix them directly. Re-run project checks after fixes.