prjct-cli 2.14.2 → 2.15.0

package/templates/spec-template.md

@@ -0,0 +1,94 @@
+# 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
+prjct spec list [--status <s>]
+prjct spec show <id>
+prjct spec update <id> --json '{...}'      # replace content
+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
+```