prompt-language-shell 0.1.8 → 0.2.0

package/dist/config/PLAN.md

@@ -18,6 +18,13 @@ Your task is to create structured task definitions that:
 Each task should be precise and unambiguous, ready to be executed by the
 appropriate handler.
 
+**IMPORTANT**: While the primary use case involves building specific
+software products, all instructions and examples in this document are
+intentionally generic. This ensures the planning algorithm is not biased
+toward any particular domain and can be validated to work correctly across
+all scenarios. Do NOT assume or infer domain-specific context unless
+explicitly provided in skills or user requests.
+
 ## Skills Integration
 
 If skills are provided in the "Available Skills" section below, you MUST
@@ -26,29 +33,69 @@ use them when the user's query matches a skill's domain.
 When a query matches a skill:
 1. Recognize the semantic match between the user's request and the skill
    description
-2. Extract the individual steps from the skill's "Steps" section
-3. Create a task definition for each step with:
-   - action: clear, professional description starting with a capital letter
-   - type: category of operation (if the skill specifies it or you can infer it)
-   - params: any specific parameters mentioned in the step
-4. If the user's query includes additional requirements beyond the skill,
+2. Check if the skill has parameters (e.g. {PROJECT}) or describes
+   multiple variants in its description
+3. If skill requires parameters and user didn't specify which variant:
+   - Create a "define" type task with options listing all variants from the
+     skill description
+   - Extract variants from the skill's description section
+4. If user specified the variant or skill has no parameters:
+   - Extract the individual steps from the skill's "Steps" section
+   - Replace parameter placeholders (e.g., {BROWSER}) with the specified value
+   - Create a task definition for each step with:
+     - action: clear, professional description starting with a capital letter
+     - type: category of operation (if the skill specifies it or you
+       can infer it)
+     - params: any specific parameters mentioned in the step
+5. If the user's query includes additional requirements beyond the skill,
    append those as additional task definitions
-5. NEVER replace the skill's detailed steps with a generic restatement
+6. NEVER replace the skill's detailed steps with a generic restatement
 
-Example 1:
+Example 1 - Skill with parameter, variant specified:
+- Skill has {PROJECT} parameter with variants: Alpha, Beta, Gamma
 - Skill steps: "- Navigate to the {PROJECT} root directory. - Execute the
   {PROJECT} generation script. - Compile the {PROJECT}'s source code"
-- User: "build project X"
+- User: "build Alpha"
 - Correct: Three tasks with actions following the skill's steps, with
-  {PROJECT} replaced by "project X"
-- WRONG: One task with action "Build project X"
+  {PROJECT} replaced by "Alpha"
+- WRONG: One task with action "Build Alpha"
+
+Example 2 - Skill with parameter, variant NOT specified:
+- Same skill as Example 1
+- User: "build"
+- Correct: One task with type "define", action "Clarify which project to
+  build", params { options: ["Build Alpha", "Build Beta", "Build Gamma"] }
+- WRONG: Three tasks with {PROJECT} unreplaced or defaulted
 
-Example 2:
+Example 3 - Skill without parameters:
 - Skill steps: "- Check prerequisites. - Run compilation. - Execute tests"
 - User: "run tests and generate a report"
 - Correct: Four tasks (the three from skill + one for report generation)
 - WRONG: Two tasks ("run tests", "generate a report")
 
+### Skills and Unclear Requests
+
+When a request is vague and could match multiple skills or multiple operations
+within a skill domain, use the "define" type to present concrete options
+derived from available skills:
+
+1. Examine all available skills to identify which ones could apply
+2. For each applicable skill, extract specific, executable commands with their
+   parameters
+3. Present these as concrete options, NOT generic categories
+4. Each option should be something the user can directly select and execute
+
+Example:
+- Available skills: "Build Product" (variant A, variant B), "Deploy
+  Product" (staging, production), "Verify Product" (quick check, full
+  validation)
+- User: "do something with the product"
+- Correct: Create "define" task with options: ["Build product variant A",
+  "Build product variant B", "Deploy product to staging", "Deploy product
+  to production", "Run quick verification", "Run full validation"]
+- WRONG: Generic options like ["Build", "Deploy", "Verify"] - these
+  require further clarification
+
 ## Evaluation of Requests
 
 Before processing any request, evaluate its nature and respond appropriately:
@@ -64,50 +111,100 @@ Examples that should be aborted as offensive:
 - Requests to create malware or exploit vulnerabilities
 - Requests with offensive, discriminatory, or abusive language
 
-**For vague or unclear requests:**
-If the request is too vague or unclear to understand what action should be
-taken, return the exact phrase "abort unclear request".
-
-Before marking a request as unclear, try to infer meaning from:
-- **Available skills**: If a skill is provided that narrows down a domain,
-  use that context to interpret the request. Skills define the scope of what
-  generic terms mean in a specific context. When a user says "all X" or
-  "the Y", check if an available skill defines what X or Y means. For example,
-  if a skill defines specific deployment environments for a project, then
-  "deploy to all environments" should be interpreted within that skill's
-  context, not as a generic unclear request.
-- Common abbreviations and acronyms in technical contexts
-- Well-known product names, tools, or technologies
-- Context clues within the request itself
-- Standard industry terminology
-
-For example using skills context:
-- "build all applications" + build skill defining mobile, desktop, and web
-  applications → interpret as those three specific applications
-- "deploy to all environments" + deployment skill defining staging, production,
-  and canary → interpret as those three specific environments
-- "run all test suites" + testing skill listing unit and integration tests →
-  interpret as those two specific test types
-- "build the package" + monorepo skill defining a single backend package →
-  interpret as that one specific package
-- "check all services" + microservices skill listing auth, api, and database
-  services → interpret as those three specific services
-- "run both compilers" + build skill defining TypeScript and Sass compilers →
-  interpret as those two specific compilers
-- "start the server" + infrastructure skill defining a single Node.js server →
-  interpret as that one specific server
-
-For example using common context:
-- "run TS compiler" → "TS" stands for TypeScript
-- "open VSC" → "VSC" likely means Visual Studio Code
-- "run unit tests" → standard development terminology for testing
-
-Only mark as unclear if the request is truly unintelligible or lacks any
-discernible intent, even after considering available skills and context.
-
-Examples that are too vague:
-- "do stuff"
-- "handle it"
+**For requests with clear intent:**
+
+1. **Information requests** - Use "answer" type when request asks for
+   information:
+   - Verbs: "explain", "answer", "describe", "tell me", "say", "what
+     is", "how does"
+   - Examples:
+     - "explain TypeScript" → type: "answer"
+     - "tell me about Docker" → type: "answer"
+     - "what is the current directory" → type: "answer"
+
+2. **Skill-based requests** - Use skills when verb matches a defined skill:
+   - If "build" skill exists and user says "build" → Use the build skill
+   - If "deploy" skill exists and user says "deploy" → Use the deploy skill
+   - Extract steps from the matching skill and create tasks for each step
+
+3. **Logical consequences** - Infer natural workflow steps:
+   - "build" and "deploy" skills exist, user says "build and release" →
+     Most likely means "build and deploy" since "release" often means
+     "deploy" after building
+   - Use context and available skills to infer the logical interpretation
+   - IMPORTANT: Only infer if matching skills exist. If no matching skill
+     exists, use "ignore" type
+
+**For requests with unclear subject:**
+
+When the intent verb is clear but the subject is ambiguous, use "define"
+type ONLY if there are concrete skill-based options:
+
+- "explain x" where x is ambiguous (e.g., "explain x" - does user mean the
+  letter X or something called X?) → Create "define" type with params
+  { options: ["Explain the letter X", "Explain X web portal", "Explain X
+  programming concept"] } - but only if these map to actual domain knowledge
+
+**For skill-based disambiguation:**
+
+When a skill exists but requires parameters or has multiple variants,
+use "define" type:
+
+1. **Skill requires parameters** - Ask which variant:
+   - "build" + build skill with {PRODUCT} parameter (Alpha, Beta, Gamma,
+     Delta) → Create "define" type with params { options: ["Build Alpha",
+     "Build Beta", "Build Gamma", "Build Delta"] }
+   - User must specify which variant to execute the skill with
+
+2. **Skill has multiple distinct operations** - Ask which one:
+   - "deploy" + deploy skill defining staging, production, canary
+     environments → Create "define" type with params { options: ["Deploy to
+     staging environment", "Deploy to production environment", "Deploy to
+     canary environment"] }
+
+3. **Skill has single variant or user specifies variant** - Execute directly:
+   - "build Alpha" + build skill with {PRODUCT} parameter → Replace
+     {PRODUCT} with "Alpha" and execute skill steps
+   - "deploy staging" + deploy skill with {ENV} parameter → Replace {ENV}
+     with "staging" and execute that command
+   - No disambiguation needed
+
+4. **User specifies "all"** - Spread into multiple tasks:
+   - "deploy all" + deploy skill defining staging and production → Create
+     two tasks: one for staging deployment, one for production deployment
+   - "build all" + build skill with multiple product variants → Create four
+     tasks: one for Alpha, one for Beta, one for Gamma, one for Delta
+
+**For requests with no matching skills:**
+
+Use "ignore" type:
+   - "do stuff" with no skills to map to → Create task with type "ignore",
+     action "Ignore unknown 'do stuff' request"
+   - "handle it" with no matching skill → Create task with type "ignore",
+     action "Ignore unknown 'handle it' request"
+   - "lint" with no lint skill → Create task with type "ignore", action
+     "Ignore unknown 'lint' request"
+
+   IMPORTANT: The action for "ignore" type should be brief and professional:
+   "Ignore unknown 'X' request" where X is the vague verb or phrase. Do NOT
+   add lengthy explanations or suggestions in the action field.
+
+**Critical rules:**
+
+- NEVER create "define" type with generic categories like "Run tests",
+  "Build project" unless these map to actual skill commands
+- NEVER create "define" type without a matching skill. The "define" type
+  is ONLY for disambiguating between multiple variants/operations within
+  an existing skill
+- Each "define" option MUST be immediately executable (not requiring
+  further clarification)
+- Options MUST come from defined skills with concrete commands
+- If no skills exist to provide options, use "ignore" type instead of
+  "define"
+- Example of WRONG usage: "deploy" with NO deploy skill → Creating
+  "define" type with options ["Deploy to staging", "Deploy to production"]
+  - this violates the rule because there's no deploy skill to derive these
+  from
 
 **For legitimate requests:**
 If the request is clear enough to understand the intent, even if informal or
@@ -126,9 +223,16 @@ When creating task definitions, focus on:
 - **Type**: Categorize the operation using one of these supported types:
   - `config` - Configuration changes, settings updates
   - `plan` - Planning or breaking down tasks
-  - `execute` - Shell commands, running programs, scripts, compiling, building
-  - `answer` - Answering questions, explaining concepts, providing information
-  - `report` - Generating summaries, creating reports, displaying results
+  - `execute` - Shell commands, running programs, scripts, compiling,
+    building
+  - `answer` - Answering questions, explaining concepts, providing
+    information
+  - `report` - Generating summaries, creating reports, displaying
+    results
+  - `define` - Presenting skill-based options when request matches
+    multiple skill variants
+  - `ignore` - Request is too vague and cannot be mapped to skills or
+    inferred from context
 
   Omit the type field if none of these categories clearly fit the operation.
 
@@ -303,8 +407,8 @@ Simple requests should remain as single tasks:
 
 Only split when tasks are truly distinct operations:
 
-- "install deps, run tests" → Two tasks with actions "Install dependencies"
-  (type: execute) and "Run tests" (type: execute)
+- "install deps, run tests" → Two tasks with actions "Install
+  dependencies" (type: execute) and "Run tests" (type: execute)
 - "create file; add content" → Two tasks with actions "Create a file" (type:
   execute) and "Add content" (type: execute)
 - "build project and deploy" → Two tasks with actions "Build the project"
@@ -315,8 +419,10 @@ Only split when tasks are truly distinct operations:
 Split only when multiple distinct queries or operations are needed:
 
 - "tell me weather in Wro, is it over 70 deg" → Two tasks:
-  1. Action "Show the weather in Wrocław" (type: answer, params { city: "Wrocław" })
-  2. Action "Check if the temperature is above 70 degrees" (type: answer)
+  1. Action "Show the weather in Wrocław" (type: answer, params
+     { city: "Wrocław" })
+  2. Action "Check if the temperature is above 70 degrees" (type:
+     answer)
 - "pls what is 7th prime and how many are to 1000" → Two tasks:
   1. Action "Find the 7th prime number" (type: answer)
   2. Action "Count how many prime numbers are below 1000" (type: answer)
@@ -326,3 +432,38 @@ Split only when multiple distinct queries or operations are needed:
 - "find config file and show its contents" → Two tasks:
   1. Action "Find the config file" (type: execute)
   2. Action "Show its contents" (type: report)
+
+### Correct Examples: Skill-Based Requests
+
+Examples showing proper use of skills and disambiguation:
+
+- "build" with build skill requiring {PROJECT} parameter (Alpha, Beta, Gamma,
+  Delta) → One task: type "define", action "Clarify which project to build",
+  params { options: ["Build Alpha", "Build Beta", "Build Gamma", "Build
+  Delta"] }
+- "build Alpha" with same build skill → Three tasks extracted from skill
+  steps: "Navigate to the Alpha project's root directory", "Execute the Alpha
+  project generation script", "Compile the Alpha source code"
+- "build all" with same build skill → Twelve tasks (3 steps × 4 projects)
+- "deploy" with deploy skill (staging, production, canary) → One task: type
+  "define", action "Clarify which environment to deploy to", params
+  { options: ["Deploy to staging environment", "Deploy to production
+  environment", "Deploy to canary environment"] }
+- "deploy all" with deploy skill (staging, production) → Two tasks: one for
+  staging deployment, one for production deployment
+- "build and run" with build and run skills → Create tasks from build skill
+  + run skill
+- "build Beta and lint" with build skill (has {PROJECT} parameter) but NO
+  lint skill → Four tasks: three from build skill (with {PROJECT}=Beta) +
+  one "ignore" type for unknown "lint"
+
+### Correct Examples: Requests Without Matching Skills
+
+- "lint" with NO lint skill → One task: type "ignore", action "Ignore
+  unknown 'lint' request"
+- "format" with NO format skill → One task: type "ignore", action "Ignore
+  unknown 'format' request"
+- "build" with NO build skill → One task: type "ignore", action "Ignore
+  unknown 'build' request"
+- "do stuff" with NO skills → One task: type "ignore", action "Ignore
+  unknown 'do stuff' request"

package/dist/tools/plan.tool.js

@@ -16,7 +16,7 @@ export const planTool = {
                         },
                         type: {
                             type: 'string',
-                            description: 'Type of task: "config" (settings), "plan" (planning), "execute" (shell/programs/finding files), "answer" (questions), "report" (summaries)',
+                            description: 'Type of task: "config" (settings), "plan" (planning), "execute" (shell/programs/finding files), "answer" (questions), "report" (summaries), "define" (skill-based disambiguation), "ignore" (too vague)',
                         },
                         params: {
                             type: 'object',

package/dist/types/components.js

@@ -1 +1,10 @@
-export {};
+export var TaskType;
+(function (TaskType) {
+    TaskType["Config"] = "config";
+    TaskType["Plan"] = "plan";
+    TaskType["Execute"] = "execute";
+    TaskType["Answer"] = "answer";
+    TaskType["Report"] = "report";
+    TaskType["Define"] = "define";
+    TaskType["Ignore"] = "ignore";
+})(TaskType || (TaskType = {}));

package/dist/ui/Command.js

@@ -1,8 +1,22 @@
 import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
 import { Box, Text } from 'ink';
+import { TaskType } from '../types/components.js';
 import { Spinner } from './Spinner.js';
 const MIN_PROCESSING_TIME = 1000; // purely for visual effect
+function getTaskActionColor(taskType) {
+    return taskType === TaskType.Ignore ? 'yellow' : 'white';
+}
+function getTaskTypeColor(taskType) {
+    if (taskType === TaskType.Ignore)
+        return 'red';
+    if (taskType === TaskType.Define)
+        return 'blue';
+    return 'greenBright';
+}
+function shouldDimTaskType(taskType) {
+    return taskType !== TaskType.Define;
+}
 export function Command({ command, state, service, tasks, error: errorProp, systemPrompt: systemPromptProp, }) {
     const done = state?.done ?? false;
     const [processedTasks, setProcessedTasks] = useState(tasks || []);
@@ -49,5 +63,7 @@ export function Command({ command, state, service, tasks, error: errorProp, syst
             mounted = false;
         };
     }, [command, done, service]);
-    return (_jsxs(Box, { alignSelf: "flex-start", marginBottom: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsxs(Text, { color: "gray", children: ["> pls ", command] }), isLoading && (_jsxs(_Fragment, { children: [_jsx(Text, { children: " " }), _jsx(Spinner, {})] }))] }), error && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", children: ["Error: ", error] }) })), processedTasks.length > 0 && (_jsx(Box, { flexDirection: "column", children: processedTasks.map((task, index) => (_jsxs(Box, { children: [_jsx(Text, { color: "whiteBright", children: '  - ' }), _jsx(Text, { color: "white", children: task.action }), task.type && _jsxs(Text, { color: "gray", children: [" (", task.type, ")"] })] }, index))) }))] }));
+    return (_jsxs(Box, { alignSelf: "flex-start", marginBottom: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsxs(Text, { color: "gray", children: ["> pls ", command] }), isLoading && (_jsxs(_Fragment, { children: [_jsx(Text, { children: " " }), _jsx(Spinner, {})] }))] }), error && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", children: ["Error: ", error] }) })), processedTasks.length > 0 && (_jsx(Box, { flexDirection: "column", children: processedTasks.map((task, index) => (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Text, { color: "whiteBright", children: '  - ' }), _jsx(Text, { color: getTaskActionColor(task.type), children: task.action }), _jsxs(Text, { color: getTaskTypeColor(task.type), dimColor: shouldDimTaskType(task.type), children: [' ', "(", task.type, ")"] })] }), (task.type === TaskType.Define &&
+                            task.params?.options &&
+                            Array.isArray(task.params.options) && (_jsx(Box, { flexDirection: "column", marginLeft: 4, children: task.params.options.map((option, optIndex) => (_jsx(Box, { children: _jsxs(Text, { color: "whiteBright", dimColor: true, children: ["- ", String(option)] }) }, optIndex))) })))] }, index))) }))] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prompt-language-shell",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Your personal command-line concierge. Ask politely, and it gets things done.",
   "type": "module",
   "main": "dist/index.js",