llms-py 3.0.10__py3-none-any.whl → 3.0.18__py3-none-any.whl

llms/extensions/skills/parser.py

@@ -0,0 +1,178 @@
+"""YAML frontmatter parsing for SKILL.md files."""
+
+from pathlib import Path
+from typing import Optional
+
+from .errors import ParseError, ValidationError
+from .models import SkillProperties
+
+
+def load_yaml(content: str) -> dict:
+    """Simple YAML parser for skill frontmatter.
+
+    Supports:
+    - Key-value pairs: key: "value"
+    - Comments: # comment
+    - Simple nesting (indentation-based)
+    """
+    result = {}
+    stack = [result]
+    indents = [-1]
+    last_key = None
+
+    for line in content.splitlines():
+        # Skip empty lines or full comments
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+
+        indent = len(line) - len(line.lstrip())
+
+        # Handle indent levels
+        while indent <= indents[-1]:
+            indents.pop()
+            stack.pop()
+
+        # If we have a nested block under last key
+        if indent > indents[-1] and last_key and isinstance(stack[-1], dict) and stack[-1].get(last_key) is None:
+            # This branch is tricky with the simple look-behind.
+            # Better approach: check if line is a key-value or array item
+            pass
+
+        # Parse key: value
+        if ":" in stripped:
+            key, val = stripped.split(":", 1)
+            key = key.strip()
+            val = val.strip()
+
+            # Handle quotes
+            if (val.startswith('"') and val.endswith('"')) or (val.startswith("'") and val.endswith("'")):
+                val = val[1:-1]
+            elif val.lower() == "true":
+                val = True
+            elif val.lower() == "false":
+                val = False
+            elif val == "":
+                val = None  # Could be start of nested object
+
+            current_dict = stack[-1]
+
+            if val is None:
+                # Prepare for nested object
+                new_dict = {}
+                current_dict[key] = new_dict
+                stack.append(new_dict)
+                indents.append(indent)
+            else:
+                current_dict[key] = val
+
+            last_key = key
+        else:
+            # Handle continuation lines or unknown format if needed,
+            # but for our simple use case we might error or ignore.
+            pass
+
+    return result
+
+
+def find_skill_md(skill_dir: Path) -> Optional[Path]:
+    """Find the SKILL.md file in a skill directory.
+
+    Prefers SKILL.md (uppercase) but accepts skill.md (lowercase).
+
+    Args:
+        skill_dir: Path to the skill directory
+
+    Returns:
+        Path to the SKILL.md file, or None if not found
+    """
+    for name in ("SKILL.md", "skill.md"):
+        path = skill_dir / name
+        if path.exists():
+            return path
+    return None
+
+
+def parse_frontmatter(content: str) -> tuple[dict, str]:
+    """Parse YAML frontmatter from SKILL.md content.
+
+    Args:
+        content: Raw content of SKILL.md file
+
+    Returns:
+        Tuple of (metadata dict, markdown body)
+
+    Raises:
+        ParseError: If frontmatter is missing or invalid
+    """
+    if not content.startswith("---"):
+        raise ParseError("SKILL.md must start with YAML frontmatter (---)")
+
+    parts = content.split("---", 2)
+    if len(parts) < 3:
+        raise ParseError("SKILL.md frontmatter not properly closed with ---")
+
+    frontmatter_str = parts[1]
+    body = parts[2].strip()
+
+    try:
+        metadata = load_yaml(frontmatter_str)
+    except Exception as e:
+        raise ParseError(f"Invalid YAML in frontmatter: {e}") from e
+
+    if not isinstance(metadata, dict):
+        raise ParseError("SKILL.md frontmatter must be a YAML mapping")
+
+    # Clean up metadata values if necessary (simple parser already handles basics)
+    if "metadata" in metadata and isinstance(metadata["metadata"], dict):
+        metadata["metadata"] = {str(k): str(v) for k, v in metadata["metadata"].items()}
+
+    return metadata, body
+
+
+def read_properties(skill_dir: Path) -> SkillProperties:
+    """Read skill properties from SKILL.md frontmatter.
+
+    This function parses the frontmatter and returns properties.
+    It does NOT perform full validation. Use validate() for that.
+
+    Args:
+        skill_dir: Path to the skill directory
+
+    Returns:
+        SkillProperties with parsed metadata
+
+    Raises:
+        ParseError: If SKILL.md is missing or has invalid YAML
+        ValidationError: If required fields (name, description) are missing
+    """
+    skill_dir = Path(skill_dir)
+    skill_md = find_skill_md(skill_dir)
+
+    if skill_md is None:
+        raise ParseError(f"SKILL.md not found in {skill_dir}")
+
+    content = skill_md.read_text()
+    metadata, _ = parse_frontmatter(content)
+
+    if "name" not in metadata:
+        raise ValidationError("Missing required field in frontmatter: name")
+    if "description" not in metadata:
+        raise ValidationError("Missing required field in frontmatter: description")
+
+    name = metadata["name"]
+    description = metadata["description"]
+
+    if not isinstance(name, str) or not name.strip():
+        raise ValidationError("Field 'name' must be a non-empty string")
+    if not isinstance(description, str) or not description.strip():
+        raise ValidationError("Field 'description' must be a non-empty string")
+
+    return SkillProperties(
+        name=name.strip(),
+        description=description.strip(),
+        license=metadata.get("license"),
+        compatibility=metadata.get("compatibility"),
+        allowed_tools=metadata.get("allowed-tools"),
+        metadata=metadata.get("metadata"),
+    )

llms/extensions/skills/ui/index.mjs

@@ -0,0 +1,376 @@
+import { ref, inject, computed } from "vue"
+import { leftPart } from "@servicestack/client"
+
+let ext
+
+const SkillSelector = {
+    template: `
+        <div class="px-4 py-4 bg-gray-50 dark:bg-gray-800 border-b border-gray-200 dark:border-gray-700 max-h-[80vh] overflow-y-auto">
+            
+            <!-- Global Controls -->
+            <div class="flex items-center justify-between mb-4">
+                <span class="text-xs font-bold uppercase text-gray-500 tracking-wider">Include Skills</span>
+                <div class="flex items-center gap-2">
+                    <button type="button" v-if="!$ctx.tools?.isToolEnabled('skill')"
+                        class="px-3 py-1 rounded-md text-xs font-medium border transition-colors select-none cursor-pointer bg-white dark:bg-gray-800 text-gray-600 dark:text-gray-400 border-gray-200 dark:border-gray-700 hover:border-gray-300 dark:hover:border-gray-600"
+                        @click="$ctx.tools?.enableTool('skill')"
+                        title="'skill' tool needs to be enabled to use Skills"
+                        >
+                        <span class="text-xs font-semibold text-red-700 dark:text-red-300">⚠️ Enable skill tool</span>
+                    </button>
+                    <button type="button" @click="$ctx.setPrefs({ onlySkills: null })"
+                        class="px-3 py-1 rounded-md text-xs font-medium border transition-colors select-none"
+                        :class="$prefs.onlySkills == null
+                            ? 'bg-green-100 dark:bg-green-900/40 text-green-800 dark:text-green-300 border-green-300 dark:border-green-800' 
+                            : 'cursor-pointer bg-white dark:bg-gray-800 text-gray-600 dark:text-gray-400 border-gray-200 dark:border-gray-700 hover:border-gray-300 dark:hover:border-gray-600'">
+                        All Skills
+                    </button>
+                    <button type="button" @click="$ctx.setPrefs({ onlySkills:[] })"
+                        class="px-3 py-1 rounded-md text-xs font-medium border transition-colors select-none"
+                        :class="$prefs.onlySkills?.length === 0
+                            ? 'bg-fuchsia-100 dark:bg-fuchsia-900/40 text-fuchsia-800 dark:text-fuchsia-300 border-fuchsia-200 dark:border-fuchsia-800' 
+                            : 'cursor-pointer bg-white dark:bg-gray-800 text-gray-600 dark:text-gray-400 border-gray-200 dark:border-gray-700 hover:border-gray-300 dark:hover:border-gray-600'">
+                        No Skills
+                    </button>
+                </div>
+            </div>
+
+            <!-- Groups -->
+            <div class="space-y-3">
+                <div v-for="group in skillGroups" :key="group.name" 
+                     class="bg-white dark:bg-gray-900 rounded-lg border border-gray-200 dark:border-gray-700 overflow-hidden">
+                     
+                     <!-- Group Header -->
+                     <div class="flex items-center justify-between px-3 py-2 bg-gray-50/50 dark:bg-gray-800/50 cursor-pointer hover:bg-gray-100 dark:hover:bg-gray-800 transition-colors"
+                          @click="toggleCollapse(group.name)">
+                        
+                        <div class="flex items-center gap-2 min-w-0">
+                             <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" class="w-4 h-4 text-gray-400 transition-transform duration-200" :class="{ '-rotate-90': isCollapsed(group.name) }">
+                                <path fill-rule="evenodd" d="M5.23 7.21a.75.75 0 011.06.02L10 11.168l3.71-3.938a.75.75 0 111.08 1.04l-4.25 4.5a.75.75 0 01-1.08 0l-4.25-4.5a.75.75 0 01.02-1.06z" clip-rule="evenodd" />
+                             </svg>
+                             <span class="font-semibold text-sm text-gray-700 dark:text-gray-200 truncate">
+                                {{ group.name || 'Other Skills' }}
+                             </span>
+                             <span class="text-xs text-gray-400 font-mono">
+                                {{ getActiveCount(group) }}/{{ group.skills.length }}
+                             </span>
+                        </div>
+
+                        <div class="flex items-center gap-2" @click.stop>
+                             <button @click="setGroupSkills(group, true)" type="button"
+                                title="Include All in Group"
+                                class="px-2 py-0.5 rounded text-xs font-medium border transition-colors select-none"
+                                :class="getActiveCount(group) === group.skills.length
+                                    ? 'bg-green-50 dark:bg-green-900/20 text-green-700 dark:text-green-300 border-green-300 dark:border-green-800 hover:bg-green-100 dark:hover:bg-green-900/40'
+                                    : 'bg-white dark:bg-gray-800 text-gray-600 dark:text-gray-400 border-gray-200 dark:border-gray-700 hover:border-gray-300 dark:hover:border-gray-600'">
+                                all
+                             </button>
+                             <button @click="setGroupSkills(group, false)" type="button"
+                                title="Include None in Group"
+                                class="px-2 py-0.5 rounded text-xs font-medium border transition-colors select-none"
+                                :class="getActiveCount(group) === 0
+                                    ? 'bg-fuchsia-50 dark:bg-fuchsia-900/20 text-fuchsia-700 dark:text-fuchsia-300 border-fuchsia-200 dark:border-fuchsia-800 hover:bg-fuchsia-100 dark:hover:bg-fuchsia-900/40'
+                                    : 'bg-white dark:bg-gray-800 text-gray-600 dark:text-gray-400 border-gray-200 dark:border-gray-700 hover:border-gray-300 dark:hover:border-gray-600'">
+                                none
+                             </button>
+                        </div>
+                     </div>
+                     
+                     <!-- Group Body -->
+                     <div v-show="!isCollapsed(group.name)" class="p-3 bg-white dark:bg-gray-900 border-t border-gray-100 dark:border-gray-800">
+                         <div class="flex flex-wrap gap-2">
+                            <button v-for="skill in group.skills" :key="skill.name" type="button"
+                                @click="toggleSkill(skill.name)"
+                                :title="skill.description"
+                                class="px-2.5 py-1 rounded-full text-xs font-medium border transition-colors select-none text-left truncate max-w-[200px]"
+                                :class="isSkillActive(skill.name)
+                                    ? 'bg-blue-100 dark:bg-blue-900/40 text-blue-800 dark:text-blue-300 border-blue-200 dark:border-blue-800' 
+                                    : 'bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-400 border-gray-200 dark:border-gray-700 hover:border-gray-300 dark:hover:border-gray-600'">
+                                {{ skill.name }}
+                            </button>
+                         </div>
+                     </div>
+                </div>
+            </div>
+        </div>
+    `,
+    setup() {
+        const ctx = inject('ctx')
+        const collapsedState = ref({})
+
+        const availableSkills = computed(() => Object.values(ctx.state.skills || {}))
+
+        const skillGroups = computed(() => {
+            const skills = availableSkills.value
+            const groupsMap = {}
+            const otherSkills = []
+
+            skills.forEach(skill => {
+                if (skill.group) {
+                    if (!groupsMap[skill.group]) groupsMap[skill.group] = []
+                    groupsMap[skill.group].push(skill)
+                } else {
+                    otherSkills.push(skill)
+                }
+            })
+
+            const definedGroups = Object.entries(groupsMap).map(([name, skills]) => ({
+                name,
+                skills
+            }))
+
+            // Sort groups by name if needed, but for now rely on insertion order or backend order
+            definedGroups.sort((a, b) => a.name.localeCompare(b.name))
+
+            if (otherSkills.length > 0) {
+                definedGroups.push({ name: '', skills: otherSkills })
+            }
+
+            return definedGroups
+        })
+
+        function isSkillActive(name) {
+            const only = ctx.prefs.onlySkills
+            if (only == null) return true
+            if (Array.isArray(only)) {
+                return only.includes(name)
+            }
+            return false
+        }
+
+        function toggleSkill(name) {
+            let onlySkills = ctx.prefs.onlySkills
+
+            if (onlySkills == null) {
+                // If currently 'All', clicking a skill means we enter custom mode with all OTHER skills selected (deselecting clicked)
+                // Wait, logic in ToolSelector:
+                // if (onlyTools == null) { onlyTools = availableTools.value.map(t => t.function.name).filter(t => t !== name) }
+                // This means deselecting one tool switches to "custom" with all but that one.
+
+                onlySkills = availableSkills.value.map(s => s.name).filter(s => s !== name)
+            } else {
+                if (onlySkills.includes(name)) {
+                    onlySkills = onlySkills.filter(s => s !== name)
+                } else {
+                    onlySkills = [...onlySkills, name]
+                }
+            }
+
+            ctx.setPrefs({ onlySkills })
+        }
+
+        function toggleCollapse(groupName) {
+            const key = groupName || '_other_'
+            collapsedState.value[key] = !collapsedState.value[key]
+        }
+
+        function isCollapsed(groupName) {
+            const key = groupName || '_other_'
+            return !!collapsedState.value[key]
+        }
+
+        function setGroupSkills(group, enable) {
+            const groupSkillNames = group.skills.map(s => s.name)
+            let onlySkills = ctx.prefs.onlySkills
+
+            if (enable) {
+                if (onlySkills == null) return
+                const newSet = new Set(onlySkills)
+                groupSkillNames.forEach(n => newSet.add(n))
+                onlySkills = Array.from(newSet)
+                if (onlySkills.length === availableSkills.value.length) {
+                    onlySkills = null
+                }
+            } else {
+                if (onlySkills == null) {
+                    onlySkills = availableSkills.value
+                        .map(s => s.name)
+                        .filter(n => !groupSkillNames.includes(n))
+                } else {
+                    onlySkills = onlySkills.filter(n => !groupSkillNames.includes(n))
+                }
+            }
+
+            ctx.setPrefs({ onlySkills })
+        }
+
+        function getActiveCount(group) {
+            const onlySkills = ctx.prefs.onlySkills
+            if (onlySkills == null) return group.skills.length
+            return group.skills.filter(s => onlySkills.includes(s.name)).length
+        }
+
+        return {
+            availableSkills,
+            skillGroups,
+            isSkillActive,
+            toggleSkill,
+            toggleCollapse,
+            isCollapsed,
+            setGroupSkills,
+            getActiveCount
+        }
+    }
+}
+
+function codeFragment(s) {
+    return "`" + s + "`"
+}
+function codeBlock(s) {
+    return "```\n" + s + "\n```\n"
+}
+
+const SkillInstructions = `
+You have access to specialized skills that extend your capabilities with domain-specific knowledge, workflows, and tools. 
+Skills are modular packages containing instructions, scripts, references, and assets for particular tasks.
+
+## Using Skills
+
+Use the skill tool to read a skill's main instructions and guidance, e.g:
+${codeBlock("skill({ name: \"skill-name\" })")}
+
+To read a specific file within a skill (scripts, references, assets):
+${codeBlock("skill({ name: \"skill-name\", file: \"relative/path/to/file\" })")}
+
+Examples:
+- ${codeFragment("skill({ name: \"create-plan\" })")} - Read the create-plan skill's SKILL.md instructions
+- ${codeFragment("skill({ name: \"web-artifacts-builder\", file: \"scripts/init-artifact.sh\" })")} - Read a specific script
+
+## When to Use Skills
+
+You should read the appropriate skill BEFORE starting work on relevant tasks. Skills contain best practices, scripts, and reference materials that significantly improve output quality.
+
+**Skill Selection Guidelines:**
+- Match the task to available skill descriptions
+- Multiple skills may be relevant - read all that apply
+- Read the skill first, then follow its instructions
+
+## Available Skills
+$$AVAILABLE_SKILLS$$
+
+## Important Notes
+
+- Always read the skill BEFORE starting implementation
+- Skills may contain scripts that can be executed directly without loading into context
+- Multiple skills can and should be combined when tasks span multiple domains
+- If a skill references additional files (references/, scripts/, assets/), read those as needed during execution
+`
+
+export default {
+    order: 15 - 100,
+
+    install(ctx) {
+        ext = ctx.scope("skills")
+
+        ctx.components({ SkillSelector })
+
+        const svg = (attrs, title) => `<svg ${attrs} xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">${title ? "<title>" + title + "</title>" : ''}<path fill="currentColor" d="M20 17a2 2 0 0 0 2-2V4a2 2 0 0 0-2-2H9.46c.35.61.54 1.3.54 2h10v11h-9v2m4-10v2H9v13H7v-6H5v6H3v-8H1.5V9a2 2 0 0 1 2-2zM8 4a2 2 0 0 1-2 2a2 2 0 0 1-2-2a2 2 0 0 1 2-2a2 2 0 0 1 2 2"/></svg>`
+
+        ctx.setTopIcons({
+            skills: {
+                component: {
+                    template: svg([
+                        `@click="$ctx.toggleTop('SkillSelector')"`,
+                        `:class="!$tools?.isToolEnabled('skill') ? '' : $prefs.onlySkills == null ? 'text-green-600 dark:text-green-300' : $prefs.onlySkills.length ? 'text-blue-600! dark:text-blue-300!' : ''"`
+                    ].join(' ')),
+                },
+                isActive({ top }) {
+                    return top === 'SkillSelector'
+                },
+                get title() {
+                    return !ctx.tools?.isToolEnabled('skill')
+                        ? `skill tool not enabled`
+                        : ctx.prefs.onlySkills == null
+                            ? `All Skills Included`
+                            : ctx.prefs.onlySkills.length
+                                ? `${ctx.prefs.onlySkills.length} ${ctx.utils.pluralize('Skill', ctx.prefs.onlySkills.length)} Included`
+                                : 'No Skills Included'
+                }
+            }
+        })
+
+        ctx.chatRequestFilters.push(({ request, thread, context }) => {
+
+            if (!ctx.tools?.isToolEnabled('skill')) {
+                console.log(`skills.chatRequestFilters: 'skill' tool is not enabled`)
+                return
+            }
+
+            const prefs = ctx.prefs
+            if (prefs.onlySkills != null) {
+                if (Array.isArray(prefs.onlySkills)) {
+                    request.metadata.skills = prefs.onlySkills.length > 0
+                        ? prefs.onlySkills.join(',')
+                        : 'none'
+                }
+            } else {
+                request.metadata.skills = 'all'
+            }
+
+            console.log('skills.chatRequestFilters', prefs.onlySkills, Object.keys(ctx.state.skills || {}))
+            const skills = ctx.state.skills
+            if (!skills) return
+
+            const includeSkills = []
+            for (const skill of Object.values(skills)) {
+                if (prefs.onlySkills == null || prefs.onlySkills.includes(skill.name)) {
+                    includeSkills.push(skill)
+                }
+            }
+            if (!includeSkills.length) return
+
+            const sb = []
+            sb.push("<available_skills>")
+            for (const skill of includeSkills) {
+                sb.push(" <skill>")
+                sb.push("  <name>" + ctx.utils.encodeHtml(skill.name) + "</name>")
+                sb.push("  <description>" + ctx.utils.encodeHtml(skill.description) + "</description>")
+                sb.push("  <location>" + ctx.utils.encodeHtml(skill.location) + "</location>")
+                sb.push(" </skill>")
+            }
+            sb.push("</available_skills>")
+
+            const skillsPrompt = SkillInstructions.replace('$$AVAILABLE_SKILLS$$', sb.join('\n')).trim()
+            context.requiredSystemPrompts.push(skillsPrompt)
+        })
+
+        ctx.setThreadFooters({
+            skills: {
+                component: {
+                    template: `
+                        <div class="mt-2 w-full flex justify-center">
+                            <button type="button" @click="$ctx.chat.sendUserMessage('proceed')"
+                                class="px-3 py-1 rounded-md text-xs font-medium border border-gray-200 dark:border-gray-700 bg-white dark:bg-gray-800 text-gray-700 dark:text-gray-300 hover:bg-gray-50 dark:hover:bg-gray-700 transition-colors select-none">
+                                proceed
+                            </button>
+                        </div>
+                    `
+                },
+                show({ thread }) {
+                    if (thread.messages.length < 2) return false
+                    const msgRoles = thread.messages.map(m => m.role)
+                    if (msgRoles[msgRoles.length - 1] != "assistant") return false
+                    const hasSkillToolCall = thread.messages.some(m =>
+                        m.tool_calls?.some(tc => tc.type == "function" && tc.function.name == "skill"))
+                    const systemPrompt = thread.messages.find(m => m.role == "system")?.content.toLowerCase() || ''
+                    const line1 = leftPart(systemPrompt.trim(), "\n")
+                    const hasPlanSystemPrompt = line1.includes("plan") || systemPrompt.includes("# plan")
+                    return hasSkillToolCall || hasPlanSystemPrompt
+                }
+            }
+        })
+
+        ctx.setState({
+            skills: {}
+        })
+    },
+
+    async load(ctx) {
+        const api = await ext.getJson('/')
+        if (api.response) {
+            ctx.setState({ skills: api.response })
+        } else {
+            ctx.setError(api.error)
+        }
+    }
+}

llms/extensions/skills/ui/skills/create-plan/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: create-plan
+description: Create a concise plan. Use when a user explicitly asks for a plan related to a coding task.
+metadata:
+  short-description: Create a plan
+---
+
+# Create Plan
+
+## Goal
+
+Turn a user prompt into a **single, actionable plan** delivered in the final assistant message.
+
+## Minimal workflow
+
+Throughout the entire workflow, operate in read-only mode. Do not write or update files.
+
+1. **Scan context quickly**
+   - Read `README.md` and any obvious docs (`docs/`, `CONTRIBUTING.md`, `ARCHITECTURE.md`).
+   - Skim relevant files (the ones most likely touched).
+   - Identify constraints (language, frameworks, CI/test commands, deployment shape).
+
+2. **Ask follow-ups only if blocking**
+   - Ask **at most 1–2 questions**.
+   - Only ask if you cannot responsibly plan without the answer; prefer multiple-choice.
+   - If unsure but not blocked, make a reasonable assumption and proceed.
+
+3. **Create a plan using the template below**
+   - Start with **1 short paragraph** describing the intent and approach.
+   - Clearly call out what is **in scope** and what is **not in scope** in short.
+   - Then provide a **small checklist** of action items (default 6–10 items).
+      - Each checklist item should be a concrete action and, when helpful, mention files/commands.
+      - **Make items atomic and ordered**: discovery → changes → tests → rollout.
+      - **Verb-first**: “Add…”, “Refactor…”, “Verify…”, “Ship…”.
+   - Include at least one item for **tests/validation** and one for **edge cases/risk** when applicable.
+   - If there are unknowns, include a tiny **Open questions** section (max 3).
+
+4. **Do not preface the plan with meta explanations; output only the plan as per template**
+
+## Plan template (follow exactly)
+
+```markdown
+# Plan
+
+<1–3 sentences: what we’re doing, why, and the high-level approach.>
+
+## Scope
+- In:
+- Out:
+
+## Action items
+[ ] <Step 1>
+[ ] <Step 2>
+[ ] <Step 3>
+[ ] <Step 4>
+[ ] <Step 5>
+[ ] <Step 6>
+
+## Open questions
+- <Question 1>
+- <Question 2>
+- <Question 3>
+```
+
+## Checklist item guidance
+Good checklist items:
+- Point to likely files/modules: src/..., app/..., services/...
+- Name concrete validation: “Run npm test”, “Add unit tests for X”
+- Include safe rollout when relevant: feature flag, migration plan, rollback note
+
+Avoid:
+- Vague steps (“handle backend”, “do auth”)
+- Too many micro-steps
+- Writing code snippets (keep the plan implementation-agnostic)