@mindfoldhq/trellis 0.3.10-beta.0 → 0.3.10

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

@@ -119,151 +119,6 @@ def _get_task_status(trellis_dir: Path) -> str:
     return f"Status: READY\nTask: {task_title}\nNext: Continue with implement or check"
 
 
-def _load_trellis_config(trellis_dir: Path) -> tuple:
-    """Load Trellis config for session-start decisions.
-
-    Returns:
-        (is_mono, packages_dict, spec_scope, task_pkg, default_pkg)
-    """
-    scripts_dir = trellis_dir / "scripts"
-    if str(scripts_dir) not in sys.path:
-        sys.path.insert(0, str(scripts_dir))
-
-    try:
-        from common.config import get_default_package, get_packages, get_spec_scope, is_monorepo
-        from common.paths import get_current_task
-
-        repo_root = trellis_dir.parent
-        is_mono = is_monorepo(repo_root)
-        packages = get_packages(repo_root) or {}
-        scope = get_spec_scope(repo_root)
-
-        # Get active task's package
-        task_pkg = None
-        current = get_current_task(repo_root)
-        if current:
-            task_json = repo_root / current / "task.json"
-            if task_json.is_file():
-                try:
-                    data = json.loads(task_json.read_text(encoding="utf-8"))
-                    if isinstance(data, dict):
-                        tp = data.get("package")
-                        if isinstance(tp, str) and tp:
-                            task_pkg = tp
-                except (json.JSONDecodeError, OSError):
-                    pass
-
-        default_pkg = get_default_package(repo_root)
-        return is_mono, packages, scope, task_pkg, default_pkg
-    except Exception:
-        return False, {}, None, None, None
-
-
-def _check_legacy_spec(trellis_dir: Path, is_mono: bool, packages: dict) -> str | None:
-    """Check for legacy spec directory structure in monorepo.
-
-    Returns warning message if legacy structure detected, None otherwise.
-    """
-    if not is_mono or not packages:
-        return None
-
-    spec_dir = trellis_dir / "spec"
-    if not spec_dir.is_dir():
-        return None
-
-    # Check for legacy flat spec dirs (spec/backend/, spec/frontend/ with index.md)
-    has_legacy = False
-    for legacy_name in ("backend", "frontend"):
-        legacy_dir = spec_dir / legacy_name
-        if legacy_dir.is_dir() and (legacy_dir / "index.md").is_file():
-            has_legacy = True
-            break
-
-    if not has_legacy:
-        return None
-
-    # Check which packages are missing spec/<pkg>/ directory
-    missing = [
-        name for name in sorted(packages.keys())
-        if not (spec_dir / name).is_dir()
-    ]
-
-    if not missing:
-        return None  # All packages have spec dirs
-
-    if len(missing) == len(packages):
-        return (
-            f"[!] Legacy spec structure detected: found `spec/backend/` or `spec/frontend/` "
-            f"but no package-scoped `spec/<package>/` directories.\n"
-            f"Monorepo packages: {', '.join(sorted(packages.keys()))}\n"
-            f"Please reorganize: `spec/backend/` -> `spec/<package>/backend/`"
-        )
-    return (
-        f"[!] Partial spec migration detected: packages {', '.join(missing)} "
-        f"still missing `spec/<pkg>/` directory.\n"
-        f"Please complete migration for all packages."
-    )
-
-
-def _resolve_spec_scope(
-    is_mono: bool,
-    packages: dict,
-    scope,
-    task_pkg: str | None,
-    default_pkg: str | None,
-) -> set | None:
-    """Resolve which packages should have their specs injected.
-
-    Returns:
-        Set of package names to include, or None for full scan.
-    """
-    if not is_mono or not packages:
-        return None  # Single-repo: full scan
-
-    if scope is None:
-        return None  # No scope configured: full scan
-
-    if isinstance(scope, str) and scope == "active_task":
-        if task_pkg and task_pkg in packages:
-            return {task_pkg}
-        if default_pkg and default_pkg in packages:
-            return {default_pkg}
-        return None  # Fallback to full scan
-
-    if isinstance(scope, list):
-        valid = set()
-        for entry in scope:
-            if entry in packages:
-                valid.add(entry)
-            else:
-                print(
-                    f"Warning: spec_scope contains unknown package: {entry}, ignoring",
-                    file=sys.stderr,
-                )
-
-        if valid:
-            # Warn if active task is out of scope
-            if task_pkg and task_pkg not in valid:
-                print(
-                    f"Warning: active task package '{task_pkg}' is out of configured spec_scope",
-                    file=sys.stderr,
-                )
-            return valid
-
-        # All entries invalid: fallback chain
-        print(
-            "Warning: all spec_scope entries invalid, falling back to task/default/full",
-            file=sys.stderr,
-        )
-        if task_pkg and task_pkg in packages:
-            return {task_pkg}
-        if default_pkg and default_pkg in packages:
-            return {default_pkg}
-        return None  # Full scan
-
-    return None  # Unknown scope type: full scan
-
-
 def main():
     if should_skip_injection():
         sys.exit(0)
@@ -272,10 +127,6 @@ def main():
     trellis_dir = project_dir / ".trellis"
     claude_dir = project_dir / ".claude"
 
-    # Load config for scope filtering and legacy detection
-    is_mono, packages, scope_config, task_pkg, default_pkg = _load_trellis_config(trellis_dir)
-    allowed_pkgs = _resolve_spec_scope(is_mono, packages, scope_config, task_pkg, default_pkg)
-
     output = StringIO()
 
     output.write("""<session-context>
@@ -285,11 +136,6 @@ Read and follow all instructions below carefully.
 
 """)
 
-    # Legacy migration warning
-    legacy_warning = _check_legacy_spec(trellis_dir, is_mono, packages)
-    if legacy_warning:
-        output.write(f"<migration-warning>\n{legacy_warning}\n</migration-warning>\n\n")
-
     output.write("<current-state>\n")
     context_script = trellis_dir / "scripts" / "get_context.py"
     output.write(run_script(context_script))
@@ -309,27 +155,13 @@ Read and follow all instructions below carefully.
         for sub in sorted(spec_dir.iterdir()):
             if not sub.is_dir() or sub.name.startswith("."):
                 continue
-
-            # Always include guides/ regardless of scope
-            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():
-                # Flat spec dir (single-repo layer like spec/backend/)
                 output.write(f"## {sub.name}\n")
                 output.write(read_file(index_file))
                 output.write("\n\n")
             else:
-                # Nested package dirs (monorepo: spec/<pkg>/<layer>/index.md)
-                # Apply scope filter
-                if allowed_pkgs is not None and sub.name not in allowed_pkgs:
-                    continue
+                # Check for nested package dirs (monorepo: spec/<pkg>/<layer>/index.md)
                 for nested in sorted(sub.iterdir()):
                     if not nested.is_dir():
                         continue
@@ -348,7 +180,7 @@ Read and follow all instructions below carefully.
     output.write(start_md)
     output.write("\n</instructions>\n\n")
 
-    # Check task status and inject structured tag
+    # R2: Check task status and inject structured tag
     task_status = _get_task_status(trellis_dir)
     output.write(f"<task-status>\n{task_status}\n</task-status>\n\n")
 

package/dist/templates/codex/skills/before-backend-dev/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: before-backend-dev
+description: "Read the backend development guidelines before starting your development task."
+---
+
+Read the backend development guidelines before starting your development task.
+
+Execute these steps:
+1. Read `.trellis/spec/backend/index.md` to understand available guidelines
+2. Based on your task, read the relevant guideline files:
+   - Database work → `.trellis/spec/backend/database-guidelines.md`
+   - Error handling → `.trellis/spec/backend/error-handling.md`
+   - Logging → `.trellis/spec/backend/logging-guidelines.md`
+   - Type questions → `.trellis/spec/backend/type-safety.md`
+3. Understand the coding standards and patterns you need to follow
+4. Then proceed with your development plan
+
+This step is **mandatory** before writing any backend code.

package/dist/templates/codex/skills/before-frontend-dev/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: before-frontend-dev
+description: "Read the frontend development guidelines before starting your development task."
+---
+
+Read the frontend development guidelines before starting your development task.
+
+Execute these steps:
+1. Read `.trellis/spec/frontend/index.md` to understand available guidelines
+2. Based on your task, read the relevant guideline files:
+   - Component work → `.trellis/spec/frontend/component-guidelines.md`
+   - Hook work → `.trellis/spec/frontend/hook-guidelines.md`
+   - State management → `.trellis/spec/frontend/state-management.md`
+   - Type questions → `.trellis/spec/frontend/type-safety.md`
+3. Understand the coding standards and patterns you need to follow
+4. Then proceed with your development plan
+
+This step is **mandatory** before writing any frontend code.

package/dist/templates/codex/skills/check-backend/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: check-backend
+description: "Check if the code you just wrote follows the backend development guidelines."
+---
+
+Check if the code you just wrote follows the backend development guidelines.
+
+Execute these steps:
+1. Run `git status` to see modified files
+2. Read `.trellis/spec/backend/index.md` to understand which guidelines apply
+3. Based on what you changed, read the relevant guideline files:
+   - Database changes → `.trellis/spec/backend/database-guidelines.md`
+   - Error handling → `.trellis/spec/backend/error-handling.md`
+   - Logging changes → `.trellis/spec/backend/logging-guidelines.md`
+   - Type changes → `.trellis/spec/backend/type-safety.md`
+   - Any changes → `.trellis/spec/backend/quality-guidelines.md`
+4. Review your code against the guidelines
+5. Report any violations and fix them if found

package/dist/templates/codex/skills/check-frontend/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: check-frontend
+description: "Check if the code you just wrote follows the frontend development guidelines."
+---
+
+Check if the code you just wrote follows the frontend development guidelines.
+
+Execute these steps:
+1. Run `git status` to see modified files
+2. Read `.trellis/spec/frontend/index.md` to understand which guidelines apply
+3. Based on what you changed, read the relevant guideline files:
+   - Component changes → `.trellis/spec/frontend/component-guidelines.md`
+   - Hook changes → `.trellis/spec/frontend/hook-guidelines.md`
+   - State changes → `.trellis/spec/frontend/state-management.md`
+   - Type changes → `.trellis/spec/frontend/type-safety.md`
+   - Any changes → `.trellis/spec/frontend/quality-guidelines.md`
+4. Review your code against the guidelines
+5. Report any violations and fix them if found

package/dist/templates/codex/skills/create-command/SKILL.md

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

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

@@ -131,13 +131,13 @@ AI needs the same onboarding - but compressed into seconds at session start.
 
 ---
 
-### $before-dev - Inject Specialized Knowledge
+### $before-frontend-dev and $before-backend-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. Discovers spec layers via `get_context.py --mode packages` and reads relevant guidelines
+1. Reads `.trellis/spec/frontend/` or `.trellis/spec/backend/`
 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 - Combat Context Drift
+### $check-frontend and $check-backend - 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-dev** - Inject project-specific development guidelines
+**[3/8] $before-frontend-dev** - Inject project-specific frontend knowledge
 **[4/8] Investigate and fix the bug** - Actual development work
-**[5/8] $check** - Re-verify code against guidelines
+**[5/8] $check-frontend** - 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-dev** - Re-inject guidelines before fixes
+**[2/6] $before-backend-dev** - Re-inject guidelines before fixes
 **[3/6] Fix each CR issue** - Address feedback with guidelines in context
-**[4/6] $check** - Verify fixes did not introduce new issues
+**[4/6] $check-backend** - Verify fixes didn't 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-dev** - Guidelines might document known gotchas
+**[2/6] $before-backend-dev** - Guidelines might document known gotchas
 **[3/6] Investigation** - Actual debugging work
-**[4/6] $check** - Verify debug changes do not break other things
+**[4/6] $check-backend** - Verify debug changes don't 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/codex/skills/record-session/SKILL.md

@@ -5,7 +5,7 @@ description: "Record work progress after human has tested and committed code"
 
 [!] **Prerequisite**: This skill should only be used AFTER the human has tested and committed the code.
 
-**AI must NOT execute git commit** - only read history (`git log`, `git status`, `git diff`).
+**Do NOT run `git commit` directly** — the scripts below handle their own commits for `.trellis/` metadata. You only need to read git history (`git log`, `git status`, `git diff`) and run the Python scripts.
 
 ---
 
@@ -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 --stdin --title "Title" --commit "hash"
+cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash"
 | Feature | Description |
 |---------|-------------|
 | New API | Added user authentication endpoint |

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

@@ -45,14 +45,9 @@ This shows: developer identity, git status, current task (if any), active tasks.
 ### Step 3: Read Guidelines Index
 
 ```bash
-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)
+cat .trellis/spec/frontend/index.md  # Frontend guidelines
+cat .trellis/spec/backend/index.md   # Backend guidelines
+cat .trellis/spec/guides/index.md    # Thinking guides
 ```
 
 > **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/cursor/commands/trellis-before-backend-dev.md

@@ -0,0 +1,13 @@
+Read the backend development guidelines before starting your development task.
+
+Execute these steps:
+1. Read `.trellis/spec/backend/index.md` to understand available guidelines
+2. Based on your task, read the relevant guideline files:
+   - Database work → `.trellis/spec/backend/database-guidelines.md`
+   - Error handling → `.trellis/spec/backend/error-handling.md`
+   - Logging → `.trellis/spec/backend/logging-guidelines.md`
+   - Type questions → `.trellis/spec/backend/type-safety.md`
+3. Understand the coding standards and patterns you need to follow
+4. Then proceed with your development plan
+
+This step is **mandatory** before writing any backend code.

package/dist/templates/cursor/commands/trellis-before-frontend-dev.md

@@ -0,0 +1,13 @@
+Read the frontend development guidelines before starting your development task.
+
+Execute these steps:
+1. Read `.trellis/spec/frontend/index.md` to understand available guidelines
+2. Based on your task, read the relevant guideline files:
+   - Component work → `.trellis/spec/frontend/component-guidelines.md`
+   - Hook work → `.trellis/spec/frontend/hook-guidelines.md`
+   - State management → `.trellis/spec/frontend/state-management.md`
+   - Type questions → `.trellis/spec/frontend/type-safety.md`
+3. Understand the coding standards and patterns you need to follow
+4. Then proceed with your development plan
+
+This step is **mandatory** before writing any frontend code.

package/dist/templates/cursor/commands/trellis-check-backend.md

@@ -0,0 +1,13 @@
+Check if the code you just wrote follows the backend development guidelines.
+
+Execute these steps:
+1. Run `git status` to see modified files
+2. Read `.trellis/spec/backend/index.md` to understand which guidelines apply
+3. Based on what you changed, read the relevant guideline files:
+   - Database changes → `.trellis/spec/backend/database-guidelines.md`
+   - Error handling → `.trellis/spec/backend/error-handling.md`
+   - Logging changes → `.trellis/spec/backend/logging-guidelines.md`
+   - Type changes → `.trellis/spec/backend/type-safety.md`
+   - Any changes → `.trellis/spec/backend/quality-guidelines.md`
+4. Review your code against the guidelines
+5. Report any violations and fix them if found

package/dist/templates/cursor/commands/trellis-check-frontend.md

@@ -0,0 +1,13 @@
+Check if the code you just wrote follows the frontend development guidelines.
+
+Execute these steps:
+1. Run `git status` to see modified files
+2. Read `.trellis/spec/frontend/index.md` to understand which guidelines apply
+3. Based on what you changed, read the relevant guideline files:
+   - Component changes → `.trellis/spec/frontend/component-guidelines.md`
+   - Hook changes → `.trellis/spec/frontend/hook-guidelines.md`
+   - State changes → `.trellis/spec/frontend/state-management.md`
+   - Type changes → `.trellis/spec/frontend/type-safety.md`
+   - Any changes → `.trellis/spec/frontend/quality-guidelines.md`
+4. Review your code against the guidelines
+5. Report any violations and fix them if found

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

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

package/dist/templates/cursor/commands/trellis-onboard.md

@@ -126,13 +126,13 @@ AI needs the same onboarding - but compressed into seconds at session start.
 
 ---
 
-### /trellis-before-dev - Inject Specialized Knowledge
+### /trellis-before-frontend-dev and /trellis-before-backend-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. Discovers spec layers via `get_context.py --mode packages` and reads relevant guidelines
+1. Reads `.trellis/spec/frontend/` or `.trellis/spec/backend/`
 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 - Combat Context Drift
+### /trellis-check-frontend and /trellis-check-backend - 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-dev** - Inject project-specific development guidelines
+**[3/8] /trellis-before-frontend-dev** - Inject project-specific frontend knowledge
 **[4/8] Investigate and fix the bug** - Actual development work
-**[5/8] /trellis-check** - Re-verify code against guidelines
+**[5/8] /trellis-check-frontend** - 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-dev** - Re-inject guidelines before fixes
+**[2/6] /trellis-before-backend-dev** - Re-inject guidelines before fixes
 **[3/6] Fix each CR issue** - Address feedback with guidelines in context
-**[4/6] /trellis-check** - Verify fixes did not introduce new issues
+**[4/6] /trellis-check-backend** - Verify fixes didn't 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 /trellis-check after each** - Incremental verification
+**[3/5] Execute phase by phase with /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-dev** - Guidelines might document known gotchas
+**[2/6] /trellis-before-backend-dev** - Guidelines might document known gotchas
 **[3/6] Investigation** - Actual debugging work
-**[4/6] /trellis-check** - Verify debug changes do not break other things
+**[4/6] /trellis-check-backend** - Verify debug changes don't 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 command injects project knowledge.
+2. **Guidelines before code** - /before-*-dev commands inject project knowledge.
 3. **Check after code** - /check-* commands catch context drift.
 4. **Record everything** - /trellis-record-session persists memory.
 

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

@@ -1,6 +1,6 @@
 [!] **Prerequisite**: This command should only be used AFTER the human has tested and committed the code.
 
-**AI must NOT execute git commit** - only read history (`git log`, `git status`, `git diff`).
+**Do NOT run `git commit` directly** — the scripts below handle their own commits for `.trellis/` metadata. You only need to read git history (`git log`, `git status`, `git diff`) and run the Python scripts.
 
 ---
 
@@ -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 --stdin --title "Title" --commit "hash"
+cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash"
 | Feature | Description |
 |---------|-------------|
 | New API | Added user authentication endpoint |

package/dist/templates/cursor/commands/trellis-start.md

@@ -38,17 +38,24 @@ This returns:
 - Active tasks
 - Journal file status
 
-### Step 3: Read Guidelines Index `[AI]`
+### Step 3: Read Project Code-Spec Index `[AI]`
 
+Based on the upcoming task, read appropriate code-spec docs:
+
+**For Frontend Work**:
 ```bash
-python3 ./.trellis/scripts/get_context.py --mode packages
+cat .trellis/spec/frontend/index.md
 ```
 
-This shows available packages and their spec layers. Read the relevant spec indexes:
+**For Backend Work**:
+```bash
+cat .trellis/spec/backend/index.md
+```
 
+**For Cross-Layer Features**:
 ```bash
-cat .trellis/spec/<package>/<layer>/index.md   # Package-specific guidelines
-cat .trellis/spec/guides/index.md              # Thinking guides (always read)
+cat .trellis/spec/guides/index.md
+cat .trellis/spec/guides/cross-layer-thinking-guide.md
 ```
 
 > **Important**: The index files are navigation — they list the actual guideline files (e.g., `error-handling.md`, `conventions.md`, `mock-strategies.md`).
@@ -324,8 +331,10 @@ The following slash commands are for users (not AI):
 |---------|-------------|
 | `/trellis-start` | Start development session (this command) |
 | `/trellis-brainstorm` | Clarify vague requirements before implementation |
-| `/trellis-before-dev` | Read development guidelines |
-| `/trellis-check` | Check code quality |
+| `/trellis-before-frontend-dev` | Read frontend guidelines |
+| `/trellis-before-backend-dev` | Read backend guidelines |
+| `/trellis-check-frontend` | Check frontend code |
+| `/trellis-check-backend` | Check backend code |
 | `/trellis-check-cross-layer` | Cross-layer verification |
 | `/trellis-finish-work` | Pre-commit checklist |
 | `/trellis-record-session` | Record session progress |

package/dist/templates/gemini/commands/trellis/before-backend-dev.toml

@@ -0,0 +1,17 @@
+description = "Read backend development guidelines before starting your task"
+
+prompt = """
+Read the backend development guidelines before starting your development task.
+
+Execute these steps:
+1. Read `.trellis/spec/backend/index.md` to understand available guidelines
+2. Based on your task, read the relevant guideline files:
+   - Database work -> `.trellis/spec/backend/database-guidelines.md`
+   - Error handling -> `.trellis/spec/backend/error-handling.md`
+   - Logging -> `.trellis/spec/backend/logging-guidelines.md`
+   - Type questions -> `.trellis/spec/backend/type-safety.md`
+3. Understand the coding standards and patterns you need to follow
+4. Then proceed with your development plan
+
+This step is **mandatory** before writing any backend code.
+"""