prjct-cli 0.57.0 → 0.58.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.58.0] - 2026-02-05
+
+### Features
+
+- complete Linear/JIRA workflow integration (#95)
+
+
 ## [0.57.0] - 2026-02-05
 
 ### Features

package/dist/bin/prjct.mjs

@@ -25841,7 +25841,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "prjct-cli",
-      version: "0.57.0",
+      version: "0.58.0",
       description: "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
       main: "core/index.ts",
       bin: {

package/package.json

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

package/templates/commands/done.md

@@ -114,18 +114,31 @@ WRITE `{globalPath}/storage/state.json`:
 }
 ```
 
-## Step 5: Sync Issue Tracker Status
+## Step 5: Sync Issue Tracker Status (REQUIRED - DO NOT SKIP)
+
+**⛔ This step is MANDATORY if there's a linked issue.**
+
+```bash
+# Get projectId
+PROJ_ID=$(cat .prjct/prjct.config.json | grep -o '"projectId"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d'"' -f4)
+```
 
 ```
 IF previousTask.linearId exists:
-  # Update Linear issue to Done
-  RUN: bun $PRJCT_CLI/core/cli/linear.ts --project {projectId} status "{linearId}" "done"
-  OUTPUT: "Linear: {linearId} → Done"
+  # Mark issue as Done in Linear (REQUIRED)
+  RUN: bun $PRJCT_CLI/core/cli/linear.ts --project $PROJ_ID done "{linearId}"
+
+  # Add completion comment with summary
+  RUN: bun $PRJCT_CLI/core/cli/linear.ts --project $PROJ_ID comment "{linearId}" "✅ Task completed. Ready for ship."
+
+  OUTPUT: "Linear: {linearId} → Done ✓"
 
 ELSE IF previousTask.externalId AND previousTask.externalProvider == "jira":
-  # Update JIRA issue to Done
-  RUN: bun $PRJCT_CLI/core/cli/jira.ts --project {projectId} status "{externalId}" "done"
-  OUTPUT: "JIRA: {externalId} → Done"
+  # Transition to Done in JIRA (REQUIRED)
+  RUN: bun $PRJCT_CLI/core/cli/jira.ts --project $PROJ_ID transition "{externalId}" "Done"
+  RUN: bun $PRJCT_CLI/core/cli/jira.ts --project $PROJ_ID comment "{externalId}" "✅ Task completed. Ready for ship."
+
+  OUTPUT: "JIRA: {externalId} → Done ✓"
 ```
 
 ## Step 6: Log Event

package/templates/commands/merge.md

@@ -132,12 +132,59 @@ git pull origin main
 
 ---
 
-### STEP 7: Update Linear (if applicable)
+### STEP 7: Update Issue Tracker (REQUIRED - DO NOT SKIP)
 
-IF `currentTask.linearId`:
+**⛔ This step is MANDATORY if there's a linked issue.**
+
+```
+READ: {globalPath}/storage/state.json
+GET: currentTask.linearId, currentTask.jiraId
+```
+
+**IF linearId exists:**
+```bash
+# Get projectId
+PROJ_ID=$(cat .prjct/prjct.config.json | grep -o '"projectId"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d'"' -f4)
+
+# Mark issue as Done in Linear (REQUIRED)
+bun $PRJCT_CLI/core/cli/linear.ts --project $PROJ_ID done "{linearId}"
+
+# Add completion comment
+bun $PRJCT_CLI/core/cli/linear.ts --project $PROJ_ID comment "{linearId}" "✅ PR #{prNumber} merged and released"
+
+OUTPUT: "Linear: {linearId} → Done ✓"
+```
+
+**IF jiraId exists:**
+```bash
+# Transition to Done in JIRA (REQUIRED)
+bun $PRJCT_CLI/core/cli/jira.ts --project $PROJ_ID transition "{jiraId}" "Done"
+bun $PRJCT_CLI/core/cli/jira.ts --project $PROJ_ID comment "{jiraId}" "✅ PR #{prNumber} merged and released"
+
+OUTPUT: "JIRA: {jiraId} → Done ✓"
 ```
-Update Linear issue status to "Done" or "Merged"
-Add comment: "PR #{prNumber} merged"
+
+**IF no issue tracker linked:**
+```
+OUTPUT: "No issue tracker linked."
+```
+
+---
+
+### STEP 8: Complete Task State
+
+```
+UPDATE: {globalPath}/storage/state.json
+
+SET: previousTask = currentTask
+SET: previousTask.status = "completed"
+SET: previousTask.completedAt = {timestamp}
+SET: currentTask = null
+```
+
+APPEND to `{globalPath}/memory/events.jsonl`:
+```json
+{"type":"task_completed","taskId":"{id}","linearId":"{linearId}","prNumber":"{prNumber}","timestamp":"{timestamp}"}
 ```
 
 ---

package/templates/commands/ship.md

@@ -10,17 +10,58 @@ allowed-tools: [Read, Write, Bash, AskUserQuestion]
 
 ---
 
-### STEP 1: Pre-flight Checks (BLOCKING)
+### STEP 0: Resolve Project Context
+
+```bash
+# Get projectId from local config
+cat .prjct/prjct.config.json 2>/dev/null | grep -o '"projectId"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d'"' -f4
+```
+
+Set `globalPath = ~/.prjct-cli/projects/{projectId}`
+
+READ: `{globalPath}/storage/state.json` to get current task info (linearId, description, etc.)
+
+---
+
+### STEP 1: Pre-flight Checks
 
 ```bash
 # 1a. Check current branch
 BRANCH=$(git branch --show-current)
 ```
 
-**⛔ IF branch is `main` or `master`:**
+**IF branch is `main` or `master`:**
+
+```bash
+# Check if there's a recent merge (within last commit)
+git log -1 --pretty=format:"%s" | head -1
 ```
-STOP. DO NOT PROCEED.
-Tell user: "Cannot ship from main branch. Create a feature branch first."
+
+**IF last commit is a merge/squash from a PR:**
+```
+# This is POST-MERGE state - user wants to finalize/release
+OUTPUT: "Detected: Already on main after merge."
+OUTPUT: "Checking for pending release..."
+
+# Check if version was already bumped by CI
+npm view prjct-cli version 2>/dev/null
+node -p "require('./package.json').version"
+
+IF npm version >= package.json version:
+  OUTPUT: "✅ Already released: v{version}"
+  OUTPUT: "npm: prjct-cli@{version}"
+  GOTO: STEP 8 (Update Issue Tracker)
+ELSE:
+  OUTPUT: "Triggering release workflow..."
+  # CI handles the release on push to main
+  OUTPUT: "Release will be handled by CI workflow."
+  GOTO: STEP 8 (Update Issue Tracker)
+```
+
+**IF no recent merge (user is trying to ship from main):**
+```
+⛔ STOP. DO NOT PROCEED.
+Tell user: "Cannot ship from main branch. Create a feature branch first: git checkout -b feature/your-feature"
 ABORT the ship command entirely.
 ```
 
@@ -37,11 +78,12 @@ ABORT the ship command entirely.
 ```
 
 ```bash
-# 1c. Check for changes
+# 1c. Check for changes (only if on feature branch)
 git status --porcelain
+git diff --stat HEAD~1..HEAD 2>/dev/null || git diff --stat
 ```
 
-**⛔ IF no changes:**
+**⛔ IF no changes AND on feature branch:**
 ```
 STOP. DO NOT PROCEED.
 Tell user: "No changes to ship."
@@ -50,7 +92,72 @@ ABORT the ship command entirely.
 
 ---
 
-### STEP 2: Show Plan and Get Approval (BLOCKING)
+### STEP 2: Gather Ship Documentation (MANDATORY)
+
+**⛔ This step is NON-NEGOTIABLE. Every ship MUST have documentation.**
+
+```
+AskUserQuestion:
+  question: "Describe what was implemented in this feature"
+  header: "Implementation"
+  options:
+    - label: "Provide description"
+      description: "Describe the implementation details"
+```
+
+SAVE the implementation description.
+
+```
+AskUserQuestion:
+  question: "What did you learn while implementing this?"
+  header: "Learnings"
+  options:
+    - label: "Add learnings"
+      description: "Patterns discovered, gotchas, insights"
+    - label: "No specific learnings"
+      description: "Skip this section"
+```
+
+SAVE the learnings (if any).
+
+---
+
+### STEP 3: Generate QA Test Plan (MANDATORY)
+
+**⛔ Every ship MUST include test steps. NO EXCEPTIONS.**
+
+Based on the changes, generate:
+
+```markdown
+## Test Plan
+
+### For QA Team
+1. [Specific step to test feature]
+2. [Expected behavior]
+3. [Edge cases to verify]
+
+### For End Users
+**What changed:** [User-facing description]
+**How to use:** [Steps to use the new feature]
+**Breaking changes:** [Any breaking changes, or "None"]
+```
+
+Show user the generated test plan and ask for approval:
+
+```
+AskUserQuestion:
+  question: "Is this test plan accurate?"
+  header: "Test Plan"
+  options:
+    - label: "Yes, looks good"
+      description: "Proceed with this test plan"
+    - label: "Modify test plan"
+      description: "Edit the test steps"
+```
+
+---
+
+### STEP 4: Show Ship Plan and Get Approval (BLOCKING)
 
 **⛔ DO NOT execute any commits/pushes until user explicitly approves.**
 
@@ -59,16 +166,21 @@ Show the user:
 ## Ship Plan
 
 Branch: {branch}
-Changes:
-{git diff --stat}
+Changes: {git diff --stat}
+
+Documentation:
+- Implementation: {summary}
+- Learnings: {summary or "None"}
+- Test Plan: {summary}
 
 Will do:
 1. Run tests (if configured)
 2. Bump version (patch/minor/major)
-3. Update CHANGELOG.md
+3. Update CHANGELOG.md with full documentation
 4. Commit with prjct footer
 5. Push branch
-6. Create PR to main
+6. Create PR to main with test plan
+7. Update Linear/JIRA status to "In Review"
 ```
 
 Then ask for confirmation:
@@ -99,11 +211,11 @@ STOP - Do not continue
 ```
 
 **If "Yes, ship it":**
-CONTINUE to Step 3
+CONTINUE to Step 5
 
 ---
 
-### STEP 3: Quality Checks
+### STEP 5: Quality Checks
 
 ```bash
 # Run tests if package.json has test script
@@ -112,12 +224,12 @@ npm test 2>/dev/null || bun test 2>/dev/null || echo "No tests configured"
 
 ```bash
 # Run lint if configured
-npm run lint 2>/dev/null || echo "No lint configured"
+npm run lint 2>/dev/null || npm run check 2>/dev/null || echo "No lint configured"
 ```
 
 ---
 
-### STEP 4: Version Bump (REQUIRED)
+### STEP 6: Version Bump (REQUIRED)
 
 Determine version bump type:
 - `fix:` commits → **patch** (0.0.X)
@@ -134,19 +246,34 @@ OLD_VERSION=$(node -p "require('./package.json').version")
 
 ---
 
-### STEP 5: Update CHANGELOG.md (REQUIRED)
+### STEP 7: Update CHANGELOG.md (REQUIRED - FULL DOCUMENTATION)
+
+Add entry at top of CHANGELOG.md with COMPLETE documentation:
 
-Add entry at top of CHANGELOG.md:
 ```markdown
 ## [X.X.X] - YYYY-MM-DD
 
-### {Fixed/Added/Changed}
-- {description of changes}
+### {Features/Bug Fixes/Changed}
+- **{Feature name}**: {description}
+
+### Implementation Details
+{implementation description from Step 2}
+
+### Learnings
+{learnings from Step 2, or omit if none}
+
+### Test Plan
+
+#### For QA
+{QA test steps from Step 3}
+
+#### For Users
+{User-facing changes from Step 3}
 ```
 
 ---
 
-### STEP 6: Commit (REQUIRED FORMAT)
+### STEP 8: Commit (REQUIRED FORMAT)
 
 ```bash
 git add .
@@ -155,6 +282,9 @@ git commit -m "$(cat <<'EOF'
 
 {body if needed}
 
+Implementation: {brief summary}
+Test: {how to test}
+
 Generated with [p/](https://www.prjct.app/)
 EOF
 )"
@@ -164,20 +294,32 @@ EOF
 
 ---
 
-### STEP 7: Push and Create PR (REQUIRED)
+### STEP 9: Push and Create PR (REQUIRED)
 
 ```bash
 git push -u origin {branch}
 gh pr create --title "{type}: {description}" --base main --body "$(cat <<'EOF'
 ## Summary
-{bullet points}
+{bullet points of what changed}
+
+## Implementation
+{implementation details from Step 2}
 
 ## Changes
-{what changed}
+{list of files/modules affected}
 
 ## Test Plan
-{how to verify}
 
+### For QA
+{QA test steps}
+
+### For Users
+{User-facing documentation}
+
+## Learnings
+{learnings, if any}
+
+---
 Generated with [p/](https://www.prjct.app/)
 EOF
 )"
@@ -185,11 +327,78 @@ EOF
 
 ---
 
-### STEP 8: Update Linear/Issue Tracker (if applicable)
+### STEP 10: Update Issue Tracker (REQUIRED - DO NOT SKIP)
+
+**⛔ This step is MANDATORY if there's a linked issue.**
+
+```
+READ: {globalPath}/storage/state.json
+GET: linearId or jiraId from currentTask
+```
+
+**IF linearId exists:**
+```bash
+# Get projectId
+PROJ_ID=$(cat .prjct/prjct.config.json | grep -o '"projectId"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d'"' -f4)
+
+# Add implementation comment to Linear issue
+bun $PRJCT_CLI/core/cli/linear.ts --project $PROJ_ID comment "{linearId}" "$(cat <<'EOF'
+## Implementation Complete
+
+**PR:** {pr_url}
+**Branch:** {branch}
+
+### What was implemented
+{implementation details}
+
+### How to test
+{test steps for QA}
+
+### For users
+{user-facing changes}
+
+### Learnings
+{learnings}
+EOF
+)"
+
+# Mark issue as Done (if PR was merged) or In Review (if PR is open)
+IF on main branch (post-merge):
+  bun $PRJCT_CLI/core/cli/linear.ts --project $PROJ_ID done "{linearId}"
+  OUTPUT: "Linear: {linearId} → Done ✓"
+ELSE:
+  # Issue stays In Progress, PR link added as comment
+  OUTPUT: "Linear: {linearId} - Comment added with PR link"
+```
+
+**IF jiraId exists:**
+```bash
+# Similar flow for JIRA
+bun $PRJCT_CLI/core/cli/jira.ts --project $PROJ_ID comment "{jiraId}" "PR: {pr_url}"
+bun $PRJCT_CLI/core/cli/jira.ts --project $PROJ_ID transition "{jiraId}" "In Review"
+OUTPUT: "JIRA: {jiraId} → In Review ✓"
+```
+
+**IF no issue tracker configured:**
+```
+OUTPUT: "No issue tracker linked. Consider using `p. linear setup` for better tracking."
+```
+
+---
+
+### STEP 11: Update Local State
 
-If task has `linearId`:
-- Update issue status to "In Review" or appropriate state
-- Add comment with PR link
+```
+UPDATE: {globalPath}/storage/state.json
+SET: currentTask.status = "shipped" (if PR merged) or "in_review" (if PR open)
+SET: currentTask.shippedAt = {timestamp}
+SET: currentTask.prUrl = {pr_url}
+```
+
+APPEND to `{globalPath}/memory/events.jsonl`:
+```json
+{"type":"task_shipped","taskId":"{id}","linearId":"{linearId}","prUrl":"{pr_url}","version":"{version}","timestamp":"{timestamp}"}
+```
 
 ---
 
@@ -201,10 +410,16 @@ If task has `linearId`:
 Version: {old} → {new}
 PR: {url}
 Branch: {branch}
+{linearId ? "Linear: {linearId} → In Review ✓" : ""}
+
+Documentation:
+- Implementation: ✓
+- Test Plan: ✓
+- Learnings: ✓
 
 Next:
 - Review PR → {url}
-- Merge when ready → `p. merge`
+- After merge → Issues auto-updated to Done
 ```
 
 ---
@@ -220,5 +435,8 @@ Common violations:
 - ❌ Skipping CHANGELOG update
 - ❌ Not waiting for user approval
 - ❌ Missing prjct footer in commit
+- ❌ **Skipping test plan documentation**
+- ❌ **Not updating Linear/JIRA status**
+- ❌ **Not adding implementation comments to issues**
 
 **These violations make prjct useless. Follow the workflow.**

package/templates/commands/task.md

@@ -96,11 +96,11 @@ IF integrations.linear.enabled:
     SET: task.description = issue.title
     SET: $ARGUMENTS = issue.title  # Use title for task
 
-    # Mark issue as In Progress in Linear
-    RUN: bun $PRJCT_CLI/core/cli/linear.ts --project {projectId} status "$ARGUMENTS" "in_progress"
+    # Mark issue as In Progress in Linear (REQUIRED - DO NOT SKIP)
+    RUN: bun $PRJCT_CLI/core/cli/linear.ts --project {projectId} start "{task.linearId}"
 
     OUTPUT: "Linked to Linear: {issue.identifier} - {issue.title}"
-    OUTPUT: "Linear: In Progress"
+    OUTPUT: "Linear: → In Progress ✓"
 
 ELSE IF integrations.jira.enabled:
   # JIRA issue detected