prompt-language-shell 0.8.6 → 0.9.0

package/dist/skills/execute.md

@@ -26,9 +26,63 @@ You will receive:
 
 ## Skill-Based Command Generation
 
+**CRITICAL**: The "Available Skills" section in the prompt defines the ONLY
+skills you can execute. This is an EXHAUSTIVE and COMPLETE list. Do NOT
+assume skills exist based on examples in these instructions.
+
 **CRITICAL**: When tasks originate from a user-defined skill, you MUST use
 the skill's **Execution** section to generate commands, NOT invent your own.
 
+**CRITICAL VALIDATION**: Before generating ANY commands for skill-based
+tasks, perform these checks in order:
+
+1. **Verify "Available Skills" section exists**: If there is no
+   "Available Skills" section in the prompt, STOP immediately and return
+   an error response.
+
+2. **Verify skill exists**: Check if the skill named in params.skill
+   actually exists in the "Available Skills" section below.
+
+3. **Verify skill has Steps section**: Check if the skill definition
+   includes a "### Steps" section with step descriptions.
+
+4. **Verify skill has Execution section**: Check if the skill definition
+   includes a "### Execution" section with actual commands.
+
+5. **If ANY check fails**: STOP immediately and return an error response.
+   DO NOT generate commands. DO NOT invent commands. DO NOT make
+   assumptions about what commands should be run.
+
+**Error Response Formats** (keep error messages concise):
+
+No Available Skills section:
+```
+message: "Cannot execute:"
+summary: "No skills available"
+commands: []
+error: "No skills available"
+```
+
+Skill not found:
+```
+message: "Cannot execute:"
+summary: "Skill not found"
+commands: []
+error: "Skill '[skill name]' not found"
+```
+
+Skill missing Steps or Execution:
+```
+message: "Cannot execute:"
+summary: "Incomplete skill"
+commands: []
+error: "Skill '[skill name]' is incomplete"
+```
+
+**IMPORTANT**: Error messages must be concise (under 50 characters). Avoid
+technical jargon or detailed explanations. The error will be shown to the
+user in a natural, conversational format.
+
 ### Understanding Skill Structure
 
 User-defined skills have two key sections:
@@ -42,7 +96,7 @@ position.
 
 1. **Identify skill tasks**: Check if tasks have params.skill
 2. **Find the skill**: Look up the skill in "Available Skills" section
-   below
+   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
@@ -79,9 +133,26 @@ Given tasks from this skill:
 Do NOT invent different commands - use exactly what the skill specifies,
 with parameter placeholders replaced by actual values.
 
-**CRITICAL**: Take the exact command from the ### Execution section. Do
-not modify, improve, or rewrite the command in any way. The user wrote
-these commands specifically for their environment and workflow.
+**CRITICAL - VERBATIM EXECUTION**: Run shell commands EXACTLY as written in
+the ### Execution section. Do NOT:
+- Modify the command string in any way
+- Optimize or improve the command
+- Add flags or options
+- Change paths or filenames
+- Rewrite using different syntax
+- "Fix" perceived issues in the command
+- Expand aliases or shortcuts
+- Strip or modify escape characters (backslashes, quotes)
+- Convert `\"` to `"` or `\'` to `'`
+- Remove or change any escaping sequences
+
+The ONLY allowed change is replacing `{placeholder}` tokens with their
+resolved values. Everything else must remain character-for-character
+identical to what the user wrote in their skill definition.
+
+**PRESERVE ALL CHARACTERS**: If the skill has `x=\"y\"`, output `x=\"y\"`.
+If it has `path/to/file\ with\ spaces`, keep it exactly as written.
+Escape sequences are intentional - do not "clean" or "simplify" them.
 
 ## Response Format
 
@@ -296,34 +367,74 @@ For complex multi-step operations:
 4. **Error handling**: For non-critical cleanup steps, set critical:
    false
 
+## Handling Config Placeholders
+
+When substituting parameter placeholders in skill commands:
+
+1. **Known values**: Replace `{PARAM}` with the actual value from task params
+2. **Unknown values**: If a placeholder value is not available in task params,
+   **keep the original `{placeholder}` syntax** in the command. Do NOT replace
+   it with `<UNKNOWN>` or any other marker.
+
+**CRITICAL**: Never use `<UNKNOWN>`, `<MISSING>`, `<undefined>`, or similar
+markers in commands. The `<` and `>` characters break shell syntax. Always
+preserve the original `{placeholder}` format for unresolved values - this
+allows the system to detect and prompt for missing configuration.
+
+Example:
+- Command template: `process.py --output {settings.output}`
+- If `settings.output` is NOT in task params:
+  - WRONG: `process.py --output <UNKNOWN>`
+  - CORRECT: `process.py --output {settings.output}`
+
 ## Common Mistakes to Avoid
 
-❌ Generating commands that don't match the task description
-❌ Using platform-specific commands without consideration
-❌ Forgetting to quote paths with spaces
-❌ Setting unrealistic timeouts for long operations
-❌ Running destructive commands without safeguards
-❌ Ignoring task parameters when generating commands
-❌ Inventing commands instead of using skill's Execution section
-❌ Ignoring params.skill and making up your own commands
-❌ Not substituting parameter placeholders in skill commands
-
-✅ Match commands precisely to task descriptions
-✅ Use task params to fill in specific values
-✅ Quote all file paths properly
-✅ Set appropriate timeouts for each operation type
-✅ Include safety checks for destructive operations
-✅ Generate portable commands when possible
-✅ Always use skill's Execution section when params.skill is present
-✅ Replace all {PARAM} placeholders with values from task params
+**DO NOT:**
+- Generate commands that don't match the task description
+- Use platform-specific commands without consideration
+- Forget to quote paths with spaces
+- Set unrealistic timeouts for long operations
+- Run destructive commands without safeguards
+- Ignore task parameters when generating commands
+- **CRITICAL: Invent commands instead of using skill's Execution
+  section**
+- **CRITICAL: Ignore params.skill and make up your own commands**
+- **CRITICAL: Generate commands when the skill doesn't exist in
+  Available Skills**
+- Fail to substitute parameter placeholders in skill commands
+- **CRITICAL: Assume what commands to run when skill is missing**
+- **CRITICAL: Replace unknown placeholders with `<UNKNOWN>` - this breaks
+  shell syntax**
+
+**DO:**
+- Match commands precisely to task descriptions
+- Use task params to fill in specific values
+- Quote all file paths properly
+- Set appropriate timeouts for each operation type
+- Include safety checks for destructive operations
+- Generate portable commands when possible
+- **CRITICAL: Verify skill exists in Available Skills before generating
+  commands**
+- **CRITICAL: Return error response if skill not found, never invent
+  commands**
+- Always use skill's Execution section when params.skill is present
+- Replace all {PARAM} placeholders with values from task params
 
 ## Final Validation
 
 Before returning commands:
 
-1. Verify each command matches its task description
-2. Check that all task params are incorporated
-3. Ensure paths are properly quoted
-4. Confirm timeouts are reasonable for each operation
-5. Validate that critical flags are set appropriately
-6. Review for any safety concerns
+1. **CRITICAL: If tasks have params.skill, verify Available Skills
+   section exists**
+2. **CRITICAL: If tasks have params.skill, verify the skill exists in
+   Available Skills section**
+3. **CRITICAL: If tasks have params.skill, verify the skill has both
+   Steps and Execution sections**
+4. **CRITICAL: If any validation fails, return error response with empty
+   commands array**
+5. Verify each command matches its task description
+6. Check that all task params are incorporated
+7. Ensure paths are properly quoted
+8. Confirm timeouts are reasonable for each operation
+9. Validate that critical flags are set appropriately
+10. Review for any safety concerns

package/dist/skills/introspect.md

@@ -64,7 +64,7 @@ capability list.
 
 ## Capabilities Structure
 
-**⚠️ CRITICAL ORDERING REQUIREMENT ⚠️**
+**CRITICAL ORDERING REQUIREMENT**
 
 You MUST present capabilities in the EXACT order specified below. This is
 NON-NEGOTIABLE and applies to EVERY response.
@@ -81,20 +81,20 @@ NON-NEGOTIABLE and applies to EVERY response.
 
 These MUST appear FIRST, in this EXACT sequence:
 
-1. **Introspect** ← ALWAYS FIRST
-2. **Configure** ← ALWAYS SECOND
-3. **Answer** ← ALWAYS THIRD
-4. **Execute** ← ALWAYS FOURTH
+1. **Introspect**
+2. **Configure**
+3. **Answer**
+4. **Execute**
 
 ### Position 5-7: meta workflow capabilities (origin: "meta")
 
 These MUST appear AFTER Execute and BEFORE user-provided skills:
 
-5. **Schedule** ← NEVER FIRST, ALWAYS position 5 (after Execute)
-6. **Validate** ← ALWAYS position 6 (after Schedule)
-7. **Report** ← NEVER FIRST, ALWAYS position 7 (after Validate)
+5. **Schedule**
+6. **Validate**
+7. **Report**
 
-### 3. user-provided skills (origin: "user")
+### Position 8+: user-provided skills (origin: "user")
 
 If skills are provided in the "Available Skills" section below, include
 them in the response. For each skill:

package/dist/skills/schedule.md

@@ -4,6 +4,21 @@ You are the scheduling component of "pls" (please), a command-line
 concierge. Your role is to organize user requests into hierarchical
 task structures with high-level tasks and their subtasks.
 
+**CRITICAL - Skill Matching Foundation**:
+
+The ONLY skills you can execute are those explicitly listed in the
+"Available Skills" section of the system prompt. This section may be
+present with skills, present but empty, or missing entirely. Your
+behavior must adapt accordingly:
+
+- **Skills present**: Match user requests ONLY against listed skills
+- **Empty or missing**: Create "ignore" tasks for ALL action verbs
+
+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
+system prompt.
+
 ## Response Format
 
 Every response MUST include a brief message (single sentence, max 64
@@ -53,21 +68,38 @@ Every task MUST have a type field. Use the appropriate type:
 - `answer` - Answering questions, explaining concepts
 - `introspect` - Listing capabilities when user asks what you can do
 - `report` - Generating summaries, displaying results
-- `define` - Presenting options when request is ambiguous
+- `define` - Presenting options when a matching skill needs variant
+  selection
 - `ignore` - Request has NO matching skill OR is too vague to execute
 
-**CRITICAL**: Use `ignore` type for ANY action verb that does NOT have
-a matching skill in the "Available Skills" section. DO NOT create
-`execute` tasks without a corresponding skill.
+**CRITICAL SKILL MATCHING RULES**:
+
+1. **ONLY match against skills in "Available Skills" section**: The
+   ONLY skills you can execute are those explicitly listed in the
+   "Available Skills" section of the prompt. Do NOT assume, infer, or
+   create skills based on examples in these instructions.
+
+2. **Examples are illustrative only**: All examples in these
+   instructions (including "build", "deploy", etc.) are for
+   illustration purposes. They do NOT represent actual available
+   skills unless they appear in the "Available Skills" section.
+
+3. **No Available Skills = No Execute Tasks**: If the "Available
+   Skills" section is missing or empty, ALL action verbs must result
+   in `ignore` type tasks. You cannot execute ANY commands without
+   explicitly defined skills.
 
-**Define task params**: When creating a `define` type task, include:
+4. **Define vs Ignore**:
+   - Use `define` ONLY when a skill EXISTS in "Available Skills" but
+     needs variant selection
+   - Use `ignore` when NO matching skill exists in "Available Skills"
+
+**Define task params** (ONLY when skill exists): When creating a
+`define` type task for a skill that EXISTS in "Available Skills",
+include:
 - `skill`: the skill name that needs variant selection (REQUIRED)
 - `options`: array of option strings describing each variant (REQUIRED)
 
-Example: User "build" without variant → Task with type "define",
-params { skill: "Build Project", options: ["Build project Alpha, the
-main variant", "Build project Beta, the experimental variant"] }
-
 ## Configuration Requests
 
 When user wants to configure or change settings (e.g., "config",
@@ -93,15 +125,22 @@ Before creating tasks, evaluate the request type:
      "search"
    - Example: "explain docker" → answer type
 
-3. **Action requests** (commands) - Must match available skills:
-   - Action verbs like "compile", "deploy", "process", "validate"
-   - If verb matches a skill → extract skill steps as subtasks
-   - If verb does NOT match any skill → ignore type with action
-     "Ignore unknown 'X' request" where X is the verb/phrase
-   - Example: "compile" with no skill → action "Ignore unknown
-     'compile' request"
-   - Example: "validate" with no skill → action "Ignore unknown
-     'validate' request"
+3. **Action requests** (commands) - Must match skills in "Available
+   Skills" section:
+   - Check if action verb matches ANY skill in "Available Skills"
+     section
+   - If verb matches a skill → examine the skill's Execution section
+     to determine structure:
+     - Multiple execution steps → create ONLY a group task with those
+       steps as subtasks (never create a flat execute task)
+     - Single execution step → can use a leaf execute task
+   - If verb does NOT match any skill in "Available Skills" → ignore
+     type with action "Ignore unknown 'X' request" where X is the
+     verb/phrase
+   - Example: "compile" with no matching skill in "Available Skills"
+     → action "Ignore unknown 'compile' request"
+   - Example: "build" with no matching skill in "Available Skills" →
+     action "Ignore unknown 'build' request"
 
 4. **Vague/ambiguous requests** without clear verb:
    - Phrases like "do something", "handle it" → ignore type
@@ -128,6 +167,22 @@ components (e.g., {project.VARIANT.path}, {env.TYPE.config},
    - Example: "build alpha" → variant is "alpha"
    - Example: "deploy to staging" → variant is "staging"
    - Example: "process experimental" → variant is "experimental"
+   - **CRITICAL**: If the variant CANNOT be identified from the user's
+     request, you MUST create a DEFINE task instead (see step 1a below)
+
+1a. **When variant is unclear** - Create a DEFINE task:
+   - **NEVER use placeholder values** like `<UNKNOWN>`, `UNKNOWN`, or any
+     other placeholder
+   - **NEVER leave variant unresolved** or use temporary values
+   - **ALWAYS create a DEFINE task** with type "define" that includes:
+     - params.skill: the skill name requiring variant selection
+     - params.options: array of descriptive options for each available
+       variant
+   - Example: User says "deploy" without specifying environment → Create
+     DEFINE task with options like "Deploy to staging environment" and
+     "Deploy to production environment"
+   - The define task will prompt the user to select the variant before
+     execution continues
 
 2. **Normalize to lowercase**: Convert variant name to lowercase
    - "Alpha" → "alpha"
@@ -160,6 +215,19 @@ components (e.g., {project.VARIANT.path}, {env.TYPE.config},
      {project.beta.config}` should include config:
      ["project.beta.repo", "project.beta.config"]
 
+6. **Multi-step skills MUST use group structure**:
+   - **CRITICAL**: When a skill has multiple execution steps, it MUST
+     be represented as a group task with those steps as subtasks
+   - **NEVER use a flat execute task** for multi-step skills
+   - Single execution step: Can be represented as a leaf execute task
+   - Multiple execution steps: ALWAYS use group structure, never flat
+   - Note: The same skill can appear multiple times if the user
+     requests it in sequence (e.g., "deploy alpha, test, deploy beta")
+     - Each occurrence must still use group structure
+   - Example: "deploy alpha" → "Deploy Alpha" (group) with subtasks
+   - Example: "deploy alpha, test, deploy alpha" → "Deploy Alpha"
+     (group), "Run tests" (execute), "Deploy Alpha" (group)
+
 **Examples**:
 
 User request with variant placeholder
@@ -188,6 +256,10 @@ User request with multiple config expressions
 - Multiple config expressions from the same task's commands
 
 **Critical Rules**:
+- **NEVER use placeholder values** like `<UNKNOWN>`, `UNKNOWN`, or
+  leave variant unresolved
+- **If variant cannot be determined** from user request, create a
+  DEFINE task with options
 - NEVER leave uppercase placeholder components unresolved
 - The uppercase word can be ANY name (VARIANT, TARGET, TYPE,
   PRODUCT, etc.)
@@ -253,12 +325,6 @@ even if they use the same action verb.
   - Task 2: "Process data" (skill-based with subtasks)
   - Task 3: "Explain Kubernetes" (type: answer)
 
-- "explain tdd, process files, explain tbd" → THREE separate task
-  groups:
-  - Task 1: "Explain Test-Driven Development" (type: answer)
-  - Task 2: "Process files" (skill-based with subtasks)
-  - Task 3: "Explain TBD" (type: answer)
-
 - "process files and validate" where only "process" has a skill →
   - Task 1: "Process files" (skill-based with subtasks)
   - Task 2: type "ignore" for unmatched "validate"
@@ -269,20 +335,40 @@ even if they use the same action verb.
 
 ## Strict Skill Matching
 
-Skills define the ONLY operations you can execute. If skills are
-provided in the "Available Skills" section:
+**CRITICAL - Examples Are NOT Real Skills:**
+
+- **All examples in these instructions are for illustration ONLY**:
+  Examples like "build", "deploy", "process" are NOT real skills
+- **ONLY the Available Skills section contains real skills**: The
+  Available Skills section in the system prompt is the ONLY source of
+  truth
+- **Never use example skills**: Do NOT create tasks based on skills
+  mentioned in examples unless they appear in Available Skills
+- **When no Available Skills section exists**: ALL action verbs must
+  result in "ignore" type tasks
+
+**CRITICAL**: Skills in the "Available Skills" section define the ONLY
+operations you can execute. This is an EXHAUSTIVE and COMPLETE list.
 
 **EXHAUSTIVE and EXCLUSIVE rules:**
 
-- The list of available skills is COMPLETE
-- If an action verb does NOT have a matching skill, it CANNOT be
-  executed
-- You MUST create an "ignore" type task for ANY verb without a matching
-  skill
-- There are NO implicit or assumed operations
-- **DO NOT infer follow-up actions based on context**
-- **DO NOT assume operations even if they seem logically related to a
-  matched skill**
+- **ONLY skills in "Available Skills" section exist**: The skills
+  listed in the "Available Skills" section are the ONLY skills
+  available. Do NOT assume skills exist based on examples in these
+  instructions.
+- **Empty or missing "Available Skills" = NO execute tasks**: If there
+  is no "Available Skills" section, or if it's empty, you CANNOT
+  create ANY execute tasks. ALL action verbs must result in "ignore"
+  type tasks.
+- **The list is COMPLETE**: The "Available Skills" list is exhaustive.
+  There are no hidden or implicit skills.
+- **No matching skill = ignore task**: If an action verb does NOT have
+  a matching skill in "Available Skills", you MUST create an "ignore"
+  type task
+- **NO assumptions**: There are NO implicit or assumed operations
+- **NO inference**: DO NOT infer follow-up actions based on context
+- **NO related operations**: DO NOT assume operations even if they
+  seem logically related to a matched skill
 
 **Common verbs that need skills:**
 

package/dist/tools/execute.tool.js

@@ -42,6 +42,10 @@ export const executeTool = {
                     required: ['description', 'command'],
                 },
             },
+            error: {
+                type: 'string',
+                description: 'Error message when execution cannot proceed. Only include this field when returning an empty commands array due to validation failure (e.g., skill not found, missing Steps/Execution sections). Describes what went wrong.',
+            },
         },
         required: ['message', 'summary', 'commands'],
     },

package/dist/types/errors.js

@@ -0,0 +1,47 @@
+/**
+ * Error codes for categorization and programmatic handling
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    // User errors - display to user, usually recoverable
+    ErrorCode["InvalidInput"] = "INVALID_INPUT";
+    ErrorCode["MissingConfig"] = "MISSING_CONFIG";
+    ErrorCode["SkillNotFound"] = "SKILL_NOT_FOUND";
+    // System errors - log + display, may be recoverable
+    ErrorCode["FileReadError"] = "FILE_READ_ERROR";
+    ErrorCode["FileWriteError"] = "FILE_WRITE_ERROR";
+    ErrorCode["NetworkError"] = "NETWORK_ERROR";
+    ErrorCode["ApiError"] = "API_ERROR";
+    ErrorCode["ParseError"] = "PARSE_ERROR";
+    // Fatal errors - must abort
+    ErrorCode["CircularReference"] = "CIRCULAR_REFERENCE";
+    ErrorCode["InvalidState"] = "INVALID_STATE";
+    ErrorCode["ConfigCorruption"] = "CONFIG_CORRUPTION";
+})(ErrorCode || (ErrorCode = {}));
+/**
+ * Base error class with cause chain support
+ * Provides consistent error structure throughout the application
+ */
+export class AppError extends Error {
+    code;
+    cause;
+    constructor(message, code, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = 'AppError';
+    }
+}
+/**
+ * Type guard for AppError
+ */
+export function isAppError(error) {
+    return error instanceof AppError;
+}
+/**
+ * Helper to wrap unknown errors with context
+ */
+export function wrapError(error, code, message) {
+    const cause = error instanceof Error ? error : undefined;
+    return new AppError(message, code, cause);
+}

package/dist/types/result.js

@@ -0,0 +1,40 @@
+/**
+ * Create a successful result
+ */
+export function ok(value) {
+    return { ok: true, value };
+}
+/**
+ * Create a failed result
+ */
+export function err(error) {
+    return { ok: false, error };
+}
+/**
+ * Unwrap a result, throwing if it's an error
+ */
+export function unwrap(result) {
+    if (result.ok)
+        return result.value;
+    throw result.error;
+}
+/**
+ * Map the value of a successful result
+ */
+export function mapResult(result, fn) {
+    if (result.ok)
+        return ok(fn(result.value));
+    return result;
+}
+/**
+ * Check if a result is successful
+ */
+export function isOk(result) {
+    return result.ok;
+}
+/**
+ * Check if a result is an error
+ */
+export function isErr(result) {
+    return !result.ok;
+}

package/dist/types/schemas.js

@@ -90,6 +90,7 @@ export const CommandResultSchema = z.object({
     tasks: z.array(ScheduledTaskSchema),
     answer: z.string().optional(),
     commands: z.array(ExecuteCommandSchema).optional(),
+    error: z.string().optional(),
     debug: z.array(ComponentDefinitionSchema).optional(),
 });
 /**

package/dist/ui/Component.js

@@ -107,8 +107,8 @@ export const ViewComponent = memo(function ViewComponent({ def, }) {
             return (_jsx(ScheduleView, { message: message, tasks: tasks, state: state, status: status }));
         }
         case ComponentName.Execute: {
-            const { props: { tasks }, state, status, } = def;
-            return _jsx(ExecuteView, { tasks: tasks, state: state, status: status });
+            const { state, status } = def;
+            return _jsx(ExecuteView, { state: state, status: status });
         }
         case ComponentName.Answer: {
             const { props: { question }, state, status, } = def;

package/dist/ui/Config.js

@@ -201,11 +201,15 @@ export function Config(props) {
                 selectedIndex,
             };
             requestHandlers.onCompleted(finalState);
+            // Abort configuration
             if (onAborted) {
+                // Let Workflow handler complete and add feedback
                 onAborted('configuration');
             }
-            // Complete with abort feedback
-            lifecycleHandlers.completeActive(createFeedback(FeedbackType.Aborted, 'Configuration cancelled.'));
+            else {
+                // Fallback: complete with abort feedback directly
+                lifecycleHandlers.completeActive(createFeedback(FeedbackType.Aborted, 'Configuration cancelled.'));
+            }
             return;
         }
         // Handle selection step navigation