prjct-cli 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [0.40.0] - 2026-01-28
+
+### Feature: Enhanced Skill System
+
+Inspired by vercel-labs/skills, prjct-cli now supports remote skill installation, version tracking via lock file, and full ecosystem-standard SKILL.md subdirectory format across all skill directories.
+
+**New: Remote Skill Installation (`p. skill add`)**
+- Install skills from GitHub repos: `p. skill add owner/repo`
+- Install specific skill: `p. skill add owner/repo@skill-name`
+- Install from local directory: `p. skill add ./path`
+- Automatic source metadata injection (`_prjct` frontmatter block)
+
+**New: Skill Lock File**
+- Tracks installed skills at `~/.prjct-cli/skills/.skill-lock.json`
+- Records source URL, commit SHA, install timestamp
+- Enables update detection via `p. skill check`
+
+**New: Additional Subcommands**
+- `p. skill add <source>` — Install from GitHub or local path
+- `p. skill remove <name>` — Uninstall a skill
+- `p. skill init <name>` — Scaffold a new skill template
+- `p. skill check` — Detect available updates
+
+**Improved: Full SKILL.md Subdirectory Support**
+- All skill directories now support both `{name}.md` (flat) and `{name}/SKILL.md` (subdirectory) formats
+- Previously only provider dirs (`~/.claude/skills/`) checked subdirectories
+- Orchestrator executor now checks both patterns when loading agent skills
+
+**New Files:**
+- `core/services/skill-installer.ts` — Remote installation service
+- `core/services/skill-lock.ts` — Lock file management
+
+**Modified:**
+- `core/types/services.ts` — Extended `SkillMetadata` with `sourceUrl`, `sourceType`, `installedAt`, `sha`; added `'remote'` source type
+- `core/services/skill-service.ts` — Unified SKILL.md discovery in all dirs
+- `core/agentic/orchestrator-executor.ts` — Both path patterns for skill loading
+- `templates/commands/skill.md` — New subcommands documentation
+
 ## [0.39.0] - 2026-01-24
 
 ### Feature: Windsurf IDE Support (PRJ-66)

package/core/agentic/orchestrator-executor.ts

@@ -344,18 +344,35 @@ export class OrchestratorExecutor {
         // Skip if already loaded
         if (loadedSkillNames.has(skillName)) continue
 
-        const skillPath = path.join(skillsDir, `${skillName}.md`)
+        // Check both patterns: flat file and subdirectory (ecosystem standard)
+        const flatPath = path.join(skillsDir, `${skillName}.md`)
+        const subdirPath = path.join(skillsDir, skillName, 'SKILL.md')
+
+        let content: string | null = null
+        let resolvedPath = flatPath
+
+        // Prefer subdirectory format (ecosystem standard)
         try {
-          const content = await fs.readFile(skillPath, 'utf-8')
+          content = await fs.readFile(subdirPath, 'utf-8')
+          resolvedPath = subdirPath
+        } catch {
+          // Fall back to flat file
+          try {
+            content = await fs.readFile(flatPath, 'utf-8')
+            resolvedPath = flatPath
+          } catch {
+            // Skill not found - not an error, just skip
+            console.warn(`Skill not found: ${skillName}`)
+          }
+        }
+
+        if (content) {
           skills.push({
             name: skillName,
             content,
-            filePath: skillPath,
+            filePath: resolvedPath,
           })
           loadedSkillNames.add(skillName)
-        } catch {
-          // Skill not found - not an error, just skip
-          console.warn(`Skill not found: ${skillName}`)
         }
       }
     }

package/core/integrations/jira/cache.ts

@@ -0,0 +1,57 @@
+/**
+ * JIRA Cache Module
+ * 5-minute TTL cache for JIRA API responses to reduce API calls
+ */
+
+import { TTLCache } from '../../utils/cache'
+import type { Issue } from '../issue-tracker/types'
+
+// 5-minute TTL for JIRA API responses
+const JIRA_CACHE_TTL = 5 * 60 * 1000 // 300000ms
+
+/**
+ * Cache for individual issues (by key like "ENG-123" or ID)
+ * Key format: "issue:{key}" or "issue:{id}"
+ */
+export const issueCache = new TTLCache<Issue>({
+  ttl: JIRA_CACHE_TTL,
+  maxSize: 100,
+})
+
+/**
+ * Cache for assigned issues list
+ * Key format: "assigned:{userId}" or "assigned:me"
+ */
+export const assignedIssuesCache = new TTLCache<Issue[]>({
+  ttl: JIRA_CACHE_TTL,
+  maxSize: 10,
+})
+
+/**
+ * Cache for projects list
+ * Key format: "projects"
+ */
+export const projectsCache = new TTLCache<Array<{ id: string; name: string; key?: string }>>({
+  ttl: JIRA_CACHE_TTL,
+  maxSize: 5,
+})
+
+/**
+ * Clear all JIRA caches
+ */
+export function clearJiraCache(): void {
+  issueCache.clear()
+  assignedIssuesCache.clear()
+  projectsCache.clear()
+}
+
+/**
+ * Get cache statistics for debugging
+ */
+export function getJiraCacheStats() {
+  return {
+    issues: issueCache.stats(),
+    assignedIssues: assignedIssuesCache.stats(),
+    projects: projectsCache.stats(),
+  }
+}

package/core/integrations/jira/index.ts

@@ -1,25 +1,30 @@
 /**
  * JIRA Integration
  *
- * Provides JIRA issue tracking integration for prjct-cli.
+ * Provides JIRA issue tracking integration for prjct-cli using REST API.
  *
- * Two authentication modes:
- *
- * 1. API Token Mode (direct REST API):
+ * Authentication (API Token Mode):
  *    - JIRA_BASE_URL: Your JIRA instance URL (e.g., https://company.atlassian.net)
  *    - JIRA_EMAIL: Your Atlassian account email
  *    - JIRA_API_TOKEN: API token from https://id.atlassian.com/manage-profile/security/api-tokens
- *
- * 2. MCP Mode (for corporate SSO):
- *    - No environment variables needed
- *    - Requires Atlassian MCP server configured in ~/.claude/mcp.json
- *    - Authenticates via browser (OAuth 2.1, SSO compatible)
  */
 
-// REST API client (supports both API token and MCP modes)
+// REST API client
 export { JiraProvider, jiraProvider, type JiraAuthMode } from './client'
 
-// MCP adapter for generating Claude instructions
+// Service layer with caching (preferred API)
+export { JiraService, jiraService } from './service'
+
+// Cache utilities
+export {
+  issueCache,
+  assignedIssuesCache,
+  projectsCache,
+  clearJiraCache,
+  getJiraCacheStats,
+} from './cache'
+
+// MCP adapter (deprecated - will be removed)
 export {
   JiraMCPAdapter,
   jiraMCPAdapter,

package/core/integrations/jira/service.ts

@@ -0,0 +1,244 @@
+/**
+ * JIRA Service Layer
+ * Wraps JiraProvider with caching for improved performance.
+ * All operations are cached with 5-minute TTL.
+ */
+
+import { jiraProvider } from './client'
+import {
+  issueCache,
+  assignedIssuesCache,
+  projectsCache,
+  clearJiraCache,
+  getJiraCacheStats,
+} from './cache'
+import type {
+  Issue,
+  CreateIssueInput,
+  UpdateIssueInput,
+  FetchOptions,
+  JiraConfig,
+} from '../issue-tracker/types'
+
+export class JiraService {
+  private initialized = false
+  private userId: string | null = null
+
+  /**
+   * Check if service is ready
+   */
+  isReady(): boolean {
+    return this.initialized && jiraProvider.isConfigured()
+  }
+
+  /**
+   * Initialize the service with config
+   * Must be called before any operations
+   */
+  async initialize(config: JiraConfig): Promise<void> {
+    if (this.initialized) return
+
+    await jiraProvider.initialize(config)
+    this.initialized = true
+  }
+
+  /**
+   * Initialize from credentials directly
+   * Convenience method for simple setup
+   */
+  async initializeFromCredentials(
+    baseUrl: string,
+    email: string,
+    apiToken: string,
+    projectKey?: string
+  ): Promise<void> {
+    // Set env vars for the provider
+    process.env.JIRA_BASE_URL = baseUrl
+    process.env.JIRA_EMAIL = email
+    process.env.JIRA_API_TOKEN = apiToken
+
+    const config: JiraConfig = {
+      enabled: true,
+      provider: 'jira',
+      baseUrl,
+      projectKey,
+      syncOn: { task: true, done: true, ship: true },
+      enrichment: { enabled: true, updateProvider: true },
+    }
+    await this.initialize(config)
+  }
+
+  /**
+   * Get issues assigned to current user (cached)
+   */
+  async fetchAssignedIssues(options?: FetchOptions): Promise<Issue[]> {
+    this.ensureInitialized()
+
+    const cacheKey = `assigned:${this.userId || 'me'}`
+    const cached = assignedIssuesCache.get(cacheKey)
+    if (cached) {
+      return cached
+    }
+
+    const issues = await jiraProvider.fetchAssignedIssues(options)
+    assignedIssuesCache.set(cacheKey, issues)
+
+    // Also cache individual issues
+    for (const issue of issues) {
+      issueCache.set(`issue:${issue.id}`, issue)
+      issueCache.set(`issue:${issue.externalId}`, issue)
+    }
+
+    return issues
+  }
+
+  /**
+   * Get issues from a project (cached)
+   */
+  async fetchProjectIssues(projectKey: string, options?: FetchOptions): Promise<Issue[]> {
+    this.ensureInitialized()
+
+    const cacheKey = `project:${projectKey}`
+    const cached = assignedIssuesCache.get(cacheKey)
+    if (cached) {
+      return cached
+    }
+
+    const issues = await jiraProvider.fetchTeamIssues(projectKey, options)
+    assignedIssuesCache.set(cacheKey, issues)
+
+    // Also cache individual issues
+    for (const issue of issues) {
+      issueCache.set(`issue:${issue.id}`, issue)
+      issueCache.set(`issue:${issue.externalId}`, issue)
+    }
+
+    return issues
+  }
+
+  /**
+   * Get a single issue by key (like "ENG-123") or ID (cached)
+   */
+  async fetchIssue(id: string): Promise<Issue | null> {
+    this.ensureInitialized()
+
+    // Check cache first
+    const cacheKey = `issue:${id}`
+    const cached = issueCache.get(cacheKey)
+    if (cached) {
+      return cached
+    }
+
+    const issue = await jiraProvider.fetchIssue(id)
+    if (issue) {
+      // Cache by both ID and key
+      issueCache.set(`issue:${issue.id}`, issue)
+      issueCache.set(`issue:${issue.externalId}`, issue)
+    }
+
+    return issue
+  }
+
+  /**
+   * Create a new issue (invalidates assigned cache)
+   */
+  async createIssue(input: CreateIssueInput): Promise<Issue> {
+    this.ensureInitialized()
+
+    const issue = await jiraProvider.createIssue(input)
+
+    // Cache the new issue
+    issueCache.set(`issue:${issue.id}`, issue)
+    issueCache.set(`issue:${issue.externalId}`, issue)
+
+    // Invalidate assigned issues cache (new issue may be assigned)
+    assignedIssuesCache.clear()
+
+    return issue
+  }
+
+  /**
+   * Update an issue (invalidates cache for that issue)
+   */
+  async updateIssue(id: string, input: UpdateIssueInput): Promise<Issue> {
+    this.ensureInitialized()
+
+    const issue = await jiraProvider.updateIssue(id, input)
+
+    // Update cache
+    issueCache.set(`issue:${issue.id}`, issue)
+    issueCache.set(`issue:${issue.externalId}`, issue)
+
+    return issue
+  }
+
+  /**
+   * Mark issue as in progress (invalidates cache)
+   */
+  async markInProgress(id: string): Promise<void> {
+    this.ensureInitialized()
+
+    await jiraProvider.markInProgress(id)
+
+    // Invalidate caches
+    issueCache.delete(`issue:${id}`)
+    assignedIssuesCache.clear()
+  }
+
+  /**
+   * Mark issue as done (invalidates cache)
+   */
+  async markDone(id: string): Promise<void> {
+    this.ensureInitialized()
+
+    await jiraProvider.markDone(id)
+
+    // Invalidate caches
+    issueCache.delete(`issue:${id}`)
+    assignedIssuesCache.clear()
+  }
+
+  /**
+   * Get available projects (cached)
+   */
+  async getProjects(): Promise<Array<{ id: string; name: string; key?: string }>> {
+    this.ensureInitialized()
+
+    const cached = projectsCache.get('projects')
+    if (cached) {
+      return cached
+    }
+
+    const projects = await jiraProvider.getTeams()
+    projectsCache.set('projects', projects)
+    return projects
+  }
+
+  /**
+   * Clear all caches
+   */
+  clearCache(): void {
+    clearJiraCache()
+  }
+
+  /**
+   * Get cache statistics for debugging
+   */
+  getCacheStats() {
+    return getJiraCacheStats()
+  }
+
+  /**
+   * Ensure service is initialized
+   */
+  private ensureInitialized(): void {
+    if (!this.initialized) {
+      throw new Error(
+        'JIRA service not initialized. Call jiraService.initialize() first or run `p. jira setup`.'
+      )
+    }
+  }
+}
+
+// Singleton instance
+export const jiraService = new JiraService()

package/core/integrations/linear/cache.ts

@@ -0,0 +1,68 @@
+/**
+ * Linear Cache Module
+ * 5-minute TTL cache for Linear API responses to reduce API calls
+ */
+
+import { TTLCache } from '../../utils/cache'
+import type { Issue } from '../issue-tracker/types'
+
+// 5-minute TTL for Linear API responses
+const LINEAR_CACHE_TTL = 5 * 60 * 1000 // 300000ms
+
+/**
+ * Cache for individual issues (by ID or identifier)
+ * Key format: "issue:{id}" or "issue:{identifier}"
+ */
+export const issueCache = new TTLCache<Issue>({
+  ttl: LINEAR_CACHE_TTL,
+  maxSize: 100,
+})
+
+/**
+ * Cache for assigned issues list
+ * Key format: "assigned:{userId}" or "assigned:me"
+ */
+export const assignedIssuesCache = new TTLCache<Issue[]>({
+  ttl: LINEAR_CACHE_TTL,
+  maxSize: 10,
+})
+
+/**
+ * Cache for teams list
+ * Key format: "teams"
+ */
+export const teamsCache = new TTLCache<Array<{ id: string; name: string; key?: string }>>({
+  ttl: LINEAR_CACHE_TTL,
+  maxSize: 5,
+})
+
+/**
+ * Cache for projects list
+ * Key format: "projects"
+ */
+export const projectsCache = new TTLCache<Array<{ id: string; name: string }>>({
+  ttl: LINEAR_CACHE_TTL,
+  maxSize: 5,
+})
+
+/**
+ * Clear all Linear caches
+ */
+export function clearLinearCache(): void {
+  issueCache.clear()
+  assignedIssuesCache.clear()
+  teamsCache.clear()
+  projectsCache.clear()
+}
+
+/**
+ * Get cache statistics for debugging
+ */
+export function getLinearCacheStats() {
+  return {
+    issues: issueCache.stats(),
+    assignedIssues: assignedIssuesCache.stats(),
+    teams: teamsCache.stats(),
+    projects: projectsCache.stats(),
+  }
+}

package/core/integrations/linear/index.ts

@@ -1,6 +1,20 @@
 /**
  * Linear Integration
- * Issue tracker provider for Linear.
+ * Issue tracker provider for Linear using @linear/sdk
  */
 
+// Core provider
 export { LinearProvider, linearProvider } from './client'
+
+// Service layer with caching (preferred API)
+export { LinearService, linearService } from './service'
+
+// Cache utilities
+export {
+  issueCache,
+  assignedIssuesCache,
+  teamsCache,
+  projectsCache,
+  clearLinearCache,
+  getLinearCacheStats,
+} from './cache'