prjct-cli 0.42.0 → 0.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prjct-cli",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
   "main": "core/index.ts",
   "bin": {

package/templates/_bases/tracker-base.md

@@ -9,6 +9,17 @@ description: 'Base template for issue tracker integrations'
 
 All issue tracker integrations (Linear, JIRA, GitHub Issues, Monday.com) inherit from this base.
 
+## CRITICAL - SDK vs MCP
+
+| Tracker | Method | Why |
+|---------|--------|-----|
+| **Linear** | **SDK ONLY** | Per-project credentials, 4x faster |
+| **JIRA** | **SDK ONLY** | Per-project credentials, 4x faster |
+| GitHub | MCP | Simple token auth |
+| Monday | MCP | OAuth only |
+
+**For Linear and JIRA**: NEVER use MCP tools (`mcp__linear__*`, `mcp__jira__*`). ALWAYS use the SDK CLI helper.
+
 ---
 
 ## Common Context Variables

package/templates/commands/done.md

@@ -26,20 +26,25 @@ WRITE `{globalPath}/storage/state.json`
 
 ## Sync Issue Tracker Status
 
-IF `currentTask.externalId` exists:
+IF `currentTask.linearId` exists:
 
 ```
-IF currentTask.externalProvider == "linear":
-  # Update Linear issue to Done
-  IMPORT: linearService from core/integrations/linear
-  CALL: linearService.markDone(currentTask.externalId)
-  OUTPUT: "Linear: {externalId} → Done"
-
-ELSE IF currentTask.externalProvider == "jira":
-  # Update JIRA issue to Done
-  IMPORT: jiraService from core/integrations/jira
-  CALL: jiraService.markDone(currentTask.externalId)
-  OUTPUT: "JIRA: {externalId} → Done"
+# Update Linear issue to Done using sync layer
+# This updates both Linear API and local issues.json cache
+
+IMPORT: linearSync from core/integrations/linear
+CALL: linearSync.pushStatus(projectId, currentTask.linearId, 'done')
+
+OUTPUT: "Linear: {linearId} → Done"
+```
+
+ELSE IF `currentTask.externalId` AND `currentTask.externalProvider == "jira"`:
+
+```
+# Update JIRA issue to Done
+IMPORT: jiraService from core/integrations/jira
+CALL: jiraService.markDone(currentTask.externalId)
+OUTPUT: "JIRA: {externalId} → Done"
 ```
 
 ---
@@ -49,7 +54,7 @@ ELSE IF currentTask.externalProvider == "jira":
 {task} ({duration})
 
 Files: {count} | Commits: {count}
-{externalId ? "{externalProvider}: {externalId} → Done" : ""}
+{linearId ? "Linear: {linearId} → Done" : ""}
 
 Next:
 - More work? → `p. task "description"`

package/templates/commands/sync.md

@@ -10,6 +10,22 @@ prjct sync
 
 CLI handles: git analysis, context generation, agents, skills.
 
+## Linear Sync (when enabled)
+
+```
+READ: .prjct/prjct.config.json → get projectId
+READ: {globalPath}/project.json → check integrations.linear.enabled
+
+IF integrations.linear.enabled:
+  # Sync Linear issues to local cache
+  RUN: bun core/cli/linear.ts --project {projectId} sync
+
+  # Result stored in {globalPath}/storage/issues.json
+  # Contains all assigned issues from Linear
+
+  OUTPUT: "Linear: {fetched} issues synced"
+```
+
 ## Cursor Router Regeneration
 
 If `.cursor/` exists but `.cursor/rules/prjct.mdc` is missing:
@@ -25,6 +41,7 @@ If `.cursor/` exists but `.cursor/rules/prjct.mdc` is missing:
 
 Ecosystem: {ecosystem}
 Agents: {count} generated
+Linear: {issueCount} issues synced (or "not enabled")
 Cursor: {regenerated/ready/not detected}
 
 Next:

package/templates/commands/task.md

@@ -17,20 +17,29 @@ READ: {globalPath}/project.json
 CHECK: integrations.linear OR integrations.jira
 
 IF integrations.linear.enabled:
-  # Linear issue detected
-  IMPORT: linearService from core/integrations/linear
-  CALL: linearService.fetchIssue("$ARGUMENTS")
+  # Linear issue detected - use LOCAL-FIRST approach
+  # Try local cache first (issues.json), then API if not found
+
+  RUN: bun core/cli/linear.ts --project {projectId} get-local "$ARGUMENTS"
+
+  IF issue found in local cache:
+    USE cached issue data (no API call needed)
+  ELSE:
+    # Fallback to API
+    IMPORT: linearSync from core/integrations/linear
+    CALL: linearSync.getIssue(projectId, "$ARGUMENTS")  # Fetches + caches
 
   IF issue found:
-    SET: task.externalId = issue.externalId
-    SET: task.externalProvider = "linear"
+    SET: task.linearId = issue.identifier     # "PRJ-123"
+    SET: task.linearUuid = issue.id           # Linear internal UUID
     SET: task.description = issue.title
     SET: $ARGUMENTS = issue.title  # Use title for task
 
-    # Mark issue as In Progress in Linear
-    CALL: linearService.markInProgress(issue.id)
+    # Mark issue as In Progress in Linear (pushes status change)
+    IMPORT: linearSync from core/integrations/linear
+    CALL: linearSync.pushStatus(projectId, issue.identifier, 'in_progress')
 
-    OUTPUT: "Linked to Linear: {issue.externalId} - {issue.title}"
+    OUTPUT: "Linked to Linear: {issue.identifier} - {issue.title}"
     OUTPUT: "Linear: In Progress"
 
 ELSE IF integrations.jira.enabled:
@@ -83,8 +92,8 @@ WRITE `{globalPath}/storage/state.json`:
     "subtasks": [...],
     "currentSubtaskIndex": 0,
     "parentDescription": "$ARGUMENTS",
-    "externalId": "{externalId or null}",
-    "externalProvider": "{linear|jira|null}"
+    "linearId": "{identifier or null}",      // "PRJ-123" - Linear identifier
+    "linearUuid": "{uuid or null}"           // Linear internal UUID
   }
 }
 ```
@@ -94,7 +103,7 @@ WRITE `{globalPath}/storage/state.json`:
 {type}: $ARGUMENTS
 
 Branch: {branch} | Subtasks: {count}
-{externalId ? "Linked: {externalProvider} {externalId}" : ""}
+{linearId ? "Linear: {linearId} → In Progress" : ""}
 
 Next: Work on subtask, then `p. done`
 ```

package/templates/global/CLAUDE.md

@@ -229,6 +229,64 @@ Next: [suggested action]
 
 ---
 
+## CLEAN TERMINAL UX (CRITICAL)
+
+**Tool calls MUST be user-friendly.** The terminal output represents prjct's quality.
+
+### Rules for Tool Calls
+
+1. **ALWAYS use clear descriptions** in Bash tool calls:
+   ```
+   GOOD: description: "Building project"
+   BAD:  description: "bun run build 2>&1 | tail -5"
+   ```
+
+2. **Hide implementation details** - Users don't need to see:
+   - Pipe chains (`| tail -5`, `| grep`, `2>&1`)
+   - Internal paths (`/Users/jj/.prjct-cli/...`)
+   - JSON parsing (`jq -r '.field'`)
+
+3. **Use action verbs** for descriptions:
+   - "Building project"
+   - "Running tests"
+   - "Checking git status"
+   - "Fetching Linear issues"
+
+4. **Group related operations** - Don't show 5 separate tool calls when 1 will do
+
+5. **Prefer prjct CLI over raw commands**:
+   ```
+   GOOD: bun core/cli/linear.ts list
+   BAD:  curl -X POST https://api.linear.app/graphql...
+   ```
+
+### Examples
+
+```
+# GOOD - Clean, understandable
+⏺ Bash: Building project
+  ✓ Build complete
+
+# BAD - Technical noise
+⏺ Bash(cd /Users/jj/Apps/prjct && bun run build 2>&1 | tail -5)
+  → core/infrastructure/editors-config.js
+  → core/utils/version.js
+```
+
+### When Reading Files
+
+- Don't announce every file read
+- Group related reads
+- Only mention files relevant to user's question
+
+### When Running Commands
+
+- Show WHAT you're doing, not HOW
+- Suppress stderr noise when possible
+- Return only meaningful output
+
+---
+
 ## LOADING DOMAIN AGENTS
 
 When working on tasks, load relevant agents from `{globalPath}/agents/`: