Cursor plugin specification and official plugins
TypeScript
pstack: architect usage-first design (caller's usage as the spec) (#99)
lauren0fe5b8a0952f
diff --git a/pstack/skills/architect/SKILL.md b/pstack/skills/architect/SKILL.mdindex ba5ab6f4..37854ac2 100644--- a/pstack/skills/architect/SKILL.md+++ b/pstack/skills/architect/SKILL.md@@ -28,7 +28,7 @@ Skip Phase A only when the work is genuinely greenfield with no surrounding syst## Phase B: Sketch-Run the **arena** skill with the design-sketch task and the Phase A grounding artifacts as input. Pass `references/runner-prompt.md` as each runner's prompt. Each candidate produces a design package shaped per `references/rationale-template.md`: type sketch, function signatures, module map, and prose rationale.+Run the **arena** skill with the design-sketch task and the Phase A grounding artifacts as input. Pass `references/runner-prompt.md` as each runner's prompt. Each candidate produces a design package shaped per `references/rationale-template.md`: the caller's usage written first, then the type sketch, function signatures, module map, and prose rationale derived from it.Use these slugs for the Phase B runners: `claude-opus-4-7-thinking-xhigh`, `gpt-5.3-codex-high-fast`, `gpt-5.5-high-fast`, and `composer-2.5-fast`.@@ -76,4 +76,4 @@ When you do scrap:## Outputs-One file with new types and signatures for small changes; the module map plus type definitions for larger work. The rationale ships alongside, shaped per `references/rationale-template.md`, including the synthesis decision.+The caller's usage is written first and the type sketch derived from it. One file with new types and signatures for small changes; the module map plus type definitions for larger work. The rationale ships alongside, shaped per `references/rationale-template.md`, including the usage sketch and the synthesis decision.diff --git a/pstack/skills/architect/references/rationale-template.md b/pstack/skills/architect/references/rationale-template.mdindex bd2bba36..809fcf8f 100644--- a/pstack/skills/architect/references/rationale-template.md+++ b/pstack/skills/architect/references/rationale-template.md@@ -6,6 +6,10 @@ This is the prose that ships alongside the type sketch. One page. Sentence-case*One paragraph. What we're trying to do, and what about the existing system or constraints makes the shape non-obvious. If [Phase A](../SKILL.md#phase-a-ground-the-problem) surfaced constraints the design now has to honor (existing types we have to interop with, callers we can't break, invariants that crossed our boundary), name them here so the reader sees the same constraints you saw.*+## Usage (caller's view)++*Write this first, before the type sketch. Show the README or quickstart the consumer reads, plus two or three realistic call sites in their own code. What they import, what they call, what comes back. The type sketch in [Shape](#shape) is derived from this. The two must agree, so when they diverge, reconcile the sketch to the usage, not the reverse. The caller's experience is the spec. The types serve it.*+## Shape*The recommended architecture. Data structures first; then how data flows through the signatures. Name the load-bearing decisions: which invariants are encoded in types, where validation lives, what the system deliberately does not do. Cite the principle behind each decision (e.g., `per boundary-discipline`); don't restate it.*diff --git a/pstack/skills/architect/references/runner-prompt.md b/pstack/skills/architect/references/runner-prompt.mdindex fbc4dad6..f9c59db9 100644--- a/pstack/skills/architect/references/runner-prompt.md+++ b/pstack/skills/architect/references/runner-prompt.md@@ -6,6 +6,7 @@ You are producing one candidate design as part of architect's parallel exploratiApply the following discipline. The orchestrator compares candidates on these axes and uses them to pick a base.+- Caller's usage first. Write the README-style usage and two or three real call sites before the types, then derive the type sketch from them. The usage is the spec, and the two must agree, so reconcile the sketch to the usage, not the reverse.- Data structures first. Get the core types right and the code becomes obvious. Trace each dominant access pattern through the proposed structure; if the answer is "we'll add a map / index / cache later," the structure is wrong.- Shared state: if two actors might both write, ask "what happens?" If the answer isn't "nothing," default to per-actor state with a merge at the read boundary, per the **separate-before-serializing-shared-state** principle skill.- Make boundaries visible. `not implemented` errors for bodies, `// TODO` pseudocode for tricky logic, doc comments stating intent and invariants. A reader should trace data from input to output by reading types and signatures alone.