prjct-cli 0.13.2 → 0.15.0

package/templates/commands/ship.md

@@ -2,23 +2,32 @@
 allowed-tools: [Read, Write, Bash]
 description: 'Ship feature with automated workflow'
 timestamp-rule: 'GetTimestamp() and GetDate() for ALL timestamps'
-architecture: 'MD-first - MD files are source of truth'
+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
 
-## Architecture: MD-First
+## Architecture: Write-Through Pattern
 
-**Source of Truth**: `progress/shipped.md`, `planning/roadmap.md`
+```
+User Action → Storage (JSON) → Context (MD) → Sync Events
+```
 
-MD files are the source of truth. Write directly to MD files.
+**Source of Truth**: `storage/shipped.json`
+**Claude Context**: `context/shipped.md` (generated)
+**Backend Sync**: `sync/pending.json` (events)
 
 ## Context Variables
 - `{projectId}`: From `.prjct/prjct.config.json`
 - `{globalPath}`: `~/.prjct-cli/projects/{projectId}`
-- `{shippedPath}`: `{globalPath}/progress/shipped.md`
-- `{roadmapPath}`: `{globalPath}/planning/roadmap.md`
-- `{memoryPath}`: `{globalPath}/memory/context.jsonl`
+- `{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)
@@ -35,14 +44,6 @@ Track what happened after shipping:
 
 If no outcome provided, default to `monitoring`.
 
-Prompt (optional):
-```
-Ship outcome? (default: monitoring)
-1. validated - Confirmed working
-2. monitoring - Watching metrics
-3. known-issues - Has minor issues
-```
-
 ## Step 1: Read Config
 
 READ: `.prjct/prjct.config.json`
@@ -70,7 +71,6 @@ IF not a git repo:
 
 ### Lint Check
 BASH: `npm run lint 2>&1 || echo "LINT_SKIP"`
-
 CAPTURE output as {lintResult}
 
 IF contains "LINT_SKIP" OR contains "missing script":
@@ -82,7 +82,6 @@ ELSE:
 
 ### Test Check
 BASH: `npm test 2>&1 || echo "TEST_SKIP"`
-
 CAPTURE output as {testResult}
 
 IF contains "TEST_SKIP" OR contains "missing script":
@@ -96,118 +95,42 @@ ELSE:
 
 ## Step 4: Version Bump (MANDATORY)
 
-**CRITICAL**: Version bump is ALWAYS required. No exceptions.
-
-### Read Current Version (Language Agnostic)
-
-Detect project type and read version from appropriate file:
+### Read Current Version
+Detect project type and read version:
 
 | 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"` |
-| `go.mod` | Go | Use git tags |
 | `VERSION` | Any | Plain text `X.Y.Z` |
 
-BASH: Check which config exists:
-```bash
-ls package.json Cargo.toml pyproject.toml VERSION 2>/dev/null | head -1
-```
-
-READ appropriate file and EXTRACT: {currentVersion}
-
-IF no version file found:
-  CREATE: `VERSION` file with content `0.0.0`
-  {currentVersion} = "0.0.0"
-
 ### Determine Bump Type
-
 BASH: `git log --oneline -10`
 
-ANALYZE commit messages:
-
 IF any commit contains "BREAKING" OR "major:":
   {bumpType} = "major"
-  {newVersion} = increment X in X.Y.Z, set Y=0, Z=0
-
 ELSE IF any commit contains "feat:" OR "feature:":
   {bumpType} = "minor"
-  {newVersion} = increment Y in X.Y.Z, set Z=0
-
 ELSE:
   {bumpType} = "patch"
-  {newVersion} = increment Z in X.Y.Z
-
-### Update Version File (MANDATORY)
-
-Update the same file where version was read:
-- `package.json`: Update `"version"` field
-- `Cargo.toml`: Update `version` in `[package]`
-- `pyproject.toml`: Update `version` in `[project]`
-- `VERSION`: Replace entire content
 
-WRITE the updated file.
-
-**This step MUST complete. If it fails, STOP and report error.**
+### Update Version File
+Update the version file with {newVersion}
 
 ## Step 5: Update CHANGELOG (MANDATORY)
 
-**CRITICAL**: CHANGELOG.md MUST be created/updated. No exceptions.
-
-### Check if CHANGELOG exists
-
-BASH: `ls CHANGELOG.md 2>/dev/null || echo "NOT_FOUND"`
-
-IF "NOT_FOUND":
-  CREATE new CHANGELOG.md with header:
-  ```markdown
-  # Changelog
-
-  All notable changes to this project will be documented in this file.
-
-  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-  ```
-
-### Get Recent Commits for Changelog
-
+### Get Recent Commits
 BASH: `git log --oneline -20 --pretty=format:"- %s"`
 CAPTURE as {commitList}
 
-### Format New Entry
-
-```markdown
-## [{newVersion}] - {GetDate()}
-
-### {feature}
-
-#### Changes
-{commitList}
-
-#### Quality
-- Lint: {lintStatus}
-- Tests: {testStatus}
-
----
-
-```
-
-### Insert Entry
-
-READ: `CHANGELOG.md`
-INSERT new entry after "# Changelog" header (or after the preamble text)
-WRITE: `CHANGELOG.md`
-
-**This step MUST complete. CHANGELOG.md MUST exist in repo after ship.**
+### Create/Update CHANGELOG.md
+INSERT new entry after header.
 
 ## Step 6: Git Commit
 
-### Stage Changes
 BASH: `git add .`
 
-### Create Commit
 BASH: `git commit -m "$(cat <<'EOF'
 feat: Ship {feature} v{newVersion}
 
@@ -220,141 +143,116 @@ EOF
 
 BASH: `git push 2>&1`
 
-CAPTURE output as {pushResult}
-
 IF contains "rejected" OR contains "failed":
   OUTPUT: "⚠️ Push failed. Try: git pull --rebase && git push"
-  CONTINUE (don't stop)
+  CONTINUE
 
-IF contains "no upstream":
-  BASH: `git push -u origin HEAD`
-
-## Step 8: Update Shipped (MD)
+## Step 8: Update Storage (SOURCE OF TRUTH)
 
 SET: {now} = GetTimestamp()
-GENERATE: {shipId} = "ship_" + 8 random alphanumeric chars
-
-READ: `{shippedPath}` (or create default if not exists)
-
-Default structure:
-```markdown
-# Shipped
-
-## Recent
+GENERATE: {shipId} = UUID v4
 
-_Nothing shipped yet_
-
-## Archive
+### Read existing shipped
+READ: `{shippedStoragePath}` or create default:
+```json
+{
+  "shipped": [],
+  "lastUpdated": null
+}
+```
 
-_No archived ships_
+### Create ship object
+```json
+{
+  "id": "{shipId}",
+  "name": "{feature}",
+  "version": "{newVersion}",
+  "outcome": "{outcome}",
+  "shippedAt": "{now}",
+  "lint": "{lintStatus}",
+  "tests": "{testStatus}",
+  "commits": {commits}
+}
 ```
 
-### Get changes from git
-BASH: `git log --oneline -5`
-CAPTURE commit messages as {changes}
+### Update shipped.json
+PREPEND new ship to shipped array
+SET: lastUpdated = {now}
+WRITE: `{shippedStoragePath}`
 
-### Update shipped.md
+## Step 9: Generate Context (FOR CLAUDE)
 
-Parse existing content and add new ship under "## Recent" section:
+WRITE: `{shippedContextPath}`
 
 ```markdown
-# Shipped
-
-## Recent
+# SHIPPED 🚀
 
-### {feature} (v{newVersion})
-- **ID**: {shipId}
-- **Shipped**: {now}
-- **Outcome**: {outcome}
-- **Lint**: {lintStatus}
-- **Tests**: {testStatus}
-- **Changes**:
-  {changes as bullet list}
+## {Month Year}
 
-{...existing recent ships}
+{FOR EACH ship in shipped WHERE month matches:}
+- **{ship.name}** v{ship.version} - {ship.shippedAt}
+{END FOR}
 
-## Archive
+---
 
-{...existing archive}
+**Total shipped:** {shipped.length}
 ```
 
-WRITE: `{shippedPath}`
-
-## Step 9: Update Roadmap Status (MD)
-
-READ: `{roadmapPath}`
-
-### Find matching feature and update status
-Look for feature entry matching {feature}:
-- Change status from `pending` or `active` to `shipped`
-- Add `Shipped: {now}` line
-- Add `Version: {newVersion}` line
-
-WRITE: `{roadmapPath}`
+## Step 10: Queue Sync Event (FOR BACKEND)
 
-## Step 10: Log to Memory
-
-APPEND to: `{memoryPath}`
-
-Single line (JSONL):
+READ: `{syncPath}` or create empty array
+APPEND event:
 ```json
-{"timestamp":"{now}","action":"feature_shipped","shipId":"{shipId}","feature":"{feature}","version":"{newVersion}","outcome":"{outcome}"}
+{
+  "type": "feature.shipped",
+  "path": ["shipped"],
+  "data": {
+    "shipId": "{shipId}",
+    "name": "{feature}",
+    "version": "{newVersion}",
+    "outcome": "{outcome}",
+    "shippedAt": "{now}"
+  },
+  "timestamp": "{now}",
+  "projectId": "{projectId}"
+}
 ```
+WRITE: `{syncPath}`
 
-## Step 11: Create Snapshot (Undo/Redo Support)
-
-This creates a snapshot for the undo/redo system.
+## Step 11: Log to Daily Session
 
-### Initialize Snapshot Directory
-BASH: `mkdir -p {snapshotDir}`
+GET: {date} = YYYY-MM-DD from {now}
+GET: {yearMonth} = YYYY-MM from {now}
+SET: {dailySessionPath} = `{globalPath}/progress/sessions/{yearMonth}/{date}.jsonl`
 
-### Check if Git Repo Exists
-BASH: `ls {snapshotDir}/.git 2>/dev/null || echo "INIT_NEEDED"`
+BASH: `mkdir -p {globalPath}/progress/sessions/{yearMonth}`
 
-IF output contains "INIT_NEEDED":
-  BASH: `cd {snapshotDir} && git init && git config user.email "prjct@local" && git config user.name "prjct-snapshots" && git commit --allow-empty -m "init: snapshot system"`
-
-### Copy Changed Files to Snapshot
-BASH: `git diff --name-only HEAD~1 2>/dev/null || git diff --name-only`
-CAPTURE as {changedFiles}
-
-For each file in {changedFiles}:
-  - Source: `{projectPath}/{file}`
-  - Destination: `{snapshotDir}/{file}`
-  - Create parent directories if needed
-  - Copy file content
-
-### Commit Snapshot
-BASH: `cd {snapshotDir} && git add -A && git commit -m "Ship: {feature} (v{newVersion})" 2>/dev/null || echo "NO_CHANGES"`
-
-### Get Snapshot Hash
-BASH: `cd {snapshotDir} && git rev-parse --short HEAD`
-CAPTURE as {snapshotHash}
-
-### Clear Redo Stack (new snapshot invalidates redo)
-WRITE: `{snapshotDir}/redo-stack.json`
-Content: `[]`
+APPEND to: `{dailySessionPath}`
+```json
+{"ts":"{now}","type":"feature_ship","name":"{feature}","version":"{newVersion}"}
+```
 
-### Log Snapshot
-APPEND to: `{snapshotDir}/manifest.jsonl`
+## Step 12: Log to Memory (AUDIT TRAIL)
 
-Single line (JSONL):
+APPEND to: `{memoryPath}`
 ```json
-{"type":"snapshot","hash":"{snapshotHash}","message":"Ship: {feature}","version":"{newVersion}","timestamp":"{GetTimestamp()}"}
+{"timestamp":"{now}","action":"feature_shipped","shipId":"{shipId}","feature":"{feature}","version":"{newVersion}","outcome":"{outcome}"}
 ```
 
-## Step 12: Run Deep Sync
+## Step 13: Update project.json
+
+SET: {projectJsonPath} = `{globalPath}/project.json`
 
-**CRITICAL**: After shipping, run a full sync to update ALL project data.
+READ: `{projectJsonPath}`
+UPDATE:
+- `"version"`: Set to `{newVersion}`
+- `"hasUncommittedChanges"`: Set to `false`
+- `"lastSync"`: Set to `{now}`
+WRITE: `{projectJsonPath}`
 
-Execute `/p:sync` logic:
-- Update `project.json` with new version, commit count
-- Update `CLAUDE.md` Quick Reference table
-- Sync `core/now.md` (clear completed task)
-- Sync `core/next.md` (remove shipped items)
-- Update all stats and metadata
+## Step 14: Run Deep Sync
 
-This ensures the dashboard reflects the latest state after shipping.
+Execute `/p:sync` logic to update all context files.
 
 ## Output
 
@@ -367,12 +265,8 @@ Outcome: {outcome}
 Lint: {lintStatus}
 Tests: {testStatus}
 Commit: {commitHash}
-Snapshot: {snapshotHash}
 
 🔄 Synced project data
-├── Files: {fileCount}
-├── Commits: {commitCount}
-└── All MD files updated
 
 Next:
 • /p:undo - Revert this ship if needed
@@ -389,18 +283,11 @@ Next:
 | Lint fails | Show warning | CONTINUE |
 | Tests fail | Show warning | CONTINUE |
 | Push fails | Show fix command | CONTINUE |
-| No version file | CREATE `VERSION` file | CONTINUE |
 | Version bump fails | "Failed to update version" | STOP |
-| CHANGELOG fails | "Failed to update changelog" | STOP |
-
-**MANDATORY outputs (never skip):**
-- Version file updated (package.json, Cargo.toml, pyproject.toml, or VERSION)
-- `CHANGELOG.md` with new entry
-- Git commit with version in message
 
 ## Examples
 
-### Example 1: Full Success (validated)
+### Example 1: Full Success
 ```
 🚀 Shipped: user authentication
 
@@ -410,10 +297,10 @@ Lint: passed
 Tests: passed
 Commit: abc1234
 
-Next: /p:feature | /p:recap | compact
+Next: /p:feature | /p:recap
 ```
 
-### Example 2: With Warnings (monitoring)
+### Example 2: With Warnings
 ```
 🚀 Shipped: bug fixes
 
@@ -425,20 +312,5 @@ Commit: def5678
 
 ⚠️ Consider fixing lint warnings
 
-Next: /p:feature | /p:recap | compact
-```
-
-### Example 3: Known Issues
-```
-🚀 Shipped: performance updates
-
-Version: 1.2.0 → 1.2.1
-Outcome: known-issues
-Lint: passed
-Tests: passed
-Commit: ghi9012
-
-Note: Minor edge case in Safari, tracking issue #45
-
-Next: /p:feature | /p:recap | compact
+Next: /p:feature | /p:recap
 ```

package/templates/commands/spec.md

@@ -3,19 +3,36 @@ allowed-tools: [Read, Write, Glob, GetTimestamp, GetDate]
 description: 'Spec-driven development for complex features'
 timestamp-rule: 'GetTimestamp() and GetDate() for ALL timestamps'
 think-triggers: [explore_to_edit, complex_analysis]
+architecture: 'Write-Through (JSON → MD → Events)'
+storage-layer: true
+source-of-truth: 'storage/specs.json'
+claude-context: 'context/specs/'
 ---
 
-# /p:spec
+# /p:spec - Spec-Driven Development
 
 Spec-Driven Development. Creates detailed specifications for complex features before implementation.
 
+## Architecture: Write-Through Pattern
+
+**Source of Truth**: `storage/specs.json`
+**Claude Context**: `context/specs/{slug}.md` (generated)
+
 ## Think First
+
 Before creating spec, analyze:
 1. Is this feature complex enough for a spec? (auth, payments, migrations = yes)
 2. What are the key architectural decisions to make?
 3. Are there multiple valid approaches? Document tradeoffs.
 4. What questions should I ask the user before proceeding?
 
+## Context Variables
+- `{projectId}`: From `.prjct/prjct.config.json`
+- `{globalPath}`: `~/.prjct-cli/projects/{projectId}`
+- `{specsStoragePath}`: `{globalPath}/storage/specs.json`
+- `{specsContextPath}`: `{globalPath}/context/specs/`
+- `{queuePath}`: `{globalPath}/storage/queue.json`
+
 ## Purpose
 
 For features that require:
@@ -38,9 +55,9 @@ For features that require:
 /p:spec "Dark Mode"
 1. Analyze: Context, patterns, dependencies
 2. Propose: Requirements + Design + Tasks
-3. Write: `planning/specs/{slug}.md`
+3. Write: `storage/specs.json` + generate `context/specs/{slug}.md`
 4. Ask: User approval
-5. On approve: Add tasks to queue, start first
+5. On approve: Add tasks to `storage/queue.json`, start first
 ```
 
 ## Spec Structure
@@ -73,6 +90,28 @@ For features that require:
 - {edge cases to consider}
 ```
 
+## Storage Format
+
+### storage/specs.json
+```json
+{
+  "specs": [
+    {
+      "id": "{specId}",
+      "name": "{feature}",
+      "slug": "{feature-slug}",
+      "status": "PENDING_APPROVAL",
+      "requirements": [...],
+      "design": {...},
+      "tasks": [...],
+      "createdAt": "{timestamp}",
+      "approvedAt": null
+    }
+  ],
+  "lastUpdated": "{timestamp}"
+}
+```
+
 ## Validation
 
 - Feature name required for creation
@@ -80,11 +119,6 @@ For features that require:
 - Each task should be 20-30 minutes
 - Check for existing spec with same name
 
-## Data
-
-Session: `{"ts":"{GetTimestamp()}","type":"spec_create","name":"{feature}","requirements":{n},"tasks":{n},"effort":"{Xh}"}`
-Spec file: `planning/specs/{feature-slug}.md`
-
 ## Response
 
 ### On creation:
@@ -126,3 +160,59 @@ Use /p:done when complete
 → Breaks into: toggle, state, styles, persist, test
 → Estimates ~3h total
 ```
+
+## Decision Logging (absorbed from /p:decision)
+
+Specs now capture architectural decisions inline. When making design choices:
+
+### Decision Format
+
+```
+/p:spec "API Design"
+
+[During spec creation, capture decisions:]
+
+Decision: Use REST instead of GraphQL
+Reasoning: Simpler for this use case, team familiarity
+Alternatives: GraphQL, gRPC
+```
+
+### Storage
+
+Decisions are stored in the spec itself:
+```json
+{
+  "id": "{specId}",
+  "name": "{feature}",
+  "decisions": [
+    {
+      "id": "{decisionId}",
+      "decision": "Use REST instead of GraphQL",
+      "reasoning": "Simpler for this use case",
+      "alternatives": ["GraphQL", "gRPC"],
+      "createdAt": "{timestamp}"
+    }
+  ]
+}
+```
+
+### Response (with decisions)
+```
+📝 Decision logged: Use REST instead of GraphQL
+
+ID: {decisionId}
+Reasoning: Simpler for this use case
+Alternatives: GraphQL, gRPC
+
+This creates institutional memory to avoid:
+- Repeating the same debates
+- Forgetting why something was done a certain way
+- Making inconsistent choices
+```
+
+## Natural Language Support
+
+- "p. spec" → Interactive spec creation
+- "p. spec dark mode" → Create spec for dark mode
+- "p. design spec auth" → Create spec for auth
+- "p. decision use postgres" → Log decision (now part of spec)

package/templates/commands/suggest.md

@@ -1,17 +1,37 @@
 ---
 allowed-tools: [Read]
 description: 'Context-aware suggestions based on project state and momentum'
+architecture: 'Write-Through (JSON → MD → Events)'
+storage-layer: true
+source-of-truth: 'storage/*.json'
 ---
 
-# /p:suggest
+# /p:suggest - Context-Aware Suggestions
+
+## Architecture: Write-Through Pattern
+
+Reads from **Storage (JSON)** as source of truth.
+
+**Source of Truth**:
+- `storage/state.json` - Current task
+- `storage/queue.json` - Task queue
+- `storage/shipped.json` - Shipped features
 
 ## Purpose
 
 Analyze project state and recommend next actions based on current task, queue, last ship time, velocity, and momentum patterns.
 
+## Context Variables
+- `{projectId}`: From `.prjct/prjct.config.json`
+- `{globalPath}`: `~/.prjct-cli/projects/{projectId}`
+- `{statePath}`: `{globalPath}/storage/state.json`
+- `{queuePath}`: `{globalPath}/storage/queue.json`
+- `{shippedPath}`: `{globalPath}/storage/shipped.json`
+- `{sessionsPath}`: `{globalPath}/progress/sessions`
+
 ## Flow
 
-1. **Read state files**: `core/now.md`, `core/next.md`, `progress/shipped.md`, `planning/roadmap.md`, sessions (last 7 days)
+1. **Read storage files**: `storage/state.json`, `storage/queue.json`, `storage/shipped.json`, sessions (last 7 days)
 2. **Calculate metrics**: Days since ship, active task duration, queue size, velocity (features/week), completion rate
 3. **Detect patterns**: Long-running task (>1 day), stale queue, high velocity, low activity, blocked
 4. **Generate recommendations**: Immediate action, urgency alerts, momentum tips, strategic suggestions