project-conventions
project-conventions
The operator has to make a handful of structural decisions on every new project that are not about secrets: which branch do I work on, where do files go, do I pin dependencies, how do I avoid hardcoding my home directory into source. Each one is a small tax on attention. Most of them have one answer that works for 95% of projects.
This skill pre-pays that tax with one opinionated answer per question. The high-stakes slice — secrets, .env, secret-shaped gitignore entries, CI secret stores — lives in manage-secrets-env. Split this way so the operator can trigger the right depth of care for the right question.
The principle: the best convention is the one the operator doesn't have to invent. When they ask "should I make a dev branch?", answer in one sentence and move on. Don't present a decision framework; make the decision.
State assumptions — before acting
Before starting the procedure, write an explicit Assumptions block. Don't pick silently between interpretations; surface the choice. If any assumption is wrong or ambiguous, pause and ask — do not proceed on a guess.
Required block:
Assumptions:
- Project maturity: <new scaffold | active repo under audit | legacy repo with historical conventions to respect>
- Branch strategy: <GitHub Flow (main only) | main + dev | trunk-based | other — detected from CONTRIBUTING.md / recent branches>
- Pinning strategy: <exact-pin + lockfile | caret-range | no lockfile | mixed per-package (monorepo)>
More from subinium/vibesubin
manage-secrets-env
Opinionated defaults and full lifecycle playbook for secrets and environment variables. Decides where a secret or env-specific value lives (constant, .env, CI secret, env var), scaffolds .env.example and .gitignore, and manages the lifecycle end to end — add, update, rotate, remove, migrate between buckets, audit cross-environment drift, provision new environments. High-stakes companion to project-conventions. Language-agnostic.
4setup-ci
Teaches CI/CD from first principles to a non-developer, then scaffolds a working test + deploy pipeline. Handles the common hosts (GitHub Actions, GitLab CI, CircleCI, Travis, Jenkins) and common deploy targets (SSH to VM, Vercel, Netlify, Fly.io, Cloud Run, Docker registries). Asks what the operator has before generating anything — never assumes.
3audit-security
Runs a deliberately small, hand-curated security sweep across a repo. Finds secrets committed to git, SQL/shell injection patterns, XSS sinks, path traversal, dangerous deserialization, missing cookie flags, wildcard CORS, and tracked credential files. Triages every finding as real / false-positive / needs-review before reporting. Language-agnostic, no heavyweight scanner required.
3unify-design
Establishes a web project's design system as the single source of truth — colors, spacing, typography, radius, shadow, breakpoints — then audits the codebase for drift against it (hardcoded hex values, arbitrary Tailwind values, magic px/rem numbers, duplicate component variants, inconsistent navigation) and fixes the drift by extracting repeated values to design tokens. Framework-aware — Tailwind (v3 and v4), CSS Modules, styled-components / Emotion, Material UI, Chakra UI, vanilla CSS with custom properties. Multi-file rewrites hand off to refactor-verify.
3refactor-verify
Proves a behavior-preserving code change (refactor, rename, split, merge, extract, inline, or delete of confirmed-dead code) is actually complete. Plans the change as a dependency tree, executes it from the leaves up, and after each step proves 1:1 semantic equivalence through four independent checks — exported symbol-set diff, per-node AST diff, full behavioral test suite, and call-site closure via find-references. Runs before claiming any such change is done. Works for any language with a test runner and a way to grep for symbols.
3manage-assets
Finds oversized files, binary bloat, and accidental artifact commits in a repo — large files currently tracked, large blobs hiding in git history, LFS migration candidates, asset directories growing without a policy, duplicate binaries. Pure diagnosis — never edits, never deletes, never rewrites history. Hands off to manage-secrets-env if secrets are found inside blobs, to refactor-verify if history rewriting is required, to fight-repo-rot if assets are unused. Language-agnostic.
3