prjct-cli 1.45.4 → 1.45.6

package/templates/architect/phases.md

@@ -0,0 +1,59 @@
+---
+name: architect-phases
+description: Determine which architecture phases are needed
+allowed-tools: [Read]
+---
+
+# Architecture Phase Selection
+
+Analyze the idea and context to determine which phases are needed.
+
+## Input
+- Idea: {{idea}}
+- Discovery results: {{discovery}}
+
+## Available Phases
+
+1. **discovery** - Problem definition, users, constraints
+2. **user-flows** - User journeys and interactions
+3. **domain-modeling** - Entities and relationships
+4. **api-design** - API contracts and endpoints
+5. **architecture** - System components and patterns
+6. **data-design** - Database schema and storage
+7. **tech-stack** - Technology choices
+8. **roadmap** - Implementation plan
+
+## Phase Selection Rules
+
+**Always include**:
+- discovery (foundation)
+- roadmap (execution plan)
+
+**Include if building**:
+- user-flows: Has UI/UX
+- domain-modeling: Has data entities
+- api-design: Has backend API
+- architecture: Complex system
+- data-design: Needs database
+- tech-stack: Greenfield project
+
+**Skip if**:
+- Simple script: Skip most phases
+- Frontend only: Skip api-design, data-design
+- CLI tool: Skip user-flows
+- Existing stack: Skip tech-stack
+
+## Output Format
+
+Return array of needed phases:
+```json
+{
+  "phases": ["discovery", "domain-modeling", "api-design", "roadmap"],
+  "reasoning": "Simple CRUD app needs data model and API"
+}
+```
+
+## Guidelines
+- Don't over-architect
+- Match complexity to project
+- MVP first, expand later

package/templates/baseline/anti-patterns/nextjs.json

@@ -0,0 +1,18 @@
+{
+  "items": [
+    {
+      "issue": "Raw <img> usage in Next.js components",
+      "suggestion": "Use next/image unless there is a documented exception for external constraints.",
+      "severity": "medium",
+      "framework": "Next.js",
+      "confidence": 0.86
+    },
+    {
+      "issue": "Client components without need",
+      "suggestion": "Avoid unnecessary use client directives and keep components server-first when possible.",
+      "severity": "medium",
+      "framework": "Next.js",
+      "confidence": 0.75
+    }
+  ]
+}

package/templates/baseline/anti-patterns/react.json

@@ -0,0 +1,18 @@
+{
+  "items": [
+    {
+      "issue": "State mutation in place",
+      "suggestion": "Use immutable updates and derive state from props/data flows where possible.",
+      "severity": "high",
+      "framework": "React",
+      "confidence": 0.82
+    },
+    {
+      "issue": "UI primitives bypassing design system",
+      "suggestion": "Use approved component abstractions before introducing raw HTML controls.",
+      "severity": "medium",
+      "framework": "React",
+      "confidence": 0.74
+    }
+  ]
+}

package/templates/baseline/anti-patterns/typescript.json

@@ -0,0 +1,18 @@
+{
+  "items": [
+    {
+      "issue": "Unbounded any type",
+      "suggestion": "Use explicit types or unknown with narrowing. Add inline justification for unavoidable any.",
+      "severity": "high",
+      "language": "TypeScript",
+      "confidence": 0.9
+    },
+    {
+      "issue": "Unscoped @ts-ignore",
+      "suggestion": "Prefer @ts-expect-error with rationale and follow-up cleanup ticket.",
+      "severity": "medium",
+      "language": "TypeScript",
+      "confidence": 0.85
+    }
+  ]
+}

package/templates/baseline/patterns/nextjs.json

@@ -0,0 +1,18 @@
+{
+  "items": [
+    {
+      "name": "Use framework primitives",
+      "description": "Prefer next/image, next/link, and native Next.js routing/data primitives over ad-hoc replacements.",
+      "severity": "high",
+      "framework": "Next.js",
+      "confidence": 0.9
+    },
+    {
+      "name": "Server-first rendering model",
+      "description": "Default to server components and move interactivity to focused client boundaries.",
+      "severity": "medium",
+      "framework": "Next.js",
+      "confidence": 0.78
+    }
+  ]
+}

package/templates/baseline/patterns/react.json

@@ -0,0 +1,18 @@
+{
+  "items": [
+    {
+      "name": "Composition over duplication",
+      "description": "Extract reusable components and hooks for repeated UI/business behaviors.",
+      "severity": "medium",
+      "framework": "React",
+      "confidence": 0.8
+    },
+    {
+      "name": "Design-system-first UI",
+      "description": "Prefer project UI components/tokens to keep behavior and styling consistent.",
+      "severity": "high",
+      "framework": "React",
+      "confidence": 0.84
+    }
+  ]
+}

package/templates/baseline/patterns/typescript.json

@@ -0,0 +1,18 @@
+{
+  "items": [
+    {
+      "name": "Prefer strict typing contracts",
+      "description": "Functions and component props should be explicitly typed; avoid implicit any boundaries.",
+      "severity": "high",
+      "language": "TypeScript",
+      "confidence": 0.88
+    },
+    {
+      "name": "Type-first API surfaces",
+      "description": "Exported modules should define reusable domain types for inputs and outputs.",
+      "severity": "medium",
+      "language": "TypeScript",
+      "confidence": 0.8
+    }
+  ]
+}

package/templates/checklists/architecture.md

@@ -0,0 +1,28 @@
+# Architecture Checklist
+
+> Applies to ANY system architecture
+
+## Design Principles
+- [ ] Clear separation of concerns
+- [ ] Loose coupling between components
+- [ ] High cohesion within modules
+- [ ] Single source of truth for data
+- [ ] Explicit dependencies (no hidden coupling)
+
+## Scalability
+- [ ] Stateless where possible
+- [ ] Horizontal scaling considered
+- [ ] Bottlenecks identified
+- [ ] Caching strategy defined
+
+## Resilience
+- [ ] Failure modes documented
+- [ ] Graceful degradation planned
+- [ ] Recovery procedures defined
+- [ ] Circuit breakers where needed
+
+## Maintainability
+- [ ] Clear boundaries between layers
+- [ ] Easy to test in isolation
+- [ ] Configuration externalized
+- [ ] Logging and observability built-in

package/templates/checklists/code-quality.md

@@ -0,0 +1,28 @@
+# Code Quality Checklist
+
+> Universal principles for ANY programming language
+
+## Universal Principles
+- [ ] Single Responsibility: Each unit does ONE thing well
+- [ ] DRY: No duplicated logic (extract shared code)
+- [ ] KISS: Simplest solution that works
+- [ ] Clear naming: Self-documenting identifiers
+- [ ] Consistent patterns: Match existing codebase style
+
+## Error Handling
+- [ ] All error paths handled gracefully
+- [ ] Meaningful error messages
+- [ ] No silent failures
+- [ ] Proper resource cleanup (files, connections, memory)
+
+## Edge Cases
+- [ ] Null/nil/None handling
+- [ ] Empty collections handled
+- [ ] Boundary conditions tested
+- [ ] Invalid input rejected early
+
+## Code Organization
+- [ ] Functions/methods are small and focused
+- [ ] Related code grouped together
+- [ ] Clear module/package boundaries
+- [ ] No circular dependencies

package/templates/checklists/data.md

@@ -0,0 +1,33 @@
+# Data Checklist
+
+> Applies to: SQL, NoSQL, GraphQL, File storage, Caching
+
+## Data Integrity
+- [ ] Schema/structure defined
+- [ ] Constraints enforced
+- [ ] Transactions used appropriately
+- [ ] Referential integrity maintained
+
+## Query Performance
+- [ ] Indexes on frequent queries
+- [ ] N+1 queries eliminated
+- [ ] Query complexity analyzed
+- [ ] Pagination for large datasets
+
+## Data Operations
+- [ ] Migrations versioned and reversible
+- [ ] Backup and restore tested
+- [ ] Data validation at boundary
+- [ ] Soft deletes considered (if applicable)
+
+## Caching
+- [ ] Cache invalidation strategy defined
+- [ ] TTL values appropriate
+- [ ] Cache warming considered
+- [ ] Cache hit/miss monitored
+
+## Data Privacy
+- [ ] PII identified and protected
+- [ ] Data anonymization where needed
+- [ ] Audit trail for sensitive data
+- [ ] Data deletion procedures defined

package/templates/checklists/documentation.md

@@ -0,0 +1,33 @@
+# Documentation Checklist
+
+> Applies to ALL projects
+
+## Essential Docs
+- [ ] README with quick start
+- [ ] Installation instructions
+- [ ] Configuration options documented
+- [ ] Common use cases shown
+
+## Code Documentation
+- [ ] Public APIs documented
+- [ ] Complex logic explained
+- [ ] Architecture decisions recorded (ADRs)
+- [ ] Diagrams for complex flows
+
+## Operational Docs
+- [ ] Deployment process documented
+- [ ] Troubleshooting guide
+- [ ] Runbooks for common issues
+- [ ] Changelog maintained
+
+## API Documentation
+- [ ] All endpoints documented
+- [ ] Request/response examples
+- [ ] Error codes explained
+- [ ] Authentication documented
+
+## Maintenance
+- [ ] Docs updated with code changes
+- [ ] Version-specific documentation
+- [ ] Broken links checked
+- [ ] Examples tested and working

package/templates/checklists/infrastructure.md

@@ -0,0 +1,33 @@
+# Infrastructure Checklist
+
+> Applies to: Cloud, On-prem, Hybrid, Edge
+
+## Deployment
+- [ ] Infrastructure as Code (Terraform, Pulumi, CloudFormation, etc.)
+- [ ] Reproducible environments
+- [ ] Rollback strategy defined
+- [ ] Blue-green or canary deployment option
+
+## Observability
+- [ ] Logging strategy defined
+- [ ] Metrics collection configured
+- [ ] Alerting thresholds set
+- [ ] Distributed tracing (if applicable)
+
+## Security
+- [ ] Secrets management (not in code)
+- [ ] Network segmentation
+- [ ] Least privilege access
+- [ ] Encryption at rest and in transit
+
+## Reliability
+- [ ] Backup strategy defined
+- [ ] Disaster recovery plan
+- [ ] Health checks configured
+- [ ] Auto-scaling rules (if applicable)
+
+## Cost Management
+- [ ] Resource sizing appropriate
+- [ ] Unused resources identified
+- [ ] Cost monitoring in place
+- [ ] Budget alerts configured

package/templates/checklists/performance.md

@@ -0,0 +1,33 @@
+# Performance Checklist
+
+> Applies to: Backend, Frontend, Mobile, Database
+
+## Analysis
+- [ ] Bottlenecks identified with profiling
+- [ ] Baseline metrics established
+- [ ] Performance budgets defined
+- [ ] Benchmarks before/after changes
+
+## Optimization Strategies
+- [ ] Algorithmic complexity reviewed (O(n) vs O(n²))
+- [ ] Appropriate data structures used
+- [ ] Caching implemented where beneficial
+- [ ] Lazy loading for expensive operations
+
+## Resource Management
+- [ ] Memory usage optimized
+- [ ] Connection pooling used
+- [ ] Batch operations where applicable
+- [ ] Async/parallel processing considered
+
+## Frontend Specific
+- [ ] Bundle size optimized
+- [ ] Images optimized
+- [ ] Critical rendering path optimized
+- [ ] Network requests minimized
+
+## Backend Specific
+- [ ] Database queries optimized
+- [ ] Response compression enabled
+- [ ] Proper indexing in place
+- [ ] Connection limits configured

package/templates/checklists/security.md

@@ -0,0 +1,33 @@
+# Security Checklist
+
+> ALWAYS ON - Applies to ALL applications
+
+## Input/Output
+- [ ] All user input validated and sanitized
+- [ ] Output encoded appropriately (prevent injection)
+- [ ] File uploads restricted and scanned
+- [ ] No sensitive data in logs or error messages
+
+## Authentication & Authorization
+- [ ] Strong authentication mechanism
+- [ ] Proper session management
+- [ ] Authorization checked at every access point
+- [ ] Principle of least privilege applied
+
+## Data Protection
+- [ ] Sensitive data encrypted at rest
+- [ ] Secure transmission (TLS/HTTPS)
+- [ ] PII handled according to regulations
+- [ ] Data retention policies followed
+
+## Dependencies
+- [ ] Dependencies from trusted sources
+- [ ] Known vulnerabilities checked
+- [ ] Minimal dependency surface
+- [ ] Regular security updates planned
+
+## API Security
+- [ ] Rate limiting implemented
+- [ ] Authentication required for sensitive endpoints
+- [ ] CORS properly configured
+- [ ] API keys/tokens secured

package/templates/checklists/testing.md

@@ -0,0 +1,33 @@
+# Testing Checklist
+
+> Applies to: Unit, Integration, E2E, Performance testing
+
+## Coverage Strategy
+- [ ] Critical paths have high coverage
+- [ ] Happy path tested
+- [ ] Error paths tested
+- [ ] Edge cases covered
+
+## Test Quality
+- [ ] Tests are deterministic (no flaky tests)
+- [ ] Tests are independent (no order dependency)
+- [ ] Tests are fast (optimize slow tests)
+- [ ] Tests are readable (clear intent)
+
+## Test Types
+- [ ] Unit tests for business logic
+- [ ] Integration tests for boundaries
+- [ ] E2E tests for critical flows
+- [ ] Performance tests for bottlenecks
+
+## Mocking Strategy
+- [ ] External services mocked
+- [ ] Database isolated or mocked
+- [ ] Time-dependent code controlled
+- [ ] Random values seeded
+
+## Test Maintenance
+- [ ] Tests updated with code changes
+- [ ] Dead tests removed
+- [ ] Test data managed properly
+- [ ] CI/CD integration working

package/templates/checklists/ux-ui.md

@@ -0,0 +1,37 @@
+# UX/UI Checklist
+
+> Applies to: Web, Mobile, CLI, Desktop, API DX
+
+## User Experience
+- [ ] Clear user journey/flow
+- [ ] Feedback for every action
+- [ ] Loading states shown
+- [ ] Error states handled gracefully
+- [ ] Success confirmation provided
+
+## Interface Design
+- [ ] Consistent visual language
+- [ ] Intuitive navigation
+- [ ] Responsive/adaptive layout (if applicable)
+- [ ] Touch targets adequate (mobile)
+- [ ] Keyboard navigation (web/desktop)
+
+## CLI Specific
+- [ ] Help text for all commands
+- [ ] Clear error messages with suggestions
+- [ ] Progress indicators for long operations
+- [ ] Consistent flag naming conventions
+- [ ] Exit codes meaningful
+
+## API DX (Developer Experience)
+- [ ] Intuitive endpoint/function naming
+- [ ] Consistent response format
+- [ ] Helpful error messages with codes
+- [ ] Good documentation with examples
+- [ ] Predictable behavior
+
+## Information Architecture
+- [ ] Content hierarchy clear
+- [ ] Important actions prominent
+- [ ] Related items grouped
+- [ ] Search/filter for large datasets

package/templates/codex/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: prjct
+description: Use when user mentions p., prjct, project management, task tracking, or workflow commands (sync, task, done, ship, pause, resume, next, bug, idea, dash).
+---
+
+# prjct — Context layer for AI agents
+
+Grammar: `p. <command> [args]`
+
+Supported commands:
+`sync` `task` `done` `ship` `pause` `resume` `next` `bug` `idea` `dash`
+`init` `setup` `verify` `status` `review` `plan` `spec` `test` `workflow`
+`sessions` `analyze` `cleanup` `design` `serve` `linear` `jira` `git`
+`history` `update` `merge` `learnings` `skill` `auth` `prd` `impact` `enrich`
+
+Deterministic template resolution order for `p. <command>`:
+1. `require.resolve('prjct-cli/package.json')` -> `{pkgRoot}/templates/commands/{command}.md`
+2. `npm root -g` -> `{npmRoot}/prjct-cli/templates/commands/{command}.md`
+3. Local fallback (dev mode) -> `{localPrjctCliRoot}/templates/commands/{command}.md`
+
+If command is not in supported list:
+- Return: `Unknown command: p. <command>`
+- Include valid commands and suggest `prjct setup`
+
+If command exists but template cannot be resolved:
+- Block and ask for repair:
+  - `prjct start`
+  - `prjct setup`
+- Do not continue with ad-hoc behavior.
+
+Rules:
+- Never commit to main/master directly
+- All commits include footer: `Generated with [p/](https://www.prjct.app/)`
+- All storage through `prjct` CLI (SQLite internally)
+- Start code tasks with `p. task` and follow Context Contract from CLI output
+- Context7 MCP is mandatory for framework/library API decisions

package/templates/commands/analyze.md

@@ -0,0 +1,11 @@
+---
+allowed-tools: [Bash]
+---
+
+# p. analyze $ARGUMENTS
+
+```bash
+prjct analyze $ARGUMENTS --md
+```
+
+Follow the instructions in the CLI output.

package/templates/commands/auth.md

@@ -0,0 +1,15 @@
+---
+allowed-tools: [Bash, AskUserQuestion]
+---
+
+# p. auth $ARGUMENTS
+
+Supports: `login`, `logout`, `status` (default: show status).
+
+```bash
+prjct auth $ARGUMENTS --md
+```
+
+Follow the instructions in the CLI output.
+
+For `login`: ASK for API key if needed.

package/templates/commands/bug.md

@@ -0,0 +1,28 @@
+---
+allowed-tools: [Bash, Task, AskUserQuestion]
+---
+
+# p. bug $ARGUMENTS
+
+## Step 1: Validate
+If $ARGUMENTS is empty, ASK the user for a bug description.
+
+## Step 2: Report and explore
+```bash
+prjct bug "$ARGUMENTS" --md
+```
+
+Search the codebase for affected files.
+
+## Step 3: Fix now or queue
+ASK: "Fix this bug now?" Fix now / Queue for later
+
+If fix now: create branch `bug/{slug}` and start working.
+If queue: done -- bug is tracked.
+
+## Presentation
+Format bug reports as:
+
+1. `**Bug reported**: {description}`
+2. Show affected files with `code formatting` for paths
+3. Present fix/queue options clearly

package/templates/commands/cleanup.md

@@ -0,0 +1,11 @@
+---
+allowed-tools: [Bash, Read, Edit]
+---
+
+# p. cleanup $ARGUMENTS
+
+```bash
+prjct cleanup $ARGUMENTS --md
+```
+
+Follow the instructions in the CLI output.

package/templates/commands/dash.md

@@ -0,0 +1,16 @@
+---
+allowed-tools: [Bash]
+---
+
+# p. dash $ARGUMENTS
+
+Supports views: `compact`, `week`, `month`, `roadmap` (default: full dashboard).
+
+```bash
+prjct dash ${ARGUMENTS || ""} --md
+```
+
+Follow the instructions in the CLI output.
+
+## Presentation
+Present dashboard data using the tables and sections from CLI markdown. Keep it scannable — the dashboard should be a quick status overview.

package/templates/commands/design.md

@@ -0,0 +1,11 @@
+---
+allowed-tools: [Bash, Read, Write]
+---
+
+# p. design $ARGUMENTS
+
+```bash
+prjct design $ARGUMENTS --md
+```
+
+Follow the instructions in the CLI output.

package/templates/commands/done.md

@@ -0,0 +1,33 @@
+---
+allowed-tools: [Bash, Read, AskUserQuestion]
+---
+
+# p. done
+
+## Step 1: Complete via CLI
+```bash
+prjct done --md
+```
+If CLI output is JSON with `options`, present the options to the user and execute the chosen command.
+
+## Step 2: Verify completion
+- Review files changed: `git diff --name-only HEAD`
+- Ensure work is complete and tested
+
+## Step 3: Handoff context
+Summarize what was done and what the next subtask needs to know.
+
+## Step 4: Follow CLI next steps → Ship
+After completing, you MUST ask:
+ASK: "Subtask done. Ready to ship or continue to next subtask?"
+- Ship now → execute `p. ship` workflow (load and follow `~/.claude/commands/p/ship.md`)
+- Next subtask → continue working
+- Pause → execute `p. pause`
+
+## Presentation
+Format your completion summary as:
+
+1. `**Subtask complete**: {what was done}`
+2. Brief summary of changes (2-3 lines max)
+3. If next subtask exists, preview what's next
+4. Show next commands as a table

package/templates/commands/enrich.md

@@ -0,0 +1,20 @@
+---
+allowed-tools: [Bash, Read, Task, AskUserQuestion]
+---
+
+# p. enrich $ARGUMENTS
+
+## Step 1: Validate
+If $ARGUMENTS is empty, ASK for an issue ID or description.
+
+## Step 2: Fetch and analyze
+```bash
+prjct enrich "$ARGUMENTS" --md
+```
+
+Search the codebase for similar implementations and affected files.
+
+## Step 3: Publish
+ASK: "Update description / Add as comment / Just show me"
+
+Follow the CLI instructions for publishing.