prjct-cli 0.15.1 → 0.18.0

package/templates/agentic/subagent-generation.md

@@ -0,0 +1,109 @@
+# Sub-Agent Generation
+
+Generate Claude Code sub-agents for this project based on detected stack.
+
+## Input Context
+
+You have access to:
+- `{analysis}` - repo-summary.md with detected technologies
+- `{projectPath}` - Path to project root
+- `{projectId}` - Project identifier
+
+## Output Location
+
+Write sub-agents to: `{projectPath}/.claude/agents/`
+
+## Sub-Agent Format (Claude Code)
+
+```markdown
+---
+name: agent-name
+description: When to use this agent. Include "Use PROACTIVELY" for auto-invocation.
+tools: Read, Write, Glob, Grep, Bash
+model: sonnet
+---
+
+Agent system prompt here...
+```
+
+## Generation Rules
+
+### 1. ALWAYS Generate Workflow Agents
+
+These are REQUIRED for every prjct project:
+
+#### prjct-workflow.md
+- Commands: /p:now, /p:done, /p:next, /p:pause, /p:resume
+- Tools: Read, Write, Glob
+- Purpose: Task lifecycle management
+
+#### prjct-planner.md
+- Commands: /p:feature, /p:idea, /p:spec, /p:bug
+- Tools: Read, Write, Glob, Grep
+- Purpose: Feature planning and breakdown
+
+#### prjct-shipper.md
+- Commands: /p:ship
+- Tools: Read, Write, Bash, Glob
+- Purpose: Git operations, testing, deployment
+
+### 2. Generate Domain Agents Based on Stack
+
+Analyze `{analysis}` and create ONLY relevant domain agents:
+
+| If Detected | Generate | Tools |
+|-------------|----------|-------|
+| React, Vue, Angular, Svelte, CSS, HTML | `frontend.md` | Read, Write, Glob, Grep |
+| Node.js, Express, Go, Python API, REST, GraphQL | `backend.md` | Read, Write, Bash, Glob, Grep |
+| PostgreSQL, MySQL, MongoDB, Redis, Prisma | `database.md` | Read, Write, Bash |
+| Docker, Kubernetes, CI/CD, GitHub Actions | `devops.md` | Read, Bash, Glob |
+| Jest, Pytest, Vitest, Testing Library | `testing.md` | Read, Write, Bash |
+
+### 3. Adapt to Project Context
+
+Each generated agent should include:
+- Project-specific paths from analysis
+- Detected frameworks and versions
+- Relevant patterns found in codebase
+
+## Execution Steps
+
+1. **Read Analysis**
+   ```
+   Read("{projectPath}/.prjct-cli/projects/{projectId}/analysis/repo-summary.md")
+   ```
+
+2. **Create Directory**
+   ```
+   Bash("mkdir -p {projectPath}/.claude/agents")
+   ```
+
+3. **Generate Workflow Agents** (always)
+   - Read template from `templates/subagents/workflow/prjct-workflow.md`
+   - Adapt with project context
+   - Write to `{projectPath}/.claude/agents/prjct-workflow.md`
+   - Repeat for prjct-planner.md and prjct-shipper.md
+
+4. **Generate Domain Agents** (based on analysis)
+   - For each detected technology stack:
+     - Read corresponding template from `templates/subagents/domain/`
+     - Adapt with project-specific details
+     - Write to `{projectPath}/.claude/agents/`
+
+5. **Report Generated Agents**
+   ```
+   Generated sub-agents in .claude/agents/:
+   - prjct-workflow.md (workflow)
+   - prjct-planner.md (workflow)
+   - prjct-shipper.md (workflow)
+   - frontend.md (detected: React)
+   - backend.md (detected: Node.js)
+   ```
+
+## Critical Rules
+
+- NEVER hardcode technology detection in TypeScript
+- ALWAYS read and analyze repo-summary.md
+- ADAPT templates to project context
+- Use Claude Code frontmatter format exactly
+- Include "Use PROACTIVELY" in descriptions for auto-invocation

package/templates/commands/auth.md

@@ -0,0 +1,234 @@
+---
+allowed-tools: [Read, Write, Bash]
+description: 'Manage Cloud Authentication'
+timestamp-rule: 'GetTimestamp() for all timestamps'
+---
+
+# /p:auth - Cloud Authentication
+
+Manage authentication for prjct cloud sync.
+
+## Subcommands
+
+| Command | Purpose |
+|---------|---------|
+| `/p:auth` | Show current auth status |
+| `/p:auth login` | Authenticate with prjct cloud |
+| `/p:auth logout` | Clear authentication |
+| `/p:auth status` | Detailed auth status |
+
+## Context Variables
+- `{authPath}`: `~/.prjct-cli/config/auth.json`
+- `{apiUrl}`: API base URL (default: https://api.prjct.app)
+- `{dashboardUrl}`: Web dashboard URL (https://app.prjct.app)
+
+---
+
+## /p:auth (default) - Show Status
+
+### Flow
+
+1. READ: `{authPath}`
+2. IF authenticated:
+   - Show email and API key prefix
+3. ELSE:
+   - Show "Not authenticated" message
+
+### Output (Authenticated)
+
+```
+☁️ Cloud Sync: Connected
+
+Email: {email}
+API Key: {apiKeyPrefix}...
+Last auth: {lastAuth}
+
+Sync enabled for all projects.
+```
+
+### Output (Not Authenticated)
+
+```
+☁️ Cloud Sync: Not connected
+
+Run `/p:auth login` to enable cloud sync.
+
+Benefits:
+- Sync progress across devices
+- Access from web dashboard
+- Backup your project data
+```
+
+---
+
+## /p:auth login - Authenticate
+
+### Flow
+
+1. **Check existing auth**
+   READ: `{authPath}`
+   IF already authenticated:
+     ASK: "You're already logged in as {email}. Re-authenticate? (y/n)"
+     IF no: STOP
+
+2. **Open dashboard**
+   OUTPUT: "Opening prjct dashboard to get your API key..."
+   OPEN browser: `{dashboardUrl}/settings/api-keys`
+
+3. **Wait for API key**
+   OUTPUT instructions:
+   ```
+   1. Log in to prjct.app (GitHub OAuth)
+   2. Go to Settings → API Keys
+   3. Click "Create New Key"
+   4. Copy the key (starts with prjct_)
+   5. Paste it below
+   ```
+
+4. **Get API key from user**
+   PROMPT: "Paste your API key: "
+   READ: `{apiKey}` from user input
+
+5. **Validate key**
+   - Check format starts with "prjct_"
+   - Test connection with GET /health
+   - Fetch user info with GET /auth/me
+
+   IF invalid:
+     OUTPUT: "Invalid API key. Please try again."
+     STOP
+
+6. **Save auth**
+   WRITE: `{authPath}`
+   ```json
+   {
+     "apiKey": "{apiKey}",
+     "apiUrl": "https://api.prjct.app",
+     "userId": "{userId}",
+     "email": "{email}",
+     "lastAuth": "{GetTimestamp()}"
+   }
+   ```
+
+### Output (Success)
+
+```
+✅ Authentication successful!
+
+Logged in as: {email}
+API Key: {apiKeyPrefix}...
+
+Cloud sync is now enabled. Your projects will sync automatically
+when you run /p:sync or /p:ship.
+```
+
+### Output (Failure)
+
+```
+❌ Authentication failed
+
+{error}
+
+Please check your API key and try again.
+Get a new key at: {dashboardUrl}/settings/api-keys
+```
+
+---
+
+## /p:auth logout - Clear Auth
+
+### Flow
+
+1. READ: `{authPath}`
+   IF not authenticated:
+     OUTPUT: "Not logged in. Nothing to do."
+     STOP
+
+2. ASK: "Are you sure you want to log out? (y/n)"
+   IF no: STOP
+
+3. DELETE or CLEAR: `{authPath}`
+
+### Output
+
+```
+✅ Logged out successfully
+
+Cloud sync is now disabled.
+Run `/p:auth login` to re-enable.
+```
+
+---
+
+## /p:auth status - Detailed Status
+
+### Flow
+
+1. READ: `{authPath}`
+2. IF authenticated:
+   - Test connection
+   - Show detailed status
+3. ELSE:
+   - Show not connected message
+
+### Output (Connected)
+
+```
+☁️ Cloud Authentication Status
+
+Connection:    ✓ Connected
+Email:         {email}
+User ID:       {userId}
+API Key:       {apiKeyPrefix}...
+API URL:       {apiUrl}
+Last Auth:     {lastAuth}
+
+API Status:    ✓ Reachable
+```
+
+### Output (Connection Error)
+
+```
+☁️ Cloud Authentication Status
+
+Connection:    ⚠️ Error
+Email:         {email}
+API Key:       {apiKeyPrefix}...
+API URL:       {apiUrl}
+
+Error: {connectionError}
+
+Try `/p:auth login` to re-authenticate.
+```
+
+---
+
+## Error Handling
+
+| Error | Response |
+|-------|----------|
+| Invalid key format | "API key must start with prjct_" |
+| Key rejected by API | "Invalid or expired API key" |
+| Network error | "Cannot connect to {apiUrl}. Check internet." |
+| Already logged in | Offer to re-authenticate |
+
+---
+
+## Auth File Structure
+
+Location: `~/.prjct-cli/config/auth.json`
+
+```json
+{
+  "apiKey": "prjct_live_xxxxxxxxxxxxxxxxxxxx",
+  "apiUrl": "https://api.prjct.app",
+  "userId": "uuid-from-server",
+  "email": "user@example.com",
+  "lastAuth": "2024-01-15T10:00:00.000Z"
+}
+```
+
+**Security Notes:**
+- API key is stored in plain text (like git credentials)
+- File permissions should be 600 (user read/write only)
+- Never commit this file to version control

package/templates/commands/sync.md

@@ -336,20 +336,67 @@ WRITE: `{globalPath}/project.json`
 
 ---
 
-## Step 7: Generate Agents (AGENTIC)
-
-Based on detected stack, generate specialized agents.
-
-For EACH specialist needed:
-```typescript
-const generator = new AgentGenerator('{projectId}')
-await generator.generateDynamicAgent('agent-name', {
-  role: 'specific role',
-  domain: 'domain',
-  expertise: 'technologies'
-})
+## Step 7: Generate Claude Code Sub-Agents (AGENTIC)
+
+Generate sub-agents for Claude Code in the PROJECT's `.claude/agents/` directory.
+
+### 7.1 Create Directory
+
+```bash
+mkdir -p {cwd}/.claude/agents
 ```
 
+### 7.2 Read Generation Instructions
+
+READ: `templates/agentic/subagent-generation.md`
+
+This template contains:
+- Which workflow agents to ALWAYS generate
+- Which domain agents to generate based on stack
+- Format and structure requirements
+
+### 7.3 Generate Workflow Agents (ALWAYS)
+
+These 3 agents are ALWAYS created for every prjct project:
+
+**prjct-workflow.md** - Handles: /p:now, /p:done, /p:next, /p:pause, /p:resume
+READ template: `templates/subagents/workflow/prjct-workflow.md`
+ADAPT with: projectId, projectPath
+WRITE to: `{cwd}/.claude/agents/prjct-workflow.md`
+
+**prjct-planner.md** - Handles: /p:feature, /p:idea, /p:spec, /p:bug
+READ template: `templates/subagents/workflow/prjct-planner.md`
+ADAPT with: projectId, projectPath
+WRITE to: `{cwd}/.claude/agents/prjct-planner.md`
+
+**prjct-shipper.md** - Handles: /p:ship
+READ template: `templates/subagents/workflow/prjct-shipper.md`
+ADAPT with: projectId, projectPath, detected test/lint commands
+WRITE to: `{cwd}/.claude/agents/prjct-shipper.md`
+
+### 7.4 Generate Domain Agents (Based on Stack)
+
+Analyze `{techStack}` from Step 3 and generate ONLY relevant domain agents:
+
+| If Detected | Generate | Template |
+|-------------|----------|----------|
+| React, Vue, Angular, Svelte, CSS | `frontend.md` | `templates/subagents/domain/frontend.md` |
+| Node.js, Express, Go, Python API | `backend.md` | `templates/subagents/domain/backend.md` |
+| PostgreSQL, MySQL, MongoDB, Prisma | `database.md` | `templates/subagents/domain/database.md` |
+| Docker, Kubernetes, GitHub Actions | `devops.md` | `templates/subagents/domain/devops.md` |
+| Jest, Pytest, Vitest, testing | `testing.md` | `templates/subagents/domain/testing.md` |
+
+For EACH detected stack:
+1. READ template from `templates/subagents/domain/{name}.md`
+2. ADAPT description with detected frameworks (e.g., "React specialist" not just "frontend")
+3. WRITE to `{cwd}/.claude/agents/{name}.md`
+
+### 7.5 Report Generated Agents
+
+Track which agents were generated for output:
+- `{workflowAgents}`: Always 3 (prjct-workflow, prjct-planner, prjct-shipper)
+- `{domainAgents}`: List of domain agents generated
+
 ---
 
 ## Step 8: Log to Memory
@@ -362,6 +409,52 @@ APPEND to: `{globalPath}/memory/events.jsonl`
 
 ---
 
+## Step 9: Backend Sync (Cloud)
+
+Sync with prjct API if authenticated.
+
+### 9.1 Check Authentication
+
+READ: `~/.prjct-cli/config/auth.json`
+
+IF no auth OR no apiKey:
+  SET: `{cloudSync}` = false
+  OUTPUT TIP: "💡 Run `prjct auth` to enable cloud sync"
+  CONTINUE to output (skip 9.2, 9.3)
+
+ELSE:
+  SET: `{cloudSync}` = true
+
+### 9.2 Push Pending Events
+
+READ: `{globalPath}/sync/pending.json`
+COUNT: `{pendingCount}` events
+
+IF pendingCount > 0:
+  CALL syncManager.push(projectId)
+
+  IF success:
+    SET: `{pushedCount}` = result.count
+    OUTPUT: "☁️ Pushed {pushedCount} events to cloud"
+  ELSE:
+    OUTPUT: "⚠️ Cloud sync failed: {error}. Events queued for retry."
+    SET: `{syncError}` = error
+ELSE:
+  SET: `{pushedCount}` = 0
+
+### 9.3 Pull Updates (if push succeeded)
+
+IF cloudSync AND no syncError:
+  CALL syncManager.pull(projectId)
+
+  IF success AND result.count > 0:
+    SET: `{pulledCount}` = result.count
+    OUTPUT: "📥 Pulled {pulledCount} updates from cloud"
+  ELSE:
+    SET: `{pulledCount}` = 0
+
+---
+
 ## Output
 
 ```
@@ -385,6 +478,19 @@ APPEND to: `{globalPath}/memory/events.jsonl`
 ├── context/shipped.md
 └── context/CLAUDE.md
 
+🤖 Claude Code Sub-Agents ({workflowAgents.length + domainAgents.length})
+├── Workflow: prjct-workflow, prjct-planner, prjct-shipper
+└── Domain: {domainAgents.join(', ') || 'none'}
+
+{IF cloudSync}
+☁️ Cloud Sync
+├── Pushed: {pushedCount} events
+├── Pulled: {pulledCount} updates
+└── Status: {syncError ? "⚠️ " + syncError : "✓ Synced"}
+{ELSE}
+💡 Cloud sync disabled. Run `prjct auth` to enable.
+{ENDIF}
+
 {IF hasUncommittedChanges}
 ⚠️  You have uncommitted changes
 
@@ -426,8 +532,18 @@ Next: /p:now to start a new task
 │   └── shipped.md           # Shipped
 ├── sync/                     # Backend Sync
 │   └── pending.json         # Events queue
-├── agents/                   # Specialists
+├── agents/                   # Specialists (legacy)
 ├── memory/                   # Audit Trail
 │   └── events.jsonl
 └── project.json             # Metadata
+
+{cwd}/.claude/agents/         # Claude Code Sub-Agents (PER PROJECT)
+├── prjct-workflow.md        # /p:now, /p:done, /p:next
+├── prjct-planner.md         # /p:feature, /p:idea, /p:spec
+├── prjct-shipper.md         # /p:ship
+├── frontend.md              # (if React/Vue/Angular detected)
+├── backend.md               # (if Node/Go/Python API detected)
+├── database.md              # (if DB detected)
+├── devops.md                # (if Docker/K8s detected)
+└── testing.md               # (if test framework detected)
 ```

package/templates/subagents/domain/backend.md

@@ -0,0 +1,105 @@
+---
+name: backend
+description: Backend specialist for Node.js, Go, Python, REST APIs, and GraphQL. Use PROACTIVELY when user works on APIs, servers, or backend logic.
+tools: Read, Write, Bash, Glob, Grep
+model: sonnet
+---
+
+You are a backend specialist agent for this project.
+
+## Your Expertise
+
+- **Runtimes**: Node.js, Bun, Deno, Go, Python, Rust
+- **Frameworks**: Express, Fastify, Hono, Gin, FastAPI, Axum
+- **APIs**: REST, GraphQL, gRPC, WebSockets
+- **Auth**: JWT, OAuth, Sessions, API Keys
+
+## Project Context
+
+When invoked, analyze the project's backend stack:
+1. Read `package.json`, `go.mod`, `requirements.txt`, or `Cargo.toml`
+2. Identify framework and patterns
+3. Check for existing API structure
+
+## Code Patterns
+
+### API Structure
+Follow project's existing patterns. Common patterns:
+
+**Express/Fastify:**
+```typescript
+// Route handler
+export async function getUser(req: Request, res: Response) {
+  const { id } = req.params
+  const user = await userService.findById(id)
+  res.json(user)
+}
+```
+
+**Go (Gin/Chi):**
+```go
+func GetUser(c *gin.Context) {
+    id := c.Param("id")
+    user, err := userService.FindByID(id)
+    if err != nil {
+        c.JSON(500, gin.H{"error": err.Error()})
+        return
+    }
+    c.JSON(200, user)
+}
+```
+
+### Error Handling
+- Use consistent error format
+- Include error codes
+- Log errors appropriately
+- Never expose internal details to clients
+
+### Validation
+- Validate all inputs
+- Use schema validation (Zod, Joi, etc.)
+- Return meaningful validation errors
+
+## Quality Guidelines
+
+1. **Security**: Validate inputs, sanitize outputs, use parameterized queries
+2. **Performance**: Use appropriate indexes, cache when needed
+3. **Reliability**: Handle errors gracefully, implement retries
+4. **Observability**: Log important events, add metrics
+
+## Common Tasks
+
+### Creating Endpoints
+1. Check existing route structure
+2. Follow RESTful conventions
+3. Add validation middleware
+4. Include error handling
+5. Add to route registry/index
+
+### Middleware
+1. Check existing middleware patterns
+2. Keep middleware focused (single responsibility)
+3. Order matters - auth before business logic
+
+### Services
+1. Keep business logic in services
+2. Services are testable units
+3. Inject dependencies
+
+## Output Format
+
+When creating/modifying backend code:
+```
+✅ {action}: {endpoint/service}
+
+Files: {count} | Routes: {affected routes}
+```
+
+## Critical Rules
+
+- NEVER expose sensitive data in responses
+- ALWAYS validate inputs
+- USE parameterized queries (prevent SQL injection)
+- FOLLOW existing error handling patterns
+- LOG errors but don't expose internals
+- CHECK for existing similar endpoints/services