prjct-cli 0.4.0

package/templates/commands/workflow.md

@@ -0,0 +1,224 @@
+# Workflow System for AI Assistants
+
+## Overview
+Interactive agent workflows that orchestrate task execution with user guidance. When capabilities are missing, the system prompts for decisions rather than auto-skipping, and tracks all installation efforts as workflow tasks.
+
+## How It Works
+
+### 1. Automatic Workflow Detection
+When a task is added via `/p:idea`, the system:
+- Classifies task type: ui, api, bug, refactor, feature
+- Detects project capabilities (design system, tests, docs)
+- Marks steps that need user prompting when capabilities are missing
+- Initializes workflow with all steps (required + optional with prompts)
+
+### 2. Workflow Types
+
+**UI Component** (ui):
+- design (optional - needs design system)
+- dev (required)
+- test (optional - needs test framework)
+- docs (optional - needs docs system)
+
+**API Endpoint** (api):
+- dev (required)
+- test (optional - needs test framework)
+- docs (optional - needs docs system)
+
+**Bug Fix** (bug):
+- analyze (required)
+- fix (required)
+- test (optional - needs test framework)
+
+**Refactor** (refactor):
+- refactor (required)
+- test (optional - needs test framework)
+
+**Feature** (feature):
+- design (optional - needs design system)
+- dev (required)
+- test (optional - needs test framework)
+- docs (optional - needs docs system)
+
+### 3. Task Classification
+
+Keywords that trigger specific workflows:
+
+**UI**: button, form, modal, card, component, menu, nav, input
+**API**: endpoint, api, service, route, controller
+**Bug**: bug, fix, error, issue, broken
+**Refactor**: refactor, improve, optimize, clean
+**Feature**: feature, functionality, module
+
+Default: ui
+
+### 4. Capability Detection
+
+The system detects capabilities by checking:
+
+**Design System**:
+- Folders: design/, designs/, .storybook/
+- Dependencies: @storybook/react, @storybook/vue
+- Files: *.figma
+
+**Test Framework**:
+- Dependencies: jest, vitest, mocha, @jest/core
+- Files: *.test.*, *.spec.*
+- Configs: jest.config.js, vitest.config.js
+
+**Documentation**:
+- Folders: docs/, documentation/
+- Files: README.md
+- Dependencies: typedoc, jsdoc
+
+### 5. Interactive Workflow Execution
+
+**When step requires missing capability:**
+1. System pauses and prompts user with options:
+   - Install recommended tool (based on stack detection)
+   - Skip this step
+   - Continue without capability
+   - Pause workflow
+
+2. If user chooses installation:
+   - Creates installation task (e.g., "Install Jest")
+   - Inserts task into workflow at current position
+   - Tracks installation effort as visible task
+   - Executes installation command
+   - Configures tool automatically
+   - Verifies capability is now available
+   - Continues to original step
+
+**When `/p:done` is executed:**
+- Marks current step as completed
+- Checks if next step needs prompting
+- Shows prompt if capability missing
+- Advances to next step (or completes workflow)
+- Updates now.md with next step details
+- Assigns appropriate agent for next step
+- Logs progress to memory
+
+### 6. Step Structure
+
+Each step has:
+- **name**: Step identifier
+- **agent**: Assigned AI agent specialist
+- **action**: What to do
+- **required**: Must execute (true) or optional (false)
+- **needs**: Required capability (if optional)
+- **prompt**: Should prompt user when capability missing
+- **needsPrompt**: Flag set when step needs user decision
+- **retry**: Max retry attempts (for test steps)
+- **type**: 'install' for dynamically inserted installation tasks
+
+## Commands
+
+### View Workflow Status
+```
+/p:workflow
+```
+Shows current workflow state, active step, progress.
+
+### Skip Current Step
+```
+/p:workflow skip
+```
+Skips current optional step, moves to next.
+
+## Example Workflows
+
+### Full Stack (Has Everything)
+```
+/p:idea "Create login form"
+→ Workflow: design→dev→test→docs
+→ Execute each step with /p:done
+```
+
+### Missing Test Framework (Interactive)
+```
+/p:idea "Create button component"
+→ Workflow: dev→test→docs
+→ /p:done (completes dev)
+
+⚠️  Missing test capability for "test" step
+
+📋 Recommended: Vitest, Jest + Testing Library
+💡 Reason: Quality assurance and regression prevention
+
+Options:
+1. Install recommended (npm install -D vitest @testing-library/react)
+2. Skip this step
+3. Continue without test
+4. Pause workflow
+
+→ User chooses: 1 (install)
+→ System creates: "Install test framework" task
+→ System executes: npm install -D vitest...
+→ System configures: vitest.config.js created
+→ Installation tracked as completed task
+→ Continues to test step
+```
+
+### User Skips Missing Capability
+```
+/p:idea "Fix auth bug"
+→ Workflow: analyze→fix→test
+→ /p:done (completes fix)
+
+⚠️  Missing test capability for "test" step
+→ User chooses: 2 (skip)
+→ Step skipped, workflow completes
+```
+
+### Installation Tracked as Task
+```
+When user installs missing tool:
+1. "Install Jest" task inserted at current position
+2. Installation runs: npm install -D jest
+3. Configuration created: jest.config.js
+4. Task marked complete with duration (e.g., 1.2 min)
+5. Installation visible in workflow progress
+6. Workflow continues to intended step
+```
+
+## Best Practices
+
+1. **Never hallucinate capabilities** - Only use what exists
+2. **Always prompt when capability missing** - Never auto-skip, ask user first
+3. **Track all installation efforts** - Every tool install becomes a visible task
+4. **Recommend based on stack** - Detect framework and suggest appropriate tools
+5. **Clear handoffs** - Each step completes before next starts
+6. **Agent assignment** - Right specialist for each step
+7. **State tracking** - Workflow progress and installations logged to memory
+
+## Error Handling
+
+- If workflow init fails, task is still created (degrades gracefully)
+- Missing capabilities = prompt user, don't auto-skip or fail
+- Installation failures = notify user, offer alternatives or skip
+- Test failures can retry up to configured limit
+- Workflow can be cleared manually if needed
+
+## State Management
+
+Workflow state stored in:
+```
+~/.prjct-cli/projects/{id}/workflow/state.json
+```
+
+Contains:
+- task: Task description
+- type: Workflow type
+- caps: Detected capabilities
+- steps: All workflow steps (including dynamically inserted install tasks)
+- missingCapabilities: Array of capabilities that need prompting
+- current: Current step index
+- active: Workflow active flag
+- timestamps: Created, completed
+
+Each step tracks:
+- status: pending, in_progress, completed, skipped
+- needsPrompt: Boolean flag for user decision required
+- type: 'install' for installation tasks
+- insertedAt: Timestamp for dynamically added tasks
+- skipReason: Why step was skipped (if user chose skip)

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

@@ -0,0 +1,320 @@
+# Natural Language Examples
+
+Real-world examples showing how the **semantic intent detection** works.
+
+> **Important**: These are examples, not the only valid phrases! The LLM understands intent semantically, so users can express themselves in countless ways.
+
+## Example 1: Starting a Task
+
+**User says (any of these work):**
+- "I want to start building the user authentication system"
+- "Let me work on the auth flow"
+- "Starting the login feature now"
+- "Voy a hacer la autenticación de usuarios"
+
+**Claude Code understands:**
+- Intent: User wants to start working on something
+- Command: `/p:now`
+- Parameter: [extracted task description]
+
+**Claude Code response:**
+```markdown
+💬 I understood: "start working on building the user authentication system"
+⚡ Executing: /p:now "building the user authentication system"
+
+🎯 Working on: building the user authentication system
+Started: 2:30 PM
+
+When you're done:
+• Say "I'm done" or "finished"
+• Or: /p:done
+
+Need help? Say "I'm stuck" or use /p:stuck
+```
+
+---
+
+## Example 2: Completing a Task
+
+**User says (any of these work):**
+- "I'm done"
+- "finished"
+- "terminé"
+- "all done with this"
+- "completed it"
+
+**Claude Code understands:**
+- Intent: User finished their current work
+- Command: `/p:done`
+
+**Claude Code response:**
+```markdown
+💬 I understood: "task completion"
+⚡ Executing: /p:done
+
+✅ Task complete: building the user authentication system (2h 15m)
+
+What's next?
+• "start next task" → Begin working
+• "ship this feature" → Track & celebrate
+• "add new idea" → Brainstorm
+
+Or use: /p:now | /p:ship | /p:idea
+```
+
+---
+
+## Example 3: Shipping a Feature
+
+**User says:**
+```
+ship the authentication system
+```
+
+**Claude Code response:**
+```markdown
+💬 I understood: "ship feature"
+⚡ Executing: /p:ship "authentication system"
+
+🚀 authentication system shipped!
+
+📈 This week: 3 | Total: 12
+Velocity: 1.2 features/day
+
+Keep the momentum!
+• "start next task" → Keep building
+• "see my progress" → View stats
+• "plan ahead" → Strategic thinking
+
+Or use: /p:now | /p:recap | /p:roadmap
+```
+
+---
+
+## Example 4: Capturing an Idea
+
+**User says:**
+```
+I have an idea about adding dark mode to the dashboard
+```
+
+**Claude Code response:**
+```markdown
+💬 I understood: "capture idea"
+⚡ Executing: /p:idea "adding dark mode to the dashboard"
+
+💡 Idea captured: adding dark mode to the dashboard
+
+Ready to start?
+• "start this" → Begin now
+• "plan more" → Keep brainstorming
+• "see ideas" → View backlog
+
+Or use: /p:now | /p:idea | /p:recap
+```
+
+---
+
+## Example 5: Viewing Progress
+
+**User says:**
+```
+show me my progress
+```
+
+**Claude Code response:**
+```markdown
+💬 I understood: "view progress"
+⚡ Executing: /p:recap
+
+📊 Recap
+
+🎯 Current: building user dashboard
+🚀 Shipped: 3
+📝 Queue: 5
+💡 Ideas: 8
+
+Recent: authentication system (2h ago)
+```
+
+---
+
+## Example 6: Getting Help
+
+**User says:**
+```
+I'm stuck on this CORS error with the API
+```
+
+**Claude Code response:**
+```markdown
+💬 I understood: "need help"
+⚡ Executing: /p:stuck "CORS error with the API"
+
+🆘 Let's solve: CORS error with the API
+
+Common solutions:
+1. Add CORS headers to API responses
+2. Configure proxy in development
+3. Check credentials mode
+
+Need to break this down?
+• "start fixing CORS" → Focus on solution
+• "add as task" → Queue for later
+```
+
+---
+
+## Example 7: Viewing Queue
+
+**User says:**
+```
+what should I work on next?
+```
+
+**Claude Code response:**
+```markdown
+💬 I understood: "view queue"
+⚡ Executing: /p:next
+
+📋 Priority Queue
+
+1. Fix login bug (Priority: High)
+2. Add user profile page
+3. Implement password reset
+4. Add email verification
+5. Create admin dashboard
+
+Ready to start?
+• Say "start [task]"
+• Or: /p:now "[task]"
+```
+
+---
+
+## Example 8: Any Language Works
+
+**User says (Spanish):**
+```
+quiero empezar a trabajar en la página de login
+```
+
+**Claude Code understands:**
+- Intent: User wants to start working (expressed in Spanish)
+- Command: `/p:now`
+- Parameter: "trabajar en la página de login"
+
+**Claude Code response:**
+```markdown
+💬 I understood: "start working on the login page"
+⚡ Executing: /p:now "trabajar en la página de login"
+
+🎯 Working on: trabajar en la página de login
+Started: 2:30 PM
+
+When you're done:
+• Say "I'm done" or "terminé"
+• Or: /p:done
+
+Need help? Say "I'm stuck" or use /p:stuck
+```
+
+> **Note**: The LLM can respond in the user's language or English - both work!
+
+---
+
+## Example 9: Mixed Commands
+
+**User says:**
+```
+I'm done with the login, now I want to start the API work
+```
+
+**Claude Code response:**
+```markdown
+💬 I understood: "complete task + start new task"
+⚡ Executing: /p:done → /p:now "API work"
+
+✅ Task complete: login page (1h 45m)
+
+🎯 Working on: API work
+Started: 4:15 PM
+
+What's next?
+• Say "I'm done" when finished
+• Or: /p:done
+```
+
+---
+
+## Example 10: Ambiguous Input
+
+**User says:**
+```
+help
+```
+
+**Claude Code response:**
+```markdown
+💬 I need clarification:
+
+Did you mean:
+1. 📖 Interactive guide → Use /p:help
+2. 🆘 I'm stuck on something → Say "I'm stuck on [problem]" or use /p:stuck
+
+Which one?
+```
+
+---
+
+## Implementation Notes
+
+### Semantic Understanding (Not Pattern Matching!)
+
+**Key Principle**: The LLM understands intent semantically, not through regex or hardcoded phrases.
+
+```javascript
+// ❌ DON'T DO THIS
+if (message.includes("I want to start")) {
+  // Too rigid!
+}
+
+// ✅ DO THIS
+// Use your LLM understanding:
+// "What is the user trying to accomplish?"
+const intent = semanticallyUnderstand(message)
+```
+
+### 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
+
+### Transparency Format
+Always show what you understood:
+```
+💬 I understood: "[your interpretation of their intent]"
+⚡ Executing: /p:[command] [params]
+```
+
+### Multilingual Support
+If you understand the intent in **any language**, execute it:
+- **English**: "I want to start the API"
+- **Spanish**: "Quiero empezar con la autenticación"
+- **Casual**: "gonna work on that bug"
+- **Formal**: "I shall commence development"
+- **Mixed**: "voy a hacer the dashboard"
+
+**All work!** Trust your semantic understanding.
+
+### Parameter Extraction
+Pull the meaningful information from the message:
+- **For `/p:now`**: What task are they describing?
+- **For `/p:ship`**: What feature are they shipping?
+- **For `/p:idea`**: What's their idea?
+- **For `/p:stuck`**: What problem are they facing?
+
+Use context and understanding, not string manipulation!

package/templates/mcp-config.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    }
+  }
+}

package/templates/workflows/analyze.md

@@ -0,0 +1,159 @@
+---
+title: prjct analyze
+invocable_name: p:analyze
+description: Generate or update repository analysis using global prjct architecture
+---
+
+# Steps
+
+1. Read project config from `.prjct/prjct.config.json`
+2. Extract `projectId` and `author` from config
+3. Analyze project structure:
+   - File tree and organization
+   - Package dependencies
+   - Framework detection
+   - Code patterns and conventions
+4. Analyze technical stack:
+   - Languages and versions
+   - Frameworks and libraries
+   - Build tools and scripts
+   - Testing setup
+5. Identify key components:
+   - Entry points
+   - Core modules
+   - API endpoints
+   - UI components
+6. Assess project health:
+   - Code quality indicators
+   - Test coverage
+   - Documentation coverage
+   - Technical debt
+7. Generate or update analysis file: `~/.prjct-cli/projects/{projectId}/analysis/repo-summary.md`
+8. Update project context: `~/.prjct-cli/projects/{projectId}/core/context.md`
+9. Log analysis to memory
+10. Display summary and insights
+
+# Response Format
+
+```
+🔍 Repository Analysis Complete
+
+## Project Overview
+- Name: {project-name}
+- Type: {app-type}
+- Primary Language: {language}
+- Framework: {framework}
+
+## Technical Stack
+**Languages**: {languages with percentages}
+**Frameworks**: {frameworks and versions}
+**Key Dependencies**:
+- {dep 1} ({version})
+- {dep 2} ({version})
+- {dep 3} ({version})
+
+## Project Structure
+{directory-tree-summary}
+
+## Key Components
+- **Entry Points**: {files}
+- **Core Modules**: {modules}
+- **API Layer**: {endpoints-count} endpoints
+- **UI Components**: {components-count} components
+- **Tests**: {tests-count} test files
+
+## Code Patterns
+- Architecture: {pattern} (e.g., MVC, Clean, Microservices)
+- State Management: {approach}
+- API Style: {REST/GraphQL/gRPC}
+- Error Handling: {pattern}
+
+## Project Health
+- Code Quality: {score/10}
+- Test Coverage: {X}%
+- Documentation: {Good/Fair/Needs Improvement}
+- Technical Debt: {Low/Medium/High}
+
+## Insights
+{key-insights-from-analysis}
+
+## Recommendations
+1. {recommendation-1}
+2. {recommendation-2}
+3. {recommendation-3}
+
+📄 Full analysis saved to: ~/.prjct-cli/projects/{id}/analysis/repo-summary.md
+
+Use /p:context to see how this integrates with your workflow
+```
+
+# Analysis Depth
+
+**Quick Analysis** (default):
+- File structure scan
+- Package.json/requirements parsing
+- Framework detection
+- Basic metrics
+
+**Deep Analysis** (optional):
+- Code complexity analysis
+- Dependency graph
+- Test coverage calculation
+- Documentation audit
+- Security scan
+
+# Framework Detection
+
+Auto-detect:
+- **Frontend**: React, Vue, Angular, Svelte, Next.js
+- **Backend**: Express, Fastify, NestJS, Django, Flask
+- **Mobile**: React Native, Flutter, Swift, Kotlin
+- **Desktop**: Electron, Tauri
+- **Database**: PostgreSQL, MongoDB, Redis, MySQL
+
+# Analysis File Structure
+
+```markdown
+# Repository Analysis - {date}
+
+## Overview
+{summary}
+
+## Stack
+{detailed-stack-info}
+
+## Architecture
+{architectural-patterns}
+
+## Dependencies
+{dependency-analysis}
+
+## Code Organization
+{structure-details}
+
+## Quality Metrics
+{metrics-and-scores}
+
+## Recommendations
+{actionable-improvements}
+
+## Change Log
+- {date}: Initial analysis
+- {date}: Updated after refactoring
+```
+
+# Integration with Workflow
+
+Analysis helps with:
+- `/p:stuck` - Provides technical context for help
+- `/p:task` - Informs task breakdown based on architecture
+- `/p:roadmap` - Aligns roadmap with technical reality
+- `/p:now` - Better task context awareness
+
+# Global Architecture Notes
+
+- **Analysis Location**: `~/.prjct-cli/projects/{id}/analysis/repo-summary.md`
+- **Context Update**: `~/.prjct-cli/projects/{id}/core/context.md`
+- **Memory Logging**: `~/.prjct-cli/projects/{id}/memory/context.jsonl`
+- **Config Location**: `{project}/.prjct/prjct.config.json`
+- **Use Case**: Onboarding, debugging, refactoring, planning