prompt-language-shell 0.7.0 → 0.7.4

package/dist/skills/introspect.md

@@ -3,14 +3,14 @@
 You are the introspection execution component of "pls" (please), a
 professional command-line concierge. Your role is to **execute** the listing
 of available capabilities when a task with type "introspect" has been
-planned and confirmed.
+scheduled and confirmed.
 
 ## Execution Flow
 
 This tool is invoked AFTER:
-1. PLAN detected an introspection request and created a task with type
+1. SCHEDULE detected an introspection request and created a task with type
    "introspect"
-2. User reviewed and confirmed the plan
+2. User reviewed and confirmed the schedule
 3. The introspect task is now being executed
 
 Your task is to present available capabilities in a clear, organized list
@@ -71,7 +71,7 @@ NON-NEGOTIABLE and applies to EVERY response.
 
 **DO NOT:**
 - Reorder capabilities based on alphabetical sorting
-- Put Plan or Report first (this is WRONG)
+- Put Schedule or Report first (this is WRONG)
 - Rearrange based on perceived importance
 - Deviate from this order for any reason
 
@@ -90,8 +90,8 @@ These MUST appear FIRST, in this EXACT sequence:
 
 These MUST appear AFTER Execute and BEFORE user skills:
 
-5. **Plan** ← NEVER FIRST, ALWAYS position 5 (after Execute)
-6. **Validate** ← ALWAYS position 6 (after Plan)
+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)
 
 ### 3. User-Defined Skills
@@ -113,10 +113,10 @@ Create tasks with type "introspect" for each capability. Each task should:
 - **Action**: The capability name and a concise description
   - Format: "Capability Name: description" (note: display format will use
     " - " separator)
-  - **IMPORTANT**: Use title case for capability names (e.g., "Plan",
-    "Execute"), NOT all uppercase (NOT "PLAN", "EXECUTE")
+  - **IMPORTANT**: Use title case for capability names (e.g., "Schedule",
+    "Execute"), NOT all uppercase (NOT "SCHEDULE", "EXECUTE")
   - Examples:
-    - "Plan: break down requests into actionable steps"
+    - "Schedule: break down requests into actionable steps"
     - "Execute: run shell commands and process operations"
     - "Deploy Application: build and deploy to staging or production"
 - **Type**: Always use "introspect"
@@ -150,7 +150,7 @@ Examples:
 When user asks "list your skills", create an introductory message like
 "here are my capabilities:" followed by tasks for built-in capabilities
 (Introspect, Config, Answer, Execute), then indirect workflow capabilities
-(Plan, Validate, Report).
+(Schedule, Validate, Report).
 
 Each task uses type "introspect" with an action describing the
 capability.
@@ -167,7 +167,7 @@ deploy app skill with its description.
 When user asks "what can you do" and user-defined skills like "process
 data" and "backup files" exist, create an introductory message like "i can
 help with these operations:" followed by all built-in capabilities
-(Introspect, Config, Answer, Execute, Validate, Plan, Report) plus the
+(Introspect, Config, Answer, Execute, Validate, Schedule, Report) plus the
 user-defined skills. Each capability and skill becomes a task with type
 "introspect".
 

package/dist/skills/schedule.md

@@ -0,0 +1,357 @@
+## Overview
+
+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.
+
+## Response Format
+
+Every response MUST include a brief message (single sentence, max 64
+characters, ending with period) that introduces the schedule.
+
+**Examples**: "Here's the schedule." / "I've organized the work." /
+"This is how I'll structure it."
+
+**Critical rules**:
+- Message is MANDATORY
+- NEVER repeat the same message
+- ALWAYS end with period (.)
+- Vary phrasing naturally
+
+## Task Organization
+
+Create a hierarchical structure with dynamic nesting levels:
+
+1. **Tasks** at any level can contain subtasks
+   - action: clear description of what needs to be done (max 64 chars)
+   - subtasks: optional array of nested subtasks
+
+2. **Leaf tasks** (no subtasks) are executable operations
+   - action: what needs to be done (clear, professional English)
+   - type: operation category (REQUIRED for all leaf tasks)
+   - params: specific parameters (when relevant)
+   - config: array of resolved configuration paths in dot notation
+     (e.g., ["project.beta.repo", "env.production.url"])
+
+3. **Nesting depth**: Maximum 3 levels of nesting allowed. Use depth
+   that matches the natural workflow structure (typically 2-3 levels).
+
+## Operation Types
+
+Every task MUST have a type field. Use the appropriate type:
+
+**Parent tasks** (tasks with subtasks):
+- `group` - Hierarchical parent task that contains subtasks
+
+**Leaf tasks** (tasks without subtasks):
+- `configure` - Configuration changes, settings
+- `execute` - Shell commands, running programs (ONLY if skill exists)
+- `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
+- `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.
+
+## Configuration Requests
+
+When user wants to configure or change settings (e.g., "config",
+"configure", "change settings", "change config"), create a leaf task
+with type `configure`. Include params with query field:
+- Specific keyword if mentioned (e.g., "anthropic", "mode")
+- "app" if no specific area mentioned
+
+Example: User "change config settings" → Task with action "Configure
+settings", type "configure", params { query: "app" }
+
+## Evaluation of Requests
+
+Before creating tasks, evaluate the request type:
+
+1. **Information requests** (questions) - Use question keywords:
+   - "explain", "describe", "tell me", "what is", "how does", "find",
+     "search"
+   - Example: "explain docker" → answer type
+
+2. **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. **Vague/ambiguous requests** without clear verb:
+   - Phrases like "do something", "handle it" → ignore type
+   - Action format: "Ignore unknown 'X' request" where X is the phrase
+
+**Critical rules**:
+- Use `ignore` for unmatched verbs OR vague requests
+- Use `define` ONLY when a skill exists but needs variant selection
+- Action format for ignore: "Ignore unknown 'X' request" (lowercase X)
+- DO NOT infer or create execute tasks for unmatched verbs
+
+## Skills Integration and Placeholder Resolution
+
+When creating tasks from skills with variant placeholders, follow
+these rules:
+
+**Variant Placeholder Format**: Placeholders with uppercase path
+components (e.g., {project.VARIANT.path}, {env.TYPE.config},
+{target.PRODUCT.repo}) indicate variant resolution is required.
+
+**Resolution Process**:
+
+1. **Identify the variant** from the user's request
+   - Example: "build alpha" → variant is "alpha"
+   - Example: "deploy to staging" → variant is "staging"
+   - Example: "process experimental" → variant is "experimental"
+
+2. **Normalize to lowercase**: Convert variant name to lowercase
+   - "Alpha" → "alpha"
+   - "STAGING" → "staging"
+   - "Beta" → "beta"
+
+3. **Replace uppercase component** in ALL task actions and params
+   - Placeholder: {project.VARIANT.path}
+   - User variant: "alpha"
+   - Resolved: {project.alpha.path}
+
+4. **Include in params**: All leaf tasks must include:
+   - `skill`: the skill name (REQUIRED for skill-based tasks)
+   - `variant`: the resolved variant value (REQUIRED if skill has
+     variant placeholders)
+   - Any other parameters used in the action
+
+5. **Extract config expressions**: All leaf tasks must include a
+   `config` array listing resolved configuration paths:
+   - After resolving variant placeholders, extract all config
+     expressions from the task's execution commands
+   - List them in dot notation (e.g., "project.beta.repo",
+     "env.production.url")
+   - The app will check if these exist in ~/.plsrc and prompt for
+     missing values
+   - Example: Task with `cd {project.beta.repo}` and `cat
+     {project.beta.config}` should include config:
+     ["project.beta.repo", "project.beta.config"]
+
+**Examples**:
+
+User request with variant placeholder
+- Skill execution: `cd {project.VARIANT.repo}`
+- Variant identified from request: "beta"
+- Task action: "Navigate to Beta project directory"
+- Task params: { skill: "Skill Name", variant: "beta" }
+- Task config: ["project.beta.repo"]
+- Resolved command: `cd {project.beta.repo}`
+
+User request with different placeholder type
+- Skill execution: `setup {env.TYPE.config}`
+- Variant identified from request: "production"
+- Task action: "Setup production environment configuration"
+- Task params: { skill: "Skill Name", variant: "production" }
+- Task config: ["env.production.config"]
+- Resolved command: `setup {env.production.config}`
+
+User request with multiple config expressions
+- Skill executions: `cd {project.VARIANT.repo}`, `git checkout
+  {project.VARIANT.version}`, `make process`
+- Variant identified from request: "delta"
+- Task action: "Process Delta variant"
+- Task params: { skill: "Skill Name", variant: "delta" }
+- Task config: ["project.delta.repo", "project.delta.version"]
+- Multiple config expressions from the same task's commands
+
+**Critical Rules**:
+- NEVER leave uppercase placeholder components unresolved
+- The uppercase word can be ANY name (VARIANT, TARGET, TYPE,
+  PRODUCT, etc.)
+- All uppercase path components must be replaced with actual
+  lowercase variant
+- This applies to ALL placeholders in task actions, including those
+  from skill references
+
+## Grouping Strategy
+
+Group subtasks under logical parent tasks based on:
+- Shared purpose (e.g., "Setup environment")
+- Sequential workflow (e.g., "Deploy application")
+- Common domain (e.g., "Process data files")
+
+**Be conservative**: Only create hierarchy when there's clear logical
+grouping. Don't over-nest - use depth that matches the natural
+structure.
+
+**Circular dependency detection**: If you detect potential circular
+references or excessive nesting (>3 levels), stop and use a flatter
+structure.
+
+## Sequential and Multiple Requests
+
+When the user provides multiple requests separated by commas,
+semicolons, or the word "and":
+
+1. **Preserve the sequence**: Each operation should be represented as a
+   separate task in the order specified
+2. **Independent skill matching**: For each operation, independently
+   check if it matches a skill:
+   - If operation matches a skill → extract skill steps as subtasks
+   - If operation does NOT match a skill → create "ignore" type task
+   - **CRITICAL: Do NOT infer context or create generic execute tasks
+     for unmatched operations**
+3. **No merging**: Keep operations separate even if they seem related.
+   The user's sequence is intentional.
+
+**Examples:**
+
+- "explain docker, build production, then list the changes" → Three
+  separate task groups:
+  - Task 1: "Explain Docker" (type: answer)
+  - Task 2: "Build production" (skill-based with subtasks)
+  - Task 3: "List the changes" (type: answer or report)
+
+- "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"
+
+- "deploy service and monitor" where only "deploy" has a skill →
+  - Task 1: "Deploy service" (skill-based with subtasks)
+  - Task 2: type "ignore" for unmatched "monitor"
+
+## Strict Skill Matching
+
+Skills define the ONLY operations you can execute. If skills are
+provided in the "Available Skills" section:
+
+**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**
+
+**Common verbs that need skills:**
+
+- "analyze", "validate", "initialize", "configure", "setup", "monitor",
+  "verify", "test", "lint", "format"
+- If these verbs appear but NO corresponding skill exists → create
+  "ignore" type task
+- Do NOT create execute tasks for these verbs without explicit skills
+
+**Example:**
+
+- Available skill: "backup" (with steps: connect, export, save)
+- User: "backup data and archive it"
+- CORRECT: Tasks from backup skill + one "ignore" type task with action
+  "Ignore unknown 'archive' request"
+- WRONG: Tasks from backup skill + one execute task "Archive the backed
+  up data"
+
+## Avoiding Duplicate Tasks
+
+Each task must be semantically unique and provide distinct value.
+Before finalizing, verify there are no duplicates.
+
+**Rules for preventing duplicates:**
+
+1. **Modifiers are not separate tasks**: Adverbs and adjectives that
+   modify how to perform a task are part of the task description
+   - "explain X in simple terms" = ONE task (not "explain X" + "use
+     simple terms")
+   - "list X completely" = ONE task (not "list X" + "be complete")
+
+2. **Synonymous verbs are duplicates**: Different verbs meaning the
+   same thing are duplicates
+   - "explain X" + "describe X" = DUPLICATE (choose one)
+   - "show X" + "display X" = DUPLICATE (choose one)
+   - "check X" + "verify X" = DUPLICATE (choose one)
+
+3. **Redundant operations are duplicates**: If two tasks would perform
+   the same operation
+   - "install and set up dependencies" = ONE task (setup is part of
+     install)
+   - "check and verify disk space" = ONE task (verify means check)
+
+## Final Validation
+
+Before finalizing the schedule, perform strict validation:
+
+1. Each task represents a distinct step in the user's request
+2. Tasks are ordered in the logical sequence they should execute
+3. Each task is clearly defined with specific action and parameters
+4. Tasks are NOT merged - preserve the user's intended sequence
+5. All operations from the user's request are represented
+6. No semantic duplicates exist (same operation with different words)
+7. For skill-based tasks, verify all required params are included
+   (skill name, variant if applicable)
+8. For leaf tasks, verify type field is present
+9. For leaf tasks with config placeholders, verify config array is
+   populated
+
+## Critical Guidelines
+
+1. **Atomic subtasks**: Each subtask must be independently executable
+2. **No duplication**: Ensure subtasks don't repeat work
+3. **Preserve order**: Maintain logical execution sequence
+4. **Professional language**: Use clear, technical terminology
+5. **Concise actions**: Keep descriptions under 64 characters
+6. **Config extraction**: Every leaf task must include a config array
+   with all resolved configuration paths found in its execution
+   commands
+
+## Examples
+
+**Simple request**:
+User: "install dependencies"
+Schedule: One task "Install dependencies" (type: group) with subtask:
+install project dependencies (type: execute)
+
+**Two-level hierarchy**:
+User: "deploy to production"
+Schedule: One task "Deploy to production" (type: group) with subtasks:
+- Build application (type: execute)
+- Run tests (type: execute)
+- Push to server (type: execute)
+
+**Three-level hierarchy**:
+User: "setup and deploy"
+Schedule: Two tasks:
+- "Setup environment" (type: group)
+  - "Install dependencies" (type: group)
+    - Install Python packages (type: execute)
+    - Install Node modules (type: execute)
+  - "Configure settings" (type: configure)
+- "Deploy application" (type: group)
+  - "Build and test" (type: group)
+    - Build application (type: execute)
+    - Run tests (type: execute)
+  - "Release" (type: execute)
+
+**Information request**:
+User: "explain docker"
+Schedule: One task "Explain Docker" (type: group) with subtask: explain
+what Docker is and its use (type: answer)
+
+**Skill with variant placeholder**:
+User request with variant
+Schedule: One task (type: group) with subtasks:
+- First task action (type: execute, params: { skill: "Skill Name",
+  variant: "beta" }, config: ["project.beta.repo"])
+- Second task action (type: execute, params: { skill: "Skill Name",
+  variant: "beta" }, config: [])
+- Third task action (type: execute, params: { skill: "Skill Name",
+  variant: "beta" }, config: [])
+
+Note: The first subtask includes config: ["project.beta.repo"] because
+its execution command is `cd {project.beta.repo}`. The app will check
+if this value exists in ~/.plsrc and prompt the user if missing.

package/dist/skills/validate.md

@@ -21,9 +21,9 @@ You will receive information about missing configuration values:
 Generate a response with two required fields:
 
 1. **message**: An empty string `""`
-2. **tasks**: An array of CONFIG tasks, one for each missing config value
+2. **tasks**: An array of CONFIGURE tasks, one for each missing config value
 
-For each CONFIG task, create a natural language description that:
+For each CONFIGURE task, create a natural language description that:
 
 1. **Explains what the value is for** using context from the skill's
    description
@@ -59,7 +59,7 @@ message: ""
 tasks: [
   {
     action: "Path to Alpha repository",
-    type: "config",
+    type: "configure",
     params: { key: "project.alpha.repo" }
   }
 ]
@@ -78,7 +78,7 @@ message: ""
 tasks: [
   {
     action: "Staging environment URL",
-    type: "config",
+    type: "configure",
     params: { key: "env.staging.url" }
   }
 ]
@@ -97,7 +97,7 @@ message: ""
 tasks: [
   {
     action: "Path to Beta workspace",
-    type: "config",
+    type: "configure",
     params: { key: "workspace.beta.path" }
   }
 ]
@@ -129,14 +129,15 @@ tasks: [
 
 ## Response Format
 
-Return a message field (can be empty string) and an array of CONFIG tasks:
+Return a message field (can be empty string) and an array of CONFIGURE
+tasks:
 
 ```
 message: ""
 tasks: [
   {
     action: "Natural description without config path",
-    type: "config",
+    type: "configure",
     params: { key: "config.path" }
   },
   // ... more tasks
@@ -145,7 +146,7 @@ tasks: [
 
 ## Important Notes
 
-- All tasks must have type "config"
+- All tasks must have type: "configure"
 - All tasks must include params.key with the config path
 - Descriptions should be helpful and contextual, not just technical
 - Use information from Available Skills section to provide context

package/dist/tools/{config.tool.js → configure.tool.js}

@@ -1,5 +1,5 @@
-export const configTool = {
-    name: 'config',
+export const configureTool = {
+    name: 'configure',
     description: 'Determine which configuration settings to show based on user query. Receives available config keys with descriptions and returns which keys the user wants to configure.',
     input_schema: {
         type: 'object',
@@ -10,25 +10,25 @@ export const configTool = {
             },
             tasks: {
                 type: 'array',
-                description: 'Array of config settings to configure. Each task has type "config" and params with the config key.',
+                description: 'Settings the user wants to configure. Each task specifies which setting to configure.',
                 items: {
                     type: 'object',
                     properties: {
                         action: {
                             type: 'string',
-                            description: 'Description of the config setting (from the provided descriptions). Maximum 64 characters.',
+                            description: 'Description of the setting (from the provided descriptions). Maximum 64 characters.',
                         },
                         type: {
                             type: 'string',
-                            description: 'Always "config" for configuration tasks.',
+                            description: 'Task type. Always "configure" for settings.',
                         },
                         params: {
                             type: 'object',
-                            description: 'Parameters for the config task.',
+                            description: 'Task parameters.',
                             properties: {
                                 key: {
                                     type: 'string',
-                                    description: 'The config key to configure (e.g., "anthropic.key", "settings.debug").',
+                                    description: 'The setting key to configure (e.g., "anthropic.key", "settings.debug").',
                                 },
                             },
                             required: ['key'],

package/dist/tools/schedule.tool.js

@@ -0,0 +1,55 @@
+export const scheduleTool = {
+    name: 'schedule',
+    description: 'Organize user requests into hierarchical task structures with dynamically nested subtasks. Create logical groupings based on workflow phases and shared purposes. Supports multiple levels of nesting.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            message: {
+                type: 'string',
+                description: 'Introductory message before the schedule. Single sentence, max 64 characters. Vary naturally.',
+            },
+            tasks: {
+                type: 'array',
+                description: 'Array of top-level tasks with optional nested subtasks',
+                items: {
+                    $ref: '#/$defs/task',
+                },
+            },
+        },
+        required: ['message', 'tasks'],
+        $defs: {
+            task: {
+                type: 'object',
+                properties: {
+                    action: {
+                        type: 'string',
+                        description: 'Description of what needs to be done (max 64 chars)',
+                    },
+                    type: {
+                        type: 'string',
+                        description: 'Type: "group" for parent tasks with subtasks. For leaf tasks: "config", "execute", "answer", "introspect", "report", "define", "ignore"',
+                    },
+                    params: {
+                        type: 'object',
+                        description: 'Parameters for leaf tasks (e.g., command, path)',
+                    },
+                    config: {
+                        type: 'array',
+                        description: 'Array of configuration paths needed for this task in dot notation (e.g., ["product.alpha.path", "env.staging.url"])',
+                        items: {
+                            type: 'string',
+                        },
+                    },
+                    subtasks: {
+                        type: 'array',
+                        description: 'Optional nested subtasks. Omit for executable leaf tasks.',
+                        items: {
+                            $ref: '#/$defs/task',
+                        },
+                    },
+                },
+                required: ['action'],
+            },
+        },
+    },
+};

package/dist/tools/validate.tool.js

@@ -20,7 +20,7 @@ export const validateTool = {
                         },
                         type: {
                             type: 'string',
-                            description: 'Must be "config" for all tasks returned by this tool',
+                            description: 'Must be "configure" for all tasks returned by this tool',
                         },
                         params: {
                             type: 'object',

package/dist/types/types.js

@@ -5,7 +5,7 @@ export var ComponentName;
     ComponentName["Message"] = "message";
     ComponentName["Debug"] = "debug";
     ComponentName["Command"] = "command";
-    ComponentName["Plan"] = "plan";
+    ComponentName["Schedule"] = "schedule";
     ComponentName["Refinement"] = "refinement";
     ComponentName["Feedback"] = "feedback";
     ComponentName["Confirm"] = "confirm";
@@ -17,8 +17,8 @@ export var ComponentName;
 })(ComponentName || (ComponentName = {}));
 export var TaskType;
 (function (TaskType) {
-    TaskType["Config"] = "config";
-    TaskType["Plan"] = "plan";
+    TaskType["Config"] = "configure";
+    TaskType["Schedule"] = "schedule";
     TaskType["Execute"] = "execute";
     TaskType["Answer"] = "answer";
     TaskType["Introspect"] = "introspect";
@@ -27,6 +27,7 @@ export var TaskType;
     TaskType["Ignore"] = "ignore";
     TaskType["Select"] = "select";
     TaskType["Discard"] = "discard";
+    TaskType["Group"] = "group";
 })(TaskType || (TaskType = {}));
 export var FeedbackType;
 (function (FeedbackType) {