@aayushchugh/skills 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,9 @@
 {
-  "name": "@aayushchugh/skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@aayushchugh/skills",
+	"version": "0.1.0",
+	"description": "The agent skills I use while building real products.",
+	"files": [
+		"skills"
+	],
+	"license": "MIT"
+}

package/skills/cases-to-run/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: cases-to-run
+description: >-
+  Write a small, risk-based set of test cases from a spec, diff, or bug
+  report. Use when the user asks for test cases or QA coverage. Do not write
+  test code or audit security.
+---
+
+# Cases to run
+
+## Scope
+
+Write the test-case document only. Do not write test code, run tests, or change the source. Cover a security requirement or access rule the source already states. Do not invent controls.
+
+## Before writing
+
+Ask every blocking question in one turn. Never invent a fact. Put an unknown under Open questions and name what it blocks. Replies are 1–2 lines. Write a paragraph only when the user asks.
+
+Ask what would change the expected behavior, data, environment, limits, or permissions. An unknown expected result is not a case. Do not write a result of "TBD" or "works correctly."
+
+## What to read
+
+- A PRD or spec: requirements, acceptance criteria, rules, states, constraints, and non-goals.
+- Code or a diff: the changed behavior, its contract, its callers, and the conditions that changed. Stop at the affected path.
+- A bug report: the shortest reproduction, expected versus actual behavior, and the environment when it changes the result.
+
+If the repository already tests a behavior, cite that test. Do not write a duplicate manual case.
+
+## Which cases
+
+Cover the relevant happy path, failure, boundary, state change, permission, and regression. Use one representative value per equivalence class. A boundary is the edge: the last allowed value and the first rejected value.
+
+Test one invalid condition at a time. Combine inputs only when they change the outcome together. One behavior is one case, even when the spec and the code both mention it. Cite both sources on that case.
+
+Skip a behavior the spec lists as a non-goal. A missing P0 behavior gets a case, or an open question that says why it cannot be tested yet.
+
+A bug gets one regression case: it fails on the current behavior and passes once the expected behavior is true. A state flow gets the valid path plus the invalid transitions a person can actually attempt.
+
+## Priority
+
+Order the document P0, then P1, then P2.
+
+- P0: data loss, money, access, a broken primary flow, or an existing caller that would regress.
+- P1: a common failure or a boundary.
+- P2: a rare edge.
+
+## Each case
+
+- ID
+- Title
+- Source requirement or changed behavior
+- Priority
+- Preconditions: role, starting data, and starting state
+- Test data
+- Steps: actions only. Do not repeat the expected result.
+- Expected result: only what a person can see, including the error, the resulting state, and data that must stay unchanged
+- Tags: `happy`, `failure`, `boundary`, `permission`, or `regression`. Use one only when it applies. Use no other tag.
+
+## Summary
+
+Counts by priority. Each source requirement or changed behavior mapped to case IDs. Anything left uncovered. Then assumptions and open questions. Do not add a matrix. Do not claim complete coverage when the source is ambiguous.
+
+## Replies
+
+Say how many cases, and what is still uncovered.

package/skills/go-or-stop/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: go-or-stop
+description: >-
+  Decide if a change is ready to ship, with a go or no-go, what to watch, and
+  how to roll back. Use when the user asks for a release check. Do not deploy.
+---
+
+# Go or stop
+
+## Scope
+
+Read the diff, the test results, the migrations, the feature flags, the dependency changes, the deploy config, and the known risks. Do not deploy, change production, or create a release until the user explicitly approves that step.
+
+## Before writing
+
+Ask every blocking question in one turn. Never invent a fact. Put an unknown under Open questions and name what it blocks. Replies are 1–2 lines. Write a paragraph only when the user asks.
+
+Ask the target environment, the migrations included, and the checks already run.
+
+## The check
+
+- What changed, in one line per user-facing change. Leave out internal refactors.
+- Tests: which ran, which failed, and which did not run.
+- Migrations and backfills. Each one needs the current state (table, row count, rows touched), the forward change, a rollback or the data that would be lost, steps that are safe to re-run, batching for a large table, and a check that proves the result. A migration missing any of these is a no-go.
+- Feature flags and dependency changes.
+- Known risks, each with the check that would catch it.
+
+## The answer
+
+- Go or no-go, with the reasons.
+- The checks still to run before the deploy.
+- What to watch after the deploy: the signal and the threshold that means stop.
+- The rollback steps, in the order to run them.
+- A short note of what changed for users.
+
+A missing test result, a migration missing any item above, or an unknown rollback is a no-go. Do not invent a test result.
+
+## Replies
+
+Say go or no-go, and the reason.

package/skills/no-slop/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: no-slop
+description: >-
+  Write the smallest readable code that reuses existing code, installed
+  utilities, and repo patterns, and fixes bugs at the root cause. Use when
+  implementing, fixing, or reviewing code. Do not use for docs.
+---
+
+# No slop
+
+## Scope
+
+Code only. Product docs, PRDs, and other non-code writing are out of scope. On a review, apply these rules to the diff and do not edit unless asked.
+
+## Before editing
+
+Ask every blocking question in one turn. Never invent a fact. Put an unknown under Open questions and name what it blocks. Replies are 1–2 lines. Write a paragraph only when the user asks.
+
+Ask only what would change the requested files, behavior, API, or approach. Leave out anything that was not asked for and that nothing currently needs.
+
+## Workflow
+
+1. Read the real path the change touches, including every caller of a shared function.
+2. Search this repo for a helper, type, or pattern that already does the job. Reuse it, and match how this repo names, lays out, and handles that kind of code.
+3. Prefer, in order: do nothing, existing code, the standard library, a native platform feature, an already-installed dependency. If that dependency exports the function, call it. Do not rewrite date-fns, lodash, or any other installed package.
+4. Make the smallest readable change that finishes the requested behavior. A bug report names a symptom. Find the source and fix that. A shared-function fix keeps existing callers working, unless their current behavior is the bug.
+5. Keep trust-boundary validation and error handling that prevents data loss.
+6. Run the repo's existing test for the changed path. Add one small check only when that path has no test and the branch is non-trivial.
+
+## Rules
+
+- Do not over-engineer. Prefer a straight sequence and early returns. A person should understand the change on a first read.
+- Correctness, security, accessibility, data safety, and this repo's conventions outrank brevity.
+- Fix a bug at its root cause. One guard in the shared function beats the same guard in every caller. A local workaround that leaves the cause in place is not a fix.
+- No speculative abstraction, interface with one implementation, factory, or config for a value that never changes.
+- No new utility file or dependency unless current code cannot do the job in a few lines. Two duplicated blocks stay inline. Extract a helper on the third copy.
+- No unrelated cleanup. No comment that restates the code. A comment is only for a non-obvious constraint or a named ceiling.
+- No pass-through wrapper, new file for one function, option with one caller, `try/catch` that only logs or rethrows, or code left for later.
+- When two options are the same size, pick the one that is correct on the edge cases. When a simplification has a known ceiling, name that ceiling and what would replace it.
+
+## Replies
+
+Say what you skipped and when to add it, and which rung you used.

package/skills/one-shape/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: one-shape
+description: >-
+  Audit a repo for duplication, divergent flows, dead code, over-engineering,
+  waste, and standards drift, then apply approved steps. Use when the user
+  asks to refactor or clean up a codebase. Do not audit security.
+---
+
+# One shape
+
+## Scope
+
+The audit is read-only until the user approves a batch. Then apply one step at a time with `no-slop`.
+
+Skip code the team does not own: `node_modules`, build output, generated files, vendored code, lockfiles, and migrations. A security issue gets one line pointing to `open-doors`.
+
+## Before auditing
+
+Ask every blocking question in one turn. Never invent a fact. Put an unknown under Open questions and name what it blocks. Replies are 1–2 lines. Write a paragraph only when the user asks.
+
+Ask the target area, hard constraints, and behavior that must not change.
+
+## Standards
+
+1. Read the repo's lint, format, and tsconfig settings, and any convention file such as `AGENTS.md`.
+2. Where config is silent, the standard is the pattern most of the repo already uses for naming, file layout, module boundaries, imports, data fetching, validation, and error handling.
+3. When the config and the majority pattern disagree, the config wins. When there is no clear majority, add an open question. Do not invent a standard.
+
+## What to find
+
+Each finding cites its files and callers, or the places the logic repeats.
+
+- **Standards drift:** code that breaks the repo's config or its majority pattern.
+- **Structure:** a file in the wrong layer, an import that crosses a module boundary, or an inconsistent folder layout.
+- **Duplication:** the same logic, matched by behavior, with a copy count. Propose a helper only on the third copy. Two copies count only when they have already drifted apart.
+- **Divergent flows:** different paths doing the same job. Unify them on the existing correct version. When copies differ, list the differences and ask which behavior is right.
+- **Reimplemented code and over-engineering:** a local copy of the standard library or an installed package, a pass-through wrapper, an interface with one implementation, or an option with one caller.
+- **Dead code:** unused exports, files, branches, and dependencies. A search is not proof. Code is still used when a framework entry point (such as Next.js `page.tsx` or a route file), a dynamic import, a string lookup, a config file, a script, or a package export refers to it.
+- **Evident performance waste:** a repeated query, work repeated in a loop, or an unbounded load. Report it only when the code shows it.
+
+Never propose a new abstraction, a new dependency, a framework migration, or a split done only for file size.
+
+## Priority
+
+- P0: copies or flows that already disagree and can cause a bug.
+- P1: high-traffic drift, duplication, dead code, or waste.
+- P2: local polish.
+
+Mark each step's effort and risk as low, medium, or high.
+
+## Plan and apply
+
+Order the steps: delete dead code, then replace reimplemented code, then fix standards drift, then unify flows, then simplify what is left. A formatting-only change is its own step and uses the repo's formatter. Never mix it with a logic change.
+
+Each step is small, keeps behavior the same, ships on its own, names its files, and names the test that checks it. When no test covers a step, say so and use `cases-to-run` before that step. A merge keeps every current caller's output the same. If any caller's output would change, that needs its own approved step. On a big repo, the user approves one batch at a time.
+
+Stop after the report. Edit nothing until the user approves a batch.
+
+1. Before the first step, run the repo's lint, typecheck, and tests, and record what already fails.
+2. Apply one approved step at a time with `no-slop`. Each step stays its own diff.
+3. After each step, run the same checks. If a new failure appears, revert that step, stop, and report.
+4. After a batch, re-check the remaining steps, then wait for the next approval.
+
+Do not commit unless the user asks.
+
+## Summary
+
+Counts by priority, the steps applied, the steps left, the areas read and not read, and open questions. Do not claim lines saved or speed gained, and do not call a partial audit complete.
+
+## Replies
+
+Say how many findings, and what needs approval next. After a batch, state what changed and what failed, if anything.

package/skills/open-doors/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: open-doors
+description: >-
+  Review application code, APIs, dependencies, secrets, and deploy config for
+  injection, web attacks, and DDoS controls. Use when the user asks for a
+  security audit. Never attack a live target.
+---
+
+# Open doors
+
+## Scope
+
+Review application code, APIs, dependencies, secrets, and deployment configuration. A diff review follows the changed path and its callers. A repository review checks every relevant surface it can find. A spec review checks whether those requirements are missing or contradicted.
+
+This is a read-only audit, not active pentesting. Do not send probes, payloads, traffic, or requests to a live target. Do not claim a control works unless repository evidence proves it. Do not edit the source.
+
+## Before writing
+
+Ask every blocking question in one turn. Never invent a fact. Put an unknown under Open questions and name what it blocks. Replies are 1–2 lines. Write a paragraph only when the user asks.
+
+Ask what would change whether an issue is real or how severe it is.
+
+## What to review
+
+Follow untrusted input from entry to side effect. Check only categories relevant to the repository:
+
+- Auth and access: authentication, sessions, authorization, tenant isolation, privilege changes.
+- Injection: SQL, NoSQL, command, template, header, and log injection.
+- Web and files: cross-site scripting, CSRF, SSRF, open redirects, path traversal, unsafe file handling.
+- Parsing and outbound: deserialization, parser abuse, request smuggling assumptions, unsafe outbound requests.
+- Data and secrets: sensitive-data exposure, excessive API responses, error leakage, logs, caches, hardcoded secrets, weak cryptography, insecure randomness, missing transport assumptions.
+- Config: CORS, cookies, security headers, origin checks, trusted-proxy configuration, dependency and supply-chain risk in manifests and lockfiles.
+- Logic and exhaustion: business-logic abuse, replay, race conditions, duplicate actions, missing idempotency, unbounded input, uploads, queries, pagination, recursion, concurrency, and expensive unauthenticated work.
+
+For DDoS and abuse prevention, inspect repository evidence for edge or proxy limits, rate limits, request and body limits, timeouts, concurrency limits, caching, queues, backpressure, and graceful rejection. State when CDN, WAF, autoscaling, network capacity, or provider controls cannot be verified from the repository.
+
+Report the surfaces reviewed and the categories that did not apply or could not be verified.
+
+## Findings
+
+One finding per root cause. The same missing check in several callers is one finding: name the shared function and list the callers. A finding names the missing check, the exposed field, or the requirement that contradicts the code. If it cannot, it is an open question.
+
+Each finding has: ID, Title, Severity, File or requirement, Evidence, Who can reach it, Impact, Fix.
+
+The fix names the control to add, in one or two lines. Do not include a patch, exploit steps, a payload, proof-of-concept code, or instructions for attacking a target.
+
+Never copy a secret. Name the file and the kind of credential. Leave the value out of the report.
+
+## Severity
+
+- Critical: an untrusted person can bypass auth, execute code, expose a production secret, or read or change other people's sensitive data at broad scope.
+- High: a reachable injection, access-control, data-exposure, or resource-exhaustion gap has serious but bounded impact.
+- Medium: the gap is real, and another condition or limited scope reduces the impact.
+
+Reachability, required access, affected data, and blast radius determine severity. An unreachable line is not Critical. Skip a style comment and a theoretical issue with no evidence.
+
+## Summary
+
+Order findings Critical, then High, then Medium. End with counts by severity, the paths and attack surfaces reviewed, what was not reviewed, controls that require live-environment verification, and any open questions. A clean result on the reviewed paths does not clear the rest of the application. Do not call the result a complete audit.
+
+## Replies
+
+Say how many findings, and what was not reviewed.

package/skills/plain-paper/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: plain-paper
+description: >-
+  Write a spec or other documentation from the request, the code, and relevant
+  sources. Use when the user asks for a PRD, spec, flow, API reference,
+  runbook, guide, or README. Do not change code.
+---
+
+# Plain paper
+
+## Scope
+
+A spec describes what will be built. Documentation describes what exists.
+
+- A PRD says what and why. It does not choose the implementation.
+- An engineering spec says how the system behaves: interfaces, data, failure, trade-offs, rollout, and verification.
+- Documentation covers a flow, API reference, architecture note, runbook, onboarding guide, README, changelog, user guide, or another document the user names.
+
+Code changes are out of scope. A security need is one requirement. Do not invent controls or run an audit.
+
+## Before writing
+
+Ask every blocking question in one turn. Never invent a fact. Put an unknown under Open questions and name what it blocks. Replies are 1–2 lines. Write a paragraph only when the user asks.
+
+Ask which kind of document when the request does not say: a spec (PRD or engineering spec) or documentation (flow, API reference, runbook, guide, or README), and who will read it. Leave no TBD outside Open questions.
+
+For documentation, read the repo first: entry points, callers, routes, data stores, integrations, error paths, feature flags, and tests. Use a connected source only when it is relevant. Before reading one that holds external or customer data, say why and ask first.
+
+## Product doc
+
+Use only the sections that apply: Summary, Problem and evidence, Users, Goals, Non-goals, User flow, Requirements with acceptance criteria, Success measures, Constraints and dependencies, Risks, Open questions.
+
+## Engineering doc
+
+Use only the sections that apply: Summary, Current behavior, Proposed behavior, Flow and interfaces, Data and failure handling, Trade-offs, Compatibility, Rollout and rollback, Verification, Open questions.
+
+## Documentation
+
+- A flow: purpose, actors, trigger, steps, inputs and outputs, how data moves, failures, and recovery.
+- An API reference: each endpoint, its inputs, outputs, and errors.
+- A runbook: the symptom, the checks, and the recovery.
+- A guide or a README: what it is, how to use it, and how to tell it worked.
+
+Also include the dependencies, the access rules the sources show, the monitoring, and where each fact came from. Mark a fact as confirmed or assumed.
+
+## Rules
+
+- Short sentences. One idea per bullet. Define a technical word in the same sentence. If a line can mean two things, add one concrete example.
+- A requirement states observable behavior and how to pass or fail it. Include the unhappy path when invalid input, an empty state, a failure, or a permission matters.
+- A non-goal excludes something a reasonable reader would assume is included.
+- A goal is a result, not an activity. A success measure says what changes and how it will be checked.
+- An open question names what it blocks. Name an owner only when one is known.
+- End a spec with the decision still required before implementation.
+- Omit a section that has nothing to say. A small change stays a short document.
+
+## Publish
+
+Show the draft first. Then ask where to publish it: chat, a Markdown file in the repo, or a connected tool such as Notion, Confluence, or ClickUp. Write nothing to a file or a tool until the user answers.
+
+## Replies
+
+The document is the deliverable. Say which document you wrote, and what is still open or unconfirmed.

package/skills/red-pen/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: red-pen
+description: >-
+  Review a diff or pull request for bugs, regressions, broken callers, missing
+  tests, and unmet requirements. Use when the user asks for a code review. Do
+  not audit security, refactor, or write tests.
+---
+
+# Red pen
+
+## Scope
+
+Read the diff, the request it was meant to satisfy, every caller of a changed function, and the tests that cover the path. For a pull request, read the diff with `gh pr diff`. Do not edit the code.
+
+A security finding gets one line pointing to `open-doors`. A structure or duplication finding gets one line pointing to `one-shape`. A missing test gets one line pointing to `cases-to-run`.
+
+## Before writing
+
+Ask every blocking question in one turn. Never invent a fact. Put an unknown under Open questions and name what it blocks. Replies are 1–2 lines. Write a paragraph only when the user asks.
+
+Ask what would change whether a finding is real.
+
+## Findings
+
+Report a correctness bug, a regression, a break in an API a caller depends on, a missing test for a changed path, or a requirement the change did not meet.
+
+Each finding has: ID, Title, Severity, File and line, Evidence, Impact, Fix in one or two lines.
+
+One finding per root cause. The same bug in several callers is one finding: name the shared function and list the callers. A finding names the broken behavior. If it cannot, it is an open question. Do not report a style comment.
+
+## Severity
+
+- Critical: the change loses data, breaks a primary flow, or breaks callers that are already in use.
+- High: a real bug on a common path, or a requirement the change missed.
+- Medium: a bug that needs another condition, or a missing test on a non-trivial branch.
+
+## Summary
+
+Order findings Critical, then High, then Medium. End with counts by severity, what was reviewed, and what was not. Do not call the result a complete review of the repo.
+
+## Replies
+
+Say how many findings, and which other skill should take the next step.

package/skills/the-cause/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: the-cause
+description: >-
+  Find a bug's root cause from the report, the code path, and the evidence.
+  Use when the user asks to diagnose or debug a failure. Do not write the fix
+  or the regression test.
+---
+
+# The cause
+
+## Scope
+
+Read only the path the bug touches, its callers, and the logs, traces, or connected sources needed to prove the cause. Do not edit the code. The fix goes to `no-slop`. The regression case goes to `cases-to-run`.
+
+## Before writing
+
+Ask every blocking question in one turn. Never invent a fact. Put an unknown under Open questions and name what it blocks. Replies are 1–2 lines. Write a paragraph only when the user asks.
+
+Ask what would change the reproduction or the expected behavior.
+
+## The report
+
+- The shortest reproduction: the steps, the data, and the environment when it changes the result.
+- Expected behavior and actual behavior.
+- Where it happens: the file, the function, and the condition.
+- The root cause, backed by the code or a log line. A cause without evidence stays marked as a hypothesis.
+- What was checked and ruled out.
+
+Name the symptom, then the source. A local workaround is not a cause.
+
+## Replies
+
+Say the cause, or the hypothesis still open.

package/skills/which-skill/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: which-skill
+description: >-
+  Pick and run the right skill, or a chain of skills, for a request. Use when
+  unsure which skill applies or when a task spans several steps.
+---
+
+# Which skill
+
+## Before writing
+
+Ask every blocking question in one turn. Never invent a fact. Put an unknown under Open questions and name what it blocks. Replies are 1–2 lines. Write a paragraph only when the user asks.
+
+## Pick
+
+Read the chosen skill and follow it. Do not restate its rules here.
+
+| Request | Skill |
+| --- | --- |
+| Implement, fix, or review code | `no-slop` |
+| PRD, engineering spec, flow, API reference, runbook, guide, or README | `plain-paper` |
+| Test cases or regression coverage | `cases-to-run` |
+| Security audit | `open-doors` |
+| Refactor or clean up a repo | `one-shape` |
+| Review a diff or pull request | `red-pen` |
+| Diagnose or debug a failure | `the-cause` |
+| Release check or go / no-go | `go-or-stop` |
+
+Run one skill when one fits. Say which skill or chain you picked in one line. Ask one question when two skills fit equally.
+
+## Chains
+
+Pause for approval before a step that writes code or would deploy.
+
+- Bug: `the-cause`, then `no-slop`, then `cases-to-run`, then `red-pen`.
+- Feature: `plain-paper` as a spec, then `no-slop`, then `red-pen`.
+- Release: `red-pen`, then `go-or-stop`. A migration is covered inside `go-or-stop`.
+- Cleanup: `one-shape`, which applies its changes through `no-slop`.
+
+`go-or-stop` does not deploy. `one-shape` does not edit until a batch is approved.

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.