Enhance Repo

Enhance Repo

A systematic workflow for upgrading a repository's quality, professionalism, and developer experience. Run the steps in order, adapting depth to the repo size and the user's goals.

1. Analyze the repository

• List the repo root (.opencode-style hidden dirs count too).
• Detect the stack: read package.json, Cargo.toml, pyproject.toml, go.mod, pom.xml, Gemfile, *.csproj, etc.
• Read the existing README, LICENSE, CONTRIBUTING, AGENTS.md, and CI configs to see what already exists.
• Note anything broken: missing files referenced by config, out-of-date versions, unused dependencies, missing license headers.

2. Fix the basics

• Ensure a .gitignore exists and covers build outputs, env files, and IDE noise for the detected stack.
• Ensure a LICENSE exists if the user wants one (ask which license if unclear — MIT by default).
• Add README.md if missing, with: project name, one-line description, badges (build, license, version), features, install/usage, API or examples, contributing link, license section.
• Add CONTRIBUTING.md with setup, test, and PR instructions.
• Add a minimal SECURITY.md (how to report vulnerabilities) and CODE_OF_CONDUCT.md for public repos.

3. Harden configuration

• Add or fix the editorconfig (.editorconfig) for consistent formatting.
• Add lint/format/tooling configs idiomatic to the stack (e.g. eslint.config.*, .prettierrc, rustfmt.toml, ruff.toml, .golangci.yml).
• Add AGENTS.md if the user wants AI agents to work in the repo; document build, test, and lint commands verbatim from the actual scripts.
• Add or improve CI (.github/workflows/ci.yml or equivalent): install deps, run lint, run tests, upload artifacts. Keep matrix small for small repos.

4. Improve code quality

• Check for obvious issues: TODO/FIXME markers, commented-out dead code, hardcoded secrets or absolute paths.
• Verify the documented build/test/lint commands actually run. Do NOT claim commands work without running them.
• Suggest dependency updates or replacements only if they are clearly beneficial; never churn dependencies without reason.

5. Developer experience

• Add a Makefile, justfile, or npm scripts for common tasks (setup, dev, build, test, lint) if missing and the stack supports it.
• Add issue/PR templates (.github/ISSUE_TEMPLATE/, .github/PULL_REQUEST_TEMPLATE.md) for public repos.
• Add a changelog convention (CHANGELOG.md or changelog generator config) for released projects.

6. Security checks

• Scan for hardcoded secrets: API keys, tokens, passwords, AKIA*/ghp_*/sk-* patterns, private keys, and connection strings in source, configs, and docs. Report findings (never print the secret value in full; redact it).
• Check .gitignore and .dockerignore cover env files (.env, .env.*, *.pem, *.key, credential stores). Warn if committed env files exist; ask before rewriting history.
• Inspect dependency manifests for known-vulnerable or unmaintained packages where clearly identifiable; suggest pinning or bumping. Do not run external scanners unless available offline.
• Verify authentication patterns: no default/weak credentials, no Bearer tokens in client-side code, secrets injected via env vars or secret managers, not config files.
• Check input handling: SQL query construction (flag string interpolation), shell command building (flag shell injection), eval/exec of user input, unsafe deserialization, missing output escaping (XSS vectors).
• Check the dependency update path exists: renovate/dependabot config or documented manual process.
• If the repo ships a web app: flag missing security headers, https enforcement, cookie flags (HttpOnly, Secure, SameSite), and obvious authorization gaps — describe fixes, only apply with user consent.

7. Testing & reliability

• Verify the test suite exists and runs; add the test command to the README and CI if missing.
• Flag untested critical paths (auth, payments, parsing, network boundaries) and suggest focused tests — add them only if the user asks.
• Check for a deterministic build: reproducible lockfiles (e.g. package-lock.json, Cargo.lock, uv.lock), pinned versions, no floating latest deps.
• Check error handling: swallowed exceptions, empty catch blocks, no logging for failures, missing retries/timeouts for network calls. Suggest improvements, apply minor ones.
• Add/verify structured logging config for services (log levels, no secrets in logs).

8. Performance & scalability

• Flag obvious inefficiencies: O(n²) loops over large collections, N+1 queries, blocking calls in async contexts, unbounded caches/queues, missing indexes on hot queries.
• For web assets: unminified bundles, missing cache headers, no pagination on list endpoints, no lazy loading for heavy pages.
• For server code: missing connection pooling, timeouts, or rate limiting.
• Only apply performance fixes when they are low-risk; otherwise report findings with suggested approach.

9. UI/UX checks (web/mobile apps)

• Verify the app renders at common viewport sizes (responsive/layout breakpoints); flag fixed widths, missing viewport meta, horizontal overflow.
• Check the primary user flows end-to-end (signup, login, main action, error state, empty state, loading state) and flag dead-ends, confusing labels, or missing feedback.
• Check accessibility (a11y): image alt text, form label/htmlFor, button/input semantics (not bare divs), keyboard navigation, focus states, color-contrast basics, aria attributes where needed. Flag issues; apply simple fixes.
• Check consistency: shared design tokens/theme instead of scattered hardcoded colors/spacing, consistent button/typography styles, consistent iconography.
• Check UX fundamentals: clear error messages with recovery paths, confirmation on destructive actions, empty/loading/error states everywhere, sensible default focus, prefers-reduced-motion respect.
• Check i18n readiness if the repo targets multiple locales: no hardcoded user-facing strings without an abstraction layer.
• Report UI findings as a prioritized list (must-fix vs. nice-to-have) rather than changing visual design without user approval.

10. Documentation & onboarding

• Verify README claims match reality (commands, screenshots, version numbers).
• Add a "Getting started" quickstart with copy-pasteable commands from first clone to running app.
• Add API documentation for public endpoints (OpenAPI/Swagger or docstrings); document env vars in .env.example with comments.
• Add architecture notes (docs/architecture.md) for repos past trivial size: main components, data flow, key decisions.
• Document troubleshooting: common errors and fixes, known issues.
• Keep AGENTS.md accurate: build/test/lint commands verbatim, repo layout, conventions.

11. Verify and report

• Re-run the project's test and lint commands to confirm nothing broke.
• Report a concise summary organized by area: what was added, what was changed, what was intentionally skipped, and follow-ups (e.g. "run npm test before pushing", "rotate the leaked key in .env.history").

Guardrails

• Ask before creating a LICENSE (legal choice), before large refactors or dependency upgrades, and before applying security or UI/UX changes that alter behavior or design — those can be risky.
• Never introduce a toolchain the repo doesn't already use (e.g. no Docker for a plain library repo).
• Preserve existing conventions and formatting; match the repo's style.
• Do not generate placeholder content like "TODO: fill this" — write real, accurate content or omit.
• Redact secrets when reporting them (never echo full key values).
• Depth scales with repo size and purpose: a tiny library gets the core checks; a production web service gets the full pass. Say explicitly which checks you skipped and why.