prompt-language-shell 0.9.4 → 0.9.8

package/dist/skills/execute.md

@@ -100,14 +100,28 @@ position.
 
 ### How to Generate Commands from Skills
 
+**CRITICAL - ONE TASK = ONE COMMAND**: Each input task maps to exactly
+ONE command in your response. The task's action tells you WHICH specific
+step from the skill to use. Do NOT expand an entire skill workflow for
+a single task - only generate the command for that specific step.
+
 1. **Identify skill tasks**: Check if tasks have params.skill
 2. **Find the skill**: Look up the skill in "Available Skills" section
    below (REQUIRED - must exist)
-3. **Match tasks to Execution**: Each task action came from a Steps line;
-   use the corresponding Execution line for the command
-4. **Substitute parameters**: Replace {PARAM} placeholders with actual
+3. **Match task action to skill step**: The task action describes which
+   step from the skill's Steps section this task represents. Find the
+   matching step by semantic meaning (e.g., "Export results" matches
+   "Export the results to {FORMAT}", NOT all three steps of the skill)
+4. **Use corresponding Execution line**: Once you identify which step
+   the task represents, use ONLY that step's corresponding Execution line
+5. **Substitute parameters**: Replace {PARAM} placeholders with actual
    values from task params
 
+**IMPORTANT**: If the schedule contains separate tasks for different
+steps of the same skill (e.g., one task for fetching data, another for
+exporting), each task produces its own single command. Do NOT combine
+them or add steps that weren't scheduled.
+
 ### Example Skill
 
 ```markdown
@@ -151,6 +165,28 @@ steps 1 and 3 (with step 2 skipped), use Execution lines 1 and 3
 which Execution line to use - always match by original position, never
 by sequential task index.
 
+### Expanding Skill References in Execution Lines
+
+Execution lines may contain **skill references** in the format
+`[ Skill Name ]`. These are references to other skills that must be
+expanded to actual commands before execution.
+
+**Format**: `[ Skill Name ]` with spaces inside the brackets
+
+**How to expand**:
+1. When an Execution line contains `[ Skill Name ]`, look up that skill
+   in the "Available Skills" section
+2. Get the referenced skill's Execution command
+3. Replace the `[ Skill Name ]` reference with the actual command
+
+**IMPORTANT**: Skill references are the ONLY exception to the verbatim
+execution rule below. You MUST expand them - never output `[ ... ]`
+syntax in the final command.
+
+**Note**: Use the `skill:` field from task metadata to find the skill
+definition. If that skill's Execution line contains `[ Other Skill ]`,
+look up "Other Skill" and replace the reference with its command.
+
 **CRITICAL - VERBATIM EXECUTION**: Run shell commands EXACTLY as written in
 the ### Execution section. Do NOT:
 - Modify the command string in any way
@@ -371,6 +407,41 @@ commands:
     command: "df -h"
 ```
 
+### Example 8: Partial skill execution (specific steps only)
+
+When the schedule breaks a multi-step skill into separate tasks, each
+task produces exactly ONE command for its specific step:
+
+Skill "Prepare Report" has 3 steps:
+- Steps: Fetch source data | Transform data | Export results
+- Execution: curl {url} | python3 process.py | cat output.csv
+
+Tasks (schedule requested only steps 1 and 3, skipping transform):
+- { action: "Fetch source data", params: { skill: "Prepare Report" } }
+- { action: "Export results", params: { skill: "Prepare Report" } }
+
+Response (2 tasks = 2 commands, NOT 3):
+```
+message: "Prepare report:"
+summary: "Report prepared"
+commands:
+  - description: "Fetch source data"
+    command: "curl {url}"
+  - description: "Export results"
+    command: "cat output.csv"
+```
+
+**WRONG** response (adding unscheduled transform step):
+```
+commands:
+  - description: "Fetch source data"
+    command: "curl {url}"
+  - description: "Transform data"       ← NOT IN SCHEDULE - DO NOT ADD
+    command: "python3 process.py"
+  - description: "Export results"
+    command: "cat output.csv"
+```
+
 ## Handling Complex Operations
 
 For complex multi-step operations:
@@ -420,6 +491,10 @@ Example:
 - **CRITICAL: Assume what commands to run when skill is missing**
 - **CRITICAL: Replace unknown placeholders with `<UNKNOWN>` - this breaks
   shell syntax**
+- **CRITICAL: Add steps that weren't in the scheduled tasks** - if the
+  schedule has 2 tasks, you MUST return exactly 2 commands
+- **CRITICAL: Expand entire skill workflows** when only specific steps
+  were scheduled - match task actions to individual skill steps
 
 **DO:**
 - Match commands precisely to task descriptions
@@ -434,6 +509,10 @@ Example:
   commands**
 - Always use skill's Execution section when params.skill is present
 - Replace all {PARAM} placeholders with values from task params
+- **CRITICAL: Count input tasks and ensure output has same count** -
+  N tasks in = N commands out, no exceptions
+- **CRITICAL: Match each task action to its specific skill step** -
+  use only that step's Execution line for the command
 
 ## Final Validation
 

package/dist/skills/schedule.md

@@ -14,6 +14,15 @@ behavior must adapt accordingly:
 - **Skills present**: Match user requests ONLY against listed skills
 - **Empty or missing**: Create "ignore" tasks for ALL action verbs
 
+**CRITICAL - Available Skills Section Takes Precedence**:
+
+Information provided in the "Available Skills" section is AUTHORITATIVE
+and OVERRIDES any default behavior in these instructions. When a skill's
+description specifies required parameters, error handling, or specific
+behaviors, those requirements MUST be followed exactly. Skill-specific
+rules always take precedence over general examples or default patterns
+in this document.
+
 All examples in these instructions (e.g., "build", "deploy", "process")
 are for illustration only. They do NOT represent actual available
 skills unless they appear in the "Available Skills" section of the
@@ -268,6 +277,152 @@ User request with multiple config expressions
 - This applies to ALL placeholders in task actions, including those
   from skill references
 
+## Runtime Parameter Placeholders
+
+Skills may include runtime parameters in their Execution section using
+angle bracket syntax. These parameters MUST be resolved by the LLM
+during scheduling - they represent values extracted from the user's
+command, NOT from stored configuration.
+
+**Parameter Format:**
+
+- `<PARAM>` - Required parameter, extract from user command
+- `<PARAM=default>` - Parameter with default, use default if not specified
+- `<PARAM?>` - Optional parameter, omit entirely if not mentioned
+
+**Distinction from Config Placeholders:**
+
+- `{x.y.z}` - Config placeholder, resolved by system at execution from
+  ~/.plsrc
+- `{x.VARIANT.z}` - Variant config, LLM matches variant at schedule time,
+  system resolves from ~/.plsrc at execution
+- `<PARAM>` - Runtime parameter, resolved entirely by LLM at schedule time
+  from user command
+
+**Resolution Rules:**
+
+1. **Full resolution required**: All `<PARAM>` placeholders MUST be
+   resolved to concrete values before creating tasks. No angle-bracket
+   syntax should remain in task actions or params.
+
+2. **Space normalization**: When optional params are omitted, collapse
+   adjacent spaces to single space (e.g., `cmd <OPT?> file` → `cmd file`)
+
+3. **Complete descriptions**: Task actions must be human-readable with
+   all parameters filled in:
+   - CORRECT: "Process /data/report.csv in batch mode with JSON output"
+   - WRONG: "Process <SOURCE> in <MODE> mode"
+
+**Parameter Classification:**
+
+Runtime parameters fall into two categories:
+
+1. **Key parameters** - Essential to the operation, define WHAT to operate on
+   - Input files, paths, URLs, target names, identifiers
+   - The primary subject of the command
+   - Cannot be guessed or listed as options
+   - Examples: `<SOURCE>`, `<FILE>`, `<URL>`, `<TARGET>`
+
+2. **Modifier parameters** - Configure HOW the operation runs
+   - Have a finite set of valid options
+   - Affect behavior but not the primary subject
+   - Examples: `<MODE>`, `<QUALITY>`, `<FORMAT>`, `<VERBOSITY>`
+
+**Resolution Outcomes:**
+
+When processing runtime parameters, exactly ONE of these outcomes applies.
+**CRITICAL: Evaluate in this EXACT order - key param check MUST happen first:**
+
+1. **Key param missing** → Create IGNORE task (CHECK THIS FIRST!)
+   - **PREREQUISITE CHECK**: Before considering ANY other outcome, verify
+     ALL key parameters (input files, paths, URLs, targets) are present
+   - A key parameter is not specified → ALWAYS create IGNORE task
+   - **NEVER create a DEFINE task when key params are missing**, even if
+     modifier params could be listed as options
+   - NEVER offer options for key parameters - they cannot be guessed
+   - Use type `ignore` with descriptive action
+   - Action format: "Missing [param]: specify [what's needed]"
+   - Examples:
+     - "Missing input: specify which file to process"
+     - "Missing target: specify which server to deploy to"
+     - "Missing URL: specify which page to fetch"
+
+2. **All resolved** → Create normal execute/group task
+   - All key parameters are present AND extracted successfully
+   - All modifier parameters are extracted or defaulted
+   - Task action contains fully resolved description
+
+3. **Modifier param unclear (ALL key params present)** → Create DEFINE task
+   - **PREREQUISITE**: ALL key parameters MUST be present in user's command
+   - Only a modifier parameter is unclear but has finite options
+   - **NEVER use DEFINE when ANY key param is missing** - use IGNORE instead
+   - Use type `define` with params.skill and params.options
+   - MUST have more than one option (if only one option exists, use it
+     directly without refinement)
+   - Example: mode (batch/stream/interactive), format (json/xml/csv)
+   - Each option is an object: { name: string, command: string }
+     - name: readable display text for user selection
+     - command: user's natural language command with ALL params resolved
+   - Note: command is NOT the shell command - shell commands are generated
+     by EXECUTE in the next step
+
+**Examples:**
+
+Skill execution line:
+- `process <SOURCE> --mode <MODE> --format <FORMAT=json> <VERBOSE?>`
+
+Key param missing case (CHECK FIRST):
+- User: "process in batch mode"
+- Problem: SOURCE path not specified (key param, cannot be guessed)
+- Task: type `ignore`, action: "Missing source: specify which file to process"
+
+Key param missing with modifier specified:
+- User: "export in JSON format"
+- Problem: SOURCE file not specified (key param, cannot be guessed)
+- Task: type `ignore`, action: "Missing source: specify which data to export"
+- Note: Even though format IS specified, key param is missing → IGNORE, not
+  DEFINE. Key param check takes absolute precedence over DEFINE.
+
+Success case (all resolved):
+- User: "process /data/report.csv in batch mode"
+- Resolution:
+  - `<SOURCE>` → `/data/report.csv` (extracted)
+  - `<MODE>` → `batch` (extracted from "batch mode")
+  - `<FORMAT=json>` → `json` (default used)
+  - `<VERBOSE?>` → omitted (optional, not mentioned)
+- Task action: "Process /data/report.csv in batch mode with JSON format"
+
+Define case (modifier unclear, ALL key params present):
+- User: "process /data/report.csv"
+- Key params: SOURCE is present (/data/report.csv) ✓
+- Problem: MODE not specified but can be listed (3 options available)
+- Task: type `define`, params:
+  - skill: "Process Data"
+  - options:
+    - { name: "Process in batch mode",
+        command: "process /data/report.csv in batch mode" }
+    - { name: "Process in stream mode",
+        command: "process /data/report.csv in stream mode" }
+    - { name: "Process interactively",
+        command: "process /data/report.csv interactively" }
+- User selects "Process in batch mode"
+- SCHEDULE receives: "process /data/report.csv in batch mode"
+- EXECUTE then generates the appropriate shell command
+
+**Critical Rules:**
+- **KEY PARAM CHECK IS MANDATORY AND FIRST**: Before creating ANY task type,
+  verify ALL key parameters are present. This check takes absolute precedence.
+- IGNORE when ANY key param is missing (input, file, URL, target, etc.)
+- Key params cannot be guessed - always require IGNORE with clear error
+- **DEFINE is ONLY valid when ALL key params are present** - if any key param
+  is missing, DEFINE is NOT an option, regardless of modifier params
+- DEFINE tasks MUST have multiple options (2+); single option = use directly
+- NEVER leave `<PARAM>` unresolved in task output
+- NEVER use placeholder values like `<UNKNOWN>` or `<MISSING>`
+- option.command is user's natural language request, NOT shell command
+- Each option.command must include ALL user parameters (original + selected)
+- option.command must preserve exact paths, filenames, URLs (case-sensitive)
+
 ## Grouping Strategy
 
 Group subtasks under logical parent tasks based on:

package/dist/tools/schedule.tool.js

@@ -31,7 +31,7 @@ export const scheduleTool = {
                     },
                     params: {
                         type: 'object',
-                        description: 'Parameters for leaf tasks (e.g., command, path)',
+                        description: 'Parameters for leaf tasks. For "define" type: { skill: string, options: Array<{ name: string, command: string }> }. "name" is display text, "command" is full resolved command.',
                     },
                     config: {
                         type: 'array',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prompt-language-shell",
-  "version": "0.9.4",
+  "version": "0.9.8",
   "description": "Your personal command-line concierge. Ask politely, and it gets things done.",
   "type": "module",
   "main": "dist/index.js",
@@ -17,9 +17,10 @@
     "dev": "npm run build && tsc --watch",
     "prepare": "husky",
     "prepublishOnly": "npm run check",
-    "test": "vitest run --exclude 'tests/integration/*.test.tsx'",
-    "test:watch": "vitest --exclude 'tests/integration/*.test.tsx'",
-    "test:llm": "vitest run tests/integration/schedule*.test.tsx",
+    "test": "vitest run --exclude 'tests/tools/schedule/*.test.tsx' --exclude 'tests/shell/*.test.ts'",
+    "test:watch": "vitest --exclude 'tests/tools/schedule/*.test.tsx' --exclude 'tests/shell/*.test.ts'",
+    "test:llm": "vitest run tests/tools/schedule/*.test.tsx",
+    "test:shell": "vitest run tests/shell/*.test.ts",
     "format": "prettier --write '**/*.{ts,tsx}'",
     "format:check": "prettier --check '**/*.{ts,tsx}'",
     "lint": "eslint .",