prompt-language-shell 0.6.4 → 0.6.6

package/README.md

@@ -2,8 +2,8 @@
 
 Your personal command-line concierge. Ask politely, and it gets things done.
 
-> **Note:** This project is in early preview. Features and APIs may change as
-> development continues.
+> **Note:** This project is in early preview. Features and APIs will change.
+> See [roadmap](#roadmap).
 
 ## Installation
 
@@ -13,14 +13,14 @@ npm install -g prompt-language-shell
 
 ## Setup
 
-On first run, `pls` walks you through a quick setup. Your settings will be saved to `~/.plsrc`.
+On first run, `pls` walks you through a quick setup.
+Your settings will be saved to `~/.plsrc`.
 
 ## Usage
 
 Type `pls` followed by your request in natural language.
 
-To see what `pls` can
-do, start by listing available capabilities:
+To see what `pls` can do, start by listing available capabilities:
 
 ```
 $ pls list skills
@@ -98,6 +98,8 @@ Skills let you teach `pls` about your project-specific workflows. Create
 markdown files in `~/.pls/skills/` to define custom operations that `pls` can
 understand and execute.
 
+For complete documentation, see [docs/SKILLS.md](./docs/SKILLS.md).
+
 ### Structure
 
 Each skill file uses a simple markdown format:
@@ -155,6 +157,13 @@ $ pls build dev
 $ pls build test
 ```
 
+## Roadmap
+
+- **0.7** - Comprehend skill, simplified prompts, better debugging
+- **0.8** - Sequential and interlaced skill execution
+- **0.9** - Learn skill, codebase refinement, complex dependency handling
+- **1.0** - Production release
+
 ## Development
 
 See [CLAUDE.md](./CLAUDE.md) for development guidelines and architecture.

package/dist/config/INTROSPECT.md

@@ -88,6 +88,8 @@ These MUST appear AFTER Execute and BEFORE user skills:
 If skills are provided in the "Available Skills" section below, include them
 in the response. For each skill:
 - Extract the skill name from the first heading (# Skill Name)
+- If the skill name contains "(INCOMPLETE)", preserve it exactly in the task
+  action
 - Extract a brief description from the Description or Overview section
 - Keep descriptions concise (1-2 lines maximum)
 - If the user specified a filter (e.g., "skills for deployment"), only include

package/dist/services/anthropic.js

@@ -1,6 +1,6 @@
 import Anthropic from '@anthropic-ai/sdk';
 import { getAvailableConfigStructure, getConfiguredKeys, } from './configuration.js';
-import { formatSkillsForPrompt, loadSkills } from './skills.js';
+import { formatSkillsForPrompt, loadSkillsWithValidation } from './skills.js';
 import { toolRegistry } from './tool-registry.js';
 /**
  * Wraps text to ensure no line exceeds the specified width.
@@ -62,7 +62,7 @@ export class AnthropicService {
             toolName === 'introspect' ||
             toolName === 'execute' ||
             toolName === 'validate') {
-            const skills = loadSkills();
+            const skills = loadSkillsWithValidation();
             const skillsSection = formatSkillsForPrompt(skills);
             systemPrompt += skillsSection;
         }

package/dist/services/execution-validator.js

@@ -5,25 +5,47 @@ import { expandSkillReferences } from './skill-expander.js';
 import { getConfigType, parseSkillMarkdown } from './skill-parser.js';
 /**
  * Validate config requirements for execute tasks
- * Returns missing config requirements
+ * Returns validation result with missing config and validation errors
  */
 export function validateExecuteTasks(tasks) {
     const userConfig = loadUserConfig();
     const missing = [];
     const seenPaths = new Set();
-    // Load and parse all skills for validation
+    const validationErrors = [];
+    const seenSkills = new Set();
+    // Load all skills (including invalid ones for validation)
     const skillContents = loadSkills();
-    const parsedSkills = skillContents
-        .map((content) => parseSkillMarkdown(content))
-        .filter((s) => s !== null);
+    const parsedSkills = skillContents.map((content) => parseSkillMarkdown(content));
     const skillLookup = (name) => parsedSkills.find((s) => s.name === name) || null;
+    // Check for invalid skills being used in tasks
+    for (const task of tasks) {
+        const skillName = typeof task.params?.skill === 'string' ? task.params.skill : null;
+        if (skillName && !seenSkills.has(skillName)) {
+            seenSkills.add(skillName);
+            // Check if this skill is invalid
+            const skill = skillLookup(skillName);
+            if (skill && !skill.isValid) {
+                validationErrors.push({
+                    skill: skill.name,
+                    issues: [skill.validationError || 'Unknown validation error'],
+                });
+            }
+        }
+    }
+    // If there are validation errors, return early
+    if (validationErrors.length > 0) {
+        return {
+            missingConfig: [],
+            validationErrors,
+        };
+    }
     for (const task of tasks) {
         // Check if task originates from a skill
         const skillName = typeof task.params?.skill === 'string' ? task.params.skill : null;
         if (skillName) {
             // Task comes from a skill - check skill's Execution section
             const skill = skillLookup(skillName);
-            if (!skill || !skill.execution) {
+            if (!skill) {
                 continue;
             }
             // Get variant from task params (if any)
@@ -106,5 +128,8 @@ export function validateExecuteTasks(tasks) {
             }
         }
     }
-    return missing;
+    return {
+        missingConfig: missing,
+        validationErrors: [],
+    };
 }

package/dist/services/skill-expander.js

@@ -37,10 +37,6 @@ export function expandSkillReferences(execution, skillLookup, visited = new Set(
             expanded.push(line);
             continue;
         }
-        if (!skill.execution || skill.execution.length === 0) {
-            // Referenced skill has no execution, skip
-            continue;
-        }
         // Recursively expand referenced skill's execution
         const newVisited = new Set(visited);
         newVisited.add(skillName);
@@ -62,7 +58,7 @@ export function getReferencedSkills(execution, skillLookup, visited = new Set())
         }
         referenced.add(skillName);
         const skill = skillLookup(skillName);
-        if (skill && skill.execution) {
+        if (skill) {
             const newVisited = new Set(visited);
             newVisited.add(skillName);
             const nested = getReferencedSkills(skill.execution, skillLookup, newVisited);

package/dist/services/skill-parser.js

@@ -1,40 +1,85 @@
 import YAML from 'yaml';
 /**
- * Parse a skill markdown file into structured definition
+ * Validate a skill without parsing it fully
+ * Returns validation error if skill is invalid, null if valid
  */
-export function parseSkillMarkdown(content) {
+export function validateSkill(content) {
     const sections = extractSections(content);
-    // Name is required
+    // Name is required for error reporting
+    const skillName = sections.name || 'Unknown skill';
+    // Check required sections
     if (!sections.name) {
-        return null;
+        return {
+            skillName,
+            error: 'The skill file is missing a Name section',
+        };
     }
-    // Description is required
     if (!sections.description) {
-        return null;
+        return {
+            skillName,
+            error: 'The skill file is missing a Description section',
+        };
     }
-    // Steps are required
     if (!sections.steps || sections.steps.length === 0) {
-        return null;
-    }
-    // Validate execution and steps have same count (if execution exists)
-    if (sections.execution &&
-        sections.execution.length !== sections.steps.length) {
-        return null;
-    }
+        return {
+            skillName,
+            error: 'The skill file is missing a Steps section',
+        };
+    }
+    if (!sections.execution || sections.execution.length === 0) {
+        return {
+            skillName,
+            error: 'The skill file is missing an Execution section',
+        };
+    }
+    // Execution and steps must have same count
+    if (sections.execution.length !== sections.steps.length) {
+        return {
+            skillName,
+            error: `The skill has ${String(sections.steps.length)} steps but ${String(sections.execution.length)} execution lines`,
+        };
+    }
+    return null;
+}
+/**
+ * Parse a skill markdown file into structured definition
+ */
+export function parseSkillMarkdown(content) {
+    const sections = extractSections(content);
+    // Validate the skill
+    const validationError = validateSkill(content);
+    // For invalid skills, return minimal definition with error
+    if (validationError) {
+        return {
+            name: sections.name || 'Unknown skill',
+            description: sections.description || '',
+            steps: sections.steps || [],
+            execution: sections.execution || [],
+            isValid: false,
+            validationError: validationError.error,
+            isIncomplete: true,
+        };
+    }
+    // Valid skill - all required fields are present (validation passed)
+    const description = sections.description;
     const skill = {
         name: sections.name,
-        description: sections.description,
+        description,
         steps: sections.steps,
+        execution: sections.execution,
+        isValid: true,
     };
+    // Check if skill is incomplete (valid but needs more documentation)
+    const MIN_DESCRIPTION_LENGTH = 20;
+    if (description.trim().length < MIN_DESCRIPTION_LENGTH) {
+        skill.isIncomplete = true;
+    }
     if (sections.aliases && sections.aliases.length > 0) {
         skill.aliases = sections.aliases;
     }
     if (sections.config) {
         skill.config = sections.config;
     }
-    if (sections.execution && sections.execution.length > 0) {
-        skill.execution = sections.execution;
-    }
     return skill;
 }
 /**
@@ -46,8 +91,8 @@ function extractSections(content) {
     let currentSection = null;
     let sectionLines = [];
     for (const line of lines) {
-        // Check for section headers (### SectionName)
-        const headerMatch = line.match(/^###\s+(.+)$/);
+        // Check for section headers (any valid markdown header: #, ##, ###, etc.)
+        const headerMatch = line.match(/^#{1,6}\s+(.+)$/);
         if (headerMatch) {
             // Process previous section
             if (currentSection) {

package/dist/services/skills.js

@@ -35,18 +35,26 @@ export function loadSkills() {
 }
 /**
  * Load and parse all skill definitions
- * Returns structured skill definitions
+ * Returns structured skill definitions (including invalid skills)
  */
 export function loadSkillDefinitions() {
     const skillContents = loadSkills();
-    const definitions = [];
-    for (const content of skillContents) {
+    return skillContents.map((content) => parseSkillMarkdown(content));
+}
+/**
+ * Load skills and mark incomplete ones in their markdown
+ * Returns array of skill markdown with status markers
+ */
+export function loadSkillsWithValidation() {
+    const skillContents = loadSkills();
+    return skillContents.map((content) => {
         const parsed = parseSkillMarkdown(content);
-        if (parsed) {
-            definitions.push(parsed);
+        // If skill is incomplete (either validation failed or needs more documentation), append (INCOMPLETE) to the name
+        if (parsed.isIncomplete) {
+            return content.replace(/^(#{1,6}\s+Name\s*\n+)(.+?)(\n|$)/im, `$1$2 (INCOMPLETE)$3`);
         }
-    }
-    return definitions;
+        return content;
+    });
 }
 /**
  * Create skill lookup function from definitions
@@ -72,6 +80,10 @@ export function formatSkillsForPrompt(skills) {
 The following skills define domain-specific workflows. When the user's
 query matches a skill, incorporate the skill's steps into your plan.
 
+Skills marked with (INCOMPLETE) have validation errors or need more
+documentation, and cannot be executed. These should be listed in
+introspection with their markers.
+
 **IMPORTANT**: When creating options from skill descriptions, do NOT use
 brackets for additional information. Use commas instead. For example:
 - CORRECT: "Build project Alpha, the legacy version"

package/dist/services/task-router.js

@@ -125,9 +125,19 @@ function executeTasksAfterConfirm(tasks, service, userRequest, handlers) {
     }
     else {
         // Execute tasks with validation
-        const missingConfig = validateExecuteTasks(tasks);
-        if (missingConfig.length > 0) {
-            handlers.addToQueue(createValidateDefinition(missingConfig, userRequest, service, (error) => {
+        const validation = validateExecuteTasks(tasks);
+        if (validation.validationErrors.length > 0) {
+            // Show error feedback for invalid skills
+            const errorMessages = validation.validationErrors.map((error) => {
+                const issuesList = error.issues
+                    .map((issue) => `  - ${issue}`)
+                    .join('\n');
+                return `Invalid skill definition "${error.skill}":\n\n${issuesList}`;
+            });
+            handlers.addToQueue(createFeedback(FeedbackType.Failed, errorMessages.join('\n\n')));
+        }
+        else if (validation.missingConfig.length > 0) {
+            handlers.addToQueue(createValidateDefinition(validation.missingConfig, userRequest, service, (error) => {
                 handlers.onError(error);
             }, () => {
                 handlers.addToQueue(createExecuteDefinition(tasks, service));

package/dist/ui/Introspect.js

@@ -24,23 +24,31 @@ function parseCapabilityFromTask(task) {
     const colonIndex = task.action.indexOf(':');
     if (colonIndex === -1) {
         const upperName = task.action.toUpperCase();
+        // Check for status markers
+        const isIncomplete = task.action.includes('(INCOMPLETE)');
+        const cleanName = task.action.replace(/\s*\(INCOMPLETE\)\s*/gi, '').trim();
         return {
-            name: task.action,
+            name: cleanName,
             description: '',
             isBuiltIn: BUILT_IN_CAPABILITIES.has(upperName),
             isIndirect: INDIRECT_CAPABILITIES.has(upperName),
+            isIncomplete,
         };
     }
     const name = task.action.substring(0, colonIndex).trim();
     const description = task.action.substring(colonIndex + 1).trim();
-    const upperName = name.toUpperCase();
+    // Check for status markers
+    const isIncomplete = name.includes('(INCOMPLETE)');
+    const cleanName = name.replace(/\s*\(INCOMPLETE\)\s*/gi, '').trim();
+    const upperName = cleanName.toUpperCase();
     const isBuiltIn = BUILT_IN_CAPABILITIES.has(upperName);
     const isIndirect = INDIRECT_CAPABILITIES.has(upperName);
     return {
-        name,
+        name: cleanName,
         description,
         isBuiltIn,
         isIndirect,
+        isIncomplete,
     };
 }
 export function Introspect({ tasks, state, status, service, children, debug = false, handlers, }) {

package/dist/ui/Report.js

@@ -1,14 +1,14 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Box, Text } from 'ink';
 import { Colors } from '../services/colors.js';
-function CapabilityItem({ name, description, isBuiltIn, isIndirect, }) {
+function CapabilityItem({ name, description, isBuiltIn, isIndirect, isIncomplete, }) {
     const color = isIndirect
         ? Colors.Origin.Indirect
         : isBuiltIn
             ? Colors.Origin.BuiltIn
             : Colors.Origin.UserProvided;
-    return (_jsxs(Box, { children: [_jsx(Text, { children: "- " }), _jsx(Text, { color: color, children: name }), _jsxs(Text, { children: [" - ", description] })] }));
+    return (_jsxs(Box, { children: [_jsx(Text, { children: "- " }), _jsx(Text, { color: color, children: name }), _jsxs(Text, { children: [" - ", description] }), isIncomplete && _jsx(Text, { color: Colors.Status.Warning, children: " (incomplete)" })] }));
 }
 export function Report({ message, capabilities }) {
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { marginLeft: 1, children: _jsx(Text, { children: message }) }), _jsx(Box, { flexDirection: "column", marginLeft: 3, marginTop: 1, children: capabilities.map((capability, index) => (_jsx(CapabilityItem, { name: capability.name, description: capability.description, isBuiltIn: capability.isBuiltIn, isIndirect: capability.isIndirect }, index))) })] }));
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { marginLeft: 1, children: _jsx(Text, { children: message }) }), _jsx(Box, { flexDirection: "column", marginLeft: 3, marginTop: 1, children: capabilities.map((capability, index) => (_jsx(CapabilityItem, { name: capability.name, description: capability.description, isBuiltIn: capability.isBuiltIn, isIndirect: capability.isIndirect, isIncomplete: capability.isIncomplete }, index))) })] }));
 }

package/package.json

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