prjct-cli 1.45.5 → 1.45.7

package/templates/design/flow.md

@@ -0,0 +1,94 @@
+---
+name: flow-design
+description: Design user/data flow
+allowed-tools: [Read, Glob, Grep]
+---
+
+# Flow Design
+
+Design the user or data flow for the given feature.
+
+## Input
+- Target: {{target}}
+- Requirements: {{requirements}}
+
+## Analysis Steps
+
+1. **Identify Actors**
+   - Who initiates the flow?
+   - What systems are involved?
+   - What are the touchpoints?
+
+2. **Map Steps**
+   - Start to end journey
+   - Decision points
+   - Error scenarios
+
+3. **Define States**
+   - Initial state
+   - Intermediate states
+   - Final state(s)
+
+4. **Plan Error Handling**
+   - What can go wrong?
+   - Recovery paths
+   - User feedback
+
+## Output Format
+
+```markdown
+# Flow: {target}
+
+## Overview
+Brief description of this flow.
+
+## Actors
+- **User**: Primary actor
+- **System**: Backend services
+- **External**: Third-party APIs
+
+## Flow Diagram
+```
+[Start] → [Step 1] → [Decision?]
+                         ↓ Yes
+                    [Step 2] → [End]
+                         ↓ No
+                    [Error] → [Recovery]
+```
+
+## Steps
+
+### 1. User Action
+- User does X
+- System validates Y
+- **Success**: Continue to step 2
+- **Error**: Show message, allow retry
+
+### 2. Processing
+- System processes data
+- Calls external API
+- Updates database
+
+### 3. Completion
+- Show success message
+- Update UI state
+- Log event
+
+## Error Scenarios
+| Error | Cause | Recovery |
+|-------|-------|----------|
+| Invalid input | Bad data | Show validation |
+| API timeout | Network | Retry with backoff |
+| Auth failed | Token expired | Redirect to login |
+
+## States
+- `idle`: Initial state
+- `loading`: Processing
+- `success`: Completed
+- `error`: Failed
+```
+
+## Guidelines
+- Cover happy path first
+- Document all error cases
+- Keep flows focused

package/templates/global/ANTIGRAVITY.md

@@ -0,0 +1,17 @@
+<!-- prjct:start - DO NOT REMOVE THIS MARKER -->
+# p/ — Context layer for AI agents
+
+Commands: `p. sync` `p. task` `p. done` `p. ship` `p. pause` `p. resume` `p. bug` `p. dash` `p. next`
+
+When user types a p command, execute the corresponding prjct CLI command with `--md` flag for context.
+
+Rules:
+- Never commit to main/master directly
+- All commits include footer: `Generated with [p/](https://www.prjct.app/)`
+- Path resolution: `.prjct/prjct.config.json` → `~/.prjct-cli/projects/{projectId}`
+- All storage through `prjct` CLI (SQLite internally)
+- For code tasks, always start with `p. task` and follow Context Contract from CLI output
+- Context7 MCP is mandatory for framework/library API decisions
+
+**Auto-managed by prjct-cli** | https://prjct.app
+<!-- prjct:end - DO NOT REMOVE THIS MARKER -->

package/templates/global/CLAUDE.md

@@ -0,0 +1,20 @@
+<!-- prjct:start - DO NOT REMOVE THIS MARKER -->
+# p/ — Context layer for AI agents
+
+Commands: `p. sync` `p. task` `p. done` `p. ship` `p. pause` `p. resume` `p. bug` `p. dash` `p. next`
+
+When user types `p. <command>`, READ the template from `~/.claude/commands/p/{command}.md` and execute step by step.
+
+Rules:
+- Never commit to main/master directly
+- All commits include footer: `Generated with [p/](https://www.prjct.app/)`
+- Path resolution: `.prjct/prjct.config.json` → `~/.prjct-cli/projects/{projectId}`
+- All storage through `prjct` CLI (SQLite internally)
+- For code tasks, always start with `p. task` and follow Context Contract from CLI output
+- Context7 MCP is mandatory for framework/library API decisions
+- Templates are MANDATORY workflows — follow every step
+- WORKFLOW IS MANDATORY: After completing work, ALWAYS run `p. ship`
+- NEVER end a session without shipping or pausing
+
+**Auto-managed by prjct-cli** | https://prjct.app
+<!-- prjct:end - DO NOT REMOVE THIS MARKER -->

package/templates/global/CURSOR.mdc

@@ -0,0 +1,20 @@
+---
+description: "prjct - Context layer for AI coding agents"
+alwaysApply: true
+---
+
+<!-- prjct:start - DO NOT REMOVE THIS MARKER -->
+# p/ — Context layer for AI agents
+
+Commands: `/sync` `/task` `/done` `/ship` `/pause` `/resume` `/bug` `/dash` `/next`
+
+When user triggers a command, execute the corresponding prjct CLI command with `--md` flag for context.
+
+Rules:
+- Never commit to main/master directly
+- All commits include footer: `Generated with [p/](https://www.prjct.app/)`
+- Path resolution: `.prjct/prjct.config.json` → `~/.prjct-cli/projects/{projectId}`
+- All storage through `prjct` CLI (SQLite internally)
+
+**Auto-managed by prjct-cli** | https://prjct.app
+<!-- prjct:end - DO NOT REMOVE THIS MARKER -->

package/templates/global/GEMINI.md

@@ -0,0 +1,17 @@
+<!-- prjct:start - DO NOT REMOVE THIS MARKER -->
+# p/ — Context layer for AI agents
+
+Commands: `p sync` `p task` `p done` `p ship` `p pause` `p resume` `p bug` `p dash` `p next`
+
+When user types a p command, execute the corresponding prjct CLI command with `--md` flag for context.
+
+Rules:
+- Never commit to main/master directly
+- All commits include footer: `Generated with [p/](https://www.prjct.app/)`
+- Path resolution: `.prjct/prjct.config.json` → `~/.prjct-cli/projects/{projectId}`
+- All storage through `prjct` CLI (SQLite internally)
+- For code tasks, always start with `p task` and follow Context Contract from CLI output
+- Context7 MCP is mandatory for framework/library API decisions
+
+**Auto-managed by prjct-cli** | https://prjct.app
+<!-- prjct:end - DO NOT REMOVE THIS MARKER -->

package/templates/global/STORAGE-SPEC.md

@@ -0,0 +1,328 @@
+# Storage Specification
+
+**Canonical specification for prjct storage format.**
+
+All storage is managed by the `prjct` CLI which uses SQLite (`prjct.db`) internally. **NEVER read or write JSON storage files directly. Use `prjct` CLI commands for all storage operations.**
+
+---
+
+## Current Storage: SQLite (prjct.db)
+
+All reads and writes go through the `prjct` CLI, which manages a SQLite database (`prjct.db`) with WAL mode for safe concurrent access.
+
+```
+~/.prjct-cli/projects/{projectId}/
+├── prjct.db            # SQLite database (SOURCE OF TRUTH for all storage)
+├── context/
+│   ├── now.md          # Current task (generated from prjct.db)
+│   └── next.md         # Queue (generated from prjct.db)
+├── config/
+│   └── skills.json     # Agent-to-skill mappings
+├── agents/             # Domain specialists (auto-generated)
+└── sync/
+    └── pending.json    # Events for backend sync
+```
+
+### How to interact with storage
+
+- **Read state**: Use `prjct status`, `prjct dash`, `prjct next` CLI commands
+- **Write state**: Use `prjct` CLI commands (task, done, pause, resume, etc.)
+- **Issue tracker setup**: Use `prjct linear setup` or `prjct jira setup` (MCP/OAuth)
+- **Never** read/write JSON files in `storage/` or `memory/` directories
+
+---
+
+## LEGACY JSON Schemas (for reference only)
+
+> **WARNING**: These JSON schemas are LEGACY documentation only. The `storage/` and `memory/` directories are no longer used. All data lives in `prjct.db` (SQLite). Do NOT read or write these files.
+
+### state.json (LEGACY)
+
+```json
+{
+  "task": {
+    "id": "uuid-v4",
+    "title": "string",
+    "type": "feature|bug|improvement|refactor|chore",
+    "status": "active|paused|done",
+    "branch": "string|null",
+    "subtasks": [
+      {
+        "id": "uuid-v4",
+        "title": "string",
+        "status": "pending|done"
+      }
+    ],
+    "currentSubtask": 0,
+    "createdAt": "2024-01-15T10:30:00.000Z",
+    "updatedAt": "2024-01-15T10:30:00.000Z"
+  }
+}
+```
+
+**Empty state (no active task):**
+```json
+{
+  "task": null
+}
+```
+
+### queue.json (LEGACY)
+
+```json
+{
+  "tasks": [
+    {
+      "id": "uuid-v4",
+      "title": "string",
+      "type": "feature|bug|improvement|refactor|chore",
+      "priority": 1,
+      "createdAt": "2024-01-15T10:30:00.000Z"
+    }
+  ],
+  "updatedAt": "2024-01-15T10:30:00.000Z"
+}
+```
+
+### shipped.json (LEGACY)
+
+```json
+{
+  "features": [
+    {
+      "id": "uuid-v4",
+      "name": "string",
+      "version": "1.0.0",
+      "type": "feature|bug|improvement|refactor|chore",
+      "shippedAt": "2024-01-15T10:30:00.000Z"
+    }
+  ],
+  "updatedAt": "2024-01-15T10:30:00.000Z"
+}
+```
+
+### events.jsonl (LEGACY - now stored in SQLite `events` table)
+
+Previously append-only JSONL. Now stored in SQLite.
+
+```jsonl
+{"type":"task.created","timestamp":"2024-01-15T10:30:00.000Z","data":{"taskId":"uuid","title":"string"}}
+{"type":"task.started","timestamp":"2024-01-15T10:30:00.000Z","data":{"taskId":"uuid"}}
+{"type":"subtask.completed","timestamp":"2024-01-15T10:35:00.000Z","data":{"taskId":"uuid","subtaskIndex":0}}
+{"type":"task.completed","timestamp":"2024-01-15T10:40:00.000Z","data":{"taskId":"uuid"}}
+{"type":"feature.shipped","timestamp":"2024-01-15T10:45:00.000Z","data":{"featureId":"uuid","name":"string","version":"1.0.0"}}
+```
+
+**Event Types:**
+- `task.created` - New task created
+- `task.started` - Task activated
+- `task.paused` - Task paused
+- `task.resumed` - Task resumed
+- `task.completed` - Task completed
+- `subtask.completed` - Subtask completed
+- `feature.shipped` - Feature shipped
+
+### learnings.jsonl (LEGACY - now stored in SQLite)
+
+Previously used for LLM-to-LLM knowledge transfer. Now stored in SQLite.
+
+```jsonl
+{"taskId":"uuid","linearId":"PRJ-123","timestamp":"2024-01-15T10:40:00.000Z","learnings":{"patterns":["Use NestedContextResolver for hierarchical discovery"],"approaches":["Mirror existing method structure when extending"],"decisions":["Extended class rather than wrapper for consistency"],"gotchas":["Must handle null parent case"]},"value":{"type":"feature","impact":"high","description":"Hierarchical AGENTS.md support for monorepos"},"filesChanged":["core/resolver.ts","core/types.ts"],"tags":["agents","hierarchy","monorepo"]}
+```
+
+**Schema:**
+```json
+{
+  "taskId": "uuid-v4",
+  "linearId": "string|null",
+  "timestamp": "2024-01-15T10:40:00.000Z",
+  "learnings": {
+    "patterns": ["string"],
+    "approaches": ["string"],
+    "decisions": ["string"],
+    "gotchas": ["string"]
+  },
+  "value": {
+    "type": "feature|bugfix|performance|dx|refactor|infrastructure",
+    "impact": "high|medium|low",
+    "description": "string"
+  },
+  "filesChanged": ["string"],
+  "tags": ["string"]
+}
+```
+
+**Why Local Cache**: Enables future semantic retrieval without API latency. Will feed into vector DB for cross-session knowledge transfer.
+
+### skills.json
+
+```json
+{
+  "mappings": {
+    "frontend.md": ["frontend-design"],
+    "backend.md": ["javascript-typescript"],
+    "testing.md": ["developer-kit"]
+  },
+  "updatedAt": "2024-01-15T10:30:00.000Z"
+}
+```
+
+### pending.json (sync queue)
+
+```json
+{
+  "events": [
+    {
+      "id": "uuid-v4",
+      "type": "task.created",
+      "timestamp": "2024-01-15T10:30:00.000Z",
+      "data": {},
+      "synced": false
+    }
+  ],
+  "lastSync": "2024-01-15T10:30:00.000Z"
+}
+```
+
+---
+
+## Formatting Rules (MANDATORY)
+
+All agents MUST follow these rules for cross-agent compatibility:
+
+| Rule | Value |
+|------|-------|
+| JSON indentation | 2 spaces |
+| Trailing commas | NEVER |
+| Key ordering | Logical (as shown in schemas above) |
+| Timestamps | ISO-8601 with milliseconds (`.000Z`) |
+| UUIDs | v4 format (lowercase) |
+| Line endings | LF (not CRLF) |
+| File encoding | UTF-8 without BOM |
+| Empty objects | `{}` |
+| Empty arrays | `[]` |
+| Null values | `null` (lowercase) |
+
+### Timestamp Generation
+
+```bash
+# ALWAYS use dynamic timestamps, NEVER hardcode
+bun -e "console.log(new Date().toISOString())" 2>/dev/null || node -e "console.log(new Date().toISOString())"
+```
+
+### UUID Generation
+
+```bash
+# ALWAYS generate fresh UUIDs
+bun -e "console.log(crypto.randomUUID())" 2>/dev/null || node -e "console.log(require('crypto').randomUUID())"
+```
+
+---
+
+## Write Rules (CRITICAL)
+
+### Direct Writes Only
+
+**NEVER use temporary files** - Write directly to final destination:
+
+```
+WRONG: Create `.tmp/file.json`, then `mv` to final path
+CORRECT: Use prjctDb.setDoc() or StorageManager.write() to write to SQLite
+```
+
+### Atomic Updates
+
+All writes go through SQLite which handles atomicity via WAL mode:
+```typescript
+// StorageManager pattern (preferred):
+await stateStorage.update(projectId, (state) => {
+  state.field = newValue
+  return state
+})
+
+// Direct kv_store pattern:
+prjctDb.setDoc(projectId, 'key', data)
+```
+
+### NEVER Do These
+
+- Read or write JSON files in `storage/` or `memory/` directories
+- Use `.tmp/` directories
+- Use `mv` or `rename` operations for storage files
+- Create backup files like `*.bak` or `*.old`
+- Bypass `prjct` CLI to write directly to `prjct.db`
+
+---
+
+## Cross-Agent Compatibility
+
+### Why This Matters
+
+1. **User freedom**: Switch between Claude and Gemini freely
+2. **Remote sync**: Storage will sync to prjct.app backend
+3. **Single truth**: Both agents produce identical output
+
+### Verification Test
+
+```bash
+# Start task with Claude
+p. task "add feature X"
+
+# Switch to Gemini, continue
+p. done  # Should work seamlessly
+
+# Switch back to Claude
+p. ship  # Should read Gemini's changes correctly
+
+# All agents read from the same prjct.db via CLI commands
+prjct status  # Works from any agent
+```
+
+### Remote Sync Flow
+
+```
+Local Storage: prjct.db (Claude/Gemini)
+        ↓
+    sync/pending.json (events queue)
+        ↓
+    prjct.app API
+        ↓
+    Global Remote Storage
+        ↓
+    Any device, any agent
+```
+
+---
+
+## MCP Issue Tracker Strategy
+
+Issue tracker integrations are MCP-only.
+
+### Rules
+
+- `prjct` CLI does not call Linear/Jira SDKs or REST APIs directly.
+- Issue operations (`sync`, `list`, `get`, `start`, `done`, `update`, etc.) are delegated to MCP tools in the AI client.
+- `p. sync` refreshes project context and agent artifacts, not issue tracker payloads.
+- Local storage keeps task linkage metadata (for example `linearId`) and project workflow state in SQLite.
+
+### Setup
+
+- `prjct linear setup`
+- `prjct jira setup`
+
+### Operational Model
+
+```
+AI client MCP tools <-> Linear/Jira
+          |
+          v
+       prjct workflow state (prjct.db)
+```
+
+The CLI remains the source of truth for local project/task state.
+Issue-system mutations happen through MCP operations in the active AI session.
+
+---
+
+**Version**: 2.0.0
+**Last Updated**: 2026-02-10

package/templates/global/WINDSURF.md

@@ -0,0 +1,22 @@
+---
+trigger: always_on
+description: "prjct - Context layer for AI coding agents"
+---
+
+<!-- prjct:start - DO NOT REMOVE THIS MARKER -->
+# p/ — Context layer for AI agents
+
+Workflows: `/sync` `/task` `/done` `/ship` `/pause` `/resume` `/bug` `/dash` `/next`
+
+When user triggers a workflow, execute the corresponding prjct CLI command with `--md` flag for context.
+
+Rules:
+- Never commit to main/master directly
+- All commits include footer: `Generated with [p/](https://www.prjct.app/)`
+- Path resolution: `.prjct/prjct.config.json` → `~/.prjct-cli/projects/{projectId}`
+- All storage through `prjct` CLI (SQLite internally)
+- For code tasks, always start with `/task` and follow Context Contract from CLI output
+- Context7 MCP is mandatory for framework/library API decisions
+
+**Auto-managed by prjct-cli** | https://prjct.app
+<!-- prjct:end - DO NOT REMOVE THIS MARKER -->

package/templates/global/modules/CLAUDE-commands.md

@@ -0,0 +1 @@
+<!-- Module deprecated: content moved to CLI --md output -->

package/templates/global/modules/CLAUDE-core.md

@@ -0,0 +1,16 @@
+# p/ — Context layer for AI agents
+
+Commands: `p. sync` `p. task` `p. done` `p. ship` `p. pause` `p. resume` `p. bug` `p. dash` `p. next`
+
+When user types `p. <command>`, READ the template from `~/.claude/commands/p/{command}.md` and execute step by step.
+
+Rules:
+- Never commit to main/master directly
+- All commits include footer: `Generated with [p/](https://www.prjct.app/)`
+- Path resolution: `.prjct/prjct.config.json` → `~/.prjct-cli/projects/{projectId}`
+- All storage through `prjct` CLI (SQLite internally)
+- For code tasks, always start with `p. task` and follow Context Contract from CLI output
+- Context7 MCP is mandatory for framework/library API decisions
+- Templates are MANDATORY workflows — follow every step
+
+**Auto-managed by prjct-cli** | https://prjct.app

package/templates/global/modules/CLAUDE-git.md

@@ -0,0 +1 @@
+<!-- Module deprecated: content moved to CLI --md output -->

package/templates/global/modules/CLAUDE-intelligence.md

@@ -0,0 +1 @@
+<!-- Module deprecated: content moved to CLI --md output -->

package/templates/global/modules/CLAUDE-storage.md

@@ -0,0 +1 @@
+<!-- Module deprecated: content moved to CLI --md output -->

package/templates/global/modules/module-config.json

@@ -0,0 +1,12 @@
+{
+  "description": "Configuration for modular CLAUDE.md composition",
+  "version": "2.0.0",
+  "profiles": {
+    "default": {
+      "description": "Ultra-thin — CLI provides context via --md flag",
+      "modules": ["CLAUDE-core.md"]
+    }
+  },
+  "default": "default",
+  "commandProfiles": {}
+}

package/templates/mcp-config.json

@@ -0,0 +1,29 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"],
+      "description": "Library documentation lookup"
+    },
+    "linear": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"],
+      "description": "Linear MCP server (OAuth)"
+    },
+    "jira": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://mcp.atlassian.com/v1/mcp"],
+      "description": "Atlassian MCP server for Jira (OAuth)"
+    }
+  },
+  "usage": {
+    "context7": {
+      "when": ["Looking up library/framework documentation", "Need current API docs"],
+      "tools": ["resolve-library-id", "get-library-docs"]
+    }
+  },
+  "integrations": {
+    "linear": "MCP - Run `prjct linear setup`",
+    "jira": "MCP - Run `prjct jira setup`"
+  }
+}

package/templates/permissions/default.jsonc

@@ -0,0 +1,60 @@
+{
+  // Default permissions preset for prjct-cli
+  // Safe defaults with protection against destructive operations
+
+  "bash": {
+    // Safe read-only commands - always allowed
+    "git status*": "allow",
+    "git log*": "allow",
+    "git diff*": "allow",
+    "git branch*": "allow",
+    "ls*": "allow",
+    "pwd": "allow",
+    "cat*": "allow",
+    "head*": "allow",
+    "tail*": "allow",
+    "grep*": "allow",
+    "find*": "allow",
+    "which*": "allow",
+    "node -e*": "allow",
+    "bun -e*": "allow",
+    "npm list*": "allow",
+    "npx tsc --noEmit*": "allow",
+
+    // Potentially destructive - ask first
+    "rm -rf*": "ask",
+    "rm -r*": "ask",
+    "git push*": "ask",
+    "git reset --hard*": "ask",
+    "npm publish*": "ask",
+    "chmod*": "ask",
+
+    // Always denied - too dangerous
+    "rm -rf /*": "deny",
+    "rm -rf ~/*": "deny",
+    "sudo*": "deny"
+  },
+
+  "files": {
+    "read": {
+      "**/*": "allow"
+    },
+    "write": {
+      "**/*": "allow"
+    },
+    "delete": {
+      "**/*": "ask"
+    }
+  },
+
+  "web": {
+    "enabled": true
+  },
+
+  "doomLoop": {
+    "enabled": true,
+    "maxRetries": 3
+  },
+
+  "externalDirectories": "ask"
+}