@coralai/sps-cli 0.42.0 → 0.44.0

package/skills/code-reviewer/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: code-reviewer
+description: Persona skill — review code like a senior engineer. Prioritize correctness, security, clarity over taste. Overlay on top of language + end skills. For the checklist detail, see `coding-standards/references/code-review.md`.
+origin: agency-agents-fork + original (https://github.com/msitarzewski/agency-agents, MIT)
+---
+
+# Code Reviewer
+
+Review with intention. This is a **mindset overlay** — for the structured checklist, see [`coding-standards/references/code-review.md`](../coding-standards/references/code-review.md).
+
+## When to load
+
+- Reviewing a PR (yours or someone else's)
+- Writing a self-review checklist before opening a PR
+- Training a more junior reviewer (what to look for, in what order)
+
+## The posture
+
+1. **Correctness before style.** Lint is a machine's job. Humans find logic bugs, missing edges, bad abstractions.
+2. **Simplicity is a feature.** Fewer moving parts = fewer bugs. Prefer the shorter correct solution.
+3. **Review the diff, think about the system.** A clean diff that makes the system messier is a net negative.
+4. **Comment to teach, not to score.** The author reads every comment. "This is wrong" gets worked around; "here's why X breaks when Y happens" teaches.
+5. **Approve or block — decide.** "LGTM but…" is indecision. Say yes or no.
+6. **Respond quickly, even partially.** "Looking at this now, initial thoughts below" beats silence.
+7. **Trust but verify.** Author says "tested locally"; the diff must still support that claim with a test or a clear manual-test description.
+
+## Priority order (top first)
+
+Walk through in this order. Spend minutes on each upper item before considering the next.
+
+1. **Understand the change.** What problem does this solve? Is this the right fix or a symptom patch? Is there a simpler approach?
+2. **Correctness.** Happy path + edges: empty / duplicate / concurrent / partial failure. Race conditions. Order-of-operations.
+3. **Security.** Input validation at boundary. SQL / command / template injection. Auth/authz check. Secret handling.
+4. **Tests.** Does a test exist that would fail without this fix? Edge cases covered? Flaky patterns?
+5. **Data / migrations.** Backward compatible with running code during deploy? Backfill safe on large tables? Reversible?
+6. **Observability.** Enough log / metric to diagnose a failure? New alerts needed?
+7. **Layering.** Business logic stays out of adapters. Framework types stay out of the domain.
+8. **Style.** Names, formatting, dead code. Last.
+
+If the formatter and linter disagree with the code, the PR shouldn't have reached you. Don't spend review time on what tooling catches.
+
+## Comment vocabulary
+
+Small, predictable prefixes so the author knows what blocks.
+
+| Prefix | Meaning | Action |
+|---|---|---|
+| `Blocker:` | Must fix before merge | Don't approve |
+| `Question:` | I don't understand | Ask |
+| `Suggestion:` | Consider, non-blocking | Approve anyway |
+| `Nit:` | Style / taste | Approve |
+| `Praise:` | This is good | Approve (and mean it) |
+
+If you only left `Nit:` / `Suggestion:`, **approve**. Don't hold up a PR for taste.
+
+## Good review comments
+
+```
+Blocker: This 500s when `roles` is empty (line 43 assumes at least one role).
+Can you add a test with an empty roles list?
+
+Question: Why retry on 401? That looks like a permanent auth failure, not transient.
+
+Suggestion: Pull this parse block into a helper — it's duplicated in orders.py:33.
+
+Praise: Nice refactor. Untangled what I've been worried about for months.
+
+Nit: `usr` → `user`.
+```
+
+## Bad review comments
+
+```
+"This is weird."                     ← not actionable
+"Why would you do it this way?"      ← confrontational; say what you'd prefer
+"I would have done X."               ← if X is better, ask for X
+"FYI, there's a library for this."   ← link, justify, or drop
+Long digressions about architecture  ← file a separate issue
+```
+
+## What you check no matter what
+
+- **"What happens when X is null / empty / wrong type?"** — trace each input.
+- **"What's the failure response visible to the user / caller?"** — status code, error shape, logs.
+- **"What's new in prod that wasn't there before?"** — new dep, new env var, new migration, new cron.
+- **"Is anything silently caught?"** — every `catch` clause, grep for bare `except:` / `catch (e) {}`.
+- **"Does this introduce a new coupling?"** — new import between modules that shouldn't know each other.
+
+## What you let go
+
+- **Personal stylistic preferences.** If the code follows the team's convention, even if you wouldn't write it that way, that's fine.
+- **Perfection over shipping.** A good-enough change now beats a perfect one in three weeks.
+- **Every abstraction could be prettier.** So could yours.
+
+## Red flags to always flag
+
+- `TODO` / `FIXME` with no owner or date.
+- Commented-out code.
+- Tests with no assertions (or a single `assertTrue(true)`).
+- `console.log` / `print` left in.
+- Catch-all exception handlers that don't log or re-raise.
+- Hard-coded secrets / IPs / URLs.
+- New dependencies not justified in the PR description.
+- Huge diffs that mix refactor and behaviour change.
+- `any` / `dynamic` / `interface{}` in typed code without comment.
+- Changes to shared utilities without review from those utilities' owners.
+
+## Size discipline
+
+| Diff size | What to do |
+|---|---|
+| < 100 lines | Thorough review |
+| 100–400 | Careful review |
+| 400–1000 | Skim; ask to split |
+| 1000+ | Send back: split this |
+
+A large PR that's rubber-stamped is worse than no review.
+
+## Review response time
+
+- First response within one working day.
+- Partial response early is better than silent perfect response.
+- Blocking a PR for days with no reason is a failure of the reviewer.
+
+## When to push for changes vs. accept
+
+Push when:
+- Correctness / security concern.
+- Architecture drift that compounds (a new bad pattern that will be copied).
+- Tests missing for a non-trivial change.
+
+Accept when:
+- Small stylistic preferences.
+- "I would have done it differently" (without concrete "better" reason).
+- Refactor opportunities not on the change's path.
+
+Follow up separately for the accept cases. Don't use PR review as the lever for every idea you've ever had.
+
+## Pair with
+
+- [`coding-standards`](../coding-standards/SKILL.md) — principles and checklists.
+- The relevant language skill for the language being reviewed.
+- [`backend`](../backend/SKILL.md) / [`frontend`](../frontend/SKILL.md) — the domain of what's being reviewed.

package/skills/coding-standards/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: coding-standards
+description: Cross-language engineering principles — TDD, naming, error strategy, code review, commits/PRs, clean code. Load alongside any language / end skill. Principles only; language-specific syntax lives in the language skill.
+origin: ecc-fork + original (https://github.com/affaan-m/everything-claude-code, MIT)
+---
+
+# Coding Standards
+
+Language- and stack-neutral engineering principles. Covers the "what" and "why"; language skills cover the "how".
+
+## When to load
+
+- Any coding task (load this + a language skill + an end skill)
+- Code review
+- Writing tests
+- Opening a PR
+- Deciding where error handling / retries / logging live
+
+## Hierarchy of rules
+
+1. **Correctness** — the code does what's intended
+2. **Readability** — the next person (or you, six months later) can follow it
+3. **Testability** — behavior is verifiable without the universe
+4. **Simplicity** — least code and least abstraction that meet 1–3
+5. **Performance** — only after 1–4 are met
+
+In that order. A fast bug is worse than a slow correct answer.
+
+## Core commitments
+
+- **Tests first** for anything non-trivial. Write a failing test, make it pass, refactor.
+- **Specific exceptions only.** Never `except:` bare. Never swallow without logging.
+- **Name things for intent, not implementation.** `users_over_18` > `filtered_list_2`.
+- **Small functions that do one thing.** If you can't say what it does in one sentence, split it.
+- **No comments that restate the code.** Comments explain the *why*, never the *what*.
+- **No speculative abstractions.** Two similar snippets: duplicate. Three: consider abstracting.
+- **PRs under 400 lines of diff.** Anything larger, split.
+
+## How to use references
+
+| Reference | When to load |
+|---|---|
+| [`references/tdd.md`](references/tdd.md) | Starting a feature, writing tests, unclear what "done" means |
+| [`references/naming.md`](references/naming.md) | Naming a function, variable, module, endpoint, feature flag |
+| [`references/error-strategy.md`](references/error-strategy.md) | Deciding whether to raise, return a result, log, or swallow |
+| [`references/code-review.md`](references/code-review.md) | Reviewing a PR (yours or someone else's) |
+| [`references/commits-and-prs.md`](references/commits-and-prs.md) | Writing a commit message; opening / sizing a PR |
+| [`references/clean-code.md`](references/clean-code.md) | Function shape, DRY vs WET, comments, dead code, magic numbers |
+
+## Forbidden patterns (auto-reject)
+
+- Commented-out code committed to main
+- `TODO` without an owner or date
+- Tests that don't actually assert anything
+- Mutable global state for business logic
+- Dead code kept "just in case"
+- Magic numbers / strings without named constants
+- Catch-all error handlers without re-raise or specific recovery
+- Abstractions that have exactly one implementation
+- PRs that mix a refactor with a feature change

package/skills/coding-standards/references/clean-code.md

@@ -0,0 +1,258 @@
+# Clean Code
+
+Function shape, DRY vs WET, comments, dead code, magic numbers. Language-neutral hygiene.
+
+## Functions
+
+### One thing
+
+A function should do one thing, at one level of abstraction. If the function's name needs "and", split it.
+
+```
+# ❌
+def validate_and_save_user(user): ...
+
+# ✅
+def validate(user): ...
+def save(user): ...
+
+def register_user(user):
+    validate(user)
+    save(user)
+```
+
+### Small
+
+Rough targets, not dogma:
+- Functions ≤ 20 lines most of the time.
+- If a function has three indentation levels, consider extracting.
+- A function you can't see in one screen is a warning sign.
+
+Exceptions: a switch-like dispatch that's naturally long is fine. A 200-line function because you kept adding cases is not.
+
+### Arguments — few
+
+Zero is best. One is fine. Two is OK. Three is suspicious. Four is a refactor.
+
+```
+# ❌
+create_user(name, email, age, role, active, parent_id, billing_addr, shipping_addr, ...)
+
+# ✅ — group related args
+create_user(identity, profile, permissions)
+```
+
+Boolean flags doubly so:
+
+```
+# ❌
+render_page(user, is_admin, is_preview, skip_cache)
+
+# ✅ — flags mean you're doing two things in one function
+render_page_for_admin(user, options)
+render_preview_page(user)
+```
+
+### Return one type
+
+If a function can return a `User`, or `None`, or a string error code, pick one contract. Use `Optional` or a result type for "success or not found". Don't overload the return to mean three different things.
+
+### Pure where possible
+
+Pure = same input produces same output, no side effects. Pure code is trivial to test and reason about. Push side effects (I/O, state mutation, logging) to the edges.
+
+```
+# core: pure
+def calculate_price(items, promo): ...
+
+# edge: side effects
+def checkout(items, promo):
+    price = calculate_price(items, promo)
+    payment = charge(price)
+    db.save_order(items, price, payment.id)
+    eventBus.publish(OrderPlaced(...))
+```
+
+## DRY vs WET — know the ratio
+
+| Situation | Do |
+|---|---|
+| Two similar snippets | **Duplicate**. Too early to know the shape. |
+| Three similar snippets | Consider abstracting — if the shape is clear. |
+| Four+ similar snippets | Abstract; you've learned what varies. |
+
+Bad abstractions cost more than duplication. A wrong shape locks every caller into a detour forever.
+
+Rule: abstract when the shape is obvious, not when the count reaches a number.
+
+## Comments
+
+Default: don't write one. If you do, explain *why*, never *what*.
+
+```
+# ❌ noise
+i += 1   # increment i
+
+def save(user):
+    # saves a user
+    db.insert(user)
+
+# ✅ non-obvious why
+# Upstream API returns 503 for ~500ms during leader election;
+# retry window tuned from their SRE post, not ours.
+sleep(0.6)
+
+# HACK: patch until [TICKET-481] lifts the 100-col DB constraint.
+name = name[:100]
+```
+
+Delete comments that:
+- Restate the code (`# loop over items`)
+- Restate the function name (`# validates input`)
+- Are out of date (the code changed; the comment didn't)
+- Reference past states (`# was previously doing X`)
+
+Git remembers history. Code is the present tense.
+
+### Docstrings
+
+For public functions/classes. Describe contract, not implementation.
+
+```
+# ✅
+"""Return the canonical URL for this resource, or None if it isn't published."""
+
+# ❌
+"""This function takes a resource and returns its URL by looking up the slug in the DB."""
+```
+
+One sentence is often enough. Longer docstrings: inputs, outputs, errors, side effects.
+
+## Dead code — delete it
+
+If a function, class, or branch is unreachable, remove it. "Just in case" is not a reason to keep dead code.
+
+- Unused imports → remove
+- Commented-out code → remove (git has it)
+- `if False:` branches → remove
+- `TODO` from two years ago → remove or fix
+
+Dead code rots. It confuses readers, breaks grep, and occasionally gets re-animated with stale assumptions.
+
+## Magic numbers and strings
+
+Named constants when the value has meaning. Literals are fine when they're self-explanatory.
+
+```
+# ✅ named — intent is clear
+MAX_LOGIN_ATTEMPTS = 5
+DEFAULT_PAGE_SIZE  = 20
+HTTP_OK            = 200
+
+# ✅ literal — self-explanatory in context
+str[:10]
+for i in range(3): ...
+x * 2
+
+# ❌ magic
+if user.attempts > 5: ...
+if status == "pa":       # what's "pa"?
+```
+
+## Early return over nested conditions
+
+Flatter reads better than deeply nested `if`s.
+
+```
+# ❌ pyramid of doom
+def process(user):
+    if user is not None:
+        if user.is_active:
+            if user.has_permission():
+                if user.payment_method_valid():
+                    return do_thing(user)
+    return None
+
+# ✅ guard clauses, early returns
+def process(user):
+    if user is None: return None
+    if not user.is_active: return None
+    if not user.has_permission(): return None
+    if not user.payment_method_valid(): return None
+    return do_thing(user)
+```
+
+## Avoid mutable global state
+
+Global mutables are action at a distance. A test sets a flag → unrelated tests fail.
+
+```
+# ❌
+_CURRENT_USER = None
+
+def set_user(u): global _CURRENT_USER; _CURRENT_USER = u
+def current(): return _CURRENT_USER
+
+# ✅ pass explicitly, or use a request-scoped context
+def handler(req, user):
+    current_user = resolve_user(req)
+    ...
+```
+
+Request-scoped context objects are fine (HTTP request context, trace context). Globals for business data are not.
+
+## Avoid clever one-liners
+
+If a line needs 30 seconds to parse, it costs every future reader 30 seconds.
+
+```
+# ❌
+return [next((v for v in xs if p(v, k)), default) for k in sorted({f(x) for x in data} - skip)]
+
+# ✅
+keys = {f(x) for x in data} - skip
+out = []
+for k in sorted(keys):
+    match = next((v for v in xs if p(v, k)), default)
+    out.append(match)
+return out
+```
+
+Density ≠ clarity. A loop you can read in one pass beats a comprehension you have to puzzle out.
+
+## Prefer immutability
+
+Where the language supports it, prefer immutable values.
+
+- Makes reasoning local (a value can't change out from under you)
+- Safer in concurrent code
+- Better cache keys, better log entries
+
+Use mutation for internal data structures when performance matters. Don't propagate mutation to the public API.
+
+## Feature flags — clean up
+
+Flags are temporary. Long-lived flags become part of the product accidentally.
+
+```
+# a few weeks after launch
+if feature_enabled("partial_shipments"):
+    ...
+
+# six months later: rollout is done. Inline. Delete the flag.
+```
+
+Track flag age. Delete dead flags. A flag that's been "on for everyone" for three months is technical debt.
+
+## Anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| 200-line function | Extract; each piece named for intent |
+| Mixing abstraction levels (business rule + DB call + HTTP call) | Layer: see backend/layering |
+| Flag arguments (`do(x, is_special=True)`) | Split into two functions |
+| "Utils" modules | Split by domain; utils becomes a dumping ground |
+| Deep nesting | Guard clauses, early returns |
+| Duplicated constants across files | Promote to a shared constants module |
+| Commented-out code "in case we need it" | Delete; git has it |
+| Over-abstracted single-use interface | Delete the interface; use the concrete type |

package/skills/coding-standards/references/code-review.md

@@ -0,0 +1,192 @@
+# Code Review
+
+How to review. How to be reviewed. A checklist that works regardless of language.
+
+## What review is for
+
+In order of importance:
+
+1. **Catching defects** — correctness bugs, security issues, data loss paths
+2. **Sharing knowledge** — both directions; reviewer learns too
+3. **Maintaining consistency** — convention drift, naming, layering
+4. **Coaching** — especially for junior → senior flow
+5. **Rubber-stamping** — never the goal, though sometimes the outcome
+
+Review is NOT:
+- A style argument you could have automated (use a formatter)
+- A place to re-litigate architecture decisions already made
+- An opportunity to impose personal preferences as requirements
+
+## Reviewer checklist
+
+Go through in this order. Don't start with nits.
+
+### 1. Understand the change
+
+- What problem does this solve? (Read the PR description; if it's empty, push back.)
+- Is this the right fix, or is it treating a symptom?
+- Is there a simpler approach that also works?
+
+### 2. Correctness
+
+- Does it handle the happy path?
+- What about the edges: empty inputs, duplicates, concurrency, partial failures?
+- What happens on error? Is the error propagation / handling at the right layer?
+- Are there new race conditions? Deadlocks? Order-of-operations assumptions?
+
+### 3. Security
+
+- Any user input that isn't validated at the boundary?
+- Any SQL / command / template construction from strings?
+- Any auth/authz check missing? Any leak of existence / enumeration?
+- Any new secret / credential in code or config?
+
+### 4. Tests
+
+- Is there a test for the change? (No test on non-trivial change = push back.)
+- Does the test actually fail without the fix? (Reviewer can mentally check this.)
+- Are edge cases tested, not just happy path?
+- Any flaky patterns: sleeps, network calls, order dependencies?
+
+### 5. Data and migrations
+
+- Schema change: is it backward compatible with the running code during deploy?
+- Backfill strategy: safe on large tables? rate-limited?
+- Is this reversible? If not, is the forward-only plan documented?
+
+### 6. Observability
+
+- Does the new code log errors with enough context (request id, user id)?
+- Are new metrics / dashboards needed? Alerts?
+- Can an oncall diagnose a failure from what's logged?
+
+### 7. Layering & design
+
+- Does business logic stay out of adapters? Do adapters stay out of the domain?
+- Any new leakage: framework types into domain, DB rows into API responses?
+- Any abstraction that has exactly one implementation? (Likely premature.)
+
+### 8. Style (last)
+
+- Formatter run? Linter clean?
+- Names clear?
+- Any comments that should be removed / added?
+
+If the formatter and linter disagree with the code, the PR shouldn't have reached human review.
+
+## How to comment
+
+Use a small vocabulary so the author knows what's blocking.
+
+| Prefix | Meaning | Action |
+|---|---|---|
+| `Blocker:` | Must fix before merge | Don't approve |
+| `Question:` | I don't understand; please explain | Ask |
+| `Suggestion:` | Consider, non-blocking | Approve anyway |
+| `Nit:` | Style / taste, truly optional | Approve |
+| `Praise:` | This is good; say it | Approve (and mean it) |
+
+If you only leave `Nit:` and `Suggestion:`, approve. Don't hold up a PR for taste.
+
+## Good comments
+
+```
+Blocker: This will 500 when `user.roles` is empty (line 43 assumes at least one).
+Can you add a test with an empty roles list?
+
+Suggestion: Pull this 3-line parse block into a helper — it's duplicated in
+handlers/orders.py too.
+
+Question: Why are we retrying on 401? That looks like the credential is wrong,
+not transient.
+
+Nit: `usr` → `user`.
+```
+
+## Bad comments
+
+```
+"This is weird."                          ← not actionable
+"Why would you do it this way?"           ← confrontational; say what you'd prefer
+"I would have done X."                    ← if X is better, ask for X; otherwise irrelevant
+"FYI, there's a library for this."        ← link, justify, or drop it
+Long digressions about architecture       ← file a separate issue
+```
+
+## Reviewing size
+
+| Diff size | Typical quality of review |
+|---|---|
+| < 100 lines | Thorough |
+| 100–400 | Careful |
+| 400–1000 | Skimmed; defects slip |
+| > 1000 | Rubber stamp |
+
+If the PR is > 400 lines and not refactor-only (e.g., rename), ask the author to split. Reviewers can't do their job on huge diffs.
+
+## Review speed
+
+- Aim to first-respond within one working day.
+- Incremental responses are fine: "looking at it now, initial thoughts below".
+- Blocking a PR for days with no reason is a failure mode.
+
+## Being reviewed
+
+Make the reviewer's job easy.
+
+### The PR description
+
+```
+## What
+One-line summary of the change.
+
+## Why
+Link to ticket / incident. Business / technical reason.
+
+## How
+Brief description of the approach and why this approach.
+
+## Tests
+What was added / run locally. Any manual verification.
+
+## Risks / rollout
+Feature flag? Migration? Rollback plan?
+```
+
+### Split your PRs
+
+- **Refactor** (no behavior change) and **feature** (behavior change) in separate PRs.
+- **Rename** PRs are mechanical — reviewer should only need to confirm "nothing else changed".
+- **Dependency bumps** separate from feature work.
+
+### Respond to all comments
+
+- `Fixed.` (with the follow-up commit ref)
+- `Good catch, added a test for that too.`
+- `I see it differently — <reason>. Want to discuss on a call?`
+
+Don't leave comments unanswered. "Ignored" on a review is how reviewers stop reviewing carefully.
+
+### Don't take it personally
+
+Code is being reviewed, not you. "This is wrong" is about the line, not your worth. If a comment does feel personal, ask the reviewer offline — don't escalate in the PR.
+
+## Approving
+
+- **Approve** when you'd be comfortable being paged at 3am because of this code.
+- **Request changes** when there are blockers.
+- **Comment** (neither approve nor block) when you've given feedback but someone more authoritative should approve.
+
+Don't approve-and-block ("LGTM but…"). Decide.
+
+## Anti-patterns
+
+| Anti-pattern | Why |
+|---|---|
+| Review-bombing with 50 nits | Exhausts the author; misses the real issue |
+| Approving without reading | Wastes the review; defects sneak through |
+| Re-litigating the design at review time | Should have been a design doc earlier |
+| "Can you just rewrite this?" | If true, say specifically why; offer an example |
+| Ignoring your own review comments later | Inconsistent; erodes trust |
+| Big PR → "looks good" after 5 min | Not an actual review |
+| Review as gate without shared standards | Reviewer's mood decides the outcome |