@gobing-ai/spur 0.3.78 → 0.3.81

package/plugins/sp/skills/taste-refactoring-api/references/api-refactoring-playbook.md

@@ -0,0 +1,253 @@
+# API Refactoring — Operational Playbook
+
+This playbook is a practical synthesis of established API standards and widely used design guidance. It is not tied to one vendor or architectural style.
+
+## 1. Start from the consumer job
+
+Before naming endpoints, write the job a caller is trying to complete. Good APIs optimize the caller’s mental model, not the server’s package structure.
+
+Questions:
+- What must the caller know before invoking this operation?
+- What is the smallest successful outcome?
+- What failures can the caller actually recover from?
+- What parts of the workflow are synchronous vs asynchronous?
+- Which data belongs in one consistency boundary?
+
+## 2. Model stable domain concepts
+
+Prefer stable nouns/types with durable identifiers. Do not expose internal database tables, ORM entities, queue names, deployment topology, or microservice ownership unless those are themselves the public domain.
+
+Refactoring signal: if a database rename forces an API rename, the contract is too coupled to storage.
+
+## 3. Prefer protocol-native semantics
+
+### HTTP
+Use method semantics and status codes as intended. RFC 9110 defines safe methods and idempotent methods; the retry characteristics of operations should align with those semantics.
+
+### RPC / gRPC
+Use explicit request/response messages, canonical status codes, deadlines, and predictable method naming. Treat semantic compatibility separately from wire compatibility.
+
+### GraphQL
+Use the schema/type system as the contract. Field names, nullability, input types, pagination, and deprecation are all compatibility decisions.
+
+### Events/webhooks
+Treat event type, envelope, delivery guarantees, ordering, retries, and deduplication as the contract.
+
+## 4. Resource-oriented by default, actions when necessary
+
+For resource APIs, model collections and resources first. Standard operations should handle the majority of use cases. Use custom actions when intent does not fit create/get/list/update/delete semantics cleanly.
+
+Example:
+- Prefer `POST /orders` over `POST /createOrder`.
+- Prefer `POST /orders/{id}:cancel` or a cancellation subresource over inventing an unsafe `GET /cancelOrder?id=...`.
+
+Custom actions are not inherently bad; arbitrary inconsistency is.
+
+## 5. Make schemas explicit
+
+Define:
+- required vs optional;
+- nullable vs absent;
+- default behavior;
+- value constraints;
+- enum semantics and unknown-value strategy;
+- identifiers and formats;
+- timestamps/time zones;
+- money/decimal representation;
+- read-only vs write-only/server-generated fields.
+
+Avoid generic maps/JSON blobs unless open-ended data is truly part of the domain.
+
+## 6. Design partial update deliberately
+
+A partial update needs an explicit model for:
+- omitted field = unchanged?
+- null = clear value, invalid, or unchanged?
+- empty collection = clear all or no change?
+- nested object = merge or replace?
+
+For HTTP, choose and document a patch format rather than relying on framework deserialization quirks.
+
+## 7. Collections need contracts too
+
+For any collection that can grow:
+- paginate from day one;
+- define deterministic ordering;
+- bound page size;
+- prefer opaque cursors/tokens when traversal must remain stable and implementation-flexible;
+- document filter and sort grammar;
+- decide whether total counts are exact, estimated, expensive, or omitted;
+- define what happens if items are inserted/deleted between pages.
+
+Adding pagination later can be behaviorally breaking because existing clients may assume a full collection response.
+
+## 8. Errors should be actionable
+
+An error contract should answer:
+- What category of failure occurred?
+- Is the request malformed, unauthenticated, unauthorized, conflicting, rate limited, temporarily unavailable, or permanently invalid?
+- Which field/value is wrong?
+- Can the caller retry? When?
+- What stable code/type can software branch on?
+
+For new HTTP APIs, RFC 9457 Problem Details is a strong standard envelope when it fits the ecosystem.
+
+Do not expose stack traces, SQL messages, internal hostnames, secrets, or raw downstream errors.
+
+## 9. Design for retries
+
+Network ambiguity means the client may not know whether a mutation succeeded.
+
+Use one or more of:
+- naturally idempotent methods/operations;
+- client-chosen resource IDs;
+- idempotency keys for retry-safe creation/action requests;
+- deduplication records keyed by caller + idempotency key + request fingerprint;
+- operation resources for asynchronous work.
+
+If using an `Idempotency-Key` header, note that the IETF specification is still an Internet-Draft as of this skill’s research date, so treat the exact standardization status accordingly.
+
+## 10. Handle concurrent writes explicitly
+
+When lost updates matter, use optimistic concurrency:
+- HTTP ETag + `If-Match`;
+- resource revision/version fields;
+- compare-and-set preconditions.
+
+A failed precondition should be distinguishable from malformed input.
+
+## 11. Long-running work should look long-running
+
+If work can exceed normal request latency or has meaningful progress/cancellation:
+- return an accepted/operation response quickly;
+- expose operation status;
+- make polling bounded and cache-friendly where possible;
+- support cancellation if useful;
+- define terminal success/failure shape;
+- separate operation identity from resulting resource identity.
+
+## 12. Evolve additively
+
+Prefer:
+- add optional request fields;
+- add response fields that tolerant clients ignore;
+- add new operations;
+- add a new version only for true contract breaks.
+
+Be cautious with:
+- enum expansion for generated/exhaustive clients;
+- changing defaults;
+- narrowing validation;
+- changing sort order;
+- changing error identities;
+- changing nullability;
+- switching sync operations to async without migration.
+
+## 13. Deprecate with evidence
+
+A deprecation needs:
+- replacement behavior;
+- deprecation date;
+- target removal date or policy;
+- usage telemetry;
+- owner/contact path;
+- migration examples;
+- client communication.
+
+Do not keep every version forever, but do not remove based on guesses.
+
+## 14. Security is deeper than authentication
+
+Use OWASP API Security Top 10 as a recurring review lens.
+
+Core checks:
+- authorize the specific object referenced by every client-controlled ID;
+- authorize individual properties on read/write when sensitivity differs;
+- avoid mass assignment by whitelisting writable fields;
+- bound expensive operations and collection sizes;
+- guard business-critical flows against automation/abuse;
+- validate outbound fetch URLs and network destinations to reduce SSRF risk;
+- inventory old hosts/versions/shadow APIs;
+- treat downstream APIs as untrusted inputs and validate their data too.
+
+## 15. Observability is a client feature
+
+A diagnosable API should provide or propagate request/trace identity and make server telemetry correlate with client-visible failures.
+
+Useful operational dimensions:
+- operation/route/method;
+- status/error type;
+- latency;
+- request/response size;
+- client/application identity where allowed;
+- retries/timeouts;
+- throttling/quota events;
+- downstream dependency failures.
+
+Never put secrets or sensitive payloads in logs by default.
+
+## 16. Documentation should be testable
+
+For contract-first or contract-documented APIs:
+- validate OpenAPI/GraphQL/protobuf/AsyncAPI-like definitions in CI;
+- lint naming and requiredness;
+- validate examples;
+- generate compatibility diffs;
+- run consumer/contract tests;
+- fail builds on undocumented public endpoints if the organization requires spec completeness.
+
+The OpenAPI Initiative currently publishes OAS 3.2.0 and 3.1.x. Choose a version your tooling supports; do not upgrade a spec version only for fashion.
+
+## 17. Protocol-specific notes
+
+### REST/HTTP quick rules
+- nouns/resources in paths by default;
+- no state change on `GET`;
+- precise status codes;
+- `Location` for newly created resources when useful;
+- conditional requests for concurrency/cache validation;
+- clear content types;
+- RFC 9457-style errors when appropriate.
+
+### gRPC quick rules
+- explicit request/response messages;
+- deadlines propagated;
+- canonical status codes;
+- idempotency/retry documented;
+- streaming only when interaction needs it;
+- reserve removed protobuf field numbers/names;
+- do not reinterpret existing fields silently.
+
+### GraphQL quick rules
+- product/domain schema, not service topology;
+- strong types over JSON blobs;
+- nullability is a guarantee;
+- input objects for evolvability;
+- cursors/connections for large lists;
+- deprecate before removal;
+- query complexity and authorization at resolver/field boundaries.
+
+### Event/webhook quick rules
+- stable event IDs and types;
+- versioning strategy;
+- explicit at-least-once/ordering semantics;
+- dedup guidance;
+- signatures + replay protection;
+- additive payload evolution.
+
+## 18. Daily refactoring sequence
+
+When reviewing an API every day, use this order:
+1. consumer job;
+2. domain model;
+3. semantics;
+4. naming/schema;
+5. collections;
+6. errors;
+7. retries/concurrency;
+8. compatibility;
+9. security;
+10. observability/performance;
+11. docs/tests.
+
+Fix the earliest broken layer first. Cosmetic naming polish should not distract from a confused domain model or unsafe mutation semantics.

package/plugins/sp/skills/taste-refactoring-api/references/protocol-modes.md

@@ -0,0 +1,79 @@
+# Protocol-specific API review
+
+## REST/HTTP mode
+
+### Resource design
+- Prefer noun-based resource paths for domain entities and collections.
+- Use nesting when it communicates true ownership or scope; avoid deep path trees that mirror storage.
+- Keep canonical IDs stable even if names or hierarchy labels change.
+- Use custom action endpoints only when standard resource operations cannot express the intent cleanly.
+
+### HTTP methods
+- `GET` and `HEAD` are read-oriented and safe; do not hide state-changing behavior behind them.
+- `PUT` should represent full replacement/upsert semantics where the client addresses the target and repeated identical requests have the same intended effect.
+- `PATCH` should define a clear patch model; do not leave null/omitted/reset semantics ambiguous.
+- `DELETE` should be idempotent in intended effect; define repeated-delete behavior consistently.
+- `POST` is appropriate for creation under a collection and non-idempotent/custom actions; add idempotency support when safe retries are required.
+
+### Status codes
+Use status codes as protocol semantics, not decorative metadata. Favor the narrowest standard code that tells generic clients what happened. Common distinctions include:
+- `200` successful response with content;
+- `201` resource created, normally with a discoverable resource location;
+- `202` accepted for asynchronous processing;
+- `204` successful response without representation;
+- `304` conditional request not modified;
+- `400` malformed/invalid request when no more specific code applies;
+- `401` missing/invalid authentication;
+- `403` authenticated but not permitted;
+- `404` target not found, including intentionally concealed unauthorized resources where appropriate;
+- `409` state conflict;
+- `412` failed precondition for conditional mutation;
+- `413` request content too large;
+- `415` unsupported media type;
+- `422` syntactically valid content that cannot be processed under the API’s validation semantics, when this distinction is useful;
+- `429` rate limited;
+- `5xx` server-side inability to fulfill an otherwise valid request.
+
+Do not create application-defined pseudo-status codes outside the HTTP status space.
+
+### Error representation
+For HTTP APIs, prefer a consistent machine-readable error envelope. RFC 9457 Problem Details is a strong default for new APIs when it fits the ecosystem. Keep problem `type`/application error identity stable, include actionable detail, and attach structured extensions only when clients need them.
+
+### Conditional requests and concurrency
+For mutation races, prefer explicit optimistic concurrency such as ETags / `If-Match`, version fields, or revision tokens. Do not silently implement last-write-wins when lost updates would matter.
+
+## RPC / gRPC mode
+
+- Prefer a small predictable set of standard methods for resource-oriented services before custom RPCs.
+- Keep request/response messages explicit even when they currently contain one field; this preserves room to evolve.
+- Use canonical status codes consistently; do not tunnel all errors through `UNKNOWN`/`INTERNAL`.
+- Propagate deadlines. A server should know when a caller no longer cares about work.
+- Define retry behavior only for operations that are safe to retry; coordinate with service config/client retry policies.
+- Use streaming when it matches interaction semantics, not merely to avoid pagination.
+- Avoid reusing a protobuf field number after removal; reserve removed numbers/names where appropriate.
+- Prefer additive field evolution and treat semantic reinterpretation as a breaking change even when wire compatibility remains.
+
+## GraphQL mode
+
+- Design the schema around consumer-facing domain concepts and product workflows, not backend services.
+- Prefer clear field names and strong types over generic `JSON` blobs.
+- Treat nullability as a compatibility contract; tightening nullability can break clients and loosening it changes guarantees.
+- Use input object types for evolving argument sets.
+- Prefer connection/cursor pagination for unbounded collections when clients need stable traversal.
+- Put side effects in mutations and name mutations by domain intent.
+- Deprecate fields/arguments/input fields/enum values with reasons before removal; measure usage where possible.
+- Prevent abusive query cost with depth/complexity/breadth controls, pagination limits, timeouts, and resolver-level authorization.
+- Avoid N+1 resolver behavior with batching/data-loader patterns or equivalent backend aggregation.
+- Remember that GraphQL errors can coexist with partial data; define which errors are expected domain outcomes versus exceptional execution failures.
+
+## Event / webhook mode
+
+- Define a stable event type and versioning strategy independent of internal producer class names.
+- Use a consistent envelope with event ID, source, type, timestamp, subject/resource identity, and payload.
+- Assume at-least-once delivery unless stronger guarantees truly exist; consumers need deduplication by event ID or domain key.
+- Define ordering scope explicitly; never imply global ordering unless guaranteed.
+- Document retry schedule, maximum attempts, dead-letter behavior, and retention.
+- Sign webhooks, include replay protection, and rotate secrets safely.
+- Make consumers tolerant of additive fields.
+- Do not use events as disguised synchronous RPC responses when the caller needs an immediate result.
+

package/plugins/sp/skills/taste-refactoring-api/references/research-basis.md

@@ -0,0 +1,58 @@
+# Research Basis and Standards References
+
+This skill intentionally synthesizes standards and public guidance instead of depending on a single book.
+
+Research checked in September 2026.
+
+## HTTP semantics
+
+- RFC 9110 — HTTP Semantics: https://www.rfc-editor.org/rfc/rfc9110.html
+  - Defines request method semantics, safe methods, idempotency, status codes, conditional requests, and HTTP representation behavior.
+
+## HTTP API errors
+
+- RFC 9457 — Problem Details for HTTP APIs: https://www.rfc-editor.org/rfc/rfc9457.html
+  - Standard machine-readable problem detail model; obsoletes RFC 7807.
+
+## OpenAPI
+
+- OpenAPI Specification: https://spec.openapis.org/oas/
+  - Current published version list includes OpenAPI 3.2.0 and 3.1.x.
+
+## Resource-oriented design
+
+- Google AIP-121 — Resource-oriented design: https://google.aip.dev/121
+- Google AIP-130 — Methods: https://google.aip.dev/130
+- Google AIP-132 — Standard methods: List: https://google.aip.dev/132
+- Google AIP-136 — Custom methods: https://google.aip.dev/136
+- Google AIP-158 — Pagination: https://google.aip.dev/158
+
+These are vendor-specific guidelines, but they capture broadly useful patterns: stable resources, standard operations, custom actions only when necessary, and pagination designed from the start.
+
+## API security
+
+- OWASP API Security Top 10 — 2023: https://api-security.owasp.org/editions/2023/en/0x11-t10/
+  - Used as the baseline threat-model checklist for object-level authorization, authentication, property-level authorization, resource consumption, function-level authorization, sensitive business flows, SSRF, misconfiguration, inventory, and unsafe downstream API consumption.
+
+## GraphQL
+
+- GraphQL Specification — September 2025: https://spec.graphql.org/September2025/
+  - Used for schema/type-system, deprecation, nullability, input/output, and execution semantics.
+
+## Events
+
+- CloudEvents: https://cloudevents.io/
+  - Useful reference for stable event envelope concepts and interoperability.
+
+## Idempotency keys
+
+- IETF HTTPAPI draft — Idempotency-Key HTTP Header Field: https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
+  - As of the research date this remains an Internet-Draft, not a final RFC. The skill therefore treats the design pattern as useful while avoiding claims that the header is a finalized HTTP standard.
+
+## Additional architectural guidance
+
+- Microsoft Azure Architecture Center — API design / RESTful web API design:
+  - https://learn.microsoft.com/en-us/azure/architecture/microservices/design/api-design
+  - https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design
+
+This material reinforces loose coupling, domain-oriented contracts, compatibility/versioning, pagination/filtering, idempotency, and operational concerns.

package/plugins/sp/skills/taste-refactoring-architect/README.md

@@ -0,0 +1,26 @@
+# taste-refactoring-architect
+
+A reusable agent skill for system architecture refactoring with one central goal:
+
+**Simplify the architecture while preserving all required features and delivery qualities.**
+
+It uses a graded intervention model instead of treating every issue as a redesign problem:
+
+- A0 KEEP
+- A1 DIRECT REMOVE
+- A2 SUGGEST REMOVE
+- A3 CONSOLIDATE / SIMPLIFY
+- A4 SUGGEST ENHANCE
+- A5 RE-BOUNDARY
+- A6 SUGGEST RE-DESIGN
+- A7 DEFER / OBSERVE
+
+The package includes:
+- `SKILL.md` — operational agent instructions
+- `references/architecture-refactoring-playbook.md` — deeper techniques
+- `references/research-basis.md` — standards/practice basis
+- `checklists/daily-architecture-review.md` — quick daily checklist
+- `examples/review-template.md` — reusable assessment format
+- `examples/refactor-example.md` — worked example
+
+The skill interprets **STOA** as **state-of-the-art** architecture techniques. If your organization means a particular named STOA methodology, customize `research-basis.md` and map its rules into the action ladder.