@mindfoldhq/trellis 0.3.10 → 0.4.0-beta.10

package/dist/templates/kiro/skills/onboard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: onboard
-description: "PART 3: Customize Your Development Guidelines"
+description: "Interactive three-part onboarding for new team members to the Trellis AI-assisted workflow system. Covers core philosophy (AI memory, project-specific knowledge, context drift), system structure and command deep-dives, real-world workflow examples, and guideline customization. Use when a new developer joins the project, someone needs to understand the Trellis workflow, or project guidelines need initial setup."
 ---
 
 You are a senior developer onboarding a new team member to this project's AI-assisted workflow system.
@@ -131,13 +131,13 @@ AI needs the same onboarding - but compressed into seconds at session start.
 
 ---
 
-### $before-frontend-dev and $before-backend-dev - Inject Specialized Knowledge
+### $before-dev - Inject Specialized Knowledge
 
 **WHY IT EXISTS**:
 AI models have "pre-trained knowledge" - general patterns from millions of codebases. But YOUR project has specific conventions that differ from generic patterns.
 
 **WHAT IT ACTUALLY DOES**:
-1. Reads `.trellis/spec/frontend/` or `.trellis/spec/backend/`
+1. Discovers spec layers via `get_context.py --mode packages` and reads relevant guidelines
 2. Loads project-specific patterns into AI's working context:
    - Component naming conventions
    - State management patterns
@@ -145,12 +145,12 @@ AI models have "pre-trained knowledge" - general patterns from millions of codeb
    - Error handling standards
 
 **WHY THIS MATTERS**:
-- Without before-*-dev: AI writes generic code that doesn't match project style.
-- With before-*-dev: AI writes code that looks like the rest of the codebase.
+- Without before-dev: AI writes generic code that doesn't match project style.
+- With before-dev: AI writes code that looks like the rest of the codebase.
 
 ---
 
-### $check-frontend and $check-backend - Combat Context Drift
+### $check - Combat Context Drift
 
 **WHY IT EXISTS**:
 AI context window has limited capacity. As conversation progresses, guidelines injected at session start become less influential. This causes "context drift."
@@ -216,9 +216,9 @@ All the context AI built during this session will be lost when session ends. The
 
 **[1/8] $start** - AI needs project context before touching code
 **[2/8] python3 ./.trellis/scripts/task.py create "Fix bug" --slug fix-bug** - Track work for future reference
-**[3/8] $before-frontend-dev** - Inject project-specific frontend knowledge
+**[3/8] $before-dev** - Inject project-specific development guidelines
 **[4/8] Investigate and fix the bug** - Actual development work
-**[5/8] $check-frontend** - Re-verify code against guidelines
+**[5/8] $check** - Re-verify code against guidelines
 **[6/8] $finish-work** - Holistic cross-layer review
 **[7/8] Human tests and commits** - Human validates before code enters repo
 **[8/8] $record-session** - Persist memory for future sessions
@@ -233,9 +233,9 @@ All the context AI built during this session will be lost when session ends. The
 ### Example 3: Code Review Fixes
 
 **[1/6] $start** - Resume context from previous session
-**[2/6] $before-backend-dev** - Re-inject guidelines before fixes
+**[2/6] $before-dev** - Re-inject guidelines before fixes
 **[3/6] Fix each CR issue** - Address feedback with guidelines in context
-**[4/6] $check-backend** - Verify fixes didn't introduce new issues
+**[4/6] $check** - Verify fixes did not introduce new issues
 **[5/6] $finish-work** - Document lessons from CR
 **[6/6] Human commits, then $record-session** - Preserve CR lessons
 
@@ -250,9 +250,9 @@ All the context AI built during this session will be lost when session ends. The
 ### Example 5: Debug Session
 
 **[1/6] $start** - See if this bug was investigated before
-**[2/6] $before-backend-dev** - Guidelines might document known gotchas
+**[2/6] $before-dev** - Guidelines might document known gotchas
 **[3/6] Investigation** - Actual debugging work
-**[4/6] $check-backend** - Verify debug changes don't break other things
+**[4/6] $check** - Verify debug changes do not break other things
 **[5/6] $finish-work** - Debug findings might need documentation
 **[6/6] Human commits, then $record-session** - Debug knowledge is valuable
 

package/dist/templates/kiro/skills/record-session/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: record-session
-description: "Record work progress after human has tested and committed code"
+description: "Records completed work progress to .trellis/workspace/ journal files after human testing and commit. Captures session summaries, commit hashes, and updates developer index files for future session context. Use when a coding session is complete, after the human has committed code, or to persist session knowledge for future AI sessions."
 ---
 
 [!] **Prerequisite**: This skill should only be used AFTER the human has tested and committed the code.
@@ -36,7 +36,7 @@ python3 ./.trellis/scripts/add_session.py \
   --summary "Brief summary of what was done"
 
 # Method 2: Pass detailed content via stdin
-cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash"
+cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --stdin --title "Title" --commit "hash"
 | Feature | Description |
 |---------|-------------|
 | New API | Added user authentication endpoint |
@@ -51,6 +51,7 @@ EOF
 **Auto-completes**:
 - [OK] Appends session to journal-N.md
 - [OK] Auto-detects line count, creates new file if >2000 lines
+- [OK] Auto-detects Branch context (`--branch` override; otherwise Branch = task.json -> current git branch; missing values are omitted gracefully)
 - [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history)
 - [OK] Auto-commits .trellis/workspace and .trellis/tasks changes
 
@@ -61,6 +62,6 @@ EOF
 | Command | Purpose |
 |---------|---------|
 | `python3 ./.trellis/scripts/get_context.py --mode record` | Get context for record-session |
-| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended)** |
+| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended, branch auto-complete)** |
 | `python3 ./.trellis/scripts/task.py archive <name>` | Archive completed task (auto-commits) |
 | `python3 ./.trellis/scripts/task.py list` | List active tasks |

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

@@ -1,6 +1,6 @@
 ---
 name: start
-description: "Start Session"
+description: "Initializes an AI development session by reading workflow guides, developer identity, git status, active tasks, and project guidelines from .trellis/. Classifies incoming tasks and routes to brainstorm, direct edit, or task workflow. Use when beginning a new coding session, resuming work, starting a new task, or re-establishing project context."
 ---
 
 # Start Session
@@ -45,9 +45,14 @@ This shows: developer identity, git status, current task (if any), active tasks.
 ### Step 3: Read Guidelines Index
 
 ```bash
-cat .trellis/spec/frontend/index.md  # Frontend guidelines
-cat .trellis/spec/backend/index.md   # Backend guidelines
-cat .trellis/spec/guides/index.md    # Thinking guides
+python3 ./.trellis/scripts/get_context.py --mode packages
+```
+
+This shows available packages and their spec layers. Read the relevant spec indexes:
+
+```bash
+cat .trellis/spec/<package>/<layer>/index.md   # Package-specific guidelines
+cat .trellis/spec/guides/index.md              # Thinking guides (always read)
 ```
 
 > **Important**: The index files are navigation — they list the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`).

package/dist/templates/kiro/skills/update-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: update-spec
-description: "Update Code-Spec - Capture Executable Contracts"
+description: "Captures executable contracts and coding knowledge into .trellis/spec/ documents after implementation, debugging, or design decisions. Enforces code-spec depth for infra and cross-layer changes with mandatory sections for signatures, contracts, validation matrices, and test points. Use when a feature is implemented, a bug is fixed, a design decision is made, a new pattern is discovered, or cross-layer contracts change."
 ---
 
 # Update Code-Spec - Capture Executable Contracts

package/dist/templates/markdown/agents.md

@@ -13,6 +13,10 @@ Use `@/.trellis/` to learn:
 - Project structure guidelines (`spec/`)
 - Developer workspace (`workspace/`)
 
+If you're using Codex, project-scoped helpers may also live in:
+- `.agents/skills/` for reusable Trellis skills
+- `.codex/agents/` for optional custom subagents
+
 Keep this managed block so 'trellis update' can refresh the instructions.
 
 <!-- TRELLIS:END -->

package/dist/templates/markdown/spec/backend/directory-structure.md

@@ -239,7 +239,7 @@ Templates use `.txt` extension to:
 ```typescript
 import { downloadTemplate } from "giget";
 
-await downloadTemplate("gh:mindfold-ai/Trellis/marketplace/specs/electron-fullstack", {
+await downloadTemplate("gh:mindfold-ai/marketplace/specs/electron-fullstack", {
   dir: destDir,
   preferOffline: true,
 });

package/dist/templates/markdown/spec/backend/script-conventions.md

@@ -502,6 +502,99 @@ parser.add_argument(
 
 ---
 
+## Parsing Structured Command Output
+
+### CRITICAL: Preserve Semantic Whitespace
+
+Many CLI tools encode status information in leading/trailing whitespace characters. **Never blindly `.strip()` before parsing.**
+
+**Example — `git submodule status` output format**:
+
+```
+ abc1234 path/to/submodule (v1.0)     ← space prefix = initialized
+-def5678 path/to/other (v2.0)         ← minus prefix = not initialized
++ghi9012 path/to/modified (v3.0)      ← plus prefix = modified (out of sync)
+```
+
+```python
+# BAD — .strip() removes the leading space that means "initialized"
+status_line = status_out.strip()
+prefix = status_line[0]  # Reads commit hash char, not status prefix!
+
+# GOOD — parse the raw line, then strip individual fields
+raw_line = status_out.rstrip("\n")  # Only remove trailing newline
+if not raw_line:
+    continue
+prefix = raw_line[0]               # ' ', '-', or '+'
+rest = raw_line[1:].strip()        # Now safe to strip the rest
+commit_hash = rest.split()[0]
+```
+
+**General rule**: When a command's output uses positional formatting (columns, prefixes, fixed-width fields), parse the structure first, then clean up individual values.
+
+**Other commands with semantic whitespace**:
+- `git status --porcelain` — two-char status prefix (`XY`)
+- `git diff --name-status` — tab-separated with status prefix
+- `docker ps --format` — column-aligned output
+
+---
+
+## Monorepo Config API (`common/config.py`)
+
+### Config Functions
+
+| Function | Return | Purpose |
+|----------|--------|---------|
+| `is_monorepo(repo_root)` | `bool` | Whether `packages:` exists in config.yaml |
+| `get_packages(repo_root)` | `dict[str, dict] \| None` | All packages from config.yaml (`{name: {path, type?}}`) |
+| `get_default_package(repo_root)` | `str \| None` | The `default_package` from config.yaml |
+| `get_submodule_packages(repo_root)` | `dict[str, str]` | Packages with `type: submodule` (`{name: path}`) |
+| `get_spec_base(package, repo_root)` | `str` | `"spec"` (single-repo) or `"spec/<package>"` (monorepo) |
+| `validate_package(package, repo_root)` | `bool` | Whether package exists in config (always `True` for single-repo) |
+| `resolve_package(task_pkg, repo_root)` | `str \| None` | Resolve package: task → default → None |
+| `get_spec_scope(repo_root)` | `str \| list \| None` | The `session.spec_scope` config value |
+| `get_hooks(event, repo_root)` | `list[str]` | Hook commands for lifecycle event |
+
+### Config.yaml Schema
+
+```yaml
+# Auto-detected monorepo packages (written by trellis init)
+packages:
+  cli:
+    path: packages/cli
+  docs-site:
+    path: docs-site
+    type: submodule       # optional, marks git submodule
+default_package: cli      # first non-submodule package
+
+# Session behavior
+session:
+  spec_scope: active_task  # or ["cli", "docs-site"] or omit for full scan
+
+# Update behavior
+update:
+  skip:
+    - .claude/commands/trellis/my-custom.md
+
+# Lifecycle hooks
+hooks:
+  after_create:
+    - "python3 .trellis/scripts/hooks/my_hook.py create"
+```
+
+### Worktree Submodule Initialization
+
+When `start.py` creates a worktree for a task, it calls `_init_submodules_for_task()`:
+
+1. Read `packages` from config.yaml via `get_packages()`
+2. Resolve target package from task data or `default_package`
+3. Check if the package is a submodule via `get_submodule_packages()`
+4. Run `git submodule status <path>` in the worktree
+5. Parse the status prefix (see "Parsing Structured Command Output" above)
+6. If uninitialized (`-` prefix): run `git submodule update --init <path>`
+
+---
+
 ## Error Handling
 
 ### Exit Codes

package/dist/templates/markdown/workspace-index.md

@@ -73,6 +73,7 @@ This will:
 
 Each session should include:
 - Summary: One-line description
+- Branch: Which branch the work was done on
 - Main Changes: What was modified
 - Git Commits: Commit hashes and messages
 - Next Steps: What to do next
@@ -88,6 +89,7 @@ Use this template when recording sessions:
 
 **Date**: YYYY-MM-DD
 **Task**: {task-name}
+**Branch**: `{branch-name}`
 
 ### Summary
 

package/dist/templates/opencode/agents/dispatch.md

@@ -71,6 +71,10 @@ Execute each step in `phase` order.
 
 > Hook will auto-inject all specs, requirements, and technical design to subagent context.
 > Dispatch only needs to issue simple call commands.
+>
+> **OpenCode dispatch rule**: Call subagents synchronously (`run_in_background: false`).
+> Do NOT use `TaskOutput` or background polling as the completion signal for child phases.
+> The background wrapper can finish before the real subagent session is actually done.
 
 ### action: "implement"
 
@@ -79,7 +83,7 @@ Task(
   subagent_type: "implement",
   prompt: "Implement the feature described in prd.md in the task directory",
   model: "opus",
-  run_in_background: true
+  run_in_background: false
 )
 ```
 
@@ -98,7 +102,7 @@ Task(
   subagent_type: "check",
   prompt: "Check code changes, fix issues yourself",
   model: "opus",
-  run_in_background: true
+  run_in_background: false
 )
 ```
 
@@ -106,8 +110,7 @@ Hook will auto-inject:
 
 - finish-work.md
 - check-cross-layer.md
-- check-backend.md
-- check-frontend.md
+- check.md
 - All spec files from check.jsonl
 
 ### action: "debug"
@@ -117,7 +120,7 @@ Task(
   subagent_type: "debug",
   prompt: "Fix the issues described in the task context",
   model: "opus",
-  run_in_background: true
+  run_in_background: false
 )
 ```
 
@@ -133,7 +136,7 @@ Task(
   subagent_type: "check",
   prompt: "[finish] Execute final completion check before PR",
   model: "opus",
-  run_in_background: true
+  run_in_background: false
 )
 ```
 
@@ -169,27 +172,23 @@ This will:
 ### Basic Pattern
 
 ```
-task_id = Task(
+result = Task(
   subagent_type: "implement",  // or "check", "debug"
   prompt: "Simple task description",
   model: "opus",
-  run_in_background: true
+  run_in_background: false
 )
 
-// Poll for completion
-for i in 1..N:
-    result = TaskOutput(task_id, block=true, timeout=300000)
-    if result.status == "completed":
-        break
+// Wait for the Task call to return before starting the next phase.
+// Do NOT call TaskOutput or use background polling inside OpenCode dispatch.
 ```
 
-### Timeout Settings
+### Execution Rule
 
-| Phase | Max Time | Poll Count |
-|-------|----------|------------|
-| implement | 30 min | 6 times |
-| check | 15 min | 3 times |
-| debug | 20 min | 4 times |
+- Run one phase at a time
+- Start the next phase only after the current `Task(...)` call returns
+- If a phase returns a clear timeout or failure, handle that result explicitly
+- Do **not** simulate completion by polling a background task wrapper
 
 ---
 
@@ -197,7 +196,7 @@ for i in 1..N:
 
 ### Timeout
 
-If a subagent times out, notify the user and ask for guidance:
+If a synchronous subagent call times out, notify the user and ask for guidance:
 
 ```
 "Subagent {phase} timed out after {time}. Options:
@@ -208,10 +207,11 @@ If a subagent times out, notify the user and ask for guidance:
 
 ### Subagent Failure
 
-If a subagent reports failure, read the output and decide:
+If a synchronous subagent call reports failure, read the output and decide:
 
 - If recoverable: call debug agent to fix
 - If not recoverable: notify user and ask for guidance
+- Do not switch back to `TaskOutput` polling for the same phase
 
 ---
 

package/dist/templates/opencode/agents/implement.md

@@ -65,8 +65,8 @@ Before implementing, read:
 
 Read relevant specs based on task type:
 
-- Backend: `.trellis/spec/backend/`
-- Frontend: `.trellis/spec/frontend/`
+- Spec layers: `.trellis/spec/<package>/<layer>/`
+- Shared guides: `.trellis/spec/guides/`
 - Guides: `.trellis/spec/guides/`
 
 ### 2. Understand Requirements

package/dist/templates/opencode/agents/research.md

@@ -29,8 +29,7 @@ Otherwise, if task-specific research is needed:
    - If `path` is a directory → Read all `.md` files in it
 
 Project spec locations for reference:
-- `.trellis/spec/backend/` - Backend standards
-- `.trellis/spec/frontend/` - Frontend standards
+- `.trellis/spec/<package>/<layer>/` - Package-specific standards
 - `.trellis/spec/guides/` - Thinking guides
 - `.trellis/big-question/` - Known issues and pitfalls
 

package/dist/templates/opencode/commands/trellis/before-dev.md

@@ -0,0 +1,29 @@
+Read the relevant development guidelines before starting your task.
+
+Execute these steps:
+
+1. **Discover packages and their spec layers**:
+   ```bash
+   python3 ./.trellis/scripts/get_context.py --mode packages
+   ```
+
+2. **Identify which specs apply** to your task based on:
+   - Which package you're modifying (e.g., `cli/`, `docs-site/`)
+   - What type of work (backend, frontend, unit-test, docs, etc.)
+
+3. **Read the spec index** for each relevant module:
+   ```bash
+   cat .trellis/spec/<package>/<layer>/index.md
+   ```
+   Follow the **"Pre-Development Checklist"** section in the index.
+
+4. **Read the specific guideline files** listed in the Pre-Development Checklist that are relevant to your task. The index is NOT the goal — it points you to the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`). Read those files to understand the coding standards and patterns.
+
+5. **Always read shared guides**:
+   ```bash
+   cat .trellis/spec/guides/index.md
+   ```
+
+6. Understand the coding standards and patterns you need to follow, then proceed with your development plan.
+
+This step is **mandatory** before writing any code.

package/dist/templates/opencode/commands/trellis/check.md

@@ -0,0 +1,25 @@
+Check if the code you just wrote follows the development guidelines.
+
+Execute these steps:
+
+1. **Identify changed files**:
+   ```bash
+   git diff --name-only HEAD
+   ```
+
+2. **Determine which spec modules apply** based on the changed file paths:
+   ```bash
+   python3 ./.trellis/scripts/get_context.py --mode packages
+   ```
+
+3. **Read the spec index** for each relevant module:
+   ```bash
+   cat .trellis/spec/<package>/<layer>/index.md
+   ```
+   Follow the **"Quality Check"** section in the index.
+
+4. **Read the specific guideline files** referenced in the Quality Check section (e.g., `quality-guidelines.md`, `conventions.md`). The index is NOT the goal — it points you to the actual guideline files. Read those files and review your code against them.
+
+5. **Run lint and typecheck** for the affected package.
+
+6. **Report any violations** and fix them if found.

package/dist/templates/opencode/commands/trellis/create-command.md

@@ -101,8 +101,8 @@ Description:
 | Command Type | Prefix | Example |
 |--------------|--------|---------|
 | Session Start | `start` | `start` |
-| Pre-development | `before-` | `before-frontend-dev` |
-| Check | `check-` | `check-frontend` |
+| Pre-development | `before-` | `before-dev` |
+| Check | `check-` | `check` |
 | Record | `record-` | `record-session` |
 | Generate | `generate-` | `generate-api-doc` |
 | Update | `update-` | `update-changelog` |

package/dist/templates/opencode/commands/trellis/onboard.md

@@ -126,13 +126,13 @@ AI needs the same onboarding - but compressed into seconds at session start.
 
 ---
 
-### /trellis:before-frontend-dev and /trellis:before-backend-dev - Inject Specialized Knowledge
+### /trellis:before-dev - Inject Specialized Knowledge
 
 **WHY IT EXISTS**:
 AI models have "pre-trained knowledge" - general patterns from millions of codebases. But YOUR project has specific conventions that differ from generic patterns.
 
 **WHAT IT ACTUALLY DOES**:
-1. Reads `.trellis/spec/frontend/` or `.trellis/spec/backend/`
+1. Discovers spec layers via `get_context.py --mode packages` and reads relevant guidelines
 2. Loads project-specific patterns into AI's working context:
    - Component naming conventions
    - State management patterns
@@ -140,12 +140,12 @@ AI models have "pre-trained knowledge" - general patterns from millions of codeb
    - Error handling standards
 
 **WHY THIS MATTERS**:
-- Without before-*-dev: AI writes generic code that doesn't match project style.
-- With before-*-dev: AI writes code that looks like the rest of the codebase.
+- Without before-dev: AI writes generic code that doesn't match project style.
+- With before-dev: AI writes code that looks like the rest of the codebase.
 
 ---
 
-### /trellis:check-frontend and /trellis:check-backend - Combat Context Drift
+### /trellis:check - Combat Context Drift
 
 **WHY IT EXISTS**:
 AI context window has limited capacity. As conversation progresses, guidelines injected at session start become less influential. This causes "context drift."
@@ -211,9 +211,9 @@ All the context AI built during this session will be lost when session ends. The
 
 **[1/8] /trellis:start** - AI needs project context before touching code
 **[2/8] python3 ./.trellis/scripts/task.py create "Fix bug" --slug fix-bug** - Track work for future reference
-**[3/8] /trellis:before-frontend-dev** - Inject project-specific frontend knowledge
+**[3/8] /trellis:before-dev** - Inject project-specific development guidelines
 **[4/8] Investigate and fix the bug** - Actual development work
-**[5/8] /trellis:check-frontend** - Re-verify code against guidelines
+**[5/8] /trellis:check** - Re-verify code against guidelines
 **[6/8] /trellis:finish-work** - Holistic cross-layer review
 **[7/8] Human tests and commits** - Human validates before code enters repo
 **[8/8] /trellis:record-session** - Persist memory for future sessions
@@ -228,9 +228,9 @@ All the context AI built during this session will be lost when session ends. The
 ### Example 3: Code Review Fixes
 
 **[1/6] /trellis:start** - Resume context from previous session
-**[2/6] /trellis:before-backend-dev** - Re-inject guidelines before fixes
+**[2/6] /trellis:before-dev** - Re-inject guidelines before fixes
 **[3/6] Fix each CR issue** - Address feedback with guidelines in context
-**[4/6] /trellis:check-backend** - Verify fixes didn't introduce new issues
+**[4/6] /trellis:check** - Verify fixes did not introduce new issues
 **[5/6] /trellis:finish-work** - Document lessons from CR
 **[6/6] Human commits, then /trellis:record-session** - Preserve CR lessons
 
@@ -238,16 +238,16 @@ All the context AI built during this session will be lost when session ends. The
 
 **[1/5] /trellis:start** - Clear baseline before major changes
 **[2/5] Plan phases** - Break into verifiable chunks
-**[3/5] Execute phase by phase with /check-* after each** - Incremental verification
+**[3/5] Execute phase by phase with /trellis:check after each** - Incremental verification
 **[4/5] /trellis:finish-work** - Check if new patterns should be documented
 **[5/5] Record with multiple commit hashes** - Link all commits to one feature
 
 ### Example 5: Debug Session
 
 **[1/6] /trellis:start** - See if this bug was investigated before
-**[2/6] /trellis:before-backend-dev** - Guidelines might document known gotchas
+**[2/6] /trellis:before-dev** - Guidelines might document known gotchas
 **[3/6] Investigation** - Actual debugging work
-**[4/6] /trellis:check-backend** - Verify debug changes don't break other things
+**[4/6] /trellis:check** - Verify debug changes do not break other things
 **[5/6] /trellis:finish-work** - Debug findings might need documentation
 **[6/6] Human commits, then /trellis:record-session** - Debug knowledge is valuable
 
@@ -256,7 +256,7 @@ All the context AI built during this session will be lost when session ends. The
 ## KEY RULES TO EMPHASIZE
 
 1. **AI NEVER commits** - Human tests and approves. AI prepares, human validates.
-2. **Guidelines before code** - /before-*-dev commands inject project knowledge.
+2. **Guidelines before code** - /before-dev command injects project knowledge.
 3. **Check after code** - /check-* commands catch context drift.
 4. **Record everything** - /trellis:record-session persists memory.
 

package/dist/templates/opencode/commands/trellis/parallel.md

@@ -41,8 +41,7 @@ python3 ./.trellis/scripts/get_context.py
 ### Step 3: Read Project Guidelines `[AI]`
 
 ```bash
-cat .trellis/spec/frontend/index.md  # Frontend guidelines index
-cat .trellis/spec/backend/index.md   # Backend guidelines index
+python3 ./.trellis/scripts/get_context.py --mode packages  # Discover available spec layers
 cat .trellis/spec/guides/index.md    # Thinking guides
 ```
 

package/dist/templates/opencode/commands/trellis/record-session.md

@@ -31,7 +31,7 @@ python3 ./.trellis/scripts/add_session.py \
   --summary "Brief summary of what was done"
 
 # Method 2: Pass detailed content via stdin
-cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash"
+cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --stdin --title "Title" --commit "hash"
 | Feature | Description |
 |---------|-------------|
 | New API | Added user authentication endpoint |
@@ -46,6 +46,7 @@ EOF
 **Auto-completes**:
 - [OK] Appends session to journal-N.md
 - [OK] Auto-detects line count, creates new file if >2000 lines
+- [OK] Auto-detects Branch context (`--branch` override; otherwise Branch = task.json -> current git branch; missing values are omitted gracefully)
 - [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history)
 - [OK] Auto-commits .trellis/workspace and .trellis/tasks changes
 
@@ -56,6 +57,6 @@ EOF
 | Command | Purpose |
 |---------|---------|
 | `python3 ./.trellis/scripts/get_context.py --mode record` | Get context for record-session |
-| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended)** |
+| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended, branch auto-complete)** |
 | `python3 ./.trellis/scripts/task.py archive <name>` | Archive completed task (auto-commits) |
 | `python3 ./.trellis/scripts/task.py list` | List active tasks |

package/dist/templates/opencode/commands/trellis/start.md

@@ -40,9 +40,14 @@ This shows: developer identity, git status, current task (if any), active tasks.
 ### Step 3: Read Guidelines Index
 
 ```bash
-cat .trellis/spec/frontend/index.md  # Frontend guidelines
-cat .trellis/spec/backend/index.md   # Backend guidelines
-cat .trellis/spec/guides/index.md    # Thinking guides
+python3 ./.trellis/scripts/get_context.py --mode packages
+```
+
+This shows available packages and their spec layers. Read the relevant spec indexes:
+
+```bash
+cat .trellis/spec/<package>/<layer>/index.md   # Package-specific guidelines
+cat .trellis/spec/guides/index.md              # Thinking guides (always read)
 ```
 
 > **Important**: The index files are navigation — they list the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`).