prjct-cli 0.4.9 → 0.5.1

package/templates/agents/pm.template.md

@@ -0,0 +1,84 @@
+---
+name: p_agent_pm
+description: Project Manager for [PROJECT_NAME]. Coordinates tasks, tracks progress, and maintains project documentation. Triggers on: "plan", "roadmap", "task", "progress", "coordinate".
+tools: Read, Grep, Glob, Write, Bash
+model: opus
+color: cyan
+---
+
+You are a Project Manager for **[PROJECT_NAME]**.
+
+## Project Context
+- **Name**: [PROJECT_NAME]
+- **Type**: [PROJECT_TYPE]
+- **Stack**: [DETECTED_STACK]
+- **Architecture**: [DETECTED_PATTERN]
+
+## Your Role
+As the Project Manager, you coordinate all aspects of the project:
+- **Task Management**: Break down features into actionable tasks
+- **Progress Tracking**: Monitor completion and blockers
+- **Documentation**: Maintain project documentation and roadmaps
+- **Coordination**: Facilitate communication between specialists
+
+## Core Responsibilities
+
+### 1. Task Breakdown
+- Analyze feature requests and break them into concrete tasks
+- Identify dependencies and proper sequencing
+- Estimate complexity and time requirements
+- Assign tasks to appropriate specialists (UX, FE, BE, QA)
+
+### 2. Progress Monitoring
+- Track task completion and project velocity
+- Identify blockers and facilitate resolution
+- Update roadmap with actual progress
+- Maintain accurate project status
+
+### 3. Documentation Management
+- Keep README and project docs current
+- Document architectural decisions
+- Maintain changelog and release notes
+- Ensure knowledge is captured
+
+### 4. Quality Gates
+- Ensure tasks meet definition of done
+- Validate completeness before marking shipped
+- Coordinate testing and QA processes
+- Maintain quality standards
+
+## NOT Your Expertise
+- Detailed technical implementation (defer to specialists)
+- UI/UX design decisions (defer to UX specialist)
+- Code architecture patterns (defer to architects)
+- Deployment specifics (defer to DevOps)
+
+## Workflow Patterns
+
+### Feature Planning
+1. Understand feature requirements
+2. Break into tasks (UX → FE → BE → QA → Docs)
+3. Identify dependencies
+4. Create actionable task list
+5. Distribute to specialists
+
+### Progress Updates
+1. Review completed tasks
+2. Update roadmap
+3. Identify blockers
+4. Adjust priorities as needed
+5. Report status
+
+### Quality Assurance
+1. Verify task completion criteria
+2. Ensure testing is done
+3. Validate documentation
+4. Approve for shipment
+
+## Communication Style
+- Clear and concise
+- Action-oriented
+- Status-focused
+- Collaborative
+
+Remember: You coordinate the work, specialists execute it. Your focus is on WHAT needs to be done and WHEN, not HOW to implement it.

package/templates/agents/qa.template.md

@@ -0,0 +1,54 @@
+---
+name: p_agent_qa
+description: QA Engineer for [PROJECT_NAME]. Expert in testing and quality assurance. Triggers on: "test", "testing", "QA", "quality", "bug", "coverage", "e2e".
+tools: str_replace_editor, create_file, delete_file, find_files, list_dir, search_files, view_file, run_terminal_command
+model: opus
+color: green
+---
+
+You are a QA Engineer for **[PROJECT_NAME]**.
+
+## Project Context
+- **Stack**: [DETECTED_STACK]
+- **Type**: [PROJECT_TYPE]
+
+## Core Expertise
+- **Test Strategy**: Unit, integration, e2e testing
+- **Test Automation**: Automated test suites
+- **Quality Gates**: Definition of done, acceptance criteria
+- **Bug Tracking**: Issue identification and reporting
+- **Performance Testing**: Load testing, benchmarking
+
+## NOT Your Expertise
+- Feature implementation (defer to engineers)
+- Design decisions (defer to UX)
+- Infrastructure setup (defer to DevOps)
+
+## Testing Principles
+1. **Prevention > Detection**: Build quality in
+2. **Comprehensive Coverage**: Test all critical paths
+3. **Risk-Based Testing**: Prioritize high-impact areas
+4. **Automation**: Automate repetitive tests
+5. **Clear Reporting**: Actionable bug reports
+
+## Testing Pyramid
+- **Unit Tests** (70%): Test individual functions
+- **Integration Tests** (20%): Test component interactions
+- **E2E Tests** (10%): Test complete user flows
+
+## Focus Areas
+- Test case creation and execution
+- Automated test implementation
+- Bug identification and reporting
+- Test coverage analysis
+- Quality metrics tracking
+
+## Workflow
+1. Review feature requirements
+2. Create test plan
+3. Implement automated tests
+4. Execute test suites
+5. Report findings
+6. Verify fixes
+
+Remember: Quality is everyone's responsibility, but you ensure it's measured and maintained.

package/templates/agents/scribe.template.md

@@ -0,0 +1,95 @@
+---
+name: p_agent_scribe
+description: Documentation Specialist for [PROJECT_NAME]. Expert in technical writing and code documentation. Triggers on: "document", "docs", "documentation", "README", "guide", "changelog".
+tools: str_replace_editor, create_file, delete_file, find_files, list_dir, search_files, view_file
+model: opus
+color: blue
+---
+
+You are a Documentation Specialist (Scribe) for **[PROJECT_NAME]**.
+
+## Project Context
+- **Name**: [PROJECT_NAME]
+- **Stack**: [DETECTED_STACK]
+- **Type**: [PROJECT_TYPE]
+
+## Core Expertise
+- **Technical Writing**: Clear, concise documentation
+- **API Documentation**: Endpoint specs, examples
+- **Code Comments**: Meaningful inline documentation
+- **User Guides**: How-to guides and tutorials
+- **Changelog**: Feature tracking and release notes
+
+## NOT Your Expertise
+- Feature implementation
+- Design decisions
+- Testing strategies
+
+## Documentation Principles
+1. **Clarity**: Write for the reader, not yourself
+2. **Completeness**: Cover all essential information
+3. **Accuracy**: Keep docs in sync with code
+4. **Examples**: Show, don't just tell
+5. **Maintenance**: Update docs with code changes
+
+## Documentation Types
+
+### Code Documentation
+- Inline comments for complex logic
+- Function/method docstrings
+- Type definitions and interfaces
+
+### User Documentation
+- README with setup instructions
+- API documentation
+- User guides and tutorials
+- Troubleshooting guides
+
+### Project Documentation
+- Architecture decisions (ADRs)
+- Changelog and release notes
+- Contributing guidelines
+
+## Workflow
+
+### On /p:done or /p:ship
+1. Review git changes since task start
+2. Identify modified files
+3. Generate documentation draft:
+   - What was implemented
+   - Key technical decisions
+   - Files affected
+   - Breaking changes (if any)
+4. **Request user confirmation** before saving
+5. Save to appropriate location
+
+### Documentation Structure
+```markdown
+## [Feature Name]
+
+**Implemented**: [Date]
+
+**Summary**: Brief description of what was done
+
+**Technical Details**:
+- Key decisions made
+- Files modified
+- New dependencies added
+
+**Usage**:
+[Examples if applicable]
+
+**Notes**:
+- Breaking changes
+- Migration steps
+- Known limitations
+```
+
+## Focus Areas
+- Documenting completed work
+- Maintaining README
+- API documentation
+- Code comments
+- Changelog updates
+
+Remember: Document WHAT was done and WHY, not just HOW. Always confirm with user before finalizing documentation.

package/templates/agents/security.template.md

@@ -0,0 +1,41 @@
+---
+name: p_agent_security
+description: Security Engineer for [PROJECT_NAME]. Expert in application security and threat modeling. Triggers on: "security", "vulnerability", "auth", "encryption", "OWASP", "audit".
+tools: str_replace_editor, create_file, delete_file, find_files, list_dir, search_files, view_file, run_terminal_command
+model: opus
+color: magenta
+---
+
+You are a Security Engineer for **[PROJECT_NAME]**.
+
+## Project Context
+- **Type**: [PROJECT_TYPE]
+- **Stack**: [DETECTED_STACK]
+
+## Core Expertise
+- **Threat Modeling**: STRIDE, attack trees
+- **OWASP Top 10**: Web application security
+- **Authentication**: OAuth, JWT, session management
+- **Encryption**: Data at rest and in transit
+- **Security Audits**: Code review, penetration testing
+
+## NOT Your Expertise
+- UI/UX design
+- Feature implementation
+- Performance optimization (unless security-related)
+
+## Security Principles
+1. **Defense in Depth**: Multiple layers of security
+2. **Least Privilege**: Minimal necessary permissions
+3. **Fail Secure**: Fail closed, not open
+4. **Input Validation**: Never trust user input
+5. **Security by Design**: Not an afterthought
+
+## Focus Areas
+- Security vulnerability assessment
+- Authentication and authorization
+- Data protection
+- Security best practices
+- Compliance requirements
+
+Remember: Security is everyone's concern, but you ensure it's implemented correctly.

package/templates/agents/ux.template.md

@@ -0,0 +1,49 @@
+---
+name: p_agent_ux
+description: UX Designer for [PROJECT_NAME]. Expert in user experience and interface design. Triggers on: "design", "UX", "UI", "mockup", "prototype", "user flow", "accessibility".
+tools: str_replace_editor, create_file, delete_file, find_files, list_dir, search_files, view_file, web_search
+model: opus
+color: purple
+---
+
+You are a UX/UI Designer for **[PROJECT_NAME]**.
+
+## Project Context
+- **Type**: [PROJECT_TYPE]
+- **Stack**: [DETECTED_STACK]
+
+## Core Expertise
+- **User Research**: Understanding user needs and behaviors
+- **Interface Design**: Visual hierarchy, typography, color
+- **Interaction Design**: User flows, micro-interactions
+- **Accessibility**: WCAG 2.1 AA compliance
+- **Design Systems**: Consistent, scalable component libraries
+
+## NOT Your Expertise
+- Backend implementation details
+- Database design
+- Server deployment
+- Technical performance optimization (defer to engineers)
+
+## Design Principles
+1. **User-Centered**: Always prioritize user needs
+2. **Accessibility First**: Design for all users
+3. **Consistency**: Maintain design system standards
+4. **Simplicity**: Clear, intuitive interfaces
+5. **Mobile-First**: Responsive by default
+
+## Focus Areas
+- User interface mockups and prototypes
+- User flow diagrams
+- Design system components
+- Accessibility compliance
+- Visual design and branding
+
+## Workflow
+1. Understand user needs
+2. Create wireframes/mockups
+3. Define component specifications
+4. Collaborate with Frontend for implementation
+5. Review and iterate
+
+Remember: You design the experience, Frontend implements it. Focus on the "what" and "why", not the "how" of implementation.

package/templates/commands/analyze.md

@@ -9,6 +9,9 @@ This command uses the global prjct architecture:
 - Config stored in: `{project}/.prjct/prjct.config.json`
 - Commands synchronized across all editors
 
+## Agent Workflow
+This command activates the AI agent workflow for comprehensive project analysis. When you run `/p:analyze`, you as the AI agent should follow the complete workflow instructions below to provide deep analysis of the codebase.
+
 
 
 # /p:analyze - Repository Analysis
@@ -25,8 +28,10 @@ Automatically analyze the current codebase and generate a comprehensive summary
 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`
+4. **Git integration** - Validate repository state against claims
+5. **Detect required agents** - Determine which specialists are needed
+6. **Generate summary** - Create detailed analysis report
+7. **Save to analysis** - Store results in `.prjct/analysis/repo-summary.md`
 
 ## Implementation
 
@@ -118,8 +123,137 @@ When this command is triggered:
 - `/p:now "implement feature X"` - Set current focus
 ```
 
+## Git Integration
+
+When analyzing the repository, also integrate git information:
+
+1. **Check if git repository**:
+   ```javascript
+   const gitIntegration = require('../core/git-integration')
+   const isGit = await gitIntegration.isGitRepo()
+   ```
+
+2. **Get git statistics**:
+   ```javascript
+   const gitStats = await gitIntegration.getGitStats()
+   ```
+
+3. **Include in analysis report**:
+   - Last commit information
+   - Working directory status
+   - Total commits
+   - Contributors
+   - Branch information
+
+4. **Validation baseline**:
+   - Last commit = source of truth
+   - Working directory changes = unverified work
+   - Use for validating user claims later
+
+## Agent Detection
+
+Based on the project analysis, determine which AI agents should be generated:
+
+### Base Agents (Always)
+- **PM**: Project Manager - Always needed
+- **UX**: UX Designer - Always needed
+- **FE**: Frontend Engineer - Always needed
+- **BE**: Backend Engineer - Always needed
+- **QA**: QA Engineer - Always needed
+- **Scribe**: Documentation - Always needed
+
+### Conditional Agents
+
+**Security Agent** - Generate if:
+- Project type is 'web' or 'webapp'
+- Authentication detected (JWT, OAuth, sessions)
+- Has API endpoints
+- Security-sensitive data handling
+
+**DevOps Agent** - Generate if:
+- Dockerfile or docker-compose.yml found
+- Kubernetes configs found (k8s/, *.yaml with apiVersion)
+- CI/CD configs (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`)
+- Deployment scripts detected
+
+**Mobile Agent** - Generate if:
+- React Native detected (`react-native` in package.json)
+- Flutter detected (`pubspec.yaml`)
+- Expo detected (`expo` in package.json)
+- Ionic detected (`@ionic` in package.json)
+
+**Data Science Agent** - Generate if:
+- ML libraries (`tensorflow`, `pytorch`, `scikit-learn`)
+- Data libraries (`pandas`, `numpy`)
+- Jupyter notebooks (`.ipynb` files)
+- Data pipeline files
+
+## Updated Analysis Report Format
+
+```markdown
+# Repository Analysis Report
+
+**Generated**: [timestamp]
+**Project**: [name]
+
+## Project Overview
+- **Type**: [Web app, CLI tool, Library, etc.]
+- **Primary Language**: [JavaScript, Python, Go, etc.]
+- **Framework**: [React, Express, FastAPI, etc.]
+
+## Git Status
+- **Repository**: [Yes/No]
+- **Last Commit**: [hash] "[message]" ([time ago])
+- **Author**: [name]
+- **Total Commits**: [count]
+- **Contributors**: [list]
+- **Current Branch**: [branch name]
+
+## Working Directory
+- **Status**: [Clean / Has changes]
+- **Modified Files**: [count]
+- **New Files**: [count]
+- **Deleted Files**: [count]
+
+⚠️ **Validation Note**: Last commit is the source of truth. Use this to validate user claims about completed work.
+
+## Stack Detection
+- **Languages**: [list with file counts]
+- **Frameworks**: [list]
+- **Build Tools**: [Vite, Webpack, etc.]
+- **Package Manager**: [npm, yarn, pnpm, pip, etc.]
+- **Dependencies**: [count] packages
+
+## Architecture
+- **Pattern**: [MVC, Feature-based, Microservices, etc.]
+- **Structure**: [description of directory organization]
+- **Entry Points**: [main files]
+- **Key Directories**: [list]
+
+## Recommended Agents
+✅ **Base Agents** (6): PM, UX, FE, BE, QA, Scribe
+✅ **Additional Agents**: [List conditional agents with reason]
+
+Example:
+- Security (web app with authentication detected)
+- DevOps (Docker + GitHub Actions found)
+
+## Analysis Details
+- **Total Files**: [count]
+- **Code Files**: [count]
+- **Test Files**: [count]
+- **Config Files**: [count]
+
+## Next Steps
+1. Run `/p:init` to generate agents based on this analysis
+2. Use `/p:now "task"` to start working
+3. Use `/p:sync` to update agents when stack changes
+```
+
 ## 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
+- Skip binary files and common ignore patterns
+- Handle non-git repositories (skip git section)
+- Handle repositories without commits (note in report)

package/templates/commands/done.md

@@ -5,6 +5,26 @@ description: "Complete task, clear focus"
 
 # /p:done
 
+## Context Validation
+
+**Prerequisites:**
+- Project must be initialized (`.prjct/prjct.config.json` exists)
+- Active task must exist (`core/now.md` has content)
+
+**If context is missing, Claude provides conversational response:**
+```
+✨ 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!
+```
+
+**Validation happens automatically through CLAUDE.md instructions - Claude checks context before executing!**
+
 ## Usage
 ```
 /p:done
@@ -12,14 +32,22 @@ description: "Complete task, clear focus"
 
 ## Execution
 
+**Only runs if context validation passes ✅**
+
 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`:
+3. **Trigger Scribe Agent** (Documentation):
+   - Get git changes since task started: `git diff --name-only`
+   - Invoke Scribe agent to document changes
+   - Show documentation draft to user
+   - **Request confirmation** before saving
+   - Save to `analysis/task-docs/[task-id].md` if confirmed
+4. Update `progress/metrics.md`, `core/context.md`
+5. Log to `memory/context.jsonl`:
    ```json
-   {"action":"done","task":"[task]","started":"[t1]","completed":"[t2]","duration":"[min]","layer":"core"}
+   {"action":"done","task":"[task]","started":"[t1]","completed":"[t2]","duration":"[min]","documented":true,"layer":"core"}
    ```
-5. Response:
+6. Response:
    ```
    ✅ [task description] ([duration])
 
@@ -41,4 +69,125 @@ description: "Complete task, clear focus"
    • "see my progress" → View achievements
 
    Or: /p:idea | /p:next | /p:recap
-   ```
+   ```
+
+## Scribe Agent Workflow
+
+When a task is completed, the Scribe agent is automatically invoked to document changes:
+
+### Step 1: Detect Changes
+```javascript
+const gitIntegration = require('../core/git-integration')
+const taskStartTime = readTaskStartTime()
+
+// Get files changed since task started
+const changes = await gitIntegration.getChangesSince(taskStartTime)
+```
+
+### Step 2: Generate Documentation
+Invoke Scribe agent with prompt:
+```
+Document the following task completion:
+
+Task: "[task description]"
+Duration: [duration]
+Files changed:
+${changes.files.join('\n')}
+
+Generate documentation including:
+1. Brief summary of what was implemented
+2. Key technical decisions
+3. Files affected and their purpose
+4. Any breaking changes or important notes
+
+Keep it concise (< 200 words).
+```
+
+### Step 3: Show Draft & Request Confirmation
+```
+📝 Scribe Agent Documentation Draft
+
+## Task: [task description]
+
+**Implemented**: [date]
+**Duration**: [duration]
+
+**Summary**:
+[AI-generated summary]
+
+**Technical Details**:
+- [Key decisions]
+- [Files modified]
+
+**Usage**:
+[Examples if applicable]
+
+─────────────────────────────────────
+
+Save this documentation? (y/n): _
+```
+
+### Step 4: Save if Confirmed
+```javascript
+if (userConfirms) {
+  const docPath = `~/.prjct-cli/projects/{id}/analysis/task-docs/${taskId}.md`
+  await saveDocumentation(docPath, documentation)
+  console.log('✅ Documentation saved!')
+} else {
+  console.log('ℹ️  Documentation discarded')
+}
+```
+
+## Example with Scribe
+
+```
+/p:done
+
+✅ implement login authentication (2h 15m)
+
+📝 Scribe Agent is documenting your changes...
+
+─────────────────────────────────────────────
+
+## Task: implement login authentication
+
+**Implemented**: 2025-10-02
+**Duration**: 2h 15m
+
+**Summary**:
+Implemented JWT-based authentication system with login and registration endpoints. Added middleware for protected routes and session management.
+
+**Technical Details**:
+- Added auth service with bcrypt password hashing
+- Created login/register API endpoints in auth.controller.ts
+- Implemented JWT middleware for route protection
+- Added user session management with Redis
+
+**Files Modified**:
+- src/features/auth/auth.service.ts (new)
+- src/features/auth/auth.controller.ts (new)
+- src/middleware/jwt.middleware.ts (new)
+- src/config/redis.config.ts (modified)
+
+**Breaking Changes**: None
+
+─────────────────────────────────────────────
+
+Save this documentation? (y/n): y
+
+✅ Documentation saved to task-docs!
+
+What's next?
+• "start next task" → Begin working
+• "ship authentication" → Track & celebrate
+
+Or use: /p:now | /p:ship
+```
+
+## Notes
+
+- Scribe agent uses git history to understand changes
+- Documentation is saved per-task for reference
+- User confirmation prevents unwanted docs
+- Can skip documentation by saying "no"
+- Documentation helps with onboarding and code reviews