prjct-cli 0.4.9 → 0.5.0

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

package/templates/commands/init.md

@@ -151,20 +151,78 @@ Create empty JSONL files for historical tracking:
 - **memory/context.jsonl**: Activity log with timestamps
 - **memory/decisions.jsonl**: Decision history (not used yet)
 
-### 8. Log Initialization
+### 8. Run Project Analysis
+
+Execute `/p:analyze` to understand the project:
+
+```javascript
+// This should execute the analyze command internally
+// The AI will:
+// 1. Scan project structure
+// 2. Detect stack and frameworks
+// 3. Check git status
+// 4. Determine which agents are needed
+// 5. Save analysis to .prjct/analysis/repo-summary.md
+```
+
+### 9. Generate AI Agents
+
+Based on the analysis, generate specialized AI agents:
+
+```javascript
+const agentGenerator = require('../core/agent-generator')
+const analysis = await readAnalysisFile('.prjct/analysis/repo-summary.md')
+
+// Generate all required agents
+const generatedAgents = await agentGenerator.generateAll(analysis)
+
+// Agents are created in ~/.claude/agents/
+// They are immediately available in Claude Code and Claude Desktop
+```
+
+**Generated Agents**:
+- **Base** (always): PM, UX, FE, BE, QA, Scribe (6 agents)
+- **Conditional** (based on project):
+  - Security (if web app or has auth)
+  - DevOps (if Docker/CI/CD detected)
+  - Mobile (if React Native/Flutter detected)
+  - Data (if ML/data science detected)
+
+### 10. Log Initialization
 
 Add initialization record to memory:
 ```jsonl
-{"timestamp":"2025-10-01T09:00:00Z","action":"init","author":"Name","projectPath":"/path/to/project","projectId":"abc123def456"}
+{"timestamp":"2025-10-01T09:00:00Z","action":"init","author":"Name","projectPath":"/path/to/project","projectId":"abc123def456","agents":["pm","ux","fe","be","qa","scribe","security"]}
 ```
 
-### 9. Success Message (Conversational Onboarding)
+### 11. Success Message (Conversational Onboarding)
 
 ```
 ✅ Your project is ready!
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+📦 Project Analysis Complete
+
+Project: [PROJECT_NAME]
+Type: [PROJECT_TYPE]
+Stack: [DETECTED_STACK]
+
+🤖 AI Agents Generated ([COUNT] specialists)
+
+✅ PM - Project coordination
+✅ UX - Design & user experience
+✅ FE - Frontend development
+✅ BE - Backend development
+✅ QA - Testing & quality
+✅ Scribe - Documentation
+[+ conditional agents if detected]
+
+These agents are now available in Claude and will provide
+specialized expertise for your project tasks.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
 💬 Let me show you around...
 
 You don't need to memorize commands.

package/templates/commands/ship.md

@@ -18,14 +18,21 @@ description: "Ship a feature"
    - ✅ [feature] ([timestamp])
    ```
 
-2. Update `progress/metrics.md` (count, velocity, streak)
-3. Update `core/context.md`
-4. Log to `memory/context.jsonl`:
+2. **Trigger Scribe Agent** (Documentation):
+   - Get git changes for the feature: `git diff --name-only`
+   - Invoke Scribe agent to document the shipped feature
+   - Show documentation draft to user
+   - **Request confirmation** before saving
+   - Save to `analysis/feature-docs/[feature-id].md` if confirmed
+
+3. Update `progress/metrics.md` (count, velocity, streak)
+4. Update `core/context.md`
+5. Log to `memory/context.jsonl`:
    ```json
-   {"action":"ship","feature":"[desc]","timestamp":"[ISO]","week":"[w]","layer":"progress","total":[n]}
+   {"action":"ship","feature":"[desc]","timestamp":"[ISO]","week":"[w]","layer":"progress","total":[n],"documented":true}
    ```
 
-5. Response:
+6. Response:
    ```
    🚀 [feature name] shipped!
 
@@ -38,4 +45,137 @@ description: "Ship a feature"
    • "plan ahead" → Strategic thinking
 
    Or: /p:now | /p:recap | /p:roadmap
-   ```
+   ```
+
+## Scribe Agent Workflow
+
+When a feature is shipped, the Scribe agent is automatically invoked to document changes:
+
+### Step 1: Detect Changes
+```javascript
+const gitIntegration = require('../core/git-integration')
+
+// Get files changed for this feature
+const changes = await gitIntegration.getChangesSince(featureStartTime)
+```
+
+### Step 2: Generate Documentation
+Invoke Scribe agent with prompt:
+```
+Document the following shipped feature:
+
+Feature: "[feature description]"
+Shipped: [timestamp]
+Files changed:
+${changes.files.join('\n')}
+
+Generate release documentation including:
+1. Feature overview and user impact
+2. Technical implementation summary
+3. Key files and components affected
+4. Breaking changes or migration notes (if any)
+5. Usage examples
+
+Keep it concise and user-focused (< 300 words).
+```
+
+### Step 3: Show Draft & Request Confirmation
+```
+📝 Scribe Agent Feature Documentation
+
+## Feature: [feature description]
+
+**Shipped**: [date]
+**Impact**: [user-facing impact]
+
+**Overview**:
+[AI-generated feature summary]
+
+**Technical Details**:
+- [Implementation highlights]
+- [Key components]
+
+**Usage**:
+[Examples if applicable]
+
+**Breaking Changes**: [None / List]
+
+─────────────────────────────────────
+
+Save this documentation? (y/n): _
+```
+
+### Step 4: Save if Confirmed
+```javascript
+if (userConfirms) {
+  const docPath = `~/.prjct-cli/projects/{id}/analysis/feature-docs/${featureId}.md`
+  await saveDocumentation(docPath, documentation)
+  console.log('✅ Feature documentation saved!')
+} else {
+  console.log('ℹ️  Documentation discarded')
+}
+```
+
+## Example with Scribe
+
+```
+/p:ship "authentication system"
+
+🚀 authentication system shipped!
+
+📝 Scribe Agent is documenting your feature...
+
+─────────────────────────────────────────────
+
+## Feature: authentication system
+
+**Shipped**: 2025-10-02
+**Impact**: Users can now securely log in and manage sessions
+
+**Overview**:
+Implemented JWT-based authentication with login, registration, and password reset. Added middleware for protected routes and session management with automatic token refresh.
+
+**Technical Details**:
+- JWT authentication with bcrypt password hashing
+- Login/register/reset endpoints in auth.controller.ts
+- JWT middleware for route protection
+- Redis-based session management with 7-day expiry
+- Email verification workflow
+
+**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
+
+**Usage**:
+```javascript
+// Protected route example
+app.get('/api/profile', jwtMiddleware, profileController.get)
+```
+
+─────────────────────────────────────────────
+
+Save this documentation? (y/n): y
+
+✅ Feature documentation saved to analysis/feature-docs/!
+
+📈 This week: 3 | Total: 15
+Velocity: 2.1 features/day
+
+Keep the momentum!
+• "start next task" → Keep building
+• "see my progress" → View stats
+
+Or: /p:now | /p:recap
+```
+
+## Notes
+
+- Scribe agent uses git history to understand feature scope
+- Documentation is saved per-feature for release notes
+- User confirmation prevents unwanted documentation
+- Can skip documentation by saying "no"
+- Feature docs help with changelog generation and onboarding

package/templates/commands/sync.md

@@ -0,0 +1,220 @@
+---
+allowed-tools: [Read, Write, Bash, Glob, Grep, TodoWrite]
+description: "Sync project state and update AI agents based on latest analysis"
+---
+
+# /p:sync - Sync Project State
+
+## Purpose
+Re-analyze the project and update all AI agents with current project state, stack changes, and new requirements.
+
+## Global Architecture
+This command uses the global prjct architecture:
+- Data stored in: `~/.prjct-cli/projects/{id}/`
+- Config stored in: `{project}/.prjct/prjct.config.json`
+- Agents updated in: `~/.claude/agents/`
+
+## Usage
+```
+/p:sync
+```
+
+## When to Run
+- After major dependency changes
+- When adding new frameworks or tools
+- After significant architecture changes
+- When project type changes (e.g., adding mobile support)
+- Periodically to keep agents up-to-date
+
+## Execution Flow
+
+### 1. Re-run Project Analysis
+
+Execute `/p:analyze` to get current project state:
+```javascript
+// This will:
+// 1. Scan all files and directories
+// 2. Detect current stack and frameworks
+// 3. Check git status
+// 4. Compare with previous analysis
+// 5. Identify what changed
+```
+
+### 2. Detect Changes
+
+Compare new analysis with previous:
+```javascript
+const previousAnalysis = await readFile('.prjct/analysis/repo-summary.md')
+const currentAnalysis = await runAnalyze()
+
+const changes = {
+  newDependencies: [],
+  removedDependencies: [],
+  newFrameworks: [],
+  stackChanges: [],
+  structureChanges: []
+}
+
+// Detect what changed
+if (currentAnalysis.frameworks !== previousAnalysis.frameworks) {
+  changes.newFrameworks = difference(current, previous)
+}
+```
+
+### 3. Update Existing Agents
+
+Regenerate all current agents with new context:
+```javascript
+const agentGenerator = require('../core/agent-generator')
+
+// Update all existing agents
+const updated = await agentGenerator.updateExistingAgents(currentAnalysis)
+
+console.log(`↻ Updated ${updated.length} agents with new context`)
+```
+
+### 4. Add New Agents
+
+Generate any newly required agents:
+```javascript
+// Detect newly required agents
+const existingAgents = await listAgentFiles()
+const requiredAgents = detectRequiredAgents(currentAnalysis)
+const newAgents = requiredAgents.filter(a => !existingAgents.includes(a))
+
+if (newAgents.length > 0) {
+  for (const agentType of newAgents) {
+    await agentGenerator.generateAgent(agentType, currentAnalysis)
+    console.log(`✅ Added ${agentType} agent`)
+  }
+}
+```
+
+### 5. Remove Obsolete Agents (Optional)
+
+Ask user if agents should be removed:
+```javascript
+const obsoleteAgents = existingAgents.filter(a => !requiredAgents.includes(a))
+
+if (obsoleteAgents.length > 0) {
+  console.log(`\n⚠️  The following agents may no longer be needed:`)
+  obsoleteAgents.forEach(a => console.log(`   - ${a}`))
+
+  const shouldRemove = await confirmWithUser('\nRemove these agents? (y/n): ')
+
+  if (shouldRemove) {
+    await agentGenerator.cleanupObsoleteAgents(requiredAgents)
+  }
+}
+```
+
+### 6. Update Analysis File
+
+Save new analysis:
+```bash
+# Backup previous analysis
+cp .prjct/analysis/repo-summary.md .prjct/analysis/repo-summary.backup.md
+
+# Save new analysis
+# (already saved by /p:analyze)
+```
+
+### 7. Update Memory Log
+
+Log sync action:
+```jsonl
+{"timestamp":"2025-10-02T14:30:00Z","action":"sync","author":"Name","changes":{"addedAgents":["mobile"],"updatedAgents":["fe","be"],"removedAgents":[],"stackChanges":["added react-native"]}}
+```
+
+## Output Examples
+
+### No Changes
+```
+🔄 Syncing project state...
+
+📊 Analysis Complete
+   No significant changes detected
+
+🤖 Agents Status
+   ✓ All 7 agents are up-to-date
+
+✅ Sync complete! Everything is current.
+```
+
+### With Changes
+```
+🔄 Syncing project state...
+
+📊 Changes Detected
+   ✅ New dependency: @tanstack/react-query
+   ✅ New framework: Expo (React Native)
+   ℹ️  Architecture: Still feature-based
+
+🤖 Agent Updates
+   ↻ FE agent - Added React Query patterns
+   ↻ BE agent - Updated API integration context
+   ✅ Mobile agent - ADDED (React Native detected)
+   ✓ Other agents - No changes needed
+
+⚠️  Obsolete Agents
+   - devops (Docker removed from project)
+
+   Remove obsolete agents? (y/n): _
+
+✅ Sync complete!
+   - 2 agents updated
+   - 1 agent added
+   - 1 agent removed
+```
+
+### Stack Migration
+```
+🔄 Syncing project state...
+
+📊 Major Changes Detected
+   ⚠️  Framework changed: Vue → React
+   ⚠️  Build tool changed: Webpack → Vite
+   ✅ New: TypeScript added
+
+🤖 Full Agent Regeneration
+   ↻ PM - Updated with React patterns
+   ↻ UX - Updated component guidelines
+   ↻ FE - COMPLETELY REGENERATED for React + TS
+   ↻ BE - Updated API patterns
+   ↻ QA - Updated test framework context
+   ↻ Scribe - Updated documentation style
+
+✅ Sync complete! All agents updated for new stack.
+
+💡 Tip: Review agent descriptions to see new capabilities.
+```
+
+## Error Handling
+
+- **No .prjct/**: Error - Project not initialized, run `/p:init` first
+- **No analysis file**: Warning - Running first-time analysis
+- **Agent generation fails**: Warn but continue with others
+- **Permission issues**: Suggest checking `~/.claude/agents/` permissions
+
+## Notes
+
+- Sync is safe to run anytime
+- Existing agents are updated, not deleted (unless confirmed)
+- Git status is refreshed during sync
+- Analysis diff helps track project evolution
+- Agents get project-specific context from analysis
+
+## Related Commands
+
+- `/p:analyze` - Just analyze without updating agents
+- `/p:init` - Initialize project (first-time setup)
+- `/p:context` - View current project context
+
+## Implementation Notes
+
+The sync command should:
+1. Be idempotent (safe to run multiple times)
+2. Preserve manual agent customizations (warn if detected)
+3. Create backups before major changes
+4. Provide clear diff of what changed
+5. Allow granular control (which agents to update)