prjct-cli 0.42.0 → 0.44.1

package/templates/commands/ship.md

@@ -4,50 +4,195 @@ allowed-tools: [Read, Write, Bash, AskUserQuestion]
 
 # p. ship "$ARGUMENTS"
 
+## ⛔ MANDATORY WORKFLOW - DO NOT SKIP ANY STEP
+
+**CRITICAL: Execute steps IN ORDER. Each step MUST complete before proceeding.**
+
+---
+
+### STEP 1: Pre-flight Checks (BLOCKING)
+
+```bash
+# 1a. Check current branch
+BRANCH=$(git branch --show-current)
+```
+
+**⛔ IF branch is `main` or `master`:**
+```
+STOP. DO NOT PROCEED.
+Tell user: "Cannot ship from main branch. Create a feature branch first."
+ABORT the ship command entirely.
+```
+
 ```bash
-prjct context ship $ARGUMENTS
+# 1b. Check GitHub auth
+gh auth status
 ```
 
-IF `currentTask` active → Ask: "Complete and ship?" or "Cancel"
+**⛔ IF not authenticated:**
+```
+STOP. DO NOT PROCEED.
+Tell user: "GitHub CLI not authenticated. Run: gh auth login"
+ABORT the ship command entirely.
+```
 
 ```bash
-git status --porcelain  # No changes? STOP
-git diff --stat HEAD
+# 1c. Check for changes
+git status --porcelain
 ```
 
-Run lint/tests if configured
+**⛔ IF no changes:**
+```
+STOP. DO NOT PROCEED.
+Tell user: "No changes to ship."
+ABORT the ship command entirely.
+```
+
+---
 
-IF not trivial → Review for security issues, error handling
+### STEP 2: Show Plan and Get Approval (BLOCKING)
 
-Version bump (patch default, minor for feat:, major for BREAKING)
-Update CHANGELOG.md
+**⛔ DO NOT execute any commits/pushes until user explicitly approves.**
+
+Show the user:
+```
+## Ship Plan
+
+Branch: {branch}
+Changes:
+{git diff --stat}
+
+Will do:
+1. Run tests (if configured)
+2. Bump version (patch/minor/major)
+3. Update CHANGELOG.md
+4. Commit with prjct footer
+5. Push branch
+6. Create PR to main
+
+Proceed? (yes/no)
+```
+
+**⛔ WAIT for explicit "yes" or approval. Do not assume.**
+
+---
+
+### STEP 3: Quality Checks
 
 ```bash
-gh auth status  # Not auth? STOP
-git branch --show-current  # On main? STOP
+# Run tests if package.json has test script
+npm test 2>/dev/null || bun test 2>/dev/null || echo "No tests configured"
 ```
 
-Commit with footer:
+```bash
+# Run lint if configured
+npm run lint 2>/dev/null || echo "No lint configured"
 ```
-🤖 Generated with [p/](https://www.prjct.app/)
-Designed for [Claude](https://www.anthropic.com/claude)
+
+---
+
+### STEP 4: Version Bump (REQUIRED)
+
+Determine version bump type:
+- `fix:` commits → **patch** (0.0.X)
+- `feat:` commits → **minor** (0.X.0)
+- `BREAKING:` in commits → **major** (X.0.0)
+
+```bash
+# Read current version
+OLD_VERSION=$(node -p "require('./package.json').version")
+
+# Calculate new version and update package.json
+# Use npm version OR manual edit
 ```
 
+---
+
+### STEP 5: Update CHANGELOG.md (REQUIRED)
+
+Add entry at top of CHANGELOG.md:
+```markdown
+## [X.X.X] - YYYY-MM-DD
+
+### {Fixed/Added/Changed}
+- {description of changes}
+```
+
+---
+
+### STEP 6: Commit (REQUIRED FORMAT)
+
+```bash
+git add .
+git commit -m "$(cat <<'EOF'
+{type}: {description}
+
+{body if needed}
+
+Generated with [p/](https://www.prjct.app/)
+EOF
+)"
+```
+
+**⛔ The prjct footer MUST be included. No exceptions.**
+
+---
+
+### STEP 7: Push and Create PR (REQUIRED)
+
 ```bash
-git add . && git commit && git push -u origin {branch}
-gh pr create --title "feat: {feature}" --base main
+git push -u origin {branch}
+gh pr create --title "{type}: {description}" --base main --body "$(cat <<'EOF'
+## Summary
+{bullet points}
+
+## Changes
+{what changed}
+
+## Test Plan
+{how to verify}
+
+Generated with [p/](https://www.prjct.app/)
+EOF
+)"
 ```
 
-**Output**:
+---
+
+### STEP 8: Update Linear/Issue Tracker (if applicable)
+
+If task has `linearId`:
+- Update issue status to "In Review" or appropriate state
+- Add comment with PR link
+
+---
+
+## Output Format
+
 ```
 🚀 Shipped: {feature}
 
 Version: {old} → {new}
 PR: {url}
-CI: {status}
+Branch: {branch}
 
 Next:
-- CI failed? → Fix and push again
-- Merge ready? → `p. merge` or merge in GitHub
-- New task? → `p. task "description"`
+- Review PR → {url}
+- Merge when ready → `p. merge`
 ```
+
+---
+
+## ⛔ VIOLATIONS
+
+**If you skip ANY step, you are BREAKING the prjct workflow.**
+
+Common violations:
+- ❌ Committing directly to main
+- ❌ Pushing without creating PR
+- ❌ Skipping version bump
+- ❌ Skipping CHANGELOG update
+- ❌ Not waiting for user approval
+- ❌ Missing prjct footer in commit
+
+**These violations make prjct useless. Follow the workflow.**

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 $PRJCT_CLI/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

@@ -4,10 +4,62 @@ allowed-tools: [Read, Write, Bash, Task, Glob, Grep, AskUserQuestion]
 
 # p. task "$ARGUMENTS"
 
+## ⛔ MANDATORY PRE-FLIGHT CHECKS
+
+**Execute these checks BEFORE any task creation:**
+
+### Check 1: Validate Arguments
+
+```
+IF $ARGUMENTS is empty:
+  ASK: "What task do you want to start?"
+  WAIT for response
+  DO NOT proceed with empty task
+```
+
+### Check 2: Check for Active Task
+
+```
+READ: {globalPath}/storage/state.json
+
+IF currentTask exists AND currentTask.status == "active":
+  OUTPUT:
+  """
+  ⚠️ Active task detected: {currentTask.description}
+
+  Options:
+  1. Complete current task first → `p. done`
+  2. Pause current task → `p. pause`
+  3. Switch anyway (current task will be paused)
+  """
+
+  ASK: "What would you like to do?"
+  WAIT for explicit choice
+  DO NOT automatically switch tasks
+```
+
+### Check 3: Validate Git State
+
 ```bash
-prjct context task $ARGUMENTS
+git status --porcelain
 ```
 
+```
+IF uncommitted changes exist:
+  OUTPUT:
+  """
+  ⚠️ You have uncommitted changes:
+  {list of files}
+
+  Commit or stash them before starting a new task.
+  """
+
+  ASK: "Would you like to commit these changes first?"
+  WAIT for response
+```
+
+---
+
 ## Step 0: Detect Issue Tracker Reference
 
 IF `$ARGUMENTS` matches pattern `/^[A-Z]+-\d+$/` (e.g., PRJ-123, PROJ-456):
@@ -17,20 +69,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 $PRJCT_CLI/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:
@@ -58,14 +119,59 @@ ELSE:
 
 ## Main Flow
 
-IF `currentTask` active → Ask: complete, pause, or cancel?
+### Step A: Show Plan and Get Approval (BLOCKING)
 
+**⛔ DO NOT create branches or modify state without user approval.**
+
+```
+OUTPUT:
+"""
+## Task Plan
+
+Description: $ARGUMENTS
+Type: {classified type}
+Branch: {type}/{slug}
+
+Will do:
+1. Create feature branch from current branch
+2. Initialize task tracking in state.json
+3. Break down into subtasks
+4. {If Linear: Update issue status to In Progress}
+
+Proceed? (yes/no)
+"""
+
+WAIT for explicit "yes" or approval
+DO NOT assume
+```
+
+### Step B: Explore Codebase
+
+```
 USE Task(Explore) → find similar code, affected files
-READ `agents[].filePath` → get patterns
-Classify: feature|bug|improvement|refactor|chore
-Break into subtasks
+READ agents/*.md → get domain patterns
+```
 
-IF on main → `git checkout -b {type}/{slug}`
+### Step C: Classify Task
+
+Determine type: feature | bug | improvement | refactor | chore
+
+### Step D: Create Branch (if needed)
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+```
+
+```
+IF CURRENT_BRANCH == "main" OR CURRENT_BRANCH == "master":
+  OUTPUT: "Creating feature branch: {type}/{slug}"
+
+  git checkout -b {type}/{slug}
+
+  IF git command fails:
+    OUTPUT: "Failed to create branch. Check git status."
+    STOP
+```
 
 ```bash
 prjct work "$ARGUMENTS"
@@ -83,8 +189,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 +200,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/ANTIGRAVITY.md

@@ -79,12 +79,10 @@ node -e "console.log(require('crypto').randomUUID())"
 **Every commit made with prjct MUST include this footer:**
 
 ```
-🤖 Generated with [p/](https://www.prjct.app/)
-Powered by [Antigravity](https://gemini.google.com/app/antigravity)
-
+Generated with [p/](https://www.prjct.app/)
 ```
 
-**This is NON-NEGOTIABLE. The prjct signature (`🤖 Generated with [p/]`) must appear in ALL commits.**
+**This is NON-NEGOTIABLE. The prjct signature must appear in ALL commits.**
 
 ### 5. Storage Rules (CROSS-AGENT COMPATIBILITY)
 

package/templates/global/CLAUDE.md

@@ -5,7 +5,7 @@
 
 ## HOW TO USE PRJCT (Read This First)
 
-When user types `p. <command>`, load the template from `templates/commands/{command}.md` and execute it intelligently.
+When user types `p. <command>`, load the template from `templates/commands/{command}.md` and execute it.
 
 ```
 p. sync     → templates/commands/sync.md
@@ -14,39 +14,70 @@ p. done     → templates/commands/done.md
 p. ship X   → templates/commands/ship.md
 ```
 
-**Key Insight**: Templates are GUIDANCE, not scripts. Use your intelligence to adapt them to the situation.
-
 ---
 
-## CRITICAL RULES
+## ⛔ CRITICAL RULES - READ BEFORE EVERY COMMAND
+
+### 0. FOLLOW TEMPLATES STEP BY STEP (NON-NEGOTIABLE)
+
+**Templates are MANDATORY WORKFLOWS, not suggestions.**
+
+```
+⛔ BEFORE executing ANY p. command:
+1. READ the template file COMPLETELY
+2. FOLLOW each step IN ORDER
+3. DO NOT skip steps - even "obvious" ones
+4. DO NOT take shortcuts - even for "simple" tasks
+5. STOP at any ⛔ BLOCKING condition
+```
 
-### 0. PLAN BEFORE ACTION (NON-NEGOTIABLE)
+**WHY THIS MATTERS:**
+- Skipping steps breaks the prjct workflow for ALL users
+- "Intelligent adaptation" is NOT permission to skip steps
+- Every step exists for a reason
+- If you skip steps, prjct becomes useless
 
-**For ANY prjct task, you MUST create a plan and get user approval BEFORE executing.**
+### ⛔ BLOCKING CONDITIONS
 
+When a template says "STOP" or has a ⛔ symbol:
 ```
-EVERY prjct command (p. task, p. sync, p. ship, etc.):
-1. STOP - Do not execute anything yet
-2. ANALYZE - Read relevant files, understand scope
-3. PLAN - Write a clear plan with:
-   - What will be done
-   - Files that will be modified
-   - Potential risks
-4. ASK - Present plan to user and wait for explicit approval
-5. EXECUTE - Only after user says "yes", "approved", "go ahead", etc.
+1. HALT execution immediately
+2. TELL the user why you stopped
+3. DO NOT proceed until the condition is resolved
+4. DO NOT work around the blocker
 ```
 
-**NEVER:**
-- Execute code changes without showing a plan first
-- Assume approval - wait for explicit confirmation
-- Skip the plan step for "simple" tasks
+**Examples of blockers:**
+- `p. ship` on main branch → STOP, tell user to create branch
+- `gh auth status` fails → STOP, tell user to authenticate
+- No changes to commit → STOP, tell user nothing to ship
+
+### GIT WORKFLOW RULES (CRITICAL)
+
+**⛔ NEVER commit directly to main/master**
+- Always create a feature branch first
+- Always create a PR for review
+- Direct pushes to main are FORBIDDEN
 
-**ALWAYS:**
-- Show the plan in a clear, readable format
-- Wait for user response before proceeding
-- If user asks questions, answer them before executing
+**⛔ NEVER push without a PR**
+- All changes go through pull requests
+- No exceptions for "small fixes"
 
-This rule applies to ALL prjct operations. No exceptions.
+**⛔ NEVER skip version bump on ship**
+- Every ship requires version update
+- Every ship requires CHANGELOG entry
+
+### PLAN BEFORE DESTRUCTIVE ACTIONS
+
+For commands that modify git state (ship, merge, done):
+```
+1. Show the user what will happen
+2. List all changes/files affected
+3. WAIT for explicit approval ("yes", "proceed", "do it")
+4. Only then execute
+```
+
+**DO NOT assume approval. WAIT for it.**
 
 ---
 
@@ -79,12 +110,10 @@ bun -e "console.log(crypto.randomUUID())" 2>/dev/null || node -e "console.log(re
 **Every commit made with prjct MUST include this footer:**
 
 ```
-🤖 Generated with [p/](https://www.prjct.app/)
-Designed for [Claude](https://www.anthropic.com/claude)
-
+Generated with [p/](https://www.prjct.app/)
 ```
 
-**This is NON-NEGOTIABLE. The prjct signature (`🤖 Generated with [p/]`) must appear in ALL commits.**
+**This is NON-NEGOTIABLE. The prjct signature must appear in ALL commits.**
 
 ### 5. Storage Rules (CROSS-AGENT COMPATIBILITY)
 
@@ -229,6 +258,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 $PRJCT_CLI/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/`:

package/templates/global/CURSOR.mdc

@@ -99,9 +99,7 @@ node -e "console.log(require('crypto').randomUUID())"
 **Every commit made with prjct MUST include this footer:**
 
 ```
-🤖 Generated with [p/](https://www.prjct.app/)
-Built with [Cursor](https://www.cursor.com/)
-
+Generated with [p/](https://www.prjct.app/)
 ```
 
 **This is NON-NEGOTIABLE. The prjct signature must appear in ALL commits.**

package/templates/global/GEMINI.md

@@ -79,12 +79,10 @@ bun -e "console.log(crypto.randomUUID())" 2>/dev/null || node -e "console.log(re
 **Every commit made with prjct MUST include this footer:**
 
 ```
-🤖 Generated with [p/](https://www.prjct.app/)
-Designed for [Gemini](https://geminicli.com/)
-
+Generated with [p/](https://www.prjct.app/)
 ```
 
-**This is NON-NEGOTIABLE. The prjct signature (`🤖 Generated with [p/]`) must appear in ALL commits.**
+**This is NON-NEGOTIABLE. The prjct signature must appear in ALL commits.**
 
 ### 5. Storage Rules (CROSS-AGENT COMPATIBILITY)
 

package/templates/global/WINDSURF.md

@@ -99,9 +99,7 @@ node -e "console.log(require('crypto').randomUUID())"
 **Every commit made with prjct MUST include this footer:**
 
 ```
-🤖 Generated with [p/](https://www.prjct.app/)
-Built with [Windsurf](https://www.windsurf.com/)
-
+Generated with [p/](https://www.prjct.app/)
 ```
 
 **This is NON-NEGOTIABLE. The prjct signature must appear in ALL commits.**

package/templates/subagents/workflow/prjct-shipper.md

@@ -64,8 +64,7 @@ Fix issues and try again.
 
    {body if needed}
 
-   🤖 Generated with [p/](https://www.prjct.app/)
-   Designed for [Claude](https://www.anthropic.com/claude)
+   Generated with [p/](https://www.prjct.app/)
    ```
 3. Commit: `git commit -m "{message}"`
 4. Push: `git push origin {current-branch}`