prjct-cli 0.4.0

package/templates/agents/AGENTS.md

@@ -0,0 +1,164 @@
+# AGENTS.md
+
+AI assistant guidance for prjct-cli.
+
+## Talk Naturally
+
+**You don't need to memorize commands** - just describe what you want to do!
+
+The AI assistant uses **semantic understanding** to map your intent to commands. Works in **any language** the LLM understands (primarily English and Spanish).
+
+**Examples:**
+```
+Intent: Start working on something
+→ "I want to build the login page"
+→ "Let me work on authentication"
+→ "Voy a hacer el dashboard"
+→ Command: /p:now
+
+Intent: Finished current work
+→ "I'm done" | "finished" | "terminé" | "completed"
+→ Command: /p:done
+
+Intent: Ship a feature
+→ "ship this" | "deploy it" | "ready to launch"
+→ Command: /p:ship
+```
+
+**Both work simultaneously:**
+- Talk naturally: "I want to start building auth"
+- Use commands directly: `/p:now "building auth"`
+
+## Architecture
+
+**Global**: `~/.prjct-cli/projects/{id}/`
+```
+core/        # now.md, next.md, context.md
+progress/    # shipped.md, metrics.md
+planning/    # ideas.md, roadmap.md
+analysis/    # repo-summary.md
+memory/      # context.jsonl
+```
+
+**Local**: `.prjct/prjct.config.json`
+
+## MCP Servers
+
+- **Context7**: Library docs (always on)
+- **Filesystem**: File ops
+- **Memory**: Persistence
+- **Sequential**: Complex reasoning
+
+## Quick Start
+
+1. Initialize: `/p:init`
+2. Type: `/p:help` for interactive guide
+3. Or just talk: "I want to start [task]"
+
+## Commands
+
+**💡 Tip**: Type `/p:help` anytime for an interactive guide with natural language options.
+
+| Command | Say This Instead | Action |
+|---------|------------------|--------|
+| `/p:help` | "help" or "what can I do?" | Interactive guide |
+| `/p:init` | - | Create global dirs + config |
+| `/p:now [task]` | "start [task]" | Update `core/now.md` |
+| `/p:done` | "I'm done" or "finished" | Clear focus, suggest next |
+| `/p:ship <feature>` | "ship [feature]" | Add to `progress/shipped.md` |
+| `/p:next` | "what's next?" | Read `core/next.md` |
+| `/p:idea <text>` | "I have an idea about [x]" | Append to `planning/ideas.md` |
+| `/p:recap` | "show my progress" | Aggregate all metrics |
+| `/p:progress [period]` | "how am I doing?" | Filter by timeframe |
+| `/p:stuck <issue>` | "I'm stuck on [issue]" | Context-based guidance |
+| `/p:context` | "show project context" | Display config + activity |
+| `/p:roadmap` | "show the plan" | Read `planning/roadmap.md` |
+| `/p:analyze` | "analyze this repo" | Generate `analysis/repo-summary.md` |
+| `/p:task` | "break this down" | Multi-step execution |
+| `/p:git` | - | Smart commits with context |
+| `/p:fix` | "help me fix [x]" | Quick problem solving |
+| `/p:test` | "run tests" | Execute + report |
+| `/p:design` | "design [x]" | Generate diagrams + specs |
+| `/p:cleanup` | "clean up code" | Remove dead code/deps |
+
+## How It Works
+
+**You can talk naturally:**
+- System detects intent from your message
+- Maps to appropriate command automatically
+- Responds conversationally with options
+- Always suggests what to do next
+
+**Every response includes:**
+- What you just did
+- Natural language options for next steps
+- Command alternatives if you prefer
+
+**Zero memorization needed** - just describe what you want!
+
+## Natural Language Detection
+
+The AI assistant uses **semantic understanding** to map user intent to commands.
+
+### How It Works
+
+**You're an LLM** - use your natural language understanding, not pattern matching!
+
+1. **Check if direct command**: Does message start with `/p:`? → Execute directly
+2. **Understand user intent**: What is the user trying to accomplish?
+3. **Map to appropriate command**: Based on semantic meaning
+4. **Extract parameters**: Pull relevant information from the message
+5. **Show transparency**: Always say what you understood and what you'll execute
+
+### Command Intent Map
+
+| User Intent | Command | Examples of Natural Expression |
+|-------------|---------|-------------------------------|
+| Start/focus on task | `/p:now` | "let me work on X", "starting the API", "voy a hacer X" |
+| Finished current work | `/p:done` | "done", "finished", "terminé", "completed", "listo" |
+| Ship/deploy feature | `/p:ship` | "ship this", "deploy X", "it's ready", "let's launch" |
+| Capture an idea | `/p:idea` | "I have an idea", "what if we...", "tengo una idea" |
+| Check progress/status | `/p:recap` | "show progress", "how am I doing", "muéstrame el avance" |
+| Stuck on problem | `/p:stuck` | "I'm stuck", "help with X", "estoy atascado" |
+| What to work on next | `/p:next` | "what's next", "qué sigue", "what should I do" |
+
+**Key principle**: If you understand what the user wants, map it to the right command. Don't rely on exact phrase matching.
+
+### Example Flow
+
+**User:** "I want to start building the login page"
+
+**Your Reasoning:**
+- Intent detected: User wants to begin working on something
+- Appropriate command: `/p:now`
+- Parameter to extract: "building the login page"
+
+**Your Response:**
+```
+💬 I understood: "start working on building the login page"
+⚡ Executing: /p:now "building the login page"
+
+✅ Starting task: building the login page
+
+What's next?
+• Say "I'm done" when finished
+• Or: /p:done
+```
+
+### Works in Any Language
+
+If you understand the user's intent in **any language**, execute the command:
+- English: "I want to start the API"
+- Spanish: "Quiero empezar con la autenticación"
+- Casual: "gonna work on that login thing"
+- Formal: "I shall commence development of the authentication module"
+
+All map to: `/p:now`
+
+## Implementation
+
+- All ops atomic
+- Log to `memory/context.jsonl` with author
+- Conversational responses with clear options
+- Intent detection (English + Spanish)
+- Handle missing files gracefully

package/templates/commands/analyze.md

@@ -0,0 +1,125 @@
+---
+allowed-tools: [Read, Grep, Glob, Bash, TodoWrite]
+description: "Analyze current repository and generate comprehensive project summary"
+---
+
+## Global Architecture
+This command uses the global prjct architecture:
+- Data stored in: `~/.prjct-cli/projects/{id}/`
+- Config stored in: `{project}/.prjct/prjct.config.json`
+- Commands synchronized across all editors
+
+
+
+# /p:analyze - Repository Analysis
+
+## Purpose
+Automatically analyze the current codebase and generate a comprehensive summary of the repository including technologies, architecture, and project structure.
+
+## Usage
+```
+/p:analyze
+```
+
+## Execution
+1. **Scan project structure** - Analyze directories and file types
+2. **Identify technologies** - Detect frameworks, languages, tools
+3. **Analyze architecture** - Understand project organization and patterns
+4. **Generate summary** - Create detailed analysis report
+5. **Save to analysis** - Store results in `.prjct/analysis/repo-summary.md`
+
+## Implementation
+
+When this command is triggered:
+
+1. **Create analysis directory**:
+   ```bash
+   mkdir -p .prjct/analysis
+   ```
+
+2. **Scan project structure**:
+   - Use Glob to find all files and directories
+   - Identify main directories (src, lib, components, etc.)
+   - Count files by type (.js, .ts, .py, .go, etc.)
+
+3. **Technology detection**:
+   - Check package.json for JavaScript/Node.js projects
+   - Check requirements.txt, Pipfile for Python projects
+   - Check go.mod for Go projects
+   - Check Cargo.toml for Rust projects
+   - Detect frameworks (React, Vue, Angular, Express, FastAPI, etc.)
+
+4. **Architecture analysis**:
+   - Identify entry points (main.js, app.py, main.go)
+   - Analyze import/require patterns
+   - Detect architectural patterns (MVC, microservices, monolith)
+   - Identify configuration files
+
+5. **Generate comprehensive report**:
+   ```markdown
+   # Repository Analysis Report
+
+   ## Project Overview
+   - **Name**: [Detected from package.json or directory name]
+   - **Type**: [Web app, Library, CLI tool, etc.]
+   - **Primary Language**: [JavaScript, Python, Go, etc.]
+   - **Framework**: [React, Express, FastAPI, etc.]
+
+   ## Structure Analysis
+   - **Total Files**: [count]
+   - **Main Directories**: [list]
+   - **Entry Points**: [main files]
+
+   ## Technologies Detected
+   - **Languages**: [list with percentages]
+   - **Frameworks**: [list]
+   - **Tools**: [build tools, testing, etc.]
+   - **Dependencies**: [key dependencies]
+
+   ## Architecture
+   - **Pattern**: [MVC, Component-based, etc.]
+   - **File Organization**: [description]
+   - **Key Components**: [main modules/components]
+
+   ## Recommendations
+   - [Suggestions for improvements]
+   - [Best practices to consider]
+
+   **Generated**: [timestamp]
+   ```
+
+6. **Save analysis**:
+   Write the complete analysis to `.prjct/analysis/repo-summary.md`
+
+7. **Provide summary**:
+   Display key findings and next suggested actions
+
+## Example Workflow
+
+```bash
+# Run analysis
+/p:analyze
+
+# Results saved to:
+# .prjct/analysis/repo-summary.md
+
+# Example output:
+🔍 **Repository Analysis Complete**
+
+**Project**: prjct-cli (CLI Tool)
+**Language**: JavaScript (Node.js)
+**Structure**: 45 files across 8 directories
+**Dependencies**: 12 packages detected
+
+📄 **Full report**: `.prjct/analysis/repo-summary.md`
+
+**Next steps**:
+- `/p:roadmap` - Plan development roadmap
+- `/p:now "implement feature X"` - Set current focus
+```
+
+## Error Handling
+- Handle projects without clear package managers
+- Gracefully handle large repositories (>1000 files)
+- Provide meaningful analysis even for minimal projects
+- Skip binary files and common ignore patterns

package/templates/commands/cleanup.md

@@ -0,0 +1,102 @@
+---
+name: p:cleanup
+description: Advanced code cleanup and optimization with backup capabilities
+---
+
+# /p:cleanup - Advanced Code Cleanup and Optimization
+
+Remove dead code, optimize imports, clean project structure, analyze unused dependencies, and clean up temporary files. Comprehensive cleanup with backup capabilities.
+
+## Usage
+
+```
+/p:cleanup [target] [--type code|imports|files|deps|memory|all] [--safe|--aggressive] [--dry-run]
+```
+
+## Global Architecture
+
+This command operates on global data stored in `~/.prjct-cli/projects/{project-id}/`.
+
+### Steps
+
+1. Read `.prjct/prjct.config.json` for project ID and author
+2. Parse cleanup arguments (target, type, mode)
+3. Create backup to `~/.prjct-cli/projects/{id}/backups/{timestamp}/` before aggressive cleanup
+4. Execute cleanup by type:
+   - **code**: Remove console.logs, commented code, dead code
+   - **imports**: Remove unused imports, organize imports
+   - **files**: Remove temp files, empty files, backups
+   - **deps**: Analyze and remove unused npm dependencies
+   - **memory**: Archive old memory entries (>30 days) to `~/.prjct-cli/projects/{id}/memory/archive/`
+   - **all**: All cleanup types
+5. Validate syntax after changes (JavaScript/TypeScript)
+6. Log all changes to `~/.prjct-cli/projects/{id}/memory/cleanup-log.jsonl`
+7. Log action with author to context.jsonl
+8. Display cleanup results with metrics
+
+## Response Format
+
+```
+🧹 ✨ Cleanup Complete! ✨ 🧹
+
+📊 Cleanup Results:
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🗑️ Dead Code Removed:
+• Console.logs: {count} statements
+• Commented code: {count} blocks
+• Unused functions: {count}
+
+📦 Imports Optimized:
+• Unused imports: {count} removed
+• Files organized: {count}
+
+📁 Files Cleaned:
+• Temp files: {count} removed
+• Empty files: {count} removed
+• Space freed: {size} MB
+
+📚 Dependencies:
+• Unused packages: {count} removed
+• Size reduced: {size} MB
+
+📦 Archived:
+• Memory entries: {count} (older than 30 days)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✨ Your project is clean and optimized!
+
+💡 Tip: Run with --dry-run first to preview changes
+```
+
+## Safety Measures
+
+- Create backup before aggressive cleanup
+- Log all changes to cleanup-log.jsonl
+- Validate syntax after modifications
+- Skip files with uncommitted git changes
+- Provide --dry-run option to preview
+
+## Examples
+
+Basic cleanup:
+```
+/p:cleanup
+```
+
+Cleanup specific type:
+```
+/p:cleanup --type code
+/p:cleanup --type imports
+/p:cleanup --type deps
+```
+
+Preview changes:
+```
+/p:cleanup --dry-run
+```
+
+Aggressive cleanup with backup:
+```
+/p:cleanup --aggressive --type all
+```

package/templates/commands/context.md

@@ -0,0 +1,105 @@
+---
+allowed-tools: [Read, Glob, Bash]
+description: "Show project context and recent activity"
+---
+
+## Global Architecture
+This command uses the global prjct architecture:
+- Data stored in: `~/.prjct-cli/projects/{id}/`
+- Config stored in: `{project}/.prjct/prjct.config.json`
+- Commands synchronized across all editors
+
+
+
+# /p:context - Project Context
+
+## Purpose
+Display project context including type, current task, and recent activity.
+
+## Usage
+```
+/p:context
+```
+
+## Execution
+1. Aggregate context from all project layers
+2. Reference analysis for technical context
+3. Show current task and planning alignment
+4. Display recent activity from memory layer
+5. Provide cross-layer insights and suggestions
+
+## Implementation
+
+1. **Layer aggregation**:
+   - **Core Layer**: Current task from `.prjct/core/now.md`, queue from `.prjct/core/next.md`
+   - **Analysis Layer**: Project insights from `.prjct/analysis/repo-summary.md`
+   - **Planning Layer**: Roadmap status from `.prjct/planning/roadmap.md`
+   - **Progress Layer**: Recent metrics from `.prjct/progress/metrics.md`
+   - **Memory Layer**: Activity history from `.prjct/memory/context.jsonl`
+
+2. **Enhanced context reading**:
+   - Project type and architecture from analysis layer
+   - Strategic alignment from planning layer
+   - Performance metrics from progress layer
+   - Decision history from memory layer
+
+3. **Comprehensive response format**:
+   ```
+   🌍 PROJECT CONTEXT
+   ━━━━━━━━━━━━━━━━━━━━━━━
+
+   📦 PROJECT OVERVIEW
+   Type: Next.js Application
+   Location: /Users/dev/projects/app
+   Framework: React 18, TypeScript
+   Architecture: [from analysis layer]
+
+   🎯 CURRENT FOCUS
+   Task: Building user dashboard
+   Started: 45 minutes ago
+   Strategic alignment: High (roadmap priority #2)
+
+   📈 RECENT PROGRESS
+   Velocity: 1.4 features/day
+   Streak: 5 days shipping
+   Quality: 95% success rate
+
+   🔄 RECENT ACTIVITY (from memory layer):
+   • shipped: Authentication system (2h ago)
+   • done: API endpoints (3h ago)
+   • idea: Add real-time updates (4h ago)
+   • now: Building user dashboard (45m ago)
+   • decision: Chose Next.js over Nuxt (yesterday)
+
+   💡 PLANNING STATUS
+   Queue: 3 tasks pending
+   Ideas: 7 captured
+   Roadmap progress: 23% complete
+
+   🧠 KEY INSIGHTS
+   Recent decisions: 3 logged
+   Learning areas: Architecture patterns
+   Growth momentum: +15% complexity handling
+
+   📂 LAYER NAVIGATION:
+   - Core: .prjct/core/ (focus & priorities)
+   - Analysis: .prjct/analysis/ (technical insights)
+   - Planning: .prjct/planning/ (strategy & roadmap)
+   - Progress: .prjct/progress/ (metrics & shipped)
+   - Memory: .prjct/memory/ (decisions & history)
+
+   🎯 NEXT SUGGESTED ACTION:
+   Continue with current task or /p:done if complete
+   ```
+
+4. **Project insights**:
+   - Dependencies summary
+   - Test coverage if available
+   - Build status
+   - Last deploy info
+
+5. **Smart suggestions**:
+   Based on context, suggest:
+   - "Long task - consider breaking down"
+   - "Good time to ship and take a break"
+   - "Review queue priorities"

package/templates/commands/design.md

@@ -0,0 +1,113 @@
+---
+name: p:design
+description: Design system architecture, APIs, and component interfaces
+---
+
+# /p:design - System Architecture and Design
+
+Create technical designs with visual diagrams and implementation guides for system architecture, APIs, components, databases, and user flows.
+
+## Usage
+
+```
+/p:design [target] [--type architecture|api|component|database|flow] [--format diagram|spec|code|all]
+```
+
+## Global Architecture
+
+This command operates on global data stored in `~/.prjct-cli/projects/{project-id}/`.
+
+### Steps
+
+1. Parse design target and type (architecture, api, component, database, flow)
+2. Generate appropriate ASCII diagrams and visual representations
+3. Create technical specifications with technology stack and patterns
+4. Generate implementation templates and interfaces
+5. Save designs to `~/.prjct-cli/projects/{id}/designs/` directory
+6. Display formatted design with overview, specs, and implementation guide
+7. Link designs to tasks and track implementation progress
+
+## Response Format
+
+```
+🎨 ✨ Design Complete! ✨ 🎨
+
+📐 Design: [Target Name]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🏗️ Architecture Overview:
+[ASCII diagram or description]
+
+📋 Technical Specifications:
+• Technology Stack: [stack details]
+• Design Patterns: [patterns used]
+• Key Components: [component list]
+
+📦 Implementation Guide:
+1. Set up project structure
+2. Implement core models
+3. Build API endpoints
+4. Create UI components
+
+📁 Files Created:
+• ~/.prjct-cli/projects/{id}/designs/[target]-architecture.md
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ Design ready for implementation!
+
+💡 Next: /p:now "Implement [target]"
+```
+
+## Design Types
+
+### Architecture
+- System architecture diagrams
+- Component relationships
+- Data flow and communication patterns
+- Scalability considerations
+
+### API
+- Endpoint specifications
+- Request/response schemas
+- Authentication and authorization
+- Rate limiting and caching
+
+### Component
+- Component interfaces
+- Props and state management
+- Lifecycle and hooks
+- Styling and theming
+
+### Database
+- Schema design
+- Entity relationships
+- Indexing strategy
+- Migration plans
+
+### Flow
+- User journey diagrams
+- State machine flows
+- Process workflows
+- Integration flows
+
+## Examples
+
+Design system architecture:
+```
+/p:design authentication --type architecture
+```
+
+Design API endpoints:
+```
+/p:design user-management --type api --format spec
+```
+
+Design database schema:
+```
+/p:design products --type database --format diagram
+```
+
+Complete design with all formats:
+```
+/p:design payment-system --type architecture --format all
+```

package/templates/commands/done.md

@@ -0,0 +1,44 @@
+---
+allowed-tools: [Read, Write, Edit, TodoWrite]
+description: "Complete task, clear focus"
+---
+
+# /p:done
+
+## Usage
+```
+/p:done
+```
+
+## Execution
+
+1. Read task from `~/.prjct-cli/projects/{id}/core/now.md`, calculate duration
+2. Clear `core/now.md`
+3. Update `progress/metrics.md`, `core/context.md`
+4. Log to `memory/context.jsonl`:
+   ```json
+   {"action":"done","task":"[task]","started":"[t1]","completed":"[t2]","duration":"[min]","layer":"core"}
+   ```
+5. Response:
+   ```
+   ✅ [task description] ([duration])
+
+   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
+   ```
+
+   Or if queue empty:
+   ```
+   ✅ [task description] ([duration])
+
+   Queue is empty! What now?
+   • "add a task" → Plan next work
+   • "brainstorm ideas" → Creative mode
+   • "see my progress" → View achievements
+
+   Or: /p:idea | /p:next | /p:recap
+   ```