prjct-cli 3.47.0 → 3.48.0

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.

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

@@ -1,32 +0,0 @@
-# Strategic reviewer rubric — `audit-spec`
-
-You are reviewing a `prjct` spec for strategic soundness. You receive the spec body verbatim. Apply the questions below; return a single structured verdict.
-
-## Questions to ask
-
-1. **Is the goal real?** Does this solve a problem the user (or org) actually has? Or is it a tools-team-flavored solution looking for a problem?
-2. **Is the goal worth the cost?** Crude estimate of build cost vs. impact. If goal is small but cost is large, fail.
-3. **Is `out_of_scope` coherent with `goal`?** Goal that says "fix onboarding" with `out_of_scope: ["welcome email", "first-login flow"]` — what's left? Fail if scope evaporates the goal.
-4. **Is the spec OVER-scoped?** Trying to ship a quarter's work in one PR. Boil-the-lake principle says completeness is cheap when it costs minutes — fail when it costs months.
-5. **Is the spec UNDER-scoped?** Acceptance criteria so narrow that shipping doesn't move the needle. Fail when meeting all criteria still leaves the user's problem unsolved.
-6. **Are stakes honest?** "Users will be frustrated" is too vague. "Auth fails for 3% of sessions during peak load" is testable.
-
-## Output format
-
-```
-verdict: pass | fail
-notes: 2–4 sentences. If pass, name the strongest framing element. If fail, name the SINGLE
-       biggest gap and how to close it.
-```
-
-## Examples
-
-**Pass:** "Goal is concrete (sub-200ms p95 on dashboard) and the stakes are measurable (lost engagement on slow widgets). Scope and out_of_scope draw a clean line. The strongest element is the explicit 'no caching layer in this PR' — that's the right anti-creep."
-
-**Fail:** "Goal says 'improve auth UX' but acceptance_criteria all measure backend latency. Either rewrite the goal (this is a perf spec, not UX) or rewrite the criteria (add a usability metric). Currently the spec would pass review on a perf change that didn't move UX at all."
-
-## Anti-patterns to refuse
-
-- Praising the spec without naming a strength (`pass: looks good!` — useless).
-- Failing without proposing a fix (the next iteration of the spec needs a path forward).
-- Auto-failing because the spec is "ambitious" — strategic review measures soundness, not size.

package/templates/spec-template.md

@@ -1,97 +0,0 @@
-# Spec template — `prjct spec`
-
-A spec frames a piece of work BEFORE implementation. Cheap to write, cheap to revise; un-doing implementation isn't.
-
-The fields below match `core/types/spec.ts`. Validation is enforced by Zod at write time.
-
----
-
-## Title (one line)
-
-What you'd say to a coworker walking by your desk.
-
-## Goal (1–3 sentences)
-
-What success looks like. Concrete. Observable.
-
-## ELI10 (2–4 sentences)
-
-Plain English a 16-year-old could follow. Forces you to articulate why this matters without jargon.
-
-## Stakes if we ship the wrong thing (1 sentence)
-
-What breaks. Who notices. How fast.
-
-## Acceptance criteria (testable, observable list)
-
-Each line is a sentence ending in a verifiable claim:
-
-- the new endpoint returns 429 after the 11th request in a minute from the same IP
-- the dashboard widget renders within 200ms p95 on a synthetic 4G profile
-- `prjct spec audit <id>` blocks if any reviewer returns `fail`
-
-Anti-patterns:
-
-- "the system should be fast" — what threshold, measured how?
-- "users will love it" — not testable
-- "follow industry best practices" — what specifically?
-
-## Scope (what's IN)
-
-The pieces this spec commits to. Be specific about file paths, surfaces, modules.
-
-## Out of scope (what's OUT)
-
-The pieces this spec explicitly DOES NOT cover. This is your anti-creep shield mid-implementation.
-
-## Risks
-
-Each risk has a mitigation. A risk without a mitigation is just a complaint.
-
-- **risk:** legacy endpoints rely on the same rate-limit middleware → **mitigation:** scope key separates `/auth` from `/api`
-- **risk:** Redis dependency raises ops cost → **mitigation:** start with in-memory token bucket; swap to Redis only above 5 RPS
-
-## Test plan
-
-How you'll prove the acceptance criteria. Includes the unhappy path.
-
-- unit tests for the token bucket math
-- integration test: 11 requests, 11th returns 429
-- load test: 100 RPS sustained for 60s, no memory growth
-- manual: trigger via `curl` and inspect response headers
-
-## Notes (optional)
-
-Things that don't fit anywhere else but matter for context.
-
----
-
-## Lifecycle
-
-```
-draft  →  reviewed  →  in_progress  →  shipped
-                                    →  archived
-```
-
-- `draft` — created, not yet audited.
-- `reviewed` — `prjct audit-spec` returned pass on all three reviewers.
-- `in_progress` — at least one task with `linked_spec_id` exists.
-- `shipped` — code merged, criteria met (or override accepted).
-- `archived` — superseded or abandoned.
-
-## Verb cheatsheet
-
-```
-prjct spec "<title>"                       # draft — NO `draft` subverb, pass title directly
-prjct spec list [--status <s>]
-prjct spec show <id>
-prjct spec update <id> --json '{...}'      # PATCH content (shallow merge)
-prjct spec audit <id>                      # emit subagent dispatch
-prjct spec record-review <id> --reviewer <name> --verdict <pass|fail> --notes "..."
-prjct spec link-task <id> --task-id <task>
-prjct spec ship <id> [--pr <n>]
-prjct spec set-status <id> --status archived
-prjct spec inventory [--md|--json]         # coverage map per module
-```
-
-> **No `draft` subverb.** `prjct spec "<title>"` already creates a draft. The CLI tolerates `prjct spec draft|new|create "<title>"` as friendly aliases (the leading word is stripped) so `prjct spec draft "rate limiting"` and `prjct spec "rate limiting"` produce the same spec — but the canonical form has no leading verb.