prjct-cli 0.7.3 → 0.8.0

package/CHANGELOG.md

@@ -7,6 +7,119 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2025-10-05
+
+### Added
+
+- **3-Tier Guided Workflow System** - Zero memorization interface for confused users
+  - **`/p:help`** - Contextual interactive guide that adapts to project state
+    - 5 different response contexts (Not initialized, Empty queue, Has active task, Has queue, Lost/confused)
+    - Shows relevant options based on current situation
+    - Educational approach with examples
+  - **`/p:ask`** - Intent to action translator with explanations
+    - Natural language understanding for any intent
+    - Recommends appropriate command flows with reasoning
+    - Works in any language (English, Spanish, etc.)
+    - Educational responses explain the "why" behind each recommendation
+    - Intent categories: Feature Development, Performance, Bug Fixing, Design, Lost/Confused
+  - **`/p:suggest`** - Context-aware smart recommendations
+    - Analyzes project state (active tasks, queue, velocity, momentum)
+    - Detects patterns: stuck tasks, losing momentum, over-planning, ready to work
+    - Provides urgency levels and actionable next steps
+    - Scenario-based suggestions with clear actions
+  - Updated from 9 to 13 core commands
+  - Version bumped to 0.7.0 → 0.8.0
+
+- **Enhanced Feature Templates** - Quick start templates for common workflows
+  - 6 interactive template categories: UI/UX, Performance, Features, Quality, Bugs, Docs
+  - Each category includes examples and natural language alternatives
+  - Integrated into `/p:feature` command for faster feature initialization
+
+- **Enhanced Onboarding** - Conversational first-time experience
+  - Updated `/p:init` with "What do you want to do first?" section
+  - 5 clear options with examples and natural language alternatives
+  - Guides users to appropriate commands based on their needs
+
+### Changed
+
+- **Website Transformation** - Complete shift from "memorize commands" to "conversational/agentic"
+
+  - **Hero Section** (`Hero.tsx`)
+    - Changed layout from centered to 60/40 asymmetric grid (better space utilization on LG screens)
+    - Updated messaging: "Just talk: 'p. I want to add auth' → Claude handles the rest"
+    - Added 3 conversational example cards showing real usage patterns
+    - Removed sequential command flow in favor of natural language examples
+    - Better visual hierarchy with left column (60%) for main content, right column (40%) for examples
+
+  - **Terminal Demo** (`Terminal.tsx`)
+    - Replaced 4 rotating examples with single comprehensive flow
+    - Shows complete journey: Installation → Setup → Usage → Progress → Shipping
+    - Demonstrates real `p.` trigger usage throughout
+    - Improved timing: 3500ms between steps (was 1500ms) for better comprehension
+    - 12s restart delay (was 10s) for proper reading time
+    - Title: "See It In Action - From installation to shipping"
+
+  - **How It Works Section** (`HowItWorks.tsx`)
+    - New 3-step visual flow: Talk Naturally → Claude Understands → You Ship
+    - Removed misleading chat-style UI examples (product is terminal-only)
+    - Clean, honest representation of terminal-based workflow
+    - Icon-based visual guide with examples
+
+  - **Command Guide** (`CommandGuide.tsx`)
+    - Added 2 priority scenarios at top:
+      - "I'm new/lost/don't know what to do" → `/p:help`, `/p:ask`, `/p:suggest`
+      - "I know what I want but not how to do it" → `/p:ask` (preferred)
+    - Updated Quick Decision Matrix to prioritize help commands
+    - All examples show `p.` trigger as preferred option with `/p:*` alternatives
+
+  - **Commands Page** (`Commands.tsx`)
+    - Added prominent "Start Here - No Memorization Needed" section
+    - Highlights 3 essential commands: `/p:help`, `/p:ask`, `/p:suggest`
+    - Moved all specific commands to "Advanced Reference" section
+    - Clear message: "You only need these 3 commands. Everything else? Just talk naturally."
+
+- **Command Registry Updates** (`command-registry.js`)
+  - Added `ask` and `suggest` to core commands
+  - Updated version from 0.7.0 to 0.8.0
+  - Increased core command count from 9 to 13
+  - Enhanced metadata for new help system commands
+
+- **Documentation Updates** (`CLAUDE.md`)
+  - Added complete "Guided Workflow System" section
+  - Documented 3-tier help architecture with examples
+  - Updated natural language system philosophy
+  - Added context validation patterns and examples
+
+### Philosophy Shift
+
+This release represents a fundamental shift in how users interact with prjct:
+
+**Before (0.7.x)**: "Learn these sequential commands: `/p:feature → /p:done → /p:ship`"
+**After (0.8.0)**: "Just talk: `p. I want to add auth` → Claude handles the rest"
+
+The 3-tier help system solves the core user frustration: **users know WHAT they want but don't know HOW to execute it**. Now they don't need to - they just describe their intent and the system guides them.
+
+### Technical Details
+
+- **New Templates**:
+  - `templates/commands/ask.md` - Intent translation with educational responses
+  - `templates/commands/suggest.md` - Context-aware recommendations
+  - Updated `templates/commands/help.md` - Contextual interactive guide
+  - Updated `templates/commands/init.md` - Conversational onboarding
+  - Updated `templates/commands/feature.md` - Interactive mode with templates
+
+- **Website Optimization**:
+  - Hero grid: `lg:grid-cols-5` with `lg:col-span-3` (60%) + `lg:col-span-2` (40%)
+  - Terminal timing: 3500ms step delay, 12s restart delay
+  - Removed chat UI mockups to avoid false expectations
+  - Consistent `p.` trigger examples throughout
+
+- **User Experience**:
+  - Zero memorization required for basic usage
+  - Natural language works in any language (English, Spanish, etc.)
+  - Context-aware help adapts to project state
+  - Educational responses explain the "why" behind recommendations
+
 ## [0.7.3] - 2025-10-05
 
 ### Added

package/CLAUDE.md

@@ -504,6 +504,213 @@ User: "/p:workflow"
 
 **Key Difference**: `/p:idea` captures NEW ideas. `/p:workflow` manages EXISTING multi-step tasks.
 
+## Guided Workflow System
+
+**NEW: Enhanced usability for confused users** - The biggest user frustration is knowing WHAT they want but not HOW to do it with prjct.
+
+### The Problem
+
+Users frequently ask:
+- "How do I start?"
+- "What command should I use?"
+- "I want to improve performance, but how?"
+- "What should I do next?"
+
+They have clear **INTENT** but struggle with **EXECUTION**.
+
+### The Solution: 3-Tier Help System
+
+#### Tier 1: `/p:help` - Contextual Interactive Guide
+
+**Purpose**: Adapts to user's current state and provides relevant guidance
+
+**Behavior**:
+- Reads project state (active task, queue, last ship, etc.)
+- Shows different help based on context:
+  - Not initialized → Guides setup
+  - Empty queue → Suggests adding features
+  - Active task → Shows completion options
+  - Has queue → Recommends starting work
+  - Lost/confused → Comprehensive guide
+
+**Example**:
+```
+User in state: "No active task, 5 tasks in queue"
+
+/p:help shows:
+→ Start working (recommended)
+→ See priority queue
+→ Add new feature
+→ Check progress
+
+With examples and natural language alternatives
+```
+
+#### Tier 2: `/p:ask` - Intent to Action Translator
+
+**Purpose**: Translate vague natural language intent into specific command flows
+
+**Behavior**:
+- User describes what they want in natural language
+- Claude analyzes intent and context
+- Recommends step-by-step command flow
+- Explains WHY each command
+- Offers interactive confirmation
+- Educational - teaches the system
+
+**Example**:
+```
+User: /p:ask "I want to improve performance and fix memory leaks"
+
+Claude responds:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎯 I understand: performance optimization + memory leak fixes
+
+📊 YOUR CONTEXT:
+  • No active task
+  • 3 tasks in queue
+  • Last ship: 2 days ago
+
+💡 RECOMMENDED FLOW:
+
+1. /p:feature "optimize performance and memory leaks"
+   → Value analysis (Impact: HIGH, Effort: 8h)
+   → Task breakdown:
+     • Setup profiler
+     • Identify memory leaks
+     • Optimize re-renders
+     • Code splitting
+     • Measure improvements
+
+2. /p:build 1 → Start with profiling
+
+3. /p:done → After each task
+
+4. /p:ship "performance optimization"
+
+✨ WHY THIS FLOW:
+→ /p:feature: Analyzes value first, creates roadmap
+→ /p:build: Focus on one task, track time
+→ /p:done: Register progress, maintain momentum
+→ /p:ship: Commit + celebrate win
+
+Ready to start?
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Key Features**:
+- Works in any language (English, Spanish, etc.)
+- No execution until user confirms
+- Shows command + natural language alternatives
+- Educational explanations
+- Contextual (checks project state first)
+
+#### Tier 3: `/p:suggest` - Smart Recommendations
+
+**Purpose**: Analyze project state and suggest next best actions
+
+**Behavior**:
+- Reads all project state files
+- Calculates metrics (velocity, days since ship, queue size, etc.)
+- Detects patterns (stuck task, losing momentum, over-planning, etc.)
+- Provides urgency-based recommendations
+- Motivational but honest
+
+**Scenarios Detected**:
+1. **Ready to work** → Suggests starting top priority task
+2. **Long-running task** → Checks if stuck, suggests help
+3. **No ships recently** → Urgency alert, suggests shipping something small
+4. **Empty queue** → Suggests planning (feature/analyze/roadmap)
+5. **High velocity** → Positive reinforcement, quality suggestions
+6. **Queue too large** → Warns about over-planning, suggests executing
+
+**Example**:
+```
+User: /p:suggest
+
+Claude analyzes:
+- No active task
+- 8 tasks in queue
+- Last ship: 5 days ago
+- Velocity: 0.4 features/week
+
+Response:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💡 PERSONALIZED SUGGESTIONS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 ANALYSIS:
+  • 5 days since last ship ⚠️
+  • Queue: 8 tasks
+  • Velocity: Low
+
+🔥 URGENT: Momentum is dropping!
+
+🎯 RECOMMENDATIONS:
+
+1. ⚡ SHIP SOMETHING TODAY
+   → /p:next (find quick win)
+   → /p:build {easiest task}
+   → /p:done → /p:ship SAME DAY
+
+2. 🎯 STOP PLANNING, START DOING
+   → 8 tasks is too many
+   → Ship > Plan
+
+3. 💡 MAINTAIN MOMENTUM
+   → Ship every 1-2 days
+   → Small wins > Big tasks
+
+Momentum = Motivation. Let's ship! 🚀
+━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Enhanced Onboarding
+
+**After `/p:init`**: Conversational "What do you want to do first?" section
+- 5 clear options with examples
+- Natural language alternatives
+- No overwhelming command lists
+- Guides to action immediately
+
+**After `/p:feature` (no params)**: Interactive template mode
+- 6 categories (UI/UX, Performance, Features, Quality, Bugs, Docs)
+- Examples for each category
+- Impact/effort estimates
+- User can describe freely OR choose template
+
+### Integration with Natural Language System
+
+All help commands work seamlessly with the "p." trigger and natural language detection:
+
+```
+User: "p. I don't know what to do"
+→ Detects confusion → Executes /p:suggest
+
+User: "p. how do I start?"
+→ Detects help need → Executes /p:help
+
+User: "p. I want to optimize performance"
+→ Detects feature intent → Shows /p:ask flow OR /p:feature
+```
+
+### Key Principles
+
+1. **Never leave users confused** - Always provide clear next steps
+2. **Educational, not prescriptive** - Teach the system while guiding
+3. **Contextual, not generic** - Different help for different states
+4. **Natural language first** - Commands as alternative, not requirement
+5. **Momentum-focused** - Push toward action, not endless planning
+
+### Success Metrics
+
+After using the guided system, users should:
+- ✅ Know exactly what command to use
+- ✅ Understand WHY that command
+- ✅ Feel confident to proceed
+- ✅ Learn the system through use
+- ✅ Never feel stuck or frustrated
+
 ### Available Commands
 
 The following commands are available in Claude Code (commands marked with ⚠️ are not yet implemented):
@@ -544,11 +751,21 @@ The following commands are available in Claude Code (commands marked with ⚠️
   - **Empty dir, no idea**: Asks for idea
   - **Empty dir + idea**: ARCHITECT MODE (conversational discovery → generates plan)
   - **Existing code**: Regular init + suggests analyze
+- `/p:help` - Interactive contextual guide (adapts to project state)
+- `/p:ask "<what you want to do>"` - Conversational intent to action translator
+  - Natural language understanding
+  - Recommends command flow with explanations
+  - Works in any language
+  - Educational and interactive
+- `/p:suggest` - Context-aware next steps suggestions
+  - Analyzes project state and momentum
+  - Detects urgencies and patterns
+  - Personalized recommendations
+  - Helps maintain momentum
 - `/p:stuck <issue description>` - Get contextual help with problems
 - `/p:analyze` - Analyze repository and sync tasks
 - `/p:sync` - Sync project state and update workflow agents
 - ⚠️ `/p:fix [error]` - Quick troubleshooting and automatic fixes
-- ⚠️ `/p:help` - Interactive guide - talk naturally, no memorization needed
 
 #### Version Control
 
@@ -558,7 +775,7 @@ The following commands are available in Claude Code (commands marked with ⚠️
 
 - ⚠️ `/p:test` - Run tests and auto-fix simple failures
 
-**Total: 23 implemented, 29 total commands**
+**Total: 26 implemented, 30 total commands** (✅ +3 new: /p:help, /p:ask, /p:suggest)
 **Status**: Check `core/command-registry.js` for current implementation status
 
 ## Agent Generation

package/core/command-registry.js

@@ -8,11 +8,11 @@
  * - CLAUDE.md (AI assistant instructions)
  * - scripts/validate-commands.js (validation)
  *
- * @version 0.6.0 - Simplified workflow with 9 core commands
+ * @version 0.8.0 - Conversational interface with zero memorization
  */
 
 const COMMANDS = [
-  // ===== CORE WORKFLOW COMMANDS (9 essential) =====
+  // ===== CORE WORKFLOW COMMANDS (13 essential) =====
 
   // 1. Initialize
   {
@@ -267,7 +267,55 @@ const COMMANDS = [
     ],
   },
 
-  // 11. Architect Execute
+  // 11. Ask - Intent to Action
+  {
+    name: 'ask',
+    category: 'core',
+    description: 'Conversational intent to action translator',
+    usage: {
+      claude: '/p:ask "what you want to do"',
+      terminal: 'prjct ask "what you want to do"',
+    },
+    params: '<description>',
+    implemented: true,
+    hasTemplate: true,
+    icon: 'MessageCircle',
+    requiresInit: false, // Can work before init to guide setup
+    blockingRules: null,
+    features: [
+      'Natural language understanding',
+      'Recommends command flow',
+      'Educational explanations',
+      'Interactive confirmation',
+      'Works in any language',
+    ],
+  },
+
+  // 12. Suggest - Context-Aware Recommendations
+  {
+    name: 'suggest',
+    category: 'core',
+    description: 'Context-aware next steps suggestions',
+    usage: {
+      claude: '/p:suggest',
+      terminal: 'prjct suggest',
+    },
+    params: null,
+    implemented: true,
+    hasTemplate: true,
+    icon: 'Lightbulb',
+    requiresInit: true,
+    blockingRules: null,
+    features: [
+      'Analyzes project state',
+      'Recommends actions',
+      'Urgency detection',
+      'Momentum tracking',
+      'Personalized suggestions',
+    ],
+  },
+
+  // 13. Architect Execute
   {
     name: 'architect',
     category: 'core',
@@ -446,7 +494,7 @@ const CATEGORIES = {
   core: {
     title: 'Core Workflow',
     icon: 'Zap',
-    description: '9 essential commands for daily development workflow',
+    description: '13 essential commands for daily development workflow',
     order: 1,
   },
   optional: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prjct-cli",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Built for Claude - Ship fast, track progress, stay focused. Developer momentum tool for indie hackers.",
   "main": "core/index.js",
   "bin": {