prjct-cli 0.4.9 → 0.5.0

package/templates/examples/natural-language-examples.md

@@ -1,8 +1,10 @@
 # Natural Language Examples
 
-Real-world examples showing how the **semantic intent detection** works.
+Real-world examples showing how **Claude Code** handles natural language with context validation.
 
-> **Important**: These are examples, not the only valid phrases! The LLM understands intent semantically, so users can express themselves in countless ways.
+> **Important**: These are examples, not the only valid phrases! Claude understands intent semantically, so users can express themselves in countless ways.
+
+> **Note**: All examples show how **Claude Code automatically validates context** and provides conversational responses when context is missing.
 
 ## Example 1: Starting a Task
 
@@ -34,7 +36,9 @@ Need help? Say "I'm stuck" or use /p:stuck
 
 ---
 
-## Example 2: Completing a Task
+## Example 2: Completing a Task (WITH Active Task)
+
+**Context:** User has an active task in `core/now.md`
 
 **User says (any of these work):**
 - "I'm done"
@@ -43,9 +47,10 @@ Need help? Say "I'm stuck" or use /p:stuck
 - "all done with this"
 - "completed it"
 
-**Claude Code understands:**
-- Intent: User finished their current work
-- Command: `/p:done`
+**Claude Code checks:**
+- Project exists: ✅
+- Active task exists: ✅
+- Context valid: Execute command
 
 **Claude Code response:**
 ```markdown
@@ -64,6 +69,36 @@ Or use: /p:now | /p:ship | /p:idea
 
 ---
 
+## Example 2b: Completing a Task (NO Active Task)
+
+**Context:** User has NO active task (empty `core/now.md`)
+
+**User says:**
+- "I'm done"
+- "finished"
+- "terminé"
+
+**Claude Code checks:**
+- Project exists: ✅
+- Active task exists: ❌
+- Context invalid: Return conversational response
+
+**Claude Code response (NO command execution):**
+```markdown
+✨ You're not working on anything right now!
+
+Want to start something?
+• Tell me what you want to build
+• Say "show me what's next"
+• Or use: /p:now | /p:next
+
+Let's ship something!
+```
+
+**Why this is better:** Instead of showing a technical error like "⏺ No hay tarea activa en este momento...", Claude provides a friendly, actionable response that guides the user forward.
+
+---
+
 ## Example 3: Shipping a Feature
 
 **User says:**
@@ -91,6 +126,36 @@ Or use: /p:now | /p:recap | /p:roadmap
 
 ---
 
+## Example 3b: Shipping a Feature (NO Work Done Yet)
+
+**Context:** User has NO active task and NO shipped features
+
+**User says:**
+- "ship this"
+- "deploy it"
+- "let's launch"
+
+**Claude Code checks:**
+- Project exists: ✅
+- Has work to ship (active task OR shipped features): ❌
+- Context invalid: Return conversational response
+
+**Claude Code response (NO command execution):**
+```markdown
+🚀 Nothing to ship yet!
+
+First, let's build something:
+• Tell me what feature you want to create
+• Say "start building [feature]"
+• Or use: /p:now "feature name"
+
+Then we'll celebrate when you ship it!
+```
+
+**Why this is better:** Instead of confusing the user with an error, Claude guides them toward the correct workflow: build first, ship later.
+
+---
+
 ## Example 4: Capturing an Idea
 
 **User says:**
@@ -267,31 +332,178 @@ Which one?
 
 ---
 
+## Example 11: p. Trigger (NEW - Zero Memorization)
+
+**Context:** User doesn't want to memorize `/p:*` commands
+
+**User says:**
+```
+p. analiza todo este documento y dame el roadmap
+```
+
+**Claude Code detects:**
+- Trigger: `p.` detected
+- Validates: `.prjct/prjct.config.json` exists ✅
+- Intent: "analysis" + "roadmap"
+- Command: `/p:analyze`
+
+**Claude Code response:**
+```markdown
+💬 I understood: "analyze document and create roadmap" (prjct context)
+⚡ Executing: /p:analyze
+
+[Performs repository analysis]
+
+📊 Analysis complete. Creating roadmap...
+
+[Shows roadmap suggestions]
+
+Ready to plan?
+• Say "p. add to roadmap" or use /p:roadmap
+• Or continue working on current task
+```
+
+---
+
+## Example 12: p. Trigger Multi-Language
+
+**User says (Spanish):**
+```
+p. estoy listo para shipear esta feature
+```
+
+**Claude Code detects:**
+- Trigger: `p.` detected
+- Validates: Project exists ✅
+- Intent: "ship" (detected from "shipear")
+- Command: `/p:ship`
+
+**Claude Code response:**
+```markdown
+💬 I understood: "ready to ship this feature" (prjct context)
+⚡ Executing: /p:ship
+
+What feature did you ship?
+• Tell me the feature name
+• Or use: /p:ship "feature name"
+```
+
+---
+
+## Example 13: p. Trigger Without Project
+
+**Context:** User tries p. trigger in non-prjct directory
+
+**User says:**
+```
+p. muéstrame mi progreso
+```
+
+**Claude Code checks:**
+- Trigger: `p.` detected
+- Validates: `.prjct/prjct.config.json` NOT found ❌
+
+**Claude Code response (NO command execution):**
+```markdown
+🎯 No prjct project here!
+
+This doesn't look like a prjct directory.
+
+Want to initialize?
+• Say "initialize prjct" or "set up project"
+• Or use: /p:init
+
+Then you can track progress with p. commands!
+```
+
+**Why this is better:** The `p.` trigger is **context-aware** - it only works in prjct directories, preventing accidental execution.
+
+---
+
+## Example 14: All Three Ways Work
+
+**Scenario:** User can choose their preferred style
+
+**Option 1 - p. Trigger (easiest):**
+```
+User: "p. terminé"
+Claude: Detects completion intent → /p:done
+```
+
+**Option 2 - Direct slash command:**
+```
+User: "/p:done"
+Claude: Executes directly
+```
+
+**Option 3 - Natural language:**
+```
+User: "I'm done"
+Claude: Detects intent → /p:done
+```
+
+**All three execute the same command!** Users pick what feels natural to them.
+
+---
+
 ## Implementation Notes
 
-### Semantic Understanding (Not Pattern Matching!)
+### How Claude Code Handles Natural Language
+
+**Key Principle**: Claude Code (and Claude Desktop) automatically handle intent detection, context validation, and conversational responses through **CLAUDE.md instructions**. No SDK needed!
+
+**How it works:**
 
-**Key Principle**: The LLM understands intent semantically, not through regex or hardcoded phrases.
+1. **CLAUDE.md is automatically read** - Both Claude Code and Desktop read this file for context
+2. **Claude understands intent naturally** - As an LLM, Claude semantically understands what users want
+3. **Simple file checks validate context** - Read `core/now.md`, check if `.prjct/prjct.config.json` exists
+4. **Conversational responses when context missing** - Friendly guidance instead of errors
+5. **Multi-language support** - Works in any language Claude understands
+
+**Implementation:**
 
 ```javascript
-// ❌ DON'T DO THIS
-if (message.includes("I want to start")) {
-  // Too rigid!
+// NO SDK NEEDED - Just use Claude Code's native capabilities:
+
+// 1. Detect p. trigger or natural language intent
+if (message.startsWith('p. ')) {
+  // Check if prjct project exists
+  const configExists = await Read('.prjct/prjct.config.json')
+  if (!configExists) {
+    return "🎯 No prjct project here! Run /p:init first."
+  }
+  // Extract intent from rest of message
+  const intent = message.slice(3).trim()
+  // Continue with semantic understanding...
+}
+
+// 2. Validate context before execution
+if (command === 'done') {
+  const nowContent = await Read('core/now.md')
+  if (!nowContent || nowContent.trim() === '') {
+    return conversationalResponse() // Friendly guidance
+  }
 }
 
-// ✅ DO THIS
-// Use your LLM understanding:
-// "What is the user trying to accomplish?"
-const intent = semanticallyUnderstand(message)
+// 3. Execute command with transparency
+console.log(`💬 I understood: "${intent}"`)
+console.log(`⚡ Executing: /p:${command} ${params}`)
 ```
 
-### Detection Flow
-1. **Check for `/p:` commands** - Execute directly if present
-2. **Understand user intent** - What are they trying to do?
-3. **Map to appropriate command** - Based on semantic meaning
-4. **Extract parameters** - Pull relevant information
-5. **Show transparency** - Communicate what you understood
-6. **Execute and respond** - Run command and guide next steps
+### Detection Flow (Natural)
+1. **Check for p. trigger** - Highest priority
+   - If starts with `p.` → Check if `.prjct/prjct.config.json` exists
+   - If exists → Extract intent from rest of message
+   - If not exists → Return "No prjct project" message
+2. **Parse user input** - Direct slash command or natural language?
+3. **Understand intent semantically** - What does the user want to do?
+4. **Validate context** - Simple file reads to check prerequisites
+5. **Respond**:
+   - Context missing → Provide conversational guidance
+   - Context valid → Execute command with transparency
+   - No command intent → Normal conversation
+6. **Show transparency** - Always communicate what you understood
+7. **Execute and guide** - Run command and suggest next steps
 
 ### Transparency Format
 Always show what you understood:

package/core/agents/codex-agent.js

@@ -1,256 +0,0 @@
-/**
- * OpenAI Codex Agent Adapter
- * Implements prjct commands for OpenAI Codex environment
- */
-
-const fs = require('fs').promises
-
-class CodexAgent {
-  constructor() {
-    this.name = 'OpenAI Codex'
-    this.type = 'codex'
-  }
-
-  /**
-   * Format response for Codex with structured output
-   * Codex runs in sandboxed environments, so we use clear text formatting
-   */
-  formatResponse(message, type = 'info') {
-    const prefixes = {
-      success: '[SUCCESS]',
-      error: '[ERROR]',
-      warning: '[WARNING]',
-      info: '[INFO]',
-      celebrate: '[SHIPPED]',
-      ship: '[FEATURE]',
-      focus: '[FOCUS]',
-      idea: '[IDEA]',
-      progress: '[PROGRESS]',
-      task: '[TASK]',
-    }
-
-    const prefix = prefixes[type] || prefixes.info
-
-    return `${prefix} ${message}`
-  }
-
-  /**
-   * Read file using native fs (Codex doesn't have MCP)
-   */
-  async readFile(filePath) {
-    try {
-      return await fs.readFile(filePath, 'utf8')
-    } catch (error) {
-      throw new Error(`Failed to read file ${filePath}: ${error.message}`)
-    }
-  }
-
-  /**
-   * Write file using native fs
-   */
-  async writeFile(filePath, content) {
-    try {
-      await fs.writeFile(filePath, content, 'utf8')
-    } catch (error) {
-      throw new Error(`Failed to write file ${filePath}: ${error.message}`)
-    }
-  }
-
-  /**
-   * List directory contents
-   */
-  async listDirectory(dirPath) {
-    try {
-      return await fs.readdir(dirPath)
-    } catch (error) {
-      throw new Error(`Failed to list directory ${dirPath}: ${error.message}`)
-    }
-  }
-
-  /**
-   * Check if file exists
-   */
-  async fileExists(filePath) {
-    try {
-      await fs.access(filePath)
-      return true
-    } catch {
-      return false
-    }
-  }
-
-  /**
-   * Create directory
-   */
-  async createDirectory(dirPath) {
-    try {
-      await fs.mkdir(dirPath, { recursive: true })
-    } catch (error) {
-      throw new Error(`Failed to create directory ${dirPath}: ${error.message}`)
-    }
-  }
-
-  /**
-   * Get current timestamp in ISO format
-   */
-  getTimestamp() {
-    return new Date().toISOString()
-  }
-
-  /**
-   * Format task list with structured output
-   */
-  formatTaskList(tasks) {
-    if (!tasks || tasks.length === 0) {
-      return this.formatResponse('No tasks in queue', 'info')
-    }
-
-    let output = 'TASK QUEUE:\n'
-    output += '===========\n'
-    tasks.forEach((task, index) => {
-      output += `  ${index + 1}. ${task}\n`
-    })
-
-    return output
-  }
-
-  /**
-   * Format recap with structured output
-   */
-  formatRecap(data) {
-    const output = `
-PROJECT RECAP
-=============
-
-Current Task: ${data.currentTask || 'None'}
-Shipped Features: ${data.shippedCount} total
-Queued Tasks: ${data.queuedCount}
-Ideas Captured: ${data.ideasCount}
-
-${data.recentActivity ? 'Recent Activity:\n' + data.recentActivity : ''}
-
-Status: ${data.shippedCount > 0 ? 'Productive' : 'Getting Started'}
-        `.trim()
-
-    return output
-  }
-
-  /**
-   * Format progress report
-   */
-  formatProgress(data) {
-    const trend =
-      data.velocity > data.previousVelocity
-        ? 'UP'
-        : data.velocity < data.previousVelocity
-          ? 'DOWN'
-          : 'STEADY'
-
-    const output = `
-PROGRESS REPORT (${data.period.toUpperCase()})
-=====================================
-
-Features Shipped: ${data.count}
-Velocity: ${data.velocity.toFixed(1)} features/day
-Trend: ${trend}
-
-${data.recentFeatures ? 'Recent Features:\n' + data.recentFeatures : ''}
-
-${data.motivationalMessage}
-        `.trim()
-
-    return output
-  }
-
-  /**
-   * Get help content based on issue type
-   * Structured format for Codex readability
-   */
-  getHelpContent(issue) {
-    const helps = {
-      debugging: `
-DEBUGGING STRATEGY:
-===================
-1. ISOLATE - Comment out code until error disappears
-2. LOG - Add console.log at key points
-3. SIMPLIFY - Create minimal reproduction
-4. RESEARCH - Search for exact error message
-5. BREAK - Take a walk, fresh perspective helps
-            `,
-      design: `
-DESIGN APPROACH:
-================
-1. START SIMPLE - Basic version first
-2. USER FIRST - What problem does this solve?
-3. ITERATE - Ship v1, improve based on feedback
-4. PATTERNS - Look for similar solutions
-5. VALIDATE - Show mockup before building
-            `,
-      performance: `
-PERFORMANCE STRATEGY:
-====================
-1. MEASURE FIRST - Profile before optimizing
-2. BIGGEST WINS - Focus on slowest parts
-3. CACHE - Store expensive computations
-4. LAZY LOAD - Defer non-critical work
-5. MONITOR - Track improvements
-            `,
-      default: `
-GENERAL STRATEGY:
-================
-1. BREAK IT DOWN - Divide into smaller tasks
-2. START SMALL - Implement simplest part first
-3. TEST OFTEN - Verify each step works
-4. DOCUMENT - Write down what you learn
-5. SHIP IT - Perfect is the enemy of done
-            `,
-    }
-
-    const helpType =
-      Object.keys(helps).find((key) => issue.toLowerCase().includes(key)) || 'default'
-
-    return helps[helpType]
-  }
-
-  /**
-   * Suggest next action based on context
-   * Clear, actionable suggestions for Codex
-   */
-  suggestNextAction(context) {
-    const suggestions = {
-      taskCompleted: 'NEXT: Check task queue with /p:next',
-      featureShipped: 'NEXT: Set new focus with /p:now [task]',
-      ideaCaptured: 'NEXT: Start working with /p:now [task]',
-      initialized: 'NEXT: Set first task with /p:now "your first task"',
-      stuck: 'NEXT: Break down problem with /p:idea for each step',
-    }
-
-    return suggestions[context] || 'NEXT: What would you like to work on?'
-  }
-
-  /**
-   * Handle sandboxed environment limitations
-   */
-  async ensureSandboxCompatibility() {
-    const isSandboxed =
-      process.cwd().includes('/sandbox/') ||
-      process.cwd().includes('/tmp/') ||
-      process.env.CODEX_SANDBOX
-
-    if (isSandboxed) {
-      return {
-        sandboxed: true,
-        basePath: process.cwd(),
-        restrictions: ['no-network', 'limited-filesystem'],
-      }
-    }
-
-    return {
-      sandboxed: false,
-      basePath: process.cwd(),
-      restrictions: [],
-    }
-  }
-}
-
-module.exports = CodexAgent