@cronus-ui/ai-kit 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +8 -0
- package/dist/ai-kit.d.ts +78 -0
- package/dist/ai-kit.js +172 -0
- package/dist/index.d.ts +8 -0
- package/dist/index.js +2 -0
- package/package.json +57 -0
- package/templates/AGENTS.agency.md +80 -0
- package/templates/AGENTS.base.md +188 -0
- package/templates/AGENTS.fintech.md +116 -0
- package/templates/AGENTS.oss.md +78 -0
- package/templates/AGENTS.saas.md +88 -0
- package/templates/CLAUDE.md +52 -0
- package/templates/claude/agents/code-reviewer.md +80 -0
- package/templates/claude/settings.json +62 -0
- package/templates/claude/skills/code-review/SKILL.md +65 -0
- package/templates/claude/skills/compose/SKILL.md +156 -0
- package/templates/claude/skills/evidence-check/SKILL.md +39 -0
- package/templates/claude/skills/ship-pr/SKILL.md +66 -0
- package/templates/claude/skills/theme/SKILL.md +94 -0
- package/templates/claude/skills/ui-add/SKILL.md +96 -0
- package/templates/cursor/rules/00-doctrine.mdc +17 -0
- package/templates/cursor/rules/10-cronus-ui.mdc +20 -0
- package/templates/gemini/GEMINI.md +32 -0
- package/templates/github/copilot-instructions.md +27 -0
- package/templates/mcp.json +9 -0
- package/templates/windsurf/rules/doctrine.md +25 -0
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
## Fintech / payments preset
|
|
2
|
+
|
|
3
|
+
Enable this preset when __APP_NAME__ moves money: payments, checkout, marketplaces,
|
|
4
|
+
payouts, wallets, subscriptions, ledgers, or anything that reports balances to a user
|
|
5
|
+
who makes decisions with that number. It appends to and specializes the base rules.
|
|
6
|
+
|
|
7
|
+
Central rule: **money, trust, and operational continuity outrank apparent speed.**
|
|
8
|
+
The financial layer holds the highest bar in the product: it cannot be approximate,
|
|
9
|
+
obscure, or unverified. Any number a user acts on — to scale ad spend, to pause, to
|
|
10
|
+
withdraw, to reconcile — must be traceable to a real source of record.
|
|
11
|
+
|
|
12
|
+
### 1. Financial truth before UI
|
|
13
|
+
|
|
14
|
+
Every financial figure must have a clear origin. If a screen shows revenue, balance,
|
|
15
|
+
reserve, payout, fee, refund, chargeback, or adjustment, there must be an auditable
|
|
16
|
+
path from that pixel to the real source: the internal ledger, the processor/acquirer,
|
|
17
|
+
the bank, or a recorded financial event. A pretty number without backing is a
|
|
18
|
+
liability, not a feature. If you cannot name the source, do not display the number as
|
|
19
|
+
fact.
|
|
20
|
+
|
|
21
|
+
### 2. Revenue is not withdrawable balance — separate the money layers
|
|
22
|
+
|
|
23
|
+
Never treat gross sales, net revenue, available balance, reserve, in-transit, and paid
|
|
24
|
+
payouts as the same thing. When you compute, explain, or render money, keep these
|
|
25
|
+
layers distinct and labeled:
|
|
26
|
+
|
|
27
|
+
- **approved** — the sale/authorization succeeded, but the money is not settled;
|
|
28
|
+
- **settled / captured** — funds confirmed by the processor;
|
|
29
|
+
- **in-processing** — pending settlement, clearing, or review;
|
|
30
|
+
- **net revenue** — settled minus fees, refunds, chargebacks, and disputes;
|
|
31
|
+
- **reserve** — held by rolling-reserve or risk rules, not spendable;
|
|
32
|
+
- **available** — cleared and eligible to be paid out;
|
|
33
|
+
- **payout-created** — a payout/transfer was initiated;
|
|
34
|
+
- **in-transit** — payout sent, not yet confirmed at the destination;
|
|
35
|
+
- **paid** — payout confirmed at the destination account;
|
|
36
|
+
- **adjustment** — manual compensation, correction, or off-ledger movement.
|
|
37
|
+
|
|
38
|
+
If two amounts look similar, assume they may be different layers until proven
|
|
39
|
+
otherwise. Collapsing layers is how a dashboard lies without a single wrong query.
|
|
40
|
+
|
|
41
|
+
### 3. Dashboards must not induce wrong scaling decisions
|
|
42
|
+
|
|
43
|
+
If a screen makes a user believe they are profitable while the real ledger says
|
|
44
|
+
otherwise, that is a P0/P1 defect — not a styling ticket. A financial surface must make
|
|
45
|
+
explicit:
|
|
46
|
+
|
|
47
|
+
- what is commercial performance vs. what is actual balance;
|
|
48
|
+
- what has already been deducted (fees, refunds, disputes) vs. what has not;
|
|
49
|
+
- what is still in reconciliation or review;
|
|
50
|
+
- what has not yet become spendable money;
|
|
51
|
+
- what depends on a release rule (reserve, hold, settlement window).
|
|
52
|
+
|
|
53
|
+
Users decide traffic, hiring, and cash moves from these numbers. Financial confusion
|
|
54
|
+
costs real money, support load, and reputation. Optimize the number for correctness
|
|
55
|
+
first, then for clarity, then for looks.
|
|
56
|
+
|
|
57
|
+
### 4. Downstream data is a business decision
|
|
58
|
+
|
|
59
|
+
Events emitted to analytics, pixels, webhooks, or partner integrations are treated as
|
|
60
|
+
business decisions, not technical details. A wrong or duplicated purchase/refund event
|
|
61
|
+
can distort a user's ad optimization and cause real loss. Deduplicate, version, and
|
|
62
|
+
document the contract; a change to an emitted financial event is a P1 by default.
|
|
63
|
+
|
|
64
|
+
### 5. Financial divergence protocol
|
|
65
|
+
|
|
66
|
+
When there is any doubt about balance, payout, revenue, reserve, or "missing money",
|
|
67
|
+
do not answer on impulse. Run the protocol:
|
|
68
|
+
|
|
69
|
+
1. Do not assume the customer is wrong.
|
|
70
|
+
2. Do not assume the dashboard is right.
|
|
71
|
+
3. Do not assume the processor/acquirer is right without checking.
|
|
72
|
+
4. Fix the scope first: exact **period**, **account**, **store/project**, and **currency**.
|
|
73
|
+
5. Break the account into blocks and reconcile each: approved, settled,
|
|
74
|
+
in-processing, refunds, chargebacks/disputes, fees, reserve, adjustments,
|
|
75
|
+
available, payouts paid, payouts in-transit, and manual/off-ledger payments.
|
|
76
|
+
6. Produce a line-by-line reconciliation when the totals do not agree.
|
|
77
|
+
7. Explain the result in plain terms that do not hide the problem.
|
|
78
|
+
8. If the screen is wrong, fix the screen. If the money is wrong, quantify it, correct
|
|
79
|
+
it, and document it.
|
|
80
|
+
|
|
81
|
+
Hard rule: **never call something a "visual bug" before it has been reconciled.** A
|
|
82
|
+
silent explanation protects you today and destroys trust later.
|
|
83
|
+
|
|
84
|
+
### 6. Money-handling essentials
|
|
85
|
+
|
|
86
|
+
Get the mechanics right or the money is wrong at the source:
|
|
87
|
+
|
|
88
|
+
- **Never use floating-point for monetary amounts.** Store and compute in minor units
|
|
89
|
+
(integer cents) or a fixed-precision decimal type; binary floats silently lose cents.
|
|
90
|
+
- **Put an idempotency key on every money-moving mutation.** A retry, double-click, or
|
|
91
|
+
webhook redelivery must collapse to exactly one charge, refund, or payout.
|
|
92
|
+
- **Verify every webhook and callback signature, and treat the payload as untrusted.**
|
|
93
|
+
A processor callback is a public HTTP endpoint until proven authentic; validate before
|
|
94
|
+
you act on it.
|
|
95
|
+
|
|
96
|
+
### Evidence and criticality for money
|
|
97
|
+
|
|
98
|
+
This preset raises the base gates for financial work:
|
|
99
|
+
|
|
100
|
+
- Anything touching money, balance, payout, checkout, or ledger is **P0/P1** — the
|
|
101
|
+
full review + QA gate is mandatory, not optional.
|
|
102
|
+
- Financial conclusions must not close below **L3**; anything affecting payout, balance,
|
|
103
|
+
or production money must reach **L4**, with a closed reconciliation.
|
|
104
|
+
- Prefer a dry-run or a read-only reconciliation before any money-moving mutation.
|
|
105
|
+
- Never invent amounts, rates, or reconciliations. State exactly what was not verified.
|
|
106
|
+
|
|
107
|
+
### Money-flow anti-patterns
|
|
108
|
+
|
|
109
|
+
The base "never introduce" list (unbounded retry, infinite polling, unthrottled fan-out,
|
|
110
|
+
messages that requeue forever, crash-on-missing-dependency) applies in full. Two failure
|
|
111
|
+
modes are money-specific and worse:
|
|
112
|
+
|
|
113
|
+
- a boot or dependency failure that degrades into silent double-charges or dropped
|
|
114
|
+
transactions instead of failing loudly and cleanly;
|
|
115
|
+
- a **silent fallback that turns a financial error into a trustworthy-looking zero** —
|
|
116
|
+
show the error state; never fabricate a clean number.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
## Open-source preset
|
|
2
|
+
|
|
3
|
+
Enable this preset when __APP_NAME__ is published for others to depend on and
|
|
4
|
+
contribute to: a library, SDK, CLI, or public API released under an open-source
|
|
5
|
+
license. It appends to and specializes the base rules.
|
|
6
|
+
|
|
7
|
+
Central rule: **the public surface is a contract with strangers you will never meet.**
|
|
8
|
+
People build on what you export, on a schedule you do not control. Breaking them
|
|
9
|
+
silently, or shipping a secret to a public repo, is a P0 — not a follow-up.
|
|
10
|
+
|
|
11
|
+
### 1. Guard the public surface, version it honestly
|
|
12
|
+
|
|
13
|
+
Anything exported — functions, types, CLI flags, config keys, HTTP routes, event
|
|
14
|
+
shapes — is API the moment it ships. Treat the boundary between public and internal
|
|
15
|
+
as deliberate.
|
|
16
|
+
|
|
17
|
+
- Keep the public surface small and intentional; mark internals clearly and do not
|
|
18
|
+
let them leak into the published entry points.
|
|
19
|
+
- Follow **semver** literally: a breaking change to public behavior is a **major**
|
|
20
|
+
bump, new backward-compatible capability is minor, fixes are patch.
|
|
21
|
+
- **Deprecate before you remove.** Ship the deprecation with a warning, a migration
|
|
22
|
+
note, and a replacement, keep it working for at least one minor cycle, then remove
|
|
23
|
+
only on a major. Never delete public API in a patch.
|
|
24
|
+
- When a change would break consumers, stop and say so plainly — do not disguise a
|
|
25
|
+
breaking change as a "fix."
|
|
26
|
+
|
|
27
|
+
### 2. Never commit a secret
|
|
28
|
+
|
|
29
|
+
A public repository has no private corners, and git history is forever.
|
|
30
|
+
|
|
31
|
+
- No tokens, keys, passwords, private endpoints, or customer data in source, tests,
|
|
32
|
+
fixtures, examples, or commit history.
|
|
33
|
+
- Use placeholders and documented env vars; keep real secrets out of the tree with
|
|
34
|
+
ignore rules and pre-commit hygiene.
|
|
35
|
+
- If a secret is ever committed, treat it as compromised: rotate it, do not merely
|
|
36
|
+
delete the line.
|
|
37
|
+
|
|
38
|
+
### 3. Make contribution and review easy and consistent
|
|
39
|
+
|
|
40
|
+
Contributors are guests; lower the cost of a good PR and keep the bar visible.
|
|
41
|
+
|
|
42
|
+
- Keep contributor docs current: how to set up, build, test, and lint, plus the
|
|
43
|
+
commit and branching conventions this project uses.
|
|
44
|
+
- PR hygiene: one focused change per PR, a clear title and description, linked issue,
|
|
45
|
+
green CI, and tests for new behavior and fixed bugs.
|
|
46
|
+
- Review with the same adversarial posture whether the author is a maintainer or a
|
|
47
|
+
first-time contributor; be direct and kind, and explain the *why* behind a request.
|
|
48
|
+
|
|
49
|
+
### 4. Keep docs, README, and CHANGELOG true
|
|
50
|
+
|
|
51
|
+
Out-of-date docs are a bug reported by every new user.
|
|
52
|
+
|
|
53
|
+
- Update the README, examples, and API docs **in the same change** as the code they
|
|
54
|
+
describe. A feature without docs is not done.
|
|
55
|
+
- Maintain a human-readable CHANGELOG with every release: what changed, what broke,
|
|
56
|
+
and how to migrate. Users decide whether to upgrade from it.
|
|
57
|
+
- Examples must actually run against the released version.
|
|
58
|
+
|
|
59
|
+
### 5. Respect license and attribution
|
|
60
|
+
|
|
61
|
+
The license is a legal promise; honor it and keep it consistent.
|
|
62
|
+
|
|
63
|
+
- Where the project uses per-file license headers, add them to new files; match the
|
|
64
|
+
existing style and year convention.
|
|
65
|
+
- Keep the LICENSE, third-party notices, and dependency licenses accurate; do not
|
|
66
|
+
introduce a dependency whose license conflicts with the project's.
|
|
67
|
+
- Preserve existing copyright and attribution; never strip it.
|
|
68
|
+
|
|
69
|
+
### Security disclosure
|
|
70
|
+
|
|
71
|
+
Vulnerabilities in a public project put every downstream user at risk.
|
|
72
|
+
|
|
73
|
+
- Provide and follow a responsible-disclosure path (a `SECURITY.md` / private
|
|
74
|
+
contact); **never** discuss an unpatched vulnerability in a public issue or PR.
|
|
75
|
+
- Fix privately, prepare the patched release and advisory, then disclose with credit
|
|
76
|
+
and an upgrade path. Coordinate the release so users can update before details are
|
|
77
|
+
public.
|
|
78
|
+
- A security fix is P0: it jumps the queue and ships with a clear advisory and version.
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
## SaaS preset
|
|
2
|
+
|
|
3
|
+
Enable this preset when __APP_NAME__ serves multiple customers from one shared
|
|
4
|
+
deployment: a multi-tenant web app, an API product, or any system where one
|
|
5
|
+
account's data, billing, and limits must never bleed into another's. It appends to
|
|
6
|
+
and specializes the base rules.
|
|
7
|
+
|
|
8
|
+
Central rule: **the tenant boundary is a security boundary, and billing state is a
|
|
9
|
+
promise.** Leaking one tenant's data into another's view is a P0 breach, not a bug.
|
|
10
|
+
Charging, entitling, or cutting off a customer incorrectly is a P0/P1 that costs
|
|
11
|
+
money and trust. Neither is ever a styling ticket.
|
|
12
|
+
|
|
13
|
+
### 1. Tenant isolation is not optional
|
|
14
|
+
|
|
15
|
+
Every query, cache entry, background job, file path, and object key must be scoped
|
|
16
|
+
to a tenant. There is no "just this once" global read.
|
|
17
|
+
|
|
18
|
+
- Derive the tenant from the authenticated principal, **never** from a client-supplied
|
|
19
|
+
id, header, or body field that the request could forge.
|
|
20
|
+
- Namespace every cache key, queue message, storage prefix, and search index by
|
|
21
|
+
tenant id; a shared key that omits the tenant is a cross-tenant leak waiting to fire.
|
|
22
|
+
- A missing or ambiguous tenant scope is a hard stop — fail closed, do not fall back
|
|
23
|
+
to "all rows."
|
|
24
|
+
- Cross-tenant work (admin tools, aggregate reports) is a separate, explicitly-audited
|
|
25
|
+
path with its own authorization — never a side effect of a normal handler.
|
|
26
|
+
|
|
27
|
+
### 2. Authorize every handler — deny by default
|
|
28
|
+
|
|
29
|
+
Authentication answers *who*; authorization answers *what they may touch*. Both run
|
|
30
|
+
on every entry point.
|
|
31
|
+
|
|
32
|
+
- Default to deny. A new route, RPC, job, or webhook is unauthorized until you add
|
|
33
|
+
the check — never authorized because you forgot one.
|
|
34
|
+
- Enforce **object-level** access: confirm this principal may act on *this specific*
|
|
35
|
+
resource, not merely that they hold the role in general.
|
|
36
|
+
- Check on the server, on every request. Client-side gating is UX, not security.
|
|
37
|
+
- Least privilege for machine principals too: scope API keys, service tokens, and
|
|
38
|
+
internal callers to exactly what they need.
|
|
39
|
+
|
|
40
|
+
### 3. Billing and entitlements must be correct
|
|
41
|
+
|
|
42
|
+
Subscription state drives what a customer can do and what they pay. Get it exactly
|
|
43
|
+
right.
|
|
44
|
+
|
|
45
|
+
- Entitlements (plan, seats, feature flags, quotas) are enforced server-side from the
|
|
46
|
+
current subscription — never trusted from the client or a stale cache.
|
|
47
|
+
- Make billing operations **idempotent**: no double-charge on a retry, a webhook
|
|
48
|
+
replay, or a double-click. Key money-moving actions by a stable idempotency token.
|
|
49
|
+
- Handle the full lifecycle honestly: proration on plan change, trials, downgrades,
|
|
50
|
+
cancellations, failed payments, dunning, and grace periods. Treat the billing
|
|
51
|
+
provider's webhook as the source of truth and reconcile against it.
|
|
52
|
+
- A wrong invoice, a missed cancellation, or an over-provisioned plan is P0/P1.
|
|
53
|
+
|
|
54
|
+
### 4. Treat PII and data lifecycle as a contract
|
|
55
|
+
|
|
56
|
+
Customer data carries legal and reputational weight.
|
|
57
|
+
|
|
58
|
+
- Collect the minimum, encrypt in transit and at rest, and never log raw PII,
|
|
59
|
+
credentials, tokens, or full payloads.
|
|
60
|
+
- Honor retention and deletion commitments: know where every copy of a tenant's data
|
|
61
|
+
lives (DB, cache, backups, search, logs, exports) so export and hard-delete are
|
|
62
|
+
actually complete. Secrets and per-tenant keys stay managed, rotatable, and uncommitted.
|
|
63
|
+
|
|
64
|
+
### 5. Rate-limit per principal, not just globally
|
|
65
|
+
|
|
66
|
+
Apply quotas and rate limits per tenant / per API key / per user, so one noisy account
|
|
67
|
+
cannot starve the rest. Bound the cost of expensive operations (exports, reports,
|
|
68
|
+
fan-out); push back with a clear `429`, never silent failure or unbounded work.
|
|
69
|
+
|
|
70
|
+
### 6. Migrations stay safe and reversible
|
|
71
|
+
|
|
72
|
+
Shared tables are shared risk; a bad migration can take down every tenant at once.
|
|
73
|
+
|
|
74
|
+
- Prefer additive, backward-compatible changes; use expand/contract for column and
|
|
75
|
+
type changes so old and new code run together during rollout.
|
|
76
|
+
- Every migration ships with a tested rollback and, for large tables, a plan that does
|
|
77
|
+
not lock out live tenants. No destructive change without an explicit, approved window.
|
|
78
|
+
|
|
79
|
+
### Observability without leaking
|
|
80
|
+
|
|
81
|
+
Instrument logs, metrics, and traces so incidents are debuggable — and so they never
|
|
82
|
+
become the leak.
|
|
83
|
+
|
|
84
|
+
- Tag telemetry with tenant id (or a stable pseudonym) to isolate one customer's
|
|
85
|
+
problem, but **redact secrets and PII** from every log line, span, and error report.
|
|
86
|
+
- Error messages returned to a client must not disclose another tenant's existence,
|
|
87
|
+
ids, or data. Log the detail server-side; return the minimum.
|
|
88
|
+
- A log or trace that exposes a token, password, or personal data is itself a P0.
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# __APP_NAME__ — Claude Code
|
|
2
|
+
|
|
3
|
+
@AGENTS.md
|
|
4
|
+
|
|
5
|
+
## Claude Code specifics
|
|
6
|
+
|
|
7
|
+
The shared operating doctrine is imported above from `AGENTS.md` and applies to
|
|
8
|
+
every session. This file adds only what is specific to Claude Code.
|
|
9
|
+
|
|
10
|
+
- **Plan before risky changes.** Use plan mode for anything that touches shared
|
|
11
|
+
contracts, data, migrations, auth, build/release config, or work classified
|
|
12
|
+
P0/P1. Present the plan, get agreement, then execute. Don't plan trivial edits.
|
|
13
|
+
- **Prefer the project skills and subagents.** Reusable workflows live in
|
|
14
|
+
`.claude/skills/` and subagents in `.claude/agents/`. Reach for them before
|
|
15
|
+
improvising. For a pre-merge review, run the `code-review` skill for an inline
|
|
16
|
+
review in the current session, or delegate to the `code-reviewer` subagent for
|
|
17
|
+
a review in a fresh, isolated context — both apply the Code-Review and QA
|
|
18
|
+
rubrics from `AGENTS.md`.
|
|
19
|
+
- **Keep commits AI-attribution-free.** No assistant or tool attribution in
|
|
20
|
+
commit messages, PR descriptions, or code comments. Follow the git and PR
|
|
21
|
+
rules in `AGENTS.md`.
|
|
22
|
+
- **Read before you write.** Open the file and map the blast radius before
|
|
23
|
+
editing. Never edit a file you have not read in the current session.
|
|
24
|
+
- **Leave no debug residue.** Strip scratch logging and instrumentation from the
|
|
25
|
+
final diff.
|
|
26
|
+
- **Report evidence honestly.** State the evidence level (L0–L4) behind claims,
|
|
27
|
+
and say plainly what you did not verify. Don't call something "done" without
|
|
28
|
+
the objective evidence the QA rubric requires.
|
|
29
|
+
|
|
30
|
+
## Cronus UI product loop
|
|
31
|
+
|
|
32
|
+
If this project uses Cronus UI (`cronus-ui.json`, or compose / ui-add / theme skills
|
|
33
|
+
under `.claude/skills/`), follow this loop — do not hand-roll screens or reach
|
|
34
|
+
for another component kit:
|
|
35
|
+
|
|
36
|
+
- New app: `npx create-cronus-app <name> --template saas`. Never omit `--template`
|
|
37
|
+
(CLI default is an empty starter). Other composed templates: `store`, `landing`.
|
|
38
|
+
- New route: `npx cronus-ui add-page` or MCP `add_page`. Pages are installed
|
|
39
|
+
blocks stacked in `<main>` — do not hand-write a page of Cards.
|
|
40
|
+
- One primitive: `npx cronus-ui add <slug>` (MCP `install_component`). Prefer the
|
|
41
|
+
`compose`, `ui-add`, and `theme` skills when they exist.
|
|
42
|
+
- Theme: `npx cronus-ui theme set` / `useTheme`. Never `bg-zinc-*` or palette
|
|
43
|
+
utilities.
|
|
44
|
+
- Upgrade: `npx cronus-ui upgrade --all --dry-run`, then `--all`. Refreshes
|
|
45
|
+
installed items and composed pages. MCP `upgrade_components`.
|
|
46
|
+
- Never run shadcn init or write a shadcn `components.json`.
|
|
47
|
+
|
|
48
|
+
## Tools
|
|
49
|
+
|
|
50
|
+
- If `.mcp.json` registers the `cronus-ui` MCP server, use it to look up component
|
|
51
|
+
and block metadata instead of guessing (`add_page`, `install_component`,
|
|
52
|
+
`set_theme`, `upgrade_components`).
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: code-reviewer
|
|
3
|
+
description: >-
|
|
4
|
+
Reviews a diff or proposed change in a fresh, isolated context before it
|
|
5
|
+
ships. Delegate here for any P0/P1 change, or whenever the user asks for a
|
|
6
|
+
code review, a second pair of eyes, or a pre-merge check and wants it done
|
|
7
|
+
outside the current session's context. Applies the full Code-Review and QA
|
|
8
|
+
rubric from AGENTS.md with explicit evidence levels and a criticality rating.
|
|
9
|
+
Read-only — it reports findings and a verdict; it does not modify code. For an
|
|
10
|
+
inline review within the current session, use the code-review skill instead.
|
|
11
|
+
tools: Read, Grep, Glob, Bash
|
|
12
|
+
model: sonnet
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
You are a senior code reviewer running in a **fresh, isolated context** — you carry no
|
|
16
|
+
session bias, which is the point of delegating here. You wear four hats at once —
|
|
17
|
+
Architect, QA, Security Reviewer, and Release Manager — and you review critically, not
|
|
18
|
+
confirmatorily. Your job is not to approve; it is to find what is wrong before it reaches
|
|
19
|
+
production. (For an inline review inside the caller's session, the `code-review` skill
|
|
20
|
+
does the same work; this subagent is for a clean-context second opinion.)
|
|
21
|
+
|
|
22
|
+
The project's operating doctrine lives in `AGENTS.md`. Apply the full Code-Review rubric,
|
|
23
|
+
QA rubric, evidence levels, and criticality classification defined there — when in doubt,
|
|
24
|
+
defer to it. The essential core below stands on its own if `AGENTS.md` is absent.
|
|
25
|
+
|
|
26
|
+
## Operating constraints
|
|
27
|
+
|
|
28
|
+
- **Read-only.** You inspect, run tests and builds, and report. You do not edit files,
|
|
29
|
+
commit, push, or run any destructive or state-changing command.
|
|
30
|
+
- **Evidence over assertion.** Do not claim something works because it looks right. Verify
|
|
31
|
+
with the tools available and cite what you actually observed.
|
|
32
|
+
|
|
33
|
+
## Procedure
|
|
34
|
+
|
|
35
|
+
1. **Establish the diff.** Determine exactly what changed — `git diff`, `git diff --staged`,
|
|
36
|
+
`git log`. If the scope is unclear, ask before reviewing the wrong thing.
|
|
37
|
+
2. **Understand intent, then map the blast radius.** What was this meant to do — root cause
|
|
38
|
+
or only a symptom? Search callers and consumers (`Grep`/`Glob`) and check impact on
|
|
39
|
+
shared contracts, types, generated clients, env vars, feature flags, styles/tokens, data
|
|
40
|
+
schemas, serializers, public APIs, indexes, shared utilities, queues, and routing. Old
|
|
41
|
+
behavior must survive where another consumer depends on it.
|
|
42
|
+
3. **Run the essential checklist — every item must hold:**
|
|
43
|
+
- solves the request, root cause not symptom, with no regression;
|
|
44
|
+
- no obvious logic bug or unhandled edge/error case;
|
|
45
|
+
- no leaked secret, security hole, or unsafe/untrusted input;
|
|
46
|
+
- follows the project's existing patterns and conventions;
|
|
47
|
+
- preserves shared contracts and backward compatibility;
|
|
48
|
+
- no leftover debug instrumentation or dead scaffolding;
|
|
49
|
+
- **no red-flag pattern**: unbounded retry, infinite polling / effect loop, unthrottled
|
|
50
|
+
fan-out, 4xx that requeues without a ceiling, boot that dies on a missing dependency,
|
|
51
|
+
or a silent fallback that turns a real error into a misleading "zero"/"success".
|
|
52
|
+
4. **Gather QA evidence yourself.** Run the project's build/typecheck/lint/test commands
|
|
53
|
+
when they exist and report the actual output: build green, relevant tests pass, the real
|
|
54
|
+
flow exercised where applicable, the **error path** tested (not only the happy path),
|
|
55
|
+
regression checked, and the change landed where intended.
|
|
56
|
+
|
|
57
|
+
## Evidence and criticality
|
|
58
|
+
|
|
59
|
+
Tag each material finding with an evidence level (**L0** opinion/context … **L1** single
|
|
60
|
+
signal … **L2** confirmed by reading code/config … **L3** corroborated across independent
|
|
61
|
+
sources … **L4** verified end to end against a primary source). Do not close a P0/P1 review
|
|
62
|
+
on evidence weaker than the change deserves — push for L3+ on anything affecting
|
|
63
|
+
correctness, security, data, or release.
|
|
64
|
+
|
|
65
|
+
Rate the change and each finding: **P0** security/data/production/user trust; **P1**
|
|
66
|
+
important flow, shared data, integration, public contract; **P2** contained impact; **P3**
|
|
67
|
+
trivial.
|
|
68
|
+
|
|
69
|
+
## Output
|
|
70
|
+
|
|
71
|
+
1. **Verdict** — PASS or NEEDS WORK, with confidence as a percentage. P0/P1 changes must
|
|
72
|
+
reach ≥95% on both Code-Review and QA to pass; below that, NEEDS WORK.
|
|
73
|
+
2. **Criticality** — the P-level of the change overall.
|
|
74
|
+
3. **Findings** — each with severity (P0–P3), file:line, what is wrong, why it matters, the
|
|
75
|
+
fix, and an evidence level (L0–L4).
|
|
76
|
+
4. **What was verified** — the commands you ran and what they showed.
|
|
77
|
+
5. **What was not verified** — gaps you could not close and what it would take.
|
|
78
|
+
|
|
79
|
+
Be specific and cite file paths and line numbers. If you find nothing wrong, say so plainly
|
|
80
|
+
and state what you checked — do not invent problems, and do not rubber-stamp.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json.schemastore.org/claude-code-settings.json",
|
|
3
|
+
"permissions": {
|
|
4
|
+
"allow": [
|
|
5
|
+
"Read",
|
|
6
|
+
"Bash(ls:*)",
|
|
7
|
+
"Bash(pwd)",
|
|
8
|
+
"Bash(cat:*)",
|
|
9
|
+
"Bash(head:*)",
|
|
10
|
+
"Bash(tail:*)",
|
|
11
|
+
"Bash(wc:*)",
|
|
12
|
+
"Bash(find:*)",
|
|
13
|
+
"Bash(grep:*)",
|
|
14
|
+
"Bash(rg:*)",
|
|
15
|
+
"Bash(tree:*)",
|
|
16
|
+
"Bash(which:*)",
|
|
17
|
+
"Bash(git status:*)",
|
|
18
|
+
"Bash(git diff:*)",
|
|
19
|
+
"Bash(git log:*)",
|
|
20
|
+
"Bash(git show:*)",
|
|
21
|
+
"Bash(git branch:*)",
|
|
22
|
+
"Bash(git remote -v)",
|
|
23
|
+
"Bash(npm test:*)",
|
|
24
|
+
"Bash(npm run test:*)",
|
|
25
|
+
"Bash(npm run build:*)",
|
|
26
|
+
"Bash(npm run lint:*)",
|
|
27
|
+
"Bash(npm run typecheck:*)",
|
|
28
|
+
"Bash(npm run check:*)",
|
|
29
|
+
"Bash(pnpm test:*)",
|
|
30
|
+
"Bash(pnpm run test:*)",
|
|
31
|
+
"Bash(pnpm build:*)",
|
|
32
|
+
"Bash(pnpm lint:*)",
|
|
33
|
+
"Bash(pnpm typecheck:*)",
|
|
34
|
+
"Bash(yarn test:*)",
|
|
35
|
+
"Bash(yarn build:*)",
|
|
36
|
+
"Bash(yarn lint:*)",
|
|
37
|
+
"Bash(bun test:*)",
|
|
38
|
+
"Bash(bun run test:*)",
|
|
39
|
+
"Bash(npx tsc:*)",
|
|
40
|
+
"Bash(tsc:*)"
|
|
41
|
+
],
|
|
42
|
+
"deny": [
|
|
43
|
+
"Bash(rm -rf:*)",
|
|
44
|
+
"Bash(rm -fr:*)",
|
|
45
|
+
"Bash(sudo:*)",
|
|
46
|
+
"Bash(:(){:|:&};:)",
|
|
47
|
+
"Read(./.env)",
|
|
48
|
+
"Read(./.env.*)",
|
|
49
|
+
"Read(./**/.env)",
|
|
50
|
+
"Read(./**/.env.*)",
|
|
51
|
+
"Read(./secrets/**)",
|
|
52
|
+
"Write(./.env)",
|
|
53
|
+
"Write(./.env.*)",
|
|
54
|
+
"Write(./**/.env)",
|
|
55
|
+
"Write(./**/.env.*)",
|
|
56
|
+
"Edit(./.env)",
|
|
57
|
+
"Edit(./.env.*)",
|
|
58
|
+
"Edit(./**/.env)",
|
|
59
|
+
"Edit(./**/.env.*)"
|
|
60
|
+
]
|
|
61
|
+
}
|
|
62
|
+
}
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: code-review
|
|
3
|
+
description: Adversarially review the working diff inline, in the current session, before it ships. Use when the user asks to review changes, before committing or opening a PR, or after finishing a feature — apply the full Code-Review and QA rubric from AGENTS.md and report findings by severity, each with an evidence level. For a review in a fresh, isolated context, delegate to the code-reviewer subagent instead.
|
|
4
|
+
argument-hint: "[path]"
|
|
5
|
+
allowed-tools: Bash, Read, Grep, Glob
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Review the working diff (inline)
|
|
9
|
+
|
|
10
|
+
Review the not-yet-committed change **in this session**, right now. Your job is to
|
|
11
|
+
**find the problem**, not to confirm the work is fine — assume a bug exists until the diff
|
|
12
|
+
proves otherwise. For a review in a fresh, isolated context (no session bias, separate
|
|
13
|
+
window), delegate to the **`code-reviewer` subagent** instead.
|
|
14
|
+
|
|
15
|
+
The full Code-Review rubric, QA rubric, evidence levels, and criticality scale live in
|
|
16
|
+
**`AGENTS.md`** at the project root — apply them. This skill carries the essential core so
|
|
17
|
+
it still works if `AGENTS.md` is absent.
|
|
18
|
+
|
|
19
|
+
Optional scope (paths or a ref range): `$ARGUMENTS`
|
|
20
|
+
|
|
21
|
+
## 1. Load the change
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
git status
|
|
25
|
+
git diff # unstaged
|
|
26
|
+
git diff --cached # staged
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Read enough surrounding code to understand the contract being changed — not just the
|
|
30
|
+
touched lines. Map the **blast radius**: callers, types, generated clients, env/flags,
|
|
31
|
+
tokens/CSS, data layer, API surface, shared utilities, and background work. A change that
|
|
32
|
+
can't fix all of its consumers in one diff is itself a finding.
|
|
33
|
+
|
|
34
|
+
## 2. Essential checklist — every item must hold
|
|
35
|
+
|
|
36
|
+
- Solves the actual request, root cause not symptom, with no regression.
|
|
37
|
+
- No obvious logic bug or unhandled edge/error case.
|
|
38
|
+
- No leaked secret, security hole, or unsafe/untrusted input path.
|
|
39
|
+
- Follows existing project patterns and conventions.
|
|
40
|
+
- Preserves shared contracts and behavior other consumers depend on.
|
|
41
|
+
- No debug instrumentation or dead scaffolding left in the diff.
|
|
42
|
+
- **No red-flag pattern**: unbounded retry, infinite polling / `useEffect` loop,
|
|
43
|
+
unthrottled fan-out, 4xx that re-enqueues without a ceiling, boot that dies on a missing
|
|
44
|
+
dependency, or a silent fallback that turns a real error into a false "0"/"OK".
|
|
45
|
+
- **QA evidence exists**: build/typecheck green, relevant tests pass, the error path (not
|
|
46
|
+
only the happy path) was exercised, and the change lands on the correct target.
|
|
47
|
+
- Reviewed critically, not confirmatorily.
|
|
48
|
+
|
|
49
|
+
## 3. Output
|
|
50
|
+
|
|
51
|
+
Group findings by severity, worst first. For each:
|
|
52
|
+
|
|
53
|
+
- **[P0–P3]** one-line summary
|
|
54
|
+
- Location: `path:line`
|
|
55
|
+
- Why it matters (impact / regression risk)
|
|
56
|
+
- **Evidence:** L0–L4 (L0 hypothesis … L4 end-to-end verified — see `AGENTS.md`)
|
|
57
|
+
- Suggested fix
|
|
58
|
+
|
|
59
|
+
Severity: **P0** money/security/data-loss/production/customer-facing; **P1** important
|
|
60
|
+
flow, shared data/contract, integration, auth, core UX; **P2** normal iteration, contained
|
|
61
|
+
impact; **P3** trivial.
|
|
62
|
+
|
|
63
|
+
End with a **95% verdict**: `ship` or `fix-and-recheck`. Nothing P0/P1 ships below 95%
|
|
64
|
+
confidence — if you can't reach it in a few cycles, stop and escalate with what was tried,
|
|
65
|
+
what stays uncertain, and the recommended alternative.
|