@mindfoldhq/trellis 0.3.10 → 0.4.0-beta.10

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

@@ -66,23 +66,47 @@ def run_script(script_path: Path) -> str:
         return "No context available"
 
 
+def _normalize_task_ref(task_ref: str) -> str:
+    normalized = task_ref.strip()
+    if not normalized:
+        return ""
+
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return str(path_obj)
+
+    normalized = normalized.replace("\\", "/")
+    while normalized.startswith("./"):
+        normalized = normalized[2:]
+
+    if normalized.startswith("tasks/"):
+        return f".trellis/{normalized}"
+
+    return normalized
+
+
+def _resolve_task_dir(trellis_dir: Path, task_ref: str) -> Path:
+    normalized = _normalize_task_ref(task_ref)
+    path_obj = Path(normalized)
+    if path_obj.is_absolute():
+        return path_obj
+    if normalized.startswith(".trellis/"):
+        return trellis_dir.parent / path_obj
+    return trellis_dir / "tasks" / path_obj
+
+
 def _get_task_status(trellis_dir: Path) -> str:
     """Check current task status and return structured status string."""
     current_task_file = trellis_dir / ".current-task"
     if not current_task_file.is_file():
         return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on"
 
-    task_ref = current_task_file.read_text(encoding="utf-8").strip()
+    task_ref = _normalize_task_ref(current_task_file.read_text(encoding="utf-8").strip())
     if not task_ref:
         return "Status: NO ACTIVE TASK\nNext: Describe what you want to work on"
 
     # Resolve task directory
-    if Path(task_ref).is_absolute():
-        task_dir = Path(task_ref)
-    elif task_ref.startswith(".trellis/"):
-        task_dir = trellis_dir.parent / task_ref
-    else:
-        task_dir = trellis_dir / "tasks" / task_ref
+    task_dir = _resolve_task_dir(trellis_dir, task_ref)
     if not task_dir.is_dir():
         return f"Status: STALE POINTER\nTask: {task_ref}\nNext: Task directory not found. Run: python3 ./.trellis/scripts/task.py finish"
 
@@ -120,6 +144,140 @@ 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  # type: ignore[import-not-found]
+        from common.paths import get_current_task  # type: ignore[import-not-found]
+
+        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."""
+    if not is_mono or not packages:
+        return None
+
+    spec_dir = trellis_dir / "spec"
+    if not spec_dir.is_dir():
+        return None
+
+    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
+
+    missing = [
+        name for name in sorted(packages.keys())
+        if not (spec_dir / name).is_dir()
+    ]
+
+    if not missing:
+        return None
+
+    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."""
+    if not is_mono or not packages:
+        return None
+
+    if scope is None:
+        return None
+
+    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
+
+    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:
+            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
+
+        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
+
+    return None
+
+
 def main():
     if should_skip_injection():
         sys.exit(0)
@@ -129,6 +287,10 @@ def main():
     trellis_dir = project_dir / ".trellis"
     iflow_dir = project_dir / ".iflow"
 
+    # 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>
@@ -138,6 +300,11 @@ 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))
@@ -157,13 +324,25 @@ 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():
                 output.write(f"## {sub.name}\n")
                 output.write(read_file(index_file))
                 output.write("\n\n")
             else:
-                # Check for nested package dirs (monorepo: spec/<pkg>/<layer>/index.md)
+                # Apply scope filter for monorepo packages
+                if allowed_pkgs is not None and sub.name not in allowed_pkgs:
+                    continue
                 for nested in sorted(sub.iterdir()):
                     if not nested.is_dir():
                         continue

package/dist/templates/kilo/workflows/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/kilo/workflows/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/kilo/workflows/create-command.md

@@ -99,8 +99,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/kilo/workflows/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/kilo/workflows/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/kilo/workflows/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/kilo/workflows/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`).

package/dist/templates/kiro/skills/before-dev/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: before-dev
+description: "Discovers and injects project-specific coding guidelines from .trellis/spec/ before implementation begins. Reads spec indexes, pre-development checklists, and shared thinking guides for the target package. Use when starting a new coding task, before writing any code, switching to a different package, or needing to refresh project conventions and standards."
+---
+
+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/kiro/skills/brainstorm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorm
-description: "Brainstorm - Requirements Discovery (AI Coding Enhanced)"
+description: "Collaborative requirements discovery session optimized for AI coding workflows. Creates task directories, seeds PRDs, runs codebase research, proposes concrete implementation approaches with trade-offs, and converges on MVP scope through structured Q&A. Use when requirements are unclear, multiple implementation paths exist, trade-offs need evaluation, or a complex feature needs scoping before development."
 ---
 
 # Brainstorm - Requirements Discovery (AI Coding Enhanced)

package/dist/templates/kiro/skills/break-loop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: break-loop
-description: "Break the Loop - Deep Bug Analysis"
+description: "Deep post-fix bug analysis across five dimensions: root cause categorization, fix failure analysis, prevention mechanisms, systematic expansion, and knowledge capture. Updates .trellis/spec/ guides with lessons learned to prevent recurring bugs. Use when a debugging session completes, after fixing a tricky bug, when the same class of bug keeps recurring, or when you want to capture debugging insights into project documentation."
 ---
 
 # Break the Loop - Deep Bug Analysis

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

@@ -0,0 +1,30 @@
+---
+name: check
+description: "Validates recently written code against project-specific development guidelines from .trellis/spec/. Identifies changed files via git diff, discovers applicable spec modules, runs lint and typecheck, and reports guideline violations. Use when code is written and needs quality verification, to catch context drift during long sessions, or before committing changes."
+---
+
+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/kiro/skills/check-cross-layer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: check-cross-layer
-description: "Cross-Layer Check"
+description: "Post-implementation verification across multiple code dimensions: cross-layer data flow, code reuse analysis, import path validation, and same-layer consistency checks. Identifies missed update sites, type mismatches, and duplicated constants. Use when changes span 3+ architectural layers, after modifying shared constants or configs, after batch file modifications, or when creating new utility functions."
 ---
 
 # Cross-Layer Check

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

@@ -1,6 +1,6 @@
 ---
 name: create-command
-description: "Create New Skill"
+description: "Scaffolds a new skill file with proper naming conventions and structure. Analyzes requirements to determine skill type and generates appropriate content. Use when adding a new developer workflow skill, creating a custom skill, or extending the Trellis skill set."
 ---
 
 # Create New Skill
@@ -93,8 +93,8 @@ Description:
 | Skill 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/kiro/skills/finish-work/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: finish-work
-description: "Finish Work - Pre-Commit Checklist"
+description: "Pre-commit quality checklist covering lint, typecheck, tests, code-spec sync, API changes, database migrations, cross-layer verification, and manual testing. Blocks commit if infra or cross-layer specs lack executable depth. Use when code is written and tested but not yet committed, before submitting changes, or as a final review before git commit."
 ---
 
 # Finish Work - Pre-Commit Checklist

package/dist/templates/kiro/skills/integrate-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: integrate-skill
-description: "Integrate Skill into Project Guidelines"
+description: "Adapts an external skill into project-specific development guidelines in .trellis/spec/. Creates guideline sections, code example templates with .template suffix, and updates spec indexes. Use when integrating an external skill, adding a new skill's patterns to project conventions, or incorporating third-party skill best practices into .trellis/spec/ documentation."
 ---
 
 # Integrate Skill into Project Guidelines