prjct-cli 3.46.0 → 3.47.1

package/templates/global/STORAGE-SPEC.md

@@ -1,327 +0,0 @@
-# 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 context`, or MCP project tools
-- **Write state**: Use `prjct` CLI commands (`task`, `status`, `capture`, `remember`, etc.)
-- **Issue tracker setup**: Configure Linear/Jira MCP servers in the AI client; prjct has no native tracker CLI verbs
-- **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 work with Claude
-p. work "add feature X"
-
-# Switch to Gemini, continue
-prjct work --md  # 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
-
-Configure Linear/Jira MCP servers in the AI client when issue tracker access is needed.
-
-### 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/planning-methodology-deep.md

@@ -1,195 +0,0 @@
-# Software Planning Methodology for prjct
-
-This methodology guides the AI through developing ideas into complete technical specifications.
-
-## Phase 1: Discovery & Problem Definition
-
-### Questions to Ask
-- What specific problem does this solve?
-- Who is the target user?
-- What's the budget and timeline?
-- What happens if this problem isn't solved?
-
-### Output
-- Problem statement
-- User personas
-- Business constraints
-- Success metrics
-
-## Phase 2: User Flows & Journeys
-
-### Process
-1. Map primary user journey
-2. Identify entry points
-3. Define success states
-4. Document error states
-5. Note edge cases
-
-### Jobs-to-be-Done
-When [situation], I want to [motivation], so I can [expected outcome]
-
-## Phase 3: Domain Modeling
-
-### Entity Definition
-For each entity, define:
-- Description
-- Attributes (name, type, constraints)
-- Relationships
-- Business rules
-- Lifecycle states
-
-### Bounded Contexts
-Group entities into logical boundaries with:
-- Owned entities
-- External dependencies
-- Events published/consumed
-
-## Phase 4: API Contract Design
-
-### Style Selection
-| Style    | Best For |
-|----------|----------|
-| REST     | Simple CRUD, broad compatibility |
-| GraphQL  | Complex data requirements |
-| tRPC     | Full-stack TypeScript |
-| gRPC     | Microservices |
-
-### Endpoint Specification
-- Method/Type
-- Path/Name
-- Authentication
-- Input/Output schemas
-- Error responses
-
-## Phase 5: System Architecture
-
-### Pattern Selection
-| Pattern | Best For |
-|---------|----------|
-| Modular Monolith | Small team, fast iteration |
-| Serverless-First | Variable load, event-driven |
-| Microservices | Large team, complex domain |
-
-### C4 Model
-1. Context - System and external actors
-2. Container - Major components
-3. Component - Internal structure
-
-## Phase 6: Data Architecture
-
-### Database Selection
-| Type | Options | Best For |
-|------|---------|----------|
-| Relational | PostgreSQL | ACID, structured data |
-| Document | MongoDB | Flexible schema |
-| Key-Value | Redis | Caching, sessions |
-
-### Schema Design
-- Tables and columns
-- Indexes
-- Constraints
-- Relationships
-
-## Phase 7: Tech Stack Decision
-
-### Frontend Stack
-- Framework (Next.js, Remix, SvelteKit)
-- Styling (Tailwind, CSS Modules)
-- State management (Zustand, Jotai)
-- Data fetching (TanStack Query, SWR)
-
-### Backend Stack
-- Runtime (Node.js, Bun)
-- Framework (Next.js API, Hono)
-- ORM (Drizzle, Prisma)
-- Validation (Zod, Valibot)
-
-### Infrastructure
-- Hosting (Vercel, Railway, Fly.io)
-- Database (Neon, PlanetScale)
-- Cache (Upstash, Redis)
-- Monitoring (Sentry, Axiom)
-
-## Phase 8: Implementation Roadmap
-
-### MVP Scope Definition
-- Must-have features (P0)
-- Should-have features (P1)
-- Nice-to-have features (P2)
-- Future considerations (P3)
-
-### Development Phases
-1. Foundation - Setup, core infrastructure
-2. Core Features - Primary functionality
-3. Polish & Launch - Optimization, deployment
-
-### Risk Assessment
-- Technical risks and mitigation
-- Business risks and mitigation
-- Dependencies and assumptions
-
-## Output Structure
-
-When complete, generate:
-
-1. **Executive Summary** - Problem, solution, key decisions
-2. **Architecture Documents** - All phases detailed
-3. **Implementation Plan** - Prioritized tasks with estimates
-4. **Decision Log** - Key choices and reasoning
-
-## Interactive Development Process
-
-1. **Classification**: Determine if idea needs full architecture
-2. **Discovery**: Ask clarifying questions
-3. **Generation**: Create architecture phase by phase
-4. **Validation**: Review with user at key points
-5. **Refinement**: Iterate based on feedback
-6. **Output**: Save complete specification
-
-## Success Criteria
-
-A complete architecture includes:
-- Clear problem definition
-- User flows mapped
-- Domain model defined
-- API contracts specified
-- Tech stack chosen
-- Database schema designed
-- Implementation roadmap created
-- Risk assessment completed
-
-## Templates
-
-### Entity Template
-```
-Entity: [Name]
-├── Description: [What it represents]
-├── Attributes:
-│   ├── id: uuid (primary key)
-│   └── [field]: [type] ([constraints])
-├── Relationships: [connections]
-├── Rules: [invariants]
-└── States: [lifecycle]
-```
-
-### API Endpoint Template
-```
-Operation: [Name]
-├── Method: [GET/POST/PUT/DELETE]
-├── Path: [/api/resource]
-├── Auth: [Required/Optional]
-├── Input: {schema}
-├── Output: {schema}
-└── Errors: [codes and descriptions]
-```
-
-### Phase Template
-```
-Phase: [Name]
-├── Duration: [timeframe]
-├── Tasks:
-│   ├── [Task 1]
-│   └── [Task 2]
-├── Deliverable: [outcome]
-└── Dependencies: [prerequisites]
-```

package/templates/sdd-canonical-sequence.md

@@ -1,85 +0,0 @@
-# SDD canonical sequence — prjct
-
-Spec-Driven Development is prjct's default flow for substantive work. The six stations:
-
-```
-spec ─→ audit-spec ─→ task (--spec <id>) ─→ implement ─→ ship (acceptance gate)
-                                                                  └─→ remember learning
-```
-
-## Stations
-
-### 1. `spec`
-
-The user describes a feature, fix, or initiative WITH goals or stakes. You don't run `task` yet. You run `prjct spec "<title>"` and walk the forcing questions:
-
-- goal (1–3 sentences)
-- eli10 (2–4 sentences)
-- stakes if we ship the wrong thing
-- acceptance criteria (testable, observable list)
-- scope (what's IN)
-- out_of_scope (what's OUT)
-- risks (each with mitigation)
-- test plan
-
-The CLI persists this in the `specs` SQLite table.
-
-### 2. `audit-spec`
-
-Before writing any code: harden the spec. Run `prjct audit-spec <id>` — it emits a dispatch prompt for THREE review subagents that you run IN PARALLEL (one tool-use block per reviewer in the SAME message):
-
-- **strategic** — scope sanity. Worth doing? Right size?
-- **architecture** — feasibility. Data flow, failure modes, dependencies.
-- **design** — UX/DX quality. Four dimensions rated 0–10.
-
-Each returns a verdict (pass | fail) + notes. You write each back via `prjct spec record-review`. When all three pass, the spec auto-promotes from `draft` → `reviewed`.
-
-If any reviewer fails: revise the spec via `prjct spec update`, re-audit. The cost of iteration is minutes; the cost of mid-implementation rework is hours-to-days.
-
-### 3. `task --spec <id>`
-
-Now create the task. The `--spec` flag wires the task to its spec via `linked_spec_id`. Without it, `ship` later has nothing to gate against.
-
-```
-prjct work "implement rate-limit middleware" --spec <id>
-```
-
-### 4. implement
-
-Normal coding loop. Mid-flight workflows (`review`, `qa`, `investigate`) still apply. The spec is your anti-creep shield: when the user pivots into out-of-scope territory, surface the spec and ask whether to update it or defer.
-
-### 5. `ship` (with the spec gate)
-
-`prjct ship` reads the linked spec's `acceptance_criteria` and surfaces them as a checklist in the PR description. Walk each one — pass / fail / N/A. If any criterion is unmet → STOP and surface to the user.
-
-Override path: `prjct ship --no-spec-gate` (use only when the user explicitly accepts).
-
-### 6. `remember learning`
-
-After ship, capture what the spec got right and wrong:
-
-```
-prjct remember learning "spec missed the clock-skew edge case; future rate-limit specs should call out time-source"
-```
-
-The next spec is sharper. Compounding effect: the vault accumulates spec-shaped lessons.
-
-## When to bypass SDD
-
-Not every keystroke goes through six stations. Routine work skips `spec`:
-
-- single-file fix with known scope
-- doc tweak / typo
-- inbox capture / GTD dump
-- conversational Q&A
-- re-running a failing test
-- bug fix where root cause is already known
-
-Rule of thumb: if the work touches >1 file, ships to users, or takes >30 minutes, default to `spec` first.
-
-## Anti-patterns
-
-- **Skipping straight to `task` because the user said "let's build X".** If they said it WITH stakes, the spec is what protects them from scope creep mid-implementation.
-- **Auditing AFTER implementing.** Pre-implementation review is the whole point. Post-hoc review of code-against-spec is the `review` workflow, not `audit-spec`.
-- **Treating the spec as immutable.** Specs evolve. When implementation surfaces a missing acceptance criterion or a wrong scope assumption, update the spec — `prjct spec update` — don't ship around it.
-- **Marking `acceptance_criteria` met without proof.** The criterion exists to be tested. If the test wasn't run, the criterion isn't met.

package/templates/spec-reviewer-rubrics/architecture.md

@@ -1,47 +0,0 @@
-# Architecture reviewer rubric — `audit-spec`
-
-You are reviewing a `prjct` spec for engineering feasibility. You receive the spec body verbatim. Apply the questions below; return a structured verdict.
-
-## Questions to ask
-
-1. **Can this be built?** With the team's stack and skill set, in the implied timeframe. If "no" or "yes but only by replacing the database", fail.
-2. **Is the data flow coherent?** Trace input → state → output. Where does data live? Who writes it? Who reads it? Failure modes at each hop.
-3. **Is the state machine implicit or explicit?** Explicit > implicit. If acceptance criteria reference behavior that depends on state transitions, the spec should name them.
-4. **What edge cases / failure modes are missing?** Concurrency, partial writes, retries, network blips, auth failures, rate-limit collisions, clock skew. Name the top 1–2 that the spec doesn't address.
-5. **What dependencies does this introduce?** New runtime dep? New infra (Redis, queue, cron)? Document it. New deps that aren't named in the spec are the #1 source of mid-implementation surprise.
-6. **Test plan adequate?** A test plan that says "tests added" is not a plan. Look for: unit, integration, manual reproduction, performance (when relevant).
-
-## Output format
-
-```
-verdict: pass | fail
-notes: 2–4 sentences + (when applicable) a short ASCII data flow / state diagram.
-       If pass, name the most load-bearing architectural choice.
-       If fail, name the SINGLE biggest gap and how to close it.
-```
-
-## Examples
-
-**Pass with diagram:**
-
-```
-verdict: pass
-notes: Token-bucket per IP with 5-minute Redis TTL is the right call — survives restarts, no GC pressure, easy to extend to user-id keys later. The spec correctly limits scope to /auth (no /api yet). One missing edge: clock-skew between Node process and Redis on bucket refill — recommend storing absolute timestamps server-side.
-
-   request → middleware → Redis GETSET (token, ts)
-                            ├── allowed → next()
-                            └── refused → 429 + Retry-After
-```
-
-**Fail:**
-
-```
-verdict: fail
-notes: Spec references "real-time updates" in acceptance_criteria but is silent on transport (WebSocket? SSE? polling?). Each has different failure modes (reconnect storms, head-of-line blocking, server load). Pick one explicitly and re-spec — current acceptance criteria are vacuously true for a 60-second polling loop, which probably isn't what the user wants.
-```
-
-## Anti-patterns to refuse
-
-- Architectural cosplay: "consider using DDD/hexagonal/CQRS" without showing why this spec demands it.
-- Failing because "the spec doesn't say which framework" when framework is obvious from the project's stack (skill body's project context tells you).
-- Skipping the data flow trace — the most useful thing this rubric produces.

package/templates/spec-reviewer-rubrics/design.md

@@ -1,38 +0,0 @@
-# Design reviewer rubric — `audit-spec`
-
-You are reviewing a `prjct` spec for design quality (UX for user-facing surfaces, DX for developer-facing surfaces — same rubric, different surface).
-
-## Questions to ask
-
-Rate each dimension 0–10 against the spec's described surface (UI, API, CLI, library):
-
-1. **Clarity** — would a new user / developer know what this does without reading code or docs? 0 = inscrutable; 10 = self-documenting.
-2. **Ergonomics** — is the common case fast and the rare case possible? 0 = forces the rare case into every flow; 10 = invisible until needed.
-3. **Consistency** — does it match the surrounding system's conventions? 0 = a foreign body; 10 = indistinguishable from neighboring features.
-4. **Accessibility** — for UI: keyboard / screen-reader / contrast / motion. For API/CLI: discoverability, error messages, --help, machine-readable output. 0 = unusable for entire categories of users; 10 = enables everyone.
-
-## Verdict rule
-
-- All four dimensions ≥ 6 → `pass`.
-- Any dimension < 6 → `fail`.
-
-## Output format
-
-```
-verdict: pass | fail
-notes: clarity=N ergonomics=N consistency=N accessibility=N
-       Lowest-scoring dimension first, with the SINGLE concrete change that would raise it.
-```
-
-## Examples
-
-**Pass:** "clarity=8 ergonomics=7 consistency=9 accessibility=6. Lowest is accessibility — the new endpoint returns errors as JSON only; recommend adding `Accept: text/plain` fallback for grep-the-pipeline operators. Otherwise the surface matches the existing `/api/v2` shape and ergonomics are right (single required field, sensible defaults)."
-
-**Fail:** "clarity=4 ergonomics=6 consistency=7 accessibility=7. Clarity tanks because the verb name `prjct shimmer` doesn't telegraph the action; rename to `prjct refresh` or `prjct rebuild` and re-rate. Other dimensions are healthy."
-
-## Anti-patterns to refuse
-
-- Vague "looks good" — every dimension needs a number.
-- Ignoring accessibility for "internal tools" — internal users include the colorblind and the blind.
-- Failing on aesthetic taste alone (color, typography). Design rubric is about USE, not opinion.
-- Over-indexing on novelty. Surfaces that surprise users score LOW on consistency, not high.