prjct-cli 0.18.1 → 0.19.0

package/templates/commands/ship.md

@@ -1,277 +1,98 @@
 ---
 allowed-tools: [Read, Write, Bash]
 description: 'Ship feature with automated workflow'
-timestamp-rule: 'GetTimestamp() and GetDate() for ALL timestamps'
-architecture: 'Write-Through (JSON → MD → Events)'
-storage-layer: true
-source-of-truth: 'storage/shipped.json'
-claude-context: 'context/shipped.md'
-backend-sync: 'sync/pending.json'
 ---
 
-# /p:ship - Ship Feature Workflow
+# /p:ship - Ship Feature
 
-## Architecture: Write-Through Pattern
+Ship completed work with quality checks, version bump, and git commit.
 
+## Usage
 ```
-User Action → Storage (JSON) → Context (MD) → Sync Events
+/p:ship [feature] [--blocking]
 ```
+- `feature`: Name of the feature being shipped (required)
+- `--blocking`: Abort if lint/tests fail
 
-**Source of Truth**: `storage/shipped.json`
-**Claude Context**: `context/shipped.md` (generated)
-**Backend Sync**: `sync/pending.json` (events)
+## Flow
 
-## Context Variables
-- `{projectId}`: From `.prjct/prjct.config.json`
-- `{globalPath}`: `~/.prjct-cli/projects/{projectId}`
-- `{shippedStoragePath}`: `{globalPath}/storage/shipped.json`
-- `{shippedContextPath}`: `{globalPath}/context/shipped.md`
-- `{syncPath}`: `{globalPath}/sync/pending.json`
-- `{memoryPath}`: `{globalPath}/memory/events.jsonl`
-- `{snapshotDir}`: `{globalPath}/snapshots`
-- `{feature}`: User-provided feature name
-- `{outcome}`: User-provided outcome status (optional)
+### Step 1: Validate
+READ: `.prjct/prjct.config.json` → extract `projectId`
+IF missing: "No prjct project. Run /p:init first." → STOP
 
-## Outcome Categories
-
-Track what happened after shipping:
-
-| Outcome | Meaning | Use When |
-|---------|---------|----------|
-| `validated` | Confirmed working in production | Feature verified by users/tests |
-| `monitoring` | Deployed, needs observation | Just shipped, watching metrics |
-| `known-issues` | Working with caveats | Minor issues known, acceptable |
-
-If no outcome provided, default to `monitoring`.
-
-## Step 1: Read Config
-
-READ: `.prjct/prjct.config.json`
-EXTRACT: `projectId`
-
-IF file not found:
-  OUTPUT: "No prjct project. Run /p:init first."
-  STOP
-
-## Step 2: Validate Prerequisites
+SET: `{globalPath}` = `~/.prjct-cli/projects/{projectId}`
 
 BASH: `git status --porcelain`
+IF empty: "No changes to ship." → STOP
 
-IF output empty (no changes):
-  OUTPUT: "⚠️ No changes to ship. Make some commits first."
-  STOP
-
-BASH: `git rev-parse --is-inside-work-tree`
-
-IF not a git repo:
-  OUTPUT: "⚠️ Not a git repository. Initialize git first."
-  STOP
-
-## Step 3: Quality Checks (Non-Blocking)
-
-### Lint Check
+### Step 2: Quality Checks (optional)
 BASH: `npm run lint 2>&1 || echo "LINT_SKIP"`
-CAPTURE output as {lintResult}
-
-IF contains "LINT_SKIP" OR contains "missing script":
-  {lintStatus} = "skipped"
-ELSE IF contains "error":
-  {lintStatus} = "warnings"
-ELSE:
-  {lintStatus} = "passed"
-
-### Test Check
 BASH: `npm test 2>&1 || echo "TEST_SKIP"`
-CAPTURE output as {testResult}
-
-IF contains "TEST_SKIP" OR contains "missing script":
-  {testStatus} = "skipped"
-ELSE IF contains "failed" OR contains "FAIL":
-  {testStatus} = "failed"
-ELSE:
-  {testStatus} = "passed"
-
-**Note**: These are NON-BLOCKING. Continue even if they fail.
 
-## Step 4: Version Bump (MANDATORY)
-
-### Read Current Version
-Detect project type and read version:
+IF `--blocking` AND (lint failed OR tests failed):
+  OUTPUT: "Quality checks failed. Ship blocked."
+  STOP
 
-| File | Language | Version Location |
-|------|----------|------------------|
-| `package.json` | Node.js | `"version": "X.Y.Z"` |
-| `Cargo.toml` | Rust | `version = "X.Y.Z"` |
-| `pyproject.toml` | Python | `version = "X.Y.Z"` |
-| `VERSION` | Any | Plain text `X.Y.Z` |
+### Step 3: Version Bump
+READ: `package.json` (or Cargo.toml, pyproject.toml)
+EXTRACT: current version
 
-### Determine Bump Type
 BASH: `git log --oneline -10`
+Determine bump type:
+- "BREAKING" or "major:" → major
+- "feat:" or "feature:" → minor
+- else → patch
 
-IF any commit contains "BREAKING" OR "major:":
-  {bumpType} = "major"
-ELSE IF any commit contains "feat:" OR "feature:":
-  {bumpType} = "minor"
-ELSE:
-  {bumpType} = "patch"
+UPDATE version file with new version
 
-### Update Version File
-Update the version file with {newVersion}
-
-## Step 5: Update CHANGELOG (MANDATORY)
-
-### Get Recent Commits
+### Step 4: Update CHANGELOG
 BASH: `git log --oneline -20 --pretty=format:"- %s"`
-CAPTURE as {commitList}
-
-### Create/Update CHANGELOG.md
-INSERT new entry after header.
-
-## Step 6: Git Commit
+INSERT new entry in CHANGELOG.md
 
+### Step 5: Git Commit & Push
 BASH: `git add .`
-
-BASH: `git commit -m "$(cat <<'EOF'
-feat: Ship {feature} v{newVersion}
+BASH: `git commit -m "feat: Ship {feature} v{newVersion}
 
 🤖 Generated with [p/](https://www.prjct.app/)
 Designed for [Claude](https://www.anthropic.com/claude)
-EOF
-)"`
+"`
+BASH: `git push`
 
-## Step 7: Git Push
+### Step 6: Update Storage
+GET timestamp: `bun -e "console.log(new Date().toISOString())" 2>/dev/null || node -e "console.log(new Date().toISOString())"`
+GET uuid: `bun -e "console.log(crypto.randomUUID())" 2>/dev/null || node -e "console.log(require('crypto').randomUUID())"`
 
-BASH: `git push 2>&1`
-
-IF contains "rejected" OR contains "failed":
-  OUTPUT: "⚠️ Push failed. Try: git pull --rebase && git push"
-  CONTINUE
-
-## Step 8: Update Storage (SOURCE OF TRUTH)
-
-SET: {now} = GetTimestamp()
-GENERATE: {shipId} = UUID v4
-
-### Read existing shipped
-READ: `{shippedStoragePath}` or create default:
+READ: `{globalPath}/storage/shipped.json` (or create default)
+PREPEND new ship object:
 ```json
 {
-  "shipped": [],
-  "lastUpdated": null
-}
-```
-
-### Create ship object
-```json
-{
-  "id": "{shipId}",
+  "id": "{uuid}",
   "name": "{feature}",
   "version": "{newVersion}",
-  "outcome": "{outcome}",
-  "shippedAt": "{now}",
+  "shippedAt": "{timestamp}",
   "lint": "{lintStatus}",
-  "tests": "{testStatus}",
-  "commits": {commits}
-}
-```
-
-### Update shipped.json
-PREPEND new ship to shipped array
-SET: lastUpdated = {now}
-WRITE: `{shippedStoragePath}`
-
-## Step 9: Generate Context (FOR CLAUDE)
-
-WRITE: `{shippedContextPath}`
-
-```markdown
-# SHIPPED 🚀
-
-## {Month Year}
-
-{FOR EACH ship in shipped WHERE month matches:}
-- **{ship.name}** v{ship.version} - {ship.shippedAt}
-{END FOR}
-
----
-
-**Total shipped:** {shipped.length}
-```
-
-## Step 10: Queue Sync Event (FOR BACKEND)
-
-READ: `{syncPath}` or create empty array
-APPEND event:
-```json
-{
-  "type": "feature.shipped",
-  "path": ["shipped"],
-  "data": {
-    "shipId": "{shipId}",
-    "name": "{feature}",
-    "version": "{newVersion}",
-    "outcome": "{outcome}",
-    "shippedAt": "{now}"
-  },
-  "timestamp": "{now}",
-  "projectId": "{projectId}"
+  "tests": "{testStatus}"
 }
 ```
-WRITE: `{syncPath}`
-
-## Step 11: Log to Daily Session
-
-GET: {date} = YYYY-MM-DD from {now}
-GET: {yearMonth} = YYYY-MM from {now}
-SET: {dailySessionPath} = `{globalPath}/progress/sessions/{yearMonth}/{date}.jsonl`
+WRITE: `{globalPath}/storage/shipped.json`
 
-BASH: `mkdir -p {globalPath}/progress/sessions/{yearMonth}`
+Generate context:
+WRITE: `{globalPath}/context/shipped.md`
 
-APPEND to: `{dailySessionPath}`
-```json
-{"ts":"{now}","type":"feature_ship","name":"{feature}","version":"{newVersion}"}
-```
+Queue sync event:
+APPEND to `{globalPath}/sync/pending.json`
 
-## Step 12: Log to Memory (AUDIT TRAIL)
+Log to memory:
+APPEND to `{globalPath}/memory/events.jsonl`
 
-APPEND to: `{memoryPath}`
-```json
-{"timestamp":"{now}","action":"feature_shipped","shipId":"{shipId}","feature":"{feature}","version":"{newVersion}","outcome":"{outcome}"}
-```
-
-## Step 13: Update project.json
-
-SET: {projectJsonPath} = `{globalPath}/project.json`
-
-READ: `{projectJsonPath}`
-UPDATE:
-- `"version"`: Set to `{newVersion}`
-- `"hasUncommittedChanges"`: Set to `false`
-- `"lastSync"`: Set to `{now}`
-WRITE: `{projectJsonPath}`
-
-## Step 14: Run Deep Sync
-
-Execute `/p:sync` logic to update all context files.
-
-## Output
-
-SUCCESS:
+### Step 7: Output
 ```
 🚀 Shipped: {feature}
 
-Version: {currentVersion} → {newVersion}
-Outcome: {outcome}
-Lint: {lintStatus}
-Tests: {testStatus}
-Commit: {commitHash}
-
-🔄 Synced project data
+Version: {oldVersion} → {newVersion}
+Lint: {lintStatus} | Tests: {testStatus}
 
-Next:
-• /p:undo - Revert this ship if needed
-• /p:feature - Plan next feature
-• /p:recap - See progress
+Next: /p:feature | /p:recap
 ```
 
 ## Error Handling
@@ -280,37 +101,10 @@ Next:
 |-------|----------|--------|
 | No git repo | "Not a git repository" | STOP |
 | No changes | "No changes to ship" | STOP |
-| Lint fails | Show warning | CONTINUE |
-| Tests fail | Show warning | CONTINUE |
-| Push fails | Show fix command | CONTINUE |
-| Version bump fails | "Failed to update version" | STOP |
-
-## Examples
-
-### Example 1: Full Success
-```
-🚀 Shipped: user authentication
-
-Version: 1.2.0 → 1.3.0
-Outcome: validated
-Lint: passed
-Tests: passed
-Commit: abc1234
+| Lint/test fails (blocking) | "Quality checks failed" | STOP |
+| Lint/test fails (non-blocking) | Show warning | CONTINUE |
+| Push fails | "Push failed. Try: git pull --rebase" | CONTINUE |
 
-Next: /p:feature | /p:recap
-```
-
-### Example 2: With Warnings
-```
-🚀 Shipped: bug fixes
-
-Version: 1.2.0 → 1.2.1
-Outcome: monitoring
-Lint: warnings (non-blocking)
-Tests: skipped
-Commit: def5678
-
-⚠️ Consider fixing lint warnings
-
-Next: /p:feature | /p:recap
-```
+## References
+- Architecture details: `~/.prjct-cli/docs/architecture.md`
+- Validation patterns: `~/.prjct-cli/docs/validation.md`

package/templates/commands/sync.md

@@ -374,12 +374,12 @@ WRITE: `{globalPath}/project.json`
 
 ## Step 7: Generate Claude Code Sub-Agents (AGENTIC)
 
-Generate sub-agents for Claude Code in the PROJECT's `.claude/agents/` directory.
+Generate sub-agents for Claude Code in the GLOBAL storage `{globalPath}/agents/` directory.
 
 ### 7.1 Create Directory
 
 ```bash
-mkdir -p {cwd}/.claude/agents
+mkdir -p {globalPath}/agents
 ```
 
 ### 7.2 Read Generation Instructions
@@ -398,17 +398,17 @@ These 3 agents are ALWAYS created for every prjct project:
 **prjct-workflow.md** - Handles: /p:now, /p:done, /p:next, /p:pause, /p:resume
 READ template: `templates/subagents/workflow/prjct-workflow.md`
 ADAPT with: projectId, projectPath
-WRITE to: `{cwd}/.claude/agents/prjct-workflow.md`
+WRITE to: `{globalPath}/agents/prjct-workflow.md`
 
 **prjct-planner.md** - Handles: /p:feature, /p:idea, /p:spec, /p:bug
 READ template: `templates/subagents/workflow/prjct-planner.md`
 ADAPT with: projectId, projectPath
-WRITE to: `{cwd}/.claude/agents/prjct-planner.md`
+WRITE to: `{globalPath}/agents/prjct-planner.md`
 
 **prjct-shipper.md** - Handles: /p:ship
 READ template: `templates/subagents/workflow/prjct-shipper.md`
 ADAPT with: projectId, projectPath, detected test/lint commands
-WRITE to: `{cwd}/.claude/agents/prjct-shipper.md`
+WRITE to: `{globalPath}/agents/prjct-shipper.md`
 
 ### 7.4 Generate Domain Agents (Based on Stack)
 
@@ -425,7 +425,7 @@ Analyze `{techStack}` from Step 3 and generate ONLY relevant domain agents:
 For EACH detected stack:
 1. READ template from `templates/subagents/domain/{name}.md`
 2. ADAPT description with detected frameworks (e.g., "React specialist" not just "frontend")
-3. WRITE to `{cwd}/.claude/agents/{name}.md`
+3. WRITE to `{globalPath}/agents/{name}.md`
 
 ### 7.5 Report Generated Agents
 
@@ -573,7 +573,7 @@ Next: /p:now to start a new task
 │   └── events.jsonl
 └── project.json             # Metadata
 
-{cwd}/.claude/agents/         # Claude Code Sub-Agents (PER PROJECT)
+# Sub-Agents are in {globalPath}/agents/ (NOT in project .claude/)
 ├── prjct-workflow.md        # /p:now, /p:done, /p:next
 ├── prjct-planner.md         # /p:feature, /p:idea, /p:spec
 ├── prjct-shipper.md         # /p:ship