@gobing-ai/spur 0.3.40 → 0.3.42

package/plugins/sp/skills/reverse-engineering/agents/openai.yaml

@@ -0,0 +1,18 @@
+name: reverse-engineering
+description: "Codebase reverse-engineering, High-Level Design (HLD) generation,
+  design reconstruction, and critical issue audit. Use when analyzing
+  unfamiliar codebases, generating architecture or design documentation,
+  auditing code quality, onboarding new developers, or assessing technical
+  debt. Supports depth modes briefing, structure, architecture, design, and
+  full with separate focus and format controls."
+version: 1.1.0
+icon: 🔍
+category: debugging
+tags:
+  - analysis-core
+  - reverse-engineering
+  - hld
+  - audit
+  - codebase-analysis
+  - architecture
+  - design

package/plugins/sp/skills/source-driven-development/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: source-driven-development
+description: "Verify framework / API / library facts against primary sources before generating code, and separate \"the API exists\" from \"I used it correctly under its contract.\" The single sp owner of source-first verification. Triggers: \"check the docs first\", \"verify this API\", \"source-first\", \"is this the real signature\"."
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  category: execution
+  interactions:
+    - technique
+  operations:
+    - verify-source
+  openclaw:
+    emoji: "📚"
+see_also:
+  - sp:code-implementation
+  - sp:doubt-driven-development
+  - sp:code-verification
+---
+
+# source-driven-development — the source-first verification competency
+
+Do not generate code from memory of an API. Before you call a framework function, pass an option, or
+rely on a library behavior, **verify it against the primary source** — the official docs for the
+pinned version, the type signature, the actual source. Memory is a cache that goes stale silently;
+the primary source is the contract.
+
+This skill is the **single sp owner** of source-first verification. Where sp workflows previously
+delegated fact-checking to an external `cc:anti-hallucination` skill, that procedure now lives here,
+in sp's own vocabulary — one authority, no duplicated procedure. Other sp skills (e.g. `brainstorm`)
+delegate verification to `sp:source-driven-development`; they do not restate the protocol.
+
+## The two questions (do not conflate them)
+
+Every use of an external API answers **two** independent questions. Confusing them is the core error:
+
+1. **Does the API exist?** — Is `foo.bar(x)` a real function with that signature in this version?
+   A hallucinated method compiles in your head and fails at runtime.
+2. **Am I using it correctly under its contract?** — Even a real API has preconditions, ordering
+   rules, error modes, and edge cases. "It exists" does not mean "I called it right."
+
+Source-first verification must satisfy **both**. A confirmed-existing API used against its contract
+is still a bug.
+
+## When to use
+
+- Before generating code against a framework / library / API you are not certain of **for the pinned
+  version** — signatures, option names, return shapes, error behavior.
+- When behavior is **version-specific** and you are recalling it from memory (state the version).
+- When a build/runtime error suggests the API does not behave as you assumed.
+- Reconciling a claim about an external system before it becomes load-bearing in a design.
+
+Do **not** use this skill for:
+
+- **Your own code's correctness** — that is `sp:code-verification` (requirements/AC) and `sp:code-review`.
+- **Stress-testing a design decision** — that is `sp:doubt-driven-development` (artifact vs contract).
+- **Well-known, version-stable stdlib** you can state with HIGH confidence — verification has a cost;
+  spend it where being wrong is likely and expensive.
+
+## The process
+
+### Step 1 — Classify your confidence before you write
+
+| Level | Meaning | Action |
+|---|---|---|
+| **HIGH** | Verified against the pinned version's docs/source **this session** | Generate; cite the source inline |
+| **MEDIUM** | Recalled from a prior session; plausibly stale | Verify before relying on it |
+| **LOW** | Memory only, no source in hand | Stop — verify first; never present as fact |
+
+If you cannot honestly claim HIGH for a version-specific behavior, you are at MEDIUM or LOW — verify.
+
+### Step 2 — Go to the primary source, in priority order
+
+1. The **type signature / source** in the installed, pinned dependency (the ground truth for *this* build).
+2. The **official docs for the pinned version** (not the latest — the version in the lockfile).
+3. Authoritative references when docs are thin.
+4. Memory — **LOW only**, and never as the final authority.
+
+State the **version** inline whenever behavior is version-specific.
+
+### Step 3 — Verify both questions
+
+- **Existence:** the signature matches — name, arity, parameter names, return type.
+- **Contract:** preconditions, call ordering, error/exception modes, null/empty edge cases, and any
+  documented caveats are accounted for in how you call it.
+
+### Step 4 — Cite, then generate
+
+Generate the code and **cite the source** (doc URL + date, or `pkg@version` + the file/symbol) at the
+point of use or in the task's notes. A claim about external behavior without a citation is
+unverified — flag it as such rather than presenting it as fact.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I've used this API a hundred times — I know the signature." | APIs change across versions and your memory is a silent cache. Verify against the *pinned* version; recall is MEDIUM at best. |
+| "It compiled, so I used it right." | Compiling proves existence and types, not contract. Ordering, preconditions, and error modes are not checked by the compiler. |
+| "The latest docs say so." | You ship against the *pinned* version, not latest. Read the docs for the version in the lockfile. |
+| "Close enough — I'll fix it if it breaks." | Guessing at an external contract moves the cost to runtime/production. Verify before generating; it is cheaper here. |
+| "Verifying every call is too slow." | Verify what you are *not sure of*, at the confidence level you honestly hold. HIGH needs no re-check; LOW always does. |
+
+## Red Flags
+
+- Generating version-specific code you would rate MEDIUM or LOW confidence, without opening a source.
+- Presenting an API claim as fact with no citation (doc + date, or `pkg@version` + symbol).
+- Treating "it exists" as proof it is used correctly (the two questions collapsed into one).
+- Reading the *latest* docs for a dependency pinned to an older version.
+- Recalling behavior "from memory" for a security-, money-, or data-integrity-sensitive call.
+- Duplicating this protocol inside another skill instead of delegating to `sp:source-driven-development`.
+
+## Verification
+
+- [ ] Every version-specific external behavior relied on was checked against the pinned version's source/docs **this session**.
+- [ ] Both questions answered — the API exists **and** is called within its contract.
+- [ ] Claims about external behavior carry a citation (source + date, or `pkg@version` + symbol); unverifiable ones are flagged, not asserted.
+- [ ] Confidence is stated honestly (HIGH/MEDIUM/LOW); nothing at LOW was presented as fact.
+
+## See also
+
+- **`sp:code-implementation`** — consumes this discipline before generating code against an external API.
+- **`sp:doubt-driven-development`** — stress-tests *your* artifact vs its contract; this skill verifies *external* facts vs their source.
+- **`sp:code-verification`** — verifies your finished code against requirements/AC (a different authority than source-first).

package/plugins/sp/skills/spec-decomposition/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: spec-decomposition
+description: "The decomposition competency — turn a validated feature into a well-formed task batch passing task-batch.schema.json: scenario-to-task mapping, template variants, sizing. Triggers: \"decompose this\", \"break into tasks\", \"task batch\", \"create tasks from this feature\", \"split this work\"."
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  interactions:
+    - technique
+  competency: decomposition
+  openclaw:
+    emoji: "🧩"
+---
+
+# spec-decomposition — the decomposition competency
+
+Turn a validated feature (Goal, Scope, acceptance criteria) into a **well-formed task batch** that
+the CLI accepts. This is the deep competency the spine (`sp:spur-dev`) dispatches
+**before** execution — it owns *how to decompose well* (scenario→task mapping, sizing, variant
+selection), distinct from the spine which decides *when* to decompose and runs the gate.
+
+Decomposition is a precondition of execution: a task must be decomposed before
+`sp:code-implementation` can build it. This skill produces the batch JSON; the CLI's
+`task-batch.schema.json` gate validates it; `spur task batch-create` lands it atomically (all-or-nothing).
+
+## When to use
+
+- **Feature → tasks** — a feature with acceptance criteria exists; produce its task batch.
+- **Break down work** — split a large requirement into dependency-ordered, right-sized subtasks.
+- **Size a task** — decide whether a task is one deliverable or should split (the granularity standard).
+- **The planning half's decompose step** — the spine dispatches here after `feature check` passes.
+
+Do **not** use this skill for:
+
+- **Authoring the feature / acceptance criteria** — that is the spine's planning half + the AC style
+  guide (`sp:spur-dev`'s `ac-style-guide.md`), which this skill *consumes*.
+- **Implementing / testing / reviewing a task** — those are `sp:code-implementation`,
+  `sp:code-testing`, `sp:code-verification`.
+- **Driving the lifecycle / running the gate** — that is the spine, `sp:spur-dev`.
+
+## Behavior
+
+This skill behaves as a **technique**: given a feature's AC, it maps each `@core` scenario to a task
+(one R-number = one task spine), sizes each by the granularity standard, selects the template variant,
+orders by dependency, and emits the batch JSON — then hands it to the CLI gate. It writes **nothing**
+directly: `task-batch.schema.json` validates and `spur task batch-create --file <json>` writes
+atomically (a single schema violation rejects the whole batch).
+
+Full procedure: **[references/decomposition.md](references/decomposition.md)** — the
+`task-batch.schema.json` contract, template-variant selection, scenario-to-task mapping, the
+granularity knobs (min/target/force-split hours), and parent/umbrella-task conventions.
+
+## The gate
+
+```bash
+spur task batch-create --file decomposition.json   # bare JSON array; atomic, all-or-nothing
+```
+
+Validate locally against `apps/cli/schemas/task-batch.schema.json` (runtime SSOT: the Zod
+`taskBatchSchema`) before invoking the CLI — a single violation rejects the entire batch. The gate is
+the only proof the decomposition is well-formed; never hand-write task files to bypass it.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "One big task is simpler than splitting it." | An undifferentiated task can't be independently verified or reviewed. Split into vertical slices, each demoable on its own. |
+| "Layer tasks (all-schema, all-UI) are cleaner." | Horizontal layer-tasks are a named anti-pattern: none is shippable alone. Slice vertically through the layers, per behavior. |
+| "The parent task will implement the shared part." | A parent implements nothing itself — it's the abstraction over its children. Shared work is a child task, not parent body. |
+| "Skip per-task AC; the feature AC covers it." | A task with no AC has no verify gate. Every task carries the scenario(s) it satisfies, or it can't be closed honestly. |
+| "This is one concern — don't over-decompose." | Under-decomposition hides multiple review lenses in one diff. If it needs more than one AC or more than ~a day, it's more than one task. |
+
+## Red Flags
+
+- A task that can't be stated as an independently verifiable vertical slice.
+- Tasks named by layer (`schema`, `API`, `UI`) rather than by behavior.
+- A parent task with body work instead of a roster of children.
+- A task with zero acceptance criteria.
+- A batch where every task depends on every other (no real slicing).
+
+## Gotchas
+
+1. **Decomposition precedes execution.** A task must be decomposed and batch-created before
+   `sp:code-implementation` runs. This skill's output is the input to the execution half.
+2. **Batch-create is atomic.** One schema violation rejects everything — validate locally first.
+3. **AC titles are the traceability key.** Map tasks to AC by scenario title (R-prefix stripped on
+   match); a renamed scenario after batch-create breaks coverage.
+4. **Size by the standard, not by feel.** Sizing has two dimensions, applied in order: **cohesion
+   first** — work that edits the same files or shares a review context is one task even when the
+   hours would permit a split (ceremony cost is per-task); **then the granularity knobs** in
+   `decomposition.md` (`min_hours` / `target_*` / `force_decompose_above_hours`) bound how large a
+   single cohesive task may get before a size-driven split overrides cohesion. Both dimensions,
+   with the H8 worked example, are in `decomposition.md` → "Granularity — two dimensions".
+5. **Cut vertical, not horizontal.** Every task is a thin slice through all the layers a scenario
+   touches, independently demoable on its own — never an all-schema/all-API/all-UI layer-task.
+   Prefactoring (making the change easy) is its own task, ordered first. Full doctrine, worked
+   wrong-vs-right example, and the pre-batch-create HITL quiz gate: `decomposition.md`.
+
+## See also
+
+- **`sp:spur-dev`** — the spine that dispatches this competency at the decompose step and runs the
+  `batch-create` gate; owns the AC style guide this skill consumes.
+- **`sp:code-implementation`** — builds the tasks this skill produces (decomposition is its precondition).
+
+## Platform Notes
+
+### Claude Code
+
+Invoked by the spine's planning half (the decompose step), or directly via
+`Skill(skill="sp:spec-decomposition", args="<feature-id>")`. Validate the batch JSON and run
+`spur task batch-create` via the Bash tool.
+
+### Codex / OpenClaw / OpenCode / Antigravity
+
+Invoke this skill directly for decomposition technique; run `spur task batch-create` via the Bash
+tool. The skill is the SSOT for the method; the CLI gate is the validator.