prjct-cli 1.53.0 → 1.55.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [1.55.0] - 2026-04-05
+
+### Features
+
+- Obsidian vault integration (#240)
+
+
+## [1.54.0] - 2026-04-05
+
+### Features
+
+- multi-agent parallel sessions with auto-worktree isolation (#237)
+- Obsidian vault integration — CLI commands, 8 MCP tools, Kanban board, Canvas roadmap, Dataview dashboards, path security
+- Sync skill generates `_insights.md` via LLM when Obsidian is configured
+- Linear CSV import script with per-project Kanban boards and tags
+
+### Bug Fixes
+
+- guard feedback array spreads preventing s.push crash (#236)
+
+## [1.53.1] - 2026-04-04
+
+### Docs
+- update README with full command reference, Windsurf support, MCP server, parallel sessions, code intelligence, web dashboard, cloud sync, and architecture overview
+
 ## [1.52.4] - 2026-03-26
 
 ### Bug Fixes

package/README.md

@@ -2,13 +2,14 @@
 
 **Context layer for AI coding agents.**
 
-Works with Claude Code, Gemini CLI, OpenAI Codex, Antigravity, Cursor IDE, and more.
+Works with Claude Code, Gemini CLI, OpenAI Codex, Antigravity, Cursor IDE, Windsurf, and more.
 
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-Ready-6366f1)](CLAUDE.md)
 [![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-Ready-4285F4)]()
 [![OpenAI Codex](https://img.shields.io/badge/OpenAI%20Codex-Ready-10A37F)]()
 [![Antigravity](https://img.shields.io/badge/Antigravity-Ready-EA4335)]()
 [![Cursor IDE](https://img.shields.io/badge/Cursor%20IDE-Ready-00D4AA)]()
+[![Windsurf](https://img.shields.io/badge/Windsurf-Ready-7C3AED)]()
 [![npm](https://img.shields.io/npm/v/prjct-cli)](https://www.npmjs.com/package/prjct-cli)
 
 ## What is prjct?
@@ -17,18 +18,18 @@ prjct gives AI coding agents the context they need about your project. It mainta
 
 ```
 Your AI Agent                              prjct
-(Claude/Gemini/Antigravity/Cursor)           │
-         │                                   │
-         │  "What am I working on?"          │
-         │ ────────────────────────────────► │
-         │                                   │ Reads project context
-         │  Task: "Add user auth"            │
-         │  Branch: feature/auth             │
-         │  Subtask 2/5: API routes          │
-         │ ◄──────────────────────────────── │
-         │                                   │
-         ▼                                   │
-    Writes code with full context            │
+(Claude/Gemini/Codex/Cursor/Windsurf)        |
+         |                                   |
+         |  "What am I working on?"          |
+         | --------------------------------> |
+         |                                   | Reads project context
+         |  Task: "Add user auth"            |
+         |  Branch: feature/auth             |
+         |  Subtask 2/5: API routes          |
+         | <-------------------------------- |
+         |                                   |
+         v                                   |
+    Writes code with full context            |
 ```
 
 ## Install
@@ -52,232 +53,270 @@ prjct init
 # 3. Open in Claude Code, Gemini CLI, or Codex and use:
 p. sync                    # Analyze project
 p. task "add user auth"    # Start a task
-p. done                    # Complete subtask
+p. done                    # Complete task
 p. ship                    # Ship with PR
 ```
 
-> **Note (Codex):** `prjct sync` generates `AGENTS.md` for project-level Codex context, `prjct start` installs `~/.codex/skills/prjct/SKILL.md`, and `prjct doctor` validates the `p.` router health.
-
-### Google Antigravity
-
-```bash
-# 1. One-time global setup (installs prjct as a skill)
-prjct start
-
-# 2. Initialize your project
-cd my-project
-prjct init
-
-# 3. Open in Antigravity and use:
-p. sync                    # Analyze project
-p. task "add user auth"    # Start a task
-p. done                    # Complete subtask
-p. ship                    # Ship with PR
-```
-
-> **Note:** prjct integrates as a Skill (not MCP server) for zero-overhead operation.
-
-### Cursor IDE
+### Cursor IDE / Windsurf
 
 ```bash
 # 1. Initialize your project (no global setup needed)
 cd my-project
 prjct init
 
-# 2. Open in Cursor and use:
+# 2. Open in Cursor or Windsurf and use:
 /sync                      # Analyze project
 /task "add user auth"      # Start a task
-/done                      # Complete subtask
+/done                      # Complete task
 /ship                      # Ship with PR
 ```
 
-> **Note:** Cursor uses `/command` syntax. Commands are installed per-project in `.cursor/commands/`. If deleted, run `/sync` to regenerate.
+> Cursor uses `.cursor/commands/`, Windsurf uses `.windsurf/` with YAML frontmatter. Run `/sync` to regenerate if deleted.
 
 ### Core Workflow
 
 ```
-Claude/Gemini/Codex/Antigravity:  p. sync  →  p. task "..."  →  [code]  →  p. done  →  p. ship
-Cursor:                     /sync    →  /task "..."    →  [code]  →  /done    →  /ship
+Claude/Gemini/Codex:  p. sync  ->  p. task "..."  ->  [code]  ->  p. done  ->  p. ship
+Cursor/Windsurf:      /sync    ->  /task "..."    ->  [code]  ->  /done    ->  /ship
 ```
 
 ## How It Works
 
-| Component | Claude Code | Gemini CLI | OpenAI Codex | Antigravity | Cursor IDE |
-|-----------|-------------|------------|--------------|-------------|------------|
-| Router | `~/.claude/commands/p.md` | `~/.gemini/commands/p.toml` | Skill (`~/.codex/skills/prjct/SKILL.md`) | Skill | `.cursor/commands/*.md` |
-| Config | `~/.claude/CLAUDE.md` | `~/.gemini/GEMINI.md` | `AGENTS.md` | `~/.gemini/antigravity/skills/prjct/` | `.cursor/rules/prjct.mdc` |
-| Storage | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` |
-| Scope | Global | Global | Project + Global skill | Global | Per-project |
-| Syntax | `p. command` | `p. command` | `p. command` | `p. command` | `/command` |
+| Component | Claude Code | Gemini CLI | OpenAI Codex | Antigravity | Cursor IDE | Windsurf |
+|-----------|-------------|------------|--------------|-------------|------------|----------|
+| Router | `~/.claude/commands/p.md` | `~/.gemini/commands/p.toml` | `~/.codex/skills/prjct/SKILL.md` | Skill | `.cursor/commands/*.md` | `.windsurf/*.md` |
+| Config | `~/.claude/CLAUDE.md` | `~/.gemini/GEMINI.md` | `AGENTS.md` | `~/.gemini/antigravity/skills/prjct/` | `.cursor/rules/prjct.mdc` | `.windsurf/` (YAML) |
+| Storage | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` | `~/.prjct-cli/projects/` |
+| Syntax | `p. command` | `p. command` | `p. command` | `p. command` | `/command` | `/command` |
 
-All agents share the same project storage, so you can switch between them freely.
+All agents share the same SQLite-backed project storage, so you can switch between them freely.
 
 ## Commands
 
-| Claude/Gemini | Cursor | Description |
-|---------------|--------|-------------|
-| `p. sync` | `/sync` | Analyze project, generate domain agents |
+### Core Workflow
+
+| Claude/Gemini | Cursor/Windsurf | Description |
+|---------------|-----------------|-------------|
+| `p. sync` | `/sync` | Analyze project, build indexes, generate skills |
 | `p. task "desc"` | `/task "desc"` | Start task with auto-classification |
-| `p. done` | `/done` | Complete current subtask |
+| `p. done` | `/done` | Complete current task |
 | `p. ship "name"` | `/ship "name"` | Ship feature with PR + version bump |
 | `p. pause` | `/pause` | Pause current task |
 | `p. resume` | `/resume` | Resume paused task |
-| `p. bug "desc"` | `/bug "desc"` | Report a bug |
-| `p. linear` | - | Linear integration |
-| `p. github` | - | GitHub Issues integration |
-
-## Task History
+| `p. next` | `/next` | Show priority queue or roadmap |
+| `p. bug "desc"` | `/bug "desc"` | Report and track a bug |
+| `p. idea "desc"` | `/idea "desc"` | Transform idea into technical architecture |
+| `p. spec` | `/spec` | Create detailed spec for complex features |
+| `p. dash` | `/dash` | Unified dashboard (status, progress, roadmap) |
+| `p. suggest` | `/suggest` | Smart recommendations based on project state |
 
-prjct automatically tracks your completed tasks to help AI agents learn from patterns and make better decisions across sessions.
+### Analysis & Performance
 
-### How It Works
+| Command | Description |
+|---------|-------------|
+| `p. status` | Check if context is stale |
+| `p. perf` | Performance dashboard (startup, memory, context) |
+| `p. velocity` | Sprint-based velocity with trend detection |
+| `p. tokens <in> <out>` | Record token usage on active task |
+| `p. stats` | Value dashboard (token savings, impact) |
+| `p. sessions` | Show recent sessions across projects |
+| `p. diff` | Diff between draft and sealed analysis |
+| `p. seal` | Seal analysis with commit-hash signature |
+| `p. verify` | Verify integrity (cryptographic or `--semantic`) |
+| `p. rollback` | Rollback to previous sealed analysis |
+
+### Advanced
 
-When you complete a task (`p. done` / `/done`), prjct stores:
-- Task description and classification (feature, bug, improvement, chore)
-- Start and completion timestamps
-- Number of subtasks and their summaries
-- Git branch name and Linear issue ID (if linked)
-- PR URL (if shipped)
+| Command | Description |
+|---------|-------------|
+| `p. design` | Design system architecture, APIs, components |
+| `p. enrich "issue"` | Build enrichment context for an issue |
+| `p. workflow` | Configure workflow hooks via natural language |
+| `p. git` | Smart git operations with context |
+| `p. test` | Run tests with auto-fix |
+| `p. undo` / `p. redo` | Snapshot-based undo/redo |
+| `p. recover` | Recover abandoned session with context |
+| `p. linear` | Linear integration via MCP |
+| `p. jira` | Jira integration via MCP |
+| `p. obsidian` | Obsidian vault integration (setup, export, status) |
 
-This history is:
-- **Bounded**: Maximum 20 entries with FIFO (First-In-First-Out) eviction
-- **Contextual**: Filtered by task type when starting similar work
-- **Persistent**: Survives across sessions and agent types
+### Parallel Agent Sessions
 
-### Context Injection
+Run multiple AI agents on different tasks simultaneously, each in an isolated git worktree.
 
-Task history is automatically injected into the AI agent's context:
-- When **starting a task**: Shows 3 most recent tasks of the same type (e.g., recent bug fixes when starting a new bug)
-- When **idle**: Shows 5 most recent tasks across all types
-- **Purpose**: Helps agents identify patterns, avoid repeating mistakes, and build on previous solutions
+| Command | Description |
+|---------|-------------|
+| `p. parallel spawn "task"` | Spawn agent in isolated worktree |
+| `p. parallel status` | Show all active agents |
+| `p. parallel join` | Merge completed branches back |
+| `p. worktree create` | Create worktree (auto-copies .env, installs deps) |
+| `p. worktree list` | List active worktrees |
+| `p. worktree remove` | Clean up completed worktrees |
+| `p. conductor init` | Scaffold Conductor.build integration |
 
-### Accessor Methods (for developers)
+## CLI Commands
 
-```typescript
-import { stateStorage } from './storage/state-storage'
+Commands you run directly in the terminal (outside your AI agent):
 
-// Get full task history (max 20 entries, newest first)
-const history = await stateStorage.getTaskHistory(projectId)
+```bash
+prjct start              # First-time setup wizard
+prjct init               # Initialize project
+prjct sync               # Analyze project and build indexes
+prjct doctor             # Check system health and dependencies
+prjct serve              # Start web dashboard (port 3478)
+prjct watch              # Auto-sync on file changes
+prjct hooks              # Manage git hooks for auto-sync
+prjct context            # Smart context filtering tools
+prjct enrich             # Prepare issue enrichment context
+prjct linear             # Linear MCP gateway
+prjct jira               # Jira MCP gateway
+prjct obsidian setup     # Link project to Obsidian vault
+prjct obsidian export    # Export board, queue, shipped, roadmap to vault
+prjct obsidian status    # Check Obsidian integration status
+prjct login              # Authenticate with prjct cloud (opens browser)
+prjct logout             # Sign out from prjct cloud
+prjct update             # Update CLI system-wide
+prjct stop               # Stop the background daemon
+prjct restart            # Restart the background daemon
+prjct uninstall          # Complete system removal
+prjct --version          # Show version + provider status
+prjct --help             # Show help
+```
 
-// Get most recent completed task
-const recent = await stateStorage.getMostRecentTask(projectId)
+## Code Intelligence
 
-// Get tasks by classification
-const bugs = await stateStorage.getTaskHistoryByType(projectId, 'bug')
-const features = await stateStorage.getTaskHistoryByType(projectId, 'feature')
-```
+`prjct sync` builds a triple-index system over your codebase:
 
-## CLI Commands
+| Index | Purpose |
+|-------|---------|
+| **BM25** | Full-text search over file names, symbols, comments |
+| **Import Graph** | Dependency graph with forward and reverse edges |
+| **Git Co-change** | Files that frequently change together |
 
-```bash
-prjct start          # First-time setup (Claude/Gemini/Codex skill install)
-prjct init           # Initialize project (+ AI tool setup)
-prjct sync           # Analyze project and generate context
-prjct verify         # Verify analysis integrity (cryptographic)
-prjct verify --semantic  # Verify analysis consistency (semantic)
-prjct --version      # Show version + provider status
-prjct --help         # Show help
-```
+These indexes power file ranking, impact analysis, and related-context suggestions for your AI agent.
 
-### Analysis Verification
+## MCP Server
 
-prjct provides two types of analysis verification to ensure data integrity and logical consistency:
+prjct exposes an MCP server with tools that AI agents can call directly:
 
-#### Cryptographic Verification (Default)
-```bash
-prjct verify [--json]
-```
+| Category | Tools | Examples |
+|----------|-------|---------|
+| **Memory** | 8 | Save/search memories, record decisions, manage preferences |
+| **Session** | 4 | Start sessions, recover context, record outcomes |
+| **Code Intelligence** | 3 | Impact analysis, related files, staleness check |
+| **Workflow** | 4 | Task and session management |
+| **File** | 3 | File reading and filtering |
+| **Pattern** | 3 | Pattern extraction and matching |
+| **Review** | 3 | Code review context |
+| **Project** | 4 | Project-level operations |
+| **Obsidian** | 8 | Read, write, search, list, export, import, stats, status |
 
-Verifies the integrity of sealed analysis results using cryptographic signatures. This ensures:
-- Analysis data hasn't been tampered with
-- Sealed analysis matches the original analysis
-- Hash signatures are valid
+The memory system uses FTS5 full-text search, tracks decision outcomes ("did this work before?"), and auto-captures patterns during normal workflow.
 
-**When to use:** After sealing an analysis (`prjct seal`) to confirm data integrity.
+## Web Dashboard
 
-#### Semantic Verification (PRJ-270)
 ```bash
-prjct verify --semantic [--json]
+prjct serve
 ```
 
-Validates that analysis results match the actual project state. This checks:
-- ✓ **Frameworks** exist in `package.json` dependencies
-- ✓ **Languages** match actual file extensions (.ts → TypeScript)
-- ✓ **Pattern locations** reference real files in the project
-- ✓ **File count** is accurate (within 10% tolerance)
-- ✓ **Anti-pattern files** exist when referenced
+Starts an HTTP server on port 3478 with:
 
-**When to use:** Before sealing an analysis to catch logical inconsistencies or after project changes to validate analysis accuracy.
+- REST API for project state, task queue, ideas, roadmap, shipped features
+- SSE (Server-Sent Events) for real-time updates
+- Status bar endpoint for IDE integration (`/api/status-bar/compact`)
+- Global statistics across all projects
 
-**Example output:**
-```
-Semantic Verification Report
-────────────────────────────
-  ✓ Framework verification: passed (2 frameworks validated)
-  ✓ Language verification: passed (1 language validated)
-  ✓ Pattern locations: passed (12 patterns verified)
-  ✓ File count verification: passed (324 files, within tolerance)
-  ✓ Anti-pattern files: passed (3 anti-patterns verified)
-
-Result: PASSED (5/5 checks)
-Total time: 145ms
+Built with Hono, supports both Bun and Node.js runtimes.
+
+## Cloud Sync
+
+```bash
+prjct login              # Browser-based OTP authentication
+prjct sync               # Bidirectional push/pull with prjct cloud
 ```
 
-Both verification modes support `--json` flag for programmatic use.
+Cloud sync enables:
+- Cross-device project state synchronization
+- Event-sourced bidirectional push/pull
+- Automatic sync on task completion
 
-## Environment Variables
+## Obsidian Integration
 
-### Configuration
+Use Obsidian as your project management tool with Kanban boards, dashboards, and knowledge base.
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PRJCT_CLI_HOME` | `~/.prjct-cli` | Override global storage location. Useful for tests or sandboxed environments. |
-| `PRJCT_DEBUG` | _(unset)_ | Enable debug logging. Values: `1`, `true`, or a log level (`error`, `warn`, `info`, `debug`). |
-| `DEBUG` | _(unset)_ | Fallback debug flag (used if `PRJCT_DEBUG` is not set). Values: `1`, `true`, or `prjct`. |
-| `CI` | _(unset)_ | Set automatically in CI environments. Skips interactive prompts. |
+```bash
+prjct obsidian setup --vault-path ~/Obsidian/my-vault   # Link project to vault
+prjct obsidian export                                    # Export data to vault
+prjct obsidian status                                    # Check config
+```
+
+Features:
+- **Kanban board** with Obsidian Kanban plugin (per-project filtered views)
+- **Dataview dashboards** (active sprint, backlog, stats, by project/priority)
+- **Canvas roadmap** with dependency arrows between features
+- **Daily standup notes** with task progress and queue
+- **8 MCP tools** for AI agents to read, write, search, and import vault notes
+- **`_insights.md`** generated by LLM on each `p. sync` (architecture, risks, progress)
+- **Tags** for Graph View coloring (status, priority, labels, project)
+- **Security**: path traversal prevention, extension whitelist, blocked directories
 
-### Issue Tracker MCP (Linear + Jira)
+## Issue Tracker Integration
 
 Issue trackers are configured via MCP (OAuth in your AI client), not API tokens.
 
-| Command | Description |
-|---------|-------------|
-| `prjct linear setup` | Configure Linear MCP server in `~/.claude/mcp.json`. |
-| `prjct linear status` | Verify Linear MCP config. |
-| `prjct linear <sync|list|get|create|update|start|done|comment>` | Delegate Linear operation to MCP tools in your AI client. |
-| `prjct jira setup` | Configure Jira MCP server in `~/.claude/mcp.json`. |
-| `prjct jira status` | Verify Jira MCP config. |
-| `prjct jira <sync|list|get|create|update|start|done|transition|comment>` | Delegate Jira operation to MCP tools in your AI client. |
+```bash
+# Linear
+prjct linear setup       # Configure Linear MCP server
+prjct linear status      # Verify config
+# Then use: p. linear sync|list|get|create|update|start|done|comment
+
+# Jira
+prjct jira setup         # Configure Jira MCP server
+prjct jira status        # Verify config
+# Then use: p. jira sync|list|get|create|update|start|done|transition|comment
+```
 
-### Agent Detection (Auto-set)
+## Analysis Verification
 
-These are typically set by the AI agent runtime, not by users:
+```bash
+prjct verify             # Cryptographic: hash signature integrity
+prjct verify --semantic  # Semantic: frameworks, languages, file counts match reality
+```
 
-| Variable | Description |
-|----------|-------------|
-| `CLAUDE_AGENT` | Set when running inside Claude Code. |
-| `ANTHROPIC_CLAUDE` | Alternative Claude environment indicator. |
-| `MCP_AVAILABLE` | Set when MCP (Model Context Protocol) is available. |
-| `HOME` / `USERPROFILE` | Standard OS home directory (used for path resolution). |
+Both modes support `--json` for programmatic use.
 
-### Usage Examples
+## Environment Variables
 
-```bash
-# Enable debug logging
-PRJCT_DEBUG=1 prjct sync
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PRJCT_CLI_HOME` | `~/.prjct-cli` | Override global storage location |
+| `PRJCT_DEBUG` | _(unset)_ | Enable debug logging (`1`, `true`, or log level) |
+| `DEBUG` | _(unset)_ | Fallback debug flag (`1`, `true`, or `prjct`) |
+| `CI` | _(unset)_ | Set in CI environments; skips interactive prompts |
 
-# Use a custom storage location
-PRJCT_CLI_HOME=/tmp/prjct-test prjct init
+## Architecture
 
-# Configure Linear + Jira via MCP
-prjct linear setup
-prjct jira setup
+```
+prjct-cli/
+  core/
+    commands/       # CLI command handlers
+    domain/         # BM25, import graph, co-change, velocity
+    infrastructure/ # Config, path manager, AI provider detection
+    mcp/            # MCP server (56 tools)
+    schemas/        # Zod schemas (PRD, model, etc.)
+    server/         # Hono HTTP server + SSE
+    services/       # Memory, sync, code intel, skills, doctor
+    storage/        # SQLite via better-sqlite3
+    sync/           # Cloud sync client + event mapping
+    types/          # TypeScript type definitions
+    utils/          # Shared utilities
+  templates/        # Skill templates per editor
 ```
 
 ## Requirements
 
 - Node.js 18+ or Bun 1.0+
-- One of: Claude Code, Gemini CLI, Antigravity, or Cursor IDE
+- One of: Claude Code, Gemini CLI, OpenAI Codex, Antigravity, Cursor IDE, or Windsurf
 
 ## Links